Modifying VTF Makefiles with autoconf and automake

The VTF software uses autoconf and automake for compatible Makefile creation. Ensure that the right autoconf and automake versions are in the actual path. autoconf --version should give 2.59 or higher. automake --version should give 1.9 or higher. For convenience, the source code for these tools is also provided in vtf/third-party/autoconf.

The standard way of doing program development with autoconf and automake is to write a configure.ac file for your package and a Makefile.am file for each directory containing source files or further package subdirectories. Running the standard command autoreconf would go through the steps necessary to produce configure scripts and Makefile.in files as necessary. Then the top level configure script could be invoked as outlined on InstallationConfiguration.

make dependencies

Since this procedure can be extremely inefficient during source code development, autoconf/automake is able to regenerate dependent files as needed during the make-process. This is achieved with dependency rules in Makefile. When the Makefile.am for a single application has been modified, for instance, only its Makefile.in and Makefile are regenerated automatically when the application is recompiled with make. Similar dependencies exist for config.status, configure, config.h.in, and aclocal.m4 that are automatically updated after changes to configure.ac when make is used anywhere in the corresponding build directory.

The described make dependencies are disabled by default for the VTF by using the automake macro AM_MAINTAINER_MODE. This simplifies the usage of production systems since all generated autoconf/automake files can be checked into a CVS repository without problems. Using cvs update on checked out versions usually leads to timestamp mismatches in the autoconf/automake files and causes unwanted file regenerations. The problem is discussed at length in the CVS section of the automake manual.

To allow for convenient source code development, developers should therefore enable the autoconf/automake make dependencies (at least on their favorite development systems) by providing the option --enable-maintainer-mode to the top-level configure script or specifying MAINT=yes in vtf/setup.

Creating new build directories

The standard way for the developer to create a new (application) build directory is to create new local Makefile.am files and to add those to the corresponding configure.ac. Running autoreconf on configure.ac or just make (for --enable-maintainer-mode) on the build directory with the corresponding config.status will automatically create all necessary files and new build sub-directories.

1. Create the input file for automake Makefile.am. Copying and modifying an existing example is a good start. Gnu automake is quite convenient, but sometimes tricky. A close look on the manual typically answers most questions.
2. Add your new Makefile to the list AC_CONFIG_FILES([...]) in the local configure.ac file, e.g. AC_CONFIG_FILES([weno/applications/euler/2d/Newdir/src/Makefile ...]). When you are using --enable-maintainer-mode, you just need to go to gnu-debug-mpi/amroc/weno and type make.
3. When you are not using --enable-maintainer-mode, go into the directory with the modified configure.ac, i.e. to vtf/amroc/weno in our example, and execute autoreconf. If configure.ac was supposed to remain unchanged, use automake --foreign weno/applications/euler/2d/Newdir/src/Makefile to generate only vtf/amroc/weno/applications/euler/2d/Newdir/src/Makefile.in.
4. If vtf/amroc/weno/configure got updated, all necessary further steps will once again be carried out automatically by autoconf, if make is invoked in the build directory with config.status, which in our case is gnu-debug-mpi/amroc/weno.
5. If configure had to remain untouched, one can produce only specified Makefiles. Go into the gnu-debug-mpi/amroc/weno directory and execute ./config.status depfiles --files=amroc/weno/applications/euler/2d/Newdir/src/Makefile.
6. Finally go to gnu-debug-mpi/amroc/weno/applications/euler/2d/Newdir/src and type make.

Useful scripts

To simplify the program development with autoconf and automake the following scripts are provided in vtf/ac. To have them always available just append the directory vtf/ac to your PATH. Note that the usage of these scripts is completely optional. The previous paragraph contains ALL necessary native autoconf/automake commands to work with the VTF.

• prepare [Optional list of Makefiles]
  • Creates configure, Makefile.in and further internal files as needed. To be run from directory that contains configure.ac.
  • Without any options the script rebuilds all Makefile.in's specified in configure.ac and is identical to using autoreconf.
• prepare_all
  • Runs prepare in all subdirectories with a configure.ac. To be run on top-level vtf directory only by VTF admins. Idential to using autoreconf on top-level vtf directory.
• create [Optional list of Makefiles]
  • Creates Makefile. To be run from a build directory that contains config.status. The script can traverse downwards to visit multiple config.status files. By using ./config.status depfiles --files=[list of Makefiles] internally it is able to produce new build sub-directories without including the Makefiles into configure.ac. See below.

The scripts prepare and prepare_all are intended to produce Makefile.in from Makefile.am (to be written by the user) and to regenerate the script configure from configure.ac whenever necessary. If a configure script has been altered, the built-in dependencies in the files config.status in the build directory will automatically rerun config.status --recheck, which will regenerate all locally specified Makefiles. In order to regenerate only some Makefiles create is provided. Note that the usage of create also allows the creation of new subdirectories without touching configure or configure.ac.

1. Create the input file for automake Makefile.am as sketched above.
2. Optionally modify configure.ac.
3. Go into the directory with the modified configure.ac, i.e. to vtf/amroc/weno in our example, and execute prepare weno/applications/euler/2d/Newdir/src/Makefile. This will generate only vtf/amroc/weno/applications/euler/2d/Newdir/src/Makefile.in and update vtf/amroc/weno/configure if vtf/amroc/weno/configure.ac is newer.
4. If vtf/amroc/weno/configure got updated, all necessary further steps will be carried out automatically by autoconf, if make is invoked in the build directory with config.status, which in our case is gnu-debug-mpi/amroc/weno.
5. If the (sometimes too cumbersome) regeneration of all local Makefiles has to be avoided, configure has to remain untouched and create can be used to produce only specified Makefiles. Go into the current build directory, e.g. gnu-debug-mpi and execute create amroc/weno/applications/euler/2d/Newdir/src/Makefile. Equivalently, you could also go down to gnu-debug-mpi/amroc/weno and execute create applications/euler/2d/Newdir/src/Makefile.
6. Finally go to gnu-debug-mpi/amroc/weno/applications/euler/2d/Newdir/src and type make.

-- RalfDeiterding - 29 Dec 2016