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.
- 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.
- 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
.
- 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
.
- 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
.
- 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
.
- 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
.
- Create the input file for automake
Makefile.am
as sketched above.
- Optionally modify
configure.ac
.
- 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.
- 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
.
- 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
.
- Finally go to
gnu-debug-mpi/amroc/weno/applications/euler/2d/Newdir/src
and type make
.
--
RalfDeiterding - 29 Dec 2016