HACKING

Instructions for developers who use the source code repository
**************************************************************

GIT repository
==============

The source repository can be obtained (read-only) at:
git clone https://github.com/drsteve/LANLGeoMag.git

For write access, fork the repository and clone from your fork.
Further information can be found in the github help.

Then:

cd LanlGeoMag

Later updates:
git pull

Committing your work:

git add [files]
git commit 
git pull
git push

Then send a pull request with your changes, read WORKFLOW.md
for additional notes on collaborative work in this repo.


Prerequisites
=============

The following list may not be complete. It is important to note that the 
dependencies for LanlGeoMag will have their own dependencies (and so on), so we
highly recommend installing the dependencies using a package manager. On Mac
package managers are not installed by default: MacPorts and HomeBrew are 
popular options.

git
automake (If Python >=3.12 is used, autotools >= 1.17 is required)
autoconf >=2.69
libtool >=2.4.2
libperl-dev (optional)
gsl >= 2.6
hdf5 >= 1.10

On Mac, the following should also be installed through the package manager:
argp-standalone


Compiling
=========

Just once (or just occasionally):

autoreconf -i
./configure

Recent updates to HDF5 include non-standard locations and use of
pkg-config. If you have problems with HDF5 when running configure, try:

./configure CFLAGS=`pkg-config hdf5 --cflags` LIBS=`pkg-config hdf5 --libs|grep -o '^\S*'`

This may also help some users with non-standard install locations for
other dependencies.

Every time:

make  (or make -j)


Installing
==========
make install

If doing a system install (i.e., not setting prefix on configure)
sudo make install

Note: This will run the script GetEopFiles. If you are behind a proxy, you may
need to modify your /etc/sudoers file to include the line;

Defaults env_keep = "http_proxy ftp_proxy" 



Release engineering
===================

Example: you want to freeze and release version 1.5.12.  The
convention is that we use tags with the name v1.5.12

Developer actions
.................

The developer takes these steps:

* Commit all final changes and sure that the code passes continuous integration

* Set the new version in configure.ac with AC_INIT(... , [2.1.0] , ...)

* Update the Changelog with a list of user-visible or API changes

* Tag the repository with

git tag -a v2.1.0
git commit -m "tagged release v2.1.0"
git push --tags


Release engineer actions
........................

Start with a fresh clone followed by a checkout of the release tag:

git clone https://github.com/drsteve/LANLGeoMag.git LanlGeoMag-v2.1.0
cd LanlGeoMag-v2.1.0
git checkout v2.1.0

autoreconf -i
./configure
make distcheck

And you've got a well-tracked tarball called lanlgeomag-2.1.0.tar.gz

Finally, you can try running

rpmbuild -ta lanlgeomag-2.1.0.tar.gz

to build RPMs.  RPMs are not yet working because we still have
some paths hard-coded in a lot of places, but we are getting closer.


Ctypesgen
=========
The Python wrappers require ctypesgen. For simplicity, we bundle our own
version from https://github.com/ctypesgen/ctypesgen

There's a nice discussion at
https://medium.com/@porteneuve/mastering-git-subtrees-943d29a798ec

If you aren't hacking on the ctypes code itself, there's no need to read
any of this. But if you need to update the bundled ctypes, first set up
the repositories:

git remote add ctypesgen https://github.com/ctypesgen/ctypesgen.git

To start this process from scratch (i.e. before we had anything pulled in):
git fetch ctypesgen
git read-tree --prefix=Python/ctypesgen/ -u ctypesgen/master

But to update ctypesgen now that it's been incorporated:
git fetch ctypesgen
git merge -s subtree --squash ctypesgen/master
git rev-parse ctypesgen/master #To get SHA1
git commit -m "Update ctypesgen to (SHA1)"

We should refer to this license (3-clause BSD) in the lanlgeomag docs.


make dist
===========
It seems you need to make with --enable-doxygen-doc on the ./configure cmd line....

Unit tests
==========
The unit tests test against the version of the library as built (not
installed). But the data directories are compiled in as at install
time. So you need to do a build of the library with those locations
specified in order to test. The directory layout in the source tree
doesn't match the expected directory layout post-install. Long-term
either there should be configure options/environment variables to
specify every directory separately (at build time or runtime), or the
layout of these directories in the source should match the expected
installed layout. For now we patch up with symlinks.

make clean
ln -s ./libLanlGeoMag/ LanlGeoMag
./configure --datadir="`pwd`"
make
JPL_EPHEM_PATH="`pwd`/libLanlGeoMag/DE_FILES/" make check
rm ./LanlGeoMag