GNU Astronomy Utilities manual

10.4 Version controlled source

The source code that is publicly distributed does not contain the revision history, it is only the final snapshot of a stable release, ready to be configured and built. To be able to develop successfully, the revision history of the code can be very useful, also some updates that are not yet released might be in it. We use Git for the version control of Gnuastro. For those who are not familiar with it, we suggest Pro Git¹⁰⁹. The whole book is publicly available for online reading and downloading. The latest version of Gnuastro can be cloned by running

$ git clone git://git.sv.gnu.org/gnuastro.git

The version controlled source code lacks the source files that we have not written or are automatically built (and included in the distributed gnuastro-0.1.tar.gz) for configuration and building. There are three types of files that we have not written:

• To ensure portability for a wider range of operating systems (those that don’t include GNU C Library, namely glibc), we have used the GNU Portability Library (Gnulib). Gnulib keeps a copy of all the functions in glibc and you can include them in the source code to replace system wide functions on other compilers.
• To test for various system architectures and compiler configurations we make use of the various GNU Autoconf macros in the GNU Autoconf archives¹¹⁰.
• Figures in the manual. Some of them are built by LaTeX (using the TikZ package) and some are actual rasterized images. An automatic script will do the job of drawing the plots with LaTeX and converting all the figures into all the formats that are necessary for all the various formats of the manual.

To get the Gnulib and the Autoconf archives, just run these commands in any directory you want to store them in (let’s assume you are in ~/Development directory):

$ pwd
/home/yourusername/Development
$ git clone git://git.sv.gnu.org/gnulib.git
$ git clone git://git.sv.gnu.org/autoconf-archive.git

This will download the full version controlled source of the two in separate directories. Both these packages are regularly updated, so every once and a while you can run $ git pull within them to get any possible updates. First, include all the necessary packages from Gnulib. To do that, run the following command from within the cloned gnuastro directory¹¹¹:

$ ~/Development/gnulib/gnulib-tool --import --source-base=gnulib/lib \
  --with-tests --tests-base=gnulib/tests --no-vc-files math argp \
  error progname

One of the directories made after running gnulib-tool is m4/. We can now add the necessary Autoconf checks from the Autoconf archives to this directory:

$ cp ~/Development/autoconf-archive/m4/ax_pthread.m4 ./m4/

The last thing you have to do is to make/convert all the figures in all the necessary formats. We use LaTeX (along with TikZ) to create some of the figures and ImageMagick’s convert tool for the conversion into various types. So make sure you have them installed. All the necessary scripts are ready and you just have to run a make command in the appropriate directory.

$ cd doc/plotsrc
$ make
$ cd ../../

All the necessary GNU C Library functions, Autoconf macros and manual figures are now available. The GNU build system will do the rest of the job. To generate all the other necessary files you have to run the following command in the cloned gnuastro directory¹¹².

$ autoreconf --install

Now you can easily configure, build and start hacking into the code and you have the full revision history under your fingers.

The hand-written (version controlled) code for Gnuastro, this manual and the tests are divided in the following sub-directories of the top directory. Their names are standard and descriptive enough, but a short summary is given here:

doc

The Texinfo source files for this manual and the Gnuastro webpage file(s).

include

The header files of the internal static libraries and also some other header files that are used by more than one program.

lib

The internal static libraries (only their .c files) are stored here. These libraries hold functions that are used by more than one program, they will not be installed.

src

This directory contains a subdirectory for every program in this version of Gnuastro. The source code for each program is placed inside each of these sub-directories to be easily separable.

tests

This directory keeps all the tests (checks) which are executed when make check is run.

Read in other formats.
GNU Astronomy Utilities manual, November 2015.