This manual is for GNU Automake (version 1.16.2, 1 February 2020), a
program that creates GNU standards-compliant Makefiles from template
files.

   Copyright © 1995–2020 Free Software Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.3 or any later version published by the Free Software
     Foundation; with no Invariant Sections, with no Front-Cover texts,
     and with no Back-Cover Texts.  A copy of the license is included in
     the section entitled “GNU Free Documentation License.”

12.4 Staged Installs
====================

Automake generates support for the ‘DESTDIR’ variable in all install
rules.  ‘DESTDIR’ is used during the ‘make install’ step to relocate
install objects into a staging area.  Each object and path is prefixed
with the value of ‘DESTDIR’ before being copied into the install area.
Here is an example of typical DESTDIR usage:

     mkdir /tmp/staging &&
     make DESTDIR=/tmp/staging install

   The ‘mkdir’ command avoids a security problem if the attacker creates
a symbolic link from ‘/tmp/staging’ to a victim area; then ‘make’ places
install objects in a directory tree built under ‘/tmp/staging’.  If
‘/gnu/bin/foo’ and ‘/gnu/share/aclocal/foo.m4’ are to be installed, the
above command would install ‘/tmp/staging/gnu/bin/foo’ and
‘/tmp/staging/gnu/share/aclocal/foo.m4’.

   This feature is commonly used to build install images and packages
(see DESTDIR).

   Support for ‘DESTDIR’ is implemented by coding it directly into the
install rules.  If your ‘Makefile.am’ uses a local install rule (e.g.,
‘install-exec-local’) or an install hook, then you must write that code
to respect ‘DESTDIR’.

   See Makefile Conventions (standards), for another usage example.

12.5 Install Rules for the User
===============================

Automake also generates rules for targets ‘uninstall’, ‘installdirs’,
and ‘install-strip’.

   Automake supports ‘uninstall-local’ and ‘uninstall-hook’.  There is
no notion of separate uninstalls for “exec” and “data”, as these
features would not provide additional functionality.

   Note that ‘uninstall’ is not meant as a replacement for a real
packaging tool.

13 What Gets Cleaned
********************

The GNU Makefile Standards specify a number of different clean rules.
See Standard Targets for Users (standards).

   Generally the files that can be cleaned are determined automatically
by Automake.  Of course, Automake also recognizes some variables that
can be defined to specify additional files to clean.  These variables
are ‘MOSTLYCLEANFILES’, ‘CLEANFILES’, ‘DISTCLEANFILES’, and
‘MAINTAINERCLEANFILES’.

   When cleaning involves more than deleting some hard-coded list of
files, it is also possible to supplement the cleaning rules with your
own commands.  Simply define a rule for any of the ‘mostlyclean-local’,
‘clean-local’, ‘distclean-local’, or ‘maintainer-clean-local’ targets
(see Extending).  A common case is deleting a directory, for
instance, a directory created by the test suite:

     clean-local:
             -rm -rf testSubDir

   Since ‘make’ allows only one set of rules for a given target, a more
extensible way of writing this is to use a separate target listed as a
dependency:

     clean-local: clean-local-check
     .PHONY: clean-local-check
     clean-local-check:
             -rm -rf testSubDir

   As the GNU Standards aren’t always explicit as to which files should
be removed by which rule, we’ve adopted a heuristic that we believe was
first formulated by François Pinard:

   • If ‘make’ built it, and it is commonly something that one would
     want to rebuild (for instance, a ‘.o’ file), then ‘mostlyclean’
     should delete it.

   • Otherwise, if ‘make’ built it, then ‘clean’ should delete it.

   • If ‘configure’ built it, then ‘distclean’ should delete it.

   • If the maintainer built it (for instance, a ‘.info’ file), then
     ‘maintainer-clean’ should delete it.  However ‘maintainer-clean’
     should not delete anything that needs to exist in order to run
     ‘./configure && make’.

   We recommend that you follow this same set of heuristics in your
‘Makefile.am’.

14 What Goes in a Distribution
******************************

14.1 Basics of Distribution
===========================

The ‘dist’ rule in the generated ‘Makefile.in’ can be used to generate a
gzipped ‘tar’ file and other flavors of archive for distribution.  The
file is named based on the ‘PACKAGE’ and ‘VERSION’ variables
automatically defined by either the ‘AC_INIT’ invocation or by a
_deprecated_ two-arguments invocation of the ‘AM_INIT_AUTOMAKE’ macro
(see Public Macros for how these variables get their values,
from either defaults or explicit values – it’s slightly trickier than
one would expect).  More precisely the gzipped ‘tar’ file is named
‘${PACKAGE}-${VERSION}.tar.gz’.  You can use the ‘make’ variable
‘GZIP_ENV’ to control how gzip is run.  The default setting is ‘--best’.

   For the most part, the files to distribute are automatically found by
Automake: all source files are automatically included in a distribution,
as are all ‘Makefile.am’ and ‘Makefile.in’ files.  Automake also has a
built-in list of commonly used files that are automatically included if
they are found in the current directory (either physically, or as the
target of a ‘Makefile.am’ rule); this list is printed by ‘automake
--help’.  Note that some files in this list are actually distributed
only if other certain conditions hold (for example, the ‘config.h.top’
and ‘config.h.bot’ files are automatically distributed only if, e.g.,
‘AC_CONFIG_HEADERS([config.h])’ is used in ‘configure.ac’).  Also, files
that are read by ‘configure’ (i.e. the source files corresponding to the
files specified in various Autoconf macros such as ‘AC_CONFIG_FILES’ and
siblings) are automatically distributed.  Files included in a
‘Makefile.am’ (using ‘include’) or in ‘configure.ac’ (using
‘m4_include’), and helper scripts installed with ‘automake
--add-missing’ are also distributed.

   Still, sometimes there are files that must be distributed, but which
are not covered in the automatic rules.  These files should be listed in
the ‘EXTRA_DIST’ variable.  You can mention files from subdirectories in
‘EXTRA_DIST’.

   You can also mention a directory in ‘EXTRA_DIST’; in this case the
entire directory will be recursively copied into the distribution.
Please note that this will also copy _everything_ in the directory,
including, e.g., Subversion’s ‘.svn’ private directories or CVS/RCS
version control files; thus we recommend against using this feature
as-is.  However, you can use the ‘dist-hook’ feature to ameliorate the
problem; see The dist Hook.

   If you define ‘SUBDIRS’, Automake will recursively include the
subdirectories in the distribution.  If ‘SUBDIRS’ is defined
conditionally (see Conditionals), Automake will normally include all
directories that could possibly appear in ‘SUBDIRS’ in the distribution.
If you need to specify the set of directories conditionally, you can set
the variable ‘DIST_SUBDIRS’ to the exact list of subdirectories to
include in the distribution (see Conditional Subdirectories).

14.2 Fine-grained Distribution Control
======================================

Sometimes you need tighter control over what does _not_ go into the
distribution; for instance, you might have source files that are
generated and that you do not want to distribute.  In this case Automake
gives fine-grained control using the ‘dist’ and ‘nodist’ prefixes.  Any
primary or ‘_SOURCES’ variable can be prefixed with ‘dist_’ to add the
listed files to the distribution.  Similarly, ‘nodist_’ can be used to
omit the files from the distribution.

   As an example, here is how you would cause some data to be
distributed while leaving some source code out of the distribution:

     dist_data_DATA = distribute-this
     bin_PROGRAMS = foo
     nodist_foo_SOURCES = do-not-distribute.c

14.3 The dist Hook
==================

Occasionally it is useful to be able to change the distribution before
it is packaged up.  If the ‘dist-hook’ rule exists, it is run after the
distribution directory is filled, but before the actual distribution
archives are created.  One way to use this is for removing unnecessary
files that get recursively included by specifying a directory in
‘EXTRA_DIST’:

     EXTRA_DIST = doc
     dist-hook:
             rm -rf `find $(distdir)/doc -type d -name .svn`

Note that the ‘dist-hook’ recipe shouldn’t assume that the regular files
in the distribution directory are writable; this might not be the case
if one is packaging from a read-only source tree, or when a ‘make
distcheck’ is being done.  For similar reasons, the recipe shouldn’t
assume that the subdirectories put into the distribution directory as an
effect of having them listed in ‘EXTRA_DIST’ are writable.  So, if the
‘dist-hook’ recipe wants to modify the content of an existing file (or
‘EXTRA_DIST’ subdirectory) in the distribution directory, it should
explicitly to make it writable first:

     EXTRA_DIST = README doc
     dist-hook:
             chmod u+w $(distdir)/README $(distdir)/doc
             echo "Distribution date: `date`" >> README
             rm -f $(distdir)/doc/HACKING

   Two variables that come handy when writing ‘dist-hook’ rules are
‘$(distdir)’ and ‘$(top_distdir)’.

   ‘$(distdir)’ points to the directory where the ‘dist’ rule will copy
files from the current directory before creating the tarball.  If you
are at the top-level directory, then ‘distdir = $(PACKAGE)-$(VERSION)’.
When used from subdirectory named ‘foo/’, then ‘distdir =
../$(PACKAGE)-$(VERSION)/foo’.  ‘$(distdir)’ can be a relative or
absolute path, do not assume any form.

   ‘$(top_distdir)’ always points to the root directory of the
distributed tree.  At the top-level it’s equal to ‘$(distdir)’.  In the
‘foo/’ subdirectory ‘top_distdir = ../$(PACKAGE)-$(VERSION)’.
‘$(top_distdir)’ too can be a relative or absolute path.

   Note that when packages are nested using ‘AC_CONFIG_SUBDIRS’ (see
Subpackages), then ‘$(distdir)’ and ‘$(top_distdir)’ are relative to
the package where ‘make dist’ was run, not to any sub-packages involved.

14.4 Checking the Distribution
==============================

Automake also generates a ‘distcheck’ rule that can be of help to ensure
that a given distribution will actually work.  Simplifying a bit, we can
say this rule first makes a distribution, and then, _operating from it_,
takes the following steps:
   • tries to do a ‘VPATH’ build (see VPATH Builds), with the
     ‘srcdir’ and all its content made _read-only_;
   • runs the test suite (with ‘make check’) on this fresh build;
   • installs the package in a temporary directory (with ‘make
     install’), and runs the test suite on the resulting installation
     (with ‘make installcheck’);
   • checks that the package can be correctly uninstalled (by ‘make
     uninstall’) and cleaned (by ‘make distclean’);
   • finally, makes another tarball to ensure the distribution is
     self-contained.

   All of these actions are performed in a temporary directory.  Please
note that the exact location and the exact structure of such a directory
(where the read-only sources are placed, how the temporary build and
install directories are named and how deeply they are nested, etc.)  is
to be considered an implementation detail, which can change at any time;
so do not rely on it.

DISTCHECK_CONFIGURE_FLAGS
-------------------------

Building the package involves running ‘./configure’.  If you need to
supply additional flags to ‘configure’, define them in the
‘AM_DISTCHECK_CONFIGURE_FLAGS’ variable in your top-level ‘Makefile.am’.
The user can still extend or override the flags provided there by
defining the ‘DISTCHECK_CONFIGURE_FLAGS’ variable, on the command line
when invoking ‘make’.  It’s worth noting that ‘make distcheck’ needs
complete control over the ‘configure’ options ‘--srcdir’ and ‘--prefix’,
so those options cannot be overridden by ‘AM_DISTCHECK_CONFIGURE_FLAGS’
nor by ‘DISTCHECK_CONFIGURE_FLAGS’.

   Also note that developers are encouraged to strive to make their code
buildable without requiring any special configure option; thus, in
general, you shouldn’t define ‘AM_DISTCHECK_CONFIGURE_FLAGS’.  However,
there might be few scenarios in which the use of this variable is
justified.  GNU ‘m4’ offers an example.  GNU ‘m4’ configures by default
with its experimental and seldom used "changeword" feature disabled; so
in this case it is useful to have ‘make distcheck’ run configure with
the ‘--with-changeword’ option, to ensure that the code for changeword
support still compiles correctly.  GNU ‘m4’ also employs the
‘AM_DISTCHECK_CONFIGURE_FLAGS’ variable to stress-test the use of
‘--program-prefix=g’, since at one point the ‘m4’ build system had a bug
where ‘make installcheck’ was wrongly assuming it could blindly test
"‘m4’", rather than the just-installed "‘gm4’".

distcheck-hook
--------------

If the ‘distcheck-hook’ rule is defined in your top-level ‘Makefile.am’,
then it will be invoked by ‘distcheck’ after the new distribution has
been unpacked, but before the unpacked copy is configured and built.
Your ‘distcheck-hook’ can do almost anything, though as always caution
is advised.  Generally this hook is used to check for potential
distribution errors not caught by the standard mechanism.  Note that
‘distcheck-hook’ as well as ‘AM_DISTCHECK_CONFIGURE_FLAGS’ and
‘DISTCHECK_CONFIGURE_FLAGS’ are not honored in a subpackage
‘Makefile.am’, but the flags from ‘AM_DISTCHECK_CONFIGURE_FLAGS’ and
‘DISTCHECK_CONFIGURE_FLAGS’ are passed down to the ‘configure’ script of
the subpackage.

distcleancheck
--------------

Speaking of potential distribution errors, ‘distcheck’ also ensures that
the ‘distclean’ rule actually removes all built files.  This is done by
running ‘make distcleancheck’ at the end of the ‘VPATH’ build.  By
default, ‘distcleancheck’ will run ‘distclean’ and then make sure the
build tree has been emptied by running ‘$(distcleancheck_listfiles)’.
Usually this check will find generated files that you forgot to add to
the ‘DISTCLEANFILES’ variable (see Clean).

   The ‘distcleancheck’ behavior should be OK for most packages,
otherwise you have the possibility to override the definition of either
the ‘distcleancheck’ rule, or the ‘$(distcleancheck_listfiles)’
variable.  For instance, to disable ‘distcleancheck’ completely, add the
following rule to your top-level ‘Makefile.am’:

     distcleancheck:
             @:

   If you want ‘distcleancheck’ to ignore built files that have not been
cleaned because they are also part of the distribution, add the
following definition instead:

     distcleancheck_listfiles = \
       find . -type f -exec sh -c 'test -f $(srcdir)/$$1 || echo $$1' \
            sh '{}' ';'

   The above definition is not the default because it’s usually an error
if your Makefiles cause some distributed files to be rebuilt when the
user builds the package.  (Think about the user missing the tool
required to build the file; or if the required tool is built by your
package, consider the cross-compilation case where it can’t be run.)
There is an entry in the FAQ about this (see Errors with distclean);
make sure you read it before playing with ‘distcleancheck_listfiles’.

distuninstallcheck
------------------

‘distcheck’ also checks that the ‘uninstall’ rule works properly, both
for ordinary and ‘DESTDIR’ builds.  It does this by invoking ‘make
uninstall’, and then it checks the install tree to see if any files are
left over.  This check will make sure that you correctly coded your
‘uninstall’-related rules.

   By default, the checking is done by the ‘distuninstallcheck’ rule,
and the list of files in the install tree is generated by
‘$(distuninstallcheck_listfiles)’ (this is a variable whose value is a
shell command to run that prints the list of files to stdout).

   Either of these can be overridden to modify the behavior of
‘distcheck’.  For instance, to disable this check completely, you would
write:

     distuninstallcheck:
             @:

14.5 The Types of Distributions
===============================

Automake generates rules to provide archives of the project for
distributions in various formats.  Their targets are:

‘dist-gzip’
     Generate a ‘gzip’ tar archive of the distribution.  This is the
     only format enabled by default.

‘dist-bzip2’
     Generate a ‘bzip2’ tar archive of the distribution.  bzip2 archives
     are frequently smaller than gzipped archives.  By default, this
     rule makes ‘bzip2’ use a compression option of ‘-9’.  To make it
     use a different one, set the ‘BZIP2’ environment variable.  For
     example, ‘make dist-bzip2 BZIP2=-7’.

‘dist-lzip’
     Generate an ‘lzip’ tar archive of the distribution.  ‘lzip’
     archives are frequently smaller than ‘bzip2’-compressed archives.

‘dist-xz’
     Generate an ‘xz’ tar archive of the distribution.  ‘xz’ archives
     are frequently smaller than ‘bzip2’-compressed archives.  By
     default, this rule makes ‘xz’ use a compression option of ‘-e’.  To
     make it use a different one, set the ‘XZ_OPT’ environment variable.
     For example, run this command to use the default compression ratio,
     but with a progress indicator: ‘make dist-xz XZ_OPT=-ve’.

‘dist-zip’
     Generate a ‘zip’ archive of the distribution.

‘dist-tarZ’
     Generate a tar archive of the distribution, compressed with the
     historical (and obsolescent) program ‘compress’.  This option is
     deprecated, and it and the corresponding functionality will be
     removed altogether in Automake 2.0.

‘dist-shar’
     Generate a ‘shar’ archive of the distribution.  This format archive
     is obsolescent, and use of this option is deprecated.  It and the
     corresponding functionality will be removed altogether in Automake
     2.0.

‘dist-zstd’
     Generate a ‘zstd’ tar archive of the distribution.  By default,
     this rule makes ‘zstd’ use a compression option of ‘-19’.  To make
     it use a different one, set the ‘ZSTD_OPT’ environment variable.
     For example, run this command to use the default compression ratio,
     but with a progress indicator: ‘make dist-zstd ZSTD_OPT=-19v’.
     However, note that for compatibility with zstd itself, you may
     instead set the ‘ZSTD_CLEVEL’ environment variable, in which case,
     any ‘ZSTD_OPT’ setting is ignored.

   The rule ‘dist’ (and its historical synonym ‘dist-all’) will create
archives in all the enabled formats (see List of Automake options
for how to change this list).  By default, only the ‘dist-gzip’ target
is hooked to ‘dist’.

15 Support for test suites
**************************

Automake can generate code to handle two kinds of test suites.  One is
based on integration with the ‘dejagnu’ framework.  The other (and most
used) form is based on the use of generic test scripts, and its
activation is triggered by the definition of the special ‘TESTS’
variable.  This second form allows for various degrees of sophistication
and customization; in particular, it allows for concurrent execution of
test scripts, use of established test protocols such as TAP, and
definition of custom test drivers and test runners.

In either case, the testsuite is invoked via ‘make check’.

15.1 Generalities about Testing
===============================

The purpose of testing is to determine whether a program or system
behaves as expected (e.g., known inputs produce the expected outputs,
error conditions are correctly handled or reported, and older bugs do
not resurface).

   The minimal unit of testing is usually called _test case_, or simply
_test_.  How a test case is defined or delimited, and even what exactly
_constitutes_ a test case, depends heavily on the testing paradigm
and/or framework in use, so we won’t attempt any more precise
definition.  The set of the test cases for a given program or system
constitutes its _testsuite_.

   A _test harness_ (also _testsuite harness_) is a program or software
component that executes all (or part of) the defined test cases,
analyzes their outcomes, and reports or registers these outcomes
appropriately.  Again, the details of how this is accomplished (and how
the developer and user can influence it or interface with it) varies
wildly, and we’ll attempt no precise definition.

   A test is said to _pass_ when it can determine that the condition or
behaviour it means to verify holds, and is said to _fail_ when it can
determine that such condition of behaviour does _not_ hold.

   Sometimes, tests can rely on non-portable tools or prerequisites, or
simply make no sense on a given system (for example, a test checking a
Windows-specific feature makes no sense on a GNU/Linux system).  In this
case, accordingly to the definition above, the tests can neither be
considered passed nor failed; instead, they are _skipped_ – i.e., they
are not run, or their result is anyway ignored for what concerns the
count of failures and successes.  Skips are usually explicitly reported
though, so that the user will be aware that not all of the testsuite has
really run.

   It’s not uncommon, especially during early development stages, that
some tests fail for known reasons, and that the developer doesn’t want
to tackle these failures immediately (this is especially true when the
failing tests deal with corner cases).  In this situation, the better
policy is to declare that each of those failures is an _expected
failure_ (or _xfail_).  In case a test that is expected to fail ends up
passing instead, many testing environments will flag the result as a
special kind of failure called _unexpected pass_ (or _xpass_).

   Many testing environments and frameworks distinguish between test
failures and hard errors.  As we’ve seen, a test failure happens when
some invariant or expected behaviour of the software under test is not
met.  A _hard error_ happens when e.g., the set-up of a test case
scenario fails, or when some other unexpected or highly undesirable
condition is encountered (for example, the program under test
experiences a segmentation fault).

15.2 Simple Tests
=================

15.2.1 Scripts-based Testsuites
-------------------------------

If the special variable ‘TESTS’ is defined, its value is taken to be a
list of programs or scripts to run in order to do the testing.  Under
the appropriate circumstances, it’s possible for ‘TESTS’ to list also
data files to be passed to one or more test scripts defined by different
means (the so-called “log compilers”, see Parallel Test Harness).

   Test scripts can be executed serially or concurrently.  Automake
supports both these kinds of test execution, with the parallel test
harness being the default.  The concurrent test harness relies on the
concurrence capabilities (if any) offered by the underlying ‘make’
implementation, and can thus only be as good as those are.

   By default, only the exit statuses of the test scripts are considered
when determining the testsuite outcome.  But Automake allows also the
use of more complex test protocols, either standard (see Using the TAP test protocol)
or custom (see Custom Test Drivers).  Note that you
can’t enable such protocols when the serial harness is used, though.  In
the rest of this section we are going to concentrate mostly on
protocol-less tests, since we cover test protocols in a later section
(again, see Custom Test Drivers).

   When no test protocol is in use, an exit status of 0 from a test
script will denote a success, an exit status of 77 a skipped test, an
exit status of 99 a hard error, and any other exit status will denote a
failure.

   You may define the variable ‘XFAIL_TESTS’ to a list of tests (usually
a subset of ‘TESTS’) that are expected to fail; this will effectively
reverse the result of those tests (with the provision that skips and
hard errors remain untouched).  You may also instruct the testsuite
harness to treat hard errors like simple failures, by defining the
‘DISABLE_HARD_ERRORS’ make variable to a nonempty value.

   Note however that, for tests based on more complex test protocols,
the exact effects of ‘XFAIL_TESTS’ and ‘DISABLE_HARD_ERRORS’ might
change, or they might even have no effect at all (for example, in tests
using TAP, there is no way to disable hard errors, and the
‘DISABLE_HARD_ERRORS’ variable has no effect on them).

   The result of each test case run by the scripts in ‘TESTS’ will be
printed on standard output, along with the test name.  For test
protocols that allow more test cases per test script (such as TAP), a
number, identifier and/or brief description specific for the single test
case is expected to be printed in addition to the name of the test
script.  The possible results (whose meanings should be clear from the
previous Generalities about Testing) are ‘PASS’, ‘FAIL’, ‘SKIP’,
‘XFAIL’, ‘XPASS’ and ‘ERROR’.  Here is an example of output from a
hypothetical testsuite that uses both plain and TAP tests:
     PASS: foo.sh
     PASS: zardoz.tap 1 - Daemon started
     PASS: zardoz.tap 2 - Daemon responding
     SKIP: zardoz.tap 3 - Daemon uses /proc # SKIP /proc is not mounted
     PASS: zardoz.tap 4 - Daemon stopped
     SKIP: bar.sh
     PASS: mu.tap 1
     XFAIL: mu.tap 2 # TODO frobnication not yet implemented

A testsuite summary (expected to report at least the number of run,
skipped and failed tests) will be printed at the end of the testsuite
run.

   If the standard output is connected to a capable terminal, then the
test results and the summary are colored appropriately.  The developer
and the user can disable colored output by setting the ‘make’ variable
‘AM_COLOR_TESTS=no’; the user can in addition force colored output even
without a connecting terminal with ‘AM_COLOR_TESTS=always’.  It’s also
worth noting that some ‘make’ implementations, when used in parallel
mode, have slightly different semantics (see Parallel make (autoconf)),
which can break the automatic detection of a connection to a
capable terminal.  If this is the case, the user will have to resort to
the use of ‘AM_COLOR_TESTS=always’ in order to have the testsuite output
colorized.

   Test programs that need data files should look for them in ‘srcdir’
(which is both a make variable and an environment variable made
available to the tests), so that they work when building in a separate
directory (see Build Directories (autoconf)), and
in particular for the ‘distcheck’ rule (see Checking the Distribution).

   The ‘AM_TESTS_ENVIRONMENT’ and ‘TESTS_ENVIRONMENT’ variables can be
used to run initialization code and set environment variables for the
test scripts.  The former variable is developer-reserved, and can be
defined in the ‘Makefile.am’, while the latter is reserved for the user,
which can employ it to extend or override the settings in the former;
for this to work portably, however, the contents of a non-empty
‘AM_TESTS_ENVIRONMENT’ _must_ be terminated by a semicolon.

   The ‘AM_TESTS_FD_REDIRECT’ variable can be used to define file
descriptor redirections for the test scripts.  One might think that
‘AM_TESTS_ENVIRONMENT’ could be used for this purpose, but experience
has shown that doing so portably is practically impossible.  The main
hurdle is constituted by Korn shells, which usually set the
close-on-exec flag on file descriptors opened with the ‘exec’ builtin,
thus rendering an idiom like ‘AM_TESTS_ENVIRONMENT = exec 9>&2;’
ineffectual.  This issue also affects some Bourne shells, such as the
HP-UX’s ‘/bin/sh’,

     AM_TESTS_ENVIRONMENT = \
     ## Some environment initializations are kept in a separate shell
     ## file 'tests-env.sh', which can make it easier to also run tests
     ## from the command line.
       . $(srcdir)/tests-env.sh; \
     ## On Solaris, prefer more POSIX-compliant versions of the standard
     ## tools by default.
       if test -d /usr/xpg4/bin; then \
         PATH=/usr/xpg4/bin:$$PATH; export PATH; \
       fi;
     ## With this, the test scripts will be able to print diagnostic
     ## messages to the original standard error stream, even if the test
     ## driver redirects the stderr of the test scripts to a log file
     ## before executing them.
     AM_TESTS_FD_REDIRECT = 9>&2

Note however that ‘AM_TESTS_ENVIRONMENT’ is, for historical and
implementation reasons, _not_ supported by the serial harness (see
Serial Test Harness).

   Automake ensures that each file listed in ‘TESTS’ is built before it
is run; you can list both source and derived programs (or scripts) in
‘TESTS’; the generated rule will look both in ‘srcdir’ and ’‘..’’.  For
instance, you might want to run a C program as a test.  To do this you
would list its name in ‘TESTS’ and also in ‘check_PROGRAMS’, and then
specify it as you would any other program.

   Programs listed in ‘check_PROGRAMS’ (and ‘check_LIBRARIES’,
‘check_LTLIBRARIES’...)  are only built during ‘make check’, not during
‘make all’.  You should list there any program needed by your tests that
does not need to be built by ‘make all’.  Note that ‘check_PROGRAMS’ are
_not_ automatically added to ‘TESTS’ because ‘check_PROGRAMS’ usually
lists programs used by the tests, not the tests themselves.  Of course
you can set ‘TESTS = $(check_PROGRAMS)’ if all your programs are test
cases.

15.2.2 Older (and discouraged) serial test harness
--------------------------------------------------

First, note that today the use of this harness is strongly discouraged
in favour of the parallel test harness (see Parallel Test Harness).
Still, there are a _few_ situations when the advantages offered by the
parallel harness are irrelevant, and when test concurrency can even
cause tricky problems.  In those cases, it might make sense to still use
the serial harness, for simplicity and reliability (we still suggest
trying to give the parallel harness a shot though).

   The serial test harness is enabled by the Automake option
‘serial-tests’.  It operates by simply running the tests serially, one
at the time, without any I/O redirection.  It’s up to the user to
implement logging of tests’ output, if that’s required or desired.

   For historical and implementation reasons, the ‘AM_TESTS_ENVIRONMENT’
variable is _not_ supported by this harness (it will be silently ignored
if defined); only ‘TESTS_ENVIRONMENT’ is, and it is to be considered a
developer-reserved variable.  This is done so that, when using the
serial harness, ‘TESTS_ENVIRONMENT’ can be defined to an invocation of
an interpreter through which the tests are to be run.  For instance, the
following setup may be used to run tests with Perl:

     TESTS_ENVIRONMENT = $(PERL) -Mstrict -w
     TESTS = foo.pl bar.pl baz.pl

It’s important to note that the use of ‘TESTS_ENVIRONMENT’ endorsed here
would be _invalid_ with the parallel harness.  That harness provides a
more elegant way to achieve the same effect, with the further benefit of
freeing the ‘TESTS_ENVIRONMENT’ variable for the user (see Parallel Test Harness).

   Another, less serious limitation of the serial harness is that it
doesn’t really distinguish between simple failures and hard errors; this
is due to historical reasons only, and might be fixed in future Automake
versions.

15.2.3 Parallel Test Harness
----------------------------

By default, Automake generated a parallel (concurrent) test harness.  It
features automatic collection of the test scripts output in ‘.log’
files, concurrent execution of tests with ‘make -j’, specification of
inter-test dependencies, lazy reruns of tests that have not completed in
a prior run, and hard errors for exceptional failures.

   The parallel test harness operates by defining a set of ‘make’ rules
that run the test scripts listed in ‘TESTS’, and, for each such script,
save its output in a corresponding ‘.log’ file and its results (and
other “metadata”, see API for Custom Test Drivers) in a
corresponding ‘.trs’ (as in Test ReSults) file.  The ‘.log’ file will
contain all the output emitted by the test on its standard output and
its standard error.  The ‘.trs’ file will contain, among the other
things, the results of the test cases run by the script.

   The parallel test harness will also create a summary log file,
‘TEST_SUITE_LOG’, which defaults to ‘test-suite.log’ and requires a
‘.log’ suffix.  This file depends upon all the ‘.log’ and ‘.trs’ files
created for the test scripts listed in ‘TESTS’.

   As with the serial harness above, by default one status line is
printed per completed test, and a short summary after the suite has
completed.  However, standard output and standard error of the test are
redirected to a per-test log file, so that parallel execution does not
produce intermingled output.  The output from failed tests is collected
in the ‘test-suite.log’ file.  If the variable ‘VERBOSE’ is set, this
file is output after the summary.

   Each couple of ‘.log’ and ‘.trs’ files is created when the
corresponding test has completed.  The set of log files is listed in the
read-only variable ‘TEST_LOGS’, and defaults to ‘TESTS’, with the
executable extension if any (see EXEEXT), as well as any suffix
listed in ‘TEST_EXTENSIONS’ removed, and ‘.log’ appended.  Results are
undefined if a test file name ends in several concatenated suffixes.
‘TEST_EXTENSIONS’ defaults to ‘.test’; it can be overridden by the user,
in which case any extension listed in it must be constituted by a dot,
followed by a non-digit alphabetic character, followed by any number of
alphabetic characters.  For example, ‘.sh’, ‘.T’ and ‘.t1’ are valid
extensions, while ‘.x-y’, ‘.6c’ and ‘.t.1’ are not.

   It is important to note that, due to current limitations (unlikely to
be lifted), configure substitutions in the definition of ‘TESTS’ can
only work if they will expand to a list of tests that have a suffix
listed in ‘TEST_EXTENSIONS’.

   For tests that match an extension ‘.EXT’ listed in ‘TEST_EXTENSIONS’,
you can provide a custom “test runner” using the variable
‘EXT_LOG_COMPILER’ (note the upper-case extension) and pass options in
‘AM_EXT_LOG_FLAGS’ and allow the user to pass options in
‘EXT_LOG_FLAGS’.  It will cause all tests with this extension to be
called with this runner.  For all tests without a registered extension,
the variables ‘LOG_COMPILER’, ‘AM_LOG_FLAGS’, and ‘LOG_FLAGS’ may be
used.  For example,

     TESTS = foo.pl bar.py baz
     TEST_EXTENSIONS = .pl .py
     PL_LOG_COMPILER = $(PERL)
     AM_PL_LOG_FLAGS = -w
     PY_LOG_COMPILER = $(PYTHON)
     AM_PY_LOG_FLAGS = -v
     LOG_COMPILER = ./wrapper-script
     AM_LOG_FLAGS = -d

will invoke ‘$(PERL) -w foo.pl’, ‘$(PYTHON) -v bar.py’, and
‘./wrapper-script -d baz’ to produce ‘foo.log’, ‘bar.log’, and
‘baz.log’, respectively.  The ‘foo.trs’, ‘bar.trs’ and ‘baz.trs’ files
will be automatically produced as a side-effect.

   It’s important to note that, differently from what we’ve seen for the
serial test harness (see Serial Test Harness), the
‘AM_TESTS_ENVIRONMENT’ and ‘TESTS_ENVIRONMENT’ variables _cannot_ be
used to define a custom test runner; the ‘LOG_COMPILER’ and ‘LOG_FLAGS’
(or their extension-specific counterparts) should be used instead:

     ## This is WRONG!
     AM_TESTS_ENVIRONMENT = PERL5LIB='$(srcdir)/lib' $(PERL) -Mstrict -w

     ## Do this instead.
     AM_TESTS_ENVIRONMENT = PERL5LIB='$(srcdir)/lib'; export PERL5LIB;
     LOG_COMPILER = $(PERL)
     AM_LOG_FLAGS = -Mstrict -w

   By default, the test suite harness will run all tests, but there are
several ways to limit the set of tests that are run:

   • You can set the ‘TESTS’ variable.  For example, you can use a
     command like this to run only a subset of the tests:

          env TESTS="foo.test bar.test" make -e check

     Note however that the command above will unconditionally overwrite
     the ‘test-suite.log’ file, thus clobbering the recorded results of
     any previous testsuite run.  This might be undesirable for packages
     whose testsuite takes a long time to execute.  Luckily, this
     problem can easily be avoided by also overriding ‘TEST_SUITE_LOG’
     at runtime; for example,

          env TEST_SUITE_LOG=partial.log TESTS="..." make -e check

     will write the result of the partial testsuite runs to the
     ‘partial.log’, without touching ‘test-suite.log’.

   • You can set the ‘TEST_LOGS’ variable.  By default, this variable is
     computed at ‘make’ run time from the value of ‘TESTS’ as described
     above.  For example, you can use the following:

          set x subset*.log; shift
          env TEST_LOGS="foo.log $*" make -e check

     The comments made above about ‘TEST_SUITE_LOG’ overriding applies
     here too.

   • By default, the test harness removes all old per-test ‘.log’ and
     ‘.trs’ files before it starts running tests to regenerate them.
     The variable ‘RECHECK_LOGS’ contains the set of ‘.log’ (and, by
     implication, ‘.trs’) files which are removed.  ‘RECHECK_LOGS’
     defaults to ‘TEST_LOGS’, which means all tests need to be
     rechecked.  By overriding this variable, you can choose which tests
     need to be reconsidered.  For example, you can lazily rerun only
     those tests which are outdated, i.e., older than their prerequisite
     test files, by setting this variable to the empty value:

          env RECHECK_LOGS= make -e check

   • You can ensure that all tests are rerun which have failed or passed
     unexpectedly, by running ‘make recheck’ in the test directory.
     This convenience target will set ‘RECHECK_LOGS’ appropriately
     before invoking the main test harness.

In order to guarantee an ordering between tests even with ‘make -jN’,
dependencies between the corresponding ‘.log’ files may be specified
through usual ‘make’ dependencies.  For example, the following snippet
lets the test named ‘foo-execute.test’ depend upon completion of the
test ‘foo-compile.test’:

     TESTS = foo-compile.test foo-execute.test
     foo-execute.log: foo-compile.log

Please note that this ordering ignores the _results_ of required tests,
thus the test ‘foo-execute.test’ is run even if the test
‘foo-compile.test’ failed or was skipped beforehand.  Further, please
note that specifying such dependencies currently works only for tests
that end in one of the suffixes listed in ‘TEST_EXTENSIONS’.

   Tests without such specified dependencies may be run concurrently
with parallel ‘make -jN’, so be sure they are prepared for concurrent
execution.

   The combination of lazy test execution and correct dependencies
between tests and their sources may be exploited for efficient unit
testing during development.  To further speed up the edit-compile-test
cycle, it may even be useful to specify compiled programs in
‘EXTRA_PROGRAMS’ instead of with ‘check_PROGRAMS’, as the former allows
intertwined compilation and test execution (but note that
‘EXTRA_PROGRAMS’ are not cleaned automatically; see Uniform).

   The variables ‘TESTS’ and ‘XFAIL_TESTS’ may contain conditional parts
as well as configure substitutions.  In the latter case, however,
certain restrictions apply: substituted test names must end with a
nonempty test suffix like ‘.test’, so that one of the inference rules
generated by ‘automake’ can apply.  For literal test names, ‘automake’
can generate per-target rules to avoid this limitation.

   Please note that it is currently not possible to use ‘$(srcdir)/’ or
‘$(top_srcdir)/’ in the ‘TESTS’ variable.  This technical limitation is
necessary to avoid generating test logs in the source tree and has the
unfortunate consequence that it is not possible to specify distributed
tests that are themselves generated by means of explicit rules, in a way
that is portable to all ‘make’ implementations (see Make Target Lookup (autoconf),
the semantics of FreeBSD and OpenBSD ‘make’ conflict
with this).  In case of doubt you may want to require to use GNU ‘make’,
or work around the issue with inference rules to generate the tests.

15.3 Custom Test Drivers
========================

15.3.1 Overview of Custom Test Drivers Support
----------------------------------------------

Starting from Automake version 1.12, the parallel test harness allows
the package authors to use third-party custom test drivers, in case the
default ones are inadequate for their purposes, or do not support their
testing protocol of choice.

   A custom test driver is expected to properly run the test programs
passed to it (including the command-line arguments passed to those
programs, if any), to analyze their execution and outcome, to create the
‘.log’ and ‘.trs’ files associated to these test runs, and to display
the test results on the console.  It is responsibility of the author of
the test driver to ensure that it implements all the above steps
meaningfully and correctly; Automake isn’t and can’t be of any help
here.  On the other hand, the Automake-provided code for testsuite
summary generation offers support for test drivers allowing several test
results per test script, if they take care to register such results
properly (see Log files generation and test results recording).

   The exact details of how test scripts’ results are to be determined
and analyzed is left to the individual drivers.  Some drivers might only
consider the test script exit status (this is done for example by the
default test driver used by the parallel test harness, described in the
previous section).  Other drivers might implement more complex and
advanced test protocols, which might require them to parse and interpret
the output emitted by the test script they’re running (examples of such
protocols are TAP and SubUnit).

   It’s very important to note that, even when using custom test
drivers, most of the infrastructure described in the previous section
about the parallel harness remains in place; this includes:

   • list of test scripts defined in ‘TESTS’, and overridable at runtime
     through the redefinition of ‘TESTS’ or ‘TEST_LOGS’;
   • concurrency through the use of ‘make’’s option ‘-j’;
   • per-test ‘.log’ and ‘.trs’ files, and generation of a summary
     ‘.log’ file from them;
   • ‘recheck’ target, ‘RECHECK_LOGS’ variable, and lazy reruns of
     tests;
   • inter-test dependencies;
   • support for ‘check_*’ variables (‘check_PROGRAMS’,
     ‘check_LIBRARIES’, ...);
   • use of ‘VERBOSE’ environment variable to get verbose output on
     testsuite failures;
   • definition and honoring of ‘TESTS_ENVIRONMENT’,
     ‘AM_TESTS_ENVIRONMENT’ and ‘AM_TESTS_FD_REDIRECT’ variables;
   • definition of generic and extension-specific ‘LOG_COMPILER’ and
     ‘LOG_FLAGS’ variables.

On the other hand, the exact semantics of how (and if) testsuite output
colorization, ‘XFAIL_TESTS’, and hard errors are supported and handled
is left to the individual test drivers.

15.3.2 Declaring Custom Test Drivers
------------------------------------

Custom testsuite drivers are declared by defining the make variables
‘LOG_DRIVER’ or ‘EXT_LOG_DRIVER’ (where EXT must be declared in
‘TEST_EXTENSIONS’).  They must be defined to programs or scripts that
will be used to drive the execution, logging, and outcome report of the
tests with corresponding extensions (or of those with no registered
extension in the case of ‘LOG_DRIVER’).  Clearly, multiple distinct test
drivers can be declared in the same ‘Makefile.am’.  Note moreover that
the ‘LOG_DRIVER’ variables are _not_ a substitute for the ‘LOG_COMPILER’
variables: the two sets of variables can, and often do, usefully and
legitimately coexist.

   The developer-reserved variable ‘AM_LOG_DRIVER_FLAGS’ and the
user-reserved variable ‘LOG_DRIVER_FLAGS’ can be used to define flags
that will be passed to each invocation of ‘LOG_DRIVER’, with the
user-defined flags obviously taking precedence over the
developer-reserved ones.  Similarly, for each extension EXT declared in
‘TEST_EXTENSIONS’, flags listed in ‘AM_EXT_LOG_DRIVER_FLAGS’ and
‘EXT_LOG_DRIVER_FLAGS’ will be passed to invocations of
‘EXT_LOG_DRIVER’.

15.3.3 API for Custom Test Drivers
----------------------------------

Note that _the APIs described here are still highly experimental_, and
will very likely undergo tightenings and likely also extensive changes
in the future, to accommodate for new features or to satisfy additional
portability requirements.

   The main characteristic of these APIs is that they are designed to
share as much infrastructure, semantics, and implementation detail as
possible with the parallel test harness and its default driver.

15.3.3.1 Command-line arguments for test drivers
................................................

A custom driver can rely on various command-line options and arguments
being passed to it automatically by the Automake-generated test harness.
It is _mandatory_ that it understands all of them (even if the exact
interpretation of the associated semantics can legitimately change
between a test driver and another, and even be a no-op in some drivers).

Here is the list of options:

‘--test-name=NAME’
     The name of the test, with VPATH prefix (if any) removed.  This can
     have a suffix and a directory component (as in e.g.,
     ‘sub/foo.test’), and is mostly meant to be used in console reports
     about testsuite advancements and results (see Testsuite progress output).
‘--log-file=PATH.log’
     The ‘.log’ file the test driver must create (see Basics of test metadata).
     If it has a directory component (as in e.g.,
     ‘sub/foo.log’), the test harness will ensure that such directory
     exists _before_ the test driver is called.
‘--trs-file=PATH.trs’
     The ‘.trs’ file the test driver must create (see Basics of test metadata).
     If it has a directory component (as in e.g.,
     ‘sub/foo.trs’), the test harness will ensure that such directory
     exists _before_ the test driver is called.
‘--color-tests={yes|no}’
     Whether the console output should be colorized or not (see Simple tests and color-tests,
     to learn when this option gets activated
     and when it doesn’t).
‘--expect-failure={yes|no}’
     Whether the tested program is expected to fail.
‘--enable-hard-errors={yes|no}’
     Whether “hard errors” in the tested program should be treated
     differently from normal failures or not (the default should be
     ‘yes’).  The exact meaning of “hard error” is highly dependent from
     the test protocols or conventions in use.
‘--’
     Explicitly terminate the list of options.

The first non-option argument passed to the test driver is the program
to be run, and all the following ones are command-line options and
arguments for this program.

   Note that the exact semantics attached to the ‘--color-tests’,
‘--expect-failure’ and ‘--enable-hard-errors’ options are left up to the
individual test drivers.  Still, having a behaviour compatible or at
least similar to that provided by the default driver is advised, as that
would offer a better consistency and a more pleasant user experience.

15.3.3.2 Log files generation and test results recording
........................................................

The test driver must correctly generate the files specified by the
‘--log-file’ and ‘--trs-file’ option (even when the tested program fails
or crashes).

   The ‘.log’ file should ideally contain all the output produced by the
tested program, plus optionally other information that might facilitate
debugging or analysis of bug reports.  Apart from that, its format is
basically free.

   The ‘.trs’ file is used to register some metadata through the use of
custom reStructuredText fields.  This metadata is expected to be
employed in various ways by the parallel test harness; for example, to
count the test results when printing the testsuite summary, or to decide
which tests to re-run upon ‘make recheck’.  Unrecognized metadata in a
‘.trs’ file is currently ignored by the harness, but this might change
in the future.  The list of currently recognized metadata follows.

‘:test-result:’
     The test driver must use this field to register the results of
     _each_ test case run by a test script file.  Several
     ‘:test-result:’ fields can be present in the same ‘.trs’ file; this
     is done in order to support test protocols that allow a single test
     script to run more test cases.

     The only recognized test results are currently ‘PASS’, ‘XFAIL’,
     ‘SKIP’, ‘FAIL’, ‘XPASS’ and ‘ERROR’.  These results, when declared
     with ‘:test-result:’, can be optionally followed by text holding
     the name and/or a brief description of the corresponding test; the
     harness will ignore such extra text when generating
     ‘test-suite.log’ and preparing the testsuite summary.

‘:recheck:’
     If this field is present and defined to ‘no’, then the
     corresponding test script will _not_ be run upon a ‘make recheck’.
     What happens when two or more ‘:recheck:’ fields are present in the
     same ‘.trs’ file is undefined behaviour.

‘:copy-in-global-log:’
     If this field is present and defined to ‘no’, then the content of
     the ‘.log’ file will _not_ be copied into the global
     ‘test-suite.log’.  We allow to forsake such copying because, while
     it can be useful in debugging and analysis of bug report, it can
     also be just a waste of space in normal situations, e.g., when a
     test script is successful.  What happens when two or more
     ‘:copy-in-global-log:’ fields are present in the same ‘.trs’ file
     is undefined behaviour.

‘:test-global-result:’
     This is used to declare the "global result" of the script.
     Currently, the value of this field is needed only to be reported
     (more or less verbatim) in the generated global log file
     ‘$(TEST_SUITE_LOG)’, so it’s quite free-form.  For example, a test
     script which runs 10 test cases, 6 of which pass and 4 of which are
     skipped, could reasonably have a ‘PASS/SKIP’ value for this field,
     while a test script which runs 19 successful tests and one failed
     test could have an ‘ALMOST PASSED’ value.  What happens when two or
     more ‘:test-global-result:’ fields are present in the same ‘.trs’
     file is undefined behaviour.

Let’s see a small example.  Assume a ‘.trs’ file contains the following
lines:

     :test-result: PASS server starts
     :global-log-copy: no
     :test-result: PASS HTTP/1.1 request
     :test-result: FAIL HTTP/1.0 request
     :recheck: yes
     :test-result: SKIP HTTPS request (TLS library wasn't available)
     :test-result: PASS server stops

Then the corresponding test script will be re-run by ‘make check’, will
contribute with _five_ test results to the testsuite summary (three of
these tests being successful, one failed, and one skipped), and the
content of the corresponding ‘.log’ file will _not_ be copied into the
global log file ‘test-suite.log’.

15.3.3.3 Testsuite progress output
..................................

A custom test driver also has the task of displaying, on the standard
output, the test results as soon as they become available.  Depending on
the protocol in use, it can also display the reasons for failures and
skips, and, more generally, any useful diagnostic output (but remember
that each line on the screen is precious, so that cluttering the screen
with overly verbose information is bad idea).  The exact format of this
progress output is left up to the test driver; in fact, a custom test
driver might _theoretically_ even decide not to do any such report,
leaving it all to the testsuite summary (that would be a very lousy
idea, of course, and serves only to illustrate the flexibility that is
granted here).

   Remember that consistency is good; so, if possible, try to be
consistent with the output of the built-in Automake test drivers,
providing a similar “look & feel”.  In particular, the testsuite
progress output should be colorized when the ‘--color-tests’ is passed
to the driver.  On the other end, if you are using a known and
widespread test protocol with well-established implementations, being
consistent with those implementations’ output might be a good idea too.

15.4 Using the TAP test protocol
================================

15.4.1 Introduction to TAP
--------------------------

TAP, the Test Anything Protocol, is a simple text-based interface
between testing modules or programs and a test harness.  The tests (also
called “TAP producers” in this context) write test results in a simple
format on standard output; a test harness (also called “TAP consumer”)
will parse and interpret these results, and properly present them to the
user, and/or register them for later analysis.  The exact details of how
this is accomplished can vary among different test harnesses.  The
Automake harness will present the results on the console in the usual
fashion (see Testsuite progress on console), and will use the ‘.trs’
files (see Basics of test metadata) to store the test results and
related metadata.  Apart from that, it will try to remain as compatible
as possible with pre-existing and widespread utilities, such as the
‘prove’ utility (http://search.cpan.org/~andya/Test-Harness/bin/prove),
at least for the simpler usages.

   TAP started its life as part of the test harness for Perl, but today
it has been (mostly) standardized, and has various independent
implementations in different languages; among them, C, C++, Perl,
Python, PHP, and Java.  For a semi-official specification of the TAP
protocol, please refer to the documentation of ‘Test::Harness::TAP’
(http://search.cpan.org/~petdance/Test-Harness/lib/Test/Harness/TAP.pod).

   The most relevant real-world usages of TAP are obviously in the
testsuites of ‘perl’ and of many perl modules.  Still, other important
third-party packages, such as ‘git’ (http://git-scm.com/), also use TAP
in their testsuite.

15.4.2 Use TAP with the Automake test harness
---------------------------------------------

Currently, the TAP driver that comes with Automake requires some by-hand
steps on the developer’s part (this situation should hopefully be
improved in future Automake versions).  You’ll have to grab the
‘tap-driver.sh’ script from the Automake distribution by hand, copy it
in your source tree, and use the Automake support for third-party test
drivers to instruct the harness to use the ‘tap-driver.sh’ script and
the awk program found by ‘AM_INIT_AUTOMAKE’ to run your TAP-producing
tests.  See the example below for clarification.

   Apart from the options common to all the Automake test drivers (see
Command-line arguments for test drivers), ‘tap-driver.sh’ supports the
following options, whose names are chosen for enhanced compatibility
with the ‘prove’ utility.

‘--ignore-exit’
     Causes the test driver to ignore the exit status of the test
     scripts; by default, the driver will report an error if the script
     exits with a non-zero status.  This option has effect also on
     non-zero exit statuses due to termination by a signal.
‘--comments’
     Instruct the test driver to display TAP diagnostics (i.e., lines
     beginning with the ‘#’ character) in the testsuite progress output
     too; by default, TAP diagnostics are only copied to the ‘.log’
     file.
‘--no-comments’
     Revert the effects of ‘--comments’.
‘--merge’
     Instruct the test driver to merge the test scripts’ standard error
     into their standard output.  This is necessary if you want to
     ensure that diagnostics from the test scripts are displayed in the
     correct order relative to test results; this can be of great help
     in debugging (especially if your test scripts are shell scripts run
     with shell tracing active).  As a downside, this option might cause
     the test harness to get confused if anything that appears on
     standard error looks like a test result.
‘--no-merge’
     Revert the effects of ‘--merge’.
‘--diagnostic-string=STRING’
     Change the string that introduces TAP diagnostics from the default
     value of “‘#’” to ‘STRING’.  This can be useful if your TAP-based
     test scripts produce verbose output on which they have limited
     control (because, say, the output comes from other tools invoked in
     the scripts), and it might contain text that gets spuriously
     interpreted as TAP diagnostics: such an issue can be solved by
     redefining the string that activates TAP diagnostics to a value you
     know won’t appear by chance in the tests’ output.  Note however
     that this feature is non-standard, as the “official” TAP protocol
     does not allow for such a customization; so don’t use it if you can
     avoid it.

Here is an example of how the TAP driver can be set up and used.

     % cat configure.ac
     AC_INIT([GNU Try Tap], [1.0], [bug-automake@gnu.org])
     AC_CONFIG_AUX_DIR([build-aux])
     AM_INIT_AUTOMAKE([foreign -Wall -Werror])
     AC_CONFIG_FILES([Makefile])
     AC_REQUIRE_AUX_FILE([tap-driver.sh])
     AC_OUTPUT

     % cat Makefile.am
     TEST_LOG_DRIVER = env AM_TAP_AWK='$(AWK)' $(SHELL) \
                       $(top_srcdir)/build-aux/tap-driver.sh
     TESTS = foo.test bar.test baz.test
     EXTRA_DIST = $(TESTS)

     % cat foo.test
     #!/bin/sh
     echo 1..4 # Number of tests to be executed.
     echo 'ok 1 - Swallows fly'
     echo 'not ok 2 - Caterpillars fly # TODO metamorphosis in progress'
     echo 'ok 3 - Pigs fly # SKIP not enough acid'
     echo '# I just love word plays ...'
     echo 'ok 4 - Flies fly too :-)'

     % cat bar.test
     #!/bin/sh
     echo 1..3
     echo 'not ok 1 - Bummer, this test has failed.'
     echo 'ok 2 - This passed though.'
     echo 'Bail out! Ennui kicking in, sorry...'
     echo 'ok 3 - This will not be seen.'

     % cat baz.test
     #!/bin/sh
     echo 1..1
     echo ok 1
     # Exit with error, even if all the tests have been successful.
     exit 7

     % cp PREFIX/share/automake-APIVERSION/tap-driver.sh .
     % autoreconf -vi && ./configure && make check
     ...
     PASS: foo.test 1 - Swallows fly
     XFAIL: foo.test 2 - Caterpillars fly # TODO metamorphosis in progress
     SKIP: foo.test 3 - Pigs fly # SKIP not enough acid
     PASS: foo.test 4 - Flies fly too :-)
     FAIL: bar.test 1 - Bummer, this test has failed.
     PASS: bar.test 2 - This passed though.
     ERROR: bar.test - Bail out! Ennui kicking in, sorry...
     PASS: baz.test 1
     ERROR: baz.test - exited with status 7
     ...
     Please report to bug-automake@gnu.org
     ...
     % echo exit status: $?
     exit status: 1

     % env TEST_LOG_DRIVER_FLAGS='--comments --ignore-exit' \
           TESTS='foo.test baz.test' make -e check
     ...
     PASS: foo.test 1 - Swallows fly
     XFAIL: foo.test 2 - Caterpillars fly # TODO metamorphosis in progress
     SKIP: foo.test 3 - Pigs fly # SKIP not enough acid
     # foo.test: I just love word plays...
     PASS: foo.test 4 - Flies fly too :-)
     PASS: baz.test 1
     ...
     % echo exit status: $?
     exit status: 0

15.4.3 Incompatibilities with other TAP parsers and drivers
-----------------------------------------------------------

For implementation or historical reasons, the TAP driver and harness as
implemented by Automake have some minor incompatibilities with the
mainstream versions, which you should be aware of.

   • A ‘Bail out!’ directive doesn’t stop the whole testsuite, but only
     the test script it occurs in.  This doesn’t follow TAP
     specifications, but on the other hand it maximizes compatibility
     (and code sharing) with the “hard error” concept of the default
     testsuite driver.
   • The ‘version’ and ‘pragma’ directives are not supported.
   • The ‘--diagnostic-string’ option of our driver allows modification
     of the string that introduces TAP diagnostics from the default
     value of “‘#’”.  The standard TAP protocol currently has no way to
     allow this, so if you use it your diagnostic will be lost to more
     compliant tools like ‘prove’ and ‘Test::Harness’
   • And there are probably some other small and yet undiscovered
     incompatibilities, especially in corner cases or with rare usages.

15.4.4 Links and external resources on TAP
------------------------------------------

Here are some links to more extensive official or third-party
documentation and resources about the TAP protocol and related tools and
libraries.
   •  ‘Test::Harness::TAP’
     (http://search.cpan.org/~petdance/Test-Harness/lib/Test/Harness/TAP.pod),
     the (mostly) official documentation about the TAP format and
     protocol.
   •  ‘prove’ (http://search.cpan.org/~andya/Test-Harness/bin/prove),
     the most famous command-line TAP test driver, included in the
     distribution of ‘perl’ and ‘Test::Harness’
     (http://search.cpan.org/~andya/Test-Harness/lib/Test/Harness.pm).
   • The TAP wiki (http://testanything.org/wiki/index.php/Main_Page).
   • A “gentle introduction” to testing for perl coders:
     ‘Test::Tutorial’
     (http://search.cpan.org/dist/Test-Simple/lib/Test/Tutorial.pod).
   •  ‘Test::Simple’
     (http://search.cpan.org/~mschwern/Test-Simple/lib/Test/Simple.pm)
     and ‘Test::More’
     (http://search.cpan.org/~mschwern/Test-Simple/lib/Test/More.pm),
     the standard perl testing libraries, which are based on TAP.
   • C TAP Harness
     (http://www.eyrie.org/~eagle/software/c-tap-harness/), a C-based
     project implementing both a TAP producer and a TAP consumer.
   • tap4j (http://www.tap4j.org/), a Java-based project implementing
     both a TAP producer and a TAP consumer.

15.5 DejaGnu Tests
==================

If ‘dejagnu’ (https://ftp.gnu.org/gnu/dejagnu/) appears in
‘AUTOMAKE_OPTIONS’, then a ‘dejagnu’-based test suite is assumed.  The
variable ‘DEJATOOL’ is a list of names that are passed, one at a time,
as the ‘--tool’ argument to ‘runtest’ invocations; it defaults to the
name of the package.

   The variable ‘RUNTESTDEFAULTFLAGS’ holds the ‘--tool’ and ‘--srcdir’
flags that are passed to dejagnu by default; this can be overridden if
necessary.

   The variables ‘EXPECT’ and ‘RUNTEST’ can also be overridden to
provide project-specific values.  For instance, you will need to do this
if you are testing a compiler toolchain, because the default values do
not take into account host and target names.

   The contents of the variable ‘RUNTESTFLAGS’ are passed to the
‘runtest’ invocation.  This is considered a “user variable” (see User Variables).
If you need to set ‘runtest’ flags in ‘Makefile.am’, you
can use ‘AM_RUNTESTFLAGS’ instead.

   Automake will generate rules to create a local ‘site.exp’ file,
defining various variables detected by ‘configure’.  This file is
automatically read by DejaGnu.  It is OK for the user of a package to
edit this file in order to tune the test suite.  However this is not the
place where the test suite author should define new variables: this
should be done elsewhere in the real test suite code.  Especially,
‘site.exp’ should not be distributed.

   Still, if the package author has legitimate reasons to extend
‘site.exp’ at ‘make’ time, he can do so by defining the variable
‘EXTRA_DEJAGNU_SITE_CONFIG’; the files listed there will be considered
‘site.exp’ prerequisites, and their content will be appended to it (in
the same order in which they appear in ‘EXTRA_DEJAGNU_SITE_CONFIG’).
Note that files are _not_ distributed by default.

   For more information regarding DejaGnu test suites, see
dejagnu.

15.6 Install Tests
==================

The ‘installcheck’ target is available to the user as a way to run any
tests after the package has been installed.  You can add tests to this
by writing an ‘installcheck-local’ rule.

16 Rebuilding Makefiles
***********************

Automake generates rules to automatically rebuild ‘Makefile’s,
‘configure’, and other derived files like ‘Makefile.in’.

   If you are using ‘AM_MAINTAINER_MODE’ in ‘configure.ac’, then these
automatic rebuilding rules are only enabled in maintainer mode.

   Sometimes it is convenient to supplement the rebuild rules for
‘configure’ or ‘config.status’ with additional dependencies.  The
variables ‘CONFIGURE_DEPENDENCIES’ and ‘CONFIG_STATUS_DEPENDENCIES’ can
be used to list these extra dependencies.  These variables should be
defined in all ‘Makefile’s of the tree (because these two rebuild rules
are output in all of them), so it is safer and easier to ‘AC_SUBST’ them
from ‘configure.ac’.  For instance, the following statement will cause
‘configure’ to be rerun each time ‘version.sh’ is changed.

     AC_SUBST([CONFIG_STATUS_DEPENDENCIES], ['$(top_srcdir)/version.sh'])

Note the ‘$(top_srcdir)/’ in the file name.  Since this variable is to
be used in all ‘Makefile’s, its value must be sensible at any level in
the build hierarchy.

   Beware not to mistake ‘CONFIGURE_DEPENDENCIES’ for
‘CONFIG_STATUS_DEPENDENCIES’.

   ‘CONFIGURE_DEPENDENCIES’ adds dependencies to the ‘configure’ rule,
whose effect is to run ‘autoconf’.  This variable should be seldom used,
because ‘automake’ already tracks ‘m4_include’d files.  However it can
be useful when playing tricky games with ‘m4_esyscmd’ or similar
non-recommendable macros with side effects.  Be also aware that
interactions of this variable with the autom4te cache (autoconf)
are quite problematic and can cause subtle
breakage, so you might want to disable the cache if you want to use
‘CONFIGURE_DEPENDENCIES’.

   ‘CONFIG_STATUS_DEPENDENCIES’ adds dependencies to the ‘config.status’
rule, whose effect is to run ‘configure’.  This variable should
therefore carry any non-standard source that may be read as a side
effect of running ‘configure’, like ‘version.sh’ in the example above.

   Speaking of ‘version.sh’ scripts, we recommend against them today.
They are mainly used when the version of a package is updated
automatically by a script (e.g., in daily builds).  Here is what some
old-style ‘configure.ac’s may look like:

     AC_INIT
     . $srcdir/version.sh
     AM_INIT_AUTOMAKE([name], $VERSION_NUMBER)
     ...

Here, ‘version.sh’ is a shell fragment that sets ‘VERSION_NUMBER’.  The
problem with this example is that ‘automake’ cannot track dependencies
(listing ‘version.sh’ in ‘CONFIG_STATUS_DEPENDENCIES’, and distributing
this file is up to the user), and that it uses the obsolete form of
‘AC_INIT’ and ‘AM_INIT_AUTOMAKE’.  Upgrading to the new syntax is not
straightforward, because shell variables are not allowed in ‘AC_INIT’’s
arguments.  We recommend that ‘version.sh’ be replaced by an M4 file
that is included by ‘configure.ac’:

     m4_include([version.m4])
     AC_INIT([name], VERSION_NUMBER)
     AM_INIT_AUTOMAKE
     ...

Here ‘version.m4’ could contain something like
‘m4_define([VERSION_NUMBER], [1.2])’.  The advantage of this second form
is that ‘automake’ will take care of the dependencies when defining the
rebuild rule, and will also distribute the file automatically.  An
inconvenience is that ‘autoconf’ will now be rerun each time the version
number is bumped, when only ‘configure’ had to be rerun in the previous
setup.

17 Changing Automake’s Behavior
*******************************

17.1 Options generalities
=========================

Various features of Automake can be controlled by options.  Except where
noted otherwise, options can be specified in one of several ways.  Most
options can be applied on a per-‘Makefile’ basis when listed in a
special ‘Makefile’ variable named ‘AUTOMAKE_OPTIONS’.  Some of these
options only make sense when specified in the toplevel ‘Makefile.am’
file.  Options are applied globally to all processed ‘Makefile’ files
when listed in the first argument of ‘AM_INIT_AUTOMAKE’ in
‘configure.ac’, and some options which require changes to the
‘configure’ script can only be specified there.  These are annotated
below.

   As a general rule, options specified in ‘AUTOMAKE_OPTIONS’ take
precedence over those specified in ‘AM_INIT_AUTOMAKE’, which in turn
take precedence over those specified on the command line.

   Also, some care must be taken about the interactions among strictness
level and warning categories.  As a general rule, strictness-implied
warnings are overridden by those specified by explicit options.  For
example, even if ‘portability’ warnings are disabled by default in
‘foreign’ strictness, a usage like this will end up enabling them:

     AUTOMAKE_OPTIONS = -Wportability foreign

   However, a strictness level specified in a higher-priority context
will override all the explicit warnings specified in a lower-priority
context.  For example, if ‘configure.ac’ contains:

     AM_INIT_AUTOMAKE([-Wportability])

and ‘Makefile.am’ contains:

     AUTOMAKE_OPTIONS = foreign

then ‘portability’ warnings will be _disabled_ in ‘Makefile.am’.

17.2 List of Automake options
=============================

‘gnits’
‘gnu’
‘foreign’

     Set the strictness as appropriate.  The ‘gnits’ option also implies
     options ‘readme-alpha’ and ‘check-news’.

‘check-news’
     Cause ‘make dist’ to fail unless the current version number appears
     in the first few lines of the ‘NEWS’ file.

‘dejagnu’
     Cause ‘dejagnu’-specific rules to be generated.  See DejaGnu Tests.

‘dist-bzip2’
     Hook ‘dist-bzip2’ to ‘dist’.

‘dist-lzip’
     Hook ‘dist-lzip’ to ‘dist’.

‘dist-xz’
     Hook ‘dist-xz’ to ‘dist’.

‘dist-zip’
     Hook ‘dist-zip’ to ‘dist’.

‘dist-zstd’
     Hook ‘dist-zstd’ to ‘dist’.

‘dist-shar’
     Hook ‘dist-shar’ to ‘dist’.  Use of this option is deprecated, as
     the ‘shar’ format is obsolescent and problematic.  Support for it
     will be removed altogether in Automake 2.0.

‘dist-tarZ’
     Hook ‘dist-tarZ’ to ‘dist’.  Use of this option is deprecated, as
     the ‘compress’ program is obsolete.  Support for it will be removed
     altogether in Automake 2.0.

‘filename-length-max=99’
     Abort if file names longer than 99 characters are found during
     ‘make dist’.  Such long file names are generally considered not to
     be portable in tarballs.  See the ‘tar-v7’ and ‘tar-ustar’ options
     below.  This option should be used in the top-level ‘Makefile.am’
     or as an argument of ‘AM_INIT_AUTOMAKE’ in ‘configure.ac’; it will
     be ignored otherwise.  It will also be ignored in sub-packages of
     nested packages (see Subpackages).

‘info-in-builddir’
     Instruct Automake to place the generated ‘.info’ files in the
     ‘builddir’ rather than in the ‘srcdir’.  Note that this might make
     VPATH builds with some non-GNU make implementations more brittle.

‘no-define’
     This option is meaningful only when passed as an argument to
     ‘AM_INIT_AUTOMAKE’.  It will prevent the ‘PACKAGE’ and ‘VERSION’
     variables from being ‘AC_DEFINE’d.  But notice that they will
     remain defined as shell variables in the generated ‘configure’, and
     as make variables in the generated ‘Makefile’; this is deliberate,
     and required for backward compatibility.

‘no-dependencies’
     This is similar to using ‘--ignore-deps’ on the command line, but
     is useful for those situations where you don’t have the necessary
     bits to make automatic dependency tracking work (see
     Dependencies).  In this case the effect is to effectively disable
     automatic dependency tracking.

‘no-dist’
     Don’t emit any code related to ‘dist’ target.  This is useful when
     a package has its own method for making distributions.

‘no-dist-gzip’
     Do not hook ‘dist-gzip’ to ‘dist’.

‘no-exeext’
     If your ‘Makefile.am’ defines a rule for target ‘foo’, it will
     override a rule for a target named ‘foo$(EXEEXT)’.  This is
     necessary when ‘EXEEXT’ is found to be empty.  However, by default
     ‘automake’ will generate an error for this use.  The ‘no-exeext’
     option will disable this error.  This is intended for use only
     where it is known in advance that the package will not be ported to
     Windows, or any other operating system using extensions on
     executables.

‘no-installinfo’
     The generated ‘Makefile.in’ will not cause info pages to be built
     or installed by default.  However, ‘info’ and ‘install-info’
     targets will still be available.  This option is disallowed at
     ‘gnu’ strictness and above.

‘no-installman’
     The generated ‘Makefile.in’ will not cause man pages to be
     installed by default.  However, an ‘install-man’ target will still
     be available for optional installation.  This option is disallowed
     at ‘gnu’ strictness and above.

‘nostdinc’
     This option can be used to disable the standard ‘-I’ options that
     are ordinarily automatically provided by Automake.

‘no-texinfo.tex’
     Don’t require ‘texinfo.tex’, even if there are texinfo files in
     this directory.

‘serial-tests’
     Enable the older serial test suite harness for ‘TESTS’ (see
     Serial Test Harness, for more information).

‘parallel-tests’
     Enable test suite harness for ‘TESTS’ that can run tests in
     parallel (see Parallel Test Harness, for more information).
     This option is only kept for backward-compatibility, since the
     parallel test harness is the default now.

‘readme-alpha’
     If this release is an alpha release, and the file ‘README-alpha’
     exists, then it will be added to the distribution.  If this option
     is given, version numbers are expected to follow one of two forms.
     The first form is ‘MAJOR.MINOR.ALPHA’, where each element is a
     number; the final period and number should be left off for
     non-alpha releases.  The second form is ‘MAJOR.MINORALPHA’, where
     ALPHA is a letter; it should be omitted for non-alpha releases.

‘std-options’

     Make the ‘installcheck’ rule check that installed scripts and
     programs support the ‘--help’ and ‘--version’ options.  This also
     provides a basic check that the program’s run-time dependencies are
     satisfied after installation.

     In a few situations, programs (or scripts) have to be exempted from
     this test.  For instance, ‘false’ (from GNU coreutils) is never
     successful, even for ‘--help’ or ‘--version’.  You can list such
     programs in the variable ‘AM_INSTALLCHECK_STD_OPTIONS_EXEMPT’.
     Programs (not scripts) listed in this variable should be suffixed
     by ‘$(EXEEXT)’ for the sake of Windows or OS/2.  For instance,
     suppose we build ‘false’ as a program but ‘true.sh’ as a script,
     and that neither of them support ‘--help’ or ‘--version’:

          AUTOMAKE_OPTIONS = std-options
          bin_PROGRAMS = false ...
          bin_SCRIPTS = true.sh ...
          AM_INSTALLCHECK_STD_OPTIONS_EXEMPT = false$(EXEEXT) true.sh

‘subdir-objects’
     If this option is specified, then objects are placed into the
     subdirectory of the build directory corresponding to the
     subdirectory of the source file.  For instance, if the source file
     is ‘subdir/file.cxx’, then the output file would be
     ‘subdir/file.o’.

‘tar-v7’
‘tar-ustar’
‘tar-pax’

     These three mutually exclusive options select the tar format to use
     when generating tarballs with ‘make dist’.  (The tar file created
     is then compressed according to the set of ‘no-dist-gzip’,
     ‘dist-bzip2’, ‘dist-lzip’, ‘dist-xz’, ‘dist-zstd’ and ‘dist-tarZ’
     options in use.)

     These options must be passed as arguments to ‘AM_INIT_AUTOMAKE’
     (see Macros) because they can require additional configure
     checks.  Automake will complain if it sees such options in an
     ‘AUTOMAKE_OPTIONS’ variable.

     ‘tar-v7’ selects the old V7 tar format.  This is the historical
     default.  This antiquated format is understood by all tar
     implementations and supports file names with up to 99 characters.
     When given longer file names some tar implementations will diagnose
     the problem while others will generate broken tarballs or use
     non-portable extensions.  Furthermore, the V7 format cannot store
     empty directories.  When using this format, consider using the
     ‘filename-length-max=99’ option to catch file names too long.

     ‘tar-ustar’ selects the ustar format defined by POSIX 1003.1-1988.
     This format is old enough to be portable: As of 2018, it is
     supported by the native ‘tar’ command on GNU, FreeBSD, NetBSD,
     OpenBSD, AIX, HP-UX, and Solaris, at least.  It fully supports
     empty directories.  It can store file names with up to 256
     characters, provided that the file name can be split at directory
     separator in two parts, first of them being at most 155 bytes long.
     So, in most cases the maximum file name length will be shorter than
     256 characters.

     ‘tar-pax’ selects the new pax interchange format defined by POSIX
     1003.1-2001.  It does not limit the length of file names.  However,
     this format is very young and should probably be restricted to
     packages that target only very modern platforms.  As of 2018, this
     format is supported by the native ‘tar’ command only on GNU,
     FreeBSD, and OpenBSD systems; it is not supported by the native
     ‘tar’ command on NetBSD, AIX, HP-UX, or Solaris.  There are moves
     to change the pax format in an upward-compatible way, so this
     option may refer to a more recent version in the future.

     See Controlling the Archive Format (tar), for further
     discussion about tar formats.

     ‘configure’ knows several ways to construct these formats.  It will
     not abort if it cannot find a tool up to the task (so that the
     package can still be built), but ‘make dist’ will fail.

VERSION
     A version number (e.g., ‘0.30’) can be specified.  If Automake is
     not the same version or newer than the version specified, creation
     of the ‘Makefile.in’ will be suppressed.

‘-WCATEGORY’ or ‘--warnings=CATEGORY’
     These options behave exactly like their command-line counterpart
     (see automake Invocation).  This allows you to enable or
     disable some warning categories on a per-file basis.  You can also
     setup some warnings for your entire project; for instance, try
     ‘AM_INIT_AUTOMAKE([-Wall])’ in your ‘configure.ac’.

   Unrecognized options are diagnosed by ‘automake’.

   If you want an option to apply to all the files in the tree, you can
use the ‘AM_INIT_AUTOMAKE’ macro in ‘configure.ac’.  See Macros.

18 Miscellaneous Rules
**********************

There are a few rules and variables that didn’t fit anywhere else.

18.1 Interfacing to ‘etags’
===========================

Automake will generate rules to generate ‘TAGS’ files for use with GNU
Emacs under some circumstances.

   If any C, C++ or Fortran 77 source code or headers are present, then
‘tags’ and ‘TAGS’ rules will be generated for the directory.  All files
listed using the ‘_SOURCES’, ‘_HEADERS’, and ‘_LISP’ primaries will be
used to generate tags.  Note that generated source files that are not
distributed must be declared in variables like ‘nodist_noinst_HEADERS’
or ‘nodist_PROG_SOURCES’ or they will be ignored.

   A ‘tags’ rule will be output at the topmost directory of a
multi-directory package.  When run from this topmost directory, ‘make
tags’ will generate a ‘TAGS’ file that includes by reference all ‘TAGS’
files from subdirectories.

   The ‘tags’ rule will also be generated if the variable ‘ETAGS_ARGS’
is defined.  This variable is intended for use in directories that
contain taggable source that ‘etags’ does not understand.  The user can
use the ‘ETAGSFLAGS’ to pass additional flags to ‘etags’;
‘AM_ETAGSFLAGS’ is also available for use in ‘Makefile.am’.

   Here is how Automake generates tags for its source, and for nodes in
its Texinfo file:

     ETAGS_ARGS = automake.in --lang=none \
      --regex='/^@node[ \t]+\([^,]+\)/\1/' automake.texi

   If you add file names to ‘ETAGS_ARGS’, you will probably also want to
define ‘TAGS_DEPENDENCIES’.  The contents of this variable are added
directly to the dependencies for the ‘tags’ rule.

   Automake also generates a ‘ctags’ rule that can be used to build
‘vi’-style ‘tags’ files.  The variable ‘CTAGS’ is the name of the
program to invoke (by default ‘ctags’); ‘CTAGSFLAGS’ can be used by the
user to pass additional flags, and ‘AM_CTAGSFLAGS’ can be used by the
‘Makefile.am’.

   Automake will also generate an ‘ID’ rule that will run ‘mkid’ on the
source.  This is only supported on a directory-by-directory basis.

   Similarly, the ‘cscope’ rule will create a list of all the source
files in the tree and run ‘cscope’ to build an inverted index database.
The variable ‘CSCOPE’ is the name of the program to invoke (by default
‘cscope’); ‘CSCOPEFLAGS’ and ‘CSCOPE_ARGS’ can be used by the user to
pass additional flags and file names respectively, while
‘AM_CSCOPEFLAGS’ can be used by the ‘Makefile.am’.  Note that,
currently, the Automake-provided ‘cscope’ support, when used in a VPATH
build, might not work well with non-GNU make implementations (especially
with make implementations performing VPATH rewrites (autoconf)).

   Finally, Automake also emits rules to support the GNU Global Tags
program (https://www.gnu.org/software/global/).  The ‘GTAGS’ rule runs
Global Tags and puts the result in the top build directory.  The
variable ‘GTAGS_ARGS’ holds arguments that are passed to ‘gtags’.

18.2 Handling new file extensions
=================================

It is sometimes useful to introduce a new implicit rule to handle a file
type that Automake does not know about.

   For instance, suppose you had a compiler that could compile ‘.foo’
files to ‘.o’ files.  You would simply define a suffix rule for your
language:

     .foo.o:
             foocc -c -o $@ $<

   Then you could directly use a ‘.foo’ file in a ‘_SOURCES’ variable
and expect the correct results:

     bin_PROGRAMS = doit
     doit_SOURCES = doit.foo

   This was the simpler and more common case.  In other cases, you will
have to help Automake to figure out which extensions you are defining
your suffix rule for.  This usually happens when your extension does not
start with a dot.  Then, all you have to do is to put a list of new
suffixes in the ‘SUFFIXES’ variable *before* you define your implicit
rule.

   For instance, the following definition prevents Automake from
misinterpreting the ‘.idlC.cpp:’ rule as an attempt to transform ‘.idlC’
files into ‘.cpp’ files.

     SUFFIXES = .idl C.cpp
     .idlC.cpp:
             # whatever

   As you may have noted, the ‘SUFFIXES’ variable behaves like the
‘.SUFFIXES’ special target of ‘make’.  You should not touch ‘.SUFFIXES’
yourself, but use ‘SUFFIXES’ instead and let Automake generate the
suffix list for ‘.SUFFIXES’.  Any given ‘SUFFIXES’ go at the start of
the generated suffixes list, followed by Automake generated suffixes not
already in the list.

19 Include
**********

Automake supports an ‘include’ directive that can be used to include
other ‘Makefile’ fragments when ‘automake’ is run.  Note that these
fragments are read and interpreted by ‘automake’, not by ‘make’.  As
with conditionals, ‘make’ has no idea that ‘include’ is in use.

   There are two forms of ‘include’:

‘include $(srcdir)/file’
     Include a fragment that is found relative to the current source
     directory.

‘include $(top_srcdir)/file’
     Include a fragment that is found relative to the top source
     directory.

   Note that if a fragment is included inside a conditional, then the
condition applies to the entire contents of that fragment.

   Makefile fragments included this way are always distributed because
they are needed to rebuild ‘Makefile.in’.

   Inside a fragment, the construct ‘%reldir%’ is replaced with the
directory of the fragment relative to the base ‘Makefile.am’.
Similarly, ‘%canon_reldir%’ is replaced with the canonicalized (see
Canonicalization) form of ‘%reldir%’.  As a convenience, ‘%D%’ is a
synonym for ‘%reldir%’, and ‘%C%’ is a synonym for ‘%canon_reldir%’.

   A special feature is that if the fragment is in the same directory as
the base ‘Makefile.am’ (i.e., ‘%reldir%’ is ‘.’), then ‘%reldir%’ and
‘%canon_reldir%’ will expand to the empty string as well as eat, if
present, a following slash or underscore respectively.

   Thus, a makefile fragment might look like this:

     bin_PROGRAMS += %reldir%/mumble
     %canon_reldir%_mumble_SOURCES = %reldir%/one.c

20 Conditionals
***************

Automake supports a simple type of conditional.

   These conditionals are not the same as conditionals in GNU Make.
Automake conditionals are checked at configure time by the ‘configure’
script, and affect the translation from ‘Makefile.in’ to ‘Makefile’.
They are based on options passed to ‘configure’ and on results that
‘configure’ has discovered about the host system.  GNU Make conditionals
are checked at ‘make’ time, and are based on variables passed to the
make program or defined in the ‘Makefile’.

   Automake conditionals will work with any make program.

20.1 Usage of Conditionals
==========================

Before using a conditional, you must define it by using ‘AM_CONDITIONAL’
in the ‘configure.ac’ file (see Macros).

 -- Macro: AM_CONDITIONAL (CONDITIONAL, CONDITION)
     The conditional name, CONDITIONAL, should be a simple string
     starting with a letter and containing only letters, digits, and
     underscores.  It must be different from ‘TRUE’ and ‘FALSE’, which
     are reserved by Automake.

     The shell CONDITION (suitable for use in a shell ‘if’ statement) is
     evaluated when ‘configure’ is run.  Note that you must arrange for
     _every_ ‘AM_CONDITIONAL’ to be invoked every time ‘configure’ is
     run.  If ‘AM_CONDITIONAL’ is run conditionally (e.g., in a shell
     ‘if’ statement), then the result will confuse ‘automake’.

   Conditionals typically depend upon options that the user provides to
the ‘configure’ script.  Here is an example of how to write a
conditional that is true if the user uses the ‘--enable-debug’ option.

     AC_ARG_ENABLE([debug],
     [  --enable-debug    Turn on debugging],
     [case "${enableval}" in
       yes) debug=true ;;
       no)  debug=false ;;
       *) AC_MSG_ERROR([bad value ${enableval} for --enable-debug]) ;;
     esac],[debug=false])
     AM_CONDITIONAL([DEBUG], [test x$debug = xtrue])

   Here is an example of how to use that conditional in ‘Makefile.am’:

     if DEBUG
     DBG = debug
     else
     DBG =
     endif
     noinst_PROGRAMS = $(DBG)

   This trivial example could also be handled using ‘EXTRA_PROGRAMS’
(see Conditional Programs).

   You may only test a single variable in an ‘if’ statement, possibly
negated using ‘!’.  The ‘else’ statement may be omitted.  Conditionals
may be nested to any depth.  You may specify an argument to ‘else’ in
which case it must be the negation of the condition used for the current
‘if’.  Similarly you may specify the condition that is closed on the
‘endif’ line:

     if DEBUG
     DBG = debug
     else !DEBUG
     DBG =
     endif !DEBUG

Unbalanced conditions are errors.  The ‘if’, ‘else’, and ‘endif’
statements should not be indented, i.e., start on column one.

   The ‘else’ branch of the above two examples could be omitted, since
assigning the empty string to an otherwise undefined variable makes no
difference.

   In order to allow access to the condition registered by
‘AM_CONDITIONAL’ inside ‘configure.ac’, and to allow conditional
‘AC_CONFIG_FILES’, ‘AM_COND_IF’ may be used:

 -- Macro: AM_COND_IF (CONDITIONAL, [IF-TRUE], [IF-FALSE])
     If CONDITIONAL is fulfilled, execute IF-TRUE, otherwise execute
     IF-FALSE.  If either branch contains ‘AC_CONFIG_FILES’, it will
     cause ‘automake’ to output the rules for the respective files only
     for the given condition.

   ‘AM_COND_IF’ macros may be nested when m4 quotation is used properly
(see M4 Quotation (autoconf)).

   Here is an example of how to define a conditional config file:

     AM_CONDITIONAL([SHELL_WRAPPER], [test "x$with_wrapper" = xtrue])
     AM_COND_IF([SHELL_WRAPPER],
                [AC_CONFIG_FILES([wrapper:wrapper.in])])

20.2 Limits of Conditionals
===========================

Conditionals should enclose complete statements like variables or rules
definitions.  Automake cannot deal with conditionals used inside a
variable definition, for instance, and is not even able to diagnose this
situation.  The following example would not work:

     # This syntax is not understood by Automake
     AM_CPPFLAGS = \
       -DFEATURE_A \
     if WANT_DEBUG
       -DDEBUG \
     endif
       -DFEATURE_B

   However the intended definition of ‘AM_CPPFLAGS’ can be achieved with

     if WANT_DEBUG
       DEBUGFLAGS = -DDEBUG
     endif
     AM_CPPFLAGS = -DFEATURE_A $(DEBUGFLAGS) -DFEATURE_B

or

     AM_CPPFLAGS = -DFEATURE_A
     if WANT_DEBUG
     AM_CPPFLAGS += -DDEBUG
     endif
     AM_CPPFLAGS += -DFEATURE_B

   More details and examples of conditionals are described alongside
various Automake features in this manual (see Conditional Subdirectories,
see Conditional Sources, Conditional Programs,
see Conditional Libtool Libraries, Conditional Libtool Sources).

21 Silencing ‘make’
*******************

21.1 Make is verbose by default
===============================

Normally, when executing the set of rules associated with a target,
‘make’ prints each rule before it is executed.  This behaviour, while
having been in place for a long time, and being even mandated by the
POSIX standard, starkly violates the “silence is golden” UNIX
principle(1):

     When a program has nothing interesting or surprising to say, it
     should say nothing.  Well-behaved Unix programs do their jobs
     unobtrusively, with a minimum of fuss and bother.  Silence is
     golden.

   In fact, while such verbosity of ‘make’ can theoretically be useful
to track bugs and understand reasons of failures right away, it can also
hide warning and error messages from ‘make’-invoked tools, drowning them
in a flood of uninteresting and seldom useful messages, and thus
allowing them to go easily undetected.

   This problem can be very annoying, especially for developers, who
usually know quite well what’s going on behind the scenes, and for whom
the verbose output from ‘make’ ends up being mostly noise that hampers
the easy detection of potentially important warning messages.

   ---------- Footnotes ----------

   (1) See also <http://catb.org/~esr/writings/taoup/html/ch11s09.html>.

21.2 Standard and generic ways to silence make
==============================================

Here we describe some common idioms/tricks to obtain a quieter make
output, with their relative advantages and drawbacks.  In the next
section (see Automake Silent Rules) we’ll see how Automake can help
in this respect, providing more elaborate and flexible idioms.

   • ‘make -s’

     This simply causes ‘make’ not to print _any_ rule before executing
     it.

     The ‘-s’ flag is mandated by POSIX, universally supported, and its
     purpose and function are easy to understand.

     But it also has its serious limitations too.  First of all, it
     embodies an “all or nothing” strategy, i.e., either everything is
     silenced, or nothing is; this lack of granularity can sometimes be
     a fatal flaw.  Moreover, when the ‘-s’ flag is used, the ‘make’
     output might turn out to be too terse; in case of errors, the user
     won’t be able to easily see what rule or command have caused them,
     or even, in case of tools with poor error reporting, what the
     errors were!

   • ‘make >/dev/null || make’

     Apparently, this perfectly obeys the “silence is golden” rule:
     warnings from stderr are passed through, output reporting is done
     only in case of error, and in that case it should provide a
     verbose-enough report to allow an easy determination of the error
     location and causes.

     However, calling ‘make’ two times in a row might hide errors
     (especially intermittent ones), or subtly change the expected
     semantics of the ‘make’ calls — these things can clearly make
     debugging and error assessment very difficult.

   • ‘make --no-print-directory’

     This is GNU ‘make’ specific.  When called with the
     ‘--no-print-directory’ option, GNU ‘make’ will disable printing of
     the working directory by invoked sub-‘make’s (the well-known
     “Entering/Leaving directory ...” messages).  This helps to decrease
     the verbosity of the output, but experience has shown that it can
     also often render debugging considerably harder in projects using
     deeply-nested ‘make’ recursion.

     As an aside, notice that the ‘--no-print-directory’ option is
     automatically activated if the ‘-s’ flag is used.

21.3 How Automake can help in silencing make
============================================

The tricks and idioms for silencing ‘make’ described in the previous
section can be useful from time to time, but we’ve seen that they all
have their serious drawbacks and limitations.  That’s why automake
provides support for a more advanced and flexible way of obtaining
quieter output from ‘make’ (for most rules at least).

   To give the gist of what Automake can do in this respect, here is a
simple comparison between a typical ‘make’ output (where silent rules
are disabled) and one with silent rules enabled:

     % cat Makefile.am
     bin_PROGRAMS = foo
     foo_SOURCES = main.c func.c
     % cat main.c
     int main (void) { return func (); }  /* func used undeclared */
     % cat func.c
     int func (void) { int i; return i; } /* i used uninitialized */

     The make output is by default very verbose.  This causes warnings
     from the compiler to be somewhat hidden, and not immediate to spot.
     % make CFLAGS=-Wall
     gcc -DPACKAGE_NAME=\"foo\" -DPACKAGE_TARNAME=\"foo\" ...
     -DPACKAGE_STRING=\"foo\ 1.0\" -DPACKAGE_BUGREPORT=\"\" ...
     -DPACKAGE=\"foo\" -DVERSION=\"1.0\" -I. -Wall -MT main.o
     -MD -MP -MF .deps/main.Tpo -c -o main.o main.c
     main.c: In function ‘main’:
     main.c:3:3: warning: implicit declaration of function ‘func’
     mv -f .deps/main.Tpo .deps/main.Po
     gcc -DPACKAGE_NAME=\"foo\" -DPACKAGE_TARNAME=\"foo\" ...
     -DPACKAGE_STRING=\"foo\ 1.0\" -DPACKAGE_BUGREPORT=\"\" ...
     -DPACKAGE=\"foo\" -DVERSION=\"1.0\" -I. -Wall -MT func.o
     -MD -MP -MF .deps/func.Tpo -c -o func.o func.c
     func.c: In function ‘func’:
     func.c:4:3: warning: ‘i’ used uninitialized in this function
     mv -f .deps/func.Tpo .deps/func.Po
     gcc -Wall -o foo main.o func.o

     Clean up, so that we we can rebuild everything from scratch.
     % make clean
     test -z "foo" || rm -f foo
     rm -f *.o

     Silent rules enabled: the output is minimal but informative.  In
     particular, the warnings from the compiler stick out very clearly.
     % make V=0 CFLAGS=-Wall
       CC     main.o
     main.c: In function ‘main’:
     main.c:3:3: warning: implicit declaration of function ‘func’
       CC     func.o
     func.c: In function ‘func’:
     func.c:4:3: warning: ‘i’ used uninitialized in this function
       CCLD   foo

   Also, in projects using ‘libtool’, the use of silent rules can
automatically enable the ‘libtool’’s ‘--silent’ option:

     % cat Makefile.am
     lib_LTLIBRARIES = libx.la

     % make # Both make and libtool are verbose by default.
     ...
     libtool: compile: gcc -DPACKAGE_NAME=\"foo\" ... -DLT_OBJDIR=\".libs/\"
       -I. -g -O2 -MT libx.lo -MD -MP -MF .deps/libx.Tpo -c libx.c -fPIC
       -DPIC -o .libs/libx.o
     mv -f .deps/libx.Tpo .deps/libx.Plo
     /bin/sh ./libtool --tag=CC --mode=link gcc -g -O2 -o libx.la -rpath
       /usr/local/lib libx.lo
     libtool: link: gcc -shared .libs/libx.o -Wl,-soname -Wl,libx.so.0
       -o .libs/libx.so.0.0.0
     libtool: link: cd .libs && rm -f libx.so && ln -s libx.so.0.0.0 libx.so
     ...

     % make V=0
       CC     libx.lo
       CCLD   libx.la

   For Automake-generated ‘Makefile’s, the user may influence the
verbosity at ‘configure’ run time as well as at ‘make’ run time:

   • Passing ‘--enable-silent-rules’ to ‘configure’ will cause build
     rules to be less verbose; the option ‘--disable-silent-rules’ will
     cause normal verbose output.
   • At ‘make’ run time, the default chosen at ‘configure’ time may be
     overridden: ‘make V=1’ will produce verbose output, ‘make V=0’ less
     verbose output.

   Note that silent rules are _disabled_ by default; the user must
enable them explicitly at either ‘configure’ run time or at ‘make’ run
time.  We think that this is a good policy, since it provides the casual
user with enough information to prepare a good bug report in case
anything breaks.

   Still, notwithstanding the rationales above, a developer who really
wants to make silent rules enabled by default in his own package can do
so by calling ‘AM_SILENT_RULES([yes])’ in ‘configure.ac’.

   Users who prefer to have silent rules enabled by default can edit
their ‘config.site’ file to make the variable ‘enable_silent_rules’
default to ‘yes’.  This should still allow disabling silent rules at
‘configure’ time and at ‘make’ time.

   For portability to different ‘make’ implementations, package authors
are advised to not set the variable ‘V’ inside the ‘Makefile.am’ file,
to allow the user to override the value for subdirectories as well.

   To work at its best, the current implementation of this feature
normally uses nested variable expansion ‘$(VAR1$(V))’, a ‘Makefile’
feature that is not required by POSIX 2008 but is widely supported in
practice.  On the rare ‘make’ implementations that do not support nested
variable expansion, whether rules are silent is always determined at
configure time, and cannot be overridden at make time.  Future versions
of POSIX are likely to require nested variable expansion, so this minor
limitation should go away with time.

   To extend the silent mode to your own rules, you have a few choices:

   • You can use the predefined variable ‘AM_V_GEN’ as a prefix to
     commands that should output a status line in silent mode, and
     ‘AM_V_at’ as a prefix to commands that should not output anything
     in silent mode.  When output is to be verbose, both of these
     variables will expand to the empty string.

   • You can silence a recipe unconditionally with ‘@’, and then use the
     predefined variable ‘AM_V_P’ to know whether make is being run in
     silent or verbose mode; adjust the verbose information your recipe
     displays accordingly:

          generate-headers:
                          ... [commands defining a shell variable '$headers'] ...; \
                  if $(AM_V_P); then set -x; else echo " GEN   [headers]"; fi; \
                  rm -f $$headers && generate-header --flags $$headers

   • You can add your own variables, so strings of your own choice are
     shown.  The following snippet shows how you would define your own
     equivalent of ‘AM_V_GEN’:

          pkg_verbose = $(pkg_verbose_@AM_V@)
          pkg_verbose_ = $(pkg_verbose_@AM_DEFAULT_V@)
          pkg_verbose_0 = @echo PKG-GEN $@;

          foo: foo.in
                  $(pkg_verbose)cp $(srcdir)/foo.in $@

   As a final note, observe that, even when silent rules are enabled,
the ‘--no-print-directory’ option is still required with GNU ‘make’ if
the “Entering/Leaving directory ...” messages are to be disabled.

22 The effect of ‘--gnu’ and ‘--gnits’
**************************************

The ‘--gnu’ option (or ‘gnu’ in the ‘AUTOMAKE_OPTIONS’ variable) causes
‘automake’ to check the following:

   • The files ‘INSTALL’, ‘NEWS’, ‘README’, ‘AUTHORS’, and ‘ChangeLog’,
     plus one of ‘COPYING.LIB’, ‘COPYING.LESSER’ or ‘COPYING’, are
     required at the topmost directory of the package.

     If the ‘--add-missing’ option is given, ‘automake’ will add a
     generic version of the ‘INSTALL’ file as well as the ‘COPYING’ file
     containing the text of the current version of the GNU General
     Public License existing at the time of this Automake release
     (version 3 as this is written,
     <https://www.gnu.org/copyleft/gpl.html>).  However, an existing
     ‘COPYING’ file will never be overwritten by ‘automake’.

   • The options ‘no-installman’ and ‘no-installinfo’ are prohibited.

   Note that this option will be extended in the future to do even more
checking; it is advisable to be familiar with the precise requirements
of the GNU standards.  Also, ‘--gnu’ can require certain non-standard
GNU programs to exist for use by various maintainer-only rules; for
instance, in the future ‘pathchk’ might be required for ‘make dist’.

   The ‘--gnits’ option does everything that ‘--gnu’ does, and checks
the following as well:

   • ‘make installcheck’ will check to make sure that the ‘--help’ and
     ‘--version’ really print a usage message and a version string,
     respectively.  This is the ‘std-options’ option (see Options).

   • ‘make dist’ will check to make sure the ‘NEWS’ file has been
     updated to the current version.

   • ‘VERSION’ is checked to make sure its format complies with Gnits
     standards.

   • If ‘VERSION’ indicates that this is an alpha release, and the file
     ‘README-alpha’ appears in the topmost directory of a package, then
     it is included in the distribution.  This is done in ‘--gnits’
     mode, and no other, because this mode is the only one where version
     number formats are constrained, and hence the only mode where
     Automake can automatically determine whether ‘README-alpha’ should
     be included.

   • The file ‘THANKS’ is required.

23 When Automake Isn’t Enough
*****************************

In some situations, where Automake is not up to one task, one has to
resort to handwritten rules or even handwritten ‘Makefile’s.

23.1 Extending Automake Rules
=============================

With some minor exceptions (for example ‘_PROGRAMS’ variables, ‘TESTS’,
or ‘XFAIL_TESTS’) being rewritten to append ‘$(EXEEXT)’), the contents
of a ‘Makefile.am’ is copied to ‘Makefile.in’ verbatim.

   These copying semantics mean that many problems can be worked around
by simply adding some ‘make’ variables and rules to ‘Makefile.am’.
Automake will ignore these additions.

   Since a ‘Makefile.in’ is built from data gathered from three
different places (‘Makefile.am’, ‘configure.ac’, and ‘automake’ itself),
it is possible to have conflicting definitions of rules or variables.
When building ‘Makefile.in’ the following priorities are respected by
‘automake’ to ensure the user always has the last word:

   • User defined variables in ‘Makefile.am’ have priority over
     variables ‘AC_SUBST’ed from ‘configure.ac’, and ‘AC_SUBST’ed
     variables have priority over ‘automake’-defined variables.
   • As far as rules are concerned, a user-defined rule overrides any
     ‘automake’-defined rule for the same target.

   These overriding semantics make it possible to fine tune some default
settings of Automake, or replace some of its rules.  Overriding Automake
rules is often inadvisable, particularly in the topmost directory of a
package with subdirectories.  The ‘-Woverride’ option (see automake Invocation)
comes in handy to catch overridden definitions.

   Note that Automake does not make any distinction between rules with
commands and rules that only specify dependencies.  So it is not
possible to append new dependencies to an ‘automake’-defined target
without redefining the entire rule.

   However, various useful targets have a ‘-local’ version you can
specify in your ‘Makefile.am’.  Automake will supplement the standard
target with these user-supplied targets.

   The targets that support a local version are ‘all’, ‘info’, ‘dvi’,
‘ps’, ‘pdf’, ‘html’, ‘check’, ‘install-data’, ‘install-dvi’,
‘install-exec’, ‘install-html’, ‘install-info’, ‘install-pdf’,
‘install-ps’, ‘uninstall’, ‘installdirs’, ‘installcheck’ and the various
‘clean’ targets (‘mostlyclean’, ‘clean’, ‘distclean’, and
‘maintainer-clean’).

   Note that there are no ‘uninstall-exec-local’ or
‘uninstall-data-local’ targets; just use ‘uninstall-local’.  It doesn’t
make sense to uninstall just data or just executables.

   For instance, here is one way to erase a subdirectory during ‘make
clean’ (see Clean).

     clean-local:
             -rm -rf testSubDir

   You may be tempted to use ‘install-data-local’ to install a file to
some hard-coded location, but you should avoid this (see Hard-Coded Install Paths).

   With the ‘-local’ targets, there is no particular guarantee of
execution order; typically, they are run early, but with parallel make,
there is no way to be sure of that.

   In contrast, some rules also have a way to run another rule, called a
“hook”; hooks are always executed after the main rule’s work is done.
The hook is named after the principal target, with ‘-hook’ appended.
The targets allowing hooks are ‘install-data’, ‘install-exec’,
‘uninstall’, ‘dist’, and ‘distcheck’.

   For instance, here is how to create a hard link to an installed
program:

     install-exec-hook:
             ln $(DESTDIR)$(bindir)/program$(EXEEXT) \
                $(DESTDIR)$(bindir)/proglink$(EXEEXT)

   Although cheaper and more portable than symbolic links, hard links
will not work everywhere (for instance, OS/2 does not have ‘ln’).
Ideally you should fall back to ‘cp -p’ when ‘ln’ does not work.  An
easy way, if symbolic links are acceptable to you, is to add
‘AC_PROG_LN_S’ to ‘configure.ac’ (see Particular Program Checks (autoconf))
and use ‘$(LN_S)’ in ‘Makefile.am’.

   For instance, here is how you could install a versioned copy of a
program using ‘$(LN_S)’:

     install-exec-hook:
             cd $(DESTDIR)$(bindir) && \
               mv -f prog$(EXEEXT) prog-$(VERSION)$(EXEEXT) && \
               $(LN_S) prog-$(VERSION)$(EXEEXT) prog$(EXEEXT)

   Note that we rename the program so that a new version will erase the
symbolic link, not the real binary.  Also we ‘cd’ into the destination
directory in order to create relative links.

   When writing ‘install-exec-hook’ or ‘install-data-hook’, please bear
in mind that the exec/data distinction is based on the installation
directory, not on the primary used (see The Two Parts of Install).
So a ‘foo_SCRIPTS’ will be installed by ‘install-data’, and a
‘barexec_SCRIPTS’ will be installed by ‘install-exec’.  You should
define your hooks accordingly.

23.2 Third-Party ‘Makefile’s
============================

In most projects all ‘Makefile’s are generated by Automake.  In some
cases, however, projects need to embed subdirectories with handwritten
‘Makefile’s.  For instance, one subdirectory could be a third-party
project with its own build system, not using Automake.

   It is possible to list arbitrary directories in ‘SUBDIRS’ or
‘DIST_SUBDIRS’ provided each of these directories has a ‘Makefile’ that
recognizes all the following recursive targets.

   When a user runs one of these targets, that target is run recursively
in all subdirectories.  This is why it is important that even
third-party ‘Makefile’s support them.

‘all’
     Compile the entire package.  This is the default target in
     Automake-generated ‘Makefile’s, but it does not need to be the
     default in third-party ‘Makefile’s.

‘distdir’
     Copy files to distribute into ‘$(distdir)’, before a tarball is
     constructed.  Of course this target is not required if the
     ‘no-dist’ option (see Options) is used.

     The variables ‘$(top_distdir)’ and ‘$(distdir)’ (see The dist Hook)
     will be passed from the outer package to the subpackage
     when the ‘distdir’ target is invoked.  These two variables have
     been adjusted for the directory that is being recursed into, so
     they are ready to use.

‘install’
‘install-data’
‘install-exec’
‘uninstall’
     Install or uninstall files (see Install).

‘install-dvi’
‘install-html’
‘install-info’
‘install-ps’
‘install-pdf’
     Install only some specific documentation format (see Texinfo).

‘installdirs’
     Create install directories, but do not install any files.

‘check’
‘installcheck’
     Check the package (see Tests).

‘mostlyclean’
‘clean’
‘distclean’
‘maintainer-clean’
     Cleaning rules (see Clean).

‘dvi’
‘pdf’
‘ps’
‘info’
‘html’
     Build the documentation in various formats (see Texinfo).

‘tags’
‘ctags’
     Build ‘TAGS’ and ‘CTAGS’ (see Tags).

   If you have ever used Gettext in a project, this is a good example of
how third-party ‘Makefile’s can be used with Automake.  The ‘Makefile’s
that ‘gettextize’ puts in the ‘po/’ and ‘intl/’ directories are
handwritten ‘Makefile’s that implement all of these targets.  That way
they can be added to ‘SUBDIRS’ in Automake packages.

   Directories that are only listed in ‘DIST_SUBDIRS’ but not in
‘SUBDIRS’ need only the ‘distclean’, ‘maintainer-clean’, and ‘distdir’
rules (see Conditional Subdirectories).

   Usually, many of these rules are irrelevant to the third-party
subproject, but they are required for the whole package to work.  It’s
OK to have a rule that does nothing, so if you are integrating a
third-party project with no documentation or tag support, you could
simply augment its ‘Makefile’ as follows:

     EMPTY_AUTOMAKE_TARGETS = dvi pdf ps info html tags ctags
     .PHONY: $(EMPTY_AUTOMAKE_TARGETS)
     $(EMPTY_AUTOMAKE_TARGETS):

   Another aspect of integrating third-party build systems is whether
they support VPATH builds (see VPATH Builds).  Obviously if the
subpackage does not support VPATH builds the whole package will not
support VPATH builds.  This in turns means that ‘make distcheck’ will
not work, because it relies on VPATH builds.  Some people can live
without this (actually, many Automake users have never heard of ‘make
distcheck’).  Other people may prefer to revamp the existing ‘Makefile’s
to support VPATH.  Doing so does not necessarily require Automake; only
Autoconf is needed (see Build Directories (autoconf)).
The necessary substitutions: ‘@srcdir@’, ‘@top_srcdir@’,
and ‘@top_builddir@’ are defined by ‘configure’ when it processes a
‘Makefile’ (see Preset Output Variables (autoconf));
they are not computed by the Makefile like the
aforementioned ‘$(distdir)’ and ‘$(top_distdir)’ variables.

   It is sometimes inconvenient to modify a third-party ‘Makefile’ to
introduce the above required targets.  For instance, one may want to
keep the third-party sources untouched to ease upgrades to new versions.

   Here are two other ideas.  If GNU make is assumed, one possibility is
to add to that subdirectory a ‘GNUmakefile’ that defines the required
targets and includes the third-party ‘Makefile’.  For this to work in
VPATH builds, ‘GNUmakefile’ must lie in the build directory; the easiest
way to do this is to write a ‘GNUmakefile.in’ instead, and have it
processed with ‘AC_CONFIG_FILES’ from the outer package.  For example if
we assume ‘Makefile’ defines all targets except the documentation
targets, and that the ‘check’ target is actually called ‘test’, we could
write ‘GNUmakefile’ (or ‘GNUmakefile.in’) like this:

     # First, include the real Makefile
     include Makefile
     # Then, define the other targets needed by Automake Makefiles.
     .PHONY: dvi pdf ps info html check
     dvi pdf ps info html:
     check: test

   A similar idea that does not use ‘include’ is to write a proxy
‘Makefile’ that dispatches rules to the real ‘Makefile’, either with
‘$(MAKE) -f Makefile.real $(AM_MAKEFLAGS) target’ (if it’s OK to rename
the original ‘Makefile’) or with ‘cd subdir && $(MAKE) $(AM_MAKEFLAGS)
target’ (if it’s OK to store the subdirectory project one directory
deeper).  The good news is that this proxy ‘Makefile’ can be generated
with Automake.  All we need are ‘-local’ targets (see Extending)
that perform the dispatch.  Of course the other Automake features are
available, so you could decide to let Automake perform distribution or
installation.  Here is a possible ‘Makefile.am’:

     all-local:
             cd subdir && $(MAKE) $(AM_MAKEFLAGS) all
     check-local:
             cd subdir && $(MAKE) $(AM_MAKEFLAGS) test
     clean-local:
             cd subdir && $(MAKE) $(AM_MAKEFLAGS) clean

     # Assuming the package knows how to install itself
     install-data-local:
             cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-data
     install-exec-local:
             cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-exec
     uninstall-local:
             cd subdir && $(MAKE) $(AM_MAKEFLAGS) uninstall

     # Distribute files from here.
     EXTRA_DIST = subdir/Makefile subdir/program.c ...

   Pushing this idea to the extreme, it is also possible to ignore the
subproject build system and build everything from this proxy
‘Makefile.am’.  This might sound very sensible if you need VPATH builds
but the subproject does not support them.

24 Distributing ‘Makefile.in’s
******************************

Automake places no restrictions on the distribution of the resulting
‘Makefile.in’s.  We still encourage software authors to distribute their
work under terms like those of the GPL, but doing so is not required to
use Automake.

   Some of the files that can be automatically installed via the
‘--add-missing’ switch do fall under the GPL.  However, these also have
a special exception allowing you to distribute them with your package,
regardless of the licensing you choose.

25 Automake API Versioning
**************************

New Automake releases usually include bug fixes and new features.
Unfortunately they may also introduce new bugs and incompatibilities.
This makes four reasons why a package may require a particular Automake
version.

   Things get worse when maintaining a large tree of packages, each one
requiring a different version of Automake.  In the past, this meant that
any developer (and sometimes users) had to install several versions of
Automake in different places, and switch ‘$PATH’ appropriately for each
package.

   Starting with version 1.6, Automake installs versioned binaries.
This means you can install several versions of Automake in the same
‘$prefix’, and can select an arbitrary Automake version by running
‘automake-1.6’ or ‘automake-1.7’ without juggling with ‘$PATH’.
Furthermore, ‘Makefile’s generated by Automake 1.6 will use
‘automake-1.6’ explicitly in their rebuild rules.

   The number ‘1.6’ in ‘automake-1.6’ is Automake’s API version, not
Automake’s version.  If a bug fix release is made, for instance Automake
1.6.1, the API version will remain 1.6.  This means that a package that
works with Automake 1.6 should also work with 1.6.1; after all, this is
what people expect from bug fix releases.

   If your package relies on a feature or a bug fix introduced in a
release, you can pass this version as an option to Automake to ensure
older releases will not be used.  For instance, use this in your
‘configure.ac’:

       AM_INIT_AUTOMAKE([1.6.1])    dnl Require Automake 1.6.1 or better.

or, in a particular ‘Makefile.am’:

       AUTOMAKE_OPTIONS = 1.6.1   # Require Automake 1.6.1 or better.

Automake will print an error message if its version is older than the
requested version.

What is in the API
==================

Automake’s programming interface is not easy to define.  Basically it
should include at least all *documented* variables and targets that a
‘Makefile.am’ author can use, any behavior associated with them (e.g.,
the places where ‘-hook’’s are run), the command line interface of
‘automake’ and ‘aclocal’, ...

What is not in the API
======================

Every undocumented variable, target, or command line option is not part
of the API.  You should avoid using them, as they could change from one
version to the other (even in bug fix releases, if this helps to fix a
bug).

   If it turns out you need to use such an undocumented feature, contact
<automake@gnu.org> and try to get it documented and exercised by the
test-suite.

26 Upgrading a Package to a Newer Automake Version
**************************************************

Automake maintains three kinds of files in a package.

   • ‘aclocal.m4’
   • ‘Makefile.in’s
   • auxiliary tools like ‘install-sh’ or ‘py-compile’

   ‘aclocal.m4’ is generated by ‘aclocal’ and contains some
Automake-supplied M4 macros.  Auxiliary tools are installed by ‘automake
--add-missing’ when needed.  ‘Makefile.in’s are built from ‘Makefile.am’
by ‘automake’, and rely on the definitions of the M4 macros put in
‘aclocal.m4’ as well as the behavior of the auxiliary tools installed.

   Because all of these files are closely related, it is important to
regenerate all of them when upgrading to a newer Automake release.  The
usual way to do that is

     aclocal # with any option needed (such as -I m4)
     autoconf
     automake --add-missing --force-missing

or more conveniently:

     autoreconf -vfi

   The use of ‘--force-missing’ ensures that auxiliary tools will be
overridden by new versions (see automake Invocation).

   It is important to regenerate all of these files each time Automake
is upgraded, even between bug fix releases.  For instance, it is not
unusual for a bug fix to involve changes to both the rules generated in
‘Makefile.in’ and the supporting M4 macros copied to ‘aclocal.m4’.

   Presently ‘automake’ is able to diagnose situations where
‘aclocal.m4’ has been generated with another version of ‘aclocal’.
However it never checks whether auxiliary scripts are up-to-date.  In
other words, ‘automake’ will tell you when ‘aclocal’ needs to be rerun,
but it will never diagnose a missing ‘--force-missing’.

   Before upgrading to a new major release, it is a good idea to read
the file ‘NEWS’.  This file lists all changes between releases: new
features, obsolete constructs, known incompatibilities, and workarounds.

27 Frequently Asked Questions about Automake
********************************************

This chapter covers some questions that often come up on the mailing
lists.

27.1 CVS and generated files
============================

Background: distributed generated Files
---------------------------------------

Packages made with Autoconf and Automake ship with some generated files
like ‘configure’ or ‘Makefile.in’.  These files were generated on the
developer’s machine and are distributed so that end-users do not have to
install the maintainer tools required to rebuild them.  Other generated
files like Lex scanners, Yacc parsers, or Info documentation are usually
distributed on similar grounds.

   Automake output generates rules in ‘Makefile’s to rebuild these
files.  For instance, ‘make’ will run ‘autoconf’ to rebuild ‘configure’
whenever ‘configure.ac’ is changed.  This makes development safer by
ensuring a ‘configure’ is never out-of-date with respect to
‘configure.ac’.

   As generated files shipped in packages are up-to-date, and because
‘tar’ preserves times-tamps, these rebuild rules are not triggered when
a user unpacks and builds a package.

Background: CVS and Timestamps
------------------------------

Unless you use CVS keywords (in which case files must be updated at
commit time), CVS preserves timestamp during ‘cvs commit’ and ‘cvs
import -d’ operations.

   When you check out a file using ‘cvs checkout’ its timestamp is set
to that of the revision that is being checked out.

   However, during ‘cvs update’, files will have the date of the update,
not the original timestamp of this revision.  This is meant to make sure
that ‘make’ notices that sources files have been updated.

   This timestamp shift is troublesome when both sources and generated
files are kept under CVS.  Because CVS processes files in lexical order,
‘configure.ac’ will appear newer than ‘configure’ after a ‘cvs update’
that updates both files, even if ‘configure’ was newer than
‘configure.ac’ when it was checked in.  Calling ‘make’ will then trigger
a spurious rebuild of ‘configure’.

Living with CVS in Autoconfiscated Projects
-------------------------------------------

There are basically two clans amongst maintainers: those who keep all
distributed files under CVS, including generated files, and those who
keep generated files _out_ of CVS.

All Files in CVS
................

   • The CVS repository contains all distributed files so you know
     exactly what is distributed, and you can check out any prior
     version entirely.

   • Maintainers can see how generated files evolve (for instance, you
     can see what happens to your ‘Makefile.in’s when you upgrade
     Automake and make sure they look OK).

   • Users do not need Autotools to build a check-out of the project; it
     works just like a released tarball.

   • If users use ‘cvs update’ to update their copy, instead of ‘cvs
     checkout’ to fetch a fresh one, timestamps will be inaccurate.
     Some rebuild rules will be triggered and attempt to run developer
     tools such as ‘autoconf’ or ‘automake’.

     Calls to such tools are all wrapped into a call to the ‘missing’
     script discussed later (see maintainer-mode), so that the user
     will see more descriptive warnings about missing or out-of-date
     tools, and possible suggestions about how to obtain them, rather
     than just some “command not found” error, or (worse) some obscure
     message from some older version of the required tool they happen to
     have installed.

     Maintainers interested in keeping their package buildable from a
     CVS checkout even for those users that lack maintainer-specific
     tools might want to provide a helper script (or to enhance their
     existing bootstrap script) to fix the timestamps after a ‘cvs
     update’ or a ‘git checkout’, to prevent spurious rebuilds.  In case
     of a project committing the Autotools-generated files, as well as
     the generated ‘.info’ files, such a script might look something
     like this:

          #!/bin/sh
          # fix-timestamp.sh: prevents useless rebuilds after "cvs update"
          sleep 1
          # aclocal-generated aclocal.m4 depends on locally-installed
          # '.m4' macro files, as well as on 'configure.ac'
          touch aclocal.m4
          sleep 1
          # autoconf-generated configure depends on aclocal.m4 and on
          # configure.ac
          touch configure
          # so does autoheader-generated config.h.in
          touch config.h.in
          # and all the automake-generated Makefile.in files
          touch `find . -name Makefile.in -print`
          # finally, the makeinfo-generated '.info' files depend on the
          # corresponding '.texi' files
          touch doc/*.info

   • In distributed development, developers are likely to have different
     versions of the maintainer tools installed.  In this case rebuilds
     triggered by timestamp lossage will lead to spurious changes to
     generated files.  There are several solutions to this:

        • All developers should use the same versions, so that the
          rebuilt files are identical to files in CVS.  (This starts to
          be difficult when each project you work on uses different
          versions.)
        • Or people use a script to fix the timestamp after a checkout
          (the GCC folks have such a script).
        • Or ‘configure.ac’ uses ‘AM_MAINTAINER_MODE’, which will
          disable all of these rebuild rules by default.  This is
          further discussed in maintainer-mode.

   • Although we focused on spurious rebuilds, the converse can also
     happen.  CVS’s timestamp handling can also let you think an
     out-of-date file is up-to-date.

     For instance, suppose a developer has modified ‘Makefile.am’ and
     has rebuilt ‘Makefile.in’, and then decides to do a last-minute
     change to ‘Makefile.am’ right before checking in both files
     (without rebuilding ‘Makefile.in’ to account for the change).

     This last change to ‘Makefile.am’ makes the copy of ‘Makefile.in’
     out-of-date.  Since CVS processes files alphabetically, when
     another developer ‘cvs update’s his or her tree, ‘Makefile.in’ will
     happen to be newer than ‘Makefile.am’.  This other developer will
     not see that ‘Makefile.in’ is out-of-date.

Generated Files out of CVS
..........................

One way to get CVS and ‘make’ working peacefully is to never store
generated files in CVS, i.e., do not CVS-control files that are
‘Makefile’ targets (also called _derived_ files).

   This way developers are not annoyed by changes to generated files.
It does not matter if they all have different versions (assuming they
are compatible, of course).  And finally, timestamps are not lost;
changes to sources files can’t be missed as in the
‘Makefile.am’/‘Makefile.in’ example discussed earlier.

   The drawback is that the CVS repository is not an exact copy of what
is distributed and that users now need to install various development
tools (maybe even specific versions) before they can build a checkout.
But, after all, CVS’s job is versioning, not distribution.

   Allowing developers to use different versions of their tools can also
hide bugs during distributed development.  Indeed, developers will be
using (hence testing) their own generated files, instead of the
generated files that will be actually released.  The developer who
prepares the tarball might be using a version of the tool that produces
bogus output (for instance a non-portable C file), something other
developers could have noticed if they weren’t using their own versions
of this tool.

Third-party Files
-----------------

Another class of files not discussed here (because they do not cause
timestamp issues) are files that are shipped with a package, but
maintained elsewhere.  For instance, tools like ‘gettextize’ and
‘autopoint’ (from Gettext) or ‘libtoolize’ (from Libtool), will install
or update files in your package.

   These files, whether they are kept under CVS or not, raise similar
concerns about version mismatch between developers’ tools.  The Gettext
manual has a section about this; see CVS Issues (gettext).

27.2 ‘missing’ and ‘AM_MAINTAINER_MODE’
=======================================

‘missing’
---------

The ‘missing’ script is a wrapper around several maintainer tools,
designed to warn users if a maintainer tool is required but missing.
Typical maintainer tools are ‘autoconf’, ‘automake’, ‘bison’, etc.
Because files generated by these tools are shipped with the other
sources of a package, these tools shouldn’t be required during a user
build and they are not checked for in ‘configure’.

   However, if for some reason a rebuild rule is triggered and involves
a missing tool, ‘missing’ will notice it and warn the user, even
suggesting how to obtain such a tool (at least in case it is a
well-known one, like ‘makeinfo’ or ‘bison’).  This is more helpful and
user-friendly than just having the rebuild rules spewing out a terse
error message like ‘sh: TOOL: command not found’.  Similarly, ‘missing’
will warn the user if it detects that a maintainer tool it attempted to
use seems too old (be warned that diagnosing this correctly is typically
more difficult than detecting missing tools, and requires cooperation
from the tool itself, so it won’t always work).

   If the required tool is installed, ‘missing’ will run it and won’t
attempt to continue after failures.  This is correct behavior during
development: developers love fixing failures.  However, users with
missing or too old maintainer tools may get an error when the rebuild
rule is spuriously triggered, halting the build.  This failure to let
the build continue is one of the arguments of the ‘AM_MAINTAINER_MODE’
advocates.

‘AM_MAINTAINER_MODE’
--------------------

‘AM_MAINTAINER_MODE’ allows you to choose whether the so called "rebuild
rules" should be enabled or disabled.  With
‘AM_MAINTAINER_MODE([enable])’, they are enabled by default; otherwise
they are disabled by default.  In the latter case, if you have
‘AM_MAINTAINER_MODE’ in ‘configure.ac’, and run ‘./configure && make’,
then ‘make’ will *never* attempt to rebuild ‘configure’, ‘Makefile.in’s,
Lex or Yacc outputs, etc.  I.e., this disables build rules for files
that are usually distributed and that users should normally not have to
update.

   The user can override the default setting by passing either
‘--enable-maintainer-mode’ or ‘--disable-maintainer-mode’ to
‘configure’.

   People use ‘AM_MAINTAINER_MODE’ either because they do not want their
users (or themselves) annoyed by timestamp lossage (see CVS), or
because they simply can’t stand the rebuild rules and prefer running
maintainer tools explicitly.

   ‘AM_MAINTAINER_MODE’ also allows you to disable some custom build
rules conditionally.  Some developers use this feature to disable rules
that need exotic tools that users may not have available.

   Several years ago François Pinard pointed out several arguments
against this ‘AM_MAINTAINER_MODE’ macro.  Most of them relate to
insecurity.  By removing dependencies you get non-dependable builds:
changes to source files can have no effect on generated files and this
can be very confusing when unnoticed.  He adds that security shouldn’t
be reserved to maintainers (what ‘--enable-maintainer-mode’ suggests),
on the contrary.  If one user has to modify a ‘Makefile.am’, then either
‘Makefile.in’ should be updated or a warning should be output (this is
what Automake uses ‘missing’ for) but the last thing you want is that
nothing happens and the user doesn’t notice it (this is what happens
when rebuild rules are disabled by ‘AM_MAINTAINER_MODE’).

   Jim Meyering, the inventor of the ‘AM_MAINTAINER_MODE’ macro, was
swayed by François’ arguments, and got rid of ‘AM_MAINTAINER_MODE’ in
all of his packages.

   Still many people continue to use ‘AM_MAINTAINER_MODE’, because it
helps them working on projects where all files are kept under version
control, and because ‘missing’ isn’t enough if you have the wrong
version of the tools.

27.3 Why doesn’t Automake support wildcards?
============================================

Developers are lazy.  They would often like to use wildcards in
‘Makefile.am’s, so that they would not need to remember to update
‘Makefile.am’s every time they add, delete, or rename a file.

   There are several objections to this:
   • When using CVS (or similar) developers need to remember they have
     to run ‘cvs add’ or ‘cvs rm’ anyway.  Updating ‘Makefile.am’
     accordingly quickly becomes a reflex.

     Conversely, if your application doesn’t compile because you forgot
     to add a file in ‘Makefile.am’, it will help you remember to ‘cvs
     add’ it.

   • Using wildcards makes it easy to distribute files by mistake.  For
     instance, some code a developer is experimenting with (a test case,
     say) that should not be part of the distribution.

   • Using wildcards it’s easy to omit some files by mistake.  For
     instance, one developer creates a new file, uses it in many places,
     but forgets to commit it.  Another developer then checks out the
     incomplete project and is able to run ‘make dist’ successfully,
     even though a file is missing.  By listing files, ‘make dist’
     _will_ complain.

   • Wildcards are not portable to some non-GNU ‘make’ implementations,
     e.g., NetBSD ‘make’ will not expand globs such as ‘*’ in
     prerequisites of a target.

   • Finally, it’s really hard to _forget_ to add a file to
     ‘Makefile.am’: files that are not listed in ‘Makefile.am’ are not
     compiled or installed, so you can’t even test them.

   Still, these are philosophical objections, and as such you may
disagree, or find enough value in wildcards to dismiss all of them.
Before you start writing a patch against Automake to teach it about
wildcards, let’s see the main technical issue: portability.

   Although ‘$(wildcard ...)’ works with GNU ‘make’, it is not portable
to other ‘make’ implementations.

   The only way Automake could support ‘$(wildcard ...)’ is by expanding
‘$(wildcard ...)’ when ‘automake’ is run.  The resulting ‘Makefile.in’s
would be portable since they would list all files and not use
‘$(wildcard ...)’.  However that means developers would need to remember
to run ‘automake’ each time they add, delete, or rename files.

   Compared to editing ‘Makefile.am’, this is a very small gain.  Sure,
it’s easier and faster to type ‘automake; make’ than to type ‘emacs
Makefile.am; make’.  But nobody bothered enough to write a patch to add
support for this syntax.  Some people use scripts to generate file lists
in ‘Makefile.am’ or in separate ‘Makefile’ fragments.

   Even if you don’t care about portability, and are tempted to use
‘$(wildcard ...)’ anyway because you target only GNU Make, you should
know there are many places where Automake needs to know exactly which
files should be processed.  As Automake doesn’t know how to expand
‘$(wildcard ...)’, you cannot use it in these places.  ‘$(wildcard ...)’
is a black box comparable to ‘AC_SUBST’ed variables as far Automake is
concerned.

   You can get warnings about ‘$(wildcard ...’) constructs using the
‘-Wportability’ flag.

27.4 Limitations on File Names
==============================

Automake attempts to support all kinds of file names, even those that
contain unusual characters or are unusually long.  However, some
limitations are imposed by the underlying operating system and tools.

   Most operating systems prohibit the use of the null byte in file
names, and reserve ‘/’ as a directory separator.  Also, they require
that file names are properly encoded for the user’s locale.  Automake is
subject to these limits.

   Portable packages should limit themselves to POSIX file names.  These
can contain ASCII letters and digits, ‘_’, ‘.’, and ‘-’.  File names
consist of components separated by ‘/’.  File name components cannot
begin with ‘-’.

   Portable POSIX file names cannot contain components that exceed a
14-byte limit, but nowadays it’s normally safe to assume the
more-generous XOPEN limit of 255 bytes.  POSIX limits file names to 255
bytes (XOPEN allows 1023 bytes), but you may want to limit a source
tarball to file names of 99 bytes to avoid interoperability problems
with old versions of ‘tar’.

   If you depart from these rules (e.g., by using non-ASCII characters
in file names, or by using lengthy file names), your installers may have
problems for reasons unrelated to Automake.  However, if this does not
concern you, you should know about the limitations imposed by Automake
itself.  These limitations are undesirable, but some of them seem to be
inherent to underlying tools like Autoconf, Make, M4, and the shell.
They fall into three categories: install directories, build directories,
and file names.

   The following characters:

     newline " # $ ' `

   should not appear in the names of install directories.  For example,
the operand of ‘configure’’s ‘--prefix’ option should not contain these
characters.

   Build directories suffer the same limitations as install directories,
and in addition should not contain the following characters:

     & @ \

   For example, the full name of the directory containing the source
files should not contain these characters.

   Source and installation file names like ‘main.c’ are limited even
further: they should conform to the POSIX/XOPEN rules described above.
In addition, if you plan to port to non-POSIX environments, you should
avoid file names that differ only in case (e.g., ‘makefile’ and
‘Makefile’).  Nowadays it is no longer worth worrying about the 8.3
limits of DOS file systems.

27.5 Errors with distclean
==========================

This is a diagnostic you might encounter while running ‘make distcheck’.

   As explained in Checking the Distribution, ‘make distcheck’
attempts to build and check your package for errors like this one.

   ‘make distcheck’ will perform a ‘VPATH’ build of your package (see
VPATH Builds), and then call ‘make distclean’.  Files left in the
build directory after ‘make distclean’ has run are listed after this
error.

   This diagnostic really covers two kinds of errors:

   • files that are forgotten by distclean;
   • distributed files that are erroneously rebuilt.

   The former left-over files are not distributed, so the fix is to mark
them for cleaning (see Clean); this is obvious and doesn’t deserve
more explanation.

   The latter bug is not always easy to understand and fix, so let’s
proceed with an example.  Suppose our package contains a program for
which we want to build a man page using ‘help2man’.  GNU ‘help2man’
produces simple manual pages from the ‘--help’ and ‘--version’ output of
other commands (see Overview (help2man)).  Because we don’t want
to force our users to install ‘help2man’, we decide to distribute the
generated man page using the following setup.

     # This Makefile.am is bogus.
     bin_PROGRAMS = foo
     foo_SOURCES = foo.c
     dist_man_MANS = foo.1

     foo.1: foo$(EXEEXT)
             help2man --output=foo.1 ./foo$(EXEEXT)

   This will effectively distribute the man page.  However, ‘make
distcheck’ will fail with:

     ERROR: files left in build directory after distclean:
     ./foo.1

   Why was ‘foo.1’ rebuilt?  Because although distributed, ‘foo.1’
depends on a non-distributed built file: ‘foo$(EXEEXT)’.  ‘foo$(EXEEXT)’
is built by the user, so it will always appear to be newer than the
distributed ‘foo.1’.

   ‘make distcheck’ caught an inconsistency in our package.  Our intent
was to distribute ‘foo.1’ so users do not need to install ‘help2man’,
however since this rule causes this file to be always rebuilt, users
_do_ need ‘help2man’.  Either we should ensure that ‘foo.1’ is not
rebuilt by users, or there is no point in distributing ‘foo.1’.

   More generally, the rule is that distributed files should never
depend on non-distributed built files.  If you distribute something
generated, distribute its sources.

   One way to fix the above example, while still distributing ‘foo.1’,
is to not depend on ‘foo$(EXEEXT)’.  For instance, assuming ‘foo
--version’ and ‘foo --help’ do not change unless ‘foo.c’ or
‘configure.ac’ change, we could write the following ‘Makefile.am’:

     bin_PROGRAMS = foo
     foo_SOURCES = foo.c
     dist_man_MANS = foo.1

     foo.1: foo.c $(top_srcdir)/configure.ac
             $(MAKE) $(AM_MAKEFLAGS) foo$(EXEEXT)
             help2man --output=foo.1 ./foo$(EXEEXT)

   This way, ‘foo.1’ will not get rebuilt every time ‘foo$(EXEEXT)’
changes.  The ‘make’ call makes sure ‘foo$(EXEEXT)’ is up-to-date before
‘help2man’.  Another way to ensure this would be to use separate
directories for binaries and man pages, and set ‘SUBDIRS’ so that
binaries are built before man pages.

   We could also decide not to distribute ‘foo.1’.  In this case it’s
fine to have ‘foo.1’ dependent upon ‘foo$(EXEEXT)’, since both will have
to be rebuilt.  However, it would be impossible to build the package in
a cross-compilation, because building ‘foo.1’ involves an _execution_ of
‘foo$(EXEEXT)’.

   Another context where such errors are common is when distributed
files are built by tools that are built by the package.  The pattern is
similar:

     distributed-file: built-tools distributed-sources
             build-command

should be changed to

     distributed-file: distributed-sources
             $(MAKE) $(AM_MAKEFLAGS) built-tools
             build-command

or you could choose not to distribute ‘distributed-file’, if
cross-compilation does not matter.

   The points made through these examples are worth a summary:

   • Distributed files should never depend upon non-distributed built
     files.
   • Distributed files should be distributed with all their
     dependencies.
   • If a file is _intended_ to be rebuilt by users, then there is no
     point in distributing it.

   For desperate cases, it’s always possible to disable this check by
setting ‘distcleancheck_listfiles’ as documented in Checking the Distribution.
Make sure you do understand the reason why ‘make
distcheck’ complains before you do this.  ‘distcleancheck_listfiles’ is
a way to _hide_ errors, not to fix them.  You can always do better.

27.6 Flag Variables Ordering
============================

     What is the difference between ‘AM_CFLAGS’, ‘CFLAGS’, and
     ‘mumble_CFLAGS’?

     Why does ‘automake’ output ‘CPPFLAGS’ after
     ‘AM_CPPFLAGS’ on compile lines?  Shouldn’t it be the converse?

     My ‘configure’ adds some warning flags into ‘CXXFLAGS’.  In
     one ‘Makefile.am’ I would like to append a new flag, however if I
     put the flag into ‘AM_CXXFLAGS’ it is prepended to the other
     flags, not appended.

Compile Flag Variables
----------------------

This section attempts to answer all the above questions.  We will mostly
discuss ‘CPPFLAGS’ in our examples, but actually the answer holds for
all the compile flags used in Automake: ‘CCASFLAGS’, ‘CFLAGS’,
‘CPPFLAGS’, ‘CXXFLAGS’, ‘FCFLAGS’, ‘FFLAGS’, ‘GCJFLAGS’, ‘LDFLAGS’,
‘LFLAGS’, ‘LIBTOOLFLAGS’, ‘OBJCFLAGS’, ‘OBJCXXFLAGS’, ‘RFLAGS’,
‘UPCFLAGS’, and ‘YFLAGS’.

   ‘CPPFLAGS’, ‘AM_CPPFLAGS’, and ‘mumble_CPPFLAGS’ are three variables
that can be used to pass flags to the C preprocessor (actually these
variables are also used for other languages like C++ or preprocessed
Fortran).  ‘CPPFLAGS’ is the user variable (see User Variables),
‘AM_CPPFLAGS’ is the Automake variable, and ‘mumble_CPPFLAGS’ is the
variable specific to the ‘mumble’ target (we call this a per-target
variable, see Program and Library Variables).

   Automake always uses two of these variables when compiling C sources
files.  When compiling an object file for the ‘mumble’ target, the first
variable will be ‘mumble_CPPFLAGS’ if it is defined, or ‘AM_CPPFLAGS’
otherwise.  The second variable is always ‘CPPFLAGS’.

   In the following example,

     bin_PROGRAMS = foo bar
     foo_SOURCES = xyz.c
     bar_SOURCES = main.c
     foo_CPPFLAGS = -DFOO
     AM_CPPFLAGS = -DBAZ

‘xyz.o’ will be compiled with ‘$(foo_CPPFLAGS) $(CPPFLAGS)’, (because
‘xyz.o’ is part of the ‘foo’ target), while ‘main.o’ will be compiled
with ‘$(AM_CPPFLAGS) $(CPPFLAGS)’ (because there is no per-target
variable for target ‘bar’).

   The difference between ‘mumble_CPPFLAGS’ and ‘AM_CPPFLAGS’ being
clear enough, let’s focus on ‘CPPFLAGS’.  ‘CPPFLAGS’ is a user variable,
i.e., a variable that users are entitled to modify in order to compile
the package.  This variable, like many others, is documented at the end
of the output of ‘configure --help’.

   For instance, someone who needs to add ‘/home/my/usr/include’ to the
C compiler’s search path would configure a package with

     ./configure CPPFLAGS='-I /home/my/usr/include'

and this flag would be propagated to the compile rules of all
‘Makefile’s.

   It is also not uncommon to override a user variable at ‘make’-time.
Many installers do this with ‘prefix’, but this can be useful with
compiler flags too.  For instance, if, while debugging a C++ project,
you need to disable optimization in one specific object file, you can
run something like

     rm file.o
     make CXXFLAGS=-O0 file.o
     make

   The reason ‘$(CPPFLAGS)’ appears after ‘$(AM_CPPFLAGS)’ or
‘$(mumble_CPPFLAGS)’ in the compile command is that users should always
have the last say.  It probably makes more sense if you think about it
while looking at the ‘CXXFLAGS=-O0’ above, which should supersede any
other switch from ‘AM_CXXFLAGS’ or ‘mumble_CXXFLAGS’ (and this of course
replaces the previous value of ‘CXXFLAGS’).

   You should never redefine a user variable such as ‘CPPFLAGS’ in
‘Makefile.am’.  Use ‘automake -Woverride’ to diagnose such mistakes.
Even something like

     CPPFLAGS = -DDATADIR=\"$(datadir)\" @CPPFLAGS@

is erroneous.  Although this preserves ‘configure’’s value of
‘CPPFLAGS’, the definition of ‘DATADIR’ will disappear if a user
attempts to override ‘CPPFLAGS’ from the ‘make’ command line.

     AM_CPPFLAGS = -DDATADIR=\"$(datadir)\"

is all that is needed here if no per-target flags are used.

   You should not add options to these user variables within ‘configure’
either, for the same reason.  Occasionally you need to modify these
variables to perform a test, but you should reset their values
afterwards.  In contrast, it is OK to modify the ‘AM_’ variables within
‘configure’ if you ‘AC_SUBST’ them, but it is rather rare that you need
to do this, unless you really want to change the default definitions of
the ‘AM_’ variables in all ‘Makefile’s.

   What we recommend is that you define extra flags in separate
variables.  For instance, you may write an Autoconf macro that computes
a set of warning options for the C compiler, and ‘AC_SUBST’ them in
‘WARNINGCFLAGS’; you may also have an Autoconf macro that determines
which compiler and which linker flags should be used to link with
library ‘libfoo’, and ‘AC_SUBST’ these in ‘LIBFOOCFLAGS’ and
‘LIBFOOLDFLAGS’.  Then, a ‘Makefile.am’ could use these variables as
follows:

     AM_CFLAGS = $(WARNINGCFLAGS)
     bin_PROGRAMS = prog1 prog2
     prog1_SOURCES = ...
     prog2_SOURCES = ...
     prog2_CFLAGS = $(LIBFOOCFLAGS) $(AM_CFLAGS)
     prog2_LDFLAGS = $(LIBFOOLDFLAGS)

   In this example both programs will be compiled with the flags
substituted into ‘$(WARNINGCFLAGS)’, and ‘prog2’ will additionally be
compiled with the flags required to link with ‘libfoo’.

   Note that listing ‘AM_CFLAGS’ in a per-target ‘CFLAGS’ variable is a
common idiom to ensure that ‘AM_CFLAGS’ applies to every target in a
‘Makefile.in’.

   Using variables like this gives you full control over the ordering of
the flags.  For instance, if there is a flag in $(WARNINGCFLAGS) that
you want to negate for a particular target, you can use something like
‘prog1_CFLAGS = $(AM_CFLAGS) -no-flag’.  If all of these flags had been
forcefully appended to ‘CFLAGS’, there would be no way to disable one
flag.  Yet another reason to leave user variables to users.

   Finally, we have avoided naming the variable of the example
‘LIBFOO_LDFLAGS’ (with an underscore) because that would cause Automake
to think that this is actually a per-target variable (like
‘mumble_LDFLAGS’) for some non-declared ‘LIBFOO’ target.

Other Variables
---------------

There are other variables in Automake that follow similar principles to
allow user options.  For instance, Texinfo rules (see Texinfo) use
‘MAKEINFOFLAGS’ and ‘AM_MAKEINFOFLAGS’.  Similarly, DejaGnu tests (see
DejaGnu Tests) use ‘RUNTESTDEFAULTFLAGS’ and ‘AM_RUNTESTDEFAULTFLAGS’.
The tags and ctags rules (see Tags) use ‘ETAGSFLAGS’,
‘AM_ETAGSFLAGS’, ‘CTAGSFLAGS’, and ‘AM_CTAGSFLAGS’.  Java rules (see
Java) use ‘JAVACFLAGS’ and ‘AM_JAVACFLAGS’.  None of these rules
support per-target flags (yet).

   To some extent, even ‘AM_MAKEFLAGS’ (see Subdirectories) obeys
this naming scheme.  The slight difference is that ‘MAKEFLAGS’ is passed
to sub-‘make’s implicitly by ‘make’ itself.

   ‘ARFLAGS’ (see A Library) is usually defined by Automake and has
neither an ‘AM_’ nor a per-target cousin.

   Finally you should not think that the existence of a per-target
variable implies the existence of an ‘AM_’ variable or of a user
variable.  For instance, the ‘mumble_LDADD’ per-target variable
overrides the makefile-wide ‘LDADD’ variable (which is not a user
variable), and ‘mumble_LIBADD’ exists only as a per-target variable.
See Program and Library Variables.

27.7 Why are object files sometimes renamed?
============================================

This happens when per-target compilation flags are used.  Object files
need to be renamed just in case they would clash with object files
compiled from the same sources, but with different flags.  Consider the
following example.

     bin_PROGRAMS = true false
     true_SOURCES = generic.c
     true_CPPFLAGS = -DEXIT_CODE=0
     false_SOURCES = generic.c
     false_CPPFLAGS = -DEXIT_CODE=1

Obviously the two programs are built from the same source, but it would
be bad if they shared the same object, because ‘generic.o’ cannot be
built with both ‘-DEXIT_CODE=0’ _and_ ‘-DEXIT_CODE=1’.  Therefore
‘automake’ outputs rules to build two different objects:
‘true-generic.o’ and ‘false-generic.o’.

   ‘automake’ doesn’t actually look whether source files are shared to
decide if it must rename objects.  It will just rename all objects of a
target as soon as it sees per-target compilation flags used.

   It’s OK to share object files when per-target compilation flags are
not used.  For instance, ‘true’ and ‘false’ will both use ‘version.o’ in
the following example.

     AM_CPPFLAGS = -DVERSION=1.0
     bin_PROGRAMS = true false
     true_SOURCES = true.c version.c
     false_SOURCES = false.c version.c

   Note that the renaming of objects is also affected by the
‘_SHORTNAME’ variable (see Program and Library Variables).

27.8 Per-Object Flags Emulation
===============================

     One of my source files needs to be compiled with different flags.  How
     do I do that?

   Automake supports per-program and per-library compilation flags (see
Program and Library Variables and Flag Variables Ordering).
With this you can define compilation flags that apply to
all files compiled for a target.  For instance, in

     bin_PROGRAMS = foo
     foo_SOURCES = foo.c foo.h bar.c bar.h main.c
     foo_CFLAGS = -some -flags

‘foo-foo.o’, ‘foo-bar.o’, and ‘foo-main.o’ will all be compiled with
‘-some -flags’.  (If you wonder about the names of these object files,
see Renamed Objects.)  Note that ‘foo_CFLAGS’ gives the flags to
use when compiling all the C sources of the _program_ ‘foo’; it has
nothing to do with ‘foo.c’ or ‘foo-foo.o’ specifically.

   What if ‘foo.c’ needs to be compiled into ‘foo.o’ using some specific
flags, that none of the other files requires?  Obviously per-program
flags are not directly applicable here.  Something like per-object flags
are expected, i.e., flags that would be used only when creating
‘foo-foo.o’.  Automake does not support that; however this is easy to
simulate using a library that contains only that object, and compiling
this library with per-library flags.

     bin_PROGRAMS = foo
     foo_SOURCES = bar.c bar.h main.c
     foo_CFLAGS = -some -flags
     foo_LDADD = libfoo.a
     noinst_LIBRARIES = libfoo.a
     libfoo_a_SOURCES = foo.c foo.h
     libfoo_a_CFLAGS = -some -other -flags

   Here ‘foo-bar.o’ and ‘foo-main.o’ will all be compiled with ‘-some
-flags’, while ‘libfoo_a-foo.o’ will be compiled using ‘-some -other
-flags’.  Eventually, all three objects will be linked to form ‘foo’.

   This trick can also be achieved using Libtool convenience libraries,
for instance ‘noinst_LTLIBRARIES = libfoo.la’ (see Libtool Convenience Libraries).

   Another tempting idea to implement per-object flags is to override
the compile rules ‘automake’ would output for these files.  Automake
will not define a rule for a target you have defined, so you could think
about defining the ‘foo-foo.o: foo.c’ rule yourself.  We recommend
against this, because this is error prone.  For instance, if you add
such a rule to the first example, it will break the day you decide to
remove ‘foo_CFLAGS’ (because ‘foo.c’ will then be compiled as ‘foo.o’
instead of ‘foo-foo.o’, see Renamed Objects).  Also in order to
support dependency tracking, the two ‘.o’/‘.obj’ extensions, and all the
other flags variables involved in a compilation, you will end up
modifying a copy of the rule previously output by ‘automake’ for this
file.  If a new release of Automake generates a different rule, your
copy will need to be updated by hand.

27.9 Handling Tools that Produce Many Outputs
=============================================

This section describes a ‘make’ idiom that can be used when a tool
produces multiple output files.  It is not specific to Automake and can
be used in ordinary ‘Makefile’s.

   Suppose we have a program called ‘foo’ that will read one file called
‘data.foo’ and produce two files named ‘data.c’ and ‘data.h’.  We want
to write a ‘Makefile’ rule that captures this one-to-two dependency.

   The naive rule is incorrect:

     # This is incorrect.
     data.c data.h: data.foo
             foo data.foo

What the above rule really says is that ‘data.c’ and ‘data.h’ each
depend on ‘data.foo’, and can each be built by running ‘foo data.foo’.
In other words it is equivalent to:

     # We do not want this.
     data.c: data.foo
             foo data.foo
     data.h: data.foo
             foo data.foo

which means that ‘foo’ can be run twice.  Usually it will not be run
twice, because ‘make’ implementations are smart enough to check for the
existence of the second file after the first one has been built; they
will therefore detect that it already exists.  However there are a few
situations where it can run twice anyway:

   • The most worrying case is when running a parallel ‘make’.  If
     ‘data.c’ and ‘data.h’ are built in parallel, two ‘foo data.foo’
     commands will run concurrently.  This is harmful.
   • Another case is when the dependency (here ‘data.foo’) is (or
     depends upon) a phony target.

   A solution that works with parallel ‘make’ but not with phony
dependencies is the following:

     data.c data.h: data.foo
             foo data.foo
     data.h: data.c

The above rules are equivalent to

     data.c: data.foo
             foo data.foo
     data.h: data.foo data.c
             foo data.foo

therefore a parallel ‘make’ will have to serialize the builds of
‘data.c’ and ‘data.h’, and will detect that the second is no longer
needed once the first is over.

   Using this pattern is probably enough for most cases.  However it
does not scale easily to more output files (in this scheme all output
files must be totally ordered by the dependency relation), so we will
explore a more complicated solution.

   Another idea is to write the following:

     # There is still a problem with this one.
     data.c: data.foo
             foo data.foo
     data.h: data.c

The idea is that ‘foo data.foo’ is run only when ‘data.c’ needs to be
updated, but we further state that ‘data.h’ depends upon ‘data.c’.  That
way, if ‘data.h’ is required and ‘data.foo’ is out of date, the
dependency on ‘data.c’ will trigger the build.

   This is almost perfect, but suppose we have built ‘data.h’ and
‘data.c’, and then we erase ‘data.h’.  Then, running ‘make data.h’ will
not rebuild ‘data.h’.  The above rules just state that ‘data.c’ must be
up-to-date with respect to ‘data.foo’, and this is already the case.

   What we need is a rule that forces a rebuild when ‘data.h’ is
missing.  Here it is:

     data.c: data.foo
             foo data.foo
     data.h: data.c
     ## Recover from the removal of $@
             @if test -f $@; then :; else \
               rm -f data.c; \
               $(MAKE) $(AM_MAKEFLAGS) data.c; \
             fi

   The above scheme can be extended to handle more outputs and more
inputs.  One of the outputs is selected to serve as a witness to the
successful completion of the command, it depends upon all inputs, and
all other outputs depend upon it.  For instance, if ‘foo’ should
additionally read ‘data.bar’ and also produce ‘data.w’ and ‘data.x’, we
would write:

     data.c: data.foo data.bar
             foo data.foo data.bar
     data.h data.w data.x: data.c
     ## Recover from the removal of $@
             @if test -f $@; then :; else \
               rm -f data.c; \
               $(MAKE) $(AM_MAKEFLAGS) data.c; \
             fi

   However there are now three minor problems in this setup.  One is
related to the timestamp ordering of ‘data.h’, ‘data.w’, ‘data.x’, and
‘data.c’.  Another one is a race condition if a parallel ‘make’ attempts
to run multiple instances of the recover block at once.  Finally, the
recursive rule breaks ‘make -n’ when run with GNU ‘make’ (as well as
some other ‘make’ implementations), as it may remove ‘data.h’ even when
it should not (see How the ‘MAKE’ Variable Works (make)).

   Let us deal with the first problem.  ‘foo’ outputs four files, but we
do not know in which order these files are created.  Suppose that
‘data.h’ is created before ‘data.c’.  Then we have a weird situation.
The next time ‘make’ is run, ‘data.h’ will appear older than ‘data.c’,
the second rule will be triggered, a shell will be started to execute
the ‘if...fi’ command, but actually it will just execute the ‘then’
branch, that is: nothing.  In other words, because the witness we
selected is not the first file created by ‘foo’, ‘make’ will start a
shell to do nothing each time it is run.

   A simple riposte is to fix the timestamps when this happens.

     data.c: data.foo data.bar
             foo data.foo data.bar
     data.h data.w data.x: data.c
             @if test -f $@; then \
               touch $@; \
             else \
     ## Recover from the removal of $@
               rm -f data.c; \
               $(MAKE) $(AM_MAKEFLAGS) data.c; \
             fi

   Another solution is to use a different and dedicated file as witness,
rather than using any of ‘foo’’s outputs.

     data.stamp: data.foo data.bar
             @rm -f data.tmp
             @touch data.tmp
             foo data.foo data.bar
             @mv -f data.tmp $@
     data.c data.h data.w data.x: data.stamp
     ## Recover from the removal of $@
             @if test -f $@; then :; else \
               rm -f data.stamp; \
               $(MAKE) $(AM_MAKEFLAGS) data.stamp; \
             fi

   ‘data.tmp’ is created before ‘foo’ is run, so it has a timestamp
older than output files output by ‘foo’.  It is then renamed to
‘data.stamp’ after ‘foo’ has run, because we do not want to update
‘data.stamp’ if ‘foo’ fails.

   This solution still suffers from the second problem: the race
condition in the recover rule.  If, after a successful build, a user
erases ‘data.c’ and ‘data.h’, and runs ‘make -j’, then ‘make’ may start
both recover rules in parallel.  If the two instances of the rule
execute ‘$(MAKE) $(AM_MAKEFLAGS) data.stamp’ concurrently the build is
likely to fail (for instance, the two rules will create ‘data.tmp’, but
only one can rename it).

   Admittedly, such a weird situation does not arise during ordinary
builds.  It occurs only when the build tree is mutilated.  Here ‘data.c’
and ‘data.h’ have been explicitly removed without also removing
‘data.stamp’ and the other output files.  ‘make clean; make’ will always
recover from these situations even with parallel makes, so you may
decide that the recover rule is solely to help non-parallel make users
and leave things as-is.  Fixing this requires some locking mechanism to
ensure only one instance of the recover rule rebuilds ‘data.stamp’.  One
could imagine something along the following lines.

     data.c data.h data.w data.x: data.stamp
     ## Recover from the removal of $@
             @if test -f $@; then :; else \
               trap 'rm -rf data.lock data.stamp' 1 2 13 15; \
     ## mkdir is a portable test-and-set
               if mkdir data.lock 2>/dev/null; then \
     ## This code is being executed by the first process.
                 rm -f data.stamp; \
                 $(MAKE) $(AM_MAKEFLAGS) data.stamp; \
                 result=$$?; rm -rf data.lock; exit $$result; \
               else \
     ## This code is being executed by the follower processes.
     ## Wait until the first process is done.
                 while test -d data.lock; do sleep 1; done; \
     ## Succeed if and only if the first process succeeded.
                 test -f data.stamp; \
               fi; \
             fi

   Using a dedicated witness, like ‘data.stamp’, is very handy when the
list of output files is not known beforehand.  As an illustration,
consider the following rules to compile many ‘*.el’ files into ‘*.elc’
files in a single command.  It does not matter how ‘ELFILES’ is defined
(as long as it is not empty: empty targets are not accepted by POSIX).

     ELFILES = one.el two.el three.el ...
     ELCFILES = $(ELFILES:=c)

     elc-stamp: $(ELFILES)
             @rm -f elc-temp
             @touch elc-temp
             $(elisp_comp) $(ELFILES)
             @mv -f elc-temp $@

     $(ELCFILES): elc-stamp
             @if test -f $@; then :; else \
     ## Recover from the removal of $@
               trap 'rm -rf elc-lock elc-stamp' 1 2 13 15; \
               if mkdir elc-lock 2>/dev/null; then \
     ## This code is being executed by the first process.
                 rm -f elc-stamp; \
                 $(MAKE) $(AM_MAKEFLAGS) elc-stamp; \
                 rmdir elc-lock; \
               else \
     ## This code is being executed by the follower processes.
     ## Wait until the first process is done.
                 while test -d elc-lock; do sleep 1; done; \
     ## Succeed if and only if the first process succeeded.
                 test -f elc-stamp; exit $$?; \
               fi; \
             fi

   These solutions all still suffer from the third problem, namely that
they break the promise that ‘make -n’ should not cause any actual
changes to the tree.  For those solutions that do not create lock files,
it is possible to split the recover rules into two separate recipe
commands, one of which does all work but the recursion, and the other
invokes the recursive ‘$(MAKE)’.  The solutions involving locking could
act upon the contents of the ‘MAKEFLAGS’ variable, but parsing that
portably is not easy (see The Make Macro MAKEFLAGS (autoconf)).  Here
is an example:

     ELFILES = one.el two.el three.el ...
     ELCFILES = $(ELFILES:=c)

     elc-stamp: $(ELFILES)
             @rm -f elc-temp
             @touch elc-temp
             $(elisp_comp) $(ELFILES)
             @mv -f elc-temp $@

     $(ELCFILES): elc-stamp
     ## Recover from the removal of $@
             @dry=; for f in x $$MAKEFLAGS; do \
               case $$f in \
                 *=*|--*);; \
                 *n*) dry=:;; \
               esac; \
             done; \
             if test -f $@; then :; else \
               $$dry trap 'rm -rf elc-lock elc-stamp' 1 2 13 15; \
               if $$dry mkdir elc-lock 2>/dev/null; then \
     ## This code is being executed by the first process.
                 $$dry rm -f elc-stamp; \
                 $(MAKE) $(AM_MAKEFLAGS) elc-stamp; \
                 $$dry rmdir elc-lock; \
               else \
     ## This code is being executed by the follower processes.
     ## Wait until the first process is done.
                 while test -d elc-lock && test -z "$$dry"; do \
                   sleep 1; \
                 done; \
     ## Succeed if and only if the first process succeeded.
                 $$dry test -f elc-stamp; exit $$?; \
               fi; \
             fi

   For completeness it should be noted that GNU ‘make’ is able to
express rules with multiple output files using pattern rules (see
Pattern Rule Examples (make)).  We do not discuss
pattern rules here because they are not portable, but they can be
convenient in packages that assume GNU ‘make’.

27.10 Installing to Hard-Coded Locations
========================================

     My package needs to install some configuration file.  I tried to use
     the following rule, but ‘make distcheck’ fails.  Why?

          # Do not do this.
          install-data-local:
                  $(INSTALL_DATA) $(srcdir)/afile $(DESTDIR)/etc/afile

     My package needs to populate the installation directory of another
     package at install-time.  I can easily compute that installation
     directory in ‘configure’, but if I install files therein,
     ‘make distcheck’ fails.  How else should I do it?

   These two setups share their symptoms: ‘make distcheck’ fails because
they are installing files to hard-coded paths.  In the latter case the
path is not really hard-coded in the package, but we can consider it to
be hard-coded in the system (or in whichever tool that supplies the
path).  As long as the path does not use any of the standard directory
variables (‘$(prefix)’, ‘$(bindir)’, ‘$(datadir)’, etc.), the effect
will be the same: user-installations are impossible.

   As a (non-root) user who wants to install a package, you usually have
no right to install anything in ‘/usr’ or ‘/usr/local’.  So you do
something like ‘./configure --prefix ~/usr’ to install a package in your
own ‘~/usr’ tree.

   If a package attempts to install something to some hard-coded path
(e.g., ‘/etc/afile’), regardless of this ‘--prefix’ setting, then the
installation will fail.  ‘make distcheck’ performs such a ‘--prefix’
installation, hence it will fail too.

   Now, there are some easy solutions.

   The above ‘install-data-local’ example for installing ‘/etc/afile’
would be better replaced by

     sysconf_DATA = afile

By default ‘sysconfdir’ will be ‘$(prefix)/etc’, because this is what
the GNU Standards require.  When such a package is installed on an FHS
compliant system, the installer will have to set ‘--sysconfdir=/etc’.
As the maintainer of the package you should not be concerned by such
site policies: use the appropriate standard directory variable to
install your files so that the installer can easily redefine these
variables to match their site conventions.

   Installing files that should be used by another package is slightly
more involved.  Let’s take an example and assume you want to install a
shared library that is a Python extension module.  If you ask Python
where to install the library, it will answer something like this:

     % python -c 'from distutils import sysconfig;
                  print sysconfig.get_python_lib(1,0)'
     /usr/lib/python2.5/site-packages

   If you indeed use this absolute path to install your shared library,
non-root users will not be able to install the package; hence distcheck
fails.

   Let’s do better.  The ‘sysconfig.get_python_lib()’ function actually
accepts a third argument that will replace Python’s installation prefix.

     % python -c 'from distutils import sysconfig;
                  print sysconfig.get_python_lib(1,0,"${exec_prefix}")'
     ${exec_prefix}/lib/python2.5/site-packages

   You can also use this new path.  If you do
   • root users can install your package with the same ‘--prefix’ as
     Python (you get the behavior of the previous attempt)

   • non-root users can install your package too; they will have the
     extension module in a place that is not searched by Python but they
     can work around this using environment variables (and if you
     installed scripts that use this shared library, it’s easy to tell
     Python where to look in the beginning of your script, so the script
     works in both cases).

   The ‘AM_PATH_PYTHON’ macro uses similar commands to define
‘$(pythondir)’ and ‘$(pyexecdir)’ (see Python).

   Of course not all tools are as advanced as Python regarding that
substitution of PREFIX.  So another strategy is to figure out the part
of the installation directory that must be preserved.  For instance,
here is how ‘AM_PATH_LISPDIR’ (see Emacs Lisp) computes
‘$(lispdir)’:

     $EMACS -batch -Q -eval '(while load-path
       (princ (concat (car load-path) "\n"))
       (setq load-path (cdr load-path)))' >conftest.out
     lispdir=`sed -n
       -e 's,/$,,'
       -e '/.*\/lib\/x*emacs\/site-lisp$/{
             s,.*/lib/\(x*emacs/site-lisp\)$,${libdir}/\1,;p;q;
           }'
       -e '/.*\/share\/x*emacs\/site-lisp$/{
             s,.*/share/\(x*emacs/site-lisp\),${datarootdir}/\1,;p;q;
           }'
       conftest.out`

   I.e., it just picks the first directory that looks like
‘*/lib/*emacs/site-lisp’ or ‘*/share/*emacs/site-lisp’ in the search
path of emacs, and then substitutes ‘${libdir}’ or ‘${datadir}’
appropriately.

   The emacs case looks complicated because it processes a list and
expects two possible layouts; otherwise it’s easy, and the benefits for
non-root users are really worth the extra ‘sed’ invocation.

27.11 Debugging Make Rules
==========================

The rules and dependency trees generated by ‘automake’ can get rather
complex, and leave the developer head-scratching when things don’t work
as expected.  Besides the debug options provided by the ‘make’ command
(see Options Summary (make)), here’s a couple of further hints for
debugging makefiles generated by ‘automake’ effectively:

   • If less verbose output has been enabled in the package with the use
     of silent rules (see Automake Silent Rules), you can use ‘make
     V=1’ to see the commands being executed.
   • ‘make -n’ can help show what would be done without actually doing
     it.  Note however, that this will _still execute_ commands prefixed
     with ‘+’, and, when using GNU ‘make’, commands that contain the
     strings ‘$(MAKE)’ or ‘${MAKE}’ (see Instead of Execution (make)).
     Typically, this is helpful to show what recursive
     rules would do, but it means that, in your own rules, you should
     not mix such recursion with actions that change any files.(1)
     Furthermore, note that GNU ‘make’ will update prerequisites for the
     ‘Makefile’ file itself even with ‘-n’ (see Remaking Makefiles (make)).
   • ‘make SHELL="/bin/bash -vx"’ can help debug complex rules.  See
     The Make Macro SHELL (autoconf), for some portability quirks
     associated with this construct.
   • ‘echo 'print: ; @echo "$(VAR)"' | make -f Makefile -f - print’ can
     be handy to examine the expanded value of variables.  You may need
     to use a target other than ‘print’ if that is already used or a
     file with that name exists.
   • <http://bashdb.sourceforge.net/remake/> provides a modified GNU
     ‘make’ command called ‘remake’ that copes with complex GNU
     ‘make’-specific Makefiles and allows tracing execution, examining
     variables, and calling rules interactively, much like a debugger.

   ---------- Footnotes ----------

   (1) Automake’s ‘dist’ and ‘distcheck’ rules had a bug in this regard
in that they created directories even with ‘-n’, but this has been fixed
in Automake 1.11.

27.12 Reporting Bugs
====================

Most nontrivial software has bugs.  Automake is no exception.  Although
we cannot promise we can or will fix a bug, and we might not even agree
that it is a bug, we want to hear about problems you encounter.  Often
we agree they are bugs and want to fix them.

   To make it possible for us to fix a bug, please report it.  In order
to do so effectively, it helps to know when and how to do it.

   Before reporting a bug, it is a good idea to see if it is already
known.  You can look at the GNU Bug Tracker (https://debbugs.gnu.org/)
and the bug-automake mailing list archives
(https://lists.gnu.org/archive/html/bug-automake/) for previous bug
reports.  We previously used a Gnats database
(http://sourceware.org/cgi-bin/gnatsweb.pl?database=automake) for bug
tracking, so some bugs might have been reported there already.  Please
do not use it for new bug reports, however.

   If the bug is not already known, it should be reported.  It is very
important to report bugs in a way that is useful and efficient.  For
this, please familiarize yourself with How to Report Bugs Effectively
(http://www.chiark.greenend.org.uk/~sgtatham/bugs.html) and How to Ask
Questions the Smart Way
(http://catb.org/~esr/faqs/smart-questions.html).  This helps you and
developers to save time, which can then be spent on fixing more bugs and
implementing more features.

   For a bug report, a feature request or other suggestions, please send
email to <bug-automake@gnu.org>.  This will then open a new bug in the
bug tracker (https://debbugs.gnu.org/automake).  Be sure to include the
versions of Autoconf and Automake that you use.  Ideally, post a minimal
‘Makefile.am’ and ‘configure.ac’ that reproduces the problem you
encounter.  If you have encountered test suite failures, please attach
the ‘test-suite.log’ file.

Appendix A Copying This Manual
******************************

A.1 GNU Free Documentation License
==================================

                     Version 1.3, 3 November 2008

     Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
     <https://fsf.org/>

     Everyone is permitted to copy and distribute verbatim copies
     of this license document, but changing it is not allowed.

  0. PREAMBLE

     The purpose of this License is to make a manual, textbook, or other
     functional and useful document “free” in the sense of freedom: to
     assure everyone the effective freedom to copy and redistribute it,
     with or without modifying it, either commercially or
     noncommercially.  Secondarily, this License preserves for the
     author and publisher a way to get credit for their work, while not
     being considered responsible for modifications made by others.

     This License is a kind of “copyleft”, which means that derivative
     works of the document must themselves be free in the same sense.
     It complements the GNU General Public License, which is a copyleft
     license designed for free software.

     We have designed this License in order to use it for manuals for
     free software, because free software needs free documentation: a
     free program should come with manuals providing the same freedoms
     that the software does.  But this License is not limited to
     software manuals; it can be used for any textual work, regardless
     of subject matter or whether it is published as a printed book.  We
     recommend this License principally for works whose purpose is
     instruction or reference.

  1. APPLICABILITY AND DEFINITIONS

     This License applies to any manual or other work, in any medium,
     that contains a notice placed by the copyright holder saying it can
     be distributed under the terms of this License.  Such a notice
     grants a world-wide, royalty-free license, unlimited in duration,
     to use that work under the conditions stated herein.  The
     “Document”, below, refers to any such manual or work.  Any member
     of the public is a licensee, and is addressed as “you”.  You accept
     the license if you copy, modify or distribute the work in a way
     requiring permission under copyright law.

     A “Modified Version” of the Document means any work containing the
     Document or a portion of it, either copied verbatim, or with
     modifications and/or translated into another language.

     A “Secondary Section” is a named appendix or a front-matter section
     of the Document that deals exclusively with the relationship of the
     publishers or authors of the Document to the Document’s overall
     subject (or to related matters) and contains nothing that could
     fall directly within that overall subject.  (Thus, if the Document
     is in part a textbook of mathematics, a Secondary Section may not
     explain any mathematics.)  The relationship could be a matter of
     historical connection with the subject or with related matters, or
     of legal, commercial, philosophical, ethical or political position
     regarding them.

     The “Invariant Sections” are certain Secondary Sections whose
     titles are designated, as being those of Invariant Sections, in the
     notice that says that the Document is released under this License.
     If a section does not fit the above definition of Secondary then it
     is not allowed to be designated as Invariant.  The Document may
     contain zero Invariant Sections.  If the Document does not identify
     any Invariant Sections then there are none.

     The “Cover Texts” are certain short passages of text that are
     listed, as Front-Cover Texts or Back-Cover Texts, in the notice
     that says that the Document is released under this License.  A
     Front-Cover Text may be at most 5 words, and a Back-Cover Text may
     be at most 25 words.

     A “Transparent” copy of the Document means a machine-readable copy,
     represented in a format whose specification is available to the
     general public, that is suitable for revising the document
     straightforwardly with generic text editors or (for images composed
     of pixels) generic paint programs or (for drawings) some widely
     available drawing editor, and that is suitable for input to text
     formatters or for automatic translation to a variety of formats
     suitable for input to text formatters.  A copy made in an otherwise
     Transparent file format whose markup, or absence of markup, has
     been arranged to thwart or discourage subsequent modification by
     readers is not Transparent.  An image format is not Transparent if
     used for any substantial amount of text.  A copy that is not
     “Transparent” is called “Opaque”.

     Examples of suitable formats for Transparent copies include plain
     ASCII without markup, Texinfo input format, LaTeX input format,
     SGML or XML using a publicly available DTD, and standard-conforming
     simple HTML, PostScript or PDF designed for human modification.
     Examples of transparent image formats include PNG, XCF and JPG.
     Opaque formats include proprietary formats that can be read and
     edited only by proprietary word processors, SGML or XML for which
     the DTD and/or processing tools are not generally available, and
     the machine-generated HTML, PostScript or PDF produced by some word
     processors for output purposes only.

     The “Title Page” means, for a printed book, the title page itself,
     plus such following pages as are needed to hold, legibly, the
     material this License requires to appear in the title page.  For
     works in formats which do not have any title page as such, “Title
     Page” means the text near the most prominent appearance of the
     work’s title, preceding the beginning of the body of the text.

     The “publisher” means any person or entity that distributes copies
     of the Document to the public.

     A section “Entitled XYZ” means a named subunit of the Document
     whose title either is precisely XYZ or contains XYZ in parentheses
     following text that translates XYZ in another language.  (Here XYZ
     stands for a specific section name mentioned below, such as
     “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.)
     To “Preserve the Title” of such a section when you modify the
     Document means that it remains a section “Entitled XYZ” according
     to this definition.

     The Document may include Warranty Disclaimers next to the notice
     which states that this License applies to the Document.  These
     Warranty Disclaimers are considered to be included by reference in
     this License, but only as regards disclaiming warranties: any other
     implication that these Warranty Disclaimers may have is void and
     has no effect on the meaning of this License.

  2. VERBATIM COPYING

     You may copy and distribute the Document in any medium, either
     commercially or noncommercially, provided that this License, the
     copyright notices, and the license notice saying this License
     applies to the Document are reproduced in all copies, and that you
     add no other conditions whatsoever to those of this License.  You
     may not use technical measures to obstruct or control the reading
     or further copying of the copies you make or distribute.  However,
     you may accept compensation in exchange for copies.  If you
     distribute a large enough number of copies you must also follow the
     conditions in section 3.

     You may also lend copies, under the same conditions stated above,
     and you may publicly display copies.

  3. COPYING IN QUANTITY

     If you publish printed copies (or copies in media that commonly
     have printed covers) of the Document, numbering more than 100, and
     the Document’s license notice requires Cover Texts, you must
     enclose the copies in covers that carry, clearly and legibly, all
     these Cover Texts: Front-Cover Texts on the front cover, and
     Back-Cover Texts on the back cover.  Both covers must also clearly
     and legibly identify you as the publisher of these copies.  The
     front cover must present the full title with all words of the title
     equally prominent and visible.  You may add other material on the
     covers in addition.  Copying with changes limited to the covers, as
     long as they preserve the title of the Document and satisfy these
     conditions, can be treated as verbatim copying in other respects.

     If the required texts for either cover are too voluminous to fit
     legibly, you should put the first ones listed (as many as fit
     reasonably) on the actual cover, and continue the rest onto
     adjacent pages.

     If you publish or distribute Opaque copies of the Document
     numbering more than 100, you must either include a machine-readable
     Transparent copy along with each Opaque copy, or state in or with
     each Opaque copy a computer-network location from which the general
     network-using public has access to download using public-standard
     network protocols a complete Transparent copy of the Document, free
     of added material.  If you use the latter option, you must take
     reasonably prudent steps, when you begin distribution of Opaque
     copies in quantity, to ensure that this Transparent copy will
     remain thus accessible at the stated location until at least one
     year after the last time you distribute an Opaque copy (directly or
     through your agents or retailers) of that edition to the public.

     It is requested, but not required, that you contact the authors of
     the Document well before redistributing any large number of copies,
     to give them a chance to provide you with an updated version of the
     Document.

  4. MODIFICATIONS

     You may copy and distribute a Modified Version of the Document
     under the conditions of sections 2 and 3 above, provided that you
     release the Modified Version under precisely this License, with the
     Modified Version filling the role of the Document, thus licensing
     distribution and modification of the Modified Version to whoever
     possesses a copy of it.  In addition, you must do these things in
     the Modified Version:

       A. Use in the Title Page (and on the covers, if any) a title
          distinct from that of the Document, and from those of previous
          versions (which should, if there were any, be listed in the
          History section of the Document).  You may use the same title
          as a previous version if the original publisher of that
          version gives permission.

       B. List on the Title Page, as authors, one or more persons or
          entities responsible for authorship of the modifications in
          the Modified Version, together with at least five of the
          principal authors of the Document (all of its principal
          authors, if it has fewer than five), unless they release you
          from this requirement.

       C. State on the Title page the name of the publisher of the
          Modified Version, as the publisher.

       D. Preserve all the copyright notices of the Document.

       E. Add an appropriate copyright notice for your modifications
          adjacent to the other copyright notices.

       F. Include, immediately after the copyright notices, a license
          notice giving the public permission to use the Modified
          Version under the terms of this License, in the form shown in
          the Addendum below.

       G. Preserve in that license notice the full lists of Invariant
          Sections and required Cover Texts given in the Document’s
          license notice.

       H. Include an unaltered copy of this License.

       I. Preserve the section Entitled “History”, Preserve its Title,
          and add to it an item stating at least the title, year, new
          authors, and publisher of the Modified Version as given on the
          Title Page.  If there is no section Entitled “History” in the
          Document, create one stating the title, year, authors, and
          publisher of the Document as given on its Title Page, then add
          an item describing the Modified Version as stated in the
          previous sentence.

       J. Preserve the network location, if any, given in the Document
          for public access to a Transparent copy of the Document, and
          likewise the network locations given in the Document for
          previous versions it was based on.  These may be placed in the
          “History” section.  You may omit a network location for a work
          that was published at least four years before the Document
          itself, or if the original publisher of the version it refers
          to gives permission.

       K. For any section Entitled “Acknowledgements” or “Dedications”,
          Preserve the Title of the section, and preserve in the section
          all the substance and tone of each of the contributor
          acknowledgements and/or dedications given therein.

       L. Preserve all the Invariant Sections of the Document, unaltered
          in their text and in their titles.  Section numbers or the
          equivalent are not considered part of the section titles.

       M. Delete any section Entitled “Endorsements”.  Such a section
          may not be included in the Modified Version.

       N. Do not retitle any existing section to be Entitled
          “Endorsements” or to conflict in title with any Invariant
          Section.

       O. Preserve any Warranty Disclaimers.

     If the Modified Version includes new front-matter sections or
     appendices that qualify as Secondary Sections and contain no
     material copied from the Document, you may at your option designate
     some or all of these sections as invariant.  To do this, add their
     titles to the list of Invariant Sections in the Modified Version’s
     license notice.  These titles must be distinct from any other
     section titles.

     You may add a section Entitled “Endorsements”, provided it contains
     nothing but endorsements of your Modified Version by various
     parties—for example, statements of peer review or that the text has
     been approved by an organization as the authoritative definition of
     a standard.

     You may add a passage of up to five words as a Front-Cover Text,
     and a passage of up to 25 words as a Back-Cover Text, to the end of
     the list of Cover Texts in the Modified Version.  Only one passage
     of Front-Cover Text and one of Back-Cover Text may be added by (or
     through arrangements made by) any one entity.  If the Document
     already includes a cover text for the same cover, previously added
     by you or by arrangement made by the same entity you are acting on
     behalf of, you may not add another; but you may replace the old
     one, on explicit permission from the previous publisher that added
     the old one.

     The author(s) and publisher(s) of the Document do not by this
     License give permission to use their names for publicity for or to
     assert or imply endorsement of any Modified Version.

  5. COMBINING DOCUMENTS

     You may combine the Document with other documents released under
     this License, under the terms defined in section 4 above for
     modified versions, provided that you include in the combination all
     of the Invariant Sections of all of the original documents,
     unmodified, and list them all as Invariant Sections of your
     combined work in its license notice, and that you preserve all
     their Warranty Disclaimers.

     The combined work need only contain one copy of this License, and
     multiple identical Invariant Sections may be replaced with a single
     copy.  If there are multiple Invariant Sections with the same name
     but different contents, make the title of each such section unique
     by adding at the end of it, in parentheses, the name of the
     original author or publisher of that section if known, or else a
     unique number.  Make the same adjustment to the section titles in
     the list of Invariant Sections in the license notice of the
     combined work.

     In the combination, you must combine any sections Entitled
     “History” in the various original documents, forming one section
     Entitled “History”; likewise combine any sections Entitled
     “Acknowledgements”, and any sections Entitled “Dedications”.  You
     must delete all sections Entitled “Endorsements.”

  6. COLLECTIONS OF DOCUMENTS

     You may make a collection consisting of the Document and other
     documents released under this License, and replace the individual
     copies of this License in the various documents with a single copy
     that is included in the collection, provided that you follow the
     rules of this License for verbatim copying of each of the documents
     in all other respects.

     You may extract a single document from such a collection, and
     distribute it individually under this License, provided you insert
     a copy of this License into the extracted document, and follow this
     License in all other respects regarding verbatim copying of that
     document.

  7. AGGREGATION WITH INDEPENDENT WORKS

     A compilation of the Document or its derivatives with other
     separate and independent documents or works, in or on a volume of a
     storage or distribution medium, is called an “aggregate” if the
     copyright resulting from the compilation is not used to limit the
     legal rights of the compilation’s users beyond what the individual
     works permit.  When the Document is included in an aggregate, this
     License does not apply to the other works in the aggregate which
     are not themselves derivative works of the Document.

     If the Cover Text requirement of section 3 is applicable to these
     copies of the Document, then if the Document is less than one half
     of the entire aggregate, the Document’s Cover Texts may be placed
     on covers that bracket the Document within the aggregate, or the
     electronic equivalent of covers if the Document is in electronic
     form.  Otherwise they must appear on printed covers that bracket
     the whole aggregate.

  8. TRANSLATION

     Translation is considered a kind of modification, so you may
     distribute translations of the Document under the terms of section
     4.  Replacing Invariant Sections with translations requires special
     permission from their copyright holders, but you may include
     translations of some or all Invariant Sections in addition to the
     original versions of these Invariant Sections.  You may include a
     translation of this License, and all the license notices in the
     Document, and any Warranty Disclaimers, provided that you also
     include the original English version of this License and the
     original versions of those notices and disclaimers.  In case of a
     disagreement between the translation and the original version of
     this License or a notice or disclaimer, the original version will
     prevail.

     If a section in the Document is Entitled “Acknowledgements”,
     “Dedications”, or “History”, the requirement (section 4) to
     Preserve its Title (section 1) will typically require changing the
     actual title.

  9. TERMINATION

     You may not copy, modify, sublicense, or distribute the Document
     except as expressly provided under this License.  Any attempt
     otherwise to copy, modify, sublicense, or distribute it is void,
     and will automatically terminate your rights under this License.

     However, if you cease all violation of this License, then your
     license from a particular copyright holder is reinstated (a)
     provisionally, unless and until the copyright holder explicitly and
     finally terminates your license, and (b) permanently, if the
     copyright holder fails to notify you of the violation by some
     reasonable means prior to 60 days after the cessation.

     Moreover, your license from a particular copyright holder is
     reinstated permanently if the copyright holder notifies you of the
     violation by some reasonable means, this is the first time you have
     received notice of violation of this License (for any work) from
     that copyright holder, and you cure the violation prior to 30 days
     after your receipt of the notice.

     Termination of your rights under this section does not terminate
     the licenses of parties who have received copies or rights from you
     under this License.  If your rights have been terminated and not
     permanently reinstated, receipt of a copy of some or all of the
     same material does not give you any rights to use it.

  10. FUTURE REVISIONS OF THIS LICENSE

     The Free Software Foundation may publish new, revised versions of
     the GNU Free Documentation License from time to time.  Such new
     versions will be similar in spirit to the present version, but may
     differ in detail to address new problems or concerns.  See
     <https://www.gnu.org/copyleft/>.

     Each version of the License is given a distinguishing version
     number.  If the Document specifies that a particular numbered
     version of this License “or any later version” applies to it, you
     have the option of following the terms and conditions either of
     that specified version or of any later version that has been
     published (not as a draft) by the Free Software Foundation.  If the
     Document does not specify a version number of this License, you may
     choose any version ever published (not as a draft) by the Free
     Software Foundation.  If the Document specifies that a proxy can
     decide which future versions of this License can be used, that
     proxy’s public statement of acceptance of a version permanently
     authorizes you to choose that version for the Document.

  11. RELICENSING

     “Massive Multiauthor Collaboration Site” (or “MMC Site”) means any
     World Wide Web server that publishes copyrightable works and also
     provides prominent facilities for anybody to edit those works.  A
     public wiki that anybody can edit is an example of such a server.
     A “Massive Multiauthor Collaboration” (or “MMC”) contained in the
     site means any set of copyrightable works thus published on the MMC
     site.

     “CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0
     license published by Creative Commons Corporation, a not-for-profit
     corporation with a principal place of business in San Francisco,
     California, as well as future copyleft versions of that license
     published by that same organization.

     “Incorporate” means to publish or republish a Document, in whole or
     in part, as part of another Document.

     An MMC is “eligible for relicensing” if it is licensed under this
     License, and if all works that were first published under this
     License somewhere other than this MMC, and subsequently
     incorporated in whole or in part into the MMC, (1) had no cover
     texts or invariant sections, and (2) were thus incorporated prior
     to November 1, 2008.

     The operator of an MMC Site may republish an MMC contained in the
     site under CC-BY-SA on the same site at any time before August 1,
     2009, provided the MMC is eligible for relicensing.

ADDENDUM: How to use this License for your documents
====================================================

To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and license
notices just after the title page:

       Copyright (C)  YEAR  YOUR NAME.
       Permission is granted to copy, distribute and/or modify this document
       under the terms of the GNU Free Documentation License, Version 1.3
       or any later version published by the Free Software Foundation;
       with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
       Texts.  A copy of the license is included in the section entitled ``GNU
       Free Documentation License''.

   If you have Invariant Sections, Front-Cover Texts and Back-Cover
Texts, replace the “with...Texts.” line with this:

         with the Invariant Sections being LIST THEIR TITLES, with
         the Front-Cover Texts being LIST, and with the Back-Cover Texts
         being LIST.

   If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.

   If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of free
software license, such as the GNU General Public License, to permit
their use in free software.

Appendix B Indices
******************