Substitutions in Makefiles

Each subdirectory in a distribution that contains something to be compiled or installed should come with a file Makefile.in, from which configure will create a Makefile in that directory. To create a Makefile, configure performs a simple variable substitution, replacing occurrences of @variable@ in Makefile.in with the value that configure has determined for that variable. Variables that are substituted into output files in this way are called output variables. They are ordinary shell variables that are set in configure. To make configure substitute a particular variable into the output files, the macro AC_SUBST must be called with that variable name as an argument. Any occurrences of @variable@ for other variables are left unchanged. the section called “Setting Output Variables”, for more information on creating output variables with AC_SUBST.

A software package that uses a configure script should be distributed with a file Makefile.in, but no Makefile; that way, the user has to properly configure the package for the local system before compiling it.

, for more information on what to put in Makefiles.

Preset Output Variables

Some output variables are preset by the Autoconf macros. Some of the Autoconf macros set additional output variables, which are mentioned in the descriptions for those macros. Output Variable Index, for a complete list of output variables. the section called “Installation Directory Variables”, for the list of the preset ones related to installation directories. Below are listed the other preset ones. They all are precious variables (the section called “Setting Output Variables”, AC_ARG_VAR).

function>CFLAGS/function> Debugging and optimization options for the C compiler. If it is not set in the environment when configure runs, the default value is set when you call AC_PROG_CC (or empty if you don't). configure uses this variable when compiling programs to test for C features.

function>configure_input/function> A comment saying that the file was generated automatically by configure and giving the name of the input file. AC_OUTPUT adds a comment line containing this variable to the top of every Makefile it creates. For other files, you should reference this variable in a comment at the top of each input file. For example, an input shell script should begin like this:

#! /bin/sh
# @configure_input@

The presence of that line also reminds people editing the file that it needs to be processed by configure in order to be used.

function>CPPFLAGS/function> Header file search directory (-Idir) and any other miscellaneous options for the C and C++ preprocessors and compilers. If it is not set in the environment when configure runs, the default value is empty. configure uses this variable when compiling or preprocessing programs to test for C and C++ features.

function>CXXFLAGS/function> Debugging and optimization options for the C++ compiler. If it is not set in the environment when configure runs, the default value is set when you call AC_PROG_CXX (or empty if you don't). configure uses this variable when compiling programs to test for C++ features.

function>DEFS/function> -D options to pass to the C compiler. If AC_CONFIG_HEADERS is called, configure replaces @DEFS@ with -DHAVE_CONFIG_H instead (the section called “Configuration Header Files ”). This variable is not defined while configure is performing its tests, only when creating the output files. the section called “Setting Output Variables”, for how to check the results of previous tests.

function>ECHO_C/function> function>ECHO_N/function> function>ECHO_T/function> How does one suppress the trailing newline from echo for question-answer message pairs? These variables provide a way:

echo $ECHO_N "And the winner is... $ECHO_C"
sleep 100000000000
echo "${ECHO_T}dead."

Some old and uncommon echo implementations offer no means to achieve this, in which case ECHO_T is set to tab. You might not want to use it.

function>FFLAGS/function> Debugging and optimization options for the Fortran 77 compiler. If it is not set in the environment when configure runs, the default value is set when you call AC_PROG_F77 (or empty if you don't). configure uses this variable when compiling programs to test for Fortran 77 features.

function>LDFLAGS/function> Stripping (-s), path (-L), and any other miscellaneous options for the linker. Don't use this variable to pass library names (-l) to the linker, use LIBS instead. If it is not set in the environment when configure runs, the default value is empty. configure uses this variable when linking programs to test for C, C++ and Fortran 77 features.

function>LIBS/function> -l options to pass to the linker. The default value is empty, but some Autoconf macros may prepend extra libraries to this variable if those libraries are found and provide necessary functions, see the section called “Library Files”. configure uses this variable when linking programs to test for C, C++ and Fortran 77 features.

function>builddir/function> Rigorously equal to .. Added for symmetry only.

function>abs_builddir/function> Absolute path of builddir.

function>top_builddir/function> The relative path to the top-level of the current build tree. In the top-level directory, this is the same as srcbuild.

function>abs_top_builddir/function> Absolute path of top_builddir.

function>srcdir/function> The relative path to the directory that contains the source code for that Makefile.

function>abs_srcdir/function> Absolute path of srcdir.

function>top_srcdir/function> The relative path to the top-level source code directory for the package. In the top-level directory, this is the same as srcdir.

function>abs_top_srcdir/function> Absolute path of top_srcdir.

Installation Directory Variables

The following variables specify the directories where the package will be installed, see , for more information. See the end of this section for details on when and how to use these variables.

function>bindir/function> The directory for installing executables that users run.

function>datadir/function> The directory for installing read-only architecture-independent data.

function>exec_prefix/function> The installation prefix for architecture-dependent files. By default it's the same as prefix. You should avoid installing anything directly to exec_prefix. However, the default value for directories containing architecture-dependent files should be relative to exec_prefix.

function>includedir/function> The directory for installing C header files.

function>infodir/function> The directory for installing documentation in Info format.

function>libdir/function> The directory for installing object code libraries.

function>libexecdir/function> The directory for installing executables that other programs run.

function>localstatedir/function> The directory for installing modifiable single-machine data.

function>mandir/function> The top-level directory for installing documentation in man format.

function>oldincludedir/function> The directory for installing C header files for non-gcc compilers.

function>prefix/function> The common installation prefix for all files. If exec_prefix is defined to a different value, prefix is used only for architecture-independent files.

function>sbindir/function> The directory for installing executables that system administrators run.

function>sharedstatedir/function> The directory for installing modifiable architecture-independent data.

function>sysconfdir/function> The directory for installing read-only single-machine data.

Most of these variables have values that rely on prefix or exec_prefix. It is deliberate that the directory output variables keep them unexpanded: typically @datadir@ will be replaced by ${prefix}/share, not /usr/local/share.

This behavior is mandated by the gnu coding standards, so that when the user runs:

make

she can still specify a different prefix from the one specified to configure, in which case, if needed, the package shall hard code dependencies corresponding to the make-specified prefix.

make install

she can specify a different installation location, in which case the package must still depend on the location which was compiled in (i.e., never recompile when make install is run). This is an extremely important feature, as many people may decide to install all the files of a package grouped together, and then install links from the final locations to there.

In order to support these features, it is essential that datadir remains being defined as ${prefix}/share to depend upon the current value of prefix.

A corollary is that you should not use these variables except in Makefiles. For instance, instead of trying to evaluate datadir in configure and hardcoding it in Makefiles using e.g. AC_DEFINE_UNQUOTED(DATADIR, "$datadir"), you should add -DDATADIR="$(datadir)" to your CPPFLAGS.

Similarly you should not rely on AC_OUTPUT_FILES to replace datadir and friends in your shell scripts and other files, rather let make manage their replacement. For instance Autoconf ships templates of its shell scripts ending with .sh, and uses this Makefile snippet:

.sh:
        rm -f $@ $@.tmp
        sed 's,@datadir\@,$(pkgdatadir),g' $ $@.tmp
        chmod +x $@.tmp
        mv $@.tmp $@

Three things are noteworthy:

@datadir\@

The backslash prevents configure from replacing @datadir@ in the sed expression itself.

$(pkgdatadir)

Don't use @pkgdatadir@! Use the matching makefile variable instead.

,

Don't use / in the sed expression(s) since most probably the variables you use, such as $(pkgdatadir), will contain some.

Build Directories

You can support compiling a software package for several architectures simultaneously from the same copy of the source code. The object files for each architecture are kept in their own directory.

To support doing this, make uses the VPATH variable to find the files that are in the source directory. gnu Make and most other recent make programs can do this. Older make programs do not support VPATH; when using them, the source code must be in the same directory as the object files.

To support VPATH, each Makefile.in should contain two lines that look like:

srcdir = @srcdir@
VPATH = @srcdir@

Do not set VPATH to the value of another variable, for example VPATH = $(srcdir), because some versions of make do not do variable substitutions on the value of VPATH.

configure substitutes in the correct value for srcdir when it produces Makefile.

Do not use the make variable $, which expands to the file name of the file in the source directory (found with VPATH), except in implicit rules. (An implicit rule is one such as .c.o, which tells how to create a .o file from a .c file.) Some versions of make do not set $ in explicit rules; they expand it to an empty value.

Instead, Makefile command lines should always refer to source files by prefixing them with $(srcdir)/. For example:

time.info: time.texinfo
        $(MAKEINFO) $(srcdir)/time.texinfo

Automatic Remaking

You can put rules like the following in the top-level Makefile.in for a package to automatically update the configuration information when you change the configuration files. This example includes all of the optional files, such as aclocal.m4 and those related to configuration header files. Omit from the Makefile.in rules for any of these files that your package does not use.

The $(srcdir)/ prefix is included because of limitations in the VPATH mechanism.

The stamp- files are necessary because the timestamps of config.h.in and config.h will not be changed if remaking them does not change their contents. This feature avoids unnecessary recompilation. You should include the file stamp-h.in your package's distribution, so make will consider config.h.in up to date. Don't use touch (the section called “Limitations of Usual Tools”), rather use echo (using date would cause needless differences, hence cvs conflicts etc.).

$(srcdir)/configure: configure.ac aclocal.m4
        cd $(srcdir)  autoconf

# autoheader might not change config.h.in, so touch a stamp file.
$(srcdir)/config.h.in: stamp-h.in
$(srcdir)/stamp-h.in: configure.ac aclocal.m4
        cd $(srcdir)  autoheader
        echo timestamp  $(srcdir)/stamp-h.in

config.h: stamp-h
stamp-h: config.h.in config.status
        ./config.status

Makefile: Makefile.in config.status
        ./config.status

config.status: configure
        ./config.status --recheck
     

(Be careful if you copy these lines directly into your Makefile, as you will need to convert the indented lines to start with the tab character.)

In addition, you should use AC_CONFIG_FILES([stamp-h], [echo timestamp stamp-h]) so config.status will ensure that config.h is considered up to date. the section called “Outputting Files”, for more information about AC_OUTPUT.

Chapter 15, for more examples of handling configuration-related dependencies.