---

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 operations.

To make it easier to learn/apply the internal program infrastructure 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 there.

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.

1. Select a name for your new program (for example, myprog).
2. Copy the TEMPLATE directory to a directory with your program’s name:

   $ cp -R bin/TEMPLATE bin/myprog
   

3. 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.
4. 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 bin/myprog/Makefile to AC_CONFIG_FILES, only here the ordering depends on the length of the name (it is not alphabetical).
5. 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 SUBDIRS.
6. 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.
7. Change TEMPLATE.c and TEMPLATE.h to myprog.c and myprog.h in the file names:

   $ cd bin/myprog
   $ mv TEMPLATE.c myprog.c
   $ mv TEMPLATE.h myprog.h
   

8. 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 *
   

9. Run the following commands to rebuild the configuration and build system, and then to configure and build Gnuastro (which now includes your exciting new program).

   $ autoreconf -f
   $ ./configure
   $ make
   

10. 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 main history.