The simple steps of Quick start will mix the source and built files. This can cause inconvenience for developers or enthusiasts following the most recent work (see Version controlled source). The current section is mainly focused on this later group of Gnuastro users. If you just install Gnuastro on major releases (following Announcements), you can safely ignore this section.
When it is necessary to keep the source (which is under version control), but not the derivative (built) files (after checking or installing), the best solution is to keep the source and the built files in separate directories. One application of this is already discussed in Configure and build in RAM.
To facilitate this process of configuring and building in a separate directory, Gnuastro comes with the developer-build script. It is available in the top source directory and is not installed. It will make a directory under a given top-level directory (given to --top-build-dir) and build Gnuastro there. It thus keeps the source completely separated from the built files. For easy access to the built files, it also makes a symbolic link to the built directory in the top source files called build.
When running the developer-build script without any options in the Gnuastro’s top source directory, default values will be used for its configuration. As with Gnuastro’s programs, you can inspect the default values with -P (or --printparams, the output just looks a little different here). The default top-level build directory is /dev/shm: the shared memory directory in RAM on GNU/Linux systems as described in Configure and build in RAM.
Besides these, it also has some features to facilitate the job of developers or bleeding edge users like the --debug option to do a fast build, with debug information, no optimization, and no shared libraries. Here is the full list of options you can feed to this script to configure its operations.
|
Not all Gnuastro’s common program behavior usable here: developer-build is just a non-installed script with a very limited scope as described above. It thus does not have all the common option behaviors or configuration files for example. |
|
White space between option and value: developer-build does not accept an = sign between the options and their values. It also needs at least one character between the option and its value. Therefore -n 4 or --numthreads 4 are acceptable, while -n4, -n=4, or --numthreads=4 are not. Finally multiple short option names cannot be merged: for example, you can say -c -n 4, but unlike Gnuastro’s programs, -cn4 is not acceptable. |
|
Reusable for other packages: This script can be used in any software which is configured and built using the GNU Build System. Just copy it in the top source directory of that software and run it from there. |
|
Example usage: See Forking tutorial for an example usage of this script in some scenarios. |
The top build directory to make a directory for the build. If this option is not called, the top build directory is /dev/shm (only available in GNU/Linux operating systems, see Configure and build in RAM).
Print the version string of Gnuastro that will be used in the build. This string will be appended to the directory name containing the built files.
Run autoreconf -f before building the package.
In Gnuastro, this is necessary when a new commit has been made to the project history.
In Gnuastro’s build system, the Git description will be used as the version, see Version numbering and Synchronizing.
Delete the contents of the build directory (clean it) before starting the configuration and building of this run.
This is useful when you have recently pulled changes from the main Git repository, or committed a change yourself and ran autoreconf -f, see Synchronizing.
After running GNU Autoconf, the version will be updated and you need to do a clean build.
Build with debugging flags (for example, to use in GNU Debugger, also known as GDB, or Valgrind), disable optimization and also the building of shared libraries. Similar to running the configure script of below
$ ./configure --enable-debug
Besides all the debugging advantages of building with this option, it will also be significantly speed up the build (at the cost of slower built programs). So when you are testing something small or working on the build system itself, it will be much faster to test your work with this option.
Build all make check tests within Valgrind.
For more, see the description of --enable-check-with-valgrind in Gnuastro configure options.
The maximum number of threads/jobs for Make to build at any moment. As the name suggests (Make has an identical option), the number given to this option is directly passed on to any call of Make with its -j option.
After finishing the build, also run make check.
By default, make check is not run because the developer usually has their own checks to work on (for example, defined in tests/during-dev.sh).
After finishing the build, also run make install.
Run make dist-lzip pdf to build a distribution tarball (in .tar.lz format) and a PDF manual.
This can be useful for archiving, or sending to colleagues who do not use Git for an easy build and manual.
Activate the --dist (-D) option, then use secure copy (scp, part of the SSH tools) to copy the tarball and PDF to the src and pdf sub-directories of the specified server and its directory (value to this option).
For example, --upload my-server:dir, will copy the tarball in the dir/src, and the PDF manual in dir/pdf of my-server server.
It will then make a symbolic link in the top server directory to the tarball that is called gnuastro-latest.tar.lz.
Clean, bootstrap, build, check and upload the checked tarball and PDF of the book to the URL given as STR.
This option is just a wrapper for --autoreconf --clean --debug --check --upload STR.
--debug is added because it will greatly speed up the build.
--debug will have no effect on the produced tarball (people who later download will be building with the default optimized, and non-debug mode).
This option is good when you have made a commit and are ready to publish it on your server (if nothing crashes).
Recall that if any of the previous steps fail the script aborts.
Short for --autoreconf --clean --check --install --dist. This is useful when you actually want to install the commit you just made (if the build and checks succeed). It will also produce a distribution tarball and PDF manual for easy access to the installed tarball on your system at a later time.
Ideally, Gnuastro’s Git version history makes it easy for a prepared system to revert back to a different point in history. But Gnuastro also needs to bootstrap files and also your collaborators might (usually do!) find it too much of a burden to do the bootstrapping themselves. So it is convenient to have a tarball and PDF manual of the version you have installed (and are using in your research) handily available.
Print a description of this script along with all the options and their current values.
GNU Astronomy Utilities 0.23 manual, July 2024.