max80_fw/tools/gnusrc/automake/doc/automake.info-2

This is automake.info, produced by makeinfo version 6.1 from
automake.texi.

This manual is for GNU Automake (version 1.15.1, 17 June 2017), a
program that creates GNU standards-compliant Makefiles from template
files.

   Copyright © 1995-2017 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.”

INFO-DIR-SECTION Software development
START-INFO-DIR-ENTRY
* Automake: (automake).         Making GNU standards-compliant Makefiles.
END-INFO-DIR-ENTRY

INFO-DIR-SECTION Individual utilities
START-INFO-DIR-ENTRY
* aclocal-invocation: (automake)aclocal Invocation.   Generating aclocal.m4.
* automake-invocation: (automake)automake Invocation. Generating Makefile.in.
END-INFO-DIR-ENTRY


File: automake.info,  Node: Staged Installs,  Next: Install Rules for the User,  Prev: Extending Installation,  Up: Install

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
(*note 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’.

   *Note (standards)Makefile Conventions::, for another usage example.


File: automake.info,  Node: Install Rules for the User,  Prev: Staged Installs,  Up: Install

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.


File: automake.info,  Node: Clean,  Next: Dist,  Prev: Install,  Up: Top

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

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

   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
(*note 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’.


File: automake.info,  Node: Dist,  Next: Tests,  Prev: Clean,  Up: Top

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

* Menu:

* Basics of Distribution::      Files distributed by default
* Fine-grained Distribution Control::  ‘dist_’ and ‘nodist_’ prefixes
* The dist Hook::               A target for last-minute distribution changes
* Checking the Distribution::   ‘make distcheck’ explained
* The Types of Distributions::  A variety of formats and compression methods


File: automake.info,  Node: Basics of Distribution,  Next: Fine-grained Distribution Control,  Up: Dist

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 *note 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; *note The dist Hook::.

   If you define ‘SUBDIRS’, Automake will recursively include the
subdirectories in the distribution.  If ‘SUBDIRS’ is defined
conditionally (*note 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 (*note Conditional Subdirectories::).


File: automake.info,  Node: Fine-grained Distribution Control,  Next: The dist Hook,  Prev: Basics of Distribution,  Up: Dist

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


File: automake.info,  Node: The dist Hook,  Next: Checking the Distribution,  Prev: Fine-grained Distribution Control,  Up: Dist

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
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’ (*note
Subpackages::), then ‘$(distdir)’ and ‘$(top_distdir)’ are relative to
the package where ‘make dist’ was run, not to any sub-packages involved.


File: automake.info,  Node: Checking the Distribution,  Next: The Types of Distributions,  Prev: The dist Hook,  Up: Dist

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 (*note 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 tries 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 reply 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 nothing 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 its 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 (*note 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 build 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 (*note 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:
             @:


File: automake.info,  Node: The Types of Distributions,  Prev: Checking the Distribution,  Up: Dist

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.

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


File: automake.info,  Node: Tests,  Next: Rebuilding,  Prev: Dist,  Up: Top

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

* Menu:

* Generalities about Testing::  Concepts and terminology about testing
* Simple Tests::                Listing test scripts in ‘TESTS’
* Custom Test Drivers::         Writing and using custom test drivers
* Using the TAP test protocol:: Integrating test scripts that use the TAP protocol
* DejaGnu Tests::               Interfacing with the ‘dejagnu’ testing framework
* Install Tests::               Running tests on installed packages


File: automake.info,  Node: Generalities about Testing,  Next: Simple Tests,  Up: Tests

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 report or register 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 an 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.  An _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).


File: automake.info,  Node: Simple Tests,  Next: Custom Test Drivers,  Prev: Generalities about Testing,  Up: Tests

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

* Menu:

* Scripts-based Testsuites::    Automake-specific concepts and terminology
* Serial Test Harness::         Older (and discouraged) serial test harness
* Parallel Test Harness::       Generic concurrent test harness


File: automake.info,  Node: Scripts-based Testsuites,  Next: Serial Test Harness,  Up: 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”, *note 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 (*note Using the TAP
test protocol::) or custom (*note 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, *note 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 an 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 not 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 *note Generalities about Testing::) are ‘PASS’, ‘FAIL’, ‘SKIP’,
‘XFAIL’, ‘XPASS’ and ‘ERROR’.  Here is an example of output from an
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 (*note (autoconf)Parallel
make::), 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 (*note Build Directories: (autoconf)Build Directories.), and
in particular for the ‘distcheck’ rule (*note 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 (*note
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.


File: automake.info,  Node: Serial Test Harness,  Next: Parallel Test Harness,  Prev: Scripts-based Testsuites,  Up: Simple Tests

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 (*note Parallel Test Harness::).
Still, there are _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 (*note Parallel
Test Harness::).

   Another, less serious limit 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.


File: automake.info,  Node: Parallel Test Harness,  Prev: Serial Test Harness,  Up: Simple Tests

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”, *note 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 (*note 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 (*note Serial Test Harness::), the
‘AM_TESTS_ENVIRONMENT’ and ‘TESTS_ENVIRONMENT’ variables _cannot_ be use
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 long time to execute.  Luckily, this problem
     can easily be avoided by overriding also ‘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, *note 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 (*note (autoconf)Make
Target Lookup::, 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.


File: automake.info,  Node: Custom Test Drivers,  Next: Using the TAP test protocol,  Prev: Simple Tests,  Up: Tests

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

* Menu:

* Overview of Custom Test Drivers Support::
* Declaring Custom Test Drivers::
* API for Custom Test Drivers::


File: automake.info,  Node: Overview of Custom Test Drivers Support,  Next: Declaring Custom Test Drivers,  Up: 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 (*note 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
interpreter 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.


File: automake.info,  Node: Declaring Custom Test Drivers,  Next: API for Custom Test Drivers,  Prev: Overview of Custom Test Drivers Support,  Up: Custom 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’.


File: automake.info,  Node: API for Custom Test Drivers,  Prev: Declaring Custom Test Drivers,  Up: Custom Test Drivers

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 details as
possible with the parallel test harness and its default driver.

* Menu:

* Command-line arguments for test drivers::
* Log files generation and test results recording::
* Testsuite progress output::


File: automake.info,  Node: Command-line arguments for test drivers,  Next: Log files generation and test results recording,  Up: API for Custom Test Drivers

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 (*note Testsuite progress
     output::).
‘--log-file=PATH.log’
     The ‘.log’ file the test driver must create (*note 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 (*note 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 (*note 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.


File: automake.info,  Node: Log files generation and test results recording,  Next: Testsuite progress output,  Prev: Command-line arguments for test drivers,  Up: API for Custom Test Drivers

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 run 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 run 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 in the
global log file ‘test-suite.log’.


File: automake.info,  Node: Testsuite progress output,  Prev: Log files generation and test results recording,  Up: API for Custom Test Drivers

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.


File: automake.info,  Node: Using the TAP test protocol,  Next: DejaGnu Tests,  Prev: Custom Test Drivers,  Up: Tests

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

* Menu:

* Introduction to TAP::
* Use TAP with the Automake test harness::
* Incompatibilities with other TAP parsers and drivers::
* Links and external resources on TAP::


File: automake.info,  Node: Introduction to TAP,  Next: Use TAP with the Automake test harness,  Up: 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 (*note Testsuite progress on console::), and will use the ‘.trs’
files (*note Basics of test metadata::) to store the test results and
related metadata.  Apart from that, it will try to remain as much
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, also other
important third-party packages, such as ‘git’ (http://git-scm.com/), use
TAP in their testsuite.


File: automake.info,  Node: Use TAP with the Automake test harness,  Next: Incompatibilities with other TAP parsers and drivers,  Prev: Introduction to TAP,  Up: Using the TAP test protocol

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 (*note
Command-line arguments for test drivers::), the ‘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 diagnostic (i.e., lines
     beginning with the ‘#’ character) in the testsuite progress output
     too; by default, TAP diagnostic is 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 diagnostic 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 diagnostic: such an issue can be solved by
     redefining the string that activates TAP diagnostic 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


File: automake.info,  Node: Incompatibilities with other TAP parsers and drivers,  Next: Links and external resources on TAP,  Prev: Use TAP with the Automake test harness,  Up: Using the TAP test protocol

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 minors 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 to modify the
     string that introduces TAP diagnostic from the default value of
     “‘#’”.  The standard TAP protocol has currently 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.


File: automake.info,  Node: Links and external resources on TAP,  Prev: Incompatibilities with other TAP parsers and drivers,  Up: Using the TAP test protocol

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.


File: automake.info,  Node: DejaGnu Tests,  Next: Install Tests,  Prev: Using the TAP test protocol,  Up: Tests

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

If ‘dejagnu’ (ftp://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” (*note 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 *note
(dejagnu)Top::.


File: automake.info,  Node: Install Tests,  Prev: DejaGnu Tests,  Up: Tests

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.


File: automake.info,  Node: Rebuilding,  Next: Options,  Prev: Tests,  Up: Top

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 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 *note autom4te cache:
(autoconf)Autom4te Cache. 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.


File: automake.info,  Node: Options,  Next: Miscellaneous,  Prev: Rebuilding,  Up: Top

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

* Menu:

* Options generalities::        Semantics of Automake option
* List of Automake options::    A comprehensive list of Automake options


File: automake.info,  Node: Options generalities,  Next: List of Automake options,  Up: Options

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, an 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’.


File: automake.info,  Node: List of Automake options,  Prev: Options generalities,  Up: Options

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.  *Note 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-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 (*note 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 (*note
     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’ (*note
     Serial Test Harness::, for more information).

‘parallel-tests’
     Enable test suite harness for ‘TESTS’ that can run tests in
     parallel (*note 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’ and ‘dist-tarZ’ options in
     use.)

     These options must be passed as arguments to ‘AM_INIT_AUTOMAKE’
     (*note 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 other 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 believed to be old enough to be portable.  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.  However you may run against broken tar
     implementations that incorrectly handle file names longer than 99
     characters (please report them to <bug-automake@gnu.org> so we can
     document this accurately).

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

     *Note Controlling the Archive Format: (tar)Formats, 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 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
     (*note 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’.  *Note Macros::.


File: automake.info,  Node: Miscellaneous,  Next: Include,  Prev: Options,  Up: Top

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

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

* Menu:

* Tags::                        Interfacing to cscope, etags and mkid
* Suffixes::                    Handling new file extensions


File: automake.info,  Node: Tags,  Next: Suffixes,  Up: Miscellaneous

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 *note VPATH rewrites:
(autoconf)Automatic Rule Rewriting.).

   Finally, Automake also emits rules to support the GNU Global Tags
program (http://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’.


File: automake.info,  Node: Suffixes,  Prev: Tags,  Up: Miscellaneous

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.


File: automake.info,  Node: Include,  Next: Conditionals,  Prev: Miscellaneous,  Up: Top

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 (*note
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


File: automake.info,  Node: Conditionals,  Next: Silencing Make,  Prev: Include,  Up: Top

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

Automake supports a simple type of conditionals.

   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.

* Menu:

* Usage of Conditionals::       Declaring conditional content
* Limits of Conditionals::      Enclosing complete statements


File: automake.info,  Node: Usage of Conditionals,  Next: Limits of Conditionals,  Up: Conditionals

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

Before using a conditional, you must define it by using ‘AM_CONDITIONAL’
in the ‘configure.ac’ file (*note 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’ that 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’
(*note 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
(*note (autoconf)M4 Quotation::).

   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])])


File: automake.info,  Node: Limits of Conditionals,  Prev: Usage of Conditionals,  Up: Conditionals

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 (*note Conditional
Subdirectories::, *note Conditional Sources::, *note Conditional
Programs::, *note Conditional Libtool Libraries::, *note Conditional
Libtool Sources::).


File: automake.info,  Node: Silencing Make,  Next: Gnits,  Prev: Conditionals,  Up: Top

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

* Menu:

* Make verbosity::              Make is verbose by default
* Tricks For Silencing Make::   Standard and generic ways to silence make
* Automake Silent Rules::       How Automake can help in silencing make


File: automake.info,  Node: Make verbosity,  Next: Tricks For Silencing Make,  Up: 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>.


File: automake.info,  Node: Tricks For Silencing Make,  Next: Automake Silent Rules,  Prev: Make verbosity,  Up: Silencing Make

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 (*note 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 much 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
     semantic of the ‘make’ calls — things these which 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.


File: automake.info,  Node: Automake Silent Rules,  Prev: Tricks For Silencing Make,  Up: Silencing Make

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


File: automake.info,  Node: Gnits,  Next: Not Enough,  Prev: Silencing Make,  Up: Top

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,
     <http://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 (*note 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.


File: automake.info,  Node: Not Enough,  Next: Distributing,  Prev: Gnits,  Up: Top

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.

* Menu:

* Extending::                   Adding new rules or overriding existing ones.
* Third-Party Makefiles::       Integrating Non-Automake ‘Makefile’s.


File: automake.info,  Node: Extending,  Next: Third-Party Makefiles,  Up: Not Enough

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 (*note 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’ (*note 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 (*note 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’ (*note Particular Program Checks:
(autoconf)Particular Programs.) 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 (*note 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 consequently.


File: automake.info,  Node: Third-Party Makefiles,  Prev: Extending,  Up: Not Enough

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 (*note Options::) is used.

     The variables ‘$(top_distdir)’ and ‘$(distdir)’ (*note 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 (*note Install::).

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

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

‘check’
‘installcheck’
     Check the package (*note Tests::).

‘mostlyclean’
‘clean’
‘distclean’
‘maintainer-clean’
     Cleaning rules (*note Clean::).

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

‘tags’
‘ctags’
     Build ‘TAGS’ and ‘CTAGS’ (*note 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
‘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 (*note 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 (*note 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 (*note Build Directories: (autoconf)Build
Directories.).  The necessary substitutions: ‘@srcdir@’, ‘@top_srcdir@’,
and ‘@top_builddir@’ are defined by ‘configure’ when it processes a
‘Makefile’ (*note Preset Output Variables: (autoconf)Preset Output
Variables.), 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 (*note 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.


File: automake.info,  Node: Distributing,  Next: API Versioning,  Prev: Not Enough,  Up: Top

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.


File: automake.info,  Node: API Versioning,  Next: Upgrading,  Prev: Distributing,  Up: Top

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.


File: automake.info,  Node: Upgrading,  Next: FAQ,  Prev: API Versioning,  Up: Top

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

Automake maintains three kind 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 a -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 (*note automake Invocation::).

   It is important to regenerate all of these files each time Automake
is upgraded, even between bug fixes 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.


File: automake.info,  Node: FAQ,  Next: Copying This Manual,  Prev: Upgrading,  Up: Top

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

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

* Menu:

* CVS::                         CVS and generated files
* maintainer-mode::             missing and AM_MAINTAINER_MODE
* Wildcards::                   Why doesn’t Automake support wildcards?
* Limitations on File Names::   Limitations on source and installed file names
* Errors with distclean::       Files left in build directory after distclean
* Flag Variables Ordering::     CFLAGS vs. AM_CFLAGS vs. mumble_CFLAGS
* Renamed Objects::             Why are object files sometimes renamed?
* Per-Object Flags::            How to simulate per-object flags?
* Multiple Outputs::            Writing rules for tools with many output files
* Hard-Coded Install Paths::    Installing to hard-coded locations
* Debugging Make Rules::        Strategies when things don’t work as expected
* Reporting Bugs::              Feedback on bugs and feature requests


File: automake.info,  Node: CVS,  Next: maintainer-mode,  Up: FAQ

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 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 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 checkout 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 the autotools to build a checkout 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 (*note 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 an 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 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
     version 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 *note 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 released actually.  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 *note CVS Issues: (gettext)CVS
Issues.


File: automake.info,  Node: maintainer-mode,  Next: Wildcards,  Prev: CVS,  Up: FAQ

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 file 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 that 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 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 timestamps lossage (*note 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 sources 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’s 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.


File: automake.info,  Node: Wildcards,  Next: Limitations on File Names,  Prev: maintainer-mode,  Up: FAQ

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.


File: automake.info,  Node: Limitations on File Names,  Next: Errors with distclean,  Prev: Wildcards,  Up: FAQ

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.


File: automake.info,  Node: Errors with distclean,  Next: Flag Variables Ordering,  Prev: Limitations on File Names,  Up: FAQ

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

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

   As explained in *note 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 (*note
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 (*note Clean::), this is obvious and doesn’t deserve
more explanations.

   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 (*note Overview: (help2man)Top.).  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 *note 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.


File: automake.info,  Node: Flag Variables Ordering,  Next: Renamed Objects,  Prev: Errors with distclean,  Up: FAQ

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 (*note 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, *note 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 (*note Texinfo::) use
‘MAKEINFOFLAGS’ and ‘AM_MAKEINFOFLAGS’.  Similarly, DejaGnu tests (*note
DejaGnu Tests::) use ‘RUNTESTDEFAULTFLAGS’ and ‘AM_RUNTESTDEFAULTFLAGS’.
The tags and ctags rules (*note Tags::) use ‘ETAGSFLAGS’,
‘AM_ETAGSFLAGS’, ‘CTAGSFLAGS’, and ‘AM_CTAGSFLAGS’.  Java rules (*note
Java::) use ‘JAVACFLAGS’ and ‘AM_JAVACFLAGS’.  None of these rules
support per-target flags (yet).

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

   ‘ARFLAGS’ (*note A Library::) is usually defined by Automake and has
neither ‘AM_’ nor 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.
*Note Program and Library Variables::.


File: automake.info,  Node: Renamed Objects,  Next: Per-Object Flags,  Prev: Flag Variables Ordering,  Up: FAQ

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 (*note Program and Library Variables::).


File: automake.info,  Node: Per-Object Flags,  Next: Multiple Outputs,  Prev: Renamed Objects,  Up: FAQ

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

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

   Automake supports per-program and per-library compilation flags (see
*note Program and Library Variables:: and *note 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 *note 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’ (*note 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’, *note 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.


File: automake.info,  Node: Multiple Outputs,  Next: Hard-Coded Install Paths,  Prev: Per-Object Flags,  Up: FAQ

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 (*note How the ‘MAKE’ Variable Works: (make)MAKE
Variable.).

   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 (*note (autoconf)The Make Macro MAKEFLAGS::).  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 (*note
Pattern Rule Examples: (make)Pattern Examples.).  We do not discuss
pattern rules here because they are not portable, but they can be
convenient in packages that assume GNU ‘make’.


File: automake.info,  Node: Hard-Coded Install Paths,  Next: Debugging Make Rules,  Prev: Multiple Outputs,  Up: FAQ

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?

   These two setups share their symptoms: ‘make distcheck’ fails because
they are installing files to hard-coded paths.  In the later 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 were 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)’ (*note Python::).

   Of course not all tools are as advanced as Python regarding that
substitution of PREFIX.  So another strategy is to figure the part of
the installation directory that must be preserved.  For instance, here
is how ‘AM_PATH_LISPDIR’ (*note 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.


File: automake.info,  Node: Debugging Make Rules,  Next: Reporting Bugs,  Prev: Hard-Coded Install Paths,  Up: FAQ

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
(*note (make)Options Summary::), 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 (*note 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}’ (*note (make)Instead of
     Execution::).  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’ (*note (make)Remaking
     Makefiles::).
   • ‘make SHELL="/bin/bash -vx"’ can help debug complex rules.  *Note
     (autoconf)The Make Macro SHELL::, 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 to trace execution, examine
     variables, and call 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.


File: automake.info,  Node: Reporting Bugs,  Prev: Debugging Make Rules,  Up: FAQ

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 (http://debbugs.gnu.org/)
and the bug-automake mailing list archives
(http://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 (http://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.


File: automake.info,  Node: Copying This Manual,  Next: Indices,  Prev: FAQ,  Up: Top

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

* Menu:

* GNU Free Documentation License::  License for copying this manual


File: automake.info,  Node: GNU Free Documentation License,  Up: Copying This Manual

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

                     Version 1.3, 3 November 2008

     Copyright © 2000-2017 Free Software Foundation, Inc.
     <http://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
     of 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
     <http://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.


File: automake.info,  Node: Indices,  Prev: Copying This Manual,  Up: Top

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

* Menu:

* Macro Index::                 Index of Autoconf macros
* Variable Index::              Index of Makefile variables
* General Index::               General index


File: automake.info,  Node: Macro Index,  Next: Variable Index,  Up: Indices

B.1 Macro Index
===============

�[index�]
* Menu:

* _AM_DEPENDENCIES:                      Private Macros.      (line  12)
* AC_CANONICAL_BUILD:                    Optional.            (line  11)
* AC_CANONICAL_HOST:                     Optional.            (line  12)
* AC_CANONICAL_TARGET:                   Optional.            (line  13)
* AC_CONFIG_AUX_DIR:                     Optional.            (line  19)
* AC_CONFIG_AUX_DIR <1>:                 Subpackages.         (line   6)
* AC_CONFIG_FILES:                       Requirements.        (line  15)
* AC_CONFIG_HEADERS:                     Optional.            (line  44)
* AC_CONFIG_LIBOBJ_DIR:                  Optional.            (line  40)
* AC_CONFIG_LIBOBJ_DIR <1>:              LIBOBJS.             (line  51)
* AC_CONFIG_LINKS:                       Optional.            (line  55)
* AC_CONFIG_SUBDIRS:                     Subpackages.         (line   6)
* AC_DEFUN:                              Extending aclocal.   (line  36)
* AC_F77_LIBRARY_LDFLAGS:                Optional.            (line 101)
* AC_FC_SRCEXT:                          Optional.            (line 107)
* AC_INIT:                               Public Macros.       (line  15)
* AC_LIBOBJ:                             Optional.            (line  65)
* AC_LIBOBJ <1>:                         LTLIBOBJS.           (line   6)
* AC_LIBOBJ <2>:                         LIBOBJS.             (line  11)
* AC_LIBSOURCE:                          Optional.            (line  66)
* AC_LIBSOURCE <1>:                      LIBOBJS.             (line  17)
* AC_LIBSOURCES:                         Optional.            (line  67)
* AC_OUTPUT:                             Requirements.        (line  15)
* AC_PREREQ:                             Extending aclocal.   (line  36)
* AC_PROG_CXX:                           Optional.            (line  85)
* AC_PROG_F77:                           Optional.            (line  97)
* AC_PROG_FC:                            Optional.            (line 112)
* AC_PROG_LEX:                           Public Macros.       (line  95)
* AC_PROG_LEX <1>:                       Optional.            (line 127)
* AC_PROG_LIBTOOL:                       Optional.            (line 117)
* AC_PROG_OBJC:                          Optional.            (line  89)
* AC_PROG_OBJCXX:                        Optional.            (line  93)
* AC_PROG_RANLIB:                        Optional.            (line  81)
* AC_PROG_YACC:                          Optional.            (line 121)
* AC_REQUIRE_AUX_FILE:                   Optional.            (line 131)
* AC_SUBST:                              Optional.            (line 139)
* AM_CONDITIONAL:                        Optional.            (line 152)
* AM_CONDITIONAL <1>:                    Usage of Conditionals.
                                                              (line   6)
* AM_CONDITIONAL <2>:                    Usage of Conditionals.
                                                              (line   9)
* AM_COND_IF:                            Optional.            (line 155)
* AM_COND_IF <1>:                        Usage of Conditionals.
                                                              (line  66)
* AM_COND_IF <2>:                        Usage of Conditionals.
                                                              (line  70)
* AM_DEP_TRACK:                          Private Macros.      (line  14)
* AM_GNU_GETTEXT:                        Optional.            (line 161)
* AM_GNU_GETTEXT_INTL_SUBDIR:            Optional.            (line 167)
* AM_INIT_AUTOMAKE:                      Requirements.        (line   6)
* AM_INIT_AUTOMAKE <1>:                  Public Macros.       (line   7)
* AM_MAINTAINER_MODE:                    Rebuilding.          (line   9)
* AM_MAINTAINER_MODE <1>:                maintainer-mode.     (line  37)
* AM_MAINTAINER_MODE([DEFAULT-MODE]):    Optional.            (line 172)
* AM_MAKE_INCLUDE:                       Private Macros.      (line  20)
* AM_MISSING_PROG:                       Public Macros.       (line 111)
* AM_OUTPUT_DEPENDENCY_COMMANDS:         Private Macros.      (line  15)
* AM_PATH_LISPDIR:                       Public Macros.       (line  61)
* AM_PATH_PYTHON:                        Python.              (line  28)
* AM_PROG_AR:                            Public Macros.       (line  76)
* AM_PROG_AS:                            Public Macros.       (line  83)
* AM_PROG_CC_C_O:                        Public Macros.       (line  88)
* AM_PROG_GCJ:                           Public Macros.       (line 100)
* AM_PROG_INSTALL_STRIP:                 Private Macros.      (line  25)
* AM_PROG_LEX:                           Public Macros.       (line  95)
* AM_PROG_MKDIR_P:                       Obsolete Macros.     (line  14)
* AM_PROG_UPC:                           Public Macros.       (line 105)
* AM_PROG_VALAC:                         Vala Support.        (line  20)
* AM_SANITY_CHECK:                       Private Macros.      (line  30)
* AM_SET_DEPDIR:                         Private Macros.      (line  13)
* AM_SILENT_RULES:                       Public Macros.       (line 119)
* AM_SUBST_NOTMAKE(VAR):                 Optional.            (line 180)
* AM_WITH_DMALLOC:                       Public Macros.       (line 123)
* m4_include:                            Basics of Distribution.
                                                              (line  17)
* m4_include <1>:                        Optional.            (line 190)


File: automake.info,  Node: Variable Index,  Next: General Index,  Prev: Macro Index,  Up: Indices

B.2 Variable Index
==================

�[index�]
* Menu:

* _DATA:                                 Data.                (line   6)
* _HEADERS:                              Headers.             (line   6)
* _LIBRARIES:                            A Library.           (line   6)
* _LISP:                                 Emacs Lisp.          (line   6)
* _LOG_COMPILE:                          Parallel Test Harness.
                                                              (line  51)
* _LOG_COMPILER:                         Parallel Test Harness.
                                                              (line  51)
* _LOG_DRIVER:                           Declaring Custom Test Drivers.
                                                              (line   6)
* _LOG_DRIVER_FLAGS:                     Declaring Custom Test Drivers.
                                                              (line   6)
* _LOG_FLAGS:                            Parallel Test Harness.
                                                              (line  51)
* _LTLIBRARIES:                          Libtool Libraries.   (line   6)
* _MANS:                                 Man Pages.           (line   6)
* _PROGRAMS:                             Uniform.             (line  11)
* _PROGRAMS <1>:                         Program Sources.     (line   6)
* _PYTHON:                               Python.              (line   6)
* _SCRIPTS:                              Scripts.             (line   6)
* _SOURCES:                              Program Sources.     (line  32)
* _SOURCES <1>:                          Program Sources.     (line  33)
* _SOURCES <2>:                          Default _SOURCES.    (line   6)
* _TEXINFOS:                             Texinfo.             (line   6)
* _TEXINFOS <1>:                         Texinfo.             (line  65)
* ALLOCA:                                LTLIBOBJS.           (line   6)
* ALLOCA <1>:                            LIBOBJS.             (line   6)
* AM_CCASFLAGS:                          Assembly Support.    (line  10)
* AM_CFLAGS:                             Program Variables.   (line  50)
* AM_COLOR_TESTS:                        Scripts-based Testsuites.
                                                              (line  67)
* AM_CPPFLAGS:                           Program Variables.   (line  16)
* AM_CPPFLAGS <1>:                       Assembly Support.    (line  10)
* AM_CXXFLAGS:                           C++ Support.         (line  22)
* AM_DEFAULT_SOURCE_EXT:                 Default _SOURCES.    (line   6)
* AM_DEFAULT_V:                          Automake Silent Rules.
                                                              (line 120)
* AM_DEFAULT_VERBOSITY:                  Automake Silent Rules.
                                                              (line 120)
* AM_DISTCHECK_CONFIGURE_FLAGS:          Checking the Distribution.
                                                              (line  28)
* AM_ETAGSFLAGS:                         Tags.                (line  25)
* AM_EXT_LOG_DRIVER_FLAGS:               Declaring Custom Test Drivers.
                                                              (line   6)
* AM_EXT_LOG_FLAGS:                      Parallel Test Harness.
                                                              (line  51)
* AM_FCFLAGS:                            Fortran 9x Support.  (line  22)
* AM_FFLAGS:                             Fortran 77 Support.  (line  22)
* AM_GCJFLAGS:                           Java Support with gcj.
                                                              (line  26)
* AM_INSTALLCHECK_STD_OPTIONS_EXEMPT:    List of Automake options.
                                                              (line 135)
* AM_JAVACFLAGS:                         Java.                (line  44)
* AM_LDFLAGS:                            Linking.             (line  10)
* AM_LDFLAGS <1>:                        Program Variables.   (line  59)
* AM_LFLAGS:                             Yacc and Lex.        (line  60)
* AM_LIBTOOLFLAGS:                       Libtool Flags.       (line   6)
* AM_LOG_DRIVER_FLAGS:                   Declaring Custom Test Drivers.
                                                              (line   6)
* AM_LOG_FLAGS:                          Parallel Test Harness.
                                                              (line  51)
* AM_MAKEFLAGS:                          Subdirectories.      (line  29)
* AM_MAKEINFOFLAGS:                      Texinfo.             (line 115)
* AM_MAKEINFOHTMLFLAGS:                  Texinfo.             (line 116)
* AM_OBJCFLAGS:                          Objective C Support. (line  22)
* AM_OBJCXXFLAGS:                        Objective C++ Support.
                                                              (line  22)
* AM_RFLAGS:                             Fortran 77 Support.  (line  28)
* AM_RUNTESTFLAGS:                       DejaGnu Tests.       (line  24)
* AM_TESTS_ENVIRONMENT:                  Scripts-based Testsuites.
                                                              (line  86)
* AM_TESTS_FD_REDIRECT:                  Scripts-based Testsuites.
                                                              (line  94)
* AM_UPCFLAGS:                           Unified Parallel C Support.
                                                              (line  21)
* AM_UPDATE_INFO_DIR:                    Texinfo.             (line  92)
* AM_V:                                  Automake Silent Rules.
                                                              (line 120)
* AM_VALAFLAGS:                          Vala Support.        (line  41)
* AM_V_at:                               Automake Silent Rules.
                                                              (line 120)
* AM_V_GEN:                              Automake Silent Rules.
                                                              (line 120)
* AM_YFLAGS:                             Yacc and Lex.        (line  37)
* AR:                                    Public Macros.       (line  76)
* AUTOCONF:                              automake Invocation. (line  28)
* AUTOM4TE:                              aclocal Invocation.  (line  44)
* AUTOMAKE_JOBS:                         automake Invocation. (line 174)
* AUTOMAKE_OPTIONS:                      Public Macros.       (line  10)
* AUTOMAKE_OPTIONS <1>:                  Dependencies.        (line  34)
* AUTOMAKE_OPTIONS <2>:                  List of Automake options.
                                                              (line   6)
* bin_PROGRAMS:                          Program Sources.     (line   6)
* bin_SCRIPTS:                           Scripts.             (line  18)
* build_triplet:                         Optional.            (line  14)
* BUILT_SOURCES:                         Sources.             (line  27)
* BZIP2:                                 The Types of Distributions.
                                                              (line  13)
* CC:                                    Program Variables.   (line  12)
* CCAS:                                  Public Macros.       (line  83)
* CCAS <1>:                              Assembly Support.    (line  10)
* CCASFLAGS:                             Public Macros.       (line  83)
* CCASFLAGS <1>:                         Assembly Support.    (line  10)
* CFLAGS:                                Program Variables.   (line  12)
* check_:                                Uniform.             (line  95)
* check_LTLIBRARIES:                     Libtool Convenience Libraries.
                                                              (line   6)
* check_PROGRAMS:                        Program Sources.     (line   6)
* check_PROGRAMS <1>:                    Default _SOURCES.    (line  28)
* check_SCRIPTS:                         Scripts.             (line  18)
* CLASSPATH_ENV:                         Java.                (line  53)
* CLEANFILES:                            Clean.               (line  13)
* COMPILE:                               Program Variables.   (line  55)
* CONFIGURE_DEPENDENCIES:                Rebuilding.          (line  12)
* CONFIG_STATUS_DEPENDENCIES:            Rebuilding.          (line  12)
* CPPFLAGS:                              Program Variables.   (line  12)
* CPPFLAGS <1>:                          Assembly Support.    (line  10)
* CXX:                                   C++ Support.         (line  16)
* CXXCOMPILE:                            C++ Support.         (line  25)
* CXXFLAGS:                              C++ Support.         (line  19)
* CXXLINK:                               C++ Support.         (line  29)
* CXXLINK <1>:                           How the Linker is Chosen.
                                                              (line  12)
* DATA:                                  Uniform.             (line 101)
* DATA <1>:                              Data.                (line   7)
* data_DATA:                             Data.                (line   9)
* DEFS:                                  Program Variables.   (line  12)
* DEJATOOL:                              DejaGnu Tests.       (line  19)
* DESTDIR:                               DESTDIR.             (line   6)
* DESTDIR <1>:                           Staged Installs.     (line   6)
* DISABLE_HARD_ERRORS:                   Scripts-based Testsuites.
                                                              (line  32)
* DISTCHECK_CONFIGURE_FLAGS:             Checking the Distribution.
                                                              (line  28)
* distcleancheck_listfiles:              Checking the Distribution.
                                                              (line  70)
* distcleancheck_listfiles <1>:          Errors with distclean.
                                                              (line 112)
* DISTCLEANFILES:                        Clean.               (line  13)
* DISTCLEANFILES <1>:                    Checking the Distribution.
                                                              (line  70)
* distdir:                               The dist Hook.       (line  33)
* distdir <1>:                           Third-Party Makefiles.
                                                              (line  25)
* distuninstallcheck_listfiles:          Checking the Distribution.
                                                              (line 106)
* dist_:                                 Alternative.         (line  29)
* dist_ <1>:                             Fine-grained Distribution Control.
                                                              (line   6)
* dist_lisp_LISP:                        Emacs Lisp.          (line  11)
* dist_noinst_LISP:                      Emacs Lisp.          (line  11)
* DIST_SUBDIRS:                          Subdirectories with AM_CONDITIONAL.
                                                              (line  25)
* DIST_SUBDIRS <1>:                      Basics of Distribution.
                                                              (line  47)
* DVIPS:                                 Texinfo.             (line 141)
* EMACS:                                 Public Macros.       (line  61)
* ETAGSFLAGS:                            Tags.                (line  25)
* ETAGS_ARGS:                            Tags.                (line  25)
* EXPECT:                                DejaGnu Tests.       (line  19)
* EXTRA_DIST:                            Basics of Distribution.
                                                              (line  34)
* EXTRA_maude_DEPENDENCIES:              Linking.             (line  41)
* EXTRA_maude_DEPENDENCIES <1>:          Program and Library Variables.
                                                              (line 119)
* EXTRA_maude_SOURCES:                   Program and Library Variables.
                                                              (line  53)
* EXTRA_PROGRAMS:                        Conditional Programs.
                                                              (line  15)
* EXT_LOG_COMPILE:                       Parallel Test Harness.
                                                              (line  51)
* EXT_LOG_COMPILER:                      Parallel Test Harness.
                                                              (line  51)
* EXT_LOG_DRIVER:                        Declaring Custom Test Drivers.
                                                              (line   6)
* EXT_LOG_DRIVER_FLAGS:                  Declaring Custom Test Drivers.
                                                              (line   6)
* EXT_LOG_FLAGS:                         Parallel Test Harness.
                                                              (line  51)
* F77:                                   Fortran 77 Support.  (line  16)
* F77COMPILE:                            Fortran 77 Support.  (line  31)
* F77LINK:                               How the Linker is Chosen.
                                                              (line  13)
* FC:                                    Fortran 9x Support.  (line  16)
* FCCOMPILE:                             Fortran 9x Support.  (line  25)
* FCFLAGS:                               Fortran 9x Support.  (line  19)
* FCLINK:                                How the Linker is Chosen.
                                                              (line  14)
* FCLINK <1>:                            Fortran 9x Support.  (line  29)
* FFLAGS:                                Fortran 77 Support.  (line  19)
* FLIBS:                                 Mixing Fortran 77 With C and C++.
                                                              (line  21)
* FLINK:                                 Fortran 77 Support.  (line  35)
* GCJ:                                   Public Macros.       (line 100)
* GCJFLAGS:                              Public Macros.       (line 100)
* GCJFLAGS <1>:                          Java Support with gcj.
                                                              (line  16)
* GCJLINK:                               How the Linker is Chosen.
                                                              (line  10)
* GTAGS_ARGS:                            Tags.                (line  60)
* GZIP_ENV:                              Basics of Distribution.
                                                              (line  14)
* HEADERS:                               Uniform.             (line 101)
* host_triplet:                          Optional.            (line  14)
* INCLUDES:                              Program Variables.   (line  44)
* include_HEADERS:                       Headers.             (line   6)
* info_TEXINFOS:                         Texinfo.             (line   6)
* JAVA:                                  Uniform.             (line 101)
* JAVAC:                                 Java.                (line  37)
* JAVACFLAGS:                            Java.                (line  40)
* JAVAROOT:                              Java.                (line  49)
* LDADD:                                 Linking.             (line  10)
* LDFLAGS:                               Program Variables.   (line  12)
* LFLAGS:                                Yacc and Lex.        (line  60)
* libexec_PROGRAMS:                      Program Sources.     (line   6)
* libexec_SCRIPTS:                       Scripts.             (line  18)
* LIBOBJS:                               Optional.            (line  68)
* LIBOBJS <1>:                           LTLIBOBJS.           (line   6)
* LIBOBJS <2>:                           LIBOBJS.             (line   6)
* LIBRARIES:                             Uniform.             (line 101)
* LIBS:                                  Program Variables.   (line  12)
* LIBTOOLFLAGS:                          Libtool Flags.       (line   6)
* lib_LIBRARIES:                         A Library.           (line   6)
* lib_LTLIBRARIES:                       Libtool Libraries.   (line   6)
* LINK:                                  Program Variables.   (line  64)
* LINK <1>:                              How the Linker is Chosen.
                                                              (line  17)
* LISP:                                  Uniform.             (line 101)
* lispdir:                               Public Macros.       (line  61)
* lisp_LISP:                             Emacs Lisp.          (line   6)
* localstate_DATA:                       Data.                (line   9)
* LOG_COMPILE:                           Parallel Test Harness.
                                                              (line  51)
* LOG_COMPILER:                          Parallel Test Harness.
                                                              (line  51)
* LOG_DRIVER:                            Declaring Custom Test Drivers.
                                                              (line   6)
* LOG_DRIVER_FLAGS:                      Declaring Custom Test Drivers.
                                                              (line   6)
* LOG_FLAGS:                             Parallel Test Harness.
                                                              (line  51)
* LTALLOCA:                              LTLIBOBJS.           (line   6)
* LTALLOCA <1>:                          LIBOBJS.             (line   6)
* LTLIBOBJS:                             LTLIBOBJS.           (line   6)
* LTLIBOBJS <1>:                         LIBOBJS.             (line   6)
* LTLIBRARIES:                           Uniform.             (line 101)
* MAINTAINERCLEANFILES:                  Clean.               (line  13)
* MAKE:                                  Subdirectories.      (line  29)
* MAKEINFO:                              Texinfo.             (line  99)
* MAKEINFOFLAGS:                         Texinfo.             (line 109)
* MAKEINFOHTML:                          Texinfo.             (line 105)
* MANS:                                  Uniform.             (line 101)
* man_MANS:                              Man Pages.           (line   6)
* maude_AR:                              Program and Library Variables.
                                                              (line  68)
* maude_CCASFLAGS:                       Program and Library Variables.
                                                              (line 170)
* maude_CFLAGS:                          Program and Library Variables.
                                                              (line 171)
* maude_CPPFLAGS:                        Program and Library Variables.
                                                              (line 172)
* maude_CXXFLAGS:                        Program and Library Variables.
                                                              (line 173)
* maude_DEPENDENCIES:                    Linking.             (line  41)
* maude_DEPENDENCIES <1>:                Program and Library Variables.
                                                              (line 118)
* maude_FFLAGS:                          Program and Library Variables.
                                                              (line 174)
* maude_GCJFLAGS:                        Program and Library Variables.
                                                              (line 175)
* maude_LDADD:                           Linking.             (line  17)
* maude_LDADD <1>:                       Program and Library Variables.
                                                              (line  86)
* maude_LDFLAGS:                         Linking.             (line  37)
* maude_LDFLAGS <1>:                     Program and Library Variables.
                                                              (line 106)
* maude_LFLAGS:                          Program and Library Variables.
                                                              (line 176)
* maude_LIBADD:                          A Library.           (line  26)
* maude_LIBADD <1>:                      Program and Library Variables.
                                                              (line  78)
* maude_LIBTOOLFLAGS:                    Libtool Flags.       (line   6)
* maude_LIBTOOLFLAGS <1>:                Program and Library Variables.
                                                              (line 111)
* maude_LINK:                            Program and Library Variables.
                                                              (line 154)
* maude_OBJCFLAGS:                       Program and Library Variables.
                                                              (line 177)
* maude_OBJCXXFLAGS:                     Program and Library Variables.
                                                              (line 178)
* maude_RFLAGS:                          Program and Library Variables.
                                                              (line 179)
* maude_SHORTNAME:                       Program and Library Variables.
                                                              (line 210)
* maude_SOURCES:                         Program and Library Variables.
                                                              (line  18)
* maude_UPCFLAGS:                        Program and Library Variables.
                                                              (line 180)
* maude_YFLAGS:                          Program and Library Variables.
                                                              (line 181)
* MISSING:                               Public Macros.       (line 111)
* MKDIR_P:                               Obsolete Macros.     (line  14)
* mkdir_p:                               Obsolete Macros.     (line  14)
* MOSTLYCLEANFILES:                      Clean.               (line  13)
* nobase_:                               Alternative.         (line  23)
* nodist_:                               Alternative.         (line  29)
* nodist_ <1>:                           Fine-grained Distribution Control.
                                                              (line   6)
* noinst_:                               Uniform.             (line  90)
* noinst_HEADERS:                        Headers.             (line   6)
* noinst_HEADERS <1>:                    Headers.             (line  23)
* noinst_LIBRARIES:                      A Library.           (line   6)
* noinst_LISP:                           Emacs Lisp.          (line   6)
* noinst_LTLIBRARIES:                    Libtool Convenience Libraries.
                                                              (line   6)
* noinst_PROGRAMS:                       Program Sources.     (line   6)
* noinst_SCRIPTS:                        Scripts.             (line  18)
* notrans_:                              Man Pages.           (line  54)
* OBJC:                                  Objective C Support. (line  16)
* OBJCCOMPILE:                           Objective C Support. (line  25)
* OBJCFLAGS:                             Objective C Support. (line  19)
* OBJCLINK:                              Objective C Support. (line  29)
* OBJCLINK <1>:                          How the Linker is Chosen.
                                                              (line  15)
* OBJCXX:                                Objective C++ Support.
                                                              (line  16)
* OBJCXXCOMPILE:                         Objective C++ Support.
                                                              (line  25)
* OBJCXXFLAGS:                           Objective C++ Support.
                                                              (line  19)
* OBJCXXLINK:                            Objective C++ Support.
                                                              (line  29)
* OBJCXXLINK <1>:                        How the Linker is Chosen.
                                                              (line  11)
* oldinclude_HEADERS:                    Headers.             (line   6)
* PACKAGE:                               Basics of Distribution.
                                                              (line   6)
* pkgdatadir:                            Uniform.             (line  19)
* pkgdata_DATA:                          Data.                (line   9)
* pkgdata_SCRIPTS:                       Scripts.             (line  18)
* pkgincludedir:                         Uniform.             (line  19)
* pkginclude_HEADERS:                    Headers.             (line   6)
* pkglibdir:                             Uniform.             (line  19)
* pkglibexecdir:                         Uniform.             (line  19)
* pkglibexec_PROGRAMS:                   Program Sources.     (line   6)
* pkglibexec_SCRIPTS:                    Scripts.             (line  18)
* pkglib_LIBRARIES:                      A Library.           (line   6)
* pkglib_LTLIBRARIES:                    Libtool Libraries.   (line   6)
* pkgpyexecdir:                          Python.              (line 105)
* pkgpythondir:                          Python.              (line  91)
* PROGRAMS:                              Uniform.             (line  17)
* PROGRAMS <1>:                          Uniform.             (line 101)
* pyexecdir:                             Python.              (line  96)
* PYTHON:                                Uniform.             (line 101)
* PYTHON <1>:                            Python.              (line  56)
* pythondir:                             Python.              (line  87)
* PYTHON_EXEC_PREFIX:                    Python.              (line  77)
* PYTHON_PLATFORM:                       Python.              (line  82)
* PYTHON_PREFIX:                         Python.              (line  72)
* PYTHON_VERSION:                        Python.              (line  68)
* RECHECK_LOGS:                          Parallel Test Harness.
                                                              (line 118)
* RFLAGS:                                Fortran 77 Support.  (line  25)
* RUNTEST:                               DejaGnu Tests.       (line  19)
* RUNTESTDEFAULTFLAGS:                   DejaGnu Tests.       (line  14)
* RUNTESTFLAGS:                          DejaGnu Tests.       (line  24)
* sbin_PROGRAMS:                         Program Sources.     (line   6)
* sbin_SCRIPTS:                          Scripts.             (line  18)
* SCRIPTS:                               Uniform.             (line 101)
* SCRIPTS <1>:                           Scripts.             (line   9)
* sharedstate_DATA:                      Data.                (line   9)
* SOURCES:                               Program Sources.     (line  33)
* SOURCES <1>:                           Default _SOURCES.    (line   6)
* SUBDIRS:                               Subdirectories.      (line   8)
* SUBDIRS <1>:                           Basics of Distribution.
                                                              (line  47)
* SUFFIXES:                              Suffixes.            (line   6)
* sysconf_DATA:                          Data.                (line   9)
* TAGS_DEPENDENCIES:                     Tags.                (line  35)
* target_triplet:                        Optional.            (line  14)
* TESTS:                                 Scripts-based Testsuites.
                                                              (line  86)
* TESTS <1>:                             Parallel Test Harness.
                                                              (line  12)
* TESTS_ENVIRONMENT:                     Scripts-based Testsuites.
                                                              (line  86)
* TEST_EXTENSIONS:                       Parallel Test Harness.
                                                              (line  34)
* TEST_LOGS:                             Parallel Test Harness.
                                                              (line  34)
* TEST_SUITE_LOG:                        Parallel Test Harness.
                                                              (line  12)
* TEXI2DVI:                              Texinfo.             (line 132)
* TEXI2PDF:                              Texinfo.             (line 137)
* TEXINFOS:                              Uniform.             (line 101)
* TEXINFOS <1>:                          Texinfo.             (line  65)
* TEXINFO_TEX:                           Texinfo.             (line 145)
* top_distdir:                           The dist Hook.       (line  33)
* top_distdir <1>:                       Third-Party Makefiles.
                                                              (line  25)
* UPC:                                   Public Macros.       (line 105)
* UPC <1>:                               Unified Parallel C Support.
                                                              (line  15)
* UPCCOMPILE:                            Unified Parallel C Support.
                                                              (line  24)
* UPCFLAGS:                              Unified Parallel C Support.
                                                              (line  18)
* UPCLINK:                               Unified Parallel C Support.
                                                              (line  28)
* UPCLINK <1>:                           How the Linker is Chosen.
                                                              (line  16)
* V:                                     Automake Silent Rules.
                                                              (line  88)
* VALAC:                                 Vala Support.        (line  34)
* VALAFLAGS:                             Vala Support.        (line  38)
* VERBOSE:                               Parallel Test Harness.
                                                              (line  26)
* VERSION:                               Basics of Distribution.
                                                              (line   6)
* WARNINGS:                              automake Invocation. (line 167)
* WARNINGS <1>:                          aclocal Options.     (line  91)
* WITH_DMALLOC:                          Public Macros.       (line 123)
* XFAIL_TESTS:                           Scripts-based Testsuites.
                                                              (line  32)
* XZ_OPT:                                The Types of Distributions.
                                                              (line  24)
* YACC:                                  Optional.            (line 122)
* YFLAGS:                                Yacc and Lex.        (line  37)


File: automake.info,  Node: General Index,  Prev: Variable Index,  Up: Indices

B.3 General Index
=================

�[index�]
* Menu:

* ## (special Automake comment):         General Operation.   (line  68)
* #serial syntax:                        Serials.             (line   6)
* $(LIBOBJS) and empty libraries:        LIBOBJS.             (line  72)
* +=:                                    General Operation.   (line  24)
* --add-missing:                         automake Invocation. (line  41)
* --automake-acdir:                      aclocal Options.     (line   9)
* --build=BUILD:                         Cross-Compilation.   (line  14)
* --copy:                                automake Invocation. (line  71)
* --diff:                                aclocal Options.     (line  18)
* --disable-dependency-tracking:         Dependency Tracking. (line  33)
* --disable-maintainer-mode:             Optional.            (line 173)
* --disable-silent-rules:                Automake Silent Rules.
                                                              (line  85)
* --dry-run:                             aclocal Options.     (line  23)
* --enable-debug, example:               Usage of Conditionals.
                                                              (line  21)
* --enable-dependency-tracking:          Dependency Tracking. (line  43)
* --enable-maintainer-mode:              Optional.            (line 173)
* --enable-silent-rules:                 Automake Silent Rules.
                                                              (line  85)
* --force:                               aclocal Options.     (line  45)
* --force-missing:                       automake Invocation. (line  76)
* --foreign:                             automake Invocation. (line  82)
* --gnits:                               automake Invocation. (line  86)
* --gnits, complete description:         Gnits.               (line  29)
* --gnu:                                 automake Invocation. (line  90)
* --gnu, complete description:           Gnits.               (line   6)
* --gnu, required files:                 Gnits.               (line   6)
* --help:                                automake Invocation. (line  94)
* --help <1>:                            aclocal Options.     (line  27)
* --help check:                          List of Automake options.
                                                              (line 129)
* --help=recursive:                      Nested Packages.     (line  30)
* --host=HOST:                           Cross-Compilation.   (line  16)
* --include-deps:                        automake Invocation. (line 102)
* --install:                             aclocal Options.     (line  34)
* --libdir:                              automake Invocation. (line  61)
* --no-force:                            automake Invocation. (line 107)
* --output:                              aclocal Options.     (line  55)
* --output-dir:                          automake Invocation. (line 114)
* --prefix:                              Standard Directory Variables.
                                                              (line  33)
* --print-ac-dir:                        aclocal Options.     (line  58)
* --print-libdir:                        automake Invocation. (line  65)
* --program-prefix=PREFIX:               Renaming.            (line  16)
* --program-suffix=SUFFIX:               Renaming.            (line  18)
* --program-transform-name=PROGRAM:      Renaming.            (line  20)
* --system-acdir:                        aclocal Options.     (line  13)
* --target=TARGET:                       Cross-Compilation.   (line  55)
* --verbose:                             automake Invocation. (line 121)
* --verbose <1>:                         aclocal Options.     (line  69)
* --version:                             automake Invocation. (line 125)
* --version <1>:                         aclocal Options.     (line  72)
* --version check:                       List of Automake options.
                                                              (line 129)
* --warnings:                            automake Invocation. (line 129)
* --warnings <1>:                        aclocal Options.     (line  76)
* --with-dmalloc:                        Public Macros.       (line 123)
* -a:                                    automake Invocation. (line  41)
* -c:                                    automake Invocation. (line  70)
* -f:                                    automake Invocation. (line  75)
* -hook targets:                         Extending.           (line  66)
* -i:                                    automake Invocation. (line  98)
* -I:                                    aclocal Options.     (line  30)
* -l and LDADD:                          Linking.             (line  70)
* -local targets:                        Extending.           (line  37)
* -module, libtool:                      Libtool Modules.     (line   6)
* -o:                                    automake Invocation. (line 114)
* -v:                                    automake Invocation. (line 121)
* -W:                                    automake Invocation. (line 129)
* -W <1>:                                aclocal Options.     (line  76)
* -Wall:                                 amhello's configure.ac Setup Explained.
                                                              (line  38)
* -Werror:                               amhello's configure.ac Setup Explained.
                                                              (line  38)
* .la suffix, defined:                   Libtool Concept.     (line   6)
* .log files:                            Parallel Test Harness.
                                                              (line  12)
* .trs files:                            Parallel Test Harness.
                                                              (line  12)
* :copy-in-global-log::                  Log files generation and test results recording.
                                                              (line  44)
* :recheck::                             Log files generation and test results recording.
                                                              (line  38)
* :test-global-result::                  Log files generation and test results recording.
                                                              (line  54)
* :test-result::                         Log files generation and test results recording.
                                                              (line  24)
* _DATA primary, defined:                Data.                (line   6)
* _DEPENDENCIES, defined:                Linking.             (line  41)
* _HEADERS primary, defined:             Headers.             (line   6)
* _JAVA primary, defined:                Java.                (line   6)
* _LDFLAGS, defined:                     Linking.             (line  37)
* _LDFLAGS, libtool:                     Libtool Flags.       (line   6)
* _LIBADD, libtool:                      Libtool Flags.       (line   6)
* _LIBRARIES primary, defined:           A Library.           (line   6)
* _LIBTOOLFLAGS, libtool:                Libtool Flags.       (line   6)
* _LISP primary, defined:                Emacs Lisp.          (line   6)
* _LTLIBRARIES primary, defined:         Libtool Libraries.   (line   6)
* _MANS primary, defined:                Man Pages.           (line   6)
* _PROGRAMS primary variable:            Uniform.             (line  11)
* _PYTHON primary, defined:              Python.              (line   6)
* _SCRIPTS primary, defined:             Scripts.             (line   6)
* _SOURCES and header files:             Program Sources.     (line  39)
* _SOURCES primary, defined:             Program Sources.     (line  32)
* _SOURCES, default:                     Default _SOURCES.    (line   6)
* _SOURCES, empty:                       Default _SOURCES.    (line  44)
* _TEXINFOS primary, defined:            Texinfo.             (line   6)
* acinclude.m4, defined:                 Complete.            (line  23)
* aclocal and serial numbers:            Serials.             (line   6)
* aclocal program, introduction:         Complete.            (line  23)
* aclocal search path:                   Macro Search Path.   (line   6)
* aclocal’s scheduled death:             Future of aclocal.   (line   6)
* aclocal, extending:                    Extending aclocal.   (line   6)
* aclocal, Invocation:                   aclocal Invocation.  (line   6)
* aclocal, Invoking:                     aclocal Invocation.  (line   6)
* aclocal, Options:                      aclocal Options.     (line   6)
* aclocal, using:                        configure.           (line   6)
* aclocal.m4, preexisting:               Complete.            (line  23)
* ACLOCAL_PATH:                          Macro Search Path.   (line 116)
* AC_CONFIG_FILES, conditional:          Usage of Conditionals.
                                                              (line  79)
* AC_SUBST and SUBDIRS:                  Subdirectories with AC_SUBST.
                                                              (line   6)
* Adding new SUFFIXES:                   Suffixes.            (line   6)
* all:                                   Standard Targets.    (line  16)
* all <1>:                               Extending.           (line  41)
* all-local:                             Extending.           (line  41)
* ALLOCA, and Libtool:                   LTLIBOBJS.           (line   6)
* ALLOCA, example:                       LIBOBJS.             (line   6)
* ALLOCA, special handling:              LIBOBJS.             (line   6)
* amhello-1.0.tar.gz, creation:          Hello World.         (line   6)
* amhello-1.0.tar.gz, location:          Use Cases.           (line   6)
* amhello-1.0.tar.gz, use cases:         Use Cases.           (line   6)
* AM_CCASFLAGS and CCASFLAGS:            Flag Variables Ordering.
                                                              (line  20)
* AM_CFLAGS and CFLAGS:                  Flag Variables Ordering.
                                                              (line  20)
* AM_CONDITIONAL and SUBDIRS:            Subdirectories with AM_CONDITIONAL.
                                                              (line   6)
* AM_CPPFLAGS and CPPFLAGS:              Flag Variables Ordering.
                                                              (line  20)
* AM_CXXFLAGS and CXXFLAGS:              Flag Variables Ordering.
                                                              (line  20)
* AM_FCFLAGS and FCFLAGS:                Flag Variables Ordering.
                                                              (line  20)
* AM_FFLAGS and FFLAGS:                  Flag Variables Ordering.
                                                              (line  20)
* AM_GCJFLAGS and GCJFLAGS:              Flag Variables Ordering.
                                                              (line  20)
* AM_INIT_AUTOMAKE, example use:         Complete.            (line  11)
* AM_LDFLAGS and LDFLAGS:                Flag Variables Ordering.
                                                              (line  20)
* AM_LFLAGS and LFLAGS:                  Flag Variables Ordering.
                                                              (line  20)
* AM_LIBTOOLFLAGS and LIBTOOLFLAGS:      Flag Variables Ordering.
                                                              (line  20)
* AM_MAINTAINER_MODE, purpose:           maintainer-mode.     (line  37)
* AM_OBJCFLAGS and OBJCFLAGS:            Flag Variables Ordering.
                                                              (line  20)
* AM_OBJCXXFLAGS and OBJXXCFLAGS:        Flag Variables Ordering.
                                                              (line  20)
* AM_RFLAGS and RFLAGS:                  Flag Variables Ordering.
                                                              (line  20)
* AM_UPCFLAGS and UPCFLAGS:              Flag Variables Ordering.
                                                              (line  20)
* AM_YFLAGS and YFLAGS:                  Flag Variables Ordering.
                                                              (line  20)
* Append operator:                       General Operation.   (line  24)
* ARG_MAX:                               Length Limitations.  (line   6)
* autogen.sh and autoreconf:             Error required file ltmain.sh not found.
                                                              (line   6)
* autom4te:                              aclocal Invocation.  (line  44)
* Automake constraints:                  Introduction.        (line  21)
* automake options:                      automake Invocation. (line  37)
* Automake parser, limitations of:       General Operation.   (line  33)
* Automake requirements:                 Introduction.        (line  26)
* Automake requirements <1>:             Requirements.        (line   6)
* automake, invocation:                  automake Invocation. (line   6)
* automake, invoking:                    automake Invocation. (line   6)
* Automake, recursive operation:         General Operation.   (line  58)
* Automatic dependency tracking:         Dependencies.        (line  11)
* Automatic linker selection:            How the Linker is Chosen.
                                                              (line   6)
* autoreconf and libtoolize:             Error required file ltmain.sh not found.
                                                              (line   6)
* autoreconf, example:                   Creating amhello.    (line  59)
* autoscan:                              amhello's configure.ac Setup Explained.
                                                              (line  89)
* Autotools, introduction:               GNU Build System.    (line  43)
* Autotools, purpose:                    Why Autotools.       (line   6)
* autoupdate:                            Obsolete Macros.     (line   6)
* Auxiliary programs:                    Auxiliary Programs.  (line   6)
* Avoiding man page renaming:            Man Pages.           (line  54)
* Avoiding path stripping:               Alternative.         (line  23)
* Binary package:                        DESTDIR.             (line  22)
* bootstrap and autoreconf:              Error required file ltmain.sh not found.
                                                              (line   6)
* Bugs, reporting:                       Introduction.        (line  30)
* build tree and source tree:            VPATH Builds.        (line   6)
* BUILT_SOURCES, defined:                Sources.             (line  27)
* C++ support:                           C++ Support.         (line   6)
* canonicalizing Automake variables:     Canonicalization.    (line   6)
* CCASFLAGS and AM_CCASFLAGS:            Flag Variables Ordering.
                                                              (line  20)
* CFLAGS and AM_CFLAGS:                  Flag Variables Ordering.
                                                              (line  20)
* cfortran:                              Mixing Fortran 77 With C and C++.
                                                              (line   6)
* check:                                 Standard Targets.    (line  31)
* check <1>:                             Tests.               (line   6)
* check <2>:                             Extending.           (line  41)
* check-local:                           Extending.           (line  41)
* check-news:                            List of Automake options.
                                                              (line  14)
* check_ primary prefix, definition:     Uniform.             (line  95)
* check_PROGRAMS example:                Default _SOURCES.    (line  28)
* clean:                                 Standard Targets.    (line  27)
* clean <1>:                             Extending.           (line  41)
* clean-local:                           Clean.               (line  15)
* clean-local <1>:                       Extending.           (line  41)
* Colorized testsuite output:            Scripts-based Testsuites.
                                                              (line  67)
* command line length limit:             Length Limitations.  (line   6)
* Comment, special to Automake:          General Operation.   (line  68)
* Compilation of Java to bytecode:       Java.                (line   6)
* Compilation of Java to native code:    Java Support with gcj.
                                                              (line   6)
* Compile Flag Variables:                Flag Variables Ordering.
                                                              (line  20)
* Complete example:                      Complete.            (line   6)
* Conditional example, --enable-debug:   Usage of Conditionals.
                                                              (line  21)
* conditional libtool libraries:         Conditional Libtool Libraries.
                                                              (line   6)
* Conditional programs:                  Conditional Programs.
                                                              (line   6)
* Conditional subdirectories:            Conditional Subdirectories.
                                                              (line   6)
* Conditional SUBDIRS:                   Conditional Subdirectories.
                                                              (line   6)
* Conditionals:                          Conditionals.        (line   6)
* config.guess:                          automake Invocation. (line  39)
* config.site example:                   config.site.         (line   6)
* configuration variables, overriding:   Standard Configuration Variables.
                                                              (line   6)
* Configuration, basics:                 Basic Installation.  (line   6)
* Configure substitutions in TESTS:      Parallel Test Harness.
                                                              (line  46)
* configure.ac, Hello World:             amhello's configure.ac Setup Explained.
                                                              (line   6)
* configure.ac, scanning:                configure.           (line   6)
* conflicting definitions:               Extending.           (line  14)
* Constraints of Automake:               Introduction.        (line  21)
* convenience libraries, libtool:        Libtool Convenience Libraries.
                                                              (line   6)
* copying semantics:                     Extending.           (line  10)
* cpio example:                          Uniform.             (line  36)
* CPPFLAGS and AM_CPPFLAGS:              Flag Variables Ordering.
                                                              (line  20)
* cross-compilation:                     Cross-Compilation.   (line   6)
* cross-compilation example:             Cross-Compilation.   (line  25)
* CVS and generated files:               CVS.                 (line  49)
* CVS and third-party files:             CVS.                 (line 167)
* CVS and timestamps:                    CVS.                 (line  28)
* CXXFLAGS and AM_CXXFLAGS:              Flag Variables Ordering.
                                                              (line  20)
* DATA primary, defined:                 Data.                (line   6)
* debug build, example:                  VPATH Builds.        (line  46)
* debugging rules:                       Debugging Make Rules.
                                                              (line   6)
* default source, Libtool modules example: Default _SOURCES.  (line  38)
* default verbosity for silent rules:    Automake Silent Rules.
                                                              (line  92)
* default _SOURCES:                      Default _SOURCES.    (line   6)
* definitions, conflicts:                Extending.           (line  14)
* dejagnu:                               DejaGnu Tests.       (line  19)
* dejagnu <1>:                           List of Automake options.
                                                              (line  18)
* depcomp:                               Dependencies.        (line  22)
* dependencies and distributed files:    Errors with distclean.
                                                              (line   6)
* Dependency tracking:                   Dependency Tracking. (line   6)
* Dependency tracking <1>:               Dependencies.        (line  11)
* Dependency tracking, disabling:        Dependencies.        (line  36)
* directory variables:                   Standard Directory Variables.
                                                              (line   6)
* dirlist:                               Macro Search Path.   (line  52)
* Disabling dependency tracking:         Dependencies.        (line  37)
* Disabling hard errors:                 Scripts-based Testsuites.
                                                              (line  32)
* dist:                                  Standard Targets.    (line  35)
* dist <1>:                              Basics of Distribution.
                                                              (line   6)
* dist-bzip2:                            The Types of Distributions.
                                                              (line  18)
* dist-bzip2 <1>:                        List of Automake options.
                                                              (line  22)
* dist-bzip2 <2>:                        List of Automake options.
                                                              (line  22)
* dist-gzip:                             The Types of Distributions.
                                                              (line  11)
* dist-hook:                             The dist Hook.       (line   6)
* dist-hook <1>:                         Extending.           (line  66)
* dist-lzip:                             The Types of Distributions.
                                                              (line  22)
* dist-lzip <1>:                         List of Automake options.
                                                              (line  25)
* dist-lzip <2>:                         List of Automake options.
                                                              (line  25)
* dist-shar:                             The Types of Distributions.
                                                              (line  45)
* dist-shar <1>:                         List of Automake options.
                                                              (line  36)
* dist-shar <2>:                         List of Automake options.
                                                              (line  34)
* dist-tarZ:                             The Types of Distributions.
                                                              (line  39)
* dist-tarZ <1>:                         List of Automake options.
                                                              (line  41)
* dist-tarZ <2>:                         List of Automake options.
                                                              (line  39)
* dist-xz:                               The Types of Distributions.
                                                              (line  30)
* dist-xz <1>:                           List of Automake options.
                                                              (line  28)
* dist-xz <2>:                           List of Automake options.
                                                              (line  28)
* dist-zip:                              The Types of Distributions.
                                                              (line  33)
* dist-zip <1>:                          List of Automake options.
                                                              (line  31)
* dist-zip <2>:                          List of Automake options.
                                                              (line  31)
* distcheck:                             Creating amhello.    (line 100)
* distcheck <1>:                         Checking the Distribution.
                                                              (line   6)
* distcheck better than dist:            Preparing Distributions.
                                                              (line  10)
* distcheck example:                     Creating amhello.    (line 100)
* distcheck-hook:                        Checking the Distribution.
                                                              (line  55)
* distclean:                             Standard Targets.    (line  29)
* distclean <1>:                         Extending.           (line  41)
* distclean <2>:                         Errors with distclean.
                                                              (line   6)
* distclean, diagnostic:                 Errors with distclean.
                                                              (line   6)
* distclean-local:                       Clean.               (line  15)
* distclean-local <1>:                   Extending.           (line  41)
* distcleancheck:                        Checking the Distribution.
                                                              (line  70)
* distdir:                               Third-Party Makefiles.
                                                              (line  25)
* Distinction between errors and failures in testsuites: Generalities about Testing.
                                                              (line  48)
* Distributions, preparation:            Preparing Distributions.
                                                              (line   6)
* distuninstallcheck:                    Checking the Distribution.
                                                              (line 106)
* dist_ and nobase_:                     Alternative.         (line  29)
* dist_ and notrans_:                    Man Pages.           (line  63)
* DIST_SUBDIRS, explained:               SUBDIRS vs DIST_SUBDIRS.
                                                              (line   6)
* dmalloc, support for:                  Public Macros.       (line 123)
* dvi:                                   Texinfo.             (line  25)
* dvi <1>:                               Extending.           (line  41)
* DVI output using Texinfo:              Texinfo.             (line   6)
* dvi-local:                             Extending.           (line  41)
* E-mail, bug reports:                   Introduction.        (line  30)
* EDITION Texinfo flag:                  Texinfo.             (line  35)
* else:                                  Usage of Conditionals.
                                                              (line  36)
* Empty libraries:                       A Library.           (line  48)
* Empty libraries and $(LIBOBJS):        LIBOBJS.             (line  72)
* empty _SOURCES:                        Default _SOURCES.    (line  44)
* endif:                                 Usage of Conditionals.
                                                              (line  36)
* Example conditional --enable-debug:    Usage of Conditionals.
                                                              (line  21)
* Example conditional AC_CONFIG_FILES:   Usage of Conditionals.
                                                              (line  79)
* Example Hello World:                   Hello World.         (line   6)
* Example of recursive operation:        General Operation.   (line  58)
* Example of shared libraries:           Libtool Libraries.   (line   6)
* Example, EXTRA_PROGRAMS:               Uniform.             (line  36)
* Example, false and true:               true.                (line   6)
* Example, mixed language:               Mixing Fortran 77 With C and C++.
                                                              (line  34)
* Executable extension:                  EXEEXT.              (line   6)
* Exit status 77, special interpretation: Scripts-based Testsuites.
                                                              (line  27)
* Exit status 99, special interpretation: Scripts-based Testsuites.
                                                              (line  27)
* expected failure:                      Generalities about Testing.
                                                              (line  39)
* expected test failure:                 Generalities about Testing.
                                                              (line  39)
* Expected test failure:                 Scripts-based Testsuites.
                                                              (line  32)
* Extending aclocal:                     Extending aclocal.   (line   6)
* Extending list of installation directories: Uniform.        (line  56)
* Extension, executable:                 EXEEXT.              (line   6)
* Extra files distributed with Automake: automake Invocation. (line  39)
* EXTRA_, prepending:                    Uniform.             (line  29)
* EXTRA_PROGRAMS, defined:               Uniform.             (line  36)
* EXTRA_PROGRAMS, defined <1>:           Conditional Programs.
                                                              (line  15)
* EXTRA_prog_SOURCES, defined:           Conditional Sources. (line  18)
* false Example:                         true.                (line   6)
* FCFLAGS and AM_FCFLAGS:                Flag Variables Ordering.
                                                              (line  20)
* Features of the GNU Build System:      Use Cases.           (line   6)
* FFLAGS and AM_FFLAGS:                  Flag Variables Ordering.
                                                              (line  20)
* file names, limitations on:            Limitations on File Names.
                                                              (line   6)
* filename-length-max=99:                List of Automake options.
                                                              (line  44)
* Files distributed with Automake:       automake Invocation. (line  39)
* First line of Makefile.am:             General Operation.   (line  74)
* Flag variables, ordering:              Flag Variables Ordering.
                                                              (line   6)
* Flag Variables, Ordering:              Flag Variables Ordering.
                                                              (line  20)
* FLIBS, defined:                        Mixing Fortran 77 With C and C++.
                                                              (line  21)
* foreign:                               amhello's configure.ac Setup Explained.
                                                              (line  38)
* foreign <1>:                           List of Automake options.
                                                              (line   9)
* foreign strictness:                    Strictness.          (line  10)
* Fortran 77 support:                    Fortran 77 Support.  (line   6)
* Fortran 77, mixing with C and C++:     Mixing Fortran 77 With C and C++.
                                                              (line   6)
* Fortran 77, Preprocessing:             Preprocessing Fortran 77.
                                                              (line   6)
* Fortran 9x support:                    Fortran 9x Support.  (line   6)
* GCJFLAGS and AM_GCJFLAGS:              Flag Variables Ordering.
                                                              (line  20)
* generated files and CVS:               CVS.                 (line  49)
* generated files, distributed:          CVS.                 (line   9)
* Gettext support:                       gettext.             (line   6)
* git-dist:                              General Operation.   (line  12)
* git-dist, non-standard example:        General Operation.   (line  12)
* gnits:                                 List of Automake options.
                                                              (line   9)
* gnits strictness:                      Strictness.          (line  10)
* gnu:                                   List of Automake options.
                                                              (line   9)
* GNU Build System, basics:              Basic Installation.  (line   6)
* GNU Build System, features:            Use Cases.           (line   6)
* GNU Build System, introduction:        GNU Build System.    (line   6)
* GNU Build System, use cases:           Use Cases.           (line   6)
* GNU Coding Standards:                  GNU Build System.    (line  29)
* GNU Gettext support:                   gettext.             (line   6)
* GNU make extensions:                   General Operation.   (line  20)
* GNU Makefile standards:                Introduction.        (line  12)
* gnu strictness:                        Strictness.          (line  10)
* GNUmakefile including Makefile:        Third-Party Makefiles.
                                                              (line 111)
* hard error:                            Generalities about Testing.
                                                              (line  48)
* Header files in _SOURCES:              Program Sources.     (line  39)
* HEADERS primary, defined:              Headers.             (line   6)
* HEADERS, installation directories:     Headers.             (line   6)
* Hello World example:                   Hello World.         (line   6)
* hook targets:                          Extending.           (line  66)
* HP-UX 10, lex problems:                Public Macros.       (line  95)
* html:                                  Texinfo.             (line  25)
* html <1>:                              Extending.           (line  41)
* HTML output using Texinfo:             Texinfo.             (line   6)
* html-local:                            Extending.           (line  41)
* id:                                    Tags.                (line  43)
* if:                                    Usage of Conditionals.
                                                              (line  36)
* include:                               Basics of Distribution.
                                                              (line  17)
* include <1>:                           Include.             (line   6)
* include, distribution:                 Basics of Distribution.
                                                              (line  17)
* Including Makefile fragment:           Include.             (line   6)
* indentation in Makefile.am:            General Operation.   (line  33)
* info:                                  List of Automake options.
                                                              (line  93)
* info <1>:                              Extending.           (line  41)
* info-in-builddir:                      List of Automake options.
                                                              (line  53)
* info-local:                            Extending.           (line  41)
* install:                               Standard Targets.    (line  18)
* install <1>:                           The Two Parts of Install.
                                                              (line  14)
* install <2>:                           Extending.           (line  41)
* Install hook:                          Extending Installation.
                                                              (line  15)
* Install, two parts of:                 The Two Parts of Install.
                                                              (line  14)
* install-data:                          Two-Part Install.    (line  16)
* install-data <1>:                      The Two Parts of Install.
                                                              (line  14)
* install-data <2>:                      Extending.           (line  41)
* install-data-hook:                     Extending.           (line  66)
* install-data-local:                    Extending Installation.
                                                              (line   9)
* install-data-local <1>:                Extending.           (line  41)
* install-dvi:                           Texinfo.             (line  25)
* install-dvi <1>:                       Extending.           (line  41)
* install-dvi-local:                     Extending.           (line  41)
* install-exec:                          Two-Part Install.    (line  16)
* install-exec <1>:                      The Two Parts of Install.
                                                              (line  14)
* install-exec <2>:                      Extending.           (line  41)
* install-exec-hook:                     Extending.           (line  66)
* install-exec-local:                    Extending Installation.
                                                              (line   9)
* install-exec-local <1>:                Extending.           (line  41)
* install-html:                          Texinfo.             (line  25)
* install-html <1>:                      Extending.           (line  41)
* install-html-local:                    Extending.           (line  41)
* install-info:                          Texinfo.             (line  85)
* install-info <1>:                      List of Automake options.
                                                              (line  93)
* install-info <2>:                      Extending.           (line  41)
* install-info target:                   Texinfo.             (line  85)
* install-info-local:                    Extending.           (line  41)
* install-man:                           Man Pages.           (line  32)
* install-man <1>:                       List of Automake options.
                                                              (line  99)
* install-man target:                    Man Pages.           (line  32)
* install-pdf:                           Texinfo.             (line  25)
* install-pdf <1>:                       Extending.           (line  41)
* install-pdf-local:                     Extending.           (line  41)
* install-ps:                            Texinfo.             (line  25)
* install-ps <1>:                        Extending.           (line  41)
* install-ps-local:                      Extending.           (line  41)
* install-strip:                         Standard Targets.    (line  21)
* install-strip <1>:                     Install Rules for the User.
                                                              (line   7)
* Installation directories, extending list: Uniform.          (line  56)
* Installation support:                  Install.             (line   6)
* Installation, basics:                  Basic Installation.  (line   6)
* installcheck:                          Standard Targets.    (line  33)
* installcheck <1>:                      Extending.           (line  41)
* installcheck-local:                    Extending.           (line  41)
* installdirs:                           Install Rules for the User.
                                                              (line   7)
* installdirs <1>:                       Extending.           (line  41)
* installdirs-local:                     Extending.           (line  41)
* Installing headers:                    Headers.             (line   6)
* Installing scripts:                    Scripts.             (line   6)
* installing versioned binaries:         Extending.           (line  86)
* Interfacing with third-party packages: Third-Party Makefiles.
                                                              (line   6)
* Invocation of aclocal:                 aclocal Invocation.  (line   6)
* Invocation of automake:                automake Invocation. (line   6)
* Invoking aclocal:                      aclocal Invocation.  (line   6)
* Invoking automake:                     automake Invocation. (line   6)
* JAVA primary, defined:                 Java.                (line   6)
* JAVA restrictions:                     Java.                (line  27)
* Java support with gcj:                 Java Support with gcj.
                                                              (line   6)
* Java to bytecode, compilation:         Java.                (line   6)
* Java to native code, compilation:      Java Support with gcj.
                                                              (line   6)
* lazy test execution:                   Parallel Test Harness.
                                                              (line 118)
* LDADD and -l:                          Linking.             (line  70)
* LDFLAGS and AM_LDFLAGS:                Flag Variables Ordering.
                                                              (line  20)
* lex problems with HP-UX 10:            Public Macros.       (line  95)
* lex, multiple lexers:                  Yacc and Lex.        (line  68)
* LFLAGS and AM_LFLAGS:                  Flag Variables Ordering.
                                                              (line  20)
* libltdl, introduction:                 Libtool Concept.     (line  29)
* LIBOBJS, and Libtool:                  LTLIBOBJS.           (line   6)
* LIBOBJS, example:                      LIBOBJS.             (line   6)
* LIBOBJS, special handling:             LIBOBJS.             (line   6)
* LIBRARIES primary, defined:            A Library.           (line   6)
* libtool convenience libraries:         Libtool Convenience Libraries.
                                                              (line   6)
* libtool libraries, conditional:        Conditional Libtool Libraries.
                                                              (line   6)
* libtool library, definition:           Libtool Concept.     (line   6)
* libtool modules:                       Libtool Modules.     (line   6)
* Libtool modules, default source example: Default _SOURCES.  (line  38)
* libtool, introduction:                 Libtool Concept.     (line   6)
* LIBTOOLFLAGS and AM_LIBTOOLFLAGS:      Flag Variables Ordering.
                                                              (line  20)
* libtoolize and autoreconf:             Error required file ltmain.sh not found.
                                                              (line   6)
* libtoolize, no longer run by automake: Error required file ltmain.sh not found.
                                                              (line   6)
* Limitations of automake parser:        General Operation.   (line  33)
* Linking Fortran 77 with C and C++:     Mixing Fortran 77 With C and C++.
                                                              (line   6)
* LISP primary, defined:                 Emacs Lisp.          (line   6)
* LN_S example:                          Extending.           (line  86)
* local targets:                         Extending.           (line  37)
* LTALLOCA, special handling:            LTLIBOBJS.           (line   6)
* LTLIBOBJS, special handling:           LTLIBOBJS.           (line   6)
* LTLIBRARIES primary, defined:          Libtool Libraries.   (line   6)
* ltmain.sh not found:                   Error required file ltmain.sh not found.
                                                              (line   6)
* m4_include, distribution:              Basics of Distribution.
                                                              (line  17)
* Macro search path:                     Macro Search Path.   (line   6)
* macro serial numbers:                  Serials.             (line   6)
* Macros Automake recognizes:            Optional.            (line   6)
* maintainer-clean-local:                Clean.               (line  15)
* make check:                            Tests.               (line   6)
* make clean support:                    Clean.               (line   6)
* make dist:                             Basics of Distribution.
                                                              (line   6)
* make distcheck:                        Checking the Distribution.
                                                              (line   6)
* make distclean, diagnostic:            Errors with distclean.
                                                              (line   6)
* make distcleancheck:                   Checking the Distribution.
                                                              (line  70)
* make distuninstallcheck:               Checking the Distribution.
                                                              (line 106)
* make install support:                  Install.             (line   6)
* make installcheck, testing --help and --version: List of Automake options.
                                                              (line 129)
* Make rules, overriding:                General Operation.   (line  46)
* Make targets, overriding:              General Operation.   (line  46)
* Makefile fragment, including:          Include.             (line   6)
* Makefile.am, first line:               General Operation.   (line  74)
* Makefile.am, Hello World:              amhello's Makefile.am Setup Explained.
                                                              (line   6)
* Man page renaming, avoiding:           Man Pages.           (line  54)
* MANS primary, defined:                 Man Pages.           (line   6)
* many outputs, rules with:              Multiple Outputs.    (line   6)
* mdate-sh:                              Texinfo.             (line  35)
* MinGW cross-compilation example:       Cross-Compilation.   (line  25)
* missing, purpose:                      maintainer-mode.     (line   9)
* Mixed language example:                Mixing Fortran 77 With C and C++.
                                                              (line  34)
* Mixing Fortran 77 with C and C++:      Mixing Fortran 77 With C and C++.
                                                              (line   6)
* Mixing Fortran 77 with C and/or C++:   Mixing Fortran 77 With C and C++.
                                                              (line   6)
* mkdir -p, macro check:                 Obsolete Macros.     (line  14)
* modules, libtool:                      Libtool Modules.     (line   6)
* mostlyclean:                           Extending.           (line  41)
* mostlyclean-local:                     Clean.               (line  15)
* mostlyclean-local <1>:                 Extending.           (line  41)
* multiple configurations, example:      VPATH Builds.        (line  46)
* Multiple configure.ac files:           automake Invocation. (line   6)
* Multiple lex lexers:                   Yacc and Lex.        (line  68)
* multiple outputs, rules with:          Multiple Outputs.    (line   6)
* Multiple yacc parsers:                 Yacc and Lex.        (line  68)
* Nested packages:                       Nested Packages.     (line   6)
* Nesting packages:                      Subpackages.         (line   6)
* no-define:                             Public Macros.       (line  55)
* no-define <1>:                         List of Automake options.
                                                              (line  58)
* no-dependencies:                       Dependencies.        (line  34)
* no-dependencies <1>:                   List of Automake options.
                                                              (line  66)
* no-dist:                               List of Automake options.
                                                              (line  73)
* no-dist-gzip:                          List of Automake options.
                                                              (line  77)
* no-dist-gzip <1>:                      List of Automake options.
                                                              (line  77)
* no-exeext:                             List of Automake options.
                                                              (line  80)
* no-installinfo:                        Texinfo.             (line  85)
* no-installinfo <1>:                    List of Automake options.
                                                              (line  90)
* no-installinfo option:                 Texinfo.             (line  85)
* no-installman:                         Man Pages.           (line  32)
* no-installman <1>:                     List of Automake options.
                                                              (line  96)
* no-installman option:                  Man Pages.           (line  32)
* no-texinfo.tex:                        List of Automake options.
                                                              (line 106)
* nobase_ and dist_ or nodist_:          Alternative.         (line  29)
* nobase_ prefix:                        Alternative.         (line  23)
* nodist_ and nobase_:                   Alternative.         (line  29)
* nodist_ and notrans_:                  Man Pages.           (line  63)
* noinst_ primary prefix, definition:    Uniform.             (line  90)
* Non-GNU packages:                      Strictness.          (line   6)
* Non-standard targets:                  General Operation.   (line  12)
* nostdinc:                              List of Automake options.
                                                              (line 102)
* notrans_ and dist_ or nodist_:         Man Pages.           (line  63)
* notrans_ prefix:                       Man Pages.           (line  54)
* OBJCFLAGS and AM_OBJCFLAGS:            Flag Variables Ordering.
                                                              (line  20)
* OBJCXXFLAGS and AM_OBJCXXFLAGS:        Flag Variables Ordering.
                                                              (line  20)
* Objective C support:                   Objective C Support. (line   6)
* Objective C++ support:                 Objective C++ Support.
                                                              (line   6)
* Objects in subdirectory:               Program and Library Variables.
                                                              (line  51)
* obsolete macros:                       Obsolete Macros.     (line   6)
* optimized build, example:              VPATH Builds.        (line  46)
* Option, --warnings=CATEGORY:           List of Automake options.
                                                              (line 211)
* Option, -WCATEGORY:                    List of Automake options.
                                                              (line 211)
* Option, check-news:                    List of Automake options.
                                                              (line  14)
* Option, dejagnu:                       List of Automake options.
                                                              (line  18)
* Option, dist-bzip2:                    List of Automake options.
                                                              (line  22)
* Option, dist-lzip:                     List of Automake options.
                                                              (line  25)
* Option, dist-shar:                     List of Automake options.
                                                              (line  34)
* Option, dist-tarZ:                     List of Automake options.
                                                              (line  39)
* Option, dist-xz:                       List of Automake options.
                                                              (line  28)
* Option, dist-zip:                      List of Automake options.
                                                              (line  31)
* Option, filename-length-max=99:        List of Automake options.
                                                              (line  44)
* Option, foreign:                       List of Automake options.
                                                              (line   9)
* Option, gnits:                         List of Automake options.
                                                              (line   9)
* Option, gnu:                           List of Automake options.
                                                              (line   9)
* Option, info-in-builddir:              List of Automake options.
                                                              (line  53)
* Option, no-define:                     List of Automake options.
                                                              (line  58)
* Option, no-dependencies:               List of Automake options.
                                                              (line  66)
* Option, no-dist:                       List of Automake options.
                                                              (line  73)
* Option, no-dist-gzip:                  List of Automake options.
                                                              (line  77)
* Option, no-exeext:                     List of Automake options.
                                                              (line  80)
* Option, no-installinfo:                Texinfo.             (line  85)
* Option, no-installinfo <1>:            List of Automake options.
                                                              (line  90)
* Option, no-installman:                 Man Pages.           (line  32)
* Option, no-installman <1>:             List of Automake options.
                                                              (line  96)
* Option, no-texinfo.tex:                List of Automake options.
                                                              (line 106)
* Option, nostdinc:                      List of Automake options.
                                                              (line 102)
* Option, parallel-tests:                List of Automake options.
                                                              (line 114)
* Option, readme-alpha:                  List of Automake options.
                                                              (line 120)
* Option, serial-tests:                  List of Automake options.
                                                              (line 110)
* Option, tar-pax:                       List of Automake options.
                                                              (line 159)
* Option, tar-ustar:                     List of Automake options.
                                                              (line 159)
* Option, tar-v7:                        List of Automake options.
                                                              (line 159)
* Option, VERSION:                       List of Automake options.
                                                              (line 206)
* Option, warnings:                      List of Automake options.
                                                              (line 211)
* Options, aclocal:                      aclocal Options.     (line   6)
* Options, automake:                     automake Invocation. (line  37)
* Options, std-options:                  List of Automake options.
                                                              (line 129)
* Options, subdir-objects:               List of Automake options.
                                                              (line 150)
* Ordering flag variables:               Flag Variables Ordering.
                                                              (line   6)
* Overriding make rules:                 General Operation.   (line  46)
* Overriding make targets:               General Operation.   (line  46)
* Overriding make variables:             General Operation.   (line  51)
* overriding rules:                      Extending.           (line  26)
* overriding semantics:                  Extending.           (line  26)
* PACKAGE, directory:                    Uniform.             (line  19)
* PACKAGE, prevent definition:           Public Macros.       (line  55)
* Packages, nested:                      Nested Packages.     (line   6)
* Packages, preparation:                 Preparing Distributions.
                                                              (line   6)
* Parallel build trees:                  VPATH Builds.        (line   6)
* parallel-tests:                        List of Automake options.
                                                              (line 114)
* Path stripping, avoiding:              Alternative.         (line  23)
* pax format:                            List of Automake options.
                                                              (line 159)
* pdf:                                   Texinfo.             (line  25)
* pdf <1>:                               Extending.           (line  41)
* PDF output using Texinfo:              Texinfo.             (line   6)
* pdf-local:                             Extending.           (line  41)
* Per-object flags, emulated:            Per-Object Flags.    (line   6)
* per-target compilation flags, defined: Program and Library Variables.
                                                              (line 182)
* pkgdatadir, defined:                   Uniform.             (line  19)
* pkgincludedir, defined:                Uniform.             (line  19)
* pkglibdir, defined:                    Uniform.             (line  19)
* pkglibexecdir, defined:                Uniform.             (line  19)
* Preparing distributions:               Preparing Distributions.
                                                              (line   6)
* Preprocessing Fortran 77:              Preprocessing Fortran 77.
                                                              (line   6)
* Primary variable, DATA:                Data.                (line   6)
* Primary variable, defined:             Uniform.             (line  11)
* Primary variable, HEADERS:             Headers.             (line   6)
* Primary variable, JAVA:                Java.                (line   6)
* Primary variable, LIBRARIES:           A Library.           (line   6)
* Primary variable, LISP:                Emacs Lisp.          (line   6)
* Primary variable, LTLIBRARIES:         Libtool Libraries.   (line   6)
* Primary variable, MANS:                Man Pages.           (line   6)
* Primary variable, PROGRAMS:            Uniform.             (line  11)
* Primary variable, PYTHON:              Python.              (line   6)
* Primary variable, SCRIPTS:             Scripts.             (line   6)
* Primary variable, SOURCES:             Program Sources.     (line  32)
* Primary variable, TEXINFOS:            Texinfo.             (line   6)
* PROGRAMS primary variable:             Uniform.             (line  11)
* Programs, auxiliary:                   Auxiliary Programs.  (line   6)
* PROGRAMS, bindir:                      Program Sources.     (line   6)
* Programs, conditional:                 Conditional Programs.
                                                              (line   6)
* Programs, renaming during installation: Renaming.           (line   6)
* prog_LDADD, defined:                   Linking.             (line  12)
* Proxy Makefile for third-party packages: Third-Party Makefiles.
                                                              (line 128)
* ps:                                    Texinfo.             (line  25)
* ps <1>:                                Extending.           (line  41)
* PS output using Texinfo:               Texinfo.             (line   6)
* ps-local:                              Extending.           (line  41)
* PYTHON primary, defined:               Python.              (line   6)
* Ratfor programs:                       Preprocessing Fortran 77.
                                                              (line   6)
* read-only source tree:                 VPATH Builds.        (line  89)
* readme-alpha:                          List of Automake options.
                                                              (line 120)
* README-alpha:                          Gnits.               (line  42)
* rebuild rules:                         Rebuilding.          (line   6)
* rebuild rules <1>:                     CVS.                 (line   9)
* recheck:                               Parallel Test Harness.
                                                              (line 130)
* Recognized macros by Automake:         Optional.            (line   6)
* Recursive operation of Automake:       General Operation.   (line  58)
* recursive targets and third-party Makefiles: Third-Party Makefiles.
                                                              (line  15)
* Register test case result:             Log files generation and test results recording.
                                                              (line  24)
* Register test result:                  Log files generation and test results recording.
                                                              (line  24)
* Renaming programs:                     Renaming.            (line   6)
* Reporting bugs:                        Introduction.        (line  30)
* Requirements of Automake:              Requirements.        (line   6)
* Requirements, Automake:                Introduction.        (line  26)
* Restrictions for JAVA:                 Java.                (line  27)
* reStructuredText field, :copy-in-global-log:: Log files generation and test results recording.
                                                              (line  44)
* reStructuredText field, :recheck::     Log files generation and test results recording.
                                                              (line  38)
* reStructuredText field, :test-global-result:: Log files generation and test results recording.
                                                              (line  54)
* reStructuredText field, :test-result:: Log files generation and test results recording.
                                                              (line  24)
* RFLAGS and AM_RFLAGS:                  Flag Variables Ordering.
                                                              (line  20)
* rules with multiple outputs:           Multiple Outputs.    (line   6)
* rules, conflicting:                    Extending.           (line  14)
* rules, debugging:                      Debugging Make Rules.
                                                              (line   6)
* rules, overriding:                     Extending.           (line  26)
* Scanning configure.ac:                 configure.           (line   6)
* SCRIPTS primary, defined:              Scripts.             (line   6)
* SCRIPTS, installation directories:     Scripts.             (line  18)
* Selecting the linker automatically:    How the Linker is Chosen.
                                                              (line   6)
* serial number and --install:           aclocal Options.     (line  38)
* serial numbers in macros:              Serials.             (line   6)
* serial-tests:                          List of Automake options.
                                                              (line 110)
* serial-tests, Using:                   Serial Test Harness. (line   6)
* Shared libraries, support for:         A Shared Library.    (line   6)
* Silencing make:                        Silencing Make.      (line   6)
* Silent make:                           Silencing Make.      (line   6)
* Silent make rules:                     Silencing Make.      (line   6)
* Silent rules:                          Silencing Make.      (line   6)
* silent rules and libtool:              Automake Silent Rules.
                                                              (line  59)
* site.exp:                              DejaGnu Tests.       (line  26)
* source tree and build tree:            VPATH Builds.        (line   6)
* source tree, read-only:                VPATH Builds.        (line  89)
* SOURCES primary, defined:              Program Sources.     (line  32)
* Special Automake comment:              General Operation.   (line  68)
* Staged installation:                   DESTDIR.             (line  14)
* std-options:                           List of Automake options.
                                                              (line 129)
* Strictness, command line:              automake Invocation. (line  37)
* Strictness, defined:                   Strictness.          (line  10)
* Strictness, foreign:                   Strictness.          (line  10)
* Strictness, gnits:                     Strictness.          (line  10)
* Strictness, gnu:                       Strictness.          (line  10)
* su, before make install:               Basic Installation.  (line  49)
* subdir-objects:                        List of Automake options.
                                                              (line 150)
* Subdirectories, building conditionally: Conditional Subdirectories.
                                                              (line   6)
* Subdirectories, configured conditionally: Unconfigured Subdirectories.
                                                              (line   6)
* Subdirectories, not distributed:       Unconfigured Subdirectories.
                                                              (line  55)
* Subdirectory, objects in:              Program and Library Variables.
                                                              (line  51)
* SUBDIRS and AC_SUBST:                  Subdirectories with AC_SUBST.
                                                              (line   6)
* SUBDIRS and AM_CONDITIONAL:            Subdirectories with AM_CONDITIONAL.
                                                              (line   6)
* SUBDIRS, conditional:                  Conditional Subdirectories.
                                                              (line   6)
* SUBDIRS, explained:                    Subdirectories.      (line   6)
* Subpackages:                           Nested Packages.     (line   6)
* Subpackages <1>:                       Subpackages.         (line   6)
* suffix .la, defined:                   Libtool Concept.     (line   6)
* suffix .lo, defined:                   Libtool Concept.     (line  15)
* SUFFIXES, adding:                      Suffixes.            (line   6)
* Support for C++:                       C++ Support.         (line   6)
* Support for Fortran 77:                Fortran 77 Support.  (line   6)
* Support for Fortran 9x:                Fortran 9x Support.  (line   6)
* Support for GNU Gettext:               gettext.             (line   6)
* Support for Java with gcj:             Java Support with gcj.
                                                              (line   6)
* Support for Objective C:               Objective C Support. (line   6)
* Support for Objective C++:             Objective C++ Support.
                                                              (line   6)
* Support for Unified Parallel C:        Unified Parallel C Support.
                                                              (line   6)
* Support for Vala:                      Vala Support.        (line   6)
* tags:                                  Tags.                (line   9)
* TAGS support:                          Tags.                (line   6)
* tar formats:                           List of Automake options.
                                                              (line 159)
* tar-pax:                               List of Automake options.
                                                              (line 159)
* tar-ustar:                             List of Automake options.
                                                              (line 159)
* tar-v7:                                List of Automake options.
                                                              (line 159)
* Target, install-info:                  Texinfo.             (line  85)
* Target, install-man:                   Man Pages.           (line  32)
* test case:                             Generalities about Testing.
                                                              (line  11)
* Test case result, registering:         Log files generation and test results recording.
                                                              (line  24)
* test failure:                          Generalities about Testing.
                                                              (line  25)
* test harness:                          Generalities about Testing.
                                                              (line  18)
* test metadata:                         Parallel Test Harness.
                                                              (line  12)
* test pass:                             Generalities about Testing.
                                                              (line  25)
* Test result, registering:              Log files generation and test results recording.
                                                              (line  24)
* test skip:                             Generalities about Testing.
                                                              (line  29)
* Test suites:                           Tests.               (line   6)
* Tests, expected failure:               Scripts-based Testsuites.
                                                              (line  32)
* testsuite harness:                     Generalities about Testing.
                                                              (line  18)
* Testsuite progress on console:         Scripts-based Testsuites.
                                                              (line  45)
* Texinfo flag, EDITION:                 Texinfo.             (line  35)
* Texinfo flag, UPDATED:                 Texinfo.             (line  35)
* Texinfo flag, UPDATED-MONTH:           Texinfo.             (line  35)
* Texinfo flag, VERSION:                 Texinfo.             (line  35)
* texinfo.tex:                           Texinfo.             (line  70)
* TEXINFOS primary, defined:             Texinfo.             (line   6)
* third-party files and CVS:             CVS.                 (line 167)
* Third-party packages, interfacing with: Third-Party Makefiles.
                                                              (line   6)
* timestamps and CVS:                    CVS.                 (line  28)
* Transforming program names:            Renaming.            (line   6)
* trees, source vs. build:               VPATH Builds.        (line   6)
* true Example:                          true.                (line   6)
* underquoted AC_DEFUN:                  Extending aclocal.   (line  36)
* unexpected pass:                       Generalities about Testing.
                                                              (line  39)
* unexpected test pass:                  Generalities about Testing.
                                                              (line  39)
* Unified Parallel C support:            Unified Parallel C Support.
                                                              (line   6)
* Uniform naming scheme:                 Uniform.             (line   6)
* uninstall:                             Standard Targets.    (line  24)
* uninstall <1>:                         Install Rules for the User.
                                                              (line   7)
* uninstall <2>:                         Extending.           (line  41)
* uninstall-hook:                        Extending.           (line  66)
* uninstall-local:                       Extending.           (line  41)
* Unit tests:                            Parallel Test Harness.
                                                              (line 154)
* Unpacking:                             Basic Installation.  (line  27)
* UPCFLAGS and AM_UPCFLAGS:              Flag Variables Ordering.
                                                              (line  20)
* UPDATED Texinfo flag:                  Texinfo.             (line  35)
* UPDATED-MONTH Texinfo flag:            Texinfo.             (line  35)
* Use Cases for the GNU Build System:    Use Cases.           (line   6)
* user variables:                        User Variables.      (line   6)
* Using aclocal:                         configure.           (line   6)
* ustar format:                          List of Automake options.
                                                              (line 159)
* v7 tar format:                         List of Automake options.
                                                              (line 159)
* Vala Support:                          Vala Support.        (line   6)
* variables, conflicting:                Extending.           (line  14)
* Variables, overriding:                 General Operation.   (line  51)
* variables, reserved for the user:      User Variables.      (line   6)
* VERSION Texinfo flag:                  Texinfo.             (line  35)
* VERSION, prevent definition:           Public Macros.       (line  55)
* version.m4, example:                   Rebuilding.          (line  12)
* version.sh, example:                   Rebuilding.          (line  12)
* versioned binaries, installing:        Extending.           (line  86)
* VPATH builds:                          VPATH Builds.        (line   6)
* wildcards:                             Wildcards.           (line   6)
* Windows:                               EXEEXT.              (line   6)
* xfail:                                 Generalities about Testing.
                                                              (line  39)
* xpass:                                 Generalities about Testing.
                                                              (line  39)
* yacc, multiple parsers:                Yacc and Lex.        (line  68)
* YFLAGS and AM_YFLAGS:                  Flag Variables Ordering.
                                                              (line  20)
* ylwrap:                                Yacc and Lex.        (line  68)
* zardoz example:                        Complete.            (line  35)