| This is automake.info, produced by makeinfo version 5.2 from |
| automake.texi. |
| |
| This manual is for GNU Automake (version 1.15, 31 December 2014), a |
| program that creates GNU standards-compliant Makefiles from template |
| files. |
| |
| Copyright © 1995-2014 Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this |
| document under the terms of the GNU Free Documentation License, |
| Version 1.3 or any later version published by the Free Software |
| Foundation; with no Invariant Sections, with no Front-Cover texts, |
| and with no Back-Cover Texts. A copy of the license is included in |
| the section entitled “GNU Free Documentation License.” |
| |
| INFO-DIR-SECTION Software development |
| START-INFO-DIR-ENTRY |
| * Automake: (automake). Making GNU standards-compliant Makefiles. |
| END-INFO-DIR-ENTRY |
| |
| INFO-DIR-SECTION Individual utilities |
| START-INFO-DIR-ENTRY |
| * aclocal-invocation: (automake)aclocal Invocation. Generating aclocal.m4. |
| * automake-invocation: (automake)automake Invocation. Generating Makefile.in. |
| END-INFO-DIR-ENTRY |
| |
| |
| File: automake.info, Node: Staged Installs, Next: Install Rules for the User, Prev: Extending Installation, Up: Install |
| |
| 12.4 Staged Installs |
| ==================== |
| |
| Automake generates support for the ‘DESTDIR’ variable in all install |
| rules. ‘DESTDIR’ is used during the ‘make install’ step to relocate |
| install objects into a staging area. Each object and path is prefixed |
| with the value of ‘DESTDIR’ before being copied into the install area. |
| Here is an example of typical DESTDIR usage: |
| |
| mkdir /tmp/staging && |
| make DESTDIR=/tmp/staging install |
| |
| The ‘mkdir’ command avoids a security problem if the attacker creates |
| a symbolic link from ‘/tmp/staging’ to a victim area; then ‘make’ places |
| install objects in a directory tree built under ‘/tmp/staging’. If |
| ‘/gnu/bin/foo’ and ‘/gnu/share/aclocal/foo.m4’ are to be installed, the |
| above command would install ‘/tmp/staging/gnu/bin/foo’ and |
| ‘/tmp/staging/gnu/share/aclocal/foo.m4’. |
| |
| This feature is commonly used to build install images and packages |
| (*note DESTDIR::). |
| |
| Support for ‘DESTDIR’ is implemented by coding it directly into the |
| install rules. If your ‘Makefile.am’ uses a local install rule (e.g., |
| ‘install-exec-local’) or an install hook, then you must write that code |
| to respect ‘DESTDIR’. |
| |
| *Note (standards)Makefile Conventions::, for another usage example. |
| |
| |
| File: automake.info, Node: Install Rules for the User, Prev: Staged Installs, Up: Install |
| |
| 12.5 Install Rules for the User |
| =============================== |
| |
| Automake also generates rules for targets ‘uninstall’, ‘installdirs’, |
| and ‘install-strip’. |
| |
| Automake supports ‘uninstall-local’ and ‘uninstall-hook’. There is |
| no notion of separate uninstalls for “exec” and “data”, as these |
| features would not provide additional functionality. |
| |
| Note that ‘uninstall’ is not meant as a replacement for a real |
| packaging tool. |
| |
| |
| File: automake.info, Node: Clean, Next: Dist, Prev: Install, Up: Top |
| |
| 13 What Gets Cleaned |
| ******************** |
| |
| The GNU Makefile Standards specify a number of different clean rules. |
| *Note Standard Targets for Users: (standards)Standard Targets. |
| |
| Generally the files that can be cleaned are determined automatically |
| by Automake. Of course, Automake also recognizes some variables that |
| can be defined to specify additional files to clean. These variables |
| are ‘MOSTLYCLEANFILES’, ‘CLEANFILES’, ‘DISTCLEANFILES’, and |
| ‘MAINTAINERCLEANFILES’. |
| |
| When cleaning involves more than deleting some hard-coded list of |
| files, it is also possible to supplement the cleaning rules with your |
| own commands. Simply define a rule for any of the ‘mostlyclean-local’, |
| ‘clean-local’, ‘distclean-local’, or ‘maintainer-clean-local’ targets |
| (*note Extending::). A common case is deleting a directory, for |
| instance, a directory created by the test suite: |
| |
| clean-local: |
| -rm -rf testSubDir |
| |
| Since ‘make’ allows only one set of rules for a given target, a more |
| extensible way of writing this is to use a separate target listed as a |
| dependency: |
| |
| clean-local: clean-local-check |
| .PHONY: clean-local-check |
| clean-local-check: |
| -rm -rf testSubDir |
| |
| As the GNU Standards aren’t always explicit as to which files should |
| be removed by which rule, we’ve adopted a heuristic that we believe was |
| first formulated by François Pinard: |
| |
| • If ‘make’ built it, and it is commonly something that one would |
| want to rebuild (for instance, a ‘.o’ file), then ‘mostlyclean’ |
| should delete it. |
| |
| • Otherwise, if ‘make’ built it, then ‘clean’ should delete it. |
| |
| • If ‘configure’ built it, then ‘distclean’ should delete it. |
| |
| • If the maintainer built it (for instance, a ‘.info’ file), then |
| ‘maintainer-clean’ should delete it. However ‘maintainer-clean’ |
| should not delete anything that needs to exist in order to run |
| ‘./configure && make’. |
| |
| We recommend that you follow this same set of heuristics in your |
| ‘Makefile.am’. |
| |
| |
| File: automake.info, Node: Dist, Next: Tests, Prev: Clean, Up: Top |
| |
| 14 What Goes in a Distribution |
| ****************************** |
| |
| * Menu: |
| |
| * Basics of Distribution:: Files distributed by default |
| * Fine-grained Distribution Control:: ‘dist_’ and ‘nodist_’ prefixes |
| * The dist Hook:: A target for last-minute distribution changes |
| * Checking the Distribution:: ‘make distcheck’ explained |
| * The Types of Distributions:: A variety of formats and compression methods |
| |
| |
| File: automake.info, Node: Basics of Distribution, Next: Fine-grained Distribution Control, Up: Dist |
| |
| 14.1 Basics of Distribution |
| =========================== |
| |
| The ‘dist’ rule in the generated ‘Makefile.in’ can be used to generate a |
| gzipped ‘tar’ file and other flavors of archive for distribution. The |
| file is named based on the ‘PACKAGE’ and ‘VERSION’ variables |
| automatically defined by either the ‘AC_INIT’ invocation or by a |
| _deprecated_ two-arguments invocation of the ‘AM_INIT_AUTOMAKE’ macro |
| (see *note Public Macros:: for how these variables get their values, |
| from either defaults or explicit values – it’s slightly trickier than |
| one would expect). More precisely the gzipped ‘tar’ file is named |
| ‘${PACKAGE}-${VERSION}.tar.gz’. You can use the ‘make’ variable |
| ‘GZIP_ENV’ to control how gzip is run. The default setting is ‘--best’. |
| |
| For the most part, the files to distribute are automatically found by |
| Automake: all source files are automatically included in a distribution, |
| as are all ‘Makefile.am’ and ‘Makefile.in’ files. Automake also has a |
| built-in list of commonly used files that are automatically included if |
| they are found in the current directory (either physically, or as the |
| target of a ‘Makefile.am’ rule); this list is printed by ‘automake |
| --help’. Note that some files in this list are actually distributed |
| only if other certain conditions hold (for example, the ‘config.h.top’ |
| and ‘config.h.bot’ files are automatically distributed only if, e.g., |
| ‘AC_CONFIG_HEADERS([config.h])’ is used in ‘configure.ac’). Also, files |
| that are read by ‘configure’ (i.e. the source files corresponding to the |
| files specified in various Autoconf macros such as ‘AC_CONFIG_FILES’ and |
| siblings) are automatically distributed. Files included in a |
| ‘Makefile.am’ (using ‘include’) or in ‘configure.ac’ (using |
| ‘m4_include’), and helper scripts installed with ‘automake |
| --add-missing’ are also distributed. |
| |
| Still, sometimes there are files that must be distributed, but which |
| are not covered in the automatic rules. These files should be listed in |
| the ‘EXTRA_DIST’ variable. You can mention files from subdirectories in |
| ‘EXTRA_DIST’. |
| |
| You can also mention a directory in ‘EXTRA_DIST’; in this case the |
| entire directory will be recursively copied into the distribution. |
| Please note that this will also copy _everything_ in the directory, |
| including, e.g., Subversion’s ‘.svn’ private directories or CVS/RCS |
| version control files; thus we recommend against using this feature |
| as-is. However, you can use the ‘dist-hook’ feature to ameliorate the |
| problem; *note The dist Hook::. |
| |
| If you define ‘SUBDIRS’, Automake will recursively include the |
| subdirectories in the distribution. If ‘SUBDIRS’ is defined |
| conditionally (*note Conditionals::), Automake will normally include all |
| directories that could possibly appear in ‘SUBDIRS’ in the distribution. |
| If you need to specify the set of directories conditionally, you can set |
| the variable ‘DIST_SUBDIRS’ to the exact list of subdirectories to |
| include in the distribution (*note Conditional Subdirectories::). |
| |
| |
| File: automake.info, Node: Fine-grained Distribution Control, Next: The dist Hook, Prev: Basics of Distribution, Up: Dist |
| |
| 14.2 Fine-grained Distribution Control |
| ====================================== |
| |
| Sometimes you need tighter control over what does _not_ go into the |
| distribution; for instance, you might have source files that are |
| generated and that you do not want to distribute. In this case Automake |
| gives fine-grained control using the ‘dist’ and ‘nodist’ prefixes. Any |
| primary or ‘_SOURCES’ variable can be prefixed with ‘dist_’ to add the |
| listed files to the distribution. Similarly, ‘nodist_’ can be used to |
| omit the files from the distribution. |
| |
| As an example, here is how you would cause some data to be |
| distributed while leaving some source code out of the distribution: |
| |
| dist_data_DATA = distribute-this |
| bin_PROGRAMS = foo |
| nodist_foo_SOURCES = do-not-distribute.c |
| |
| |
| File: automake.info, Node: The dist Hook, Next: Checking the Distribution, Prev: Fine-grained Distribution Control, Up: Dist |
| |
| 14.3 The dist Hook |
| ================== |
| |
| Occasionally it is useful to be able to change the distribution before |
| it is packaged up. If the ‘dist-hook’ rule exists, it is run after the |
| distribution directory is filled, but before the actual distribution |
| archives are created. One way to use this is for removing unnecessary |
| files that get recursively included by specifying a directory in |
| ‘EXTRA_DIST’: |
| |
| EXTRA_DIST = doc |
| dist-hook: |
| rm -rf `find $(distdir)/doc -type d -name .svn` |
| |
| Note that the ‘dist-hook’ recipe shouldn’t assume that the regular files |
| in the distribution directory are writable; this might not be the case |
| if one is packaging from a read-only source tree, or when a ‘make |
| distcheck’ is being done. For similar reasons, the recipe shouldn’t |
| assume that the subdirectories put into the distribution directory as |
| effect of having them listed in ‘EXTRA_DIST’ are writable. So, if the |
| ‘dist-hook’ recipe wants to modify the content of an existing file (or |
| ‘EXTRA_DIST’ subdirectory) in the distribution directory, it should |
| explicitly to make it writable first: |
| |
| EXTRA_DIST = README doc |
| dist-hook: |
| chmod u+w $(distdir)/README $(distdir)/doc |
| echo "Distribution date: `date`" >> README |
| rm -f $(distdir)/doc/HACKING |
| |
| Two variables that come handy when writing ‘dist-hook’ rules are |
| ‘$(distdir)’ and ‘$(top_distdir)’. |
| |
| ‘$(distdir)’ points to the directory where the ‘dist’ rule will copy |
| files from the current directory before creating the tarball. If you |
| are at the top-level directory, then ‘distdir = $(PACKAGE)-$(VERSION)’. |
| When used from subdirectory named ‘foo/’, then ‘distdir = |
| ../$(PACKAGE)-$(VERSION)/foo’. ‘$(distdir)’ can be a relative or |
| absolute path, do not assume any form. |
| |
| ‘$(top_distdir)’ always points to the root directory of the |
| distributed tree. At the top-level it’s equal to ‘$(distdir)’. In the |
| ‘foo/’ subdirectory ‘top_distdir = ../$(PACKAGE)-$(VERSION)’. |
| ‘$(top_distdir)’ too can be a relative or absolute path. |
| |
| Note that when packages are nested using ‘AC_CONFIG_SUBDIRS’ (*note |
| Subpackages::), then ‘$(distdir)’ and ‘$(top_distdir)’ are relative to |
| the package where ‘make dist’ was run, not to any sub-packages involved. |
| |
| |
| File: automake.info, Node: Checking the Distribution, Next: The Types of Distributions, Prev: The dist Hook, Up: Dist |
| |
| 14.4 Checking the Distribution |
| ============================== |
| |
| Automake also generates a ‘distcheck’ rule that can be of help to ensure |
| that a given distribution will actually work. Simplifying a bit, we can |
| say this rule first makes a distribution, and then, _operating from it_, |
| takes the following steps: |
| • tries to do a ‘VPATH’ build (*note VPATH Builds::), with the |
| ‘srcdir’ and all its content made _read-only_; |
| • runs the test suite (with ‘make check’) on this fresh build; |
| • installs the package in a temporary directory (with ‘make |
| install’), and tries runs the test suite on the resulting |
| installation (with ‘make installcheck’); |
| • checks that the package can be correctly uninstalled (by ‘make |
| uninstall’) and cleaned (by ‘make distclean’); |
| • finally, makes another tarball to ensure the distribution is |
| self-contained. |
| |
| All of these actions are performed in a temporary directory. Please |
| note that the exact location and the exact structure of such a directory |
| (where the read-only sources are placed, how the temporary build and |
| install directories are named and how deeply they are nested, etc.) is |
| to be considered an implementation detail, which can change at any time; |
| so do not reply on it. |
| |
| DISTCHECK_CONFIGURE_FLAGS |
| ------------------------- |
| |
| Building the package involves running ‘./configure’. If you need to |
| supply additional flags to ‘configure’, define them in the |
| ‘AM_DISTCHECK_CONFIGURE_FLAGS’ variable in your top-level ‘Makefile.am’. |
| The user can still extend or override the flags provided there by |
| defining the ‘DISTCHECK_CONFIGURE_FLAGS’ variable, on the command line |
| when invoking ‘make’. It’s worth nothing that ‘make distcheck’ needs |
| complete control over the ‘configure’ options ‘--srcdir’ and ‘--prefix’, |
| so those options cannot be overridden by ‘AM_DISTCHECK_CONFIGURE_FLAGS’ |
| nor by ‘DISTCHECK_CONFIGURE_FLAGS’. |
| |
| Also note that developers are encouraged to strive to make their code |
| buildable without requiring any special configure option; thus, in |
| general, you shouldn’t define ‘AM_DISTCHECK_CONFIGURE_FLAGS’. However, |
| there might be few scenarios in which the use of this variable is |
| justified. GNU ‘m4’ offers an example. GNU ‘m4’ configures by default |
| with its experimental and seldom used "changeword" feature disabled; so |
| in its case it is useful to have ‘make distcheck’ run configure with the |
| ‘--with-changeword’ option, to ensure that the code for changeword |
| support still compiles correctly. GNU ‘m4’ also employs the |
| ‘AM_DISTCHECK_CONFIGURE_FLAGS’ variable to stress-test the use of |
| ‘--program-prefix=g’, since at one point the ‘m4’ build system had a bug |
| where ‘make installcheck’ was wrongly assuming it could blindly test |
| "‘m4’", rather than the just-installed "‘gm4’". |
| |
| distcheck-hook |
| -------------- |
| |
| If the ‘distcheck-hook’ rule is defined in your top-level ‘Makefile.am’, |
| then it will be invoked by ‘distcheck’ after the new distribution has |
| been unpacked, but before the unpacked copy is configured and built. |
| Your ‘distcheck-hook’ can do almost anything, though as always caution |
| is advised. Generally this hook is used to check for potential |
| distribution errors not caught by the standard mechanism. Note that |
| ‘distcheck-hook’ as well as ‘AM_DISTCHECK_CONFIGURE_FLAGS’ and |
| ‘DISTCHECK_CONFIGURE_FLAGS’ are not honored in a subpackage |
| ‘Makefile.am’, but the flags from ‘AM_DISTCHECK_CONFIGURE_FLAGS’ and |
| ‘DISTCHECK_CONFIGURE_FLAGS’ are passed down to the ‘configure’ script of |
| the subpackage. |
| |
| distcleancheck |
| -------------- |
| |
| Speaking of potential distribution errors, ‘distcheck’ also ensures that |
| the ‘distclean’ rule actually removes all built files. This is done by |
| running ‘make distcleancheck’ at the end of the ‘VPATH’ build. By |
| default, ‘distcleancheck’ will run ‘distclean’ and then make sure the |
| build tree has been emptied by running ‘$(distcleancheck_listfiles)’. |
| Usually this check will find generated files that you forgot to add to |
| the ‘DISTCLEANFILES’ variable (*note Clean::). |
| |
| The ‘distcleancheck’ behavior should be OK for most packages, |
| otherwise you have the possibility to override the definition of either |
| the ‘distcleancheck’ rule, or the ‘$(distcleancheck_listfiles)’ |
| variable. For instance, to disable ‘distcleancheck’ completely, add the |
| following rule to your top-level ‘Makefile.am’: |
| |
| distcleancheck: |
| @: |
| |
| If you want ‘distcleancheck’ to ignore built files that have not been |
| cleaned because they are also part of the distribution, add the |
| following definition instead: |
| |
| distcleancheck_listfiles = \ |
| find . -type f -exec sh -c 'test -f $(srcdir)/$$1 || echo $$1' \ |
| sh '{}' ';' |
| |
| The above definition is not the default because it’s usually an error |
| if your Makefiles cause some distributed files to be rebuilt when the |
| user build the package. (Think about the user missing the tool required |
| to build the file; or if the required tool is built by your package, |
| consider the cross-compilation case where it can’t be run.) There is an |
| entry in the FAQ about this (*note Errors with distclean::), make sure |
| you read it before playing with ‘distcleancheck_listfiles’. |
| |
| distuninstallcheck |
| ------------------ |
| |
| ‘distcheck’ also checks that the ‘uninstall’ rule works properly, both |
| for ordinary and ‘DESTDIR’ builds. It does this by invoking ‘make |
| uninstall’, and then it checks the install tree to see if any files are |
| left over. This check will make sure that you correctly coded your |
| ‘uninstall’-related rules. |
| |
| By default, the checking is done by the ‘distuninstallcheck’ rule, |
| and the list of files in the install tree is generated by |
| ‘$(distuninstallcheck_listfiles)’ (this is a variable whose value is a |
| shell command to run that prints the list of files to stdout). |
| |
| Either of these can be overridden to modify the behavior of |
| ‘distcheck’. For instance, to disable this check completely, you would |
| write: |
| |
| distuninstallcheck: |
| @: |
| |
| |
| File: automake.info, Node: The Types of Distributions, Prev: Checking the Distribution, Up: Dist |
| |
| 14.5 The Types of Distributions |
| =============================== |
| |
| Automake generates rules to provide archives of the project for |
| distributions in various formats. Their targets are: |
| |
| ‘dist-gzip’ |
| Generate a ‘gzip’ tar archive of the distribution. This is the |
| only format enabled by default. |
| |
| ‘dist-bzip2’ |
| Generate a ‘bzip2’ tar archive of the distribution. bzip2 archives |
| are frequently smaller than gzipped archives. By default, this |
| rule makes ‘bzip2’ use a compression option of ‘-9’. To make it |
| use a different one, set the ‘BZIP2’ environment variable. For |
| example, ‘make dist-bzip2 BZIP2=-7’. |
| |
| ‘dist-lzip’ |
| Generate an ‘lzip’ tar archive of the distribution. ‘lzip’ |
| archives are frequently smaller than ‘bzip2’-compressed archives. |
| |
| ‘dist-xz’ |
| Generate an ‘xz’ tar archive of the distribution. ‘xz’ archives |
| are frequently smaller than ‘bzip2’-compressed archives. By |
| default, this rule makes ‘xz’ use a compression option of ‘-e’. To |
| make it use a different one, set the ‘XZ_OPT’ environment variable. |
| For example, run this command to use the default compression ratio, |
| but with a progress indicator: ‘make dist-xz XZ_OPT=-ve’. |
| |
| ‘dist-zip’ |
| Generate a ‘zip’ archive of the distribution. |
| |
| ‘dist-tarZ’ |
| Generate a tar archive of the distribution, compressed with the |
| historical (and obsolescent) program ‘compress’. This option is |
| deprecated, and it and the corresponding functionality will be |
| removed altogether in Automake 2.0. |
| |
| ‘dist-shar’ |
| Generate a ‘shar’ archive of the distribution. This format archive |
| is obsolescent, and use of this option is deprecated. It and the |
| corresponding functionality will be removed altogether in Automake |
| 2.0. |
| |
| The rule ‘dist’ (and its historical synonym ‘dist-all’) will create |
| archives in all the enabled formats (*note List of Automake options:: |
| for how to change this list). By default, only the ‘dist-gzip’ target |
| is hooked to ‘dist’. |
| |
| |
| File: automake.info, Node: Tests, Next: Rebuilding, Prev: Dist, Up: Top |
| |
| 15 Support for test suites |
| ************************** |
| |
| Automake can generate code to handle two kinds of test suites. One is |
| based on integration with the ‘dejagnu’ framework. The other (and most |
| used) form is based on the use of generic test scripts, and its |
| activation is triggered by the definition of the special ‘TESTS’ |
| variable. This second form allows for various degrees of sophistication |
| and customization; in particular, it allows for concurrent execution of |
| test scripts, use of established test protocols such as TAP, and |
| definition of custom test drivers and test runners. |
| |
| In either case, the testsuite is invoked via ‘make check’. |
| |
| * Menu: |
| |
| * Generalities about Testing:: Concepts and terminology about testing |
| * Simple Tests:: Listing test scripts in ‘TESTS’ |
| * Custom Test Drivers:: Writing and using custom test drivers |
| * Using the TAP test protocol:: Integrating test scripts that use the TAP protocol |
| * DejaGnu Tests:: Interfacing with the ‘dejagnu’ testing framework |
| * Install Tests:: Running tests on installed packages |
| |
| |
| File: automake.info, Node: Generalities about Testing, Next: Simple Tests, Up: Tests |
| |
| 15.1 Generalities about Testing |
| =============================== |
| |
| The purpose of testing is to determine whether a program or system |
| behaves as expected (e.g., known inputs produce the expected outputs, |
| error conditions are correctly handled or reported, and older bugs do |
| not resurface). |
| |
| The minimal unit of testing is usually called _test case_, or simply |
| _test_. How a test case is defined or delimited, and even what exactly |
| _constitutes_ a test case, depends heavily on the testing paradigm |
| and/or framework in use, so we won’t attempt any more precise |
| definition. The set of the test cases for a given program or system |
| constitutes its _testsuite_. |
| |
| A _test harness_ (also _testsuite harness_) is a program or software |
| component that executes all (or part of) the defined test cases, |
| analyzes their outcomes, and report or register these outcomes |
| appropriately. Again, the details of how this is accomplished (and how |
| the developer and user can influence it or interface with it) varies |
| wildly, and we’ll attempt no precise definition. |
| |
| A test is said to _pass_ when it can determine that the condition or |
| behaviour it means to verify holds, and is said to _fail_ when it can |
| determine that such condition of behaviour does _not_ hold. |
| |
| Sometimes, tests can rely on non-portable tools or prerequisites, or |
| simply make no sense on a given system (for example, a test checking a |
| Windows-specific feature makes no sense on a GNU/Linux system). In this |
| case, accordingly to the definition above, the tests can neither be |
| considered passed nor failed; instead, they are _skipped_ – i.e., they |
| are not run, or their result is anyway ignored for what concerns the |
| count of failures an successes. Skips are usually explicitly reported |
| though, so that the user will be aware that not all of the testsuite has |
| really run. |
| |
| It’s not uncommon, especially during early development stages, that |
| some tests fail for known reasons, and that the developer doesn’t want |
| to tackle these failures immediately (this is especially true when the |
| failing tests deal with corner cases). In this situation, the better |
| policy is to declare that each of those failures is an _expected |
| failure_ (or _xfail_). In case a test that is expected to fail ends up |
| passing instead, many testing environments will flag the result as a |
| special kind of failure called _unexpected pass_ (or _xpass_). |
| |
| Many testing environments and frameworks distinguish between test |
| failures and hard errors. As we’ve seen, a test failure happens when |
| some invariant or expected behaviour of the software under test is not |
| met. An _hard error_ happens when e.g., the set-up of a test case |
| scenario fails, or when some other unexpected or highly undesirable |
| condition is encountered (for example, the program under test |
| experiences a segmentation fault). |
| |
| |
| File: automake.info, Node: Simple Tests, Next: Custom Test Drivers, Prev: Generalities about Testing, Up: Tests |
| |
| 15.2 Simple Tests |
| ================= |
| |
| * Menu: |
| |
| * Scripts-based Testsuites:: Automake-specific concepts and terminology |
| * Serial Test Harness:: Older (and discouraged) serial test harness |
| * Parallel Test Harness:: Generic concurrent test harness |
| |
| |
| File: automake.info, Node: Scripts-based Testsuites, Next: Serial Test Harness, Up: Simple Tests |
| |
| 15.2.1 Scripts-based Testsuites |
| ------------------------------- |
| |
| If the special variable ‘TESTS’ is defined, its value is taken to be a |
| list of programs or scripts to run in order to do the testing. Under |
| the appropriate circumstances, it’s possible for ‘TESTS’ to list also |
| data files to be passed to one or more test scripts defined by different |
| means (the so-called “log compilers”, *note Parallel Test Harness::). |
| |
| Test scripts can be executed serially or concurrently. Automake |
| supports both these kinds of test execution, with the parallel test |
| harness being the default. The concurrent test harness relies on the |
| concurrence capabilities (if any) offered by the underlying ‘make’ |
| implementation, and can thus only be as good as those are. |
| |
| By default, only the exit statuses of the test scripts are considered |
| when determining the testsuite outcome. But Automake allows also the |
| use of more complex test protocols, either standard (*note Using the TAP |
| test protocol::) or custom (*note Custom Test Drivers::). Note that you |
| can’t enable such protocols when the serial harness is used, though. In |
| the rest of this section we are going to concentrate mostly on |
| protocol-less tests, since we cover test protocols in a later section |
| (again, *note Custom Test Drivers::). |
| |
| When no test protocol is in use, an exit status of 0 from a test |
| script will denote a success, an exit status of 77 a skipped test, an |
| exit status of 99 an hard error, and any other exit status will denote a |
| failure. |
| |
| You may define the variable ‘XFAIL_TESTS’ to a list of tests (usually |
| a subset of ‘TESTS’) that are expected to fail; this will effectively |
| reverse the result of those tests (with the provision that skips and |
| hard errors remain untouched). You may also instruct the testsuite |
| harness to treat hard errors like simple failures, by defining the |
| ‘DISABLE_HARD_ERRORS’ make variable to a nonempty value. |
| |
| Note however that, for tests based on more complex test protocols, |
| the exact effects of ‘XFAIL_TESTS’ and ‘DISABLE_HARD_ERRORS’ might |
| change, or they might even have no effect at all (for example, in tests |
| using TAP, there is not way to disable hard errors, and the |
| ‘DISABLE_HARD_ERRORS’ variable has no effect on them). |
| |
| The result of each test case run by the scripts in ‘TESTS’ will be |
| printed on standard output, along with the test name. For test |
| protocols that allow more test cases per test script (such as TAP), a |
| number, identifier and/or brief description specific for the single test |
| case is expected to be printed in addition to the name of the test |
| script. The possible results (whose meanings should be clear from the |
| previous *note Generalities about Testing::) are ‘PASS’, ‘FAIL’, ‘SKIP’, |
| ‘XFAIL’, ‘XPASS’ and ‘ERROR’. Here is an example of output from an |
| hypothetical testsuite that uses both plain and TAP tests: |
| PASS: foo.sh |
| PASS: zardoz.tap 1 - Daemon started |
| PASS: zardoz.tap 2 - Daemon responding |
| SKIP: zardoz.tap 3 - Daemon uses /proc # SKIP /proc is not mounted |
| PASS: zardoz.tap 4 - Daemon stopped |
| SKIP: bar.sh |
| PASS: mu.tap 1 |
| XFAIL: mu.tap 2 # TODO frobnication not yet implemented |
| |
| A testsuite summary (expected to report at least the number of run, |
| skipped and failed tests) will be printed at the end of the testsuite |
| run. |
| |
| If the standard output is connected to a capable terminal, then the |
| test results and the summary are colored appropriately. The developer |
| and the user can disable colored output by setting the ‘make’ variable |
| ‘AM_COLOR_TESTS=no’; the user can in addition force colored output even |
| without a connecting terminal with ‘AM_COLOR_TESTS=always’. It’s also |
| worth noting that some ‘make’ implementations, when used in parallel |
| mode, have slightly different semantics (*note (autoconf)Parallel |
| make::), which can break the automatic detection of a connection to a |
| capable terminal. If this is the case, the user will have to resort to |
| the use of ‘AM_COLOR_TESTS=always’ in order to have the testsuite output |
| colorized. |
| |
| Test programs that need data files should look for them in ‘srcdir’ |
| (which is both a make variable and an environment variable made |
| available to the tests), so that they work when building in a separate |
| directory (*note Build Directories: (autoconf)Build Directories.), and |
| in particular for the ‘distcheck’ rule (*note Checking the |
| Distribution::). |
| |
| The ‘AM_TESTS_ENVIRONMENT’ and ‘TESTS_ENVIRONMENT’ variables can be |
| used to run initialization code and set environment variables for the |
| test scripts. The former variable is developer-reserved, and can be |
| defined in the ‘Makefile.am’, while the latter is reserved for the user, |
| which can employ it to extend or override the settings in the former; |
| for this to work portably, however, the contents of a non-empty |
| ‘AM_TESTS_ENVIRONMENT’ _must_ be terminated by a semicolon. |
| |
| The ‘AM_TESTS_FD_REDIRECT’ variable can be used to define file |
| descriptor redirections for the test scripts. One might think that |
| ‘AM_TESTS_ENVIRONMENT’ could be used for this purpose, but experience |
| has shown that doing so portably is practically impossible. The main |
| hurdle is constituted by Korn shells, which usually set the |
| close-on-exec flag on file descriptors opened with the ‘exec’ builtin, |
| thus rendering an idiom like ‘AM_TESTS_ENVIRONMENT = exec 9>&2;’ |
| ineffectual. This issue also affects some Bourne shells, such as the |
| HP-UX’s ‘/bin/sh’, |
| |
| AM_TESTS_ENVIRONMENT = \ |
| ## Some environment initializations are kept in a separate shell |
| ## file 'tests-env.sh', which can make it easier to also run tests |
| ## from the command line. |
| . $(srcdir)/tests-env.sh; \ |
| ## On Solaris, prefer more POSIX-compliant versions of the standard |
| ## tools by default. |
| if test -d /usr/xpg4/bin; then \ |
| PATH=/usr/xpg4/bin:$$PATH; export PATH; \ |
| fi; |
| ## With this, the test scripts will be able to print diagnostic |
| ## messages to the original standard error stream, even if the test |
| ## driver redirects the stderr of the test scripts to a log file |
| ## before executing them. |
| AM_TESTS_FD_REDIRECT = 9>&2 |
| |
| Note however that ‘AM_TESTS_ENVIRONMENT’ is, for historical and |
| implementation reasons, _not_ supported by the serial harness (*note |
| Serial Test Harness::). |
| |
| Automake ensures that each file listed in ‘TESTS’ is built before it |
| is run; you can list both source and derived programs (or scripts) in |
| ‘TESTS’; the generated rule will look both in ‘srcdir’ and ‘.’. For |
| instance, you might want to run a C program as a test. To do this you |
| would list its name in ‘TESTS’ and also in ‘check_PROGRAMS’, and then |
| specify it as you would any other program. |
| |
| Programs listed in ‘check_PROGRAMS’ (and ‘check_LIBRARIES’, |
| ‘check_LTLIBRARIES’...) are only built during ‘make check’, not during |
| ‘make all’. You should list there any program needed by your tests that |
| does not need to be built by ‘make all’. Note that ‘check_PROGRAMS’ are |
| _not_ automatically added to ‘TESTS’ because ‘check_PROGRAMS’ usually |
| lists programs used by the tests, not the tests themselves. Of course |
| you can set ‘TESTS = $(check_PROGRAMS)’ if all your programs are test |
| cases. |
| |
| |
| File: automake.info, Node: Serial Test Harness, Next: Parallel Test Harness, Prev: Scripts-based Testsuites, Up: Simple Tests |
| |
| 15.2.2 Older (and discouraged) serial test harness |
| -------------------------------------------------- |
| |
| First, note that today the use of this harness is strongly discouraged |
| in favour of the parallel test harness (*note Parallel Test Harness::). |
| Still, there are _few_ situations when the advantages offered by the |
| parallel harness are irrelevant, and when test concurrency can even |
| cause tricky problems. In those cases, it might make sense to still use |
| the serial harness, for simplicity and reliability (we still suggest |
| trying to give the parallel harness a shot though). |
| |
| The serial test harness is enabled by the Automake option |
| ‘serial-tests’. It operates by simply running the tests serially, one |
| at the time, without any I/O redirection. It’s up to the user to |
| implement logging of tests’ output, if that’s requited or desired. |
| |
| For historical and implementation reasons, the ‘AM_TESTS_ENVIRONMENT’ |
| variable is _not_ supported by this harness (it will be silently ignored |
| if defined); only ‘TESTS_ENVIRONMENT’ is, and it is to be considered a |
| developer-reserved variable. This is done so that, when using the |
| serial harness, ‘TESTS_ENVIRONMENT’ can be defined to an invocation of |
| an interpreter through which the tests are to be run. For instance, the |
| following setup may be used to run tests with Perl: |
| |
| TESTS_ENVIRONMENT = $(PERL) -Mstrict -w |
| TESTS = foo.pl bar.pl baz.pl |
| |
| It’s important to note that the use of ‘TESTS_ENVIRONMENT’ endorsed here |
| would be _invalid_ with the parallel harness. That harness provides a |
| more elegant way to achieve the same effect, with the further benefit of |
| freeing the ‘TESTS_ENVIRONMENT’ variable for the user (*note Parallel |
| Test Harness::). |
| |
| Another, less serious limit of the serial harness is that it doesn’t |
| really distinguish between simple failures and hard errors; this is due |
| to historical reasons only, and might be fixed in future Automake |
| versions. |
| |
| |
| File: automake.info, Node: Parallel Test Harness, Prev: Serial Test Harness, Up: Simple Tests |
| |
| 15.2.3 Parallel Test Harness |
| ---------------------------- |
| |
| By default, Automake generated a parallel (concurrent) test harness. It |
| features automatic collection of the test scripts output in ‘.log’ |
| files, concurrent execution of tests with ‘make -j’, specification of |
| inter-test dependencies, lazy reruns of tests that have not completed in |
| a prior run, and hard errors for exceptional failures. |
| |
| The parallel test harness operates by defining a set of ‘make’ rules |
| that run the test scripts listed in ‘TESTS’, and, for each such script, |
| save its output in a corresponding ‘.log’ file and its results (and |
| other “metadata”, *note API for Custom Test Drivers::) in a |
| corresponding ‘.trs’ (as in Test ReSults) file. The ‘.log’ file will |
| contain all the output emitted by the test on its standard output and |
| its standard error. The ‘.trs’ file will contain, among the other |
| things, the results of the test cases run by the script. |
| |
| The parallel test harness will also create a summary log file, |
| ‘TEST_SUITE_LOG’, which defaults to ‘test-suite.log’ and requires a |
| ‘.log’ suffix. This file depends upon all the ‘.log’ and ‘.trs’ files |
| created for the test scripts listed in ‘TESTS’. |
| |
| As with the serial harness above, by default one status line is |
| printed per completed test, and a short summary after the suite has |
| completed. However, standard output and standard error of the test are |
| redirected to a per-test log file, so that parallel execution does not |
| produce intermingled output. The output from failed tests is collected |
| in the ‘test-suite.log’ file. If the variable ‘VERBOSE’ is set, this |
| file is output after the summary. |
| |
| Each couple of ‘.log’ and ‘.trs’ files is created when the |
| corresponding test has completed. The set of log files is listed in the |
| read-only variable ‘TEST_LOGS’, and defaults to ‘TESTS’, with the |
| executable extension if any (*note EXEEXT::), as well as any suffix |
| listed in ‘TEST_EXTENSIONS’ removed, and ‘.log’ appended. Results are |
| undefined if a test file name ends in several concatenated suffixes. |
| ‘TEST_EXTENSIONS’ defaults to ‘.test’; it can be overridden by the user, |
| in which case any extension listed in it must be constituted by a dot, |
| followed by a non-digit alphabetic character, followed by any number of |
| alphabetic characters. For example, ‘.sh’, ‘.T’ and ‘.t1’ are valid |
| extensions, while ‘.x-y’, ‘.6c’ and ‘.t.1’ are not. |
| |
| It is important to note that, due to current limitations (unlikely to |
| be lifted), configure substitutions in the definition of ‘TESTS’ can |
| only work if they will expand to a list of tests that have a suffix |
| listed in ‘TEST_EXTENSIONS’. |
| |
| For tests that match an extension ‘.EXT’ listed in ‘TEST_EXTENSIONS’, |
| you can provide a custom “test runner” using the variable |
| ‘EXT_LOG_COMPILER’ (note the upper-case extension) and pass options in |
| ‘AM_EXT_LOG_FLAGS’ and allow the user to pass options in |
| ‘EXT_LOG_FLAGS’. It will cause all tests with this extension to be |
| called with this runner. For all tests without a registered extension, |
| the variables ‘LOG_COMPILER’, ‘AM_LOG_FLAGS’, and ‘LOG_FLAGS’ may be |
| used. For example, |
| |
| TESTS = foo.pl bar.py baz |
| TEST_EXTENSIONS = .pl .py |
| PL_LOG_COMPILER = $(PERL) |
| AM_PL_LOG_FLAGS = -w |
| PY_LOG_COMPILER = $(PYTHON) |
| AM_PY_LOG_FLAGS = -v |
| LOG_COMPILER = ./wrapper-script |
| AM_LOG_FLAGS = -d |
| |
| will invoke ‘$(PERL) -w foo.pl’, ‘$(PYTHON) -v bar.py’, and |
| ‘./wrapper-script -d baz’ to produce ‘foo.log’, ‘bar.log’, and |
| ‘baz.log’, respectively. The ‘foo.trs’, ‘bar.trs’ and ‘baz.trs’ files |
| will be automatically produced as a side-effect. |
| |
| It’s important to note that, differently from what we’ve seen for the |
| serial test harness (*note Serial Test Harness::), the |
| ‘AM_TESTS_ENVIRONMENT’ and ‘TESTS_ENVIRONMENT’ variables _cannot_ be use |
| to define a custom test runner; the ‘LOG_COMPILER’ and ‘LOG_FLAGS’ (or |
| their extension-specific counterparts) should be used instead: |
| |
| ## This is WRONG! |
| AM_TESTS_ENVIRONMENT = PERL5LIB='$(srcdir)/lib' $(PERL) -Mstrict -w |
| |
| ## Do this instead. |
| AM_TESTS_ENVIRONMENT = PERL5LIB='$(srcdir)/lib'; export PERL5LIB; |
| LOG_COMPILER = $(PERL) |
| AM_LOG_FLAGS = -Mstrict -w |
| |
| By default, the test suite harness will run all tests, but there are |
| several ways to limit the set of tests that are run: |
| |
| • You can set the ‘TESTS’ variable. For example, you can use a |
| command like this to run only a subset of the tests: |
| |
| env TESTS="foo.test bar.test" make -e check |
| |
| Note however that the command above will unconditionally overwrite |
| the ‘test-suite.log’ file, thus clobbering the recorded results of |
| any previous testsuite run. This might be undesirable for packages |
| whose testsuite takes long time to execute. Luckily, this problem |
| can easily be avoided by overriding also ‘TEST_SUITE_LOG’ at |
| runtime; for example, |
| |
| env TEST_SUITE_LOG=partial.log TESTS="..." make -e check |
| |
| will write the result of the partial testsuite runs to the |
| ‘partial.log’, without touching ‘test-suite.log’. |
| |
| • You can set the ‘TEST_LOGS’ variable. By default, this variable is |
| computed at ‘make’ run time from the value of ‘TESTS’ as described |
| above. For example, you can use the following: |
| |
| set x subset*.log; shift |
| env TEST_LOGS="foo.log $*" make -e check |
| |
| The comments made above about ‘TEST_SUITE_LOG’ overriding applies |
| here too. |
| |
| • By default, the test harness removes all old per-test ‘.log’ and |
| ‘.trs’ files before it starts running tests to regenerate them. |
| The variable ‘RECHECK_LOGS’ contains the set of ‘.log’ (and, by |
| implication, ‘.trs’) files which are removed. ‘RECHECK_LOGS’ |
| defaults to ‘TEST_LOGS’, which means all tests need to be |
| rechecked. By overriding this variable, you can choose which tests |
| need to be reconsidered. For example, you can lazily rerun only |
| those tests which are outdated, i.e., older than their prerequisite |
| test files, by setting this variable to the empty value: |
| |
| env RECHECK_LOGS= make -e check |
| |
| • You can ensure that all tests are rerun which have failed or passed |
| unexpectedly, by running ‘make recheck’ in the test directory. |
| This convenience target will set ‘RECHECK_LOGS’ appropriately |
| before invoking the main test harness. |
| |
| In order to guarantee an ordering between tests even with ‘make -jN’, |
| dependencies between the corresponding ‘.log’ files may be specified |
| through usual ‘make’ dependencies. For example, the following snippet |
| lets the test named ‘foo-execute.test’ depend upon completion of the |
| test ‘foo-compile.test’: |
| |
| TESTS = foo-compile.test foo-execute.test |
| foo-execute.log: foo-compile.log |
| |
| Please note that this ordering ignores the _results_ of required tests, |
| thus the test ‘foo-execute.test’ is run even if the test |
| ‘foo-compile.test’ failed or was skipped beforehand. Further, please |
| note that specifying such dependencies currently works only for tests |
| that end in one of the suffixes listed in ‘TEST_EXTENSIONS’. |
| |
| Tests without such specified dependencies may be run concurrently |
| with parallel ‘make -jN’, so be sure they are prepared for concurrent |
| execution. |
| |
| The combination of lazy test execution and correct dependencies |
| between tests and their sources may be exploited for efficient unit |
| testing during development. To further speed up the edit-compile-test |
| cycle, it may even be useful to specify compiled programs in |
| ‘EXTRA_PROGRAMS’ instead of with ‘check_PROGRAMS’, as the former allows |
| intertwined compilation and test execution (but note that |
| ‘EXTRA_PROGRAMS’ are not cleaned automatically, *note Uniform::). |
| |
| The variables ‘TESTS’ and ‘XFAIL_TESTS’ may contain conditional parts |
| as well as configure substitutions. In the latter case, however, |
| certain restrictions apply: substituted test names must end with a |
| nonempty test suffix like ‘.test’, so that one of the inference rules |
| generated by ‘automake’ can apply. For literal test names, ‘automake’ |
| can generate per-target rules to avoid this limitation. |
| |
| Please note that it is currently not possible to use ‘$(srcdir)/’ or |
| ‘$(top_srcdir)/’ in the ‘TESTS’ variable. This technical limitation is |
| necessary to avoid generating test logs in the source tree and has the |
| unfortunate consequence that it is not possible to specify distributed |
| tests that are themselves generated by means of explicit rules, in a way |
| that is portable to all ‘make’ implementations (*note (autoconf)Make |
| Target Lookup::, the semantics of FreeBSD and OpenBSD ‘make’ conflict |
| with this). In case of doubt you may want to require to use GNU ‘make’, |
| or work around the issue with inference rules to generate the tests. |
| |
| |
| File: automake.info, Node: Custom Test Drivers, Next: Using the TAP test protocol, Prev: Simple Tests, Up: Tests |
| |
| 15.3 Custom Test Drivers |
| ======================== |
| |
| * Menu: |
| |
| * Overview of Custom Test Drivers Support:: |
| * Declaring Custom Test Drivers:: |
| * API for Custom Test Drivers:: |
| |
| |
| File: automake.info, Node: Overview of Custom Test Drivers Support, Next: Declaring Custom Test Drivers, Up: Custom Test Drivers |
| |
| 15.3.1 Overview of Custom Test Drivers Support |
| ---------------------------------------------- |
| |
| Starting from Automake version 1.12, the parallel test harness allows |
| the package authors to use third-party custom test drivers, in case the |
| default ones are inadequate for their purposes, or do not support their |
| testing protocol of choice. |
| |
| A custom test driver is expected to properly run the test programs |
| passed to it (including the command-line arguments passed to those |
| programs, if any), to analyze their execution and outcome, to create the |
| ‘.log’ and ‘.trs’ files associated to these test runs, and to display |
| the test results on the console. It is responsibility of the author of |
| the test driver to ensure that it implements all the above steps |
| meaningfully and correctly; Automake isn’t and can’t be of any help |
| here. On the other hand, the Automake-provided code for testsuite |
| summary generation offers support for test drivers allowing several test |
| results per test script, if they take care to register such results |
| properly (*note Log files generation and test results recording::). |
| |
| The exact details of how test scripts’ results are to be determined |
| and analyzed is left to the individual drivers. Some drivers might only |
| consider the test script exit status (this is done for example by the |
| default test driver used by the parallel test harness, described in the |
| previous section). Other drivers might implement more complex and |
| advanced test protocols, which might require them to parse and |
| interpreter the output emitted by the test script they’re running |
| (examples of such protocols are TAP and SubUnit). |
| |
| It’s very important to note that, even when using custom test |
| drivers, most of the infrastructure described in the previous section |
| about the parallel harness remains in place; this includes: |
| |
| • list of test scripts defined in ‘TESTS’, and overridable at runtime |
| through the redefinition of ‘TESTS’ or ‘TEST_LOGS’; |
| • concurrency through the use of ‘make’’s option ‘-j’; |
| • per-test ‘.log’ and ‘.trs’ files, and generation of a summary |
| ‘.log’ file from them; |
| • ‘recheck’ target, ‘RECHECK_LOGS’ variable, and lazy reruns of |
| tests; |
| • inter-test dependencies; |
| • support for ‘check_*’ variables (‘check_PROGRAMS’, |
| ‘check_LIBRARIES’, ...); |
| • use of ‘VERBOSE’ environment variable to get verbose output on |
| testsuite failures; |
| • definition and honoring of ‘TESTS_ENVIRONMENT’, |
| ‘AM_TESTS_ENVIRONMENT’ and ‘AM_TESTS_FD_REDIRECT’ variables; |
| • definition of generic and extension-specific ‘LOG_COMPILER’ and |
| ‘LOG_FLAGS’ variables. |
| |
| On the other hand, the exact semantics of how (and if) testsuite output |
| colorization, ‘XFAIL_TESTS’, and hard errors are supported and handled |
| is left to the individual test drivers. |
| |
| |
| File: automake.info, Node: Declaring Custom Test Drivers, Next: API for Custom Test Drivers, Prev: Overview of Custom Test Drivers Support, Up: Custom Test Drivers |
| |
| 15.3.2 Declaring Custom Test Drivers |
| ------------------------------------ |
| |
| Custom testsuite drivers are declared by defining the make variables |
| ‘LOG_DRIVER’ or ‘EXT_LOG_DRIVER’ (where EXT must be declared in |
| ‘TEST_EXTENSIONS’). They must be defined to programs or scripts that |
| will be used to drive the execution, logging, and outcome report of the |
| tests with corresponding extensions (or of those with no registered |
| extension in the case of ‘LOG_DRIVER’). Clearly, multiple distinct test |
| drivers can be declared in the same ‘Makefile.am’. Note moreover that |
| the ‘LOG_DRIVER’ variables are _not_ a substitute for the ‘LOG_COMPILER’ |
| variables: the two sets of variables can, and often do, usefully and |
| legitimately coexist. |
| |
| The developer-reserved variable ‘AM_LOG_DRIVER_FLAGS’ and the |
| user-reserved variable ‘LOG_DRIVER_FLAGS’ can be used to define flags |
| that will be passed to each invocation of ‘LOG_DRIVER’, with the |
| user-defined flags obviously taking precedence over the |
| developer-reserved ones. Similarly, for each extension EXT declared in |
| ‘TEST_EXTENSIONS’, flags listed in ‘AM_EXT_LOG_DRIVER_FLAGS’ and |
| ‘EXT_LOG_DRIVER_FLAGS’ will be passed to invocations of |
| ‘EXT_LOG_DRIVER’. |
| |
| |
| File: automake.info, Node: API for Custom Test Drivers, Prev: Declaring Custom Test Drivers, Up: Custom Test Drivers |
| |
| 15.3.3 API for Custom Test Drivers |
| ---------------------------------- |
| |
| Note that _the APIs described here are still highly experimental_, and |
| will very likely undergo tightenings and likely also extensive changes |
| in the future, to accommodate for new features or to satisfy additional |
| portability requirements. |
| |
| The main characteristic of these APIs is that they are designed to |
| share as much infrastructure, semantics, and implementation details as |
| possible with the parallel test harness and its default driver. |
| |
| * Menu: |
| |
| * Command-line arguments for test drivers:: |
| * Log files generation and test results recording:: |
| * Testsuite progress output:: |
| |
| |
| File: automake.info, Node: Command-line arguments for test drivers, Next: Log files generation and test results recording, Up: API for Custom Test Drivers |
| |
| 15.3.3.1 Command-line arguments for test drivers |
| ................................................ |
| |
| A custom driver can rely on various command-line options and arguments |
| being passed to it automatically by the Automake-generated test harness. |
| It is _mandatory_ that it understands all of them (even if the exact |
| interpretation of the associated semantics can legitimately change |
| between a test driver and another, and even be a no-op in some drivers). |
| |
| Here is the list of options: |
| |
| ‘--test-name=NAME’ |
| The name of the test, with VPATH prefix (if any) removed. This can |
| have a suffix and a directory component (as in e.g., |
| ‘sub/foo.test’), and is mostly meant to be used in console reports |
| about testsuite advancements and results (*note Testsuite progress |
| output::). |
| ‘--log-file=PATH.log’ |
| The ‘.log’ file the test driver must create (*note Basics of test |
| metadata::). If it has a directory component (as in e.g., |
| ‘sub/foo.log’), the test harness will ensure that such directory |
| exists _before_ the test driver is called. |
| ‘--trs-file=PATH.trs’ |
| The ‘.trs’ file the test driver must create (*note Basics of test |
| metadata::). If it has a directory component (as in e.g., |
| ‘sub/foo.trs’), the test harness will ensure that such directory |
| exists _before_ the test driver is called. |
| ‘--color-tests={yes|no}’ |
| Whether the console output should be colorized or not (*note Simple |
| tests and color-tests::, to learn when this option gets activated |
| and when it doesn’t). |
| ‘--expect-failure={yes|no}’ |
| Whether the tested program is expected to fail. |
| ‘--enable-hard-errors={yes|no}’ |
| Whether “hard errors” in the tested program should be treated |
| differently from normal failures or not (the default should be |
| ‘yes’). The exact meaning of “hard error” is highly dependent from |
| the test protocols or conventions in use. |
| ‘--’ |
| Explicitly terminate the list of options. |
| |
| The first non-option argument passed to the test driver is the program |
| to be run, and all the following ones are command-line options and |
| arguments for this program. |
| |
| Note that the exact semantics attached to the ‘--color-tests’, |
| ‘--expect-failure’ and ‘--enable-hard-errors’ options are left up to the |
| individual test drivers. Still, having a behaviour compatible or at |
| least similar to that provided by the default driver is advised, as that |
| would offer a better consistency and a more pleasant user experience. |
| |
| |
| File: automake.info, Node: Log files generation and test results recording, Next: Testsuite progress output, Prev: Command-line arguments for test drivers, Up: API for Custom Test Drivers |
| |
| 15.3.3.2 Log files generation and test results recording |
| ........................................................ |
| |
| The test driver must correctly generate the files specified by the |
| ‘--log-file’ and ‘--trs-file’ option (even when the tested program fails |
| or crashes). |
| |
| The ‘.log’ file should ideally contain all the output produced by the |
| tested program, plus optionally other information that might facilitate |
| debugging or analysis of bug reports. Apart from that, its format is |
| basically free. |
| |
| The ‘.trs’ file is used to register some metadata through the use of |
| custom reStructuredText fields. This metadata is expected to be |
| employed in various ways by the parallel test harness; for example, to |
| count the test results when printing the testsuite summary, or to decide |
| which tests to re-run upon ‘make recheck’. Unrecognized metadata in a |
| ‘.trs’ file is currently ignored by the harness, but this might change |
| in the future. The list of currently recognized metadata follows. |
| |
| ‘:test-result:’ |
| The test driver must use this field to register the results of |
| _each_ test case run by a test script file. Several |
| ‘:test-result:’ fields can be present in the same ‘.trs’ file; this |
| is done in order to support test protocols that allow a single test |
| script to run more test cases. |
| |
| The only recognized test results are currently ‘PASS’, ‘XFAIL’, |
| ‘SKIP’, ‘FAIL’, ‘XPASS’ and ‘ERROR’. These results, when declared |
| with ‘:test-result:’, can be optionally followed by text holding |
| the name and/or a brief description of the corresponding test; the |
| harness will ignore such extra text when generating |
| ‘test-suite.log’ and preparing the testsuite summary. |
| |
| ‘:recheck:’ |
| If this field is present and defined to ‘no’, then the |
| corresponding test script will _not_ be run upon a ‘make recheck’. |
| What happens when two or more ‘:recheck:’ fields are present in the |
| same ‘.trs’ file is undefined behaviour. |
| |
| ‘:copy-in-global-log:’ |
| If this field is present and defined to ‘no’, then the content of |
| the ‘.log’ file will _not_ be copied into the global |
| ‘test-suite.log’. We allow to forsake such copying because, while |
| it can be useful in debugging and analysis of bug report, it can |
| also be just a waste of space in normal situations, e.g., when a |
| test script is successful. What happens when two or more |
| ‘:copy-in-global-log:’ fields are present in the same ‘.trs’ file |
| is undefined behaviour. |
| |
| ‘:test-global-result:’ |
| This is used to declare the "global result" of the script. |
| Currently, the value of this field is needed only to be reported |
| (more or less verbatim) in the generated global log file |
| ‘$(TEST_SUITE_LOG)’, so it’s quite free-form. For example, a test |
| script which run 10 test cases, 6 of which pass and 4 of which are |
| skipped, could reasonably have a ‘PASS/SKIP’ value for this field, |
| while a test script which run 19 successful tests and one failed |
| test could have an ‘ALMOST PASSED’ value. What happens when two or |
| more ‘:test-global-result:’ fields are present in the same ‘.trs’ |
| file is undefined behaviour. |
| |
| Let’s see a small example. Assume a ‘.trs’ file contains the following |
| lines: |
| |
| :test-result: PASS server starts |
| :global-log-copy: no |
| :test-result: PASS HTTP/1.1 request |
| :test-result: FAIL HTTP/1.0 request |
| :recheck: yes |
| :test-result: SKIP HTTPS request (TLS library wasn't available) |
| :test-result: PASS server stops |
| |
| Then the corresponding test script will be re-run by ‘make check’, will |
| contribute with _five_ test results to the testsuite summary (three of |
| these tests being successful, one failed, and one skipped), and the |
| content of the corresponding ‘.log’ file will _not_ be copied in the |
| global log file ‘test-suite.log’. |
| |
| |
| File: automake.info, Node: Testsuite progress output, Prev: Log files generation and test results recording, Up: API for Custom Test Drivers |
| |
| 15.3.3.3 Testsuite progress output |
| .................................. |
| |
| A custom test driver also has the task of displaying, on the standard |
| output, the test results as soon as they become available. Depending on |
| the protocol in use, it can also display the reasons for failures and |
| skips, and, more generally, any useful diagnostic output (but remember |
| that each line on the screen is precious, so that cluttering the screen |
| with overly verbose information is bad idea). The exact format of this |
| progress output is left up to the test driver; in fact, a custom test |
| driver might _theoretically_ even decide not to do any such report, |
| leaving it all to the testsuite summary (that would be a very lousy |
| idea, of course, and serves only to illustrate the flexibility that is |
| granted here). |
| |
| Remember that consistency is good; so, if possible, try to be |
| consistent with the output of the built-in Automake test drivers, |
| providing a similar “look & feel”. In particular, the testsuite |
| progress output should be colorized when the ‘--color-tests’ is passed |
| to the driver. On the other end, if you are using a known and |
| widespread test protocol with well-established implementations, being |
| consistent with those implementations’ output might be a good idea too. |
| |
| |
| File: automake.info, Node: Using the TAP test protocol, Next: DejaGnu Tests, Prev: Custom Test Drivers, Up: Tests |
| |
| 15.4 Using the TAP test protocol |
| ================================ |
| |
| * Menu: |
| |
| * Introduction to TAP:: |
| * Use TAP with the Automake test harness:: |
| * Incompatibilities with other TAP parsers and drivers:: |
| * Links and external resources on TAP:: |
| |
| |
| File: automake.info, Node: Introduction to TAP, Next: Use TAP with the Automake test harness, Up: Using the TAP test protocol |
| |
| 15.4.1 Introduction to TAP |
| -------------------------- |
| |
| TAP, the Test Anything Protocol, is a simple text-based interface |
| between testing modules or programs and a test harness. The tests (also |
| called “TAP producers” in this context) write test results in a simple |
| format on standard output; a test harness (also called “TAP consumer”) |
| will parse and interpret these results, and properly present them to the |
| user, and/or register them for later analysis. The exact details of how |
| this is accomplished can vary among different test harnesses. The |
| Automake harness will present the results on the console in the usual |
| fashion (*note Testsuite progress on console::), and will use the ‘.trs’ |
| files (*note Basics of test metadata::) to store the test results and |
| related metadata. Apart from that, it will try to remain as much |
| compatible as possible with pre-existing and widespread utilities, such |
| as the ‘prove’ utility |
| (http://search.cpan.org/~andya/Test-Harness/bin/prove), at least for the |
| simpler usages. |
| |
| TAP started its life as part of the test harness for Perl, but today |
| it has been (mostly) standardized, and has various independent |
| implementations in different languages; among them, C, C++, Perl, |
| Python, PHP, and Java. For a semi-official specification of the TAP |
| protocol, please refer to the documentation of ‘Test::Harness::TAP’ |
| (http://search.cpan.org/~petdance/Test-Harness/lib/Test/Harness/TAP.pod). |
| |
| The most relevant real-world usages of TAP are obviously in the |
| testsuites of ‘perl’ and of many perl modules. Still, also other |
| important third-party packages, such as ‘git’ (http://git-scm.com/), use |
| TAP in their testsuite. |
| |
| |
| File: automake.info, Node: Use TAP with the Automake test harness, Next: Incompatibilities with other TAP parsers and drivers, Prev: Introduction to TAP, Up: Using the TAP test protocol |
| |
| 15.4.2 Use TAP with the Automake test harness |
| --------------------------------------------- |
| |
| Currently, the TAP driver that comes with Automake requires some by-hand |
| steps on the developer’s part (this situation should hopefully be |
| improved in future Automake versions). You’ll have to grab the |
| ‘tap-driver.sh’ script from the Automake distribution by hand, copy it |
| in your source tree, and use the Automake support for third-party test |
| drivers to instruct the harness to use the ‘tap-driver.sh’ script and |
| the awk program found by ‘AM_INIT_AUTOMAKE’ to run your TAP-producing |
| tests. See the example below for clarification. |
| |
| Apart from the options common to all the Automake test drivers (*note |
| Command-line arguments for test drivers::), the ‘tap-driver.sh’ supports |
| the following options, whose names are chosen for enhanced compatibility |
| with the ‘prove’ utility. |
| |
| ‘--ignore-exit’ |
| Causes the test driver to ignore the exit status of the test |
| scripts; by default, the driver will report an error if the script |
| exits with a non-zero status. This option has effect also on |
| non-zero exit statuses due to termination by a signal. |
| ‘--comments’ |
| Instruct the test driver to display TAP diagnostic (i.e., lines |
| beginning with the ‘#’ character) in the testsuite progress output |
| too; by default, TAP diagnostic is only copied to the ‘.log’ file. |
| ‘--no-comments’ |
| Revert the effects of ‘--comments’. |
| ‘--merge’ |
| Instruct the test driver to merge the test scripts’ standard error |
| into their standard output. This is necessary if you want to |
| ensure that diagnostics from the test scripts are displayed in the |
| correct order relative to test results; this can be of great help |
| in debugging (especially if your test scripts are shell scripts run |
| with shell tracing active). As a downside, this option might cause |
| the test harness to get confused if anything that appears on |
| standard error looks like a test result. |
| ‘--no-merge’ |
| Revert the effects of ‘--merge’. |
| ‘--diagnostic-string=STRING’ |
| Change the string that introduces TAP diagnostic from the default |
| value of “‘#’” to ‘STRING’. This can be useful if your TAP-based |
| test scripts produce verbose output on which they have limited |
| control (because, say, the output comes from other tools invoked in |
| the scripts), and it might contain text that gets spuriously |
| interpreted as TAP diagnostic: such an issue can be solved by |
| redefining the string that activates TAP diagnostic to a value you |
| know won’t appear by chance in the tests’ output. Note however |
| that this feature is non-standard, as the “official” TAP protocol |
| does not allow for such a customization; so don’t use it if you can |
| avoid it. |
| |
| Here is an example of how the TAP driver can be set up and used. |
| |
| % cat configure.ac |
| AC_INIT([GNU Try Tap], [1.0], [bug-automake@gnu.org]) |
| AC_CONFIG_AUX_DIR([build-aux]) |
| AM_INIT_AUTOMAKE([foreign -Wall -Werror]) |
| AC_CONFIG_FILES([Makefile]) |
| AC_REQUIRE_AUX_FILE([tap-driver.sh]) |
| AC_OUTPUT |
| |
| % cat Makefile.am |
| TEST_LOG_DRIVER = env AM_TAP_AWK='$(AWK)' $(SHELL) \ |
| $(top_srcdir)/build-aux/tap-driver.sh |
| TESTS = foo.test bar.test baz.test |
| EXTRA_DIST = $(TESTS) |
| |
| % cat foo.test |
| #!/bin/sh |
| echo 1..4 # Number of tests to be executed. |
| echo 'ok 1 - Swallows fly' |
| echo 'not ok 2 - Caterpillars fly # TODO metamorphosis in progress' |
| echo 'ok 3 - Pigs fly # SKIP not enough acid' |
| echo '# I just love word plays ...' |
| echo 'ok 4 - Flies fly too :-)' |
| |
| % cat bar.test |
| #!/bin/sh |
| echo 1..3 |
| echo 'not ok 1 - Bummer, this test has failed.' |
| echo 'ok 2 - This passed though.' |
| echo 'Bail out! Ennui kicking in, sorry...' |
| echo 'ok 3 - This will not be seen.' |
| |
| % cat baz.test |
| #!/bin/sh |
| echo 1..1 |
| echo ok 1 |
| # Exit with error, even if all the tests have been successful. |
| exit 7 |
| |
| % cp PREFIX/share/automake-APIVERSION/tap-driver.sh . |
| % autoreconf -vi && ./configure && make check |
| ... |
| PASS: foo.test 1 - Swallows fly |
| XFAIL: foo.test 2 - Caterpillars fly # TODO metamorphosis in progress |
| SKIP: foo.test 3 - Pigs fly # SKIP not enough acid |
| PASS: foo.test 4 - Flies fly too :-) |
| FAIL: bar.test 1 - Bummer, this test has failed. |
| PASS: bar.test 2 - This passed though. |
| ERROR: bar.test - Bail out! Ennui kicking in, sorry... |
| PASS: baz.test 1 |
| ERROR: baz.test - exited with status 7 |
| ... |
| Please report to bug-automake@gnu.org |
| ... |
| % echo exit status: $? |
| exit status: 1 |
| |
| % env TEST_LOG_DRIVER_FLAGS='--comments --ignore-exit' \ |
| TESTS='foo.test baz.test' make -e check |
| ... |
| PASS: foo.test 1 - Swallows fly |
| XFAIL: foo.test 2 - Caterpillars fly # TODO metamorphosis in progress |
| SKIP: foo.test 3 - Pigs fly # SKIP not enough acid |
| # foo.test: I just love word plays... |
| PASS: foo.test 4 - Flies fly too :-) |
| PASS: baz.test 1 |
| ... |
| % echo exit status: $? |
| exit status: 0 |
| |
| |
| File: automake.info, Node: Incompatibilities with other TAP parsers and drivers, Next: Links and external resources on TAP, Prev: Use TAP with the Automake test harness, Up: Using the TAP test protocol |
| |
| 15.4.3 Incompatibilities with other TAP parsers and drivers |
| ----------------------------------------------------------- |
| |
| For implementation or historical reasons, the TAP driver and harness as |
| implemented by Automake have some minors incompatibilities with the |
| mainstream versions, which you should be aware of. |
| |
| • A ‘Bail out!’ directive doesn’t stop the whole testsuite, but only |
| the test script it occurs in. This doesn’t follow TAP |
| specifications, but on the other hand it maximizes compatibility |
| (and code sharing) with the “hard error” concept of the default |
| testsuite driver. |
| • The ‘version’ and ‘pragma’ directives are not supported. |
| • The ‘--diagnostic-string’ option of our driver allows to modify the |
| string that introduces TAP diagnostic from the default value of |
| “‘#’”. The standard TAP protocol has currently no way to allow |
| this, so if you use it your diagnostic will be lost to more |
| compliant tools like ‘prove’ and ‘Test::Harness’ |
| • And there are probably some other small and yet undiscovered |
| incompatibilities, especially in corner cases or with rare usages. |
| |
| |
| File: automake.info, Node: Links and external resources on TAP, Prev: Incompatibilities with other TAP parsers and drivers, Up: Using the TAP test protocol |
| |
| 15.4.4 Links and external resources on TAP |
| ------------------------------------------ |
| |
| Here are some links to more extensive official or third-party |
| documentation and resources about the TAP protocol and related tools and |
| libraries. |
| • ‘Test::Harness::TAP’ |
| (http://search.cpan.org/~petdance/Test-Harness/lib/Test/Harness/TAP.pod), |
| the (mostly) official documentation about the TAP format and |
| protocol. |
| • ‘prove’ (http://search.cpan.org/~andya/Test-Harness/bin/prove), |
| the most famous command-line TAP test driver, included in the |
| distribution of ‘perl’ and ‘Test::Harness’ |
| (http://search.cpan.org/~andya/Test-Harness/lib/Test/Harness.pm). |
| • The TAP wiki (http://testanything.org/wiki/index.php/Main_Page). |
| • A “gentle introduction” to testing for perl coders: |
| ‘Test::Tutorial’ |
| (http://search.cpan.org/dist/Test-Simple/lib/Test/Tutorial.pod). |
| • ‘Test::Simple’ |
| (http://search.cpan.org/~mschwern/Test-Simple/lib/Test/Simple.pm) |
| and ‘Test::More’ |
| (http://search.cpan.org/~mschwern/Test-Simple/lib/Test/More.pm), |
| the standard perl testing libraries, which are based on TAP. |
| • C TAP Harness |
| (http://www.eyrie.org/~eagle/software/c-tap-harness/), a C-based |
| project implementing both a TAP producer and a TAP consumer. |
| • tap4j (http://www.tap4j.org/), a Java-based project implementing |
| both a TAP producer and a TAP consumer. |
| |
| |
| File: automake.info, Node: DejaGnu Tests, Next: Install Tests, Prev: Using the TAP test protocol, Up: Tests |
| |
| 15.5 DejaGnu Tests |
| ================== |
| |
| If ‘dejagnu’ (ftp://ftp.gnu.org/gnu/dejagnu/) appears in |
| ‘AUTOMAKE_OPTIONS’, then a ‘dejagnu’-based test suite is assumed. The |
| variable ‘DEJATOOL’ is a list of names that are passed, one at a time, |
| as the ‘--tool’ argument to ‘runtest’ invocations; it defaults to the |
| name of the package. |
| |
| The variable ‘RUNTESTDEFAULTFLAGS’ holds the ‘--tool’ and ‘--srcdir’ |
| flags that are passed to dejagnu by default; this can be overridden if |
| necessary. |
| |
| The variables ‘EXPECT’ and ‘RUNTEST’ can also be overridden to |
| provide project-specific values. For instance, you will need to do this |
| if you are testing a compiler toolchain, because the default values do |
| not take into account host and target names. |
| |
| The contents of the variable ‘RUNTESTFLAGS’ are passed to the |
| ‘runtest’ invocation. This is considered a “user variable” (*note User |
| Variables::). If you need to set ‘runtest’ flags in ‘Makefile.am’, you |
| can use ‘AM_RUNTESTFLAGS’ instead. |
| |
| Automake will generate rules to create a local ‘site.exp’ file, |
| defining various variables detected by ‘configure’. This file is |
| automatically read by DejaGnu. It is OK for the user of a package to |
| edit this file in order to tune the test suite. However this is not the |
| place where the test suite author should define new variables: this |
| should be done elsewhere in the real test suite code. Especially, |
| ‘site.exp’ should not be distributed. |
| |
| Still, if the package author has legitimate reasons to extend |
| ‘site.exp’ at ‘make’ time, he can do so by defining the variable |
| ‘EXTRA_DEJAGNU_SITE_CONFIG’; the files listed there will be considered |
| ‘site.exp’ prerequisites, and their content will be appended to it (in |
| the same order in which they appear in ‘EXTRA_DEJAGNU_SITE_CONFIG’). |
| Note that files are _not_ distributed by default. |
| |
| For more information regarding DejaGnu test suites, see *note |
| (dejagnu)Top::. |
| |
| |
| File: automake.info, Node: Install Tests, Prev: DejaGnu Tests, Up: Tests |
| |
| 15.6 Install Tests |
| ================== |
| |
| The ‘installcheck’ target is available to the user as a way to run any |
| tests after the package has been installed. You can add tests to this |
| by writing an ‘installcheck-local’ rule. |
| |
| |
| File: automake.info, Node: Rebuilding, Next: Options, Prev: Tests, Up: Top |
| |
| 16 Rebuilding Makefiles |
| *********************** |
| |
| Automake generates rules to automatically rebuild ‘Makefile’s, |
| ‘configure’, and other derived files like ‘Makefile.in’. |
| |
| If you are using ‘AM_MAINTAINER_MODE’ in ‘configure.ac’, then these |
| automatic rebuilding rules are only enabled in maintainer mode. |
| |
| Sometimes it is convenient to supplement the rebuild rules for |
| ‘configure’ or ‘config.status’ with additional dependencies. The |
| variables ‘CONFIGURE_DEPENDENCIES’ and ‘CONFIG_STATUS_DEPENDENCIES’ can |
| be used to list these extra dependencies. These variables should be |
| defined in all ‘Makefile’s of the tree (because these two rebuild rules |
| are output in all them), so it is safer and easier to ‘AC_SUBST’ them |
| from ‘configure.ac’. For instance, the following statement will cause |
| ‘configure’ to be rerun each time ‘version.sh’ is changed. |
| |
| AC_SUBST([CONFIG_STATUS_DEPENDENCIES], ['$(top_srcdir)/version.sh']) |
| |
| Note the ‘$(top_srcdir)/’ in the file name. Since this variable is to |
| be used in all ‘Makefile’s, its value must be sensible at any level in |
| the build hierarchy. |
| |
| Beware not to mistake ‘CONFIGURE_DEPENDENCIES’ for |
| ‘CONFIG_STATUS_DEPENDENCIES’. |
| |
| ‘CONFIGURE_DEPENDENCIES’ adds dependencies to the ‘configure’ rule, |
| whose effect is to run ‘autoconf’. This variable should be seldom used, |
| because ‘automake’ already tracks ‘m4_include’d files. However it can |
| be useful when playing tricky games with ‘m4_esyscmd’ or similar |
| non-recommendable macros with side effects. Be also aware that |
| interactions of this variable with the *note autom4te cache: |
| (autoconf)Autom4te Cache. are quite problematic and can cause subtle |
| breakage, so you might want to disable the cache if you want to use |
| ‘CONFIGURE_DEPENDENCIES’. |
| |
| ‘CONFIG_STATUS_DEPENDENCIES’ adds dependencies to the ‘config.status’ |
| rule, whose effect is to run ‘configure’. This variable should |
| therefore carry any non-standard source that may be read as a side |
| effect of running ‘configure’, like ‘version.sh’ in the example above. |
| |
| Speaking of ‘version.sh’ scripts, we recommend against them today. |
| They are mainly used when the version of a package is updated |
| automatically by a script (e.g., in daily builds). Here is what some |
| old-style ‘configure.ac’s may look like: |
| |
| AC_INIT |
| . $srcdir/version.sh |
| AM_INIT_AUTOMAKE([name], $VERSION_NUMBER) |
| … |
| |
| Here, ‘version.sh’ is a shell fragment that sets ‘VERSION_NUMBER’. The |
| problem with this example is that ‘automake’ cannot track dependencies |
| (listing ‘version.sh’ in ‘CONFIG_STATUS_DEPENDENCIES’, and distributing |
| this file is up to the user), and that it uses the obsolete form of |
| ‘AC_INIT’ and ‘AM_INIT_AUTOMAKE’. Upgrading to the new syntax is not |
| straightforward, because shell variables are not allowed in ‘AC_INIT’’s |
| arguments. We recommend that ‘version.sh’ be replaced by an M4 file |
| that is included by ‘configure.ac’: |
| |
| m4_include([version.m4]) |
| AC_INIT([name], VERSION_NUMBER) |
| AM_INIT_AUTOMAKE |
| … |
| |
| Here ‘version.m4’ could contain something like |
| ‘m4_define([VERSION_NUMBER], [1.2])’. The advantage of this second form |
| is that ‘automake’ will take care of the dependencies when defining the |
| rebuild rule, and will also distribute the file automatically. An |
| inconvenience is that ‘autoconf’ will now be rerun each time the version |
| number is bumped, when only ‘configure’ had to be rerun in the previous |
| setup. |
| |
| |
| File: automake.info, Node: Options, Next: Miscellaneous, Prev: Rebuilding, Up: Top |
| |
| 17 Changing Automake’s Behavior |
| ******************************* |
| |
| * Menu: |
| |
| * Options generalities:: Semantics of Automake option |
| * List of Automake options:: A comprehensive list of Automake options |
| |
| |
| File: automake.info, Node: Options generalities, Next: List of Automake options, Up: Options |
| |
| 17.1 Options generalities |
| ========================= |
| |
| Various features of Automake can be controlled by options. Except where |
| noted otherwise, options can be specified in one of several ways. Most |
| options can be applied on a per-‘Makefile’ basis when listed in a |
| special ‘Makefile’ variable named ‘AUTOMAKE_OPTIONS’. Some of these |
| options only make sense when specified in the toplevel ‘Makefile.am’ |
| file. Options are applied globally to all processed ‘Makefile’ files |
| when listed in the first argument of ‘AM_INIT_AUTOMAKE’ in |
| ‘configure.ac’, and some options which require changes to the |
| ‘configure’ script can only be specified there. These are annotated |
| below. |
| |
| As a general rule, options specified in ‘AUTOMAKE_OPTIONS’ take |
| precedence over those specified in ‘AM_INIT_AUTOMAKE’, which in turn |
| take precedence over those specified on the command line. |
| |
| Also, some care must be taken about the interactions among strictness |
| level and warning categories. As a general rule, strictness-implied |
| warnings are overridden by those specified by explicit options. For |
| example, even if ‘portability’ warnings are disabled by default in |
| ‘foreign’ strictness, an usage like this will end up enabling them: |
| |
| AUTOMAKE_OPTIONS = -Wportability foreign |
| |
| However, a strictness level specified in a higher-priority context |
| will override all the explicit warnings specified in a lower-priority |
| context. For example, if ‘configure.ac’ contains: |
| |
| AM_INIT_AUTOMAKE([-Wportability]) |
| |
| and ‘Makefile.am’ contains: |
| |
| AUTOMAKE_OPTIONS = foreign |
| |
| then ‘portability’ warnings will be _disabled_ in ‘Makefile.am’. |
| |
| |
| File: automake.info, Node: List of Automake options, Prev: Options generalities, Up: Options |
| |
| 17.2 List of Automake options |
| ============================= |
| |
| ‘gnits’ |
| ‘gnu’ |
| ‘foreign’ |
| |
| Set the strictness as appropriate. The ‘gnits’ option also implies |
| options ‘readme-alpha’ and ‘check-news’. |
| |
| ‘check-news’ |
| Cause ‘make dist’ to fail unless the current version number appears |
| in the first few lines of the ‘NEWS’ file. |
| |
| ‘dejagnu’ |
| Cause ‘dejagnu’-specific rules to be generated. *Note DejaGnu |
| Tests::. |
| |
| ‘dist-bzip2’ |
| Hook ‘dist-bzip2’ to ‘dist’. |
| |
| ‘dist-lzip’ |
| Hook ‘dist-lzip’ to ‘dist’. |
| |
| ‘dist-xz’ |
| Hook ‘dist-xz’ to ‘dist’. |
| |
| ‘dist-zip’ |
| Hook ‘dist-zip’ to ‘dist’. |
| |
| ‘dist-shar’ |
| Hook ‘dist-shar’ to ‘dist’. Use of this option is deprecated, as |
| the ‘shar’ format is obsolescent and problematic. Support for it |
| will be removed altogether in Automake 2.0. |
| |
| ‘dist-tarZ’ |
| Hook ‘dist-tarZ’ to ‘dist’. Use of this option is deprecated, as |
| the ‘compress’ program is obsolete. Support for it will be removed |
| altogether in Automake 2.0. |
| |
| ‘filename-length-max=99’ |
| Abort if file names longer than 99 characters are found during |
| ‘make dist’. Such long file names are generally considered not to |
| be portable in tarballs. See the ‘tar-v7’ and ‘tar-ustar’ options |
| below. This option should be used in the top-level ‘Makefile.am’ |
| or as an argument of ‘AM_INIT_AUTOMAKE’ in ‘configure.ac’, it will |
| be ignored otherwise. It will also be ignored in sub-packages of |
| nested packages (*note Subpackages::). |
| |
| ‘info-in-builddir’ |
| Instruct Automake to place the generated ‘.info’ files in the |
| ‘builddir’ rather than in the ‘srcdir’. Note that this might make |
| VPATH builds with some non-GNU make implementations more brittle. |
| |
| ‘no-define’ |
| This option is meaningful only when passed as an argument to |
| ‘AM_INIT_AUTOMAKE’. It will prevent the ‘PACKAGE’ and ‘VERSION’ |
| variables from being ‘AC_DEFINE’d. But notice that they will |
| remain defined as shell variables in the generated ‘configure’, and |
| as make variables in the generated ‘Makefile’; this is deliberate, |
| and required for backward compatibility. |
| |
| ‘no-dependencies’ |
| This is similar to using ‘--ignore-deps’ on the command line, but |
| is useful for those situations where you don’t have the necessary |
| bits to make automatic dependency tracking work (*note |
| Dependencies::). In this case the effect is to effectively disable |
| automatic dependency tracking. |
| |
| ‘no-dist’ |
| Don’t emit any code related to ‘dist’ target. This is useful when |
| a package has its own method for making distributions. |
| |
| ‘no-dist-gzip’ |
| Do not hook ‘dist-gzip’ to ‘dist’. |
| |
| ‘no-exeext’ |
| If your ‘Makefile.am’ defines a rule for target ‘foo’, it will |
| override a rule for a target named ‘foo$(EXEEXT)’. This is |
| necessary when ‘EXEEXT’ is found to be empty. However, by default |
| ‘automake’ will generate an error for this use. The ‘no-exeext’ |
| option will disable this error. This is intended for use only |
| where it is known in advance that the package will not be ported to |
| Windows, or any other operating system using extensions on |
| executables. |
| |
| ‘no-installinfo’ |
| The generated ‘Makefile.in’ will not cause info pages to be built |
| or installed by default. However, ‘info’ and ‘install-info’ |
| targets will still be available. This option is disallowed at |
| ‘gnu’ strictness and above. |
| |
| ‘no-installman’ |
| The generated ‘Makefile.in’ will not cause man pages to be |
| installed by default. However, an ‘install-man’ target will still |
| be available for optional installation. This option is disallowed |
| at ‘gnu’ strictness and above. |
| |
| ‘nostdinc’ |
| This option can be used to disable the standard ‘-I’ options that |
| are ordinarily automatically provided by Automake. |
| |
| ‘no-texinfo.tex’ |
| Don’t require ‘texinfo.tex’, even if there are texinfo files in |
| this directory. |
| |
| ‘serial-tests’ |
| Enable the older serial test suite harness for ‘TESTS’ (*note |
| Serial Test Harness::, for more information). |
| |
| ‘parallel-tests’ |
| Enable test suite harness for ‘TESTS’ that can run tests in |
| parallel (*note Parallel Test Harness::, for more information). |
| This option is only kept for backward-compatibility, since the |
| parallel test harness is the default now. |
| |
| ‘readme-alpha’ |
| If this release is an alpha release, and the file ‘README-alpha’ |
| exists, then it will be added to the distribution. If this option |
| is given, version numbers are expected to follow one of two forms. |
| The first form is ‘MAJOR.MINOR.ALPHA’, where each element is a |
| number; the final period and number should be left off for |
| non-alpha releases. The second form is ‘MAJOR.MINORALPHA’, where |
| ALPHA is a letter; it should be omitted for non-alpha releases. |
| |
| ‘std-options’ |
| |
| Make the ‘installcheck’ rule check that installed scripts and |
| programs support the ‘--help’ and ‘--version’ options. This also |
| provides a basic check that the program’s run-time dependencies are |
| satisfied after installation. |
| |
| In a few situations, programs (or scripts) have to be exempted from |
| this test. For instance, ‘false’ (from GNU coreutils) is never |
| successful, even for ‘--help’ or ‘--version’. You can list such |
| programs in the variable ‘AM_INSTALLCHECK_STD_OPTIONS_EXEMPT’. |
| Programs (not scripts) listed in this variable should be suffixed |
| by ‘$(EXEEXT)’ for the sake of Windows or OS/2. For instance, |
| suppose we build ‘false’ as a program but ‘true.sh’ as a script, |
| and that neither of them support ‘--help’ or ‘--version’: |
| |
| AUTOMAKE_OPTIONS = std-options |
| bin_PROGRAMS = false ... |
| bin_SCRIPTS = true.sh ... |
| AM_INSTALLCHECK_STD_OPTIONS_EXEMPT = false$(EXEEXT) true.sh |
| |
| ‘subdir-objects’ |
| If this option is specified, then objects are placed into the |
| subdirectory of the build directory corresponding to the |
| subdirectory of the source file. For instance, if the source file |
| is ‘subdir/file.cxx’, then the output file would be |
| ‘subdir/file.o’. |
| |
| ‘tar-v7’ |
| ‘tar-ustar’ |
| ‘tar-pax’ |
| |
| These three mutually exclusive options select the tar format to use |
| when generating tarballs with ‘make dist’. (The tar file created |
| is then compressed according to the set of ‘no-dist-gzip’, |
| ‘dist-bzip2’, ‘dist-lzip’, ‘dist-xz’ and ‘dist-tarZ’ options in |
| use.) |
| |
| These options must be passed as arguments to ‘AM_INIT_AUTOMAKE’ |
| (*note Macros::) because they can require additional configure |
| checks. Automake will complain if it sees such options in an |
| ‘AUTOMAKE_OPTIONS’ variable. |
| |
| ‘tar-v7’ selects the old V7 tar format. This is the historical |
| default. This antiquated format is understood by all tar |
| implementations and supports file names with up to 99 characters. |
| When given longer file names some tar implementations will diagnose |
| the problem while other will generate broken tarballs or use |
| non-portable extensions. Furthermore, the V7 format cannot store |
| empty directories. When using this format, consider using the |
| ‘filename-length-max=99’ option to catch file names too long. |
| |
| ‘tar-ustar’ selects the ustar format defined by POSIX 1003.1-1988. |
| This format is believed to be old enough to be portable. It fully |
| supports empty directories. It can store file names with up to 256 |
| characters, provided that the file name can be split at directory |
| separator in two parts, first of them being at most 155 bytes long. |
| So, in most cases the maximum file name length will be shorter than |
| 256 characters. However you may run against broken tar |
| implementations that incorrectly handle file names longer than 99 |
| characters (please report them to <bug-automake@gnu.org> so we can |
| document this accurately). |
| |
| ‘tar-pax’ selects the new pax interchange format defined by POSIX |
| 1003.1-2001. It does not limit the length of file names. However, |
| this format is very young and should probably be restricted to |
| packages that target only very modern platforms. There are moves |
| to change the pax format in an upward-compatible way, so this |
| option may refer to a more recent version in the future. |
| |
| *Note Controlling the Archive Format: (tar)Formats, for further |
| discussion about tar formats. |
| |
| ‘configure’ knows several ways to construct these formats. It will |
| not abort if it cannot find a tool up to the task (so that the |
| package can still be built), but ‘make dist’ will fail. |
| |
| VERSION |
| A version number (e.g., ‘0.30’) can be specified. If Automake is |
| not newer than the version specified, creation of the ‘Makefile.in’ |
| will be suppressed. |
| |
| ‘-WCATEGORY’ or ‘--warnings=CATEGORY’ |
| These options behave exactly like their command-line counterpart |
| (*note automake Invocation::). This allows you to enable or |
| disable some warning categories on a per-file basis. You can also |
| setup some warnings for your entire project; for instance, try |
| ‘AM_INIT_AUTOMAKE([-Wall])’ in your ‘configure.ac’. |
| |
| Unrecognized options are diagnosed by ‘automake’. |
| |
| If you want an option to apply to all the files in the tree, you can |
| use the ‘AM_INIT_AUTOMAKE’ macro in ‘configure.ac’. *Note Macros::. |
| |
| |
| File: automake.info, Node: Miscellaneous, Next: Include, Prev: Options, Up: Top |
| |
| 18 Miscellaneous Rules |
| ********************** |
| |
| There are a few rules and variables that didn’t fit anywhere else. |
| |
| * Menu: |
| |
| * Tags:: Interfacing to cscope, etags and mkid |
| * Suffixes:: Handling new file extensions |
| |
| |
| File: automake.info, Node: Tags, Next: Suffixes, Up: Miscellaneous |
| |
| 18.1 Interfacing to ‘etags’ |
| =========================== |
| |
| Automake will generate rules to generate ‘TAGS’ files for use with GNU |
| Emacs under some circumstances. |
| |
| If any C, C++ or Fortran 77 source code or headers are present, then |
| ‘tags’ and ‘TAGS’ rules will be generated for the directory. All files |
| listed using the ‘_SOURCES’, ‘_HEADERS’, and ‘_LISP’ primaries will be |
| used to generate tags. Note that generated source files that are not |
| distributed must be declared in variables like ‘nodist_noinst_HEADERS’ |
| or ‘nodist_PROG_SOURCES’ or they will be ignored. |
| |
| A ‘tags’ rule will be output at the topmost directory of a |
| multi-directory package. When run from this topmost directory, ‘make |
| tags’ will generate a ‘TAGS’ file that includes by reference all ‘TAGS’ |
| files from subdirectories. |
| |
| The ‘tags’ rule will also be generated if the variable ‘ETAGS_ARGS’ |
| is defined. This variable is intended for use in directories that |
| contain taggable source that ‘etags’ does not understand. The user can |
| use the ‘ETAGSFLAGS’ to pass additional flags to ‘etags’; |
| ‘AM_ETAGSFLAGS’ is also available for use in ‘Makefile.am’. |
| |
| Here is how Automake generates tags for its source, and for nodes in |
| its Texinfo file: |
| |
| ETAGS_ARGS = automake.in --lang=none \ |
| --regex='/^@node[ \t]+\([^,]+\)/\1/' automake.texi |
| |
| If you add file names to ‘ETAGS_ARGS’, you will probably also want to |
| define ‘TAGS_DEPENDENCIES’. The contents of this variable are added |
| directly to the dependencies for the ‘tags’ rule. |
| |
| Automake also generates a ‘ctags’ rule that can be used to build |
| ‘vi’-style ‘tags’ files. The variable ‘CTAGS’ is the name of the |
| program to invoke (by default ‘ctags’); ‘CTAGSFLAGS’ can be used by the |
| user to pass additional flags, and ‘AM_CTAGSFLAGS’ can be used by the |
| ‘Makefile.am’. |
| |
| Automake will also generate an ‘ID’ rule that will run ‘mkid’ on the |
| source. This is only supported on a directory-by-directory basis. |
| |
| Similarly, the ‘cscope’ rule will create a list of all the source |
| files in the tree and run ‘cscope’ to build an inverted index database. |
| The variable ‘CSCOPE’ is the name of the program to invoke (by default |
| ‘cscope’); ‘CSCOPEFLAGS’ and ‘CSCOPE_ARGS’ can be used by the user to |
| pass additional flags and file names respectively, while |
| ‘AM_CSCOPEFLAGS’ can be used by the ‘Makefile.am’. Note that, |
| currently, the Automake-provided ‘cscope’ support, when used in a VPATH |
| build, might not work well with non-GNU make implementations (especially |
| with make implementations performing *note VPATH rewrites: |
| (autoconf)Automatic Rule Rewriting.). |
| |
| Finally, Automake also emits rules to support the GNU Global Tags |
| program (http://www.gnu.org/software/global/). The ‘GTAGS’ rule runs |
| Global Tags and puts the result in the top build directory. The |
| variable ‘GTAGS_ARGS’ holds arguments that are passed to ‘gtags’. |
| |
| |
| File: automake.info, Node: Suffixes, Prev: Tags, Up: Miscellaneous |
| |
| 18.2 Handling new file extensions |
| ================================= |
| |
| It is sometimes useful to introduce a new implicit rule to handle a file |
| type that Automake does not know about. |
| |
| For instance, suppose you had a compiler that could compile ‘.foo’ |
| files to ‘.o’ files. You would simply define a suffix rule for your |
| language: |
| |
| .foo.o: |
| foocc -c -o $@ $< |
| |
| Then you could directly use a ‘.foo’ file in a ‘_SOURCES’ variable |
| and expect the correct results: |
| |
| bin_PROGRAMS = doit |
| doit_SOURCES = doit.foo |
| |
| This was the simpler and more common case. In other cases, you will |
| have to help Automake to figure out which extensions you are defining |
| your suffix rule for. This usually happens when your extension does not |
| start with a dot. Then, all you have to do is to put a list of new |
| suffixes in the ‘SUFFIXES’ variable *before* you define your implicit |
| rule. |
| |
| For instance, the following definition prevents Automake from |
| misinterpreting the ‘.idlC.cpp:’ rule as an attempt to transform ‘.idlC’ |
| files into ‘.cpp’ files. |
| |
| SUFFIXES = .idl C.cpp |
| .idlC.cpp: |
| # whatever |
| |
| As you may have noted, the ‘SUFFIXES’ variable behaves like the |
| ‘.SUFFIXES’ special target of ‘make’. You should not touch ‘.SUFFIXES’ |
| yourself, but use ‘SUFFIXES’ instead and let Automake generate the |
| suffix list for ‘.SUFFIXES’. Any given ‘SUFFIXES’ go at the start of |
| the generated suffixes list, followed by Automake generated suffixes not |
| already in the list. |
| |
| |
| File: automake.info, Node: Include, Next: Conditionals, Prev: Miscellaneous, Up: Top |
| |
| 19 Include |
| ********** |
| |
| Automake supports an ‘include’ directive that can be used to include |
| other ‘Makefile’ fragments when ‘automake’ is run. Note that these |
| fragments are read and interpreted by ‘automake’, not by ‘make’. As |
| with conditionals, ‘make’ has no idea that ‘include’ is in use. |
| |
| There are two forms of ‘include’: |
| |
| ‘include $(srcdir)/file’ |
| Include a fragment that is found relative to the current source |
| directory. |
| |
| ‘include $(top_srcdir)/file’ |
| Include a fragment that is found relative to the top source |
| directory. |
| |
| Note that if a fragment is included inside a conditional, then the |
| condition applies to the entire contents of that fragment. |
| |
| Makefile fragments included this way are always distributed because |
| they are needed to rebuild ‘Makefile.in’. |
| |
| Inside a fragment, the construct ‘%reldir%’ is replaced with the |
| directory of the fragment relative to the base ‘Makefile.am’. |
| Similarly, ‘%canon_reldir%’ is replaced with the canonicalized (*note |
| Canonicalization::) form of ‘%reldir%’. As a convenience, ‘%D%’ is a |
| synonym for ‘%reldir%’, and ‘%C%’ is a synonym for ‘%canon_reldir%’. |
| |
| A special feature is that if the fragment is in the same directory as |
| the base ‘Makefile.am’ (i.e., ‘%reldir%’ is ‘.’), then ‘%reldir%’ and |
| ‘%canon_reldir%’ will expand to the empty string as well as eat, if |
| present, a following slash or underscore respectively. |
| |
| Thus, a makefile fragment might look like this: |
| |
| bin_PROGRAMS += %reldir%/mumble |
| %canon_reldir%_mumble_SOURCES = %reldir%/one.c |
| |
| |
| File: automake.info, Node: Conditionals, Next: Silencing Make, Prev: Include, Up: Top |
| |
| 20 Conditionals |
| *************** |
| |
| Automake supports a simple type of conditionals. |
| |
| These conditionals are not the same as conditionals in GNU Make. |
| Automake conditionals are checked at configure time by the ‘configure’ |
| script, and affect the translation from ‘Makefile.in’ to ‘Makefile’. |
| They are based on options passed to ‘configure’ and on results that |
| ‘configure’ has discovered about the host system. GNU Make conditionals |
| are checked at ‘make’ time, and are based on variables passed to the |
| make program or defined in the ‘Makefile’. |
| |
| Automake conditionals will work with any make program. |
| |
| * Menu: |
| |
| * Usage of Conditionals:: Declaring conditional content |
| * Limits of Conditionals:: Enclosing complete statements |
| |
| |
| File: automake.info, Node: Usage of Conditionals, Next: Limits of Conditionals, Up: Conditionals |
| |
| 20.1 Usage of Conditionals |
| ========================== |
| |
| Before using a conditional, you must define it by using ‘AM_CONDITIONAL’ |
| in the ‘configure.ac’ file (*note Macros::). |
| |
| -- Macro: AM_CONDITIONAL (CONDITIONAL, CONDITION) |
| The conditional name, CONDITIONAL, should be a simple string |
| starting with a letter and containing only letters, digits, and |
| underscores. It must be different from ‘TRUE’ and ‘FALSE’ that are |
| reserved by Automake. |
| |
| The shell CONDITION (suitable for use in a shell ‘if’ statement) is |
| evaluated when ‘configure’ is run. Note that you must arrange for |
| _every_ ‘AM_CONDITIONAL’ to be invoked every time ‘configure’ is |
| run. If ‘AM_CONDITIONAL’ is run conditionally (e.g., in a shell |
| ‘if’ statement), then the result will confuse ‘automake’. |
| |
| Conditionals typically depend upon options that the user provides to |
| the ‘configure’ script. Here is an example of how to write a |
| conditional that is true if the user uses the ‘--enable-debug’ option. |
| |
| AC_ARG_ENABLE([debug], |
| [ --enable-debug Turn on debugging], |
| [case "${enableval}" in |
| yes) debug=true ;; |
| no) debug=false ;; |
| *) AC_MSG_ERROR([bad value ${enableval} for --enable-debug]) ;; |
| esac],[debug=false]) |
| AM_CONDITIONAL([DEBUG], [test x$debug = xtrue]) |
| |
| Here is an example of how to use that conditional in ‘Makefile.am’: |
| |
| if DEBUG |
| DBG = debug |
| else |
| DBG = |
| endif |
| noinst_PROGRAMS = $(DBG) |
| |
| This trivial example could also be handled using ‘EXTRA_PROGRAMS’ |
| (*note Conditional Programs::). |
| |
| You may only test a single variable in an ‘if’ statement, possibly |
| negated using ‘!’. The ‘else’ statement may be omitted. Conditionals |
| may be nested to any depth. You may specify an argument to ‘else’ in |
| which case it must be the negation of the condition used for the current |
| ‘if’. Similarly you may specify the condition that is closed on the |
| ‘endif’ line: |
| |
| if DEBUG |
| DBG = debug |
| else !DEBUG |
| DBG = |
| endif !DEBUG |
| |
| Unbalanced conditions are errors. The ‘if’, ‘else’, and ‘endif’ |
| statements should not be indented, i.e., start on column one. |
| |
| The ‘else’ branch of the above two examples could be omitted, since |
| assigning the empty string to an otherwise undefined variable makes no |
| difference. |
| |
| In order to allow access to the condition registered by |
| ‘AM_CONDITIONAL’ inside ‘configure.ac’, and to allow conditional |
| ‘AC_CONFIG_FILES’, ‘AM_COND_IF’ may be used: |
| |
| -- Macro: AM_COND_IF (CONDITIONAL, [IF-TRUE], [IF-FALSE]) |
| If CONDITIONAL is fulfilled, execute IF-TRUE, otherwise execute |
| IF-FALSE. If either branch contains ‘AC_CONFIG_FILES’, it will |
| cause ‘automake’ to output the rules for the respective files only |
| for the given condition. |
| |
| ‘AM_COND_IF’ macros may be nested when m4 quotation is used properly |
| (*note (autoconf)M4 Quotation::). |
| |
| Here is an example of how to define a conditional config file: |
| |
| AM_CONDITIONAL([SHELL_WRAPPER], [test "x$with_wrapper" = xtrue]) |
| AM_COND_IF([SHELL_WRAPPER], |
| [AC_CONFIG_FILES([wrapper:wrapper.in])]) |
| |
| |
| File: automake.info, Node: Limits of Conditionals, Prev: Usage of Conditionals, Up: Conditionals |
| |
| 20.2 Limits of Conditionals |
| =========================== |
| |
| Conditionals should enclose complete statements like variables or rules |
| definitions. Automake cannot deal with conditionals used inside a |
| variable definition, for instance, and is not even able to diagnose this |
| situation. The following example would not work: |
| |
| # This syntax is not understood by Automake |
| AM_CPPFLAGS = \ |
| -DFEATURE_A \ |
| if WANT_DEBUG |
| -DDEBUG \ |
| endif |
| -DFEATURE_B |
| |
| However the intended definition of ‘AM_CPPFLAGS’ can be achieved with |
| |
| if WANT_DEBUG |
| DEBUGFLAGS = -DDEBUG |
| endif |
| AM_CPPFLAGS = -DFEATURE_A $(DEBUGFLAGS) -DFEATURE_B |
| |
| or |
| |
| AM_CPPFLAGS = -DFEATURE_A |
| if WANT_DEBUG |
| AM_CPPFLAGS += -DDEBUG |
| endif |
| AM_CPPFLAGS += -DFEATURE_B |
| |
| More details and examples of conditionals are described alongside |
| various Automake features in this manual (*note Conditional |
| Subdirectories::, *note Conditional Sources::, *note Conditional |
| Programs::, *note Conditional Libtool Libraries::, *note Conditional |
| Libtool Sources::). |
| |
| |
| File: automake.info, Node: Silencing Make, Next: Gnits, Prev: Conditionals, Up: Top |
| |
| 21 Silencing ‘make’ |
| ******************* |
| |
| * Menu: |
| |
| * Make verbosity:: Make is verbose by default |
| * Tricks For Silencing Make:: Standard and generic ways to silence make |
| * Automake Silent Rules:: How Automake can help in silencing make |
| |
| |
| File: automake.info, Node: Make verbosity, Next: Tricks For Silencing Make, Up: Silencing Make |
| |
| 21.1 Make is verbose by default |
| =============================== |
| |
| Normally, when executing the set of rules associated with a target, |
| ‘make’ prints each rule before it is executed. This behaviour, while |
| having been in place for a long time, and being even mandated by the |
| POSIX standard, starkly violates the “silence is golden” UNIX |
| principle(1): |
| |
| When a program has nothing interesting or surprising to say, it |
| should say nothing. Well-behaved Unix programs do their jobs |
| unobtrusively, with a minimum of fuss and bother. Silence is |
| golden. |
| |
| In fact, while such verbosity of ‘make’ can theoretically be useful |
| to track bugs and understand reasons of failures right away, it can also |
| hide warning and error messages from ‘make’-invoked tools, drowning them |
| in a flood of uninteresting and seldom useful messages, and thus |
| allowing them to go easily undetected. |
| |
| This problem can be very annoying, especially for developers, who |
| usually know quite well what’s going on behind the scenes, and for whom |
| the verbose output from ‘make’ ends up being mostly noise that hampers |
| the easy detection of potentially important warning messages. |
| |
| ---------- Footnotes ---------- |
| |
| (1) See also <http://catb.org/~esr/writings/taoup/html/ch11s09.html>. |
| |
| |
| File: automake.info, Node: Tricks For Silencing Make, Next: Automake Silent Rules, Prev: Make verbosity, Up: Silencing Make |
| |
| 21.2 Standard and generic ways to silence make |
| ============================================== |
| |
| Here we describe some common idioms/tricks to obtain a quieter make |
| output, with their relative advantages and drawbacks. In the next |
| section (*note Automake Silent Rules::) we’ll see how Automake can help |
| in this respect, providing more elaborate and flexible idioms. |
| |
| • ‘make -s’ |
| |
| This simply causes ‘make’ not to print _any_ rule before executing |
| it. |
| |
| The ‘-s’ flag is mandated by POSIX, universally supported, and its |
| purpose and function are easy to understand. |
| |
| But it also has its serious limitations too. First of all, it |
| embodies an “all or nothing” strategy, i.e., either everything is |
| silenced, or nothing is; this lack of granularity can sometimes be |
| a fatal flaw. Moreover, when the ‘-s’ flag is used, the ‘make’ |
| output might turn out to be too much terse; in case of errors, the |
| user won’t be able to easily see what rule or command have caused |
| them, or even, in case of tools with poor error reporting, what the |
| errors were! |
| |
| • ‘make >/dev/null || make’ |
| |
| Apparently, this perfectly obeys the “silence is golden” rule: |
| warnings from stderr are passed through, output reporting is done |
| only in case of error, and in that case it should provide a |
| verbose-enough report to allow an easy determination of the error |
| location and causes. |
| |
| However, calling ‘make’ two times in a row might hide errors |
| (especially intermittent ones), or subtly change the expected |
| semantic of the ‘make’ calls — things these which can clearly make |
| debugging and error assessment very difficult. |
| |
| • ‘make --no-print-directory’ |
| |
| This is GNU ‘make’ specific. When called with the |
| ‘--no-print-directory’ option, GNU ‘make’ will disable printing of |
| the working directory by invoked sub-‘make’s (the well-known |
| “Entering/Leaving directory ...” messages). This helps to decrease |
| the verbosity of the output, but experience has shown that it can |
| also often render debugging considerably harder in projects using |
| deeply-nested ‘make’ recursion. |
| |
| As an aside, notice that the ‘--no-print-directory’ option is |
| automatically activated if the ‘-s’ flag is used. |
| |
| |
| File: automake.info, Node: Automake Silent Rules, Prev: Tricks For Silencing Make, Up: Silencing Make |
| |
| 21.3 How Automake can help in silencing make |
| ============================================ |
| |
| The tricks and idioms for silencing ‘make’ described in the previous |
| section can be useful from time to time, but we’ve seen that they all |
| have their serious drawbacks and limitations. That’s why automake |
| provides support for a more advanced and flexible way of obtaining |
| quieter output from ‘make’ (for most rules at least). |
| |
| To give the gist of what Automake can do in this respect, here is a |
| simple comparison between a typical ‘make’ output (where silent rules |
| are disabled) and one with silent rules enabled: |
| |
| % cat Makefile.am |
| bin_PROGRAMS = foo |
| foo_SOURCES = main.c func.c |
| % cat main.c |
| int main (void) { return func (); } /* func used undeclared */ |
| % cat func.c |
| int func (void) { int i; return i; } /* i used uninitialized */ |
| |
| The make output is by default very verbose. This causes warnings |
| from the compiler to be somewhat hidden, and not immediate to spot. |
| % make CFLAGS=-Wall |
| gcc -DPACKAGE_NAME=\"foo\" -DPACKAGE_TARNAME=\"foo\" ... |
| -DPACKAGE_STRING=\"foo\ 1.0\" -DPACKAGE_BUGREPORT=\"\" ... |
| -DPACKAGE=\"foo\" -DVERSION=\"1.0\" -I. -Wall -MT main.o |
| -MD -MP -MF .deps/main.Tpo -c -o main.o main.c |
| main.c: In function ‘main’: |
| main.c:3:3: warning: implicit declaration of function ‘func’ |
| mv -f .deps/main.Tpo .deps/main.Po |
| gcc -DPACKAGE_NAME=\"foo\" -DPACKAGE_TARNAME=\"foo\" ... |
| -DPACKAGE_STRING=\"foo\ 1.0\" -DPACKAGE_BUGREPORT=\"\" ... |
| -DPACKAGE=\"foo\" -DVERSION=\"1.0\" -I. -Wall -MT func.o |
| -MD -MP -MF .deps/func.Tpo -c -o func.o func.c |
| func.c: In function ‘func’: |
| func.c:4:3: warning: ‘i’ used uninitialized in this function |
| mv -f .deps/func.Tpo .deps/func.Po |
| gcc -Wall -o foo main.o func.o |
| |
| Clean up, so that we we can rebuild everything from scratch. |
| % make clean |
| test -z "foo" || rm -f foo |
| rm -f *.o |
| |
| Silent rules enabled: the output is minimal but informative. In |
| particular, the warnings from the compiler stick out very clearly. |
| % make V=0 CFLAGS=-Wall |
| CC main.o |
| main.c: In function ‘main’: |
| main.c:3:3: warning: implicit declaration of function ‘func’ |
| CC func.o |
| func.c: In function ‘func’: |
| func.c:4:3: warning: ‘i’ used uninitialized in this function |
| CCLD foo |
| |
| Also, in projects using ‘libtool’, the use of silent rules can |
| automatically enable the ‘libtool’’s ‘--silent’ option: |
| |
| % cat Makefile.am |
| lib_LTLIBRARIES = libx.la |
| |
| % make # Both make and libtool are verbose by default. |
| ... |
| libtool: compile: gcc -DPACKAGE_NAME=\"foo\" ... -DLT_OBJDIR=\".libs/\" |
| -I. -g -O2 -MT libx.lo -MD -MP -MF .deps/libx.Tpo -c libx.c -fPIC |
| -DPIC -o .libs/libx.o |
| mv -f .deps/libx.Tpo .deps/libx.Plo |
| /bin/sh ./libtool --tag=CC --mode=link gcc -g -O2 -o libx.la -rpath |
| /usr/local/lib libx.lo |
| libtool: link: gcc -shared .libs/libx.o -Wl,-soname -Wl,libx.so.0 |
| -o .libs/libx.so.0.0.0 |
| libtool: link: cd .libs && rm -f libx.so && ln -s libx.so.0.0.0 libx.so |
| ... |
| |
| % make V=0 |
| CC libx.lo |
| CCLD libx.la |
| |
| For Automake-generated ‘Makefile’s, the user may influence the |
| verbosity at ‘configure’ run time as well as at ‘make’ run time: |
| |
| • Passing ‘--enable-silent-rules’ to ‘configure’ will cause build |
| rules to be less verbose; the option ‘--disable-silent-rules’ will |
| cause normal verbose output. |
| • At ‘make’ run time, the default chosen at ‘configure’ time may be |
| overridden: ‘make V=1’ will produce verbose output, ‘make V=0’ less |
| verbose output. |
| |
| Note that silent rules are _disabled_ by default; the user must |
| enable them explicitly at either ‘configure’ run time or at ‘make’ run |
| time. We think that this is a good policy, since it provides the casual |
| user with enough information to prepare a good bug report in case |
| anything breaks. |
| |
| Still, notwithstanding the rationales above, a developer who really |
| wants to make silent rules enabled by default in his own package can do |
| so by calling ‘AM_SILENT_RULES([yes])’ in ‘configure.ac’. |
| |
| Users who prefer to have silent rules enabled by default can edit |
| their ‘config.site’ file to make the variable ‘enable_silent_rules’ |
| default to ‘yes’. This should still allow disabling silent rules at |
| ‘configure’ time and at ‘make’ time. |
| |
| For portability to different ‘make’ implementations, package authors |
| are advised to not set the variable ‘V’ inside the ‘Makefile.am’ file, |
| to allow the user to override the value for subdirectories as well. |
| |
| To work at its best, the current implementation of this feature |
| normally uses nested variable expansion ‘$(VAR1$(V))’, a ‘Makefile’ |
| feature that is not required by POSIX 2008 but is widely supported in |
| practice. On the rare ‘make’ implementations that do not support nested |
| variable expansion, whether rules are silent is always determined at |
| configure time, and cannot be overridden at make time. Future versions |
| of POSIX are likely to require nested variable expansion, so this minor |
| limitation should go away with time. |
| |
| To extend the silent mode to your own rules, you have few choices: |
| |
| • You can use the predefined variable ‘AM_V_GEN’ as a prefix to |
| commands that should output a status line in silent mode, and |
| ‘AM_V_at’ as a prefix to commands that should not output anything |
| in silent mode. When output is to be verbose, both of these |
| variables will expand to the empty string. |
| |
| • You can silence a recipe unconditionally with ‘@’, and then use the |
| predefined variable ‘AM_V_P’ to know whether make is being run in |
| silent or verbose mode, adjust the verbose information your recipe |
| displays accordingly: |
| |
| generate-headers: |
| ... [commands defining a shell variable '$headers'] ...; \ |
| if $(AM_V_P); then set -x; else echo " GEN [headers]"; fi; \ |
| rm -f $$headers && generate-header --flags $$headers |
| |
| • You can add your own variables, so strings of your own choice are |
| shown. The following snippet shows how you would define your own |
| equivalent of ‘AM_V_GEN’: |
| |
| pkg_verbose = $(pkg_verbose_@AM_V@) |
| pkg_verbose_ = $(pkg_verbose_@AM_DEFAULT_V@) |
| pkg_verbose_0 = @echo PKG-GEN $@; |
| |
| foo: foo.in |
| $(pkg_verbose)cp $(srcdir)/foo.in $@ |
| |
| As a final note, observe that, even when silent rules are enabled, |
| the ‘--no-print-directory’ option is still required with GNU ‘make’ if |
| the “Entering/Leaving directory ...” messages are to be disabled. |
| |
| |
| File: automake.info, Node: Gnits, Next: Not Enough, Prev: Silencing Make, Up: Top |
| |
| 22 The effect of ‘--gnu’ and ‘--gnits’ |
| ************************************** |
| |
| The ‘--gnu’ option (or ‘gnu’ in the ‘AUTOMAKE_OPTIONS’ variable) causes |
| ‘automake’ to check the following: |
| |
| • The files ‘INSTALL’, ‘NEWS’, ‘README’, ‘AUTHORS’, and ‘ChangeLog’, |
| plus one of ‘COPYING.LIB’, ‘COPYING.LESSER’ or ‘COPYING’, are |
| required at the topmost directory of the package. |
| |
| If the ‘--add-missing’ option is given, ‘automake’ will add a |
| generic version of the ‘INSTALL’ file as well as the ‘COPYING’ file |
| containing the text of the current version of the GNU General |
| Public License existing at the time of this Automake release |
| (version 3 as this is written, |
| <http://www.gnu.org/copyleft/gpl.html>). However, an existing |
| ‘COPYING’ file will never be overwritten by ‘automake’. |
| |
| • The options ‘no-installman’ and ‘no-installinfo’ are prohibited. |
| |
| Note that this option will be extended in the future to do even more |
| checking; it is advisable to be familiar with the precise requirements |
| of the GNU standards. Also, ‘--gnu’ can require certain non-standard |
| GNU programs to exist for use by various maintainer-only rules; for |
| instance, in the future ‘pathchk’ might be required for ‘make dist’. |
| |
| The ‘--gnits’ option does everything that ‘--gnu’ does, and checks |
| the following as well: |
| |
| • ‘make installcheck’ will check to make sure that the ‘--help’ and |
| ‘--version’ really print a usage message and a version string, |
| respectively. This is the ‘std-options’ option (*note Options::). |
| |
| • ‘make dist’ will check to make sure the ‘NEWS’ file has been |
| updated to the current version. |
| |
| • ‘VERSION’ is checked to make sure its format complies with Gnits |
| standards. |
| |
| • If ‘VERSION’ indicates that this is an alpha release, and the file |
| ‘README-alpha’ appears in the topmost directory of a package, then |
| it is included in the distribution. This is done in ‘--gnits’ |
| mode, and no other, because this mode is the only one where version |
| number formats are constrained, and hence the only mode where |
| Automake can automatically determine whether ‘README-alpha’ should |
| be included. |
| |
| • The file ‘THANKS’ is required. |
| |
| |
| File: automake.info, Node: Not Enough, Next: Distributing, Prev: Gnits, Up: Top |
| |
| 23 When Automake Isn’t Enough |
| ***************************** |
| |
| In some situations, where Automake is not up to one task, one has to |
| resort to handwritten rules or even handwritten ‘Makefile’s. |
| |
| * Menu: |
| |
| * Extending:: Adding new rules or overriding existing ones. |
| * Third-Party Makefiles:: Integrating Non-Automake ‘Makefile’s. |
| |
| |
| File: automake.info, Node: Extending, Next: Third-Party Makefiles, Up: Not Enough |
| |
| 23.1 Extending Automake Rules |
| ============================= |
| |
| With some minor exceptions (for example ‘_PROGRAMS’ variables, ‘TESTS’, |
| or ‘XFAIL_TESTS’) being rewritten to append ‘$(EXEEXT)’), the contents |
| of a ‘Makefile.am’ is copied to ‘Makefile.in’ verbatim. |
| |
| These copying semantics mean that many problems can be worked around |
| by simply adding some ‘make’ variables and rules to ‘Makefile.am’. |
| Automake will ignore these additions. |
| |
| Since a ‘Makefile.in’ is built from data gathered from three |
| different places (‘Makefile.am’, ‘configure.ac’, and ‘automake’ itself), |
| it is possible to have conflicting definitions of rules or variables. |
| When building ‘Makefile.in’ the following priorities are respected by |
| ‘automake’ to ensure the user always has the last word: |
| |
| • User defined variables in ‘Makefile.am’ have priority over |
| variables ‘AC_SUBST’ed from ‘configure.ac’, and ‘AC_SUBST’ed |
| variables have priority over ‘automake’-defined variables. |
| • As far as rules are concerned, a user-defined rule overrides any |
| ‘automake’-defined rule for the same target. |
| |
| These overriding semantics make it possible to fine tune some default |
| settings of Automake, or replace some of its rules. Overriding Automake |
| rules is often inadvisable, particularly in the topmost directory of a |
| package with subdirectories. The ‘-Woverride’ option (*note automake |
| Invocation::) comes in handy to catch overridden definitions. |
| |
| Note that Automake does not make any distinction between rules with |
| commands and rules that only specify dependencies. So it is not |
| possible to append new dependencies to an ‘automake’-defined target |
| without redefining the entire rule. |
| |
| However, various useful targets have a ‘-local’ version you can |
| specify in your ‘Makefile.am’. Automake will supplement the standard |
| target with these user-supplied targets. |
| |
| The targets that support a local version are ‘all’, ‘info’, ‘dvi’, |
| ‘ps’, ‘pdf’, ‘html’, ‘check’, ‘install-data’, ‘install-dvi’, |
| ‘install-exec’, ‘install-html’, ‘install-info’, ‘install-pdf’, |
| ‘install-ps’, ‘uninstall’, ‘installdirs’, ‘installcheck’ and the various |
| ‘clean’ targets (‘mostlyclean’, ‘clean’, ‘distclean’, and |
| ‘maintainer-clean’). |
| |
| Note that there are no ‘uninstall-exec-local’ or |
| ‘uninstall-data-local’ targets; just use ‘uninstall-local’. It doesn’t |
| make sense to uninstall just data or just executables. |
| |
| For instance, here is one way to erase a subdirectory during ‘make |
| clean’ (*note Clean::). |
| |
| clean-local: |
| -rm -rf testSubDir |
| |
| You may be tempted to use ‘install-data-local’ to install a file to |
| some hard-coded location, but you should avoid this (*note Hard-Coded |
| Install Paths::). |
| |
| With the ‘-local’ targets, there is no particular guarantee of |
| execution order; typically, they are run early, but with parallel make, |
| there is no way to be sure of that. |
| |
| In contrast, some rules also have a way to run another rule, called a |
| "hook"; hooks are always executed after the main rule’s work is done. |
| The hook is named after the principal target, with ‘-hook’ appended. |
| The targets allowing hooks are ‘install-data’, ‘install-exec’, |
| ‘uninstall’, ‘dist’, and ‘distcheck’. |
| |
| For instance, here is how to create a hard link to an installed |
| program: |
| |
| install-exec-hook: |
| ln $(DESTDIR)$(bindir)/program$(EXEEXT) \ |
| $(DESTDIR)$(bindir)/proglink$(EXEEXT) |
| |
| Although cheaper and more portable than symbolic links, hard links |
| will not work everywhere (for instance, OS/2 does not have ‘ln’). |
| Ideally you should fall back to ‘cp -p’ when ‘ln’ does not work. An |
| easy way, if symbolic links are acceptable to you, is to add |
| ‘AC_PROG_LN_S’ to ‘configure.ac’ (*note Particular Program Checks: |
| (autoconf)Particular Programs.) and use ‘$(LN_S)’ in ‘Makefile.am’. |
| |
| For instance, here is how you could install a versioned copy of a |
| program using ‘$(LN_S)’: |
| |
| install-exec-hook: |
| cd $(DESTDIR)$(bindir) && \ |
| mv -f prog$(EXEEXT) prog-$(VERSION)$(EXEEXT) && \ |
| $(LN_S) prog-$(VERSION)$(EXEEXT) prog$(EXEEXT) |
| |
| Note that we rename the program so that a new version will erase the |
| symbolic link, not the real binary. Also we ‘cd’ into the destination |
| directory in order to create relative links. |
| |
| When writing ‘install-exec-hook’ or ‘install-data-hook’, please bear |
| in mind that the exec/data distinction is based on the installation |
| directory, not on the primary used (*note The Two Parts of Install::). |
| So a ‘foo_SCRIPTS’ will be installed by ‘install-data’, and a |
| ‘barexec_SCRIPTS’ will be installed by ‘install-exec’. You should |
| define your hooks consequently. |
| |
| |
| File: automake.info, Node: Third-Party Makefiles, Prev: Extending, Up: Not Enough |
| |
| 23.2 Third-Party ‘Makefile’s |
| ============================ |
| |
| In most projects all ‘Makefile’s are generated by Automake. In some |
| cases, however, projects need to embed subdirectories with handwritten |
| ‘Makefile’s. For instance, one subdirectory could be a third-party |
| project with its own build system, not using Automake. |
| |
| It is possible to list arbitrary directories in ‘SUBDIRS’ or |
| ‘DIST_SUBDIRS’ provided each of these directories has a ‘Makefile’ that |
| recognizes all the following recursive targets. |
| |
| When a user runs one of these targets, that target is run recursively |
| in all subdirectories. This is why it is important that even |
| third-party ‘Makefile’s support them. |
| |
| ‘all’ |
| Compile the entire package. This is the default target in |
| Automake-generated ‘Makefile’s, but it does not need to be the |
| default in third-party ‘Makefile’s. |
| |
| ‘distdir’ |
| Copy files to distribute into ‘$(distdir)’, before a tarball is |
| constructed. Of course this target is not required if the |
| ‘no-dist’ option (*note Options::) is used. |
| |
| The variables ‘$(top_distdir)’ and ‘$(distdir)’ (*note The dist |
| Hook::) will be passed from the outer package to the subpackage |
| when the ‘distdir’ target is invoked. These two variables have |
| been adjusted for the directory that is being recursed into, so |
| they are ready to use. |
| |
| ‘install’ |
| ‘install-data’ |
| ‘install-exec’ |
| ‘uninstall’ |
| Install or uninstall files (*note Install::). |
| |
| ‘install-dvi’ |
| ‘install-html’ |
| ‘install-info’ |
| ‘install-ps’ |
| ‘install-pdf’ |
| Install only some specific documentation format (*note Texinfo::). |
| |
| ‘installdirs’ |
| Create install directories, but do not install any files. |
| |
| ‘check’ |
| ‘installcheck’ |
| Check the package (*note Tests::). |
| |
| ‘mostlyclean’ |
| ‘clean’ |
| ‘distclean’ |
| ‘maintainer-clean’ |
| Cleaning rules (*note Clean::). |
| |
| ‘dvi’ |
| ‘pdf’ |
| ‘ps’ |
| ‘info’ |
| ‘html’ |
| Build the documentation in various formats (*note Texinfo::). |
| |
| ‘tags’ |
| ‘ctags’ |
| Build ‘TAGS’ and ‘CTAGS’ (*note Tags::). |
| |
| If you have ever used Gettext in a project, this is a good example of |
| how third-party ‘Makefile’s can be used with Automake. The ‘Makefile’s |
| ‘gettextize’ puts in the ‘po/’ and ‘intl/’ directories are handwritten |
| ‘Makefile’s that implement all of these targets. That way they can be |
| added to ‘SUBDIRS’ in Automake packages. |
| |
| Directories that are only listed in ‘DIST_SUBDIRS’ but not in |
| ‘SUBDIRS’ need only the ‘distclean’, ‘maintainer-clean’, and ‘distdir’ |
| rules (*note Conditional Subdirectories::). |
| |
| Usually, many of these rules are irrelevant to the third-party |
| subproject, but they are required for the whole package to work. It’s |
| OK to have a rule that does nothing, so if you are integrating a |
| third-party project with no documentation or tag support, you could |
| simply augment its ‘Makefile’ as follows: |
| |
| EMPTY_AUTOMAKE_TARGETS = dvi pdf ps info html tags ctags |
| .PHONY: $(EMPTY_AUTOMAKE_TARGETS) |
| $(EMPTY_AUTOMAKE_TARGETS): |
| |
| Another aspect of integrating third-party build systems is whether |
| they support VPATH builds (*note VPATH Builds::). Obviously if the |
| subpackage does not support VPATH builds the whole package will not |
| support VPATH builds. This in turns means that ‘make distcheck’ will |
| not work, because it relies on VPATH builds. Some people can live |
| without this (actually, many Automake users have never heard of ‘make |
| distcheck’). Other people may prefer to revamp the existing ‘Makefile’s |
| to support VPATH. Doing so does not necessarily require Automake, only |
| Autoconf is needed (*note Build Directories: (autoconf)Build |
| Directories.). The necessary substitutions: ‘@srcdir@’, ‘@top_srcdir@’, |
| and ‘@top_builddir@’ are defined by ‘configure’ when it processes a |
| ‘Makefile’ (*note Preset Output Variables: (autoconf)Preset Output |
| Variables.), they are not computed by the Makefile like the |
| aforementioned ‘$(distdir)’ and ‘$(top_distdir)’ variables. |
| |
| It is sometimes inconvenient to modify a third-party ‘Makefile’ to |
| introduce the above required targets. For instance, one may want to |
| keep the third-party sources untouched to ease upgrades to new versions. |
| |
| Here are two other ideas. If GNU make is assumed, one possibility is |
| to add to that subdirectory a ‘GNUmakefile’ that defines the required |
| targets and includes the third-party ‘Makefile’. For this to work in |
| VPATH builds, ‘GNUmakefile’ must lie in the build directory; the easiest |
| way to do this is to write a ‘GNUmakefile.in’ instead, and have it |
| processed with ‘AC_CONFIG_FILES’ from the outer package. For example if |
| we assume ‘Makefile’ defines all targets except the documentation |
| targets, and that the ‘check’ target is actually called ‘test’, we could |
| write ‘GNUmakefile’ (or ‘GNUmakefile.in’) like this: |
| |
| # First, include the real Makefile |
| include Makefile |
| # Then, define the other targets needed by Automake Makefiles. |
| .PHONY: dvi pdf ps info html check |
| dvi pdf ps info html: |
| check: test |
| |
| A similar idea that does not use ‘include’ is to write a proxy |
| ‘Makefile’ that dispatches rules to the real ‘Makefile’, either with |
| ‘$(MAKE) -f Makefile.real $(AM_MAKEFLAGS) target’ (if it’s OK to rename |
| the original ‘Makefile’) or with ‘cd subdir && $(MAKE) $(AM_MAKEFLAGS) |
| target’ (if it’s OK to store the subdirectory project one directory |
| deeper). The good news is that this proxy ‘Makefile’ can be generated |
| with Automake. All we need are ‘-local’ targets (*note Extending::) |
| that perform the dispatch. Of course the other Automake features are |
| available, so you could decide to let Automake perform distribution or |
| installation. Here is a possible ‘Makefile.am’: |
| |
| all-local: |
| cd subdir && $(MAKE) $(AM_MAKEFLAGS) all |
| check-local: |
| cd subdir && $(MAKE) $(AM_MAKEFLAGS) test |
| clean-local: |
| cd subdir && $(MAKE) $(AM_MAKEFLAGS) clean |
| |
| # Assuming the package knows how to install itself |
| install-data-local: |
| cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-data |
| install-exec-local: |
| cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-exec |
| uninstall-local: |
| cd subdir && $(MAKE) $(AM_MAKEFLAGS) uninstall |
| |
| # Distribute files from here. |
| EXTRA_DIST = subdir/Makefile subdir/program.c ... |
| |
| Pushing this idea to the extreme, it is also possible to ignore the |
| subproject build system and build everything from this proxy |
| ‘Makefile.am’. This might sound very sensible if you need VPATH builds |
| but the subproject does not support them. |
| |
| |
| File: automake.info, Node: Distributing, Next: API Versioning, Prev: Not Enough, Up: Top |
| |
| 24 Distributing ‘Makefile.in’s |
| ****************************** |
| |
| Automake places no restrictions on the distribution of the resulting |
| ‘Makefile.in’s. We still encourage software authors to distribute their |
| work under terms like those of the GPL, but doing so is not required to |
| use Automake. |
| |
| Some of the files that can be automatically installed via the |
| ‘--add-missing’ switch do fall under the GPL. However, these also have |
| a special exception allowing you to distribute them with your package, |
| regardless of the licensing you choose. |
| |
| |
| File: automake.info, Node: API Versioning, Next: Upgrading, Prev: Distributing, Up: Top |
| |
| 25 Automake API Versioning |
| ************************** |
| |
| New Automake releases usually include bug fixes and new features. |
| Unfortunately they may also introduce new bugs and incompatibilities. |
| This makes four reasons why a package may require a particular Automake |
| version. |
| |
| Things get worse when maintaining a large tree of packages, each one |
| requiring a different version of Automake. In the past, this meant that |
| any developer (and sometimes users) had to install several versions of |
| Automake in different places, and switch ‘$PATH’ appropriately for each |
| package. |
| |
| Starting with version 1.6, Automake installs versioned binaries. |
| This means you can install several versions of Automake in the same |
| ‘$prefix’, and can select an arbitrary Automake version by running |
| ‘automake-1.6’ or ‘automake-1.7’ without juggling with ‘$PATH’. |
| Furthermore, ‘Makefile’’s generated by Automake 1.6 will use |
| ‘automake-1.6’ explicitly in their rebuild rules. |
| |
| The number ‘1.6’ in ‘automake-1.6’ is Automake’s API version, not |
| Automake’s version. If a bug fix release is made, for instance Automake |
| 1.6.1, the API version will remain 1.6. This means that a package that |
| works with Automake 1.6 should also work with 1.6.1; after all, this is |
| what people expect from bug fix releases. |
| |
| If your package relies on a feature or a bug fix introduced in a |
| release, you can pass this version as an option to Automake to ensure |
| older releases will not be used. For instance, use this in your |
| ‘configure.ac’: |
| |
| AM_INIT_AUTOMAKE([1.6.1]) dnl Require Automake 1.6.1 or better. |
| |
| or, in a particular ‘Makefile.am’: |
| |
| AUTOMAKE_OPTIONS = 1.6.1 # Require Automake 1.6.1 or better. |
| |
| Automake will print an error message if its version is older than the |
| requested version. |
| |
| What is in the API |
| ================== |
| |
| Automake’s programming interface is not easy to define. Basically it |
| should include at least all *documented* variables and targets that a |
| ‘Makefile.am’ author can use, any behavior associated with them (e.g., |
| the places where ‘-hook’’s are run), the command line interface of |
| ‘automake’ and ‘aclocal’, … |
| |
| What is not in the API |
| ====================== |
| |
| Every undocumented variable, target, or command line option, is not part |
| of the API. You should avoid using them, as they could change from one |
| version to the other (even in bug fix releases, if this helps to fix a |
| bug). |
| |
| If it turns out you need to use such an undocumented feature, contact |
| <automake@gnu.org> and try to get it documented and exercised by the |
| test-suite. |
| |
| |
| File: automake.info, Node: Upgrading, Next: FAQ, Prev: API Versioning, Up: Top |
| |
| 26 Upgrading a Package to a Newer Automake Version |
| ************************************************** |
| |
| Automake maintains three kind of files in a package. |
| |
| • ‘aclocal.m4’ |
| • ‘Makefile.in’s |
| • auxiliary tools like ‘install-sh’ or ‘py-compile’ |
| |
| ‘aclocal.m4’ is generated by ‘aclocal’ and contains some |
| Automake-supplied M4 macros. Auxiliary tools are installed by ‘automake |
| --add-missing’ when needed. ‘Makefile.in’s are built from ‘Makefile.am’ |
| by ‘automake’, and rely on the definitions of the M4 macros put in |
| ‘aclocal.m4’ as well as the behavior of the auxiliary tools installed. |
| |
| Because all of these files are closely related, it is important to |
| regenerate all of them when upgrading to a newer Automake release. The |
| usual way to do that is |
| |
| aclocal # with any option needed (such a -I m4) |
| autoconf |
| automake --add-missing --force-missing |
| |
| or more conveniently: |
| |
| autoreconf -vfi |
| |
| The use of ‘--force-missing’ ensures that auxiliary tools will be |
| overridden by new versions (*note automake Invocation::). |
| |
| It is important to regenerate all of these files each time Automake |
| is upgraded, even between bug fixes releases. For instance, it is not |
| unusual for a bug fix to involve changes to both the rules generated in |
| ‘Makefile.in’ and the supporting M4 macros copied to ‘aclocal.m4’. |
| |
| Presently ‘automake’ is able to diagnose situations where |
| ‘aclocal.m4’ has been generated with another version of ‘aclocal’. |
| However it never checks whether auxiliary scripts are up-to-date. In |
| other words, ‘automake’ will tell you when ‘aclocal’ needs to be rerun, |
| but it will never diagnose a missing ‘--force-missing’. |
| |
| Before upgrading to a new major release, it is a good idea to read |
| the file ‘NEWS’. This file lists all changes between releases: new |
| features, obsolete constructs, known incompatibilities, and workarounds. |
| |
| |
| File: automake.info, Node: FAQ, Next: Copying This Manual, Prev: Upgrading, Up: Top |
| |
| 27 Frequently Asked Questions about Automake |
| ******************************************** |
| |
| This chapter covers some questions that often come up on the mailing |
| lists. |
| |
| * Menu: |
| |
| * CVS:: CVS and generated files |
| * maintainer-mode:: missing and AM_MAINTAINER_MODE |
| * Wildcards:: Why doesn’t Automake support wildcards? |
| * Limitations on File Names:: Limitations on source and installed file names |
| * Errors with distclean:: Files left in build directory after distclean |
| * Flag Variables Ordering:: CFLAGS vs. AM_CFLAGS vs. mumble_CFLAGS |
| * Renamed Objects:: Why are object files sometimes renamed? |
| * Per-Object Flags:: How to simulate per-object flags? |
| * Multiple Outputs:: Writing rules for tools with many output files |
| * Hard-Coded Install Paths:: Installing to hard-coded locations |
| * Debugging Make Rules:: Strategies when things don’t work as expected |
| * Reporting Bugs:: Feedback on bugs and feature requests |
| |
| |
| File: automake.info, Node: CVS, Next: maintainer-mode, Up: FAQ |
| |
| 27.1 CVS and generated files |
| ============================ |
| |
| Background: distributed generated Files |
| --------------------------------------- |
| |
| Packages made with Autoconf and Automake ship with some generated files |
| like ‘configure’ or ‘Makefile.in’. These files were generated on the |
| developer’s machine and are distributed so that end-users do not have to |
| install the maintainer tools required to rebuild them. Other generated |
| files like Lex scanners, Yacc parsers, or Info documentation, are |
| usually distributed on similar grounds. |
| |
| Automake output rules in ‘Makefile’s to rebuild these files. For |
| instance, ‘make’ will run ‘autoconf’ to rebuild ‘configure’ whenever |
| ‘configure.ac’ is changed. This makes development safer by ensuring a |
| ‘configure’ is never out-of-date with respect to ‘configure.ac’. |
| |
| As generated files shipped in packages are up-to-date, and because |
| ‘tar’ preserves times-tamps, these rebuild rules are not triggered when |
| a user unpacks and builds a package. |
| |
| Background: CVS and Timestamps |
| ------------------------------ |
| |
| Unless you use CVS keywords (in which case files must be updated at |
| commit time), CVS preserves timestamp during ‘cvs commit’ and ‘cvs |
| import -d’ operations. |
| |
| When you check out a file using ‘cvs checkout’ its timestamp is set |
| to that of the revision that is being checked out. |
| |
| However, during ‘cvs update’, files will have the date of the update, |
| not the original timestamp of this revision. This is meant to make sure |
| that ‘make’ notices sources files have been updated. |
| |
| This timestamp shift is troublesome when both sources and generated |
| files are kept under CVS. Because CVS processes files in lexical order, |
| ‘configure.ac’ will appear newer than ‘configure’ after a ‘cvs update’ |
| that updates both files, even if ‘configure’ was newer than |
| ‘configure.ac’ when it was checked in. Calling ‘make’ will then trigger |
| a spurious rebuild of ‘configure’. |
| |
| Living with CVS in Autoconfiscated Projects |
| ------------------------------------------- |
| |
| There are basically two clans amongst maintainers: those who keep all |
| distributed files under CVS, including generated files, and those who |
| keep generated files _out_ of CVS. |
| |
| All Files in CVS |
| ................ |
| |
| • The CVS repository contains all distributed files so you know |
| exactly what is distributed, and you can checkout any prior version |
| entirely. |
| |
| • Maintainers can see how generated files evolve (for instance, you |
| can see what happens to your ‘Makefile.in’s when you upgrade |
| Automake and make sure they look OK). |
| |
| • Users do not need the autotools to build a checkout of the project, |
| it works just like a released tarball. |
| |
| • If users use ‘cvs update’ to update their copy, instead of ‘cvs |
| checkout’ to fetch a fresh one, timestamps will be inaccurate. |
| Some rebuild rules will be triggered and attempt to run developer |
| tools such as ‘autoconf’ or ‘automake’. |
| |
| Calls to such tools are all wrapped into a call to the ‘missing’ |
| script discussed later (*note maintainer-mode::), so that the user |
| will see more descriptive warnings about missing or out-of-date |
| tools, and possible suggestions about how to obtain them, rather |
| than just some “command not found” error, or (worse) some obscure |
| message from some older version of the required tool they happen to |
| have installed. |
| |
| Maintainers interested in keeping their package buildable from a |
| CVS checkout even for those users that lack maintainer-specific |
| tools might want to provide an helper script (or to enhance their |
| existing bootstrap script) to fix the timestamps after a ‘cvs |
| update’ or a ‘git checkout’, to prevent spurious rebuilds. In case |
| of a project committing the Autotools-generated files, as well as |
| the generated ‘.info’ files, such script might look something like |
| this: |
| |
| #!/bin/sh |
| # fix-timestamp.sh: prevents useless rebuilds after "cvs update" |
| sleep 1 |
| # aclocal-generated aclocal.m4 depends on locally-installed |
| # '.m4' macro files, as well as on 'configure.ac' |
| touch aclocal.m4 |
| sleep 1 |
| # autoconf-generated configure depends on aclocal.m4 and on |
| # configure.ac |
| touch configure |
| # so does autoheader-generated config.h.in |
| touch config.h.in |
| # and all the automake-generated Makefile.in files |
| touch `find . -name Makefile.in -print` |
| # finally, the makeinfo-generated '.info' files depend on the |
| # corresponding '.texi' files |
| touch doc/*.info |
| |
| • In distributed development, developers are likely to have different |
| version of the maintainer tools installed. In this case rebuilds |
| triggered by timestamp lossage will lead to spurious changes to |
| generated files. There are several solutions to this: |
| |
| • All developers should use the same versions, so that the |
| rebuilt files are identical to files in CVS. (This starts to |
| be difficult when each project you work on uses different |
| versions.) |
| • Or people use a script to fix the timestamp after a checkout |
| (the GCC folks have such a script). |
| • Or ‘configure.ac’ uses ‘AM_MAINTAINER_MODE’, which will |
| disable all of these rebuild rules by default. This is |
| further discussed in *note maintainer-mode::. |
| |
| • Although we focused on spurious rebuilds, the converse can also |
| happen. CVS’s timestamp handling can also let you think an |
| out-of-date file is up-to-date. |
| |
| For instance, suppose a developer has modified ‘Makefile.am’ and |
| has rebuilt ‘Makefile.in’, and then decides to do a last-minute |
| change to ‘Makefile.am’ right before checking in both files |
| (without rebuilding ‘Makefile.in’ to account for the change). |
| |
| This last change to ‘Makefile.am’ makes the copy of ‘Makefile.in’ |
| out-of-date. Since CVS processes files alphabetically, when |
| another developer ‘cvs update’s his or her tree, ‘Makefile.in’ will |
| happen to be newer than ‘Makefile.am’. This other developer will |
| not see that ‘Makefile.in’ is out-of-date. |
| |
| Generated Files out of CVS |
| .......................... |
| |
| One way to get CVS and ‘make’ working peacefully is to never store |
| generated files in CVS, i.e., do not CVS-control files that are |
| ‘Makefile’ targets (also called _derived_ files). |
| |
| This way developers are not annoyed by changes to generated files. |
| It does not matter if they all have different versions (assuming they |
| are compatible, of course). And finally, timestamps are not lost, |
| changes to sources files can’t be missed as in the |
| ‘Makefile.am’/‘Makefile.in’ example discussed earlier. |
| |
| The drawback is that the CVS repository is not an exact copy of what |
| is distributed and that users now need to install various development |
| tools (maybe even specific versions) before they can build a checkout. |
| But, after all, CVS’s job is versioning, not distribution. |
| |
| Allowing developers to use different versions of their tools can also |
| hide bugs during distributed development. Indeed, developers will be |
| using (hence testing) their own generated files, instead of the |
| generated files that will be released actually. The developer who |
| prepares the tarball might be using a version of the tool that produces |
| bogus output (for instance a non-portable C file), something other |
| developers could have noticed if they weren’t using their own versions |
| of this tool. |
| |
| Third-party Files |
| ----------------- |
| |
| Another class of files not discussed here (because they do not cause |
| timestamp issues) are files that are shipped with a package, but |
| maintained elsewhere. For instance, tools like ‘gettextize’ and |
| ‘autopoint’ (from Gettext) or ‘libtoolize’ (from Libtool), will install |
| or update files in your package. |
| |
| These files, whether they are kept under CVS or not, raise similar |
| concerns about version mismatch between developers’ tools. The Gettext |
| manual has a section about this, see *note CVS Issues: (gettext)CVS |
| Issues. |
| |
| |
| File: automake.info, Node: maintainer-mode, Next: Wildcards, Prev: CVS, Up: FAQ |
| |
| 27.2 ‘missing’ and ‘AM_MAINTAINER_MODE’ |
| ======================================= |
| |
| ‘missing’ |
| --------- |
| |
| The ‘missing’ script is a wrapper around several maintainer tools, |
| designed to warn users if a maintainer tool is required but missing. |
| Typical maintainer tools are ‘autoconf’, ‘automake’, ‘bison’, etc. |
| Because file generated by these tools are shipped with the other sources |
| of a package, these tools shouldn’t be required during a user build and |
| they are not checked for in ‘configure’. |
| |
| However, if for some reason a rebuild rule is triggered and involves |
| a missing tool, ‘missing’ will notice it and warn the user, even |
| suggesting how to obtain such a tool (at least in case it is a |
| well-known one, like ‘makeinfo’ or ‘bison’). This is more helpful and |
| user-friendly than just having the rebuild rules spewing out a terse |
| error message like ‘sh: TOOL: command not found’. Similarly, ‘missing’ |
| will warn the user if it detects that a maintainer tool it attempted to |
| use seems too old (be warned that diagnosing this correctly is typically |
| more difficult that detecting missing tools, and requires cooperation |
| from the tool itself, so it won’t always work). |
| |
| If the required tool is installed, ‘missing’ will run it and won’t |
| attempt to continue after failures. This is correct during development: |
| developers love fixing failures. However, users with missing or too old |
| maintainer tools may get an error when the rebuild rule is spuriously |
| triggered, halting the build. This failure to let the build continue is |
| one of the arguments of the ‘AM_MAINTAINER_MODE’ advocates. |
| |
| ‘AM_MAINTAINER_MODE’ |
| -------------------- |
| |
| ‘AM_MAINTAINER_MODE’ allows you to choose whether the so called "rebuild |
| rules" should be enabled or disabled. With |
| ‘AM_MAINTAINER_MODE([enable])’, they are enabled by default, otherwise |
| they are disabled by default. In the latter case, if you have |
| ‘AM_MAINTAINER_MODE’ in ‘configure.ac’, and run ‘./configure && make’, |
| then ‘make’ will *never* attempt to rebuild ‘configure’, ‘Makefile.in’s, |
| Lex or Yacc outputs, etc. I.e., this disables build rules for files |
| that are usually distributed and that users should normally not have to |
| update. |
| |
| The user can override the default setting by passing either |
| ‘--enable-maintainer-mode’ or ‘--disable-maintainer-mode’ to |
| ‘configure’. |
| |
| People use ‘AM_MAINTAINER_MODE’ either because they do not want their |
| users (or themselves) annoyed by timestamps lossage (*note CVS::), or |
| because they simply can’t stand the rebuild rules and prefer running |
| maintainer tools explicitly. |
| |
| ‘AM_MAINTAINER_MODE’ also allows you to disable some custom build |
| rules conditionally. Some developers use this feature to disable rules |
| that need exotic tools that users may not have available. |
| |
| Several years ago François Pinard pointed out several arguments |
| against this ‘AM_MAINTAINER_MODE’ macro. Most of them relate to |
| insecurity. By removing dependencies you get non-dependable builds: |
| changes to sources files can have no effect on generated files and this |
| can be very confusing when unnoticed. He adds that security shouldn’t |
| be reserved to maintainers (what ‘--enable-maintainer-mode’ suggests), |
| on the contrary. If one user has to modify a ‘Makefile.am’, then either |
| ‘Makefile.in’ should be updated or a warning should be output (this is |
| what Automake uses ‘missing’ for) but the last thing you want is that |
| nothing happens and the user doesn’t notice it (this is what happens |
| when rebuild rules are disabled by ‘AM_MAINTAINER_MODE’). |
| |
| Jim Meyering, the inventor of the ‘AM_MAINTAINER_MODE’ macro was |
| swayed by François’s arguments, and got rid of ‘AM_MAINTAINER_MODE’ in |
| all of his packages. |
| |
| Still many people continue to use ‘AM_MAINTAINER_MODE’, because it |
| helps them working on projects where all files are kept under version |
| control, and because ‘missing’ isn’t enough if you have the wrong |
| version of the tools. |
| |
| |
| File: automake.info, Node: Wildcards, Next: Limitations on File Names, Prev: maintainer-mode, Up: FAQ |
| |
| 27.3 Why doesn’t Automake support wildcards? |
| ============================================ |
| |
| Developers are lazy. They would often like to use wildcards in |
| ‘Makefile.am’s, so that they would not need to remember to update |
| ‘Makefile.am’s every time they add, delete, or rename a file. |
| |
| There are several objections to this: |
| • When using CVS (or similar) developers need to remember they have |
| to run ‘cvs add’ or ‘cvs rm’ anyway. Updating ‘Makefile.am’ |
| accordingly quickly becomes a reflex. |
| |
| Conversely, if your application doesn’t compile because you forgot |
| to add a file in ‘Makefile.am’, it will help you remember to ‘cvs |
| add’ it. |
| |
| • Using wildcards makes it easy to distribute files by mistake. For |
| instance, some code a developer is experimenting with (a test case, |
| say) that should not be part of the distribution. |
| |
| • Using wildcards it’s easy to omit some files by mistake. For |
| instance, one developer creates a new file, uses it in many places, |
| but forgets to commit it. Another developer then checks out the |
| incomplete project and is able to run ‘make dist’ successfully, |
| even though a file is missing. By listing files, ‘make dist’ |
| _will_ complain. |
| |
| • Wildcards are not portable to some non-GNU ‘make’ implementations, |
| e.g., NetBSD ‘make’ will not expand globs such as ‘*’ in |
| prerequisites of a target. |
| |
| • Finally, it’s really hard to _forget_ to add a file to |
| ‘Makefile.am’: files that are not listed in ‘Makefile.am’ are not |
| compiled or installed, so you can’t even test them. |
| |
| Still, these are philosophical objections, and as such you may |
| disagree, or find enough value in wildcards to dismiss all of them. |
| Before you start writing a patch against Automake to teach it about |
| wildcards, let’s see the main technical issue: portability. |
| |
| Although ‘$(wildcard ...)’ works with GNU ‘make’, it is not portable |
| to other ‘make’ implementations. |
| |
| The only way Automake could support ‘$(wildcard ...)’ is by expanding |
| ‘$(wildcard ...)’ when ‘automake’ is run. The resulting ‘Makefile.in’s |
| would be portable since they would list all files and not use |
| ‘$(wildcard ...)’. However that means developers would need to remember |
| to run ‘automake’ each time they add, delete, or rename files. |
| |
| Compared to editing ‘Makefile.am’, this is a very small gain. Sure, |
| it’s easier and faster to type ‘automake; make’ than to type ‘emacs |
| Makefile.am; make’. But nobody bothered enough to write a patch to add |
| support for this syntax. Some people use scripts to generate file lists |
| in ‘Makefile.am’ or in separate ‘Makefile’ fragments. |
| |
| Even if you don’t care about portability, and are tempted to use |
| ‘$(wildcard ...)’ anyway because you target only GNU Make, you should |
| know there are many places where Automake needs to know exactly which |
| files should be processed. As Automake doesn’t know how to expand |
| ‘$(wildcard ...)’, you cannot use it in these places. ‘$(wildcard ...)’ |
| is a black box comparable to ‘AC_SUBST’ed variables as far Automake is |
| concerned. |
| |
| You can get warnings about ‘$(wildcard ...’) constructs using the |
| ‘-Wportability’ flag. |
| |
| |
| File: automake.info, Node: Limitations on File Names, Next: Errors with distclean, Prev: Wildcards, Up: FAQ |
| |
| 27.4 Limitations on File Names |
| ============================== |
| |
| Automake attempts to support all kinds of file names, even those that |
| contain unusual characters or are unusually long. However, some |
| limitations are imposed by the underlying operating system and tools. |
| |
| Most operating systems prohibit the use of the null byte in file |
| names, and reserve ‘/’ as a directory separator. Also, they require |
| that file names are properly encoded for the user’s locale. Automake is |
| subject to these limits. |
| |
| Portable packages should limit themselves to POSIX file names. These |
| can contain ASCII letters and digits, ‘_’, ‘.’, and ‘-’. File names |
| consist of components separated by ‘/’. File name components cannot |
| begin with ‘-’. |
| |
| Portable POSIX file names cannot contain components that exceed a |
| 14-byte limit, but nowadays it’s normally safe to assume the |
| more-generous XOPEN limit of 255 bytes. POSIX limits file names to 255 |
| bytes (XOPEN allows 1023 bytes), but you may want to limit a source |
| tarball to file names of 99 bytes to avoid interoperability problems |
| with old versions of ‘tar’. |
| |
| If you depart from these rules (e.g., by using non-ASCII characters |
| in file names, or by using lengthy file names), your installers may have |
| problems for reasons unrelated to Automake. However, if this does not |
| concern you, you should know about the limitations imposed by Automake |
| itself. These limitations are undesirable, but some of them seem to be |
| inherent to underlying tools like Autoconf, Make, M4, and the shell. |
| They fall into three categories: install directories, build directories, |
| and file names. |
| |
| The following characters: |
| |
| newline " # $ ' ` |
| |
| should not appear in the names of install directories. For example, |
| the operand of ‘configure’’s ‘--prefix’ option should not contain these |
| characters. |
| |
| Build directories suffer the same limitations as install directories, |
| and in addition should not contain the following characters: |
| |
| & @ \ |
| |
| For example, the full name of the directory containing the source |
| files should not contain these characters. |
| |
| Source and installation file names like ‘main.c’ are limited even |
| further: they should conform to the POSIX/XOPEN rules described above. |
| In addition, if you plan to port to non-POSIX environments, you should |
| avoid file names that differ only in case (e.g., ‘makefile’ and |
| ‘Makefile’). Nowadays it is no longer worth worrying about the 8.3 |
| limits of DOS file systems. |
| |
| |
| File: automake.info, Node: Errors with distclean, Next: Flag Variables Ordering, Prev: Limitations on File Names, Up: FAQ |
| |
| 27.5 Errors with distclean |
| ========================== |
| |
| This is a diagnostic you might encounter while running ‘make distcheck’. |
| |
| As explained in *note Checking the Distribution::, ‘make distcheck’ |
| attempts to build and check your package for errors like this one. |
| |
| ‘make distcheck’ will perform a ‘VPATH’ build of your package (*note |
| VPATH Builds::), and then call ‘make distclean’. Files left in the |
| build directory after ‘make distclean’ has run are listed after this |
| error. |
| |
| This diagnostic really covers two kinds of errors: |
| |
| • files that are forgotten by distclean; |
| • distributed files that are erroneously rebuilt. |
| |
| The former left-over files are not distributed, so the fix is to mark |
| them for cleaning (*note Clean::), this is obvious and doesn’t deserve |
| more explanations. |
| |
| The latter bug is not always easy to understand and fix, so let’s |
| proceed with an example. Suppose our package contains a program for |
| which we want to build a man page using ‘help2man’. GNU ‘help2man’ |
| produces simple manual pages from the ‘--help’ and ‘--version’ output of |
| other commands (*note Overview: (help2man)Top.). Because we don’t want |
| to force our users to install ‘help2man’, we decide to distribute the |
| generated man page using the following setup. |
| |
| # This Makefile.am is bogus. |
| bin_PROGRAMS = foo |
| foo_SOURCES = foo.c |
| dist_man_MANS = foo.1 |
| |
| foo.1: foo$(EXEEXT) |
| help2man --output=foo.1 ./foo$(EXEEXT) |
| |
| This will effectively distribute the man page. However, ‘make |
| distcheck’ will fail with: |
| |
| ERROR: files left in build directory after distclean: |
| ./foo.1 |
| |
| Why was ‘foo.1’ rebuilt? Because although distributed, ‘foo.1’ |
| depends on a non-distributed built file: ‘foo$(EXEEXT)’. ‘foo$(EXEEXT)’ |
| is built by the user, so it will always appear to be newer than the |
| distributed ‘foo.1’. |
| |
| ‘make distcheck’ caught an inconsistency in our package. Our intent |
| was to distribute ‘foo.1’ so users do not need to install ‘help2man’, |
| however since this rule causes this file to be always rebuilt, users |
| _do_ need ‘help2man’. Either we should ensure that ‘foo.1’ is not |
| rebuilt by users, or there is no point in distributing ‘foo.1’. |
| |
| More generally, the rule is that distributed files should never |
| depend on non-distributed built files. If you distribute something |
| generated, distribute its sources. |
| |
| One way to fix the above example, while still distributing ‘foo.1’ is |
| to not depend on ‘foo$(EXEEXT)’. For instance, assuming ‘foo --version’ |
| and ‘foo --help’ do not change unless ‘foo.c’ or ‘configure.ac’ change, |
| we could write the following ‘Makefile.am’: |
| |
| bin_PROGRAMS = foo |
| foo_SOURCES = foo.c |
| dist_man_MANS = foo.1 |
| |
| foo.1: foo.c $(top_srcdir)/configure.ac |
| $(MAKE) $(AM_MAKEFLAGS) foo$(EXEEXT) |
| help2man --output=foo.1 ./foo$(EXEEXT) |
| |
| This way, ‘foo.1’ will not get rebuilt every time ‘foo$(EXEEXT)’ |
| changes. The ‘make’ call makes sure ‘foo$(EXEEXT)’ is up-to-date before |
| ‘help2man’. Another way to ensure this would be to use separate |
| directories for binaries and man pages, and set ‘SUBDIRS’ so that |
| binaries are built before man pages. |
| |
| We could also decide not to distribute ‘foo.1’. In this case it’s |
| fine to have ‘foo.1’ dependent upon ‘foo$(EXEEXT)’, since both will have |
| to be rebuilt. However it would be impossible to build the package in a |
| cross-compilation, because building ‘foo.1’ involves an _execution_ of |
| ‘foo$(EXEEXT)’. |
| |
| Another context where such errors are common is when distributed |
| files are built by tools that are built by the package. The pattern is |
| similar: |
| |
| distributed-file: built-tools distributed-sources |
| build-command |
| |
| should be changed to |
| |
| distributed-file: distributed-sources |
| $(MAKE) $(AM_MAKEFLAGS) built-tools |
| build-command |
| |
| or you could choose not to distribute ‘distributed-file’, if |
| cross-compilation does not matter. |
| |
| The points made through these examples are worth a summary: |
| |
| • Distributed files should never depend upon non-distributed built |
| files. |
| • Distributed files should be distributed with all their |
| dependencies. |
| • If a file is _intended_ to be rebuilt by users, then there is no |
| point in distributing it. |
| |
| For desperate cases, it’s always possible to disable this check by |
| setting ‘distcleancheck_listfiles’ as documented in *note Checking the |
| Distribution::. Make sure you do understand the reason why ‘make |
| distcheck’ complains before you do this. ‘distcleancheck_listfiles’ is |
| a way to _hide_ errors, not to fix them. You can always do better. |
| |
| |
| File: automake.info, Node: Flag Variables Ordering, Next: Renamed Objects, Prev: Errors with distclean, Up: FAQ |
| |
| 27.6 Flag Variables Ordering |
| ============================ |
| |
| What is the difference between ‘AM_CFLAGS’, ‘CFLAGS’, and |
| ‘mumble_CFLAGS’? |
| |
| Why does ‘automake’ output ‘CPPFLAGS’ after |
| ‘AM_CPPFLAGS’ on compile lines? Shouldn’t it be the converse? |
| |
| My ‘configure’ adds some warning flags into ‘CXXFLAGS’. In |
| one ‘Makefile.am’ I would like to append a new flag, however if I |
| put the flag into ‘AM_CXXFLAGS’ it is prepended to the other |
| flags, not appended. |
| |
| Compile Flag Variables |
| ---------------------- |
| |
| This section attempts to answer all the above questions. We will mostly |
| discuss ‘CPPFLAGS’ in our examples, but actually the answer holds for |
| all the compile flags used in Automake: ‘CCASFLAGS’, ‘CFLAGS’, |
| ‘CPPFLAGS’, ‘CXXFLAGS’, ‘FCFLAGS’, ‘FFLAGS’, ‘GCJFLAGS’, ‘LDFLAGS’, |
| ‘LFLAGS’, ‘LIBTOOLFLAGS’, ‘OBJCFLAGS’, ‘OBJCXXFLAGS’, ‘RFLAGS’, |
| ‘UPCFLAGS’, and ‘YFLAGS’. |
| |
| ‘CPPFLAGS’, ‘AM_CPPFLAGS’, and ‘mumble_CPPFLAGS’ are three variables |
| that can be used to pass flags to the C preprocessor (actually these |
| variables are also used for other languages like C++ or preprocessed |
| Fortran). ‘CPPFLAGS’ is the user variable (*note User Variables::), |
| ‘AM_CPPFLAGS’ is the Automake variable, and ‘mumble_CPPFLAGS’ is the |
| variable specific to the ‘mumble’ target (we call this a per-target |
| variable, *note Program and Library Variables::). |
| |
| Automake always uses two of these variables when compiling C sources |
| files. When compiling an object file for the ‘mumble’ target, the first |
| variable will be ‘mumble_CPPFLAGS’ if it is defined, or ‘AM_CPPFLAGS’ |
| otherwise. The second variable is always ‘CPPFLAGS’. |
| |
| In the following example, |
| |
| bin_PROGRAMS = foo bar |
| foo_SOURCES = xyz.c |
| bar_SOURCES = main.c |
| foo_CPPFLAGS = -DFOO |
| AM_CPPFLAGS = -DBAZ |
| |
| ‘xyz.o’ will be compiled with ‘$(foo_CPPFLAGS) $(CPPFLAGS)’, (because |
| ‘xyz.o’ is part of the ‘foo’ target), while ‘main.o’ will be compiled |
| with ‘$(AM_CPPFLAGS) $(CPPFLAGS)’ (because there is no per-target |
| variable for target ‘bar’). |
| |
| The difference between ‘mumble_CPPFLAGS’ and ‘AM_CPPFLAGS’ being |
| clear enough, let’s focus on ‘CPPFLAGS’. ‘CPPFLAGS’ is a user variable, |
| i.e., a variable that users are entitled to modify in order to compile |
| the package. This variable, like many others, is documented at the end |
| of the output of ‘configure --help’. |
| |
| For instance, someone who needs to add ‘/home/my/usr/include’ to the |
| C compiler’s search path would configure a package with |
| |
| ./configure CPPFLAGS='-I /home/my/usr/include' |
| |
| and this flag would be propagated to the compile rules of all |
| ‘Makefile’s. |
| |
| It is also not uncommon to override a user variable at ‘make’-time. |
| Many installers do this with ‘prefix’, but this can be useful with |
| compiler flags too. For instance, if, while debugging a C++ project, |
| you need to disable optimization in one specific object file, you can |
| run something like |
| |
| rm file.o |
| make CXXFLAGS=-O0 file.o |
| make |
| |
| The reason ‘$(CPPFLAGS)’ appears after ‘$(AM_CPPFLAGS)’ or |
| ‘$(mumble_CPPFLAGS)’ in the compile command is that users should always |
| have the last say. It probably makes more sense if you think about it |
| while looking at the ‘CXXFLAGS=-O0’ above, which should supersede any |
| other switch from ‘AM_CXXFLAGS’ or ‘mumble_CXXFLAGS’ (and this of course |
| replaces the previous value of ‘CXXFLAGS’). |
| |
| You should never redefine a user variable such as ‘CPPFLAGS’ in |
| ‘Makefile.am’. Use ‘automake -Woverride’ to diagnose such mistakes. |
| Even something like |
| |
| CPPFLAGS = -DDATADIR=\"$(datadir)\" @CPPFLAGS@ |
| |
| is erroneous. Although this preserves ‘configure’’s value of |
| ‘CPPFLAGS’, the definition of ‘DATADIR’ will disappear if a user |
| attempts to override ‘CPPFLAGS’ from the ‘make’ command line. |
| |
| AM_CPPFLAGS = -DDATADIR=\"$(datadir)\" |
| |
| is all that is needed here if no per-target flags are used. |
| |
| You should not add options to these user variables within ‘configure’ |
| either, for the same reason. Occasionally you need to modify these |
| variables to perform a test, but you should reset their values |
| afterwards. In contrast, it is OK to modify the ‘AM_’ variables within |
| ‘configure’ if you ‘AC_SUBST’ them, but it is rather rare that you need |
| to do this, unless you really want to change the default definitions of |
| the ‘AM_’ variables in all ‘Makefile’s. |
| |
| What we recommend is that you define extra flags in separate |
| variables. For instance, you may write an Autoconf macro that computes |
| a set of warning options for the C compiler, and ‘AC_SUBST’ them in |
| ‘WARNINGCFLAGS’; you may also have an Autoconf macro that determines |
| which compiler and which linker flags should be used to link with |
| library ‘libfoo’, and ‘AC_SUBST’ these in ‘LIBFOOCFLAGS’ and |
| ‘LIBFOOLDFLAGS’. Then, a ‘Makefile.am’ could use these variables as |
| follows: |
| |
| AM_CFLAGS = $(WARNINGCFLAGS) |
| bin_PROGRAMS = prog1 prog2 |
| prog1_SOURCES = … |
| prog2_SOURCES = … |
| prog2_CFLAGS = $(LIBFOOCFLAGS) $(AM_CFLAGS) |
| prog2_LDFLAGS = $(LIBFOOLDFLAGS) |
| |
| In this example both programs will be compiled with the flags |
| substituted into ‘$(WARNINGCFLAGS)’, and ‘prog2’ will additionally be |
| compiled with the flags required to link with ‘libfoo’. |
| |
| Note that listing ‘AM_CFLAGS’ in a per-target ‘CFLAGS’ variable is a |
| common idiom to ensure that ‘AM_CFLAGS’ applies to every target in a |
| ‘Makefile.in’. |
| |
| Using variables like this gives you full control over the ordering of |
| the flags. For instance, if there is a flag in $(WARNINGCFLAGS) that |
| you want to negate for a particular target, you can use something like |
| ‘prog1_CFLAGS = $(AM_CFLAGS) -no-flag’. If all of these flags had been |
| forcefully appended to ‘CFLAGS’, there would be no way to disable one |
| flag. Yet another reason to leave user variables to users. |
| |
| Finally, we have avoided naming the variable of the example |
| ‘LIBFOO_LDFLAGS’ (with an underscore) because that would cause Automake |
| to think that this is actually a per-target variable (like |
| ‘mumble_LDFLAGS’) for some non-declared ‘LIBFOO’ target. |
| |
| Other Variables |
| --------------- |
| |
| There are other variables in Automake that follow similar principles to |
| allow user options. For instance, Texinfo rules (*note Texinfo::) use |
| ‘MAKEINFOFLAGS’ and ‘AM_MAKEINFOFLAGS’. Similarly, DejaGnu tests (*note |
| DejaGnu Tests::) use ‘RUNTESTDEFAULTFLAGS’ and ‘AM_RUNTESTDEFAULTFLAGS’. |
| The tags and ctags rules (*note Tags::) use ‘ETAGSFLAGS’, |
| ‘AM_ETAGSFLAGS’, ‘CTAGSFLAGS’, and ‘AM_CTAGSFLAGS’. Java rules (*note |
| Java::) use ‘JAVACFLAGS’ and ‘AM_JAVACFLAGS’. None of these rules |
| support per-target flags (yet). |
| |
| To some extent, even ‘AM_MAKEFLAGS’ (*note Subdirectories::) obeys |
| this naming scheme. The slight difference is that ‘MAKEFLAGS’ is passed |
| to sub-‘make’s implicitly by ‘make’ itself. |
| |
| ‘ARFLAGS’ (*note A Library::) is usually defined by Automake and has |
| neither ‘AM_’ nor per-target cousin. |
| |
| Finally you should not think that the existence of a per-target |
| variable implies the existence of an ‘AM_’ variable or of a user |
| variable. For instance, the ‘mumble_LDADD’ per-target variable |
| overrides the makefile-wide ‘LDADD’ variable (which is not a user |
| variable), and ‘mumble_LIBADD’ exists only as a per-target variable. |
| *Note Program and Library Variables::. |
| |
| |
| File: automake.info, Node: Renamed Objects, Next: Per-Object Flags, Prev: Flag Variables Ordering, Up: FAQ |
| |
| 27.7 Why are object files sometimes renamed? |
| ============================================ |
| |
| This happens when per-target compilation flags are used. Object files |
| need to be renamed just in case they would clash with object files |
| compiled from the same sources, but with different flags. Consider the |
| following example. |
| |
| bin_PROGRAMS = true false |
| true_SOURCES = generic.c |
| true_CPPFLAGS = -DEXIT_CODE=0 |
| false_SOURCES = generic.c |
| false_CPPFLAGS = -DEXIT_CODE=1 |
| |
| Obviously the two programs are built from the same source, but it would |
| be bad if they shared the same object, because ‘generic.o’ cannot be |
| built with both ‘-DEXIT_CODE=0’ _and_ ‘-DEXIT_CODE=1’. Therefore |
| ‘automake’ outputs rules to build two different objects: |
| ‘true-generic.o’ and ‘false-generic.o’. |
| |
| ‘automake’ doesn’t actually look whether source files are shared to |
| decide if it must rename objects. It will just rename all objects of a |
| target as soon as it sees per-target compilation flags used. |
| |
| It’s OK to share object files when per-target compilation flags are |
| not used. For instance, ‘true’ and ‘false’ will both use ‘version.o’ in |
| the following example. |
| |
| AM_CPPFLAGS = -DVERSION=1.0 |
| bin_PROGRAMS = true false |
| true_SOURCES = true.c version.c |
| false_SOURCES = false.c version.c |
| |
| Note that the renaming of objects is also affected by the |
| ‘_SHORTNAME’ variable (*note Program and Library Variables::). |
| |
| |
| File: automake.info, Node: Per-Object Flags, Next: Multiple Outputs, Prev: Renamed Objects, Up: FAQ |
| |
| 27.8 Per-Object Flags Emulation |
| =============================== |
| |
| One of my source files needs to be compiled with different flags. How |
| do I do? |
| |
| Automake supports per-program and per-library compilation flags (see |
| *note Program and Library Variables:: and *note Flag Variables |
| Ordering::). With this you can define compilation flags that apply to |
| all files compiled for a target. For instance, in |
| |
| bin_PROGRAMS = foo |
| foo_SOURCES = foo.c foo.h bar.c bar.h main.c |
| foo_CFLAGS = -some -flags |
| |
| ‘foo-foo.o’, ‘foo-bar.o’, and ‘foo-main.o’ will all be compiled with |
| ‘-some -flags’. (If you wonder about the names of these object files, |
| see *note Renamed Objects::.) Note that ‘foo_CFLAGS’ gives the flags to |
| use when compiling all the C sources of the _program_ ‘foo’, it has |
| nothing to do with ‘foo.c’ or ‘foo-foo.o’ specifically. |
| |
| What if ‘foo.c’ needs to be compiled into ‘foo.o’ using some specific |
| flags, that none of the other files requires? Obviously per-program |
| flags are not directly applicable here. Something like per-object flags |
| are expected, i.e., flags that would be used only when creating |
| ‘foo-foo.o’. Automake does not support that, however this is easy to |
| simulate using a library that contains only that object, and compiling |
| this library with per-library flags. |
| |
| bin_PROGRAMS = foo |
| foo_SOURCES = bar.c bar.h main.c |
| foo_CFLAGS = -some -flags |
| foo_LDADD = libfoo.a |
| noinst_LIBRARIES = libfoo.a |
| libfoo_a_SOURCES = foo.c foo.h |
| libfoo_a_CFLAGS = -some -other -flags |
| |
| Here ‘foo-bar.o’ and ‘foo-main.o’ will all be compiled with ‘-some |
| -flags’, while ‘libfoo_a-foo.o’ will be compiled using ‘-some -other |
| -flags’. Eventually, all three objects will be linked to form ‘foo’. |
| |
| This trick can also be achieved using Libtool convenience libraries, |
| for instance ‘noinst_LTLIBRARIES = libfoo.la’ (*note Libtool Convenience |
| Libraries::). |
| |
| Another tempting idea to implement per-object flags is to override |
| the compile rules ‘automake’ would output for these files. Automake |
| will not define a rule for a target you have defined, so you could think |
| about defining the ‘foo-foo.o: foo.c’ rule yourself. We recommend |
| against this, because this is error prone. For instance, if you add |
| such a rule to the first example, it will break the day you decide to |
| remove ‘foo_CFLAGS’ (because ‘foo.c’ will then be compiled as ‘foo.o’ |
| instead of ‘foo-foo.o’, *note Renamed Objects::). Also in order to |
| support dependency tracking, the two ‘.o’/‘.obj’ extensions, and all the |
| other flags variables involved in a compilation, you will end up |
| modifying a copy of the rule previously output by ‘automake’ for this |
| file. If a new release of Automake generates a different rule, your |
| copy will need to be updated by hand. |
| |
| |
| File: automake.info, Node: Multiple Outputs, Next: Hard-Coded Install Paths, Prev: Per-Object Flags, Up: FAQ |
| |
| 27.9 Handling Tools that Produce Many Outputs |
| ============================================= |
| |
| This section describes a ‘make’ idiom that can be used when a tool |
| produces multiple output files. It is not specific to Automake and can |
| be used in ordinary ‘Makefile’s. |
| |
| Suppose we have a program called ‘foo’ that will read one file called |
| ‘data.foo’ and produce two files named ‘data.c’ and ‘data.h’. We want |
| to write a ‘Makefile’ rule that captures this one-to-two dependency. |
| |
| The naive rule is incorrect: |
| |
| # This is incorrect. |
| data.c data.h: data.foo |
| foo data.foo |
| |
| What the above rule really says is that ‘data.c’ and ‘data.h’ each |
| depend on ‘data.foo’, and can each be built by running ‘foo data.foo’. |
| In other words it is equivalent to: |
| |
| # We do not want this. |
| data.c: data.foo |
| foo data.foo |
| data.h: data.foo |
| foo data.foo |
| |
| which means that ‘foo’ can be run twice. Usually it will not be run |
| twice, because ‘make’ implementations are smart enough to check for the |
| existence of the second file after the first one has been built; they |
| will therefore detect that it already exists. However there are a few |
| situations where it can run twice anyway: |
| |
| • The most worrying case is when running a parallel ‘make’. If |
| ‘data.c’ and ‘data.h’ are built in parallel, two ‘foo data.foo’ |
| commands will run concurrently. This is harmful. |
| • Another case is when the dependency (here ‘data.foo’) is (or |
| depends upon) a phony target. |
| |
| A solution that works with parallel ‘make’ but not with phony |
| dependencies is the following: |
| |
| data.c data.h: data.foo |
| foo data.foo |
| data.h: data.c |
| |
| The above rules are equivalent to |
| |
| data.c: data.foo |
| foo data.foo |
| data.h: data.foo data.c |
| foo data.foo |
| |
| therefore a parallel ‘make’ will have to serialize the builds of |
| ‘data.c’ and ‘data.h’, and will detect that the second is no longer |
| needed once the first is over. |
| |
| Using this pattern is probably enough for most cases. However it |
| does not scale easily to more output files (in this scheme all output |
| files must be totally ordered by the dependency relation), so we will |
| explore a more complicated solution. |
| |
| Another idea is to write the following: |
| |
| # There is still a problem with this one. |
| data.c: data.foo |
| foo data.foo |
| data.h: data.c |
| |
| The idea is that ‘foo data.foo’ is run only when ‘data.c’ needs to be |
| updated, but we further state that ‘data.h’ depends upon ‘data.c’. That |
| way, if ‘data.h’ is required and ‘data.foo’ is out of date, the |
| dependency on ‘data.c’ will trigger the build. |
| |
| This is almost perfect, but suppose we have built ‘data.h’ and |
| ‘data.c’, and then we erase ‘data.h’. Then, running ‘make data.h’ will |
| not rebuild ‘data.h’. The above rules just state that ‘data.c’ must be |
| up-to-date with respect to ‘data.foo’, and this is already the case. |
| |
| What we need is a rule that forces a rebuild when ‘data.h’ is |
| missing. Here it is: |
| |
| data.c: data.foo |
| foo data.foo |
| data.h: data.c |
| ## Recover from the removal of $@ |
| @if test -f $@; then :; else \ |
| rm -f data.c; \ |
| $(MAKE) $(AM_MAKEFLAGS) data.c; \ |
| fi |
| |
| The above scheme can be extended to handle more outputs and more |
| inputs. One of the outputs is selected to serve as a witness to the |
| successful completion of the command, it depends upon all inputs, and |
| all other outputs depend upon it. For instance, if ‘foo’ should |
| additionally read ‘data.bar’ and also produce ‘data.w’ and ‘data.x’, we |
| would write: |
| |
| data.c: data.foo data.bar |
| foo data.foo data.bar |
| data.h data.w data.x: data.c |
| ## Recover from the removal of $@ |
| @if test -f $@; then :; else \ |
| rm -f data.c; \ |
| $(MAKE) $(AM_MAKEFLAGS) data.c; \ |
| fi |
| |
| However there are now three minor problems in this setup. One is |
| related to the timestamp ordering of ‘data.h’, ‘data.w’, ‘data.x’, and |
| ‘data.c’. Another one is a race condition if a parallel ‘make’ attempts |
| to run multiple instances of the recover block at once. Finally, the |
| recursive rule breaks ‘make -n’ when run with GNU ‘make’ (as well as |
| some other ‘make’ implementations), as it may remove ‘data.h’ even when |
| it should not (*note How the ‘MAKE’ Variable Works: (make)MAKE |
| Variable.). |
| |
| Let us deal with the first problem. ‘foo’ outputs four files, but we |
| do not know in which order these files are created. Suppose that |
| ‘data.h’ is created before ‘data.c’. Then we have a weird situation. |
| The next time ‘make’ is run, ‘data.h’ will appear older than ‘data.c’, |
| the second rule will be triggered, a shell will be started to execute |
| the ‘if…fi’ command, but actually it will just execute the ‘then’ |
| branch, that is: nothing. In other words, because the witness we |
| selected is not the first file created by ‘foo’, ‘make’ will start a |
| shell to do nothing each time it is run. |
| |
| A simple riposte is to fix the timestamps when this happens. |
| |
| data.c: data.foo data.bar |
| foo data.foo data.bar |
| data.h data.w data.x: data.c |
| @if test -f $@; then \ |
| touch $@; \ |
| else \ |
| ## Recover from the removal of $@ |
| rm -f data.c; \ |
| $(MAKE) $(AM_MAKEFLAGS) data.c; \ |
| fi |
| |
| Another solution is to use a different and dedicated file as witness, |
| rather than using any of ‘foo’’s outputs. |
| |
| data.stamp: data.foo data.bar |
| @rm -f data.tmp |
| @touch data.tmp |
| foo data.foo data.bar |
| @mv -f data.tmp $@ |
| data.c data.h data.w data.x: data.stamp |
| ## Recover from the removal of $@ |
| @if test -f $@; then :; else \ |
| rm -f data.stamp; \ |
| $(MAKE) $(AM_MAKEFLAGS) data.stamp; \ |
| fi |
| |
| ‘data.tmp’ is created before ‘foo’ is run, so it has a timestamp |
| older than output files output by ‘foo’. It is then renamed to |
| ‘data.stamp’ after ‘foo’ has run, because we do not want to update |
| ‘data.stamp’ if ‘foo’ fails. |
| |
| This solution still suffers from the second problem: the race |
| condition in the recover rule. If, after a successful build, a user |
| erases ‘data.c’ and ‘data.h’, and runs ‘make -j’, then ‘make’ may start |
| both recover rules in parallel. If the two instances of the rule |
| execute ‘$(MAKE) $(AM_MAKEFLAGS) data.stamp’ concurrently the build is |
| likely to fail (for instance, the two rules will create ‘data.tmp’, but |
| only one can rename it). |
| |
| Admittedly, such a weird situation does not arise during ordinary |
| builds. It occurs only when the build tree is mutilated. Here ‘data.c’ |
| and ‘data.h’ have been explicitly removed without also removing |
| ‘data.stamp’ and the other output files. ‘make clean; make’ will always |
| recover from these situations even with parallel makes, so you may |
| decide that the recover rule is solely to help non-parallel make users |
| and leave things as-is. Fixing this requires some locking mechanism to |
| ensure only one instance of the recover rule rebuilds ‘data.stamp’. One |
| could imagine something along the following lines. |
| |
| data.c data.h data.w data.x: data.stamp |
| ## Recover from the removal of $@ |
| @if test -f $@; then :; else \ |
| trap 'rm -rf data.lock data.stamp' 1 2 13 15; \ |
| ## mkdir is a portable test-and-set |
| if mkdir data.lock 2>/dev/null; then \ |
| ## This code is being executed by the first process. |
| rm -f data.stamp; \ |
| $(MAKE) $(AM_MAKEFLAGS) data.stamp; \ |
| result=$$?; rm -rf data.lock; exit $$result; \ |
| else \ |
| ## This code is being executed by the follower processes. |
| ## Wait until the first process is done. |
| while test -d data.lock; do sleep 1; done; \ |
| ## Succeed if and only if the first process succeeded. |
| test -f data.stamp; \ |
| fi; \ |
| fi |
| |
| Using a dedicated witness, like ‘data.stamp’, is very handy when the |
| list of output files is not known beforehand. As an illustration, |
| consider the following rules to compile many ‘*.el’ files into ‘*.elc’ |
| files in a single command. It does not matter how ‘ELFILES’ is defined |
| (as long as it is not empty: empty targets are not accepted by POSIX). |
| |
| ELFILES = one.el two.el three.el … |
| ELCFILES = $(ELFILES:=c) |
| |
| elc-stamp: $(ELFILES) |
| @rm -f elc-temp |
| @touch elc-temp |
| $(elisp_comp) $(ELFILES) |
| @mv -f elc-temp $@ |
| |
| $(ELCFILES): elc-stamp |
| @if test -f $@; then :; else \ |
| ## Recover from the removal of $@ |
| trap 'rm -rf elc-lock elc-stamp' 1 2 13 15; \ |
| if mkdir elc-lock 2>/dev/null; then \ |
| ## This code is being executed by the first process. |
| rm -f elc-stamp; \ |
| $(MAKE) $(AM_MAKEFLAGS) elc-stamp; \ |
| rmdir elc-lock; \ |
| else \ |
| ## This code is being executed by the follower processes. |
| ## Wait until the first process is done. |
| while test -d elc-lock; do sleep 1; done; \ |
| ## Succeed if and only if the first process succeeded. |
| test -f elc-stamp; exit $$?; \ |
| fi; \ |
| fi |
| |
| These solutions all still suffer from the third problem, namely that |
| they break the promise that ‘make -n’ should not cause any actual |
| changes to the tree. For those solutions that do not create lock files, |
| it is possible to split the recover rules into two separate recipe |
| commands, one of which does all work but the recursion, and the other |
| invokes the recursive ‘$(MAKE)’. The solutions involving locking could |
| act upon the contents of the ‘MAKEFLAGS’ variable, but parsing that |
| portably is not easy (*note (autoconf)The Make Macro MAKEFLAGS::). Here |
| is an example: |
| |
| ELFILES = one.el two.el three.el … |
| ELCFILES = $(ELFILES:=c) |
| |
| elc-stamp: $(ELFILES) |
| @rm -f elc-temp |
| @touch elc-temp |
| $(elisp_comp) $(ELFILES) |
| @mv -f elc-temp $@ |
| |
| $(ELCFILES): elc-stamp |
| ## Recover from the removal of $@ |
| @dry=; for f in x $$MAKEFLAGS; do \ |
| case $$f in \ |
| *=*|--*);; \ |
| *n*) dry=:;; \ |
| esac; \ |
| done; \ |
| if test -f $@; then :; else \ |
| $$dry trap 'rm -rf elc-lock elc-stamp' 1 2 13 15; \ |
| if $$dry mkdir elc-lock 2>/dev/null; then \ |
| ## This code is being executed by the first process. |
| $$dry rm -f elc-stamp; \ |
| $(MAKE) $(AM_MAKEFLAGS) elc-stamp; \ |
| $$dry rmdir elc-lock; \ |
| else \ |
| ## This code is being executed by the follower processes. |
| ## Wait until the first process is done. |
| while test -d elc-lock && test -z "$$dry"; do \ |
| sleep 1; \ |
| done; \ |
| ## Succeed if and only if the first process succeeded. |
| $$dry test -f elc-stamp; exit $$?; \ |
| fi; \ |
| fi |
| |
| For completeness it should be noted that GNU ‘make’ is able to |
| express rules with multiple output files using pattern rules (*note |
| Pattern Rule Examples: (make)Pattern Examples.). We do not discuss |
| pattern rules here because they are not portable, but they can be |
| convenient in packages that assume GNU ‘make’. |
| |
| |
| File: automake.info, Node: Hard-Coded Install Paths, Next: Debugging Make Rules, Prev: Multiple Outputs, Up: FAQ |
| |
| 27.10 Installing to Hard-Coded Locations |
| ======================================== |
| |
| My package needs to install some configuration file. I tried to use |
| the following rule, but ‘make distcheck’ fails. Why? |
| |
| # Do not do this. |
| install-data-local: |
| $(INSTALL_DATA) $(srcdir)/afile $(DESTDIR)/etc/afile |
| |
| My package needs to populate the installation directory of another |
| package at install-time. I can easily compute that installation |
| directory in ‘configure’, but if I install files therein, |
| ‘make distcheck’ fails. How else should I do? |
| |
| These two setups share their symptoms: ‘make distcheck’ fails because |
| they are installing files to hard-coded paths. In the later case the |
| path is not really hard-coded in the package, but we can consider it to |
| be hard-coded in the system (or in whichever tool that supplies the |
| path). As long as the path does not use any of the standard directory |
| variables (‘$(prefix)’, ‘$(bindir)’, ‘$(datadir)’, etc.), the effect |
| will be the same: user-installations are impossible. |
| |
| As a (non-root) user who wants to install a package, you usually have |
| no right to install anything in ‘/usr’ or ‘/usr/local’. So you do |
| something like ‘./configure --prefix ~/usr’ to install a package in your |
| own ‘~/usr’ tree. |
| |
| If a package attempts to install something to some hard-coded path |
| (e.g., ‘/etc/afile’), regardless of this ‘--prefix’ setting, then the |
| installation will fail. ‘make distcheck’ performs such a ‘--prefix’ |
| installation, hence it will fail too. |
| |
| Now, there are some easy solutions. |
| |
| The above ‘install-data-local’ example for installing ‘/etc/afile’ |
| would be better replaced by |
| |
| sysconf_DATA = afile |
| |
| by default ‘sysconfdir’ will be ‘$(prefix)/etc’, because this is what |
| the GNU Standards require. When such a package is installed on an FHS |
| compliant system, the installer will have to set ‘--sysconfdir=/etc’. |
| As the maintainer of the package you should not be concerned by such |
| site policies: use the appropriate standard directory variable to |
| install your files so that the installer can easily redefine these |
| variables to match their site conventions. |
| |
| Installing files that should be used by another package is slightly |
| more involved. Let’s take an example and assume you want to install a |
| shared library that is a Python extension module. If you ask Python |
| where to install the library, it will answer something like this: |
| |
| % python -c 'from distutils import sysconfig; |
| print sysconfig.get_python_lib(1,0)' |
| /usr/lib/python2.5/site-packages |
| |
| If you indeed use this absolute path to install your shared library, |
| non-root users will not be able to install the package, hence distcheck |
| fails. |
| |
| Let’s do better. The ‘sysconfig.get_python_lib()’ function actually |
| accepts a third argument that will replace Python’s installation prefix. |
| |
| % python -c 'from distutils import sysconfig; |
| print sysconfig.get_python_lib(1,0,"${exec_prefix}")' |
| ${exec_prefix}/lib/python2.5/site-packages |
| |
| You can also use this new path. If you do |
| • root users can install your package with the same ‘--prefix’ as |
| Python (you get the behavior of the previous attempt) |
| |
| • non-root users can install your package too, they will have the |
| extension module in a place that is not searched by Python but they |
| can work around this using environment variables (and if you |
| installed scripts that use this shared library, it’s easy to tell |
| Python were to look in the beginning of your script, so the script |
| works in both cases). |
| |
| The ‘AM_PATH_PYTHON’ macro uses similar commands to define |
| ‘$(pythondir)’ and ‘$(pyexecdir)’ (*note Python::). |
| |
| Of course not all tools are as advanced as Python regarding that |
| substitution of PREFIX. So another strategy is to figure the part of |
| the installation directory that must be preserved. For instance, here |
| is how ‘AM_PATH_LISPDIR’ (*note Emacs Lisp::) computes ‘$(lispdir)’: |
| |
| $EMACS -batch -Q -eval '(while load-path |
| (princ (concat (car load-path) "\n")) |
| (setq load-path (cdr load-path)))' >conftest.out |
| lispdir=`sed -n |
| -e 's,/$,,' |
| -e '/.*\/lib\/x*emacs\/site-lisp$/{ |
| s,.*/lib/\(x*emacs/site-lisp\)$,${libdir}/\1,;p;q; |
| }' |
| -e '/.*\/share\/x*emacs\/site-lisp$/{ |
| s,.*/share/\(x*emacs/site-lisp\),${datarootdir}/\1,;p;q; |
| }' |
| conftest.out` |
| |
| I.e., it just picks the first directory that looks like |
| ‘*/lib/*emacs/site-lisp’ or ‘*/share/*emacs/site-lisp’ in the search |
| path of emacs, and then substitutes ‘${libdir}’ or ‘${datadir}’ |
| appropriately. |
| |
| The emacs case looks complicated because it processes a list and |
| expects two possible layouts, otherwise it’s easy, and the benefits for |
| non-root users are really worth the extra ‘sed’ invocation. |
| |
| |
| File: automake.info, Node: Debugging Make Rules, Next: Reporting Bugs, Prev: Hard-Coded Install Paths, Up: FAQ |
| |
| 27.11 Debugging Make Rules |
| ========================== |
| |
| The rules and dependency trees generated by ‘automake’ can get rather |
| complex, and leave the developer head-scratching when things don’t work |
| as expected. Besides the debug options provided by the ‘make’ command |
| (*note (make)Options Summary::), here’s a couple of further hints for |
| debugging makefiles generated by ‘automake’ effectively: |
| |
| • If less verbose output has been enabled in the package with the use |
| of silent rules (*note Automake Silent Rules::), you can use ‘make |
| V=1’ to see the commands being executed. |
| • ‘make -n’ can help show what would be done without actually doing |
| it. Note however, that this will _still execute_ commands prefixed |
| with ‘+’, and, when using GNU ‘make’, commands that contain the |
| strings ‘$(MAKE)’ or ‘${MAKE}’ (*note (make)Instead of |
| Execution::). Typically, this is helpful to show what recursive |
| rules would do, but it means that, in your own rules, you should |
| not mix such recursion with actions that change any files.(1) |
| Furthermore, note that GNU ‘make’ will update prerequisites for the |
| ‘Makefile’ file itself even with ‘-n’ (*note (make)Remaking |
| Makefiles::). |
| • ‘make SHELL="/bin/bash -vx"’ can help debug complex rules. *Note |
| (autoconf)The Make Macro SHELL::, for some portability quirks |
| associated with this construct. |
| • ‘echo 'print: ; @echo "$(VAR)"' | make -f Makefile -f - print’ can |
| be handy to examine the expanded value of variables. You may need |
| to use a target other than ‘print’ if that is already used or a |
| file with that name exists. |
| • <http://bashdb.sourceforge.net/remake/> provides a modified GNU |
| ‘make’ command called ‘remake’ that copes with complex GNU |
| ‘make’-specific Makefiles and allows to trace execution, examine |
| variables, and call rules interactively, much like a debugger. |
| |
| ---------- Footnotes ---------- |
| |
| (1) Automake’s ‘dist’ and ‘distcheck’ rules had a bug in this regard |
| in that they created directories even with ‘-n’, but this has been fixed |
| in Automake 1.11. |
| |
| |
| File: automake.info, Node: Reporting Bugs, Prev: Debugging Make Rules, Up: FAQ |
| |
| 27.12 Reporting Bugs |
| ==================== |
| |
| Most nontrivial software has bugs. Automake is no exception. Although |
| we cannot promise we can or will fix a bug, and we might not even agree |
| that it is a bug, we want to hear about problems you encounter. Often |
| we agree they are bugs and want to fix them. |
| |
| To make it possible for us to fix a bug, please report it. In order |
| to do so effectively, it helps to know when and how to do it. |
| |
| Before reporting a bug, it is a good idea to see if it is already |
| known. You can look at the GNU Bug Tracker (http://debbugs.gnu.org/) |
| and the bug-automake mailing list archives |
| (http://lists.gnu.org/archive/html/bug-automake/) for previous bug |
| reports. We previously used a Gnats database |
| (http://sourceware.org/cgi-bin/gnatsweb.pl?database=automake) for bug |
| tracking, so some bugs might have been reported there already. Please |
| do not use it for new bug reports, however. |
| |
| If the bug is not already known, it should be reported. It is very |
| important to report bugs in a way that is useful and efficient. For |
| this, please familiarize yourself with How to Report Bugs Effectively |
| (http://www.chiark.greenend.org.uk/~sgtatham/bugs.html) and How to Ask |
| Questions the Smart Way |
| (http://catb.org/~esr/faqs/smart-questions.html). This helps you and |
| developers to save time which can then be spent on fixing more bugs and |
| implementing more features. |
| |
| For a bug report, a feature request or other suggestions, please send |
| email to <bug-automake@gnu.org>. This will then open a new bug in the |
| bug tracker (http://debbugs.gnu.org/automake). Be sure to include the |
| versions of Autoconf and Automake that you use. Ideally, post a minimal |
| ‘Makefile.am’ and ‘configure.ac’ that reproduces the problem you |
| encounter. If you have encountered test suite failures, please attach |
| the ‘test-suite.log’ file. |
| |
| |
| File: automake.info, Node: Copying This Manual, Next: Indices, Prev: FAQ, Up: Top |
| |
| Appendix A Copying This Manual |
| ****************************** |
| |
| * Menu: |
| |
| * GNU Free Documentation License:: License for copying this manual |
| |
| |
| File: automake.info, Node: GNU Free Documentation License, Up: Copying This Manual |
| |
| A.1 GNU Free Documentation License |
| ================================== |
| |
| Version 1.3, 3 November 2008 |
| |
| Copyright © 2000-2014 Free Software Foundation, Inc. |
| <http://fsf.org/> |
| |
| Everyone is permitted to copy and distribute verbatim copies |
| of this license document, but changing it is not allowed. |
| |
| 0. PREAMBLE |
| |
| The purpose of this License is to make a manual, textbook, or other |
| functional and useful document "free" in the sense of freedom: to |
| assure everyone the effective freedom to copy and redistribute it, |
| with or without modifying it, either commercially or |
| noncommercially. Secondarily, this License preserves for the |
| author and publisher a way to get credit for their work, while not |
| being considered responsible for modifications made by others. |
| |
| This License is a kind of “copyleft”, which means that derivative |
| works of the document must themselves be free in the same sense. |
| It complements the GNU General Public License, which is a copyleft |
| license designed for free software. |
| |
| We have designed this License in order to use it for manuals for |
| free software, because free software needs free documentation: a |
| free program should come with manuals providing the same freedoms |
| that the software does. But this License is not limited to |
| software manuals; it can be used for any textual work, regardless |
| of subject matter or whether it is published as a printed book. We |
| recommend this License principally for works whose purpose is |
| instruction or reference. |
| |
| 1. APPLICABILITY AND DEFINITIONS |
| |
| This License applies to any manual or other work, in any medium, |
| that contains a notice placed by the copyright holder saying it can |
| be distributed under the terms of this License. Such a notice |
| grants a world-wide, royalty-free license, unlimited in duration, |
| to use that work under the conditions stated herein. The |
| “Document”, below, refers to any such manual or work. Any member |
| of the public is a licensee, and is addressed as “you”. You accept |
| the license if you copy, modify or distribute the work in a way |
| requiring permission under copyright law. |
| |
| A “Modified Version” of the Document means any work containing the |
| Document or a portion of it, either copied verbatim, or with |
| modifications and/or translated into another language. |
| |
| A “Secondary Section” is a named appendix or a front-matter section |
| of the Document that deals exclusively with the relationship of the |
| publishers or authors of the Document to the Document’s overall |
| subject (or to related matters) and contains nothing that could |
| fall directly within that overall subject. (Thus, if the Document |
| is in part a textbook of mathematics, a Secondary Section may not |
| explain any mathematics.) The relationship could be a matter of |
| historical connection with the subject or with related matters, or |
| of legal, commercial, philosophical, ethical or political position |
| regarding them. |
| |
| The “Invariant Sections” are certain Secondary Sections whose |
| titles are designated, as being those of Invariant Sections, in the |
| notice that says that the Document is released under this License. |
| If a section does not fit the above definition of Secondary then it |
| is not allowed to be designated as Invariant. The Document may |
| contain zero Invariant Sections. If the Document does not identify |
| any Invariant Sections then there are none. |
| |
| The “Cover Texts” are certain short passages of text that are |
| listed, as Front-Cover Texts or Back-Cover Texts, in the notice |
| that says that the Document is released under this License. A |
| Front-Cover Text may be at most 5 words, and a Back-Cover Text may |
| be at most 25 words. |
| |
| A “Transparent” copy of the Document means a machine-readable copy, |
| represented in a format whose specification is available to the |
| general public, that is suitable for revising the document |
| straightforwardly with generic text editors or (for images composed |
| of pixels) generic paint programs or (for drawings) some widely |
| available drawing editor, and that is suitable for input to text |
| formatters or for automatic translation to a variety of formats |
| suitable for input to text formatters. A copy made in an otherwise |
| Transparent file format whose markup, or absence of markup, has |
| been arranged to thwart or discourage subsequent modification by |
| readers is not Transparent. An image format is not Transparent if |
| used for any substantial amount of text. A copy that is not |
| “Transparent” is called “Opaque”. |
| |
| Examples of suitable formats for Transparent copies include plain |
| ASCII without markup, Texinfo input format, LaTeX input format, |
| SGML or XML using a publicly available DTD, and standard-conforming |
| simple HTML, PostScript or PDF designed for human modification. |
| Examples of transparent image formats include PNG, XCF and JPG. |
| Opaque formats include proprietary formats that can be read and |
| edited only by proprietary word processors, SGML or XML for which |
| the DTD and/or processing tools are not generally available, and |
| the machine-generated HTML, PostScript or PDF produced by some word |
| processors for output purposes only. |
| |
| The “Title Page” means, for a printed book, the title page itself, |
| plus such following pages as are needed to hold, legibly, the |
| material this License requires to appear in the title page. For |
| works in formats which do not have any title page as such, “Title |
| Page” means the text near the most prominent appearance of the |
| work’s title, preceding the beginning of the body of the text. |
| |
| The “publisher” means any person or entity that distributes copies |
| of the Document to the public. |
| |
| A section “Entitled XYZ” means a named subunit of the Document |
| whose title either is precisely XYZ or contains XYZ in parentheses |
| following text that translates XYZ in another language. (Here XYZ |
| stands for a specific section name mentioned below, such as |
| “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) |
| To “Preserve the Title” of such a section when you modify the |
| Document means that it remains a section “Entitled XYZ” according |
| to this definition. |
| |
| The Document may include Warranty Disclaimers next to the notice |
| which states that this License applies to the Document. These |
| Warranty Disclaimers are considered to be included by reference in |
| this License, but only as regards disclaiming warranties: any other |
| implication that these Warranty Disclaimers may have is void and |
| has no effect on the meaning of this License. |
| |
| 2. VERBATIM COPYING |
| |
| You may copy and distribute the Document in any medium, either |
| commercially or noncommercially, provided that this License, the |
| copyright notices, and the license notice saying this License |
| applies to the Document are reproduced in all copies, and that you |
| add no other conditions whatsoever to those of this License. You |
| may not use technical measures to obstruct or control the reading |
| or further copying of the copies you make or distribute. However, |
| you may accept compensation in exchange for copies. If you |
| distribute a large enough number of copies you must also follow the |
| conditions in section 3. |
| |
| You may also lend copies, under the same conditions stated above, |
| and you may publicly display copies. |
| |
| 3. COPYING IN QUANTITY |
| |
| If you publish printed copies (or copies in media that commonly |
| have printed covers) of the Document, numbering more than 100, and |
| the Document’s license notice requires Cover Texts, you must |
| enclose the copies in covers that carry, clearly and legibly, all |
| of these Cover Texts: Front-Cover Texts on the front cover, and |
| Back-Cover Texts on the back cover. Both covers must also clearly |
| and legibly identify you as the publisher of these copies. The |
| front cover must present the full title with all words of the title |
| equally prominent and visible. You may add other material on the |
| covers in addition. Copying with changes limited to the covers, as |
| long as they preserve the title of the Document and satisfy these |
| conditions, can be treated as verbatim copying in other respects. |
| |
| If the required texts for either cover are too voluminous to fit |
| legibly, you should put the first ones listed (as many as fit |
| reasonably) on the actual cover, and continue the rest onto |
| adjacent pages. |
| |
| If you publish or distribute Opaque copies of the Document |
| numbering more than 100, you must either include a machine-readable |
| Transparent copy along with each Opaque copy, or state in or with |
| each Opaque copy a computer-network location from which the general |
| network-using public has access to download using public-standard |
| network protocols a complete Transparent copy of the Document, free |
| of added material. If you use the latter option, you must take |
| reasonably prudent steps, when you begin distribution of Opaque |
| copies in quantity, to ensure that this Transparent copy will |
| remain thus accessible at the stated location until at least one |
| year after the last time you distribute an Opaque copy (directly or |
| through your agents or retailers) of that edition to the public. |
| |
| It is requested, but not required, that you contact the authors of |
| the Document well before redistributing any large number of copies, |
| to give them a chance to provide you with an updated version of the |
| Document. |
| |
| 4. MODIFICATIONS |
| |
| You may copy and distribute a Modified Version of the Document |
| under the conditions of sections 2 and 3 above, provided that you |
| release the Modified Version under precisely this License, with the |
| Modified Version filling the role of the Document, thus licensing |
| distribution and modification of the Modified Version to whoever |
| possesses a copy of it. In addition, you must do these things in |
| the Modified Version: |
| |
| A. Use in the Title Page (and on the covers, if any) a title |
| distinct from that of the Document, and from those of previous |
| versions (which should, if there were any, be listed in the |
| History section of the Document). You may use the same title |
| as a previous version if the original publisher of that |
| version gives permission. |
| |
| B. List on the Title Page, as authors, one or more persons or |
| entities responsible for authorship of the modifications in |
| the Modified Version, together with at least five of the |
| principal authors of the Document (all of its principal |
| authors, if it has fewer than five), unless they release you |
| from this requirement. |
| |
| C. State on the Title page the name of the publisher of the |
| Modified Version, as the publisher. |
| |
| D. Preserve all the copyright notices of the Document. |
| |
| E. Add an appropriate copyright notice for your modifications |
| adjacent to the other copyright notices. |
| |
| F. Include, immediately after the copyright notices, a license |
| notice giving the public permission to use the Modified |
| Version under the terms of this License, in the form shown in |
| the Addendum below. |
| |
| G. Preserve in that license notice the full lists of Invariant |
| Sections and required Cover Texts given in the Document’s |
| license notice. |
| |
| H. Include an unaltered copy of this License. |
| |
| I. Preserve the section Entitled “History”, Preserve its Title, |
| and add to it an item stating at least the title, year, new |
| authors, and publisher of the Modified Version as given on the |
| Title Page. If there is no section Entitled “History” in the |
| Document, create one stating the title, year, authors, and |
| publisher of the Document as given on its Title Page, then add |
| an item describing the Modified Version as stated in the |
| previous sentence. |
| |
| J. Preserve the network location, if any, given in the Document |
| for public access to a Transparent copy of the Document, and |
| likewise the network locations given in the Document for |
| previous versions it was based on. These may be placed in the |
| “History” section. You may omit a network location for a work |
| that was published at least four years before the Document |
| itself, or if the original publisher of the version it refers |
| to gives permission. |
| |
| K. For any section Entitled “Acknowledgements” or “Dedications”, |
| Preserve the Title of the section, and preserve in the section |
| all the substance and tone of each of the contributor |
| acknowledgements and/or dedications given therein. |
| |
| L. Preserve all the Invariant Sections of the Document, unaltered |
| in their text and in their titles. Section numbers or the |
| equivalent are not considered part of the section titles. |
| |
| M. Delete any section Entitled “Endorsements”. Such a section |
| may not be included in the Modified Version. |
| |
| N. Do not retitle any existing section to be Entitled |
| “Endorsements” or to conflict in title with any Invariant |
| Section. |
| |
| O. Preserve any Warranty Disclaimers. |
| |
| If the Modified Version includes new front-matter sections or |
| appendices that qualify as Secondary Sections and contain no |
| material copied from the Document, you may at your option designate |
| some or all of these sections as invariant. To do this, add their |
| titles to the list of Invariant Sections in the Modified Version’s |
| license notice. These titles must be distinct from any other |
| section titles. |
| |
| You may add a section Entitled “Endorsements”, provided it contains |
| nothing but endorsements of your Modified Version by various |
| parties—for example, statements of peer review or that the text has |
| been approved by an organization as the authoritative definition of |
| a standard. |
| |
| You may add a passage of up to five words as a Front-Cover Text, |
| and a passage of up to 25 words as a Back-Cover Text, to the end of |
| the list of Cover Texts in the Modified Version. Only one passage |
| of Front-Cover Text and one of Back-Cover Text may be added by (or |
| through arrangements made by) any one entity. If the Document |
| already includes a cover text for the same cover, previously added |
| by you or by arrangement made by the same entity you are acting on |
| behalf of, you may not add another; but you may replace the old |
| one, on explicit permission from the previous publisher that added |
| the old one. |
| |
| The author(s) and publisher(s) of the Document do not by this |
| License give permission to use their names for publicity for or to |
| assert or imply endorsement of any Modified Version. |
| |
| 5. COMBINING DOCUMENTS |
| |
| You may combine the Document with other documents released under |
| this License, under the terms defined in section 4 above for |
| modified versions, provided that you include in the combination all |
| of the Invariant Sections of all of the original documents, |
| unmodified, and list them all as Invariant Sections of your |
| combined work in its license notice, and that you preserve all |
| their Warranty Disclaimers. |
| |
| The combined work need only contain one copy of this License, and |
| multiple identical Invariant Sections may be replaced with a single |
| copy. If there are multiple Invariant Sections with the same name |
| but different contents, make the title of each such section unique |
| by adding at the end of it, in parentheses, the name of the |
| original author or publisher of that section if known, or else a |
| unique number. Make the same adjustment to the section titles in |
| the list of Invariant Sections in the license notice of the |
| combined work. |
| |
| In the combination, you must combine any sections Entitled |
| “History” in the various original documents, forming one section |
| Entitled “History”; likewise combine any sections Entitled |
| “Acknowledgements”, and any sections Entitled “Dedications”. You |
| must delete all sections Entitled “Endorsements.” |
| |
| 6. COLLECTIONS OF DOCUMENTS |
| |
| You may make a collection consisting of the Document and other |
| documents released under this License, and replace the individual |
| copies of this License in the various documents with a single copy |
| that is included in the collection, provided that you follow the |
| rules of this License for verbatim copying of each of the documents |
| in all other respects. |
| |
| You may extract a single document from such a collection, and |
| distribute it individually under this License, provided you insert |
| a copy of this License into the extracted document, and follow this |
| License in all other respects regarding verbatim copying of that |
| document. |
| |
| 7. AGGREGATION WITH INDEPENDENT WORKS |
| |
| A compilation of the Document or its derivatives with other |
| separate and independent documents or works, in or on a volume of a |
| storage or distribution medium, is called an “aggregate” if the |
| copyright resulting from the compilation is not used to limit the |
| legal rights of the compilation’s users beyond what the individual |
| works permit. When the Document is included in an aggregate, this |
| License does not apply to the other works in the aggregate which |
| are not themselves derivative works of the Document. |
| |
| If the Cover Text requirement of section 3 is applicable to these |
| copies of the Document, then if the Document is less than one half |
| of the entire aggregate, the Document’s Cover Texts may be placed |
| on covers that bracket the Document within the aggregate, or the |
| electronic equivalent of covers if the Document is in electronic |
| form. Otherwise they must appear on printed covers that bracket |
| the whole aggregate. |
| |
| 8. TRANSLATION |
| |
| Translation is considered a kind of modification, so you may |
| distribute translations of the Document under the terms of section |
| 4. Replacing Invariant Sections with translations requires special |
| permission from their copyright holders, but you may include |
| translations of some or all Invariant Sections in addition to the |
| original versions of these Invariant Sections. You may include a |
| translation of this License, and all the license notices in the |
| Document, and any Warranty Disclaimers, provided that you also |
| include the original English version of this License and the |
| original versions of those notices and disclaimers. In case of a |
| disagreement between the translation and the original version of |
| this License or a notice or disclaimer, the original version will |
| prevail. |
| |
| If a section in the Document is Entitled “Acknowledgements”, |
| “Dedications”, or “History”, the requirement (section 4) to |
| Preserve its Title (section 1) will typically require changing the |
| actual title. |
| |
| 9. TERMINATION |
| |
| You may not copy, modify, sublicense, or distribute the Document |
| except as expressly provided under this License. Any attempt |
| otherwise to copy, modify, sublicense, or distribute it is void, |
| and will automatically terminate your rights under this License. |
| |
| However, if you cease all violation of this License, then your |
| license from a particular copyright holder is reinstated (a) |
| provisionally, unless and until the copyright holder explicitly and |
| finally terminates your license, and (b) permanently, if the |
| copyright holder fails to notify you of the violation by some |
| reasonable means prior to 60 days after the cessation. |
| |
| Moreover, your license from a particular copyright holder is |
| reinstated permanently if the copyright holder notifies you of the |
| violation by some reasonable means, this is the first time you have |
| received notice of violation of this License (for any work) from |
| that copyright holder, and you cure the violation prior to 30 days |
| after your receipt of the notice. |
| |
| Termination of your rights under this section does not terminate |
| the licenses of parties who have received copies or rights from you |
| under this License. If your rights have been terminated and not |
| permanently reinstated, receipt of a copy of some or all of the |
| same material does not give you any rights to use it. |
| |
| 10. FUTURE REVISIONS OF THIS LICENSE |
| |
| The Free Software Foundation may publish new, revised versions of |
| the GNU Free Documentation License from time to time. Such new |
| versions will be similar in spirit to the present version, but may |
| differ in detail to address new problems or concerns. See |
| <http://www.gnu.org/copyleft/>. |
| |
| Each version of the License is given a distinguishing version |
| number. If the Document specifies that a particular numbered |
| version of this License “or any later version” applies to it, you |
| have the option of following the terms and conditions either of |
| that specified version or of any later version that has been |
| published (not as a draft) by the Free Software Foundation. If the |
| Document does not specify a version number of this License, you may |
| choose any version ever published (not as a draft) by the Free |
| Software Foundation. If the Document specifies that a proxy can |
| decide which future versions of this License can be used, that |
| proxy’s public statement of acceptance of a version permanently |
| authorizes you to choose that version for the Document. |
| |
| 11. RELICENSING |
| |
| “Massive Multiauthor Collaboration Site” (or “MMC Site”) means any |
| World Wide Web server that publishes copyrightable works and also |
| provides prominent facilities for anybody to edit those works. A |
| public wiki that anybody can edit is an example of such a server. |
| A “Massive Multiauthor Collaboration” (or “MMC”) contained in the |
| site means any set of copyrightable works thus published on the MMC |
| site. |
| |
| “CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 |
| license published by Creative Commons Corporation, a not-for-profit |
| corporation with a principal place of business in San Francisco, |
| California, as well as future copyleft versions of that license |
| published by that same organization. |
| |
| “Incorporate” means to publish or republish a Document, in whole or |
| in part, as part of another Document. |
| |
| An MMC is “eligible for relicensing” if it is licensed under this |
| License, and if all works that were first published under this |
| License somewhere other than this MMC, and subsequently |
| incorporated in whole or in part into the MMC, (1) had no cover |
| texts or invariant sections, and (2) were thus incorporated prior |
| to November 1, 2008. |
| |
| The operator of an MMC Site may republish an MMC contained in the |
| site under CC-BY-SA on the same site at any time before August 1, |
| 2009, provided the MMC is eligible for relicensing. |
| |
| ADDENDUM: How to use this License for your documents |
| ==================================================== |
| |
| To use this License in a document you have written, include a copy of |
| the License in the document and put the following copyright and license |
| notices just after the title page: |
| |
| Copyright (C) YEAR YOUR NAME. |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 |
| or any later version published by the Free Software Foundation; |
| with no Invariant Sections, no Front-Cover Texts, and no Back-Cover |
| Texts. A copy of the license is included in the section entitled ``GNU |
| Free Documentation License''. |
| |
| If you have Invariant Sections, Front-Cover Texts and Back-Cover |
| Texts, replace the “with…Texts.” line with this: |
| |
| with the Invariant Sections being LIST THEIR TITLES, with |
| the Front-Cover Texts being LIST, and with the Back-Cover Texts |
| being LIST. |
| |
| If you have Invariant Sections without Cover Texts, or some other |
| combination of the three, merge those two alternatives to suit the |
| situation. |
| |
| If your document contains nontrivial examples of program code, we |
| recommend releasing these examples in parallel under your choice of free |
| software license, such as the GNU General Public License, to permit |
| their use in free software. |
| |
| |
| File: automake.info, Node: Indices, Prev: Copying This Manual, Up: Top |
| |
| Appendix B Indices |
| ****************** |
| |
| * Menu: |
| |
| * Macro Index:: Index of Autoconf macros |
| * Variable Index:: Index of Makefile variables |
| * General Index:: General index |
| |
| |
| File: automake.info, Node: Macro Index, Next: Variable Index, Up: Indices |
| |
| B.1 Macro Index |
| =============== |
| |
| [index] |
| * Menu: |
| |
| * _AM_DEPENDENCIES: Private Macros. (line 12) |
| * AC_CANONICAL_BUILD: Optional. (line 11) |
| * AC_CANONICAL_HOST: Optional. (line 12) |
| * AC_CANONICAL_TARGET: Optional. (line 13) |
| * AC_CONFIG_AUX_DIR: Optional. (line 19) |
| * AC_CONFIG_AUX_DIR <1>: Subpackages. (line 6) |
| * AC_CONFIG_FILES: Requirements. (line 15) |
| * AC_CONFIG_HEADERS: Optional. (line 44) |
| * AC_CONFIG_LIBOBJ_DIR: Optional. (line 40) |
| * AC_CONFIG_LIBOBJ_DIR <1>: LIBOBJS. (line 51) |
| * AC_CONFIG_LINKS: Optional. (line 55) |
| * AC_CONFIG_SUBDIRS: Subpackages. (line 6) |
| * AC_DEFUN: Extending aclocal. (line 36) |
| * AC_F77_LIBRARY_LDFLAGS: Optional. (line 101) |
| * AC_FC_SRCEXT: Optional. (line 107) |
| * AC_INIT: Public Macros. (line 15) |
| * AC_LIBOBJ: Optional. (line 65) |
| * AC_LIBOBJ <1>: LTLIBOBJS. (line 6) |
| * AC_LIBOBJ <2>: LIBOBJS. (line 11) |
| * AC_LIBSOURCE: Optional. (line 66) |
| * AC_LIBSOURCE <1>: LIBOBJS. (line 17) |
| * AC_LIBSOURCES: Optional. (line 67) |
| * AC_OUTPUT: Requirements. (line 15) |
| * AC_PREREQ: Extending aclocal. (line 36) |
| * AC_PROG_CXX: Optional. (line 85) |
| * AC_PROG_F77: Optional. (line 97) |
| * AC_PROG_FC: Optional. (line 112) |
| * AC_PROG_LEX: Public Macros. (line 95) |
| * AC_PROG_LEX <1>: Optional. (line 127) |
| * AC_PROG_LIBTOOL: Optional. (line 117) |
| * AC_PROG_OBJC: Optional. (line 89) |
| * AC_PROG_OBJCXX: Optional. (line 93) |
| * AC_PROG_RANLIB: Optional. (line 81) |
| * AC_PROG_YACC: Optional. (line 121) |
| * AC_REQUIRE_AUX_FILE: Optional. (line 131) |
| * AC_SUBST: Optional. (line 139) |
| * AM_CONDITIONAL: Optional. (line 152) |
| * AM_CONDITIONAL <1>: Usage of Conditionals. |
| (line 6) |
| * AM_CONDITIONAL <2>: Usage of Conditionals. |
| (line 9) |
| * AM_COND_IF: Optional. (line 155) |
| * AM_COND_IF <1>: Usage of Conditionals. |
| (line 66) |
| * AM_COND_IF <2>: Usage of Conditionals. |
| (line 70) |
| * AM_DEP_TRACK: Private Macros. (line 14) |
| * AM_GNU_GETTEXT: Optional. (line 161) |
| * AM_GNU_GETTEXT_INTL_SUBDIR: Optional. (line 167) |
| * AM_INIT_AUTOMAKE: Requirements. (line 6) |
| * AM_INIT_AUTOMAKE <1>: Public Macros. (line 7) |
| * AM_MAINTAINER_MODE: Rebuilding. (line 9) |
| * AM_MAINTAINER_MODE <1>: maintainer-mode. (line 37) |
| * AM_MAINTAINER_MODE([DEFAULT-MODE]): Optional. (line 172) |
| * AM_MAKE_INCLUDE: Private Macros. (line 20) |
| * AM_MISSING_PROG: Public Macros. (line 111) |
| * AM_OUTPUT_DEPENDENCY_COMMANDS: Private Macros. (line 15) |
| * AM_PATH_LISPDIR: Public Macros. (line 61) |
| * AM_PATH_PYTHON: Python. (line 28) |
| * AM_PROG_AR: Public Macros. (line 76) |
| * AM_PROG_AS: Public Macros. (line 83) |
| * AM_PROG_CC_C_O: Public Macros. (line 88) |
| * AM_PROG_GCJ: Public Macros. (line 100) |
| * AM_PROG_INSTALL_STRIP: Private Macros. (line 25) |
| * AM_PROG_LEX: Public Macros. (line 95) |
| * AM_PROG_MKDIR_P: Obsolete Macros. (line 14) |
| * AM_PROG_UPC: Public Macros. (line 105) |
| * AM_PROG_VALAC: Vala Support. (line 20) |
| * AM_SANITY_CHECK: Private Macros. (line 30) |
| * AM_SET_DEPDIR: Private Macros. (line 13) |
| * AM_SILENT_RULES: Public Macros. (line 119) |
| * AM_SUBST_NOTMAKE(VAR): Optional. (line 180) |
| * AM_WITH_DMALLOC: Public Macros. (line 123) |
| * m4_include: Basics of Distribution. |
| (line 17) |
| * m4_include <1>: Optional. (line 190) |
| |
| |
| File: automake.info, Node: Variable Index, Next: General Index, Prev: Macro Index, Up: Indices |
| |
| B.2 Variable Index |
| ================== |
| |
| [index] |
| * Menu: |
| |
| * _DATA: Data. (line 6) |
| * _HEADERS: Headers. (line 6) |
| * _LIBRARIES: A Library. (line 6) |
| * _LISP: Emacs Lisp. (line 6) |
| * _LOG_COMPILE: Parallel Test Harness. |
| (line 51) |
| * _LOG_COMPILER: Parallel Test Harness. |
| (line 51) |
| * _LOG_DRIVER: Declaring Custom Test Drivers. |
| (line 6) |
| * _LOG_DRIVER_FLAGS: Declaring Custom Test Drivers. |
| (line 6) |
| * _LOG_FLAGS: Parallel Test Harness. |
| (line 51) |
| * _LTLIBRARIES: Libtool Libraries. (line 6) |
| * _MANS: Man Pages. (line 6) |
| * _PROGRAMS: Uniform. (line 11) |
| * _PROGRAMS <1>: Program Sources. (line 6) |
| * _PYTHON: Python. (line 6) |
| * _SCRIPTS: Scripts. (line 6) |
| * _SOURCES: Program Sources. (line 32) |
| * _SOURCES <1>: Program Sources. (line 33) |
| * _SOURCES <2>: Default _SOURCES. (line 6) |
| * _TEXINFOS: Texinfo. (line 6) |
| * _TEXINFOS <1>: Texinfo. (line 65) |
| * ALLOCA: LTLIBOBJS. (line 6) |
| * ALLOCA <1>: LIBOBJS. (line 6) |
| * AM_CCASFLAGS: Assembly Support. (line 10) |
| * AM_CFLAGS: Program Variables. (line 50) |
| * AM_COLOR_TESTS: Scripts-based Testsuites. |
| (line 67) |
| * AM_CPPFLAGS: Program Variables. (line 16) |
| * AM_CPPFLAGS <1>: Assembly Support. (line 10) |
| * AM_CXXFLAGS: C++ Support. (line 22) |
| * AM_DEFAULT_SOURCE_EXT: Default _SOURCES. (line 6) |
| * ‘AM_DEFAULT_V’: Automake Silent Rules. |
| (line 120) |
| * ‘AM_DEFAULT_VERBOSITY’: Automake Silent Rules. |
| (line 120) |
| * AM_DISTCHECK_CONFIGURE_FLAGS: Checking the Distribution. |
| (line 28) |
| * AM_ETAGSFLAGS: Tags. (line 25) |
| * AM_EXT_LOG_DRIVER_FLAGS: Declaring Custom Test Drivers. |
| (line 6) |
| * AM_EXT_LOG_FLAGS: Parallel Test Harness. |
| (line 51) |
| * AM_FCFLAGS: Fortran 9x Support. (line 22) |
| * AM_FFLAGS: Fortran 77 Support. (line 22) |
| * AM_GCJFLAGS: Java Support with gcj. |
| (line 26) |
| * AM_INSTALLCHECK_STD_OPTIONS_EXEMPT: List of Automake options. |
| (line 135) |
| * AM_JAVACFLAGS: Java. (line 44) |
| * AM_LDFLAGS: Linking. (line 10) |
| * AM_LDFLAGS <1>: Program Variables. (line 59) |
| * AM_LFLAGS: Yacc and Lex. (line 60) |
| * AM_LIBTOOLFLAGS: Libtool Flags. (line 6) |
| * AM_LOG_DRIVER_FLAGS: Declaring Custom Test Drivers. |
| (line 6) |
| * AM_LOG_FLAGS: Parallel Test Harness. |
| (line 51) |
| * AM_MAKEFLAGS: Subdirectories. (line 29) |
| * AM_MAKEINFOFLAGS: Texinfo. (line 115) |
| * AM_MAKEINFOHTMLFLAGS: Texinfo. (line 116) |
| * AM_OBJCFLAGS: Objective C Support. (line 22) |
| * AM_OBJCXXFLAGS: Objective C++ Support. |
| (line 22) |
| * AM_RFLAGS: Fortran 77 Support. (line 28) |
| * AM_RUNTESTFLAGS: DejaGnu Tests. (line 24) |
| * AM_TESTS_ENVIRONMENT: Scripts-based Testsuites. |
| (line 86) |
| * AM_TESTS_FD_REDIRECT: Scripts-based Testsuites. |
| (line 94) |
| * AM_UPCFLAGS: Unified Parallel C Support. |
| (line 21) |
| * AM_UPDATE_INFO_DIR: Texinfo. (line 92) |
| * ‘AM_V’: Automake Silent Rules. |
| (line 120) |
| * AM_VALAFLAGS: Vala Support. (line 41) |
| * ‘AM_V_at’: Automake Silent Rules. |
| (line 120) |
| * ‘AM_V_GEN’: Automake Silent Rules. |
| (line 120) |
| * AM_YFLAGS: Yacc and Lex. (line 37) |
| * AR: Public Macros. (line 76) |
| * AUTOCONF: automake Invocation. (line 28) |
| * AUTOM4TE: aclocal Invocation. (line 44) |
| * AUTOMAKE_JOBS: automake Invocation. (line 174) |
| * AUTOMAKE_OPTIONS: Public Macros. (line 10) |
| * AUTOMAKE_OPTIONS <1>: Dependencies. (line 34) |
| * AUTOMAKE_OPTIONS <2>: List of Automake options. |
| (line 6) |
| * bin_PROGRAMS: Program Sources. (line 6) |
| * bin_SCRIPTS: Scripts. (line 18) |
| * build_triplet: Optional. (line 14) |
| * BUILT_SOURCES: Sources. (line 27) |
| * BZIP2: The Types of Distributions. |
| (line 13) |
| * CC: Program Variables. (line 12) |
| * CCAS: Public Macros. (line 83) |
| * CCAS <1>: Assembly Support. (line 10) |
| * CCASFLAGS: Public Macros. (line 83) |
| * CCASFLAGS <1>: Assembly Support. (line 10) |
| * CFLAGS: Program Variables. (line 12) |
| * check_: Uniform. (line 95) |
| * check_LTLIBRARIES: Libtool Convenience Libraries. |
| (line 6) |
| * check_PROGRAMS: Program Sources. (line 6) |
| * check_PROGRAMS <1>: Default _SOURCES. (line 28) |
| * check_SCRIPTS: Scripts. (line 18) |
| * CLASSPATH_ENV: Java. (line 53) |
| * CLEANFILES: Clean. (line 13) |
| * COMPILE: Program Variables. (line 55) |
| * CONFIGURE_DEPENDENCIES: Rebuilding. (line 12) |
| * CONFIG_STATUS_DEPENDENCIES: Rebuilding. (line 12) |
| * CPPFLAGS: Program Variables. (line 12) |
| * CPPFLAGS <1>: Assembly Support. (line 10) |
| * CXX: C++ Support. (line 16) |
| * CXXCOMPILE: C++ Support. (line 25) |
| * CXXFLAGS: C++ Support. (line 19) |
| * CXXLINK: C++ Support. (line 29) |
| * CXXLINK <1>: How the Linker is Chosen. |
| (line 12) |
| * DATA: Uniform. (line 101) |
| * DATA <1>: Data. (line 7) |
| * data_DATA: Data. (line 9) |
| * DEFS: Program Variables. (line 12) |
| * DEJATOOL: DejaGnu Tests. (line 19) |
| * DESTDIR: DESTDIR. (line 6) |
| * DESTDIR <1>: Staged Installs. (line 6) |
| * DISABLE_HARD_ERRORS: Scripts-based Testsuites. |
| (line 32) |
| * DISTCHECK_CONFIGURE_FLAGS: Checking the Distribution. |
| (line 28) |
| * distcleancheck_listfiles: Checking the Distribution. |
| (line 70) |
| * distcleancheck_listfiles <1>: Errors with distclean. |
| (line 112) |
| * DISTCLEANFILES: Clean. (line 13) |
| * DISTCLEANFILES <1>: Checking the Distribution. |
| (line 70) |
| * distdir: The dist Hook. (line 33) |
| * distdir <1>: Third-Party Makefiles. |
| (line 25) |
| * distuninstallcheck_listfiles: Checking the Distribution. |
| (line 106) |
| * dist_: Alternative. (line 29) |
| * dist_ <1>: Fine-grained Distribution Control. |
| (line 6) |
| * dist_lisp_LISP: Emacs Lisp. (line 11) |
| * dist_noinst_LISP: Emacs Lisp. (line 11) |
| * DIST_SUBDIRS: Subdirectories with AM_CONDITIONAL. |
| (line 25) |
| * DIST_SUBDIRS <1>: Basics of Distribution. |
| (line 47) |
| * DVIPS: Texinfo. (line 141) |
| * EMACS: Public Macros. (line 61) |
| * ETAGSFLAGS: Tags. (line 25) |
| * ETAGS_ARGS: Tags. (line 25) |
| * EXPECT: DejaGnu Tests. (line 19) |
| * EXTRA_DIST: Basics of Distribution. |
| (line 34) |
| * EXTRA_maude_DEPENDENCIES: Linking. (line 41) |
| * EXTRA_maude_DEPENDENCIES <1>: Program and Library Variables. |
| (line 119) |
| * EXTRA_maude_SOURCES: Program and Library Variables. |
| (line 53) |
| * EXTRA_PROGRAMS: Conditional Programs. |
| (line 15) |
| * EXT_LOG_COMPILE: Parallel Test Harness. |
| (line 51) |
| * EXT_LOG_COMPILER: Parallel Test Harness. |
| (line 51) |
| * EXT_LOG_DRIVER: Declaring Custom Test Drivers. |
| (line 6) |
| * EXT_LOG_DRIVER_FLAGS: Declaring Custom Test Drivers. |
| (line 6) |
| * EXT_LOG_FLAGS: Parallel Test Harness. |
| (line 51) |
| * F77: Fortran 77 Support. (line 16) |
| * F77COMPILE: Fortran 77 Support. (line 31) |
| * F77LINK: How the Linker is Chosen. |
| (line 13) |
| * FC: Fortran 9x Support. (line 16) |
| * FCCOMPILE: Fortran 9x Support. (line 25) |
| * FCFLAGS: Fortran 9x Support. (line 19) |
| * FCLINK: How the Linker is Chosen. |
| (line 14) |
| * FCLINK <1>: Fortran 9x Support. (line 29) |
| * FFLAGS: Fortran 77 Support. (line 19) |
| * FLIBS: Mixing Fortran 77 With C and C++. |
| (line 21) |
| * FLINK: Fortran 77 Support. (line 35) |
| * GCJ: Public Macros. (line 100) |
| * GCJFLAGS: Public Macros. (line 100) |
| * GCJFLAGS <1>: Java Support with gcj. |
| (line 16) |
| * GCJLINK: How the Linker is Chosen. |
| (line 10) |
| * GTAGS_ARGS: Tags. (line 60) |
| * GZIP_ENV: Basics of Distribution. |
| (line 14) |
| * HEADERS: Uniform. (line 101) |
| * host_triplet: Optional. (line 14) |
| * INCLUDES: Program Variables. (line 44) |
| * include_HEADERS: Headers. (line 6) |
| * info_TEXINFOS: Texinfo. (line 6) |
| * JAVA: Uniform. (line 101) |
| * JAVAC: Java. (line 37) |
| * JAVACFLAGS: Java. (line 40) |
| * JAVAROOT: Java. (line 49) |
| * LDADD: Linking. (line 10) |
| * LDFLAGS: Program Variables. (line 12) |
| * LFLAGS: Yacc and Lex. (line 60) |
| * libexec_PROGRAMS: Program Sources. (line 6) |
| * libexec_SCRIPTS: Scripts. (line 18) |
| * LIBOBJS: Optional. (line 68) |
| * LIBOBJS <1>: LTLIBOBJS. (line 6) |
| * LIBOBJS <2>: LIBOBJS. (line 6) |
| * LIBRARIES: Uniform. (line 101) |
| * LIBS: Program Variables. (line 12) |
| * LIBTOOLFLAGS: Libtool Flags. (line 6) |
| * lib_LIBRARIES: A Library. (line 6) |
| * lib_LTLIBRARIES: Libtool Libraries. (line 6) |
| * LINK: Program Variables. (line 64) |
| * LINK <1>: How the Linker is Chosen. |
| (line 17) |
| * LISP: Uniform. (line 101) |
| * lispdir: Public Macros. (line 61) |
| * lisp_LISP: Emacs Lisp. (line 6) |
| * localstate_DATA: Data. (line 9) |
| * LOG_COMPILE: Parallel Test Harness. |
| (line 51) |
| * LOG_COMPILER: Parallel Test Harness. |
| (line 51) |
| * LOG_DRIVER: Declaring Custom Test Drivers. |
| (line 6) |
| * LOG_DRIVER_FLAGS: Declaring Custom Test Drivers. |
| (line 6) |
| * LOG_FLAGS: Parallel Test Harness. |
| (line 51) |
| * LTALLOCA: LTLIBOBJS. (line 6) |
| * LTALLOCA <1>: LIBOBJS. (line 6) |
| * LTLIBOBJS: LTLIBOBJS. (line 6) |
| * LTLIBOBJS <1>: LIBOBJS. (line 6) |
| * LTLIBRARIES: Uniform. (line 101) |
| * MAINTAINERCLEANFILES: Clean. (line 13) |
| * MAKE: Subdirectories. (line 29) |
| * MAKEINFO: Texinfo. (line 99) |
| * MAKEINFOFLAGS: Texinfo. (line 109) |
| * MAKEINFOHTML: Texinfo. (line 105) |
| * MANS: Uniform. (line 101) |
| * man_MANS: Man Pages. (line 6) |
| * maude_AR: Program and Library Variables. |
| (line 68) |
| * maude_CCASFLAGS: Program and Library Variables. |
| (line 170) |
| * maude_CFLAGS: Program and Library Variables. |
| (line 171) |
| * maude_CPPFLAGS: Program and Library Variables. |
| (line 172) |
| * maude_CXXFLAGS: Program and Library Variables. |
| (line 173) |
| * maude_DEPENDENCIES: Linking. (line 41) |
| * maude_DEPENDENCIES <1>: Program and Library Variables. |
| (line 118) |
| * maude_FFLAGS: Program and Library Variables. |
| (line 174) |
| * maude_GCJFLAGS: Program and Library Variables. |
| (line 175) |
| * maude_LDADD: Linking. (line 17) |
| * maude_LDADD <1>: Program and Library Variables. |
| (line 86) |
| * maude_LDFLAGS: Linking. (line 37) |
| * maude_LDFLAGS <1>: Program and Library Variables. |
| (line 106) |
| * maude_LFLAGS: Program and Library Variables. |
| (line 176) |
| * maude_LIBADD: A Library. (line 26) |
| * maude_LIBADD <1>: Program and Library Variables. |
| (line 78) |
| * maude_LIBTOOLFLAGS: Libtool Flags. (line 6) |
| * maude_LIBTOOLFLAGS <1>: Program and Library Variables. |
| (line 111) |
| * maude_LINK: Program and Library Variables. |
| (line 154) |
| * maude_OBJCFLAGS: Program and Library Variables. |
| (line 177) |
| * maude_OBJCXXFLAGS: Program and Library Variables. |
| (line 178) |
| * maude_RFLAGS: Program and Library Variables. |
| (line 179) |
| * maude_SHORTNAME: Program and Library Variables. |
| (line 210) |
| * maude_SOURCES: Program and Library Variables. |
| (line 18) |
| * maude_UPCFLAGS: Program and Library Variables. |
| (line 180) |
| * maude_YFLAGS: Program and Library Variables. |
| (line 181) |
| * MISSING: Public Macros. (line 111) |
| * MKDIR_P: Obsolete Macros. (line 14) |
| * mkdir_p: Obsolete Macros. (line 14) |
| * MOSTLYCLEANFILES: Clean. (line 13) |
| * nobase_: Alternative. (line 23) |
| * nodist_: Alternative. (line 29) |
| * nodist_ <1>: Fine-grained Distribution Control. |
| (line 6) |
| * noinst_: Uniform. (line 90) |
| * noinst_HEADERS: Headers. (line 6) |
| * noinst_HEADERS <1>: Headers. (line 23) |
| * noinst_LIBRARIES: A Library. (line 6) |
| * noinst_LISP: Emacs Lisp. (line 6) |
| * noinst_LTLIBRARIES: Libtool Convenience Libraries. |
| (line 6) |
| * noinst_PROGRAMS: Program Sources. (line 6) |
| * noinst_SCRIPTS: Scripts. (line 18) |
| * notrans_: Man Pages. (line 54) |
| * OBJC: Objective C Support. (line 16) |
| * OBJCCOMPILE: Objective C Support. (line 25) |
| * OBJCFLAGS: Objective C Support. (line 19) |
| * OBJCLINK: Objective C Support. (line 29) |
| * OBJCLINK <1>: How the Linker is Chosen. |
| (line 15) |
| * OBJCXX: Objective C++ Support. |
| (line 16) |
| * OBJCXXCOMPILE: Objective C++ Support. |
| (line 25) |
| * OBJCXXFLAGS: Objective C++ Support. |
| (line 19) |
| * OBJCXXLINK: Objective C++ Support. |
| (line 29) |
| * OBJCXXLINK <1>: How the Linker is Chosen. |
| (line 11) |
| * oldinclude_HEADERS: Headers. (line 6) |
| * PACKAGE: Basics of Distribution. |
| (line 6) |
| * pkgdatadir: Uniform. (line 19) |
| * pkgdata_DATA: Data. (line 9) |
| * pkgdata_SCRIPTS: Scripts. (line 18) |
| * pkgincludedir: Uniform. (line 19) |
| * pkginclude_HEADERS: Headers. (line 6) |
| * pkglibdir: Uniform. (line 19) |
| * pkglibexecdir: Uniform. (line 19) |
| * pkglibexec_PROGRAMS: Program Sources. (line 6) |
| * pkglibexec_SCRIPTS: Scripts. (line 18) |
| * pkglib_LIBRARIES: A Library. (line 6) |
| * pkglib_LTLIBRARIES: Libtool Libraries. (line 6) |
| * pkgpyexecdir: Python. (line 105) |
| * pkgpythondir: Python. (line 91) |
| * PROGRAMS: Uniform. (line 17) |
| * PROGRAMS <1>: Uniform. (line 101) |
| * pyexecdir: Python. (line 96) |
| * PYTHON: Uniform. (line 101) |
| * PYTHON <1>: Python. (line 56) |
| * pythondir: Python. (line 87) |
| * PYTHON_EXEC_PREFIX: Python. (line 77) |
| * PYTHON_PLATFORM: Python. (line 82) |
| * PYTHON_PREFIX: Python. (line 72) |
| * PYTHON_VERSION: Python. (line 68) |
| * RECHECK_LOGS: Parallel Test Harness. |
| (line 118) |
| * RFLAGS: Fortran 77 Support. (line 25) |
| * RUNTEST: DejaGnu Tests. (line 19) |
| * RUNTESTDEFAULTFLAGS: DejaGnu Tests. (line 14) |
| * RUNTESTFLAGS: DejaGnu Tests. (line 24) |
| * sbin_PROGRAMS: Program Sources. (line 6) |
| * sbin_SCRIPTS: Scripts. (line 18) |
| * SCRIPTS: Uniform. (line 101) |
| * SCRIPTS <1>: Scripts. (line 9) |
| * sharedstate_DATA: Data. (line 9) |
| * SOURCES: Program Sources. (line 33) |
| * SOURCES <1>: Default _SOURCES. (line 6) |
| * SUBDIRS: Subdirectories. (line 8) |
| * SUBDIRS <1>: Basics of Distribution. |
| (line 47) |
| * SUFFIXES: Suffixes. (line 6) |
| * sysconf_DATA: Data. (line 9) |
| * TAGS_DEPENDENCIES: Tags. (line 35) |
| * target_triplet: Optional. (line 14) |
| * TESTS: Scripts-based Testsuites. |
| (line 86) |
| * TESTS <1>: Parallel Test Harness. |
| (line 12) |
| * TESTS_ENVIRONMENT: Scripts-based Testsuites. |
| (line 86) |
| * TEST_EXTENSIONS: Parallel Test Harness. |
| (line 34) |
| * TEST_LOGS: Parallel Test Harness. |
| (line 34) |
| * TEST_SUITE_LOG: Parallel Test Harness. |
| (line 12) |
| * TEXI2DVI: Texinfo. (line 132) |
| * TEXI2PDF: Texinfo. (line 137) |
| * TEXINFOS: Uniform. (line 101) |
| * TEXINFOS <1>: Texinfo. (line 65) |
| * TEXINFO_TEX: Texinfo. (line 145) |
| * top_distdir: The dist Hook. (line 33) |
| * top_distdir <1>: Third-Party Makefiles. |
| (line 25) |
| * UPC: Public Macros. (line 105) |
| * UPC <1>: Unified Parallel C Support. |
| (line 15) |
| * UPCCOMPILE: Unified Parallel C Support. |
| (line 24) |
| * UPCFLAGS: Unified Parallel C Support. |
| (line 18) |
| * UPCLINK: Unified Parallel C Support. |
| (line 28) |
| * UPCLINK <1>: How the Linker is Chosen. |
| (line 16) |
| * ‘V’: Automake Silent Rules. |
| (line 88) |
| * VALAC: Vala Support. (line 34) |
| * VALAFLAGS: Vala Support. (line 38) |
| * VERBOSE: Parallel Test Harness. |
| (line 26) |
| * VERSION: Basics of Distribution. |
| (line 6) |
| * WARNINGS: automake Invocation. (line 167) |
| * WARNINGS <1>: aclocal Options. (line 91) |
| * WITH_DMALLOC: Public Macros. (line 123) |
| * XFAIL_TESTS: Scripts-based Testsuites. |
| (line 32) |
| * XZ_OPT: The Types of Distributions. |
| (line 24) |
| * YACC: Optional. (line 122) |
| * YFLAGS: Yacc and Lex. (line 37) |
| |
| |
| File: automake.info, Node: General Index, Prev: Variable Index, Up: Indices |
| |
| B.3 General Index |
| ================= |
| |
| [index] |
| * Menu: |
| |
| * ‘##’ (special Automake comment): General Operation. (line 68) |
| * ‘#serial’ syntax: Serials. (line 6) |
| * ‘$(LIBOBJS)’ and empty libraries: LIBOBJS. (line 72) |
| * +=: General Operation. (line 24) |
| * --add-missing: automake Invocation. (line 41) |
| * --automake-acdir: aclocal Options. (line 9) |
| * --build=BUILD: Cross-Compilation. (line 14) |
| * --copy: automake Invocation. (line 71) |
| * --diff: aclocal Options. (line 18) |
| * --disable-dependency-tracking: Dependency Tracking. (line 33) |
| * --disable-maintainer-mode: Optional. (line 173) |
| * --disable-silent-rules: Automake Silent Rules. |
| (line 85) |
| * --dry-run: aclocal Options. (line 23) |
| * ‘--enable-debug’, example: Usage of Conditionals. |
| (line 21) |
| * --enable-dependency-tracking: Dependency Tracking. (line 43) |
| * --enable-maintainer-mode: Optional. (line 173) |
| * --enable-silent-rules: Automake Silent Rules. |
| (line 85) |
| * --force: aclocal Options. (line 45) |
| * --force-missing: automake Invocation. (line 76) |
| * --foreign: automake Invocation. (line 82) |
| * --gnits: automake Invocation. (line 86) |
| * ‘--gnits’, complete description: Gnits. (line 29) |
| * --gnu: automake Invocation. (line 90) |
| * ‘--gnu’, complete description: Gnits. (line 6) |
| * ‘--gnu’, required files: Gnits. (line 6) |
| * --help: automake Invocation. (line 94) |
| * --help <1>: aclocal Options. (line 27) |
| * ‘--help’ check: List of Automake options. |
| (line 129) |
| * --help=recursive: Nested Packages. (line 30) |
| * --host=HOST: Cross-Compilation. (line 16) |
| * --include-deps: automake Invocation. (line 102) |
| * --install: aclocal Options. (line 34) |
| * --libdir: automake Invocation. (line 61) |
| * --no-force: automake Invocation. (line 107) |
| * --output: aclocal Options. (line 55) |
| * --output-dir: automake Invocation. (line 114) |
| * --prefix: Standard Directory Variables. |
| (line 33) |
| * --print-ac-dir: aclocal Options. (line 58) |
| * --print-libdir: automake Invocation. (line 65) |
| * --program-prefix=PREFIX: Renaming. (line 16) |
| * --program-suffix=SUFFIX: Renaming. (line 18) |
| * --program-transform-name=PROGRAM: Renaming. (line 20) |
| * --system-acdir: aclocal Options. (line 13) |
| * --target=TARGET: Cross-Compilation. (line 55) |
| * --verbose: automake Invocation. (line 121) |
| * --verbose <1>: aclocal Options. (line 69) |
| * --version: automake Invocation. (line 125) |
| * --version <1>: aclocal Options. (line 72) |
| * ‘--version’ check: List of Automake options. |
| (line 129) |
| * --warnings: automake Invocation. (line 129) |
| * --warnings <1>: aclocal Options. (line 76) |
| * --with-dmalloc: Public Macros. (line 123) |
| * -a: automake Invocation. (line 41) |
| * -c: automake Invocation. (line 70) |
| * -f: automake Invocation. (line 75) |
| * ‘-hook’ targets: Extending. (line 66) |
| * -i: automake Invocation. (line 98) |
| * -I: aclocal Options. (line 30) |
| * ‘-l’ and ‘LDADD’: Linking. (line 70) |
| * ‘-local’ targets: Extending. (line 37) |
| * ‘-module’, libtool: Libtool Modules. (line 6) |
| * -o: automake Invocation. (line 114) |
| * -v: automake Invocation. (line 121) |
| * -W: automake Invocation. (line 129) |
| * -W <1>: aclocal Options. (line 76) |
| * -Wall: amhello's configure.ac Setup Explained. |
| (line 38) |
| * -Werror: amhello's configure.ac Setup Explained. |
| (line 38) |
| * ‘.la’ suffix, defined: Libtool Concept. (line 6) |
| * ‘.log’ files: Parallel Test Harness. |
| (line 12) |
| * ‘.trs’ files: Parallel Test Harness. |
| (line 12) |
| * :copy-in-global-log:: Log files generation and test results recording. |
| (line 44) |
| * :recheck:: Log files generation and test results recording. |
| (line 38) |
| * :test-global-result:: Log files generation and test results recording. |
| (line 54) |
| * ‘:test-result:’: Log files generation and test results recording. |
| (line 24) |
| * ‘_DATA’ primary, defined: Data. (line 6) |
| * ‘_DEPENDENCIES’, defined: Linking. (line 41) |
| * ‘_HEADERS’ primary, defined: Headers. (line 6) |
| * ‘_JAVA’ primary, defined: Java. (line 6) |
| * ‘_LDFLAGS’, defined: Linking. (line 37) |
| * ‘_LDFLAGS’, libtool: Libtool Flags. (line 6) |
| * ‘_LIBADD’, libtool: Libtool Flags. (line 6) |
| * ‘_LIBRARIES’ primary, defined: A Library. (line 6) |
| * ‘_LIBTOOLFLAGS’, libtool: Libtool Flags. (line 6) |
| * ‘_LISP’ primary, defined: Emacs Lisp. (line 6) |
| * ‘_LTLIBRARIES’ primary, defined: Libtool Libraries. (line 6) |
| * ‘_MANS’ primary, defined: Man Pages. (line 6) |
| * ‘_PROGRAMS’ primary variable: Uniform. (line 11) |
| * ‘_PYTHON’ primary, defined: Python. (line 6) |
| * ‘_SCRIPTS’ primary, defined: Scripts. (line 6) |
| * ‘_SOURCES’ and header files: Program Sources. (line 39) |
| * ‘_SOURCES’ primary, defined: Program Sources. (line 32) |
| * ‘_SOURCES’, default: Default _SOURCES. (line 6) |
| * ‘_SOURCES’, empty: Default _SOURCES. (line 44) |
| * ‘_TEXINFOS’ primary, defined: Texinfo. (line 6) |
| * ‘acinclude.m4’, defined: Complete. (line 23) |
| * ‘aclocal’ and serial numbers: Serials. (line 6) |
| * ‘aclocal’ program, introduction: Complete. (line 23) |
| * ‘aclocal’ search path: Macro Search Path. (line 6) |
| * ‘aclocal’’s scheduled death: Future of aclocal. (line 6) |
| * ‘aclocal’, extending: Extending aclocal. (line 6) |
| * ‘aclocal’, Invocation: aclocal Invocation. (line 6) |
| * ‘aclocal’, Invoking: aclocal Invocation. (line 6) |
| * ‘aclocal’, Options: aclocal Options. (line 6) |
| * ‘aclocal’, using: configure. (line 6) |
| * ‘aclocal.m4’, preexisting: Complete. (line 23) |
| * ‘ACLOCAL_PATH’: Macro Search Path. (line 116) |
| * ‘AC_CONFIG_FILES’, conditional: Usage of Conditionals. |
| (line 79) |
| * ‘AC_SUBST’ and ‘SUBDIRS’: Subdirectories with AC_SUBST. |
| (line 6) |
| * Adding new ‘SUFFIXES’: Suffixes. (line 6) |
| * all: Standard Targets. (line 16) |
| * all <1>: Extending. (line 41) |
| * all-local: Extending. (line 41) |
| * ‘ALLOCA’, and Libtool: LTLIBOBJS. (line 6) |
| * ‘ALLOCA’, example: LIBOBJS. (line 6) |
| * ‘ALLOCA’, special handling: LIBOBJS. (line 6) |
| * ‘amhello-1.0.tar.gz’, creation: Hello World. (line 6) |
| * ‘amhello-1.0.tar.gz’, location: Use Cases. (line 6) |
| * ‘amhello-1.0.tar.gz’, use cases: Use Cases. (line 6) |
| * ‘AM_CCASFLAGS’ and ‘CCASFLAGS’: Flag Variables Ordering. |
| (line 20) |
| * ‘AM_CFLAGS’ and ‘CFLAGS’: Flag Variables Ordering. |
| (line 20) |
| * ‘AM_CONDITIONAL’ and ‘SUBDIRS’: Subdirectories with AM_CONDITIONAL. |
| (line 6) |
| * ‘AM_CPPFLAGS’ and ‘CPPFLAGS’: Flag Variables Ordering. |
| (line 20) |
| * ‘AM_CXXFLAGS’ and ‘CXXFLAGS’: Flag Variables Ordering. |
| (line 20) |
| * ‘AM_FCFLAGS’ and ‘FCFLAGS’: Flag Variables Ordering. |
| (line 20) |
| * ‘AM_FFLAGS’ and ‘FFLAGS’: Flag Variables Ordering. |
| (line 20) |
| * ‘AM_GCJFLAGS’ and ‘GCJFLAGS’: Flag Variables Ordering. |
| (line 20) |
| * ‘AM_INIT_AUTOMAKE’, example use: Complete. (line 11) |
| * ‘AM_LDFLAGS’ and ‘LDFLAGS’: Flag Variables Ordering. |
| (line 20) |
| * ‘AM_LFLAGS’ and ‘LFLAGS’: Flag Variables Ordering. |
| (line 20) |
| * ‘AM_LIBTOOLFLAGS’ and ‘LIBTOOLFLAGS’: Flag Variables Ordering. |
| (line 20) |
| * ‘AM_MAINTAINER_MODE’, purpose: maintainer-mode. (line 37) |
| * ‘AM_OBJCFLAGS’ and ‘OBJCFLAGS’: Flag Variables Ordering. |
| (line 20) |
| * ‘AM_OBJCXXFLAGS’ and ‘OBJXXCFLAGS’: Flag Variables Ordering. |
| (line 20) |
| * ‘AM_RFLAGS’ and ‘RFLAGS’: Flag Variables Ordering. |
| (line 20) |
| * ‘AM_UPCFLAGS’ and ‘UPCFLAGS’: Flag Variables Ordering. |
| (line 20) |
| * ‘AM_YFLAGS’ and ‘YFLAGS’: Flag Variables Ordering. |
| (line 20) |
| * Append operator: General Operation. (line 24) |
| * ARG_MAX: Length Limitations. (line 6) |
| * ‘autogen.sh’ and ‘autoreconf’: Error required file ltmain.sh not found. |
| (line 6) |
| * autom4te: aclocal Invocation. (line 44) |
| * Automake constraints: Introduction. (line 21) |
| * ‘automake’ options: automake Invocation. (line 37) |
| * Automake parser, limitations of: General Operation. (line 33) |
| * Automake requirements: Introduction. (line 26) |
| * Automake requirements <1>: Requirements. (line 6) |
| * ‘automake’, invocation: automake Invocation. (line 6) |
| * ‘automake’, invoking: automake Invocation. (line 6) |
| * Automake, recursive operation: General Operation. (line 58) |
| * Automatic dependency tracking: Dependencies. (line 11) |
| * Automatic linker selection: How the Linker is Chosen. |
| (line 6) |
| * ‘autoreconf’ and ‘libtoolize’: Error required file ltmain.sh not found. |
| (line 6) |
| * ‘autoreconf’, example: Creating amhello. (line 59) |
| * ‘autoscan’: amhello's configure.ac Setup Explained. |
| (line 89) |
| * Autotools, introduction: GNU Build System. (line 43) |
| * Autotools, purpose: Why Autotools. (line 6) |
| * autoupdate: Obsolete Macros. (line 6) |
| * Auxiliary programs: Auxiliary Programs. (line 6) |
| * Avoiding man page renaming: Man Pages. (line 54) |
| * Avoiding path stripping: Alternative. (line 23) |
| * Binary package: DESTDIR. (line 22) |
| * ‘bootstrap.sh’ and ‘autoreconf’: Error required file ltmain.sh not found. |
| (line 6) |
| * Bugs, reporting: Introduction. (line 30) |
| * build tree and source tree: VPATH Builds. (line 6) |
| * ‘BUILT_SOURCES’, defined: Sources. (line 27) |
| * C++ support: C++ Support. (line 6) |
| * canonicalizing Automake variables: Canonicalization. (line 6) |
| * ‘CCASFLAGS’ and ‘AM_CCASFLAGS’: Flag Variables Ordering. |
| (line 20) |
| * ‘CFLAGS’ and ‘AM_CFLAGS’: Flag Variables Ordering. |
| (line 20) |
| * cfortran: Mixing Fortran 77 With C and C++. |
| (line 6) |
| * check: Standard Targets. (line 31) |
| * check <1>: Tests. (line 6) |
| * check <2>: Extending. (line 41) |
| * check-local: Extending. (line 41) |
| * check-news: List of Automake options. |
| (line 14) |
| * ‘check_’ primary prefix, definition: Uniform. (line 95) |
| * ‘check_PROGRAMS’ example: Default _SOURCES. (line 28) |
| * clean: Standard Targets. (line 27) |
| * clean <1>: Extending. (line 41) |
| * clean-local: Clean. (line 15) |
| * clean-local <1>: Extending. (line 41) |
| * Colorized testsuite output: Scripts-based Testsuites. |
| (line 67) |
| * command line length limit: Length Limitations. (line 6) |
| * Comment, special to Automake: General Operation. (line 68) |
| * Compilation of Java to bytecode: Java. (line 6) |
| * Compilation of Java to native code: Java Support with gcj. |
| (line 6) |
| * Compile Flag Variables: Flag Variables Ordering. |
| (line 20) |
| * Complete example: Complete. (line 6) |
| * Conditional example, ‘--enable-debug’: Usage of Conditionals. |
| (line 21) |
| * conditional libtool libraries: Conditional Libtool Libraries. |
| (line 6) |
| * Conditional programs: Conditional Programs. |
| (line 6) |
| * Conditional subdirectories: Conditional Subdirectories. |
| (line 6) |
| * Conditional ‘SUBDIRS’: Conditional Subdirectories. |
| (line 6) |
| * Conditionals: Conditionals. (line 6) |
| * ‘config.guess’: automake Invocation. (line 39) |
| * ‘config.site’ example: config.site. (line 6) |
| * configuration variables, overriding: Standard Configuration Variables. |
| (line 6) |
| * Configuration, basics: Basic Installation. (line 6) |
| * Configure substitutions in ‘TESTS’: Parallel Test Harness. |
| (line 46) |
| * ‘configure.ac’, Hello World: amhello's configure.ac Setup Explained. |
| (line 6) |
| * ‘configure.ac’, scanning: configure. (line 6) |
| * conflicting definitions: Extending. (line 14) |
| * Constraints of Automake: Introduction. (line 21) |
| * convenience libraries, libtool: Libtool Convenience Libraries. |
| (line 6) |
| * copying semantics: Extending. (line 10) |
| * ‘cpio’ example: Uniform. (line 36) |
| * ‘CPPFLAGS’ and ‘AM_CPPFLAGS’: Flag Variables Ordering. |
| (line 20) |
| * cross-compilation: Cross-Compilation. (line 6) |
| * cross-compilation example: Cross-Compilation. (line 25) |
| * CVS and generated files: CVS. (line 49) |
| * CVS and third-party files: CVS. (line 167) |
| * CVS and timestamps: CVS. (line 28) |
| * ‘CXXFLAGS’ and ‘AM_CXXFLAGS’: Flag Variables Ordering. |
| (line 20) |
| * ‘DATA’ primary, defined: Data. (line 6) |
| * debug build, example: VPATH Builds. (line 46) |
| * debugging rules: Debugging Make Rules. |
| (line 6) |
| * default source, Libtool modules example: Default _SOURCES. (line 38) |
| * default verbosity for silent rules: Automake Silent Rules. |
| (line 92) |
| * default ‘_SOURCES’: Default _SOURCES. (line 6) |
| * definitions, conflicts: Extending. (line 14) |
| * dejagnu: DejaGnu Tests. (line 19) |
| * dejagnu <1>: List of Automake options. |
| (line 18) |
| * ‘depcomp’: Dependencies. (line 22) |
| * dependencies and distributed files: Errors with distclean. |
| (line 6) |
| * Dependency tracking: Dependency Tracking. (line 6) |
| * Dependency tracking <1>: Dependencies. (line 11) |
| * Dependency tracking, disabling: Dependencies. (line 36) |
| * directory variables: Standard Directory Variables. |
| (line 6) |
| * ‘dirlist’: Macro Search Path. (line 52) |
| * Disabling dependency tracking: Dependencies. (line 37) |
| * Disabling hard errors: Scripts-based Testsuites. |
| (line 32) |
| * dist: Standard Targets. (line 35) |
| * dist <1>: Basics of Distribution. |
| (line 6) |
| * dist-bzip2: The Types of Distributions. |
| (line 18) |
| * dist-bzip2 <1>: List of Automake options. |
| (line 22) |
| * dist-bzip2 <2>: List of Automake options. |
| (line 22) |
| * dist-gzip: The Types of Distributions. |
| (line 11) |
| * dist-hook: The dist Hook. (line 6) |
| * dist-hook <1>: Extending. (line 66) |
| * dist-lzip: The Types of Distributions. |
| (line 22) |
| * dist-lzip <1>: List of Automake options. |
| (line 25) |
| * dist-lzip <2>: List of Automake options. |
| (line 25) |
| * dist-shar: The Types of Distributions. |
| (line 45) |
| * dist-shar <1>: List of Automake options. |
| (line 36) |
| * dist-shar <2>: List of Automake options. |
| (line 34) |
| * dist-tarZ: The Types of Distributions. |
| (line 39) |
| * dist-tarZ <1>: List of Automake options. |
| (line 41) |
| * dist-tarZ <2>: List of Automake options. |
| (line 39) |
| * dist-xz: The Types of Distributions. |
| (line 30) |
| * dist-xz <1>: List of Automake options. |
| (line 28) |
| * dist-xz <2>: List of Automake options. |
| (line 28) |
| * dist-zip: The Types of Distributions. |
| (line 33) |
| * dist-zip <1>: List of Automake options. |
| (line 31) |
| * dist-zip <2>: List of Automake options. |
| (line 31) |
| * distcheck: Creating amhello. (line 100) |
| * distcheck <1>: Checking the Distribution. |
| (line 6) |
| * ‘distcheck’ better than ‘dist’: Preparing Distributions. |
| (line 10) |
| * ‘distcheck’ example: Creating amhello. (line 100) |
| * distcheck-hook: Checking the Distribution. |
| (line 55) |
| * distclean: Standard Targets. (line 29) |
| * distclean <1>: Extending. (line 41) |
| * distclean <2>: Errors with distclean. |
| (line 6) |
| * ‘distclean’, diagnostic: Errors with distclean. |
| (line 6) |
| * distclean-local: Clean. (line 15) |
| * distclean-local <1>: Extending. (line 41) |
| * distcleancheck: Checking the Distribution. |
| (line 70) |
| * distdir: Third-Party Makefiles. |
| (line 25) |
| * Distinction between errors and failures in testsuites: Generalities about Testing. |
| (line 48) |
| * Distributions, preparation: Preparing Distributions. |
| (line 6) |
| * distuninstallcheck: Checking the Distribution. |
| (line 106) |
| * ‘dist_’ and ‘nobase_’: Alternative. (line 29) |
| * ‘dist_’ and ‘notrans_’: Man Pages. (line 63) |
| * ‘DIST_SUBDIRS’, explained: SUBDIRS vs DIST_SUBDIRS. |
| (line 6) |
| * ‘dmalloc’, support for: Public Macros. (line 123) |
| * dvi: Texinfo. (line 25) |
| * dvi <1>: Extending. (line 41) |
| * DVI output using Texinfo: Texinfo. (line 6) |
| * dvi-local: Extending. (line 41) |
| * E-mail, bug reports: Introduction. (line 30) |
| * ‘EDITION’ Texinfo flag: Texinfo. (line 35) |
| * else: Usage of Conditionals. |
| (line 36) |
| * Empty libraries: A Library. (line 48) |
| * Empty libraries and ‘$(LIBOBJS)’: LIBOBJS. (line 72) |
| * empty ‘_SOURCES’: Default _SOURCES. (line 44) |
| * endif: Usage of Conditionals. |
| (line 36) |
| * Example conditional ‘--enable-debug’: Usage of Conditionals. |
| (line 21) |
| * Example conditional ‘AC_CONFIG_FILES’: Usage of Conditionals. |
| (line 79) |
| * Example Hello World: Hello World. (line 6) |
| * Example of recursive operation: General Operation. (line 58) |
| * Example of shared libraries: Libtool Libraries. (line 6) |
| * Example, ‘EXTRA_PROGRAMS’: Uniform. (line 36) |
| * Example, ‘false’ and ‘true’: true. (line 6) |
| * Example, mixed language: Mixing Fortran 77 With C and C++. |
| (line 34) |
| * Executable extension: EXEEXT. (line 6) |
| * Exit status 77, special interpretation: Scripts-based Testsuites. |
| (line 27) |
| * Exit status 99, special interpretation: Scripts-based Testsuites. |
| (line 27) |
| * expected failure: Generalities about Testing. |
| (line 39) |
| * expected test failure: Generalities about Testing. |
| (line 39) |
| * Expected test failure: Scripts-based Testsuites. |
| (line 32) |
| * Extending ‘aclocal’: Extending aclocal. (line 6) |
| * Extending list of installation directories: Uniform. (line 56) |
| * Extension, executable: EXEEXT. (line 6) |
| * Extra files distributed with Automake: automake Invocation. (line 39) |
| * ‘EXTRA_’, prepending: Uniform. (line 29) |
| * ‘EXTRA_PROGRAMS’, defined: Uniform. (line 36) |
| * ‘EXTRA_PROGRAMS’, defined <1>: Conditional Programs. |
| (line 15) |
| * ‘EXTRA_prog_SOURCES’, defined: Conditional Sources. (line 18) |
| * ‘false’ Example: true. (line 6) |
| * ‘FCFLAGS’ and ‘AM_FCFLAGS’: Flag Variables Ordering. |
| (line 20) |
| * Features of the GNU Build System: Use Cases. (line 6) |
| * ‘FFLAGS’ and ‘AM_FFLAGS’: Flag Variables Ordering. |
| (line 20) |
| * file names, limitations on: Limitations on File Names. |
| (line 6) |
| * filename-length-max=99: List of Automake options. |
| (line 44) |
| * Files distributed with Automake: automake Invocation. (line 39) |
| * First line of Makefile.am: General Operation. (line 74) |
| * Flag variables, ordering: Flag Variables Ordering. |
| (line 6) |
| * Flag Variables, Ordering: Flag Variables Ordering. |
| (line 20) |
| * ‘FLIBS’, defined: Mixing Fortran 77 With C and C++. |
| (line 21) |
| * foreign: amhello's configure.ac Setup Explained. |
| (line 38) |
| * foreign <1>: List of Automake options. |
| (line 9) |
| * ‘foreign’ strictness: Strictness. (line 10) |
| * Fortran 77 support: Fortran 77 Support. (line 6) |
| * Fortran 77, mixing with C and C++: Mixing Fortran 77 With C and C++. |
| (line 6) |
| * Fortran 77, Preprocessing: Preprocessing Fortran 77. |
| (line 6) |
| * Fortran 9x support: Fortran 9x Support. (line 6) |
| * ‘GCJFLAGS’ and ‘AM_GCJFLAGS’: Flag Variables Ordering. |
| (line 20) |
| * generated files and CVS: CVS. (line 49) |
| * generated files, distributed: CVS. (line 9) |
| * Gettext support: gettext. (line 6) |
| * git-dist: General Operation. (line 12) |
| * ‘git-dist’, non-standard example: General Operation. (line 12) |
| * gnits: List of Automake options. |
| (line 9) |
| * ‘gnits’ strictness: Strictness. (line 10) |
| * gnu: List of Automake options. |
| (line 9) |
| * GNU Build System, basics: Basic Installation. (line 6) |
| * GNU Build System, features: Use Cases. (line 6) |
| * GNU Build System, introduction: GNU Build System. (line 6) |
| * GNU Build System, use cases: Use Cases. (line 6) |
| * GNU Coding Standards: GNU Build System. (line 29) |
| * GNU Gettext support: gettext. (line 6) |
| * GNU make extensions: General Operation. (line 20) |
| * GNU Makefile standards: Introduction. (line 12) |
| * ‘gnu’ strictness: Strictness. (line 10) |
| * ‘GNUmakefile’ including ‘Makefile’: Third-Party Makefiles. |
| (line 111) |
| * hard error: Generalities about Testing. |
| (line 48) |
| * Header files in ‘_SOURCES’: Program Sources. (line 39) |
| * ‘HEADERS’ primary, defined: Headers. (line 6) |
| * ‘HEADERS’, installation directories: Headers. (line 6) |
| * Hello World example: Hello World. (line 6) |
| * hook targets: Extending. (line 66) |
| * HP-UX 10, ‘lex’ problems: Public Macros. (line 95) |
| * html: Texinfo. (line 25) |
| * html <1>: Extending. (line 41) |
| * HTML output using Texinfo: Texinfo. (line 6) |
| * html-local: Extending. (line 41) |
| * id: Tags. (line 43) |
| * if: Usage of Conditionals. |
| (line 36) |
| * include: Basics of Distribution. |
| (line 17) |
| * include <1>: Include. (line 6) |
| * ‘include’, distribution: Basics of Distribution. |
| (line 17) |
| * Including ‘Makefile’ fragment: Include. (line 6) |
| * indentation in Makefile.am: General Operation. (line 33) |
| * info: List of Automake options. |
| (line 93) |
| * info <1>: Extending. (line 41) |
| * info-in-builddir: List of Automake options. |
| (line 53) |
| * info-local: Extending. (line 41) |
| * install: Standard Targets. (line 18) |
| * install <1>: The Two Parts of Install. |
| (line 14) |
| * install <2>: Extending. (line 41) |
| * Install hook: Extending Installation. |
| (line 15) |
| * Install, two parts of: The Two Parts of Install. |
| (line 14) |
| * install-data: Two-Part Install. (line 16) |
| * install-data <1>: The Two Parts of Install. |
| (line 14) |
| * install-data <2>: Extending. (line 41) |
| * install-data-hook: Extending. (line 66) |
| * install-data-local: Extending Installation. |
| (line 9) |
| * install-data-local <1>: Extending. (line 41) |
| * install-dvi: Texinfo. (line 25) |
| * install-dvi <1>: Extending. (line 41) |
| * install-dvi-local: Extending. (line 41) |
| * install-exec: Two-Part Install. (line 16) |
| * install-exec <1>: The Two Parts of Install. |
| (line 14) |
| * install-exec <2>: Extending. (line 41) |
| * install-exec-hook: Extending. (line 66) |
| * install-exec-local: Extending Installation. |
| (line 9) |
| * install-exec-local <1>: Extending. (line 41) |
| * install-html: Texinfo. (line 25) |
| * install-html <1>: Extending. (line 41) |
| * install-html-local: Extending. (line 41) |
| * install-info: Texinfo. (line 85) |
| * install-info <1>: List of Automake options. |
| (line 93) |
| * install-info <2>: Extending. (line 41) |
| * ‘install-info’ target: Texinfo. (line 85) |
| * install-info-local: Extending. (line 41) |
| * install-man: Man Pages. (line 32) |
| * install-man <1>: List of Automake options. |
| (line 99) |
| * ‘install-man’ target: Man Pages. (line 32) |
| * install-pdf: Texinfo. (line 25) |
| * install-pdf <1>: Extending. (line 41) |
| * install-pdf-local: Extending. (line 41) |
| * install-ps: Texinfo. (line 25) |
| * install-ps <1>: Extending. (line 41) |
| * install-ps-local: Extending. (line 41) |
| * install-strip: Standard Targets. (line 21) |
| * install-strip <1>: Install Rules for the User. |
| (line 7) |
| * Installation directories, extending list: Uniform. (line 56) |
| * Installation support: Install. (line 6) |
| * Installation, basics: Basic Installation. (line 6) |
| * installcheck: Standard Targets. (line 33) |
| * installcheck <1>: Extending. (line 41) |
| * installcheck-local: Extending. (line 41) |
| * installdirs: Install Rules for the User. |
| (line 7) |
| * installdirs <1>: Extending. (line 41) |
| * installdirs-local: Extending. (line 41) |
| * Installing headers: Headers. (line 6) |
| * Installing scripts: Scripts. (line 6) |
| * installing versioned binaries: Extending. (line 86) |
| * Interfacing with third-party packages: Third-Party Makefiles. |
| (line 6) |
| * Invocation of ‘aclocal’: aclocal Invocation. (line 6) |
| * Invocation of ‘automake’: automake Invocation. (line 6) |
| * Invoking ‘aclocal’: aclocal Invocation. (line 6) |
| * Invoking ‘automake’: automake Invocation. (line 6) |
| * ‘JAVA’ primary, defined: Java. (line 6) |
| * ‘JAVA’ restrictions: Java. (line 27) |
| * Java support with gcj: Java Support with gcj. |
| (line 6) |
| * Java to bytecode, compilation: Java. (line 6) |
| * Java to native code, compilation: Java Support with gcj. |
| (line 6) |
| * lazy test execution: Parallel Test Harness. |
| (line 118) |
| * ‘LDADD’ and ‘-l’: Linking. (line 70) |
| * ‘LDFLAGS’ and ‘AM_LDFLAGS’: Flag Variables Ordering. |
| (line 20) |
| * ‘lex’ problems with HP-UX 10: Public Macros. (line 95) |
| * ‘lex’, multiple lexers: Yacc and Lex. (line 68) |
| * ‘LFLAGS’ and ‘AM_LFLAGS’: Flag Variables Ordering. |
| (line 20) |
| * ‘libltdl’, introduction: Libtool Concept. (line 29) |
| * ‘LIBOBJS’, and Libtool: LTLIBOBJS. (line 6) |
| * ‘LIBOBJS’, example: LIBOBJS. (line 6) |
| * ‘LIBOBJS’, special handling: LIBOBJS. (line 6) |
| * ‘LIBRARIES’ primary, defined: A Library. (line 6) |
| * libtool convenience libraries: Libtool Convenience Libraries. |
| (line 6) |
| * libtool libraries, conditional: Conditional Libtool Libraries. |
| (line 6) |
| * libtool library, definition: Libtool Concept. (line 6) |
| * libtool modules: Libtool Modules. (line 6) |
| * Libtool modules, default source example: Default _SOURCES. (line 38) |
| * ‘libtool’, introduction: Libtool Concept. (line 6) |
| * ‘LIBTOOLFLAGS’ and ‘AM_LIBTOOLFLAGS’: Flag Variables Ordering. |
| (line 20) |
| * ‘libtoolize’ and ‘autoreconf’: Error required file ltmain.sh not found. |
| (line 6) |
| * ‘libtoolize’, no longer run by ‘automake’: Error required file ltmain.sh not found. |
| (line 6) |
| * Limitations of automake parser: General Operation. (line 33) |
| * Linking Fortran 77 with C and C++: Mixing Fortran 77 With C and C++. |
| (line 6) |
| * ‘LISP’ primary, defined: Emacs Lisp. (line 6) |
| * ‘LN_S’ example: Extending. (line 86) |
| * local targets: Extending. (line 37) |
| * ‘LTALLOCA’, special handling: LTLIBOBJS. (line 6) |
| * ‘LTLIBOBJS’, special handling: LTLIBOBJS. (line 6) |
| * ‘LTLIBRARIES’ primary, defined: Libtool Libraries. (line 6) |
| * ‘ltmain.sh’ not found: Error required file ltmain.sh not found. |
| (line 6) |
| * ‘m4_include’, distribution: Basics of Distribution. |
| (line 17) |
| * Macro search path: Macro Search Path. (line 6) |
| * macro serial numbers: Serials. (line 6) |
| * Macros Automake recognizes: Optional. (line 6) |
| * maintainer-clean-local: Clean. (line 15) |
| * ‘make check’: Tests. (line 6) |
| * ‘make clean’ support: Clean. (line 6) |
| * ‘make dist’: Basics of Distribution. |
| (line 6) |
| * ‘make distcheck’: Checking the Distribution. |
| (line 6) |
| * ‘make distclean’, diagnostic: Errors with distclean. |
| (line 6) |
| * ‘make distcleancheck’: Checking the Distribution. |
| (line 70) |
| * ‘make distuninstallcheck’: Checking the Distribution. |
| (line 106) |
| * ‘make install’ support: Install. (line 6) |
| * ‘make installcheck’, testing ‘--help’ and ‘--version’: List of Automake options. |
| (line 129) |
| * Make rules, overriding: General Operation. (line 46) |
| * Make targets, overriding: General Operation. (line 46) |
| * ‘Makefile’ fragment, including: Include. (line 6) |
| * Makefile.am, first line: General Operation. (line 74) |
| * ‘Makefile.am’, Hello World: amhello's Makefile.am Setup Explained. |
| (line 6) |
| * Man page renaming, avoiding: Man Pages. (line 54) |
| * ‘MANS’ primary, defined: Man Pages. (line 6) |
| * many outputs, rules with: Multiple Outputs. (line 6) |
| * ‘mdate-sh’: Texinfo. (line 35) |
| * MinGW cross-compilation example: Cross-Compilation. (line 25) |
| * ‘missing’, purpose: maintainer-mode. (line 9) |
| * Mixed language example: Mixing Fortran 77 With C and C++. |
| (line 34) |
| * Mixing Fortran 77 with C and C++: Mixing Fortran 77 With C and C++. |
| (line 6) |
| * Mixing Fortran 77 with C and/or C++: Mixing Fortran 77 With C and C++. |
| (line 6) |
| * ‘mkdir -p’, macro check: Obsolete Macros. (line 14) |
| * modules, libtool: Libtool Modules. (line 6) |
| * mostlyclean: Extending. (line 41) |
| * mostlyclean-local: Clean. (line 15) |
| * mostlyclean-local <1>: Extending. (line 41) |
| * multiple configurations, example: VPATH Builds. (line 46) |
| * Multiple ‘configure.ac’ files: automake Invocation. (line 6) |
| * Multiple ‘lex’ lexers: Yacc and Lex. (line 68) |
| * multiple outputs, rules with: Multiple Outputs. (line 6) |
| * Multiple ‘yacc’ parsers: Yacc and Lex. (line 68) |
| * Nested packages: Nested Packages. (line 6) |
| * Nesting packages: Subpackages. (line 6) |
| * no-define: Public Macros. (line 55) |
| * no-define <1>: List of Automake options. |
| (line 58) |
| * no-dependencies: Dependencies. (line 34) |
| * no-dependencies <1>: List of Automake options. |
| (line 66) |
| * no-dist: List of Automake options. |
| (line 73) |
| * no-dist-gzip: List of Automake options. |
| (line 77) |
| * no-dist-gzip <1>: List of Automake options. |
| (line 77) |
| * no-exeext: List of Automake options. |
| (line 80) |
| * no-installinfo: Texinfo. (line 85) |
| * no-installinfo <1>: List of Automake options. |
| (line 90) |
| * ‘no-installinfo’ option: Texinfo. (line 85) |
| * no-installman: Man Pages. (line 32) |
| * no-installman <1>: List of Automake options. |
| (line 96) |
| * ‘no-installman’ option: Man Pages. (line 32) |
| * no-texinfo.tex: List of Automake options. |
| (line 106) |
| * ‘nobase_’ and ‘dist_’ or ‘nodist_’: Alternative. (line 29) |
| * ‘nobase_’ prefix: Alternative. (line 23) |
| * ‘nodist_’ and ‘nobase_’: Alternative. (line 29) |
| * ‘nodist_’ and ‘notrans_’: Man Pages. (line 63) |
| * ‘noinst_’ primary prefix, definition: Uniform. (line 90) |
| * Non-GNU packages: Strictness. (line 6) |
| * Non-standard targets: General Operation. (line 12) |
| * nostdinc: List of Automake options. |
| (line 102) |
| * ‘notrans_’ and ‘dist_’ or ‘nodist_’: Man Pages. (line 63) |
| * ‘notrans_’ prefix: Man Pages. (line 54) |
| * ‘OBJCFLAGS’ and ‘AM_OBJCFLAGS’: Flag Variables Ordering. |
| (line 20) |
| * ‘OBJCXXFLAGS’ and ‘AM_OBJCXXFLAGS’: Flag Variables Ordering. |
| (line 20) |
| * Objective C support: Objective C Support. (line 6) |
| * Objective C++ support: Objective C++ Support. |
| (line 6) |
| * Objects in subdirectory: Program and Library Variables. |
| (line 51) |
| * obsolete macros: Obsolete Macros. (line 6) |
| * optimized build, example: VPATH Builds. (line 46) |
| * Option, ‘--warnings=CATEGORY’: List of Automake options. |
| (line 211) |
| * Option, ‘-WCATEGORY’: List of Automake options. |
| (line 211) |
| * Option, ‘check-news’: List of Automake options. |
| (line 14) |
| * Option, ‘dejagnu’: List of Automake options. |
| (line 18) |
| * Option, ‘dist-bzip2’: List of Automake options. |
| (line 22) |
| * Option, ‘dist-lzip’: List of Automake options. |
| (line 25) |
| * Option, ‘dist-shar’: List of Automake options. |
| (line 34) |
| * Option, ‘dist-tarZ’: List of Automake options. |
| (line 39) |
| * Option, ‘dist-xz’: List of Automake options. |
| (line 28) |
| * Option, ‘dist-zip’: List of Automake options. |
| (line 31) |
| * Option, ‘filename-length-max=99’: List of Automake options. |
| (line 44) |
| * Option, ‘foreign’: List of Automake options. |
| (line 9) |
| * Option, ‘gnits’: List of Automake options. |
| (line 9) |
| * Option, ‘gnu’: List of Automake options. |
| (line 9) |
| * Option, ‘info-in-builddir’: List of Automake options. |
| (line 53) |
| * Option, ‘no-define’: List of Automake options. |
| (line 58) |
| * Option, ‘no-dependencies’: List of Automake options. |
| (line 66) |
| * Option, ‘no-dist’: List of Automake options. |
| (line 73) |
| * Option, ‘no-dist-gzip’: List of Automake options. |
| (line 77) |
| * Option, ‘no-exeext’: List of Automake options. |
| (line 80) |
| * Option, ‘no-installinfo’: Texinfo. (line 85) |
| * Option, ‘no-installinfo’ <1>: List of Automake options. |
| (line 90) |
| * Option, ‘no-installman’: Man Pages. (line 32) |
| * Option, ‘no-installman’ <1>: List of Automake options. |
| (line 96) |
| * Option, ‘no-texinfo.tex’: List of Automake options. |
| (line 106) |
| * Option, ‘nostdinc’: List of Automake options. |
| (line 102) |
| * Option, ‘parallel-tests’: List of Automake options. |
| (line 114) |
| * Option, ‘readme-alpha’: List of Automake options. |
| (line 120) |
| * Option, ‘serial-tests’: List of Automake options. |
| (line 110) |
| * Option, ‘tar-pax’: List of Automake options. |
| (line 159) |
| * Option, ‘tar-ustar’: List of Automake options. |
| (line 159) |
| * Option, ‘tar-v7’: List of Automake options. |
| (line 159) |
| * Option, VERSION: List of Automake options. |
| (line 206) |
| * Option, warnings: List of Automake options. |
| (line 211) |
| * Options, ‘aclocal’: aclocal Options. (line 6) |
| * Options, ‘automake’: automake Invocation. (line 37) |
| * Options, ‘std-options’: List of Automake options. |
| (line 129) |
| * Options, ‘subdir-objects’: List of Automake options. |
| (line 150) |
| * Ordering flag variables: Flag Variables Ordering. |
| (line 6) |
| * Overriding make rules: General Operation. (line 46) |
| * Overriding make targets: General Operation. (line 46) |
| * Overriding make variables: General Operation. (line 51) |
| * overriding rules: Extending. (line 26) |
| * overriding semantics: Extending. (line 26) |
| * ‘PACKAGE’, directory: Uniform. (line 19) |
| * ‘PACKAGE’, prevent definition: Public Macros. (line 55) |
| * Packages, nested: Nested Packages. (line 6) |
| * Packages, preparation: Preparing Distributions. |
| (line 6) |
| * Parallel build trees: VPATH Builds. (line 6) |
| * parallel-tests: List of Automake options. |
| (line 114) |
| * Path stripping, avoiding: Alternative. (line 23) |
| * pax format: List of Automake options. |
| (line 159) |
| * pdf: Texinfo. (line 25) |
| * pdf <1>: Extending. (line 41) |
| * PDF output using Texinfo: Texinfo. (line 6) |
| * pdf-local: Extending. (line 41) |
| * Per-object flags, emulated: Per-Object Flags. (line 6) |
| * per-target compilation flags, defined: Program and Library Variables. |
| (line 182) |
| * ‘pkgdatadir’, defined: Uniform. (line 19) |
| * ‘pkgincludedir’, defined: Uniform. (line 19) |
| * ‘pkglibdir’, defined: Uniform. (line 19) |
| * ‘pkglibexecdir’, defined: Uniform. (line 19) |
| * Preparing distributions: Preparing Distributions. |
| (line 6) |
| * Preprocessing Fortran 77: Preprocessing Fortran 77. |
| (line 6) |
| * Primary variable, ‘DATA’: Data. (line 6) |
| * Primary variable, defined: Uniform. (line 11) |
| * Primary variable, ‘HEADERS’: Headers. (line 6) |
| * Primary variable, ‘JAVA’: Java. (line 6) |
| * Primary variable, ‘LIBRARIES’: A Library. (line 6) |
| * Primary variable, ‘LISP’: Emacs Lisp. (line 6) |
| * Primary variable, ‘LTLIBRARIES’: Libtool Libraries. (line 6) |
| * Primary variable, ‘MANS’: Man Pages. (line 6) |
| * Primary variable, ‘PROGRAMS’: Uniform. (line 11) |
| * Primary variable, ‘PYTHON’: Python. (line 6) |
| * Primary variable, ‘SCRIPTS’: Scripts. (line 6) |
| * Primary variable, ‘SOURCES’: Program Sources. (line 32) |
| * Primary variable, ‘TEXINFOS’: Texinfo. (line 6) |
| * ‘PROGRAMS’ primary variable: Uniform. (line 11) |
| * Programs, auxiliary: Auxiliary Programs. (line 6) |
| * ‘PROGRAMS’, ‘bindir’: Program Sources. (line 6) |
| * Programs, conditional: Conditional Programs. |
| (line 6) |
| * Programs, renaming during installation: Renaming. (line 6) |
| * ‘prog_LDADD’, defined: Linking. (line 12) |
| * Proxy ‘Makefile’ for third-party packages: Third-Party Makefiles. |
| (line 128) |
| * ps: Texinfo. (line 25) |
| * ps <1>: Extending. (line 41) |
| * PS output using Texinfo: Texinfo. (line 6) |
| * ps-local: Extending. (line 41) |
| * ‘PYTHON’ primary, defined: Python. (line 6) |
| * Ratfor programs: Preprocessing Fortran 77. |
| (line 6) |
| * read-only source tree: VPATH Builds. (line 89) |
| * readme-alpha: List of Automake options. |
| (line 120) |
| * ‘README-alpha’: Gnits. (line 42) |
| * rebuild rules: Rebuilding. (line 6) |
| * rebuild rules <1>: CVS. (line 9) |
| * recheck: Parallel Test Harness. |
| (line 130) |
| * Recognized macros by Automake: Optional. (line 6) |
| * Recursive operation of Automake: General Operation. (line 58) |
| * recursive targets and third-party ‘Makefile’s: Third-Party Makefiles. |
| (line 15) |
| * Register test case result: Log files generation and test results recording. |
| (line 24) |
| * Register test result: Log files generation and test results recording. |
| (line 24) |
| * Renaming programs: Renaming. (line 6) |
| * Reporting bugs: Introduction. (line 30) |
| * Requirements of Automake: Requirements. (line 6) |
| * Requirements, Automake: Introduction. (line 26) |
| * Restrictions for ‘JAVA’: Java. (line 27) |
| * reStructuredText field, ‘:copy-in-global-log:’: Log files generation and test results recording. |
| (line 44) |
| * reStructuredText field, ‘:recheck:’: Log files generation and test results recording. |
| (line 38) |
| * reStructuredText field, ‘:test-global-result:’: Log files generation and test results recording. |
| (line 54) |
| * reStructuredText field, ‘:test-result:’: Log files generation and test results recording. |
| (line 24) |
| * ‘RFLAGS’ and ‘AM_RFLAGS’: Flag Variables Ordering. |
| (line 20) |
| * rules with multiple outputs: Multiple Outputs. (line 6) |
| * rules, conflicting: Extending. (line 14) |
| * rules, debugging: Debugging Make Rules. |
| (line 6) |
| * rules, overriding: Extending. (line 26) |
| * Scanning ‘configure.ac’: configure. (line 6) |
| * ‘SCRIPTS’ primary, defined: Scripts. (line 6) |
| * ‘SCRIPTS’, installation directories: Scripts. (line 18) |
| * Selecting the linker automatically: How the Linker is Chosen. |
| (line 6) |
| * serial number and ‘--install’: aclocal Options. (line 38) |
| * serial numbers in macros: Serials. (line 6) |
| * serial-tests: List of Automake options. |
| (line 110) |
| * ‘serial-tests’, Using: Serial Test Harness. (line 6) |
| * Shared libraries, support for: A Shared Library. (line 6) |
| * Silencing ‘make’: Silencing Make. (line 6) |
| * Silent ‘make’: Silencing Make. (line 6) |
| * Silent ‘make’ rules: Silencing Make. (line 6) |
| * Silent rules: Silencing Make. (line 6) |
| * silent rules and libtool: Automake Silent Rules. |
| (line 59) |
| * ‘site.exp’: DejaGnu Tests. (line 26) |
| * source tree and build tree: VPATH Builds. (line 6) |
| * source tree, read-only: VPATH Builds. (line 89) |
| * ‘SOURCES’ primary, defined: Program Sources. (line 32) |
| * Special Automake comment: General Operation. (line 68) |
| * Staged installation: DESTDIR. (line 14) |
| * std-options: List of Automake options. |
| (line 129) |
| * Strictness, command line: automake Invocation. (line 37) |
| * Strictness, defined: Strictness. (line 10) |
| * Strictness, ‘foreign’: Strictness. (line 10) |
| * Strictness, ‘gnits’: Strictness. (line 10) |
| * Strictness, ‘gnu’: Strictness. (line 10) |
| * su, before ‘make install’: Basic Installation. (line 49) |
| * subdir-objects: List of Automake options. |
| (line 150) |
| * Subdirectories, building conditionally: Conditional Subdirectories. |
| (line 6) |
| * Subdirectories, configured conditionally: Unconfigured Subdirectories. |
| (line 6) |
| * Subdirectories, not distributed: Unconfigured Subdirectories. |
| (line 55) |
| * Subdirectory, objects in: Program and Library Variables. |
| (line 51) |
| * ‘SUBDIRS’ and ‘AC_SUBST’: Subdirectories with AC_SUBST. |
| (line 6) |
| * ‘SUBDIRS’ and ‘AM_CONDITIONAL’: Subdirectories with AM_CONDITIONAL. |
| (line 6) |
| * ‘SUBDIRS’, conditional: Conditional Subdirectories. |
| (line 6) |
| * ‘SUBDIRS’, explained: Subdirectories. (line 6) |
| * Subpackages: Nested Packages. (line 6) |
| * Subpackages <1>: Subpackages. (line 6) |
| * suffix ‘.la’, defined: Libtool Concept. (line 6) |
| * suffix ‘.lo’, defined: Libtool Concept. (line 15) |
| * ‘SUFFIXES’, adding: Suffixes. (line 6) |
| * Support for C++: C++ Support. (line 6) |
| * Support for Fortran 77: Fortran 77 Support. (line 6) |
| * Support for Fortran 9x: Fortran 9x Support. (line 6) |
| * Support for GNU Gettext: gettext. (line 6) |
| * Support for Java with gcj: Java Support with gcj. |
| (line 6) |
| * Support for Objective C: Objective C Support. (line 6) |
| * Support for Objective C++: Objective C++ Support. |
| (line 6) |
| * Support for Unified Parallel C: Unified Parallel C Support. |
| (line 6) |
| * Support for Vala: Vala Support. (line 6) |
| * tags: Tags. (line 9) |
| * ‘TAGS’ support: Tags. (line 6) |
| * ‘tar’ formats: List of Automake options. |
| (line 159) |
| * tar-pax: List of Automake options. |
| (line 159) |
| * tar-ustar: List of Automake options. |
| (line 159) |
| * tar-v7: List of Automake options. |
| (line 159) |
| * Target, ‘install-info’: Texinfo. (line 85) |
| * Target, ‘install-man’: Man Pages. (line 32) |
| * test case: Generalities about Testing. |
| (line 11) |
| * Test case result, registering: Log files generation and test results recording. |
| (line 24) |
| * test failure: Generalities about Testing. |
| (line 25) |
| * test harness: Generalities about Testing. |
| (line 18) |
| * test metadata: Parallel Test Harness. |
| (line 12) |
| * test pass: Generalities about Testing. |
| (line 25) |
| * Test result, registering: Log files generation and test results recording. |
| (line 24) |
| * test skip: Generalities about Testing. |
| (line 29) |
| * Test suites: Tests. (line 6) |
| * Tests, expected failure: Scripts-based Testsuites. |
| (line 32) |
| * testsuite harness: Generalities about Testing. |
| (line 18) |
| * Testsuite progress on console: Scripts-based Testsuites. |
| (line 45) |
| * Texinfo flag, ‘EDITION’: Texinfo. (line 35) |
| * Texinfo flag, ‘UPDATED’: Texinfo. (line 35) |
| * Texinfo flag, ‘UPDATED-MONTH’: Texinfo. (line 35) |
| * Texinfo flag, ‘VERSION’: Texinfo. (line 35) |
| * ‘texinfo.tex’: Texinfo. (line 70) |
| * ‘TEXINFOS’ primary, defined: Texinfo. (line 6) |
| * third-party files and CVS: CVS. (line 167) |
| * Third-party packages, interfacing with: Third-Party Makefiles. |
| (line 6) |
| * timestamps and CVS: CVS. (line 28) |
| * Transforming program names: Renaming. (line 6) |
| * trees, source vs. build: VPATH Builds. (line 6) |
| * ‘true’ Example: true. (line 6) |
| * underquoted ‘AC_DEFUN’: Extending aclocal. (line 36) |
| * unexpected pass: Generalities about Testing. |
| (line 39) |
| * unexpected test pass: Generalities about Testing. |
| (line 39) |
| * Unified Parallel C support: Unified Parallel C Support. |
| (line 6) |
| * Uniform naming scheme: Uniform. (line 6) |
| * uninstall: Standard Targets. (line 24) |
| * uninstall <1>: Install Rules for the User. |
| (line 7) |
| * uninstall <2>: Extending. (line 41) |
| * uninstall-hook: Extending. (line 66) |
| * uninstall-local: Extending. (line 41) |
| * Unit tests: Parallel Test Harness. |
| (line 154) |
| * Unpacking: Basic Installation. (line 27) |
| * ‘UPCFLAGS’ and ‘AM_UPCFLAGS’: Flag Variables Ordering. |
| (line 20) |
| * ‘UPDATED’ Texinfo flag: Texinfo. (line 35) |
| * ‘UPDATED-MONTH’ Texinfo flag: Texinfo. (line 35) |
| * Use Cases for the GNU Build System: Use Cases. (line 6) |
| * user variables: User Variables. (line 6) |
| * Using ‘aclocal’: configure. (line 6) |
| * ustar format: List of Automake options. |
| (line 159) |
| * v7 ‘tar’ format: List of Automake options. |
| (line 159) |
| * Vala Support: Vala Support. (line 6) |
| * variables, conflicting: Extending. (line 14) |
| * Variables, overriding: General Operation. (line 51) |
| * variables, reserved for the user: User Variables. (line 6) |
| * ‘VERSION’ Texinfo flag: Texinfo. (line 35) |
| * ‘VERSION’, prevent definition: Public Macros. (line 55) |
| * ‘version.m4’, example: Rebuilding. (line 12) |
| * ‘version.sh’, example: Rebuilding. (line 12) |
| * versioned binaries, installing: Extending. (line 86) |
| * VPATH builds: VPATH Builds. (line 6) |
| * wildcards: Wildcards. (line 6) |
| * Windows: EXEEXT. (line 6) |
| * xfail: Generalities about Testing. |
| (line 39) |
| * xpass: Generalities about Testing. |
| (line 39) |
| * ‘yacc’, multiple parsers: Yacc and Lex. (line 68) |
| * ‘YFLAGS’ and ‘AM_YFLAGS’: Flag Variables Ordering. |
| (line 20) |
| * ‘ylwrap’: Yacc and Lex. (line 68) |
| * ‘zardoz’ example: Complete. (line 35) |
| |