This is automake.info, produced by makeinfo version 6.8 from automake.texi. This manual is for GNU Automake (version 1.16.5, 1 October 2021), a program that creates GNU standards-compliant Makefiles from template files. Copyright © 1995–2021 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: Install, Next: Clean, Prev: Documentation, Up: Top 12 What Gets Installed ********************** Naturally, Automake handles the details of installing your program once it has been built. All files named by the various primaries are automatically installed in the appropriate places when the user runs ‘make install’. * Menu: * Basics of Installation:: What gets installed where * The Two Parts of Install:: Installing data and programs separately * Extending Installation:: Adding your own rules for installation * Staged Installs:: Installation in a temporary location * Install Rules for the User:: Useful additional rules  File: automake.info, Node: Basics of Installation, Next: The Two Parts of Install, Up: Install 12.1 Basics of Installation =========================== A file named in a primary is installed by copying the built file into the appropriate directory. The base name of the file is used when installing. bin_PROGRAMS = hello subdir/goodbye In this example, both ‘hello’ and ‘goodbye’ will be installed in ‘$(bindir)’. Sometimes it is useful to avoid the basename step at install time. For instance, you might have a number of header files in subdirectories of the source tree that are laid out precisely how you want to install them. In this situation you can use the ‘nobase_’ prefix to suppress the base name step. For example: nobase_include_HEADERS = stdio.h sys/types.h will install ‘stdio.h’ in ‘$(includedir)’ and ‘types.h’ in ‘$(includedir)/sys’. For most file types, Automake will install multiple files at once, while avoiding command line length issues (*note Length Limitations::). Since some ‘install’ programs will not install the same file twice in one invocation, you may need to ensure that file lists are unique within one variable such as ‘nobase_include_HEADERS’ above. You should not rely on the order in which files listed in one variable are installed. Likewise, to cater for parallel make, you should not rely on any particular file installation order even among different file types (library dependencies are an exception here).  File: automake.info, Node: The Two Parts of Install, Next: Extending Installation, Prev: Basics of Installation, Up: Install 12.2 The Two Parts of Install ============================= Automake generates separate ‘install-data’ and ‘install-exec’ rules, in case the installer is installing on multiple machines that share directory structure—these targets allow the machine-independent parts to be installed only once. ‘install-exec’ installs platform-dependent files, and ‘install-data’ installs platform-independent files. The ‘install’ target depends on both of these targets. While Automake tries to automatically segregate objects into the correct category, the ‘Makefile.am’ author is, in the end, responsible for making sure this is done correctly. Variables using the standard directory prefixes ‘data’, ‘info’, ‘man’, ‘include’, ‘oldinclude’, ‘pkgdata’, or ‘pkginclude’ are installed by ‘install-data’. Variables using the standard directory prefixes ‘bin’, ‘sbin’, ‘libexec’, ‘sysconf’, ‘localstate’, ‘lib’, or ‘pkglib’ are installed by ‘install-exec’. For instance, ‘data_DATA’ files are installed by ‘install-data’, while ‘bin_PROGRAMS’ files are installed by ‘install-exec’. Any variable using a user-defined directory prefix with ‘exec’ in the name (e.g., ‘myexecbin_PROGRAMS’) is installed by ‘install-exec’. All other user-defined prefixes are installed by ‘install-data’.  File: automake.info, Node: Extending Installation, Next: Staged Installs, Prev: The Two Parts of Install, Up: Install 12.3 Extending Installation =========================== It is possible to extend this mechanism by defining an ‘install-exec-local’ or ‘install-data-local’ rule. If these rules exist, they will be run at ‘make install’ time. These rules can do almost anything; care is required. Automake also supports two install hooks, ‘install-exec-hook’ and ‘install-data-hook’. These hooks are run after all other install rules of the appropriate type, exec or data, have completed. So, for instance, it is possible to perform post-installation modifications using an install hook. *Note Extending::, for some examples.  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/or other flavors of archives 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 set the environment variable ‘TAR’ to override the tar program used; it defaults to ‘tar’. *Note The Types of Distributions::, for how to generate other kinds of archives. 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. • Files that are read by ‘configure’ are automatically distributed. These are the source files as specified in various Autoconf macros such as ‘AC_CONFIG_FILES’ and siblings. • Files included in a ‘Makefile.am’ (using ‘include’) or in ‘configure.ac’ (using ‘m4_include’). • Automake has a built-in list of commonly used files automatically included in the distribution if they are found in the current directory (either physically, or as the target of a ‘Makefile.am’ rule). Some common examples: ‘ABOUT-GNU’, ‘COPYING’, ‘TODO’. This list also includes helper scripts installed with ‘automake --add-missing’. Some common examples: ‘compile’, ‘config.guess’, ‘config.rpath’, ‘config.sub’, ‘texinfo.tex’. • Automake has another built-in list of files automatically distributed if they are found either with the plain name, or with extension ‘.md’ (presumably MarkDown, though this not checked). They are checked for in that order, so the plain name is preferred. These are: ‘AUTHORS ChangeLog INSTALL NEWS README README-alpha THANKS’. • A final built-in list of files are those distributed only if other certain conditions hold. For example, the files ‘config.h.top’ and ‘config.h.bot’ are automatically distributed only if, e.g., ‘AC_CONFIG_HEADERS([config.h])’ is used in ‘configure.ac’). ‘README-alpha’ is another such file, with ‘README-alpha.md’ distributed if that is what is available; *note Strictness::, for its conditions for distribution. These three lists of files are given in their entirety in the output from ‘automake --help’. Despite all this automatic inclusion, it is still common to have files to be distributed which are not found by the automatic rules. You should listed these files in the ‘EXTRA_DIST’ variable. You can mention files in 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. To emphasize, this copies _everything_ in the directory, including temporary editor files, intermediate build files, version control files, etc.; 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: chmod -R u+w $(distdir)/doc rm -rf `find $(distdir)/doc -type d -name RCS` The ‘dist-hook’ recipe should not 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. Similarly, the recipe should not assume that the subdirectories put into the distribution directory as a result of being 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`" >> $(distdir)/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 either a relative or absolute path; do not assume a particular 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)’ can also be either a relative or absolute path. 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 (in this order): • tries to do a ‘VPATH’ build (*note VPATH Builds::), with the ‘srcdir’ and all its content made _read-only_; • tries to make the printable documentation, if any (with ‘make dvi’), • runs the test suite (with ‘make check’) on this fresh build; • installs the package in a temporary directory (with ‘make install’), and runs the test suite on the resulting installation (with ‘make installcheck’); • checks that the package can be correctly uninstalled (by ‘make uninstall’) and cleaned (by ‘make distclean’); • finally, makes another tarball to ensure the distribution is self-contained. All of these actions are performed in a temporary directory. The exact location and the exact structure of such a directory (where the read-only sources are placed, how the temporary build and install directories are named and how deeply they are nested, etc.) is to be considered an implementation detail, which can change at any time; so do not rely on it. DISTCHECK_CONFIGURE_FLAGS ------------------------- Building the package involves running ‘./configure’. If you need to supply additional flags to ‘configure’, define them in the ‘AM_DISTCHECK_CONFIGURE_FLAGS’ variable in your top-level ‘Makefile.am’. The user can still extend or override the flags provided there by defining the ‘DISTCHECK_CONFIGURE_FLAGS’ variable, on the command line when invoking ‘make’. It’s worth noting that ‘make distcheck’ needs complete control over the ‘configure’ options ‘--srcdir’ and ‘--prefix’, so those options cannot be overridden by ‘AM_DISTCHECK_CONFIGURE_FLAGS’ nor by ‘DISTCHECK_CONFIGURE_FLAGS’. Also note that developers are encouraged to strive to make their code buildable without requiring any special configure option; thus, in general, you shouldn’t define ‘AM_DISTCHECK_CONFIGURE_FLAGS’. However, there might be few scenarios in which the use of this variable is justified. GNU ‘m4’ offers an example. GNU ‘m4’ configures by default with its experimental and seldom used "changeword" feature disabled; so in this case it is useful to have ‘make distcheck’ run configure with the ‘--with-changeword’ option, to ensure that the code for changeword support still compiles correctly. GNU ‘m4’ also employs the ‘AM_DISTCHECK_CONFIGURE_FLAGS’ variable to stress-test the use of ‘--program-prefix=g’, since at one point the ‘m4’ build system had a bug where ‘make installcheck’ was wrongly assuming it could blindly test "‘m4’", rather than the just-installed "‘gm4’". dvi and distcheck ----------------- Ordinarily, ‘make distcheck’ runs ‘make dvi’. It does nothing if the distribution contains no Texinfo sources. If the distribution does contain a Texinfo manual, by default the ‘dvi’ target will run TeX to make sure it can be successfully processed (*note Texinfo::). However, you may wish to test the manual by producing ‘pdf’ (e.g., if your manual uses images in formats other than ‘eps’), ‘html’ (if you don’t have TeX at all), some other format, or just skip the test entirely (not recommended). You can change the target that is run by setting the variable ‘AM_DISTCHECK_DVI_TARGET’ in your ‘Makefile.am’; for example, AM_DISTCHECK_DVI_TARGET = pdf To make ‘dvi’ into a do-nothing target, see the example for ‘EMPTY_AUTOMAKE_TARGETS’ in *note Third-Party Makefiles::. 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 builds the package. (Think about the user missing the tool required to build the file; or if the required tool is built by your package, consider the cross-compilation case where it can’t be run.) There is an entry in the FAQ about this (*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. By default, this rule makes ‘gzip’ use a compression option of ‘--best’. To make it use a different one, set the ‘GZIP_ENV’ environment variable. For example, ‘make dist-gzip GZIP_ENV=-7’. ‘dist-bzip2’ Generate a ‘bzip2’ tar archive of the distribution. bzip2 archives are usually 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. ‘dist-lzip’ Generate an ‘lzip’ tar archive of the distribution. ‘lzip’ archives are usually smaller than ‘bzip2’-compressed archives. By default, this rule makes ‘lzip’ use a compression option of ‘-9’. To make it use a different one, set the ‘LZIP_OPT’ environment variable. ‘dist-xz’ Generate an ‘xz’ tar archive of the distribution. ‘xz’ archives are usually 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-zstd’ Generate a ‘zstd’ tar archive of the distribution. By default, this rule makes ‘zstd’ use a compression option of ‘-19’. To use a different setting, set the ‘ZSTD_OPT’ environment variable. For example, run this command to use the default compression ratio, but with a progress indicator: ‘make dist-zstd ZSTD_OPT=-19v’. However, note that for compatibility with ‘zstd’ itself, you may instead set the ‘ZSTD_CLEVEL’ environment variable, in which case, any ‘ZSTD_OPT’ setting is ignored. ‘dist-shar’ Generate a ‘shar’ archive of the distribution. This format archive is obsolescent, and use of this option is deprecated. It and the corresponding functionality will be removed altogether in Automake 2.0. ‘dist-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. 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 enabled by ‘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 reports or registers these outcomes appropriately. Again, the details of how this is accomplished (and how the developer and user can influence it or interface with it) varies wildly, and we’ll attempt no precise definition. A test is said to _pass_ when it can determine that the condition or behaviour it means to verify holds, and is said to _fail_ when it can determine that such condition of behaviour does _not_ hold. Sometimes, tests can rely on non-portable tools or prerequisites, or simply make no sense on a given system (for example, a test checking a Windows-specific feature makes no sense on a GNU/Linux system). In this case, accordingly to the definition above, the tests can neither be considered passed nor failed; instead, they are _skipped_, that is, they are not run, or their result is in any case ignored for what concerns the count of failures and successes. Skips are usually explicitly reported though, so that the user will be aware that not all of the testsuite has been run. It’s not uncommon, especially during early development stages, that some tests fail for known reasons, and that the developer doesn’t want to tackle these failures immediately (this is especially true when the failing tests deal with corner cases). In this situation, the better policy is to declare that each of those failures is an _expected failure_ (or _xfail_). In case a test that is expected to fail ends up passing instead, many testing environments will flag the result as a special kind of failure called _unexpected pass_ (or _xpass_). Many testing environments and frameworks distinguish between test failures and hard errors. As we’ve seen, a test failure happens when some invariant or expected behaviour of the software under test is not met. A _hard error_ happens when e.g., the set-up of a test case scenario fails, or when some other unexpected or highly undesirable condition is encountered (for example, the program under test experiences a segmentation fault).  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::). 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 a hard error, and any other exit status will denote a failure. You may define the variable ‘XFAIL_TESTS’ to a list of tests (usually a subset of ‘TESTS’) that are expected to fail; this will effectively reverse the result of those tests (with the provision that skips and hard errors remain untouched). You may also instruct the testsuite harness to treat hard errors like simple failures, by defining the ‘DISABLE_HARD_ERRORS’ make variable to a nonempty value. Note however that, for tests based on more complex test protocols, the exact effects of ‘XFAIL_TESTS’ and ‘DISABLE_HARD_ERRORS’ might change, or they might even have no effect at all (for example, in tests using TAP, there is no way to disable hard errors, and the ‘DISABLE_HARD_ERRORS’ variable has no effect on them). The result of each test case run by the scripts in ‘TESTS’ will be printed on standard output, along with the test name. For test protocols that allow more test cases per test script (such as TAP), a number, identifier and/or brief description specific for the single test case is expected to be printed in addition to the name of the test script. The possible results (whose meanings should be clear from the previous *note Generalities about Testing::) are ‘PASS’, ‘FAIL’, ‘SKIP’, ‘XFAIL’, ‘XPASS’ and ‘ERROR’. Here is an example of output from a hypothetical testsuite that uses both plain and TAP tests: PASS: foo.sh PASS: zardoz.tap 1 - Daemon started PASS: zardoz.tap 2 - Daemon responding SKIP: zardoz.tap 3 - Daemon uses /proc # SKIP /proc is not mounted PASS: zardoz.tap 4 - Daemon stopped SKIP: bar.sh PASS: mu.tap 1 XFAIL: mu.tap 2 # TODO frobnication not yet implemented A testsuite summary (expected to report at least the number of run, skipped and failed tests) will be printed at the end of the testsuite run. By default, the first line of the summary has the form: Testsuite summary for PACKAGE-STRING where PACKAGE-STRING is the name and version of the package. If you have several independent test suites for different parts of the package, though, it can be misleading for each suite to imply it is for the whole package. Or, in complex projects, you may wish to add the current directory or other information to the testsuite header line. So you can override the ‘ for PACKAGE-STRING’ suffix on that line by setting the ‘AM_TESTSUITE_SUMMARY_HEADER’ variable. The value of this variable is used unquoted in a shell echo command, so you must include any necessary quotes. For example, the default value is AM_TESTSUITE_SUMMARY_HEADER = ' for $(PACKAGE_STRING)' including the double quotes (interpreted by the shell) and the leading space (since the value is output directly after the ‘Testsuite summary’). The ‘$(PACKAGE_STRING)’ is substituted by ‘make’. 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::). 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’. The programs in ‘check_PROGRAMS’ are _not_ automatically added to ‘TESTS’ because ‘check_PROGRAMS’ usually lists programs used by the tests, not the tests themselves. If all your programs are in fact test cases, you can set ‘TESTS = $(check_PROGRAMS)’. * Menu: * Testsuite Environment Overrides::  File: automake.info, Node: Testsuite Environment Overrides, Up: Scripts-based Testsuites 15.2.1.1 Testsuite Environment Overrides ........................................ 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 As another example, a notice that a test is starting can be emitted using ‘AM_TESTS_ENVIRONMENT’ (for package maintainers) or ‘TESTS_ENVIRONMENT’ by users: make -j12 ... TESTS_ENVIRONMENT='echo RUNNING: "$$f";' check The shell variable ‘$f’ contains the test name. (Although technically this is not guaranteed, in practice it is extremely unlikely to ever change.) This can be helpful to see when trying to debug test failures. Notwithstanding these benefits, ‘AM_TESTS_ENVIRONMENT’ is, for historical and implementation reasons, _not_ supported by the serial harness (*note Serial Test Harness::).  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 a _few_ situations when the advantages offered by the parallel harness are irrelevant, and when test concurrency can even cause tricky problems. In those cases, it might make sense to still use the serial harness, for simplicity and reliability (we still suggest trying to give the parallel harness a shot though). The serial test harness is enabled by the Automake option ‘serial-tests’. It operates by simply running the tests serially, one at the time, without any I/O redirection. It’s up to the user to implement logging of tests’ output, if that’s required or desired. For historical and implementation reasons, the ‘AM_TESTS_ENVIRONMENT’ variable is _not_ supported by this harness (it will be silently ignored if defined); only ‘TESTS_ENVIRONMENT’ is, and it is to be considered a developer-reserved variable. This is done so that, when using the serial harness, ‘TESTS_ENVIRONMENT’ can be defined to an invocation of an interpreter through which the tests are to be run. For instance, the following setup may be used to run tests with Perl: TESTS_ENVIRONMENT = $(PERL) -Mstrict -w TESTS = foo.pl bar.pl baz.pl It’s important to note that the use of ‘TESTS_ENVIRONMENT’ endorsed here would be _invalid_ with the parallel harness. That harness provides a more elegant way to achieve the same effect, with the further benefit of freeing the ‘TESTS_ENVIRONMENT’ variable for the user (*note Parallel Test Harness::). Another, less serious limitation of the serial harness is that it doesn’t distinguish between simple failures and hard errors; this is for historical reasons, 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 used to define a custom test runner; the ‘LOG_COMPILER’ and ‘LOG_FLAGS’ (or their extension-specific counterparts) should be used instead: ## This is WRONG! AM_TESTS_ENVIRONMENT = PERL5LIB='$(srcdir)/lib' $(PERL) -Mstrict -w ## Do this instead. AM_TESTS_ENVIRONMENT = PERL5LIB='$(srcdir)/lib'; export PERL5LIB; LOG_COMPILER = $(PERL) AM_LOG_FLAGS = -Mstrict -w By default, the test suite harness will run all tests, but there are several ways to limit the set of tests that are run: • You can set the ‘TESTS’ variable. For example, you can use a command like this to run only a subset of the tests: env TESTS="foo.test bar.test" make -e check If you’re using a recursive make setup, you’ll probably also need to override ‘SUBDIRS’: env TESTS="foo.test bar.test" make -e check SUBDIRS= Otherwise, the test harness will descend into all subdirectories, where the tests presumably do not exist, and thus fail. (Patch to provide better behavior would be welcome.) Another issue: the command above will unconditionally overwrite the ‘test-suite.log’ file, thus clobbering the recorded results of any previous testsuite run. This might be undesirable for packages whose testsuite takes a long time to execute. Luckily, this problem can easily be avoided by also overriding ‘TEST_SUITE_LOG’ at runtime; for example, env TEST_SUITE_LOG=partial.log TESTS="..." make -e check will write the result of the partial testsuite runs to the ‘partial.log’, without touching ‘test-suite.log’. • You can set the ‘TEST_LOGS’ variable. By default, this variable is computed at ‘make’ run time from the value of ‘TESTS’ as described above. For example, you can use the following: set x subset*.log; shift env TEST_LOGS="foo.log $*" make -e check The comments made above about ‘TEST_SUITE_LOG’ overriding applies here too. • By default, the test harness removes all old per-test ‘.log’ and ‘.trs’ files before it starts running tests to regenerate them. The variable ‘RECHECK_LOGS’ contains the set of ‘.log’ (and, by implication, ‘.trs’) files which are removed. ‘RECHECK_LOGS’ defaults to ‘TEST_LOGS’, which means all tests need to be rechecked. By overriding this variable, you can choose which tests need to be reconsidered. For example, you can lazily rerun only those tests which are outdated, i.e., older than their prerequisite test files, by setting this variable to the empty value: env RECHECK_LOGS= make -e check • You can ensure that all tests are rerun which have failed or passed unexpectedly, by running ‘make recheck’ in the test directory. This convenience target will set ‘RECHECK_LOGS’ appropriately before invoking the main test harness. In order to guarantee an ordering between tests even with ‘make -jN’, dependencies between the corresponding ‘.log’ files may be specified through usual ‘make’ dependencies. For example, the following snippet lets the test named ‘foo-execute.test’ depend upon completion of the test ‘foo-compile.test’: TESTS = foo-compile.test foo-execute.test foo-execute.log: foo-compile.log Please note that this ordering ignores the _results_ of required tests, thus the test ‘foo-execute.test’ is run even if the test ‘foo-compile.test’ failed or was skipped beforehand. Further, please note that specifying such dependencies currently works only for tests that end in one of the suffixes listed in ‘TEST_EXTENSIONS’. Tests without such specified dependencies may be run concurrently with parallel ‘make -jN’, so be sure they are prepared for concurrent execution. The combination of lazy test execution and correct dependencies between tests and their sources may be exploited for efficient unit testing during development. To further speed up the edit-compile-test cycle, it may even be useful to specify compiled programs in ‘EXTRA_PROGRAMS’ instead of with ‘check_PROGRAMS’, as the former allows intertwined compilation and test execution (but note that ‘EXTRA_PROGRAMS’ are not cleaned automatically; *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 interpret the output emitted by the test script they’re running (examples of such protocols are TAP and SubUnit). It’s very important to note that, even when using custom test drivers, most of the infrastructure described in the previous section about the parallel harness remains in place; this includes: • list of test scripts defined in ‘TESTS’, and overridable at runtime through the redefinition of ‘TESTS’ or ‘TEST_LOGS’; • concurrency through the use of ‘make’’s option ‘-j’; • per-test ‘.log’ and ‘.trs’ files, and generation of a summary ‘.log’ file from them; • ‘recheck’ target, ‘RECHECK_LOGS’ variable, and lazy reruns of tests; • inter-test dependencies; • support for ‘check_*’ variables (‘check_PROGRAMS’, ‘check_LIBRARIES’, ...); • use of ‘VERBOSE’ environment variable to get verbose output on testsuite failures; • definition and honoring of ‘TESTS_ENVIRONMENT’, ‘AM_TESTS_ENVIRONMENT’ and ‘AM_TESTS_FD_REDIRECT’ variables; • definition of generic and extension-specific ‘LOG_COMPILER’ and ‘LOG_FLAGS’ variables. On the other hand, the exact semantics of how (and if) testsuite output colorization, ‘XFAIL_TESTS’, and hard errors are supported and handled is left to the individual test drivers.  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 tightening and possibly extensive changes in the future, to accommodate for new features or to satisfy additional portability requirements. The main characteristic of these APIs is that they are designed to share as much infrastructure, semantics, and implementation detail as possible with the parallel test harness and its default driver. * 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 runs 10 test cases, 6 of which pass and 4 of which are skipped, could reasonably have a ‘PASS/SKIP’ value for this field, while a test script which runs 19 successful tests and one failed test could have an ‘ALMOST PASSED’ value. What happens when two or more ‘:test-global-result:’ fields are present in the same ‘.trs’ file is undefined behaviour. Let’s see a small example. Assume a ‘.trs’ file contains the following lines: :test-result: PASS server starts :global-log-copy: no :test-result: PASS HTTP/1.1 request :test-result: FAIL HTTP/1.0 request :recheck: yes :test-result: SKIP HTTPS request (TLS library wasn't available) :test-result: PASS server stops Then the corresponding test script will be re-run by ‘make check’, will contribute with _five_ test results to the testsuite summary (three of these tests being successful, one failed, and one skipped), and the content of the corresponding ‘.log’ file will _not_ be copied into the global log file ‘test-suite.log’.  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 compatible as possible with pre-existing and widespread utilities, such as the ‘prove’ utility (https://metacpan.org/pod/distribution/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’ (https://metacpan.org/pod/Test::Harness). The most relevant real-world usages of TAP are obviously in the testsuites of ‘perl’ and of many Perl modules. Still, other important third-party packages, such as ‘git’ (https://git-scm.com/), also 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::), ‘tap-driver.sh’ supports the following options, whose names are chosen for enhanced compatibility with the ‘prove’ utility. ‘--ignore-exit’ Causes the test driver to ignore the exit status of the test scripts; by default, the driver will report an error if the script exits with a non-zero status. This option has effect also on non-zero exit statuses due to termination by a signal. ‘--comments’ Instruct the test driver to display TAP diagnostics (i.e., lines beginning with the ‘#’ character) in the testsuite progress output too; by default, TAP diagnostics are only copied to the ‘.log’ file. ‘--no-comments’ Revert the effects of ‘--comments’. ‘--merge’ Instruct the test driver to merge the test scripts’ standard error into their standard output. This is necessary if you want to ensure that diagnostics from the test scripts are displayed in the correct order relative to test results; this can be of great help in debugging (especially if your test scripts are shell scripts run with shell tracing active). As a downside, this option might cause the test harness to get confused if anything that appears on standard error looks like a test result. ‘--no-merge’ Revert the effects of ‘--merge’. ‘--diagnostic-string=STRING’ Change the string that introduces TAP diagnostics from the default value of “‘#’” to ‘STRING’. This can be useful if your TAP-based test scripts produce verbose output on which they have limited control (because, say, the output comes from other tools invoked in the scripts), and it might contain text that gets spuriously interpreted as TAP diagnostics: such an issue can be solved by redefining the string that activates TAP diagnostics to a value you know won’t appear by chance in the tests’ output. Note however that this feature is non-standard, as the “official” TAP protocol does not allow for such a customization; so don’t use it if you can avoid it. Here is an example of how the TAP driver can be set up and used. % cat configure.ac AC_INIT([GNU Try Tap], [1.0], [bug-automake@gnu.org]) AC_CONFIG_AUX_DIR([build-aux]) AM_INIT_AUTOMAKE([foreign -Wall -Werror]) AC_CONFIG_FILES([Makefile]) AC_REQUIRE_AUX_FILE([tap-driver.sh]) AC_OUTPUT % cat Makefile.am TEST_LOG_DRIVER = env AM_TAP_AWK='$(AWK)' $(SHELL) \ $(top_srcdir)/build-aux/tap-driver.sh TESTS = foo.test bar.test baz.test EXTRA_DIST = $(TESTS) % cat foo.test #!/bin/sh echo 1..4 # Number of tests to be executed. echo 'ok 1 - Swallows fly' echo 'not ok 2 - Caterpillars fly # TODO metamorphosis in progress' echo 'ok 3 - Pigs fly # SKIP not enough acid' echo '# I just love word plays ...' echo 'ok 4 - Flies fly too :-)' % cat bar.test #!/bin/sh echo 1..3 echo 'not ok 1 - Bummer, this test has failed.' echo 'ok 2 - This passed though.' echo 'Bail out! Ennui kicking in, sorry...' echo 'ok 3 - This will not be seen.' % cat baz.test #!/bin/sh echo 1..1 echo ok 1 # Exit with error, even if all the tests have been successful. exit 7 % cp PREFIX/share/automake-APIVERSION/tap-driver.sh . % autoreconf -vi && ./configure && make check ... PASS: foo.test 1 - Swallows fly XFAIL: foo.test 2 - Caterpillars fly # TODO metamorphosis in progress SKIP: foo.test 3 - Pigs fly # SKIP not enough acid PASS: foo.test 4 - Flies fly too :-) FAIL: bar.test 1 - Bummer, this test has failed. PASS: bar.test 2 - This passed though. ERROR: bar.test - Bail out! Ennui kicking in, sorry... PASS: baz.test 1 ERROR: baz.test - exited with status 7 ... Please report to bug-automake@gnu.org ... % echo exit status: $? exit status: 1 % env TEST_LOG_DRIVER_FLAGS='--comments --ignore-exit' \ TESTS='foo.test baz.test' make -e check ... PASS: foo.test 1 - Swallows fly XFAIL: foo.test 2 - Caterpillars fly # TODO metamorphosis in progress SKIP: foo.test 3 - Pigs fly # SKIP not enough acid # foo.test: I just love word plays... PASS: foo.test 4 - Flies fly too :-) PASS: baz.test 1 ... % echo exit status: $? exit status: 0  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 minor incompatibilities with the mainstream versions, which you should be aware of. • A ‘Bail out!’ directive doesn’t stop the whole testsuite, but only the test script it occurs in. This doesn’t follow TAP specifications, but on the other hand it maximizes compatibility (and code sharing) with the “hard error” concept of the default testsuite driver. • The ‘version’ and ‘pragma’ directives are not supported. • The ‘--diagnostic-string’ option of our driver allows modification of the string that introduces TAP diagnostics from the default value of “‘#’”. The standard TAP protocol currently has no way to allow this, so if you use it your diagnostic will be lost to more compliant tools like ‘prove’ and ‘Test::Harness’ • And there are probably some other small and yet undiscovered incompatibilities, especially in corner cases or with rare usages.  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’ (https://metacpan.org/pod/Test::Harness), the (mostly) official documentation about the TAP format and protocol. • ‘prove’ (https://metacpan.org/pod/distribution/Test-Harness/bin/prove), the most famous command-line TAP test driver, included in the distribution of ‘perl’ and ‘Test::Harness’ (https://metacpan.org/pod/distribution/Test-Harness/lib/Test/Harness.pm). • The TAP wiki (https://testanything.org/). • A “gentle introduction” to testing for Perl coders: ‘Test::Tutorial’ (https://metacpan.org/pod/distribution/Test-Simple/lib/Test/Tutorial.pod). • ‘Test::Simple’ (https://metacpan.org/pod/distribution/Test-Simple/lib/Test/Simple.pm) and ‘Test::More’ (https://metacpan.org/pod/distribution/Test-Simple/lib/Test/More.pm), the standard Perl testing libraries, which are based on TAP. • C TAP Harness (https://www.eyrie.org/~eagle/software/c-tap-harness/), a C-based project implementing both a TAP producer and a TAP consumer. • tap4j (https://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’ (*note Introduction: (dejagnu)Top.) 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 of them), so it is safer and easier to ‘AC_SUBST’ them from ‘configure.ac’. For instance, the following statement will cause ‘configure’ to be rerun each time ‘version.sh’ is changed. AC_SUBST([CONFIG_STATUS_DEPENDENCIES], ['$(top_srcdir)/version.sh']) Note the ‘$(top_srcdir)/’ in the file name. Since this variable is to be used in all ‘Makefile’s, its value must be sensible at any level in the build hierarchy. Beware not to mistake ‘CONFIGURE_DEPENDENCIES’ for ‘CONFIG_STATUS_DEPENDENCIES’. ‘CONFIGURE_DEPENDENCIES’ adds dependencies to the ‘configure’ rule, whose effect is to run ‘autoconf’. This variable should be seldom used, because ‘automake’ already tracks ‘m4_include’d files. However it can be useful when playing tricky games with ‘m4_esyscmd’ or similar non-recommendable macros with side effects. Be also aware that interactions of this variable with the *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. GNU Make, at least, has an option ‘--always-make’ which tells Make to consider that all targets are out of date. This interacts badly with Automake-generated Makefiles, which implement their own careful rules for when to regenerate Makefiles, as described above. The result is an endless loop, or other poor behavior. The only thing to do, as far as we know, is to refrain from using ‘--always-make’.  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, a usage like this will end up enabling them: AUTOMAKE_OPTIONS = -Wportability foreign However, a strictness level specified in a higher-priority context will override all the explicit warnings specified in a lower-priority context. For example, if ‘configure.ac’ contains: AM_INIT_AUTOMAKE([-Wportability]) and ‘Makefile.am’ contains: AUTOMAKE_OPTIONS = foreign then ‘portability’ warnings will be _disabled_ in ‘Makefile.am’.  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. *Note Strictness::. 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-zstd’ Hook ‘dist-zstd’ to ‘dist’. ‘dist-shar’ Hook ‘dist-shar’ to ‘dist’. Use of this option is deprecated, as the ‘shar’ format is obsolescent and problematic. Support for it will be removed altogether in Automake 2.0. ‘dist-tarZ’ Hook ‘dist-tarZ’ to ‘dist’. Use of this option is deprecated, as the ‘compress’ program is obsolete. Support for it will be removed altogether in Automake 2.0. ‘filename-length-max=99’ Abort if file names longer than 99 characters are found during ‘make dist’. Such long file names are generally considered not to be portable in tarballs. See the ‘tar-v7’ and ‘tar-ustar’ options below. This option should be used in the top-level ‘Makefile.am’ or as an argument of ‘AM_INIT_AUTOMAKE’ in ‘configure.ac’; it will be ignored otherwise. It will also be ignored in sub-packages of nested packages (*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-built-sources’ Don’t build ‘BUILT_SOURCES’ as part of ‘dist’. This option can be set if building the distribution only requires the source files, and doesn’t compile anything as a side-effect. The default is for ‘$(distdir)’ to depend on ‘$(BUILT_SOURCES)’ because it is common, at least among GNU packages, to want to build the program to generate man pages with ‘help2man’ (*note Errors with distclean::). Admittedly the default behavior should perhaps be to omit the dependency, but to preserve compatibility, we don’t want to change it now. ‘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’. *Note Program and Library Variables::. ‘tar-v7’ ‘tar-ustar’ ‘tar-pax’ These three mutually exclusive options select the tar format to use when generating tarballs with ‘make dist’. (The tar file created is then compressed according to the set of ‘no-dist-gzip’, ‘dist-bzip2’, ‘dist-lzip’, ‘dist-xz’, ‘dist-zstd’ and ‘dist-tarZ’ options in use.) These options must be passed as arguments to ‘AM_INIT_AUTOMAKE’ (*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 others will generate broken tarballs or use non-portable extensions. Furthermore, the V7 format cannot store empty directories. When using this format, consider using the ‘filename-length-max=99’ option to catch file names too long. ‘tar-ustar’ selects the ustar format defined by POSIX 1003.1-1988. This format is old enough to be portable: As of 2018, it is supported by the native ‘tar’ command on GNU, FreeBSD, NetBSD, OpenBSD, AIX, HP-UX, and Solaris, at least. It fully supports empty directories. It can store file names with up to 256 characters, provided that the file name can be split at directory separator in two parts, first of them being at most 155 bytes long. So, in most cases the maximum file name length will be shorter than 256 characters. ‘tar-pax’ selects the new pax interchange format defined by POSIX 1003.1-2001. It does not limit the length of file names. However, this format is very young and should probably be restricted to packages that target only very modern platforms. As of 2018, this format is supported by the native ‘tar’ command only on GNU, FreeBSD, and OpenBSD systems; it is not supported by the native ‘tar’ command on NetBSD, AIX, HP-UX, or Solaris. There are moves to change the pax format in an upward-compatible way, so this option may refer to a more recent version in the future. *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 the same version or newer than the version specified, creation of the ‘Makefile.in’ will be suppressed. ‘-WCATEGORY’ or ‘--warnings=CATEGORY’ These options behave exactly like their command-line counterpart (*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. 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’. The variable ‘ETAGS’ is the name of the program to invoke (by default ‘etags’). 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 (https://www.gnu.org/software/global/). The ‘GTAGS’ rule runs Global Tags and puts the result in the top build directory. The variable ‘GTAGS_ARGS’ holds arguments that are passed to ‘gtags’.  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 conditional. These conditionals are not the same as conditionals in GNU Make. Automake conditionals are checked at configure time by the ‘configure’ script, and affect the translation from ‘Makefile.in’ to ‘Makefile’. They are based on options passed to ‘configure’ and on results that ‘configure’ has discovered about the host system. GNU Make conditionals are checked at ‘make’ time, and are based on variables passed to the make program or defined in the ‘Makefile’. Automake conditionals will work with any make program. * 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’, which are reserved by Automake. The shell CONDITION (suitable for use in a shell ‘if’ statement) is evaluated when ‘configure’ is run. Note that you must arrange for _every_ ‘AM_CONDITIONAL’ to be invoked every time ‘configure’ is run. If ‘AM_CONDITIONAL’ is run conditionally (e.g., in a shell ‘if’ statement), then the result will confuse ‘automake’. Conditionals typically depend upon options that the user provides to the ‘configure’ script. Here is an example of how to write a conditional that is true if the user uses the ‘--enable-debug’ option. AC_ARG_ENABLE([debug], [ --enable-debug Turn on debugging], [case "${enableval}" in yes) debug=true ;; no) debug=false ;; *) AC_MSG_ERROR([bad value ${enableval} for --enable-debug]) ;; esac],[debug=false]) AM_CONDITIONAL([DEBUG], [test x$debug = xtrue]) Here is an example of how to use that conditional in ‘Makefile.am’: if DEBUG DBG = debug else DBG = endif noinst_PROGRAMS = $(DBG) This trivial example could also be handled using ‘EXTRA_PROGRAMS’ (*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: Not Enough, 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 .  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 terse; in case of errors, the user won’t be able to easily see what rule or command have caused them, or even, in case of tools with poor error reporting, what the errors were! • ‘make >/dev/null || make’ Apparently, this perfectly obeys the “silence is golden” rule: warnings from stderr are passed through, output reporting is done only in case of error, and in that case it should provide a verbose-enough report to allow an easy determination of the error location and causes. However, calling ‘make’ two times in a row might hide errors (especially intermittent ones), or subtly change the expected semantics of the ‘make’ calls — these things can clearly make debugging and error assessment very difficult. • ‘make --no-print-directory’ This is GNU ‘make’ specific. When called with the ‘--no-print-directory’ option, GNU ‘make’ will disable printing of the working directory by invoked sub-‘make’s (the well-known “Entering/Leaving directory ...” messages). This helps to decrease the verbosity of the output, but experience has shown that it can also often render debugging considerably harder in projects using deeply-nested ‘make’ recursion. As an aside, notice that the ‘--no-print-directory’ option is automatically activated if the ‘-s’ flag is used.  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 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, developers who wants to make silent rules enabled by default in their own packages can do so by calling ‘AM_SILENT_RULES([yes])’ in ‘configure.ac’. Users who prefer to have silent rules enabled by default can edit their ‘config.site’ file to make the variable ‘enable_silent_rules’ default to ‘yes’. This should still allow disabling silent rules at ‘configure’ time and at ‘make’ time. For portability to different ‘make’ implementations, package authors are advised to not set the variable ‘V’ inside the ‘Makefile.am’ file, to allow the user to override the value for subdirectories as well. To work at its best, the current implementation of this feature normally uses nested variable expansion ‘$(VAR1$(V))’, a ‘Makefile’ feature that is not required by POSIX 2008 but is widely supported in practice. On the rare ‘make’ implementations that do not support nested variable expansion, whether rules are silent is always determined at configure time, and cannot be overridden at make time. Future versions of POSIX are likely to require nested variable expansion, so this minor limitation should go away with time. To extend the silent mode to your own rules, you have a few choices: • You can use the predefined variable ‘AM_V_GEN’ as a prefix to commands that should output a status line in silent mode, and ‘AM_V_at’ as a prefix to commands that should not output anything in silent mode. When output is to be verbose, both of these variables will expand to the empty string. • You can silence a recipe unconditionally with ‘@’, and then use the predefined variable ‘AM_V_P’ to know whether make is being run in silent or verbose mode; adjust the verbose information your recipe displays accordingly: generate-headers: ... [commands defining a shell variable '$headers'] ...; \ if $(AM_V_P); then set -x; else echo " GEN [headers]"; fi; \ rm -f $$headers && generate-header --flags $$headers • You can add your own variables, so strings of your own choice are shown. The following snippet shows how you would define your own equivalent of ‘AM_V_GEN’: pkg_verbose = $(pkg_verbose_@AM_V@) pkg_verbose_ = $(pkg_verbose_@AM_DEFAULT_V@) pkg_verbose_0 = @echo PKG-GEN $@; foo: foo.in $(pkg_verbose)cp $(srcdir)/foo.in $@ As a final note, observe that, even when silent rules are enabled, the ‘--no-print-directory’ option is still required with GNU ‘make’ if the “Entering/Leaving directory ...” messages are to be disabled.  File: automake.info, Node: Not Enough, Next: Distributing, Prev: Silencing Make, Up: Top 22 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 22.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 accordingly.  File: automake.info, Node: Third-Party Makefiles, Prev: Extending, Up: Not Enough 22.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 that ‘gettextize’ puts in the ‘po/’ and ‘intl/’ directories are handwritten ‘Makefile’s that implement all of these targets. That way they can be added to ‘SUBDIRS’ in Automake packages. Directories that are only listed in ‘DIST_SUBDIRS’ but not in ‘SUBDIRS’ need only the ‘distclean’, ‘maintainer-clean’, and ‘distdir’ rules (*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): To be clear, there is nothing special about the variable name ‘EMPTY_AUTOMAKE_TARGETS’; the name could be anything. 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 (indeed, 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 real ‘check’ target is named ‘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 23 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 24 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 and try to get it documented and exercised by the test-suite.  File: automake.info, Node: Upgrading, Next: FAQ, Prev: API Versioning, Up: Top 25 Upgrading a Package to a Newer Automake Version ************************************************** Automake maintains three kinds of files in a package. • ‘aclocal.m4’ • ‘Makefile.in’s • auxiliary tools like ‘install-sh’ or ‘py-compile’ ‘aclocal.m4’ is generated by ‘aclocal’ and contains some Automake-supplied M4 macros. Auxiliary tools are installed by ‘automake --add-missing’ when needed. ‘Makefile.in’s are built from ‘Makefile.am’ by ‘automake’, and rely on the definitions of the M4 macros put in ‘aclocal.m4’ as well as the behavior of the auxiliary tools installed. Because all of these files are closely related, it is important to regenerate all of them when upgrading to a newer Automake release. The usual way to do that is aclocal # with any option needed (such as -I m4) autoconf automake --add-missing --force-missing or more conveniently: autoreconf -vfi The use of ‘--force-missing’ ensures that auxiliary tools will be overridden by new versions (*note automake Invocation::). It is important to regenerate all of these files each time Automake is upgraded, even between bug fix releases. For instance, it is not unusual for a bug fix to involve changes to both the rules generated in ‘Makefile.in’ and the supporting M4 macros copied to ‘aclocal.m4’. Presently ‘automake’ is able to diagnose situations where ‘aclocal.m4’ has been generated with another version of ‘aclocal’. However it never checks whether auxiliary scripts are up-to-date. In other words, ‘automake’ will tell you when ‘aclocal’ needs to be rerun, but it will never diagnose a missing ‘--force-missing’. Before upgrading to a new major release, it is a good idea to read the file ‘NEWS’. This file lists all changes between releases: new features, obsolete constructs, known incompatibilities, and workarounds.  File: automake.info, Node: FAQ, Next: Copying This Manual, Prev: Upgrading, Up: Top 26 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 26.1 CVS and generated files ============================ Background: distributed generated Files --------------------------------------- Packages made with Autoconf and Automake ship with some generated files like ‘configure’ or ‘Makefile.in’. These files were generated on the developer’s machine and are distributed so that end-users do not have to install the maintainer tools required to rebuild them. Other generated files like Lex scanners, Yacc parsers, or Info documentation are usually distributed on similar grounds. Automake output generates rules in ‘Makefile’s to rebuild these files. For instance, ‘make’ will run ‘autoconf’ to rebuild ‘configure’ whenever ‘configure.ac’ is changed. This makes development safer by ensuring a ‘configure’ is never out-of-date with respect to ‘configure.ac’. As generated files shipped in packages are up-to-date, and because ‘tar’ preserves times-tamps, these rebuild rules are not triggered when a user unpacks and builds a package. Background: CVS and Timestamps ------------------------------ Unless you use CVS keywords (in which case files must be updated at commit time), CVS preserves timestamp during ‘cvs commit’ and ‘cvs import -d’ operations. When you check out a file using ‘cvs checkout’ its timestamp is set to that of the revision that is being checked out. However, during ‘cvs update’, files will have the date of the update, not the original timestamp of this revision. This is meant to make sure that ‘make’ notices that sources files have been updated. This timestamp shift is troublesome when both sources and generated files are kept under CVS. Because CVS processes files in lexical order, ‘configure.ac’ will appear newer than ‘configure’ after a ‘cvs update’ that updates both files, even if ‘configure’ was newer than ‘configure.ac’ when it was checked in. Calling ‘make’ will then trigger a spurious rebuild of ‘configure’. Living with CVS in Autoconfiscated Projects ------------------------------------------- There are basically two clans amongst maintainers: those who keep all distributed files under CVS, including generated files, and those who keep generated files _out_ of CVS. All Files in CVS ................ • The CVS repository contains all distributed files so you know exactly what is distributed, and you can check out any prior version entirely. • Maintainers can see how generated files evolve (for instance, you can see what happens to your ‘Makefile.in’s when you upgrade Automake and make sure they look OK). • Users do not need Autotools to build a check-out of the project; it works just like a released tarball. • If users use ‘cvs update’ to update their copy, instead of ‘cvs checkout’ to fetch a fresh one, timestamps will be inaccurate. Some rebuild rules will be triggered and attempt to run developer tools such as ‘autoconf’ or ‘automake’. Calls to such tools are all wrapped into a call to the ‘missing’ script discussed later (*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 a helper script (or to enhance their existing bootstrap script) to fix the timestamps after a ‘cvs update’ or a ‘git checkout’, to prevent spurious rebuilds. In case of a project committing the Autotools-generated files, as well as the generated ‘.info’ files, such a script might look something like this: #!/bin/sh # fix-timestamp.sh: prevents useless rebuilds after "cvs update" sleep 1 # aclocal-generated aclocal.m4 depends on locally-installed # '.m4' macro files, as well as on 'configure.ac' touch aclocal.m4 sleep 1 # autoconf-generated configure depends on aclocal.m4 and on # configure.ac touch configure # so does autoheader-generated config.h.in touch config.h.in # and all the automake-generated Makefile.in files touch `find . -name Makefile.in -print` # finally, the makeinfo-generated '.info' files depend on the # corresponding '.texi' files touch doc/*.info • In distributed development, developers are likely to have different versions of the maintainer tools installed. In this case rebuilds triggered by timestamp lossage will lead to spurious changes to generated files. There are several solutions to this: • All developers should use the same versions, so that the rebuilt files are identical to files in CVS. (This starts to be difficult when each project you work on uses different versions.) • Or people use a script to fix the timestamp after a checkout (the GCC folks have such a script). • Or ‘configure.ac’ uses ‘AM_MAINTAINER_MODE’, which will disable all of these rebuild rules by default. This is further discussed in *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. 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 Integrating with Version Control Systems: (gettext)Version Control Issues.  File: automake.info, Node: maintainer-mode, Next: Wildcards, Prev: CVS, Up: FAQ 26.2 ‘missing’ and ‘AM_MAINTAINER_MODE’ ======================================= ‘missing’ --------- The ‘missing’ script is a wrapper around several maintainer tools, designed to warn users if a maintainer tool is required but missing. Typical maintainer tools are ‘autoconf’, ‘automake’, ‘bison’, etc. Because files generated by these tools are shipped with the other sources of a package, these tools shouldn’t be required during a user build and they are not checked for in ‘configure’. However, if for some reason a rebuild rule is triggered and involves a missing tool, ‘missing’ will notice it and warn the user, even suggesting how to obtain such a tool (at least in case it is a well-known one, like ‘makeinfo’ or ‘bison’). This is more helpful and user-friendly than just having the rebuild rules spewing out a terse error message like ‘sh: TOOL: command not found’. Similarly, ‘missing’ will warn the user if it detects that a maintainer tool it attempted to use seems too old (be warned that diagnosing this correctly is typically more difficult than detecting missing tools, and requires cooperation from the tool itself, so it won’t always work). If the required tool is installed, ‘missing’ will run it and won’t attempt to continue after failures. This is correct behavior during development: developers love fixing failures. However, users with missing or too old maintainer tools may get an error when the rebuild rule is spuriously triggered, halting the build. This failure to let the build continue is one of the arguments of the ‘AM_MAINTAINER_MODE’ advocates. ‘AM_MAINTAINER_MODE’ -------------------- ‘AM_MAINTAINER_MODE’ allows you to choose whether the so called "rebuild rules" should be enabled or disabled. With ‘AM_MAINTAINER_MODE([enable])’, they are enabled by default; otherwise they are disabled by default. In the latter case, if you have ‘AM_MAINTAINER_MODE’ in ‘configure.ac’, and run ‘./configure && make’, then ‘make’ will *never* attempt to rebuild ‘configure’, ‘Makefile.in’s, Lex or Yacc outputs, etc. That is, this disables build rules for files that are usually distributed and that users should normally not have to update. The user can override the default setting by passing either ‘--enable-maintainer-mode’ or ‘--disable-maintainer-mode’ to ‘configure’. People use ‘AM_MAINTAINER_MODE’ either because they do not want their users (or themselves) annoyed by timestamp lossage (*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 source files can have no effect on generated files and this can be very confusing when unnoticed. He adds that security shouldn’t be reserved to maintainers (what ‘--enable-maintainer-mode’ suggests), on the contrary. If one user has to modify a ‘Makefile.am’, then either ‘Makefile.in’ should be updated or a warning should be output (this is what Automake uses ‘missing’ for) but the last thing you want is that nothing happens and the user doesn’t notice it (this is what happens when rebuild rules are disabled by ‘AM_MAINTAINER_MODE’). Jim Meyering, the inventor of the ‘AM_MAINTAINER_MODE’ macro, was swayed by François’ arguments, and got rid of ‘AM_MAINTAINER_MODE’ in all of his packages. Still many people continue to use ‘AM_MAINTAINER_MODE’, because it helps them working on projects where all files are kept under version control, and because ‘missing’ isn’t enough if you have the wrong version of the tools.  File: automake.info, Node: Wildcards, Next: Limitations on File Names, Prev: maintainer-mode, Up: FAQ 26.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 quite 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 26.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 26.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 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 explanation. The latter bug is not always easy to understand and fix, so let’s proceed with an example. Suppose our package contains a program for which we want to build a man page using ‘help2man’. GNU ‘help2man’ produces simple manual pages from the ‘--help’ and ‘--version’ output of other commands (*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 26.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 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 ( 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, while debugging a C++ project, if 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 have the last say. In the example above, the desire is for the ‘CXXFLAGS=-O0’ to supersede any other switch from ‘AM_CXXFLAGS’ or ‘mumble_CXXFLAGS’. It’s true that not all options to all programs can be overridden. So in general, users could conceivably want to place options at arbitrary places in the command line, but Automake does not support this. It would be difficult to make such generality comprehensible. Being able to specify the final options commonly suffices. Thus, 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 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 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 ‘RUNTESTFLAGS’ and ‘AM_RUNTESTFLAGS’. 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 an ‘AM_’ nor a per-target cousin. Finally you should not think that the existence of a per-target variable implies the existence of an ‘AM_’ variable or of a user variable. For instance, the ‘mumble_LDADD’ per-target variable overrides the makefile-wide ‘LDADD’ variable (which is not a user variable), and ‘mumble_LIBADD’ exists only as a per-target variable. *Note Program and Library Variables::.  File: automake.info, Node: Renamed Objects, Next: Per-Object Flags, Prev: Flag Variables Ordering, Up: FAQ 26.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 determine whether source files are shared to decide if it must rename objects. It just renames all objects of a target as soon as it sees that per-target compilation flags are 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 26.8 Per-Object Flags Emulation =============================== One of my source files needs to be compiled with different flags. How do I do that? Automake supports per-program and per-library compilation flags (see *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 26.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 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 $@ @test -f $@ || rm -f data.c @test -f $@ || $(MAKE) $(AM_MAKEFLAGS) data.c It is tempting to use a single test as follows: data.h: data.c ## Recover from the removal of $@ @if test -f $@; then :; else \ rm -f data.c; \ $(MAKE) $(AM_MAKEFLAGS) data.c; \ fi but that would break ‘make -n’: at least GNU ‘make’ and Solaris ‘make’ execute recipes containing the ‘$(MAKE)’ string even when they are running in dry mode. So if we didn’t break the recipe above in two invocations, the file ‘data.c’ would be removed even upon ‘make -n’. Not nice. 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 $@ @test -f $@ || rm -f data.c @test -f $@ || $(MAKE) $(AM_MAKEFLAGS) data.c 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 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 @test ! -f $@ || touch $@ ## Recover from the removal of $@ @test -f $@ || rm -f data.c @test -f $@ || $(MAKE) $(AM_MAKEFLAGS) data.c 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 $@ @test -f $@ || rm -f data.stamp @test -f $@ || $(MAKE) $(AM_MAKEFLAGS) data.stamp ‘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 26.10 Installing to Hard-Coded Locations ======================================== My package needs to install some configuration file. I tried to use the following rule, but ‘make distcheck’ fails. Why? # Do not do this. install-data-local: $(INSTALL_DATA) $(srcdir)/afile $(DESTDIR)/etc/afile My package needs to populate the installation directory of another package at install-time. I can easily compute that installation directory in ‘configure’, but if I install files therein, ‘make distcheck’ fails. How else should I do it? These two setups share their symptoms: ‘make distcheck’ fails because they are installing files to hard-coded paths. In the latter case the path is not 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 accepts a third argument that will replace Python’s installation prefix. % python -c 'from distutils import sysconfig; print sysconfig.get_python_lib(1,0,"${exec_prefix}")' ${exec_prefix}/lib/python2.5/site-packages You can also use this new path. If you do • root users can install your package with the same ‘--prefix’ as Python (you get the behavior of the previous attempt) • non-root users can install your package too; they will have the extension module in a place that is not searched by Python but they can work around this using environment variables (and if you installed scripts that use this shared library, it’s easy to tell Python where to look in the beginning of your script, so the script works in both cases). The ‘AM_PATH_PYTHON’ macro uses similar commands to define ‘$(pythondir)’ and ‘$(pyexecdir)’ (*note Python::). Of course not all tools are as advanced as Python regarding that substitution of PREFIX. So another strategy is to figure out the part of the installation directory that must be preserved. For instance, here is how ‘AM_PATH_LISPDIR’ (*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` That is, 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 worth the extra ‘sed’ invocation.  File: automake.info, Node: Debugging Make Rules, Next: Reporting Bugs, Prev: Hard-Coded Install Paths, Up: FAQ 26.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. However, this _still executes_ 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. • provides a modified GNU ‘make’ command called ‘remake’ that copes with complex GNU ‘make’-specific Makefiles and allows tracing execution, examining variables, and calling rules interactively, much like a debugger. ---------- Footnotes ---------- (1) Automake’s ‘dist’ and ‘distcheck’ rules had a bug in this regard in that they created directories even with ‘-n’, but this has been fixed in Automake 1.11.  File: automake.info, Node: Reporting Bugs, Prev: Debugging Make Rules, Up: FAQ 26.12 Reporting Bugs ==================== Most nontrivial software has bugs. Automake is no exception. We cannot promise we can or will fix a bug, and we might not even agree that it is a bug, but we want to hear about problems you encounter. Often we agree they are bugs and want to fix them. So, to make it possible for us to fix a bug, please report it. If you can, though, it is helpful if you check if it is already known. You can look at the GNU Bug Tracker (https://debbugs.gnu.org/) and the bug-automake mailing list archives (https://lists.gnu.org/archive/html/bug-automake/) for previous bug reports. (We previously used a Gnats database for bug tracking, but it is no longer online.) If the bug is not already known, it should be reported. To report bugs in a way that is useful and efficient, please read How to Report Bugs Effectively (https://www.chiark.greenend.org.uk/~sgtatham/bugs.html) and How to Ask Questions the Smart Way (http://catb.org/~esr/faqs/smart-questions.html). Good bug reports save time for everyone. For a bug report, a feature request or other suggestions, please send email to . This will then open a new bug in the bug tracker (https://debbugs.gnu.org/automake). Be sure to include the versions of Autoconf and Automake that you use and the kind of system you’re on. 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–2021 Free Software Foundation, Inc. Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. 0. PREAMBLE The purpose of this License is to make a manual, textbook, or other functional and useful document “free” in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others. This License is a kind of “copyleft”, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software. We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference. 1. APPLICABILITY AND DEFINITIONS This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”. You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law. A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language. A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document’s overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them. The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none. The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words. A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not “Transparent” is called “Opaque”. Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only. The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” means the text near the most prominent appearance of the work’s title, preceding the beginning of the body of the text. The “publisher” means any person or entity that distributes copies of the Document to the public. A section “Entitled XYZ” means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” of such a section when you modify the Document means that it remains a section “Entitled XYZ” according to this definition. The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License. 2. VERBATIM COPYING You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3. You may also lend copies, under the same conditions stated above, and you may publicly display copies. 3. COPYING IN QUANTITY If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document’s license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects. If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages. If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public. It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document. 4. MODIFICATIONS You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version: A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission. B. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement. C. State on the Title page the name of the publisher of the Modified Version, as the publisher. D. Preserve all the copyright notices of the Document. E. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices. F. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below. G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document’s license notice. H. Include an unaltered copy of this License. I. Preserve the section Entitled “History”, Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled “History” in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence. J. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the “History” section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission. K. For any section Entitled “Acknowledgements” or “Dedications”, Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein. L. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles. M. Delete any section Entitled “Endorsements”. Such a section may not be included in the Modified Version. N. Do not retitle any existing section to be Entitled “Endorsements” or to conflict in title with any Invariant Section. O. Preserve any Warranty Disclaimers. If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version’s license notice. These titles must be distinct from any other section titles. You may add a section Entitled “Endorsements”, provided it contains nothing but endorsements of your Modified Version by various parties—for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard. You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one. The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version. 5. COMBINING DOCUMENTS You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers. The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work. In the combination, you must combine any sections Entitled “History” in the various original documents, forming one section Entitled “History”; likewise combine any sections Entitled “Acknowledgements”, and any sections Entitled “Dedications”. You must delete all sections Entitled “Endorsements.” 6. COLLECTIONS OF DOCUMENTS You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects. You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document. 7. AGGREGATION WITH INDEPENDENT WORKS A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an “aggregate” if the copyright resulting from the compilation is not used to limit the legal rights of the compilation’s users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document’s Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate. 8. TRANSLATION Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail. If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”, the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title. 9. TERMINATION You may not copy, modify, sublicense, or distribute the Document except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, or distribute it is void, and will automatically terminate your rights under this License. However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation. Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice. Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, receipt of a copy of some or all of the same material does not give you any rights to use it. 10. FUTURE REVISIONS OF THIS LICENSE The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See . 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_FILES <1>: Basics of Distribution. (line 26) * AC_CONFIG_HEADERS: Optional. (line 50) * AC_CONFIG_LIBOBJ_DIR: Optional. (line 46) * AC_CONFIG_LIBOBJ_DIR <1>: LIBOBJS. (line 51) * AC_CONFIG_LINKS: Optional. (line 62) * AC_CONFIG_SUBDIRS: Subpackages. (line 6) * AC_CONFIG_SUBDIRS <1>: The dist Hook. (line 49) * AC_DEFUN: Extending aclocal. (line 36) * AC_F77_LIBRARY_LDFLAGS: Optional. (line 108) * AC_FC_SRCEXT: Optional. (line 114) * AC_INIT: Public Macros. (line 15) * AC_LIBOBJ: Optional. (line 72) * AC_LIBOBJ <1>: LTLIBOBJS. (line 6) * AC_LIBOBJ <2>: LIBOBJS. (line 11) * AC_LIBSOURCE: Optional. (line 73) * AC_LIBSOURCE <1>: LIBOBJS. (line 17) * AC_LIBSOURCES: Optional. (line 74) * AC_OUTPUT: Requirements. (line 15) * AC_PREREQ: Extending aclocal. (line 36) * AC_PROG_CXX: Optional. (line 92) * AC_PROG_F77: Optional. (line 104) * AC_PROG_FC: Optional. (line 119) * AC_PROG_LEX: Public Macros. (line 94) * AC_PROG_LEX <1>: Optional. (line 134) * AC_PROG_LIBTOOL: Optional. (line 124) * AC_PROG_OBJC: Optional. (line 96) * AC_PROG_OBJCXX: Optional. (line 100) * AC_PROG_RANLIB: Optional. (line 88) * AC_PROG_YACC: Optional. (line 128) * AC_REQUIRE_AUX_FILE: Optional. (line 138) * AC_SUBST: Optional. (line 146) * AM_CONDITIONAL: Optional. (line 159) * AM_CONDITIONAL <1>: Usage of Conditionals. (line 6) * AM_CONDITIONAL <2>: Usage of Conditionals. (line 9) * AM_COND_IF: Optional. (line 162) * 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 168) * AM_GNU_GETTEXT_INTL_SUBDIR: Optional. (line 174) * 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 38) * AM_MAINTAINER_MODE([DEFAULT-MODE]): Optional. (line 179) * AM_MAKE_INCLUDE: Private Macros. (line 20) * AM_MISSING_PROG: Public Macros. (line 110) * AM_OUTPUT_DEPENDENCY_COMMANDS: Private Macros. (line 15) * AM_PATH_LISPDIR: Public Macros. (line 60) * AM_PATH_PYTHON: Python. (line 28) * AM_PROG_AR: Public Macros. (line 75) * AM_PROG_AS: Public Macros. (line 82) * AM_PROG_CC_C_O: Public Macros. (line 87) * AM_PROG_GCJ: Public Macros. (line 99) * AM_PROG_INSTALL_STRIP: Private Macros. (line 25) * AM_PROG_LEX: Public Macros. (line 94) * AM_PROG_MKDIR_P: Obsolete Macros. (line 14) * AM_PROG_UPC: Public Macros. (line 104) * 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 118) * AM_SUBST_NOTMAKE(VAR): Optional. (line 187) * AM_WITH_DMALLOC: Public Macros. (line 122) * m4_include: Basics of Distribution. (line 30) * m4_include <1>: Optional. (line 197)  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) * ACLOCAL_AUTOMAKE_DIR: aclocal Options. (line 12) * 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 85) * 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 30) * AM_ETAGSFLAGS: Tags. (line 27) * 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 150) * AM_JAVACFLAGS: Java. (line 44) * AM_LDFLAGS: Linking. (line 10) * AM_LDFLAGS <1>: Program Variables. (line 59) * AM_LFLAGS: Yacc and Lex. (line 65) * 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_TESTSUITE_SUMMARY_HEADER: Scripts-based Testsuites. (line 69) * AM_TESTS_ENVIRONMENT: Testsuite Environment Overrides. (line 6) * AM_TESTS_FD_REDIRECT: Testsuite Environment Overrides. (line 14) * 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 44) * 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 75) * AUTOCONF: automake Invocation. (line 28) * AUTOM4TE: aclocal Invocation. (line 44) * AUTOMAKE_JOBS: automake Invocation. (line 195) * AUTOMAKE_LIBDIR: automake Invocation. (line 64) * 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) * BUILT_SOURCES, and dist target: List of Automake options. (line 81) * BZIP2: The Types of Distributions. (line 17) * CC: Program Variables. (line 12) * CCAS: Public Macros. (line 82) * CCAS <1>: Assembly Support. (line 10) * CCASFLAGS: Public Macros. (line 82) * 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_PROGRAMS <2>: Scripts-based Testsuites. (line 111) * 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) * CSCOPE: Tags. (line 57) * CSCOPEFLAGS: Tags. (line 57) * CSCOPE_ARGS: Tags. (line 57) * CTAGS: Tags. (line 43) * CTAGSFLAGS: Tags. (line 43) * CTAGS_ARGS: Tags. (line 43) * 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 30) * distcleancheck_listfiles: Checking the Distribution. (line 92) * distcleancheck_listfiles <1>: Errors with distclean. (line 112) * DISTCLEANFILES: Clean. (line 13) * DISTCLEANFILES <1>: Checking the Distribution. (line 92) * distdir: The dist Hook. (line 34) * distdir <1>: Third-Party Makefiles. (line 25) * distuninstallcheck_listfiles: Checking the Distribution. (line 128) * dist_: Alternative. (line 28) * 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 73) * DVIPS: Texinfo. (line 141) * EMACS: Public Macros. (line 60) * EMPTY_AUTOMAKE_TARGETS: Third-Party Makefiles. (line 88) * ETAGS: Tags. (line 27) * ETAGSFLAGS: Tags. (line 27) * ETAGS_ARGS: Tags. (line 27) * EXPECT: DejaGnu Tests. (line 19) * EXTRA_DIST: Basics of Distribution. (line 60) * EXTRA_maude_DEPENDENCIES: Linking. (line 41) * EXTRA_maude_DEPENDENCIES <1>: Program and Library Variables. (line 129) * EXTRA_maude_SOURCES: Program and Library Variables. (line 60) * 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 99) * GCJFLAGS: Public Macros. (line 99) * GCJFLAGS <1>: Java Support with gcj. (line 16) * GCJLINK: How the Linker is Chosen. (line 10) * GTAGS_ARGS: Tags. (line 62) * GZIP_ENV: The Types of Distributions. (line 10) * 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 65) * libexec_PROGRAMS: Program Sources. (line 6) * libexec_SCRIPTS: Scripts. (line 18) * LIBOBJS: Optional. (line 75) * 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 60) * 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) * LZIP_OPT: The Types of Distributions. (line 23) * 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 76) * maude_CCASFLAGS: Program and Library Variables. (line 183) * maude_CFLAGS: Program and Library Variables. (line 184) * maude_CPPFLAGS: Program and Library Variables. (line 185) * maude_CXXFLAGS: Program and Library Variables. (line 186) * maude_DEPENDENCIES: Linking. (line 41) * maude_DEPENDENCIES <1>: Program and Library Variables. (line 128) * maude_FFLAGS: Program and Library Variables. (line 187) * maude_GCJFLAGS: Program and Library Variables. (line 188) * maude_LDADD: Linking. (line 17) * maude_LDADD <1>: Program and Library Variables. (line 94) * maude_LDFLAGS: Linking. (line 37) * maude_LDFLAGS <1>: Program and Library Variables. (line 114) * maude_LFLAGS: Program and Library Variables. (line 189) * maude_LIBADD: A Library. (line 26) * maude_LIBADD <1>: Program and Library Variables. (line 86) * maude_LIBTOOLFLAGS: Libtool Flags. (line 6) * maude_LIBTOOLFLAGS <1>: Program and Library Variables. (line 121) * maude_LINK: Program and Library Variables. (line 164) * maude_OBJCFLAGS: Program and Library Variables. (line 190) * maude_OBJCXXFLAGS: Program and Library Variables. (line 191) * maude_RFLAGS: Program and Library Variables. (line 192) * maude_SHORTNAME: Program and Library Variables. (line 223) * maude_SOURCES: Program and Library Variables. (line 18) * maude_UPCFLAGS: Program and Library Variables. (line 193) * maude_YFLAGS: Program and Library Variables. (line 194) * MISSING: Public Macros. (line 110) * MKDIR_P: Obsolete Macros. (line 14) * mkdir_p: Obsolete Macros. (line 14) * MOSTLYCLEANFILES: Clean. (line 13) * nobase_: Alternative. (line 22) * nodist_: Alternative. (line 28) * 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 109) * pkgpythondir: Python. (line 95) * PROGRAMS: Uniform. (line 17) * PROGRAMS <1>: Uniform. (line 101) * pyexecdir: Python. (line 100) * PYTHON: Uniform. (line 101) * PYTHON <1>: Python. (line 56) * pythondir: Python. (line 91) * PYTHON_EXEC_PREFIX: Python. (line 73) * PYTHON_PLATFORM: Python. (line 86) * PYTHON_PREFIX: Python. (line 72) * PYTHON_VERSION: Python. (line 68) * RECHECK_LOGS: Parallel Test Harness. (line 127) * 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 73) * SUFFIXES: Suffixes. (line 6) * sys.exec_prefix Python variable: Python. (line 74) * sys.platform Python variable: Python. (line 87) * sys.prefix Python variable: Python. (line 74) * sys.version_info Python variable: Python. (line 69) * sysconf_DATA: Data. (line 9) * TAGS_DEPENDENCIES: Tags. (line 37) * TAR: Basics of Distribution. (line 16) * target_triplet: Optional. (line 14) * TESTS: Scripts-based Testsuites. (line 104) * TESTS <1>: Parallel Test Harness. (line 12) * TESTS_ENVIRONMENT: Testsuite Environment Overrides. (line 6) * 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 34) * top_distdir <1>: Third-Party Makefiles. (line 25) * UPC: Public Macros. (line 104) * 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 37) * VALAFLAGS: Vala Support. (line 41) * VERBOSE: Parallel Test Harness. (line 26) * VERSION: Basics of Distribution. (line 6) * WARNINGS: automake Invocation. (line 187) * WARNINGS <1>: aclocal Options. (line 95) * WITH_DMALLOC: Public Macros. (line 122) * XFAIL_TESTS: Scripts-based Testsuites. (line 32) * XZ_OPT: The Types of Distributions. (line 30) * YACC: Optional. (line 129) * YFLAGS: Yacc and Lex. (line 37) * ZSTD_CLEVEL: The Types of Distributions. (line 41) * ZSTD_OPT: The Types of Distributions. (line 41)  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) * --always-make GNU Make option: Rebuilding. (line 77) * --automake-acdir: aclocal Options. (line 9) * --build=BUILD: Cross-Compilation. (line 14) * --copy: automake Invocation. (line 75) * --diff: aclocal Options. (line 22) * --disable-dependency-tracking: Dependency Tracking. (line 33) * --disable-maintainer-mode: Optional. (line 180) * --disable-silent-rules: Automake Silent Rules. (line 85) * --dry-run: aclocal Options. (line 27) * --enable-debug, example: Usage of Conditionals. (line 21) * --enable-dependency-tracking: Dependency Tracking. (line 43) * --enable-maintainer-mode: Optional. (line 180) * --enable-silent-rules: Automake Silent Rules. (line 85) * --force: aclocal Options. (line 49) * --force-missing: automake Invocation. (line 80) * --foreign: Strictness. (line 51) * --foreign <1>: automake Invocation. (line 86) * --gnits: Strictness. (line 58) * --gnits <1>: automake Invocation. (line 90) * --gnu: Strictness. (line 18) * --gnu <1>: automake Invocation. (line 94) * --help: automake Invocation. (line 98) * --help <1>: aclocal Options. (line 31) * --help check: List of Automake options. (line 144) * --help=recursive: Nested Packages. (line 30) * --host=HOST: Cross-Compilation. (line 16) * --include-deps: automake Invocation. (line 106) * --install: aclocal Options. (line 38) * --libdir: automake Invocation. (line 61) * --no-force: automake Invocation. (line 111) * --output: aclocal Options. (line 59) * --output-dir: automake Invocation. (line 118) * --prefix: Standard Directory Variables. (line 33) * --print-ac-dir: aclocal Options. (line 62) * --print-libdir: automake Invocation. (line 69) * --program-prefix=PREFIX: Renaming. (line 16) * --program-suffix=SUFFIX: Renaming. (line 18) * --program-transform-name=PROGRAM: Renaming. (line 20) * --system-acdir: aclocal Options. (line 17) * --target=TARGET: Cross-Compilation. (line 55) * --verbose: automake Invocation. (line 125) * --verbose <1>: aclocal Options. (line 73) * --version: automake Invocation. (line 129) * --version <1>: aclocal Options. (line 76) * --version check: List of Automake options. (line 144) * --warnings: automake Invocation. (line 133) * --warnings <1>: aclocal Options. (line 80) * --with-dmalloc: Public Macros. (line 122) * --with-python-sys-prefix: Python. (line 74) * --with-python_exec_prefix: Python. (line 74) * --with-python_prefix: Python. (line 74) * -a: automake Invocation. (line 41) * -c: automake Invocation. (line 74) * -f: automake Invocation. (line 79) * -hook targets: Extending. (line 66) * -i: automake Invocation. (line 102) * -I: aclocal Options. (line 34) * -l and LDADD: Linking. (line 70) * -local targets: Extending. (line 37) * -module, libtool: Libtool Modules. (line 6) * -o: automake Invocation. (line 118) * -v: automake Invocation. (line 125) * -W: automake Invocation. (line 133) * -W <1>: aclocal Options. (line 80) * -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) * .pyc, .pyo files: Python. (line 15) * .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 38) * 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) * ar-lib: Auxiliary Programs. (line 16) * 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 targets, no-op: Third-Party Makefiles. (line 88) * 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 22) * Binary package: DESTDIR. (line 22) * bootstrap and autoreconf: Error required file ltmain.sh not found. (line 6) * Bugs, reporting: Reporting Bugs. (line 6) * build tree and source tree: VPATH Builds. (line 6) * BUILT_SOURCES, defined: Sources. (line 27) * bzip2: The Types of Distributions. (line 17) * 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 15) * 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 85) * 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: Auxiliary Programs. (line 20) * Compile Flag Variables: Flag Variables Ordering. (line 20) * Complete example: Complete. (line 6) * compress: The Types of Distributions. (line 57) * 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: Auxiliary Programs. (line 30) * config.guess <1>: automake Invocation. (line 39) * config.site example: config.site. (line 6) * config.sub: Auxiliary Programs. (line 30) * 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 50) * CVS and third-party files: CVS. (line 167) * CVS and timestamps: CVS. (line 29) * CXXFLAGS and AM_CXXFLAGS: Flag Variables Ordering. (line 20) * DATA primary, defined: Data. (line 6) * debug build, example: VPATH Builds. (line 48) * 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 19) * depcomp: Auxiliary Programs. (line 40) * depcomp <1>: 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-all: The Types of Distributions. (line 62) * dist-bzip2: The Types of Distributions. (line 17) * dist-bzip2 <1>: List of Automake options. (line 23) * dist-bzip2 <2>: List of Automake options. (line 23) * dist-gzip: The Types of Distributions. (line 10) * dist-hook: The dist Hook. (line 6) * dist-hook <1>: Extending. (line 66) * dist-lzip: The Types of Distributions. (line 23) * dist-lzip <1>: List of Automake options. (line 26) * dist-lzip <2>: List of Automake options. (line 26) * dist-shar: The Types of Distributions. (line 51) * dist-shar <1>: List of Automake options. (line 40) * dist-shar <2>: List of Automake options. (line 38) * dist-tarZ: The Types of Distributions. (line 57) * dist-tarZ <1>: List of Automake options. (line 45) * dist-tarZ <2>: List of Automake options. (line 43) * dist-xz: The Types of Distributions. (line 30) * dist-xz <1>: List of Automake options. (line 29) * dist-xz <2>: List of Automake options. (line 29) * dist-zip: The Types of Distributions. (line 37) * dist-zip <1>: List of Automake options. (line 32) * dist-zip <2>: List of Automake options. (line 32) * dist-zstd: The Types of Distributions. (line 41) * dist-zstd <1>: List of Automake options. (line 35) * dist-zstd <2>: List of Automake options. (line 35) * 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 77) * 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 92) * 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 128) * dist_ and nobase_: Alternative. (line 28) * dist_ and notrans_: Man Pages. (line 63) * DIST_SUBDIRS, explained: SUBDIRS vs DIST_SUBDIRS. (line 6) * dmalloc, support for: Public Macros. (line 122) * do-nothing Automake targets: Third-Party Makefiles. (line 88) * dvi: Texinfo. (line 25) * dvi <1>: Checking the Distribution. (line 57) * dvi <2>: Extending. (line 41) * DVI output using Texinfo: Texinfo. (line 6) * dvi-local: Extending. (line 41) * EDITION Texinfo flag: Texinfo. (line 35) * else: Usage of Conditionals. (line 36) * empty Automake targets: Third-Party Makefiles. (line 88) * 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) * eps images: Checking the Distribution. (line 60) * 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 48) * 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 51) * 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 50) * 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 58) * 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 18) * GNUmakefile including Makefile: Third-Party Makefiles. (line 114) * gzip: The Types of Distributions. (line 10) * 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) * help2man, and dist target: List of Automake options. (line 81) * hook targets: Extending. (line 66) * HP-UX 10, lex problems: Public Macros. (line 94) * html: Texinfo. (line 25) * html <1>: Extending. (line 41) * HTML output using Texinfo: Texinfo. (line 6) * html-local: Extending. (line 41) * id: Tags. (line 45) * if: Usage of Conditionals. (line 36) * include: Basics of Distribution. (line 30) * include <1>: Include. (line 6) * include, distribution: Basics of Distribution. (line 30) * Including Makefile fragment: Include. (line 6) * indentation in Makefile.am: General Operation. (line 33) * info: List of Automake options. (line 108) * info <1>: Extending. (line 41) * info-in-builddir: List of Automake options. (line 57) * 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 108) * 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 114) * 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-sh: Auxiliary Programs. (line 46) * 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 127) * LDADD and -l: Linking. (line 70) * LDFLAGS and AM_LDFLAGS: Flag Variables Ordering. (line 20) * lex problems with HP-UX 10: Public Macros. (line 94) * lex, multiple lexers: Yacc and Lex. (line 73) * 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) * Linking multiple yacc parsers: Linking Multiple Yacc Parsers. (line 3) * 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) * lzip: The Types of Distributions. (line 23) * m4_include, distribution: Basics of Distribution. (line 30) * 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 92) * make distuninstallcheck: Checking the Distribution. (line 128) * make install support: Install. (line 6) * make installcheck, testing --help and --version: List of Automake options. (line 144) * 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: Auxiliary Programs. (line 50) * mdate-sh <1>: Texinfo. (line 35) * MinGW cross-compilation example: Cross-Compilation. (line 25) * missing program: Auxiliary Programs. (line 54) * 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) * mkinstalldirs: Auxiliary Programs. (line 60) * 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 48) * Multiple configure.ac files: automake Invocation. (line 6) * Multiple lex lexers: Yacc and Lex. (line 73) * multiple outputs, rules with: Multiple Outputs. (line 6) * Multiple yacc parsers: Yacc and Lex. (line 73) * Nested packages: Nested Packages. (line 6) * Nesting packages: Subpackages. (line 6) * no-define: Public Macros. (line 54) * no-define <1>: List of Automake options. (line 62) * no-dependencies: Dependencies. (line 34) * no-dependencies <1>: List of Automake options. (line 70) * no-dist: List of Automake options. (line 77) * no-dist-built-sources: List of Automake options. (line 81) * no-dist-gzip: List of Automake options. (line 92) * no-dist-gzip <1>: List of Automake options. (line 92) * no-exeext: List of Automake options. (line 95) * no-installinfo: Texinfo. (line 85) * no-installinfo <1>: List of Automake options. (line 105) * no-installinfo option: Texinfo. (line 85) * no-installman: Man Pages. (line 32) * no-installman <1>: List of Automake options. (line 111) * no-installman option: Man Pages. (line 32) * no-op Automake targets: Third-Party Makefiles. (line 88) * no-texinfo.tex: List of Automake options. (line 121) * nobase_ and dist_ or nodist_: Alternative. (line 28) * nobase_ prefix: Alternative. (line 22) * nodist_ and nobase_: Alternative. (line 28) * 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 117) * 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 48) * Option, --warnings=CATEGORY: List of Automake options. (line 228) * Option, -WCATEGORY: List of Automake options. (line 228) * Option, check-news: List of Automake options. (line 15) * Option, dejagnu: List of Automake options. (line 19) * Option, dist-bzip2: List of Automake options. (line 23) * Option, dist-lzip: List of Automake options. (line 26) * Option, dist-shar: List of Automake options. (line 38) * Option, dist-tarZ: List of Automake options. (line 43) * Option, dist-xz: List of Automake options. (line 29) * Option, dist-zip: List of Automake options. (line 32) * Option, dist-zstd: List of Automake options. (line 35) * Option, filename-length-max=99: List of Automake options. (line 48) * 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 57) * Option, no-define: List of Automake options. (line 62) * Option, no-dependencies: List of Automake options. (line 70) * Option, no-dist: List of Automake options. (line 77) * Option, no-dist-built-sources: List of Automake options. (line 81) * Option, no-dist-gzip: List of Automake options. (line 92) * Option, no-exeext: List of Automake options. (line 95) * Option, no-installinfo: Texinfo. (line 85) * Option, no-installinfo <1>: List of Automake options. (line 105) * Option, no-installman: Man Pages. (line 32) * Option, no-installman <1>: List of Automake options. (line 111) * Option, no-texinfo.tex: List of Automake options. (line 121) * Option, nostdinc: List of Automake options. (line 117) * Option, parallel-tests: List of Automake options. (line 129) * Option, readme-alpha: List of Automake options. (line 135) * Option, serial-tests: List of Automake options. (line 125) * Option, tar-pax: List of Automake options. (line 174) * Option, tar-ustar: List of Automake options. (line 174) * Option, tar-v7: List of Automake options. (line 174) * Option, VERSION: List of Automake options. (line 223) * Option, warnings: List of Automake options. (line 228) * Options, aclocal: aclocal Options. (line 6) * Options, automake: automake Invocation. (line 37) * Options, std-options: List of Automake options. (line 144) * Options, subdir-objects: List of Automake options. (line 165) * 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) * Overriding testsuite environment: Testsuite Environment Overrides. (line 6) * PACKAGE, directory: Uniform. (line 19) * PACKAGE, prevent definition: Public Macros. (line 54) * 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 129) * Path stripping, avoiding: Alternative. (line 22) * pax format: List of Automake options. (line 174) * 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 195) * 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 131) * ps: Texinfo. (line 25) * ps <1>: Extending. (line 41) * PS output using Texinfo: Texinfo. (line 6) * ps-local: Extending. (line 41) * py-compile: Auxiliary Programs. (line 70) * PYTHON primary, defined: Python. (line 6) * Ratfor programs: Preprocessing Fortran 77. (line 6) * read-only source tree: VPATH Builds. (line 91) * README-alpha: Strictness. (line 78) * readme-alpha: List of Automake options. (line 135) * rebuild rules: Rebuilding. (line 6) * rebuild rules <1>: CVS. (line 9) * recheck: Parallel Test Harness. (line 139) * 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: Reporting Bugs. (line 6) * 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 42) * serial numbers in macros: Serials. (line 6) * serial-tests: List of Automake options. (line 125) * serial-tests, Using: Serial Test Harness. (line 6) * shar: The Types of Distributions. (line 51) * 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-packages Python directory: Python. (line 92) * site.exp: DejaGnu Tests. (line 26) * source tree and build tree: VPATH Builds. (line 6) * source tree, read-only: VPATH Builds. (line 91) * 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 144) * Strictness, command line: automake Invocation. (line 37) * Strictness, defined: Strictness. (line 10) * Strictness, foreign: Strictness. (line 51) * Strictness, gnits: Strictness. (line 58) * Strictness, gnu: Strictness. (line 18) * su, before make install: Basic Installation. (line 49) * subdir-objects: List of Automake options. (line 165) * 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 174) * tar-pax: List of Automake options. (line 174) * tar-ustar: List of Automake options. (line 174) * tar-v7: List of Automake options. (line 174) * Target, install-info: Texinfo. (line 85) * Target, install-man: Man Pages. (line 32) * targets, making into no-op: Third-Party Makefiles. (line 88) * 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) * test-driver: Auxiliary Programs. (line 73) * Tests, expected failure: Scripts-based Testsuites. (line 32) * Testsuite environment overrides: Testsuite Environment Overrides. (line 6) * 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: Auxiliary Programs. (line 77) * texinfo.tex <1>: 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 29) * 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 163) * 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 174) * v7 tar format: List of Automake options. (line 174) * 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 54) * 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) * xz: The Types of Distributions. (line 30) * yacc, multiple parsers: Yacc and Lex. (line 73) * YFLAGS and AM_YFLAGS: Flag Variables Ordering. (line 20) * ylwrap: Auxiliary Programs. (line 85) * ylwrap <1>: Yacc and Lex. (line 73) * zardoz example: Complete. (line 35) * zip: The Types of Distributions. (line 37) * zstd: The Types of Distributions. (line 41)