GNU Astronomy Utilities
13.4.2 The TEMPLATE program
The extra creativity offered by libraries comes at a cost: you have to
actually write your
main function and get your hands dirty in
managing user inputs: are all the necessary parameters given a value? is
the input in the correct format? do the options and the inputs correspond?
and many other similar checks. So when an operation has well-defined inputs
and outputs and is commonly needed, it is much more worthwhile to simply do
use all the great features that Gnuastro has already defined for such
To make it easier to learn/apply the internal program infra-structure
discussed in Mandatory source code files, in the Version controlled source, Gnuastro ships with a template program. This template
program is not available in the Gnuastro tarball so it does not confuse
people using the tarball. The bin/TEMPLATE directory in Gnuastro’s
Git repository contains the bare-minimum files necessary to define a new
program and all the basic/necessary files/functions are pre-defined
Below you can see a list of initial steps to take for customizing this
template. We just assume that after cloning Gnuastro’s history, you have
already bootstrapped Gnuastro, if not, please see Bootstrapping.
- Select a name for your new program (for example, myprog).
- Copy the TEMPLATE directory to a directory with your program’s name:
$ cp -R bin/TEMPLATE bin/myprog
- As with all source files in Gnuastro, all the files in template also have a
copyright notice at their top. Open all the files and correct these
notices: 1) The first line contains a single-line description of the
program. 2) In the second line only the name or your program needs to be
fixed and 3) Add your name and email as a “Contributing author”. As your
program grows, you will need to add new files, do not forget to add this
notice in those new files too, just put your name and email under
“Original author” and correct the copyright years.
- Open configure.ac in the top Gnuastro source. This file manages the
operations that are done when a user runs ./configure. Going down
the file, you will notice repetitive parts for each program. You will
notice that the program names follow an alphabetic ordering in each
part. There is also a commented line/patch for the TEMPLATE program
in each part. You can copy one line/patch (from the program above or below
your desired name for example) and paste it in the proper place for your
new program. Then correct the names of the copied program to your new
program name. There are multiple places where this has to be done, so be
patient and go down to the bottom of the file. Ultimately add
AC_CONFIG_FILES, only here the
ordering depends on the length of the name (it is not alphabetical).
- Open Makefile.am in the top Gnuastro source. Similar to the previous
step, add your new program similar to all the other programs. Here there
are only two places: 1) at the top where we define the conditionals (three
lines per program), and 2) immediately under it as part of the value for
- Open doc/Makefile.am and similar to Makefile.am (above), add
the proper entries for the man-page of your program to be created (here,
the variable that keeps all the man-pages to be created is
dist_man_MANS). Then scroll down and add a rule to build the
man-page similar to the other existing rules (in alphabetical order). Do Not
forget to add a short one-line description here, it will be displayed on
top of the man-page.
myprog.h in the file names:
$ cd bin/myprog
$ mv TEMPLATE.c myprog.c
$ mv TEMPLATE.h myprog.h
Correct all occurrences of
TEMPLATE in the input files to
myprog (in short or long format). You can get a list of all
occurrences with the following command. If you use Emacs, it will be able to
parse the Grep output and open the proper file and line automatically. So
this step can be very easy.
$ grep --color -nHi -e template *
- Run the following commands to re-build the configuration and build system,
and then to configure and build Gnuastro (which now includes your exciting
$ autoreconf -f
- You are done! You can now start customizing your new program to do your
special processing. When it is complete, just do not forget to add checks
also, so it can be tested at least once on a user’s system with
make check, see Test scripts. Finally, if you would like to
share it with all Gnuastro users, inform us so we merge it into Gnuastro’s
Read in other formats.
GNU Astronomy Utilities 0.20 manual, April 2023.