{ "mode": "info", "parameter": "automake", "section": "", "url": "https://www.chedong.com/phpMan.php/info/automake/json", "generated": "2026-06-15T12:07:55Z", "sections": { "GNU Automake": { "content": "This manual is for GNU Automake (version 1.16.5, 18 March 2022), a\nprogram that creates GNU standards-compliant Makefiles from template\nfiles.\n\nCopyright (C) 1995-2021 Free Software Foundation, Inc.\n\nPermission is granted to copy, distribute and/or modify this\ndocument under the terms of the GNU Free Documentation License,\nVersion 1.3 or any later version published by the Free Software\nFoundation; with no Invariant Sections, with no Front-Cover texts,\nand with no Back-Cover Texts. A copy of the license is included in\nthe section entitled \"GNU Free Documentation License.\"\n\n* Menu:\n\n* Introduction:: Automake's purpose\n* Autotools Introduction:: An Introduction to the Autotools\n* Generalities:: General ideas\n* Examples:: Some example packages\n* automake Invocation:: Creating a Makefile.in\n* configure:: Scanning configure.ac, using aclocal\n* Directories:: Declaring subdirectories\n* Programs:: Building programs and libraries\n* Other Objects:: Other derived objects\n* Other GNU Tools:: Other GNU Tools\n* Documentation:: Building documentation\n* Install:: What gets installed\n* Clean:: What gets cleaned\n* Dist:: What goes in a distribution\n* Tests:: Support for test suites\n* Rebuilding:: Automatic rebuilding of Makefile\n* Options:: Changing Automake's behavior\n* Miscellaneous:: Miscellaneous rules\n* Include:: Including extra files in an Automake template\n* Conditionals:: Conditionals\n* Silencing Make:: Obtain less verbose output from 'make'\n* Not Enough:: When Automake is not Enough\n* Distributing:: Distributing the Makefile.in\n* API Versioning:: About compatibility between Automake versions\n* Upgrading:: Upgrading to a Newer Automake Version\n* FAQ:: Frequently Asked Questions\n* Copying This Manual:: How to make copies of this manual\n* Indices:: Indices of variables, macros, and concepts\n\n-- The Detailed Node Listing --\n\nAn Introduction to the Autotools\n\n* GNU Build System:: Introducing the GNU Build System\n* Use Cases:: Use Cases for the GNU Build System\n* Why Autotools:: How Autotools Help\n* Hello World:: A Small Hello World Package\n\nUse Cases for the GNU Build System\n\n* Basic Installation:: Common installation procedure\n* Standard Targets:: A list of standard Makefile targets\n* Standard Directory Variables:: A list of standard directory variables\n* Standard Configuration Variables:: Using configuration variables\n* config.site:: Using a config.site file\n* VPATH Builds:: Parallel build trees\n* Two-Part Install:: Installing data and programs separately\n* Cross-Compilation:: Building for other architectures\n* Renaming:: Renaming programs at install time\n* DESTDIR:: Building binary packages with DESTDIR\n* Preparing Distributions:: Rolling out tarballs\n* Dependency Tracking:: Automatic dependency tracking\n* Nested Packages:: The GNU Build Systems can be nested\n\nA Small Hello World\n\n* Creating amhello:: Create 'amhello-1.0.tar.gz' from scratch\n* amhello's configure.ac Setup Explained::\n* amhello's Makefile.am Setup Explained::\n\nGeneral ideas\n\n* General Operation:: General operation of Automake\n* Strictness:: Standards conformance checking\n* Uniform:: The Uniform Naming Scheme\n* Length Limitations:: Staying below the command line length limit\n* Canonicalization:: How derived variables are named\n* User Variables:: Variables reserved for the user\n* Auxiliary Programs:: Programs automake might require\n\nSome example packages\n\n* Complete:: A simple example, start to finish\n* true:: Building true and false\n\nScanning 'configure.ac', using 'aclocal'\n\n* Requirements:: Configuration requirements\n* Optional:: Other things Automake recognizes\n* aclocal Invocation:: Auto-generating aclocal.m4\n* Macros:: Autoconf macros supplied with Automake\n\nAuto-generating aclocal.m4\n\n* aclocal Options:: Options supported by aclocal\n* Macro Search Path:: How aclocal finds .m4 files\n* Extending aclocal:: Writing your own aclocal macros\n* Local Macros:: Organizing local macros\n* Serials:: Serial lines in Autoconf macros\n* Future of aclocal:: aclocal's scheduled death\n\nAutoconf macros supplied with Automake\n\n* Public Macros:: Macros that you can use.\n* Obsolete Macros:: Macros that will soon be removed.\n* Private Macros:: Macros that you should not use.\n\nDirectories\n\n* Subdirectories:: Building subdirectories recursively\n* Conditional Subdirectories:: Conditionally not building directories\n* Alternative:: Subdirectories without recursion\n* Subpackages:: Nesting packages\n\nConditional Subdirectories\n\n* SUBDIRS vs DISTSUBDIRS:: Two sets of directories\n* Subdirectories with AMCONDITIONAL:: Specifying conditional subdirectories\n* Subdirectories with ACSUBST:: Another way for conditional recursion\n* Unconfigured Subdirectories:: Not even creating a 'Makefile'\n\nBuilding Programs and Libraries\n\n* A Program:: Building a program\n* A Library:: Building a library\n* A Shared Library:: Building a Libtool library\n* Program and Library Variables:: Variables controlling program and\nlibrary builds\n* Default SOURCES:: Default source files\n* LIBOBJS:: Special handling for LIBOBJS and ALLOCA\n* Program Variables:: Variables used when building a program\n* Yacc and Lex:: Yacc and Lex support\n* C++ Support:: Compiling C++ sources\n* Objective C Support:: Compiling Objective C sources\n* Objective C++ Support:: Compiling Objective C++ sources\n* Unified Parallel C Support:: Compiling Unified Parallel C sources\n* Assembly Support:: Compiling assembly sources\n* Fortran 77 Support:: Compiling Fortran 77 sources\n* Fortran 9x Support:: Compiling Fortran 9x sources\n* Java Support with gcj:: Compiling Java sources using gcj\n* Vala Support:: Compiling Vala sources\n* Support for Other Languages:: Compiling other languages\n* Dependencies:: Automatic dependency tracking\n* EXEEXT:: Support for executable extensions\n\nBuilding a program\n\n* Program Sources:: Defining program sources\n* Linking:: Linking with libraries or extra objects\n* Conditional Sources:: Handling conditional sources\n* Conditional Programs:: Building a program conditionally\n\nBuilding a Shared Library\n\n* Libtool Concept:: Introducing Libtool\n* Libtool Libraries:: Declaring Libtool Libraries\n* Conditional Libtool Libraries:: Building Libtool Libraries Conditionally\n* Conditional Libtool Sources:: Choosing Library Sources Conditionally\n* Libtool Convenience Libraries:: Building Convenience Libtool Libraries\n* Libtool Modules:: Building Libtool Modules\n* Libtool Flags:: Using LIBADD, LDFLAGS, and LIBTOOLFLAGS\n* LTLIBOBJS:: Using $(LTLIBOBJS) and $(LTALLOCA)\n* Libtool Issues:: Common Issues Related to Libtool's Use\n\nCommon Issues Related to Libtool's Use\n\n* Error required file ltmain.sh not found:: The need to run libtoolize\n* Objects created both with libtool and without:: Avoid a specific build race\n\nYacc and Lex support\n\n* Linking Multiple Yacc Parsers::\n\nFortran 77 Support\n\n* Preprocessing Fortran 77:: Preprocessing Fortran 77 sources\n* Compiling Fortran 77 Files:: Compiling Fortran 77 sources\n* Mixing Fortran 77 With C and C++:: Mixing Fortran 77 With C and C++\n\nMixing Fortran 77 With C and C++\n\n* How the Linker is Chosen:: Automatic linker selection\n\nFortran 9x Support\n\n* Compiling Fortran 9x Files:: Compiling Fortran 9x sources\n\nOther Derived Objects\n\n* Scripts:: Executable scripts\n* Headers:: Header files\n* Data:: Architecture-independent data files\n* Sources:: Derived sources\n\nBuilt Sources\n\n* Built Sources Example:: Several ways to handle built sources.\n\nOther GNU Tools\n\n* Emacs Lisp:: Emacs Lisp\n* gettext:: Gettext\n* Libtool:: Libtool\n* Java:: Java bytecode compilation (deprecated)\n* Python:: Python\n\nBuilding documentation\n\n* Texinfo:: Texinfo\n* Man Pages:: Man pages\n\nWhat Gets Installed\n\n* Basics of Installation:: What gets installed where\n* The Two Parts of Install:: Installing data and programs separately\n* Extending Installation:: Adding your own rules for installation\n* Staged Installs:: Installation in a temporary location\n* Install Rules for the User:: Useful additional rules\n\nWhat Goes in a Distribution\n\n* Basics of Distribution:: Files distributed by default\n* Fine-grained Distribution Control:: 'dist' and 'nodist' prefixes\n* The dist Hook:: A target for last-minute distribution changes\n* Checking the Distribution:: 'make distcheck' explained\n* The Types of Distributions:: A variety of formats and compression methods\n\nSupport for test suites\n\n* Generalities about Testing:: Concepts and terminology about testing\n* Simple Tests:: Listing test scripts in 'TESTS'\n* Custom Test Drivers:: Writing and using custom test drivers\n* Using the TAP test protocol:: Integrating test scripts that use the TAP protocol\n* DejaGnu Tests:: Interfacing with the 'dejagnu' testing framework\n* Install Tests:: Running tests on installed packages\n\nSimple Tests\n\n* Scripts-based Testsuites:: Automake-specific concepts and terminology\n* Serial Test Harness:: Older (and discouraged) serial test harness\n* Parallel Test Harness:: Generic concurrent test harness\n\nScripts-based Testsuites\n\n* Testsuite Environment Overrides::\n\nCustom Test Drivers\n\n* Overview of Custom Test Drivers Support::\n* Declaring Custom Test Drivers::\n* API for Custom Test Drivers::\n\nAPI for Custom Test Drivers\n\n* Command-line arguments for test drivers::\n* Log files generation and test results recording::\n* Testsuite progress output::\n\nUsing the TAP test protocol\n\n* Introduction to TAP::\n* Use TAP with the Automake test harness::\n* Incompatibilities with other TAP parsers and drivers::\n* Links and external resources on TAP::\n\nChanging Automake's Behavior\n\n* Options generalities:: Semantics of Automake option\n* List of Automake options:: A comprehensive list of Automake options\n\nMiscellaneous Rules\n\n* Tags:: Interfacing to cscope, etags and mkid\n* Suffixes:: Handling new file extensions\n\nConditionals\n\n* Usage of Conditionals:: Declaring conditional content\n* Limits of Conditionals:: Enclosing complete statements\n\nSilencing 'make'\n\n* Make verbosity:: Make is verbose by default\n* Tricks For Silencing Make:: Standard and generic ways to silence make\n* Automake Silent Rules:: How Automake can help in silencing make\n\nWhen Automake Isn't Enough\n\n* Extending:: Adding new rules or overriding existing ones.\n* Third-Party Makefiles:: Integrating Non-Automake 'Makefile's.\n\nFrequently Asked Questions about Automake\n\n* CVS:: CVS and generated files\n* maintainer-mode:: missing and AMMAINTAINERMODE\n* Wildcards:: Why doesn't Automake support wildcards?\n* Limitations on File Names:: Limitations on source and installed file names\n* Errors with distclean:: Files left in build directory after distclean\n* Flag Variables Ordering:: CFLAGS vs. AMCFLAGS vs. mumbleCFLAGS\n* Renamed Objects:: Why are object files sometimes renamed?\n* Per-Object Flags:: How to simulate per-object flags?\n* Multiple Outputs:: Writing rules for tools with many output files\n* Hard-Coded Install Paths:: Installing to hard-coded locations\n* Debugging Make Rules:: Strategies when things don't work as expected\n* Reporting Bugs:: Feedback on bugs and feature requests\n\nCopying This Manual\n\n* GNU Free Documentation License:: License for copying this manual\n\nIndices\n\n* Macro Index:: Index of Autoconf macros\n* Variable Index:: Index of Makefile variables\n* General Index:: General index\n\n\nFile: automake-1.16.info, Node: Introduction, Next: Autotools Introduction, Prev: Top, Up: Top\n", "subsections": [] }, "1 Introduction": { "content": "Automake is a tool for automatically generating 'Makefile.in's from\nfiles called 'Makefile.am'. Each 'Makefile.am' is basically a series of\n'make' variable definitions(1), with rules being thrown in occasionally.\nThe generated 'Makefile.in's are compliant with the GNU Makefile\nstandards.\n\nThe GNU Makefile Standards Document (*note (standards)Makefile\nConventions::) is long, complicated, and subject to change. The goal of\nAutomake is to remove the burden of Makefile maintenance from the back\nof the individual GNU maintainer (and put it on the back of the Automake\nmaintainers).\n\nThe typical Automake input file is simply a series of variable\ndefinitions. Each such file is processed to create a 'Makefile.in'.\n\nAutomake does constrain a project in certain ways; for instance, it\nassumes that the project uses Autoconf (*note Introduction:\n(autoconf)Top.), and enforces certain restrictions on the 'configure.ac'\ncontents.\n\nAutomake requires 'perl' in order to generate the 'Makefile.in's.\nHowever, the distributions created by Automake are fully GNU\nstandards-compliant, and do not require 'perl' in order to be built.\n\nFor more information on bug reports, *Note Reporting Bugs::.\n\n---------- Footnotes ----------\n\n(1) These variables are also called \"make macros\" in Make\nterminology, however in this manual we reserve the term \"macro\" for\nAutoconf's macros.\n\nFile: automake-1.16.info, Node: Autotools Introduction, Next: Generalities, Prev: Introduction, Up: Top\n", "subsections": [] }, "2 An Introduction to the Autotools": { "content": "If you are new to Automake, maybe you know that it is part of a set of\ntools called The Autotools. Maybe you've already delved into a\npackage full of files named 'configure', 'configure.ac', 'Makefile.in',\n'Makefile.am', 'aclocal.m4', ..., some of them claiming to be generated\nby Autoconf or Automake. But the exact purpose of these files and\ntheir relations is probably fuzzy. The goal of this chapter is to\nintroduce you to this machinery, to show you how it works and how\npowerful it is. If you've never installed or seen such a package, do\nnot worry: this chapter will walk you through it.\n\nIf you need some teaching material, more illustrations, or a less\n'automake'-centered continuation, some slides for this introduction are\navailable in Alexandre Duret-Lutz's Autotools Tutorial\n(https://www.lrde.epita.fr/~adl/autotools.html). This chapter is the\nwritten version of the first part of his tutorial.\n\n* Menu:\n\n* GNU Build System:: Introducing the GNU Build System\n* Use Cases:: Use Cases for the GNU Build System\n* Why Autotools:: How Autotools Help\n* Hello World:: A Small Hello World Package\n\nFile: automake-1.16.info, Node: GNU Build System, Next: Use Cases, Up: Autotools Introduction\n", "subsections": [ { "name": "2.1 Introducing the GNU Build System", "content": "It is a truth universally acknowledged, that as a developer in\npossession of a new package, you must be in want of a build system.\n\nIn the Unix world, such a build system is traditionally achieved\nusing the command 'make' (*note Overview: (make)Top.). You express the\nrecipe to build your package in a 'Makefile'. This file is a set of\nrules to build the files in the package. For instance the program\n'prog' may be built by running the linker on the files 'main.o',\n'foo.o', and 'bar.o'; the file 'main.o' may be built by running the\ncompiler on 'main.c'; etc. Each time 'make' is run, it reads\n'Makefile', checks the existence and modification time of the files\nmentioned, decides what files need to be built (or rebuilt), and runs\nthe associated commands.\n\nWhen a package needs to be built on a different platform than the one\nit was developed on, its 'Makefile' usually needs to be adjusted. For\ninstance the compiler may have another name or require more options. In\n1991, David J. MacKenzie got tired of customizing 'Makefile' for the 20\nplatforms he had to deal with. Instead, he handcrafted a little shell\nscript called 'configure' to automatically adjust the 'Makefile' (*note\nGenesis: (autoconf)Genesis.). Compiling his package was now as simple\nas running './configure && make'.\n\nToday this process has been standardized in the GNU project. The GNU\nCoding Standards (*note The Release Process: (standards)Managing\nReleases.) explains how each package of the GNU project should have a\n'configure' script, and the minimal interface it should have. The\n'Makefile' too should follow some established conventions. The result?\nA unified build system that makes all packages almost indistinguishable\nby the installer. In its simplest scenario, all the installer has to do\nis to unpack the package, run './configure && make && make install', and\nrepeat with the next package to install.\n\nWe call this build system the \"GNU Build System\", since it was grown\nout of the GNU project. However it is used by a vast number of other\npackages: following any existing convention has its advantages.\n\nThe Autotools are tools that will create a GNU Build System for your\npackage. Autoconf mostly focuses on 'configure' and Automake on\n'Makefile's. It is entirely possible to create a GNU Build System\nwithout the help of these tools. However it is rather burdensome and\nerror-prone. We will discuss this again after some illustration of the\nGNU Build System in action.\n\nFile: automake-1.16.info, Node: Use Cases, Next: Why Autotools, Prev: GNU Build System, Up: Autotools Introduction\n" }, { "name": "2.2 Use Cases for the GNU Build System", "content": "In this section we explore several use cases for the GNU Build System.\nYou can replay all of these examples on the 'amhello-1.0.tar.gz' package\ndistributed with Automake. If Automake is installed on your system, you\nshould find a copy of this file in\n'PREFIX/share/doc/automake/amhello-1.0.tar.gz', where PREFIX is the\ninstallation prefix specified during configuration (PREFIX defaults to\n'/usr/local', however if Automake was installed by some GNU/Linux\ndistribution it most likely has been set to '/usr'). If you do not have\na copy of Automake installed, you can find a copy of this file inside\nthe 'doc/' directory of the Automake package.\n\nSome of the following use cases present features that are in fact\nextensions to the GNU Build System. Read: they are not specified by the\nGNU Coding Standards, but they are nonetheless part of the build system\ncreated by the Autotools. To keep things simple, we do not point out\nthe difference. Our objective is to show you many of the features that\nthe build system created by the Autotools will offer to you.\n\n* Menu:\n\n* Basic Installation:: Common installation procedure\n* Standard Targets:: A list of standard Makefile targets\n* Standard Directory Variables:: A list of standard directory variables\n* Standard Configuration Variables:: Using configuration variables\n* config.site:: Using a config.site file\n* VPATH Builds:: Parallel build trees\n* Two-Part Install:: Installing data and programs separately\n* Cross-Compilation:: Building for other architectures\n* Renaming:: Renaming programs at install time\n* DESTDIR:: Building binary packages with DESTDIR\n* Preparing Distributions:: Rolling out tarballs\n* Dependency Tracking:: Automatic dependency tracking\n* Nested Packages:: The GNU Build Systems can be nested\n\nFile: automake-1.16.info, Node: Basic Installation, Next: Standard Targets, Up: Use Cases\n\n\nThe most common installation procedure looks as follows.\n\n~ % tar zxf amhello-1.0.tar.gz\n~ % cd amhello-1.0\n~/amhello-1.0 % ./configure\n...\nconfig.status: creating Makefile\nconfig.status: creating src/Makefile\n...\n~/amhello-1.0 % make\n...\n~/amhello-1.0 % make check\n...\n~/amhello-1.0 % su\nPassword:\n/home/adl/amhello-1.0 # make install\n...\n/home/adl/amhello-1.0 # exit\n~/amhello-1.0 % make installcheck\n...\n\nThe user first unpacks the package. Here, and in the following\nexamples, we will use the non-portable 'tar zxf' command for simplicity.\nOn a system without GNU 'tar' installed, this command should read\n'gunzip -c amhello-1.0.tar.gz | tar xf -'.\n\nThe user then enters the newly created directory to run the\n'configure' script. This script probes the system for various features,\nand finally creates the 'Makefile's. In this toy example there are only\ntwo 'Makefile's, but in real-world projects, there may be many more,\nusually one 'Makefile' per directory.\n\nIt is now possible to run 'make'. This will construct all the\nprograms, libraries, and scripts that need to be constructed for the\npackage. In our example, this compiles the 'hello' program. All files\nare constructed in place, in the source tree; we will see later how this\ncan be changed.\n\n'make check' causes the package's tests to be run. This step is not\nmandatory, but it is often good to make sure the programs that have been\nbuilt behave as they should, before you decide to install them. Our\nexample does not contain any tests, so running 'make check' is a no-op.\n\nAfter everything has been built, and maybe tested, it is time to\ninstall it on the system. That means copying the programs, libraries,\nheader files, scripts, and other data files from the source directory to\ntheir final destination on the system. The command 'make install' will\ndo that. However, by default everything will be installed in\nsubdirectories of '/usr/local': binaries will go into '/usr/local/bin',\nlibraries will end up in '/usr/local/lib', etc. This destination is\nusually not writable by any user, so we assume that we have to become\nroot before we can run 'make install'. In our example, running 'make\ninstall' will copy the program 'hello' into '/usr/local/bin' and\n'README' into '/usr/local/share/doc/amhello'.\n\nA last and optional step is to run 'make installcheck'. This command\nmay run tests on the installed files. 'make check' tests the files in\nthe source tree, while 'make installcheck' tests their installed copies.\nThe tests run by the latter can be different from those run by the\nformer. For instance, there are tests that cannot be run in the source\ntree. Conversely, some packages are set up so that 'make installcheck'\nwill run the very same tests as 'make check', only on different files\n(non-installed vs. installed). It can make a difference, for instance\nwhen the source tree's layout is different from that of the\ninstallation. Furthermore it may help to diagnose an incomplete\ninstallation.\n\nPresently most packages do not have any 'installcheck' tests because\nthe existence of 'installcheck' is little known, and its usefulness is\nneglected. Our little toy package is no better: 'make installcheck'\ndoes nothing.\n\nFile: automake-1.16.info, Node: Standard Targets, Next: Standard Directory Variables, Prev: Basic Installation, Up: Use Cases\n\n\nSo far we have come across four ways to run 'make' in the GNU Build\nSystem: 'make', 'make check', 'make install', and 'make installcheck'.\nThe words 'check', 'install', and 'installcheck', passed as arguments to\n'make', are called \"targets\". 'make' is a shorthand for 'make all',\n'all' being the default target in the GNU Build System.\n\nHere is a list of the most useful targets that the GNU Coding\nStandards specify.\n\n'make all'\nBuild programs, libraries, documentation, etc. (same as 'make').\n'make install'\nInstall what needs to be installed, copying the files from the\npackage's tree to system-wide directories.\n'make install-strip'\nSame as 'make install', then strip debugging symbols. Some users\nlike to trade space for useful bug reports...\n'make uninstall'\nThe opposite of 'make install': erase the installed files. (This\nneeds to be run from the same build tree that was installed.)\n'make clean'\nErase from the build tree the files built by 'make all'.\n'make distclean'\nAdditionally erase anything './configure' created.\n'make check'\nRun the test suite, if any.\n'make installcheck'\nCheck the installed programs or libraries, if supported.\n'make dist'\nRecreate 'PACKAGE-VERSION.tar.gz' from all the source files.\n\nFile: automake-1.16.info, Node: Standard Directory Variables, Next: Standard Configuration Variables, Prev: Standard Targets, Up: Use Cases\n\n\nThe GNU Coding Standards also specify a hierarchy of variables to denote\ninstallation directories. Some of these are:\n\n'prefix' '/usr/local'\n'execprefix' '${prefix}'\n'bindir' '${execprefix}/bin'\n'libdir' '${execprefix}/lib'\n...\n'includedir' '${prefix}/include'\n'datarootdir' '${prefix}/share'\n'datadir' '${datarootdir}'\n'mandir' '${datarootdir}/man'\n'infodir' '${datarootdir}/info'\n'docdir' '${datarootdir}/doc/${PACKAGE}'\n...\n\nEach of these directories has a role which is often obvious from its\nname. In a package, any installable file will be installed in one of\nthese directories. For instance in 'amhello-1.0', the program 'hello'\nis to be installed in BINDIR, the directory for binaries. The default\nvalue for this directory is '/usr/local/bin', but the user can supply a\ndifferent value when calling 'configure'. Also the file 'README' will\nbe installed into DOCDIR, which defaults to\n'/usr/local/share/doc/amhello'.\n\nAs a user, if you wish to install a package on your own account, you\ncould proceed as follows:\n\n~/amhello-1.0 % ./configure --prefix ~/usr\n...\n~/amhello-1.0 % make\n...\n~/amhello-1.0 % make install\n...\n\nThis would install '~/usr/bin/hello' and\n'~/usr/share/doc/amhello/README'.\n\nThe list of all such directory options is shown by './configure\n--help'.\n\nFile: automake-1.16.info, Node: Standard Configuration Variables, Next: config.site, Prev: Standard Directory Variables, Up: Use Cases\n\n\nThe GNU Coding Standards also define a set of standard configuration\nvariables used during the build. Here are some:\n\n'CC'\nC compiler command\n'CFLAGS'\nC compiler flags\n'CXX'\nC++ compiler command\n'CXXFLAGS'\nC++ compiler flags\n'LDFLAGS'\nlinker flags\n'CPPFLAGS'\nC/C++ preprocessor flags\n...\n\n'configure' usually does a good job at setting appropriate values for\nthese variables, but there are cases where you may want to override\nthem. For instance you may have several versions of a compiler\ninstalled and would like to use another one, you may have header files\ninstalled outside the default search path of the compiler, or even\nlibraries out of the way of the linker.\n\nHere is how one would call 'configure' to force it to use 'gcc-3' as\nC compiler, use header files from '~/usr/include' when compiling, and\nlibraries from '~/usr/lib' when linking.\n\n~/amhello-1.0 % ./configure --prefix ~/usr CC=gcc-3 \\\nCPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib\n\nAgain, a full list of these variables appears in the output of\n'./configure --help'.\n\nFile: automake-1.16.info, Node: config.site, Next: VPATH Builds, Prev: Standard Configuration Variables, Up: Use Cases\n\n\nWhen installing several packages using the same setup, it can be\nconvenient to create a file to capture common settings. If a file named\n'PREFIX/share/config.site' exists, 'configure' will source it at the\nbeginning of its execution.\n\nRecall the command from the previous section:\n\n~/amhello-1.0 % ./configure --prefix ~/usr CC=gcc-3 \\\nCPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib\n\nAssuming we are installing many package in '~/usr', and will always\nwant to use these definitions of 'CC', 'CPPFLAGS', and 'LDFLAGS', we can\nautomate this by creating the following '~/usr/share/config.site' file:\n\ntest -z \"$CC\" && CC=gcc-3\ntest -z \"$CPPFLAGS\" && CPPFLAGS=-I$HOME/usr/include\ntest -z \"$LDFLAGS\" && LDFLAGS=-L$HOME/usr/lib\n\nNow, any time a 'configure' script is using the '~/usr' prefix, it\nwill execute the above 'config.site' and define these three variables.\n\n~/amhello-1.0 % ./configure --prefix ~/usr\nconfigure: loading site script /home/adl/usr/share/config.site\n...\n\n*Note Setting Site Defaults: (autoconf)Site Defaults, for more\ninformation about this feature.\n\nFile: automake-1.16.info, Node: VPATH Builds, Next: Two-Part Install, Prev: config.site, Up: Use Cases\n\n\nThe GNU Build System distinguishes two trees: the source tree, and the\nbuild tree. These are two directories that may be the same, or\ndifferent.\n\nThe source tree is rooted in the directory containing the 'configure'\nscript. It contains all the source files (those that are distributed),\nand may be arranged using several subdirectories.\n\nThe build tree is rooted in the current directory at the time\n'configure' was run, and is populated with all object files, programs,\nlibraries, and other derived files built from the sources (and hence not\ndistributed). The build tree usually has the same subdirectory layout\nas the source tree; its subdirectories are created automatically by the\nbuild system.\n\nIf 'configure' is executed in its own directory, the source and build\ntrees are combined: derived files are constructed in the same\ndirectories as their sources. This was the case in our first\ninstallation example (*note Basic Installation::).\n\nA common request from users is that they want to confine all derived\nfiles to a single directory, to keep their source directories\nuncluttered. Here is how we could run 'configure' to create everything\nin a build tree (that is, subdirectory) called 'build/'.\n\n~ % tar zxf ~/amhello-1.0.tar.gz\n~ % cd amhello-1.0\n~/amhello-1.0 % mkdir build && cd build\n~/amhello-1.0/build % ../configure\n...\n~/amhello-1.0/build % make\n...\n\nThese setups, where source and build trees are different, are often\ncalled \"parallel builds\" or \"VPATH builds\". The expression parallel\nbuild is misleading: the word parallel is a reference to the way the\nbuild tree shadows the source tree, it is not about some concurrency in\nthe way build commands are run. For this reason we refer to such setups\nusing the name VPATH builds in the following. VPATH is the name of\nthe 'make' feature used by the 'Makefile's to allow these builds (*note\n'VPATH' Search Path for All Prerequisites: (make)General Search.).\n\nVPATH builds have other interesting uses. One is to build the same\nsources with multiple configurations. For instance:\n\n~ % tar zxf ~/amhello-1.0.tar.gz\n~ % cd amhello-1.0\n~/amhello-1.0 % mkdir debug optim && cd debug\n~/amhello-1.0/debug % ../configure CFLAGS='-g -O0'\n...\n~/amhello-1.0/debug % make\n...\n~/amhello-1.0/debug % cd ../optim\n~/amhello-1.0/optim % ../configure CFLAGS='-O3 -fomit-frame-pointer'\n...\n~/amhello-1.0/optim % make\n...\n\nWith network file systems, a similar approach can be used to build\nthe same sources on different machines. For instance, suppose that the\nsources are installed on a directory shared by two hosts: 'HOST1' and\n'HOST2', which may be different platforms.\n\n~ % cd /nfs/src\n/nfs/src % tar zxf ~/amhello-1.0.tar.gz\n\nOn the first host, you could create a local build directory:\n[HOST1] ~ % mkdir /tmp/amh && cd /tmp/amh\n[HOST1] /tmp/amh % /nfs/src/amhello-1.0/configure\n...\n[HOST1] /tmp/amh % make && sudo make install\n...\n\n(Here we assume that the installer has configured 'sudo' so it can\nexecute 'make install' with root privileges; it is more convenient than\nusing 'su' like in *note Basic Installation::).\n\nOn the second host, you would do exactly the same, possibly at the\nsame time:\n[HOST2] ~ % mkdir /tmp/amh && cd /tmp/amh\n[HOST2] /tmp/amh % /nfs/src/amhello-1.0/configure\n...\n[HOST2] /tmp/amh % make && sudo make install\n...\n\nIn this scenario, nothing forbids the '/nfs/src/amhello-1.0'\ndirectory from being read-only. In fact VPATH builds are also a means\nof building packages from a read-only medium such as a CD-ROM. (The FSF\nused to sell CD-ROMs with unpacked source code, before the GNU project\ngrew so big.)\n\nFile: automake-1.16.info, Node: Two-Part Install, Next: Cross-Compilation, Prev: VPATH Builds, Up: Use Cases\n\n\nIn our last example (*note VPATH Builds::), a source tree was shared by\ntwo hosts, but compilation and installation were done separately on each\nhost.\n\nThe GNU Build System also supports networked setups where part of the\ninstalled files should be shared amongst multiple hosts. It does so by\ndistinguishing architecture-dependent files from\narchitecture-independent files, and providing two 'Makefile' targets to\ninstall each of these classes of files.\n\nThese targets are 'install-exec' for architecture-dependent files and\n'install-data' for architecture-independent files. The command we used\nup to now, 'make install', can be thought of as a shorthand for 'make\ninstall-exec install-data'.\n\nFrom the GNU Build System point of view, the distinction between\narchitecture-dependent files and architecture-independent files is based\nexclusively on the directory variable used to specify their installation\ndestination. In the list of directory variables we provided earlier\n(*note Standard Directory Variables::), all the variables based on\nEXEC-PREFIX designate architecture-dependent directories whose files\nwill be installed by 'make install-exec'. The others designate\narchitecture-independent directories and will serve files installed by\n'make install-data'. *Note The Two Parts of Install::, for more\ndetails.\n\nHere is how we could revisit our two-host installation example,\nassuming that (1) we want to install the package directly in '/usr', and\n(2) the directory '/usr/share' is shared by the two hosts.\n\nOn the first host we would run\n[HOST1] ~ % mkdir /tmp/amh && cd /tmp/amh\n[HOST1] /tmp/amh % /nfs/src/amhello-1.0/configure --prefix /usr\n...\n[HOST1] /tmp/amh % make && sudo make install\n...\n\nOn the second host, however, we need only install the\narchitecture-specific files.\n[HOST2] ~ % mkdir /tmp/amh && cd /tmp/amh\n[HOST2] /tmp/amh % /nfs/src/amhello-1.0/configure --prefix /usr\n...\n[HOST2] /tmp/amh % make && sudo make install-exec\n...\n\nIn packages that have installation checks, it would make sense to run\n'make installcheck' (*note Basic Installation::) to verify that the\npackage works correctly despite the apparent partial installation.\n\nFile: automake-1.16.info, Node: Cross-Compilation, Next: Renaming, Prev: Two-Part Install, Up: Use Cases\n\n\nTo \"cross-compile\" is to build on one platform a binary that will run on\nanother platform. When speaking of cross-compilation, it is important\nto distinguish between the \"build platform\" on which the compilation is\nperformed, and the \"host platform\" on which the resulting executable is\nexpected to run. The following 'configure' options are used to specify\neach of them:\n\n'--build=BUILD'\nThe system on which the package is built.\n'--host=HOST'\nThe system where built programs and libraries will run.\n\nWhen the '--host' is used, 'configure' will search for the\ncross-compiling suite for this platform. Cross-compilation tools\ncommonly have their target architecture as prefix of their name. For\ninstance my cross-compiler for MinGW32 has its binaries called\n'i586-mingw32msvc-gcc', 'i586-mingw32msvc-ld', 'i586-mingw32msvc-as',\netc.\n\nHere is how we could build 'amhello-1.0' for 'i586-mingw32msvc' on a\nGNU/Linux PC.\n\n~/amhello-1.0 % ./configure --build i686-pc-linux-gnu --host i586-mingw32msvc\nchecking for a BSD-compatible install... /usr/bin/install -c\nchecking whether build environment is sane... yes\nchecking for gawk... gawk\nchecking whether make sets $(MAKE)... yes\nchecking for i586-mingw32msvc-strip... i586-mingw32msvc-strip\nchecking for i586-mingw32msvc-gcc... i586-mingw32msvc-gcc\nchecking for C compiler default output file name... a.exe\nchecking whether the C compiler works... yes\nchecking whether we are cross compiling... yes\nchecking for suffix of executables... .exe\nchecking for suffix of object files... o\nchecking whether we are using the GNU C compiler... yes\nchecking whether i586-mingw32msvc-gcc accepts -g... yes\nchecking for i586-mingw32msvc-gcc option to accept ANSI C...\n...\n~/amhello-1.0 % make\n...\n~/amhello-1.0 % cd src; file hello.exe\nhello.exe: MS Windows PE 32-bit Intel 80386 console executable not relocatable\n\nThe '--host' and '--build' options are usually all we need for\ncross-compiling. The only exception is if the package being built is\nitself a cross-compiler: we need a third option to specify its target\narchitecture.\n\n'--target=TARGET'\nWhen building compiler tools: the system for which the tools will\ncreate output.\n\nFor instance when installing GCC, the GNU Compiler Collection, we can\nuse '--target=TARGET' to specify that we want to build GCC as a\ncross-compiler for TARGET. Mixing '--build' and '--target', we can\ncross-compile a cross-compiler; such a three-way cross-compilation is\nknown as a \"Canadian cross\".\n\n*Note Specifying the System Type: (autoconf)Specifying Names, for\nmore information about these 'configure' options.\n\nFile: automake-1.16.info, Node: Renaming, Next: DESTDIR, Prev: Cross-Compilation, Up: Use Cases\n\n\nThe GNU Build System provides means to automatically rename executables\nand manpages before they are installed (*note Man Pages::). This is\nespecially convenient when installing a GNU package on a system that\nalready has a proprietary implementation you do not want to overwrite.\nFor instance, you may want to install GNU 'tar' as 'gtar' so you can\ndistinguish it from your vendor's 'tar'.\n\nThis can be done using one of these three 'configure' options.\n\n'--program-prefix=PREFIX'\nPrepend PREFIX to installed program names.\n'--program-suffix=SUFFIX'\nAppend SUFFIX to installed program names.\n'--program-transform-name=PROGRAM'\nRun 'sed PROGRAM' on installed program names.\n\nThe following commands would install 'hello' as\n'/usr/local/bin/test-hello', for instance.\n\n~/amhello-1.0 % ./configure --program-prefix test-\n...\n~/amhello-1.0 % make\n...\n~/amhello-1.0 % sudo make install\n...\n\nFile: automake-1.16.info, Node: DESTDIR, Next: Preparing Distributions, Prev: Renaming, Up: Use Cases\n\n\nThe GNU Build System's 'make install' and 'make uninstall' interface\ndoes not exactly fit the needs of a system administrator who has to\ndeploy and upgrade packages on lots of hosts. In other words, the GNU\nBuild System does not replace a package manager.\n\nSuch package managers usually need to know which files have been\ninstalled by a package, so a mere 'make install' is inappropriate.\n\nThe 'DESTDIR' variable can be used to perform a staged installation.\nThe package should be configured as if it was going to be installed in\nits final location (e.g., '--prefix /usr'), but when running 'make\ninstall', the 'DESTDIR' should be set to the absolute name of a\ndirectory into which the installation will be diverted. From this\ndirectory it is easy to review which files are being installed where,\nand finally copy them to their final location by some means.\n\nFor instance here is how we could create a binary package containing\na snapshot of all the files to be installed.\n\n~/amhello-1.0 % ./configure --prefix /usr\n...\n~/amhello-1.0 % make\n...\n~/amhello-1.0 % make DESTDIR=$HOME/inst install\n...\n~/amhello-1.0 % cd ~/inst\n~/inst % find . -type f -print > ../files.lst\n~/inst % tar zcvf ~/amhello-1.0-i686.tar.gz `cat ../files.lst`\n./usr/bin/hello\n./usr/share/doc/amhello/README\n\nAfter this example, 'amhello-1.0-i686.tar.gz' is ready to be\nuncompressed in '/' on many hosts. (Using '`cat ../files.lst`' instead\nof '.' as argument for 'tar' avoids entries for each subdirectory in the\narchive: we would not like 'tar' to restore the modification time of\n'/', '/usr/', etc.)\n\nNote that when building packages for several architectures, it might\nbe convenient to use 'make install-data' and 'make install-exec' (*note\nTwo-Part Install::) to gather architecture-independent files in a single\npackage.\n\n*Note Install::, for more information.\n\nFile: automake-1.16.info, Node: Preparing Distributions, Next: Dependency Tracking, Prev: DESTDIR, Up: Use Cases\n\n\nWe have already mentioned 'make dist'. This target collects all your\nsource files and the necessary parts of the build system to create a\ntarball named 'PACKAGE-VERSION.tar.gz'.\n\nAnother, more useful command is 'make distcheck'. The 'distcheck'\ntarget constructs 'PACKAGE-VERSION.tar.gz' just as well as 'dist', but\nit additionally ensures most of the use cases presented so far work:\n\n* It attempts a full compilation of the package (*note Basic\nInstallation::): unpacking the newly constructed tarball, running\n'make', 'make dvi', 'make check', 'make install', as well as 'make\ninstallcheck', and even 'make dist',\n* it tests VPATH builds with read-only source tree (*note VPATH\nBuilds::),\n* it makes sure 'make clean', 'make distclean', and 'make uninstall'\ndo not omit any file (*note Standard Targets::),\n* and it checks that 'DESTDIR' installations work (*note DESTDIR::).\n\nAll of these actions are performed in a temporary directory, so that\nno root privileges are required. The exact location and the exact\nstructure of such a subdirectory (where the extracted sources are\nplaced, how the temporary build and install directories are named and\nhow deeply they are nested, etc.) is to be considered an implementation\ndetail, which can change at any time; so do not rely on it.\n\nReleasing a package that fails 'make distcheck' means that one of the\nscenarios we presented will not work and some users will be\ndisappointed. Therefore it is a good practice to release a package only\nafter a successful 'make distcheck'. This of course does not imply that\nthe package will be flawless, but at least it will prevent some of the\nembarrassing errors you may find in packages released by people who have\nnever heard about 'distcheck' (like 'DESTDIR' not working because of a\ntypo, or a distributed file being erased by 'make clean', or even\n'VPATH' builds not working).\n\n*Note Creating amhello::, to recreate 'amhello-1.0.tar.gz' using\n'make distcheck'. *Note Checking the Distribution::, for more\ninformation about 'distcheck'.\n\nFile: automake-1.16.info, Node: Dependency Tracking, Next: Nested Packages, Prev: Preparing Distributions, Up: Use Cases\n\n\nDependency tracking is performed as a side-effect of compilation. Each\ntime the build system compiles a source file, it computes its list of\ndependencies (in C these are the header files included by the source\nbeing compiled). Later, any time 'make' is run and a dependency appears\nto have changed, the dependent files will be rebuilt.\n\nAutomake generates code for automatic dependency tracking by default,\nunless the developer chooses to override it; for more information, *note\nDependencies::.\n\nWhen 'configure' is executed, you can see it probing each compiler\nfor the dependency mechanism it supports (several mechanisms can be\nused):\n\n~/amhello-1.0 % ./configure --prefix /usr\n...\nchecking dependency style of gcc... gcc3\n...\n\nBecause dependencies are only computed as a side-effect of the\ncompilation, no dependency information exists the first time a package\nis built. This is OK because all the files need to be built anyway:\n'make' does not have to decide which files need to be rebuilt. In fact,\ndependency tracking is completely useless for one-time builds and there\nis a 'configure' option to disable this:\n\n'--disable-dependency-tracking'\nSpeed up one-time builds.\n\nSome compilers do not offer any practical way to derive the list of\ndependencies as a side-effect of the compilation, requiring a separate\nrun (maybe of another tool) to compute these dependencies. The\nperformance penalty implied by these methods is important enough to\ndisable them by default. The option '--enable-dependency-tracking' must\nbe passed to 'configure' to activate them.\n\n'--enable-dependency-tracking'\nDo not reject slow dependency extractors.\n\n*Note Dependency Tracking Evolution: (automake-history)Dependency\nTracking Evolution, for some discussion about the different dependency\ntracking schemes used by Automake over the years.\n\nFile: automake-1.16.info, Node: Nested Packages, Prev: Dependency Tracking, Up: Use Cases\n\n\nAlthough nesting packages isn't something we would recommend to someone\nwho is discovering the Autotools, it is a nice feature worthy of mention\nin this small advertising tour.\n\nAutoconfiscated packages (that means packages whose build system have\nbeen created by Autoconf and friends) can be nested to arbitrary depth.\n\nA typical setup is that package A will distribute one of the\nlibraries it needs in a subdirectory. This library B is a complete\npackage with its own GNU Build System. The 'configure' script of A will\nrun the 'configure' script of B as part of its execution; building and\ninstalling A will also build and install B. Generating a distribution\nfor A will also include B.\n\nIt is possible to gather several packages like this. GCC is a heavy\nuser of this feature. This gives installers a single package to\nconfigure, build and install, while it allows developers to work on\nsubpackages independently.\n\nWhen configuring nested packages, the 'configure' options given to\nthe top-level 'configure' are passed recursively to nested 'configure's.\nA package that does not understand an option will ignore it, assuming it\nis meaningful to some other package.\n\nThe command 'configure --help=recursive' can be used to display the\noptions supported by all the included packages.\n\n*Note Subpackages::, for an example setup.\n\nFile: automake-1.16.info, Node: Why Autotools, Next: Hello World, Prev: Use Cases, Up: Autotools Introduction\n" }, { "name": "2.3 How Autotools Help", "content": "There are several reasons why you may not want to implement the GNU\nBuild System yourself (read: write a 'configure' script and 'Makefile's\nyourself).\n\n* As we have seen, the GNU Build System has a lot of features (*note\nUse Cases::). Some users may expect features you have not\nimplemented because you did not need them.\n* Implementing these features portably is difficult and exhausting.\nThink of writing portable shell scripts, and portable 'Makefile's,\nfor systems you may not have handy. *Note Portable Shell\nProgramming: (autoconf)Portable Shell, to convince yourself.\n* You will have to upgrade your setup to follow changes to the GNU\nCoding Standards.\n\nThe GNU Autotools take all this burden off your back and provide:\n\n* Tools to create a portable, complete, and self-contained GNU Build\nSystem, from simple instructions. Self-contained meaning the\nresulting build system does not require the GNU Autotools.\n* A central place where fixes and improvements are made: a bug-fix\nfor a portability issue will benefit every package.\n\nYet there also exist reasons why you may want NOT to use the\nAutotools... For instance you may be already using (or used to) another\nincompatible build system. Autotools will only be useful if you do\naccept the concepts of the GNU Build System. People who have their own\nidea of how a build system should work will feel frustrated by the\nAutotools.\n\nFile: automake-1.16.info, Node: Hello World, Prev: Why Autotools, Up: Autotools Introduction\n" }, { "name": "2.4 A Small Hello World", "content": "In this section we recreate the 'amhello-1.0' package from scratch. The\nfirst subsection shows how to call the Autotools to instantiate the GNU\nBuild System, while the second explains the meaning of the\n'configure.ac' and 'Makefile.am' files read by the Autotools.\n\n* Menu:\n\n* Creating amhello:: Create 'amhello-1.0.tar.gz' from scratch\n* amhello's configure.ac Setup Explained::\n* amhello's Makefile.am Setup Explained::\n\nFile: automake-1.16.info, Node: Creating amhello, Next: amhello's configure.ac Setup Explained, Up: Hello World\n\n\nHere is how we can recreate 'amhello-1.0.tar.gz' from scratch. The\npackage is simple enough so that we will only need to write 5 files.\n(You may copy them from the final 'amhello-1.0.tar.gz' that is\ndistributed with Automake if you do not want to write them.)\n\nCreate the following files in an empty directory.\n\n* 'src/main.c' is the source file for the 'hello' program. We store\nit in the 'src/' subdirectory, because later, when the package\nevolves, it will ease the addition of a 'man/' directory for man\npages, a 'data/' directory for data files, etc.\n~/amhello % cat src/main.c\n#include \n#include \n\nint\nmain (void)\n{\nputs (\"Hello World!\");\nputs (\"This is \" PACKAGESTRING \".\");\nreturn 0;\n}\n\n* 'README' contains some very limited documentation for our little\npackage.\n~/amhello % cat README\nThis is a demonstration package for GNU Automake.\nType 'info Automake' to read the Automake manual.\n\n* 'Makefile.am' and 'src/Makefile.am' contain Automake instructions\nfor these two directories.\n\n~/amhello % cat src/Makefile.am\nbinPROGRAMS = hello\nhelloSOURCES = main.c\n~/amhello % cat Makefile.am\nSUBDIRS = src\ndistdocDATA = README\n\n* Finally, 'configure.ac' contains Autoconf instructions to create\nthe 'configure' script.\n\n~/amhello % cat configure.ac\nACINIT([amhello], [1.0], [bug-automake@gnu.org])\nAMINITAUTOMAKE([-Wall -Werror foreign])\nACPROGCC\nACCONFIGHEADERS([config.h])\nACCONFIGFILES([\nMakefile\nsrc/Makefile\n])\nACOUTPUT\n\nOnce you have these five files, it is time to run the Autotools to\ninstantiate the build system. Do this using the 'autoreconf' command as\nfollows:\n\n~/amhello % autoreconf --install\nconfigure.ac: installing './install-sh'\nconfigure.ac: installing './missing'\nconfigure.ac: installing './compile'\nsrc/Makefile.am: installing './depcomp'\n\nAt this point the build system is complete.\n\nIn addition to the three scripts mentioned in its output, you can see\nthat 'autoreconf' created four other files: 'configure', 'config.h.in',\n'Makefile.in', and 'src/Makefile.in'. The latter three files are\ntemplates that will be adapted to the system by 'configure' under the\nnames 'config.h', 'Makefile', and 'src/Makefile'. Let's do this:\n\n~/amhello % ./configure\nchecking for a BSD-compatible install... /usr/bin/install -c\nchecking whether build environment is sane... yes\nchecking for gawk... no\nchecking for mawk... mawk\nchecking whether make sets $(MAKE)... yes\nchecking for gcc... gcc\nchecking for C compiler default output file name... a.out\nchecking whether the C compiler works... yes\nchecking whether we are cross compiling... no\nchecking for suffix of executables...\nchecking for suffix of object files... o\nchecking whether we are using the GNU C compiler... yes\nchecking whether gcc accepts -g... yes\nchecking for gcc option to accept ISO C89... none needed\nchecking for style of include used by make... GNU\nchecking dependency style of gcc... gcc3\nconfigure: creating ./config.status\nconfig.status: creating Makefile\nconfig.status: creating src/Makefile\nconfig.status: creating config.h\nconfig.status: executing depfiles commands\n\nYou can see 'Makefile', 'src/Makefile', and 'config.h' being created\nat the end after 'configure' has probed the system. It is now possible\nto run all the targets we wish (*note Standard Targets::). For\ninstance:\n\n~/amhello % make\n...\n~/amhello % src/hello\nHello World!\nThis is amhello 1.0.\n~/amhello % make distcheck" }, { "name": "...", "content": "amhello-1.0 archives ready for distribution:" }, { "name": "amhello-1.0.tar.gz", "content": "Note that running 'autoreconf' is only needed initially when the GNU\nBuild System does not exist. When you later change some instructions in\na 'Makefile.am' or 'configure.ac', the relevant part of the build system\nwill be regenerated automatically when you execute 'make'.\n\n'autoreconf' is a script that calls 'autoconf', 'automake', and a\nbunch of other commands in the right order. If you are beginning with\nthese tools, it is not important to figure out in which order all of\nthese tools should be invoked and why. However, because Autoconf and\nAutomake have separate manuals, the important point to understand is\nthat 'autoconf' is in charge of creating 'configure' from\n'configure.ac', while 'automake' is in charge of creating 'Makefile.in's\nfrom 'Makefile.am's and 'configure.ac'. This should at least direct you\nto the right manual when seeking answers.\n\nFile: automake-1.16.info, Node: amhello's configure.ac Setup Explained, Next: amhello's Makefile.am Setup Explained, Prev: Creating amhello, Up: Hello World\n\n\nLet us begin with the contents of 'configure.ac'.\n\nACINIT([amhello], [1.0], [bug-automake@gnu.org])\nAMINITAUTOMAKE([-Wall -Werror foreign])\nACPROGCC\nACCONFIGHEADERS([config.h])\nACCONFIGFILES([\nMakefile\nsrc/Makefile\n])\nACOUTPUT\n\nThis file is read by both 'autoconf' (to create 'configure') and\n'automake' (to create the various 'Makefile.in's). It contains a series\nof M4 macros that will be expanded as shell code to finally form the\n'configure' script. We will not elaborate on the syntax of this file,\nbecause the Autoconf manual has a whole section about it (*note Writing\n'configure.ac': (autoconf)Writing Autoconf Input.).\n\nThe macros prefixed with 'AC' are Autoconf macros, documented in the\nAutoconf manual (*note Autoconf Macro Index: (autoconf)Autoconf Macro\nIndex.). The macros that start with 'AM' are Automake macros,\ndocumented later in this manual (*note Macro Index::).\n\nThe first two lines of 'configure.ac' initialize Autoconf and\nAutomake. 'ACINIT' takes in as parameters the name of the package, its\nversion number, and a contact address for bug-reports about the package\n(this address is output at the end of './configure --help', for\ninstance). When adapting this setup to your own package, by all means\nplease do not blindly copy Automake's address: use the mailing list of\nyour package, or your own mail address.\n\nThe argument to 'AMINITAUTOMAKE' is a list of options for\n'automake' (*note Options::). '-Wall' and '-Werror' ask 'automake' to\nturn on all warnings and report them as errors. We are speaking of\n*Automake* warnings here, such as dubious instructions in 'Makefile.am'.\nThis has absolutely nothing to do with how the compiler will be called,\neven though it may support options with similar names. Using '-Wall\n-Werror' is a safe setting when starting to work on a package: you do\nnot want to miss any issues. Later you may decide to relax things a\nbit. The 'foreign' option tells Automake that this package will not\nfollow the GNU Standards. GNU packages should always distribute\nadditional files such as 'ChangeLog', 'AUTHORS', etc. We do not want\n'automake' to complain about these missing files in our small example.\n\nThe 'ACPROGCC' line causes the 'configure' script to search for a C\ncompiler and define the variable 'CC' with its name. The\n'src/Makefile.in' file generated by Automake uses the variable 'CC' to\nbuild 'hello', so when 'configure' creates 'src/Makefile' from\n'src/Makefile.in', it will define 'CC' with the value it has found. If\nAutomake is asked to create a 'Makefile.in' that uses 'CC' but\n'configure.ac' does not define it, it will suggest you add a call to\n'ACPROGCC'.\n\nThe 'ACCONFIGHEADERS([config.h])' invocation causes the 'configure'\nscript to create a 'config.h' file gathering '#define's defined by other\nmacros in 'configure.ac'. In our case, the 'ACINIT' macro already\ndefined a few of them. Here is an excerpt of 'config.h' after\n'configure' has run:\n\n...\n/* Define to the address where bug reports for this package should be sent. */\n#define PACKAGEBUGREPORT \"bug-automake@gnu.org\"\n\n/* Define to the full name and version of this package. */\n#define PACKAGESTRING \"amhello 1.0\"\n...\n\nAs you probably noticed, 'src/main.c' includes 'config.h' so it can\nuse 'PACKAGESTRING'. In a real-world project, 'config.h' can grow\nquite large, with one '#define' per feature probed on the system.\n\nThe 'ACCONFIGFILES' macro declares the list of files that\n'configure' should create from their '*.in' templates. Automake also\nscans this list to find the 'Makefile.am' files it must process. (This\nis important to remember: when adding a new directory to your project,\nyou should add its 'Makefile' to this list, otherwise Automake will\nnever process the new 'Makefile.am' you wrote in that directory.)\n\nFinally, the 'ACOUTPUT' line is a closing command that actually\nproduces the part of the script in charge of creating the files\nregistered with 'ACCONFIGHEADERS' and 'ACCONFIGFILES'.\n\nWhen starting a new project, we suggest you start with such a simple\n'configure.ac', and gradually add the other tests it requires. The\ncommand 'autoscan' can also suggest a few of the tests your package may\nneed (*note Using 'autoscan' to Create 'configure.ac':\n(autoconf)autoscan Invocation.).\n\nFile: automake-1.16.info, Node: amhello's Makefile.am Setup Explained, Prev: amhello's configure.ac Setup Explained, Up: Hello World\n\n\nWe now turn to 'src/Makefile.am'. This file contains Automake\ninstructions to build and install 'hello'.\n\nbinPROGRAMS = hello\nhelloSOURCES = main.c\n\nA 'Makefile.am' has the same syntax as an ordinary 'Makefile'. When\n'automake' processes a 'Makefile.am' it copies the entire file into the\noutput 'Makefile.in' (that will be later turned into 'Makefile' by\n'configure') but will react to certain variable definitions by\ngenerating some build rules and other variables. Often 'Makefile.am's\ncontain only a list of variable definitions as above, but they can also\ncontain other variable and rule definitions that 'automake' will pass\nalong without interpretation.\n\nVariables that end with 'PROGRAMS' are special variables that list\nprograms that the resulting 'Makefile' should build. In Automake speak,\nthis 'PROGRAMS' suffix is called a \"primary\"; Automake recognizes other\nprimaries such as 'SCRIPTS', 'DATA', 'LIBRARIES', etc. corresponding\nto different types of files.\n\nThe 'bin' part of the 'binPROGRAMS' tells 'automake' that the\nresulting programs should be installed in BINDIR. Recall that the GNU\nBuild System uses a set of variables to denote destination directories\nand allow users to customize these locations (*note Standard Directory\nVariables::). Any such directory variable can be put in front of a\nprimary (omitting the 'dir' suffix) to tell 'automake' where to install\nthe listed files.\n\nPrograms need to be built from source files, so for each program\n'PROG' listed in a 'PROGRAMS' variable, 'automake' will look for\nanother variable named 'PROGSOURCES' listing its source files. There\nmay be more than one source file: they will all be compiled and linked\ntogether.\n\nAutomake also knows that source files need to be distributed when\ncreating a tarball (unlike built programs). So a side-effect of this\n'helloSOURCES' declaration is that 'main.c' will be part of the tarball\ncreated by 'make dist'.\n\nFinally here are some explanations regarding the top-level\n'Makefile.am'.\n\nSUBDIRS = src\ndistdocDATA = README\n\n'SUBDIRS' is a special variable listing all directories that 'make'\nshould recurse into before processing the current directory. So this\nline is responsible for 'make' building 'src/hello' even though we run\nit from the top-level. This line also causes 'make install' to install\n'src/hello' before installing 'README' (not that this order matters).\n\nThe line 'distdocDATA = README' causes 'README' to be distributed\nand installed in DOCDIR. Files listed with the 'DATA' primary are not\nautomatically part of the tarball built with 'make dist', so we add the\n'dist' prefix so they get distributed. However, for 'README' it would\nnot have been necessary: 'automake' automatically distributes any\n'README' file it encounters (the list of other files automatically\ndistributed is presented by 'automake --help'). The only important\neffect of this second line is therefore to install 'README' during 'make\ninstall'.\n\nOne thing not covered in this example is accessing the installation\ndirectory values (*note Standard Directory Variables::) from your\nprogram code, that is, converting them into defined macros. For this,\n*note (autoconf)Defining Directories::.\n\nFile: automake-1.16.info, Node: Generalities, Next: Examples, Prev: Autotools Introduction, Up: Top\n" } ] }, "3 General ideas": { "content": "The following sections cover a few basic ideas that will help you\nunderstand how Automake works.\n\n* Menu:\n\n* General Operation:: General operation of Automake\n* Strictness:: Standards conformance checking\n* Uniform:: The Uniform Naming Scheme\n* Length Limitations:: Staying below the command line length limit\n* Canonicalization:: How derived variables are named\n* User Variables:: Variables reserved for the user\n* Auxiliary Programs:: Programs automake might require\n\nFile: automake-1.16.info, Node: General Operation, Next: Strictness, Up: Generalities\n", "subsections": [ { "name": "3.1 General Operation", "content": "Automake works by reading a 'Makefile.am' and generating a\n'Makefile.in'. Certain variables and rules defined in the 'Makefile.am'\ninstruct Automake to generate more specialized code; for instance, a\n'binPROGRAMS' variable definition will cause rules for compiling and\nlinking programs to be generated.\n\nThe variable definitions and rules in the 'Makefile.am' are copied\nmostly verbatim into the generated file, with all variable definitions\npreceding all rules. This allows you to add almost arbitrary code into\nthe generated 'Makefile.in'. For instance, the Automake distribution\nincludes a non-standard rule for the 'git-dist' target, which the\nAutomake maintainer uses to make distributions from the source control\nsystem.\n\nNote that most GNU Make extensions are not recognized by Automake.\nUsing such extensions in a 'Makefile.am' will lead to errors or\nconfusing behavior.\n\nA special exception is that the GNU Make append operator, '+=', is\nsupported. This operator appends its right hand argument to the\nvariable specified on the left. Automake will translate the operator\ninto an ordinary '=' operator; '+=' will thus work with any make\nprogram.\n\nAutomake tries to keep comments grouped with any adjoining rules or\nvariable definitions.\n\nGenerally, Automake is not particularly smart in the parsing of\nunusual Makefile constructs, so you're advised to avoid fancy constructs\nor \"creative\" use of whitespace. For example, characters cannot\nbe used between a target name and the following \"':'\" character, and\nvariable assignments shouldn't be indented with characters. Also,\nusing more complex macros in target names can cause trouble:\n\n% cat Makefile.am\n$(FOO:=x): bar\n% automake\nMakefile.am:1: bad characters in variable name '$(FOO'\nMakefile.am:1: ':='-style assignments are not portable\n\nA rule defined in 'Makefile.am' generally overrides any such rule of\na similar name that would be automatically generated by 'automake'.\nAlthough this is a supported feature, it is generally best to avoid\nmaking use of it, as sometimes the generated rules are very particular.\n\nSimilarly, a variable defined in 'Makefile.am' or 'ACSUBST'ed from\n'configure.ac' will override any definition of the variable that\n'automake' would ordinarily create. This feature is often more useful\nthan the ability to override a rule. Be warned that many of the\nvariables generated by 'automake' are considered to be for internal use\nonly, and their names might change in future releases.\n\nWhen examining a variable definition, Automake will recursively\nexamine variables referenced in the definition. For example, if\nAutomake is looking at the content of 'fooSOURCES' in this snippet\n\nxs = a.c b.c\nfooSOURCES = c.c $(xs)\n\nit would use the files 'a.c', 'b.c', and 'c.c' as the contents of\n'fooSOURCES'.\n\nAutomake also allows a form of comment that is not copied into the\noutput; all lines beginning with '##' (leading spaces allowed) are\ncompletely ignored by Automake.\n\nIt is customary to make the first line of 'Makefile.am' read:\n\n## Process this file with automake to produce Makefile.in\n\nFile: automake-1.16.info, Node: Strictness, Next: Uniform, Prev: General Operation, Up: Generalities\n" }, { "name": "3.2 Strictness", "content": "While Automake is intended to be used by maintainers of GNU packages, it\ndoes make some effort to accommodate those who wish to use it, but do\nnot want to use all the GNU conventions.\n\nTo this end, Automake supports three levels of \"strictness\"--how\nstringently Automake should enforce conformance with GNU conventions.\nEach strictness level can be selected using an option of the same name;\nsee *note Options::.\n\nThe strictness levels are:\n\n'gnu'\nThis is the default level of strictness. Automake will check for\nbasic compliance with the GNU standards for software packaging.\n*Note (standards)Top::, for full details of these standards.\nCurrently the following checks are made:\n\n* The files 'INSTALL', 'NEWS', 'README', 'AUTHORS', and\n'ChangeLog', plus one of 'COPYING.LIB', 'COPYING.LESSER' or\n'COPYING', are required at the topmost directory of the\npackage.\n\nIf the '--add-missing' option is given, 'automake' will add a\ngeneric version of the 'INSTALL' file as well as the 'COPYING'\nfile containing the text of the current version of the GNU\nGeneral Public License existing at the time of this Automake\nrelease (version 3 as this is written,\n). However, an\nexisting 'COPYING' file will never be overwritten by\n'automake'.\n\n* The options 'no-installman' and 'no-installinfo' are\nprohibited.\n\nFuture versions of Automake will add more checks at this level of\nstrictness; it is advisable to be familiar with the precise\nrequirements of the GNU standards.\n\nFuture versions of Automake may, at this level of strictness,\nrequire certain non-standard GNU tools to be available to\nmaintainer-only Makefile rules. For instance, in the future\n'pathchk' (*note (coreutils)pathchk invocation::) may be required\nto run 'make dist'.\n\n'foreign'\nAutomake will check for only those things that are absolutely\nrequired for proper operation. For instance, whereas GNU standards\ndictate the existence of a 'NEWS' file, it will not be required in\nthis mode. This strictness will also turn off some warnings by\ndefault (among them, portability warnings).\n\n'gnits'\nAutomake will check for compliance to the as-yet-unwritten \"Gnits\nstandards\". These are based on the GNU standards, but are even\nmore detailed. Unless you are a Gnits standards contributor, it is\nrecommended that you avoid this option until such time as the Gnits\nstandard is published (which is unlikely to ever happen).\n\nCurrently, '--gnits' does all the checks that '--gnu' does, and\nchecks the following as well:\n\n* 'make installcheck' will check to make sure that the '--help'\nand '--version' print a usage message and a version string,\nrespectively. This is the 'std-options' option (*note\nOptions::).\n\n* 'make dist' will check to make sure the 'NEWS' file has been\nupdated to the current version.\n\n* 'VERSION' is checked to make sure its format complies with\nGnits standards.\n\n* If 'VERSION' indicates that this is an alpha release, and the\nfile 'README-alpha' appears in the topmost directory of a\npackage, then it is included in the distribution. This is\ndone in '--gnits' mode, and no other, because this mode is the\nonly one where version number formats are constrained, and\nhence the only mode where Automake can automatically determine\nwhether 'README-alpha' should be included.\n\n* The file 'THANKS' is required.\n\nFile: automake-1.16.info, Node: Uniform, Next: Length Limitations, Prev: Strictness, Up: Generalities\n" }, { "name": "3.3 The Uniform Naming Scheme", "content": "Automake variables generally follow a \"uniform naming scheme\" that makes\nit easy to decide how programs (and other derived objects) are built,\nand how they are installed. This scheme also supports 'configure' time\ndetermination of what should be built.\n\nAt 'make' time, certain variables are used to determine which objects\nare to be built. The variable names are made of several pieces that are\nconcatenated together.\n\nThe piece that tells 'automake' what is being built is commonly\ncalled the \"primary\". For instance, the primary 'PROGRAMS' holds a list\nof programs that are to be compiled and linked.\n\nA different set of names is used to decide where the built objects\nshould be installed. These names are prefixes to the primary, and they\nindicate which standard directory should be used as the installation\ndirectory. The standard directory names are given in the GNU standards\n(*note (standards)Directory Variables::). Automake extends this list\nwith 'pkgdatadir', 'pkgincludedir', 'pkglibdir', and 'pkglibexecdir';\nthese are the same as the non-'pkg' versions, but with '$(PACKAGE)'\nappended. For instance, 'pkglibdir' is defined as\n'$(libdir)/$(PACKAGE)'.\n\nFor each primary, there is one additional variable named by\nprepending 'EXTRA' to the primary name. This variable is used to list\nobjects that may or may not be built, depending on what 'configure'\ndecides. This variable is required because Automake must statically\nknow the entire list of objects that may be built in order to generate a\n'Makefile.in' that will work in all cases.\n\nFor instance, 'cpio' decides at configure time which programs should\nbe built. Some of the programs are installed in 'bindir', and some are\ninstalled in 'sbindir':\n\nEXTRAPROGRAMS = mt rmt\nbinPROGRAMS = cpio pax\nsbinPROGRAMS = $(MOREPROGRAMS)\n\nDefining a primary without a prefix as a variable, e.g., 'PROGRAMS',\nis an error.\n\nNote that the common 'dir' suffix is left off when constructing the\nvariable names; thus one writes 'binPROGRAMS' and not\n'bindirPROGRAMS'.\n\nNot every sort of object can be installed in every directory.\nAutomake will flag those attempts it finds in error (but see below how\nto override the check if you need to). Automake will also diagnose\nobvious misspellings in directory names.\n\nSometimes the standard directories--even as augmented by Automake--are\nnot enough. In particular it is sometimes useful, for clarity, to\ninstall objects in a subdirectory of some predefined directory. To this\nend, Automake allows you to extend the list of possible installation\ndirectories. A given prefix (e.g., 'zar') is valid if a variable of the\nsame name with 'dir' appended is defined (e.g., 'zardir').\n\nFor instance, the following snippet will install 'file.xml' into\n'$(datadir)/xml'.\n\nxmldir = $(datadir)/xml\nxmlDATA = file.xml\n\nThis feature can also be used to override the sanity checks Automake\nperforms to diagnose suspicious directory/primary couples (in the\nunlikely case that you need to omit these checks). For example,\nAutomake would error out on this input:\n\n# Forbidden directory combinations, automake will error out on this.\npkglibPROGRAMS = foo\ndocLIBRARIES = libquux.a\n\nbut it will succeed with this:\n\n# Work around forbidden directory combinations. Do not use this\n# without a very good reason!\nmyexecbindir = $(pkglibdir)\nmydoclibdir = $(docdir)\nmyexecbinPROGRAMS = foo\nmydoclibLIBRARIES = libquux.a\n\nThe 'exec' substring of the 'myexecbindir' variable lets the files\nbe installed at the right time (*note The Two Parts of Install::).\n\nThe special prefix 'noinst' indicates that the objects in question\nshould be built but not installed at all. This is usually used for\nobjects required to build the rest of your package, for instance static\nlibraries (*note A Library::), or helper scripts.\n\nThe special prefix 'check' indicates that the objects in question\nshould not be built until the 'make check' command is run. Those\nobjects are not installed either.\n\nThe current primary names are 'PROGRAMS', 'LIBRARIES', 'LTLIBRARIES',\n'LISP', 'PYTHON', 'JAVA', 'SCRIPTS', 'DATA', 'HEADERS', 'MANS', and\n'TEXINFOS'.\n\nSome primaries also allow additional prefixes that control other\naspects of 'automake''s behavior. The currently defined prefixes are\n'dist', 'nodist', 'nobase', and 'notrans'. These prefixes are\nexplained later (*note Program and Library Variables::) (*note Man\nPages::).\n\nFile: automake-1.16.info, Node: Length Limitations, Next: Canonicalization, Prev: Uniform, Up: Generalities\n" }, { "name": "3.4 Staying below the command line length limit", "content": "Traditionally, most unix-like systems have a length limitation for the\ncommand line arguments and environment contents when creating new\nprocesses (see for example\n for an overview on\nthis issue), which of course also applies to commands spawned by 'make'.\nPOSIX requires this limit to be at least 4096 bytes, and most modern\nsystems have quite high limits (or are unlimited).\n\nIn order to create portable Makefiles that do not trip over these\nlimits, it is necessary to keep the length of file lists bounded.\nUnfortunately, it is not possible to do so fully transparently within\nAutomake, so your help may be needed. Typically, you can split long\nfile lists manually and use different installation directory names for\neach list. For example,\n\ndataDATA = file1 ... fileN fileN+1 ... file2N\n\nmay also be written as\n\ndataDATA = file1 ... fileN\ndata2dir = $(datadir)\ndata2DATA = fileN+1 ... file2N\n\nand will cause Automake to treat the two lists separately during 'make\ninstall'. See *note The Two Parts of Install:: for choosing directory\nnames that will keep the ordering of the two parts of installation Note\nthat 'make dist' may still only work on a host with a higher length\nlimit in this example.\n\nAutomake itself employs a couple of strategies to avoid long command\nlines. For example, when '${srcdir}/' is prepended to file names, as\ncan happen with above '$(dataDATA)' lists, it limits the amount of\narguments passed to external commands.\n\nUnfortunately, some systems' 'make' commands may prepend 'VPATH'\nprefixes like '${srcdir}/' to file names from the source tree\nautomatically (*note Automatic Rule Rewriting: (autoconf)Automatic Rule\nRewriting.). In this case, the user may have to switch to use GNU Make,\nor refrain from using VPATH builds, in order to stay below the length\nlimit.\n\nFor libraries and programs built from many sources, convenience\narchives may be used as intermediates in order to limit the object list\nlength (*note Libtool Convenience Libraries::).\n\nFile: automake-1.16.info, Node: Canonicalization, Next: User Variables, Prev: Length Limitations, Up: Generalities\n" }, { "name": "3.5 How derived variables are named", "content": "Sometimes a Makefile variable name is derived from some text the\nmaintainer supplies. For instance, a program name listed in 'PROGRAMS'\nis rewritten into the name of a 'SOURCES' variable. In cases like\nthis, Automake canonicalizes the text, so that program names and the\nlike do not have to follow Makefile variable naming rules. All\ncharacters in the name except for letters, numbers, the strudel (@), and\nthe underscore are turned into underscores when making variable\nreferences.\n\nFor example, if your program is named 'sniff-glue', the derived\nvariable name would be 'sniffglueSOURCES', not 'sniff-glueSOURCES'.\nSimilarly the sources for a library named 'libmumble++.a' should be\nlisted in the 'libmumbleaSOURCES' variable.\n\nThe strudel is an addition, to make the use of Autoconf substitutions\nin variable names less obfuscating.\n\nFile: automake-1.16.info, Node: User Variables, Next: Auxiliary Programs, Prev: Canonicalization, Up: Generalities\n" }, { "name": "3.6 Variables reserved for the user", "content": "Some 'Makefile' variables are reserved by the GNU Coding Standards for\nthe use of the \"user\"--the person building the package. For instance,\n'CFLAGS' is one such variable.\n\nSometimes package developers are tempted to set user variables such\nas 'CFLAGS' because it appears to make their job easier. However, the\npackage itself should never set a user variable, particularly not to\ninclude switches that are required for proper compilation of the\npackage. Since these variables are documented as being for the package\nbuilder, that person rightfully expects to be able to override any of\nthese variables at build time.\n\nTo get around this problem, Automake introduces an automake-specific\nshadow variable for each user flag variable. (Shadow variables are not\nintroduced for variables like 'CC', where they would make no sense.)\nThe shadow variable is named by prepending 'AM' to the user variable's\nname. For instance, the shadow variable for 'YFLAGS' is 'AMYFLAGS'.\nThe package maintainer--that is, the author(s) of the 'Makefile.am' and\n'configure.ac' files--may adjust these shadow variables however\nnecessary.\n\n*Note Flag Variables Ordering::, for more discussion about these\nvariables and how they interact with per-target variables.\n\nFile: automake-1.16.info, Node: Auxiliary Programs, Prev: User Variables, Up: Generalities\n" }, { "name": "3.7 Programs automake might require", "content": "Automake sometimes requires helper programs so that the generated\n'Makefile' can do its work properly. There are a fairly large number of\nthem, and we list them here.\n\nAlthough all of these files are distributed and installed with\nAutomake, a couple of them are maintained separately. The Automake\ncopies are updated before each release, but we mention the original\nsource in case you need more recent versions.\n\n'ar-lib'\nThis is a wrapper primarily for the Microsoft lib archiver, to make\nit more POSIX-like.\n\n'compile'\nThis is a wrapper for compilers that do not accept options '-c' and\n'-o' at the same time. It is only used when absolutely required.\nSuch compilers are rare, with the Microsoft C/C++ Compiler as the\nmost notable exception. This wrapper also makes the following\ncommon options available for that compiler, while performing file\nname translation where needed: '-I', '-L', '-l', '-Wl,' and\n'-Xlinker'.\n\n'config.guess'\n'config.sub'\nThese two programs compute the canonical triplets for the given\nbuild, host, or target architecture. These programs are updated\nregularly to support new architectures and fix probes broken by\nchanges in new kernel versions. Each new release of Automake comes\nwith up-to-date copies of these programs. If your copy of Automake\nis getting old, you are encouraged to fetch the latest versions of\nthese files from \nbefore making a release.\n\n'depcomp'\nThis program understands how to run a compiler so that it will\ngenerate not only the desired output but also dependency\ninformation that is then used by the automatic dependency tracking\nfeature (*note Dependencies::).\n\n'install-sh'\nThis is a replacement for the 'install' program that works on\nplatforms where 'install' is unavailable or unusable.\n\n'mdate-sh'\nThis script is used to generate a 'version.texi' file. It examines\na file and prints some date information about it.\n\n'missing'\nThis wraps a number of programs that are typically only required by\nmaintainers. If the program in question doesn't exist, or seems\ntoo old, 'missing' will print an informative warning before failing\nout, to provide the user with more context and information.\n\n'mkinstalldirs'\nThis script used to be a wrapper around 'mkdir -p', which is not\nportable. Now we prefer to use 'install-sh -d' when 'configure'\nfinds that 'mkdir -p' does not work, this makes one less script to\ndistribute.\n\nFor backward compatibility 'mkinstalldirs' is still used and\ndistributed when 'automake' finds it in a package. But it is no\nlonger installed automatically, and it should be safe to remove it.\n\n'py-compile'\nThis is used to byte-compile Python scripts.\n\n'test-driver'\nThis implements the default test driver offered by the parallel\ntestsuite harness.\n\n'texinfo.tex'\nWhen Texinfo sources are in the package, this file is required for\n'make dvi', 'make ps' and 'make pdf'. The latest version can be\ndownloaded from . A working\nTeX distribution, or at least a 'tex' program, is also required.\nFurthermore, 'make dist' invokes 'make dvi', so these become\nrequirements for making a distribution with Texinfo sources.\n\n'ylwrap'\nThis program wraps 'lex' and 'yacc' to rename their output files.\nIt also ensures that, for instance, multiple 'yacc' instances can\nbe invoked in a single directory in parallel.\n\nFile: automake-1.16.info, Node: Examples, Next: automake Invocation, Prev: Generalities, Up: Top\n" } ] }, "4 Some example packages": { "content": "This section contains two small examples.\n\nThe first example (*note Complete::) assumes you have an existing\nproject already using Autoconf, with handcrafted 'Makefile's, and that\nyou want to convert it to using Automake. If you are discovering both\ntools, it is probably better that you look at the Hello World example\npresented earlier (*note Hello World::).\n\nThe second example (*note true::) shows how two programs can be built\nfrom the same file, using different compilation parameters. It contains\nsome technical digressions that are probably best skipped on first read.\n\n* Menu:\n\n* Complete:: A simple example, start to finish\n* true:: Building true and false\n\nFile: automake-1.16.info, Node: Complete, Next: true, Up: Examples\n", "subsections": [ { "name": "4.1 A simple example, start to finish", "content": "Let's suppose you just finished writing 'zardoz', a program to make your\nhead float from vortex to vortex. You've been using Autoconf to provide\na portability framework, but your 'Makefile.in's have been ad-hoc. You\nwant to make them bulletproof, so you turn to Automake.\n\nThe first step is to update your 'configure.ac' to include the\ncommands that 'automake' needs. The way to do this is to add an\n'AMINITAUTOMAKE' call just after 'ACINIT':\n\nACINIT([zardoz], [1.0])\nAMINITAUTOMAKE\n...\n\nSince your program doesn't have any complicating factors (e.g., it\ndoesn't use 'gettext', it doesn't want to build a shared library),\nyou're done with this part. That was easy!\n\nNow you must regenerate 'configure'. But to do that, you'll need to\ntell 'autoconf' how to find the new macro you've used. The easiest way\nto do this is to use the 'aclocal' program to generate your 'aclocal.m4'\nfor you. But wait... maybe you already have an 'aclocal.m4', because\nyou had to write some hairy macros for your program. The 'aclocal'\nprogram lets you put your own macros into 'acinclude.m4', so simply\nrename and then run:\n\nmv aclocal.m4 acinclude.m4\naclocal\nautoconf\n\nNow it is time to write your 'Makefile.am' for 'zardoz'. Since\n'zardoz' is a user program, you want to install it where the rest of the\nuser programs go: 'bindir'. Additionally, 'zardoz' has some Texinfo\ndocumentation. Your 'configure.ac' script uses 'ACREPLACEFUNCS', so\nyou need to link against '$(LIBOBJS)'. So here's what you'd write:\n\nbinPROGRAMS = zardoz\nzardozSOURCES = main.c head.c float.c vortex9.c gun.c\nzardozLDADD = $(LIBOBJS)\n\ninfoTEXINFOS = zardoz.texi\n\nNow you can run 'automake --add-missing' to generate your\n'Makefile.in' and grab any auxiliary files you might need, and you're\ndone!\n\nFile: automake-1.16.info, Node: true, Prev: Complete, Up: Examples\n" }, { "name": "4.2 Building true and false", "content": "Here is another, trickier example. It shows how to generate two\nprograms ('true' and 'false') from the same source file ('true.c'). The\ndifficult part is that each compilation of 'true.c' requires different\n'cpp' flags.\n\nbinPROGRAMS = true false\nfalseSOURCES =\nfalseLDADD = false.o\n\ntrue.o: true.c\n$(COMPILE) -DEXITCODE=0 -c true.c\n\nfalse.o: true.c\n$(COMPILE) -DEXITCODE=1 -o false.o -c true.c\n\nNote that there is no 'trueSOURCES' definition. Automake will\nimplicitly assume that there is a source file named 'true.c' (*note\nDefault SOURCES::), and define rules to compile 'true.o' and link\n'true'. The 'true.o: true.c' rule supplied by the above 'Makefile.am',\nwill override the Automake generated rule to build 'true.o'.\n\n'falseSOURCES' is defined to be empty--that way no implicit value is\nsubstituted. Because we have not listed the source of 'false', we have\nto tell Automake how to link the program. This is the purpose of the\n'falseLDADD' line. A 'falseDEPENDENCIES' variable, holding the\ndependencies of the 'false' target will be automatically generated by\nAutomake from the content of 'falseLDADD'.\n\nThe above rules won't work if your compiler doesn't accept both '-c'\nand '-o'. The simplest fix for this is to introduce a bogus dependency\n(to avoid problems with a parallel 'make'):\n\ntrue.o: true.c false.o\n$(COMPILE) -DEXITCODE=0 -c true.c\n\nfalse.o: true.c\n$(COMPILE) -DEXITCODE=1 -c true.c && mv true.o false.o\n\nAs it turns out, there is also a much easier way to do this same\ntask. Some of the above technique is useful enough that we've kept the\nexample in the manual. However if you were to build 'true' and 'false'\nin real life, you would probably use per-program compilation flags, like\nso:\n\nbinPROGRAMS = false true\n\nfalseSOURCES = true.c\nfalseCPPFLAGS = -DEXITCODE=1\n\ntrueSOURCES = true.c\ntrueCPPFLAGS = -DEXITCODE=0\n\nIn this case Automake will cause 'true.c' to be compiled twice, with\ndifferent flags. In this instance, the names of the object files would\nbe chosen by automake; they would be 'false-true.o' and 'true-true.o'.\n(The name of the object files rarely matters.)\n\nFile: automake-1.16.info, Node: automake Invocation, Next: configure, Prev: Examples, Up: Top\n" } ] }, "5 Creating a 'Makefile.in'": { "content": "To create all the 'Makefile.in's for a package, run the 'automake'\nprogram in the top level directory, with no arguments. 'automake' will\nautomatically find each appropriate 'Makefile.am' (by scanning\n'configure.ac'; *note configure::) and generate the corresponding\n'Makefile.in'. Note that 'automake' has a rather simplistic view of\nwhat constitutes a package; it assumes that a package has only one\n'configure.ac', at the top. If your package has multiple\n'configure.ac's, then you must run 'automake' in each directory holding\na 'configure.ac'. (Alternatively, you may rely on Autoconf's\n'autoreconf', which is able to recurse your package tree and run\n'automake' where appropriate.)\n\nYou can optionally give 'automake' an argument; '.am' is appended to\nthe argument and the result is used as the name of the input file. This\nfeature is generally only used to automatically rebuild an out-of-date\n'Makefile.in'. Note that 'automake' must always be run from the topmost\ndirectory of a project, even if being used to regenerate the\n'Makefile.in' in some subdirectory. This is necessary because\n'automake' must scan 'configure.ac', and because 'automake' uses the\nknowledge that a 'Makefile.in' is in a subdirectory to change its\nbehavior in some cases.\n\nAutomake will run 'autoconf' to scan 'configure.ac' and its\ndependencies (i.e., 'aclocal.m4' and any included file), therefore\n'autoconf' must be in your 'PATH'. If there is an 'AUTOCONF' variable\nin your environment it will be used instead of 'autoconf'; this allows\nyou to select a particular version of Autoconf. By the way, don't\nmisunderstand this paragraph: 'automake' runs 'autoconf' to *scan* your\n'configure.ac'; this won't build 'configure' and you still have to run\n'autoconf' yourself for this purpose.\n\n'automake' accepts the following options:\n\n'-a'\n'--add-missing'\nAutomake requires certain common files to exist in certain\nsituations; for instance, 'config.guess' is required if\n'configure.ac' invokes 'ACCANONICALHOST'. Automake is\ndistributed with several of these files (*note Auxiliary\nPrograms::); this option will cause the missing ones to be\nautomatically added to the package, whenever possible. In general\nif Automake tells you a file is missing, try using this option. By\ndefault Automake tries to make a symbolic link pointing to its own\ncopy of the missing file; this can be changed with '--copy'.\n\nMany of the potentially-missing files are common scripts whose\nlocation may be specified via the 'ACCONFIGAUXDIR' macro.\nTherefore, 'ACCONFIGAUXDIR''s setting affects whether a file is\nconsidered missing, and where the missing file is added (*note\nOptional::).\n\nIn some strictness modes, additional files are installed, see *note\nGnits:: for more information.\n\n'--libdir=DIR'\nLook for Automake data files in directory DIR instead of in the\ninstallation directory. This is typically used for debugging.\n\nThe environment variable 'AUTOMAKELIBDIR' provides another way to\nset the directory containing Automake data files. However\n'--libdir' takes precedence over it.\n\n'--print-libdir'\nPrint the path of the installation directory containing\nAutomake-provided scripts and data files (e.g., 'texinfo.texi' and\n'install-sh').\n\n'-c'\n'--copy'\nWhen used with '--add-missing', causes installed files to be\ncopied. The default is to make a symbolic link.\n\n'-f'\n'--force-missing'\nWhen used with '--add-missing', causes standard files to be\nreinstalled even if they already exist in the source tree. This\ninvolves removing the file from the source tree before creating the\nnew symlink (or, with '--copy', copying the new file).\n\n'--foreign'\nSet the global strictness to 'foreign'. For more information, see\n*note Strictness::.\n\n'--gnits'\nSet the global strictness to 'gnits'. For more information, see\n*note Strictness::.\n\n'--gnu'\nSet the global strictness to 'gnu'. For more information, see\n*note Strictness::. This is the default strictness.\n\n'--help'\nPrint a summary of the command line options and exit.\n\n'-i'\n'--ignore-deps'\nThis disables the dependency tracking feature in generated\n'Makefile's; see *note Dependencies::.\n\n'--include-deps'\nThis enables the dependency tracking feature. This feature is\nenabled by default. This option is provided for historical reasons\nonly and probably should not be used.\n\n'--no-force'\nOrdinarily 'automake' creates all 'Makefile.in's mentioned in\n'configure.ac'. This option causes it to only update those\n'Makefile.in's that are out of date with respect to one of their\ndependents.\n\n'-o DIR'\n'--output-dir=DIR'\nPut the generated 'Makefile.in' in the directory DIR. Ordinarily\neach 'Makefile.in' is created in the directory of the corresponding\n'Makefile.am'. This option is deprecated and will be removed in a\nfuture release.\n\n'-v'\n'--verbose'\nCause Automake to print information about which files are being\nread or created.\n\n'--version'\nPrint the version number of Automake and exit.\n\n'-W CATEGORY[,CATEGORY...]'\n'--warnings=CATEGORY[,CATEGORY...]'\nOutput warnings about a CATEGORY of potential problems with the\npackage. CATEGORY can be any of:\n\n'cross'\nConstructs compromising the ability to cross-compile the\npackage.\n'gnu'\nMinor deviations from the GNU Coding Standards (*note\n(standards)Top::).\n'obsolete'\nObsolete features or constructions.\n'override'\nRedefinitions of Automake rules or variables.\n'portability'\nPortability issues (e.g., use of 'make' features that are\nknown to be not portable).\n'portability-recursive'\nRecursive, or nested, Make variable expansions ('$(foo$(x))').\nThese are not universally supported, but are more portable\nthan the other non-portable constructs diagnosed by\n'-Wportability'. These warnings are turned on by\n'-Wportability' but can then be turned off specifically by\n'-Wno-portability-recursive'.\n'extra-portability'\nExtra portability issues, related to rarely-used tools such as\nthe Microsoft 'lib' archiver.\n'syntax'\nQuestionable syntax, unused variables, typos, etc.\n'unsupported'\nUnsupported or incomplete features.\n'all'\nTurn on all the above categories of warnings.\n'none'\nTurn off all the above categories of warnings.\n'error'\nTreat warnings as errors.\n\nA category can be turned off by prefixing its name with 'no-'. For\ninstance, '-Wno-syntax' will hide the warnings about unused\nvariables.\n\nWarnings in the 'gnu', 'obsolete', 'portability', 'syntax', and\n'unsupported' categories are turned on by default. The 'gnu' and\n'portability' categories are turned off in '--foreign' strictness.\n\nTurning off 'portability' will also turn off 'extra-portability',\nand similarly turning on 'extra-portability' will also turn on\n'portability'. However, turning on 'portability' or turning off\n'extra-portability' will not affect the other category.\n\nUnknown warning categories supplied as an argument to '-W' will\nthemselves produce a warning, in the 'unsupported' category. This\nwarning is never treated as an error.\n\nThe environment variable 'WARNINGS' can contain a comma separated\nlist of categories to enable. '-W' settings on the command line\ntake precedence; for instance, '-Wnone' also turns off any warning\ncategories enabled by 'WARNINGS'.\n\nUnknown warning categories named in 'WARNINGS' are silently\nignored.\n\nIf the environment variable 'AUTOMAKEJOBS' contains a positive\nnumber, it is taken as the maximum number of Perl threads to use in\n'automake' for generating multiple 'Makefile.in' files concurrently.\nThis is an experimental feature.\n\nFile: automake-1.16.info, Node: configure, Next: Directories, Prev: automake Invocation, Up: Top\n", "subsections": [] }, "6 Scanning 'configure.ac', using 'aclocal'": { "content": "Automake scans the package's 'configure.ac' to determine certain\ninformation about the package. Some 'autoconf' macros are required and\nsome variables must be defined in 'configure.ac'. Automake will also\nuse information from 'configure.ac' to further tailor its output.\n\nAutomake also supplies some Autoconf macros to make the maintenance\neasier. These macros can automatically be put into your 'aclocal.m4'\nusing the 'aclocal' program.\n\n* Menu:\n\n* Requirements:: Configuration requirements\n* Optional:: Other things Automake recognizes\n* aclocal Invocation:: Auto-generating aclocal.m4\n* Macros:: Autoconf macros supplied with Automake\n\nFile: automake-1.16.info, Node: Requirements, Next: Optional, Up: configure\n", "subsections": [ { "name": "6.1 Configuration requirements", "content": "The one real requirement of Automake is that your 'configure.ac' call\n'AMINITAUTOMAKE'. This macro does several things that are required\nfor proper Automake operation (*note Macros::).\n\nHere are the other macros that Automake requires but which are not\nrun by 'AMINITAUTOMAKE':\n\n'ACCONFIGFILES'\n'ACOUTPUT'\nThese two macros are usually invoked as follows near the end of\n'configure.ac'.\n\n...\nACCONFIGFILES([\nMakefile\ndoc/Makefile\nsrc/Makefile\nsrc/lib/Makefile\n...\n])\nACOUTPUT\n\nAutomake uses these to determine which files to create (*note\nCreating Output Files: (autoconf)Output.). A listed file is\nconsidered to be an Automake generated 'Makefile' if there exists a\nfile with the same name and the '.am' extension appended.\nTypically, 'ACCONFIGFILES([foo/Makefile])' will cause Automake to\ngenerate 'foo/Makefile.in' if 'foo/Makefile.am' exists.\n\nWhen using 'ACCONFIGFILES' with multiple input files, as in\n\nACCONFIGFILES([Makefile:top.in:Makefile.in:bot.in])\n\n'automake' will generate the first '.in' input file for which a\n'.am' file exists. If no such file exists the output file is not\nconsidered to be generated by Automake.\n\nFiles created by 'ACCONFIGFILES', be they Automake 'Makefile's or\nnot, are all removed by 'make distclean'. Their inputs are\nautomatically distributed, unless they are the output of prior\n'ACCONFIGFILES' commands. Finally, rebuild rules are generated\nin the Automake 'Makefile' existing in the subdirectory of the\noutput file, if there is one, or in the top-level 'Makefile'\notherwise.\n\nThe above machinery (cleaning, distributing, and rebuilding) works\nfine if the 'ACCONFIGFILES' specifications contain only literals.\nIf part of the specification uses shell variables, 'automake' will\nnot be able to fulfill this setup, and you will have to complete\nthe missing bits by hand. For instance, on\n\nfile=input\n...\nACCONFIGFILES([output:$file],, [file=$file])\n\n'automake' will output rules to clean 'output', and rebuild it.\nHowever the rebuild rule will not depend on 'input', and this file\nwill not be distributed either. (You must add 'EXTRADIST = input'\nto your 'Makefile.am' if 'input' is a source file.)\n\nSimilarly\n\nfile=output\nfile2=out:in\n...\nACCONFIGFILES([$file:input],, [file=$file])\nACCONFIGFILES([$file2],, [file2=$file2])\n\nwill only cause 'input' to be distributed. No file will be cleaned\nautomatically (add 'DISTCLEANFILES = output out' yourself), and no\nrebuild rule will be output.\n\nObviously 'automake' cannot guess what value '$file' is going to\nhold later when 'configure' is run, and it cannot use the shell\nvariable '$file' in a 'Makefile'. However, if you make reference\nto '$file' as '${file}' (i.e., in a way that is compatible with\n'make''s syntax) and furthermore use 'ACSUBST' to ensure that\n'${file}' is meaningful in a 'Makefile', then 'automake' will be\nable to use '${file}' to generate all of these rules. For\ninstance, here is how the Automake package itself generates\nversioned scripts for its test suite:\n\nACSUBST([APIVERSION], ...)\n...\nACCONFIGFILES(\n[tests/aclocal-${APIVERSION}:tests/aclocal.in],\n[chmod +x tests/aclocal-${APIVERSION}],\n[APIVERSION=$APIVERSION])\nACCONFIGFILES(\n[tests/automake-${APIVERSION}:tests/automake.in],\n[chmod +x tests/automake-${APIVERSION}])\n\nHere cleaning, distributing, and rebuilding are done automatically,\nbecause '${APIVERSION}' is known at 'make'-time.\n\nNote that you should not use shell variables to declare 'Makefile'\nfiles for which 'automake' must create 'Makefile.in'. Even\n'ACSUBST' does not help here, because 'automake' needs to know the\nfile name when it runs in order to check whether 'Makefile.am'\nexists. (In the very hairy case that your setup requires such use\nof variables, you will have to tell Automake which 'Makefile.in's\nto generate on the command-line.)\n\nIt is possible to let 'automake' emit conditional rules for\n'ACCONFIGFILES' with the help of 'AMCONDIF' (*note Optional::).\n\nTo summarize:\n* Use literals for 'Makefile's, and for other files whenever\npossible.\n* Use '$file' (or '${file}' without 'ACSUBST([file])') for\nfiles that 'automake' should ignore.\n* Use '${file}' and 'ACSUBST([file])' for files that 'automake'\nshould not ignore.\n\nFile: automake-1.16.info, Node: Optional, Next: aclocal Invocation, Prev: Requirements, Up: configure\n" }, { "name": "6.2 Other things Automake recognizes", "content": "Every time Automake is run it calls Autoconf to trace 'configure.ac'.\nThis way it can recognize the use of certain macros and tailor the\ngenerated 'Makefile.in' appropriately. Currently recognized macros and\ntheir effects are:\n\n'ACCANONICALBUILD'\n'ACCANONICALHOST'\n'ACCANONICALTARGET'\nAutomake will ensure that 'config.guess' and 'config.sub' exist.\nAlso, the 'Makefile' variables 'buildtriplet', 'hosttriplet' and\n'targettriplet' are introduced. See *note Getting the Canonical\nSystem Type: (autoconf)Canonicalizing.\n\n'ACCONFIGAUXDIR'\nAutomake will look for various helper scripts, such as\n'install-sh', in the directory named in this macro invocation.\n(The full list of scripts is: 'ar-lib', 'config.guess',\n'config.sub', 'depcomp', 'compile', 'install-sh', 'ltmain.sh',\n'mdate-sh', 'missing', 'mkinstalldirs', 'py-compile',\n'test-driver', 'texinfo.tex', 'ylwrap'.) Not all scripts are\nalways searched for; some scripts will only be sought if the\ngenerated 'Makefile.in' requires them.\n\nIf 'ACCONFIGAUXDIR' is used, it must be given before the call to\n'AMINITAUTOMAKE'; Automake will warn about this if it is not so.\nAll other 'ACCONFIG...' macros are conventionally called after\n'AMINITAUTOMAKE', though they may or may not work in other\nlocations, with or without warnings.\n\nIf 'ACCONFIGAUXDIR' is not given, the scripts are looked for in\ntheir standard locations. For 'mdate-sh', 'texinfo.tex', and\n'ylwrap', the standard location is the source directory\ncorresponding to the current 'Makefile.am'. For the rest, the\nstandard location is the first one of '.', '..', or '../..'\n(relative to the top source directory) that provides any one of the\nhelper scripts. *Note Finding 'configure' Input: (autoconf)Input.\n\nRequired files from 'ACCONFIGAUXDIR' are automatically\ndistributed, even if there is no 'Makefile.am' in this directory.\n\n'ACCONFIGLIBOBJDIR'\nAutomake will require the sources file declared with 'ACLIBSOURCE'\n(see below) in the directory specified by this macro.\n\n'ACCONFIGHEADERS'\nAutomake will generate rules to rebuild these headers from the\ncorresponding templates (usually, the template for a 'foo.h' header\nbeing 'foo.h.in').\n\nAs with 'ACCONFIGFILES' (*note Requirements::), parts of the\nspecification using shell variables will be ignored as far as\ncleaning, distributing, and rebuilding is concerned.\n\nOlder versions of Automake required the use of 'AMCONFIGHEADER';\nthis is no longer the case, and that macro has indeed been removed.\n\n'ACCONFIGLINKS'\nAutomake will generate rules to remove 'configure' generated links\non 'make distclean' and to distribute named source files as part of\n'make dist'.\n\nAs with 'ACCONFIGFILES' (*note Requirements::), parts of the\nspecification using shell variables will be ignored as far as\ncleaning and distributing is concerned. (There are no rebuild\nrules for links.)\n\n'ACLIBOBJ'\n'ACLIBSOURCE'\n'ACLIBSOURCES'\nAutomake will automatically distribute any file listed in\n'ACLIBSOURCE' or 'ACLIBSOURCES'.\n\nNote that the 'ACLIBOBJ' macro calls 'ACLIBSOURCE'. So if an\nAutoconf macro is documented to call 'ACLIBOBJ([file])', then\n'file.c' will be distributed automatically by Automake. This\nencompasses many macros like 'ACFUNCALLOCA', 'ACFUNCMEMCMP',\n'ACREPLACEFUNCS', and others.\n\nBy the way, direct assignments to 'LIBOBJS' are no longer\nsupported. You should always use 'ACLIBOBJ' for this purpose.\n*Note 'ACLIBOBJ' vs. 'LIBOBJS': (autoconf)ACLIBOBJ vs LIBOBJS.\n\n'ACPROGRANLIB'\nThis is required if any libraries are built in the package. *Note\nParticular Program Checks: (autoconf)Particular Programs.\n\n'ACPROGCXX'\nThis is required if any C++ source is included. *Note Particular\nProgram Checks: (autoconf)Particular Programs.\n\n'ACPROGOBJC'\nThis is required if any Objective C source is included. *Note\nParticular Program Checks: (autoconf)Particular Programs.\n\n'ACPROGOBJCXX'\nThis is required if any Objective C++ source is included. *Note\nParticular Program Checks: (autoconf)Particular Programs.\n\n'ACPROGF77'\nThis is required if any Fortran 77 source is included. *Note\nParticular Program Checks: (autoconf)Particular Programs.\n\n'ACF77LIBRARYLDFLAGS'\nThis is required for programs and shared libraries that are a\nmixture of languages that include Fortran 77 (*note Mixing Fortran\n77 With C and C++::). *Note Autoconf macros supplied with\nAutomake: Macros.\n\n'ACFCSRCEXT'\nAutomake will add the flags computed by 'ACFCSRCEXT' to\ncompilation of files with the respective source extension (*note\nFortran Compiler Characteristics: (autoconf)Fortran Compiler.).\n\n'ACPROGFC'\nThis is required if any Fortran 90/95 source is included. This\nmacro is distributed with Autoconf version 2.58 and later. *Note\nParticular Program Checks: (autoconf)Particular Programs.\n\n'ACPROGLIBTOOL'\nAutomake will turn on processing for 'libtool' (*note Introduction:\n(libtool)Top.).\n\n'ACPROGYACC'\nIf a Yacc source file is seen, then you must either use this macro\nor define the variable 'YACC' in 'configure.ac'. The former is\npreferred (*note Particular Program Checks: (autoconf)Particular\nPrograms.).\n\n'ACPROGLEX'\nIf a Lex source file is seen, then this macro must be used. *Note\nParticular Program Checks: (autoconf)Particular Programs.\n\n'ACREQUIREAUXFILE'\nFor each 'ACREQUIREAUXFILE([FILE])', 'automake' will ensure that\n'FILE' exists in the aux directory, and will complain otherwise.\nIt will also automatically distribute the file. This macro should\nbe used by third-party Autoconf macros that require some supporting\nfiles in the aux directory specified with 'ACCONFIGAUXDIR'\nabove. *Note Finding 'configure' Input: (autoconf)Input.\n\n'ACSUBST'\nThe first argument is automatically defined as a variable in each\ngenerated 'Makefile.in', unless 'AMSUBSTNOTMAKE' is also used for\nthis variable. *Note Setting Output Variables: (autoconf)Setting\nOutput Variables.\n\nFor every substituted variable VAR, 'automake' will add a line 'VAR\n= VALUE' to each 'Makefile.in' file. Many Autoconf macros invoke\n'ACSUBST' to set output variables this way, e.g., 'ACPATHXTRA'\ndefines 'XCFLAGS' and 'XLIBS'. Thus, you can access these\nvariables as '$(XCFLAGS)' and '$(XLIBS)' in any 'Makefile.am' if\n'ACPATHXTRA' is called.\n\n'AMCONDITIONAL'\nThis introduces an Automake conditional (*note Conditionals::).\n\n'AMCONDIF'\nThis macro allows 'automake' to detect subsequent access within\n'configure.ac' to a conditional previously introduced with\n'AMCONDITIONAL', thus enabling conditional 'ACCONFIGFILES'\n(*note Usage of Conditionals::).\n\n'AMGNUGETTEXT'\nThis macro is required for packages that use GNU gettext (*note\ngettext::). It is distributed with gettext. If Automake sees this\nmacro it ensures that the package meets some of gettext's\nrequirements.\n\n'AMGNUGETTEXTINTLSUBDIR'\nThis macro specifies that the 'intl/' subdirectory is to be built,\neven if the 'AMGNUGETTEXT' macro was invoked with a first\nargument of 'external'.\n\n'AMMAINTAINERMODE([DEFAULT-MODE])'\nThis macro adds an '--enable-maintainer-mode' option to\n'configure'. If this is used, 'automake' will cause\n\"maintainer-only\" rules to be turned off by default in the\ngenerated 'Makefile.in's, unless DEFAULT-MODE is 'enable'. This\nmacro defines the 'MAINTAINERMODE' conditional, which you can use\nin your own 'Makefile.am'. *Note maintainer-mode::.\n\n'AMSUBSTNOTMAKE(VAR)'\nPrevent Automake from defining a variable VAR, even if it is\nsubstituted by 'config.status'. Normally, Automake defines a\n'make' variable for each 'configure' substitution, i.e., for each\n'ACSUBST([VAR])'. This macro prevents that definition from\nAutomake. If 'ACSUBST' has not been called for this variable,\nthen 'AMSUBSTNOTMAKE' has no effects. Preventing variable\ndefinitions may be useful for substitution of multi-line values,\nwhere 'VAR = @VALUE@' might yield unintended results.\n\n'm4include'\nFiles included by 'configure.ac' using this macro will be detected\nby Automake and automatically distributed. They will also appear\nas dependencies in 'Makefile' rules.\n\n'm4include' is seldom used by 'configure.ac' authors, but can\nappear in 'aclocal.m4' when 'aclocal' detects that some required\nmacros come from files local to your package (as opposed to macros\ninstalled in a system-wide directory; *note aclocal Invocation::).\n\nFile: automake-1.16.info, Node: aclocal Invocation, Next: Macros, Prev: Optional, Up: configure\n" }, { "name": "6.3 Auto-generating aclocal.m4", "content": "Automake includes a number of Autoconf macros that can be used in your\npackage (*note Macros::); some of them are required by Automake in\ncertain situations. These macros must be defined in your 'aclocal.m4';\notherwise they will not be seen by 'autoconf'.\n\nThe 'aclocal' program will automatically generate 'aclocal.m4' files\nbased on the contents of 'configure.ac'. This provides a convenient way\nto get Automake-provided macros, without having to search around. The\n'aclocal' mechanism allows other packages to supply their own macros\n(*note Extending aclocal::). You can also use it to maintain your own\nset of custom macros (*note Local Macros::).\n\nAt startup, 'aclocal' scans all the '.m4' files it can find, looking\nfor macro definitions (*note Macro Search Path::). Then it scans\n'configure.ac'. Any mention of one of the macros found in the first\nstep causes that macro, and any macros it in turn requires, to be put\ninto 'aclocal.m4'.\n\nPutting the file that contains the macro definition into\n'aclocal.m4' is usually done by copying the entire text of this file,\nincluding unused macro definitions as well as both '#' and 'dnl'\ncomments. If you want to make a comment that will be completely ignored\nby 'aclocal', use '##' as the comment leader.\n\nWhen a file selected by 'aclocal' is located in a subdirectory\nspecified as a relative search path with 'aclocal''s '-I' argument,\n'aclocal' assumes the file belongs to the package and uses 'm4include'\ninstead of copying it into 'aclocal.m4'. This makes the package\nsmaller, eases dependency tracking, and cause the file to be distributed\nautomatically. (*Note Local Macros::, for an example.) Any macro that\nis found in a system-wide directory or via an absolute search path will\nbe copied. So use '-I `pwd`/reldir' instead of '-I reldir' whenever\nsome relative directory should be considered outside the package.\n\nThe contents of 'acinclude.m4', if this file exists, are also\nautomatically included in 'aclocal.m4'. We recommend against using\n'acinclude.m4' in new packages (*note Local Macros::).\n\nWhile computing 'aclocal.m4', 'aclocal' runs 'autom4te' (*note Using\n'Autom4te': (autoconf)Using autom4te.) in order to trace the macros that\nare used, and omit from 'aclocal.m4' all macros that are mentioned but\notherwise unexpanded (this can happen when a macro is called\nconditionally). 'autom4te' is expected to be in the 'PATH', just as\n'autoconf'. Its location can be overridden using the 'AUTOM4TE'\nenvironment variable.\n\n* Menu:\n\n* aclocal Options:: Options supported by aclocal\n* Macro Search Path:: How aclocal finds .m4 files\n* Extending aclocal:: Writing your own aclocal macros\n* Local Macros:: Organizing local macros\n* Serials:: Serial lines in Autoconf macros\n* Future of aclocal:: aclocal's scheduled death\n\nFile: automake-1.16.info, Node: aclocal Options, Next: Macro Search Path, Up: aclocal Invocation\n\n\n'aclocal' accepts the following options:\n\n'--automake-acdir=DIR'\nLook for the automake-provided macro files in DIR instead of in the\ninstallation directory. This is typically used for debugging.\n\nThe environment variable 'ACLOCALAUTOMAKEDIR' provides another\nway to set the directory containing automake-provided macro files.\nHowever '--automake-acdir' takes precedence over it.\n\n'--system-acdir=DIR'\nLook for the system-wide third-party macro files (and the special\n'dirlist' file) in DIR instead of in the installation directory.\nThis is typically used for debugging.\n\n'--diff[=COMMAND]'\nRun COMMAND on the M4 file that would be installed or overwritten\nby '--install'. The default COMMAND is 'diff -u'. This option\nimplies '--install' and '--dry-run'.\n\n'--dry-run'\nDo not overwrite (or create) 'aclocal.m4' and M4 files installed by\n'--install'.\n\n'--help'\nPrint a summary of the command line options and exit.\n\n'-I DIR'\nAdd the directory DIR to the list of directories searched for '.m4'\nfiles.\n\n'--install'\nInstall system-wide third-party macros into the first directory\nspecified with '-I DIR' instead of copying them in the output file.\nNote that this will happen also if DIR is an absolute path.\n\nWhen this option is used, and only when this option is used,\n'aclocal' will also honor '#serial NUMBER' lines that appear in\nmacros: an M4 file is ignored if there exists another M4 file with\nthe same basename and a greater serial number in the search path\n(*note Serials::).\n\n'--force'\nAlways overwrite the output file. The default is to overwrite the\noutput file only when needed, i.e., when its contents change or if\none of its dependencies is younger.\n\nThis option forces the update of 'aclocal.m4' (or the file\nspecified with '--output' below) and only this file, it has\nabsolutely no influence on files that may need to be installed by\n'--install'.\n\n'--output=FILE'\nCause the output to be put into FILE instead of 'aclocal.m4'.\n\n'--print-ac-dir'\nPrints the name of the directory that 'aclocal' will search to find\nthird-party '.m4' files. When this option is given, normal\nprocessing is suppressed. This option was used in the past by\nthird-party packages to determine where to install '.m4' macro\nfiles, but this usage is today discouraged, since it causes\n'$(prefix)' not to be thoroughly honored (which violates the GNU\nCoding Standards), and similar semantics can be better obtained\nwith the 'ACLOCALPATH' environment variable; *note Extending\naclocal::.\n\n'--verbose'\nPrint the names of the files it examines.\n\n'--version'\nPrint the version number of Automake and exit.\n\n'-W CATEGORY'\n'--warnings=CATEGORY'\nOutput warnings falling in CATEGORY. CATEGORY can be one of:\n'syntax'\ndubious syntactic constructs, underquoted macros, unused\nmacros, etc.\n'unsupported'\nunknown macros\n'all'\nall the warnings, this is the default\n'none'\nturn off all the warnings\n'error'\ntreat warnings as errors\n\nAll warnings are output by default.\n\nThe environment variable 'WARNINGS' is honored in the same way as\nit is for 'automake' (*note automake Invocation::).\n\nFile: automake-1.16.info, Node: Macro Search Path, Next: Extending aclocal, Prev: aclocal Options, Up: aclocal Invocation\n\n\nBy default, 'aclocal' searches for '.m4' files in the following\ndirectories, in this order:\n\n'ACDIR-APIVERSION'\nThis is where the '.m4' macros distributed with Automake itself are\nstored. APIVERSION depends on the Automake release used; for\nexample, for Automake 1.11.x, APIVERSION = '1.11'.\n\n'ACDIR'\nThis directory is intended for third party '.m4' files, and is\nconfigured when 'automake' itself is built. This is\n'@datadir@/aclocal/', which typically expands to\n'${prefix}/share/aclocal/'. To find the compiled-in value of\nACDIR, use the '--print-ac-dir' option (*note aclocal Options::).\n\nAs an example, suppose that 'automake-1.11.2' was configured with\n'--prefix=/usr/local'. Then, the search path would be:\n\n1. '/usr/local/share/aclocal-1.11.2/'\n2. '/usr/local/share/aclocal/'\n\nThe paths for the ACDIR and ACDIR-APIVERSION directories can be\nchanged respectively through aclocal options '--system-acdir' and\n'--automake-acdir' (*note aclocal Options::). Note however that these\noptions are only intended for use by the internal Automake test suite,\nor for debugging under highly unusual situations; they are not\nordinarily needed by end-users.\n\nAs explained in (*note aclocal Options::), there are several options\nthat can be used to change or extend this search path.\n\nModifying the Macro Search Path: '-I DIR'\n.........................................\n\nAny extra directories specified using '-I' options (*note aclocal\nOptions::) are prepended to this search list. Thus, 'aclocal -I /foo\n-I /bar' results in the following search path:\n\n1. '/foo'\n2. '/bar'\n3. ACDIR-APIVERSION\n4. ACDIR\n\nModifying the Macro Search Path: 'dirlist'\n..........................................\n\nThere is a third mechanism for customizing the search path. If a\n'dirlist' file exists in ACDIR, then that file is assumed to contain a\nlist of directory patterns, one per line. 'aclocal' expands these\npatterns to directory names, and adds them to the search list after\nall other directories. 'dirlist' entries may use shell wildcards such\nas '*', '?', or '[...]'.\n\nFor example, suppose 'ACDIR/dirlist' contains the following:\n\n/test1\n/test2\n/test3*\n\nand that 'aclocal' was called with the '-I /foo -I /bar' options. Then,\nthe search path would be\n\n1. '/foo'\n2. '/bar'\n3. ACDIR-APIVERSION\n4. ACDIR\n5. '/test1'\n6. '/test2'\n\nand all directories with path names starting with '/test3'.\n\nIf the '--system-acdir=DIR' option is used, then 'aclocal' will\nsearch for the 'dirlist' file in DIR; but remember the warnings above\nagainst the use of '--system-acdir'.\n\n'dirlist' is useful in the following situation: suppose that\n'automake' version '1.11.2' is installed with '--prefix=/usr' by the\nsystem vendor. Thus, the default search directories are\n\n1. '/usr/share/aclocal-1.11/'\n2. '/usr/share/aclocal/'\n\nHowever, suppose further that many packages have been manually\ninstalled on the system, with $prefix=/usr/local, as is typical. In\nthat case, many of these \"extra\" '.m4' files are in\n'/usr/local/share/aclocal'. The only way to force '/usr/bin/aclocal' to\nfind these \"extra\" '.m4' files is to always call 'aclocal -I\n/usr/local/share/aclocal'. This is inconvenient. With 'dirlist', one\nmay create a file '/usr/share/aclocal/dirlist' containing only the\nsingle line\n\n/usr/local/share/aclocal\n\nNow, the \"default\" search path on the affected system is\n\n1. '/usr/share/aclocal-1.11/'\n2. '/usr/share/aclocal/'\n3. '/usr/local/share/aclocal/'\n\nwithout the need for '-I' options; '-I' options can be reserved for\nproject-specific needs ('my-source-dir/m4/'), rather than using them to\nwork around local system-dependent tool installation directories.\n\nSimilarly, 'dirlist' can be handy if you have installed a local copy\nof Automake in your account and want 'aclocal' to look for macros\ninstalled at other places on the system.\n\nModifying the Macro Search Path: 'ACLOCALPATH'\n...............................................\n\nThe fourth and last mechanism to customize the macro search path is also\nthe simplest. Any directory included in the colon-separated environment\nvariable 'ACLOCALPATH' is added to the search path and takes precedence\nover system directories (including those found via 'dirlist'), with the\nexception of the versioned directory ACDIR-APIVERSION (*note Macro\nSearch Path::). However, directories passed via '-I' will take\nprecedence over directories in 'ACLOCALPATH'.\n\nAlso note that, if the '--install' option is used, any '.m4' file\ncontaining a required macro that is found in a directory listed in\n'ACLOCALPATH' will be installed locally. In this case, serial numbers\nin '.m4' are honored too, *note Serials::.\n\nConversely to 'dirlist', 'ACLOCALPATH' is useful if you are using a\nglobal copy of Automake and want 'aclocal' to look for macros somewhere\nunder your home directory.\n\nPlanned future incompatibilities\n................................\n\nThe order in which the directories in the macro search path are\ncurrently looked up is confusing and/or suboptimal in various aspects,\nand is probably going to be changed in the future Automake release. In\nparticular, directories in 'ACLOCALPATH' and 'ACDIR' might end up\ntaking precedence over 'ACDIR-APIVERSION', and directories in\n'ACDIR/dirlist' might end up taking precedence over 'ACDIR'. This is a\npossible future incompatibility!\n\nFile: automake-1.16.info, Node: Extending aclocal, Next: Local Macros, Prev: Macro Search Path, Up: aclocal Invocation\n\n\nThe 'aclocal' program doesn't have any built-in knowledge of any macros,\nso it is easy to extend it with your own macros.\n\nThis can be used by libraries that want to supply their own Autoconf\nmacros for use by other programs. For instance, the 'gettext' library\nsupplies a macro 'AMGNUGETTEXT' that should be used by any package\nusing 'gettext'. When the library is installed, it installs this macro\nso that 'aclocal' will find it.\n\nA macro file's name should end in '.m4'. Such files should be\ninstalled in '$(datadir)/aclocal'. This is as simple as writing:\n\naclocaldir = $(datadir)/aclocal\naclocalDATA = mymacro.m4 myothermacro.m4\n\nPlease do use '$(datadir)/aclocal', and not something based on the\nresult of 'aclocal --print-ac-dir' (*note Hard-Coded Install Paths::,\nfor arguments). It might also be helpful to suggest to the user to add\nthe '$(datadir)/aclocal' directory to his 'ACLOCALPATH' variable (*note\nACLOCALPATH::) so that 'aclocal' will find the '.m4' files installed by\nyour package automatically.\n\nA file of macros should be a series of properly quoted 'ACDEFUN''s\n(*note (autoconf)Macro Definitions::). The 'aclocal' programs also\nunderstands 'ACREQUIRE' (*note (autoconf)Prerequisite Macros::), so it\nis safe to put each macro in a separate file. Each file should have no\nside effects but macro definitions. Especially, any call to 'ACPREREQ'\nshould be done inside the defined macro, not at the beginning of the\nfile.\n\nStarting with Automake 1.8, 'aclocal' warns about all underquoted\ncalls to 'ACDEFUN'. We realize this annoys some people, because\n'aclocal' was not so strict in the past and many third party macros are\nunderquoted; and we have to apologize for this temporary inconvenience.\nThe reason we have to be stricter is that a future implementation of\n'aclocal' (*note Future of aclocal::) will have to temporarily include\nall of these third party '.m4' files, maybe several times, even\nincluding files that end up not being needed. Doing so should alleviate\nmany problems of the current implementation; however, it requires a\nstricter style from macro authors. Hopefully it is easy to revise the\nexisting macros. For instance,\n\n# bad style\nACPREREQ(2.68)\nACDEFUN(AXFOOBAR,\n[ACREQUIRE([AXSOMETHING])dnl\nAXFOO\nAXBAR\n])\n\nshould be rewritten as\n\nACDEFUN([AXFOOBAR],\n[ACPREREQ([2.68])dnl\nACREQUIRE([AXSOMETHING])dnl\nAXFOO\nAXBAR\n])\n\nWrapping the 'ACPREREQ' call inside the macro ensures that Autoconf\n2.68 will not be required if 'AXFOOBAR' is not used. Most importantly,\nquoting the first argument of 'ACDEFUN' allows the macro to be\nredefined or included twice (otherwise this first argument would be\nexpanded during the second definition). For consistency we like to\nquote even arguments such as '2.68' that do not require it.\n\nIf you have been directed here by the 'aclocal' diagnostic but are\nnot the maintainer of the implicated macro, you will want to contact the\nmaintainer of that macro. Please make sure you have the latest version\nof the macro and that the problem hasn't already been reported before\ndoing so: people tend to work faster when they aren't flooded by mails.\n\nAnother situation where 'aclocal' is commonly used is to manage\nmacros that are used locally by the package; *note Local Macros::.\n\nFile: automake-1.16.info, Node: Local Macros, Next: Serials, Prev: Extending aclocal, Up: aclocal Invocation\n\n\nFeature tests offered by Autoconf do not cover all needs. People often\nhave to supplement existing tests with their own macros, or with\nthird-party macros.\n\nThere are two ways to organize custom macros in a package.\n\nThe first possibility (the historical practice) is to list all your\nmacros in 'acinclude.m4'. This file will be included in 'aclocal.m4'\nwhen you run 'aclocal', and its macro(s) will henceforth be visible to\n'autoconf'. However if it contains numerous macros, it will rapidly\nbecome difficult to maintain, and it will be almost impossible to share\nmacros between packages.\n\nThe second possibility, which we do recommend, is to write each macro\nin its own file and gather all these files in a directory. This\ndirectory is usually called 'm4/'. Then it's enough to update\n'configure.ac' by adding a proper call to 'ACCONFIGMACRODIRS':\n\nACCONFIGMACRODIRS([m4])\n\n'aclocal' will then take care of automatically adding 'm4/' to its\nsearch path for m4 files.\n\nWhen 'aclocal' is run, it will build an 'aclocal.m4' that\n'm4include's any file from 'm4/' that defines a required macro. Macros\nnot found locally will still be searched in system-wide directories, as\nexplained in *note Macro Search Path::.\n\nCustom macros should be distributed for the same reason that\n'configure.ac' is: so that other people have all the sources of your\npackage if they want to work on it. In fact, this distribution happens\nautomatically because all 'm4include'd files are distributed.\n\nHowever there is no consensus on the distribution of third-party\nmacros that your package may use. Many libraries install their own\nmacro in the system-wide 'aclocal' directory (*note Extending\naclocal::). For instance, Guile ships with a file called 'guile.m4'\nthat contains the macro 'GUILEFLAGS' that can be used to define setup\ncompiler and linker flags appropriate for using Guile. Using\n'GUILEFLAGS' in 'configure.ac' will cause 'aclocal' to copy 'guile.m4'\ninto 'aclocal.m4', but as 'guile.m4' is not part of the project, it will\nnot be distributed. Technically, that means a user who needs to rebuild\n'aclocal.m4' will have to install Guile first. This is probably OK, if\nGuile already is a requirement to build the package. However, if Guile\nis only an optional feature, or if your package might run on\narchitectures where Guile cannot be installed, this requirement will\nhinder development. An easy solution is to copy such third-party macros\nin your local 'm4/' directory so they get distributed.\n\nSince Automake 1.10, 'aclocal' offers the option '--install' to copy\nthese system-wide third-party macros in your local macro directory,\nhelping to solve the above problem.\n\nWith this setup, system-wide macros will be copied to 'm4/' the first\ntime you run 'aclocal'. Then the locally installed macros will have\nprecedence over the system-wide installed macros each time 'aclocal' is\nrun again.\n\nOne reason why you should keep '--install' in the flags even after\nthe first run is that when you later edit 'configure.ac' and depend on a\nnew macro, this macro will be installed in your 'm4/' automatically.\nAnother one is that serial numbers (*note Serials::) can be used to\nupdate the macros in your source tree automatically when new system-wide\nversions are installed. A serial number should be a single line of the\nform\n\n#serial NNN\n\nwhere NNN contains only digits and dots. It should appear in the M4\nfile before any macro definition. It is a good practice to maintain a\nserial number for each macro you distribute, even if you do not use the\n'--install' option of 'aclocal': this allows other people to use it.\n\nFile: automake-1.16.info, Node: Serials, Next: Future of aclocal, Prev: Local Macros, Up: aclocal Invocation\n\n\nBecause third-party macros defined in '*.m4' files are naturally shared\nbetween multiple projects, some people like to version them. This makes\nit easier to tell which of two M4 files is newer. Since at least 1996,\nthe tradition is to use a '#serial' line for this.\n\nA serial number should be a single line of the form\n\n# serial VERSION\n\nwhere VERSION is a version number containing only digits and dots.\nUsually people use a single integer, and they increment it each time\nthey change the macro (hence the name of \"serial\"). Such a line should\nappear in the M4 file before any macro definition.\n\nThe '#' must be the first character on the line, and it is OK to have\nextra words after the version, as in\n\n#serial VERSION GARBAGE\n\nNormally these serial numbers are completely ignored by 'aclocal' and\n'autoconf', like any genuine comment. However when using 'aclocal''s\n'--install' feature, these serial numbers will modify the way 'aclocal'\nselects the macros to install in the package: if two files with the same\nbasename exist in your search path, and if at least one of them uses a\n'#serial' line, 'aclocal' will ignore the file that has the older\n'#serial' line (or the file that has none).\n\nNote that a serial number applies to a whole M4 file, not to any\nmacro it contains. A file can contain multiple macros, but only one\nserial.\n\nHere is a use case that illustrates the use of '--install' and its\ninteraction with serial numbers. Let's assume we maintain a package\ncalled MyPackage, the 'configure.ac' of which requires a third-party\nmacro 'AXTHIRDPARTY' defined in '/usr/share/aclocal/thirdparty.m4' as\nfollows:\n\n# serial 1\nACDEFUN([AXTHIRDPARTY], [...])\n\nMyPackage uses an 'm4/' directory to store local macros as explained\nin *note Local Macros::, and has\n\nACCONFIGMACRODIRS([m4])\n\nin its 'configure.ac'.\n\nInitially the 'm4/' directory is empty. The first time we run\n'aclocal --install', it will notice that\n\n* 'configure.ac' uses 'AXTHIRDPARTY'\n* No local macros define 'AXTHIRDPARTY'\n* '/usr/share/aclocal/thirdparty.m4' defines 'AXTHIRDPARTY' with\nserial number 1.\n\nBecause '/usr/share/aclocal/thirdparty.m4' is a system-wide macro and\n'aclocal' was given the '--install' option, it will copy this file in\n'm4/thirdparty.m4', and output an 'aclocal.m4' that contains\n'm4include([m4/thirdparty.m4])'.\n\nThe next time 'aclocal --install' is run, something different\nhappens. 'aclocal' notices that\n\n* 'configure.ac' uses 'AXTHIRDPARTY'\n* 'm4/thirdparty.m4' defines 'AXTHIRDPARTY' with serial number 1.\n* '/usr/share/aclocal/thirdparty.m4' defines 'AXTHIRDPARTY' with\nserial number 1.\n\nBecause both files have the same serial number, 'aclocal' uses the first\nit found in its search path order (*note Macro Search Path::).\n'aclocal' therefore ignores '/usr/share/aclocal/thirdparty.m4' and\noutputs an 'aclocal.m4' that contains 'm4include([m4/thirdparty.m4])'.\n\nLocal directories specified with '-I' are always searched before\nsystem-wide directories, so a local file will always be preferred to the\nsystem-wide file in case of equal serial numbers.\n\nNow suppose the system-wide third-party macro is changed. This can\nhappen if the package installing this macro is updated. Let's suppose\nthe new macro has serial number 2. The next time 'aclocal --install' is\nrun the situation is the following:\n\n* 'configure.ac' uses 'AXTHIRDPARTY'\n* 'm4/thirdparty.m4' defines 'AXTHIRDPARTY' with serial number 1.\n* '/usr/share/aclocal/thirdparty.m4' defines 'AXTHIRDPARTY' with\nserial 2.\n\nWhen 'aclocal' sees a greater serial number, it immediately forgets\nanything it knows from files that have the same basename and a smaller\nserial number. So after it has found '/usr/share/aclocal/thirdparty.m4'\nwith serial 2, 'aclocal' will proceed as if it had never seen\n'm4/thirdparty.m4'. This brings us back to a situation similar to that\nat the beginning of our example, where no local file defined the macro.\n'aclocal' will install the new version of the macro in\n'm4/thirdparty.m4', in this case overriding the old version. MyPackage\njust had its macro updated as a side effect of running 'aclocal'.\n\nIf you are leery of letting 'aclocal' update your local macro, you\ncan run 'aclocal --diff' to review the changes 'aclocal --install' would\nperform on these macros.\n\nFinally, note that the '--force' option of 'aclocal' has absolutely\nno effect on the files installed by '--install'. For instance, if you\nhave modified your local macros, do not expect '--install --force' to\nreplace the local macros by their system-wide versions. If you want to\ndo so, simply erase the local macros you want to revert, and run\n'aclocal --install'.\n\nFile: automake-1.16.info, Node: Future of aclocal, Prev: Serials, Up: aclocal Invocation\n\n\nIdeally, 'aclocal' should not be part of Automake. Automake should\nfocus on generating 'Makefile's; dealing with M4 macros is more\nAutoconf's job. The fact that some people install Automake just to use\n'aclocal', but do not use 'automake' otherwise is an indication of how\nthat feature is misplaced.\n\nThe new implementation will probably be done slightly differently.\nFor instance, it could enforce the 'm4/'-style layout discussed in *note\nLocal Macros::.\n\nWe have no idea when and how this will happen. This has been\ndiscussed several times in the past, but someone still has to commit to\nthat non-trivial task.\n\nFrom the user point of view, 'aclocal''s removal might turn out to be\npainful. There is a simple precaution that you may take to make that\nswitch more seamless: never call 'aclocal' yourself. Keep this guy\nunder the exclusive control of 'autoreconf' and Automake's rebuild\nrules. Hopefully you won't need to worry about things breaking; when\n'aclocal' disappears, because everything will have been taken care of.\nIf otherwise you used to call 'aclocal' directly yourself or from some\nscript, you will quickly notice the change.\n\nMany packages come with a script called 'bootstrap' or 'autogen.sh',\nthat will just call 'aclocal', 'libtoolize', 'gettextize' or\n'autopoint', 'autoconf', 'autoheader', and 'automake' in the right\norder. In fact, this is precisely what 'autoreconf' can do for you. If\nyour package has such a 'bootstrap' or 'autogen.sh' script, consider\nusing 'autoreconf'. That should simplify its logic a lot (less things\nto maintain, all to the good), it's even likely you will not need the\nscript anymore, and more to the point you will not call 'aclocal'\ndirectly anymore.\n\nFor the time being, third-party packages should continue to install\npublic macros into '/usr/share/aclocal/'. If 'aclocal' is replaced by\nanother tool it might make sense to rename the directory, but supporting\n'/usr/share/aclocal/' for backward compatibility should be easy provided\nall macros are properly written (*note Extending aclocal::).\n\nFile: automake-1.16.info, Node: Macros, Prev: aclocal Invocation, Up: configure\n" }, { "name": "6.4 Autoconf macros supplied with Automake", "content": "Automake ships with several Autoconf macros that you can use from your\n'configure.ac'. When you use one of them it will be included by\n'aclocal' in 'aclocal.m4'.\n\n* Menu:\n\n* Public Macros:: Macros that you can use.\n* Obsolete Macros:: Macros that will soon be removed.\n* Private Macros:: Macros that you should not use.\n\nFile: automake-1.16.info, Node: Public Macros, Next: Obsolete Macros, Up: Macros\n\n\n'AMINITAUTOMAKE([OPTIONS])'\nRuns many macros required for proper operation of the generated\nMakefiles.\n\nToday, 'AMINITAUTOMAKE' is called with a single argument: a\nspace-separated list of Automake options that should be applied to\nevery 'Makefile.am' in the tree. The effect is as if each option\nwere listed in 'AUTOMAKEOPTIONS' (*note Options::).\n\nThis macro can also be called in another, deprecated form:\n'AMINITAUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])'. In this form,\nthere are two required arguments: the package and the version\nnumber. This usage is mostly obsolete because the PACKAGE and\nVERSION can be obtained from Autoconf's 'ACINIT' macro. However,\ndifferently from what happens for 'ACINIT' invocations, this\n'AMINITAUTOMAKE' invocation supports shell variables' expansions\nin the 'PACKAGE' and 'VERSION' arguments (which otherwise defaults,\nrespectively, to the 'PACKAGETARNAME' and 'PACKAGEVERSION'\ndefined via the 'ACINIT' invocation; *note The 'ACINIT' macro:\n(autoconf)ACINIT.); and this can still be useful in some selected\nsituations. Our hope is that future Autoconf versions will improve\ntheir support for package versions defined dynamically at configure\nruntime; when (and if) this happens, support for the two-args\n'AMINITAUTOMAKE' invocation will likely be removed from Automake.\n\nIf your 'configure.ac' has:\n\nACINIT([src/foo.c])\nAMINITAUTOMAKE([mumble], [1.5])\n\nyou should modernize it as follows:\n\nACINIT([mumble], [1.5])\nACCONFIGSRCDIR([src/foo.c])\nAMINITAUTOMAKE\n\nNote that if you're upgrading your 'configure.ac' from an earlier\nversion of Automake, it is not always correct to simply move the\npackage and version arguments from 'AMINITAUTOMAKE' directly to\n'ACINIT', as in the example above. The first argument to\n'ACINIT' should be the name of your package (e.g., 'GNU\nAutomake'), not the tarball name (e.g., 'automake') that you used\nto pass to 'AMINITAUTOMAKE'. Autoconf tries to derive a tarball\nname from the package name, which should work for most but not all\npackage names. (If it doesn't work for yours, you can use the\nfour-argument form of 'ACINIT' to provide the tarball name\nexplicitly).\n\nBy default this macro 'ACDEFINE''s 'PACKAGE' and 'VERSION'. This\ncan be avoided by passing the 'no-define' option (*note List of\nAutomake options::):\nAMINITAUTOMAKE([no-define ...])\n\n'AMPATHLISPDIR'\nSearches for the program 'emacs', and, if found, sets the output\nvariable 'lispdir' to the full path to Emacs' site-lisp directory.\n\nNote that this test assumes the 'emacs' found to be a version that\nsupports Emacs Lisp (such as GNU Emacs or XEmacs). Other emacsen\ncan cause this test to hang (some, like old versions of MicroEmacs,\nstart up in interactive mode, requiring 'C-x C-c' to exit, which is\nhardly obvious for a non-emacs user). In most cases, however, you\nshould be able to use 'C-c' to kill the test. In order to avoid\nproblems, you can set 'EMACS' to \"no\" in the environment, or use\nthe '--with-lispdir' option to 'configure' to explicitly set the\ncorrect path (if you're sure you have an 'emacs' that supports\nEmacs Lisp).\n\n'AMPROGAR([ACT-IF-FAIL])'\nYou must use this macro when you use the archiver in your project,\nif you want support for unusual archivers such as Microsoft 'lib'.\nThe content of the optional argument is executed if the archiver\ninterface is not recognized; the default action is to abort\nconfigure with an error message.\n\n'AMPROGAS'\nUse this macro when you have assembly code in your project. This\nwill choose the assembler for you (by default the C compiler) and\nset 'CCAS', and will also set 'CCASFLAGS' if required.\n\n'AMPROGCCCO'\nThis is an obsolescent macro that checks that the C compiler\nsupports the '-c' and '-o' options together. Note that, since\nAutomake 1.14, the 'ACPROGCC' is rewritten to implement such\nchecks itself, and thus the explicit use of 'AMPROGCCCO' should\nno longer be required.\n\n'AMPROGLEX'\nLike 'ACPROGLEX' (*note Particular Program Checks:\n(autoconf)Particular Programs.), but uses the 'missing' script on\nsystems that do not have 'lex'. HP-UX 10 is one such system.\n\n'AMPROGGCJ'\nThis macro finds the 'gcj' program or causes an error. It sets\n'GCJ' and 'GCJFLAGS'. 'gcj' is the Java front-end to the GNU\nCompiler Collection.\n\n'AMPROGUPC([COMPILER-SEARCH-LIST])'\nFind a compiler for Unified Parallel C and define the 'UPC'\nvariable. The default COMPILER-SEARCH-LIST is 'upcc upc'. This\nmacro will abort 'configure' if no Unified Parallel C compiler is\nfound.\n\n'AMMISSINGPROG(NAME, PROGRAM)'\nFind a maintainer tool PROGRAM and define the NAME environment\nvariable with its location. If PROGRAM is not detected, then NAME\nwill instead invoke the 'missing' script, in order to give useful\nadvice to the user about the missing maintainer tool. *Note\nmaintainer-mode::, for more information on when the 'missing'\nscript is appropriate.\n\n'AMSILENTRULES'\nControl the machinery for less verbose build output (*note Automake\nSilent Rules::).\n\n'AMWITHDMALLOC'\nAdd support for the Dmalloc package (https://dmalloc.com/). If the\nuser runs 'configure' with '--with-dmalloc', then define\n'WITHDMALLOC' and add '-ldmalloc' to 'LIBS'.\n\nFile: automake-1.16.info, Node: Obsolete Macros, Next: Private Macros, Prev: Public Macros, Up: Macros\n\n\nAlthough using some of the following macros was required in past\nreleases, you should not use any of them in new code. All these macros\nwill be removed in the next major Automake version; if you are still\nusing them, running 'autoupdate' should adjust your 'configure.ac'\nautomatically (*note Using 'autoupdate' to Modernize 'configure.ac':\n(autoconf)autoupdate Invocation.). Do it NOW!\n\n'AMPROGMKDIRP'\n\nFrom Automake 1.8 to 1.9.6 this macro used to define the output\nvariable 'mkdirp' to one of 'mkdir -p', 'install-sh -d', or\n'mkinstalldirs'.\n\nNowadays Autoconf provides a similar functionality with\n'ACPROGMKDIRP' (*note Particular Program Checks:\n(autoconf)Particular Programs.), however this defines the output\nvariable 'MKDIRP' instead. In case you are still using the\n'AMPROGMKDIRP' macro in your 'configure.ac', or its provided\nvariable '$(mkdirp)' in your 'Makefile.am', you are advised to\nswitch ASAP to the more modern Autoconf-provided interface instead;\nboth the macro and the variable might be removed in a future major\nAutomake release.\n\nFile: automake-1.16.info, Node: Private Macros, Prev: Obsolete Macros, Up: Macros\n\n\nThe following macros are private macros you should not call directly.\nThey are called by the other public macros when appropriate. Do not\nrely on them, as they might be changed in a future version. Consider\nthem as implementation details; or better, do not consider them at all:\nskip this section!\n\n'AMDEPENDENCIES'\n'AMSETDEPDIR'\n'AMDEPTRACK'\n'AMOUTPUTDEPENDENCYCOMMANDS'\nThese macros are used to implement Automake's automatic dependency\ntracking scheme. They are called automatically by Automake when\nrequired, and there should be no need to invoke them manually.\n\n'AMMAKEINCLUDE'\nThis macro is used to discover how the user's 'make' handles\n'include' statements. This macro is automatically invoked when\nneeded; there should be no need to invoke it manually.\n\n'AMPROGINSTALLSTRIP'\nThis is used to find a version of 'install' that can be used to\nstrip a program at installation time. This macro is automatically\nincluded when required.\n\n'AMSANITYCHECK'\nThis checks to make sure that a file created in the build directory\nis newer than a file in the source directory. This can fail on\nsystems where the clock is set incorrectly. This macro is\nautomatically run from 'AMINITAUTOMAKE'.\n\nFile: automake-1.16.info, Node: Directories, Next: Programs, Prev: configure, Up: Top\n" } ] }, "7 Directories": { "content": "For simple projects that distribute all files in the same directory it\nis enough to have a single 'Makefile.am' that builds everything in\nplace.\n\nIn larger projects, it is common to organize files in different\ndirectories, in a tree. For example, there could be a directory for the\nprogram's source, one for the testsuite, and one for the documentation;\nor, for very large projects, there could be one directory per program,\nper library or per module.\n\nThe traditional approach is to build these subdirectories\nrecursively, employing make recursion: each directory contains its own\n'Makefile', and when 'make' is run from the top-level directory, it\nenters each subdirectory in turn, and invokes there a new 'make'\ninstance to build the directory's contents.\n\nBecause this approach is very widespread, Automake offers built-in\nsupport for it. However, it is worth noting that the use of make\nrecursion has its own serious issues and drawbacks, and that it's well\npossible to have packages with a multi directory layout that make little\nor no use of such recursion (examples of such packages are GNU Bison and\nGNU Automake itself); see also the *note Alternative:: section below.\n\n* Menu:\n\n* Subdirectories:: Building subdirectories recursively\n* Conditional Subdirectories:: Conditionally not building directories\n* Alternative:: Subdirectories without recursion\n* Subpackages:: Nesting packages\n\nFile: automake-1.16.info, Node: Subdirectories, Next: Conditional Subdirectories, Up: Directories\n", "subsections": [ { "name": "7.1 Recursing subdirectories", "content": "In packages using make recursion, the top level 'Makefile.am' must tell\nAutomake which subdirectories are to be built. This is done via the\n'SUBDIRS' variable.\n\nThe 'SUBDIRS' variable holds a list of subdirectories in which\nbuilding of various sorts can occur. The rules for many targets (e.g.,\n'all') in the generated 'Makefile' will run commands both locally and in\nall specified subdirectories. Note that the directories listed in\n'SUBDIRS' are not required to contain 'Makefile.am's; only 'Makefile's\n(after configuration). This allows inclusion of libraries from packages\nthat do not use Automake (such as 'gettext'; see also *note Third-Party\nMakefiles::).\n\nIn packages that use subdirectories, the top-level 'Makefile.am' is\noften very short. For instance, here is the 'Makefile.am' from the GNU\nHello distribution:\n\nEXTRADIST = BUGS ChangeLog.O README-alpha\nSUBDIRS = doc intl po src tests\n\nWhen Automake invokes 'make' in a subdirectory, it uses the value of\nthe 'MAKE' variable. It passes the value of the variable 'AMMAKEFLAGS'\nto the 'make' invocation; this can be set in 'Makefile.am' if there are\nflags you must always pass to 'make'.\n\nThe directories mentioned in 'SUBDIRS' are usually direct children of\nthe current directory, each subdirectory containing its own\n'Makefile.am' with a 'SUBDIRS' pointing to deeper subdirectories.\nAutomake can be used to construct packages of arbitrary depth this way.\n\nBy default, Automake generates 'Makefiles' that work depth-first in\npostfix order: the subdirectories are built before the current\ndirectory. However, it is possible to change this ordering. You can do\nthis by putting '.' into 'SUBDIRS'. For instance, putting '.' first\nwill cause a prefix ordering of directories.\n\nUsing\n\nSUBDIRS = lib src . test\n\nwill cause 'lib/' to be built before 'src/', then the current directory\nwill be built, finally the 'test/' directory will be built. It is\ncustomary to arrange test directories to be built after everything else\nsince they are meant to test what has been constructed.\n\nIn addition to the built-in recursive targets defined by Automake\n('all', 'check', etc.), the developer can also define his own recursive\ntargets. That is done by passing the names of such targets as arguments\nto the m4 macro 'AMEXTRARECURSIVETARGETS' in 'configure.ac'.\nAutomake generates rules to handle the recursion for such targets; and\nthe developer can define real actions for them by defining corresponding\n'-local' targets.\n\n% cat configure.ac\nACINIT([pkg-name], [1.0])\nAMINITAUTOMAKE\nAMEXTRARECURSIVETARGETS([foo])\nACCONFIGFILES([Makefile sub/Makefile sub/src/Makefile])\nACOUTPUT\n% cat Makefile.am\nSUBDIRS = sub\nfoo-local:\n@echo This will be run by \"make foo\".\n% cat sub/Makefile.am\nSUBDIRS = src\n% cat sub/src/Makefile.am\nfoo-local:\n@echo This too will be run by a \"make foo\" issued either in\n@echo the 'sub/src/' directory, the 'sub/' directory, or the\n@echo top-level directory.\n\nFile: automake-1.16.info, Node: Conditional Subdirectories, Next: Alternative, Prev: Subdirectories, Up: Directories\n" }, { "name": "7.2 Conditional Subdirectories", "content": "It is possible to define the 'SUBDIRS' variable conditionally if, like\nin the case of GNU Inetutils, you want to only build a subset of the\nentire package.\n\nTo illustrate how this works, let's assume we have two directories,\n'src/' and 'opt/'. 'src/' should always be built, but we want to decide\nin 'configure' whether 'opt/' will be built or not. (For this example\nwe will assume that 'opt/' should be built when the variable '$wantopt'\nwas set to 'yes'.)\n\nRunning 'make' should thus recurse into 'src/' always, and then maybe\nin 'opt/'.\n\nHowever 'make dist' should always recurse into both 'src/' and\n'opt/', because 'opt/' should be distributed even if it is not needed in\nthe current configuration. This means 'opt/Makefile' should be created\nunconditionally.\n\nThere are two ways to set up a project like this. You can use\nAutomake conditionals (*note Conditionals::) or use Autoconf 'ACSUBST'\nvariables (*note Setting Output Variables: (autoconf)Setting Output\nVariables.). Using Automake conditionals is the preferred solution.\nBefore we illustrate these two possibilities, let's introduce\n'DISTSUBDIRS'.\n\n* Menu:\n\n* SUBDIRS vs DISTSUBDIRS:: Two sets of directories\n* Subdirectories with AMCONDITIONAL:: Specifying conditional subdirectories\n* Subdirectories with ACSUBST:: Another way for conditional recursion\n* Unconfigured Subdirectories:: Not even creating a 'Makefile'\n\nFile: automake-1.16.info, Node: SUBDIRS vs DISTSUBDIRS, Next: Subdirectories with AMCONDITIONAL, Up: Conditional Subdirectories\n\n\nAutomake considers two sets of directories, defined by the variables\n'SUBDIRS' and 'DISTSUBDIRS'.\n\n'SUBDIRS' contains the subdirectories of the current directory that\nmust be built (*note Subdirectories::). It must be defined manually;\nAutomake will never guess a directory is to be built. As we will see in\nthe next two sections, it is possible to define it conditionally so that\nsome directory will be omitted from the build.\n\n'DISTSUBDIRS' is used in rules that need to recurse in all\ndirectories, even those that have been conditionally left out of the\nbuild. Recall our example where we may not want to build subdirectory\n'opt/', but yet we want to distribute it? This is where 'DISTSUBDIRS'\ncomes into play: 'opt' may not appear in 'SUBDIRS', but it must appear\nin 'DISTSUBDIRS'.\n\nPrecisely, 'DISTSUBDIRS' is used by 'make maintainer-clean', 'make\ndistclean' and 'make dist'. All other recursive rules use 'SUBDIRS'.\n\nIf 'SUBDIRS' is defined conditionally using Automake conditionals,\nAutomake will define 'DISTSUBDIRS' automatically from the possible\nvalues of 'SUBDIRS' in all conditions.\n\nIf 'SUBDIRS' contains 'ACSUBST' variables, 'DISTSUBDIRS' will not\nbe defined correctly because Automake does not know the possible values\nof these variables. In this case 'DISTSUBDIRS' needs to be defined\nmanually.\n\nFile: automake-1.16.info, Node: Subdirectories with AMCONDITIONAL, Next: Subdirectories with ACSUBST, Prev: SUBDIRS vs DISTSUBDIRS, Up: Conditional Subdirectories\n\n\n'configure' should output the 'Makefile' for each directory and define a\ncondition into which 'opt/' should be built.\n\n...\nAMCONDITIONAL([CONDOPT], [test \"$wantopt\" = yes])\nACCONFIGFILES([Makefile src/Makefile opt/Makefile])\n...\n\nThen 'SUBDIRS' can be defined in the top-level 'Makefile.am' as\nfollows.\n\nif CONDOPT\nMAYBEOPT = opt\nendif\nSUBDIRS = src $(MAYBEOPT)\n\nAs you can see, running 'make' will rightly recurse into 'src/' and\nmaybe 'opt/'.\n\nAs you can't see, running 'make dist' will recurse into both 'src/'\nand 'opt/' directories because 'make dist', unlike 'make all', doesn't\nuse the 'SUBDIRS' variable. It uses the 'DISTSUBDIRS' variable.\n\nIn this case Automake will define 'DISTSUBDIRS = src opt'\nautomatically because it knows that 'MAYBEOPT' can contain 'opt' in\nsome condition.\n\nFile: automake-1.16.info, Node: Subdirectories with ACSUBST, Next: Unconfigured Subdirectories, Prev: Subdirectories with AMCONDITIONAL, Up: Conditional Subdirectories\n\n\nAnother possibility is to define 'MAYBEOPT' from './configure' using\n'ACSUBST':\n\n...\nif test \"$wantopt\" = yes; then\nMAYBEOPT=opt\nelse\nMAYBEOPT=\nfi\nACSUBST([MAYBEOPT])\nACCONFIGFILES([Makefile src/Makefile opt/Makefile])\n...\n\nIn this case the top-level 'Makefile.am' should look as follows.\n\nSUBDIRS = src $(MAYBEOPT)\nDISTSUBDIRS = src opt\n\nThe drawback is that since Automake cannot guess what the possible\nvalues of 'MAYBEOPT' are, it is necessary to define 'DISTSUBDIRS'.\n\nFile: automake-1.16.info, Node: Unconfigured Subdirectories, Prev: Subdirectories with ACSUBST, Up: Conditional Subdirectories\n\n\nThe semantics of 'DISTSUBDIRS' are often misunderstood by some users\nthat try to configure and build subdirectories conditionally. Here by\nconfiguring we mean creating the 'Makefile' (it might also involve\nrunning a nested 'configure' script: this is a costly operation that\nexplains why people want to do it conditionally, but only the 'Makefile'\nis relevant to the discussion).\n\nThe above examples all assume that every 'Makefile' is created, even\nin directories that are not going to be built. The simple reason is\nthat we want 'make dist' to distribute even the directories that are not\nbeing built (e.g., platform-dependent code), hence 'make dist' must\nrecurse into the subdirectory, hence this directory must be configured\nand appear in 'DISTSUBDIRS'.\n\nBuilding packages that do not configure every subdirectory is a\ntricky business, and we do not recommend it to the novice as it is easy\nto produce an incomplete tarball by mistake. We will not discuss this\ntopic in depth here, yet for the adventurous here are a few rules to\nremember.\n\n* 'SUBDIRS' should always be a subset of 'DISTSUBDIRS'.\n\nIt makes little sense to have a directory in 'SUBDIRS' that is not\nin 'DISTSUBDIRS'. Think of the former as a way to tell which\ndirectories listed in the latter should be built.\n* Any directory listed in 'DISTSUBDIRS' and 'SUBDIRS' must be\nconfigured.\n\nThat is, the 'Makefile' must exist or the recursive 'make' rules\nwill not be able to process the directory.\n* Any configured directory must be listed in 'DISTSUBDIRS'.\n\nThis is so the cleaning rules remove the generated 'Makefile's. It\nwould be correct to see 'DISTSUBDIRS' as a variable that lists all\nthe directories that have been configured.\n\nIn order to prevent recursion in some unconfigured directory you must\ntherefore ensure that this directory does not appear in 'DISTSUBDIRS'\n(and 'SUBDIRS'). For instance, if you define 'SUBDIRS' conditionally\nusing 'ACSUBST' and do not define 'DISTSUBDIRS' explicitly, it will be\ndefault to '$(SUBDIRS)'; another possibility is to force 'DISTSUBDIRS =\n$(SUBDIRS)'.\n\nOf course, directories that are omitted from 'DISTSUBDIRS' will not\nbe distributed unless you make other arrangements for this to happen\n(for instance, always running 'make dist' in a configuration where all\ndirectories are known to appear in 'DISTSUBDIRS'; or writing a\n'dist-hook' target to distribute these directories).\n\nIn a few packages, unconfigured directories are not even expected to\nbe distributed. Although these packages do not require the\naforementioned extra arrangements, there is another pitfall. If the\nname of a directory appears in 'SUBDIRS' or 'DISTSUBDIRS', 'automake'\nwill make sure the directory exists. Consequently 'automake' cannot be\nrun on such a distribution when one directory has been omitted. One way\nto avoid this check is to use the 'ACSUBST' method to declare\nconditional directories; since 'automake' does not know the values of\n'ACSUBST' variables it cannot ensure the corresponding directory\nexists.\n\nFile: automake-1.16.info, Node: Alternative, Next: Subpackages, Prev: Conditional Subdirectories, Up: Directories\n" }, { "name": "7.3 An Alternative Approach to Subdirectories", "content": "If you've ever read Peter Miller's excellent paper, 'Recursive Make\nConsidered Harmful', the preceding sections on the use of make recursion\nwill probably come as unwelcome advice. For those who haven't read the\npaper, Miller's main thesis is that recursive 'make' invocations are\nboth slow and error-prone.\n\nAutomake is intended to have sufficient cross-directory support to\nenable you to write a single 'Makefile.am' for a complex multi-directory\npackage. (If it seems to be lacking, please report the issue as usual.)\n\nBy default an installable file specified in a subdirectory will have\nits directory name stripped before installation. For instance, in this\nexample, the header file will be installed as '$(includedir)/stdio.h':\n\nincludeHEADERS = inc/stdio.h\n\nHowever, the 'nobase' prefix can be used to circumvent this path\nstripping. In this example, the header file will be installed as\n'$(includedir)/sys/types.h':\n\nnobaseincludeHEADERS = sys/types.h\n\n'nobase' should be specified first when used in conjunction with\neither 'dist' or 'nodist' (*note Fine-grained Distribution Control::).\nFor instance:\n\nnobasedistpkgdataDATA = images/vortex.pgm sounds/whirl.ogg\n\nFinally, note that a variable using the 'nobase' prefix can often be\nreplaced by several variables, one for each destination directory (*note\nUniform::). For instance, the last example could be rewritten as\nfollows:\n\nimagesdir = $(pkgdatadir)/images\nsoundsdir = $(pkgdatadir)/sounds\ndistimagesDATA = images/vortex.pgm\ndistsoundsDATA = sounds/whirl.ogg\n\nThis latter syntax makes it possible to change one destination directory\nwithout changing the layout of the source tree.\n\nCurrently, 'nobase*LTLIBRARIES' are the only exception to this\nrule, in that there is no particular installation order guarantee for an\notherwise equivalent set of variables without 'nobase' prefix.\n\nFile: automake-1.16.info, Node: Subpackages, Prev: Alternative, Up: Directories\n" }, { "name": "7.4 Nesting Packages", "content": "In the GNU Build System, packages can be nested to arbitrary depth.\nThis means that a package can embed other packages with their own\n'configure', 'Makefile's, etc.\n\nThese other packages should just appear as subdirectories of their\nparent package. They must be listed in 'SUBDIRS' like other ordinary\ndirectories. However the subpackage's 'Makefile's should be output by\nits own 'configure' script, not by the parent's 'configure'. This is\nachieved using the 'ACCONFIGSUBDIRS' Autoconf macro (*note\nACCONFIGSUBDIRS: (autoconf)Subdirectories.).\n\nHere is an example package for an 'arm' program that links with a\n'hand' library that is a nested package in subdirectory 'hand/'.\n\n'arm''s 'configure.ac':\n\nACINIT([arm], [1.0])\nACCONFIGAUXDIR([.])\nAMINITAUTOMAKE\nACPROGCC\nACCONFIGFILES([Makefile])\n# Call hand's ./configure script recursively.\nACCONFIGSUBDIRS([hand])\nACOUTPUT\n\n'arm''s 'Makefile.am':\n\n# Build the library in the hand subdirectory first.\nSUBDIRS = hand\n\n# Include hand's header when compiling this directory.\nAMCPPFLAGS = -I$(srcdir)/hand\n\nbinPROGRAMS = arm\narmSOURCES = arm.c\n# link with the hand library.\narmLDADD = hand/libhand.a\n\nNow here is 'hand''s 'hand/configure.ac':\n\nACINIT([hand], [1.2])\nACCONFIGAUXDIR([.])\nAMINITAUTOMAKE\nACPROGCC\nAMPROGAR\nACPROGRANLIB\nACCONFIGFILES([Makefile])\nACOUTPUT\n\nand its 'hand/Makefile.am':\n\nlibLIBRARIES = libhand.a\nlibhandaSOURCES = hand.c\n\nWhen 'make dist' is run from the top-level directory it will create\nan archive 'arm-1.0.tar.gz' that contains the 'arm' code as well as the\n'hand' subdirectory. This package can be built and installed like any\nordinary package, with the usual './configure && make && make install'\nsequence (the 'hand' subpackage will be built and installed by the\nprocess).\n\nWhen 'make dist' is run from the hand directory, it will create a\nself-contained 'hand-1.2.tar.gz' archive. So although it appears to be\nembedded in another package, it can still be used separately.\n\nThe purpose of the 'ACCONFIGAUXDIR([.])' instruction is to force\nAutomake and Autoconf to search for auxiliary scripts in the current\ndirectory. For instance, this means that there will be two copies of\n'install-sh': one in the top-level of the 'arm' package, and another one\nin the 'hand/' subdirectory for the 'hand' package.\n\nThe historical default is to search for these auxiliary scripts in\nthe parent directory and the grandparent directory. So if the\n'ACCONFIGAUXDIR([.])' line was removed from 'hand/configure.ac', that\nsubpackage would share the auxiliary script of the 'arm' package. This\nmay look like a gain in size (a few kilobytes), but more importantly, it\nis a loss of modularity as the 'hand' subpackage is no longer\nself-contained ('make dist' in the subdirectory will not work anymore).\n\nPackages that do not use Automake need more work to be integrated\nthis way. *Note Third-Party Makefiles::.\n\nFile: automake-1.16.info, Node: Programs, Next: Other Objects, Prev: Directories, Up: Top\n" } ] }, "8 Building Programs and Libraries": { "content": "A large part of Automake's functionality is dedicated to making it easy\nto build programs and libraries.\n\n* Menu:\n\n* A Program:: Building a program\n* A Library:: Building a library\n* A Shared Library:: Building a Libtool library\n* Program and Library Variables:: Variables controlling program and\nlibrary builds\n* Default SOURCES:: Default source files\n* LIBOBJS:: Special handling for LIBOBJS and ALLOCA\n* Program Variables:: Variables used when building a program\n* Yacc and Lex:: Yacc and Lex support\n* C++ Support:: Compiling C++ sources\n* Objective C Support:: Compiling Objective C sources\n* Objective C++ Support:: Compiling Objective C++ sources\n* Unified Parallel C Support:: Compiling Unified Parallel C sources\n* Assembly Support:: Compiling assembly sources\n* Fortran 77 Support:: Compiling Fortran 77 sources\n* Fortran 9x Support:: Compiling Fortran 9x sources\n* Java Support with gcj:: Compiling Java sources using gcj\n* Vala Support:: Compiling Vala sources\n* Support for Other Languages:: Compiling other languages\n* Dependencies:: Automatic dependency tracking\n* EXEEXT:: Support for executable extensions\n\nFile: automake-1.16.info, Node: A Program, Next: A Library, Up: Programs\n", "subsections": [ { "name": "8.1 Building a program", "content": "In order to build a program, you need to tell Automake which sources are\npart of it, and which libraries it should be linked with.\n\nThis section also covers conditional compilation of sources or\nprograms. Most of the comments about these also apply to libraries\n(*note A Library::) and libtool libraries (*note A Shared Library::).\n\n* Menu:\n\n* Program Sources:: Defining program sources\n* Linking:: Linking with libraries or extra objects\n* Conditional Sources:: Handling conditional sources\n* Conditional Programs:: Building a program conditionally\n\nFile: automake-1.16.info, Node: Program Sources, Next: Linking, Up: A Program\n\n\nIn a directory containing source that gets built into a program (as\nopposed to a library or a script), the 'PROGRAMS' primary is used.\nPrograms can be installed in 'bindir', 'sbindir', 'libexecdir',\n'pkglibexecdir', or not at all ('noinst'). They can also be built only\nfor 'make check', in which case the prefix is 'check'.\n\nFor instance:\n\nbinPROGRAMS = hello\n\nIn this simple case, the resulting 'Makefile.in' will contain code to\ngenerate a program named 'hello'.\n\nAssociated with each program are several assisting variables that are\nnamed after the program. These variables are all optional, and have\nreasonable defaults. Each variable, its use, and default is spelled out\nbelow; we use the \"hello\" example throughout.\n\nThe variable 'helloSOURCES' is used to specify which source files\nget built into an executable:\n\nhelloSOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h\n\nThis causes each mentioned '.c' file to be compiled into the\ncorresponding '.o'. Then all are linked to produce 'hello'.\n\nIf 'helloSOURCES' is not specified, then it defaults to the single\nfile 'hello.c' (*note Default SOURCES::).\n\nMultiple programs can be built in a single directory. Multiple\nprograms can share a single source file, which must be listed in each\n'SOURCES' definition.\n\nHeader files listed in a 'SOURCES' definition will be included in\nthe distribution but otherwise ignored. In case it isn't obvious, you\nshould not include the header file generated by 'configure' in a\n'SOURCES' variable; this file should not be distributed. Lex ('.l')\nand Yacc ('.y') files can also be listed; see *note Yacc and Lex::.\n\nFile: automake-1.16.info, Node: Linking, Next: Conditional Sources, Prev: Program Sources, Up: A Program\n\n\nIf you need to link against libraries that are not found by 'configure',\nyou can use 'LDADD' to do so. This variable is used to specify\nadditional objects or libraries to link with; it is inappropriate for\nspecifying specific linker flags; you should use 'AMLDFLAGS' for this\npurpose.\n\nSometimes, multiple programs are built in one directory but do not\nshare the same link-time requirements. In this case, you can use the\n'PROGLDADD' variable (where PROG is the name of the program as it\nappears in some 'PROGRAMS' variable, and usually written in lowercase)\nto override 'LDADD'. If this variable exists for a given program, then\nthat program is not linked using 'LDADD'.\n\nFor instance, in GNU cpio, 'pax', 'cpio' and 'mt' are linked against\nthe library 'libcpio.a'. However, 'rmt' is built in the same directory,\nand has no such link requirement. Also, 'mt' and 'rmt' are only built\non certain architectures. Here is what cpio's 'src/Makefile.am' looks\nlike (abridged):\n\nbinPROGRAMS = cpio pax $(MT)\nlibexecPROGRAMS = $(RMT)\nEXTRAPROGRAMS = mt rmt\n\nLDADD = ../lib/libcpio.a $(INTLLIBS)\nrmtLDADD =\n\ncpioSOURCES = ...\npaxSOURCES = ...\nmtSOURCES = ...\nrmtSOURCES = ...\n\n'PROGLDADD' is inappropriate for passing program-specific linker\nflags (except for '-l', '-L', '-dlopen' and '-dlpreopen'). So, use the\n'PROGLDFLAGS' variable for this purpose.\n\nIt is also occasionally useful to have a program depend on some other\ntarget that is not in fact part of that program. This can be done using\neither the 'PROGDEPENDENCIES' or the 'EXTRAPROGDEPENDENCIES'\nvariable. Each program depends on the contents both variables, but no\nfurther interpretation is done.\n\nSince these dependencies are associated to the link rule used to\ncreate the programs they should normally list files used by the link\ncommand. That is '*.$(OBJEXT)', '*.a', or '*.la' files. In rare cases\nyou may need to add other kinds of files such as linker scripts, but\nlisting a source file in 'DEPENDENCIES' is wrong. If some source\nfile needs to be built before all the components of a program are built,\nconsider using the 'BUILTSOURCES' variable instead (*note Sources::).\n\nIf 'PROGDEPENDENCIES' is not supplied, it is computed by Automake.\nThe automatically-assigned value is the contents of 'PROGLDADD', with\nmost configure substitutions, '-l', '-L', '-dlopen' and '-dlpreopen'\noptions removed. The configure substitutions that are left in are only\n'$(LIBOBJS)' and '$(ALLOCA)'; these are left because it is known that\nthey will not cause an invalid value for 'PROGDEPENDENCIES' to be\ngenerated.\n\n*note Conditional Sources:: shows a situation where 'DEPENDENCIES'\nmay be used.\n\nThe 'EXTRAPROGDEPENDENCIES' may be useful for cases where you\nmerely want to augment the 'automake'-generated 'PROGDEPENDENCIES'\nrather than replacing it.\n\nWe recommend that you avoid using '-l' options in 'LDADD' or\n'PROGLDADD' when referring to libraries built by your package.\nInstead, write the file name of the library explicitly as in the above\n'cpio' example. Use '-l' only to list third-party libraries. If you\nfollow this rule, the default value of 'PROGDEPENDENCIES' will list all\nyour local libraries and omit the other ones.\n\nFile: automake-1.16.info, Node: Conditional Sources, Next: Conditional Programs, Prev: Linking, Up: A Program\n\n\nYou can't put a configure substitution (e.g., '@FOO@' or '$(FOO)' where\n'FOO' is defined via 'ACSUBST') into a 'SOURCES' variable. The reason\nfor this is a bit hard to explain, but suffice to say that it simply\nwon't work. Automake will give an error if you try to do this.\n\nFortunately there are two other ways to achieve the same result. One\nis to use configure substitutions in 'LDADD' variables, the other is to\nuse an Automake conditional.\n\nConditional Compilation using 'LDADD' Substitutions\n....................................................\n\nAutomake must know all the source files that could possibly go into a\nprogram, even if not all the files are built in every circumstance. Any\nfiles that are only conditionally built should be listed in the\nappropriate 'EXTRA' variable. For instance, if 'hello-linux.c' or\n'hello-generic.c' were conditionally included in 'hello', the\n'Makefile.am' would contain:\n\nbinPROGRAMS = hello\nhelloSOURCES = hello-common.c\nEXTRAhelloSOURCES = hello-linux.c hello-generic.c\nhelloLDADD = $(HELLOSYSTEM)\nhelloDEPENDENCIES = $(HELLOSYSTEM)\n\nYou can then set up the '$(HELLOSYSTEM)' substitution from\n'configure.ac':\n\n...\ncase $host in\n*linux*) HELLOSYSTEM='hello-linux.$(OBJEXT)' ;;\n*) HELLOSYSTEM='hello-generic.$(OBJEXT)' ;;\nesac\nACSUBST([HELLOSYSTEM])\n...\n\nIn this case, the variable 'HELLOSYSTEM' should be replaced by\neither 'hello-linux.o' or 'hello-generic.o', and added to both\n'helloDEPENDENCIES' and 'helloLDADD' in order to be built and linked\nin.\n\nConditional Compilation using Automake Conditionals\n...................................................\n\nAn often simpler way to compile source files conditionally is to use\nAutomake conditionals. For instance, you could use this 'Makefile.am'\nconstruct to build the same 'hello' example:\n\nbinPROGRAMS = hello\nif LINUX\nhelloSOURCES = hello-linux.c hello-common.c\nelse\nhelloSOURCES = hello-generic.c hello-common.c\nendif\n\nIn this case, 'configure.ac' should set up the 'LINUX' conditional\nusing 'AMCONDITIONAL' (*note Conditionals::).\n\nWhen using conditionals like this you don't need to use the 'EXTRA'\nvariable, because Automake will examine the contents of each variable to\nconstruct the complete list of source files.\n\nIf your program uses a lot of files, you will probably prefer a\nconditional '+='.\n\nbinPROGRAMS = hello\nhelloSOURCES = hello-common.c\nif LINUX\nhelloSOURCES += hello-linux.c\nelse\nhelloSOURCES += hello-generic.c\nendif\n\nFile: automake-1.16.info, Node: Conditional Programs, Prev: Conditional Sources, Up: A Program\n\n\nSometimes it is useful to determine the programs that are to be built at\nconfigure time. For instance, GNU 'cpio' only builds 'mt' and 'rmt'\nunder special circumstances. The means to achieve conditional\ncompilation of programs are the same you can use to compile source files\nconditionally: substitutions or conditionals.\n\nConditional Programs using 'configure' Substitutions\n....................................................\n\nIn this case, you must notify Automake of all the programs that can\npossibly be built, but at the same time cause the generated\n'Makefile.in' to use the programs specified by 'configure'. This is\ndone by having 'configure' substitute values into each 'PROGRAMS'\ndefinition, while listing all optionally built programs in\n'EXTRAPROGRAMS'.\n\nbinPROGRAMS = cpio pax $(MT)\nlibexecPROGRAMS = $(RMT)\nEXTRAPROGRAMS = mt rmt\n\nAs explained in *note EXEEXT::, Automake will rewrite 'binPROGRAMS',\n'libexecPROGRAMS', and 'EXTRAPROGRAMS', appending '$(EXEEXT)' to each\nbinary. Obviously it cannot rewrite values obtained at run-time through\n'configure' substitutions, therefore you should take care of appending\n'$(EXEEXT)' yourself, as in 'ACSUBST([MT], ['mt${EXEEXT}'])'.\n\nConditional Programs using Automake Conditionals\n................................................\n\nYou can also use Automake conditionals (*note Conditionals::) to select\nprograms to be built. In this case you don't have to worry about\n'$(EXEEXT)' or 'EXTRAPROGRAMS'.\n\nbinPROGRAMS = cpio pax\nif WANTMT\nbinPROGRAMS += mt\nendif\nif WANTRMT\nlibexecPROGRAMS = rmt\nendif\n\nFile: automake-1.16.info, Node: A Library, Next: A Shared Library, Prev: A Program, Up: Programs\n" }, { "name": "8.2 Building a library", "content": "Building a library is much like building a program. In this case, the\nname of the primary is 'LIBRARIES'. Libraries can be installed in\n'libdir' or 'pkglibdir'.\n\n*Note A Shared Library::, for information on how to build shared\nlibraries using libtool and the 'LTLIBRARIES' primary.\n\nEach 'LIBRARIES' variable is a list of the libraries to be built.\nFor instance, to create a library named 'libcpio.a', but not install it,\nyou would write:\n\nnoinstLIBRARIES = libcpio.a\nlibcpioaSOURCES = ...\n\nThe sources that go into a library are determined exactly as they are\nfor programs, via the 'SOURCES' variables. Note that the library name\nis canonicalized (*note Canonicalization::), so the 'SOURCES' variable\ncorresponding to 'libcpio.a' is 'libcpioaSOURCES', not\n'libcpio.aSOURCES'.\n\nExtra objects can be added to a library using the 'LIBRARYLIBADD'\nvariable. This should be used for objects determined by 'configure'.\nAgain from 'cpio':\n\nlibcpioaLIBADD = $(LIBOBJS) $(ALLOCA)\n\nIn addition, sources for extra objects that will not exist until\nconfigure-time must be added to the 'BUILTSOURCES' variable (*note\nSources::).\n\nBuilding a static library is done by compiling all object files, then\nby invoking '$(AR) $(ARFLAGS)' followed by the name of the library and\nthe list of objects, and finally by calling '$(RANLIB)' on that library.\nYou should call 'ACPROGRANLIB' from your 'configure.ac' to define\n'RANLIB' (Automake will complain otherwise). You should also call\n'AMPROGAR' to define 'AR', in order to support unusual archivers such\nas Microsoft lib. 'ARFLAGS' will default to 'cru'; you can override\nthis variable by setting it in your 'Makefile.am' or by 'ACSUBST'ing it\nfrom your 'configure.ac'. You can override the 'AR' variable by\ndefining a per-library 'maudeAR' variable (*note Program and Library\nVariables::).\n\nBe careful when selecting library components conditionally. Because\nbuilding an empty library is not portable, you should ensure that any\nlibrary always contains at least one object.\n\nTo use a static library when building a program, add it to 'LDADD'\nfor this program. In the following example, the program 'cpio' is\nstatically linked with the library 'libcpio.a'.\n\nnoinstLIBRARIES = libcpio.a\nlibcpioaSOURCES = ...\n\nbinPROGRAMS = cpio\ncpioSOURCES = cpio.c ...\ncpioLDADD = libcpio.a\n\nFile: automake-1.16.info, Node: A Shared Library, Next: Program and Library Variables, Prev: A Library, Up: Programs\n" }, { "name": "8.3 Building a Shared Library", "content": "Building shared libraries portably is a relatively complex matter. For\nthis reason, GNU Libtool (*note Introduction: (libtool)Top.) was created\nto help build shared libraries in a platform-independent way.\n\n* Menu:\n\n* Libtool Concept:: Introducing Libtool\n* Libtool Libraries:: Declaring Libtool Libraries\n* Conditional Libtool Libraries:: Building Libtool Libraries Conditionally\n* Conditional Libtool Sources:: Choosing Library Sources Conditionally\n* Libtool Convenience Libraries:: Building Convenience Libtool Libraries\n* Libtool Modules:: Building Libtool Modules\n* Libtool Flags:: Using LIBADD, LDFLAGS, and LIBTOOLFLAGS\n* LTLIBOBJS:: Using $(LTLIBOBJS) and $(LTALLOCA)\n* Libtool Issues:: Common Issues Related to Libtool's Use\n\nFile: automake-1.16.info, Node: Libtool Concept, Next: Libtool Libraries, Up: A Shared Library\n\n\nLibtool abstracts shared and static libraries into a unified concept\nhenceforth called \"libtool libraries\". Libtool libraries are files\nusing the '.la' suffix, and can designate a static library, a shared\nlibrary, or maybe both. Their exact nature cannot be determined until\n'./configure' is run: not all platforms support all kinds of libraries,\nand users can explicitly select which libraries should be built.\n(However the package's maintainers can tune the default; *note The\n'LTINIT' macro: (libtool)LTINIT.)\n\nBecause object files for shared and static libraries must be compiled\ndifferently, libtool is also used during compilation. Object files\nbuilt by libtool are called \"libtool objects\": these are files using the\n'.lo' suffix. Libtool libraries are built from these libtool objects.\n\nYou should not assume anything about the structure of '.la' or '.lo'\nfiles and how libtool constructs them: this is libtool's concern, and\nthe last thing one wants is to learn about libtool's guts. However the\nexistence of these files matters, because they are used as targets and\ndependencies in 'Makefile's' rules when building libtool libraries.\nThere are situations where you may have to refer to these, for instance\nwhen expressing dependencies for building source files conditionally\n(*note Conditional Libtool Sources::).\n\nPeople considering writing a plug-in system, with dynamically loaded\nmodules, should look into 'libltdl': libtool's dlopening library (*note\nUsing libltdl: (libtool)Using libltdl.). This offers a portable\ndlopening facility to load libtool libraries dynamically, and can also\nachieve static linking where unavoidable.\n\nBefore we discuss how to use libtool with Automake in detail, it\nshould be noted that the libtool manual also has a section about how to\nuse Automake with libtool (*note Using Automake with Libtool:\n(libtool)Using Automake.).\n\nFile: automake-1.16.info, Node: Libtool Libraries, Next: Conditional Libtool Libraries, Prev: Libtool Concept, Up: A Shared Library\n\n\nAutomake uses libtool to build libraries declared with the 'LTLIBRARIES'\nprimary. Each 'LTLIBRARIES' variable is a list of libtool libraries to\nbuild. For instance, to create a libtool library named 'libgettext.la',\nand install it in 'libdir', write:\n\nlibLTLIBRARIES = libgettext.la\nlibgettextlaSOURCES = gettext.c gettext.h ...\n\nAutomake predefines the variable 'pkglibdir', so you can use\n'pkglibLTLIBRARIES' to install libraries in '$(libdir)/@PACKAGE@/'.\n\nIf 'gettext.h' is a public header file that needs to be installed in\norder for people to use the library, it should be declared using a\n'HEADERS' variable, not in 'libgettextlaSOURCES'. Headers listed in\nthe latter should be internal headers that are not part of the public\ninterface.\n\nlibLTLIBRARIES = libgettext.la\nlibgettextlaSOURCES = gettext.c ...\nincludeHEADERS = gettext.h ...\n\nA package can build and install such a library along with other\nprograms that use it. This dependency should be specified using\n'LDADD'. The following example builds a program named 'hello' that is\nlinked with 'libgettext.la'.\n\nlibLTLIBRARIES = libgettext.la\nlibgettextlaSOURCES = gettext.c ...\n\nbinPROGRAMS = hello\nhelloSOURCES = hello.c ...\nhelloLDADD = libgettext.la\n\nWhether 'hello' is statically or dynamically linked with 'libgettext.la'\nis not yet known: this will depend on the configuration of libtool and\nthe capabilities of the host.\n\nFile: automake-1.16.info, Node: Conditional Libtool Libraries, Next: Conditional Libtool Sources, Prev: Libtool Libraries, Up: A Shared Library\n\n\nLike conditional programs (*note Conditional Programs::), there are two\nmain ways to build conditional libraries: using Automake conditionals or\nusing Autoconf 'ACSUBST'itutions.\n\nThe important implementation detail you have to be aware of is that\nthe place where a library will be installed matters to libtool: it needs\nto be indicated at link-time using the '-rpath' option.\n\nFor libraries whose destination directory is known when Automake\nruns, Automake will automatically supply the appropriate '-rpath' option\nto libtool. This is the case for libraries listed explicitly in some\ninstallable 'LTLIBRARIES' variables such as 'libLTLIBRARIES'.\n\nHowever, for libraries determined at configure time (and thus\nmentioned in 'EXTRALTLIBRARIES'), Automake does not know the final\ninstallation directory. For such libraries you must add the '-rpath'\noption to the appropriate 'LDFLAGS' variable by hand.\n\nThe examples below illustrate the differences between these two\nmethods.\n\nHere is an example where 'WANTEDLIBS' is an 'ACSUBST'ed variable set\nat './configure'-time to either 'libfoo.la', 'libbar.la', both, or none.\nAlthough '$(WANTEDLIBS)' appears in the 'libLTLIBRARIES', Automake\ncannot guess it relates to 'libfoo.la' or 'libbar.la' at the time it\ncreates the link rule for these two libraries. Therefore the '-rpath'\nargument must be explicitly supplied.\n\nEXTRALTLIBRARIES = libfoo.la libbar.la\nlibLTLIBRARIES = $(WANTEDLIBS)\nlibfoolaSOURCES = foo.c ...\nlibfoolaLDFLAGS = -rpath '$(libdir)'\nlibbarlaSOURCES = bar.c ...\nlibbarlaLDFLAGS = -rpath '$(libdir)'\n\nHere is how the same 'Makefile.am' would look using Automake\nconditionals named 'WANTLIBFOO' and 'WANTLIBBAR'. Now Automake is\nable to compute the '-rpath' setting itself, because it's clear that\nboth libraries will end up in '$(libdir)' if they are installed.\n\nlibLTLIBRARIES =\nif WANTLIBFOO\nlibLTLIBRARIES += libfoo.la\nendif\nif WANTLIBBAR\nlibLTLIBRARIES += libbar.la\nendif\nlibfoolaSOURCES = foo.c ...\nlibbarlaSOURCES = bar.c ...\n\nFile: automake-1.16.info, Node: Conditional Libtool Sources, Next: Libtool Convenience Libraries, Prev: Conditional Libtool Libraries, Up: A Shared Library\n\n\nConditional compilation of sources in a library can be achieved in the\nsame way as conditional compilation of sources in a program (*note\nConditional Sources::). The only difference is that 'LIBADD' should be\nused instead of 'LDADD' and that it should mention libtool objects\n('.lo' files).\n\nSo, to mimic the 'hello' example from *note Conditional Sources::, we\ncould build a 'libhello.la' library using either 'hello-linux.c' or\n'hello-generic.c' with the following 'Makefile.am'.\n\nlibLTLIBRARIES = libhello.la\nlibhellolaSOURCES = hello-common.c\nEXTRAlibhellolaSOURCES = hello-linux.c hello-generic.c\nlibhellolaLIBADD = $(HELLOSYSTEM)\nlibhellolaDEPENDENCIES = $(HELLOSYSTEM)\n\nAnd make sure 'configure' defines 'HELLOSYSTEM' as either\n'hello-linux.lo' or 'hello-generic.lo'.\n\nOr we could simply use an Automake conditional as follows.\n\nlibLTLIBRARIES = libhello.la\nlibhellolaSOURCES = hello-common.c\nif LINUX\nlibhellolaSOURCES += hello-linux.c\nelse\nlibhellolaSOURCES += hello-generic.c\nendif\n\nFile: automake-1.16.info, Node: Libtool Convenience Libraries, Next: Libtool Modules, Prev: Conditional Libtool Sources, Up: A Shared Library\n\n\nSometimes you want to build libtool libraries that should not be\ninstalled. These are called \"libtool convenience libraries\" and are\ntypically used to encapsulate many sublibraries, later gathered into one\nbig installed library.\n\nLibtool convenience libraries are declared by directory-less\nvariables such as 'noinstLTLIBRARIES', 'checkLTLIBRARIES', or even\n'EXTRALTLIBRARIES'. Unlike installed libtool libraries they do not\nneed an '-rpath' flag at link time (this is in fact the only\ndifference).\n\nConvenience libraries listed in 'noinstLTLIBRARIES' are always\nbuilt. Those listed in 'checkLTLIBRARIES' are built only upon 'make\ncheck'. Finally, libraries listed in 'EXTRALTLIBRARIES' are never\nbuilt explicitly: Automake outputs rules to build them, but if the\nlibrary does not appear as a Makefile dependency anywhere it won't be\nbuilt (this is why 'EXTRALTLIBRARIES' is used for conditional\ncompilation).\n\nHere is a sample setup merging libtool convenience libraries from\nsubdirectories into one main 'libtop.la' library.\n\n# -- Top-level Makefile.am --\nSUBDIRS = sub1 sub2 ...\nlibLTLIBRARIES = libtop.la\nlibtoplaSOURCES =\nlibtoplaLIBADD = \\\nsub1/libsub1.la \\\nsub2/libsub2.la \\\n...\n\n# -- sub1/Makefile.am --\nnoinstLTLIBRARIES = libsub1.la\nlibsub1laSOURCES = ...\n\n# -- sub2/Makefile.am --\n# showing nested convenience libraries\nSUBDIRS = sub2.1 sub2.2 ...\nnoinstLTLIBRARIES = libsub2.la\nlibsub2laSOURCES =\nlibsub2laLIBADD = \\\nsub21/libsub21.la \\\nsub22/libsub22.la \\\n...\n\nWhen using such a setup, beware that 'automake' will assume\n'libtop.la' is to be linked with the C linker. This is because\n'libtoplaSOURCES' is empty, so 'automake' picks C as default language.\nIf 'libtoplaSOURCES' was not empty, 'automake' would select the linker\nas explained in *note How the Linker is Chosen::.\n\nIf one of the sublibraries contains non-C source, it is important\nthat the appropriate linker be chosen. One way to achieve this is to\npretend that there is such a non-C file among the sources of the\nlibrary, thus forcing 'automake' to select the appropriate linker. Here\nis the top-level 'Makefile' of our example updated to force C++ linking.\n\nSUBDIRS = sub1 sub2 ...\nlibLTLIBRARIES = libtop.la\nlibtoplaSOURCES =\n# Dummy C++ source to cause C++ linking.\nnodistEXTRAlibtoplaSOURCES = dummy.cxx\nlibtoplaLIBADD = \\\nsub1/libsub1.la \\\nsub2/libsub2.la \\\n...\n\n'EXTRA*SOURCES' variables are used to keep track of source files\nthat might be compiled (this is mostly useful when doing conditional\ncompilation using 'ACSUBST'; *note Conditional Libtool Sources::), and\nthe 'nodist' prefix means the listed sources are not to be distributed\n(*note Program and Library Variables::). In effect the file 'dummy.cxx'\ndoes not need to exist in the source tree. Of course if you have some\nreal source file to list in 'libtoplaSOURCES' there is no point in\ncheating with 'nodistEXTRAlibtoplaSOURCES'.\n\nFile: automake-1.16.info, Node: Libtool Modules, Next: Libtool Flags, Prev: Libtool Convenience Libraries, Up: A Shared Library\n\n\nThese are libtool libraries meant to be dlopened. They are indicated to\nlibtool by passing '-module' at link-time.\n\npkglibLTLIBRARIES = mymodule.la\nmymodulelaSOURCES = doit.c\nmymodulelaLDFLAGS = -module\n\nOrdinarily, Automake requires that a library's name start with 'lib'.\nHowever, when building a dynamically loadable module you might wish to\nuse a \"nonstandard\" name. Automake will not complain about such\nnonstandard names if it knows the library being built is a libtool\nmodule, i.e., if '-module' explicitly appears in the library's\n'LDFLAGS' variable (or in the common 'AMLDFLAGS' variable when no\nper-library 'LDFLAGS' variable is defined).\n\nAs always, 'ACSUBST' variables are black boxes to Automake since\ntheir values are not yet known when 'automake' is run. Therefore if\n'-module' is set via such a variable, Automake cannot notice it and will\nproceed as if the library was an ordinary libtool library, with strict\nnaming.\n\nIf 'mymodulelaSOURCES' is not specified, then it defaults to the\nsingle file 'mymodule.c' (*note Default SOURCES::).\n\nFile: automake-1.16.info, Node: Libtool Flags, Next: LTLIBOBJS, Prev: Libtool Modules, Up: A Shared Library\n\n\nAs shown in previous sections, the 'LIBRARYLIBADD' variable should be\nused to list extra libtool objects ('.lo' files) or libtool libraries\n('.la') to add to LIBRARY.\n\nThe 'LIBRARYLDFLAGS' variable is the place to list additional\nlibtool linking flags, such as '-version-info', '-static', and a lot\nmore. *Note Link mode: (libtool)Link mode.\n\nThe 'libtool' command has two kinds of options: mode-specific options\nand generic options. Mode-specific options such as the aforementioned\nlinking flags should be lumped with the other flags passed to the tool\ninvoked by 'libtool' (hence the use of 'LIBRARYLDFLAGS' for libtool\nlinking flags). Generic options include '--tag=TAG' and '--silent'\n(*note Invoking 'libtool': (libtool)Invoking libtool. for more options).\nThey should appear before the mode selection on the command line; in\n'Makefile.am's they should be listed in the 'LIBRARYLIBTOOLFLAGS'\nvariable.\n\nIf 'LIBRARYLIBTOOLFLAGS' is not defined, then the variable\n'AMLIBTOOLFLAGS' is used instead.\n\nThese flags are passed to libtool after the '--tag=TAG' option\ncomputed by Automake (if any), so 'LIBRARYLIBTOOLFLAGS' (or\n'AMLIBTOOLFLAGS') is a good place to override or supplement the\n'--tag=TAG' setting.\n\nThe libtool rules also use a 'LIBTOOLFLAGS' variable that should not\nbe set in 'Makefile.am': this is a user variable (*note Flag Variables\nOrdering::). It allows users to run 'make LIBTOOLFLAGS=--silent', for\ninstance. Note that the verbosity of 'libtool' can also be influenced\nby the Automake support for silent rules (*note Automake Silent\nRules::).\n\nFile: automake-1.16.info, Node: LTLIBOBJS, Next: Libtool Issues, Prev: Libtool Flags, Up: A Shared Library\n\n\nWhere an ordinary library might include '$(LIBOBJS)' or '$(ALLOCA)'\n(*note LIBOBJS::), a libtool library must use '$(LTLIBOBJS)' or\n'$(LTALLOCA)'. This is required because the object files that libtool\noperates on do not necessarily end in '.o'.\n\nNowadays, the computation of 'LTLIBOBJS' from 'LIBOBJS' is performed\nautomatically by Autoconf (*note 'ACLIBOBJ' vs. 'LIBOBJS':\n(autoconf)ACLIBOBJ vs LIBOBJS.).\n\nFile: automake-1.16.info, Node: Libtool Issues, Prev: LTLIBOBJS, Up: A Shared Library\n\n\n* Menu:\n\n* Error required file ltmain.sh not found:: The need to run libtoolize\n* Objects created both with libtool and without:: Avoid a specific build race\n\nFile: automake-1.16.info, Node: Error required file ltmain.sh not found, Next: Objects created both with libtool and without, Up: Libtool Issues\n\n8.3.9.1 Error: 'required file `./ltmain.sh' not found'\n......................................................\n\nLibtool comes with a tool called 'libtoolize' that will install\nlibtool's supporting files into a package. Running this command will\ninstall 'ltmain.sh'. You should execute it before 'aclocal' and\n'automake'.\n\nPeople upgrading old packages to newer autotools are likely to face\nthis issue because older Automake versions used to call 'libtoolize'.\nTherefore old build scripts do not call 'libtoolize'.\n\nSince Automake 1.6, it has been decided that running 'libtoolize' was\nnone of Automake's business. Instead, that functionality has been moved\ninto the 'autoreconf' command (*note Using 'autoreconf':\n(autoconf)autoreconf Invocation.). If you do not want to remember what\nto run and when, just learn the 'autoreconf' command. Hopefully,\nreplacing existing 'bootstrap' or 'autogen.sh' scripts by a call to\n'autoreconf' should also free you from any similar incompatible change\nin the future.\n\nFile: automake-1.16.info, Node: Objects created both with libtool and without, Prev: Error required file ltmain.sh not found, Up: Libtool Issues\n\n8.3.9.2 Objects 'created with both libtool and without'\n.......................................................\n\nSometimes, the same source file is used both to build a libtool library\nand to build another non-libtool target (be it a program or another\nlibrary).\n\nLet's consider the following 'Makefile.am'.\n\nbinPROGRAMS = prog\nprogSOURCES = prog.c foo.c ...\n\nlibLTLIBRARIES = libfoo.la\nlibfoolaSOURCES = foo.c ...\n\n(In this trivial case the issue could be avoided by linking 'libfoo.la'\nwith 'prog' instead of listing 'foo.c' in 'progSOURCES'. But let's\nassume we want to keep 'prog' and 'libfoo.la' separate.)\n\nTechnically, it means that we should build 'foo.$(OBJEXT)' for\n'prog', and 'foo.lo' for 'libfoo.la'. The problem is that in the course\nof creating 'foo.lo', libtool may erase (or replace) 'foo.$(OBJEXT)',\nand this cannot be avoided.\n\nTherefore, when Automake detects this situation it will complain with\na message such as\nobject 'foo.$(OBJEXT)' created both with libtool and without\n\nA workaround for this issue is to ensure that these two objects get\ndifferent basenames. As explained in *note Renamed Objects::, this\nhappens automatically when per-target flags are used.\n\nbinPROGRAMS = prog\nprogSOURCES = prog.c foo.c ...\nprogCFLAGS = $(AMCFLAGS)\n\nlibLTLIBRARIES = libfoo.la\nlibfoolaSOURCES = foo.c ...\n\nAdding 'progCFLAGS = $(AMCFLAGS)' is almost a no-op, because when the\n'progCFLAGS' is defined, it is used instead of 'AMCFLAGS'. However as\na side effect it will cause 'prog.c' and 'foo.c' to be compiled as\n'prog-prog.$(OBJEXT)' and 'prog-foo.$(OBJEXT)', which solves the issue.\n\nFile: automake-1.16.info, Node: Program and Library Variables, Next: Default SOURCES, Prev: A Shared Library, Up: Programs\n" }, { "name": "8.4 Program and Library Variables", "content": "Associated with each program is a collection of variables that can be\nused to modify how that program is built. There is a similar list of\nsuch variables for each library. The canonical name of the program (or\nlibrary) is used as a base for naming these variables.\n\nIn the list below, we use the name \"maude\" to refer to the program or\nlibrary. In your 'Makefile.am' you would replace this with the\ncanonical name of your program. This list also refers to \"maude\" as a\nprogram, but in general the same rules apply for both static and dynamic\nlibraries; the documentation below notes situations where programs and\nlibraries differ.\n\n'maudeSOURCES'\nThis variable, if it exists, lists all the source files that are\ncompiled to build the program. These files are added to the\ndistribution by default. When building the program, Automake will\ncause each source file to be compiled to a single '.o' file (or\n'.lo' when using libtool). Normally these object files are named\nafter the source file, but other factors can change this. If a\nfile in the 'SOURCES' variable has an unrecognized extension,\nAutomake will do one of two things with it. If a suffix rule\nexists for turning files with the unrecognized extension into '.o'\nfiles, then 'automake' will treat this file as it will any other\nsource file (*note Support for Other Languages::). Otherwise, the\nfile will be ignored as though it were a header file.\n\nThe prefixes 'dist' and 'nodist' can be used to control whether\nfiles listed in a 'SOURCES' variable are distributed. 'dist' is\nredundant, as sources are distributed by default, but it can be\nspecified for clarity if desired.\n\nIt is possible to have both 'dist' and 'nodist' variants of a\ngiven 'SOURCES' variable at once; this lets you easily distribute\nsome files and not others, for instance:\n\nnodistmaudeSOURCES = nodist.c\ndistmaudeSOURCES = dist-me.c\n\nBy default the output file (on Unix systems, the '.o' file) will be\nput into the current build directory. However, if the option\n'subdir-objects' is in effect in the current directory then the\n'.o' file will be put into the subdirectory named after the source\nfile. For instance, with 'subdir-objects' enabled,\n'sub/dir/file.c' will be compiled to 'sub/dir/file.o'. Some\nprojects prefer or require this mode of operation. You can specify\n'subdir-objects' in 'AUTOMAKEOPTIONS' (*note Options::).\n\nWhen 'subdir-objects' is specified, and source files which lie\noutside the current directory tree are nevertheless specified, as\nin 'fooSOURCES = ../lib/other.c', Automake will still remove\n'../lib/other.o', in fact, '../lib/*.o' (e.g., at 'make clean',\neven though it is arguably wrong for one subdirectory to clean in a\nsibling. This may or may not be changed in the future.\n\n'EXTRAmaudeSOURCES'\nAutomake needs to know the list of files you intend to compile\nstatically. For one thing, this is the only way Automake has of\nknowing what sort of language support a given 'Makefile.in'\nrequires. (There are other, more obscure reasons for this\nlimitation as well.) This means that, for example, you can't put a\nconfigure substitution like '@mysources@' into a 'SOURCES'\nvariable. If you intend to conditionally compile source files and\nuse 'configure' to substitute the appropriate object names into,\ne.g., 'LDADD' (see below), then you should list the corresponding\nsource files in the 'EXTRA' variable.\n\nThis variable also supports 'dist' and 'nodist' prefixes. For\ninstance, 'nodistEXTRAmaudeSOURCES' would list extra sources\nthat may need to be built, but should not be distributed.\n\n'maudeAR'\nA static library is created by default by invoking '$(AR)\n$(ARFLAGS)' followed by the name of the library and then the\nobjects being put into the library. You can override this by\nsetting the 'AR' variable. This is usually used with C++; some\nC++ compilers require a special invocation in order to instantiate\nall the templates that should go into a library. For instance, the\nSGI C++ compiler likes this variable set like so:\nlibmaudeaAR = $(CXX) -ar -o\n\n'maudeLIBADD'\nExtra objects can be added to a library using the 'LIBADD'\nvariable. For instance, this should be used for objects determined\nby 'configure' (*note A Library::).\n\nIn the case of libtool libraries, 'maudeLIBADD' can also refer to\nother libtool libraries.\n\n'maudeLDADD'\nExtra objects ('*.$(OBJEXT)') and libraries ('*.a', '*.la') can be\nadded to a program by listing them in the 'LDADD' variable. For\ninstance, this should be used for objects determined by 'configure'\n(*note Linking::).\n\n'LDADD' and 'LIBADD' are inappropriate for passing\nprogram-specific linker flags (except for '-l', '-L', '-dlopen' and\n'-dlpreopen'). Use the 'LDFLAGS' variable for this purpose.\n\nFor instance, if your 'configure.ac' uses 'ACPATHXTRA', you could\nlink your program against the X libraries like so:\n\nmaudeLDADD = $(XPRELIBS) $(XLIBS) $(XEXTRALIBS)\n\nWe recommend that you use '-l' and '-L' only when referring to\nthird-party libraries, and give the explicit file names of any\nlibrary built by your package. Doing so will ensure that\n'maudeDEPENDENCIES' (see below) is correctly defined by default.\n\n'maudeLDFLAGS'\nThis variable is used to pass extra flags to the link step of a\nprogram or a shared library. It overrides the 'AMLDFLAGS'\nvariable, even if it is defined only in a false branch of a\nconditional; in other words, if 'PROGLDFLAGS' is defined at all,\n'AMLDFLAGS' will not be used.\n\n'maudeLIBTOOLFLAGS'\nThis variable is used to pass extra options to 'libtool'. It\noverrides the 'AMLIBTOOLFLAGS' variable. These options are output\nbefore 'libtool''s '--mode=MODE' option, so they should not be\nmode-specific options (those belong to the compiler or linker\nflags). *Note Libtool Flags::.\n\n'maudeDEPENDENCIES'\n'EXTRAmaudeDEPENDENCIES'\nIt is also occasionally useful to have a target (program or\nlibrary) depend on some other file that is not in fact part of that\ntarget. This can be done using the 'DEPENDENCIES' variable. Each\ntarget depends on the contents of such a variable, but no further\ninterpretation is done.\n\nSince these dependencies are associated with the link rule used to\ncreate the programs they should normally list files used by the\nlink command. That is '*.$(OBJEXT)', '*.a', or '*.la' files for\nprograms; '*.lo' and '*.la' files for Libtool libraries; and\n'*.$(OBJEXT)' files for static libraries. In rare cases you may\nneed to add other kinds of files such as linker scripts, but\nlisting a source file in 'DEPENDENCIES' is wrong. If some\nsource file needs to be built before all the components of a\nprogram are built, consider using the 'BUILTSOURCES' variable\n(*note Sources::).\n\nIf 'DEPENDENCIES' is not supplied, it is computed by Automake.\nThe automatically-assigned value is the contents of 'LDADD' or\n'LIBADD', with most configure substitutions, '-l', '-L', '-dlopen'\nand '-dlpreopen' options removed. The configure substitutions that\nare left in are only '$(LIBOBJS)' and '$(ALLOCA)'; these are left\nbecause it is known that they will not cause an invalid value for\n'DEPENDENCIES' to be generated.\n\n'DEPENDENCIES' is more likely used to perform conditional\ncompilation using an 'ACSUBST' variable that contains a list of\nobjects. *Note Conditional Sources::, and *note Conditional\nLibtool Sources::.\n\nThe 'EXTRA*DEPENDENCIES' variable may be useful for cases where\nyou merely want to augment the 'automake'-generated 'DEPENDENCIES'\nvariable rather than replacing it.\n\n'maudeLINK'\nYou can override the linker on a per-program basis. By default the\nlinker is chosen according to the languages used by the program.\nFor instance, a program that includes C++ source code would use the\nC++ compiler to link. The 'LINK' variable must hold the name of a\ncommand that can be passed all the '.o' file names and libraries to\nlink against as arguments. Note that the name of the underlying\nprogram is not passed to 'LINK'; typically one uses '$@':\n\nmaudeLINK = $(CCLD) -magic -o $@\n\nIf a 'LINK' variable is not supplied, it may still be generated\nand used by Automake due to the use of per-target link flags such\nas 'CFLAGS', 'LDFLAGS' or 'LIBTOOLFLAGS', in cases where they\napply.\n\nIf the variable 'AMV*LINK' exists, it is used to output a status\nline in silent mode; otherwise, 'AMVGEN' is used.\n\n'maudeCCASFLAGS'\n'maudeCFLAGS'\n'maudeCPPFLAGS'\n'maudeCXXFLAGS'\n'maudeFFLAGS'\n'maudeGCJFLAGS'\n'maudeLFLAGS'\n'maudeOBJCFLAGS'\n'maudeOBJCXXFLAGS'\n'maudeRFLAGS'\n'maudeUPCFLAGS'\n'maudeYFLAGS'\nAutomake allows you to set compilation flags on a per-program (or\nper-library) basis. A single source file can be included in\nseveral programs, and it will potentially be compiled with\ndifferent flags for each program. This works for any language\ndirectly supported by Automake. These \"per-target compilation\nflags\" are 'CCASFLAGS', 'CFLAGS', 'CPPFLAGS', 'CXXFLAGS',\n'FFLAGS', 'GCJFLAGS', 'LFLAGS', 'OBJCFLAGS', 'OBJCXXFLAGS',\n'RFLAGS', 'UPCFLAGS', and 'YFLAGS'.\n\nWhen using a per-target compilation flag, Automake will choose a\ndifferent name for the intermediate object files. Ordinarily a\nfile like 'sample.c' will be compiled to produce 'sample.o'.\nHowever, if the program's 'CFLAGS' variable is set, then the\nobject file will be named, for instance, 'maude-sample.o'. (See\nalso *note Renamed Objects::.)\n\nIn compilations with per-target flags, the ordinary 'AM' form of\nthe flags variable is not automatically included in the\ncompilation (however, the user form of the variable is included).\nSo for instance, if you want the hypothetical 'maude' compilations\nto also use the value of 'AMCFLAGS', you would need to write:\n\nmaudeCFLAGS = ... your flags ... $(AMCFLAGS)\n\n*Note Flag Variables Ordering::, for more discussion about the\ninteraction between user variables, 'AM' shadow variables, and\nper-target variables.\n\n'maudeSHORTNAME'\nOn some platforms the allowable file names are very short. In\norder to support these systems and per-target compilation flags at\nthe same time, Automake allows you to set a \"short name\" that will\ninfluence how intermediate object files are named. For instance,\nin the following example,\n\nbinPROGRAMS = maude\nmaudeCPPFLAGS = -DSOMEFLAG\nmaudeSHORTNAME = m\nmaudeSOURCES = sample.c ...\n\nthe object file would be named 'm-sample.o' rather than\n'maude-sample.o'.\n\nThis facility is rarely needed in practice, and we recommend\navoiding it until you find it is required.\n\nFile: automake-1.16.info, Node: Default SOURCES, Next: LIBOBJS, Prev: Program and Library Variables, Up: Programs\n" }, { "name": "8.5 Default 'SOURCES'", "content": "'SOURCES' variables are used to specify source files of programs (*note\nA Program::), libraries (*note A Library::), and Libtool libraries\n(*note A Shared Library::).\n\nWhen no such variable is specified for a target, Automake will define\none itself. The default is to compile a single C file whose base name\nis the name of the target itself, with any extension replaced by\n'AMDEFAULTSOURCEEXT', which defaults to '.c'.\n\nFor example if you have the following somewhere in your 'Makefile.am'\nwith no corresponding 'libfooaSOURCES':\n\nlibLIBRARIES = libfoo.a sub/libc++.a\n\n'libfoo.a' will be built using a default source file named 'libfoo.c',\nand 'sub/libc++.a' will be built from 'sub/libc++.c'. (In older\nversions 'sub/libc++.a' would be built from 'sublibca.c', i.e., the\ndefault source was the canonicalized name of the target, with '.c'\nappended. We believe the new behavior is more sensible, but for\nbackward compatibility 'automake' will use the old name if a file or a\nrule with that name exists and 'AMDEFAULTSOURCEEXT' is not used.)\n\nDefault sources are mainly useful in test suites, when building many\ntest programs each from a single source. For instance, in\n\ncheckPROGRAMS = test1 test2 test3\nAMDEFAULTSOURCEEXT = .cpp\n\n'test1', 'test2', and 'test3' will be built from 'test1.cpp',\n'test2.cpp', and 'test3.cpp'. Without the last line, they will be built\nfrom 'test1.c', 'test2.c', and 'test3.c'.\n\nAnother case where this is convenient is building many Libtool\nmodules ('moduleN.la'), each defined in its own file ('moduleN.c').\n\nAMLDFLAGS = -module\nlibLTLIBRARIES = module1.la module2.la module3.la\n\nFinally, there is one situation where this default source computation\nneeds to be avoided: when a target should not be built from sources. We\nalready saw such an example in *note true::; this happens when all the\nconstituents of a target have already been compiled and just need to be\ncombined using a 'LDADD' variable. Then it is necessary to define an\nempty 'SOURCES' variable, so that 'automake' does not compute a\ndefault.\n\nbinPROGRAMS = target\ntargetSOURCES =\ntargetLDADD = libmain.a libmisc.a\n\nFile: automake-1.16.info, Node: LIBOBJS, Next: Program Variables, Prev: Default SOURCES, Up: Programs\n" }, { "name": "8.6 Special handling for 'LIBOBJS' and 'ALLOCA'", "content": "The '$(LIBOBJS)' and '$(ALLOCA)' variables list object files that should\nbe compiled into the project to provide an implementation for functions\nthat are missing or broken on the host system. They are substituted by\n'configure'.\n\nThese variables are defined by Autoconf macros such as 'ACLIBOBJ',\n'ACREPLACEFUNCS' (*note Generic Function Checks: (autoconf)Generic\nFunctions.), or 'ACFUNCALLOCA' (*note Particular Function Checks:\n(autoconf)Particular Functions.). Many other Autoconf macros call\n'ACLIBOBJ' or 'ACREPLACEFUNCS' to populate '$(LIBOBJS)'.\n\nUsing these variables is very similar to doing conditional\ncompilation using 'ACSUBST' variables, as described in *note\nConditional Sources::. That is, when building a program, '$(LIBOBJS)'\nand '$(ALLOCA)' should be added to the associated '*LDADD' variable, or\nto the '*LIBADD' variable when building a library. However there is no\nneed to list the corresponding sources in 'EXTRA*SOURCES' nor to\ndefine '*DEPENDENCIES'. Automake automatically adds '$(LIBOBJS)' and\n'$(ALLOCA)' to the dependencies, and it will discover the list of\ncorresponding source files automatically (by tracing the invocations of\nthe 'ACLIBSOURCE' Autoconf macros). If you have already defined\n'*DEPENDENCIES' explicitly for an unrelated reason, then you either\nneed to add these variables manually, or use 'EXTRA*DEPENDENCIES'\ninstead of '*DEPENDENCIES'.\n\nThese variables are usually used to build a portability library that\nis linked with all the programs of the project. We now review a sample\nsetup. First, 'configure.ac' contains some checks that affect either\n'LIBOBJS' or 'ALLOCA'.\n\n# configure.ac\n...\nACCONFIGLIBOBJDIR([lib])\n...\nACFUNCMALLOC dnl May add malloc.$(OBJEXT) to LIBOBJS\nACFUNCMEMCMP dnl May add memcmp.$(OBJEXT) to LIBOBJS\nACREPLACEFUNCS([strdup]) dnl May add strdup.$(OBJEXT) to LIBOBJS\nACFUNCALLOCA dnl May add alloca.$(OBJEXT) to ALLOCA\n...\nACCONFIGFILES([\nlib/Makefile\nsrc/Makefile\n])\nACOUTPUT\n\nThe 'ACCONFIGLIBOBJDIR' tells Autoconf that the source files of\nthese object files are to be found in the 'lib/' directory. Automake\ncan also use this information, otherwise it expects the source files are\nto be in the directory where the '$(LIBOBJS)' and '$(ALLOCA)' variables\nare used.\n\nThe 'lib/' directory should therefore contain 'malloc.c', 'memcmp.c',\n'strdup.c', 'alloca.c'. Here is its 'Makefile.am':\n\n# lib/Makefile.am\n\nnoinstLIBRARIES = libcompat.a\nlibcompataSOURCES =\nlibcompataLIBADD = $(LIBOBJS) $(ALLOCA)\n\nThe library can have any name, of course, and anyway it is not going\nto be installed: it just holds the replacement versions of the missing\nor broken functions so we can later link them in. Many projects also\ninclude extra functions, specific to the project, in that library: they\nare simply added on the 'SOURCES' line.\n\nThere is a small trap here, though: '$(LIBOBJS)' and '$(ALLOCA)'\nmight be empty, and building an empty library is not portable. You\nshould ensure that there is always something to put in 'libcompat.a'.\nMost projects will also add some utility functions in that directory,\nand list them in 'libcompataSOURCES', so in practice 'libcompat.a'\ncannot be empty.\n\nFinally here is how this library could be used from the 'src/'\ndirectory.\n\n# src/Makefile.am\n\n# Link all programs in this directory with libcompat.a\nLDADD = ../lib/libcompat.a\n\nbinPROGRAMS = tool1 tool2 ...\ntool1SOURCES = ...\ntool2SOURCES = ...\n\nWhen option 'subdir-objects' is not used, as in the above example,\nthe variables '$(LIBOBJS)' or '$(ALLOCA)' can only be used in the\ndirectory where their sources lie. E.g., here it would be wrong to use\n'$(LIBOBJS)' or '$(ALLOCA)' in 'src/Makefile.am'. However if both\n'subdir-objects' and 'ACCONFIGLIBOBJDIR' are used, it is OK to use\nthese variables in other directories. For instance 'src/Makefile.am'\ncould be changed as follows.\n\n# src/Makefile.am\n\nAUTOMAKEOPTIONS = subdir-objects\nLDADD = $(LIBOBJS) $(ALLOCA)\n\nbinPROGRAMS = tool1 tool2 ...\ntool1SOURCES = ...\ntool2SOURCES = ...\n\nBecause '$(LIBOBJS)' and '$(ALLOCA)' contain object file names that\nend with '.$(OBJEXT)', they are not suitable for Libtool libraries\n(where the expected object extension is '.lo'): 'LTLIBOBJS' and\n'LTALLOCA' should be used instead.\n\n'LTLIBOBJS' is defined automatically by Autoconf and should not be\ndefined by hand (as in the past), however at the time of writing\n'LTALLOCA' still needs to be defined from 'ALLOCA' manually. *Note\n'ACLIBOBJ' vs. 'LIBOBJS': (autoconf)ACLIBOBJ vs LIBOBJS.\n\nFile: automake-1.16.info, Node: Program Variables, Next: Yacc and Lex, Prev: LIBOBJS, Up: Programs\n" }, { "name": "8.7 Variables used when building a program", "content": "Occasionally it is useful to know which 'Makefile' variables Automake\nuses for compilations, and in which order (*note Flag Variables\nOrdering::); for instance, you might need to do your own compilation in\nsome special cases.\n\nSome variables are inherited from Autoconf; these are 'CC', 'CFLAGS',\n'CPPFLAGS', 'DEFS', 'LDFLAGS', and 'LIBS'.\n\nThere are some additional variables that Automake defines on its own:\n\n'AMCPPFLAGS'\nThe contents of this variable are passed to every compilation that\ninvokes the C preprocessor; it is a list of arguments to the\npreprocessor. For instance, '-I' and '-D' options should be listed\nhere.\n\nAutomake already provides some '-I' options automatically, in a\nseparate variable that is also passed to every compilation that\ninvokes the C preprocessor. In particular it generates '-I.',\n'-I$(srcdir)', and a '-I' pointing to the directory holding\n'config.h' (if you've used 'ACCONFIGHEADERS'). You can disable\nthe default '-I' options using the 'nostdinc' option.\n\nWhen a file to be included is generated during the build and not\npart of a distribution tarball, its location is under\n'$(builddir)', not under '$(srcdir)'. This matters especially for\npackages that use header files placed in sub-directories and want\nto allow builds outside the source tree (*note VPATH Builds::). In\nthat case we recommend using a pair of '-I' options, such as, e.g.,\n'-Isome/subdir -I$(srcdir)/some/subdir' or\n'-I$(topbuilddir)/some/subdir -I$(topsrcdir)/some/subdir'. Note\nthat the reference to the build tree should come before the\nreference to the source tree, so that accidentally leftover\ngenerated files in the source directory are ignored.\n\n'AMCPPFLAGS' is ignored in preference to a per-executable (or\nper-library) 'CPPFLAGS' variable if it is defined.\n\n'INCLUDES'\nThis does the same job as 'AMCPPFLAGS' (or any per-target\n'CPPFLAGS' variable if it is used). It is an older name for the\nsame functionality. This variable is deprecated; we suggest using\n'AMCPPFLAGS' and per-target 'CPPFLAGS' instead.\n\n'AMCFLAGS'\nThis is the variable the 'Makefile.am' author can use to pass in\nadditional C compiler flags. In some situations, this is not used,\nin preference to the per-executable (or per-library) 'CFLAGS'.\n\n'COMPILE'\nThis is the command used to compile a C source file. The file name\nis appended to form the complete command line.\n\n'AMLDFLAGS'\nThis is the variable the 'Makefile.am' author can use to pass in\nadditional linker flags. In some situations, this is not used, in\npreference to the per-executable (or per-library) 'LDFLAGS'.\n\n'LINK'\nThis is the command used to link a C program. It already includes\n'-o $@' and the usual variable references (for instance, 'CFLAGS');\nit takes as \"arguments\" the names of the object files and libraries\nto link in. This variable is not used when the linker is\noverridden with a per-target 'LINK' variable or per-target flags\ncause Automake to define such a 'LINK' variable.\n\nFile: automake-1.16.info, Node: Yacc and Lex, Next: C++ Support, Prev: Program Variables, Up: Programs\n" }, { "name": "8.8 Yacc and Lex support", "content": "Automake has somewhat idiosyncratic support for Yacc and Lex.\n\nAutomake assumes that the '.c' file generated by 'yacc' or 'lex'\nshould be named using the basename of the input file. That is, for a\nYacc source file 'foo.y', Automake will cause the intermediate file to\nbe named 'foo.c' (as opposed to 'y.tab.c', which is more traditional).\n\nThe extension of a Yacc source file is used to determine the\nextension of the resulting C or C++ source and header files. Be aware\nthat header files are generated only when the option '-d' is given to\nYacc; see below for more information about this flag, and how to specify\nit. Files with the extension '.y' will thus be turned into '.c' sources\nand '.h' headers; likewise, '.yy' will become '.cc' and '.hh', '.y++'\nwill become 'c++' and 'h++', '.yxx' will become '.cxx' and '.hxx', and\n'.ypp' will become '.cpp' and '.hpp'.\n\nSimilarly, Lex source files can be used to generate C or C++; the\nextensions '.l', '.ll', '.l++', '.lxx', and '.lpp' are recognized.\n\nYou should never explicitly mention the intermediate (C or C++) file\nin any 'SOURCES' variable; only list the source file.\n\nThe intermediate files generated by 'yacc' (or 'lex') will be\nincluded in any distribution that is made. That way the user doesn't\nneed to have 'yacc' or 'lex'.\n\nIf a Yacc source file is seen, then your 'configure.ac' must define\nthe variable 'YACC'. This is most easily done by invoking the macro\n'ACPROGYACC' (*note Particular Program Checks: (autoconf)Particular\nPrograms.).\n\nWhen 'yacc' is invoked, it is passed 'AMYFLAGS' and 'YFLAGS'. The\nlatter is a user variable and the former is intended for the\n'Makefile.am' author.\n\n'AMYFLAGS' is usually used to pass the '-d' option to 'yacc'.\nAutomake knows what this means and will automatically adjust its rules\nto update and distribute the header file built by 'yacc -d'. Caveat:\n'automake' recognizes '-d' in 'AMYFLAGS' only if it is not clustered\nwith other options; for example, it won't be recognized if 'AMYFLAGS'\nis '-dt', but it will be if 'AMYFLAGS' is '-d -t' or '-t -d'.\n\nWhat Automake cannot guess, though, is where this header will be\nused: it is up to you to ensure the header gets built before it is first\nused. Typically this is necessary in order for dependency tracking to\nwork when the header is included by another file. The common solution\nis listing the header file in 'BUILTSOURCES' (*note Sources::) as\nfollows.\n\nBUILTSOURCES = parser.h\nAMYFLAGS = -d\nbinPROGRAMS = foo\nfooSOURCES = ... parser.y ...\n\nIf a Lex source file is seen, then your 'configure.ac' must define\nthe variable 'LEX'. You can use 'ACPROGLEX' to do this (*note\nParticular Program Checks: (autoconf)Particular Programs.), but using\nthe 'AMPROGLEX' macro (*note Macros::) is recommended.\n\nWhen 'lex' is invoked, it is passed 'AMLFLAGS' and 'LFLAGS'. The\nlatter is a user variable and the former is intended for the\n'Makefile.am' author.\n\nWhen 'AMMAINTAINERMODE' (*note maintainer-mode::) is in effect, the\nrebuild rules for distributed Yacc and Lex sources are only used when\n'maintainer-mode' is enabled, or when the files have been erased.\n\nWhen Yacc or Lex sources are used, 'automake -a' automatically\ninstalls an auxiliary program called 'ylwrap' in your package (*note\nAuxiliary Programs::). This program is used by the build rules to\nrename the output of these tools, and makes it possible to include\nmultiple 'yacc' (or 'lex') source files in a single directory. This is\nnecessary because Yacc's output file name is fixed, and a parallel make\ncould invoke more than one instance of 'yacc' simultaneously.\n\n* Menu:\n\n* Linking Multiple Yacc Parsers::\n\n\nFile: automake-1.16.info, Node: Linking Multiple Yacc Parsers, Up: Yacc and Lex\n\nFor 'yacc', simply managing locking as with 'ylwrap' is insufficient.\nThe output of 'yacc' always uses the same symbol names internally, so it\nisn't possible to link two 'yacc' parsers into the same executable.\n\nWe recommend using the following renaming hack used in 'gdb':\n#define yymaxdepth cmaxdepth\n#define yyparse cparse\n#define yylex clex\n#define yyerror cerror\n#define yylval clval\n#define yychar cchar\n#define yydebug cdebug\n#define yypact cpact\n#define yyr1 cr1\n#define yyr2 cr2\n#define yydef cdef\n#define yychk cchk\n#define yypgo cpgo\n#define yyact cact\n#define yyexca cexca\n#define yyerrflag cerrflag\n#define yynerrs cnerrs\n#define yyps cps\n#define yypv cpv\n#define yys cs\n#define yyyys cyys\n#define yystate cstate\n#define yytmp ctmp\n#define yyv cv\n#define yyyyv cyyv\n#define yyval cval\n#define yylloc clloc\n#define yyreds creds\n#define yytoks ctoks\n#define yylhs cyylhs\n#define yylen cyylen\n#define yydefred cyydefred\n#define yydgoto cyydgoto\n#define yysindex cyysindex\n#define yyrindex cyyrindex\n#define yygindex cyygindex\n#define yytable cyytable\n#define yycheck cyycheck\n#define yyname cyyname\n#define yyrule cyyrule\n\nFor each define, replace the 'c' prefix with whatever you like.\nThese defines work for 'bison', 'byacc', and traditional 'yacc's. If\nyou find a parser generator that uses a symbol not covered here, please\nreport the new name so it can be added to the list.\n\nFile: automake-1.16.info, Node: C++ Support, Next: Objective C Support, Prev: Yacc and Lex, Up: Programs\n" }, { "name": "8.9 C++ Support", "content": "Automake includes full support for C++.\n\nAny package including C++ code must define the output variable 'CXX'\nin 'configure.ac'; the simplest way to do this is to use the\n'ACPROGCXX' macro (*note Particular Program Checks:\n(autoconf)Particular Programs.).\n\nA few additional variables are defined when a C++ source file is\nseen:\n\n'CXX'\nThe name of the C++ compiler.\n\n'CXXFLAGS'\nAny flags to pass to the C++ compiler.\n\n'AMCXXFLAGS'\nThe maintainer's variant of 'CXXFLAGS'.\n\n'CXXCOMPILE'\nThe command used to compile a C++ source file. The file name is\nappended to form the complete command line.\n\n'CXXLINK'\nThe command used to link a C++ program.\n\nFile: automake-1.16.info, Node: Objective C Support, Next: Objective C++ Support, Prev: C++ Support, Up: Programs\n" }, { "name": "8.10 Objective C Support", "content": "Automake includes some support for Objective C.\n\nAny package including Objective C code must define the output\nvariable 'OBJC' in 'configure.ac'; the simplest way to do this is to use\nthe 'ACPROGOBJC' macro (*note Particular Program Checks:\n(autoconf)Particular Programs.).\n\nA few additional variables are defined when an Objective C source\nfile is seen:\n\n'OBJC'\nThe name of the Objective C compiler.\n\n'OBJCFLAGS'\nAny flags to pass to the Objective C compiler.\n\n'AMOBJCFLAGS'\nThe maintainer's variant of 'OBJCFLAGS'.\n\n'OBJCCOMPILE'\nThe command used to compile an Objective C source file. The file\nname is appended to form the complete command line.\n\n'OBJCLINK'\nThe command used to link an Objective C program.\n\nFile: automake-1.16.info, Node: Objective C++ Support, Next: Unified Parallel C Support, Prev: Objective C Support, Up: Programs\n" }, { "name": "8.11 Objective C++ Support", "content": "Automake includes some support for Objective C++.\n\nAny package including Objective C++ code must define the output\nvariable 'OBJCXX' in 'configure.ac'; the simplest way to do this is to\nuse the 'ACPROGOBJCXX' macro (*note Particular Program Checks:\n(autoconf)Particular Programs.).\n\nA few additional variables are defined when an Objective C++ source\nfile is seen:\n\n'OBJCXX'\nThe name of the Objective C++ compiler.\n\n'OBJCXXFLAGS'\nAny flags to pass to the Objective C++ compiler.\n\n'AMOBJCXXFLAGS'\nThe maintainer's variant of 'OBJCXXFLAGS'.\n\n'OBJCXXCOMPILE'\nThe command used to compile an Objective C++ source file. The file\nname is appended to form the complete command line.\n\n'OBJCXXLINK'\nThe command used to link an Objective C++ program.\n\nFile: automake-1.16.info, Node: Unified Parallel C Support, Next: Assembly Support, Prev: Objective C++ Support, Up: Programs\n" }, { "name": "8.12 Unified Parallel C Support", "content": "Automake includes some support for Unified Parallel C.\n\nAny package including Unified Parallel C code must define the output\nvariable 'UPC' in 'configure.ac'; the simplest way to do this is to use\nthe 'AMPROGUPC' macro (*note Public Macros::).\n\nA few additional variables are defined when a Unified Parallel C\nsource file is seen:\n\n'UPC'\nThe name of the Unified Parallel C compiler.\n\n'UPCFLAGS'\nAny flags to pass to the Unified Parallel C compiler.\n\n'AMUPCFLAGS'\nThe maintainer's variant of 'UPCFLAGS'.\n\n'UPCCOMPILE'\nThe command used to compile a Unified Parallel C source file. The\nfile name is appended to form the complete command line.\n\n'UPCLINK'\nThe command used to link a Unified Parallel C program.\n\nFile: automake-1.16.info, Node: Assembly Support, Next: Fortran 77 Support, Prev: Unified Parallel C Support, Up: Programs\n" }, { "name": "8.13 Assembly Support", "content": "Automake includes some support for assembly code. There are two forms\nof assembler files: normal ('*.s') and preprocessed by 'CPP' ('*.S' or\n'*.sx').\n\nThe variable 'CCAS' holds the name of the compiler used to build\nassembly code. This compiler must work a bit like a C compiler; in\nparticular it must accept '-c' and '-o'. The values of 'CCASFLAGS' and\n'AMCCASFLAGS' (or its per-target definition) is passed to the\ncompilation. For preprocessed files, 'DEFS', 'DEFAULTINCLUDES',\n'INCLUDES', 'CPPFLAGS' and 'AMCPPFLAGS' are also used.\n\nThe autoconf macro 'AMPROGAS' will define 'CCAS' and 'CCASFLAGS'\nfor you (unless they are already set, it simply sets 'CCAS' to the C\ncompiler and 'CCASFLAGS' to the C compiler flags), but you are free to\ndefine these variables by other means.\n\nOnly the suffixes '.s', '.S', and '.sx' are recognized by 'automake'\nas being files containing assembly code.\n\nFile: automake-1.16.info, Node: Fortran 77 Support, Next: Fortran 9x Support, Prev: Assembly Support, Up: Programs\n" }, { "name": "8.14 Fortran 77 Support", "content": "Automake includes full support for Fortran 77.\n\nAny package including Fortran 77 code must define the output variable\n'F77' in 'configure.ac'; the simplest way to do this is to use the\n'ACPROGF77' macro (*note Particular Program Checks:\n(autoconf)Particular Programs.).\n\nA few additional variables are defined when a Fortran 77 source file\nis seen:\n\n'F77'\nThe name of the Fortran 77 compiler.\n\n'FFLAGS'\nAny flags to pass to the Fortran 77 compiler.\n\n'AMFFLAGS'\nThe maintainer's variant of 'FFLAGS'.\n\n'RFLAGS'\nAny flags to pass to the Ratfor compiler.\n\n'AMRFLAGS'\nThe maintainer's variant of 'RFLAGS'.\n\n'F77COMPILE'\nThe command used to compile a Fortran 77 source file. The file\nname is appended to form the complete command line.\n\n'FLINK'\nThe command used to link a pure Fortran 77 program or shared\nlibrary.\n\nAutomake can handle preprocessing Fortran 77 and Ratfor source files\nin addition to compiling them(1). Automake also contains some support\nfor creating programs and shared libraries that are a mixture of Fortran\n77 and other languages (*note Mixing Fortran 77 With C and C++::).\n\nThese issues are covered in the following sections.\n\n* Menu:\n\n* Preprocessing Fortran 77:: Preprocessing Fortran 77 sources\n* Compiling Fortran 77 Files:: Compiling Fortran 77 sources\n* Mixing Fortran 77 With C and C++:: Mixing Fortran 77 With C and C++\n\n---------- Footnotes ----------\n\n(1) Much, if not most, of the information in the following sections\npertaining to preprocessing Fortran 77 programs was taken almost\nverbatim from *note Catalogue of Rules: (make)Catalogue of Rules.\n\nFile: automake-1.16.info, Node: Preprocessing Fortran 77, Next: Compiling Fortran 77 Files, Up: Fortran 77 Support\n\n\n'N.f' is made automatically from 'N.F' or 'N.r'. This rule runs just\nthe preprocessor to convert a preprocessable Fortran 77 or Ratfor source\nfile into a strict Fortran 77 source file. The precise command used is\nas follows:\n\n'.F'\n'$(F77) -F $(DEFS) $(INCLUDES) $(AMCPPFLAGS) $(CPPFLAGS)\n$(AMFFLAGS) $(FFLAGS)'\n\n'.r'\n'$(F77) -F $(AMFFLAGS) $(FFLAGS) $(AMRFLAGS) $(RFLAGS)'\n\nFile: automake-1.16.info, Node: Compiling Fortran 77 Files, Next: Mixing Fortran 77 With C and C++, Prev: Preprocessing Fortran 77, Up: Fortran 77 Support\n\n\n'N.o' is made automatically from 'N.f', 'N.F' or 'N.r' by running the\nFortran 77 compiler. The precise command used is as follows:\n\n'.f'\n'$(F77) -c $(AMFFLAGS) $(FFLAGS)'\n\n'.F'\n'$(F77) -c $(DEFS) $(INCLUDES) $(AMCPPFLAGS) $(CPPFLAGS)\n$(AMFFLAGS) $(FFLAGS)'\n\n'.r'\n'$(F77) -c $(AMFFLAGS) $(FFLAGS) $(AMRFLAGS) $(RFLAGS)'\n\nFile: automake-1.16.info, Node: Mixing Fortran 77 With C and C++, Prev: Compiling Fortran 77 Files, Up: Fortran 77 Support\n\n\nAutomake currently provides limited support for creating programs and\nshared libraries that are a mixture of Fortran 77 and C and/or C++.\nHowever, there are many other issues related to mixing Fortran 77 with\nother languages that are not (currently) handled by Automake, but that\nare handled by other packages(1).\n\nAutomake can help in two ways:\n\n1. Automatic selection of the linker depending on which combinations\nof source code.\n\n2. Automatic selection of the appropriate linker flags (e.g., '-L' and\n'-l') to pass to the automatically selected linker in order to link\nin the appropriate Fortran 77 intrinsic and run-time libraries.\n\nThese extra Fortran 77 linker flags are supplied in the output\nvariable 'FLIBS' by the 'ACF77LIBRARYLDFLAGS' Autoconf macro.\n*Note Fortran Compiler Characteristics: (autoconf)Fortran Compiler.\n\nIf Automake detects that a program or shared library (as mentioned in\nsome 'PROGRAMS' or 'LTLIBRARIES' primary) contains source code that is\na mixture of Fortran 77 and C and/or C++, then it requires that the\nmacro 'ACF77LIBRARYLDFLAGS' be called in 'configure.ac', and that\neither '$(FLIBS)' appear in the appropriate 'LDADD' (for programs) or\n'LIBADD' (for shared libraries) variables. It is the responsibility of\nthe person writing the 'Makefile.am' to make sure that '$(FLIBS)'\nappears in the appropriate 'LDADD' or 'LIBADD' variable.\n\nFor example, consider the following 'Makefile.am':\n\nbinPROGRAMS = foo\nfooSOURCES = main.cc foo.f\nfooLDADD = libfoo.la $(FLIBS)\n\npkglibLTLIBRARIES = libfoo.la\nlibfoolaSOURCES = bar.f baz.c zardoz.cc\nlibfoolaLIBADD = $(FLIBS)\n\nIn this case, Automake will insist that 'ACF77LIBRARYLDFLAGS' is\nmentioned in 'configure.ac'. Also, if '$(FLIBS)' hadn't been mentioned\nin 'fooLDADD' and 'libfoolaLIBADD', then Automake would have issued a\nwarning.\n\n* Menu:\n\n* How the Linker is Chosen:: Automatic linker selection\n\n---------- Footnotes ----------\n\n(1) For example, the cfortran package\n(https://www-zeus.desy.de/~burow/cfortran/) addresses all of these\ninter-language issues, and runs under nearly all Fortran 77, C and C++\ncompilers on nearly all platforms. However, 'cfortran' is not yet Free\nSoftware, but it will be in the next major release.\n\nFile: automake-1.16.info, Node: How the Linker is Chosen, Up: Mixing Fortran 77 With C and C++\n\n8.14.3.1 How the Linker is Chosen\n.................................\n\nWhen a program or library mixes several languages, Automake chooses the\nlinker according to the following priorities. (The names in parentheses\nare the variables containing the link command.)\n\n1. Native Java ('GCJLINK')\n2. Objective C++ ('OBJCXXLINK')\n3. C++ ('CXXLINK')\n4. Fortran 77 ('F77LINK')\n5. Fortran ('FCLINK')\n6. Objective C ('OBJCLINK')\n7. Unified Parallel C ('UPCLINK')\n8. C ('LINK')\n\nFor example, if Fortran 77, C and C++ source code is compiled into a\nprogram, then the C++ linker will be used. In this case, if the C or\nFortran 77 linkers required any special libraries that weren't included\nby the C++ linker, then they must be manually added to an 'LDADD' or\n'LIBADD' variable by the user writing the 'Makefile.am'.\n\nAutomake only looks at the file names listed in 'SOURCES' variables\nto choose the linker, and defaults to the C linker. Sometimes this is\ninconvenient because you are linking against a library written in\nanother language and would like to set the linker more appropriately.\n*Note Libtool Convenience Libraries::, for a trick with\n'nodistEXTRA...SOURCES'.\n\nA per-target 'LINK' variable will override the above selection.\nPer-target link flags will cause Automake to write a per-target 'LINK'\nvariable according to the language chosen as above.\n\nFile: automake-1.16.info, Node: Fortran 9x Support, Next: Java Support with gcj, Prev: Fortran 77 Support, Up: Programs\n" }, { "name": "8.15 Fortran 9x Support", "content": "Automake includes support for Fortran 9x.\n\nAny package including Fortran 9x code must define the output variable\n'FC' in 'configure.ac'; the simplest way to do this is to use the\n'ACPROGFC' macro (*note Particular Program Checks:\n(autoconf)Particular Programs.).\n\nA few additional variables are defined when a Fortran 9x source file\nis seen:\n\n'FC'\nThe name of the Fortran 9x compiler.\n\n'FCFLAGS'\nAny flags to pass to the Fortran 9x compiler.\n\n'AMFCFLAGS'\nThe maintainer's variant of 'FCFLAGS'.\n\n'FCCOMPILE'\nThe command used to compile a Fortran 9x source file. The file\nname is appended to form the complete command line.\n\n'FCLINK'\nThe command used to link a pure Fortran 9x program or shared\nlibrary.\n\n* Menu:\n\n* Compiling Fortran 9x Files:: Compiling Fortran 9x sources\n\nFile: automake-1.16.info, Node: Compiling Fortran 9x Files, Up: Fortran 9x Support\n\n\n'FILE.o' is made automatically from 'FILE.f90', 'FILE.f95', 'FILE.f03',\nor 'FILE.f08' by running the Fortran 9x compiler. The precise command\nused is as follows:\n\n'.f90'\n'$(FC) $(AMFCFLAGS) $(FCFLAGS) -c $(FCFLAGSf90) $<'\n\n'.f95'\n'$(FC) $(AMFCFLAGS) $(FCFLAGS) -c $(FCFLAGSf95) $<'\n\n'.f03'\n'$(FC) $(AMFCFLAGS) $(FCFLAGS) -c $(FCFLAGSf03) $<'\n\n'.f08'\n'$(FC) $(AMFCFLAGS) $(FCFLAGS) -c $(FCFLAGSf08) $<'\n\nFile: automake-1.16.info, Node: Java Support with gcj, Next: Vala Support, Prev: Fortran 9x Support, Up: Programs\n" }, { "name": "8.16 Compiling Java sources using gcj", "content": "Automake includes support for natively compiled Java, using 'gcj', the\nJava front end to the GNU Compiler Collection (rudimentary support for\ncompiling Java to bytecode using the 'javac' compiler is also present,\nalbeit deprecated; *note Java::).\n\nAny package including Java code to be compiled must define the output\nvariable 'GCJ' in 'configure.ac'; the variable 'GCJFLAGS' must also be\ndefined somehow (either in 'configure.ac' or 'Makefile.am'). The\nsimplest way to do this is to use the 'AMPROGGCJ' macro.\n\nBy default, programs including Java source files are linked with\n'gcj'.\n\nAs always, the contents of 'AMGCJFLAGS' are passed to every\ncompilation invoking 'gcj' (in its role as an ahead-of-time compiler,\nwhen invoking it to create '.class' files, 'AMJAVACFLAGS' is used\ninstead). If it is necessary to pass options to 'gcj' from\n'Makefile.am', this variable, and not the user variable 'GCJFLAGS',\nshould be used.\n\n'gcj' can be used to compile '.java', '.class', '.zip', or '.jar'\nfiles.\n\nWhen linking, 'gcj' requires that the main class be specified using\nthe '--main=' option. The easiest way to do this is to use the\n'LDFLAGS' variable for the program.\n\nFile: automake-1.16.info, Node: Vala Support, Next: Support for Other Languages, Prev: Java Support with gcj, Up: Programs\n" }, { "name": "8.17 Vala Support", "content": "Automake provides initial support for Vala\n(). This requires valac version 0.7.0 or\nlater, and currently requires the user to use GNU 'make'.\n\nfooSOURCES = foo.vala bar.vala zardoz.c\n\nAny '.vala' file listed in a 'SOURCES' variable will be compiled\ninto C code by the Vala compiler. The generated '.c' files are\ndistributed. The end user does not need to have a Vala compiler\ninstalled.\n\nAutomake ships with an Autoconf macro called 'AMPROGVALAC' that\nwill locate the Vala compiler and optionally check its version number.\n\n-- Macro: AMPROGVALAC ([MINIMUM-VERSION], [ACTION-IF-FOUND],\n[ACTION-IF-NOT-FOUND]) Search for a Vala compiler in 'PATH'. If it\nis found, the variable 'VALAC' is set to point to it (see below for\nmore details). This macro takes three optional arguments. The\nfirst argument, if present, is the minimum version of the Vala API\nrequired to compile this package. For Vala releases, this is the\nsame as the major and minor release number; e.g., when 'valac\n--version' reports '0.48.7', 'valac --api-version' reports '0.48'.\nIf a compiler is found and satisfies MINIMUM-VERSION, then\nACTION-IF-FOUND is run (this defaults to do nothing). Otherwise,\nACTION-IF-NOT-FOUND is run. If ACTION-IF-NOT-FOUND is not\nspecified, the default value is to print a warning in case no\ncompiler is found, or if a too-old version of the compiler is\nfound.\n\nThere are a few variables that are used when compiling Vala sources:\n\n'VALAC'\nAbsolute path to the Vala compiler, or simply 'valac' if no\nsuitable Vala compiler could be found at configure runtime.\n\n'VALAFLAGS'\nAdditional arguments for the Vala compiler.\n\n'AMVALAFLAGS'\nThe maintainer's variant of 'VALAFLAGS'.\n\nlibLTLIBRARIES = libfoo.la\nlibfoolaSOURCES = foo.vala\n\nNote that currently, you cannot use per-target '*VALAFLAGS' (*note\nRenamed Objects::) to produce different C files from one Vala source\nfile.\n\nFile: automake-1.16.info, Node: Support for Other Languages, Next: Dependencies, Prev: Vala Support, Up: Programs\n" }, { "name": "8.18 Support for Other Languages", "content": "Automake currently only includes full support for C, C++ (*note C++\nSupport::), Objective C (*note Objective C Support::), Objective C++\n(*note Objective C++ Support::), Fortran 77 (*note Fortran 77\nSupport::), Fortran 9x (*note Fortran 9x Support::), and Java (*note\nJava Support with gcj::). There is only rudimentary support for other\nlanguages, support for which will be improved based on user demand.\n\nSome limited support for adding your own languages is available via\nthe suffix rule handling (*note Suffixes::).\n\nFile: automake-1.16.info, Node: Dependencies, Next: EXEEXT, Prev: Support for Other Languages, Up: Programs\n" }, { "name": "8.19 Automatic dependency tracking", "content": "As a developer it is often painful to continually update the\n'Makefile.am' whenever the include-file dependencies change in a\nproject. Automake supplies a way to automatically track dependency\nchanges (*note Dependency Tracking::).\n\nAutomake always uses complete dependencies for a compilation,\nincluding system headers. Automake's model is that dependency\ncomputation should be a side effect of the build. To this end,\ndependencies are computed by running all compilations through a special\nwrapper program called 'depcomp'. 'depcomp' understands how to coax\nmany different C and C++ compilers into generating dependency\ninformation in the format it requires. 'automake -a' will install\n'depcomp' into your source tree for you. If 'depcomp' can't figure out\nhow to properly invoke your compiler, dependency tracking will simply be\ndisabled for your build.\n\nExperience with earlier versions of Automake (*note Dependency\nTracking Evolution: (automake-history)Dependency Tracking Evolution.)\ntaught us that it is not reliable to generate dependencies only on the\nmaintainer's system, as configurations vary too much. So instead\nAutomake implements dependency tracking at build time.\n\nAutomatic dependency tracking can be suppressed by putting\n'no-dependencies' in the variable 'AUTOMAKEOPTIONS', or passing\n'no-dependencies' as an argument to 'AMINITAUTOMAKE' (this should be\nthe preferred way). Or, you can invoke 'automake' with the '-i' option.\nDependency tracking is enabled by default.\n\nThe person building your package also can choose to disable\ndependency tracking by configuring with '--disable-dependency-tracking'.\n\nFile: automake-1.16.info, Node: EXEEXT, Prev: Dependencies, Up: Programs\n" }, { "name": "8.20 Support for executable extensions", "content": "On some platforms, such as Windows, executables are expected to have an\nextension such as '.exe'. On these platforms, some compilers (GCC among\nthem) will automatically generate 'foo.exe' when asked to generate\n'foo'.\n\nAutomake provides mostly-transparent support for this. Unfortunately\nmostly doesn't yet mean fully. Until the English dictionary is\nrevised, you will have to assist Automake if your package must support\nthose platforms.\n\nOne thing you must be aware of is that, internally, Automake rewrites\nsomething like this:\n\nbinPROGRAMS = liver\n\nto this:\n\nbinPROGRAMS = liver$(EXEEXT)\n\nThe targets Automake generates are likewise given the '$(EXEEXT)'\nextension.\n\nThe variables 'TESTS' and 'XFAILTESTS' (*note Simple Tests::) are\nalso rewritten if they contain filenames that have been declared as\nprograms in the same 'Makefile'. (This is mostly useful when some\nprograms from 'checkPROGRAMS' are listed in 'TESTS'.)\n\nHowever, Automake cannot apply this rewriting to 'configure'\nsubstitutions. This means that if you are conditionally building a\nprogram using such a substitution, then your 'configure.ac' must take\ncare to add '$(EXEEXT)' when constructing the output variable.\n\nSometimes maintainers like to write an explicit link rule for their\nprogram. Without executable extension support, this is easy--you simply\nwrite a rule whose target is the name of the program. However, when\nexecutable extension support is enabled, you must instead add the\n'$(EXEEXT)' suffix.\n\nThis might be a nuisance for maintainers who know their package will\nnever run on a platform that has executable extensions. For those\nmaintainers, the 'no-exeext' option (*note Options::) will disable this\nfeature. This works in a fairly ugly way; if 'no-exeext' is seen, then\nthe presence of a rule for a target named 'foo' in 'Makefile.am' will\noverride an 'automake'-generated rule for 'foo$(EXEEXT)'. Without the\n'no-exeext' option, this use will give a diagnostic.\n\nFile: automake-1.16.info, Node: Other Objects, Next: Other GNU Tools, Prev: Programs, Up: Top\n" } ] }, "9 Other Derived Objects": { "content": "Automake can handle derived objects that are not C programs. Sometimes\nthe support for building such objects must be explicitly supplied, but\nAutomake can still automatically handle installation and distribution.\n\n* Menu:\n\n* Scripts:: Executable scripts\n* Headers:: Header files\n* Data:: Architecture-independent data files\n* Sources:: Derived sources\n\nFile: automake-1.16.info, Node: Scripts, Next: Headers, Up: Other Objects\n", "subsections": [ { "name": "9.1 Executable Scripts", "content": "It is possible to define and install programs that are scripts. Such\nprograms are listed using the 'SCRIPTS' primary name. When the script\nis distributed in its final, installable form, the 'Makefile' usually\nlooks as follows:\n\n# Install myscript in $(bindir) and distribute it.\ndistbinSCRIPTS = myscript\n\nScripts are not distributed by default; as we have just seen, those\nthat should be distributed can be specified using a 'dist' prefix as\nwith other primaries.\n\nScripts can be installed in 'bindir', 'sbindir', 'libexecdir',\n'pkglibexecdir', or 'pkgdatadir'.\n\nScripts that need not be installed can be listed in 'noinstSCRIPTS',\nand among them, those which are needed only by 'make check' should go in\n'checkSCRIPTS'.\n\nWhen a script needs to be built, the 'Makefile.am' should include the\nappropriate rules. For instance the 'automake' program itself is a Perl\nscript that is generated from 'automake.in'. Here is how this is\nhandled:\n\nbinSCRIPTS = automake\nCLEANFILES = $(binSCRIPTS)\nEXTRADIST = automake.in\n\ndosubst = sed -e 's,[@]datadir[@],$(datadir),g' \\\n-e 's,[@]PERL[@],$(PERL),g' \\\n-e 's,[@]PACKAGE[@],$(PACKAGE),g' \\\n-e 's,[@]VERSION[@],$(VERSION),g' \\\n...\n\nautomake: automake.in Makefile\n$(dosubst) < $(srcdir)/automake.in > automake\nchmod +x automake\n\nSuch scripts for which a build rule has been supplied need to be\ndeleted explicitly using 'CLEANFILES' (*note Clean::), and their sources\nhave to be distributed, usually with 'EXTRADIST' (*note Basics of\nDistribution::).\n\nAnother common way to build scripts is to process them from\n'configure' with 'ACCONFIGFILES'. In this situation Automake knows\nwhich files should be cleaned and distributed, and what the rebuild\nrules should look like.\n\nFor instance if 'configure.ac' contains\n\nACCONFIGFILES([src/myscript], [chmod +x src/myscript])\n\nto build 'src/myscript' from 'src/myscript.in', then a\n'src/Makefile.am' to install this script in '$(bindir)' can be as simple\nas\n\nbinSCRIPTS = myscript\nCLEANFILES = $(binSCRIPTS)\n\nThere is no need for 'EXTRADIST' or any build rule: Automake infers\nthem from 'ACCONFIGFILES' (*note Requirements::). 'CLEANFILES' is\nstill useful, because by default Automake will clean targets of\n'ACCONFIGFILES' in 'distclean', not 'clean'.\n\nAlthough this looks simpler, building scripts this way has one\ndrawback: directory variables such as '$(datadir)' are not fully\nexpanded and may refer to other directory variables.\n\nFile: automake-1.16.info, Node: Headers, Next: Data, Prev: Scripts, Up: Other Objects\n" }, { "name": "9.2 Header files", "content": "Header files that must be installed are specified by the 'HEADERS'\nfamily of variables. Headers can be installed in 'includedir',\n'oldincludedir', 'pkgincludedir' or any other directory you may have\ndefined (*note Uniform::). For instance,\n\nincludeHEADERS = foo.h bar/bar.h\n\nwill install the two files as '$(includedir)/foo.h' and\n'$(includedir)/bar.h'.\n\nThe 'nobase' prefix is also supported:\n\nnobaseincludeHEADERS = foo.h bar/bar.h\n\nwill install the two files as '$(includedir)/foo.h' and\n'$(includedir)/bar/bar.h' (*note Alternative::).\n\nUsually, only header files that accompany installed libraries need to\nbe installed. Headers used by programs or convenience libraries are not\ninstalled. The 'noinstHEADERS' variable can be used for such headers.\nHowever, when the header belongs to a single convenience library or\nprogram, we recommend listing it in the program's or library's\n'SOURCES' variable (*note Program Sources::) instead of in\n'noinstHEADERS'. This is clearer for the 'Makefile.am' reader.\n'noinstHEADERS' would be the right variable to use in a directory\ncontaining only headers and no associated library or program.\n\nAll header files must be listed somewhere; in a 'SOURCES' variable\nor in a 'HEADERS' variable. Missing ones will not appear in the\ndistribution.\n\nFor header files that are built and must not be distributed, use the\n'nodist' prefix as in 'nodistincludeHEADERS' or\n'nodistprogSOURCES'. If these generated headers are needed during the\nbuild, you must also ensure they exist before they are used (*note\nSources::).\n\nFile: automake-1.16.info, Node: Data, Next: Sources, Prev: Headers, Up: Other Objects\n" }, { "name": "9.3 Architecture-independent data files", "content": "Automake supports the installation of miscellaneous data files using the\n'DATA' family of variables.\n\nSuch data can be installed in the directories 'datadir',\n'sysconfdir', 'sharedstatedir', 'localstatedir', or 'pkgdatadir'.\n\nBy default, data files are not included in a distribution. Of\ncourse, you can use the 'dist' prefix to change this on a per-variable\nbasis.\n\nHere is how Automake declares its auxiliary data files:\n\ndistpkgdataDATA = clean-kr.am clean.am ...\n\nFile: automake-1.16.info, Node: Sources, Prev: Data, Up: Other Objects\n" }, { "name": "9.4 Built Sources", "content": "Because Automake's automatic dependency tracking works as a side-effect\nof compilation (*note Dependencies::) there is a bootstrap issue: a\ntarget should not be compiled before its dependencies are made, but\nthese dependencies are unknown until the target is first compiled.\n\nOrdinarily this is not a problem, because dependencies are\ndistributed sources: they preexist and do not need to be built. Suppose\nthat 'foo.c' includes 'foo.h'. When it first compiles 'foo.o', 'make'\nonly knows that 'foo.o' depends on 'foo.c'. As a side-effect of this\ncompilation 'depcomp' records the 'foo.h' dependency so that following\ninvocations of 'make' will honor it. In these conditions, it's clear\nthere is no problem: either 'foo.o' doesn't exist and has to be built\n(regardless of the dependencies), or accurate dependencies exist and\nthey can be used to decide whether 'foo.o' should be rebuilt.\n\nIt's a different story if 'foo.h' doesn't exist by the first 'make'\nrun. For instance, there might be a rule to build 'foo.h'. This time\n'file.o''s build will fail because the compiler can't find 'foo.h'.\n'make' failed to trigger the rule to build 'foo.h' first by lack of\ndependency information.\n\nThe 'BUILTSOURCES' variable is a workaround for this problem. A\nsource file listed in 'BUILTSOURCES' is made when 'make all', 'make\ncheck', 'make install', 'make install-exec' (or 'make dist') is run,\nbefore other targets are processed. However, such a source file is not\ncompiled unless explicitly requested by mentioning it in some other\n'SOURCES' variable.\n\nSo, to conclude our introductory example, we could use 'BUILTSOURCES\n= foo.h' to ensure 'foo.h' gets built before any other target (including\n'foo.o') during 'make all' or 'make check'.\n\n'BUILTSOURCES' is a bit of a misnomer, as any file which must be\ncreated early in the build process can be listed in this variable.\nMoreover, all built sources do not necessarily have to be listed in\n'BUILTSOURCES'. For instance, a generated '.c' file doesn't need to\nappear in 'BUILTSOURCES' (unless it is included by another source),\nbecause it's a known dependency of the associated object.\n\nTo emphasize, 'BUILTSOURCES' is honored only by 'make all', 'make\ncheck', 'make install', and 'make install-exec' (and 'make dist'). This\nmeans you cannot build an arbitrary target (e.g., 'make foo') in a clean\ntree if it depends on a built source. However it will succeed if you\nhave run 'make all' earlier, because accurate dependencies are already\navailable.\n\nThe next section illustrates and discusses the handling of built\nsources on a toy example.\n\n* Menu:\n\n* Built Sources Example:: Several ways to handle built sources.\n\nFile: automake-1.16.info, Node: Built Sources Example, Up: Sources\n\n\nSuppose that 'foo.c' includes 'bindir.h', which is\ninstallation-dependent and not distributed: it needs to be built. Here\n'bindir.h' defines the preprocessor macro 'bindir' to the value of the\n'make' variable 'bindir' (inherited from 'configure').\n\nWe suggest several implementations below. It's not meant to be an\nexhaustive listing of all ways to handle built sources, but it will give\nyou a few ideas if you encounter this issue.\n\nFirst Try\n.........\n\nThis first implementation will illustrate the bootstrap issue mentioned\nin the previous section (*note Sources::).\n\nHere is a tentative 'Makefile.am'.\n\n# This won't work.\nbinPROGRAMS = foo\nfooSOURCES = foo.c\nnodistfooSOURCES = bindir.h\nCLEANFILES = bindir.h\nbindir.h: Makefile\necho '#define bindir \"$(bindir)\"' >$@\n\nThis setup doesn't work, because Automake doesn't know that 'foo.c'\nincludes 'bindir.h'. Remember, automatic dependency tracking works as a\nside-effect of compilation, so the dependencies of 'foo.o' will be known\nonly after 'foo.o' has been compiled (*note Dependencies::). The\nsymptom is as follows.\n\n% make\nsource='foo.c' object='foo.o' libtool=no \\\ndepfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \\\ndepmode=gcc /bin/sh ./depcomp \\\ngcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c\nfoo.c:2: bindir.h: No such file or directory\nmake: * [foo.o] Error 1\n\nIn this example 'bindir.h' is not distributed nor installed, and it\nis not even being built on-time. One may wonder if the\n'nodistfooSOURCES = bindir.h' line has any use at all. This line\nsimply states that 'bindir.h' is a source of 'foo', so for instance, it\nshould be inspected while generating tags (*note Tags::). In other\nwords, it does not help our present problem, and the build would fail\nidentically without it.\n\nUsing 'BUILTSOURCES'\n.....................\n\nA solution is to require 'bindir.h' to be built before anything else.\nThis is what 'BUILTSOURCES' is meant for (*note Sources::).\n\nbinPROGRAMS = foo\nfooSOURCES = foo.c\nnodistfooSOURCES = bindir.h\nBUILTSOURCES = bindir.h\nCLEANFILES = bindir.h\nbindir.h: Makefile\necho '#define bindir \"$(bindir)\"' >$@\n\nSee how 'bindir.h' gets built first:\n\n% make\necho '#define bindir \"/usr/local/bin\"' >bindir.h\nmake all-am\nmake[1]: Entering directory `/home/adl/tmp'\nsource='foo.c' object='foo.o' libtool=no \\\ndepfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \\\ndepmode=gcc /bin/sh ./depcomp \\\ngcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c\ngcc -g -O2 -o foo foo.o\nmake[1]: Leaving directory `/home/adl/tmp'\n\nHowever, as said earlier, 'BUILTSOURCES' applies only to the 'all',\n'check', and 'install' targets. It still fails if you try to run 'make\nfoo' explicitly:\n\n% make clean\ntest -z \"bindir.h\" || rm -f bindir.h\ntest -z \"foo\" || rm -f foo\nrm -f *.o\n% : > .deps/foo.Po # Suppress previously recorded dependencies\n% make foo\nsource='foo.c' object='foo.o' libtool=no \\\ndepfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \\\ndepmode=gcc /bin/sh ./depcomp \\\ngcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c\nfoo.c:2: bindir.h: No such file or directory\nmake: * [foo.o] Error 1\n\nRecording Dependencies manually\n...............................\n\nUsually people are happy enough with 'BUILTSOURCES' because they never\nbuild targets such as 'make foo' before 'make all', as in the previous\nexample. However if this matters to you, you can avoid 'BUILTSOURCES'\nand record such dependencies explicitly in the 'Makefile.am'.\n\nbinPROGRAMS = foo\nfooSOURCES = foo.c\nnodistfooSOURCES = bindir.h\nfoo.$(OBJEXT): bindir.h\nCLEANFILES = bindir.h\nbindir.h: Makefile\necho '#define bindir \"$(bindir)\"' >$@\n\nYou don't have to list all the dependencies of 'foo.o' explicitly,\nonly those that might need to be built. If a dependency already exists,\nit will not hinder the first compilation and will be recorded by the\nnormal dependency tracking code. (After this first compilation, the\ndependency tracking code will also have recorded the dependency between\n'foo.o' and 'bindir.h', so our explicit dependency is only useful to the\nfirst build.)\n\nAdding explicit dependencies like this can be a bit dangerous if you\nare not careful enough. This is due to the way Automake tries not to\noverwrite your rules (it assumes you know better than it).\n'foo.$(OBJEXT): bindir.h' supersedes any rule Automake may want to\noutput to build 'foo.$(OBJEXT)'. It happens to work in this case\nbecause Automake doesn't have to output any 'foo.$(OBJEXT):' target: it\nrelies on a suffix rule instead (i.e., '.c.$(OBJEXT):'). Always check\nthe generated 'Makefile.in' if you do this.\n\nBuild 'bindir.h' from 'configure'\n.................................\n\nIt's possible to define this preprocessor macro from 'configure', either\nin 'config.h' (*note Defining Directories: (autoconf)Defining\nDirectories.), or by processing a 'bindir.h.in' file using\n'ACCONFIGFILES' (*note Configuration Actions: (autoconf)Configuration\nActions.).\n\nAt this point it should be clear that building 'bindir.h' from\n'configure' works well for this example. 'bindir.h' will exist before\nyou build any target, hence will not cause any dependency issue.\n\nThe Makefile can be shrunk as follows. We do not even have to\nmention 'bindir.h'.\n\nbinPROGRAMS = foo\nfooSOURCES = foo.c\n\nHowever, it's not always possible to build sources from 'configure',\nespecially when these sources are generated by a tool that needs to be\nbuilt first.\n\nBuild 'bindir.c', not 'bindir.h'.\n.................................\n\nAnother attractive idea is to define 'bindir' as a variable or function\nexported from 'bindir.o', and build 'bindir.c' instead of 'bindir.h'.\n\nnoinstPROGRAMS = foo\nfooSOURCES = foo.c bindir.h\nnodistfooSOURCES = bindir.c\nCLEANFILES = bindir.c\nbindir.c: Makefile\necho 'const char bindir[] = \"$(bindir)\";' >$@\n\n'bindir.h' contains just the variable's declaration and doesn't need\nto be built, so it won't cause any trouble. 'bindir.o' is always\ndependent on 'bindir.c', so 'bindir.c' will get built first.\n\nWhich is best?\n..............\n\nThere is no panacea, of course. Each solution has its merits and\ndrawbacks.\n\nYou cannot use 'BUILTSOURCES' if the ability to run 'make foo' on a\nclean tree is important to you.\n\nYou won't add explicit dependencies if you are leery of overriding an\nAutomake rule by mistake.\n\nBuilding files from './configure' is not always possible, neither is\nconverting '.h' files into '.c' files.\n\nFile: automake-1.16.info, Node: Other GNU Tools, Next: Documentation, Prev: Other Objects, Up: Top\n" } ] }, "10 Other GNU Tools": { "content": "Since Automake is primarily intended to generate 'Makefile.in's for use\nin GNU programs, it tries hard to interoperate with other GNU tools.\n\n* Menu:\n\n* Emacs Lisp:: Emacs Lisp\n* gettext:: Gettext\n* Libtool:: Libtool\n* Java:: Java bytecode compilation (deprecated)\n* Python:: Python\n\nFile: automake-1.16.info, Node: Emacs Lisp, Next: gettext, Up: Other GNU Tools\n", "subsections": [ { "name": "10.1 Emacs Lisp", "content": "Automake provides some support for Emacs Lisp. The 'LISP' primary is\nused to hold a list of '.el' files. Possible prefixes for this primary\nare 'lisp' and 'noinst'. Note that if 'lispLISP' is defined, then\n'configure.ac' must run 'AMPATHLISPDIR' (*note Macros::).\n\nLisp sources are not distributed by default. You can prefix the\n'LISP' primary with 'dist', as in 'distlispLISP' or\n'distnoinstLISP', to indicate that these files should be distributed.\n\nAutomake will byte-compile all Emacs Lisp source files using the\nEmacs found by 'AMPATHLISPDIR', if any was found. When performing\nsuch byte-compilation, the flags specified in the (developer-reserved)\n'AMELCFLAGS' and (user-reserved) 'ELCFLAGS' make variables will be\npassed to the Emacs invocation.\n\nByte-compiled Emacs Lisp files are not portable among all versions of\nEmacs, so it makes sense to turn this off if you expect sites to have\nmore than one version of Emacs installed. Furthermore, many packages do\nnot actually benefit from byte-compilation. Still, we recommend that\nyou byte-compile your Emacs Lisp sources. It is probably better for\nsites with strange setups to cope for themselves than to make the\ninstallation less nice for everybody else.\n\nThere are two ways to avoid byte-compiling. Historically, we have\nrecommended the following construct.\n\nlispLISP = file1.el file2.el\nELCFILES =\n\n'ELCFILES' is an internal Automake variable that normally lists all\n'.elc' files that must be byte-compiled. Automake defines 'ELCFILES'\nautomatically from 'lispLISP'. Emptying this variable explicitly\nprevents byte-compilation.\n\nSince Automake 1.8, we now recommend using 'lispDATA' instead:\n\nlispDATA = file1.el file2.el\n\nNote that these two constructs are not equivalent. 'LISP' will not\ninstall a file if Emacs is not installed, while 'DATA' will always\ninstall its files.\n\nFile: automake-1.16.info, Node: gettext, Next: Libtool, Prev: Emacs Lisp, Up: Other GNU Tools\n" }, { "name": "10.2 Gettext", "content": "If 'AMGNUGETTEXT' is seen in 'configure.ac', then Automake turns on\nsupport for GNU gettext, a message catalog system for\ninternationalization (*note Introduction: (gettext)Top.).\n\nThe 'gettext' support in Automake requires the addition of one or two\nsubdirectories to the package: 'po' and possibly also 'intl'. The\nlatter is needed if 'AMGNUGETTEXT' is not invoked with the 'external'\nargument, or if 'AMGNUGETTEXTINTLSUBDIR' is used. Automake ensures\nthat these directories exist and are mentioned in 'SUBDIRS'.\n\nFile: automake-1.16.info, Node: Libtool, Next: Java, Prev: gettext, Up: Other GNU Tools\n" }, { "name": "10.3 Libtool", "content": "Automake provides support for GNU Libtool (*note Introduction:\n(libtool)Top.) with the 'LTLIBRARIES' primary. *Note A Shared\nLibrary::.\n\nFile: automake-1.16.info, Node: Java, Next: Python, Prev: Libtool, Up: Other GNU Tools\n" }, { "name": "10.4 Java bytecode compilation (deprecated)", "content": "Automake provides some minimal support for Java bytecode compilation\nwith the 'JAVA' primary (in addition to the support for compiling Java\nto native machine code; *note Java Support with gcj::). Note however\nthat the interface and most features described here are deprecated.\nFuture Automake releases will strive to provide a better and cleaner\ninterface, which however won't be backward-compatible; the present\ninterface will probably be removed altogether some time after the\nintroduction of the new interface (if that ever materializes). In any\ncase, the current 'JAVA' primary features are frozen and will no longer\nbe developed, not even to take bug fixes.\n\nAny '.java' files listed in a 'JAVA' variable will be compiled with\n'JAVAC' at build time. By default, '.java' files are not included in\nthe distribution; you should use the 'dist' prefix to distribute them.\n\nHere is a typical setup for distributing '.java' files and installing\nthe '.class' files resulting from their compilation.\n\njavadir = $(datadir)/java\ndistjavaJAVA = a.java b.java ...\n\nCurrently Automake enforces the restriction that only one 'JAVA'\nprimary can be used in a given 'Makefile.am'. The reason for this\nrestriction is that, in general, it isn't possible to know which\n'.class' files were generated from which '.java' files, so it would be\nimpossible to know which files to install where. For instance, a\n'.java' file can define multiple classes; the resulting '.class' file\nnames cannot be predicted without parsing the '.java' file.\n\nThere are a few variables that are used when compiling Java sources:\n\n'JAVAC'\nThe name of the Java compiler. This defaults to 'javac'.\n\n'JAVACFLAGS'\nThe flags to pass to the compiler. This is considered to be a user\nvariable (*note User Variables::).\n\n'AMJAVACFLAGS'\nMore flags to pass to the Java compiler. This, and not\n'JAVACFLAGS', should be used when it is necessary to put Java\ncompiler flags into 'Makefile.am'.\n\n'JAVAROOT'\nThe value of this variable is passed to the '-d' option to 'javac'.\nIt defaults to '$(topbuilddir)'.\n\n'CLASSPATHENV'\nThis variable is a shell expression that is used to set the\n'CLASSPATH' environment variable on the 'javac' command line. (In\nthe future we will probably handle class path setting differently.)\n\nFile: automake-1.16.info, Node: Python, Prev: Java, Up: Other GNU Tools\n" }, { "name": "10.5 Python", "content": "Automake provides support for Python compilation with the 'PYTHON'\nprimary. A typical setup is to call 'AMPATHPYTHON' in 'configure.ac'\nand use a line like this in 'Makefile.am':\n\npythonPYTHON = tree.py leave.py\n\nPython source files are included in the distribution by default;\nprepend 'nodist' (as in 'nodistpythonPYTHON') to omit them.\n\nAt install time, any files listed in a 'PYTHON' variable will be\nbyte-compiled with 'py-compile'. 'py-compile' creates both standard\n('.pyc') and optimized ('.pyo') byte-compiled versions of the source\nfiles. Because byte-compilation occurs at install time, files listed in\n'noinstPYTHON' will not be compiled.\n\nAutomake ships with an Autoconf macro named 'AMPATHPYTHON' that\ndetermines some Python-related directory variables (see below). If you\nhave called 'AMPATHPYTHON' from 'configure.ac', then you may use the\nvariables 'pythonPYTHON' and 'pkgpythonPYTHON' to list Python source\nfiles in your 'Makefile.am', depending on whether you want your files\ninstalled in 'pythondir' or 'pkgpythondir', respectively.\n\n-- Macro: AMPATHPYTHON ([VERSION], [ACTION-IF-FOUND],\n[ACTION-IF-NOT-FOUND])\n\nSearch for a Python interpreter on the system. This macro takes\nthree optional arguments. The first argument, if present, is the\nminimum version of Python required for this package:\n'AMPATHPYTHON' will skip any Python interpreter that is older\nthan VERSION. If an interpreter is found and satisfies VERSION,\nthen ACTION-IF-FOUND is run. Otherwise, ACTION-IF-NOT-FOUND is\nrun.\n\nIf ACTION-IF-NOT-FOUND is not specified, as in the following\nexample, the default is to abort 'configure':\n\nAMPATHPYTHON([2.5])\n\nThis is fine when Python is an absolute requirement for the\npackage. If Python ??? 2.5 was only optional for the package,\n'AMPATHPYTHON' could be called as follows.\n\nAMPATHPYTHON([2.5],, [:])\n\nIf the 'PYTHON' variable is set when 'AMPATHPYTHON' is called,\nthen that will be the only Python interpreter that is tried.\n\n'AMPATHPYTHON' creates the following output variables based on\nthe Python installation found during configuration:\n\n'PYTHON'\nThe name of the Python executable, or ':' if no suitable\ninterpreter could be found.\n\nAssuming ACTION-IF-NOT-FOUND is used (otherwise './configure' will\nabort if Python is absent), the value of 'PYTHON' can be used to\nset up a conditional in order to disable the relevant part of a\nbuild as follows.\n\nAMPATHPYTHON(,, [:])\nAMCONDITIONAL([HAVEPYTHON], [test \"$PYTHON\" != :])\n\n'PYTHONVERSION'\nThe Python version number, in the form MAJOR.MINOR (e.g., '2.5').\nThis is set to be the value of ''%u.%u' % sys.versioninfo[:2]'.\n\n'PYTHONPREFIX'\n'PYTHONEXECPREFIX'\nWith no special options given, these have values '${prefix}' and\n'${execprefix}', respectively (unexpanded; see below).\n\nThe 'configure' options '--with-pythonprefix' and\n'--with-pythonexecprefix' set them to an explicit value.\n\nThe 'configure' option '--with-python-sys-prefix' set them to the\nvalues of Python's 'sys.prefix' and 'sys.execprefix' variables.\nThese often differ from '${prefix}' and '${execprefix}', e.g., on\nplatforms such as Mac OS x (where Python is usually installed as a\nFramework).\n\n'PYTHONPLATFORM'\nThe canonical name used by Python to describe the operating system,\nas given by 'sys.platform'. This value is sometimes needed when\nbuilding Python extensions.\n\n'pythondir'\nThe directory name for the 'site-packages' subdirectory of the\nstandard Python install tree.\n\n'pkgpythondir'\nThis is the directory under 'pythondir' that is named after the\npackage. That is, it is '$(pythondir)/$(PACKAGE)'. It is provided\nas a convenience.\n\n'pyexecdir'\nThis is the directory where Python extension modules (shared\nlibraries) should be installed. An extension module written in C\ncould be declared as follows to Automake:\n\npyexecLTLIBRARIES = quaternion.la\nquaternionlaSOURCES = quaternion.c support.c support.h\nquaternionlaLDFLAGS = -avoid-version -module\n\n'pkgpyexecdir'\nThis is a convenience variable that is defined as\n'$(pyexecdir)/$(PACKAGE)'.\n\nAll of these directory variables have values that can start with\neither '${prefix}' or '${execprefix}', unexpanded. This works fine in\n'Makefile's, but it makes these variables hard to use in 'configure'.\nThis is mandated by the GNU coding standards, so that the user can run\n'make prefix=/foo install'. The Autoconf manual has a section with more\ndetails on this topic (*note Installation Directory Variables:\n(autoconf)Installation Directory Variables.). See also *note Hard-Coded\nInstall Paths::.\n\nFile: automake-1.16.info, Node: Documentation, Next: Install, Prev: Other GNU Tools, Up: Top\n" } ] }, "11 Building documentation": { "content": "Currently Automake provides support for Texinfo and man pages.\n\n* Menu:\n\n* Texinfo:: Texinfo\n* Man Pages:: Man pages\n\nFile: automake-1.16.info, Node: Texinfo, Next: Man Pages, Up: Documentation\n", "subsections": [ { "name": "11.1 Texinfo", "content": "If the current directory contains Texinfo source, you must declare it\nwith the 'TEXINFOS' primary. Generally Texinfo files are converted into\ninfo, and thus the 'infoTEXINFOS' variable is most commonly used here.\nAny Texinfo source file should have the '.texi' extension. Automake\nalso accepts '.txi' or '.texinfo' extensions, but their use is\ndiscouraged now, and will elicit runtime warnings.\n\nAutomake generates rules to build '.info', '.dvi', '.ps', '.pdf' and\n'.html' files from your Texinfo sources. Following the GNU Coding\nStandards, only the '.info' files are built by 'make all' and installed\nby 'make install' (unless you use 'no-installinfo', see below).\nFurthermore, '.info' files are automatically distributed so that Texinfo\nis not a prerequisite for installing your package.\n\nIt is worth noting that, contrary to what happens with the other\nformats, the generated '.info' files are by default placed in 'srcdir'\nrather than in the 'builddir'. This can be changed with the\n'info-in-builddir' option.\n\nOther documentation formats can be built on request by 'make dvi',\n'make ps', 'make pdf' and 'make html', and they can be installed with\n'make install-dvi', 'make install-ps', 'make install-pdf' and 'make\ninstall-html' explicitly. 'make uninstall' will remove everything: the\nTexinfo documentation installed by default as well as all the above\noptional formats.\n\nAll of these targets can be extended using '-local' rules (*note\nExtending::).\n\nIf the '.texi' file '@include's 'version.texi', then that file will\nbe automatically generated. The file 'version.texi' defines four\nTexinfo flags you can reference using '@value{EDITION}',\n'@value{VERSION}', '@value{UPDATED}', and '@value{UPDATED-MONTH}'.\n\n'EDITION'\n'VERSION'\nBoth of these flags hold the version number of your program. They\nare kept separate for clarity.\n\n'UPDATED'\nThis holds the date the primary '.texi' file was last modified.\n\n'UPDATED-MONTH'\nThis holds the name of the month in which the primary '.texi' file\nwas last modified.\n\nThe 'version.texi' support requires the 'mdate-sh' script; this\nscript is supplied with Automake and automatically included when\n'automake' is invoked with the '--add-missing' option.\n\nIf you have multiple Texinfo files, and you want to use the\n'version.texi' feature, then you have to have a separate version file\nfor each Texinfo file. Automake will treat any include in a Texinfo\nfile that matches 'vers*.texi' just as an automatically generated\nversion file.\n\nOften an Info file depends on more than one '.texi' file. For\ninstance, in GNU Hello, 'hello.texi' includes the file 'fdl.texi'. You\ncan tell Automake about these dependencies using the 'TEXITEXINFOS'\nvariable. Here is how GNU Hello does it:\n\ninfoTEXINFOS = hello.texi\nhelloTEXINFOS = fdl.texi\n\nBy default, Automake requires the file 'texinfo.tex' to appear in the\nsame directory as the 'Makefile.am' file that lists the '.texi' files.\nIf you used 'ACCONFIGAUXDIR' in 'configure.ac' (*note Finding\n'configure' Input: (autoconf)Input.), then 'texinfo.tex' is looked for\nthere. In both cases, 'automake' then supplies 'texinfo.tex' if\n'--add-missing' is given, and takes care of its distribution. However,\nif you set the 'TEXINFOTEX' variable (see below), it overrides the\nlocation of the file and turns off its installation into the source as\nwell as its distribution.\n\nThe option 'no-texinfo.tex' can be used to eliminate the requirement\nfor the file 'texinfo.tex'. Use of the variable 'TEXINFOTEX' is\npreferable, however, because that allows the 'dvi', 'ps', and 'pdf'\ntargets to still work.\n\nAutomake generates an 'install-info' rule; some people apparently use\nthis. By default, info pages are installed by 'make install', so\nrunning 'make install-info' is pointless. This can be prevented via the\n'no-installinfo' option. In this case, '.info' files are not installed\nby default, and user must request this explicitly using 'make\ninstall-info'.\n\nBy default, 'make install-info' and 'make uninstall-info' will try to\nrun the 'install-info' program (if available) to update (or\ncreate/remove) the '${infodir}/dir' index. If this is undesired, it can\nbe prevented by exporting the 'AMUPDATEINFODIR' variable to \"'no'\".\n\nThe following variables are used by the Texinfo build rules.\n\n'MAKEINFO'\nThe name of the program invoked to build '.info' files. This\nvariable is defined by Automake. If the 'makeinfo' program is\nfound on the system then it will be used by default; otherwise\n'missing' will be used instead.\n\n'MAKEINFOHTML'\nThe command invoked to build '.html' files. Automake defines this\nto '$(MAKEINFO) --html'.\n\n'MAKEINFOFLAGS'\nUser flags passed to each invocation of '$(MAKEINFO)' and\n'$(MAKEINFOHTML)'. This user variable (*note User Variables::) is\nnot expected to be defined in any 'Makefile'; it can be used by\nusers to pass extra flags to suit their needs.\n\n'AMMAKEINFOFLAGS'\n'AMMAKEINFOHTMLFLAGS'\nMaintainer flags passed to each 'makeinfo' invocation. Unlike\n'MAKEINFOFLAGS', these variables are meant to be defined by\nmaintainers in 'Makefile.am'. '$(AMMAKEINFOFLAGS)' is passed to\n'makeinfo' when building '.info' files; and\n'$(AMMAKEINFOHTMLFLAGS)' is used when building '.html' files.\n\nFor instance, the following setting can be used to obtain one\nsingle '.html' file per manual, without node separators.\nAMMAKEINFOHTMLFLAGS = --no-headers --no-split\n\n'AMMAKEINFOHTMLFLAGS' defaults to '$(AMMAKEINFOFLAGS)'. This\nmeans that defining 'AMMAKEINFOFLAGS' without defining\n'AMMAKEINFOHTMLFLAGS' will impact builds of both '.info' and\n'.html' files.\n\n'TEXI2DVI'\nThe name of the command that converts a '.texi' file into a '.dvi'\nfile. This defaults to 'texi2dvi', a script that ships with the\nTexinfo package.\n\n'TEXI2PDF'\nThe name of the command that translates a '.texi' file into a\n'.pdf' file. This defaults to '$(TEXI2DVI) --pdf --batch'.\n\n'DVIPS'\nThe name of the command that builds a '.ps' file out of a '.dvi'\nfile. This defaults to 'dvips'.\n\n'TEXINFOTEX'\nIf your package has Texinfo files in many directories, you can use\nthe variable 'TEXINFOTEX' to tell Automake where to find the\ncanonical 'texinfo.tex' for your package. The value of this\nvariable should be the relative path from the current 'Makefile.am'\nto 'texinfo.tex':\n\nTEXINFOTEX = ../doc/texinfo.tex\n\nFile: automake-1.16.info, Node: Man Pages, Prev: Texinfo, Up: Documentation\n" }, { "name": "11.2 Man Pages", "content": "A package can also include man pages (but see the GNU standards on this\nmatter, *note (standards)Man Pages::.) Man pages are declared using the\n'MANS' primary. Generally the 'manMANS' variable is used. Man pages\nare automatically installed in the correct subdirectory of 'mandir',\nbased on the file extension.\n\nFile extensions such as '.1c' are handled by looking for the valid\npart of the extension and using that to determine the correct\nsubdirectory of 'mandir'. Valid section names are the digits '0'\nthrough '9', and the letters 'l' and 'n'.\n\nSometimes developers prefer to name a man page something like\n'foo.man' in the source, and then rename it to have the correct suffix,\nfor example 'foo.1', when installing the file. Automake also supports\nthis mode. For a valid section named SECTION, there is a corresponding\ndirectory named 'manSECTIONdir', and a corresponding 'MANS' variable.\nFiles listed in such a variable are installed in the indicated section.\nIf the file already has a valid suffix, then it is installed as-is;\notherwise the file suffix is changed to match the section.\n\nFor instance, consider this example:\nman1MANS = rename.man thesame.1 alsothesame.1c\n\nIn this case, 'rename.man' will be renamed to 'rename.1' when installed,\nbut the other files will keep their names.\n\nBy default, man pages are installed by 'make install'. However,\nsince the GNU project does not require man pages, many maintainers do\nnot expend effort to keep the man pages up to date. In these cases, the\n'no-installman' option will prevent the man pages from being installed\nby default. The user can still explicitly install them via 'make\ninstall-man'.\n\nFor fast installation, with many files it is preferable to use\n'manSECTIONMANS' over 'manMANS' as well as files that do not need to\nbe renamed.\n\nMan pages are not currently considered to be source, because it is\nnot uncommon for man pages to be automatically generated. Therefore\nthey are not automatically included in the distribution. However, this\ncan be changed by use of the 'dist' prefix. For instance here is how\nto distribute and install the two man pages of GNU 'cpio' (which\nincludes both Texinfo documentation and man pages):\n\ndistmanMANS = cpio.1 mt.1\n\nThe 'nobase' prefix is meaningless for man pages and is disallowed.\n\nExecutables and manpages may be renamed upon installation (*note\nRenaming::). For manpages this can be avoided by use of the 'notrans'\nprefix. For instance, suppose an executable 'foo' allowing to access a\nlibrary function 'foo' from the command line. The way to avoid renaming\nof the 'foo.3' manpage is:\n\nmanMANS = foo.1\nnotransmanMANS = foo.3\n\n'notrans' must be specified first when used in conjunction with\neither 'dist' or 'nodist' (*note Fine-grained Distribution Control::).\nFor instance:\n\nnotransdistman3MANS = bar.3\n\nFile: automake-1.16.info, Node: Install, Next: Clean, Prev: Documentation, Up: Top\n" } ] }, "12 What Gets Installed": { "content": "Naturally, Automake handles the details of installing your program once\nit has been built. All files named by the various primaries are\nautomatically installed in the appropriate places when the user runs\n'make install'.\n\n* Menu:\n\n* Basics of Installation:: What gets installed where\n* The Two Parts of Install:: Installing data and programs separately\n* Extending Installation:: Adding your own rules for installation\n* Staged Installs:: Installation in a temporary location\n* Install Rules for the User:: Useful additional rules\n\nFile: automake-1.16.info, Node: Basics of Installation, Next: The Two Parts of Install, Up: Install\n", "subsections": [ { "name": "12.1 Basics of Installation", "content": "A file named in a primary is installed by copying the built file into\nthe appropriate directory. The base name of the file is used when\ninstalling.\n\nbinPROGRAMS = hello subdir/goodbye\n\nIn this example, both 'hello' and 'goodbye' will be installed in\n'$(bindir)'.\n\nSometimes it is useful to avoid the basename step at install time.\nFor instance, you might have a number of header files in subdirectories\nof the source tree that are laid out precisely how you want to install\nthem. In this situation you can use the 'nobase' prefix to suppress\nthe base name step. For example:\n\nnobaseincludeHEADERS = stdio.h sys/types.h\n\nwill install 'stdio.h' in '$(includedir)' and 'types.h' in\n'$(includedir)/sys'.\n\nFor most file types, Automake will install multiple files at once,\nwhile avoiding command line length issues (*note Length Limitations::).\nSince some 'install' programs will not install the same file twice in\none invocation, you may need to ensure that file lists are unique within\none variable such as 'nobaseincludeHEADERS' above.\n\nYou should not rely on the order in which files listed in one\nvariable are installed. Likewise, to cater for parallel make, you\nshould not rely on any particular file installation order even among\ndifferent file types (library dependencies are an exception here).\n\nFile: automake-1.16.info, Node: The Two Parts of Install, Next: Extending Installation, Prev: Basics of Installation, Up: Install\n" }, { "name": "12.2 The Two Parts of Install", "content": "Automake generates separate 'install-data' and 'install-exec' rules, in\ncase the installer is installing on multiple machines that share\ndirectory structure--these targets allow the machine-independent parts to\nbe installed only once. 'install-exec' installs platform-dependent\nfiles, and 'install-data' installs platform-independent files. The\n'install' target depends on both of these targets. While Automake tries\nto automatically segregate objects into the correct category, the\n'Makefile.am' author is, in the end, responsible for making sure this is\ndone correctly.\n\nVariables using the standard directory prefixes 'data', 'info',\n'man', 'include', 'oldinclude', 'pkgdata', or 'pkginclude' are installed\nby 'install-data'.\n\nVariables using the standard directory prefixes 'bin', 'sbin',\n'libexec', 'sysconf', 'localstate', 'lib', or 'pkglib' are installed by\n'install-exec'.\n\nFor instance, 'dataDATA' files are installed by 'install-data',\nwhile 'binPROGRAMS' files are installed by 'install-exec'.\n\nAny variable using a user-defined directory prefix with 'exec' in the\nname (e.g., 'myexecbinPROGRAMS') is installed by 'install-exec'. All\nother user-defined prefixes are installed by 'install-data'.\n\nFile: automake-1.16.info, Node: Extending Installation, Next: Staged Installs, Prev: The Two Parts of Install, Up: Install\n" }, { "name": "12.3 Extending Installation", "content": "It is possible to extend this mechanism by defining an\n'install-exec-local' or 'install-data-local' rule. If these rules\nexist, they will be run at 'make install' time. These rules can do\nalmost anything; care is required.\n\nAutomake also supports two install hooks, 'install-exec-hook' and\n'install-data-hook'. These hooks are run after all other install rules\nof the appropriate type, exec or data, have completed. So, for\ninstance, it is possible to perform post-installation modifications\nusing an install hook. *Note Extending::, for some examples.\n\nFile: automake-1.16.info, Node: Staged Installs, Next: Install Rules for the User, Prev: Extending Installation, Up: Install\n" }, { "name": "12.4 Staged Installs", "content": "Automake generates support for the 'DESTDIR' variable in all install\nrules. 'DESTDIR' is used during the 'make install' step to relocate\ninstall objects into a staging area. Each object and path is prefixed\nwith the value of 'DESTDIR' before being copied into the install area.\nHere is an example of typical DESTDIR usage:\n\nmkdir /tmp/staging &&\nmake DESTDIR=/tmp/staging install\n\nThe 'mkdir' command avoids a security problem if the attacker creates\na symbolic link from '/tmp/staging' to a victim area; then 'make' places\ninstall objects in a directory tree built under '/tmp/staging'. If\n'/gnu/bin/foo' and '/gnu/share/aclocal/foo.m4' are to be installed, the\nabove command would install '/tmp/staging/gnu/bin/foo' and\n'/tmp/staging/gnu/share/aclocal/foo.m4'.\n\nThis feature is commonly used to build install images and packages\n(*note DESTDIR::).\n\nSupport for 'DESTDIR' is implemented by coding it directly into the\ninstall rules. If your 'Makefile.am' uses a local install rule (e.g.,\n'install-exec-local') or an install hook, then you must write that code\nto respect 'DESTDIR'.\n\n*Note (standards)Makefile Conventions::, for another usage example.\n\nFile: automake-1.16.info, Node: Install Rules for the User, Prev: Staged Installs, Up: Install\n" }, { "name": "12.5 Install Rules for the User", "content": "Automake also generates rules for targets 'uninstall', 'installdirs',\nand 'install-strip'.\n\nAutomake supports 'uninstall-local' and 'uninstall-hook'. There is\nno notion of separate uninstalls for \"exec\" and \"data\", as these\nfeatures would not provide additional functionality.\n\nNote that 'uninstall' is not meant as a replacement for a real\npackaging tool.\n\nFile: automake-1.16.info, Node: Clean, Next: Dist, Prev: Install, Up: Top\n" } ] }, "13 What Gets Cleaned": { "content": "The GNU Makefile Standards specify a number of different clean rules.\n*Note Standard Targets for Users: (standards)Standard Targets.\n\nGenerally the files that can be cleaned are determined automatically\nby Automake. Of course, Automake also recognizes some variables that\ncan be defined to specify additional files to clean. These variables\nare 'MOSTLYCLEANFILES', 'CLEANFILES', 'DISTCLEANFILES', and\n'MAINTAINERCLEANFILES'.\n\nWhen cleaning involves more than deleting some hard-coded list of\nfiles, it is also possible to supplement the cleaning rules with your\nown commands. Simply define a rule for any of the 'mostlyclean-local',\n'clean-local', 'distclean-local', or 'maintainer-clean-local' targets\n(*note Extending::). A common case is deleting a directory, for\ninstance, a directory created by the test suite:\n\nclean-local:\n-rm -rf testSubDir\n\nSince 'make' allows only one set of rules for a given target, a more\nextensible way of writing this is to use a separate target listed as a\ndependency:\n\nclean-local: clean-local-check\n.PHONY: clean-local-check\nclean-local-check:\n-rm -rf testSubDir\n\nAs the GNU Standards aren't always explicit as to which files should\nbe removed by which rule, we've adopted a heuristic that we believe was\nfirst formulated by Franc,ois Pinard:\n\n* If 'make' built it, and it is commonly something that one would\nwant to rebuild (for instance, a '.o' file), then 'mostlyclean'\nshould delete it.\n\n* Otherwise, if 'make' built it, then 'clean' should delete it.\n\n* If 'configure' built it, then 'distclean' should delete it.\n\n* If the maintainer built it (for instance, a '.info' file), then\n'maintainer-clean' should delete it. However 'maintainer-clean'\nshould not delete anything that needs to exist in order to run\n'./configure && make'.\n\nWe recommend that you follow this same set of heuristics in your\n'Makefile.am'.\n\nFile: automake-1.16.info, Node: Dist, Next: Tests, Prev: Clean, Up: Top\n", "subsections": [] }, "14 What Goes in a Distribution": { "content": "* Menu:\n\n* Basics of Distribution:: Files distributed by default\n* Fine-grained Distribution Control:: 'dist' and 'nodist' prefixes\n* The dist Hook:: A target for last-minute distribution changes\n* Checking the Distribution:: 'make distcheck' explained\n* The Types of Distributions:: A variety of formats and compression methods\n\nFile: automake-1.16.info, Node: Basics of Distribution, Next: Fine-grained Distribution Control, Up: Dist\n", "subsections": [ { "name": "14.1 Basics of Distribution", "content": "The 'dist' rule in the generated 'Makefile.in' can be used to generate a\ngzipped 'tar' file and/or other flavors of archives for distribution.\nThe file is named based on the 'PACKAGE' and 'VERSION' variables\nautomatically defined by either the 'ACINIT' invocation or by a\ndeprecated two-arguments invocation of the 'AMINITAUTOMAKE' macro\n(see *note Public Macros:: for how these variables get their values,\nfrom either defaults or explicit values--it's slightly trickier than one\nwould expect). More precisely, the gzipped 'tar' file is named\n'${PACKAGE}-${VERSION}.tar.gz'.\n\nYou can set the environment variable 'TAR' to override the tar\nprogram used; it defaults to 'tar'. *Note The Types of Distributions::,\nfor how to generate other kinds of archives.\n\nFor the most part, the files to distribute are automatically found by\nAutomake:\n\n* All source files are automatically included in a distribution, as\nare all 'Makefile.am' and 'Makefile.in' files.\n\n* Files that are read by 'configure' are automatically distributed.\nThese are the source files as specified in various Autoconf macros\nsuch as 'ACCONFIGFILES' and siblings.\n\n* Files included in a 'Makefile.am' (using 'include') or in\n'configure.ac' (using 'm4include').\n\n* Automake has a built-in list of commonly used files automatically\nincluded in the distribution if they are found in the current\ndirectory (either physically, or as the target of a 'Makefile.am'\nrule). Some common examples: 'ABOUT-GNU', 'COPYING', 'TODO'.\n\nThis list also includes helper scripts installed with 'automake\n--add-missing'. Some common examples: 'compile', 'config.guess',\n'config.rpath', 'config.sub', 'texinfo.tex'.\n\n* Automake has another built-in list of files automatically\ndistributed if they are found either with the plain name, or with\nextension '.md' (presumably MarkDown, though this not checked).\nThey are checked for in that order, so the plain name is preferred.\nThese are: 'AUTHORS ChangeLog INSTALL NEWS README README-alpha\nTHANKS'.\n\n* A final built-in list of files are those distributed only if other\ncertain conditions hold. For example, the files 'config.h.top' and\n'config.h.bot' are automatically distributed only if, e.g.,\n'ACCONFIGHEADERS([config.h])' is used in 'configure.ac').\n'README-alpha' is another such file, with 'README-alpha.md'\ndistributed if that is what is available; *note Strictness::, for\nits conditions for distribution.\n\nThese three lists of files are given in their entirety in the output\nfrom 'automake --help'.\n\nDespite all this automatic inclusion, it is still common to have\nfiles to be distributed which are not found by the automatic rules. You\nshould listed these files in the 'EXTRADIST' variable. You can mention\nfiles in subdirectories in 'EXTRADIST'.\n\nYou can also mention a directory in 'EXTRADIST'; in this case the\nentire directory will be recursively copied into the distribution. To\nemphasize, this copies everything in the directory, including\ntemporary editor files, intermediate build files, version control files,\netc.; thus we recommend against using this feature as-is. However, you\ncan use the 'dist-hook' feature to ameliorate the problem; *note The\ndist Hook::.\n\nIf you define 'SUBDIRS', Automake will recursively include the\nsubdirectories in the distribution. If 'SUBDIRS' is defined\nconditionally (*note Conditionals::), Automake will normally include all\ndirectories that could possibly appear in 'SUBDIRS' in the distribution.\nIf you need to specify the set of directories conditionally, you can set\nthe variable 'DISTSUBDIRS' to the exact list of subdirectories to\ninclude in the distribution (*note Conditional Subdirectories::).\n\nFile: automake-1.16.info, Node: Fine-grained Distribution Control, Next: The dist Hook, Prev: Basics of Distribution, Up: Dist\n" }, { "name": "14.2 Fine-grained Distribution Control", "content": "Sometimes you need tighter control over what does not go into the\ndistribution; for instance, you might have source files that are\ngenerated and that you do not want to distribute. In this case Automake\ngives fine-grained control using the 'dist' and 'nodist' prefixes. Any\nprimary or 'SOURCES' variable can be prefixed with 'dist' to add the\nlisted files to the distribution. Similarly, 'nodist' can be used to\nomit the files from the distribution.\n\nAs an example, here is how you would cause some data to be\ndistributed while leaving some source code out of the distribution:\n\ndistdataDATA = distribute-this\nbinPROGRAMS = foo\nnodistfooSOURCES = do-not-distribute.c\n\nFile: automake-1.16.info, Node: The dist Hook, Next: Checking the Distribution, Prev: Fine-grained Distribution Control, Up: Dist\n" }, { "name": "14.3 The dist Hook", "content": "Occasionally it is useful to be able to change the distribution before\nit is packaged up. If the 'dist-hook' rule exists, it is run after the\ndistribution directory is filled, but before the actual distribution\narchives are created. One way to use this is for removing unnecessary\nfiles that get recursively included by specifying a directory in\n'EXTRADIST':\n\nEXTRADIST = doc\ndist-hook:\nchmod -R u+w $(distdir)/doc\nrm -rf `find $(distdir)/doc -type d -name RCS`\n\nThe 'dist-hook' recipe should not assume that the regular files in the\ndistribution directory are writable; this might not be the case if one\nis packaging from a read-only source tree, or when a 'make distcheck' is\nbeing done. Similarly, the recipe should not assume that the\nsubdirectories put into the distribution directory as a result of being\nlisted in 'EXTRADIST' are writable. So, if the 'dist-hook' recipe\nwants to modify the content of an existing file (or 'EXTRADIST'\nsubdirectory) in the distribution directory, it should explicitly to\nmake it writable first:\n\nEXTRADIST = README doc\ndist-hook:\nchmod u+w $(distdir)/README $(distdir)/doc\necho \"Distribution date: `date`\" >> $(distdir)/README\nrm -f $(distdir)/doc/HACKING\n\nTwo variables that come handy when writing 'dist-hook' rules are\n'$(distdir)' and '$(topdistdir)'.\n\n'$(distdir)' points to the directory where the 'dist' rule will copy\nfiles from the current directory before creating the tarball. If you\nare at the top-level directory, then 'distdir = $(PACKAGE)-$(VERSION)'.\nWhen used from subdirectory named 'foo/', then 'distdir =\n../$(PACKAGE)-$(VERSION)/foo'. '$(distdir)' can be either a relative or\nabsolute path; do not assume a particular form.\n\n'$(topdistdir)' always points to the root directory of the\ndistributed tree. At the top level it's equal to '$(distdir)'. In the\n'foo/' subdirectory 'topdistdir = ../$(PACKAGE)-$(VERSION)'.\n'$(topdistdir)' can also be either a relative or absolute path.\n\nWhen packages are nested using 'ACCONFIGSUBDIRS' (*note\nSubpackages::), then '$(distdir)' and '$(topdistdir)' are relative to\nthe package where 'make dist' was run, not to any sub-packages involved.\n\nFile: automake-1.16.info, Node: Checking the Distribution, Next: The Types of Distributions, Prev: The dist Hook, Up: Dist\n" }, { "name": "14.4 Checking the Distribution", "content": "Automake also generates a 'distcheck' rule that can be of help to ensure\nthat a given distribution will actually work. Simplifying a bit, we can\nsay this rule first makes a distribution, and then, operating from it,\ntakes the following steps (in this order):\n* tries to do a 'VPATH' build (*note VPATH Builds::), with the\n'srcdir' and all its content made read-only;\n* tries to make the printable documentation, if any (with 'make\ndvi'),\n* runs the test suite (with 'make check') on this fresh build;\n* installs the package in a temporary directory (with 'make\ninstall'), and runs the test suite on the resulting installation\n(with 'make installcheck');\n* checks that the package can be correctly uninstalled (by 'make\nuninstall') and cleaned (by 'make distclean');\n* finally, makes another tarball to ensure the distribution is\nself-contained.\n\nAll of these actions are performed in a temporary directory. The\nexact location and the exact structure of such a directory (where the\nread-only sources are placed, how the temporary build and install\ndirectories are named and how deeply they are nested, etc.) is to be\nconsidered an implementation detail, which can change at any time; so do\nnot rely on it.\n\n\nBuilding the package involves running './configure'. If you need to\nsupply additional flags to 'configure', define them in the\n'AMDISTCHECKCONFIGUREFLAGS' variable in your top-level 'Makefile.am'.\nThe user can still extend or override the flags provided there by\ndefining the 'DISTCHECKCONFIGUREFLAGS' variable, on the command line\nwhen invoking 'make'. It's worth noting that 'make distcheck' needs\ncomplete control over the 'configure' options '--srcdir' and '--prefix',\nso those options cannot be overridden by 'AMDISTCHECKCONFIGUREFLAGS'\nnor by 'DISTCHECKCONFIGUREFLAGS'.\n\nAlso note that developers are encouraged to strive to make their code\nbuildable without requiring any special configure option; thus, in\ngeneral, you shouldn't define 'AMDISTCHECKCONFIGUREFLAGS'. However,\nthere might be few scenarios in which the use of this variable is\njustified. GNU 'm4' offers an example. GNU 'm4' configures by default\nwith its experimental and seldom used \"changeword\" feature disabled; so\nin this case it is useful to have 'make distcheck' run configure with\nthe '--with-changeword' option, to ensure that the code for changeword\nsupport still compiles correctly. GNU 'm4' also employs the\n'AMDISTCHECKCONFIGUREFLAGS' variable to stress-test the use of\n'--program-prefix=g', since at one point the 'm4' build system had a bug\nwhere 'make installcheck' was wrongly assuming it could blindly test\n\"'m4'\", rather than the just-installed \"'gm4'\".\n\n\nOrdinarily, 'make distcheck' runs 'make dvi'. It does nothing if the\ndistribution contains no Texinfo sources. If the distribution does\ncontain a Texinfo manual, by default the 'dvi' target will run TeX to\nmake sure it can be successfully processed (*note Texinfo::).\n\nHowever, you may wish to test the manual by producing 'pdf' (e.g., if\nyour manual uses images in formats other than 'eps'), 'html' (if you\ndon't have TeX at all), some other format, or just skip the test\nentirely (not recommended). You can change the target that is run by\nsetting the variable 'AMDISTCHECKDVITARGET' in your 'Makefile.am';\nfor example,\n\nAMDISTCHECKDVITARGET = pdf\n\nTo make 'dvi' into a do-nothing target, see the example for\n'EMPTYAUTOMAKETARGETS' in *note Third-Party Makefiles::.\n\n\nIf the 'distcheck-hook' rule is defined in your top-level 'Makefile.am',\nthen it will be invoked by 'distcheck' after the new distribution has\nbeen unpacked, but before the unpacked copy is configured and built.\nYour 'distcheck-hook' can do almost anything, though as always caution\nis advised. Generally this hook is used to check for potential\ndistribution errors not caught by the standard mechanism. Note that\n'distcheck-hook' as well as 'AMDISTCHECKCONFIGUREFLAGS' and\n'DISTCHECKCONFIGUREFLAGS' are not honored in a subpackage\n'Makefile.am', but the flags from 'AMDISTCHECKCONFIGUREFLAGS' and\n'DISTCHECKCONFIGUREFLAGS' are passed down to the 'configure' script of\nthe subpackage.\n\n\nSpeaking of potential distribution errors, 'distcheck' also ensures that\nthe 'distclean' rule actually removes all built files. This is done by\nrunning 'make distcleancheck' at the end of the 'VPATH' build. By\ndefault, 'distcleancheck' will run 'distclean' and then make sure the\nbuild tree has been emptied by running '$(distcleanchecklistfiles)'.\nUsually this check will find generated files that you forgot to add to\nthe 'DISTCLEANFILES' variable (*note Clean::).\n\nThe 'distcleancheck' behavior should be OK for most packages,\notherwise you have the possibility to override the definition of either\nthe 'distcleancheck' rule, or the '$(distcleanchecklistfiles)'\nvariable. For instance, to disable 'distcleancheck' completely, add the\nfollowing rule to your top-level 'Makefile.am':\n\ndistcleancheck:\n@:\n\nIf you want 'distcleancheck' to ignore built files that have not been\ncleaned because they are also part of the distribution, add the\nfollowing definition instead:\n\ndistcleanchecklistfiles = \\\nfind . -type f -exec sh -c 'test -f $(srcdir)/$$1 || echo $$1' \\\nsh '{}' ';'\n\nThe above definition is not the default because it's usually an error\nif your Makefiles cause some distributed files to be rebuilt when the\nuser builds the package. (Think about the user missing the tool\nrequired to build the file; or if the required tool is built by your\npackage, consider the cross-compilation case where it can't be run.)\nThere is an entry in the FAQ about this (*note Errors with distclean::);\nmake sure you read it before playing with 'distcleanchecklistfiles'.\n\n\n'distcheck' also checks that the 'uninstall' rule works properly, both\nfor ordinary and 'DESTDIR' builds. It does this by invoking 'make\nuninstall', and then it checks the install tree to see if any files are\nleft over. This check will make sure that you correctly coded your\n'uninstall'-related rules.\n\nBy default, the checking is done by the 'distuninstallcheck' rule,\nand the list of files in the install tree is generated by\n'$(distuninstallchecklistfiles)' (this is a variable whose value is a\nshell command to run that prints the list of files to stdout).\n\nEither of these can be overridden to modify the behavior of\n'distcheck'. For instance, to disable this check completely, you would\nwrite:\n\ndistuninstallcheck:\n@:\n\nFile: automake-1.16.info, Node: The Types of Distributions, Prev: Checking the Distribution, Up: Dist\n" }, { "name": "14.5 The Types of Distributions", "content": "Automake generates rules to provide archives of the project for\ndistributions in various formats. Their targets are:\n\n'dist-gzip'\nGenerate a 'gzip' tar archive of the distribution. This is the\nonly format enabled by default. By default, this rule makes 'gzip'\nuse a compression option of '--best'. To make it use a different\none, set the 'GZIPENV' environment variable. For example, 'make\ndist-gzip GZIPENV=-7'.\n\n'dist-bzip2'\nGenerate a 'bzip2' tar archive of the distribution. bzip2 archives\nare usually smaller than gzipped archives. By default, this rule\nmakes 'bzip2' use a compression option of '-9'. To make it use a\ndifferent one, set the 'BZIP2' environment variable.\n\n'dist-lzip'\nGenerate an 'lzip' tar archive of the distribution. 'lzip'\narchives are usually smaller than 'bzip2'-compressed archives. By\ndefault, this rule makes 'lzip' use a compression option of '-9'.\nTo make it use a different one, set the 'LZIPOPT' environment\nvariable.\n\n'dist-xz'\nGenerate an 'xz' tar archive of the distribution. 'xz' archives\nare usually smaller than 'bzip2'-compressed archives. By default,\nthis rule makes 'xz' use a compression option of '-e'. To make it\nuse a different one, set the 'XZOPT' environment variable. For\nexample, run this command to use the default compression ratio, but\nwith a progress indicator: 'make dist-xz XZOPT=-ve'.\n\n'dist-zip'\nGenerate a 'zip' archive of the distribution.\n\n'dist-zstd'\nGenerate a 'zstd' tar archive of the distribution. By default,\nthis rule makes 'zstd' use a compression option of '-19'. To use a\ndifferent setting, set the 'ZSTDOPT' environment variable. For\nexample, run this command to use the default compression ratio, but\nwith a progress indicator: 'make dist-zstd ZSTDOPT=-19v'.\nHowever, note that for compatibility with 'zstd' itself, you may\ninstead set the 'ZSTDCLEVEL' environment variable, in which case,\nany 'ZSTDOPT' setting is ignored.\n\n'dist-shar'\nGenerate a 'shar' archive of the distribution. This format archive\nis obsolescent, and use of this option is deprecated. It and the\ncorresponding functionality will be removed altogether in Automake\n2.0.\n\n'dist-tarZ'\nGenerate a tar archive of the distribution, compressed with the\nhistorical (and obsolescent) program 'compress'. This option is\ndeprecated, and it and the corresponding functionality will be\nremoved altogether in Automake 2.0.\n\nThe rule 'dist' (and its historical synonym 'dist-all') will create\narchives in all the enabled formats (*note List of Automake options::\nfor how to change this list). By default, only the 'dist-gzip' target\nis enabled by 'dist'.\n\nFile: automake-1.16.info, Node: Tests, Next: Rebuilding, Prev: Dist, Up: Top\n" } ] }, "15 Support for test suites": { "content": "Automake can generate code to handle two kinds of test suites. One is\nbased on integration with the 'dejagnu' framework. The other (and most\nused) form is based on the use of generic test scripts, and its\nactivation is triggered by the definition of the special 'TESTS'\nvariable. This second form allows for various degrees of sophistication\nand customization; in particular, it allows for concurrent execution of\ntest scripts, use of established test protocols such as TAP, and\ndefinition of custom test drivers and test runners.\n\nIn either case, the testsuite is invoked via 'make check'.\n\n* Menu:\n\n* Generalities about Testing:: Concepts and terminology about testing\n* Simple Tests:: Listing test scripts in 'TESTS'\n* Custom Test Drivers:: Writing and using custom test drivers\n* Using the TAP test protocol:: Integrating test scripts that use the TAP protocol\n* DejaGnu Tests:: Interfacing with the 'dejagnu' testing framework\n* Install Tests:: Running tests on installed packages\n\nFile: automake-1.16.info, Node: Generalities about Testing, Next: Simple Tests, Up: Tests\n", "subsections": [ { "name": "15.1 Generalities about Testing", "content": "The purpose of testing is to determine whether a program or system\nbehaves as expected (e.g., known inputs produce the expected outputs,\nerror conditions are correctly handled or reported, and older bugs do\nnot resurface).\n\nThe minimal unit of testing is usually called test case, or simply\ntest. How a test case is defined or delimited, and even what exactly\nconstitutes a test case, depends heavily on the testing paradigm\nand/or framework in use, so we won't attempt any more precise\ndefinition. The set of the test cases for a given program or system\nconstitutes its testsuite.\n\nA test harness (also testsuite harness) is a program or software\ncomponent that executes all (or part of) the defined test cases,\nanalyzes their outcomes, and reports or registers these outcomes\nappropriately. Again, the details of how this is accomplished (and how\nthe developer and user can influence it or interface with it) varies\nwildly, and we'll attempt no precise definition.\n\nA test is said to pass when it can determine that the condition or\nbehaviour it means to verify holds, and is said to fail when it can\ndetermine that such condition of behaviour does not hold.\n\nSometimes, tests can rely on non-portable tools or prerequisites, or\nsimply make no sense on a given system (for example, a test checking a\nWindows-specific feature makes no sense on a GNU/Linux system). In this\ncase, accordingly to the definition above, the tests can neither be\nconsidered passed nor failed; instead, they are skipped, that is, they\nare not run, or their result is in any case ignored for what concerns\nthe count of failures and successes. Skips are usually explicitly\nreported though, so that the user will be aware that not all of the\ntestsuite has been run.\n\nIt's not uncommon, especially during early development stages, that\nsome tests fail for known reasons, and that the developer doesn't want\nto tackle these failures immediately (this is especially true when the\nfailing tests deal with corner cases). In this situation, the better\npolicy is to declare that each of those failures is an expected\nfailure (or xfail). In case a test that is expected to fail ends up\npassing instead, many testing environments will flag the result as a\nspecial kind of failure called unexpected pass (or xpass).\n\nMany testing environments and frameworks distinguish between test\nfailures and hard errors. As we've seen, a test failure happens when\nsome invariant or expected behaviour of the software under test is not\nmet. A hard error happens when e.g., the set-up of a test case\nscenario fails, or when some other unexpected or highly undesirable\ncondition is encountered (for example, the program under test\nexperiences a segmentation fault).\n\nFile: automake-1.16.info, Node: Simple Tests, Next: Custom Test Drivers, Prev: Generalities about Testing, Up: Tests\n" }, { "name": "15.2 Simple Tests", "content": "* Menu:\n\n* Scripts-based Testsuites:: Automake-specific concepts and terminology\n* Serial Test Harness:: Older (and discouraged) serial test harness\n* Parallel Test Harness:: Generic concurrent test harness\n\nFile: automake-1.16.info, Node: Scripts-based Testsuites, Next: Serial Test Harness, Up: Simple Tests\n\n\nIf the special variable 'TESTS' is defined, its value is taken to be a\nlist of programs or scripts to run in order to do the testing. Under\nthe appropriate circumstances, it's possible for 'TESTS' to list also\ndata files to be passed to one or more test scripts defined by different\nmeans (the so-called \"log compilers\", *note Parallel Test Harness::).\n\nTest scripts can be executed serially or concurrently. Automake\nsupports both these kinds of test execution, with the parallel test\nharness being the default. The concurrent test harness relies on the\nconcurrence capabilities (if any) offered by the underlying 'make'\nimplementation, and can thus only be as good as those are.\n\nBy default, only the exit statuses of the test scripts are considered\nwhen determining the testsuite outcome. But Automake allows also the\nuse of more complex test protocols, either standard (*note Using the TAP\ntest protocol::) or custom (*note Custom Test Drivers::). You can't\nenable such protocols when the serial harness is used, though. In the\nrest of this section we are going to concentrate mostly on protocol-less\ntests, since we cover test protocols in a later section (again, *note\nCustom Test Drivers::).\n\nWhen no test protocol is in use, an exit status of 0 from a test\nscript will denote a success, an exit status of 77 a skipped test, an\nexit status of 99 a hard error, and any other exit status will denote a\nfailure.\n\nYou may define the variable 'XFAILTESTS' to a list of tests (usually\na subset of 'TESTS') that are expected to fail; this will effectively\nreverse the result of those tests (with the provision that skips and\nhard errors remain untouched). You may also instruct the testsuite\nharness to treat hard errors like simple failures, by defining the\n'DISABLEHARDERRORS' make variable to a nonempty value.\n\nNote however that, for tests based on more complex test protocols,\nthe exact effects of 'XFAILTESTS' and 'DISABLEHARDERRORS' might\nchange, or they might even have no effect at all (for example, in tests\nusing TAP, there is no way to disable hard errors, and the\n'DISABLEHARDERRORS' variable has no effect on them).\n\nThe result of each test case run by the scripts in 'TESTS' will be\nprinted on standard output, along with the test name. For test\nprotocols that allow more test cases per test script (such as TAP), a\nnumber, identifier and/or brief description specific for the single test\ncase is expected to be printed in addition to the name of the test\nscript. The possible results (whose meanings should be clear from the\nprevious *note Generalities about Testing::) are 'PASS', 'FAIL', 'SKIP',\n'XFAIL', 'XPASS' and 'ERROR'. Here is an example of output from a\nhypothetical testsuite that uses both plain and TAP tests:\nPASS: foo.sh\nPASS: zardoz.tap 1 - Daemon started\nPASS: zardoz.tap 2 - Daemon responding\nSKIP: zardoz.tap 3 - Daemon uses /proc # SKIP /proc is not mounted\nPASS: zardoz.tap 4 - Daemon stopped\nSKIP: bar.sh\nPASS: mu.tap 1\nXFAIL: mu.tap 2 # TODO frobnication not yet implemented\n\nA testsuite summary (expected to report at least the number of run,\nskipped and failed tests) will be printed at the end of the testsuite\nrun. By default, the first line of the summary has the form:\n\nTestsuite summary for PACKAGE-STRING\n\nwhere PACKAGE-STRING is the name and version of the package. If you\nhave several independent test suites for different parts of the package,\nthough, it can be misleading for each suite to imply it is for the whole\npackage. Or, in complex projects, you may wish to add the current\ndirectory or other information to the testsuite header line. So you can\noverride the ' for PACKAGE-STRING' suffix on that line by setting the\n'AMTESTSUITESUMMARYHEADER' variable. The value of this variable is\nused unquoted in a shell echo command, so you must include any necessary\nquotes. For example, the default value is\n\nAMTESTSUITESUMMARYHEADER = ' for $(PACKAGESTRING)'\n\nincluding the double quotes (interpreted by the shell) and the leading\nspace (since the value is output directly after the 'Testsuite\nsummary'). The '$(PACKAGESTRING)' is substituted by 'make'.\n\nIf the standard output is connected to a capable terminal, then the\ntest results and the summary are colored appropriately. The developer\nand the user can disable colored output by setting the 'make' variable\n'AMCOLORTESTS=no'; the user can in addition force colored output even\nwithout a connecting terminal with 'AMCOLORTESTS=always'. It's also\nworth noting that some 'make' implementations, when used in parallel\nmode, have slightly different semantics (*note (autoconf)Parallel\nmake::), which can break the automatic detection of a connection to a\ncapable terminal. If this is the case, the user will have to resort to\nthe use of 'AMCOLORTESTS=always' in order to have the testsuite output\ncolorized.\n\nTest programs that need data files should look for them in 'srcdir'\n(which is both a make variable and an environment variable made\navailable to the tests), so that they work when building in a separate\ndirectory (*note Build Directories: (autoconf)Build Directories.), and\nin particular for the 'distcheck' rule (*note Checking the\nDistribution::).\n\nAutomake ensures that each file listed in 'TESTS' is built before it\nis run; you can list both source and derived programs (or scripts) in\n'TESTS'; the generated rule will look both in 'srcdir' and ''..''. For\ninstance, you might want to run a C program as a test. To do this you\nwould list its name in 'TESTS' and also in 'checkPROGRAMS', and then\nspecify it as you would any other program.\n\nPrograms listed in 'checkPROGRAMS' (and 'checkLIBRARIES',\n'checkLTLIBRARIES', ...) are only built during 'make check', not\nduring 'make all'. You should list there any program needed by your\ntests that does not need to be built by 'make all'. The programs in\n'checkPROGRAMS' are not automatically added to 'TESTS' because\n'checkPROGRAMS' usually lists programs used by the tests, not the tests\nthemselves. If all your programs are in fact test cases, you can set\n'TESTS = $(checkPROGRAMS)'.\n\n* Menu:\n\n* Testsuite Environment Overrides::\n\nFile: automake-1.16.info, Node: Testsuite Environment Overrides, Up: Scripts-based Testsuites\n\n15.2.1.1 Testsuite Environment Overrides\n........................................\n\nThe 'AMTESTSENVIRONMENT' and 'TESTSENVIRONMENT' variables can be used\nto run initialization code and set environment variables for the test\nscripts. The former variable is developer-reserved, and can be defined\nin the 'Makefile.am', while the latter is reserved for the user, which\ncan employ it to extend or override the settings in the former; for this\nto work portably, however, the contents of a non-empty\n'AMTESTSENVIRONMENT' must be terminated by a semicolon.\n\nThe 'AMTESTSFDREDIRECT' variable can be used to define file\ndescriptor redirections for the test scripts. One might think that\n'AMTESTSENVIRONMENT' could be used for this purpose, but experience\nhas shown that doing so portably is practically impossible. The main\nhurdle is constituted by Korn shells, which usually set the\nclose-on-exec flag on file descriptors opened with the 'exec' builtin,\nthus rendering an idiom like 'AMTESTSENVIRONMENT = exec 9>&2;'\nineffectual. This issue also affects some Bourne shells, such as the\nHP-UX's '/bin/sh'.\n\nAMTESTSENVIRONMENT = \\\n## Some environment initializations are kept in a separate shell\n## file 'tests-env.sh', which can make it easier to also run tests\n## from the command line.\n. $(srcdir)/tests-env.sh; \\\n## On Solaris, prefer more POSIX-compliant versions of the standard\n## tools by default.\nif test -d /usr/xpg4/bin; then \\\nPATH=/usr/xpg4/bin:$$PATH; export PATH; \\\nfi;\n\n## With this, the test scripts will be able to print diagnostic\n## messages to the original standard error stream, even if the test\n## driver redirects the stderr of the test scripts to a log file\n## before executing them.\nAMTESTSFDREDIRECT = 9>&2\n\nAs another example, a notice that a test is starting can be emitted\nusing 'AMTESTSENVIRONMENT' (for package maintainers) or\n'TESTSENVIRONMENT' by users:\n\nmake -j12 ... TESTSENVIRONMENT='echo RUNNING: \"$$f\";' check\n\nThe shell variable '$f' contains the test name. (Although technically\nthis is not guaranteed, in practice it is extremely unlikely to ever\nchange.) This can be helpful to see when trying to debug test failures.\n\nNotwithstanding these benefits, 'AMTESTSENVIRONMENT' is, for\nhistorical and implementation reasons, not supported by the serial\nharness (*note Serial Test Harness::).\n\nFile: automake-1.16.info, Node: Serial Test Harness, Next: Parallel Test Harness, Prev: Scripts-based Testsuites, Up: Simple Tests\n\n\nFirst, note that today the use of this harness is strongly discouraged\nin favour of the parallel test harness (*note Parallel Test Harness::).\nStill, there are a few situations when the advantages offered by the\nparallel harness are irrelevant, and when test concurrency can even\ncause tricky problems. In those cases, it might make sense to still use\nthe serial harness, for simplicity and reliability (we still suggest\ntrying to give the parallel harness a shot though).\n\nThe serial test harness is enabled by the Automake option\n'serial-tests'. It operates by simply running the tests serially, one\nat the time, without any I/O redirection. It's up to the user to\nimplement logging of tests' output, if that's required or desired.\n\nFor historical and implementation reasons, the 'AMTESTSENVIRONMENT'\nvariable is not supported by this harness (it will be silently ignored\nif defined); only 'TESTSENVIRONMENT' is, and it is to be considered a\ndeveloper-reserved variable. This is done so that, when using the\nserial harness, 'TESTSENVIRONMENT' can be defined to an invocation of\nan interpreter through which the tests are to be run. For instance, the\nfollowing setup may be used to run tests with Perl:\n\nTESTSENVIRONMENT = $(PERL) -Mstrict -w\nTESTS = foo.pl bar.pl baz.pl\n\nIt's important to note that the use of 'TESTSENVIRONMENT' endorsed here\nwould be invalid with the parallel harness. That harness provides a\nmore elegant way to achieve the same effect, with the further benefit of\nfreeing the 'TESTSENVIRONMENT' variable for the user (*note Parallel\nTest Harness::).\n\nAnother, less serious limitation of the serial harness is that it\ndoesn't distinguish between simple failures and hard errors; this is for\nhistorical reasons, and might be fixed in future Automake versions.\n\nFile: automake-1.16.info, Node: Parallel Test Harness, Prev: Serial Test Harness, Up: Simple Tests\n\n\nBy default, Automake generated a parallel (concurrent) test harness. It\nfeatures automatic collection of the test scripts output in '.log'\nfiles, concurrent execution of tests with 'make -j', specification of\ninter-test dependencies, lazy reruns of tests that have not completed in\na prior run, and hard errors for exceptional failures.\n\nThe parallel test harness operates by defining a set of 'make' rules\nthat run the test scripts listed in 'TESTS', and, for each such script,\nsave its output in a corresponding '.log' file and its results (and\nother \"metadata\", *note API for Custom Test Drivers::) in a\ncorresponding '.trs' (as in Test ReSults) file. The '.log' file will\ncontain all the output emitted by the test on its standard output and\nits standard error. The '.trs' file will contain, among the other\nthings, the results of the test cases run by the script.\n\nThe parallel test harness will also create a summary log file,\n'TESTSUITELOG', which defaults to 'test-suite.log' and requires a\n'.log' suffix. This file depends upon all the '.log' and '.trs' files\ncreated for the test scripts listed in 'TESTS'.\n\nAs with the serial harness above, by default one status line is\nprinted per completed test, and a short summary after the suite has\ncompleted. However, standard output and standard error of the test are\nredirected to a per-test log file, so that parallel execution does not\nproduce intermingled output. The output from failed tests is collected\nin the 'test-suite.log' file. If the variable 'VERBOSE' is set, this\nfile is output after the summary.\n\nEach couple of '.log' and '.trs' files is created when the\ncorresponding test has completed. The set of log files is listed in the\nread-only variable 'TESTLOGS', and defaults to 'TESTS', with the\nexecutable extension if any (*note EXEEXT::), as well as any suffix\nlisted in 'TESTEXTENSIONS' removed, and '.log' appended. Results are\nundefined if a test file name ends in several concatenated suffixes.\n'TESTEXTENSIONS' defaults to '.test'; it can be overridden by the user,\nin which case any extension listed in it must be constituted by a dot,\nfollowed by a non-digit alphabetic character, followed by any number of\nalphabetic characters. For example, '.sh', '.T' and '.t1' are valid\nextensions, while '.x-y', '.6c' and '.t.1' are not.\n\nIt is important to note that, due to current limitations (unlikely to\nbe lifted), configure substitutions in the definition of 'TESTS' can\nonly work if they will expand to a list of tests that have a suffix\nlisted in 'TESTEXTENSIONS'.\n\nFor tests that match an extension '.EXT' listed in 'TESTEXTENSIONS',\nyou can provide a custom \"test runner\" using the variable\n'EXTLOGCOMPILER' (note the upper-case extension) and pass options in\n'AMEXTLOGFLAGS' and allow the user to pass options in\n'EXTLOGFLAGS'. It will cause all tests with this extension to be\ncalled with this runner. For all tests without a registered extension,\nthe variables 'LOGCOMPILER', 'AMLOGFLAGS', and 'LOGFLAGS' may be\nused. For example,\n\nTESTS = foo.pl bar.py baz\nTESTEXTENSIONS = .pl .py\nPLLOGCOMPILER = $(PERL)\nAMPLLOGFLAGS = -w\nPYLOGCOMPILER = $(PYTHON)\nAMPYLOGFLAGS = -v\nLOGCOMPILER = ./wrapper-script\nAMLOGFLAGS = -d\n\nwill invoke '$(PERL) -w foo.pl', '$(PYTHON) -v bar.py', and\n'./wrapper-script -d baz' to produce 'foo.log', 'bar.log', and\n'baz.log', respectively. The 'foo.trs', 'bar.trs' and 'baz.trs' files\nwill be automatically produced as a side-effect.\n\nIt's important to note that, differently from what we've seen for the\nserial test harness (*note Serial Test Harness::), the\n'AMTESTSENVIRONMENT' and 'TESTSENVIRONMENT' variables cannot be\nused to define a custom test runner; the 'LOGCOMPILER' and 'LOGFLAGS'\n(or their extension-specific counterparts) should be used instead:\n\n## This is WRONG!\nAMTESTSENVIRONMENT = PERL5LIB='$(srcdir)/lib' $(PERL) -Mstrict -w\n\n## Do this instead.\nAMTESTSENVIRONMENT = PERL5LIB='$(srcdir)/lib'; export PERL5LIB;\nLOGCOMPILER = $(PERL)\nAMLOGFLAGS = -Mstrict -w\n\nBy default, the test suite harness will run all tests, but there are\nseveral ways to limit the set of tests that are run:\n\n* You can set the 'TESTS' variable. For example, you can use a\ncommand like this to run only a subset of the tests:\n\nenv TESTS=\"foo.test bar.test\" make -e check\n\nIf you're using a recursive make setup, you'll probably also need\nto override 'SUBDIRS':\n\nenv TESTS=\"foo.test bar.test\" make -e check SUBDIRS=\n\nOtherwise, the test harness will descend into all subdirectories,\nwhere the tests presumably do not exist, and thus fail. (Patch to\nprovide better behavior would be welcome.)\n\nAnother issue: the command above will unconditionally overwrite the\n'test-suite.log' file, thus clobbering the recorded results of any\nprevious testsuite run. This might be undesirable for packages\nwhose testsuite takes a long time to execute. Luckily, this\nproblem can easily be avoided by also overriding 'TESTSUITELOG'\nat runtime; for example,\n\nenv TESTSUITELOG=partial.log TESTS=\"...\" make -e check\n\nwill write the result of the partial testsuite runs to the\n'partial.log', without touching 'test-suite.log'.\n\n* You can set the 'TESTLOGS' variable. By default, this variable is\ncomputed at 'make' run time from the value of 'TESTS' as described\nabove. For example, you can use the following:\n\nset x subset*.log; shift\nenv TESTLOGS=\"foo.log $*\" make -e check\n\nThe comments made above about 'TESTSUITELOG' overriding applies\nhere too.\n\n* By default, the test harness removes all old per-test '.log' and\n'.trs' files before it starts running tests to regenerate them.\nThe variable 'RECHECKLOGS' contains the set of '.log' (and, by\nimplication, '.trs') files which are removed. 'RECHECKLOGS'\ndefaults to 'TESTLOGS', which means all tests need to be\nrechecked. By overriding this variable, you can choose which tests\nneed to be reconsidered. For example, you can lazily rerun only\nthose tests which are outdated, i.e., older than their prerequisite\ntest files, by setting this variable to the empty value:\n\nenv RECHECKLOGS= make -e check\n\n* You can ensure that all tests are rerun which have failed or passed\nunexpectedly, by running 'make recheck' in the test directory.\nThis convenience target will set 'RECHECKLOGS' appropriately\nbefore invoking the main test harness.\n\nIn order to guarantee an ordering between tests even with 'make -jN',\ndependencies between the corresponding '.log' files may be specified\nthrough usual 'make' dependencies. For example, the following snippet\nlets the test named 'foo-execute.test' depend upon completion of the\ntest 'foo-compile.test':\n\nTESTS = foo-compile.test foo-execute.test\nfoo-execute.log: foo-compile.log\n\nPlease note that this ordering ignores the results of required tests,\nthus the test 'foo-execute.test' is run even if the test\n'foo-compile.test' failed or was skipped beforehand. Further, please\nnote that specifying such dependencies currently works only for tests\nthat end in one of the suffixes listed in 'TESTEXTENSIONS'.\n\nTests without such specified dependencies may be run concurrently\nwith parallel 'make -jN', so be sure they are prepared for concurrent\nexecution.\n\nThe combination of lazy test execution and correct dependencies\nbetween tests and their sources may be exploited for efficient unit\ntesting during development. To further speed up the edit-compile-test\ncycle, it may even be useful to specify compiled programs in\n'EXTRAPROGRAMS' instead of with 'checkPROGRAMS', as the former allows\nintertwined compilation and test execution (but note that\n'EXTRAPROGRAMS' are not cleaned automatically; *note Uniform::).\n\nThe variables 'TESTS' and 'XFAILTESTS' may contain conditional parts\nas well as configure substitutions. In the latter case, however,\ncertain restrictions apply: substituted test names must end with a\nnonempty test suffix like '.test', so that one of the inference rules\ngenerated by 'automake' can apply. For literal test names, 'automake'\ncan generate per-target rules to avoid this limitation.\n\nPlease note that it is currently not possible to use '$(srcdir)/' or\n'$(topsrcdir)/' in the 'TESTS' variable. This technical limitation is\nnecessary to avoid generating test logs in the source tree and has the\nunfortunate consequence that it is not possible to specify distributed\ntests that are themselves generated by means of explicit rules, in a way\nthat is portable to all 'make' implementations (*note (autoconf)Make\nTarget Lookup::, the semantics of FreeBSD and OpenBSD 'make' conflict\nwith this). In case of doubt you may want to require to use GNU 'make',\nor work around the issue with inference rules to generate the tests.\n\nFile: automake-1.16.info, Node: Custom Test Drivers, Next: Using the TAP test protocol, Prev: Simple Tests, Up: Tests\n" }, { "name": "15.3 Custom Test Drivers", "content": "* Menu:\n\n* Overview of Custom Test Drivers Support::\n* Declaring Custom Test Drivers::\n* API for Custom Test Drivers::\n\nFile: automake-1.16.info, Node: Overview of Custom Test Drivers Support, Next: Declaring Custom Test Drivers, Up: Custom Test Drivers\n\n\nStarting from Automake version 1.12, the parallel test harness allows\nthe package authors to use third-party custom test drivers, in case the\ndefault ones are inadequate for their purposes, or do not support their\ntesting protocol of choice.\n\nA custom test driver is expected to properly run the test programs\npassed to it (including the command-line arguments passed to those\nprograms, if any), to analyze their execution and outcome, to create the\n'.log' and '.trs' files associated to these test runs, and to display\nthe test results on the console. It is responsibility of the author of\nthe test driver to ensure that it implements all the above steps\nmeaningfully and correctly; Automake isn't and can't be of any help\nhere. On the other hand, the Automake-provided code for testsuite\nsummary generation offers support for test drivers allowing several test\nresults per test script, if they take care to register such results\nproperly (*note Log files generation and test results recording::).\n\nThe exact details of how test scripts' results are to be determined\nand analyzed is left to the individual drivers. Some drivers might only\nconsider the test script exit status (this is done for example by the\ndefault test driver used by the parallel test harness, described in the\nprevious section). Other drivers might implement more complex and\nadvanced test protocols, which might require them to parse and interpret\nthe output emitted by the test script they're running (examples of such\nprotocols are TAP and SubUnit).\n\nIt's very important to note that, even when using custom test\ndrivers, most of the infrastructure described in the previous section\nabout the parallel harness remains in place; this includes:\n\n* list of test scripts defined in 'TESTS', and overridable at runtime\nthrough the redefinition of 'TESTS' or 'TESTLOGS';\n* concurrency through the use of 'make''s option '-j';\n* per-test '.log' and '.trs' files, and generation of a summary\n'.log' file from them;\n* 'recheck' target, 'RECHECKLOGS' variable, and lazy reruns of\ntests;\n* inter-test dependencies;\n* support for 'check*' variables ('checkPROGRAMS',\n'checkLIBRARIES', ...);\n* use of 'VERBOSE' environment variable to get verbose output on\ntestsuite failures;\n* definition and honoring of 'TESTSENVIRONMENT',\n'AMTESTSENVIRONMENT' and 'AMTESTSFDREDIRECT' variables;\n* definition of generic and extension-specific 'LOGCOMPILER' and\n'LOGFLAGS' variables.\n\nOn the other hand, the exact semantics of how (and if) testsuite output\ncolorization, 'XFAILTESTS', and hard errors are supported and handled\nis left to the individual test drivers.\n\nFile: automake-1.16.info, Node: Declaring Custom Test Drivers, Next: API for Custom Test Drivers, Prev: Overview of Custom Test Drivers Support, Up: Custom Test Drivers\n\n\nCustom testsuite drivers are declared by defining the make variables\n'LOGDRIVER' or 'EXTLOGDRIVER' (where EXT must be declared in\n'TESTEXTENSIONS'). They must be defined to programs or scripts that\nwill be used to drive the execution, logging, and outcome report of the\ntests with corresponding extensions (or of those with no registered\nextension in the case of 'LOGDRIVER'). Clearly, multiple distinct test\ndrivers can be declared in the same 'Makefile.am'. Note moreover that\nthe 'LOGDRIVER' variables are not a substitute for the 'LOGCOMPILER'\nvariables: the two sets of variables can, and often do, usefully and\nlegitimately coexist.\n\nThe developer-reserved variable 'AMLOGDRIVERFLAGS' and the\nuser-reserved variable 'LOGDRIVERFLAGS' can be used to define flags\nthat will be passed to each invocation of 'LOGDRIVER', with the\nuser-defined flags obviously taking precedence over the\ndeveloper-reserved ones. Similarly, for each extension EXT declared in\n'TESTEXTENSIONS', flags listed in 'AMEXTLOGDRIVERFLAGS' and\n'EXTLOGDRIVERFLAGS' will be passed to invocations of\n'EXTLOGDRIVER'.\n\nFile: automake-1.16.info, Node: API for Custom Test Drivers, Prev: Declaring Custom Test Drivers, Up: Custom Test Drivers\n\n\nNote that the APIs described here are still highly experimental, and\nwill very likely undergo tightening and possibly extensive changes in\nthe future, to accommodate for new features or to satisfy additional\nportability requirements.\n\nThe main characteristic of these APIs is that they are designed to\nshare as much infrastructure, semantics, and implementation detail as\npossible with the parallel test harness and its default driver.\n\n* Menu:\n\n* Command-line arguments for test drivers::\n* Log files generation and test results recording::\n* Testsuite progress output::\n\nFile: automake-1.16.info, Node: Command-line arguments for test drivers, Next: Log files generation and test results recording, Up: API for Custom Test Drivers\n\n15.3.3.1 Command-line arguments for test drivers\n................................................\n\nA custom driver can rely on various command-line options and arguments\nbeing passed to it automatically by the Automake-generated test harness.\nIt is mandatory that it understands all of them (even if the exact\ninterpretation of the associated semantics can legitimately change\nbetween a test driver and another, and even be a no-op in some drivers).\n\nHere is the list of options:\n\n'--test-name=NAME'\nThe name of the test, with VPATH prefix (if any) removed. This can\nhave a suffix and a directory component (as in e.g.,\n'sub/foo.test'), and is mostly meant to be used in console reports\nabout testsuite advancements and results (*note Testsuite progress\noutput::).\n'--log-file=PATH.log'\nThe '.log' file the test driver must create (*note Basics of test\nmetadata::). If it has a directory component (as in e.g.,\n'sub/foo.log'), the test harness will ensure that such directory\nexists before the test driver is called.\n'--trs-file=PATH.trs'\nThe '.trs' file the test driver must create (*note Basics of test\nmetadata::). If it has a directory component (as in e.g.,\n'sub/foo.trs'), the test harness will ensure that such directory\nexists before the test driver is called.\n'--color-tests={yes|no}'\nWhether the console output should be colorized or not (*note Simple\ntests and color-tests::, to learn when this option gets activated\nand when it doesn't).\n'--expect-failure={yes|no}'\nWhether the tested program is expected to fail.\n'--enable-hard-errors={yes|no}'\nWhether \"hard errors\" in the tested program should be treated\ndifferently from normal failures or not (the default should be\n'yes'). The exact meaning of \"hard error\" is highly dependent from\nthe test protocols or conventions in use.\n'--'\nExplicitly terminate the list of options.\n\nThe first non-option argument passed to the test driver is the program\nto be run, and all the following ones are command-line options and\narguments for this program.\n\nNote that the exact semantics attached to the '--color-tests',\n'--expect-failure' and '--enable-hard-errors' options are left up to the\nindividual test drivers. Still, having a behaviour compatible or at\nleast similar to that provided by the default driver is advised, as that\nwould offer a better consistency and a more pleasant user experience.\n\nFile: automake-1.16.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\n\n15.3.3.2 Log files generation and test results recording\n........................................................\n\nThe test driver must correctly generate the files specified by the\n'--log-file' and '--trs-file' option (even when the tested program fails\nor crashes).\n\nThe '.log' file should ideally contain all the output produced by the\ntested program, plus optionally other information that might facilitate\ndebugging or analysis of bug reports. Apart from that, its format is\nbasically free.\n\nThe '.trs' file is used to register some metadata through the use of\ncustom reStructuredText fields. This metadata is expected to be\nemployed in various ways by the parallel test harness; for example, to\ncount the test results when printing the testsuite summary, or to decide\nwhich tests to re-run upon 'make recheck'. Unrecognized metadata in a\n'.trs' file is currently ignored by the harness, but this might change\nin the future. The list of currently recognized metadata follows.\n\n':test-result:'\nThe test driver must use this field to register the results of\neach test case run by a test script file. Several\n':test-result:' fields can be present in the same '.trs' file; this\nis done in order to support test protocols that allow a single test\nscript to run more test cases.\n\nThe only recognized test results are currently 'PASS', 'XFAIL',\n'SKIP', 'FAIL', 'XPASS' and 'ERROR'. These results, when declared\nwith ':test-result:', can be optionally followed by text holding\nthe name and/or a brief description of the corresponding test; the\nharness will ignore such extra text when generating\n'test-suite.log' and preparing the testsuite summary.\n\n':recheck:'\nIf this field is present and defined to 'no', then the\ncorresponding test script will not be run upon a 'make recheck'.\nWhat happens when two or more ':recheck:' fields are present in the\nsame '.trs' file is undefined behaviour.\n\n':copy-in-global-log:'\nIf this field is present and defined to 'no', then the content of\nthe '.log' file will not be copied into the global\n'test-suite.log'. We allow to forsake such copying because, while\nit can be useful in debugging and analysis of bug report, it can\nalso be just a waste of space in normal situations, e.g., when a\ntest script is successful. What happens when two or more\n':copy-in-global-log:' fields are present in the same '.trs' file\nis undefined behaviour.\n\n':test-global-result:'\nThis is used to declare the \"global result\" of the script.\nCurrently, the value of this field is needed only to be reported\n(more or less verbatim) in the generated global log file\n'$(TESTSUITELOG)', so it's quite free-form. For example, a test\nscript which runs 10 test cases, 6 of which pass and 4 of which are\nskipped, could reasonably have a 'PASS/SKIP' value for this field,\nwhile a test script which runs 19 successful tests and one failed\ntest could have an 'ALMOST PASSED' value. What happens when two or\nmore ':test-global-result:' fields are present in the same '.trs'\nfile is undefined behaviour.\n\nLet's see a small example. Assume a '.trs' file contains the following\nlines:\n\n:test-result: PASS server starts\n:global-log-copy: no\n:test-result: PASS HTTP/1.1 request\n:test-result: FAIL HTTP/1.0 request\n:recheck: yes\n:test-result: SKIP HTTPS request (TLS library wasn't available)\n:test-result: PASS server stops\n\nThen the corresponding test script will be re-run by 'make check', will\ncontribute with five test results to the testsuite summary (three of\nthese tests being successful, one failed, and one skipped), and the\ncontent of the corresponding '.log' file will not be copied into the\nglobal log file 'test-suite.log'.\n\nFile: automake-1.16.info, Node: Testsuite progress output, Prev: Log files generation and test results recording, Up: API for Custom Test Drivers\n\n15.3.3.3 Testsuite progress output\n..................................\n\nA custom test driver also has the task of displaying, on the standard\noutput, the test results as soon as they become available. Depending on\nthe protocol in use, it can also display the reasons for failures and\nskips, and, more generally, any useful diagnostic output (but remember\nthat each line on the screen is precious, so that cluttering the screen\nwith overly verbose information is bad idea). The exact format of this\nprogress output is left up to the test driver; in fact, a custom test\ndriver might theoretically even decide not to do any such report,\nleaving it all to the testsuite summary (that would be a very lousy\nidea, of course, and serves only to illustrate the flexibility that is\ngranted here).\n\nRemember that consistency is good; so, if possible, try to be\nconsistent with the output of the built-in Automake test drivers,\nproviding a similar \"look & feel\". In particular, the testsuite\nprogress output should be colorized when the '--color-tests' is passed\nto the driver. On the other end, if you are using a known and\nwidespread test protocol with well-established implementations, being\nconsistent with those implementations' output might be a good idea too.\n\nFile: automake-1.16.info, Node: Using the TAP test protocol, Next: DejaGnu Tests, Prev: Custom Test Drivers, Up: Tests\n" }, { "name": "15.4 Using the TAP test protocol", "content": "* Menu:\n\n* Introduction to TAP::\n* Use TAP with the Automake test harness::\n* Incompatibilities with other TAP parsers and drivers::\n* Links and external resources on TAP::\n\nFile: automake-1.16.info, Node: Introduction to TAP, Next: Use TAP with the Automake test harness, Up: Using the TAP test protocol\n\n\nTAP, the Test Anything Protocol, is a simple text-based interface\nbetween testing modules or programs and a test harness. The tests (also\ncalled \"TAP producers\" in this context) write test results in a simple\nformat on standard output; a test harness (also called \"TAP consumer\")\nwill parse and interpret these results, and properly present them to the\nuser, and/or register them for later analysis. The exact details of how\nthis is accomplished can vary among different test harnesses. The\nAutomake harness will present the results on the console in the usual\nfashion (*note Testsuite progress on console::), and will use the '.trs'\nfiles (*note Basics of test metadata::) to store the test results and\nrelated metadata. Apart from that, it will try to remain as compatible\nas possible with pre-existing and widespread utilities, such as the\n'prove' utility\n(https://metacpan.org/pod/distribution/Test-Harness/bin/prove), at least\nfor the simpler usages.\n\nTAP started its life as part of the test harness for Perl, but today\nit has been (mostly) standardized, and has various independent\nimplementations in different languages; among them, C, C++, Perl,\nPython, PHP, and Java. For a semi-official specification of the TAP\nprotocol, please refer to the documentation of 'Test::Harness'\n(https://metacpan.org/pod/Test::Harness).\n\nThe most relevant real-world usages of TAP are obviously in the\ntestsuites of 'perl' and of many Perl modules. Still, other important\nthird-party packages, such as 'git' (https://git-scm.com/), also use TAP\nin their testsuite.\n\nFile: automake-1.16.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\n\n\nCurrently, the TAP driver that comes with Automake requires some by-hand\nsteps on the developer's part (this situation should hopefully be\nimproved in future Automake versions). You'll have to grab the\n'tap-driver.sh' script from the Automake distribution by hand, copy it\nin your source tree, and use the Automake support for third-party test\ndrivers to instruct the harness to use the 'tap-driver.sh' script and\nthe awk program found by 'AMINITAUTOMAKE' to run your TAP-producing\ntests. See the example below for clarification.\n\nApart from the options common to all the Automake test drivers (*note\nCommand-line arguments for test drivers::), 'tap-driver.sh' supports the\nfollowing options, whose names are chosen for enhanced compatibility\nwith the 'prove' utility.\n\n'--ignore-exit'\nCauses the test driver to ignore the exit status of the test\nscripts; by default, the driver will report an error if the script\nexits with a non-zero status. This option has effect also on\nnon-zero exit statuses due to termination by a signal.\n'--comments'\nInstruct the test driver to display TAP diagnostics (i.e., lines\nbeginning with the '#' character) in the testsuite progress output\ntoo; by default, TAP diagnostics are only copied to the '.log'\nfile.\n'--no-comments'\nRevert the effects of '--comments'.\n'--merge'\nInstruct the test driver to merge the test scripts' standard error\ninto their standard output. This is necessary if you want to\nensure that diagnostics from the test scripts are displayed in the\ncorrect order relative to test results; this can be of great help\nin debugging (especially if your test scripts are shell scripts run\nwith shell tracing active). As a downside, this option might cause\nthe test harness to get confused if anything that appears on\nstandard error looks like a test result.\n'--no-merge'\nRevert the effects of '--merge'.\n'--diagnostic-string=STRING'\nChange the string that introduces TAP diagnostics from the default\nvalue of \"'#'\" to 'STRING'. This can be useful if your TAP-based\ntest scripts produce verbose output on which they have limited\ncontrol (because, say, the output comes from other tools invoked in\nthe scripts), and it might contain text that gets spuriously\ninterpreted as TAP diagnostics: such an issue can be solved by\nredefining the string that activates TAP diagnostics to a value you\nknow won't appear by chance in the tests' output. Note however\nthat this feature is non-standard, as the \"official\" TAP protocol\ndoes not allow for such a customization; so don't use it if you can\navoid it.\n\nHere is an example of how the TAP driver can be set up and used.\n\n% cat configure.ac\nACINIT([GNU Try Tap], [1.0], [bug-automake@gnu.org])\nACCONFIGAUXDIR([build-aux])\nAMINITAUTOMAKE([foreign -Wall -Werror])\nACCONFIGFILES([Makefile])\nACREQUIREAUXFILE([tap-driver.sh])\nACOUTPUT\n\n% cat Makefile.am\nTESTLOGDRIVER = env AMTAPAWK='$(AWK)' $(SHELL) \\\n$(topsrcdir)/build-aux/tap-driver.sh\nTESTS = foo.test bar.test baz.test\nEXTRADIST = $(TESTS)\n\n% cat foo.test\n#!/bin/sh\necho 1..4 # Number of tests to be executed.\necho 'ok 1 - Swallows fly'\necho 'not ok 2 - Caterpillars fly # TODO metamorphosis in progress'\necho 'ok 3 - Pigs fly # SKIP not enough acid'\necho '# I just love word plays ...'\necho 'ok 4 - Flies fly too :-)'\n\n% cat bar.test\n#!/bin/sh\necho 1..3\necho 'not ok 1 - Bummer, this test has failed.'\necho 'ok 2 - This passed though.'\necho 'Bail out! Ennui kicking in, sorry...'\necho 'ok 3 - This will not be seen.'\n\n% cat baz.test\n#!/bin/sh\necho 1..1\necho ok 1\n# Exit with error, even if all the tests have been successful.\nexit 7\n\n% cp PREFIX/share/automake-APIVERSION/tap-driver.sh .\n% autoreconf -vi && ./configure && make check\n...\nPASS: foo.test 1 - Swallows fly\nXFAIL: foo.test 2 - Caterpillars fly # TODO metamorphosis in progress\nSKIP: foo.test 3 - Pigs fly # SKIP not enough acid\nPASS: foo.test 4 - Flies fly too :-)\nFAIL: bar.test 1 - Bummer, this test has failed.\nPASS: bar.test 2 - This passed though.\nERROR: bar.test - Bail out! Ennui kicking in, sorry...\nPASS: baz.test 1\nERROR: baz.test - exited with status 7\n...\nPlease report to bug-automake@gnu.org\n...\n% echo exit status: $?\nexit status: 1\n\n% env TESTLOGDRIVERFLAGS='--comments --ignore-exit' \\\nTESTS='foo.test baz.test' make -e check\n...\nPASS: foo.test 1 - Swallows fly\nXFAIL: foo.test 2 - Caterpillars fly # TODO metamorphosis in progress\nSKIP: foo.test 3 - Pigs fly # SKIP not enough acid\n# foo.test: I just love word plays...\nPASS: foo.test 4 - Flies fly too :-)\nPASS: baz.test 1\n...\n% echo exit status: $?\nexit status: 0\n\nFile: automake-1.16.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\n\n\nFor implementation or historical reasons, the TAP driver and harness as\nimplemented by Automake have some minor incompatibilities with the\nmainstream versions, which you should be aware of.\n\n* A 'Bail out!' directive doesn't stop the whole testsuite, but only\nthe test script it occurs in. This doesn't follow TAP\nspecifications, but on the other hand it maximizes compatibility\n(and code sharing) with the \"hard error\" concept of the default\ntestsuite driver.\n* The 'version' and 'pragma' directives are not supported.\n* The '--diagnostic-string' option of our driver allows modification\nof the string that introduces TAP diagnostics from the default\nvalue of \"'#'\". The standard TAP protocol currently has no way to\nallow this, so if you use it your diagnostic will be lost to more\ncompliant tools like 'prove' and 'Test::Harness'\n* And there are probably some other small and yet undiscovered\nincompatibilities, especially in corner cases or with rare usages.\n\nFile: automake-1.16.info, Node: Links and external resources on TAP, Prev: Incompatibilities with other TAP parsers and drivers, Up: Using the TAP test protocol\n\n\nHere are some links to more extensive official or third-party\ndocumentation and resources about the TAP protocol and related tools and\nlibraries.\n* 'Test::Harness' (https://metacpan.org/pod/Test::Harness), the\n(mostly) official documentation about the TAP format and protocol.\n* 'prove'\n(https://metacpan.org/pod/distribution/Test-Harness/bin/prove), the\nmost famous command-line TAP test driver, included in the\ndistribution of 'perl' and 'Test::Harness'\n(https://metacpan.org/pod/distribution/Test-Harness/lib/Test/Harness.pm).\n* The TAP wiki (https://testanything.org/).\n* A \"gentle introduction\" to testing for Perl coders:\n'Test::Tutorial'\n(https://metacpan.org/pod/distribution/Test-Simple/lib/Test/Tutorial.pod).\n* 'Test::Simple'\n(https://metacpan.org/pod/distribution/Test-Simple/lib/Test/Simple.pm)\nand 'Test::More'\n(https://metacpan.org/pod/distribution/Test-Simple/lib/Test/More.pm),\nthe standard Perl testing libraries, which are based on TAP.\n* C TAP Harness\n(https://www.eyrie.org/~eagle/software/c-tap-harness/), a C-based\nproject implementing both a TAP producer and a TAP consumer.\n* tap4j (https://tap4j.org/), a Java-based project implementing both\na TAP producer and a TAP consumer.\n\nFile: automake-1.16.info, Node: DejaGnu Tests, Next: Install Tests, Prev: Using the TAP test protocol, Up: Tests\n" }, { "name": "15.5 DejaGnu Tests", "content": "If 'dejagnu' (*note Introduction: (dejagnu)Top.) appears in\n'AUTOMAKEOPTIONS', then a 'dejagnu'-based test suite is assumed. The\nvariable 'DEJATOOL' is a list of names that are passed, one at a time,\nas the '--tool' argument to 'runtest' invocations; it defaults to the\nname of the package.\n\nThe variable 'RUNTESTDEFAULTFLAGS' holds the '--tool' and '--srcdir'\nflags that are passed to dejagnu by default; this can be overridden if\nnecessary.\n\nThe variables 'EXPECT' and 'RUNTEST' can also be overridden to\nprovide project-specific values. For instance, you will need to do this\nif you are testing a compiler toolchain, because the default values do\nnot take into account host and target names.\n\nThe contents of the variable 'RUNTESTFLAGS' are passed to the\n'runtest' invocation. This is considered a \"user variable\" (*note User\nVariables::). If you need to set 'runtest' flags in 'Makefile.am', you\ncan use 'AMRUNTESTFLAGS' instead.\n\nAutomake will generate rules to create a local 'site.exp' file,\ndefining various variables detected by 'configure'. This file is\nautomatically read by DejaGnu. It is OK for the user of a package to\nedit this file in order to tune the test suite. However this is not the\nplace where the test suite author should define new variables: this\nshould be done elsewhere in the real test suite code. Especially,\n'site.exp' should not be distributed.\n\nStill, if the package author has legitimate reasons to extend\n'site.exp' at 'make' time, he can do so by defining the variable\n'EXTRADEJAGNUSITECONFIG'; the files listed there will be considered\n'site.exp' prerequisites, and their content will be appended to it (in\nthe same order in which they appear in 'EXTRADEJAGNUSITECONFIG').\nNote that files are not distributed by default.\n\nFor more information regarding DejaGnu test suites, see *note\n(dejagnu)Top::.\n\nFile: automake-1.16.info, Node: Install Tests, Prev: DejaGnu Tests, Up: Tests\n" }, { "name": "15.6 Install Tests", "content": "The 'installcheck' target is available to the user as a way to run any\ntests after the package has been installed. You can add tests to this\nby writing an 'installcheck-local' rule.\n\nFile: automake-1.16.info, Node: Rebuilding, Next: Options, Prev: Tests, Up: Top\n" } ] }, "16 Rebuilding Makefiles": { "content": "Automake generates rules to automatically rebuild 'Makefile's,\n'configure', and other derived files like 'Makefile.in'.\n\nIf you are using 'AMMAINTAINERMODE' in 'configure.ac', then these\nautomatic rebuilding rules are only enabled in maintainer mode.\n\nSometimes it is convenient to supplement the rebuild rules for\n'configure' or 'config.status' with additional dependencies. The\nvariables 'CONFIGUREDEPENDENCIES' and 'CONFIGSTATUSDEPENDENCIES' can\nbe used to list these extra dependencies. These variables should be\ndefined in all 'Makefile's of the tree (because these two rebuild rules\nare output in all of them), so it is safer and easier to 'ACSUBST' them\nfrom 'configure.ac'. For instance, the following statement will cause\n'configure' to be rerun each time 'version.sh' is changed.\n\nACSUBST([CONFIGSTATUSDEPENDENCIES], ['$(topsrcdir)/version.sh'])\n\nNote the '$(topsrcdir)/' in the file name. Since this variable is to\nbe used in all 'Makefile's, its value must be sensible at any level in\nthe build hierarchy.\n\nBeware not to mistake 'CONFIGUREDEPENDENCIES' for\n'CONFIGSTATUSDEPENDENCIES'.\n\n'CONFIGUREDEPENDENCIES' adds dependencies to the 'configure' rule,\nwhose effect is to run 'autoconf'. This variable should be seldom used,\nbecause 'automake' already tracks 'm4include'd files. However it can\nbe useful when playing tricky games with 'm4esyscmd' or similar\nnon-recommendable macros with side effects. Be also aware that\ninteractions of this variable with the *note autom4te cache:\n(autoconf)Autom4te Cache. are quite problematic and can cause subtle\nbreakage, so you might want to disable the cache if you want to use\n'CONFIGUREDEPENDENCIES'.\n\n'CONFIGSTATUSDEPENDENCIES' adds dependencies to the 'config.status'\nrule, whose effect is to run 'configure'. This variable should\ntherefore carry any non-standard source that may be read as a side\neffect of running 'configure', like 'version.sh' in the example above.\n\nSpeaking of 'version.sh' scripts, we recommend against them today.\nThey are mainly used when the version of a package is updated\nautomatically by a script (e.g., in daily builds). Here is what some\nold-style 'configure.ac's may look like:\n\nACINIT\n. $srcdir/version.sh\nAMINITAUTOMAKE([name], $VERSIONNUMBER)\n...\n\nHere, 'version.sh' is a shell fragment that sets 'VERSIONNUMBER'. The\nproblem with this example is that 'automake' cannot track dependencies\n(listing 'version.sh' in 'CONFIGSTATUSDEPENDENCIES', and distributing\nthis file is up to the user), and that it uses the obsolete form of\n'ACINIT' and 'AMINITAUTOMAKE'. Upgrading to the new syntax is not\nstraightforward, because shell variables are not allowed in 'ACINIT''s\narguments. We recommend that 'version.sh' be replaced by an M4 file\nthat is included by 'configure.ac':\n\nm4include([version.m4])\nACINIT([name], VERSIONNUMBER)\nAMINITAUTOMAKE\n...\n\nHere 'version.m4' could contain something like\n'm4define([VERSIONNUMBER], [1.2])'. The advantage of this second form\nis that 'automake' will take care of the dependencies when defining the\nrebuild rule, and will also distribute the file automatically. An\ninconvenience is that 'autoconf' will now be rerun each time the version\nnumber is bumped, when only 'configure' had to be rerun in the previous\nsetup.\n\nGNU Make, at least, has an option '--always-make' which tells Make to\nconsider that all targets are out of date. This interacts badly with\nAutomake-generated Makefiles, which implement their own careful rules\nfor when to regenerate Makefiles, as described above. The result is an\nendless loop, or other poor behavior. The only thing to do, as far as\nwe know, is to refrain from using '--always-make'.\n\nFile: automake-1.16.info, Node: Options, Next: Miscellaneous, Prev: Rebuilding, Up: Top\n", "subsections": [] }, "17 Changing Automake's Behavior": { "content": "* Menu:\n\n* Options generalities:: Semantics of Automake option\n* List of Automake options:: A comprehensive list of Automake options\n\nFile: automake-1.16.info, Node: Options generalities, Next: List of Automake options, Up: Options\n", "subsections": [ { "name": "17.1 Options generalities", "content": "Various features of Automake can be controlled by options. Except where\nnoted otherwise, options can be specified in one of several ways. Most\noptions can be applied on a per-'Makefile' basis when listed in a\nspecial 'Makefile' variable named 'AUTOMAKEOPTIONS'. Some of these\noptions only make sense when specified in the toplevel 'Makefile.am'\nfile. Options are applied globally to all processed 'Makefile' files\nwhen listed in the first argument of 'AMINITAUTOMAKE' in\n'configure.ac', and some options which require changes to the\n'configure' script can only be specified there. These are annotated\nbelow.\n\nAs a general rule, options specified in 'AUTOMAKEOPTIONS' take\nprecedence over those specified in 'AMINITAUTOMAKE', which in turn\ntake precedence over those specified on the command line.\n\nAlso, some care must be taken about the interactions among strictness\nlevel and warning categories. As a general rule, strictness-implied\nwarnings are overridden by those specified by explicit options. For\nexample, even if 'portability' warnings are disabled by default in\n'foreign' strictness, a usage like this will end up enabling them:\n\nAUTOMAKEOPTIONS = -Wportability foreign\n\nHowever, a strictness level specified in a higher-priority context\nwill override all the explicit warnings specified in a lower-priority\ncontext. For example, if 'configure.ac' contains:\n\nAMINITAUTOMAKE([-Wportability])\n\nand 'Makefile.am' contains:\n\nAUTOMAKEOPTIONS = foreign\n\nthen 'portability' warnings will be disabled in 'Makefile.am'.\n\nFile: automake-1.16.info, Node: List of Automake options, Prev: Options generalities, Up: Options\n" }, { "name": "17.2 List of Automake options", "content": "'gnits'\n'gnu'\n'foreign'\n\nSet the strictness as appropriate. *Note Strictness::. The\n'gnits' option also implies options 'readme-alpha' and\n'check-news'.\n\n'check-news'\nCause 'make dist' to fail unless the current version number appears\nin the first few lines of the 'NEWS' file.\n\n'dejagnu'\nCause 'dejagnu'-specific rules to be generated. *Note DejaGnu\nTests::.\n\n'dist-bzip2'\nHook 'dist-bzip2' to 'dist'.\n\n'dist-lzip'\nHook 'dist-lzip' to 'dist'.\n\n'dist-xz'\nHook 'dist-xz' to 'dist'.\n\n'dist-zip'\nHook 'dist-zip' to 'dist'.\n\n'dist-zstd'\nHook 'dist-zstd' to 'dist'.\n\n'dist-shar'\nHook 'dist-shar' to 'dist'. Use of this option is deprecated, as\nthe 'shar' format is obsolescent and problematic. Support for it\nwill be removed altogether in Automake 2.0.\n\n'dist-tarZ'\nHook 'dist-tarZ' to 'dist'. Use of this option is deprecated, as\nthe 'compress' program is obsolete. Support for it will be removed\naltogether in Automake 2.0.\n\n'filename-length-max=99'\nAbort if file names longer than 99 characters are found during\n'make dist'. Such long file names are generally considered not to\nbe portable in tarballs. See the 'tar-v7' and 'tar-ustar' options\nbelow. This option should be used in the top-level 'Makefile.am'\nor as an argument of 'AMINITAUTOMAKE' in 'configure.ac'; it will\nbe ignored otherwise. It will also be ignored in sub-packages of\nnested packages (*note Subpackages::).\n\n'info-in-builddir'\nInstruct Automake to place the generated '.info' files in the\n'builddir' rather than in the 'srcdir'. Note that this might make\nVPATH builds with some non-GNU make implementations more brittle.\n\n'no-define'\nThis option is meaningful only when passed as an argument to\n'AMINITAUTOMAKE'. It will prevent the 'PACKAGE' and 'VERSION'\nvariables from being 'ACDEFINE'd. But notice that they will\nremain defined as shell variables in the generated 'configure', and\nas make variables in the generated 'Makefile'; this is deliberate,\nand required for backward compatibility.\n\n'no-dependencies'\nThis is similar to using '--ignore-deps' on the command line, but\nis useful for those situations where you don't have the necessary\nbits to make automatic dependency tracking work (*note\nDependencies::). In this case the effect is to effectively disable\nautomatic dependency tracking.\n\n'no-dist'\nDon't emit any code related to 'dist' target. This is useful when\na package has its own method for making distributions.\n\n'no-dist-built-sources'\nDon't build 'BUILTSOURCES' as part of 'dist'. This option can be\nset if building the distribution only requires the source files,\nand doesn't compile anything as a side-effect. The default is for\n'$(distdir)' to depend on '$(BUILTSOURCES)' because it is common,\nat least among GNU packages, to want to build the program to\ngenerate man pages with 'help2man' (*note Errors with distclean::).\nAdmittedly the default behavior should perhaps be to omit the\ndependency, but to preserve compatibility, we don't want to change\nit now.\n\n'no-dist-gzip'\nDo not hook 'dist-gzip' to 'dist'.\n\n'no-exeext'\nIf your 'Makefile.am' defines a rule for target 'foo', it will\noverride a rule for a target named 'foo$(EXEEXT)'. This is\nnecessary when 'EXEEXT' is found to be empty. However, by default\n'automake' will generate an error for this use. The 'no-exeext'\noption will disable this error. This is intended for use only\nwhere it is known in advance that the package will not be ported to\nWindows, or any other operating system using extensions on\nexecutables.\n\n'no-installinfo'\nThe generated 'Makefile.in' will not cause info pages to be built\nor installed by default. However, 'info' and 'install-info'\ntargets will still be available. This option is disallowed at\n'gnu' strictness and above.\n\n'no-installman'\nThe generated 'Makefile.in' will not cause man pages to be\ninstalled by default. However, an 'install-man' target will still\nbe available for optional installation. This option is disallowed\nat 'gnu' strictness and above.\n\n'nostdinc'\nThis option can be used to disable the standard '-I' options that\nare ordinarily automatically provided by Automake.\n\n'no-texinfo.tex'\nDon't require 'texinfo.tex', even if there are texinfo files in\nthis directory.\n\n'serial-tests'\nEnable the older serial test suite harness for 'TESTS' (*note\nSerial Test Harness::, for more information).\n\n'parallel-tests'\nEnable test suite harness for 'TESTS' that can run tests in\nparallel (*note Parallel Test Harness::, for more information).\nThis option is only kept for backward-compatibility, since the\nparallel test harness is the default now.\n\n'readme-alpha'\nIf this release is an alpha release, and the file 'README-alpha'\nexists, then it will be added to the distribution. If this option\nis given, version numbers are expected to follow one of two forms.\nThe first form is 'MAJOR.MINOR.ALPHA', where each element is a\nnumber; the final period and number should be left off for\nnon-alpha releases. The second form is 'MAJOR.MINORALPHA', where\nALPHA is a letter; it should be omitted for non-alpha releases.\n\n'std-options'\n\nMake the 'installcheck' rule check that installed scripts and\nprograms support the '--help' and '--version' options. This also\nprovides a basic check that the program's run-time dependencies are\nsatisfied after installation.\n\nIn a few situations, programs (or scripts) have to be exempted from\nthis test. For instance, 'false' (from GNU coreutils) is never\nsuccessful, even for '--help' or '--version'. You can list such\nprograms in the variable 'AMINSTALLCHECKSTDOPTIONSEXEMPT'.\nPrograms (not scripts) listed in this variable should be suffixed\nby '$(EXEEXT)' for the sake of Windows or OS/2. For instance,\nsuppose we build 'false' as a program but 'true.sh' as a script,\nand that neither of them support '--help' or '--version':\n\nAUTOMAKEOPTIONS = std-options\nbinPROGRAMS = false ...\nbinSCRIPTS = true.sh ...\nAMINSTALLCHECKSTDOPTIONSEXEMPT = false$(EXEEXT) true.sh\n\n'subdir-objects'\nIf this option is specified, then objects are placed into the\nsubdirectory of the build directory corresponding to the\nsubdirectory of the source file. For instance, if the source file\nis 'subdir/file.cxx', then the output file would be\n'subdir/file.o'. *Note Program and Library Variables::.\n\n'tar-v7'\n'tar-ustar'\n'tar-pax'\n\nThese three mutually exclusive options select the tar format to use\nwhen generating tarballs with 'make dist'. (The tar file created\nis then compressed according to the set of 'no-dist-gzip',\n'dist-bzip2', 'dist-lzip', 'dist-xz', 'dist-zstd' and 'dist-tarZ'\noptions in use.)\n\nThese options must be passed as arguments to 'AMINITAUTOMAKE'\n(*note Macros::) because they can require additional configure\nchecks. Automake will complain if it sees such options in an\n'AUTOMAKEOPTIONS' variable.\n\n'tar-v7' selects the old V7 tar format. This is the historical\ndefault. This antiquated format is understood by all tar\nimplementations and supports file names with up to 99 characters.\nWhen given longer file names some tar implementations will diagnose\nthe problem while others will generate broken tarballs or use\nnon-portable extensions. Furthermore, the V7 format cannot store\nempty directories. When using this format, consider using the\n'filename-length-max=99' option to catch file names too long.\n\n'tar-ustar' selects the ustar format defined by POSIX 1003.1-1988.\nThis format is old enough to be portable: As of 2018, it is\nsupported by the native 'tar' command on GNU, FreeBSD, NetBSD,\nOpenBSD, AIX, HP-UX, and Solaris, at least. It fully supports\nempty directories. It can store file names with up to 256\ncharacters, provided that the file name can be split at directory\nseparator in two parts, first of them being at most 155 bytes long.\nSo, in most cases the maximum file name length will be shorter than\n256 characters.\n\n'tar-pax' selects the new pax interchange format defined by POSIX\n1003.1-2001. It does not limit the length of file names. However,\nthis format is very young and should probably be restricted to\npackages that target only very modern platforms. As of 2018, this\nformat is supported by the native 'tar' command only on GNU,\nFreeBSD, and OpenBSD systems; it is not supported by the native\n'tar' command on NetBSD, AIX, HP-UX, or Solaris. There are moves\nto change the pax format in an upward-compatible way, so this\noption may refer to a more recent version in the future.\n\n*Note Controlling the Archive Format: (tar)Formats, for further\ndiscussion about tar formats.\n\n'configure' knows several ways to construct these formats. It will\nnot abort if it cannot find a tool up to the task (so that the\npackage can still be built), but 'make dist' will fail.\n\nVERSION\nA version number (e.g., '0.30') can be specified. If Automake is\nnot the same version or newer than the version specified, creation\nof the 'Makefile.in' will be suppressed.\n\n'-WCATEGORY' or '--warnings=CATEGORY'\nThese options behave exactly like their command-line counterpart\n(*note automake Invocation::). This allows you to enable or\ndisable some warning categories on a per-file basis. You can also\nsetup some warnings for your entire project; for instance, try\n'AMINITAUTOMAKE([-Wall])' in your 'configure.ac'.\n\nUnrecognized options are diagnosed by 'automake'.\n\nIf you want an option to apply to all the files in the tree, you can\nuse the 'AMINITAUTOMAKE' macro in 'configure.ac'. *Note Macros::.\n\nFile: automake-1.16.info, Node: Miscellaneous, Next: Include, Prev: Options, Up: Top\n" } ] }, "18 Miscellaneous Rules": { "content": "There are a few rules and variables that didn't fit anywhere else.\n\n* Menu:\n\n* Tags:: Interfacing to cscope, etags and mkid\n* Suffixes:: Handling new file extensions\n\nFile: automake-1.16.info, Node: Tags, Next: Suffixes, Up: Miscellaneous\n", "subsections": [ { "name": "18.1 Interfacing to 'etags'", "content": "Automake will generate rules to generate 'TAGS' files for use with GNU\nEmacs under some circumstances.\n\nIf any C, C++ or Fortran 77 source code or headers are present, then\n'tags' and 'TAGS' rules will be generated for the directory. All files\nlisted using the 'SOURCES', 'HEADERS', and 'LISP' primaries will be\nused to generate tags. Generated source files that are not distributed\nmust be declared in variables like 'nodistnoinstHEADERS' or\n'nodistPROGSOURCES' or they will be ignored.\n\nA 'tags' rule will be output at the topmost directory of a\nmulti-directory package. When run from this topmost directory, 'make\ntags' will generate a 'TAGS' file that includes by reference all 'TAGS'\nfiles from subdirectories.\n\nThe 'tags' rule will also be generated if the variable 'ETAGSARGS'\nis defined. This variable is intended for use in directories that\ncontain taggable source that 'etags' does not understand. The user can\nuse the 'ETAGSFLAGS' to pass additional flags to 'etags';\n'AMETAGSFLAGS' is also available for use in 'Makefile.am'. The\nvariable 'ETAGS' is the name of the program to invoke (by default\n'etags').\n\nHere is how Automake generates tags for its source, and for nodes in\nits Texinfo file:\n\nETAGSARGS = automake.in --lang=none \\\n--regex='/^@node[ \\t]+\\([^,]+\\)/\\1/' automake.texi\n\nIf you add file names to 'ETAGSARGS', you will probably also want to\ndefine 'TAGSDEPENDENCIES'. The contents of this variable are added\ndirectly to the dependencies for the 'tags' rule.\n\nAutomake also generates a 'ctags' rule that can be used to build\n'vi'-style 'tags' files. The variable 'CTAGS' is the name of the\nprogram to invoke (by default 'ctags'); 'CTAGSFLAGS' can be used by the\nuser to pass additional flags, and 'AMCTAGSFLAGS' can be used by the\n'Makefile.am'.\n\nAutomake will also generate an 'ID' rule that will run 'mkid' on the\nsource. This is only supported on a directory-by-directory basis.\n\nSimilarly, the 'cscope' rule will create a list of all the source\nfiles in the tree and run 'cscope' to build an inverted index database.\nThe variable 'CSCOPE' is the name of the program to invoke (by default\n'cscope'); 'CSCOPEFLAGS' and 'CSCOPEARGS' can be used by the user to\npass additional flags and file names respectively, while\n'AMCSCOPEFLAGS' can be used by the 'Makefile.am'. Note that,\ncurrently, the Automake-provided 'cscope' support, when used in a VPATH\nbuild, might not work well with non-GNU make implementations (especially\nwith make implementations performing *note VPATH rewrites:\n(autoconf)Automatic Rule Rewriting.).\n\nFinally, Automake also emits rules to support the GNU Global Tags\nprogram (https://www.gnu.org/software/global/). The 'GTAGS' rule runs\nGlobal Tags and puts the result in the top build directory. The\nvariable 'GTAGSARGS' holds arguments that are passed to 'gtags'.\n\nFile: automake-1.16.info, Node: Suffixes, Prev: Tags, Up: Miscellaneous\n" }, { "name": "18.2 Handling new file extensions", "content": "It is sometimes useful to introduce a new implicit rule to handle a file\ntype that Automake does not know about.\n\nFor instance, suppose you had a compiler that could compile '.foo'\nfiles to '.o' files. You would simply define a suffix rule for your\nlanguage:\n\n.foo.o:\nfoocc -c -o $@ $<\n\nThen you could directly use a '.foo' file in a 'SOURCES' variable\nand expect the correct results:\n\nbinPROGRAMS = doit\ndoitSOURCES = doit.foo\n\nThis was the simpler and more common case. In other cases, you will\nhave to help Automake to figure out which extensions you are defining\nyour suffix rule for. This usually happens when your extension does not\nstart with a dot. Then, all you have to do is to put a list of new\nsuffixes in the 'SUFFIXES' variable *before* you define your implicit\nrule.\n\nFor instance, the following definition prevents Automake from\nmisinterpreting the '.idlC.cpp:' rule as an attempt to transform '.idlC'\nfiles into '.cpp' files.\n\nSUFFIXES = .idl C.cpp\n.idlC.cpp:\n# whatever\n\nAs you may have noted, the 'SUFFIXES' variable behaves like the\n'.SUFFIXES' special target of 'make'. You should not touch '.SUFFIXES'\nyourself, but use 'SUFFIXES' instead and let Automake generate the\nsuffix list for '.SUFFIXES'. Any given 'SUFFIXES' go at the start of\nthe generated suffixes list, followed by Automake generated suffixes not\nalready in the list.\n\nFile: automake-1.16.info, Node: Include, Next: Conditionals, Prev: Miscellaneous, Up: Top\n" } ] }, "19 Include": { "content": "Automake supports an 'include' directive that can be used to include\nother 'Makefile' fragments when 'automake' is run. Note that these\nfragments are read and interpreted by 'automake', not by 'make'. As\nwith conditionals, 'make' has no idea that 'include' is in use.\n\nThere are two forms of 'include':\n\n'include $(srcdir)/file'\nInclude a fragment that is found relative to the current source\ndirectory.\n\n'include $(topsrcdir)/file'\nInclude a fragment that is found relative to the top source\ndirectory.\n\nNote that if a fragment is included inside a conditional, then the\ncondition applies to the entire contents of that fragment.\n\nMakefile fragments included this way are always distributed because\nthey are needed to rebuild 'Makefile.in'.\n\nInside a fragment, the construct '%reldir%' is replaced with the\ndirectory of the fragment relative to the base 'Makefile.am'.\nSimilarly, '%canonreldir%' is replaced with the canonicalized (*note\nCanonicalization::) form of '%reldir%'. As a convenience, '%D%' is a\nsynonym for '%reldir%', and '%C%' is a synonym for '%canonreldir%'.\n\nA special feature is that if the fragment is in the same directory as\nthe base 'Makefile.am' (i.e., '%reldir%' is '.'), then '%reldir%' and\n'%canonreldir%' will expand to the empty string as well as eat, if\npresent, a following slash or underscore respectively.\n\nThus, a makefile fragment might look like this:\n\nbinPROGRAMS += %reldir%/mumble\n%canonreldir%mumbleSOURCES = %reldir%/one.c\n\nFile: automake-1.16.info, Node: Conditionals, Next: Silencing Make, Prev: Include, Up: Top\n", "subsections": [] }, "20 Conditionals": { "content": "Automake supports a simple type of conditional.\n\nThese conditionals are not the same as conditionals in GNU Make.\nAutomake conditionals are checked at configure time by the 'configure'\nscript, and affect the translation from 'Makefile.in' to 'Makefile'.\nThey are based on options passed to 'configure' and on results that\n'configure' has discovered about the host system. GNU Make conditionals\nare checked at 'make' time, and are based on variables passed to the\nmake program or defined in the 'Makefile'.\n\nAutomake conditionals will work with any make program.\n\n* Menu:\n\n* Usage of Conditionals:: Declaring conditional content\n* Limits of Conditionals:: Enclosing complete statements\n\nFile: automake-1.16.info, Node: Usage of Conditionals, Next: Limits of Conditionals, Up: Conditionals\n", "subsections": [ { "name": "20.1 Usage of Conditionals", "content": "Before using a conditional, you must define it by using 'AMCONDITIONAL'\nin the 'configure.ac' file (*note Macros::).\n\n-- Macro: AMCONDITIONAL (CONDITIONAL, CONDITION)\nThe conditional name, CONDITIONAL, should be a simple string\nstarting with a letter and containing only letters, digits, and\nunderscores. It must be different from 'TRUE' and 'FALSE', which\nare reserved by Automake.\n\nThe shell CONDITION (suitable for use in a shell 'if' statement) is\nevaluated when 'configure' is run. Note that you must arrange for\nevery 'AMCONDITIONAL' to be invoked every time 'configure' is\nrun. If 'AMCONDITIONAL' is run conditionally (e.g., in a shell\n'if' statement), then the result will confuse 'automake'.\n\nConditionals typically depend upon options that the user provides to\nthe 'configure' script. Here is an example of how to write a\nconditional that is true if the user uses the '--enable-debug' option.\n\nACARGENABLE([debug],\n[ --enable-debug Turn on debugging],\n[case \"${enableval}\" in\nyes) debug=true ;;\nno) debug=false ;;\n*) ACMSGERROR([bad value ${enableval} for --enable-debug]) ;;\nesac],[debug=false])\nAMCONDITIONAL([DEBUG], [test x$debug = xtrue])\n\nHere is an example of how to use that conditional in 'Makefile.am':\n\nif DEBUG\nDBG = debug\nelse\nDBG =\nendif\nnoinstPROGRAMS = $(DBG)\n\nThis trivial example could also be handled using 'EXTRAPROGRAMS'\n(*note Conditional Programs::).\n\nYou may only test a single variable in an 'if' statement, possibly\nnegated using '!'. The 'else' statement may be omitted. Conditionals\nmay be nested to any depth. You may specify an argument to 'else' in\nwhich case it must be the negation of the condition used for the current\n'if'. Similarly you may specify the condition that is closed on the\n'endif' line:\n\nif DEBUG\nDBG = debug\nelse !DEBUG\nDBG =\nendif !DEBUG\n\nUnbalanced conditions are errors. The 'if', 'else', and 'endif'\nstatements should not be indented, i.e., start on column one.\n\nThe 'else' branch of the above two examples could be omitted, since\nassigning the empty string to an otherwise undefined variable makes no\ndifference.\n\nIn order to allow access to the condition registered by\n'AMCONDITIONAL' inside 'configure.ac', and to allow conditional\n'ACCONFIGFILES', 'AMCONDIF' may be used:\n\n-- Macro: AMCONDIF (CONDITIONAL, [IF-TRUE], [IF-FALSE])\nIf CONDITIONAL is fulfilled, execute IF-TRUE, otherwise execute\nIF-FALSE. If either branch contains 'ACCONFIGFILES', it will\ncause 'automake' to output the rules for the respective files only\nfor the given condition.\n\n'AMCONDIF' macros may be nested when m4 quotation is used properly\n(*note (autoconf)M4 Quotation::).\n\nHere is an example of how to define a conditional config file:\n\nAMCONDITIONAL([SHELLWRAPPER], [test \"x$withwrapper\" = xtrue])\nAMCONDIF([SHELLWRAPPER],\n[ACCONFIGFILES([wrapper:wrapper.in])])\n\nFile: automake-1.16.info, Node: Limits of Conditionals, Prev: Usage of Conditionals, Up: Conditionals\n" }, { "name": "20.2 Limits of Conditionals", "content": "Conditionals should enclose complete statements like variables or rules\ndefinitions. Automake cannot deal with conditionals used inside a\nvariable definition, for instance, and is not even able to diagnose this\nsituation. The following example would not work:\n\n# This syntax is not understood by Automake\nAMCPPFLAGS = \\\n-DFEATUREA \\\nif WANTDEBUG\n-DDEBUG \\\nendif\n-DFEATUREB\n\nHowever the intended definition of 'AMCPPFLAGS' can be achieved with\n\nif WANTDEBUG\nDEBUGFLAGS = -DDEBUG\nendif\nAMCPPFLAGS = -DFEATUREA $(DEBUGFLAGS) -DFEATUREB\n\nor\n\nAMCPPFLAGS = -DFEATUREA\nif WANTDEBUG\nAMCPPFLAGS += -DDEBUG\nendif\nAMCPPFLAGS += -DFEATUREB\n\nMore details and examples of conditionals are described alongside\nvarious Automake features in this manual (*note Conditional\nSubdirectories::, *note Conditional Sources::, *note Conditional\nPrograms::, *note Conditional Libtool Libraries::, *note Conditional\nLibtool Sources::).\n\nFile: automake-1.16.info, Node: Silencing Make, Next: Not Enough, Prev: Conditionals, Up: Top\n" } ] }, "21 Silencing 'make'": { "content": "* Menu:\n\n* Make verbosity:: Make is verbose by default\n* Tricks For Silencing Make:: Standard and generic ways to silence make\n* Automake Silent Rules:: How Automake can help in silencing make\n\nFile: automake-1.16.info, Node: Make verbosity, Next: Tricks For Silencing Make, Up: Silencing Make\n", "subsections": [ { "name": "21.1 Make is verbose by default", "content": "Normally, when executing the set of rules associated with a target,\n'make' prints each rule before it is executed. This behaviour, while\nhaving been in place for a long time, and being even mandated by the\nPOSIX standard, starkly violates the \"silence is golden\" UNIX\nprinciple(1):\n\nWhen a program has nothing interesting or surprising to say, it\nshould say nothing. Well-behaved Unix programs do their jobs\nunobtrusively, with a minimum of fuss and bother. Silence is\ngolden.\n\nIn fact, while such verbosity of 'make' can theoretically be useful\nto track bugs and understand reasons of failures right away, it can also\nhide warning and error messages from 'make'-invoked tools, drowning them\nin a flood of uninteresting and seldom useful messages, and thus\nallowing them to go easily undetected.\n\nThis problem can be very annoying, especially for developers, who\nusually know quite well what's going on behind the scenes, and for whom\nthe verbose output from 'make' ends up being mostly noise that hampers\nthe easy detection of potentially important warning messages.\n\n---------- Footnotes ----------\n\n(1) See also .\n\nFile: automake-1.16.info, Node: Tricks For Silencing Make, Next: Automake Silent Rules, Prev: Make verbosity, Up: Silencing Make\n" }, { "name": "21.2 Standard and generic ways to silence Make", "content": "Here we describe some common idioms/tricks to obtain a quieter make\noutput, with their relative advantages and drawbacks. In the next\nsection (*note Automake Silent Rules::) we'll see how Automake can help\nin this respect, providing more elaborate and flexible idioms.\n\n* 'make -s'\n\nThis simply causes 'make' not to print any rule before executing\nit.\n\nThe '-s' flag is mandated by POSIX, universally supported, and its\npurpose and function are easy to understand.\n\nBut it also has its serious limitations too. First of all, it\nembodies an \"all or nothing\" strategy, i.e., either everything is\nsilenced, or nothing is; this lack of granularity can sometimes be\na fatal flaw. Moreover, when the '-s' flag is used, the 'make'\noutput might turn out to be too terse; in case of errors, the user\nwon't be able to easily see what rule or command have caused them,\nor even, in case of tools with poor error reporting, what the\nerrors were!\n\n* 'make >/dev/null || make'\n\nApparently, this perfectly obeys the \"silence is golden\" rule:\nwarnings from stderr are passed through, output reporting is done\nonly in case of error, and in that case it should provide a\nverbose-enough report to allow an easy determination of the error\nlocation and causes.\n\nHowever, calling 'make' two times in a row might hide errors\n(especially intermittent ones), or subtly change the expected\nsemantics of the 'make' calls -- these things can clearly make\ndebugging and error assessment very difficult.\n\n* 'make --no-print-directory'\n\nThis is GNU 'make' specific. When called with the\n'--no-print-directory' option, GNU 'make' will disable printing of\nthe working directory by invoked sub-'make's (the well-known\n\"Entering/Leaving directory ...\" messages). This helps to decrease\nthe verbosity of the output, but experience has shown that it can\nalso often render debugging considerably harder in projects using\ndeeply-nested 'make' recursion.\n\nAs an aside, notice that the '--no-print-directory' option is\nautomatically activated if the '-s' flag is used.\n\nFile: automake-1.16.info, Node: Automake Silent Rules, Prev: Tricks For Silencing Make, Up: Silencing Make\n" }, { "name": "21.3 How Automake can help in silencing Make", "content": "The tricks and idioms for silencing 'make' described in the previous\nsection can be useful from time to time, but we've seen that they all\nhave their serious drawbacks and limitations. That's why automake\nprovides support for a more advanced and flexible way of obtaining\nquieter output from 'make' (for most rules at least).\n\nTo give the gist of what Automake can do in this respect, here is a\nsimple comparison between a typical 'make' output (where silent rules\nare disabled) and one with silent rules enabled:\n\n% cat Makefile.am\nbinPROGRAMS = foo\nfooSOURCES = main.c func.c\n% cat main.c\nint main (void) { return func (); } /* func used undeclared */\n% cat func.c\nint func (void) { int i; return i; } /* i used uninitialized */\n\nThe make output is by default very verbose. This causes warnings\nfrom the compiler to be somewhat hidden, and not immediate to spot.\n% make CFLAGS=-Wall\ngcc -DPACKAGENAME=\\\"foo\\\" -DPACKAGETARNAME=\\\"foo\\\" ...\n-DPACKAGESTRING=\\\"foo\\ 1.0\\\" -DPACKAGEBUGREPORT=\\\"\\\" ...\n-DPACKAGE=\\\"foo\\\" -DVERSION=\\\"1.0\\\" -I. -Wall -MT main.o\n-MD -MP -MF .deps/main.Tpo -c -o main.o main.c\nmain.c: In function 'main':\nmain.c:3:3: warning: implicit declaration of function 'func'\nmv -f .deps/main.Tpo .deps/main.Po\ngcc -DPACKAGENAME=\\\"foo\\\" -DPACKAGETARNAME=\\\"foo\\\" ...\n-DPACKAGESTRING=\\\"foo\\ 1.0\\\" -DPACKAGEBUGREPORT=\\\"\\\" ...\n-DPACKAGE=\\\"foo\\\" -DVERSION=\\\"1.0\\\" -I. -Wall -MT func.o\n-MD -MP -MF .deps/func.Tpo -c -o func.o func.c\nfunc.c: In function 'func':\nfunc.c:4:3: warning: 'i' used uninitialized in this function\nmv -f .deps/func.Tpo .deps/func.Po\ngcc -Wall -o foo main.o func.o\n\nClean up, so that we can rebuild everything from scratch.\n% make clean\ntest -z \"foo\" || rm -f foo\nrm -f *.o\n\nSilent rules enabled: the output is minimal but informative. In\nparticular, the warnings from the compiler stick out very clearly.\n% make V=0 CFLAGS=-Wall\nCC main.o\nmain.c: In function 'main':\nmain.c:3:3: warning: implicit declaration of function 'func'\nCC func.o\nfunc.c: In function 'func':\nfunc.c:4:3: warning: 'i' used uninitialized in this function\nCCLD foo\n\nAlso, in projects using 'libtool', the use of silent rules can\nautomatically enable the 'libtool''s '--silent' option:\n\n% cat Makefile.am\nlibLTLIBRARIES = libx.la\n\n% make # Both make and libtool are verbose by default.\n...\nlibtool: compile: gcc -DPACKAGENAME=\\\"foo\\\" ... -DLTOBJDIR=\\\".libs/\\\"\n-I. -g -O2 -MT libx.lo -MD -MP -MF .deps/libx.Tpo -c libx.c -fPIC\n-DPIC -o .libs/libx.o\nmv -f .deps/libx.Tpo .deps/libx.Plo\n/bin/sh ./libtool --tag=CC --mode=link gcc -g -O2 -o libx.la -rpath\n/usr/local/lib libx.lo\nlibtool: link: gcc -shared .libs/libx.o -Wl,-soname -Wl,libx.so.0\n-o .libs/libx.so.0.0.0\nlibtool: link: cd .libs && rm -f libx.so && ln -s libx.so.0.0.0 libx.so\n...\n\n% make V=0\nCC libx.lo\nCCLD libx.la\n\nFor Automake-generated 'Makefile's, the user may influence the\nverbosity at 'configure' run time as well as at 'make' run time:\n\n* Passing '--enable-silent-rules' to 'configure' will cause build\nrules to be less verbose; the option '--disable-silent-rules' will\ncause normal verbose output.\n* At 'make' run time, the default chosen at 'configure' time may be\noverridden: 'make V=1' will produce verbose output, 'make V=0' less\nverbose output.\n\nNote that silent rules are disabled by default; the user must\nenable them explicitly at either 'configure' run time or at 'make' run\ntime. We think that this is a good policy, since it provides the casual\nuser with enough information to prepare a good bug report in case\nanything breaks.\n\nStill, notwithstanding the rationales above, developers who wants to\nmake silent rules enabled by default in their own packages can do so by\ncalling 'AMSILENTRULES([yes])' in 'configure.ac'.\n\nUsers who prefer to have silent rules enabled by default can edit\ntheir 'config.site' file to make the variable 'enablesilentrules'\ndefault to 'yes'. This should still allow disabling silent rules at\n'configure' time and at 'make' time.\n\nFor portability to different 'make' implementations, package authors\nare advised to not set the variable 'V' inside the 'Makefile.am' file,\nto allow the user to override the value for subdirectories as well.\n\nTo work at its best, the current implementation of this feature\nnormally uses nested variable expansion '$(VAR1$(V))', a 'Makefile'\nfeature that is not required by POSIX 2008 but is widely supported in\npractice. On the rare 'make' implementations that do not support nested\nvariable expansion, whether rules are silent is always determined at\nconfigure time, and cannot be overridden at make time. Future versions\nof POSIX are likely to require nested variable expansion, so this minor\nlimitation should go away with time.\n\nTo extend the silent mode to your own rules, you have a few choices:\n\n* You can use the predefined variable 'AMVGEN' as a prefix to\ncommands that should output a status line in silent mode, and\n'AMVat' as a prefix to commands that should not output anything\nin silent mode. When output is to be verbose, both of these\nvariables will expand to the empty string.\n\n* You can silence a recipe unconditionally with '@', and then use the\npredefined variable 'AMVP' to know whether make is being run in\nsilent or verbose mode; adjust the verbose information your recipe\ndisplays accordingly:\n\ngenerate-headers:\n... [commands defining a shell variable '$headers'] ...; \\\nif $(AMVP); then set -x; else echo \" GEN [headers]\"; fi; \\\nrm -f $$headers && generate-header --flags $$headers\n\n* You can add your own variables, so strings of your own choice are\nshown. The following snippet shows how you would define your own\nequivalent of 'AMVGEN':\n\npkgverbose = $(pkgverbose@AMV@)\npkgverbose = $(pkgverbose@AMDEFAULTV@)\npkgverbose0 = @echo PKG-GEN $@;\n\nfoo: foo.in\n$(pkgverbose)cp $(srcdir)/foo.in $@\n\nAs a final note, observe that, even when silent rules are enabled,\nthe '--no-print-directory' option is still required with GNU 'make' if\nthe \"Entering/Leaving directory ...\" messages are to be disabled.\n\nFile: automake-1.16.info, Node: Not Enough, Next: Distributing, Prev: Silencing Make, Up: Top\n" } ] }, "22 When Automake Isn't Enough": { "content": "In some situations, where Automake is not up to one task, one has to\nresort to handwritten rules or even handwritten 'Makefile's.\n\n* Menu:\n\n* Extending:: Adding new rules or overriding existing ones.\n* Third-Party Makefiles:: Integrating Non-Automake 'Makefile's.\n\nFile: automake-1.16.info, Node: Extending, Next: Third-Party Makefiles, Up: Not Enough\n", "subsections": [ { "name": "22.1 Extending Automake Rules", "content": "With some minor exceptions (for example 'PROGRAMS' variables, 'TESTS',\nor 'XFAILTESTS') being rewritten to append '$(EXEEXT)'), the contents\nof a 'Makefile.am' is copied to 'Makefile.in' verbatim.\n\nThese copying semantics mean that many problems can be worked around\nby simply adding some 'make' variables and rules to 'Makefile.am'.\nAutomake will ignore these additions.\n\nSince a 'Makefile.in' is built from data gathered from three\ndifferent places ('Makefile.am', 'configure.ac', and 'automake' itself),\nit is possible to have conflicting definitions of rules or variables.\nWhen building 'Makefile.in' the following priorities are respected by\n'automake' to ensure the user always has the last word:\n\n* User defined variables in 'Makefile.am' have priority over\nvariables 'ACSUBST'ed from 'configure.ac', and 'ACSUBST'ed\nvariables have priority over 'automake'-defined variables.\n* As far as rules are concerned, a user-defined rule overrides any\n'automake'-defined rule for the same target.\n\nThese overriding semantics make it possible to fine tune some default\nsettings of Automake, or replace some of its rules. Overriding Automake\nrules is often inadvisable, particularly in the topmost directory of a\npackage with subdirectories. The '-Woverride' option (*note automake\nInvocation::) comes in handy to catch overridden definitions.\n\nNote that Automake does not make any distinction between rules with\ncommands and rules that only specify dependencies. So it is not\npossible to append new dependencies to an 'automake'-defined target\nwithout redefining the entire rule.\n\nHowever, various useful targets have a '-local' version you can\nspecify in your 'Makefile.am'. Automake will supplement the standard\ntarget with these user-supplied targets.\n\nThe targets that support a local version are 'all', 'info', 'dvi',\n'ps', 'pdf', 'html', 'check', 'install-data', 'install-dvi',\n'install-exec', 'install-html', 'install-info', 'install-pdf',\n'install-ps', 'uninstall', 'installdirs', 'installcheck' and the various\n'clean' targets ('mostlyclean', 'clean', 'distclean', and\n'maintainer-clean').\n\nNote that there are no 'uninstall-exec-local' or\n'uninstall-data-local' targets; just use 'uninstall-local'. It doesn't\nmake sense to uninstall just data or just executables.\n\nFor instance, here is one way to erase a subdirectory during 'make\nclean' (*note Clean::).\n\nclean-local:\n-rm -rf testSubDir\n\nYou may be tempted to use 'install-data-local' to install a file to\nsome hard-coded location, but you should avoid this (*note Hard-Coded\nInstall Paths::).\n\nWith the '-local' targets, there is no particular guarantee of\nexecution order; typically, they are run early, but with parallel make,\nthere is no way to be sure of that.\n\nIn contrast, some rules also have a way to run another rule, called a\n\"hook\"; hooks are always executed after the main rule's work is done.\nThe hook is named after the principal target, with '-hook' appended.\nThe targets allowing hooks are 'install-data', 'install-exec',\n'uninstall', 'dist', and 'distcheck'.\n\nFor instance, here is how to create a hard link to an installed\nprogram:\n\ninstall-exec-hook:\nln $(DESTDIR)$(bindir)/program$(EXEEXT) \\\n$(DESTDIR)$(bindir)/proglink$(EXEEXT)\n\nAlthough cheaper and more portable than symbolic links, hard links\nwill not work everywhere (for instance, OS/2 does not have 'ln').\nIdeally you should fall back to 'cp -p' when 'ln' does not work. An\neasy way, if symbolic links are acceptable to you, is to add\n'ACPROGLNS' to 'configure.ac' (*note Particular Program Checks:\n(autoconf)Particular Programs.) and use '$(LNS)' in 'Makefile.am'.\n\nFor instance, here is how you could install a versioned copy of a\nprogram using '$(LNS)':\n\ninstall-exec-hook:\ncd $(DESTDIR)$(bindir) && \\\nmv -f prog$(EXEEXT) prog-$(VERSION)$(EXEEXT) && \\\n$(LNS) prog-$(VERSION)$(EXEEXT) prog$(EXEEXT)\n\nNote that we rename the program so that a new version will erase the\nsymbolic link, not the real binary. Also we 'cd' into the destination\ndirectory in order to create relative links.\n\nWhen writing 'install-exec-hook' or 'install-data-hook', please bear\nin mind that the exec/data distinction is based on the installation\ndirectory, not on the primary used (*note The Two Parts of Install::).\nSo a 'fooSCRIPTS' will be installed by 'install-data', and a\n'barexecSCRIPTS' will be installed by 'install-exec'. You should\ndefine your hooks accordingly.\n\nFile: automake-1.16.info, Node: Third-Party Makefiles, Prev: Extending, Up: Not Enough\n" }, { "name": "22.2 Third-Party 'Makefile's", "content": "In most projects all 'Makefile's are generated by Automake. In some\ncases, however, projects need to embed subdirectories with handwritten\n'Makefile's. For instance, one subdirectory could be a third-party\nproject with its own build system, not using Automake.\n\nIt is possible to list arbitrary directories in 'SUBDIRS' or\n'DISTSUBDIRS' provided each of these directories has a 'Makefile' that\nrecognizes all the following recursive targets.\n\nWhen a user runs one of these targets, that target is run recursively\nin all subdirectories. This is why it is important that even\nthird-party 'Makefile's support them.\n\n'all'\nCompile the entire package. This is the default target in\nAutomake-generated 'Makefile's, but it does not need to be the\ndefault in third-party 'Makefile's.\n\n'distdir'\nCopy files to distribute into '$(distdir)', before a tarball is\nconstructed. Of course this target is not required if the\n'no-dist' option (*note Options::) is used.\n\nThe variables '$(topdistdir)' and '$(distdir)' (*note The dist\nHook::) will be passed from the outer package to the subpackage\nwhen the 'distdir' target is invoked. These two variables have\nbeen adjusted for the directory that is being recursed into, so\nthey are ready to use.\n\n'install'\n'install-data'\n'install-exec'\n'uninstall'\nInstall or uninstall files (*note Install::).\n\n'install-dvi'\n'install-html'\n'install-info'\n'install-ps'\n'install-pdf'\nInstall only some specific documentation format (*note Texinfo::).\n\n'installdirs'\nCreate install directories, but do not install any files.\n\n'check'\n'installcheck'\nCheck the package (*note Tests::).\n\n'mostlyclean'\n'clean'\n'distclean'\n'maintainer-clean'\nCleaning rules (*note Clean::).\n\n'dvi'\n'pdf'\n'ps'\n'info'\n'html'\nBuild the documentation in various formats (*note Texinfo::).\n\n'tags'\n'ctags'\nBuild 'TAGS' and 'CTAGS' (*note Tags::).\n\nIf you have ever used Gettext in a project, this is a good example of\nhow third-party 'Makefile's can be used with Automake. The 'Makefile's\nthat 'gettextize' puts in the 'po/' and 'intl/' directories are\nhandwritten 'Makefile's that implement all of these targets. That way\nthey can be added to 'SUBDIRS' in Automake packages.\n\nDirectories that are only listed in 'DISTSUBDIRS' but not in\n'SUBDIRS' need only the 'distclean', 'maintainer-clean', and 'distdir'\nrules (*note Conditional Subdirectories::).\n\nUsually, many of these rules are irrelevant to the third-party\nsubproject, but they are required for the whole package to work. It's\nOK to have a rule that does nothing, so if you are integrating a\nthird-party project with no documentation or tag support, you could\nsimply augment its 'Makefile' as follows:\n\nEMPTYAUTOMAKETARGETS = dvi pdf ps info html tags ctags\n.PHONY: $(EMPTYAUTOMAKETARGETS)\n$(EMPTYAUTOMAKETARGETS):\n\nTo be clear, there is nothing special about the variable name\n'EMPTYAUTOMAKETARGETS'; the name could be anything.\n\nAnother aspect of integrating third-party build systems is whether\nthey support VPATH builds (*note VPATH Builds::). Obviously if the\nsubpackage does not support VPATH builds the whole package will not\nsupport VPATH builds. This in turns means that 'make distcheck' will\nnot work, because it relies on VPATH builds. Some people can live\nwithout this (indeed, many Automake users have never heard of 'make\ndistcheck'). Other people may prefer to revamp the existing 'Makefile's\nto support VPATH. Doing so does not necessarily require Automake; only\nAutoconf is needed (*note Build Directories: (autoconf)Build\nDirectories.). The necessary substitutions: '@srcdir@', '@topsrcdir@',\nand '@topbuilddir@' are defined by 'configure' when it processes a\n'Makefile' (*note Preset Output Variables: (autoconf)Preset Output\nVariables.); they are not computed by the Makefile like the\naforementioned '$(distdir)' and '$(topdistdir)' variables.\n\nIt is sometimes inconvenient to modify a third-party 'Makefile' to\nintroduce the above required targets. For instance, one may want to\nkeep the third-party sources untouched to ease upgrades to new versions.\n\nHere are two other ideas. If GNU Make is assumed, one possibility is\nto add to that subdirectory a 'GNUmakefile' that defines the required\ntargets and includes the third-party 'Makefile'. For this to work in\nVPATH builds, 'GNUmakefile' must lie in the build directory; the easiest\nway to do this is to write a 'GNUmakefile.in' instead, and have it\nprocessed with 'ACCONFIGFILES' from the outer package. For example,\nif we assume 'Makefile' defines all targets except the documentation\ntargets, and that the real 'check' target is named 'test', we could\nwrite 'GNUmakefile' (or 'GNUmakefile.in') like this:\n\n# First, include the real Makefile\ninclude Makefile\n# Then, define the other targets needed by Automake Makefiles.\n.PHONY: dvi pdf ps info html check\ndvi pdf ps info html:\ncheck: test\n\nA similar idea that does not use 'include' is to write a proxy\n'Makefile' that dispatches rules to the real 'Makefile', either with\n'$(MAKE) -f Makefile.real $(AMMAKEFLAGS) target' (if it's OK to rename\nthe original 'Makefile') or with 'cd subdir && $(MAKE) $(AMMAKEFLAGS)\ntarget' (if it's OK to store the subdirectory project one directory\ndeeper). The good news is that this proxy 'Makefile' can be generated\nwith Automake. All we need are '-local' targets (*note Extending::)\nthat perform the dispatch. Of course the other Automake features are\navailable, so you could decide to let Automake perform distribution or\ninstallation. Here is a possible 'Makefile.am':\n\nall-local:\ncd subdir && $(MAKE) $(AMMAKEFLAGS) all\ncheck-local:\ncd subdir && $(MAKE) $(AMMAKEFLAGS) test\nclean-local:\ncd subdir && $(MAKE) $(AMMAKEFLAGS) clean\n\n# Assuming the package knows how to install itself\ninstall-data-local:\ncd subdir && $(MAKE) $(AMMAKEFLAGS) install-data\ninstall-exec-local:\ncd subdir && $(MAKE) $(AMMAKEFLAGS) install-exec\nuninstall-local:\ncd subdir && $(MAKE) $(AMMAKEFLAGS) uninstall\n\n# Distribute files from here.\nEXTRADIST = subdir/Makefile subdir/program.c ...\n\nPushing this idea to the extreme, it is also possible to ignore the\nsubproject build system and build everything from this proxy\n'Makefile.am'. This might sound very sensible if you need VPATH builds\nbut the subproject does not support them.\n\nFile: automake-1.16.info, Node: Distributing, Next: API Versioning, Prev: Not Enough, Up: Top\n" } ] }, "23 Distributing 'Makefile.in's": { "content": "Automake places no restrictions on the distribution of the resulting\n'Makefile.in's. We still encourage software authors to distribute their\nwork under terms like those of the GPL, but doing so is not required to\nuse Automake.\n\nSome of the files that can be automatically installed via the\n'--add-missing' switch do fall under the GPL. However, these also have\na special exception allowing you to distribute them with your package,\nregardless of the licensing you choose.\n\nFile: automake-1.16.info, Node: API Versioning, Next: Upgrading, Prev: Distributing, Up: Top\n", "subsections": [] }, "24 Automake API Versioning": { "content": "New Automake releases usually include bug fixes and new features.\nUnfortunately they may also introduce new bugs and incompatibilities.\nThis makes four reasons why a package may require a particular Automake\nversion.\n\nThings get worse when maintaining a large tree of packages, each one\nrequiring a different version of Automake. In the past, this meant that\nany developer (and sometimes users) had to install several versions of\nAutomake in different places, and switch '$PATH' appropriately for each\npackage.\n\nStarting with version 1.6, Automake installs versioned binaries.\nThis means you can install several versions of Automake in the same\n'$prefix', and can select an arbitrary Automake version by running\n'automake-1.6' or 'automake-1.7' without juggling with '$PATH'.\nFurthermore, 'Makefile's generated by Automake 1.6 will use\n'automake-1.6' explicitly in their rebuild rules.\n\nThe number '1.6' in 'automake-1.6' is Automake's API version, not\nAutomake's version. If a bug fix release is made, for instance Automake\n1.6.1, the API version will remain 1.6. This means that a package that\nworks with Automake 1.6 should also work with 1.6.1; after all, this is\nwhat people expect from bug fix releases.\n\nIf your package relies on a feature or a bug fix introduced in a\nrelease, you can pass this version as an option to Automake to ensure\nolder releases will not be used. For instance, use this in your\n'configure.ac':\n\nAMINITAUTOMAKE([1.6.1]) dnl Require Automake 1.6.1 or better.\n\nor, in a particular 'Makefile.am':\n\nAUTOMAKEOPTIONS = 1.6.1 # Require Automake 1.6.1 or better.\n\nAutomake will print an error message if its version is older than the\nrequested version.\n", "subsections": [ { "name": "What is in the API", "content": "Automake's programming interface is not easy to define. Basically it\nshould include at least all *documented* variables and targets that a\n'Makefile.am' author can use, any behavior associated with them (e.g.,\nthe places where '-hook''s are run), the command line interface of\n'automake' and 'aclocal', ...\n" }, { "name": "What is not in the API", "content": "Every undocumented variable, target, or command line option is not part\nof the API. You should avoid using them, as they could change from one\nversion to the other (even in bug fix releases, if this helps to fix a\nbug).\n\nIf it turns out you need to use such an undocumented feature, contact\n and try to get it documented and exercised by the\ntest-suite.\n\nFile: automake-1.16.info, Node: Upgrading, Next: FAQ, Prev: API Versioning, Up: Top\n" } ] }, "25 Upgrading a Package to a Newer Automake Version": { "content": "Automake maintains three kinds of files in a package.\n\n* 'aclocal.m4'\n* 'Makefile.in's\n* auxiliary tools like 'install-sh' or 'py-compile'\n\n'aclocal.m4' is generated by 'aclocal' and contains some\nAutomake-supplied M4 macros. Auxiliary tools are installed by 'automake\n--add-missing' when needed. 'Makefile.in's are built from 'Makefile.am'\nby 'automake', and rely on the definitions of the M4 macros put in\n'aclocal.m4' as well as the behavior of the auxiliary tools installed.\n\nBecause all of these files are closely related, it is important to\nregenerate all of them when upgrading to a newer Automake release. The\nusual way to do that is\n\naclocal # with any option needed (such as -I m4)\nautoconf\nautomake --add-missing --force-missing\n\nor more conveniently:\n\nautoreconf -vfi\n\nThe use of '--force-missing' ensures that auxiliary tools will be\noverridden by new versions (*note automake Invocation::).\n\nIt is important to regenerate all of these files each time Automake\nis upgraded, even between bug fix releases. For instance, it is not\nunusual for a bug fix to involve changes to both the rules generated in\n'Makefile.in' and the supporting M4 macros copied to 'aclocal.m4'.\n\nPresently 'automake' is able to diagnose situations where\n'aclocal.m4' has been generated with another version of 'aclocal'.\nHowever it never checks whether auxiliary scripts are up-to-date. In\nother words, 'automake' will tell you when 'aclocal' needs to be rerun,\nbut it will never diagnose a missing '--force-missing'.\n\nBefore upgrading to a new major release, it is a good idea to read\nthe file 'NEWS'. This file lists all changes between releases: new\nfeatures, obsolete constructs, known incompatibilities, and workarounds.\n\nFile: automake-1.16.info, Node: FAQ, Next: Copying This Manual, Prev: Upgrading, Up: Top\n", "subsections": [] }, "26 Frequently Asked Questions about Automake": { "content": "This chapter covers some questions that often come up on the mailing\nlists.\n\n* Menu:\n\n* CVS:: CVS and generated files\n* maintainer-mode:: missing and AMMAINTAINERMODE\n* Wildcards:: Why doesn't Automake support wildcards?\n* Limitations on File Names:: Limitations on source and installed file names\n* Errors with distclean:: Files left in build directory after distclean\n* Flag Variables Ordering:: CFLAGS vs. AMCFLAGS vs. mumbleCFLAGS\n* Renamed Objects:: Why are object files sometimes renamed?\n* Per-Object Flags:: How to simulate per-object flags?\n* Multiple Outputs:: Writing rules for tools with many output files\n* Hard-Coded Install Paths:: Installing to hard-coded locations\n* Debugging Make Rules:: Strategies when things don't work as expected\n* Reporting Bugs:: Feedback on bugs and feature requests\n\nFile: automake-1.16.info, Node: CVS, Next: maintainer-mode, Up: FAQ\n", "subsections": [ { "name": "26.1 CVS and generated files", "content": "Packages made with Autoconf and Automake ship with some generated files\nlike 'configure' or 'Makefile.in'. These files were generated on the\ndeveloper's machine and are distributed so that end-users do not have to\ninstall the maintainer tools required to rebuild them. Other generated\nfiles like Lex scanners, Yacc parsers, or Info documentation are usually\ndistributed on similar grounds.\n\nAutomake output generates rules in 'Makefile's to rebuild these\nfiles. For instance, 'make' will run 'autoconf' to rebuild 'configure'\nwhenever 'configure.ac' is changed. This makes development safer by\nensuring a 'configure' is never out-of-date with respect to\n'configure.ac'.\n\nAs generated files shipped in packages are up-to-date, and because\n'tar' preserves times-tamps, these rebuild rules are not triggered when\na user unpacks and builds a package.\n\n\nUnless you use CVS keywords (in which case files must be updated at\ncommit time), CVS preserves timestamp during 'cvs commit' and 'cvs\nimport -d' operations.\n\nWhen you check out a file using 'cvs checkout' its timestamp is set\nto that of the revision that is being checked out.\n\nHowever, during 'cvs update', files will have the date of the update,\nnot the original timestamp of this revision. This is meant to make sure\nthat 'make' notices that sources files have been updated.\n\nThis timestamp shift is troublesome when both sources and generated\nfiles are kept under CVS. Because CVS processes files in lexical order,\n'configure.ac' will appear newer than 'configure' after a 'cvs update'\nthat updates both files, even if 'configure' was newer than\n'configure.ac' when it was checked in. Calling 'make' will then trigger\na spurious rebuild of 'configure'.\n\n\nThere are basically two clans amongst maintainers: those who keep all\ndistributed files under CVS, including generated files, and those who\nkeep generated files out of CVS.\n\nAll Files in CVS\n................\n\n* The CVS repository contains all distributed files so you know\nexactly what is distributed, and you can check out any prior\nversion entirely.\n\n* Maintainers can see how generated files evolve (for instance, you\ncan see what happens to your 'Makefile.in's when you upgrade\nAutomake and make sure they look OK).\n\n* Users do not need Autotools to build a check-out of the project; it\nworks just like a released tarball.\n\n* If users use 'cvs update' to update their copy, instead of 'cvs\ncheckout' to fetch a fresh one, timestamps will be inaccurate.\nSome rebuild rules will be triggered and attempt to run developer\ntools such as 'autoconf' or 'automake'.\n\nCalls to such tools are all wrapped into a call to the 'missing'\nscript discussed later (*note maintainer-mode::), so that the user\nwill see more descriptive warnings about missing or out-of-date\ntools, and possible suggestions about how to obtain them, rather\nthan just some \"command not found\" error, or (worse) some obscure\nmessage from some older version of the required tool they happen to\nhave installed.\n\nMaintainers interested in keeping their package buildable from a\nCVS checkout even for those users that lack maintainer-specific\ntools might want to provide a helper script (or to enhance their\nexisting bootstrap script) to fix the timestamps after a 'cvs\nupdate' or a 'git checkout', to prevent spurious rebuilds. In case\nof a project committing the Autotools-generated files, as well as\nthe generated '.info' files, such a script might look something\nlike this:\n\n#!/bin/sh\n# fix-timestamp.sh: prevents useless rebuilds after \"cvs update\"\nsleep 1\n# aclocal-generated aclocal.m4 depends on locally-installed\n# '.m4' macro files, as well as on 'configure.ac'\ntouch aclocal.m4\nsleep 1\n# autoconf-generated configure depends on aclocal.m4 and on\n# configure.ac\ntouch configure\n# so does autoheader-generated config.h.in\ntouch config.h.in\n# and all the automake-generated Makefile.in files\ntouch `find . -name Makefile.in -print`\n# finally, the makeinfo-generated '.info' files depend on the\n# corresponding '.texi' files\ntouch doc/*.info\n\n* In distributed development, developers are likely to have different\nversions of the maintainer tools installed. In this case rebuilds\ntriggered by timestamp lossage will lead to spurious changes to\ngenerated files. There are several solutions to this:\n\n* All developers should use the same versions, so that the\nrebuilt files are identical to files in CVS. (This starts to\nbe difficult when each project you work on uses different\nversions.)\n* Or people use a script to fix the timestamp after a checkout\n(the GCC folks have such a script).\n* Or 'configure.ac' uses 'AMMAINTAINERMODE', which will\ndisable all of these rebuild rules by default. This is\nfurther discussed in *note maintainer-mode::.\n\n* Although we focused on spurious rebuilds, the converse can also\nhappen. CVS's timestamp handling can also let you think an\nout-of-date file is up-to-date.\n\nFor instance, suppose a developer has modified 'Makefile.am' and\nhas rebuilt 'Makefile.in', and then decides to do a last-minute\nchange to 'Makefile.am' right before checking in both files\n(without rebuilding 'Makefile.in' to account for the change).\n\nThis last change to 'Makefile.am' makes the copy of 'Makefile.in'\nout-of-date. Since CVS processes files alphabetically, when\nanother developer 'cvs update's his or her tree, 'Makefile.in' will\nhappen to be newer than 'Makefile.am'. This other developer will\nnot see that 'Makefile.in' is out-of-date.\n\nGenerated Files out of CVS\n..........................\n\nOne way to get CVS and 'make' working peacefully is to never store\ngenerated files in CVS, i.e., do not CVS-control files that are\n'Makefile' targets (also called derived files).\n\nThis way developers are not annoyed by changes to generated files.\nIt does not matter if they all have different versions (assuming they\nare compatible, of course). And finally, timestamps are not lost;\nchanges to sources files can't be missed as in the\n'Makefile.am'/'Makefile.in' example discussed earlier.\n\nThe drawback is that the CVS repository is not an exact copy of what\nis distributed and that users now need to install various development\ntools (maybe even specific versions) before they can build a checkout.\nBut, after all, CVS's job is versioning, not distribution.\n\nAllowing developers to use different versions of their tools can also\nhide bugs during distributed development. Indeed, developers will be\nusing (hence testing) their own generated files, instead of the\ngenerated files that will be released. The developer who prepares the\ntarball might be using a version of the tool that produces bogus output\n(for instance a non-portable C file), something other developers could\nhave noticed if they weren't using their own versions of this tool.\n\n\nAnother class of files not discussed here (because they do not cause\ntimestamp issues) are files that are shipped with a package, but\nmaintained elsewhere. For instance, tools like 'gettextize' and\n'autopoint' (from Gettext) or 'libtoolize' (from Libtool), will install\nor update files in your package.\n\nThese files, whether they are kept under CVS or not, raise similar\nconcerns about version mismatch between developers' tools. The Gettext\nmanual has a section about this; see *note Integrating with Version\nControl Systems: (gettext)Version Control Issues.\n\nFile: automake-1.16.info, Node: maintainer-mode, Next: Wildcards, Prev: CVS, Up: FAQ\n" }, { "name": "26.2 'missing' and 'AMMAINTAINERMODE'", "content": "The 'missing' script is a wrapper around several maintainer tools,\ndesigned to warn users if a maintainer tool is required but missing.\nTypical maintainer tools are 'autoconf', 'automake', 'bison', etc.\nBecause files generated by these tools are shipped with the other\nsources of a package, these tools shouldn't be required during a user\nbuild and they are not checked for in 'configure'.\n\nHowever, if for some reason a rebuild rule is triggered and involves\na missing tool, 'missing' will notice it and warn the user, even\nsuggesting how to obtain such a tool (at least in case it is a\nwell-known one, like 'makeinfo' or 'bison'). This is more helpful and\nuser-friendly than just having the rebuild rules spewing out a terse\nerror message like 'sh: TOOL: command not found'. Similarly, 'missing'\nwill warn the user if it detects that a maintainer tool it attempted to\nuse seems too old (be warned that diagnosing this correctly is typically\nmore difficult than detecting missing tools, and requires cooperation\nfrom the tool itself, so it won't always work).\n\nIf the required tool is installed, 'missing' will run it and won't\nattempt to continue after failures. This is correct behavior during\ndevelopment: developers love fixing failures. However, users with\nmissing or too old maintainer tools may get an error when the rebuild\nrule is spuriously triggered, halting the build. This failure to let\nthe build continue is one of the arguments of the 'AMMAINTAINERMODE'\nadvocates.\n\n\n'AMMAINTAINERMODE' allows you to choose whether the so called \"rebuild\nrules\" should be enabled or disabled. With\n'AMMAINTAINERMODE([enable])', they are enabled by default; otherwise\nthey are disabled by default. In the latter case, if you have\n'AMMAINTAINERMODE' in 'configure.ac', and run './configure && make',\nthen 'make' will *never* attempt to rebuild 'configure', 'Makefile.in's,\nLex or Yacc outputs, etc. That is, this disables build rules for files\nthat are usually distributed and that users should normally not have to\nupdate.\n\nThe user can override the default setting by passing either\n'--enable-maintainer-mode' or '--disable-maintainer-mode' to\n'configure'.\n\nPeople use 'AMMAINTAINERMODE' either because they do not want their\nusers (or themselves) annoyed by timestamp lossage (*note CVS::), or\nbecause they simply can't stand the rebuild rules and prefer running\nmaintainer tools explicitly.\n\n'AMMAINTAINERMODE' also allows you to disable some custom build\nrules conditionally. Some developers use this feature to disable rules\nthat need exotic tools that users may not have available.\n\nSeveral years ago Franc,ois Pinard pointed out several arguments\nagainst this 'AMMAINTAINERMODE' macro. Most of them relate to\ninsecurity. By removing dependencies you get non-dependable builds:\nchanges to source files can have no effect on generated files and this\ncan be very confusing when unnoticed. He adds that security shouldn't\nbe reserved to maintainers (what '--enable-maintainer-mode' suggests),\non the contrary. If one user has to modify a 'Makefile.am', then either\n'Makefile.in' should be updated or a warning should be output (this is\nwhat Automake uses 'missing' for) but the last thing you want is that\nnothing happens and the user doesn't notice it (this is what happens\nwhen rebuild rules are disabled by 'AMMAINTAINERMODE').\n\nJim Meyering, the inventor of the 'AMMAINTAINERMODE' macro, was\nswayed by Franc,ois' arguments, and got rid of 'AMMAINTAINERMODE' in\nall of his packages.\n\nStill many people continue to use 'AMMAINTAINERMODE', because it\nhelps them working on projects where all files are kept under version\ncontrol, and because 'missing' isn't enough if you have the wrong\nversion of the tools.\n\nFile: automake-1.16.info, Node: Wildcards, Next: Limitations on File Names, Prev: maintainer-mode, Up: FAQ\n" }, { "name": "26.3 Why doesn't Automake support wildcards?", "content": "Developers are lazy. They would often like to use wildcards in\n'Makefile.am's, so that they would not need to remember to update\n'Makefile.am's every time they add, delete, or rename a file.\n\nThere are several objections to this:\n* When using CVS (or similar) developers need to remember they have\nto run 'cvs add' or 'cvs rm' anyway. Updating 'Makefile.am'\naccordingly quickly becomes a reflex.\n\nConversely, if your application doesn't compile because you forgot\nto add a file in 'Makefile.am', it will help you remember to 'cvs\nadd' it.\n\n* Using wildcards makes it easy to distribute files by mistake. For\ninstance, some code a developer is experimenting with (a test case,\nsay) that should not be part of the distribution.\n\n* Using wildcards it's easy to omit some files by mistake. For\ninstance, one developer creates a new file, uses it in many places,\nbut forgets to commit it. Another developer then checks out the\nincomplete project and is able to run 'make dist' successfully,\neven though a file is missing. By listing files, 'make dist'\nwill complain.\n\n* Wildcards are not portable to some non-GNU 'make' implementations,\ne.g., NetBSD 'make' will not expand globs such as '*' in\nprerequisites of a target.\n\n* Finally, it's quite hard to forget to add a file to\n'Makefile.am': files that are not listed in 'Makefile.am' are not\ncompiled or installed, so you can't even test them.\n\nStill, these are philosophical objections, and as such you may\ndisagree, or find enough value in wildcards to dismiss all of them.\nBefore you start writing a patch against Automake to teach it about\nwildcards, let's see the main technical issue: portability.\n\nAlthough '$(wildcard ...)' works with GNU 'make', it is not portable\nto other 'make' implementations.\n\nThe only way Automake could support '$(wildcard ...)' is by expanding\n'$(wildcard ...)' when 'automake' is run. The resulting 'Makefile.in's\nwould be portable since they would list all files and not use\n'$(wildcard ...)'. However that means developers would need to remember\nto run 'automake' each time they add, delete, or rename files.\n\nCompared to editing 'Makefile.am', this is a very small gain. Sure,\nit's easier and faster to type 'automake; make' than to type 'emacs\nMakefile.am; make'. But nobody bothered enough to write a patch to add\nsupport for this syntax. Some people use scripts to generate file lists\nin 'Makefile.am' or in separate 'Makefile' fragments.\n\nEven if you don't care about portability, and are tempted to use\n'$(wildcard ...)' anyway because you target only GNU Make, you should\nknow there are many places where Automake needs to know exactly which\nfiles should be processed. As Automake doesn't know how to expand\n'$(wildcard ...)', you cannot use it in these places. '$(wildcard ...)'\nis a black box comparable to 'ACSUBST'ed variables as far Automake is\nconcerned.\n\nYou can get warnings about '$(wildcard ...') constructs using the\n'-Wportability' flag.\n\nFile: automake-1.16.info, Node: Limitations on File Names, Next: Errors with distclean, Prev: Wildcards, Up: FAQ\n" }, { "name": "26.4 Limitations on File Names", "content": "Automake attempts to support all kinds of file names, even those that\ncontain unusual characters or are unusually long. However, some\nlimitations are imposed by the underlying operating system and tools.\n\nMost operating systems prohibit the use of the null byte in file\nnames, and reserve '/' as a directory separator. Also, they require\nthat file names are properly encoded for the user's locale. Automake is\nsubject to these limits.\n\nPortable packages should limit themselves to POSIX file names. These\ncan contain ASCII letters and digits, '', '.', and '-'. File names\nconsist of components separated by '/'. File name components cannot\nbegin with '-'.\n\nPortable POSIX file names cannot contain components that exceed a\n14-byte limit, but nowadays it's normally safe to assume the\nmore-generous XOPEN limit of 255 bytes. POSIX limits file names to 255\nbytes (XOPEN allows 1023 bytes), but you may want to limit a source\ntarball to file names of 99 bytes to avoid interoperability problems\nwith old versions of 'tar'.\n\nIf you depart from these rules (e.g., by using non-ASCII characters\nin file names, or by using lengthy file names), your installers may have\nproblems for reasons unrelated to Automake. However, if this does not\nconcern you, you should know about the limitations imposed by Automake\nitself. These limitations are undesirable, but some of them seem to be\ninherent to underlying tools like Autoconf, Make, M4, and the shell.\nThey fall into three categories: install directories, build directories,\nand file names.\n\nThe following characters:\n\nnewline \" # $ ' `\n\nshould not appear in the names of install directories. For example,\nthe operand of 'configure''s '--prefix' option should not contain these\ncharacters.\n\nBuild directories suffer the same limitations as install directories,\nand in addition should not contain the following characters:\n\n& @ \\\n\nFor example, the full name of the directory containing the source\nfiles should not contain these characters.\n\nSource and installation file names like 'main.c' are limited even\nfurther: they should conform to the POSIX/XOPEN rules described above.\nIn addition, if you plan to port to non-POSIX environments, you should\navoid file names that differ only in case (e.g., 'makefile' and\n'Makefile'). Nowadays it is no longer worth worrying about the 8.3\nlimits of DOS file systems.\n\nFile: automake-1.16.info, Node: Errors with distclean, Next: Flag Variables Ordering, Prev: Limitations on File Names, Up: FAQ\n" }, { "name": "26.5 Errors with distclean", "content": "This is a diagnostic you might encounter while running 'make distcheck'.\n\nAs explained in *note Checking the Distribution::, 'make distcheck'\nattempts to build and check your package for errors like this one.\n\n'make distcheck' will perform a 'VPATH' build of your package (*note\nVPATH Builds::), and then call 'make distclean'. Files left in the\nbuild directory after 'make distclean' has run are listed after this\nerror.\n\nThis diagnostic covers two kinds of errors:\n\n* files that are forgotten by distclean;\n* distributed files that are erroneously rebuilt.\n\nThe former left-over files are not distributed, so the fix is to mark\nthem for cleaning (*note Clean::); this is obvious and doesn't deserve\nmore explanation.\n\nThe latter bug is not always easy to understand and fix, so let's\nproceed with an example. Suppose our package contains a program for\nwhich we want to build a man page using 'help2man'. GNU 'help2man'\nproduces simple manual pages from the '--help' and '--version' output of\nother commands (*note Overview: (help2man)Top.). Because we don't want\nto force our users to install 'help2man', we decide to distribute the\ngenerated man page using the following setup.\n\n# This Makefile.am is bogus.\nbinPROGRAMS = foo\nfooSOURCES = foo.c\ndistmanMANS = foo.1\n\nfoo.1: foo$(EXEEXT)\nhelp2man --output=foo.1 ./foo$(EXEEXT)\n\nThis will effectively distribute the man page. However, 'make\ndistcheck' will fail with:\n\nERROR: files left in build directory after distclean:\n./foo.1\n\nWhy was 'foo.1' rebuilt? Because although distributed, 'foo.1'\ndepends on a non-distributed built file: 'foo$(EXEEXT)'. 'foo$(EXEEXT)'\nis built by the user, so it will always appear to be newer than the\ndistributed 'foo.1'.\n\n'make distcheck' caught an inconsistency in our package. Our intent\nwas to distribute 'foo.1' so users do not need to install 'help2man',\nhowever since this rule causes this file to be always rebuilt, users\ndo need 'help2man'. Either we should ensure that 'foo.1' is not\nrebuilt by users, or there is no point in distributing 'foo.1'.\n\nMore generally, the rule is that distributed files should never\ndepend on non-distributed built files. If you distribute something\ngenerated, distribute its sources.\n\nOne way to fix the above example, while still distributing 'foo.1',\nis to not depend on 'foo$(EXEEXT)'. For instance, assuming 'foo\n--version' and 'foo --help' do not change unless 'foo.c' or\n'configure.ac' change, we could write the following 'Makefile.am':\n\nbinPROGRAMS = foo\nfooSOURCES = foo.c\ndistmanMANS = foo.1\n\nfoo.1: foo.c $(topsrcdir)/configure.ac\n$(MAKE) $(AMMAKEFLAGS) foo$(EXEEXT)\nhelp2man --output=foo.1 ./foo$(EXEEXT)\n\nThis way, 'foo.1' will not get rebuilt every time 'foo$(EXEEXT)'\nchanges. The 'make' call makes sure 'foo$(EXEEXT)' is up-to-date before\n'help2man'. Another way to ensure this would be to use separate\ndirectories for binaries and man pages, and set 'SUBDIRS' so that\nbinaries are built before man pages.\n\nWe could also decide not to distribute 'foo.1'. In this case it's\nfine to have 'foo.1' dependent upon 'foo$(EXEEXT)', since both will have\nto be rebuilt. However, it would be impossible to build the package in\na cross-compilation, because building 'foo.1' involves an execution of\n'foo$(EXEEXT)'.\n\nAnother context where such errors are common is when distributed\nfiles are built by tools that are built by the package. The pattern is\nsimilar:\n\ndistributed-file: built-tools distributed-sources\nbuild-command\n\nshould be changed to\n\ndistributed-file: distributed-sources\n$(MAKE) $(AMMAKEFLAGS) built-tools\nbuild-command\n\nor you could choose not to distribute 'distributed-file', if\ncross-compilation does not matter.\n\nThe points made through these examples are worth a summary:\n\n* Distributed files should never depend upon non-distributed built\nfiles.\n* Distributed files should be distributed with all their\ndependencies.\n* If a file is intended to be rebuilt by users, then there is no\npoint in distributing it.\n\nFor desperate cases, it's always possible to disable this check by\nsetting 'distcleanchecklistfiles' as documented in *note Checking the\nDistribution::. Make sure you do understand the reason why 'make\ndistcheck' complains before you do this. 'distcleanchecklistfiles' is\na way to hide errors, not to fix them. You can always do better.\n\nFile: automake-1.16.info, Node: Flag Variables Ordering, Next: Renamed Objects, Prev: Errors with distclean, Up: FAQ\n" }, { "name": "26.6 Flag Variables Ordering", "content": "What is the difference between 'AMCFLAGS', 'CFLAGS', and\n'mumbleCFLAGS'?\n\nWhy does 'automake' output 'CPPFLAGS' after\n'AMCPPFLAGS' on compile lines? Shouldn't it be the converse?\n\nMy 'configure' adds some warning flags into 'CXXFLAGS'. In\none 'Makefile.am' I would like to append a new flag, however if I\nput the flag into 'AMCXXFLAGS' it is prepended to the other\nflags, not appended.\n\n\nThis section attempts to answer all the above questions. We will mostly\ndiscuss 'CPPFLAGS' in our examples, but the answer holds for all the\ncompile flags used in Automake: 'CCASFLAGS', 'CFLAGS', 'CPPFLAGS',\n'CXXFLAGS', 'FCFLAGS', 'FFLAGS', 'GCJFLAGS', 'LDFLAGS', 'LFLAGS',\n'LIBTOOLFLAGS', 'OBJCFLAGS', 'OBJCXXFLAGS', 'RFLAGS', 'UPCFLAGS', and\n'YFLAGS'.\n\n'CPPFLAGS', 'AMCPPFLAGS', and 'mumbleCPPFLAGS' are three variables\nthat can be used to pass flags to the C preprocessor ( these variables\nare also used for other languages like C++ or preprocessed Fortran).\n'CPPFLAGS' is the user variable (*note User Variables::), 'AMCPPFLAGS'\nis the Automake variable, and 'mumbleCPPFLAGS' is the variable specific\nto the 'mumble' target (we call this a per-target variable, *note\nProgram and Library Variables::).\n\nAutomake always uses two of these variables when compiling C sources\nfiles. When compiling an object file for the 'mumble' target, the first\nvariable will be 'mumbleCPPFLAGS' if it is defined, or 'AMCPPFLAGS'\notherwise. The second variable is always 'CPPFLAGS'.\n\nIn the following example,\n\nbinPROGRAMS = foo bar\nfooSOURCES = xyz.c\nbarSOURCES = main.c\nfooCPPFLAGS = -DFOO\nAMCPPFLAGS = -DBAZ\n\n'xyz.o' will be compiled with '$(fooCPPFLAGS) $(CPPFLAGS)', (because\n'xyz.o' is part of the 'foo' target), while 'main.o' will be compiled\nwith '$(AMCPPFLAGS) $(CPPFLAGS)' (because there is no per-target\nvariable for target 'bar').\n\nThe difference between 'mumbleCPPFLAGS' and 'AMCPPFLAGS' being\nclear enough, let's focus on 'CPPFLAGS'. 'CPPFLAGS' is a user variable,\ni.e., a variable that users are entitled to modify in order to compile\nthe package. This variable, like many others, is documented at the end\nof the output of 'configure --help'.\n\nFor instance, someone who needs to add '/home/my/usr/include' to the\nC compiler's search path would configure a package with\n\n./configure CPPFLAGS='-I /home/my/usr/include'\n\nand this flag would be propagated to the compile rules of all\n'Makefile's.\n\nIt is also not uncommon to override a user variable at 'make'-time.\nMany installers do this with 'prefix', but this can be useful with\ncompiler flags too. For instance, while debugging a C++ project, if you\nneed to disable optimization in one specific object file, you can run\nsomething like\n\nrm file.o\nmake CXXFLAGS=-O0 file.o\nmake\n\nThe reason '$(CPPFLAGS)' appears after '$(AMCPPFLAGS)' or\n'$(mumbleCPPFLAGS)' in the compile command is that users should have\nthe last say. In the example above, the desire is for the\n'CXXFLAGS=-O0' to supersede any other switch from 'AMCXXFLAGS' or\n'mumbleCXXFLAGS'.\n\nIt's true that not all options to all programs can be overridden. So\nin general, users could conceivably want to place options at arbitrary\nplaces in the command line, but Automake does not support this. It\nwould be difficult to make such generality comprehensible. Being able\nto specify the final options commonly suffices.\n\nThus, you should never redefine a user variable such as 'CPPFLAGS' in\n'Makefile.am'. Use 'automake -Woverride' to diagnose such mistakes.\nEven something like\n\nCPPFLAGS = -DDATADIR=\\\"$(datadir)\\\" @CPPFLAGS@\n\nis erroneous. Although this preserves 'configure''s value of\n'CPPFLAGS', the definition of 'DATADIR' will disappear if a user\nattempts to override 'CPPFLAGS' from the 'make' command line.\n\nAMCPPFLAGS = -DDATADIR=\\\"$(datadir)\\\"\n\nis all that is needed here if no per-target flags are used.\n\nYou should not add options to these user variables within 'configure'\neither, for the same reason. Occasionally you need to modify these\nvariables to perform a test, but you should reset their values\nafterwards. In contrast, it is OK to modify the 'AM' variables within\n'configure' if you 'ACSUBST' them, but it is rather rare that you need\nto do this, unless you want to change the default definitions of the\n'AM' variables in all 'Makefile's.\n\nWhat we recommend is that you define extra flags in separate\nvariables. For instance, you may write an Autoconf macro that computes\na set of warning options for the C compiler, and 'ACSUBST' them in\n'WARNINGCFLAGS'; you may also have an Autoconf macro that determines\nwhich compiler and which linker flags should be used to link with\nlibrary 'libfoo', and 'ACSUBST' these in 'LIBFOOCFLAGS' and\n'LIBFOOLDFLAGS'. Then, a 'Makefile.am' could use these variables as\nfollows:\n\nAMCFLAGS = $(WARNINGCFLAGS)\nbinPROGRAMS = prog1 prog2\nprog1SOURCES = ...\nprog2SOURCES = ...\nprog2CFLAGS = $(LIBFOOCFLAGS) $(AMCFLAGS)\nprog2LDFLAGS = $(LIBFOOLDFLAGS)\n\nIn this example both programs will be compiled with the flags\nsubstituted into '$(WARNINGCFLAGS)', and 'prog2' will additionally be\ncompiled with the flags required to link with 'libfoo'.\n\nNote that listing 'AMCFLAGS' in a per-target 'CFLAGS' variable is a\ncommon idiom to ensure that 'AMCFLAGS' applies to every target in a\n'Makefile.in'.\n\nUsing variables like this gives you full control over the ordering of\nthe flags. For instance, if there is a flag in $(WARNINGCFLAGS) that\nyou want to negate for a particular target, you can use something like\n'prog1CFLAGS = $(AMCFLAGS) -no-flag'. If all of these flags had been\nforcefully appended to 'CFLAGS', there would be no way to disable one\nflag. Yet another reason to leave user variables to users.\n\nFinally, we have avoided naming the variable of the example\n'LIBFOOLDFLAGS' (with an underscore) because that would cause Automake\nto think that this is a per-target variable (like 'mumbleLDFLAGS') for\nsome non-declared 'LIBFOO' target.\n\n\nThere are other variables in Automake that follow similar principles to\nallow user options. For instance, Texinfo rules (*note Texinfo::) use\n'MAKEINFOFLAGS' and 'AMMAKEINFOFLAGS'. Similarly, DejaGnu tests (*note\nDejaGnu Tests::) use 'RUNTESTFLAGS' and 'AMRUNTESTFLAGS'. The tags and\nctags rules (*note Tags::) use 'ETAGSFLAGS', 'AMETAGSFLAGS',\n'CTAGSFLAGS', and 'AMCTAGSFLAGS'. Java rules (*note Java::) use\n'JAVACFLAGS' and 'AMJAVACFLAGS'. None of these rules support\nper-target flags (yet).\n\nTo some extent, even 'AMMAKEFLAGS' (*note Subdirectories::) obeys\nthis naming scheme. The slight difference is that 'MAKEFLAGS' is passed\nto sub-'make's implicitly by 'make' itself.\n\n'ARFLAGS' (*note A Library::) is usually defined by Automake and has\nneither an 'AM' nor a per-target cousin.\n\nFinally you should not think that the existence of a per-target\nvariable implies the existence of an 'AM' variable or of a user\nvariable. For instance, the 'mumbleLDADD' per-target variable\noverrides the makefile-wide 'LDADD' variable (which is not a user\nvariable), and 'mumbleLIBADD' exists only as a per-target variable.\n*Note Program and Library Variables::.\n\nFile: automake-1.16.info, Node: Renamed Objects, Next: Per-Object Flags, Prev: Flag Variables Ordering, Up: FAQ\n" }, { "name": "26.7 Why are object files sometimes renamed?", "content": "This happens when per-target compilation flags are used. Object files\nneed to be renamed just in case they would clash with object files\ncompiled from the same sources, but with different flags. Consider the\nfollowing example.\n\nbinPROGRAMS = true false\ntrueSOURCES = generic.c\ntrueCPPFLAGS = -DEXITCODE=0\nfalseSOURCES = generic.c\nfalseCPPFLAGS = -DEXITCODE=1\n\nObviously the two programs are built from the same source, but it would\nbe bad if they shared the same object, because 'generic.o' cannot be\nbuilt with both '-DEXITCODE=0' and '-DEXITCODE=1'. Therefore\n'automake' outputs rules to build two different objects:\n'true-generic.o' and 'false-generic.o'.\n\nAutomake doesn't actually determine whether source files are shared\nto decide if it must rename objects. It just renames all objects of a\ntarget as soon as it sees that per-target compilation flags are used.\n\nIt's OK to share object files when per-target compilation flags are\nnot used. For instance, 'true' and 'false' will both use 'version.o' in\nthe following example.\n\nAMCPPFLAGS = -DVERSION=1.0\nbinPROGRAMS = true false\ntrueSOURCES = true.c version.c\nfalseSOURCES = false.c version.c\n\nNote that the renaming of objects is also affected by the\n'SHORTNAME' variable (*note Program and Library Variables::).\n\nFile: automake-1.16.info, Node: Per-Object Flags, Next: Multiple Outputs, Prev: Renamed Objects, Up: FAQ\n" }, { "name": "26.8 Per-Object Flags Emulation", "content": "One of my source files needs to be compiled with different flags. How\ndo I do that?\n\nAutomake supports per-program and per-library compilation flags (see\n*note Program and Library Variables:: and *note Flag Variables\nOrdering::). With this you can define compilation flags that apply to\nall files compiled for a target. For instance, in\n\nbinPROGRAMS = foo\nfooSOURCES = foo.c foo.h bar.c bar.h main.c\nfooCFLAGS = -some -flags\n\n'foo-foo.o', 'foo-bar.o', and 'foo-main.o' will all be compiled with\n'-some -flags'. (If you wonder about the names of these object files,\nsee *note Renamed Objects::.) Note that 'fooCFLAGS' gives the flags to\nuse when compiling all the C sources of the program 'foo'; it has\nnothing to do with 'foo.c' or 'foo-foo.o' specifically.\n\nWhat if 'foo.c' needs to be compiled into 'foo.o' using some specific\nflags, that none of the other files requires? Obviously per-program\nflags are not directly applicable here. Something like per-object flags\nare expected, i.e., flags that would be used only when creating\n'foo-foo.o'. Automake does not support that; however this is easy to\nsimulate using a library that contains only that object, and compiling\nthis library with per-library flags.\n\nbinPROGRAMS = foo\nfooSOURCES = bar.c bar.h main.c\nfooCFLAGS = -some -flags\nfooLDADD = libfoo.a\nnoinstLIBRARIES = libfoo.a\nlibfooaSOURCES = foo.c foo.h\nlibfooaCFLAGS = -some -other -flags\n\nHere 'foo-bar.o' and 'foo-main.o' will all be compiled with '-some\n-flags', while 'libfooa-foo.o' will be compiled using '-some -other\n-flags'. Eventually, all three objects will be linked to form 'foo'.\n\nThis trick can also be achieved using Libtool convenience libraries,\nfor instance 'noinstLTLIBRARIES = libfoo.la' (*note Libtool Convenience\nLibraries::).\n\nAnother tempting idea to implement per-object flags is to override\nthe compile rules 'automake' would output for these files. Automake\nwill not define a rule for a target you have defined, so you could think\nabout defining the 'foo-foo.o: foo.c' rule yourself. We recommend\nagainst this, because this is error prone. For instance, if you add\nsuch a rule to the first example, it will break the day you decide to\nremove 'fooCFLAGS' (because 'foo.c' will then be compiled as 'foo.o'\ninstead of 'foo-foo.o', *note Renamed Objects::). Also in order to\nsupport dependency tracking, the two '.o'/'.obj' extensions, and all the\nother flags variables involved in a compilation, you will end up\nmodifying a copy of the rule previously output by 'automake' for this\nfile. If a new release of Automake generates a different rule, your\ncopy will need to be updated by hand.\n\nFile: automake-1.16.info, Node: Multiple Outputs, Next: Hard-Coded Install Paths, Prev: Per-Object Flags, Up: FAQ\n" }, { "name": "26.9 Handling Tools that Produce Many Outputs", "content": "This section describes a 'make' idiom that can be used when a tool\nproduces multiple output files. It is not specific to Automake and can\nbe used in ordinary 'Makefile's.\n\nSuppose we have a program called 'foo' that will read one file called\n'data.foo' and produce two files named 'data.c' and 'data.h'. We want\nto write a 'Makefile' rule that captures this one-to-two dependency.\n\nThe naive rule is incorrect:\n\n# This is incorrect.\ndata.c data.h: data.foo\nfoo data.foo\n\nWhat the above rule says is that 'data.c' and 'data.h' each depend on\n'data.foo', and can each be built by running 'foo data.foo'. In other\nwords it is equivalent to:\n\n# We do not want this.\ndata.c: data.foo\nfoo data.foo\ndata.h: data.foo\nfoo data.foo\n\nwhich means that 'foo' can be run twice. Usually it will not be run\ntwice, because 'make' implementations are smart enough to check for the\nexistence of the second file after the first one has been built; they\nwill therefore detect that it already exists. However there are a few\nsituations where it can run twice anyway:\n\n* The most worrying case is when running a parallel 'make'. If\n'data.c' and 'data.h' are built in parallel, two 'foo data.foo'\ncommands will run concurrently. This is harmful.\n* Another case is when the dependency (here 'data.foo') is (or\ndepends upon) a phony target.\n\nA solution that works with parallel 'make' but not with phony\ndependencies is the following:\n\ndata.c data.h: data.foo\nfoo data.foo\ndata.h: data.c\n\nThe above rules are equivalent to\n\ndata.c: data.foo\nfoo data.foo\ndata.h: data.foo data.c\nfoo data.foo\n\ntherefore a parallel 'make' will have to serialize the builds of\n'data.c' and 'data.h', and will detect that the second is no longer\nneeded once the first is over.\n\nUsing this pattern is probably enough for most cases. However it\ndoes not scale easily to more output files (in this scheme all output\nfiles must be totally ordered by the dependency relation), so we will\nexplore a more complicated solution.\n\nAnother idea is to write the following:\n\n# There is still a problem with this one.\ndata.c: data.foo\nfoo data.foo\ndata.h: data.c\n\nThe idea is that 'foo data.foo' is run only when 'data.c' needs to be\nupdated, but we further state that 'data.h' depends upon 'data.c'. That\nway, if 'data.h' is required and 'data.foo' is out of date, the\ndependency on 'data.c' will trigger the build.\n\nThis is almost perfect, but suppose we have built 'data.h' and\n'data.c', and then we erase 'data.h'. Then, running 'make data.h' will\nnot rebuild 'data.h'. The above rules just state that 'data.c' must be\nup-to-date with respect to 'data.foo', and this is already the case.\n\nWhat we need is a rule that forces a rebuild when 'data.h' is\nmissing. Here it is:\n\ndata.c: data.foo\nfoo data.foo\ndata.h: data.c\n## Recover from the removal of $@\n@test -f $@ || rm -f data.c\n@test -f $@ || $(MAKE) $(AMMAKEFLAGS) data.c\n\nIt is tempting to use a single test as follows:\n\ndata.h: data.c\n## Recover from the removal of $@\n@if test -f $@; then :; else \\\nrm -f data.c; \\\n$(MAKE) $(AMMAKEFLAGS) data.c; \\\nfi\n\nbut that would break 'make -n': at least GNU 'make' and Solaris 'make'\nexecute recipes containing the '$(MAKE)' string even when they are\nrunning in dry mode. So if we didn't break the recipe above in two\ninvocations, the file 'data.c' would be removed even upon 'make -n'.\nNot nice.\n\nThe above scheme can be extended to handle more outputs and more\ninputs. One of the outputs is selected to serve as a witness to the\nsuccessful completion of the command, it depends upon all inputs, and\nall other outputs depend upon it. For instance, if 'foo' should\nadditionally read 'data.bar' and also produce 'data.w' and 'data.x', we\nwould write:\n\ndata.c: data.foo data.bar\nfoo data.foo data.bar\ndata.h data.w data.x: data.c\n## Recover from the removal of $@\n@test -f $@ || rm -f data.c\n@test -f $@ || $(MAKE) $(AMMAKEFLAGS) data.c\n\nHowever there are now three minor problems in this setup. One is\nrelated to the timestamp ordering of 'data.h', 'data.w', 'data.x', and\n'data.c'. Another one is a race condition if a parallel 'make' attempts\nto run multiple instances of the recover block at once. Finally, the\nrecursive rule breaks 'make -n' when run with GNU 'make' (as well as\nsome other 'make' implementations), as it may remove 'data.h' even when\nit should not (*note How the 'MAKE' Variable Works: (make)MAKE\nVariable.).\n\nLet us deal with the first problem. 'foo' outputs four files, but we\ndo not know in which order these files are created. Suppose that\n'data.h' is created before 'data.c'. Then we have a weird situation.\nThe next time 'make' is run, 'data.h' will appear older than 'data.c',\nthe second rule will be triggered, a shell will be started to execute\nthe 'if...fi' command, but it will just execute the 'then' branch, that\nis: nothing. In other words, because the witness we selected is not the\nfirst file created by 'foo', 'make' will start a shell to do nothing\neach time it is run.\n\nA simple riposte is to fix the timestamps when this happens.\n\ndata.c: data.foo data.bar\nfoo data.foo data.bar\ndata.h data.w data.x: data.c\n@test ! -f $@ || touch $@\n## Recover from the removal of $@\n@test -f $@ || rm -f data.c\n@test -f $@ || $(MAKE) $(AMMAKEFLAGS) data.c\n\nAnother solution is to use a different and dedicated file as witness,\nrather than using any of 'foo''s outputs.\n\ndata.stamp: data.foo data.bar\n@rm -f data.tmp\n@touch data.tmp\nfoo data.foo data.bar\n@mv -f data.tmp $@\ndata.c data.h data.w data.x: data.stamp\n## Recover from the removal of $@\n@test -f $@ || rm -f data.stamp\n@test -f $@ || $(MAKE) $(AMMAKEFLAGS) data.stamp\n\n'data.tmp' is created before 'foo' is run, so it has a timestamp\nolder than output files output by 'foo'. It is then renamed to\n'data.stamp' after 'foo' has run, because we do not want to update\n'data.stamp' if 'foo' fails.\n\nThis solution still suffers from the second problem: the race\ncondition in the recover rule. If, after a successful build, a user\nerases 'data.c' and 'data.h', and runs 'make -j', then 'make' may start\nboth recover rules in parallel. If the two instances of the rule\nexecute '$(MAKE) $(AMMAKEFLAGS) data.stamp' concurrently the build is\nlikely to fail (for instance, the two rules will create 'data.tmp', but\nonly one can rename it).\n\nAdmittedly, such a weird situation does not arise during ordinary\nbuilds. It occurs only when the build tree is mutilated. Here 'data.c'\nand 'data.h' have been explicitly removed without also removing\n'data.stamp' and the other output files. 'make clean; make' will always\nrecover from these situations even with parallel makes, so you may\ndecide that the recover rule is solely to help non-parallel make users\nand leave things as-is. Fixing this requires some locking mechanism to\nensure only one instance of the recover rule rebuilds 'data.stamp'. One\ncould imagine something along the following lines.\n\ndata.c data.h data.w data.x: data.stamp\n## Recover from the removal of $@\n@if test -f $@; then :; else \\\ntrap 'rm -rf data.lock data.stamp' 1 2 13 15; \\\n## mkdir is a portable test-and-set\nif mkdir data.lock 2>/dev/null; then \\\n## This code is being executed by the first process.\nrm -f data.stamp; \\\n$(MAKE) $(AMMAKEFLAGS) data.stamp; \\\nresult=$$?; rm -rf data.lock; exit $$result; \\\nelse \\\n## This code is being executed by the follower processes.\n## Wait until the first process is done.\nwhile test -d data.lock; do sleep 1; done; \\\n## Succeed if and only if the first process succeeded.\ntest -f data.stamp; \\\nfi; \\\nfi\n\nUsing a dedicated witness, like 'data.stamp', is very handy when the\nlist of output files is not known beforehand. As an illustration,\nconsider the following rules to compile many '*.el' files into '*.elc'\nfiles in a single command. It does not matter how 'ELFILES' is defined\n(as long as it is not empty: empty targets are not accepted by POSIX).\n\nELFILES = one.el two.el three.el ...\nELCFILES = $(ELFILES:=c)\n\nelc-stamp: $(ELFILES)\n@rm -f elc-temp\n@touch elc-temp\n$(elispcomp) $(ELFILES)\n@mv -f elc-temp $@\n\n$(ELCFILES): elc-stamp\n@if test -f $@; then :; else \\\n## Recover from the removal of $@\ntrap 'rm -rf elc-lock elc-stamp' 1 2 13 15; \\\nif mkdir elc-lock 2>/dev/null; then \\\n## This code is being executed by the first process.\nrm -f elc-stamp; \\\n$(MAKE) $(AMMAKEFLAGS) elc-stamp; \\\nrmdir elc-lock; \\\nelse \\\n## This code is being executed by the follower processes.\n## Wait until the first process is done.\nwhile test -d elc-lock; do sleep 1; done; \\\n## Succeed if and only if the first process succeeded.\ntest -f elc-stamp; exit $$?; \\\nfi; \\\nfi\n\nThese solutions all still suffer from the third problem, namely that\nthey break the promise that 'make -n' should not cause any actual\nchanges to the tree. For those solutions that do not create lock files,\nit is possible to split the recover rules into two separate recipe\ncommands, one of which does all work but the recursion, and the other\ninvokes the recursive '$(MAKE)'. The solutions involving locking could\nact upon the contents of the 'MAKEFLAGS' variable, but parsing that\nportably is not easy (*note (autoconf)The Make Macro MAKEFLAGS::). Here\nis an example:\n\nELFILES = one.el two.el three.el ...\nELCFILES = $(ELFILES:=c)\n\nelc-stamp: $(ELFILES)\n@rm -f elc-temp\n@touch elc-temp\n$(elispcomp) $(ELFILES)\n@mv -f elc-temp $@\n\n$(ELCFILES): elc-stamp\n## Recover from the removal of $@\n@dry=; for f in x $$MAKEFLAGS; do \\\ncase $$f in \\\n*=*|--*);; \\\n*n*) dry=:;; \\\nesac; \\\ndone; \\\nif test -f $@; then :; else \\\n$$dry trap 'rm -rf elc-lock elc-stamp' 1 2 13 15; \\\nif $$dry mkdir elc-lock 2>/dev/null; then \\\n## This code is being executed by the first process.\n$$dry rm -f elc-stamp; \\\n$(MAKE) $(AMMAKEFLAGS) elc-stamp; \\\n$$dry rmdir elc-lock; \\\nelse \\\n## This code is being executed by the follower processes.\n## Wait until the first process is done.\nwhile test -d elc-lock && test -z \"$$dry\"; do \\\nsleep 1; \\\ndone; \\\n## Succeed if and only if the first process succeeded.\n$$dry test -f elc-stamp; exit $$?; \\\nfi; \\\nfi\n\nFor completeness it should be noted that GNU 'make' is able to\nexpress rules with multiple output files using pattern rules (*note\nPattern Rule Examples: (make)Pattern Examples.). We do not discuss\npattern rules here because they are not portable, but they can be\nconvenient in packages that assume GNU 'make'.\n\nFile: automake-1.16.info, Node: Hard-Coded Install Paths, Next: Debugging Make Rules, Prev: Multiple Outputs, Up: FAQ\n" }, { "name": "26.10 Installing to Hard-Coded Locations", "content": "My package needs to install some configuration file. I tried to use\nthe following rule, but 'make distcheck' fails. Why?\n\n# Do not do this.\ninstall-data-local:\n$(INSTALLDATA) $(srcdir)/afile $(DESTDIR)/etc/afile\n\nMy package needs to populate the installation directory of another\npackage at install-time. I can easily compute that installation\ndirectory in 'configure', but if I install files therein,\n'make distcheck' fails. How else should I do it?\n\nThese two setups share their symptoms: 'make distcheck' fails because\nthey are installing files to hard-coded paths. In the latter case the\npath is not hard-coded in the package, but we can consider it to be\nhard-coded in the system (or in whichever tool that supplies the path).\nAs long as the path does not use any of the standard directory variables\n('$(prefix)', '$(bindir)', '$(datadir)', etc.), the effect will be the\nsame: user-installations are impossible.\n\nAs a (non-root) user who wants to install a package, you usually have\nno right to install anything in '/usr' or '/usr/local'. So you do\nsomething like './configure --prefix ~/usr' to install a package in your\nown '~/usr' tree.\n\nIf a package attempts to install something to some hard-coded path\n(e.g., '/etc/afile'), regardless of this '--prefix' setting, then the\ninstallation will fail. 'make distcheck' performs such a '--prefix'\ninstallation, hence it will fail too.\n\nNow, there are some easy solutions.\n\nThe above 'install-data-local' example for installing '/etc/afile'\nwould be better replaced by\n\nsysconfDATA = afile\n\nBy default 'sysconfdir' will be '$(prefix)/etc', because this is what\nthe GNU Standards require. When such a package is installed on an FHS\ncompliant system, the installer will have to set '--sysconfdir=/etc'.\nAs the maintainer of the package you should not be concerned by such\nsite policies: use the appropriate standard directory variable to\ninstall your files so that the installer can easily redefine these\nvariables to match their site conventions.\n\nInstalling files that should be used by another package is slightly\nmore involved. Let's take an example and assume you want to install a\nshared library that is a Python extension module. If you ask Python\nwhere to install the library, it will answer something like this:\n\n% python -c 'from distutils import sysconfig;\nprint sysconfig.getpythonlib(1,0)'\n/usr/lib/python2.5/site-packages\n\nIf you indeed use this absolute path to install your shared library,\nnon-root users will not be able to install the package; hence distcheck\nfails.\n\nLet's do better. The 'sysconfig.getpythonlib()' function accepts a\nthird argument that will replace Python's installation prefix.\n\n% python -c 'from distutils import sysconfig;\nprint sysconfig.getpythonlib(1,0,\"${execprefix}\")'\n${execprefix}/lib/python2.5/site-packages\n\nYou can also use this new path. If you do\n* root users can install your package with the same '--prefix' as\nPython (you get the behavior of the previous attempt)\n\n* non-root users can install your package too; they will have the\nextension module in a place that is not searched by Python but they\ncan work around this using environment variables (and if you\ninstalled scripts that use this shared library, it's easy to tell\nPython where to look in the beginning of your script, so the script\nworks in both cases).\n\nThe 'AMPATHPYTHON' macro uses similar commands to define\n'$(pythondir)' and '$(pyexecdir)' (*note Python::).\n\nOf course not all tools are as advanced as Python regarding that\nsubstitution of PREFIX. So another strategy is to figure out the part\nof the installation directory that must be preserved. For instance,\nhere is how 'AMPATHLISPDIR' (*note Emacs Lisp::) computes\n'$(lispdir)':\n\n$EMACS -batch -Q -eval '(while load-path\n(princ (concat (car load-path) \"\\n\"))\n(setq load-path (cdr load-path)))' >conftest.out\nlispdir=`sed -n\n-e 's,/$,,'\n-e '/.*\\/lib\\/x*emacs\\/site-lisp$/{\ns,.*/lib/\\(x*emacs/site-lisp\\)$,${libdir}/\\1,;p;q;\n}'\n-e '/.*\\/share\\/x*emacs\\/site-lisp$/{\ns,.*/share/\\(x*emacs/site-lisp\\),${datarootdir}/\\1,;p;q;\n}'\nconftest.out`\n\nThat is, it just picks the first directory that looks like\n'*/lib/*emacs/site-lisp' or '*/share/*emacs/site-lisp' in the search\npath of emacs, and then substitutes '${libdir}' or '${datadir}'\nappropriately.\n\nThe emacs case looks complicated because it processes a list and\nexpects two possible layouts; otherwise it's easy, and the benefits for\nnon-root users are worth the extra 'sed' invocation.\n\nFile: automake-1.16.info, Node: Debugging Make Rules, Next: Reporting Bugs, Prev: Hard-Coded Install Paths, Up: FAQ\n" }, { "name": "26.11 Debugging Make Rules", "content": "The rules and dependency trees generated by 'automake' can get rather\ncomplex, and leave the developer head-scratching when things don't work\nas expected. Besides the debug options provided by the 'make' command\n(*note (make)Options Summary::), here's a couple of further hints for\ndebugging makefiles generated by 'automake' effectively:\n\n* If less verbose output has been enabled in the package with the use\nof silent rules (*note Automake Silent Rules::), you can use 'make\nV=1' to see the commands being executed.\n\n* 'make -n' can help show what would be done without actually doing\nit. However, this still executes commands prefixed with '+',\nand, when using GNU 'make', commands that contain the strings\n'$(MAKE)' or '${MAKE}' (*note (make)Instead of Execution::).\nTypically, this is helpful to show what recursive rules would do,\nbut it means that, in your own rules, you should not mix such\nrecursion with actions that change any files.(1) Furthermore, note\nthat GNU 'make' will update prerequisites for the 'Makefile' file\nitself even with '-n' (*note (make)Remaking Makefiles::).\n\n* 'make SHELL=\"/bin/bash -vx\"' can help debug complex rules. *Note\n(autoconf)The Make Macro SHELL::, for some portability quirks\nassociated with this construct.\n\n* 'echo 'print: ; @echo \"$(VAR)\"' | make -f Makefile -f - print' can\nbe handy to examine the expanded value of variables. You may need\nto use a target other than 'print' if that is already used or a\nfile with that name exists.\n\n* provides a modified GNU\n'make' command called 'remake' that copes with complex GNU\n'make'-specific Makefiles and allows tracing execution, examining\nvariables, and calling rules interactively, much like a debugger.\n\n---------- Footnotes ----------\n\n(1) Automake's 'dist' and 'distcheck' rules had a bug in this regard\nin that they created directories even with '-n', but this has been fixed\nin Automake 1.11.\n\nFile: automake-1.16.info, Node: Reporting Bugs, Prev: Debugging Make Rules, Up: FAQ\n" }, { "name": "26.12 Reporting Bugs", "content": "Most nontrivial software has bugs. Automake is no exception. We cannot\npromise we can or will fix a bug, and we might not even agree that it is\na bug, but we want to hear about problems you encounter. Often we agree\nthey are bugs and want to fix them.\n\nSo, to make it possible for us to fix a bug, please report it. If\nyou can, though, it is helpful if you check if it is already known. You\ncan look at the GNU Bug Tracker (https://debbugs.gnu.org/) and the\nbug-automake mailing list archives\n(https://lists.gnu.org/archive/html/bug-automake/) for previous bug\nreports. (We previously used a Gnats database for bug tracking, but it\nis no longer online.)\n\nIf the bug is not already known, it should be reported. To report\nbugs in a way that is useful and efficient, please read How to Report\nBugs Effectively\n(https://www.chiark.greenend.org.uk/~sgtatham/bugs.html) and How to Ask\nQuestions the Smart Way\n(http://catb.org/~esr/faqs/smart-questions.html). Good bug reports save\ntime for everyone.\n\nFor a bug report, a feature request or other suggestions, please send\nemail to . This will then open a new bug in the\nbug tracker (https://debbugs.gnu.org/automake). Be sure to include the\nversions of Autoconf and Automake that you use and the kind of system\nyou're on. Ideally, post a minimal 'Makefile.am' and 'configure.ac'\nthat reproduces the problem you encounter. If you have encountered test\nsuite failures, please attach the 'test-suite.log' file.\n\nFile: automake-1.16.info, Node: Copying This Manual, Next: Indices, Prev: FAQ, Up: Top\n" } ] }, "Appendix A Copying This Manual": { "content": "* Menu:\n\n* GNU Free Documentation License:: License for copying this manual\n\nFile: automake-1.16.info, Node: GNU Free Documentation License, Up: Copying This Manual\n", "subsections": [ { "name": "A.1 GNU Free Documentation License", "content": "Version 1.3, 3 November 2008\n\nCopyright (C) 2000-2021 Free Software Foundation, Inc.\n\n\nEveryone is permitted to copy and distribute verbatim copies\nof this license document, but changing it is not allowed.\n\n0. PREAMBLE\n\nThe purpose of this License is to make a manual, textbook, or other\nfunctional and useful document \"free\" in the sense of freedom: to\nassure everyone the effective freedom to copy and redistribute it,\nwith or without modifying it, either commercially or\nnoncommercially. Secondarily, this License preserves for the\nauthor and publisher a way to get credit for their work, while not\nbeing considered responsible for modifications made by others.\n\nThis License is a kind of \"copyleft\", which means that derivative\nworks of the document must themselves be free in the same sense.\nIt complements the GNU General Public License, which is a copyleft\nlicense designed for free software.\n\nWe have designed this License in order to use it for manuals for\nfree software, because free software needs free documentation: a\nfree program should come with manuals providing the same freedoms\nthat the software does. But this License is not limited to\nsoftware manuals; it can be used for any textual work, regardless\nof subject matter or whether it is published as a printed book. We\nrecommend this License principally for works whose purpose is\ninstruction or reference.\n\n1. APPLICABILITY AND DEFINITIONS\n\nThis License applies to any manual or other work, in any medium,\nthat contains a notice placed by the copyright holder saying it can\nbe distributed under the terms of this License. Such a notice\ngrants a world-wide, royalty-free license, unlimited in duration,\nto use that work under the conditions stated herein. The\n\"Document\", below, refers to any such manual or work. Any member\nof the public is a licensee, and is addressed as \"you\". You accept\nthe license if you copy, modify or distribute the work in a way\nrequiring permission under copyright law.\n\nA \"Modified Version\" of the Document means any work containing the\nDocument or a portion of it, either copied verbatim, or with\nmodifications and/or translated into another language.\n\nA \"Secondary Section\" is a named appendix or a front-matter section\nof the Document that deals exclusively with the relationship of the\npublishers or authors of the Document to the Document's overall\nsubject (or to related matters) and contains nothing that could\nfall directly within that overall subject. (Thus, if the Document\nis in part a textbook of mathematics, a Secondary Section may not\nexplain any mathematics.) The relationship could be a matter of\nhistorical connection with the subject or with related matters, or\nof legal, commercial, philosophical, ethical or political position\nregarding them.\n\nThe \"Invariant Sections\" are certain Secondary Sections whose\ntitles are designated, as being those of Invariant Sections, in the\nnotice that says that the Document is released under this License.\nIf a section does not fit the above definition of Secondary then it\nis not allowed to be designated as Invariant. The Document may\ncontain zero Invariant Sections. If the Document does not identify\nany Invariant Sections then there are none.\n\nThe \"Cover Texts\" are certain short passages of text that are\nlisted, as Front-Cover Texts or Back-Cover Texts, in the notice\nthat says that the Document is released under this License. A\nFront-Cover Text may be at most 5 words, and a Back-Cover Text may\nbe at most 25 words.\n\nA \"Transparent\" copy of the Document means a machine-readable copy,\nrepresented in a format whose specification is available to the\ngeneral public, that is suitable for revising the document\nstraightforwardly with generic text editors or (for images composed\nof pixels) generic paint programs or (for drawings) some widely\navailable drawing editor, and that is suitable for input to text\nformatters or for automatic translation to a variety of formats\nsuitable for input to text formatters. A copy made in an otherwise\nTransparent file format whose markup, or absence of markup, has\nbeen arranged to thwart or discourage subsequent modification by\nreaders is not Transparent. An image format is not Transparent if\nused for any substantial amount of text. A copy that is not\n\"Transparent\" is called \"Opaque\".\n\nExamples of suitable formats for Transparent copies include plain\nASCII without markup, Texinfo input format, LaTeX input format,\nSGML or XML using a publicly available DTD, and standard-conforming\nsimple HTML, PostScript or PDF designed for human modification.\nExamples of transparent image formats include PNG, XCF and JPG.\nOpaque formats include proprietary formats that can be read and\nedited only by proprietary word processors, SGML or XML for which\nthe DTD and/or processing tools are not generally available, and\nthe machine-generated HTML, PostScript or PDF produced by some word\nprocessors for output purposes only.\n\nThe \"Title Page\" means, for a printed book, the title page itself,\nplus such following pages as are needed to hold, legibly, the\nmaterial this License requires to appear in the title page. For\nworks in formats which do not have any title page as such, \"Title\nPage\" means the text near the most prominent appearance of the\nwork's title, preceding the beginning of the body of the text.\n\nThe \"publisher\" means any person or entity that distributes copies\nof the Document to the public.\n\nA section \"Entitled XYZ\" means a named subunit of the Document\nwhose title either is precisely XYZ or contains XYZ in parentheses\nfollowing text that translates XYZ in another language. (Here XYZ\nstands for a specific section name mentioned below, such as\n\"Acknowledgements\", \"Dedications\", \"Endorsements\", or \"History\".)\nTo \"Preserve the Title\" of such a section when you modify the\nDocument means that it remains a section \"Entitled XYZ\" according\nto this definition.\n\nThe Document may include Warranty Disclaimers next to the notice\nwhich states that this License applies to the Document. These\nWarranty Disclaimers are considered to be included by reference in\nthis License, but only as regards disclaiming warranties: any other\nimplication that these Warranty Disclaimers may have is void and\nhas no effect on the meaning of this License.\n\n2. VERBATIM COPYING\n\nYou may copy and distribute the Document in any medium, either\ncommercially or noncommercially, provided that this License, the\ncopyright notices, and the license notice saying this License\napplies to the Document are reproduced in all copies, and that you\nadd no other conditions whatsoever to those of this License. You\nmay not use technical measures to obstruct or control the reading\nor further copying of the copies you make or distribute. However,\nyou may accept compensation in exchange for copies. If you\ndistribute a large enough number of copies you must also follow the\nconditions in section 3.\n\nYou may also lend copies, under the same conditions stated above,\nand you may publicly display copies.\n\n3. COPYING IN QUANTITY\n\nIf you publish printed copies (or copies in media that commonly\nhave printed covers) of the Document, numbering more than 100, and\nthe Document's license notice requires Cover Texts, you must\nenclose the copies in covers that carry, clearly and legibly, all\nthese Cover Texts: Front-Cover Texts on the front cover, and\nBack-Cover Texts on the back cover. Both covers must also clearly\nand legibly identify you as the publisher of these copies. The\nfront cover must present the full title with all words of the title\nequally prominent and visible. You may add other material on the\ncovers in addition. Copying with changes limited to the covers, as\nlong as they preserve the title of the Document and satisfy these\nconditions, can be treated as verbatim copying in other respects.\n\nIf the required texts for either cover are too voluminous to fit\nlegibly, you should put the first ones listed (as many as fit\nreasonably) on the actual cover, and continue the rest onto\nadjacent pages.\n\nIf you publish or distribute Opaque copies of the Document\nnumbering more than 100, you must either include a machine-readable\nTransparent copy along with each Opaque copy, or state in or with\neach Opaque copy a computer-network location from which the general\nnetwork-using public has access to download using public-standard\nnetwork protocols a complete Transparent copy of the Document, free\nof added material. If you use the latter option, you must take\nreasonably prudent steps, when you begin distribution of Opaque\ncopies in quantity, to ensure that this Transparent copy will\nremain thus accessible at the stated location until at least one\nyear after the last time you distribute an Opaque copy (directly or\nthrough your agents or retailers) of that edition to the public.\n\nIt is requested, but not required, that you contact the authors of\nthe Document well before redistributing any large number of copies,\nto give them a chance to provide you with an updated version of the\nDocument.\n\n4. MODIFICATIONS\n\nYou may copy and distribute a Modified Version of the Document\nunder the conditions of sections 2 and 3 above, provided that you\nrelease the Modified Version under precisely this License, with the\nModified Version filling the role of the Document, thus licensing\ndistribution and modification of the Modified Version to whoever\npossesses a copy of it. In addition, you must do these things in\nthe Modified Version:\n\nA. Use in the Title Page (and on the covers, if any) a title\ndistinct from that of the Document, and from those of previous\nversions (which should, if there were any, be listed in the\nHistory section of the Document). You may use the same title\nas a previous version if the original publisher of that\nversion gives permission.\n\nB. List on the Title Page, as authors, one or more persons or\nentities responsible for authorship of the modifications in\nthe Modified Version, together with at least five of the\nprincipal authors of the Document (all of its principal\nauthors, if it has fewer than five), unless they release you\nfrom this requirement.\n\nC. State on the Title page the name of the publisher of the\nModified Version, as the publisher.\n\nD. Preserve all the copyright notices of the Document.\n\nE. Add an appropriate copyright notice for your modifications\nadjacent to the other copyright notices.\n\nF. Include, immediately after the copyright notices, a license\nnotice giving the public permission to use the Modified\nVersion under the terms of this License, in the form shown in\nthe Addendum below.\n\nG. Preserve in that license notice the full lists of Invariant\nSections and required Cover Texts given in the Document's\nlicense notice.\n\nH. Include an unaltered copy of this License.\n\nI. Preserve the section Entitled \"History\", Preserve its Title,\nand add to it an item stating at least the title, year, new\nauthors, and publisher of the Modified Version as given on the\nTitle Page. If there is no section Entitled \"History\" in the\nDocument, create one stating the title, year, authors, and\npublisher of the Document as given on its Title Page, then add\nan item describing the Modified Version as stated in the\nprevious sentence.\n\nJ. Preserve the network location, if any, given in the Document\nfor public access to a Transparent copy of the Document, and\nlikewise the network locations given in the Document for\nprevious versions it was based on. These may be placed in the\n\"History\" section. You may omit a network location for a work\nthat was published at least four years before the Document\nitself, or if the original publisher of the version it refers\nto gives permission.\n\nK. For any section Entitled \"Acknowledgements\" or \"Dedications\",\nPreserve the Title of the section, and preserve in the section\nall the substance and tone of each of the contributor\nacknowledgements and/or dedications given therein.\n\nL. Preserve all the Invariant Sections of the Document, unaltered\nin their text and in their titles. Section numbers or the\nequivalent are not considered part of the section titles.\n\nM. Delete any section Entitled \"Endorsements\". Such a section\nmay not be included in the Modified Version.\n\nN. Do not retitle any existing section to be Entitled\n\"Endorsements\" or to conflict in title with any Invariant\nSection.\n\nO. Preserve any Warranty Disclaimers.\n\nIf the Modified Version includes new front-matter sections or\nappendices that qualify as Secondary Sections and contain no\nmaterial copied from the Document, you may at your option designate\nsome or all of these sections as invariant. To do this, add their\ntitles to the list of Invariant Sections in the Modified Version's\nlicense notice. These titles must be distinct from any other\nsection titles.\n\nYou may add a section Entitled \"Endorsements\", provided it contains\nnothing but endorsements of your Modified Version by various\nparties--for example, statements of peer review or that the text has\nbeen approved by an organization as the authoritative definition of\na standard.\n\nYou may add a passage of up to five words as a Front-Cover Text,\nand a passage of up to 25 words as a Back-Cover Text, to the end of\nthe list of Cover Texts in the Modified Version. Only one passage\nof Front-Cover Text and one of Back-Cover Text may be added by (or\nthrough arrangements made by) any one entity. If the Document\nalready includes a cover text for the same cover, previously added\nby you or by arrangement made by the same entity you are acting on\nbehalf of, you may not add another; but you may replace the old\none, on explicit permission from the previous publisher that added\nthe old one.\n\nThe author(s) and publisher(s) of the Document do not by this\nLicense give permission to use their names for publicity for or to\nassert or imply endorsement of any Modified Version.\n\n5. COMBINING DOCUMENTS\n\nYou may combine the Document with other documents released under\nthis License, under the terms defined in section 4 above for\nmodified versions, provided that you include in the combination all\nof the Invariant Sections of all of the original documents,\nunmodified, and list them all as Invariant Sections of your\ncombined work in its license notice, and that you preserve all\ntheir Warranty Disclaimers.\n\nThe combined work need only contain one copy of this License, and\nmultiple identical Invariant Sections may be replaced with a single\ncopy. If there are multiple Invariant Sections with the same name\nbut different contents, make the title of each such section unique\nby adding at the end of it, in parentheses, the name of the\noriginal author or publisher of that section if known, or else a\nunique number. Make the same adjustment to the section titles in\nthe list of Invariant Sections in the license notice of the\ncombined work.\n\nIn the combination, you must combine any sections Entitled\n\"History\" in the various original documents, forming one section\nEntitled \"History\"; likewise combine any sections Entitled\n\"Acknowledgements\", and any sections Entitled \"Dedications\". You\nmust delete all sections Entitled \"Endorsements.\"\n\n6. COLLECTIONS OF DOCUMENTS\n\nYou may make a collection consisting of the Document and other\ndocuments released under this License, and replace the individual\ncopies of this License in the various documents with a single copy\nthat is included in the collection, provided that you follow the\nrules of this License for verbatim copying of each of the documents\nin all other respects.\n\nYou may extract a single document from such a collection, and\ndistribute it individually under this License, provided you insert\na copy of this License into the extracted document, and follow this\nLicense in all other respects regarding verbatim copying of that\ndocument.\n\n7. AGGREGATION WITH INDEPENDENT WORKS\n\nA compilation of the Document or its derivatives with other\nseparate and independent documents or works, in or on a volume of a\nstorage or distribution medium, is called an \"aggregate\" if the\ncopyright resulting from the compilation is not used to limit the\nlegal rights of the compilation's users beyond what the individual\nworks permit. When the Document is included in an aggregate, this\nLicense does not apply to the other works in the aggregate which\nare not themselves derivative works of the Document.\n\nIf the Cover Text requirement of section 3 is applicable to these\ncopies of the Document, then if the Document is less than one half\nof the entire aggregate, the Document's Cover Texts may be placed\non covers that bracket the Document within the aggregate, or the\nelectronic equivalent of covers if the Document is in electronic\nform. Otherwise they must appear on printed covers that bracket\nthe whole aggregate.\n\n8. TRANSLATION\n\nTranslation is considered a kind of modification, so you may\ndistribute translations of the Document under the terms of section\n4. Replacing Invariant Sections with translations requires special\npermission from their copyright holders, but you may include\ntranslations of some or all Invariant Sections in addition to the\noriginal versions of these Invariant Sections. You may include a\ntranslation of this License, and all the license notices in the\nDocument, and any Warranty Disclaimers, provided that you also\ninclude the original English version of this License and the\noriginal versions of those notices and disclaimers. In case of a\ndisagreement between the translation and the original version of\nthis License or a notice or disclaimer, the original version will\nprevail.\n\nIf a section in the Document is Entitled \"Acknowledgements\",\n\"Dedications\", or \"History\", the requirement (section 4) to\nPreserve its Title (section 1) will typically require changing the\nactual title.\n\n9. TERMINATION\n\nYou may not copy, modify, sublicense, or distribute the Document\nexcept as expressly provided under this License. Any attempt\notherwise to copy, modify, sublicense, or distribute it is void,\nand will automatically terminate your rights under this License.\n\nHowever, if you cease all violation of this License, then your\nlicense from a particular copyright holder is reinstated (a)\nprovisionally, unless and until the copyright holder explicitly and\nfinally terminates your license, and (b) permanently, if the\ncopyright holder fails to notify you of the violation by some\nreasonable means prior to 60 days after the cessation.\n\nMoreover, your license from a particular copyright holder is\nreinstated permanently if the copyright holder notifies you of the\nviolation by some reasonable means, this is the first time you have\nreceived notice of violation of this License (for any work) from\nthat copyright holder, and you cure the violation prior to 30 days\nafter your receipt of the notice.\n\nTermination of your rights under this section does not terminate\nthe licenses of parties who have received copies or rights from you\nunder this License. If your rights have been terminated and not\npermanently reinstated, receipt of a copy of some or all of the\nsame material does not give you any rights to use it.\n\n10. FUTURE REVISIONS OF THIS LICENSE\n\nThe Free Software Foundation may publish new, revised versions of\nthe GNU Free Documentation License from time to time. Such new\nversions will be similar in spirit to the present version, but may\ndiffer in detail to address new problems or concerns. See\n.\n\nEach version of the License is given a distinguishing version\nnumber. If the Document specifies that a particular numbered\nversion of this License \"or any later version\" applies to it, you\nhave the option of following the terms and conditions either of\nthat specified version or of any later version that has been\npublished (not as a draft) by the Free Software Foundation. If the\nDocument does not specify a version number of this License, you may\nchoose any version ever published (not as a draft) by the Free\nSoftware Foundation. If the Document specifies that a proxy can\ndecide which future versions of this License can be used, that\nproxy's public statement of acceptance of a version permanently\nauthorizes you to choose that version for the Document.\n\n11. RELICENSING\n\n\"Massive Multiauthor Collaboration Site\" (or \"MMC Site\") means any\nWorld Wide Web server that publishes copyrightable works and also\nprovides prominent facilities for anybody to edit those works. A\npublic wiki that anybody can edit is an example of such a server.\nA \"Massive Multiauthor Collaboration\" (or \"MMC\") contained in the\nsite means any set of copyrightable works thus published on the MMC\nsite.\n\n\"CC-BY-SA\" means the Creative Commons Attribution-Share Alike 3.0\nlicense published by Creative Commons Corporation, a not-for-profit\ncorporation with a principal place of business in San Francisco,\nCalifornia, as well as future copyleft versions of that license\npublished by that same organization.\n\n\"Incorporate\" means to publish or republish a Document, in whole or\nin part, as part of another Document.\n\nAn MMC is \"eligible for relicensing\" if it is licensed under this\nLicense, and if all works that were first published under this\nLicense somewhere other than this MMC, and subsequently\nincorporated in whole or in part into the MMC, (1) had no cover\ntexts or invariant sections, and (2) were thus incorporated prior\nto November 1, 2008.\n\nThe operator of an MMC Site may republish an MMC contained in the\nsite under CC-BY-SA on the same site at any time before August 1,\n2009, provided the MMC is eligible for relicensing.\n" }, { "name": "ADDENDUM: How to use this License for your documents", "content": "To use this License in a document you have written, include a copy of\nthe License in the document and put the following copyright and license\nnotices just after the title page:\n\nCopyright (C) YEAR YOUR NAME.\nPermission is granted to copy, distribute and/or modify this document\nunder the terms of the GNU Free Documentation License, Version 1.3\nor any later version published by the Free Software Foundation;\nwith no Invariant Sections, no Front-Cover Texts, and no Back-Cover\nTexts. A copy of the license is included in the section entitled ``GNU\nFree Documentation License''.\n\nIf you have Invariant Sections, Front-Cover Texts and Back-Cover\nTexts, replace the \"with...Texts.\" line with this:\n\nwith the Invariant Sections being LIST THEIR TITLES, with\nthe Front-Cover Texts being LIST, and with the Back-Cover Texts\nbeing LIST.\n\nIf you have Invariant Sections without Cover Texts, or some other\ncombination of the three, merge those two alternatives to suit the\nsituation.\n\nIf your document contains nontrivial examples of program code, we\nrecommend releasing these examples in parallel under your choice of free\nsoftware license, such as the GNU General Public License, to permit\ntheir use in free software.\n\nFile: automake-1.16.info, Node: Indices, Prev: Copying This Manual, Up: Top\n" } ] }, "Appendix B Indices": { "content": "* Menu:\n\n* Macro Index:: Index of Autoconf macros\n* Variable Index:: Index of Makefile variables\n* General Index:: General index\n\nFile: automake-1.16.info, Node: Macro Index, Next: Variable Index, Up: Indices\n", "subsections": [ { "name": "B.1 Macro Index", "content": "* Menu:\n\n* AMDEPENDENCIES: Private Macros. (line 12)\n* ACCANONICALBUILD: Optional. (line 11)\n* ACCANONICALHOST: Optional. (line 12)\n* ACCANONICALTARGET: Optional. (line 13)\n* ACCONFIGAUXDIR: Optional. (line 19)\n* ACCONFIGAUXDIR <1>: Subpackages. (line 6)\n* ACCONFIGFILES: Requirements. (line 15)\n* ACCONFIGFILES <1>: Basics of Distribution.\n(line 26)\n* ACCONFIGHEADERS: Optional. (line 50)\n* ACCONFIGLIBOBJDIR: Optional. (line 46)\n* ACCONFIGLIBOBJDIR <1>: LIBOBJS. (line 51)\n* ACCONFIGLINKS: Optional. (line 62)\n* ACCONFIGSUBDIRS: Subpackages. (line 6)\n* ACCONFIGSUBDIRS <1>: The dist Hook. (line 49)\n* ACDEFUN: Extending aclocal. (line 36)\n* ACF77LIBRARYLDFLAGS: Optional. (line 108)\n* ACFCSRCEXT: Optional. (line 114)\n* ACINIT: Public Macros. (line 15)\n* ACLIBOBJ: Optional. (line 72)\n* ACLIBOBJ <1>: LTLIBOBJS. (line 6)\n* ACLIBOBJ <2>: LIBOBJS. (line 11)\n* ACLIBSOURCE: Optional. (line 73)\n* ACLIBSOURCE <1>: LIBOBJS. (line 17)\n* ACLIBSOURCES: Optional. (line 74)\n* ACOUTPUT: Requirements. (line 15)\n* ACPREREQ: Extending aclocal. (line 36)\n* ACPROGCXX: Optional. (line 92)\n* ACPROGF77: Optional. (line 104)\n* ACPROGFC: Optional. (line 119)\n* ACPROGLEX: Public Macros. (line 94)\n* ACPROGLEX <1>: Optional. (line 134)\n* ACPROGLIBTOOL: Optional. (line 124)\n* ACPROGOBJC: Optional. (line 96)\n* ACPROGOBJCXX: Optional. (line 100)\n* ACPROGRANLIB: Optional. (line 88)\n* ACPROGYACC: Optional. (line 128)\n* ACREQUIREAUXFILE: Optional. (line 138)\n* ACSUBST: Optional. (line 146)\n* AMCONDITIONAL: Optional. (line 159)\n* AMCONDITIONAL <1>: Usage of Conditionals.\n(line 6)\n* AMCONDITIONAL <2>: Usage of Conditionals.\n(line 9)\n* AMCONDIF: Optional. (line 162)\n* AMCONDIF <1>: Usage of Conditionals.\n(line 66)\n* AMCONDIF <2>: Usage of Conditionals.\n(line 70)\n* AMDEPTRACK: Private Macros. (line 14)\n* AMGNUGETTEXT: Optional. (line 168)\n* AMGNUGETTEXTINTLSUBDIR: Optional. (line 174)\n* AMINITAUTOMAKE: Requirements. (line 6)\n* AMINITAUTOMAKE <1>: Public Macros. (line 7)\n* AMMAINTAINERMODE: Rebuilding. (line 9)\n* AMMAINTAINERMODE <1>: maintainer-mode. (line 38)\n* AMMAINTAINERMODE([DEFAULT-MODE]): Optional. (line 179)\n* AMMAKEINCLUDE: Private Macros. (line 20)\n* AMMISSINGPROG: Public Macros. (line 110)\n* AMOUTPUTDEPENDENCYCOMMANDS: Private Macros. (line 15)\n* AMPATHLISPDIR: Public Macros. (line 60)\n* AMPATHPYTHON: Python. (line 28)\n* AMPROGAR: Public Macros. (line 75)\n* AMPROGAS: Public Macros. (line 82)\n* AMPROGCCCO: Public Macros. (line 87)\n* AMPROGGCJ: Public Macros. (line 99)\n* AMPROGINSTALLSTRIP: Private Macros. (line 25)\n* AMPROGLEX: Public Macros. (line 94)\n* AMPROGMKDIRP: Obsolete Macros. (line 14)\n* AMPROGUPC: Public Macros. (line 104)\n* AMPROGVALAC: Vala Support. (line 20)\n* AMSANITYCHECK: Private Macros. (line 30)\n* AMSETDEPDIR: Private Macros. (line 13)\n* AMSILENTRULES: Public Macros. (line 118)\n* AMSUBSTNOTMAKE(VAR): Optional. (line 187)\n* AMWITHDMALLOC: Public Macros. (line 122)\n* m4include: Basics of Distribution.\n(line 30)\n* m4include <1>: Optional. (line 197)\n\nFile: automake-1.16.info, Node: Variable Index, Next: General Index, Prev: Macro Index, Up: Indices\n" }, { "name": "B.2 Variable Index", "content": "* Menu:\n\n* DATA: Data. (line 6)\n* HEADERS: Headers. (line 6)\n* LIBRARIES: A Library. (line 6)\n* LISP: Emacs Lisp. (line 6)\n* LOGCOMPILE: Parallel Test Harness.\n(line 51)\n* LOGCOMPILER: Parallel Test Harness.\n(line 51)\n* LOGDRIVER: Declaring Custom Test Drivers.\n(line 6)\n* LOGDRIVERFLAGS: Declaring Custom Test Drivers.\n(line 6)\n* LOGFLAGS: Parallel Test Harness.\n(line 51)\n* LTLIBRARIES: Libtool Libraries. (line 6)\n* MANS: Man Pages. (line 6)\n* PROGRAMS: Uniform. (line 11)\n* PROGRAMS <1>: Program Sources. (line 6)\n* PYTHON: Python. (line 6)\n* SCRIPTS: Scripts. (line 6)\n* SOURCES: Program Sources. (line 32)\n* SOURCES <1>: Program Sources. (line 33)\n* SOURCES <2>: Default SOURCES. (line 6)\n* TEXINFOS: Texinfo. (line 6)\n* TEXINFOS <1>: Texinfo. (line 65)\n* ACLOCALAUTOMAKEDIR: aclocal Options. (line 12)\n* ALLOCA: LTLIBOBJS. (line 6)\n* ALLOCA <1>: LIBOBJS. (line 6)\n* AMCCASFLAGS: Assembly Support. (line 10)\n* AMCFLAGS: Program Variables. (line 50)\n* AMCOLORTESTS: Scripts-based Testsuites.\n(line 85)\n* AMCPPFLAGS: Program Variables. (line 16)\n* AMCPPFLAGS <1>: Assembly Support. (line 10)\n* AMCXXFLAGS: C++ Support. (line 22)\n* AMDEFAULTSOURCEEXT: Default SOURCES. (line 6)\n* AMDEFAULTV: Automake Silent Rules.\n(line 120)\n* AMDEFAULTVERBOSITY: Automake Silent Rules.\n(line 120)\n* AMDISTCHECKCONFIGUREFLAGS: Checking the Distribution.\n(line 30)\n* AMETAGSFLAGS: Tags. (line 27)\n* AMEXTLOGDRIVERFLAGS: Declaring Custom Test Drivers.\n(line 6)\n* AMEXTLOGFLAGS: Parallel Test Harness.\n(line 51)\n* AMFCFLAGS: Fortran 9x Support. (line 22)\n* AMFFLAGS: Fortran 77 Support. (line 22)\n* AMGCJFLAGS: Java Support with gcj.\n(line 26)\n* AMINSTALLCHECKSTDOPTIONSEXEMPT: List of Automake options.\n(line 150)\n* AMJAVACFLAGS: Java. (line 44)\n* AMLDFLAGS: Linking. (line 10)\n* AMLDFLAGS <1>: Program Variables. (line 59)\n* AMLFLAGS: Yacc and Lex. (line 65)\n* AMLIBTOOLFLAGS: Libtool Flags. (line 6)\n* AMLOGDRIVERFLAGS: Declaring Custom Test Drivers.\n(line 6)\n* AMLOGFLAGS: Parallel Test Harness.\n(line 51)\n* AMMAKEFLAGS: Subdirectories. (line 29)\n* AMMAKEINFOFLAGS: Texinfo. (line 115)\n* AMMAKEINFOHTMLFLAGS: Texinfo. (line 116)\n* AMOBJCFLAGS: Objective C Support. (line 22)\n* AMOBJCXXFLAGS: Objective C++ Support.\n(line 22)\n* AMRFLAGS: Fortran 77 Support. (line 28)\n* AMRUNTESTFLAGS: DejaGnu Tests. (line 24)\n* AMTESTSUITESUMMARYHEADER: Scripts-based Testsuites.\n(line 69)\n* AMTESTSENVIRONMENT: Testsuite Environment Overrides.\n(line 6)\n* AMTESTSFDREDIRECT: Testsuite Environment Overrides.\n(line 14)\n* AMUPCFLAGS: Unified Parallel C Support.\n(line 21)\n* AMUPDATEINFODIR: Texinfo. (line 92)\n* AMV: Automake Silent Rules.\n(line 120)\n* AMVALAFLAGS: Vala Support. (line 44)\n* AMVat: Automake Silent Rules.\n(line 120)\n* AMVGEN: Automake Silent Rules.\n(line 120)\n* AMYFLAGS: Yacc and Lex. (line 37)\n* AR: Public Macros. (line 75)\n* AUTOCONF: automake Invocation. (line 28)\n* AUTOM4TE: aclocal Invocation. (line 44)\n* AUTOMAKEJOBS: automake Invocation. (line 195)\n* AUTOMAKELIBDIR: automake Invocation. (line 64)\n* AUTOMAKEOPTIONS: Public Macros. (line 10)\n* AUTOMAKEOPTIONS <1>: Dependencies. (line 34)\n* AUTOMAKEOPTIONS <2>: List of Automake options.\n(line 6)\n* binPROGRAMS: Program Sources. (line 6)\n* binSCRIPTS: Scripts. (line 18)\n* buildtriplet: Optional. (line 14)\n* BUILTSOURCES: Sources. (line 27)\n* BUILTSOURCES, and dist target: List of Automake options.\n(line 81)\n* BZIP2: The Types of Distributions.\n(line 17)\n* CC: Program Variables. (line 12)\n* CCAS: Public Macros. (line 82)\n* CCAS <1>: Assembly Support. (line 10)\n* CCASFLAGS: Public Macros. (line 82)\n* CCASFLAGS <1>: Assembly Support. (line 10)\n* CFLAGS: Program Variables. (line 12)\n* check: Uniform. (line 95)\n* checkLTLIBRARIES: Libtool Convenience Libraries.\n(line 6)\n* checkPROGRAMS: Program Sources. (line 6)\n* checkPROGRAMS <1>: Default SOURCES. (line 28)\n* checkPROGRAMS <2>: Scripts-based Testsuites.\n(line 111)\n* checkSCRIPTS: Scripts. (line 18)\n* CLASSPATHENV: Java. (line 53)\n* CLEANFILES: Clean. (line 13)\n* COMPILE: Program Variables. (line 55)\n* CONFIGUREDEPENDENCIES: Rebuilding. (line 12)\n* CONFIGSTATUSDEPENDENCIES: Rebuilding. (line 12)\n* CPPFLAGS: Program Variables. (line 12)\n* CPPFLAGS <1>: Assembly Support. (line 10)\n* CSCOPE: Tags. (line 57)\n* CSCOPEFLAGS: Tags. (line 57)\n* CSCOPEARGS: Tags. (line 57)\n* CTAGS: Tags. (line 43)\n* CTAGSFLAGS: Tags. (line 43)\n* CTAGSARGS: Tags. (line 43)\n* CXX: C++ Support. (line 16)\n* CXXCOMPILE: C++ Support. (line 25)\n* CXXFLAGS: C++ Support. (line 19)\n* CXXLINK: C++ Support. (line 29)\n* CXXLINK <1>: How the Linker is Chosen.\n(line 12)\n* DATA: Uniform. (line 101)\n* DATA <1>: Data. (line 7)\n* dataDATA: Data. (line 9)\n* DEFS: Program Variables. (line 12)\n* DEJATOOL: DejaGnu Tests. (line 19)\n* DESTDIR: DESTDIR. (line 6)\n* DESTDIR <1>: Staged Installs. (line 6)\n* DISABLEHARDERRORS: Scripts-based Testsuites.\n(line 32)\n* DISTCHECKCONFIGUREFLAGS: Checking the Distribution.\n(line 30)\n* distcleanchecklistfiles: Checking the Distribution.\n(line 92)\n* distcleanchecklistfiles <1>: Errors with distclean.\n(line 112)\n* DISTCLEANFILES: Clean. (line 13)\n* DISTCLEANFILES <1>: Checking the Distribution.\n(line 92)\n* distdir: The dist Hook. (line 34)\n* distdir <1>: Third-Party Makefiles.\n(line 25)\n* distuninstallchecklistfiles: Checking the Distribution.\n(line 128)\n* dist: Alternative. (line 28)\n* dist <1>: Fine-grained Distribution Control.\n(line 6)\n* distlispLISP: Emacs Lisp. (line 11)\n* distnoinstLISP: Emacs Lisp. (line 11)\n* DISTSUBDIRS: Subdirectories with AMCONDITIONAL.\n(line 25)\n* DISTSUBDIRS <1>: Basics of Distribution.\n(line 73)\n* DVIPS: Texinfo. (line 141)\n* EMACS: Public Macros. (line 60)\n* EMPTYAUTOMAKETARGETS: Third-Party Makefiles.\n(line 88)\n* ETAGS: Tags. (line 27)\n* ETAGSFLAGS: Tags. (line 27)\n* ETAGSARGS: Tags. (line 27)\n* EXPECT: DejaGnu Tests. (line 19)\n* EXTRADIST: Basics of Distribution.\n(line 60)\n* EXTRAmaudeDEPENDENCIES: Linking. (line 41)\n* EXTRAmaudeDEPENDENCIES <1>: Program and Library Variables.\n(line 129)\n* EXTRAmaudeSOURCES: Program and Library Variables.\n(line 60)\n* EXTRAPROGRAMS: Conditional Programs.\n(line 15)\n* EXTLOGCOMPILE: Parallel Test Harness.\n(line 51)\n* EXTLOGCOMPILER: Parallel Test Harness.\n(line 51)\n* EXTLOGDRIVER: Declaring Custom Test Drivers.\n(line 6)\n* EXTLOGDRIVERFLAGS: Declaring Custom Test Drivers.\n(line 6)\n* EXTLOGFLAGS: Parallel Test Harness.\n(line 51)\n* F77: Fortran 77 Support. (line 16)\n* F77COMPILE: Fortran 77 Support. (line 31)\n* F77LINK: How the Linker is Chosen.\n(line 13)\n* FC: Fortran 9x Support. (line 16)\n* FCCOMPILE: Fortran 9x Support. (line 25)\n* FCFLAGS: Fortran 9x Support. (line 19)\n* FCLINK: How the Linker is Chosen.\n(line 14)\n* FCLINK <1>: Fortran 9x Support. (line 29)\n* FFLAGS: Fortran 77 Support. (line 19)\n* FLIBS: Mixing Fortran 77 With C and C++.\n(line 21)\n* FLINK: Fortran 77 Support. (line 35)\n* GCJ: Public Macros. (line 99)\n* GCJFLAGS: Public Macros. (line 99)\n* GCJFLAGS <1>: Java Support with gcj.\n(line 16)\n* GCJLINK: How the Linker is Chosen.\n(line 10)\n* GTAGSARGS: Tags. (line 62)\n* GZIPENV: The Types of Distributions.\n(line 10)\n* HEADERS: Uniform. (line 101)\n* hosttriplet: Optional. (line 14)\n* INCLUDES: Program Variables. (line 44)\n* includeHEADERS: Headers. (line 6)\n* infoTEXINFOS: Texinfo. (line 6)\n* JAVA: Uniform. (line 101)\n* JAVAC: Java. (line 37)\n* JAVACFLAGS: Java. (line 40)\n* JAVAROOT: Java. (line 49)\n* LDADD: Linking. (line 10)\n* LDFLAGS: Program Variables. (line 12)\n* LFLAGS: Yacc and Lex. (line 65)\n* libexecPROGRAMS: Program Sources. (line 6)\n* libexecSCRIPTS: Scripts. (line 18)\n* LIBOBJS: Optional. (line 75)\n* LIBOBJS <1>: LTLIBOBJS. (line 6)\n* LIBOBJS <2>: LIBOBJS. (line 6)\n* LIBRARIES: Uniform. (line 101)\n* LIBS: Program Variables. (line 12)\n* LIBTOOLFLAGS: Libtool Flags. (line 6)\n* libLIBRARIES: A Library. (line 6)\n* libLTLIBRARIES: Libtool Libraries. (line 6)\n* LINK: Program Variables. (line 64)\n* LINK <1>: How the Linker is Chosen.\n(line 17)\n* LISP: Uniform. (line 101)\n* lispdir: Public Macros. (line 60)\n* lispLISP: Emacs Lisp. (line 6)\n* localstateDATA: Data. (line 9)\n* LOGCOMPILE: Parallel Test Harness.\n(line 51)\n* LOGCOMPILER: Parallel Test Harness.\n(line 51)\n* LOGDRIVER: Declaring Custom Test Drivers.\n(line 6)\n* LOGDRIVERFLAGS: Declaring Custom Test Drivers.\n(line 6)\n* LOGFLAGS: Parallel Test Harness.\n(line 51)\n* LTALLOCA: LTLIBOBJS. (line 6)\n* LTALLOCA <1>: LIBOBJS. (line 6)\n* LTLIBOBJS: LTLIBOBJS. (line 6)\n* LTLIBOBJS <1>: LIBOBJS. (line 6)\n* LTLIBRARIES: Uniform. (line 101)\n* LZIPOPT: The Types of Distributions.\n(line 23)\n* MAINTAINERCLEANFILES: Clean. (line 13)\n* MAKE: Subdirectories. (line 29)\n* MAKEINFO: Texinfo. (line 99)\n* MAKEINFOFLAGS: Texinfo. (line 109)\n* MAKEINFOHTML: Texinfo. (line 105)\n* MANS: Uniform. (line 101)\n* manMANS: Man Pages. (line 6)\n* maudeAR: Program and Library Variables.\n(line 76)\n* maudeCCASFLAGS: Program and Library Variables.\n(line 183)\n* maudeCFLAGS: Program and Library Variables.\n(line 184)\n* maudeCPPFLAGS: Program and Library Variables.\n(line 185)\n* maudeCXXFLAGS: Program and Library Variables.\n(line 186)\n* maudeDEPENDENCIES: Linking. (line 41)\n* maudeDEPENDENCIES <1>: Program and Library Variables.\n(line 128)\n* maudeFFLAGS: Program and Library Variables.\n(line 187)\n* maudeGCJFLAGS: Program and Library Variables.\n(line 188)\n* maudeLDADD: Linking. (line 17)\n* maudeLDADD <1>: Program and Library Variables.\n(line 94)\n* maudeLDFLAGS: Linking. (line 37)\n* maudeLDFLAGS <1>: Program and Library Variables.\n(line 114)\n* maudeLFLAGS: Program and Library Variables.\n(line 189)\n* maudeLIBADD: A Library. (line 26)\n* maudeLIBADD <1>: Program and Library Variables.\n(line 86)\n* maudeLIBTOOLFLAGS: Libtool Flags. (line 6)\n* maudeLIBTOOLFLAGS <1>: Program and Library Variables.\n(line 121)\n* maudeLINK: Program and Library Variables.\n(line 164)\n* maudeOBJCFLAGS: Program and Library Variables.\n(line 190)\n* maudeOBJCXXFLAGS: Program and Library Variables.\n(line 191)\n* maudeRFLAGS: Program and Library Variables.\n(line 192)\n* maudeSHORTNAME: Program and Library Variables.\n(line 223)\n* maudeSOURCES: Program and Library Variables.\n(line 18)\n* maudeUPCFLAGS: Program and Library Variables.\n(line 193)\n* maudeYFLAGS: Program and Library Variables.\n(line 194)\n* MISSING: Public Macros. (line 110)\n* MKDIRP: Obsolete Macros. (line 14)\n* mkdirp: Obsolete Macros. (line 14)\n* MOSTLYCLEANFILES: Clean. (line 13)\n* nobase: Alternative. (line 22)\n* nodist: Alternative. (line 28)\n* nodist <1>: Fine-grained Distribution Control.\n(line 6)\n* noinst: Uniform. (line 90)\n* noinstHEADERS: Headers. (line 6)\n* noinstHEADERS <1>: Headers. (line 23)\n* noinstLIBRARIES: A Library. (line 6)\n* noinstLISP: Emacs Lisp. (line 6)\n* noinstLTLIBRARIES: Libtool Convenience Libraries.\n(line 6)\n* noinstPROGRAMS: Program Sources. (line 6)\n* noinstSCRIPTS: Scripts. (line 18)\n* notrans: Man Pages. (line 54)\n* OBJC: Objective C Support. (line 16)\n* OBJCCOMPILE: Objective C Support. (line 25)\n* OBJCFLAGS: Objective C Support. (line 19)\n* OBJCLINK: Objective C Support. (line 29)\n* OBJCLINK <1>: How the Linker is Chosen.\n(line 15)\n* OBJCXX: Objective C++ Support.\n(line 16)\n* OBJCXXCOMPILE: Objective C++ Support.\n(line 25)\n* OBJCXXFLAGS: Objective C++ Support.\n(line 19)\n* OBJCXXLINK: Objective C++ Support.\n(line 29)\n* OBJCXXLINK <1>: How the Linker is Chosen.\n(line 11)\n* oldincludeHEADERS: Headers. (line 6)\n* PACKAGE: Basics of Distribution.\n(line 6)\n* pkgdatadir: Uniform. (line 19)\n* pkgdataDATA: Data. (line 9)\n* pkgdataSCRIPTS: Scripts. (line 18)\n* pkgincludedir: Uniform. (line 19)\n* pkgincludeHEADERS: Headers. (line 6)\n* pkglibdir: Uniform. (line 19)\n* pkglibexecdir: Uniform. (line 19)\n* pkglibexecPROGRAMS: Program Sources. (line 6)\n* pkglibexecSCRIPTS: Scripts. (line 18)\n* pkglibLIBRARIES: A Library. (line 6)\n* pkglibLTLIBRARIES: Libtool Libraries. (line 6)\n* pkgpyexecdir: Python. (line 109)\n* pkgpythondir: Python. (line 95)\n* PROGRAMS: Uniform. (line 17)\n* PROGRAMS <1>: Uniform. (line 101)\n* pyexecdir: Python. (line 100)\n* PYTHON: Uniform. (line 101)\n* PYTHON <1>: Python. (line 56)\n* pythondir: Python. (line 91)\n* PYTHONEXECPREFIX: Python. (line 73)\n* PYTHONPLATFORM: Python. (line 86)\n* PYTHONPREFIX: Python. (line 72)\n* PYTHONVERSION: Python. (line 68)\n* RECHECKLOGS: Parallel Test Harness.\n(line 127)\n* RFLAGS: Fortran 77 Support. (line 25)\n* RUNTEST: DejaGnu Tests. (line 19)\n* RUNTESTDEFAULTFLAGS: DejaGnu Tests. (line 14)\n* RUNTESTFLAGS: DejaGnu Tests. (line 24)\n* sbinPROGRAMS: Program Sources. (line 6)\n* sbinSCRIPTS: Scripts. (line 18)\n* SCRIPTS: Uniform. (line 101)\n* SCRIPTS <1>: Scripts. (line 9)\n* sharedstateDATA: Data. (line 9)\n* SOURCES: Program Sources. (line 33)\n* SOURCES <1>: Default SOURCES. (line 6)\n* SUBDIRS: Subdirectories. (line 8)\n* SUBDIRS <1>: Basics of Distribution.\n(line 73)\n* SUFFIXES: Suffixes. (line 6)\n* sys.execprefix Python variable: Python. (line 74)\n* sys.platform Python variable: Python. (line 87)\n* sys.prefix Python variable: Python. (line 74)\n* sys.versioninfo Python variable: Python. (line 69)\n* sysconfDATA: Data. (line 9)\n* TAGSDEPENDENCIES: Tags. (line 37)\n* TAR: Basics of Distribution.\n(line 16)\n* targettriplet: Optional. (line 14)\n* TESTS: Scripts-based Testsuites.\n(line 104)\n* TESTS <1>: Parallel Test Harness.\n(line 12)\n* TESTSENVIRONMENT: Testsuite Environment Overrides.\n(line 6)\n* TESTEXTENSIONS: Parallel Test Harness.\n(line 34)\n* TESTLOGS: Parallel Test Harness.\n(line 34)\n* TESTSUITELOG: Parallel Test Harness.\n(line 12)\n* TEXI2DVI: Texinfo. (line 132)\n* TEXI2PDF: Texinfo. (line 137)\n* TEXINFOS: Uniform. (line 101)\n* TEXINFOS <1>: Texinfo. (line 65)\n* TEXINFOTEX: Texinfo. (line 145)\n* topdistdir: The dist Hook. (line 34)\n* topdistdir <1>: Third-Party Makefiles.\n(line 25)\n* UPC: Public Macros. (line 104)\n* UPC <1>: Unified Parallel C Support.\n(line 15)\n* UPCCOMPILE: Unified Parallel C Support.\n(line 24)\n* UPCFLAGS: Unified Parallel C Support.\n(line 18)\n* UPCLINK: Unified Parallel C Support.\n(line 28)\n* UPCLINK <1>: How the Linker is Chosen.\n(line 16)\n* V: Automake Silent Rules.\n(line 88)\n* VALAC: Vala Support. (line 37)\n* VALAFLAGS: Vala Support. (line 41)\n* VERBOSE: Parallel Test Harness.\n(line 26)\n* VERSION: Basics of Distribution.\n(line 6)\n* WARNINGS: automake Invocation. (line 187)\n* WARNINGS <1>: aclocal Options. (line 95)\n* WITHDMALLOC: Public Macros. (line 122)\n* XFAILTESTS: Scripts-based Testsuites.\n(line 32)\n* XZOPT: The Types of Distributions.\n(line 30)\n* YACC: Optional. (line 129)\n* YFLAGS: Yacc and Lex. (line 37)\n* ZSTDCLEVEL: The Types of Distributions.\n(line 41)\n* ZSTDOPT: The Types of Distributions.\n(line 41)\n\nFile: automake-1.16.info, Node: General Index, Prev: Variable Index, Up: Indices\n" }, { "name": "B.3 General Index", "content": "* Menu:\n\n* ## (special Automake comment): General Operation. (line 68)\n* #serial syntax: Serials. (line 6)\n* $(LIBOBJS) and empty libraries: LIBOBJS. (line 72)\n* +=: General Operation. (line 24)\n* --add-missing: automake Invocation. (line 41)\n* --always-make GNU Make option: Rebuilding. (line 77)\n* --automake-acdir: aclocal Options. (line 9)\n* --build=BUILD: Cross-Compilation. (line 14)\n* --copy: automake Invocation. (line 75)\n* --diff: aclocal Options. (line 22)\n* --disable-dependency-tracking: Dependency Tracking. (line 33)\n* --disable-maintainer-mode: Optional. (line 180)\n* --disable-silent-rules: Automake Silent Rules.\n(line 85)\n* --dry-run: aclocal Options. (line 27)\n* --enable-debug, example: Usage of Conditionals.\n(line 21)\n* --enable-dependency-tracking: Dependency Tracking. (line 43)\n* --enable-maintainer-mode: Optional. (line 180)\n* --enable-silent-rules: Automake Silent Rules.\n(line 85)\n* --force: aclocal Options. (line 49)\n* --force-missing: automake Invocation. (line 80)\n* --foreign: Strictness. (line 51)\n* --foreign <1>: automake Invocation. (line 86)\n* --gnits: Strictness. (line 58)\n* --gnits <1>: automake Invocation. (line 90)\n* --gnu: Strictness. (line 18)\n* --gnu <1>: automake Invocation. (line 94)\n* --help: automake Invocation. (line 98)\n* --help <1>: aclocal Options. (line 31)\n* --help check: List of Automake options.\n(line 144)\n* --help=recursive: Nested Packages. (line 30)\n* --host=HOST: Cross-Compilation. (line 16)\n* --include-deps: automake Invocation. (line 106)\n* --install: aclocal Options. (line 38)\n* --libdir: automake Invocation. (line 61)\n* --no-force: automake Invocation. (line 111)\n* --output: aclocal Options. (line 59)\n* --output-dir: automake Invocation. (line 118)\n* --prefix: Standard Directory Variables.\n(line 33)\n* --print-ac-dir: aclocal Options. (line 62)\n* --print-libdir: automake Invocation. (line 69)\n* --program-prefix=PREFIX: Renaming. (line 16)\n* --program-suffix=SUFFIX: Renaming. (line 18)\n* --program-transform-name=PROGRAM: Renaming. (line 20)\n* --system-acdir: aclocal Options. (line 17)\n* --target=TARGET: Cross-Compilation. (line 55)\n* --verbose: automake Invocation. (line 125)\n* --verbose <1>: aclocal Options. (line 73)\n* --version: automake Invocation. (line 129)\n* --version <1>: aclocal Options. (line 76)\n* --version check: List of Automake options.\n(line 144)\n* --warnings: automake Invocation. (line 133)\n* --warnings <1>: aclocal Options. (line 80)\n* --with-dmalloc: Public Macros. (line 122)\n* --with-python-sys-prefix: Python. (line 74)\n* --with-pythonexecprefix: Python. (line 74)\n* --with-pythonprefix: Python. (line 74)\n* -a: automake Invocation. (line 41)\n* -c: automake Invocation. (line 74)\n* -f: automake Invocation. (line 79)\n* -hook targets: Extending. (line 66)\n* -i: automake Invocation. (line 102)\n* -I: aclocal Options. (line 34)\n* -l and LDADD: Linking. (line 70)\n* -local targets: Extending. (line 37)\n* -module, libtool: Libtool Modules. (line 6)\n* -o: automake Invocation. (line 118)\n* -v: automake Invocation. (line 125)\n* -W: automake Invocation. (line 133)\n* -W <1>: aclocal Options. (line 80)\n* -Wall: amhello's configure.ac Setup Explained.\n(line 38)\n* -Werror: amhello's configure.ac Setup Explained.\n(line 38)\n* .la suffix, defined: Libtool Concept. (line 6)\n* .log files: Parallel Test Harness.\n(line 12)\n* .pyc, .pyo files: Python. (line 15)\n* .trs files: Parallel Test Harness.\n(line 12)\n* :copy-in-global-log:: Log files generation and test results recording.\n(line 44)\n* :recheck:: Log files generation and test results recording.\n(line 38)\n* :test-global-result:: Log files generation and test results recording.\n(line 54)\n* :test-result:: Log files generation and test results recording.\n(line 24)\n* DATA primary, defined: Data. (line 6)\n* DEPENDENCIES, defined: Linking. (line 41)\n* HEADERS primary, defined: Headers. (line 6)\n* JAVA primary, defined: Java. (line 6)\n* LDFLAGS, defined: Linking. (line 37)\n* LDFLAGS, libtool: Libtool Flags. (line 6)\n* LIBADD, libtool: Libtool Flags. (line 6)\n* LIBRARIES primary, defined: A Library. (line 6)\n* LIBTOOLFLAGS, libtool: Libtool Flags. (line 6)\n* LISP primary, defined: Emacs Lisp. (line 6)\n* LTLIBRARIES primary, defined: Libtool Libraries. (line 6)\n* MANS primary, defined: Man Pages. (line 6)\n* PROGRAMS primary variable: Uniform. (line 11)\n* PYTHON primary, defined: Python. (line 6)\n* SCRIPTS primary, defined: Scripts. (line 6)\n* SOURCES and header files: Program Sources. (line 39)\n* SOURCES primary, defined: Program Sources. (line 32)\n* SOURCES, default: Default SOURCES. (line 6)\n* SOURCES, empty: Default SOURCES. (line 44)\n* TEXINFOS primary, defined: Texinfo. (line 6)\n* acinclude.m4, defined: Complete. (line 23)\n* aclocal and serial numbers: Serials. (line 6)\n* aclocal program, introduction: Complete. (line 23)\n* aclocal search path: Macro Search Path. (line 6)\n* aclocal's scheduled death: Future of aclocal. (line 6)\n* aclocal, extending: Extending aclocal. (line 6)\n* aclocal, Invocation: aclocal Invocation. (line 6)\n* aclocal, Invoking: aclocal Invocation. (line 6)\n* aclocal, Options: aclocal Options. (line 6)\n* aclocal, using: configure. (line 6)\n* aclocal.m4, preexisting: Complete. (line 23)\n* ACLOCALPATH: Macro Search Path. (line 116)\n* ACCONFIGFILES, conditional: Usage of Conditionals.\n(line 79)\n* ACSUBST and SUBDIRS: Subdirectories with ACSUBST.\n(line 6)\n* Adding new SUFFIXES: Suffixes. (line 6)\n* all: Standard Targets. (line 16)\n* all <1>: Extending. (line 41)\n* all-local: Extending. (line 41)\n* ALLOCA, and Libtool: LTLIBOBJS. (line 6)\n* ALLOCA, example: LIBOBJS. (line 6)\n* ALLOCA, special handling: LIBOBJS. (line 6)\n* amhello-1.0.tar.gz, creation: Hello World. (line 6)\n* amhello-1.0.tar.gz, location: Use Cases. (line 6)\n* amhello-1.0.tar.gz, use cases: Use Cases. (line 6)\n* AMCCASFLAGS and CCASFLAGS: Flag Variables Ordering.\n(line 20)\n* AMCFLAGS and CFLAGS: Flag Variables Ordering.\n(line 20)\n* AMCONDITIONAL and SUBDIRS: Subdirectories with AMCONDITIONAL.\n(line 6)\n* AMCPPFLAGS and CPPFLAGS: Flag Variables Ordering.\n(line 20)\n* AMCXXFLAGS and CXXFLAGS: Flag Variables Ordering.\n(line 20)\n* AMFCFLAGS and FCFLAGS: Flag Variables Ordering.\n(line 20)\n* AMFFLAGS and FFLAGS: Flag Variables Ordering.\n(line 20)\n* AMGCJFLAGS and GCJFLAGS: Flag Variables Ordering.\n(line 20)\n* AMINITAUTOMAKE, example use: Complete. (line 11)\n* AMLDFLAGS and LDFLAGS: Flag Variables Ordering.\n(line 20)\n* AMLFLAGS and LFLAGS: Flag Variables Ordering.\n(line 20)\n* AMLIBTOOLFLAGS and LIBTOOLFLAGS: Flag Variables Ordering.\n(line 20)\n* AMMAINTAINERMODE, purpose: maintainer-mode. (line 38)\n* AMOBJCFLAGS and OBJCFLAGS: Flag Variables Ordering.\n(line 20)\n* AMOBJCXXFLAGS and OBJXXCFLAGS: Flag Variables Ordering.\n(line 20)\n* AMRFLAGS and RFLAGS: Flag Variables Ordering.\n(line 20)\n* AMUPCFLAGS and UPCFLAGS: Flag Variables Ordering.\n(line 20)\n* AMYFLAGS and YFLAGS: Flag Variables Ordering.\n(line 20)\n* Append operator: General Operation. (line 24)\n* ar-lib: Auxiliary Programs. (line 16)\n* ARGMAX: Length Limitations. (line 6)\n* autogen.sh and autoreconf: Error required file ltmain.sh not found.\n(line 6)\n* autom4te: aclocal Invocation. (line 44)\n* Automake constraints: Introduction. (line 21)\n* automake options: automake Invocation. (line 37)\n* Automake parser, limitations of: General Operation. (line 33)\n* Automake requirements: Introduction. (line 26)\n* Automake requirements <1>: Requirements. (line 6)\n* Automake targets, no-op: Third-Party Makefiles.\n(line 88)\n* automake, invocation: automake Invocation. (line 6)\n* automake, invoking: automake Invocation. (line 6)\n* Automake, recursive operation: General Operation. (line 58)\n* Automatic dependency tracking: Dependencies. (line 11)\n* Automatic linker selection: How the Linker is Chosen.\n(line 6)\n* autoreconf and libtoolize: Error required file ltmain.sh not found.\n(line 6)\n* autoreconf, example: Creating amhello. (line 59)\n* autoscan: amhello's configure.ac Setup Explained.\n(line 89)\n* Autotools, introduction: GNU Build System. (line 43)\n* Autotools, purpose: Why Autotools. (line 6)\n* autoupdate: Obsolete Macros. (line 6)\n* Auxiliary programs: Auxiliary Programs. (line 6)\n* Avoiding man page renaming: Man Pages. (line 54)\n* Avoiding path stripping: Alternative. (line 22)\n* Binary package: DESTDIR. (line 22)\n* bootstrap and autoreconf: Error required file ltmain.sh not found.\n(line 6)\n* Bugs, reporting: Reporting Bugs. (line 6)\n* build tree and source tree: VPATH Builds. (line 6)\n* BUILTSOURCES, defined: Sources. (line 27)\n* bzip2: The Types of Distributions.\n(line 17)\n* C++ support: C++ Support. (line 6)\n* canonicalizing Automake variables: Canonicalization. (line 6)\n* CCASFLAGS and AMCCASFLAGS: Flag Variables Ordering.\n(line 20)\n* CFLAGS and AMCFLAGS: Flag Variables Ordering.\n(line 20)\n* cfortran: Mixing Fortran 77 With C and C++.\n(line 6)\n* check: Standard Targets. (line 31)\n* check <1>: Tests. (line 6)\n* check <2>: Extending. (line 41)\n* check-local: Extending. (line 41)\n* check-news: List of Automake options.\n(line 15)\n* check primary prefix, definition: Uniform. (line 95)\n* checkPROGRAMS example: Default SOURCES. (line 28)\n* clean: Standard Targets. (line 27)\n* clean <1>: Extending. (line 41)\n* clean-local: Clean. (line 15)\n* clean-local <1>: Extending. (line 41)\n* Colorized testsuite output: Scripts-based Testsuites.\n(line 85)\n* command line length limit: Length Limitations. (line 6)\n* Comment, special to Automake: General Operation. (line 68)\n* Compilation of Java to bytecode: Java. (line 6)\n* Compilation of Java to native code: Java Support with gcj.\n(line 6)\n* compile: Auxiliary Programs. (line 20)\n* Compile Flag Variables: Flag Variables Ordering.\n(line 20)\n* Complete example: Complete. (line 6)\n* compress: The Types of Distributions.\n(line 57)\n* Conditional example, --enable-debug: Usage of Conditionals.\n(line 21)\n* conditional libtool libraries: Conditional Libtool Libraries.\n(line 6)\n* Conditional programs: Conditional Programs.\n(line 6)\n* Conditional subdirectories: Conditional Subdirectories.\n(line 6)\n* Conditional SUBDIRS: Conditional Subdirectories.\n(line 6)\n* Conditionals: Conditionals. (line 6)\n* config.guess: Auxiliary Programs. (line 30)\n* config.guess <1>: automake Invocation. (line 39)\n* config.site example: config.site. (line 6)\n* config.sub: Auxiliary Programs. (line 30)\n* configuration variables, overriding: Standard Configuration Variables.\n(line 6)\n* Configuration, basics: Basic Installation. (line 6)\n* Configure substitutions in TESTS: Parallel Test Harness.\n(line 46)\n* configure.ac, Hello World: amhello's configure.ac Setup Explained.\n(line 6)\n* configure.ac, scanning: configure. (line 6)\n* conflicting definitions: Extending. (line 14)\n* Constraints of Automake: Introduction. (line 21)\n* convenience libraries, libtool: Libtool Convenience Libraries.\n(line 6)\n* copying semantics: Extending. (line 10)\n* cpio example: Uniform. (line 36)\n* CPPFLAGS and AMCPPFLAGS: Flag Variables Ordering.\n(line 20)\n* cross-compilation: Cross-Compilation. (line 6)\n* cross-compilation example: Cross-Compilation. (line 25)\n* CVS and generated files: CVS. (line 50)\n* CVS and third-party files: CVS. (line 167)\n* CVS and timestamps: CVS. (line 29)\n* CXXFLAGS and AMCXXFLAGS: Flag Variables Ordering.\n(line 20)\n* DATA primary, defined: Data. (line 6)\n* debug build, example: VPATH Builds. (line 48)\n* debugging rules: Debugging Make Rules.\n(line 6)\n* default source, Libtool modules example: Default SOURCES. (line 38)\n* default verbosity for silent rules: Automake Silent Rules.\n(line 92)\n* default SOURCES: Default SOURCES. (line 6)\n* definitions, conflicts: Extending. (line 14)\n* dejagnu: DejaGnu Tests. (line 19)\n* dejagnu <1>: List of Automake options.\n(line 19)\n* depcomp: Auxiliary Programs. (line 40)\n* depcomp <1>: Dependencies. (line 22)\n* dependencies and distributed files: Errors with distclean.\n(line 6)\n* Dependency tracking: Dependency Tracking. (line 6)\n* Dependency tracking <1>: Dependencies. (line 11)\n* Dependency tracking, disabling: Dependencies. (line 36)\n* directory variables: Standard Directory Variables.\n(line 6)\n* dirlist: Macro Search Path. (line 52)\n* Disabling dependency tracking: Dependencies. (line 37)\n* Disabling hard errors: Scripts-based Testsuites.\n(line 32)\n* dist: Standard Targets. (line 35)\n* dist <1>: Basics of Distribution.\n(line 6)\n* dist-all: The Types of Distributions.\n(line 62)\n* dist-bzip2: The Types of Distributions.\n(line 17)\n* dist-bzip2 <1>: List of Automake options.\n(line 23)\n* dist-bzip2 <2>: List of Automake options.\n(line 23)\n* dist-gzip: The Types of Distributions.\n(line 10)\n* dist-hook: The dist Hook. (line 6)\n* dist-hook <1>: Extending. (line 66)\n* dist-lzip: The Types of Distributions.\n(line 23)\n* dist-lzip <1>: List of Automake options.\n(line 26)\n* dist-lzip <2>: List of Automake options.\n(line 26)\n* dist-shar: The Types of Distributions.\n(line 51)\n* dist-shar <1>: List of Automake options.\n(line 40)\n* dist-shar <2>: List of Automake options.\n(line 38)\n* dist-tarZ: The Types of Distributions.\n(line 57)\n* dist-tarZ <1>: List of Automake options.\n(line 45)\n* dist-tarZ <2>: List of Automake options.\n(line 43)\n* dist-xz: The Types of Distributions.\n(line 30)\n* dist-xz <1>: List of Automake options.\n(line 29)\n* dist-xz <2>: List of Automake options.\n(line 29)\n* dist-zip: The Types of Distributions.\n(line 37)\n* dist-zip <1>: List of Automake options.\n(line 32)\n* dist-zip <2>: List of Automake options.\n(line 32)\n* dist-zstd: The Types of Distributions.\n(line 41)\n* dist-zstd <1>: List of Automake options.\n(line 35)\n* dist-zstd <2>: List of Automake options.\n(line 35)\n* distcheck: Creating amhello. (line 100)\n* distcheck <1>: Checking the Distribution.\n(line 6)\n* distcheck better than dist: Preparing Distributions.\n(line 10)\n* distcheck example: Creating amhello. (line 100)\n* distcheck-hook: Checking the Distribution.\n(line 77)\n* distclean: Standard Targets. (line 29)\n* distclean <1>: Extending. (line 41)\n* distclean <2>: Errors with distclean.\n(line 6)\n* distclean, diagnostic: Errors with distclean.\n(line 6)\n* distclean-local: Clean. (line 15)\n* distclean-local <1>: Extending. (line 41)\n* distcleancheck: Checking the Distribution.\n(line 92)\n* distdir: Third-Party Makefiles.\n(line 25)\n* Distinction between errors and failures in testsuites: Generalities about Testing.\n(line 48)\n* Distributions, preparation: Preparing Distributions.\n(line 6)\n* distuninstallcheck: Checking the Distribution.\n(line 128)\n* dist and nobase: Alternative. (line 28)\n* dist and notrans: Man Pages. (line 63)\n* DISTSUBDIRS, explained: SUBDIRS vs DISTSUBDIRS.\n(line 6)\n* dmalloc, support for: Public Macros. (line 122)\n* do-nothing Automake targets: Third-Party Makefiles.\n(line 88)\n* dvi: Texinfo. (line 25)\n* dvi <1>: Checking the Distribution.\n(line 57)\n* dvi <2>: Extending. (line 41)\n* DVI output using Texinfo: Texinfo. (line 6)\n* dvi-local: Extending. (line 41)\n* EDITION Texinfo flag: Texinfo. (line 35)\n* else: Usage of Conditionals.\n(line 36)\n* empty Automake targets: Third-Party Makefiles.\n(line 88)\n* Empty libraries: A Library. (line 48)\n* Empty libraries and $(LIBOBJS): LIBOBJS. (line 72)\n* empty SOURCES: Default SOURCES. (line 44)\n* endif: Usage of Conditionals.\n(line 36)\n* eps images: Checking the Distribution.\n(line 60)\n* Example conditional --enable-debug: Usage of Conditionals.\n(line 21)\n* Example conditional ACCONFIGFILES: Usage of Conditionals.\n(line 79)\n* Example Hello World: Hello World. (line 6)\n* Example of recursive operation: General Operation. (line 58)\n* Example of shared libraries: Libtool Libraries. (line 6)\n* Example, EXTRAPROGRAMS: Uniform. (line 36)\n* Example, false and true: true. (line 6)\n* Example, mixed language: Mixing Fortran 77 With C and C++.\n(line 34)\n* Executable extension: EXEEXT. (line 6)\n* Exit status 77, special interpretation: Scripts-based Testsuites.\n(line 27)\n* Exit status 99, special interpretation: Scripts-based Testsuites.\n(line 27)\n* expected failure: Generalities about Testing.\n(line 39)\n* expected test failure: Generalities about Testing.\n(line 39)\n* Expected test failure: Scripts-based Testsuites.\n(line 32)\n* Extending aclocal: Extending aclocal. (line 6)\n* Extending list of installation directories: Uniform. (line 56)\n* Extension, executable: EXEEXT. (line 6)\n* Extra files distributed with Automake: automake Invocation. (line 39)\n* EXTRA, prepending: Uniform. (line 29)\n* EXTRAPROGRAMS, defined: Uniform. (line 36)\n* EXTRAPROGRAMS, defined <1>: Conditional Programs.\n(line 15)\n* EXTRAprogSOURCES, defined: Conditional Sources. (line 18)\n* false Example: true. (line 6)\n* FCFLAGS and AMFCFLAGS: Flag Variables Ordering.\n(line 20)\n* Features of the GNU Build System: Use Cases. (line 6)\n* FFLAGS and AMFFLAGS: Flag Variables Ordering.\n(line 20)\n* file names, limitations on: Limitations on File Names.\n(line 6)\n* filename-length-max=99: List of Automake options.\n(line 48)\n* Files distributed with Automake: automake Invocation. (line 39)\n* First line of Makefile.am: General Operation. (line 74)\n* Flag variables, ordering: Flag Variables Ordering.\n(line 6)\n* Flag Variables, Ordering: Flag Variables Ordering.\n(line 20)\n* FLIBS, defined: Mixing Fortran 77 With C and C++.\n(line 21)\n* foreign: amhello's configure.ac Setup Explained.\n(line 38)\n* foreign <1>: List of Automake options.\n(line 9)\n* foreign strictness: Strictness. (line 51)\n* Fortran 77 support: Fortran 77 Support. (line 6)\n* Fortran 77, mixing with C and C++: Mixing Fortran 77 With C and C++.\n(line 6)\n* Fortran 77, Preprocessing: Preprocessing Fortran 77.\n(line 6)\n* Fortran 9x support: Fortran 9x Support. (line 6)\n* GCJFLAGS and AMGCJFLAGS: Flag Variables Ordering.\n(line 20)\n* generated files and CVS: CVS. (line 50)\n* generated files, distributed: CVS. (line 9)\n* Gettext support: gettext. (line 6)\n* git-dist: General Operation. (line 12)\n* git-dist, non-standard example: General Operation. (line 12)\n* gnits: List of Automake options.\n(line 9)\n* gnits strictness: Strictness. (line 58)\n* gnu: List of Automake options.\n(line 9)\n* GNU Build System, basics: Basic Installation. (line 6)\n* GNU Build System, features: Use Cases. (line 6)\n* GNU Build System, introduction: GNU Build System. (line 6)\n* GNU Build System, use cases: Use Cases. (line 6)\n* GNU Coding Standards: GNU Build System. (line 29)\n* GNU Gettext support: gettext. (line 6)\n* GNU Make extensions: General Operation. (line 20)\n* GNU Makefile standards: Introduction. (line 12)\n* gnu strictness: Strictness. (line 18)\n* GNUmakefile including Makefile: Third-Party Makefiles.\n(line 114)\n* gzip: The Types of Distributions.\n(line 10)\n* hard error: Generalities about Testing.\n(line 48)\n* Header files in SOURCES: Program Sources. (line 39)\n* HEADERS primary, defined: Headers. (line 6)\n* HEADERS, installation directories: Headers. (line 6)\n* Hello World example: Hello World. (line 6)\n* help2man, and dist target: List of Automake options.\n(line 81)\n* hook targets: Extending. (line 66)\n* HP-UX 10, lex problems: Public Macros. (line 94)\n* html: Texinfo. (line 25)\n* html <1>: Extending. (line 41)\n* HTML output using Texinfo: Texinfo. (line 6)\n* html-local: Extending. (line 41)\n* id: Tags. (line 45)\n* if: Usage of Conditionals.\n(line 36)\n* include: Basics of Distribution.\n(line 30)\n* include <1>: Include. (line 6)\n* include, distribution: Basics of Distribution.\n(line 30)\n* Including Makefile fragment: Include. (line 6)\n* indentation in Makefile.am: General Operation. (line 33)\n* info: List of Automake options.\n(line 108)\n* info <1>: Extending. (line 41)\n* info-in-builddir: List of Automake options.\n(line 57)\n* info-local: Extending. (line 41)\n* install: Standard Targets. (line 18)\n* install <1>: The Two Parts of Install.\n(line 14)\n* install <2>: Extending. (line 41)\n* Install hook: Extending Installation.\n(line 15)\n* Install, two parts of: The Two Parts of Install.\n(line 14)\n* install-data: Two-Part Install. (line 16)\n* install-data <1>: The Two Parts of Install.\n(line 14)\n* install-data <2>: Extending. (line 41)\n* install-data-hook: Extending. (line 66)\n* install-data-local: Extending Installation.\n(line 9)\n* install-data-local <1>: Extending. (line 41)\n* install-dvi: Texinfo. (line 25)\n* install-dvi <1>: Extending. (line 41)\n* install-dvi-local: Extending. (line 41)\n* install-exec: Two-Part Install. (line 16)\n* install-exec <1>: The Two Parts of Install.\n(line 14)\n* install-exec <2>: Extending. (line 41)\n* install-exec-hook: Extending. (line 66)\n* install-exec-local: Extending Installation.\n(line 9)\n* install-exec-local <1>: Extending. (line 41)\n* install-html: Texinfo. (line 25)\n* install-html <1>: Extending. (line 41)\n* install-html-local: Extending. (line 41)\n* install-info: Texinfo. (line 85)\n* install-info <1>: List of Automake options.\n(line 108)\n* install-info <2>: Extending. (line 41)\n* install-info target: Texinfo. (line 85)\n* install-info-local: Extending. (line 41)\n* install-man: Man Pages. (line 32)\n* install-man <1>: List of Automake options.\n(line 114)\n* install-man target: Man Pages. (line 32)\n* install-pdf: Texinfo. (line 25)\n* install-pdf <1>: Extending. (line 41)\n* install-pdf-local: Extending. (line 41)\n* install-ps: Texinfo. (line 25)\n* install-ps <1>: Extending. (line 41)\n* install-ps-local: Extending. (line 41)\n* install-sh: Auxiliary Programs. (line 46)\n* install-strip: Standard Targets. (line 21)\n* install-strip <1>: Install Rules for the User.\n(line 7)\n* Installation directories, extending list: Uniform. (line 56)\n* Installation support: Install. (line 6)\n* Installation, basics: Basic Installation. (line 6)\n* installcheck: Standard Targets. (line 33)\n* installcheck <1>: Extending. (line 41)\n* installcheck-local: Extending. (line 41)\n* installdirs: Install Rules for the User.\n(line 7)\n* installdirs <1>: Extending. (line 41)\n* installdirs-local: Extending. (line 41)\n* Installing headers: Headers. (line 6)\n* Installing scripts: Scripts. (line 6)\n* installing versioned binaries: Extending. (line 86)\n* Interfacing with third-party packages: Third-Party Makefiles.\n(line 6)\n* Invocation of aclocal: aclocal Invocation. (line 6)\n* Invocation of automake: automake Invocation. (line 6)\n* Invoking aclocal: aclocal Invocation. (line 6)\n* Invoking automake: automake Invocation. (line 6)\n* JAVA primary, defined: Java. (line 6)\n* JAVA restrictions: Java. (line 27)\n* Java support with gcj: Java Support with gcj.\n(line 6)\n* Java to bytecode, compilation: Java. (line 6)\n* Java to native code, compilation: Java Support with gcj.\n(line 6)\n* lazy test execution: Parallel Test Harness.\n(line 127)\n* LDADD and -l: Linking. (line 70)\n* LDFLAGS and AMLDFLAGS: Flag Variables Ordering.\n(line 20)\n* lex problems with HP-UX 10: Public Macros. (line 94)\n* lex, multiple lexers: Yacc and Lex. (line 73)\n* LFLAGS and AMLFLAGS: Flag Variables Ordering.\n(line 20)\n* libltdl, introduction: Libtool Concept. (line 29)\n* LIBOBJS, and Libtool: LTLIBOBJS. (line 6)\n* LIBOBJS, example: LIBOBJS. (line 6)\n* LIBOBJS, special handling: LIBOBJS. (line 6)\n* LIBRARIES primary, defined: A Library. (line 6)\n* libtool convenience libraries: Libtool Convenience Libraries.\n(line 6)\n* libtool libraries, conditional: Conditional Libtool Libraries.\n(line 6)\n* libtool library, definition: Libtool Concept. (line 6)\n* libtool modules: Libtool Modules. (line 6)\n* Libtool modules, default source example: Default SOURCES. (line 38)\n* libtool, introduction: Libtool Concept. (line 6)\n* LIBTOOLFLAGS and AMLIBTOOLFLAGS: Flag Variables Ordering.\n(line 20)\n* libtoolize and autoreconf: Error required file ltmain.sh not found.\n(line 6)\n* libtoolize, no longer run by automake: Error required file ltmain.sh not found.\n(line 6)\n* Limitations of automake parser: General Operation. (line 33)\n* Linking Fortran 77 with C and C++: Mixing Fortran 77 With C and C++.\n(line 6)\n* Linking multiple yacc parsers: Linking Multiple Yacc Parsers.\n(line 3)\n* LISP primary, defined: Emacs Lisp. (line 6)\n* LNS example: Extending. (line 86)\n* local targets: Extending. (line 37)\n* LTALLOCA, special handling: LTLIBOBJS. (line 6)\n* LTLIBOBJS, special handling: LTLIBOBJS. (line 6)\n* LTLIBRARIES primary, defined: Libtool Libraries. (line 6)\n* ltmain.sh not found: Error required file ltmain.sh not found.\n(line 6)\n* lzip: The Types of Distributions.\n(line 23)\n* m4include, distribution: Basics of Distribution.\n(line 30)\n* Macro search path: Macro Search Path. (line 6)\n* macro serial numbers: Serials. (line 6)\n* Macros Automake recognizes: Optional. (line 6)\n* maintainer-clean-local: Clean. (line 15)\n* make check: Tests. (line 6)\n* make clean support: Clean. (line 6)\n* make dist: Basics of Distribution.\n(line 6)\n* make distcheck: Checking the Distribution.\n(line 6)\n* make distclean, diagnostic: Errors with distclean.\n(line 6)\n* make distcleancheck: Checking the Distribution.\n(line 92)\n* make distuninstallcheck: Checking the Distribution.\n(line 128)\n* make install support: Install. (line 6)\n* make installcheck, testing --help and --version: List of Automake options.\n(line 144)\n* Make rules, overriding: General Operation. (line 46)\n* Make targets, overriding: General Operation. (line 46)\n* Makefile fragment, including: Include. (line 6)\n* Makefile.am, first line: General Operation. (line 74)\n* Makefile.am, Hello World: amhello's Makefile.am Setup Explained.\n(line 6)\n* Man page renaming, avoiding: Man Pages. (line 54)\n* MANS primary, defined: Man Pages. (line 6)\n* many outputs, rules with: Multiple Outputs. (line 6)\n* mdate-sh: Auxiliary Programs. (line 50)\n* mdate-sh <1>: Texinfo. (line 35)\n* MinGW cross-compilation example: Cross-Compilation. (line 25)\n* missing program: Auxiliary Programs. (line 54)\n* missing, purpose: maintainer-mode. (line 9)\n* Mixed language example: Mixing Fortran 77 With C and C++.\n(line 34)\n* Mixing Fortran 77 with C and C++: Mixing Fortran 77 With C and C++.\n(line 6)\n* Mixing Fortran 77 with C and/or C++: Mixing Fortran 77 With C and C++.\n(line 6)\n* mkdir -p, macro check: Obsolete Macros. (line 14)\n* mkinstalldirs: Auxiliary Programs. (line 60)\n* modules, libtool: Libtool Modules. (line 6)\n* mostlyclean: Extending. (line 41)\n* mostlyclean-local: Clean. (line 15)\n* mostlyclean-local <1>: Extending. (line 41)\n* multiple configurations, example: VPATH Builds. (line 48)\n* Multiple configure.ac files: automake Invocation. (line 6)\n* Multiple lex lexers: Yacc and Lex. (line 73)\n* multiple outputs, rules with: Multiple Outputs. (line 6)\n* Multiple yacc parsers: Yacc and Lex. (line 73)\n* Nested packages: Nested Packages. (line 6)\n* Nesting packages: Subpackages. (line 6)\n* no-define: Public Macros. (line 54)\n* no-define <1>: List of Automake options.\n(line 62)\n* no-dependencies: Dependencies. (line 34)\n* no-dependencies <1>: List of Automake options.\n(line 70)\n* no-dist: List of Automake options.\n(line 77)\n* no-dist-built-sources: List of Automake options.\n(line 81)\n* no-dist-gzip: List of Automake options.\n(line 92)\n* no-dist-gzip <1>: List of Automake options.\n(line 92)\n* no-exeext: List of Automake options.\n(line 95)\n* no-installinfo: Texinfo. (line 85)\n* no-installinfo <1>: List of Automake options.\n(line 105)\n* no-installinfo option: Texinfo. (line 85)\n* no-installman: Man Pages. (line 32)\n* no-installman <1>: List of Automake options.\n(line 111)\n* no-installman option: Man Pages. (line 32)\n* no-op Automake targets: Third-Party Makefiles.\n(line 88)\n* no-texinfo.tex: List of Automake options.\n(line 121)\n* nobase and dist or nodist: Alternative. (line 28)\n* nobase prefix: Alternative. (line 22)\n* nodist and nobase: Alternative. (line 28)\n* nodist and notrans: Man Pages. (line 63)\n* noinst primary prefix, definition: Uniform. (line 90)\n* Non-GNU packages: Strictness. (line 6)\n* Non-standard targets: General Operation. (line 12)\n* nostdinc: List of Automake options.\n(line 117)\n* notrans and dist or nodist: Man Pages. (line 63)\n* notrans prefix: Man Pages. (line 54)\n* OBJCFLAGS and AMOBJCFLAGS: Flag Variables Ordering.\n(line 20)\n* OBJCXXFLAGS and AMOBJCXXFLAGS: Flag Variables Ordering.\n(line 20)\n* Objective C support: Objective C Support. (line 6)\n* Objective C++ support: Objective C++ Support.\n(line 6)\n* Objects in subdirectory: Program and Library Variables.\n(line 51)\n* obsolete macros: Obsolete Macros. (line 6)\n* optimized build, example: VPATH Builds. (line 48)\n* Option, --warnings=CATEGORY: List of Automake options.\n(line 228)\n* Option, -WCATEGORY: List of Automake options.\n(line 228)\n* Option, check-news: List of Automake options.\n(line 15)\n* Option, dejagnu: List of Automake options.\n(line 19)\n* Option, dist-bzip2: List of Automake options.\n(line 23)\n* Option, dist-lzip: List of Automake options.\n(line 26)\n* Option, dist-shar: List of Automake options.\n(line 38)\n* Option, dist-tarZ: List of Automake options.\n(line 43)\n* Option, dist-xz: List of Automake options.\n(line 29)\n* Option, dist-zip: List of Automake options.\n(line 32)\n* Option, dist-zstd: List of Automake options.\n(line 35)\n* Option, filename-length-max=99: List of Automake options.\n(line 48)\n* Option, foreign: List of Automake options.\n(line 9)\n* Option, gnits: List of Automake options.\n(line 9)\n* Option, gnu: List of Automake options.\n(line 9)\n* Option, info-in-builddir: List of Automake options.\n(line 57)\n* Option, no-define: List of Automake options.\n(line 62)\n* Option, no-dependencies: List of Automake options.\n(line 70)\n* Option, no-dist: List of Automake options.\n(line 77)\n* Option, no-dist-built-sources: List of Automake options.\n(line 81)\n* Option, no-dist-gzip: List of Automake options.\n(line 92)\n* Option, no-exeext: List of Automake options.\n(line 95)\n* Option, no-installinfo: Texinfo. (line 85)\n* Option, no-installinfo <1>: List of Automake options.\n(line 105)\n* Option, no-installman: Man Pages. (line 32)\n* Option, no-installman <1>: List of Automake options.\n(line 111)\n* Option, no-texinfo.tex: List of Automake options.\n(line 121)\n* Option, nostdinc: List of Automake options.\n(line 117)\n* Option, parallel-tests: List of Automake options.\n(line 129)\n* Option, readme-alpha: List of Automake options.\n(line 135)\n* Option, serial-tests: List of Automake options.\n(line 125)\n* Option, tar-pax: List of Automake options.\n(line 174)\n* Option, tar-ustar: List of Automake options.\n(line 174)\n* Option, tar-v7: List of Automake options.\n(line 174)\n* Option, VERSION: List of Automake options.\n(line 223)\n* Option, warnings: List of Automake options.\n(line 228)\n* Options, aclocal: aclocal Options. (line 6)\n* Options, automake: automake Invocation. (line 37)\n* Options, std-options: List of Automake options.\n(line 144)\n* Options, subdir-objects: List of Automake options.\n(line 165)\n* Ordering flag variables: Flag Variables Ordering.\n(line 6)\n* Overriding make rules: General Operation. (line 46)\n* Overriding make targets: General Operation. (line 46)\n* Overriding make variables: General Operation. (line 51)\n* overriding rules: Extending. (line 26)\n* overriding semantics: Extending. (line 26)\n* Overriding testsuite environment: Testsuite Environment Overrides.\n(line 6)\n* PACKAGE, directory: Uniform. (line 19)\n* PACKAGE, prevent definition: Public Macros. (line 54)\n* Packages, nested: Nested Packages. (line 6)\n* Packages, preparation: Preparing Distributions.\n(line 6)\n* Parallel build trees: VPATH Builds. (line 6)\n* parallel-tests: List of Automake options.\n(line 129)\n* Path stripping, avoiding: Alternative. (line 22)\n* pax format: List of Automake options.\n(line 174)\n* pdf: Texinfo. (line 25)\n* pdf <1>: Extending. (line 41)\n* PDF output using Texinfo: Texinfo. (line 6)\n* pdf-local: Extending. (line 41)\n* Per-object flags, emulated: Per-Object Flags. (line 6)\n* per-target compilation flags, defined: Program and Library Variables.\n(line 195)\n* pkgdatadir, defined: Uniform. (line 19)\n* pkgincludedir, defined: Uniform. (line 19)\n* pkglibdir, defined: Uniform. (line 19)\n* pkglibexecdir, defined: Uniform. (line 19)\n* Preparing distributions: Preparing Distributions.\n(line 6)\n* Preprocessing Fortran 77: Preprocessing Fortran 77.\n(line 6)\n* Primary variable, DATA: Data. (line 6)\n* Primary variable, defined: Uniform. (line 11)\n* Primary variable, HEADERS: Headers. (line 6)\n* Primary variable, JAVA: Java. (line 6)\n* Primary variable, LIBRARIES: A Library. (line 6)\n* Primary variable, LISP: Emacs Lisp. (line 6)\n* Primary variable, LTLIBRARIES: Libtool Libraries. (line 6)\n* Primary variable, MANS: Man Pages. (line 6)\n* Primary variable, PROGRAMS: Uniform. (line 11)\n* Primary variable, PYTHON: Python. (line 6)\n* Primary variable, SCRIPTS: Scripts. (line 6)\n* Primary variable, SOURCES: Program Sources. (line 32)\n* Primary variable, TEXINFOS: Texinfo. (line 6)\n* PROGRAMS primary variable: Uniform. (line 11)\n* Programs, auxiliary: Auxiliary Programs. (line 6)\n* PROGRAMS, bindir: Program Sources. (line 6)\n* Programs, conditional: Conditional Programs.\n(line 6)\n* Programs, renaming during installation: Renaming. (line 6)\n* progLDADD, defined: Linking. (line 12)\n* Proxy Makefile for third-party packages: Third-Party Makefiles.\n(line 131)\n* ps: Texinfo. (line 25)\n* ps <1>: Extending. (line 41)\n* PS output using Texinfo: Texinfo. (line 6)\n* ps-local: Extending. (line 41)\n* py-compile: Auxiliary Programs. (line 70)\n* PYTHON primary, defined: Python. (line 6)\n* Ratfor programs: Preprocessing Fortran 77.\n(line 6)\n* read-only source tree: VPATH Builds. (line 91)\n* README-alpha: Strictness. (line 78)\n* readme-alpha: List of Automake options.\n(line 135)\n* rebuild rules: Rebuilding. (line 6)\n* rebuild rules <1>: CVS. (line 9)\n* recheck: Parallel Test Harness.\n(line 139)\n* Recognized macros by Automake: Optional. (line 6)\n* Recursive operation of Automake: General Operation. (line 58)\n* recursive targets and third-party Makefiles: Third-Party Makefiles.\n(line 15)\n* Register test case result: Log files generation and test results recording.\n(line 24)\n* Register test result: Log files generation and test results recording.\n(line 24)\n* Renaming programs: Renaming. (line 6)\n* Reporting bugs: Reporting Bugs. (line 6)\n* Requirements of Automake: Requirements. (line 6)\n* Requirements, Automake: Introduction. (line 26)\n* Restrictions for JAVA: Java. (line 27)\n* reStructuredText field, :copy-in-global-log:: Log files generation and test results recording.\n(line 44)\n* reStructuredText field, :recheck:: Log files generation and test results recording.\n(line 38)\n* reStructuredText field, :test-global-result:: Log files generation and test results recording.\n(line 54)\n* reStructuredText field, :test-result:: Log files generation and test results recording.\n(line 24)\n* RFLAGS and AMRFLAGS: Flag Variables Ordering.\n(line 20)\n* rules with multiple outputs: Multiple Outputs. (line 6)\n* rules, conflicting: Extending. (line 14)\n* rules, debugging: Debugging Make Rules.\n(line 6)\n* rules, overriding: Extending. (line 26)\n* Scanning configure.ac: configure. (line 6)\n* SCRIPTS primary, defined: Scripts. (line 6)\n* SCRIPTS, installation directories: Scripts. (line 18)\n* Selecting the linker automatically: How the Linker is Chosen.\n(line 6)\n* serial number and --install: aclocal Options. (line 42)\n* serial numbers in macros: Serials. (line 6)\n* serial-tests: List of Automake options.\n(line 125)\n* serial-tests, Using: Serial Test Harness. (line 6)\n* shar: The Types of Distributions.\n(line 51)\n* Shared libraries, support for: A Shared Library. (line 6)\n* Silencing make: Silencing Make. (line 6)\n* Silent make: Silencing Make. (line 6)\n* Silent make rules: Silencing Make. (line 6)\n* Silent rules: Silencing Make. (line 6)\n* silent rules and libtool: Automake Silent Rules.\n(line 59)\n* site-packages Python directory: Python. (line 92)\n* site.exp: DejaGnu Tests. (line 26)\n* source tree and build tree: VPATH Builds. (line 6)\n* source tree, read-only: VPATH Builds. (line 91)\n* SOURCES primary, defined: Program Sources. (line 32)\n* Special Automake comment: General Operation. (line 68)\n* Staged installation: DESTDIR. (line 14)\n* std-options: List of Automake options.\n(line 144)\n* Strictness, command line: automake Invocation. (line 37)\n* Strictness, defined: Strictness. (line 10)\n* Strictness, foreign: Strictness. (line 51)\n* Strictness, gnits: Strictness. (line 58)\n* Strictness, gnu: Strictness. (line 18)\n* su, before make install: Basic Installation. (line 49)\n* subdir-objects: List of Automake options.\n(line 165)\n* Subdirectories, building conditionally: Conditional Subdirectories.\n(line 6)\n* Subdirectories, configured conditionally: Unconfigured Subdirectories.\n(line 6)\n* Subdirectories, not distributed: Unconfigured Subdirectories.\n(line 55)\n* Subdirectory, objects in: Program and Library Variables.\n(line 51)\n* SUBDIRS and ACSUBST: Subdirectories with ACSUBST.\n(line 6)\n* SUBDIRS and AMCONDITIONAL: Subdirectories with AMCONDITIONAL.\n(line 6)\n* SUBDIRS, conditional: Conditional Subdirectories.\n(line 6)\n* SUBDIRS, explained: Subdirectories. (line 6)\n* Subpackages: Nested Packages. (line 6)\n* Subpackages <1>: Subpackages. (line 6)\n* suffix .la, defined: Libtool Concept. (line 6)\n* suffix .lo, defined: Libtool Concept. (line 15)\n* SUFFIXES, adding: Suffixes. (line 6)\n* Support for C++: C++ Support. (line 6)\n* Support for Fortran 77: Fortran 77 Support. (line 6)\n* Support for Fortran 9x: Fortran 9x Support. (line 6)\n* Support for GNU Gettext: gettext. (line 6)\n* Support for Java with gcj: Java Support with gcj.\n(line 6)\n* Support for Objective C: Objective C Support. (line 6)\n* Support for Objective C++: Objective C++ Support.\n(line 6)\n* Support for Unified Parallel C: Unified Parallel C Support.\n(line 6)\n* Support for Vala: Vala Support. (line 6)\n* tags: Tags. (line 9)\n* TAGS support: Tags. (line 6)\n* tar formats: List of Automake options.\n(line 174)\n* tar-pax: List of Automake options.\n(line 174)\n* tar-ustar: List of Automake options.\n(line 174)\n* tar-v7: List of Automake options.\n(line 174)\n* Target, install-info: Texinfo. (line 85)\n* Target, install-man: Man Pages. (line 32)\n* targets, making into no-op: Third-Party Makefiles.\n(line 88)\n* test case: Generalities about Testing.\n(line 11)\n* Test case result, registering: Log files generation and test results recording.\n(line 24)\n* test failure: Generalities about Testing.\n(line 25)\n* test harness: Generalities about Testing.\n(line 18)\n* test metadata: Parallel Test Harness.\n(line 12)\n* test pass: Generalities about Testing.\n(line 25)\n* Test result, registering: Log files generation and test results recording.\n(line 24)\n* test skip: Generalities about Testing.\n(line 29)\n* Test suites: Tests. (line 6)\n* test-driver: Auxiliary Programs. (line 73)\n* Tests, expected failure: Scripts-based Testsuites.\n(line 32)\n* Testsuite environment overrides: Testsuite Environment Overrides.\n(line 6)\n* testsuite harness: Generalities about Testing.\n(line 18)\n* Testsuite progress on console: Scripts-based Testsuites.\n(line 45)\n* Texinfo flag, EDITION: Texinfo. (line 35)\n* Texinfo flag, UPDATED: Texinfo. (line 35)\n* Texinfo flag, UPDATED-MONTH: Texinfo. (line 35)\n* Texinfo flag, VERSION: Texinfo. (line 35)\n* texinfo.tex: Auxiliary Programs. (line 77)\n* texinfo.tex <1>: Texinfo. (line 70)\n* TEXINFOS primary, defined: Texinfo. (line 6)\n* third-party files and CVS: CVS. (line 167)\n* Third-party packages, interfacing with: Third-Party Makefiles.\n(line 6)\n* timestamps and CVS: CVS. (line 29)\n* Transforming program names: Renaming. (line 6)\n* trees, source vs. build: VPATH Builds. (line 6)\n* true Example: true. (line 6)\n* underquoted ACDEFUN: Extending aclocal. (line 36)\n* unexpected pass: Generalities about Testing.\n(line 39)\n* unexpected test pass: Generalities about Testing.\n(line 39)\n* Unified Parallel C support: Unified Parallel C Support.\n(line 6)\n* Uniform naming scheme: Uniform. (line 6)\n* uninstall: Standard Targets. (line 24)\n* uninstall <1>: Install Rules for the User.\n(line 7)\n* uninstall <2>: Extending. (line 41)\n* uninstall-hook: Extending. (line 66)\n* uninstall-local: Extending. (line 41)\n* Unit tests: Parallel Test Harness.\n(line 163)\n* Unpacking: Basic Installation. (line 27)\n* UPCFLAGS and AMUPCFLAGS: Flag Variables Ordering.\n(line 20)\n* UPDATED Texinfo flag: Texinfo. (line 35)\n* UPDATED-MONTH Texinfo flag: Texinfo. (line 35)\n* Use Cases for the GNU Build System: Use Cases. (line 6)\n* user variables: User Variables. (line 6)\n* Using aclocal: configure. (line 6)\n* ustar format: List of Automake options.\n(line 174)\n* v7 tar format: List of Automake options.\n(line 174)\n* Vala Support: Vala Support. (line 6)\n* variables, conflicting: Extending. (line 14)\n* Variables, overriding: General Operation. (line 51)\n* variables, reserved for the user: User Variables. (line 6)\n* VERSION Texinfo flag: Texinfo. (line 35)\n* VERSION, prevent definition: Public Macros. (line 54)\n* version.m4, example: Rebuilding. (line 12)\n* version.sh, example: Rebuilding. (line 12)\n* versioned binaries, installing: Extending. (line 86)\n* VPATH builds: VPATH Builds. (line 6)\n* wildcards: Wildcards. (line 6)\n* Windows: EXEEXT. (line 6)\n* xfail: Generalities about Testing.\n(line 39)\n* xpass: Generalities about Testing.\n(line 39)\n* xz: The Types of Distributions.\n(line 30)\n* yacc, multiple parsers: Yacc and Lex. (line 73)\n* YFLAGS and AMYFLAGS: Flag Variables Ordering.\n(line 20)\n* ylwrap: Auxiliary Programs. (line 85)\n* ylwrap <1>: Yacc and Lex. (line 73)\n* zardoz example: Complete. (line 35)\n* zip: The Types of Distributions.\n(line 37)\n* zstd: The Types of Distributions.\n(line 41)\n" } ] } }, "flags": [], "examples": [], "see_also": [] }