| \input texinfo @c -*-texinfo-*- |
| @c %**start of header |
| @setfilename automake-ng.info |
| @settitle automake-ng |
| @setchapternewpage off |
| @c %**end of header |
| |
| @include version.texi |
| |
| @c @ovar(ARG, DEFAULT) |
| @c ------------------- |
| @c The ARG is an optional argument. To be used for macro arguments in |
| @c their documentation (@defmac). |
| @macro ovar{varname} |
| @r{[}@var{\varname\}@r{]} |
| @end macro |
| |
| @set PACKAGE_BUGREPORT automake-ng@@gnu.org |
| |
| @copying |
| |
| This manual is for GNU Automake-NG (version @value{VERSION}, |
| @value{UPDATED}), a program that creates GNU standards-compliant |
| Makefiles from template files. |
| |
| Copyright @copyright{} 1995-2012 Free Software Foundation, Inc. |
| |
| @quotation |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, |
| Version 1.3 or any later version published by the Free Software |
| Foundation; with no Invariant Sections, with no Front-Cover texts, |
| and with no Back-Cover Texts. A copy of the license is included in the |
| section entitled ``GNU Free Documentation License.'' |
| |
| @end quotation |
| @end copying |
| |
| @dircategory Software development |
| @direntry |
| * Automake-NG: (automake-ng). Making GNU standards-compliant Makefiles. |
| @end direntry |
| |
| @dircategory Individual utilities |
| @direntry |
| * aclocal-invocation: (automake-ng)aclocal Invocation. Generating aclocal.m4. |
| * automake-invocation: (automake-ng)automake Invocation. Generating Makefile.in. |
| @end direntry |
| |
| @titlepage |
| @title GNU Automake-NG |
| @subtitle For version @value{VERSION}, @value{UPDATED} |
| @author David MacKenzie |
| @author Tom Tromey |
| @author Alexandre Duret-Lutz |
| @author Ralf Wildenhues |
| @author Stefano Lattarini |
| @page |
| @vskip 0pt plus 1filll |
| @insertcopying |
| @end titlepage |
| |
| @contents |
| |
| @c We use the following macros to define indices: |
| @c @cindex concepts, and anything that does not fit elsewhere |
| @c @vindex Makefile variables |
| @c @trindex targets |
| @c @acindex Autoconf/Automake/Libtool/M4/... macros |
| @c @opindex tool options |
| |
| @c Define an index of configure macros. |
| @defcodeindex ac |
| @c Define an index of options. |
| @defcodeindex op |
| @c Define an index of targets. |
| @defcodeindex tr |
| @c Define an index of commands. |
| @defcodeindex cm |
| |
| @c Put the macros in the function index. |
| @syncodeindex ac fn |
| |
| @c Put everything else into one index (arbitrarily chosen to be the |
| @c concept index). |
| @syncodeindex op cp |
| @syncodeindex tr cp |
| @syncodeindex cm cp |
| |
| @ifnottex |
| @node Top |
| @comment node-name, next, previous, up |
| @top GNU Automake-NG |
| |
| @insertcopying |
| |
| @menu |
| * Introduction:: Automake-NG's purpose |
| * Autotools Introduction:: An Introduction to the Autotools |
| * Generalities:: General ideas |
| * Examples:: Some example packages |
| * automake Invocation:: Creating a Makefile.in |
| * configure:: Scanning configure.ac, using aclocal |
| * Directories:: Declaring subdirectories |
| * Programs:: Building programs and libraries |
| * Other Objects:: Other derived objects |
| * Other GNU Tools:: Other GNU Tools |
| * Documentation:: Building documentation |
| * Install:: What gets installed |
| * Clean:: What gets cleaned |
| * Dist:: What goes in a distribution |
| * Tests:: Support for test suites |
| * Rebuilding:: Automatic rebuilding of Makefile |
| * Options:: Changing Automake's behavior |
| * Miscellaneous:: Miscellaneous rules |
| * Include:: Including extra files in an Automake template |
| * Conditionals:: Conditionals |
| * Silencing Make:: Obtain less verbose output from @command{make} |
| * Gnits:: The effect of @option{--gnu} and @option{--gnits} |
| * Not Enough:: When Automake is not Enough |
| * Distributing:: Distributing the Makefile.in |
| * API Versioning:: About compatibility between Automake versions |
| * Upgrading:: Upgrading to a Newer Automake Version |
| * FAQ:: Frequently Asked Questions |
| * Copying This Manual:: How to make copies of this manual |
| * Indices:: Indices of variables, macros, and concepts |
| |
| @detailmenu |
| --- The Detailed Node Listing --- |
| |
| An Introduction to the Autotools |
| |
| * GNU Build System:: Introducing the GNU Build System |
| * Use Cases:: Use Cases for the GNU Build System |
| * Why Autotools:: How Autotools Help |
| * Hello World:: A Small Hello World Package |
| |
| Use Cases for the GNU Build System |
| |
| * Basic Installation:: Common installation procedure |
| * Standard Targets:: A list of standard Makefile targets |
| * Standard Directory Variables:: A list of standard directory variables |
| * Standard Configuration Variables:: Using configuration variables |
| * config.site:: Using a config.site file |
| * VPATH Builds:: Parallel build trees |
| * Two-Part Install:: Installing data and programs separately |
| * Cross-Compilation:: Building for other architectures |
| * Renaming:: Renaming programs at install time |
| * DESTDIR:: Building binary packages with DESTDIR |
| * Preparing Distributions:: Rolling out tarballs |
| * Dependency Tracking:: Automatic dependency tracking |
| * Nested Packages:: The GNU Build Systems can be nested |
| |
| A Small Hello World |
| |
| * Creating amhello:: Create @file{amhello-1.0.tar.gz} from scratch |
| * amhello's configure.ac Setup Explained:: |
| * amhello's Makefile.am Setup Explained:: |
| |
| General ideas |
| |
| * General Operation:: General operation of Automake |
| * Strictness:: Standards conformance checking |
| * Uniform:: The Uniform Naming Scheme |
| * Length Limitations:: Staying below the command line length limit |
| * Canonicalization:: How derived variables are named |
| * User Variables:: Variables reserved for the user |
| * Auxiliary Programs:: Programs automake might require |
| |
| Some example packages |
| |
| * Complete:: A simple example, start to finish |
| * true:: Building true and false |
| |
| Scanning @file{configure.ac}, using @command{aclocal} |
| |
| * Requirements:: Configuration requirements |
| * Optional:: Other things Automake recognizes |
| * aclocal Invocation:: Auto-generating aclocal.m4 |
| * Macros:: Autoconf macros supplied with Automake |
| |
| Auto-generating aclocal.m4 |
| |
| * aclocal Options:: Options supported by aclocal |
| * Macro Search Path:: How aclocal finds .m4 files |
| * Extending aclocal:: Writing your own aclocal macros |
| * Local Macros:: Organizing local macros |
| * Serials:: Serial lines in Autoconf macros |
| * Future of aclocal:: aclocal's scheduled death |
| |
| Autoconf macros supplied with Automake |
| |
| * Public Macros:: Macros that you can use. |
| * Private Macros:: Macros that you should not use. |
| |
| Directories |
| |
| * Subdirectories:: Building subdirectories recursively |
| * Conditional Subdirectories:: Conditionally not building directories |
| * Alternative:: Subdirectories without recursion |
| * Subpackages:: Nesting packages |
| |
| Conditional Subdirectories |
| |
| * SUBDIRS vs DIST_SUBDIRS:: Two sets of directories |
| * Subdirectories with AM_CONDITIONAL:: Specifying conditional subdirectories |
| * Subdirectories with AC_SUBST:: Another way for conditional recursion |
| * Unconfigured Subdirectories:: Not even creating a @samp{Makefile} |
| |
| Building Programs and Libraries |
| |
| * A Program:: Building a program |
| * A Library:: Building a library |
| * A Shared Library:: Building a Libtool library |
| * Program and Library Variables:: Variables controlling program and |
| library builds |
| * Default _SOURCES:: Default source files |
| * LIBOBJS:: Special handling for LIBOBJS and ALLOCA |
| * Program Variables:: Variables used when building a program |
| * Yacc and Lex:: Yacc and Lex support |
| * C++ Support:: Compiling C++ sources |
| * Objective C Support:: Compiling Objective C sources |
| * Objective C++ Support:: Compiling Objective C++ sources |
| * Unified Parallel C Support:: Compiling Unified Parallel C sources |
| * Assembly Support:: Compiling assembly sources |
| * Fortran 77 Support:: Compiling Fortran 77 sources |
| * Fortran 9x Support:: Compiling Fortran 9x sources |
| * Java Support with gcj:: Compiling Java sources using gcj |
| * Vala Support:: Compiling Vala sources |
| * Support for Other Languages:: Compiling other languages |
| * Dependencies:: Automatic dependency tracking |
| * EXEEXT:: Support for executable extensions |
| |
| Building a program |
| |
| * Program Sources:: Defining program sources |
| * Linking:: Linking with libraries or extra objects |
| * Conditional Sources:: Handling conditional sources |
| * Conditional Programs:: Building a program conditionally |
| |
| Building a Shared Library |
| |
| * Libtool Concept:: Introducing Libtool |
| * Libtool Libraries:: Declaring Libtool Libraries |
| * Conditional Libtool Libraries:: Building Libtool Libraries Conditionally |
| * Conditional Libtool Sources:: Choosing Library Sources Conditionally |
| * Libtool Convenience Libraries:: Building Convenience Libtool Libraries |
| * Libtool Modules:: Building Libtool Modules |
| * Libtool Flags:: Using _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS |
| * LTLIBOBJS:: Using $(LTLIBOBJS) and $(LTALLOCA) |
| * Libtool Issues:: Common Issues Related to Libtool's Use |
| |
| Common Issues Related to Libtool's Use |
| |
| * Error required file ltmain.sh not found:: The need to run libtoolize |
| * Objects created both with libtool and without:: Avoid a specific build race |
| |
| Fortran 77 Support |
| |
| * Preprocessing Fortran 77:: Preprocessing Fortran 77 sources |
| * Compiling Fortran 77 Files:: Compiling Fortran 77 sources |
| * Mixing Fortran 77 With C and C++:: Mixing Fortran 77 With C and C++ |
| |
| Mixing Fortran 77 With C and C++ |
| |
| * How the Linker is Chosen:: Automatic linker selection |
| |
| Fortran 9x Support |
| |
| * Compiling Fortran 9x Files:: Compiling Fortran 9x sources |
| |
| Other Derived Objects |
| |
| * Scripts:: Executable scripts |
| * Headers:: Header files |
| * Data:: Architecture-independent data files |
| * Sources:: Derived sources |
| |
| Built Sources |
| |
| * Built Sources Example:: Several ways to handle built sources. |
| |
| Other GNU Tools |
| |
| * Emacs Lisp:: Emacs Lisp |
| * gettext:: Gettext |
| * Libtool:: Libtool |
| * Java:: Java bytecode compilation (deprecated) |
| * Python:: Python |
| |
| Building documentation |
| |
| * Texinfo:: Texinfo |
| * Man Pages:: Man pages |
| |
| What Gets Installed |
| |
| * Basics of Installation:: What gets installed where |
| * The Two Parts of Install:: Installing data and programs separately |
| * Extending Installation:: Adding your own rules for installation |
| * Staged Installs:: Installation in a temporary location |
| * Install Rules for the User:: Useful additional rules |
| |
| What Goes in a Distribution |
| |
| * Basics of Distribution:: Files distributed by default |
| * Fine-grained Distribution Control:: @code{dist_} and @code{nodist_} prefixes |
| * The dist Hook:: A target for last-minute distribution changes |
| * Checking the Distribution:: @samp{make distcheck} explained |
| * The Types of Distributions:: A variety of formats and compression methods |
| |
| Support for test suites |
| |
| * Generalities about Testing:: Generic concepts and terminology about testing |
| * Simple Tests:: Listing test scripts in @code{TESTS} |
| * Custom Test Drivers:: Writing and using custom test drivers |
| * Using the TAP test protocol:: Integrating test scripts that use the TAP protocol |
| * DejaGnu Tests:: Interfacing with the @command{dejagnu} testing framework |
| * Install Tests:: Running tests on installed packages |
| |
| Simple Tests |
| |
| * Scripts-based Testsuites:: Automake-specific concepts and terminology |
| * Serial Test Harness:: Older (and obsolescent) serial test harness |
| * Parallel Test Harness:: Generic concurrent test harness |
| |
| Using the TAP test protocol |
| |
| * Introduction to TAP:: |
| * Use TAP with the Automake test harness:: |
| * Incompatibilities with other TAP parsers and drivers:: |
| * Links and external resources on TAP:: |
| |
| Custom Test Drivers |
| |
| * Overview of Custom Test Drivers Support:: |
| * Declaring Custom Test Drivers:: |
| * API for Custom Test Drivers:: |
| |
| API for Custom Test Drivers |
| |
| * Command-line arguments for test drivers:: |
| * Log files generation and test results recording:: |
| * Testsuite progress output:: |
| |
| Changing Automake's Behavior |
| |
| * Options generalities:: Semantics of Automake option |
| * List of Automake options:: A comprehensive list of Automake options |
| |
| Miscellaneous Rules |
| |
| * Tags:: Interfacing to cscope, etags and mkid |
| * Suffixes:: Handling new file extensions |
| |
| Conditionals |
| |
| * Usage of Conditionals:: Declaring conditional content |
| * Limits of Conditionals:: Enclosing complete statements |
| |
| Silencing Make |
| |
| * Make verbosity:: Make is verbose by default |
| * Tricks For Silencing Make:: Standard and generic ways to silence make |
| * Automake Silent Rules:: How Automake can help in silencing make |
| |
| When Automake Isn't Enough |
| |
| * Extending:: Adding new rules or overriding existing ones. |
| * Third-Party Makefiles:: Integrating Non-Automake @file{Makefile}s. |
| |
| Frequently Asked Questions about Automake |
| |
| * CVS:: CVS and generated files |
| * maintainer tools:: The missing script and maintainer tools |
| * Wildcards:: Why doesn't Automake support wildcards? |
| * Limitations on File Names:: Limitations on source and installed file names |
| * Errors with distclean:: Files left in build directory after distclean |
| * Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS |
| * Renamed Objects:: Why are object files sometimes renamed? |
| * Per-Object Flags:: How to simulate per-object flags? |
| * Multiple Outputs:: Writing rules for tools with many output files |
| * Hard-Coded Install Paths:: Installing to hard-coded locations |
| * Debugging Make Rules:: Strategies when things don't work as expected |
| * Reporting Bugs:: Feedback on bugs and feature requests |
| |
| Copying This Manual |
| |
| * GNU Free Documentation License:: License for copying this manual |
| |
| Indices |
| |
| * Macro Index:: Index of Autoconf macros |
| * Variable Index:: Index of Makefile variables |
| * General Index:: General index |
| |
| @end detailmenu |
| @end menu |
| |
| @end ifnottex |
| |
| |
| @node Introduction |
| @chapter Introduction |
| |
| Automake-NG is a tool for automatically generating @file{Makefile.in}s |
| from files called @file{Makefile.am}. Each @file{Makefile.am} is |
| basically a series of @command{make} variable |
| definitions@footnote{These variables are also called @dfn{make macros} |
| in Make terminology, however in this manual we reserve the term |
| @dfn{macro} for Autoconf's macros.}, with rules being thrown in |
| occasionally. The generated @file{Makefile.in}s are compliant with |
| the GNU Makefile standards. |
| |
| @cindex GNU Makefile standards |
| |
| The GNU Makefile Standards Document |
| (@pxref{Makefile Conventions, , , standards, The GNU Coding Standards}) |
| is long, complicated, and subject to change. The goal of Automake-NG |
| is to remove the burden of Makefile maintenance from the back of the |
| individual GNU maintainer (and put it on the back of the Automake-NG |
| maintainers). |
| |
| The typical Automake-NG input file is simply a series of variable |
| definitions. Each such file is processed to create a @file{Makefile.in}. |
| There should generally be one @file{Makefile.am} per directory of a |
| project. |
| |
| @cindex Constraints of Automake-NG |
| @cindex Automake-NG constraints |
| @cindex Constraints of Automake |
| @cindex Automake constraints |
| |
| Automake-NG does constrain a project in certain ways; for instance, it |
| assumes that the project uses Autoconf (@pxref{Top, , Introduction, |
| autoconf, The Autoconf Manual}), and enforces certain restrictions on |
| the @file{configure.ac} contents. |
| |
| @cindex Automake-NG requirements |
| @cindex Requirements, Automake-NG |
| @cindex Automake requirements |
| @cindex Requirements, Automake |
| |
| Automake-NG requires @command{perl} in order to generate the |
| @file{Makefile.in}s. However, the distributions created by Automake-NG |
| are fully GNU standards-compliant, and do not require @command{perl} in |
| order to be built. |
| |
| @cindex Bugs, reporting |
| @cindex Reporting bugs |
| @cindex E-mail, bug reports |
| |
| For more information on bug reports, @xref{Reporting Bugs}. |
| |
| @node Autotools Introduction |
| @chapter An Introduction to the Autotools |
| |
| If you are new to Automake-NG, maybe you know that it is part of a set of |
| tools called @emph{The Autotools}. Maybe you've already delved into a |
| package full of files named @file{configure}, @file{configure.ac}, |
| @file{Makefile.in}, @file{Makefile.am}, @file{aclocal.m4}, @dots{}, |
| some of them claiming to be @emph{generated by} Autoconf or Automake-NG. |
| But the exact purpose of these files and their relations is probably |
| fuzzy. The goal of this chapter is to introduce you to this machinery, |
| to show you how it works and how powerful it is. If you've never |
| installed or seen such a package, do not worry: this chapter will walk |
| you through it. |
| |
| If you need some teaching material, more illustrations, or a less |
| @command{automake}-centered continuation, some slides for this |
| introduction are available in Alexandre Duret-Lutz's |
| @uref{http://www.lrde.epita.fr/@/~adl/@/autotools.html, |
| Autotools Tutorial}. |
| This chapter is the written version of the first part of his tutorial. |
| |
| @menu |
| * GNU Build System:: Introducing the GNU Build System |
| * Use Cases:: Use Cases for the GNU Build System |
| * Why Autotools:: How Autotools Help |
| * Hello World:: A Small Hello World Package |
| @end menu |
| |
| @node GNU Build System |
| @section Introducing the GNU Build System |
| @cindex GNU Build System, introduction |
| |
| It is a truth universally acknowledged, that as a developer in |
| possession of a new package, you must be in want of a build system. |
| |
| In the Unix world, such a build system is traditionally achieved using |
| the command @command{make} (@pxref{Top, , Overview, make, The GNU Make |
| Manual}). You express the recipe to build your package in a |
| @file{Makefile}. This file is a set of rules to build the files in |
| the package. For instance the program @file{prog} may be built by |
| running the linker on the files @file{main.o}, @file{foo.o}, and |
| @file{bar.o}; the file @file{main.o} may be built by running the |
| compiler on @file{main.c}; etc. Each time @command{make} is run, it |
| reads @file{Makefile}, checks the existence and modification time of |
| the files mentioned, decides what files need to be built (or rebuilt), |
| and runs the associated commands. |
| |
| When a package needs to be built on a different platform than the one |
| it was developed on, its @file{Makefile} usually needs to be adjusted. |
| For instance the compiler may have another name or require more |
| options. In 1991, David J. MacKenzie got tired of customizing |
| @file{Makefile} for the 20 platforms he had to deal with. Instead, he |
| handcrafted a little shell script called @file{configure} to |
| automatically adjust the @file{Makefile} (@pxref{Genesis, , Genesis, |
| autoconf, The Autoconf Manual}). Compiling his package was now |
| as simple as running @code{./configure && make}. |
| |
| @cindex GNU Coding Standards |
| |
| Today this process has been standardized in the GNU project. The GNU |
| Coding Standards (@pxref{Managing Releases, The Release Process, , |
| standards, The GNU Coding Standards}) explains how each package of the |
| GNU project should have a @file{configure} script, and the minimal |
| interface it should have. The @file{Makefile} too should follow some |
| established conventions. The result? A unified build system that |
| makes all packages almost indistinguishable by the installer. In its |
| simplest scenario, all the installer has to do is to unpack the |
| package, run @code{./configure && make && make install}, and repeat |
| with the next package to install. |
| |
| We call this build system the @dfn{GNU Build System}, since it was |
| grown out of the GNU project. However it is used by a vast number of |
| other packages: following any existing convention has its advantages. |
| |
| @cindex Autotools, introduction |
| |
| The Autotools are tools that will create a GNU Build System for your |
| package. Autoconf mostly focuses on @file{configure} and Automake-NG |
| on @file{Makefile}s. It is entirely possible to create a GNU Build |
| System without the help of these tools. However it is rather |
| burdensome and error-prone. We will discuss this again after some |
| illustration of the GNU Build System in action. |
| |
| @node Use Cases |
| @section Use Cases for the GNU Build System |
| @cindex GNU Build System, use cases |
| @cindex GNU Build System, features |
| @cindex Features of the GNU Build System |
| @cindex Use Cases for the GNU Build System |
| @cindex @file{amhello-1.0.tar.gz}, location |
| @cindex @file{amhello-1.0.tar.gz}, use cases |
| |
| In this section we explore several use cases for the GNU Build System. |
| You can replay all of these examples on the @file{amhello-1.0.tar.gz} |
| package distributed with Automake-NG. If Automake-NG is installed on |
| your system, you should find a copy of this file in |
| @file{@var{prefix}/share/doc/automake/amhello-1.0.tar.gz}, where |
| @var{prefix} is the installation prefix specified during configuration |
| (@var{prefix} defaults to @file{/usr/local}, however if Automake-NG was |
| installed by some GNU/Linux distribution it most likely has been set |
| to @file{/usr}). If you do not have a copy of Automake-NG installed, |
| you can find a copy of this file inside the @file{doc/} directory of |
| the Automake-NG package. |
| |
| Some of the following use cases present features that are in fact |
| extensions to the GNU Build System. Read: they are not specified by |
| the GNU Coding Standards, but they are nonetheless part of the build |
| system created by the Autotools. To keep things simple, we do not |
| point out the difference. Our objective is to show you many of the |
| features that the build system created by the Autotools will offer to |
| you. |
| |
| @menu |
| * Basic Installation:: Common installation procedure |
| * Standard Targets:: A list of standard Makefile targets |
| * Standard Directory Variables:: A list of standard directory variables |
| * Standard Configuration Variables:: Using configuration variables |
| * config.site:: Using a config.site file |
| * VPATH Builds:: Parallel build trees |
| * Two-Part Install:: Installing data and programs separately |
| * Cross-Compilation:: Building for other architectures |
| * Renaming:: Renaming programs at install time |
| * DESTDIR:: Building binary packages with DESTDIR |
| * Preparing Distributions:: Rolling out tarballs |
| * Dependency Tracking:: Automatic dependency tracking |
| * Nested Packages:: The GNU Build Systems can be nested |
| @end menu |
| |
| @node Basic Installation |
| @subsection Basic Installation |
| @cindex Configuration, basics |
| @cindex Installation, basics |
| @cindex GNU Build System, basics |
| |
| The most common installation procedure looks as follows. |
| |
| @example |
| ~ % @kbd{tar zxf amhello-1.0.tar.gz} |
| ~ % @kbd{cd amhello-1.0} |
| ~/amhello-1.0 % @kbd{./configure} |
| @dots{} |
| config.status: creating Makefile |
| config.status: creating src/Makefile |
| @dots{} |
| ~/amhello-1.0 % @kbd{make} |
| @dots{} |
| ~/amhello-1.0 % @kbd{make check} |
| @dots{} |
| ~/amhello-1.0 % @kbd{su} |
| Password: |
| /home/adl/amhello-1.0 # @kbd{make install} |
| @dots{} |
| /home/adl/amhello-1.0 # @kbd{exit} |
| ~/amhello-1.0 % @kbd{make installcheck} |
| @dots{} |
| @end example |
| |
| @cindex Unpacking |
| |
| The user first unpacks the package. Here, and in the following |
| examples, we will use the non-portable @code{tar zxf} command for |
| simplicity. On a system without GNU @command{tar} installed, this |
| command should read @code{gunzip -c amhello-1.0.tar.gz | tar xf -}. |
| |
| The user then enters the newly created directory to run the |
| @file{configure} script. This script probes the system for various |
| features, and finally creates the @file{Makefile}s. In this toy |
| example there are only two @file{Makefile}s, but in real-world projects, |
| there may be many more, usually one @file{Makefile} per directory. |
| |
| It is now possible to run @code{make}. This will construct all the |
| programs, libraries, and scripts that need to be constructed for the |
| package. In our example, this compiles the @file{hello} program. |
| All files are constructed in place, in the source tree; we will see |
| later how this can be changed. |
| |
| @code{make check} causes the package's tests to be run. This step is |
| not mandatory, but it is often good to make sure the programs that |
| have been built behave as they should, before you decide to install |
| them. Our example does not contain any tests, so running @code{make |
| check} is a no-op. |
| |
| @cindex su, before @code{make install} |
| After everything has been built, and maybe tested, it is time to |
| install it on the system. That means copying the programs, |
| libraries, header files, scripts, and other data files from the |
| source directory to their final destination on the system. The |
| command @code{make install} will do that. However, by default |
| everything will be installed in subdirectories of @file{/usr/local}: |
| binaries will go into @file{/usr/local/bin}, libraries will end up in |
| @file{/usr/local/lib}, etc. This destination is usually not writable |
| by any user, so we assume that we have to become root before we can |
| run @code{make install}. In our example, running @code{make install} |
| will copy the program @file{hello} into @file{/usr/local/bin} |
| and @file{README} into @file{/usr/local/share/doc/amhello}. |
| |
| A last and optional step is to run @code{make installcheck}. This |
| command may run tests on the installed files. @code{make check} tests |
| the files in the source tree, while @code{make installcheck} tests |
| their installed copies. The tests run by the latter can be different |
| from those run by the former. For instance, there are tests that |
| cannot be run in the source tree. Conversely, some packages are set |
| up so that @code{make installcheck} will run the very same tests as |
| @code{make check}, only on different files (non-installed |
| vs.@: installed). It can make a difference, for instance when the |
| source tree's layout is different from that of the installation. |
| Furthermore it may help to diagnose an incomplete installation. |
| |
| Presently most packages do not have any @code{installcheck} tests |
| because the existence of @code{installcheck} is little known, and its |
| usefulness is neglected. Our little toy package is no better: @code{make |
| installcheck} does nothing. |
| |
| @node Standard Targets |
| @subsection Standard @file{Makefile} Targets |
| |
| So far we have come across four ways to run @command{make} in the GNU |
| Build System: @code{make}, @code{make check}, @code{make install}, and |
| @code{make installcheck}. The words @code{check}, @code{install}, and |
| @code{installcheck}, passed as arguments to @command{make}, are called |
| @dfn{targets}. @code{make} is a shorthand for @code{make all}, |
| @code{all} being the default target in the GNU Build System. |
| |
| Here is a list of the most useful targets that the GNU Coding Standards |
| specify. |
| |
| @table @code |
| @item make all |
| @trindex all |
| Build programs, libraries, documentation, etc.@: (same as @code{make}). |
| @item make install |
| @trindex install |
| Install what needs to be installed, copying the files from the |
| package's tree to system-wide directories. |
| @item make install-strip |
| @trindex install-strip |
| Same as @code{make install}, then strip debugging symbols. Some |
| users like to trade space for useful bug reports@enddots{} |
| @item make uninstall |
| @trindex uninstall |
| The opposite of @code{make install}: erase the installed files. |
| (This needs to be run from the same build tree that was installed.) |
| @item make clean |
| @trindex clean |
| Erase from the build tree the files built by @code{make all}. |
| @item make distclean |
| @trindex distclean |
| Additionally erase anything @code{./configure} created. |
| @item make check |
| @trindex check |
| Run the test suite, if any. |
| @item make installcheck |
| @trindex installcheck |
| Check the installed programs or libraries, if supported. |
| @item make dist |
| @trindex dist |
| Recreate @file{@var{package}-@var{version}.tar.gz} from all the source |
| files. |
| @end table |
| |
| @node Standard Directory Variables |
| @subsection Standard Directory Variables |
| @cindex directory variables |
| |
| The GNU Coding Standards also specify a hierarchy of variables to |
| denote installation directories. Some of these are: |
| |
| @multitable {Directory variable} {@code{$@{datarootdir@}/doc/$@{PACKAGE@}}} |
| @headitem Directory variable @tab Default value |
| @item @code{prefix} @tab @code{/usr/local} |
| @item @w{@ @ @code{exec_prefix}} @tab @code{$@{prefix@}} |
| @item @w{@ @ @ @ @code{bindir}} @tab @code{$@{exec_prefix@}/bin} |
| @item @w{@ @ @ @ @code{libdir}} @tab @code{$@{exec_prefix@}/lib} |
| @item @w{@ @ @ @ @dots{}} |
| @item @w{@ @ @code{includedir}} @tab @code{$@{prefix@}/include} |
| @item @w{@ @ @code{datarootdir}} @tab @code{$@{prefix@}/share} |
| @item @w{@ @ @ @ @code{datadir}} @tab @code{$@{datarootdir@}} |
| @item @w{@ @ @ @ @code{mandir}} @tab @code{$@{datarootdir@}/man} |
| @item @w{@ @ @ @ @code{infodir}} @tab @code{$@{datarootdir@}/info} |
| @item @w{@ @ @ @ @code{docdir}} @tab @code{$@{datarootdir@}/doc/$@{PACKAGE@}} |
| @item @w{@ @ @dots{}} |
| @end multitable |
| |
| @c We should provide a complete table somewhere, but not here. The |
| @c complete list of directory variables it too confusing as-is. It |
| @c requires some explanations that are too complicated for this |
| @c introduction. Besides listing directories like localstatedir |
| @c would make the explanations in ``Two-Part Install'' harder. |
| |
| Each of these directories has a role which is often obvious from its |
| name. In a package, any installable file will be installed in one of |
| these directories. For instance in @code{amhello-1.0}, the program |
| @file{hello} is to be installed in @var{bindir}, the directory for |
| binaries. The default value for this directory is |
| @file{/usr/local/bin}, but the user can supply a different value when |
| calling @command{configure}. Also the file @file{README} will be |
| installed into @var{docdir}, which defaults to |
| @file{/usr/local/share/doc/amhello}. |
| |
| @opindex --prefix |
| |
| As a user, if you wish to install a package on your own account, you |
| could proceed as follows: |
| |
| @example |
| ~/amhello-1.0 % @kbd{./configure --prefix ~/usr} |
| @dots{} |
| ~/amhello-1.0 % @kbd{make} |
| @dots{} |
| ~/amhello-1.0 % @kbd{make install} |
| @dots{} |
| @end example |
| |
| This would install @file{~/usr/bin/hello} and |
| @file{~/usr/share/doc/amhello/README}. |
| |
| The list of all such directory options is shown by |
| @code{./configure --help}. |
| |
| @node Standard Configuration Variables |
| @subsection Standard Configuration Variables |
| @cindex configuration variables, overriding |
| |
| The GNU Coding Standards also define a set of standard configuration |
| variables used during the build. Here are some: |
| |
| @table @asis |
| @item @code{CC} |
| C compiler command |
| @item @code{CFLAGS} |
| C compiler flags |
| @item @code{CXX} |
| C++ compiler command |
| @item @code{CXXFLAGS} |
| C++ compiler flags |
| @item @code{LDFLAGS} |
| linker flags |
| @item @code{CPPFLAGS} |
| C/C++ preprocessor flags |
| @item @dots{} |
| @end table |
| |
| @command{configure} usually does a good job at setting appropriate |
| values for these variables, but there are cases where you may want to |
| override them. For instance you may have several versions of a |
| compiler installed and would like to use another one, you may have |
| header files installed outside the default search path of the |
| compiler, or even libraries out of the way of the linker. |
| |
| Here is how one would call @command{configure} to force it to use |
| @command{gcc-3} as C compiler, use header files from |
| @file{~/usr/include} when compiling, and libraries from |
| @file{~/usr/lib} when linking. |
| |
| @example |
| ~/amhello-1.0 % @kbd{./configure --prefix ~/usr CC=gcc-3 \ |
| CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib} |
| @end example |
| |
| Again, a full list of these variables appears in the output of |
| @code{./configure --help}. |
| |
| @node config.site |
| @subsection Overriding Default Configuration Setting with @file{config.site} |
| @cindex @file{config.site} example |
| |
| When installing several packages using the same setup, it can be |
| convenient to create a file to capture common settings. |
| If a file named @file{@var{prefix}/share/config.site} exists, |
| @command{configure} will source it at the beginning of its execution. |
| |
| Recall the command from the previous section: |
| |
| @example |
| ~/amhello-1.0 % @kbd{./configure --prefix ~/usr CC=gcc-3 \ |
| CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib} |
| @end example |
| |
| Assuming we are installing many package in @file{~/usr}, and will |
| always want to use these definitions of @code{CC}, @code{CPPFLAGS}, and |
| @code{LDFLAGS}, we can automate this by creating the following |
| @file{~/usr/share/config.site} file: |
| |
| @example |
| test -z "$CC" && CC=gcc-3 |
| test -z "$CPPFLAGS" && CPPFLAGS=-I$HOME/usr/include |
| test -z "$LDFLAGS" && LDFLAGS=-L$HOME/usr/lib |
| @end example |
| |
| Now, any time a @file{configure} script is using the @file{~/usr} |
| prefix, it will execute the above @file{config.site} and define |
| these three variables. |
| |
| @example |
| ~/amhello-1.0 % @kbd{./configure --prefix ~/usr} |
| configure: loading site script /home/adl/usr/share/config.site |
| @dots{} |
| @end example |
| |
| @xref{Site Defaults, , Setting Site Defaults, autoconf, The Autoconf |
| Manual}, for more information about this feature. |
| |
| |
| @node VPATH Builds |
| @subsection Parallel Build Trees (a.k.a.@: VPATH Builds) |
| @cindex Parallel build trees |
| @cindex VPATH builds |
| @cindex source tree and build tree |
| @cindex build tree and source tree |
| @cindex trees, source vs.@: build |
| |
| The GNU Build System distinguishes two trees: the source tree, and |
| the build tree. |
| |
| The source tree is rooted in the directory containing |
| @file{configure}. It contains all the sources files (those that are |
| distributed), and may be arranged using several subdirectories. |
| |
| The build tree is rooted in the directory in which @file{configure} |
| was run, and is populated with all object files, programs, libraries, |
| and other derived files built from the sources (and hence not |
| distributed). The build tree usually has the same subdirectory layout |
| as the source tree; its subdirectories are created automatically by |
| the build system. |
| |
| If @file{configure} is executed in its own directory, the source and |
| build trees are combined: derived files are constructed in the same |
| directories as their sources. This was the case in our first |
| installation example (@pxref{Basic Installation}). |
| |
| A common request from users is that they want to confine all derived |
| files to a single directory, to keep their source directories |
| uncluttered. Here is how we could run @file{configure} to build |
| everything in a subdirectory called @file{build/}. |
| |
| @example |
| ~ % @kbd{tar zxf ~/amhello-1.0.tar.gz} |
| ~ % @kbd{cd amhello-1.0} |
| ~/amhello-1.0 % @kbd{mkdir build && cd build} |
| ~/amhello-1.0/build % @kbd{../configure} |
| @dots{} |
| ~/amhello-1.0/build % @kbd{make} |
| @dots{} |
| @end example |
| |
| These setups, where source and build trees are different, are often |
| called @dfn{parallel builds} or @dfn{VPATH builds}. The expression |
| @emph{parallel build} is misleading: the word @emph{parallel} is a |
| reference to the way the build tree shadows the source tree, it is not |
| about some concurrency in the way build commands are run. For this |
| reason we refer to such setups using the name @emph{VPATH builds} in |
| the following. @emph{VPATH} is the name of the @command{make} feature |
| used by the @file{Makefile}s to allow these builds (@pxref{General |
| Search, , @code{VPATH} Search Path for All Prerequisites, make, The |
| GNU Make Manual}). |
| |
| @cindex multiple configurations, example |
| @cindex debug build, example |
| @cindex optimized build, example |
| |
| VPATH builds have other interesting uses. One is to build the same |
| sources with multiple configurations. For instance: |
| |
| @c Keep in sync with amhello-cflags.sh |
| @example |
| ~ % @kbd{tar zxf ~/amhello-1.0.tar.gz} |
| ~ % @kbd{cd amhello-1.0} |
| ~/amhello-1.0 % @kbd{mkdir debug optim && cd debug} |
| ~/amhello-1.0/debug % @kbd{../configure CFLAGS='-g -O0'} |
| @dots{} |
| ~/amhello-1.0/debug % @kbd{make} |
| @dots{} |
| ~/amhello-1.0/debug % cd ../optim |
| ~/amhello-1.0/optim % @kbd{../configure CFLAGS='-O3 -fomit-frame-pointer'} |
| @dots{} |
| ~/amhello-1.0/optim % @kbd{make} |
| @dots{} |
| @end example |
| |
| With network file systems, a similar approach can be used to build the |
| same sources on different machines. For instance, suppose that the |
| sources are installed on a directory shared by two hosts: @code{HOST1} |
| and @code{HOST2}, which may be different platforms. |
| |
| @example |
| ~ % @kbd{cd /nfs/src} |
| /nfs/src % @kbd{tar zxf ~/amhello-1.0.tar.gz} |
| @end example |
| |
| On the first host, you could create a local build directory: |
| @example |
| [HOST1] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh} |
| [HOST1] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure} |
| ... |
| [HOST1] /tmp/amh % @kbd{make && sudo make install} |
| ... |
| @end example |
| |
| @noindent |
| (Here we assume that the installer has configured @command{sudo} so it |
| can execute @code{make install} with root privileges; it is more convenient |
| than using @command{su} like in @ref{Basic Installation}). |
| |
| On the second host, you would do exactly the same, possibly at |
| the same time: |
| @example |
| [HOST2] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh} |
| [HOST2] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure} |
| ... |
| [HOST2] /tmp/amh % @kbd{make && sudo make install} |
| ... |
| @end example |
| |
| @cindex read-only source tree |
| @cindex source tree, read-only |
| |
| In this scenario, nothing forbids the @file{/nfs/src/amhello-1.0} |
| directory from being read-only. In fact VPATH builds are also a means |
| of building packages from a read-only medium such as a CD-ROM. (The |
| FSF used to sell CD-ROM with unpacked source code, before the GNU |
| project grew so big.) |
| |
| @node Two-Part Install |
| @subsection Two-Part Installation |
| |
| In our last example (@pxref{VPATH Builds}), a source tree was shared |
| by two hosts, but compilation and installation were done separately on |
| each host. |
| |
| The GNU Build System also supports networked setups where part of the |
| installed files should be shared amongst multiple hosts. It does so |
| by distinguishing architecture-dependent files from |
| architecture-independent files, and providing two @file{Makefile} |
| targets to install each of these classes of files. |
| |
| @trindex install-exec |
| @trindex install-data |
| |
| These targets are @code{install-exec} for architecture-dependent files |
| and @code{install-data} for architecture-independent files. |
| The command we used up to now, @code{make install}, can be thought of |
| as a shorthand for @code{make install-exec install-data}. |
| |
| From the GNU Build System point of view, the distinction between |
| architecture-dependent files and architecture-independent files is |
| based exclusively on the directory variable used to specify their |
| installation destination. In the list of directory variables we |
| provided earlier (@pxref{Standard Directory Variables}), all the |
| variables based on @var{exec-prefix} designate architecture-dependent |
| directories whose files will be installed by @code{make install-exec}. |
| The others designate architecture-independent directories and will |
| serve files installed by @code{make install-data}. @xref{The Two Parts |
| of Install}, for more details. |
| |
| Here is how we could revisit our two-host installation example, |
| assuming that (1) we want to install the package directly in |
| @file{/usr}, and (2) the directory @file{/usr/share} is shared by the |
| two hosts. |
| |
| On the first host we would run |
| @example |
| [HOST1] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh} |
| [HOST1] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure --prefix /usr} |
| ... |
| [HOST1] /tmp/amh % @kbd{make && sudo make install} |
| ... |
| @end example |
| |
| On the second host, however, we need only install the |
| architecture-specific files. |
| @example |
| [HOST2] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh} |
| [HOST2] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure --prefix /usr} |
| ... |
| [HOST2] /tmp/amh % @kbd{make && sudo make install-exec} |
| ... |
| @end example |
| |
| In packages that have installation checks, it would make sense to run |
| @code{make installcheck} (@pxref{Basic Installation}) to verify that |
| the package works correctly despite the apparent partial installation. |
| |
| @node Cross-Compilation |
| @subsection Cross-Compilation |
| @cindex cross-compilation |
| |
| To @dfn{cross-compile} is to build on one platform a binary that will |
| run on another platform. When speaking of cross-compilation, it is |
| important to distinguish between the @dfn{build platform} on which |
| the compilation is performed, and the @dfn{host platform} on which the |
| resulting executable is expected to run. The following |
| @command{configure} options are used to specify each of them: |
| |
| @table @option |
| @item --build=@var{build} |
| @opindex --build=@var{build} |
| The system on which the package is built. |
| @item --host=@var{host} |
| @opindex --host=@var{host} |
| The system where built programs and libraries will run. |
| @end table |
| |
| When the @option{--host} is used, @command{configure} will search for |
| the cross-compiling suite for this platform. Cross-compilation tools |
| commonly have their target architecture as prefix of their name. For |
| instance my cross-compiler for MinGW32 has its binaries called |
| @code{i586-mingw32msvc-gcc}, @code{i586-mingw32msvc-ld}, |
| @code{i586-mingw32msvc-as}, etc. |
| |
| @cindex MinGW cross-compilation example |
| @cindex cross-compilation example |
| |
| Here is how we could build @code{amhello-1.0} for |
| @code{i586-mingw32msvc} on a GNU/Linux PC. |
| |
| @c Keep in sync with amhello-cross-compile.sh |
| @smallexample |
| ~/amhello-1.0 % @kbd{./configure --build i686-pc-linux-gnu --host i586-mingw32msvc} |
| checking for a BSD-compatible install... /usr/bin/install -c |
| checking whether build environment is sane... yes |
| checking for gawk... gawk |
| checking whether make sets $(MAKE)... yes |
| checking for i586-mingw32msvc-strip... i586-mingw32msvc-strip |
| checking for i586-mingw32msvc-gcc... i586-mingw32msvc-gcc |
| checking for C compiler default output file name... a.exe |
| checking whether the C compiler works... yes |
| checking whether we are cross compiling... yes |
| checking for suffix of executables... .exe |
| checking for suffix of object files... o |
| checking whether we are using the GNU C compiler... yes |
| checking whether i586-mingw32msvc-gcc accepts -g... yes |
| checking for i586-mingw32msvc-gcc option to accept ANSI C... |
| @dots{} |
| ~/amhello-1.0 % @kbd{make} |
| @dots{} |
| ~/amhello-1.0 % @kbd{cd src; file hello.exe} |
| hello.exe: MS Windows PE 32-bit Intel 80386 console executable not relocatable |
| @end smallexample |
| |
| The @option{--host} and @option{--build} options are usually all we |
| need for cross-compiling. The only exception is if the package being |
| built is itself a cross-compiler: we need a third option to specify |
| its target architecture. |
| |
| @table @option |
| @item --target=@var{target} |
| @opindex --target=@var{target} |
| When building compiler tools: the system for which the tools will |
| create output. |
| @end table |
| |
| For instance when installing GCC, the GNU Compiler Collection, we can |
| use @option{--target=@/@var{target}} to specify that we want to build |
| GCC as a cross-compiler for @var{target}. Mixing @option{--build} and |
| @option{--target}, we can actually cross-compile a cross-compiler; |
| such a three-way cross-compilation is known as a @dfn{Canadian cross}. |
| |
| @xref{Specifying Names, , Specifying the System Type, autoconf, The |
| Autoconf Manual}, for more information about these @command{configure} |
| options. |
| |
| @node Renaming |
| @subsection Renaming Programs at Install Time |
| @cindex Renaming programs |
| @cindex Transforming program names |
| @cindex Programs, renaming during installation |
| |
| The GNU Build System provides means to automatically rename |
| executables and manpages before they are installed (@pxref{Man Pages}). |
| This is especially convenient |
| when installing a GNU package on a system that already has a |
| proprietary implementation you do not want to overwrite. For instance, |
| you may want to install GNU @command{tar} as @command{gtar} so you can |
| distinguish it from your vendor's @command{tar}. |
| |
| This can be done using one of these three @command{configure} options. |
| |
| @table @option |
| @item --program-prefix=@var{prefix} |
| @opindex --program-prefix=@var{prefix} |
| Prepend @var{prefix} to installed program names. |
| @item --program-suffix=@var{suffix} |
| @opindex --program-suffix=@var{suffix} |
| Append @var{suffix} to installed program names. |
| @item --program-transform-name=@var{program} |
| @opindex --program-transform-name=@var{program} |
| Run @code{sed @var{program}} on installed program names. |
| @end table |
| |
| The following commands would install @file{hello} |
| as @file{/usr/local/bin/test-hello}, for instance. |
| |
| @example |
| ~/amhello-1.0 % @kbd{./configure --program-prefix test-} |
| @dots{} |
| ~/amhello-1.0 % @kbd{make} |
| @dots{} |
| ~/amhello-1.0 % @kbd{sudo make install} |
| @dots{} |
| @end example |
| |
| @node DESTDIR |
| @subsection Building Binary Packages Using DESTDIR |
| @vindex DESTDIR |
| |
| The GNU Build System's @code{make install} and @code{make uninstall} |
| interface does not exactly fit the needs of a system administrator |
| who has to deploy and upgrade packages on lots of hosts. In other |
| words, the GNU Build System does not replace a package manager. |
| |
| Such package managers usually need to know which files have been |
| installed by a package, so a mere @code{make install} is |
| inappropriate. |
| |
| @cindex Staged installation |
| |
| The @code{DESTDIR} variable can be used to perform a staged |
| installation. The package should be configured as if it was going to |
| be installed in its final location (e.g., @code{--prefix /usr}), but |
| when running @code{make install}, the @code{DESTDIR} should be set to |
| the absolute name of a directory into which the installation will be |
| diverted. From this directory it is easy to review which files are |
| being installed where, and finally copy them to their final location |
| by some means. |
| |
| @cindex Binary package |
| |
| For instance here is how we could create a binary package containing a |
| snapshot of all the files to be installed. |
| |
| @c Keep in sync with amhello-binpkg.sh |
| @example |
| ~/amhello-1.0 % @kbd{./configure --prefix /usr} |
| @dots{} |
| ~/amhello-1.0 % @kbd{make} |
| @dots{} |
| ~/amhello-1.0 % @kbd{make DESTDIR=$HOME/inst install} |
| @dots{} |
| ~/amhello-1.0 % @kbd{cd ~/inst} |
| ~/inst % @kbd{find . -type f -print > ../files.lst} |
| ~/inst % @kbd{tar zcvf ~/amhello-1.0-i686.tar.gz `cat ../files.lst`} |
| ./usr/bin/hello |
| ./usr/share/doc/amhello/README |
| @end example |
| |
| After this example, @code{amhello-1.0-i686.tar.gz} is ready to be |
| uncompressed in @file{/} on many hosts. (Using @code{`cat ../files.lst`} |
| instead of @samp{.} as argument for @command{tar} avoids entries for |
| each subdirectory in the archive: we would not like @command{tar} to |
| restore the modification time of @file{/}, @file{/usr/}, etc.) |
| |
| Note that when building packages for several architectures, it might |
| be convenient to use @code{make install-data} and @code{make |
| install-exec} (@pxref{Two-Part Install}) to gather |
| architecture-independent files in a single package. |
| |
| @xref{Install}, for more information. |
| |
| @c We should document PRE_INSTALL/POST_INSTALL/NORMAL_INSTALL and their |
| @c UNINSTALL counterparts. |
| |
| @node Preparing Distributions |
| @subsection Preparing Distributions |
| @cindex Preparing distributions |
| @cindex Packages, preparation |
| @cindex Distributions, preparation |
| |
| We have already mentioned @code{make dist}. This target collects all |
| your source files and the necessary parts of the build system to |
| create a tarball named @file{@var{package}-@var{version}.tar.gz}. |
| |
| @cindex @code{distcheck} better than @code{dist} |
| |
| Another, more useful command is @code{make distcheck}. The |
| @code{distcheck} target constructs |
| @file{@var{package}-@var{version}.tar.gz} just as well as @code{dist}, |
| but it additionally ensures most of the use cases presented so far |
| work: |
| |
| @itemize @bullet |
| @item |
| It attempts a full compilation of the package (@pxref{Basic |
| Installation}), unpacking the newly constructed tarball, running |
| @code{make}, @code{make check}, @code{make install}, as well as |
| @code{make installcheck}, and even @code{make dist}, |
| @item |
| it tests VPATH builds with read-only source tree (@pxref{VPATH Builds}), |
| @item |
| it makes sure @code{make clean}, @code{make distclean}, and @code{make |
| uninstall} do not omit any file (@pxref{Standard Targets}), |
| @item |
| and it checks that @code{DESTDIR} installations work (@pxref{DESTDIR}). |
| @end itemize |
| |
| All of these actions are performed in a temporary subdirectory, so |
| that no root privileges are required. |
| |
| Releasing a package that fails @code{make distcheck} means that one of |
| the scenarios we presented will not work and some users will be |
| disappointed. Therefore it is a good practice to release a package |
| only after a successful @code{make distcheck}. This of course does |
| not imply that the package will be flawless, but at least it will |
| prevent some of the embarrassing errors you may find in packages |
| released by people who have never heard about @code{distcheck} (like |
| @code{DESTDIR} not working because of a typo, or a distributed file |
| being erased by @code{make clean}, or even @code{VPATH} builds not |
| working). |
| |
| @xref{Creating amhello}, to recreate @file{amhello-1.0.tar.gz} using |
| @code{make distcheck}. @xref{Checking the Distribution}, for more |
| information about @code{distcheck}. |
| |
| @node Dependency Tracking |
| @subsection Automatic Dependency Tracking |
| @cindex Dependency tracking |
| |
| Dependency tracking is performed as a side-effect of compilation. |
| Each time the build system compiles a source file, it computes its |
| list of dependencies (in C these are the header files included by the |
| source being compiled). Later, any time @command{make} is run and a |
| dependency appears to have changed, the dependent files will be |
| rebuilt. |
| |
| Automake generates code for automatic dependency tracking by default, |
| unless the developer chooses to override it; for more information, |
| @pxref{Dependencies}. |
| |
| When @command{configure} is executed, you can see it probing each |
| compiler for the dependency mechanism it supports (several mechanisms |
| can be used): |
| |
| @example |
| ~/amhello-1.0 % @kbd{./configure --prefix /usr} |
| @dots{} |
| checking dependency style of gcc... gcc3 |
| @dots{} |
| @end example |
| |
| Because dependencies are only computed as a side-effect of the |
| compilation, no dependency information exists the first time a package |
| is built. This is OK because all the files need to be built anyway: |
| @code{make} does not have to decide which files need to be rebuilt. |
| In fact, dependency tracking is completely useless for one-time builds |
| and there is a @command{configure} option to disable this: |
| |
| @table @option |
| @item --disable-dependency-tracking |
| @opindex --disable-dependency-tracking |
| Speed up one-time builds. |
| @end table |
| |
| Some compilers do not offer any practical way to derive the list of |
| dependencies as a side-effect of the compilation, requiring a separate |
| run (maybe of another tool) to compute these dependencies. The |
| performance penalty implied by these methods is important enough to |
| disable them by default. The option @option{--enable-dependency-tracking} |
| must be passed to @command{configure} to activate them. |
| |
| @table @option |
| @item --enable-dependency-tracking |
| @opindex --enable-dependency-tracking |
| Do not reject slow dependency extractors. |
| @end table |
| |
| @xref{Dependency Tracking Evolution, , Dependency Tracking Evolution, |
| automake-history, Brief History of Automake}, for some discussion about |
| the different dependency tracking schemes used by Automake over the years. |
| |
| @node Nested Packages |
| @subsection Nested Packages |
| @cindex Nested packages |
| @cindex Packages, nested |
| @cindex Subpackages |
| |
| Although nesting packages isn't something we would recommend to |
| someone who is discovering the Autotools, it is a nice feature worthy |
| of mention in this small advertising tour. |
| |
| Autoconfiscated packages (that means packages whose build system have |
| been created by Autoconf and friends) can be nested to arbitrary |
| depth. |
| |
| A typical setup is that package A will distribute one of the libraries |
| it needs in a subdirectory. This library B is a complete package with |
| its own GNU Build System. The @command{configure} script of A will |
| run the @command{configure} script of B as part of its execution, |
| building and installing A will also build and install B. Generating a |
| distribution for A will also include B. |
| |
| It is possible to gather several packages like this. GCC is a heavy |
| user of this feature. This gives installers a single package to |
| configure, build and install, while it allows developers to work on |
| subpackages independently. |
| |
| When configuring nested packages, the @command{configure} options |
| given to the top-level @command{configure} are passed recursively to |
| nested @command{configure}s. A package that does not understand an |
| option will ignore it, assuming it is meaningful to some other |
| package. |
| |
| @opindex --help=recursive |
| |
| The command @code{configure --help=recursive} can be used to display |
| the options supported by all the included packages. |
| |
| @xref{Subpackages}, for an example setup. |
| |
| @node Why Autotools |
| @section How Autotools Help |
| @cindex Autotools, purpose |
| |
| There are several reasons why you may not want to implement the GNU |
| Build System yourself (read: write a @file{configure} script and |
| @file{Makefile}s yourself). |
| |
| @itemize @bullet |
| @item |
| As we have seen, the GNU Build System has a lot of |
| features (@pxref{Use Cases}). |
| Some users may expect features you have not implemented because |
| you did not need them. |
| @item |
| Implementing these features portably is difficult and exhausting. |
| Think of writing portable shell scripts, and portable |
| @file{Makefile}s, for systems you may not have handy. @xref{Portable |
| Shell, , Portable Shell Programming, autoconf, The Autoconf Manual}, to |
| convince yourself. |
| @item |
| You will have to upgrade your setup to follow changes to the GNU |
| Coding Standards. |
| @end itemize |
| |
| The GNU Autotools take all this burden off your back and provide: |
| |
| @itemize @bullet |
| @item |
| Tools to create a portable, complete, and self-contained GNU Build |
| System, from simple instructions. |
| @emph{Self-contained} meaning the resulting build system does not |
| require the GNU Autotools. |
| @item |
| A central place where fixes and improvements are made: |
| a bug-fix for a portability issue will benefit every package. |
| @end itemize |
| |
| Yet there also exist reasons why you may want NOT to use the |
| Autotools@enddots{} For instance you may be already using (or used to) |
| another incompatible build system. Autotools will only be useful if |
| you do accept the concepts of the GNU Build System. People who have their |
| own idea of how a build system should work will feel frustrated by the |
| Autotools. |
| |
| @node Hello World |
| @section A Small Hello World |
| @cindex Example Hello World |
| @cindex Hello World example |
| @cindex @file{amhello-1.0.tar.gz}, creation |
| |
| In this section we recreate the @file{amhello-1.0} package from |
| scratch. The first subsection shows how to call the Autotools to |
| instantiate the GNU Build System, while the second explains the |
| meaning of the @file{configure.ac} and @file{Makefile.am} files read |
| by the Autotools. |
| |
| @anchor{amhello Explained} |
| @menu |
| * Creating amhello:: Create @file{amhello-1.0.tar.gz} from scratch |
| * amhello's configure.ac Setup Explained:: |
| * amhello's Makefile.am Setup Explained:: |
| @end menu |
| |
| @node Creating amhello |
| @subsection Creating @file{amhello-1.0.tar.gz} |
| |
| Here is how we can recreate @file{amhello-1.0.tar.gz} from scratch. |
| The package is simple enough so that we will only need to write 5 |
| files. (You may copy them from the final @file{amhello-1.0.tar.gz} |
| that is distributed with Automake if you do not want to write them.) |
| |
| Create the following files in an empty directory. |
| |
| @itemize @bullet |
| |
| @item |
| @file{src/main.c} is the source file for the @file{hello} program. We |
| store it in the @file{src/} subdirectory, because later, when the package |
| evolves, it will ease the addition of a @file{man/} directory for man |
| pages, a @file{data/} directory for data files, etc. |
| @example |
| ~/amhello % @kbd{cat src/main.c} |
| #include <config.h> |
| #include <stdio.h> |
| |
| int |
| main (void) |
| @{ |
| puts ("Hello World!"); |
| puts ("This is " PACKAGE_STRING "."); |
| return 0; |
| @} |
| @end example |
| |
| @item |
| @file{README} contains some very limited documentation for our little |
| package. |
| @example |
| ~/amhello % @kbd{cat README} |
| This is a demonstration package for GNU Automake-NG. |
| Type 'info Automake-NG' to read its manual. |
| @end example |
| |
| @item |
| @file{Makefile.am} and @file{src/Makefile.am} contain Automake-NG |
| instructions for these two directories. |
| |
| @example |
| ~/amhello % @kbd{cat src/Makefile.am} |
| bin_PROGRAMS = hello |
| hello_SOURCES = main.c |
| ~/amhello % @kbd{cat Makefile.am} |
| SUBDIRS = src |
| dist_doc_DATA = README |
| @end example |
| |
| @item |
| Finally, @file{configure.ac} contains Autoconf instructions to |
| create the @command{configure} script. |
| |
| @example |
| ~/amhello % @kbd{cat configure.ac} |
| AC_INIT([amhello], [1.0], [@value{PACKAGE_BUGREPORT}]) |
| AM_INIT_AUTOMAKE([-Wall -Werror foreign]) |
| AC_PROG_CC |
| AC_CONFIG_HEADERS([config.h]) |
| AC_CONFIG_FILES([ |
| Makefile |
| src/Makefile |
| ]) |
| AC_OUTPUT |
| @end example |
| @end itemize |
| |
| @cindex @command{autoreconf}, example |
| |
| Once you have these five files, it is time to run the Autotools to |
| instantiate the build system. Do this using the @command{autoreconf} |
| command as follows: |
| |
| @example |
| ~/amhello % @kbd{autoreconf --install} |
| configure.ac: installing './install-sh' |
| configure.ac: installing './missing' |
| src/Makefile.am: installing './depcomp' |
| @end example |
| |
| At this point the build system is complete. |
| |
| In addition to the three scripts mentioned in its output, you can see |
| that @command{autoreconf} created four other files: @file{configure}, |
| @file{config.h.in}, @file{Makefile.in}, and @file{src/Makefile.in}. |
| The latter three files are templates that will be adapted to the |
| system by @command{configure} under the names @file{config.h}, |
| @file{Makefile}, and @file{src/Makefile}. Let's do this: |
| |
| @example |
| ~/amhello % @kbd{./configure} |
| checking for a BSD-compatible install... /usr/bin/install -c |
| checking whether build environment is sane... yes |
| checking for gawk... no |
| checking for mawk... mawk |
| checking whether make sets $(MAKE)... yes |
| checking for gcc... gcc |
| checking for C compiler default output file name... a.out |
| checking whether the C compiler works... yes |
| checking whether we are cross compiling... no |
| checking for suffix of executables... |
| checking for suffix of object files... o |
| checking whether we are using the GNU C compiler... yes |
| checking whether gcc accepts -g... yes |
| checking for gcc option to accept ISO C89... none needed |
| checking for style of include used by make... GNU |
| checking dependency style of gcc... gcc3 |
| configure: creating ./config.status |
| config.status: creating Makefile |
| config.status: creating src/Makefile |
| config.status: creating config.h |
| config.status: executing depfiles commands |
| @end example |
| |
| @trindex distcheck |
| @cindex @code{distcheck} example |
| |
| You can see @file{Makefile}, @file{src/Makefile}, and @file{config.h} |
| being created at the end after @command{configure} has probed the |
| system. It is now possible to run all the targets we wish |
| (@pxref{Standard Targets}). For instance: |
| |
| @example |
| ~/amhello % @kbd{make} |
| @dots{} |
| ~/amhello % @kbd{src/hello} |
| Hello World! |
| This is amhello 1.0. |
| ~/amhello % @kbd{make distcheck} |
| @dots{} |
| ============================================= |
| amhello-1.0 archives ready for distribution: |
| amhello-1.0.tar.gz |
| ============================================= |
| @end example |
| |
| Note that running @command{autoreconf} is only needed initially when |
| the GNU Build System does not exist. When you later change some |
| instructions in a @file{Makefile.am} or @file{configure.ac}, the |
| relevant part of the build system will be regenerated automatically |
| when you execute @command{make}. |
| |
| @command{autoreconf} is a script that calls @command{autoconf}, |
| @command{automake}, and a bunch of other commands in the right order. |
| If you are beginning with these tools, it is not important to figure |
| out in which order all of these tools should be invoked and why. However, |
| because Autoconf and Automake-NG have separate manuals, the important |
| point to understand is that @command{autoconf} is in charge of |
| creating @file{configure} from @file{configure.ac}, while |
| @command{automake} is in charge of creating @file{Makefile.in}s from |
| @file{Makefile.am}s and @file{configure.ac}. This should at least |
| direct you to the right manual when seeking answers. |
| |
| |
| @node amhello's configure.ac Setup Explained |
| @subsection @code{amhello}'s @file{configure.ac} Setup Explained |
| |
| @cindex @file{configure.ac}, Hello World |
| |
| Let us begin with the contents of @file{configure.ac}. |
| |
| @example |
| AC_INIT([amhello], [1.0], [@value{PACKAGE_BUGREPORT}]) |
| AM_INIT_AUTOMAKE([-Wall -Werror foreign]) |
| AC_PROG_CC |
| AC_CONFIG_HEADERS([config.h]) |
| AC_CONFIG_FILES([ |
| Makefile |
| src/Makefile |
| ]) |
| AC_OUTPUT |
| @end example |
| |
| This file is read by both @command{autoconf} (to create |
| @file{configure}) and @command{automake} (to create the various |
| @file{Makefile.in}s). It contains a series of M4 macros that will be |
| expanded as shell code to finally form the @file{configure} script. |
| We will not elaborate on the syntax of this file, because the Autoconf |
| manual has a whole section about it (@pxref{Writing Autoconf Input, , |
| Writing @file{configure.ac}, autoconf, The Autoconf Manual}). |
| |
| The macros prefixed with @code{AC_} are Autoconf macros, documented |
| in the Autoconf manual (@pxref{Autoconf Macro Index, , Autoconf Macro |
| Index, autoconf, The Autoconf Manual}). The macros that start with |
| @code{AM_} are Automake macros, documented later in this manual |
| (@pxref{Macro Index}). |
| |
| The first two lines of @file{configure.ac} initialize Autoconf and |
| Automake. @code{AC_INIT} takes in as parameters the name of the package, |
| its version number, and a contact address for bug-reports about the |
| package (this address is output at the end of @code{./configure |
| --help}, for instance). When adapting this setup to your own package, |
| by all means please do not blindly copy Automake's address: use the |
| mailing list of your package, or your own mail address. |
| |
| @opindex -Wall |
| @opindex -Werror |
| @opindex foreign |
| |
| The argument to @code{AM_INIT_AUTOMAKE} is a list of options for |
| @command{automake} (@pxref{Options}). @option{-Wall} and |
| @option{-Werror} ask @command{automake} to turn on all warnings and |
| report them as errors. We are speaking of @strong{Automake} warnings |
| here, such as dubious instructions in @file{Makefile.am}. This has |
| absolutely nothing to do with how the compiler will be called, even |
| though it may support options with similar names. Using @option{-Wall |
| -Werror} is a safe setting when starting to work on a package: you do |
| not want to miss any issues. Later you may decide to relax things a |
| bit. The @option{foreign} option tells Automake that this package |
| will not follow the GNU Standards. GNU packages should always |
| distribute additional files such as @file{ChangeLog}, @file{AUTHORS}, |
| etc. We do not want @command{automake} to complain about these |
| missing files in our small example. |
| |
| The @code{AC_PROG_CC} line causes the @command{configure} script to |
| search for a C compiler and define the variable @code{CC} with its |
| name. The @file{src/Makefile.in} file generated by Automake uses the |
| variable @code{CC} to build @file{hello}, so when @command{configure} |
| creates @file{src/Makefile} from @file{src/Makefile.in}, it will define |
| @code{CC} with the value it has found. If Automake is asked to create |
| a @file{Makefile.in} that uses @code{CC} but @file{configure.ac} does |
| not define it, it will suggest you add a call to @code{AC_PROG_CC}. |
| |
| The @code{AC_CONFIG_HEADERS([config.h])} invocation causes the |
| @command{configure} script to create a @file{config.h} file gathering |
| @samp{#define}s defined by other macros in @file{configure.ac}. In our |
| case, the @code{AC_INIT} macro already defined a few of them. Here |
| is an excerpt of @file{config.h} after @command{configure} has run: |
| |
| @smallexample |
| @dots{} |
| /* Define to the address where bug reports for this package should be sent. */ |
| #define PACKAGE_BUGREPORT "@value{PACKAGE_BUGREPORT}" |
| |
| /* Define to the full name and version of this package. */ |
| #define PACKAGE_STRING "amhello 1.0" |
| @dots{} |
| @end smallexample |
| |
| As you probably noticed, @file{src/main.c} includes @file{config.h} so |
| it can use @code{PACKAGE_STRING}. In a real-world project, |
| @file{config.h} can grow really big, with one @samp{#define} per |
| feature probed on the system. |
| |
| The @code{AC_CONFIG_FILES} macro declares the list of files that |
| @command{configure} should create from their @file{*.in} templates. |
| Automake also scans this list to find the @file{Makefile.am} files it must |
| process. (This is important to remember: when adding a new directory |
| to your project, you should add its @file{Makefile} to this list, |
| otherwise Automake will never process the new @file{Makefile.am} you |
| wrote in that directory.) |
| |
| Finally, the @code{AC_OUTPUT} line is a closing command that actually |
| produces the part of the script in charge of creating the files |
| registered with @code{AC_CONFIG_HEADERS} and @code{AC_CONFIG_FILES}. |
| |
| @cindex @command{autoscan} |
| |
| When starting a new project, we suggest you start with such a simple |
| @file{configure.ac}, and gradually add the other tests it requires. |
| The command @command{autoscan} can also suggest a few of the tests |
| your package may need (@pxref{autoscan Invocation, , Using |
| @command{autoscan} to Create @file{configure.ac}, autoconf, The |
| Autoconf Manual}). |
| |
| |
| @node amhello's Makefile.am Setup Explained |
| @subsection @code{amhello}'s @file{Makefile.am} Setup Explained |
| |
| @cindex @file{Makefile.am}, Hello World |
| |
| We now turn to @file{src/Makefile.am}. This file contains |
| Automake instructions to build and install @file{hello}. |
| |
| @example |
| bin_PROGRAMS = hello |
| hello_SOURCES = main.c |
| @end example |
| |
| A @file{Makefile.am} has the same syntax as an ordinary |
| @file{Makefile}. When @command{automake} processes a |
| @file{Makefile.am} it copies the entire file into the output |
| @file{Makefile.in} (that will be later turned into @file{Makefile} by |
| @command{configure}) but will react to certain variable definitions |
| by generating some build rules and other variables. |
| Often @file{Makefile.am}s contain only a list of variable definitions as |
| above, but they can also contain other variable and rule definitions that |
| @command{automake} will pass along without interpretation. |
| |
| Variables that end with @code{_PROGRAMS} are special variables |
| that list programs that the resulting @file{Makefile} should build. |
| In Automake speak, this @code{_PROGRAMS} suffix is called a |
| @dfn{primary}; Automake recognizes other primaries such as |
| @code{_SCRIPTS}, @code{_DATA}, @code{_LIBRARIES}, etc.@: corresponding |
| to different types of files. |
| |
| The @samp{bin} part of the @code{bin_PROGRAMS} tells |
| @command{automake} that the resulting programs should be installed in |
| @var{bindir}. Recall that the GNU Build System uses a set of variables |
| to denote destination directories and allow users to customize these |
| locations (@pxref{Standard Directory Variables}). Any such directory |
| variable can be put in front of a primary (omitting the @code{dir} |
| suffix) to tell @command{automake} where to install the listed files. |
| |
| Programs need to be built from source files, so for each program |
| @code{@var{prog}} listed in a @code{@w{_PROGRAMS}} variable, |
| @command{automake} will look for another variable named |
| @code{@var{prog}_SOURCES} listing its source files. There may be more |
| than one source file: they will all be compiled and linked together. |
| |
| Automake also knows that source files need to be distributed when |
| creating a tarball (unlike built programs). So a side-effect of this |
| @code{hello_SOURCES} declaration is that @file{main.c} will be |
| part of the tarball created by @code{make dist}. |
| |
| Finally here are some explanations regarding the top-level |
| @file{Makefile.am}. |
| |
| @example |
| SUBDIRS = src |
| dist_doc_DATA = README |
| @end example |
| |
| @code{SUBDIRS} is a special variable listing all directories that |
| @command{make} should recurse into before processing the current |
| directory. So this line is responsible for @command{make} building |
| @file{src/hello} even though we run it from the top-level. This line |
| also causes @code{make install} to install @file{src/hello} before |
| installing @file{README} (not that this order matters). |
| |
| The line @code{dist_doc_DATA = README} causes @file{README} to be |
| distributed and installed in @var{docdir}. Files listed with the |
| @code{_DATA} primary are not automatically part of the tarball built |
| with @code{make dist}, so we add the @code{dist_} prefix so they get |
| distributed. However, for @file{README} it would not have been |
| necessary: @command{automake} automatically distributes any |
| @file{README} file it encounters (the list of other files |
| automatically distributed is presented by @code{automake --help}). |
| The only important effect of this second line is therefore to install |
| @file{README} during @code{make install}. |
| |
| One thing not covered in this example is accessing the installation |
| directory values (@pxref{Standard Directory Variables}) from your |
| program code, that is, converting them into defined macros. For this, |
| @pxref{Defining Directories,,, autoconf, The Autoconf Manual}. |
| |
| |
| @node Generalities |
| @chapter General ideas |
| |
| The following sections cover a few basic ideas that will help you |
| understand how Automake works. |
| |
| @menu |
| * General Operation:: General operation of Automake |
| * Strictness:: Standards conformance checking |
| * Uniform:: The Uniform Naming Scheme |
| * Length Limitations:: Staying below the command line length limit |
| * Canonicalization:: How derived variables are named |
| * User Variables:: Variables reserved for the user |
| * Auxiliary Programs:: Programs automake might require |
| @end menu |
| |
| |
| @node General Operation |
| @section General Operation |
| |
| Automake works by reading a @file{Makefile.am} and generating a |
| @file{Makefile.in}. Certain variables and rules defined in the |
| @file{Makefile.am} instruct Automake to generate more specialized code; |
| for instance, a @code{bin_PROGRAMS} variable definition will cause rules |
| for compiling and linking programs to be generated. |
| |
| @cindex Non-standard targets |
| @cindex @code{git-dist}, non-standard example |
| @trindex git-dist |
| |
| The variable definitions and rules in the @file{Makefile.am} are |
| copied mostly verbatim into the generated file, with all variable |
| definitions preceding all rules. This allows you to add almost |
| arbitrary code into the generated @file{Makefile.in}. For instance, |
| the Automake distribution includes a non-standard rule for the |
| @code{git-dist} target, which the Automake maintainer uses to make |
| distributions from the source control system. |
| |
| @cindex GNU make extensions |
| |
| Note that most GNU make extensions are sadly not yet recognized by |
| Automake. Using such extensions in a @file{Makefile.am} will likely |
| lead to errors or confusing behavior. We hope to improve this |
| situation over time. |
| |
| @cindex Append operator |
| @cmindex += |
| For historical reasons, the GNU make append operator @samp{+=} (which |
| appends its right hand argument to the variable specified on the left) |
| is supported and handled in a special way: Automake will translate the |
| operator into an ordinary @samp{=} operator @emph{at Automake (not make) |
| runtime}. This behaviour might change future versions. |
| |
| Automake tries to keep comments grouped with any adjoining rules or |
| variable definitions. |
| |
| @cindex Limitations of automake parser |
| @cindex Automake parser, limitations of |
| @cindex indentation in Makefile.am |
| Generally, Automake is not particularly smart in the parsing of unusual |
| Makefile constructs, so you're advised to avoid fancy constructs or |
| ``creative'' use of whitespaces. |
| For example, @key{TAB} characters cannot be used between a target name |
| and the following ``@code{:}'' character, and variable assignments |
| shouldn't be indented with @key{TAB} characters. |
| |
| @cindex Make targets, overriding |
| @cindex Make rules, overriding |
| @cindex Overriding make rules |
| @cindex Overriding make targets |
| |
| A rule defined in @file{Makefile.am} generally overrides any such |
| rule of a similar name that would be automatically generated by |
| @command{automake}. Although this is a supported feature, it is generally |
| best to avoid making use of it, as sometimes the generated rules are |
| very particular. |
| |
| @cindex Variables, overriding |
| @cindex Overriding make variables |
| |
| Similarly, a variable defined in @file{Makefile.am} or |
| @code{AC_SUBST}ed from @file{configure.ac} will override any |
| definition of the variable that @command{automake} would ordinarily |
| create. This feature is more often useful than the ability to |
| override a rule. Be warned that many of the variables generated by |
| @command{automake} are considered to be for internal use only, and their |
| names might change in future releases. |
| |
| @cindex Recursive operation of Automake |
| @cindex Automake, recursive operation |
| @cindex Example of recursive operation |
| |
| When examining the definition of some ``special'' variables, Automake |
| might recursively examine variables referenced in the definition in order |
| to perform its magic. For example, if Automake is looking at the content |
| of @code{foo_SOURCES} in this snippet |
| |
| @c Keep in sync with interp.sh |
| @example |
| xs = a.c b.c |
| foo_SOURCES = c.c $(xs) |
| @end example |
| |
| it would use the files @file{a.c}, @file{b.c}, and @file{c.c} as the |
| contents of @code{foo_SOURCES}. |
| |
| Unfortunately, for historical reasons, this interpolation processes |
| has the effect of currently making it impossible to use more advanced |
| GNU make features in the definitions of special variables like |
| @code{foo_SOURCES}; for example, Automake will generate a broken |
| @file{Makefile.in} on this input: |
| |
| @c Keep in sync with interp3.test. |
| @example |
| bin_PROGRAMS = foo |
| xs = one two |
| foo_SOURCES = main.c $(foreach base, $(xs), $(base).c $(base).h) |
| @end example |
| |
| @cindex @code{##} (special Automake comment) |
| @cindex Special Automake comment |
| @cindex Comment, special to Automake |
| |
| Automake also allows a form of comment that is @emph{not} copied into |
| the output; all lines beginning with @samp{##} (leading spaces allowed) |
| are completely ignored by Automake. |
| |
| It is customary to make the first line of @file{Makefile.am} read: |
| |
| @cindex Makefile.am, first line |
| @cindex First line of Makefile.am |
| |
| @example |
| ## Process this file with automake to produce Makefile.in |
| @end example |
| |
| @c FIXME discuss putting a copyright into Makefile.am here? I would but |
| @c I don't know quite what to say. |
| |
| @c FIXME document customary ordering of Makefile.am here! |
| |
| |
| @node Strictness |
| @section Strictness |
| |
| @cindex Non-GNU packages |
| |
| While Automake is intended to be used by maintainers of GNU packages, it |
| does make some effort to accommodate those who wish to use it, but do |
| not want to use all the GNU conventions. |
| |
| @cindex Strictness, defined |
| @cindex Strictness, @option{foreign} |
| @cindex @option{foreign} strictness |
| @cindex Strictness, @option{gnu} |
| @cindex @option{gnu} strictness |
| @cindex Strictness, @option{gnits} |
| @cindex @option{gnits} strictness |
| |
| To this end, Automake supports three levels of @dfn{strictness}---the |
| strictness indicating how stringently Automake should check standards |
| conformance. |
| |
| The valid strictness levels are: |
| |
| @table @option |
| @item foreign |
| Automake will check for only those things that are absolutely |
| required for proper operations. For instance, whereas GNU standards |
| dictate the existence of a @file{NEWS} file, it will not be required in |
| this mode. This strictness will also turn off some warnings by default |
| (among them, portability warnings). |
| The name comes from the fact that Automake is intended to be |
| used for GNU programs; these relaxed rules are not the standard mode of |
| operation. |
| |
| @item gnu |
| Automake will check---as much as possible---for compliance to the GNU |
| standards for packages. This is the default. |
| |
| @item gnits |
| Automake will check for compliance to the as-yet-unwritten @dfn{Gnits |
| standards}. These are based on the GNU standards, but are even more |
| detailed. Unless you are a Gnits standards contributor, it is |
| recommended that you avoid this option until such time as the Gnits |
| standard is actually published (which may never happen). |
| @end table |
| |
| @xref{Gnits}, for more information on the precise implications of the |
| strictness level. |
| |
| |
| @node Uniform |
| @section The Uniform Naming Scheme |
| |
| @cindex Uniform naming scheme |
| |
| Automake variables generally follow a @dfn{uniform naming scheme} that |
| makes it easy to decide how programs (and other derived objects) are |
| built, and how they are installed. This scheme also supports |
| @command{configure} time determination of what should be built. |
| |
| @cindex @code{_PROGRAMS} primary variable |
| @cindex @code{PROGRAMS} primary variable |
| @cindex Primary variable, @code{PROGRAMS} |
| @cindex Primary variable, defined |
| @vindex _PROGRAMS |
| |
| At @command{make} time, certain variables are used to determine which |
| objects are to be built. The variable names are made of several pieces |
| that are concatenated together. |
| |
| The piece that tells @command{automake} what is being built is commonly called |
| the @dfn{primary}. For instance, the primary @code{PROGRAMS} holds a |
| list of programs that are to be compiled and linked. |
| @vindex PROGRAMS |
| |
| @cindex @code{pkgdatadir}, defined |
| @cindex @code{pkgincludedir}, defined |
| @cindex @code{pkglibdir}, defined |
| @cindex @code{pkglibexecdir}, defined |
| |
| @vindex pkgdatadir |
| @vindex pkgincludedir |
| @vindex pkglibdir |
| @vindex pkglibexecdir |
| |
| @cindex @code{PACKAGE}, directory |
| A different set of names is used to decide where the built objects |
| should be installed. These names are prefixes to the primary, and they |
| indicate which standard directory should be used as the installation |
| directory. The standard directory names are given in the GNU standards |
| (@pxref{Directory Variables, , , standards, The GNU Coding Standards}). |
| Automake extends this list with @code{pkgdatadir}, @code{pkgincludedir}, |
| @code{pkglibdir}, and @code{pkglibexecdir}; these are the same as the |
| non-@samp{pkg} versions, but with @samp{$(PACKAGE)} appended. For instance, |
| @code{pkglibdir} is defined as @samp{$(libdir)/$(PACKAGE)}. |
| |
| @cindex @code{EXTRA_}, prepending |
| For each primary, there is one additional variable named by prepending |
| @samp{EXTRA_} to the primary name. This variable is used to list |
| objects that may or may not be built, depending on what |
| @command{configure} decides. This variable is required because Automake |
| must statically know the entire list of objects that may be built in |
| order to generate a @file{Makefile.in} that will work in all cases. |
| |
| @cindex @code{EXTRA_PROGRAMS}, defined |
| @cindex Example, @code{EXTRA_PROGRAMS} |
| @cindex @command{cpio} example |
| |
| For instance, @command{cpio} decides at configure time which programs |
| should be built. Some of the programs are installed in @code{bindir}, |
| and some are installed in @code{sbindir}: |
| |
| @example |
| EXTRA_PROGRAMS = mt rmt |
| bin_PROGRAMS = cpio pax |
| sbin_PROGRAMS = $(MORE_PROGRAMS) |
| @end example |
| |
| Defining a primary without a prefix as a variable, e.g., |
| @samp{PROGRAMS}, is an error. |
| |
| Note that the common @samp{dir} suffix is left off when constructing the |
| variable names; thus one writes @samp{bin_PROGRAMS} and not |
| @samp{bindir_PROGRAMS}. |
| |
| Not every sort of object can be installed in every directory. Automake |
| will flag those attempts it finds in error (but see below how to override |
| the check if you really need to). |
| Automake will also diagnose obvious misspellings in directory names. |
| |
| @cindex Extending list of installation directories |
| @cindex Installation directories, extending list |
| |
| Sometimes the standard directories---even as augmented by |
| Automake---are not enough. In particular it is sometimes useful, for |
| clarity, to install objects in a subdirectory of some predefined |
| directory. To this end, Automake allows you to extend the list of |
| possible installation directories. A given prefix (e.g., @samp{zar}) |
| is valid if a variable of the same name with @samp{dir} appended is |
| defined (e.g., @samp{zardir}). |
| |
| For instance, the following snippet will install @file{file.xml} into |
| @samp{$(datadir)/xml}. |
| |
| @c Keep in sync with primary-prefix-couples-documented-valid.sh |
| @example |
| xmldir = $(datadir)/xml |
| xml_DATA = file.xml |
| @end example |
| |
| This feature can also be used to override the sanity checks Automake |
| performs to diagnose suspicious directory/primary couples (in the |
| unlikely case these checks are undesirable, and you really know what |
| you're doing). For example, Automake would error out on this input: |
| |
| @c Should be tested in primary-prefix-invalid-couples.sh |
| @example |
| # Forbidden directory combinations, automake will error out on this. |
| pkglib_PROGRAMS = foo |
| doc_LIBRARIES = libquux.a |
| @end example |
| |
| @noindent |
| but it will succeed with this: |
| |
| @c Keep in sync with primary-prefix-couples-documented-valid.sh |
| @example |
| # Work around forbidden directory combinations. Do not use this |
| # without a very good reason! |
| my_execbindir = $(pkglibdir) |
| my_doclibdir = $(docdir) |
| my_execbin_PROGRAMS = foo |
| my_doclib_LIBRARIES = libquux.a |
| @end example |
| |
| The @samp{exec} substring of the @samp{my_execbindir} variable lets |
| the files be installed at the right time (@pxref{The Two Parts of |
| Install}). |
| |
| @cindex @samp{noinst_} primary prefix, definition |
| @vindex noinst_ |
| |
| The special prefix @samp{noinst_} indicates that the objects in question |
| should be built but not installed at all. This is usually used for |
| objects required to build the rest of your package, for instance static |
| libraries (@pxref{A Library}), or helper scripts. |
| |
| @cindex @samp{check_} primary prefix, definition |
| @vindex check_ |
| |
| The special prefix @samp{check_} indicates that the objects in question |
| should not be built until the @samp{make check} command is run. Those |
| objects are not installed either. |
| |
| The current primary names are @samp{PROGRAMS}, @samp{LIBRARIES}, |
| @samp{LTLIBRARIES}, @samp{LISP}, @samp{PYTHON}, @samp{JAVA}, |
| @samp{SCRIPTS}, @samp{DATA}, @samp{HEADERS}, @samp{MANS}, and |
| @samp{TEXINFOS}. |
| @vindex PROGRAMS |
| @vindex LIBRARIES |
| @vindex LTLIBRARIES |
| @vindex LISP |
| @vindex PYTHON |
| @vindex JAVA |
| @vindex SCRIPTS |
| @vindex DATA |
| @vindex HEADERS |
| @vindex MANS |
| @vindex TEXINFOS |
| |
| Some primaries also allow additional prefixes that control other |
| aspects of @command{automake}'s behavior. The currently defined prefixes |
| are @samp{dist_}, @samp{nodist_}, @samp{nobase_}, and @samp{notrans_}. |
| These prefixes are explained later (@pxref{Program and Library Variables}) |
| (@pxref{Man Pages}). |
| |
| |
| @node Length Limitations |
| @section Staying below the command line length limit |
| |
| @cindex command line length limit |
| @cindex ARG_MAX |
| |
| Traditionally, most unix-like systems have a length limitation for the |
| command line arguments and environment contents when creating new |
| processes (see for example |
| @uref{http://www.in-ulm.de/@/~mascheck/@/various/@/argmax/} for an |
| overview on this issue), |
| which of course also applies to commands spawned by @command{make}. |
| POSIX requires this limit to be at least 4096 bytes, and most modern |
| systems have quite high limits (or are unlimited). |
| |
| In order to create portable Makefiles that do not trip over these |
| limits, it is necessary to keep the length of file lists bounded. |
| Unfortunately, it is not possible to do so fully transparently within |
| Automake, so your help may be needed. Typically, you can split long |
| file lists manually and use different installation directory names for |
| each list. For example, |
| |
| @example |
| data_DATA = file1 @dots{} file@var{N} file@var{N+1} @dots{} file@var{2N} |
| @end example |
| |
| @noindent |
| may also be written as |
| |
| @c Keep in sync with primary-prefix-couples-documented-valid.sh |
| @example |
| data_DATA = file1 @dots{} file@var{N} |
| data2dir = $(datadir) |
| data2_DATA = file@var{N+1} @dots{} file@var{2N} |
| @end example |
| |
| @noindent |
| and will cause Automake to treat the two lists separately during |
| @code{make install}. See @ref{The Two Parts of Install} for choosing |
| directory names that will keep the ordering of the two parts of |
| installation Note that @code{make dist} may still only work on a host |
| with a higher length limit in this example. |
| |
| Automake itself employs a couple of strategies to avoid long command |
| lines. For example, when @samp{$@{srcdir@}/} is prepended to file |
| names, as can happen with above @code{$(data_DATA)} lists, it limits |
| the amount of arguments passed to external commands. |
| |
| Unfortunately, some system's @command{make} commands may prepend |
| @code{VPATH} prefixes like @samp{$@{srcdir@}/} to file names from the |
| source tree automatically (@pxref{Automatic Rule Rewriting, , Automatic |
| Rule Rewriting, autoconf, The Autoconf Manual}). In this case, the user |
| may have to switch to use GNU Make, or refrain from using VPATH builds, |
| in order to stay below the length limit. |
| |
| For libraries and programs built from many sources, convenience archives |
| may be used as intermediates in order to limit the object list length |
| (@pxref{Libtool Convenience Libraries}). |
| |
| |
| @node Canonicalization |
| @section How derived variables are named |
| |
| @cindex canonicalizing Automake variables |
| |
| Sometimes a Makefile variable name is derived from some text the |
| maintainer supplies. For instance, a program name listed in |
| @samp{_PROGRAMS} is rewritten into the name of a @samp{_SOURCES} |
| variable. In cases like this, Automake canonicalizes the text, so that |
| program names and the like do not have to follow Makefile variable naming |
| rules. All characters in the name except for letters, numbers, the |
| strudel (@@), and the underscore are turned into underscores when making |
| variable references. |
| |
| For example, if your program is named @file{sniff-glue}, the derived |
| variable name would be @samp{sniff_glue_SOURCES}, not |
| @samp{sniff-glue_SOURCES}. Similarly the sources for a library named |
| @file{libmumble++.a} should be listed in the |
| @samp{libmumble___a_SOURCES} variable. |
| |
| The strudel is an addition, to make the use of Autoconf substitutions in |
| variable names less obfuscating. |
| |
| |
| @node User Variables |
| @section Variables reserved for the user |
| |
| @cindex variables, reserved for the user |
| @cindex user variables |
| |
| Some @file{Makefile} variables are reserved by the GNU Coding Standards |
| for the use of the ``user''---the person building the package. For |
| instance, @code{CFLAGS} is one such variable. |
| |
| Sometimes package developers are tempted to set user variables such as |
| @code{CFLAGS} because it appears to make their job easier. However, |
| the package itself should never set a user variable, particularly not |
| to include switches that are required for proper compilation of the |
| package. Since these variables are documented as being for the |
| package builder, that person rightfully expects to be able to override |
| any of these variables at build time. |
| |
| To get around this problem, Automake introduces an automake-specific |
| shadow variable for each user flag variable. (Shadow variables are |
| not introduced for variables like @code{CC}, where they would make no |
| sense.) The shadow variable is named by prepending @samp{AM_} to the |
| user variable's name. For instance, the shadow variable for |
| @code{YFLAGS} is @code{AM_YFLAGS}. The package maintainer---that is, |
| the author(s) of the @file{Makefile.am} and @file{configure.ac} |
| files---may adjust these shadow variables however necessary. |
| |
| @xref{Flag Variables Ordering}, for more discussion about these |
| variables and how they interact with per-target variables. |
| |
| @node Auxiliary Programs |
| @section Programs automake might require |
| |
| @cindex Programs, auxiliary |
| @cindex Auxiliary programs |
| |
| Automake sometimes requires helper programs so that the generated |
| @file{Makefile} can do its work properly. There are a fairly large |
| number of them, and we list them here. |
| |
| Although all of these files are distributed and installed with |
| Automake, a couple of them are maintained separately. The Automake |
| copies are updated before each release, but we mention the original |
| source in case you need more recent versions. |
| |
| @table @code |
| @item ar-lib |
| This is a wrapper primarily for the Microsoft lib archiver, to make |
| it more POSIX-like. |
| |
| @item compile |
| This is a wrapper for compilers that do not accept options @option{-c} |
| and @option{-o} at the same time. It is only used when absolutely |
| required. Such compilers are rare, with the Microsoft C/C++ Compiler |
| as the most notable exception. This wrapper also makes the following |
| common options available for that compiler, while performing file name |
| translation where needed: @option{-I}, @option{-L}, @option{-l}, |
| @option{-Wl,} and @option{-Xlinker}. |
| |
| @item config.guess |
| @itemx config.sub |
| These two programs compute the canonical triplets for the given build, |
| host, or target architecture. These programs are updated regularly to |
| support new architectures and fix probes broken by changes in new |
| kernel versions. Each new release of Automake comes with up-to-date |
| copies of these programs. If your copy of Automake is getting old, |
| you are encouraged to fetch the latest versions of these files from |
| @url{http://savannah.gnu.org/git/?group=config} before making a |
| release. |
| |
| @item depcomp |
| This program understands how to run a compiler so that it will |
| generate not only the desired output but also dependency information |
| that is then used by the automatic dependency tracking feature |
| (@pxref{Dependencies}). |
| |
| @item install-sh |
| This is a replacement for the @command{install} program that works on |
| platforms where @command{install} is unavailable or unusable. |
| |
| @item mdate-sh |
| This script is used to generate a @file{version.texi} file. It examines |
| a file and prints some date information about it. |
| |
| @item missing |
| This wraps a number of programs that are typically only required by |
| maintainers. If the program in question doesn't exist, or seems to old, |
| @command{missing} will print an informative warning before failing out, |
| to provide the user with more context and information. |
| |
| @item py-compile |
| This is used to byte-compile Python scripts. |
| |
| @item test-driver |
| This implements the default test driver offered by the parallel |
| testsuite harness. |
| |
| @item texinfo.tex |
| Not a program, this file is required for @samp{make dvi}, @samp{make |
| ps} and @samp{make pdf} to work when Texinfo sources are in the |
| package. The latest version can be downloaded from |
| @url{http://www.gnu.org/software/texinfo/}. |
| |
| @item ylwrap |
| This program wraps @command{lex} and @command{yacc} to rename their |
| output files. It also ensures that, for instance, multiple |
| @command{yacc} instances can be invoked in a single directory in |
| parallel. |
| |
| @end table |
| |
| |
| @node Examples |
| @chapter Some example packages |
| |
| This section contains two small examples. |
| |
| The first example (@pxref{Complete}) assumes you have an existing |
| project already using Autoconf, with handcrafted @file{Makefile}s, and |
| that you want to convert it to using Automake. If you are discovering |
| both tools, it is probably better that you look at the Hello World |
| example presented earlier (@pxref{Hello World}). |
| |
| The second example (@pxref{true}) shows how two programs can be built |
| from the same file, using different compilation parameters. It |
| contains some technical digressions that are probably best skipped on |
| first read. |
| |
| @menu |
| * Complete:: A simple example, start to finish |
| * true:: Building true and false |
| @end menu |
| |
| |
| @node Complete |
| @section A simple example, start to finish |
| |
| @cindex Complete example |
| |
| Let's suppose you just finished writing @code{zardoz}, a program to make |
| your head float from vortex to vortex. You've been using Autoconf to |
| provide a portability framework, but your @file{Makefile.in}s have been |
| ad-hoc. You want to make them bulletproof, so you turn to Automake. |
| |
| @cindex @code{AM_INIT_AUTOMAKE}, example use |
| |
| The first step is to update your @file{configure.ac} to include the |
| commands that @command{automake} needs. The way to do this is to add an |
| @code{AM_INIT_AUTOMAKE} call just after @code{AC_INIT}: |
| |
| @example |
| AC_INIT([zardoz], [1.0]) |
| AM_INIT_AUTOMAKE |
| @dots{} |
| @end example |
| |
| Since your program doesn't have any complicating factors (e.g., it |
| doesn't use @code{gettext}, it doesn't want to build a shared library), |
| you're done with this part. That was easy! |
| |
| @cindex @command{aclocal} program, introduction |
| @cindex @file{aclocal.m4}, preexisting |
| @cindex @file{acinclude.m4}, defined |
| |
| Now you must regenerate @file{configure}. But to do that, you'll need |
| to tell @command{autoconf} how to find the new macro you've used. The |
| easiest way to do this is to use the @command{aclocal} program to |
| generate your @file{aclocal.m4} for you. But wait@dots{} maybe you |
| already have an @file{aclocal.m4}, because you had to write some hairy |
| macros for your program. The @command{aclocal} program lets you put |
| your own macros into @file{acinclude.m4}, so simply rename and then |
| run: |
| |
| @example |
| mv aclocal.m4 acinclude.m4 |
| aclocal |
| autoconf |
| @end example |
| |
| @cindex @command{zardoz} example |
| |
| Now it is time to write your @file{Makefile.am} for @code{zardoz}. |
| Since @code{zardoz} is a user program, you want to install it where the |
| rest of the user programs go: @code{bindir}. Additionally, |
| @code{zardoz} has some Texinfo documentation. Your @file{configure.ac} |
| script uses @code{AC_REPLACE_FUNCS}, so you need to link against |
| @samp{$(LIBOBJS)}. So here's what you'd write: |
| |
| @example |
| bin_PROGRAMS = zardoz |
| zardoz_SOURCES = main.c head.c float.c vortex9.c gun.c |
| zardoz_LDADD = $(LIBOBJS) |
| |
| info_TEXINFOS = zardoz.texi |
| @end example |
| |
| Now you can run @samp{automake --add-missing} to generate your |
| @file{Makefile.in} and grab any auxiliary files you might need, and |
| you're done! |
| |
| |
| @node true |
| @section Building true and false |
| |
| @cindex Example, @command{false} and @command{true} |
| @cindex @command{false} Example |
| @cindex @command{true} Example |
| |
| Here is another, trickier example. It shows how to generate two |
| programs (@code{true} and @code{false}) from the same source file |
| (@file{true.c}). The difficult part is that each compilation of |
| @file{true.c} requires different @code{cpp} flags. |
| |
| @example |
| bin_PROGRAMS = true false |
| false_SOURCES = |
| false_LDADD = false.o |
| |
| true.o: true.c |
| $(COMPILE) -DEXIT_CODE=0 -c true.c |
| |
| false.o: true.c |
| $(COMPILE) -DEXIT_CODE=1 -o false.o -c true.c |
| @end example |
| |
| Note that there is no @code{true_SOURCES} definition. Automake will |
| implicitly assume that there is a source file named @file{true.c} |
| (@pxref{Default _SOURCES}), and |
| define rules to compile @file{true.o} and link @file{true}. The |
| @samp{true.o: true.c} rule supplied by the above @file{Makefile.am}, |
| will override the Automake generated rule to build @file{true.o}. |
| |
| @code{false_SOURCES} is defined to be empty---that way no implicit value |
| is substituted. Because we have not listed the source of |
| @file{false}, we have to tell Automake how to link the program. This is |
| the purpose of the @code{false_LDADD} line. A @code{false_DEPENDENCIES} |
| variable, holding the dependencies of the @file{false} target will be |
| automatically generated by Automake from the content of |
| @code{false_LDADD}. |
| |
| The above rules won't work if your compiler doesn't accept both |
| @option{-c} and @option{-o}. The simplest fix for this is to introduce a |
| bogus dependency (to avoid problems with a parallel @command{make}): |
| |
| @example |
| true.o: true.c false.o |
| $(COMPILE) -DEXIT_CODE=0 -c true.c |
| |
| false.o: true.c |
| $(COMPILE) -DEXIT_CODE=1 -c true.c && mv true.o false.o |
| @end example |
| |
| As it turns out, there is also a much easier way to do this same task. |
| Some of the above technique is useful enough that we've kept the |
| example in the manual. However if you were to build @code{true} and |
| @code{false} in real life, you would probably use per-program |
| compilation flags, like so: |
| |
| @c Keep in sync with specflg7.sh and specflg8.sh |
| @example |
| bin_PROGRAMS = false true |
| |
| false_SOURCES = true.c |
| false_CPPFLAGS = -DEXIT_CODE=1 |
| |
| true_SOURCES = true.c |
| true_CPPFLAGS = -DEXIT_CODE=0 |
| @end example |
| |
| In this case Automake will cause @file{true.c} to be compiled twice, |
| with different flags. In this instance, the names of the object files |
| would be chosen by automake; they would be @file{false-true.o} and |
| @file{true-true.o}. (The name of the object files rarely matters.) |
| |
| @node automake Invocation |
| @chapter Creating a @file{Makefile.in} |
| @c This node used to be named "Invoking automake". This @anchor |
| @c allows old links to still work. |
| @anchor{Invoking automake} |
| |
| @cindex Multiple @file{configure.ac} files |
| @cindex Invoking @command{automake} |
| @cindex @command{automake}, invoking |
| @cindex Invocation of @command{automake} |
| @cindex @command{automake}, invocation |
| |
| To create all the @file{Makefile.in}s for a package, run the |
| @command{automake} program in the top level directory, with no |
| arguments. @command{automake} will automatically find each |
| appropriate @file{Makefile.am} (by scanning @file{configure.ac}; |
| @pxref{configure}) and generate the corresponding @file{Makefile.in}. |
| Note that @command{automake} has a rather simplistic view of what |
| constitutes a package; it assumes that a package has only one |
| @file{configure.ac}, at the top. If your package has multiple |
| @file{configure.ac}s, then you must run @command{automake} in each |
| directory holding a @file{configure.ac}. (Alternatively, you may rely |
| on Autoconf's @command{autoreconf}, which is able to recurse your |
| package tree and run @command{automake} where appropriate.) |
| |
| You can optionally give @command{automake} an argument; @file{.am} is |
| appended to the argument and the result is used as the name of the |
| input file. This feature is generally only used to automatically |
| rebuild an out-of-date @file{Makefile.in}. Note that |
| @command{automake} must always be run from the topmost directory of a |
| project, even if being used to regenerate the @file{Makefile.in} in |
| some subdirectory. This is necessary because @command{automake} must |
| scan @file{configure.ac}, and because @command{automake} uses the |
| knowledge that a @file{Makefile.in} is in a subdirectory to change its |
| behavior in some cases. |
| |
| @vindex AUTOCONF |
| Automake will run @command{autoconf} to scan @file{configure.ac} and |
| its dependencies (i.e., @file{aclocal.m4} and any included file), |
| therefore @command{autoconf} must be in your @env{PATH}. If there is |
| an @env{AUTOCONF} variable in your environment it will be used |
| instead of @command{autoconf}, this allows you to select a particular |
| version of Autoconf. By the way, don't misunderstand this paragraph: |
| @command{automake} runs @command{autoconf} to @strong{scan} your |
| @file{configure.ac}, this won't build @file{configure} and you still |
| have to run @command{autoconf} yourself for this purpose. |
| |
| @cindex @command{automake} options |
| @cindex Options, @command{automake} |
| @cindex Strictness, command line |
| |
| @command{automake} accepts the following options: |
| |
| @cindex Extra files distributed with Automake |
| @cindex Files distributed with Automake |
| @cindex @file{config.guess} |
| |
| @table @code |
| @item -a |
| @itemx --add-missing |
| @opindex -a |
| @opindex --add-missing |
| Automake requires certain common files to exist in certain situations; |
| for instance, @file{config.guess} is required if @file{configure.ac} invokes |
| @code{AC_CANONICAL_HOST}. Automake is distributed with several of these |
| files (@pxref{Auxiliary Programs}); this option will cause the missing |
| ones to be automatically added to the package, whenever possible. In |
| general if Automake tells you a file is missing, try using this option. |
| By default Automake tries to make a symbolic link pointing to its own |
| copy of the missing file; this can be changed with @option{--copy}. |
| |
| Many of the potentially-missing files are common scripts whose |
| location may be specified via the @code{AC_CONFIG_AUX_DIR} macro. |
| Therefore, @code{AC_CONFIG_AUX_DIR}'s setting affects whether a |
| file is considered missing, and where the missing file is added |
| (@pxref{Optional}). |
| |
| In some strictness modes, additional files are installed, see @ref{Gnits} |
| for more information. |
| |
| @item --libdir=@var{dir} |
| @opindex --libdir |
| Look for Automake data files in directory @var{dir} instead of in the |
| installation directory. This is typically used for debugging. |
| |
| @item --print-libdir |
| @opindex --print-libdir |
| Print the path of the installation directory containing Automake-provided |
| scripts and data files (like e.g., @file{texinfo.texi} and |
| @file{install-sh}). |
| |
| @item -c |
| @opindex -c |
| @itemx --copy |
| @opindex --copy |
| When used with @option{--add-missing}, causes installed files to be |
| copied. The default is to make a symbolic link. |
| |
| @item -f |
| @opindex -f |
| @itemx --force-missing |
| @opindex --force-missing |
| When used with @option{--add-missing}, causes standard files to be reinstalled |
| even if they already exist in the source tree. This involves removing |
| the file from the source tree before creating the new symlink (or, with |
| @option{--copy}, copying the new file). |
| |
| @item --foreign |
| @opindex --foreign |
| Set the global strictness to @option{foreign}. For more information, see |
| @ref{Strictness}. |
| |
| @item --gnits |
| @opindex --gnits |
| Set the global strictness to @option{gnits}. For more information, see |
| @ref{Gnits}. |
| |
| @item --gnu |
| @opindex --gnu |
| Set the global strictness to @option{gnu}. For more information, see |
| @ref{Gnits}. This is the default strictness. |
| |
| @item --help |
| @opindex --help |
| Print a summary of the command line options and exit. |
| |
| @item -i |
| @itemx --ignore-deps |
| @opindex -i |
| This disables the dependency tracking feature in generated |
| @file{Makefile}s; see @ref{Dependencies}. |
| |
| @item --include-deps |
| @opindex --include-deps |
| This enables the dependency tracking feature. This feature is enabled |
| by default. This option is provided for historical reasons only and |
| probably should not be used. |
| |
| @item --no-force |
| @opindex --no-force |
| Ordinarily @command{automake} creates all @file{Makefile.in}s mentioned in |
| @file{configure.ac}. This option causes it to only update those |
| @file{Makefile.in}s that are out of date with respect to one of their |
| dependents. |
| |
| @item -o @var{dir} |
| @itemx --output-dir=@var{dir} |
| @opindex -o |
| @opindex --output-dir |
| Put the generated @file{Makefile.in} in the directory @var{dir}. |
| Ordinarily each @file{Makefile.in} is created in the directory of the |
| corresponding @file{Makefile.am}. This option is deprecated and will be |
| removed in a future release. |
| |
| @item -v |
| @itemx --verbose |
| @opindex -v |
| @opindex --verbose |
| Cause Automake to print information about which files are being read or |
| created. |
| |
| @item --version |
| @opindex --version |
| Print the version number of Automake and exit. |
| |
| @item -W CATEGORY |
| @itemx --warnings=@var{category} |
| @opindex -W |
| @opindex --warnings |
| Output warnings falling in @var{category}. @var{category} can be |
| one of: |
| @table @code |
| @item gnu |
| warnings related to the GNU Coding Standards |
| (@pxref{Top, , , standards, The GNU Coding Standards}). |
| @item obsolete |
| obsolete features or constructions |
| @item override |
| user redefinitions of Automake rules or variables |
| @item portability |
| portability issues; e.g., use of file names like @file{aux} that are |
| reserved on some systems (like Windows), or use of Automake features |
| that require support from the target C compiler, support that is |
| known not be present on all the mainstream C compilers. |
| @item extra-portability |
| extra portability issues related to obscure tools. One example of such |
| a tool is the Microsoft @command{lib} archiver. |
| @item syntax |
| weird syntax, unused variables, typos |
| @item unsupported |
| unsupported or incomplete features |
| @item all |
| all the warnings |
| @item none |
| turn off all the warnings |
| @item error |
| treat warnings as errors |
| @end table |
| |
| A category can be turned off by prefixing its name with @samp{no-}. For |
| instance, @option{-Wno-syntax} will hide the warnings about unused |
| variables. |
| |
| The categories output by default are @samp{syntax} and |
| @samp{unsupported}. Additionally, @samp{gnu} and @samp{portability} |
| are enabled in @option{--gnu} and @option{--gnits} strictness. |
| |
| @c Checked by extra-portability.sh |
| Turning off @samp{portability} will also turn off @samp{extra-portability}, |
| and similarly turning on @samp{extra-portability} will also turn on |
| @samp{portability}. However, turning on @samp{portability} or turning |
| off @samp{extra-portability} will not affect the other category. |
| |
| @vindex WARNINGS |
| The environment variable @env{WARNINGS} can contain a comma separated |
| list of categories to enable. It will be taken into account before the |
| command-line switches, this way @option{-Wnone} will also ignore any |
| warning category enabled by @env{WARNINGS}. This variable is also used |
| by other tools like @command{autoconf}; unknown categories are ignored |
| for this reason. |
| |
| @end table |
| |
| |
| @node configure |
| @chapter Scanning @file{configure.ac}, using @command{aclocal} |
| |
| @cindex @file{configure.ac}, scanning |
| @cindex Scanning @file{configure.ac} |
| @cindex Using @command{aclocal} |
| @cindex @command{aclocal}, using |
| |
| Automake scans the package's @file{configure.ac} to determine certain |
| information about the package. Some @command{autoconf} macros are required |
| and some variables must be defined in @file{configure.ac}. Automake |
| will also use information from @file{configure.ac} to further tailor its |
| output. |
| |
| Automake also supplies some Autoconf macros to make the maintenance |
| easier. These macros can automatically be put into your |
| @file{aclocal.m4} using the @command{aclocal} program. |
| |
| @menu |
| * Requirements:: Configuration requirements |
| * Optional:: Other things Automake recognizes |
| * aclocal Invocation:: Auto-generating aclocal.m4 |
| * Macros:: Autoconf macros supplied with Automake |
| @end menu |
| |
| |
| @node Requirements |
| @section Configuration requirements |
| |
| @cindex Automake requirements |
| @cindex Requirements of Automake |
| |
| @acindex AM_INIT_AUTOMAKE |
| The one real requirement of Automake is that your @file{configure.ac} |
| call @code{AM_INIT_AUTOMAKE}. This macro does several things that are |
| required for proper Automake operation (@pxref{Macros}). |
| |
| Here are the other macros that Automake requires but which are not run |
| by @code{AM_INIT_AUTOMAKE}: |
| |
| @table @code |
| @item AC_CONFIG_FILES |
| @itemx AC_OUTPUT |
| @acindex AC_CONFIG_FILES |
| @acindex AC_OUTPUT |
| These two macros are usually invoked as follows near the end of |
| @file{configure.ac}. |
| |
| @example |
| @dots{} |
| AC_CONFIG_FILES([ |
| Makefile |
| doc/Makefile |
| src/Makefile |
| src/lib/Makefile |
| @dots{} |
| ]) |
| AC_OUTPUT |
| @end example |
| |
| Automake uses these to determine which files to create (@pxref{Output, , |
| Creating Output Files, autoconf, The Autoconf Manual}). A listed file |
| is considered to be an Automake generated @file{Makefile} if there |
| exists a file with the same name and the @file{.am} extension appended. |
| Typically, @samp{AC_CONFIG_FILES([foo/Makefile])} will cause Automake to |
| generate @file{foo/Makefile.in} if @file{foo/Makefile.am} exists. |
| |
| When using @code{AC_CONFIG_FILES} with multiple input files, as in |
| |
| @example |
| AC_CONFIG_FILES([Makefile:top.in:Makefile.in:bot.in]) |
| @end example |
| |
| @noindent |
| @command{automake} will generate the first @file{.in} input file for |
| which a @file{.am} file exists. If no such file exists the output |
| file is not considered to be generated by Automake. |
| |
| Files created by @code{AC_CONFIG_FILES}, be they Automake |
| @file{Makefile}s or not, are all removed by @samp{make distclean}. |
| Their inputs are automatically distributed, unless they |
| are the output of prior @code{AC_CONFIG_FILES} commands. |
| Finally, rebuild rules are generated in the Automake @file{Makefile} |
| existing in the subdirectory of the output file, if there is one, or |
| in the top-level @file{Makefile} otherwise. |
| |
| The above machinery (cleaning, distributing, and rebuilding) works |
| fine if the @code{AC_CONFIG_FILES} specifications contain only |
| literals. If part of the specification uses shell variables, |
| @command{automake} will not be able to fulfill this setup, and you will |
| have to complete the missing bits by hand. For instance, on |
| |
| @c Keep in sync with output11.sh |
| @example |
| file=input |
| @dots{} |
| AC_CONFIG_FILES([output:$file],, [file=$file]) |
| @end example |
| |
| @noindent |
| @command{automake} will output rules to clean @file{output}, and |
| rebuild it. However the rebuild rule will not depend on @file{input}, |
| and this file will not be distributed either. (You must add |
| @samp{EXTRA_DIST = input} to your @file{Makefile.am} if @file{input} is a |
| source file.) |
| |
| Similarly |
| |
| @c Keep in sync with output11.sh |
| @example |
| file=output |
| file2=out:in |
| @dots{} |
| AC_CONFIG_FILES([$file:input],, [file=$file]) |
| AC_CONFIG_FILES([$file2],, [file2=$file2]) |
| @end example |
| |
| @noindent |
| will only cause @file{input} to be distributed. No file will be |
| cleaned automatically (add @samp{DISTCLEANFILES = output out} |
| yourself), and no rebuild rule will be output. |
| |
| Obviously @command{automake} cannot guess what value @samp{$file} is |
| going to hold later when @file{configure} is run, and it cannot use |
| the shell variable @samp{$file} in a @file{Makefile}. However, if you |
| make reference to @samp{$file} as @samp{$@{file@}} (i.e., in a way |
| that is compatible with @command{make}'s syntax) and furthermore use |
| @code{AC_SUBST} to ensure that @samp{$@{file@}} is meaningful in a |
| @file{Makefile}, then @command{automake} will be able to use |
| @samp{$@{file@}} to generate all of these rules. For instance, here is |
| how the Automake package itself generates versioned scripts for its |
| test suite: |
| |
| @example |
| AC_SUBST([APIVERSION], @dots{}) |
| @dots{} |
| AC_CONFIG_FILES( |
| [tests/aclocal-$@{APIVERSION@}:tests/aclocal.in], |
| [chmod +x tests/aclocal-$@{APIVERSION@}], |
| [APIVERSION=$APIVERSION]) |
| AC_CONFIG_FILES( |
| [tests/automake-$@{APIVERSION@}:tests/automake.in], |
| [chmod +x tests/automake-$@{APIVERSION@}]) |
| @end example |
| |
| @noindent |
| Here cleaning, distributing, and rebuilding are done automatically, |
| because @samp{$@{APIVERSION@}} is known at @command{make}-time. |
| |
| Note that you should not use shell variables to declare |
| @file{Makefile} files for which @command{automake} must create |
| @file{Makefile.in}. Even @code{AC_SUBST} does not help here, because |
| @command{automake} needs to know the file name when it runs in order |
| to check whether @file{Makefile.am} exists. (In the very hairy case |
| that your setup requires such use of variables, you will have to tell |
| Automake which @file{Makefile.in}s to generate on the command-line.) |
| |
| It is possible to let @command{automake} emit conditional rules for |
| @code{AC_CONFIG_FILES} with the help of @code{AM_COND_IF} |
| (@pxref{Optional}). |
| |
| To summarize: |
| @itemize @bullet |
| @item |
| Use literals for @file{Makefile}s, and for other files whenever possible. |
| @item |
| Use @samp{$file} (or @samp{$@{file@}} without @samp{AC_SUBST([file])}) |
| for files that @command{automake} should ignore. |
| @item |
| Use @samp{$@{file@}} and @samp{AC_SUBST([file])} for files |
| that @command{automake} should not ignore. |
| @end itemize |
| |
| @end table |
| |
| |
| @node Optional |
| @section Other things Automake recognizes |
| |
| @cindex Macros Automake recognizes |
| @cindex Recognized macros by Automake |
| |
| Every time Automake is run it calls Autoconf to trace |
| @file{configure.ac}. This way it can recognize the use of certain |
| macros and tailor the generated @file{Makefile.in} appropriately. |
| Currently recognized macros and their effects are: |
| |
| @ftable @code |
| @item AC_CANONICAL_BUILD |
| @itemx AC_CANONICAL_HOST |
| @itemx AC_CANONICAL_TARGET |
| @vindex build |
| @vindex host |
| @vindex target |
| Automake will ensure that @file{config.guess} and @file{config.sub} |
| exist. Also, the @file{Makefile} variables @code{build}, @code{host} |
| and @code{target} are introduced. See @ref{Canonicalizing, , |
| Getting the Canonical System Type, autoconf, The Autoconf Manual}. |
| |
| @item AC_CONFIG_AUX_DIR |
| Automake will look for various helper scripts, such as |
| @file{install-sh}, in the directory named in this macro invocation. |
| @c This list is accurate relative to version 1.11 |
| (The full list of scripts is: |
| @file{ar-lib}, |
| @file{config.guess}, |
| @file{config.sub}, |
| @file{depcomp}, |
| @file{compile}, |
| @file{install-sh}, |
| @file{ltmain.sh}, |
| @file{mdate-sh}, |
| @file{missing}, |
| @file{py-compile}, |
| @file{test-driver}, |
| @file{texinfo.tex}, |
| @file{ylwrap}.) |
| Not all scripts are always searched for; some scripts |
| will only be sought if the generated @file{Makefile.in} requires them. |
| |
| If @code{AC_CONFIG_AUX_DIR} is not given, the scripts are looked for in |
| their standard locations. For @file{mdate-sh}, |
| @file{texinfo.tex}, and @file{ylwrap}, the standard location is the |
| source directory corresponding to the current @file{Makefile.am}. For |
| the rest, the standard location is the first one of @file{.}, @file{..}, |
| or @file{../..} (relative to the top source directory) that provides any |
| one of the helper scripts. @xref{Input, , Finding `configure' Input, |
| autoconf, The Autoconf Manual}. |
| |
| Required files from @code{AC_CONFIG_AUX_DIR} are automatically |
| distributed, even if there is no @file{Makefile.am} in this directory. |
| |
| @item AC_CONFIG_LIBOBJ_DIR |
| Automake will require the sources file declared with |
| @code{AC_LIBSOURCE} (see below) in the directory specified by this |
| macro. |
| |
| @item AC_CONFIG_HEADERS |
| Automake will generate rules to rebuild these headers. Older versions |
| of Automake required the use of @code{AM_CONFIG_HEADER}; this is no |
| longer the case, and that macro has indeed been removed. |
| |
| As with @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the |
| specification using shell variables will be ignored as far as |
| cleaning, distributing, and rebuilding is concerned. |
| |
| @item AC_CONFIG_LINKS |
| Automake will generate rules to remove @file{configure} generated |
| links on @samp{make distclean} and to distribute named source files as |
| part of @samp{make dist}. |
| |
| As for @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the |
| specification using shell variables will be ignored as far as cleaning |
| and distributing is concerned. (There are no rebuild rules for links.) |
| |
| @item AC_LIBOBJ |
| @itemx AC_LIBSOURCE |
| @itemx AC_LIBSOURCES |
| @vindex LIBOBJS |
| Automake will automatically distribute any file listed in |
| @code{AC_LIBSOURCE} or @code{AC_LIBSOURCES}. |
| |
| Note that the @code{AC_LIBOBJ} macro calls @code{AC_LIBSOURCE}. So if |
| an Autoconf macro is documented to call @samp{AC_LIBOBJ([file])}, then |
| @file{file.c} will be distributed automatically by Automake. This |
| encompasses many macros like @code{AC_FUNC_ALLOCA}, |
| @code{AC_FUNC_MEMCMP}, @code{AC_REPLACE_FUNCS}, and others. |
| |
| By the way, direct assignments to @code{LIBOBJS} are no longer |
| supported. You should always use @code{AC_LIBOBJ} for this purpose. |
| @xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs.@: @code{LIBOBJS}, |
| autoconf, The Autoconf Manual}. |
| |
| @item AC_PROG_RANLIB |
| This is required if any libraries are built in the package. |
| @xref{Particular Programs, , Particular Program Checks, autoconf, The |
| Autoconf Manual}. |
| |
| @item AC_PROG_CXX |
| This is required if any C++ source is included. @xref{Particular |
| Programs, , Particular Program Checks, autoconf, The Autoconf Manual}. |
| |
| @item AC_PROG_OBJC |
| This is required if any Objective C source is included. @xref{Particular |
| Programs, , Particular Program Checks, autoconf, The Autoconf Manual}. |
| |
| @item AC_PROG_OBJCXX |
| This is required if any Objective C++ source is included. @xref{Particular |
| Programs, , Particular Program Checks, autoconf, The Autoconf Manual}. |
| |
| @item AC_PROG_F77 |
| This is required if any Fortran 77 source is included. @xref{Particular |
| Programs, , Particular Program Checks, autoconf, The Autoconf Manual}. |
| |
| @item AC_F77_LIBRARY_LDFLAGS |
| This is required for programs and shared libraries that are a mixture of |
| languages that include Fortran 77 (@pxref{Mixing Fortran 77 With C and |
| C++}). @xref{Macros, , Autoconf macros supplied with Automake}. |
| |
| @item AC_FC_SRCEXT |
| Automake will add the flags computed by @code{AC_FC_SRCEXT} to compilation |
| of files with the respective source extension (@pxref{Fortran Compiler, , |
| Fortran Compiler Characteristics, autoconf, The Autoconf Manual}). |
| |
| @item AC_PROG_FC |
| This is required if any Fortran 90/95 source is included. This macro is |
| distributed with Autoconf version 2.58 and later. @xref{Particular |
| Programs, , Particular Program Checks, autoconf, The Autoconf Manual}. |
| |
| @item AC_PROG_LIBTOOL |
| Automake will turn on processing for @command{libtool} (@pxref{Top, , |
| Introduction, libtool, The Libtool Manual}). |
| |
| @item AC_PROG_YACC |
| @vindex YACC |
| If a Yacc source file is seen, then you must either use this macro or |
| define the variable @code{YACC} in @file{configure.ac}. The former is |
| preferred (@pxref{Particular Programs, , Particular Program Checks, |
| autoconf, The Autoconf Manual}). |
| |
| @item AC_PROG_LEX |
| If a Lex source file is seen, then this macro must be used. |
| @xref{Particular Programs, , Particular Program Checks, autoconf, The |
| Autoconf Manual}. |
| |
| @item AC_REQUIRE_AUX_FILE |
| For each @code{AC_REQUIRE_AUX_FILE([@var{file}])}, |
| @command{automake} will ensure that @file{@var{file}} exists in the |
| aux directory, and will complain otherwise. It |
| will also automatically distribute the file. This macro should be |
| used by third-party Autoconf macros that require some supporting |
| files in the aux directory specified with @code{AC_CONFIG_AUX_DIR} |
| above. @xref{Input, , Finding @command{configure} Input, autoconf, |
| The Autoconf Manual}. |
| |
| @item AC_SUBST |
| The first argument is automatically defined as a variable in each |
| generated @file{Makefile.in}, unless @code{AM_SUBST_NOTMAKE} is also |
| used for this variable. @xref{Setting Output Variables, , Setting |
| Output Variables, autoconf, The Autoconf Manual}. |
| |
| For every substituted variable @var{var}, @command{automake} will add |
| a line @code{@var{var} = @var{value}} to each @file{Makefile.in} file. |
| Many Autoconf macros invoke @code{AC_SUBST} to set output variables |
| this way, e.g., @code{AC_PATH_XTRA} defines @code{X_CFLAGS} and |
| @code{X_LIBS}. Thus, you can access these variables as |
| @code{$(X_CFLAGS)} and @code{$(X_LIBS)} in any @file{Makefile.am} |
| if @code{AC_PATH_XTRA} is called. |
| |
| @item AM_CONDITIONAL |
| This introduces an Automake conditional (@pxref{Conditionals}). |
| |
| @item AM_COND_IF |
| This macro allows @code{automake} to detect subsequent access within |
| @file{configure.ac} to a conditional previously introduced with |
| @code{AM_CONDITIONAL}, thus enabling conditional @code{AC_CONFIG_FILES} |
| (@pxref{Usage of Conditionals}). |
| |
| @item AM_GNU_GETTEXT |
| This macro is required for packages that use GNU gettext |
| (@pxref{gettext}). It is distributed with gettext. If Automake sees |
| this macro it ensures that the package meets some of gettext's |
| requirements. |
| |
| @item AM_GNU_GETTEXT_INTL_SUBDIR |
| This macro specifies that the @file{intl/} subdirectory is to be built, |
| even if the @code{AM_GNU_GETTEXT} macro was invoked with a first argument |
| of @samp{external}. |
| |
| @item AM_SUBST_NOTMAKE(@var{var}) |
| Prevent Automake from defining a variable @var{var}, even if it is |
| substituted by @command{config.status}. Normally, Automake defines a |
| @command{make} variable for each @command{configure} substitution, |
| i.e., for each @code{AC_SUBST([@var{var}])}. This macro prevents that |
| definition from Automake. If @code{AC_SUBST} has not been called |
| for this variable, then @code{AM_SUBST_NOTMAKE} has no effects. |
| Preventing variable definitions may be useful for substitution of |
| multi-line values, where @code{@var{var} = @@@var{value}@@} might yield |
| unintended results. |
| |
| @item m4_include |
| Files included by @file{configure.ac} using this macro will be |
| detected by Automake and automatically distributed. They will also |
| appear as dependencies in @file{Makefile} rules. |
| |
| @code{m4_include} is seldom used by @file{configure.ac} authors, but |
| can appear in @file{aclocal.m4} when @command{aclocal} detects that |
| some required macros come from files local to your package (as opposed to |
| macros installed in a system-wide directory, @pxref{aclocal Invocation}). |
| |
| @end ftable |
| |
| @node aclocal Invocation |
| @section Auto-generating aclocal.m4 |
| @c This node used to be named "Invoking automake". This @anchor |
| @c allows old links to still work. |
| @anchor{Invoking aclocal} |
| |
| @cindex Invocation of @command{aclocal} |
| @cindex @command{aclocal}, Invocation |
| @cindex Invoking @command{aclocal} |
| @cindex @command{aclocal}, Invoking |
| |
| Automake includes a number of Autoconf macros that can be used in |
| your package (@pxref{Macros}); some of them are actually required by |
| Automake in certain situations. These macros must be defined in your |
| @file{aclocal.m4}; otherwise they will not be seen by |
| @command{autoconf}. |
| |
| The @command{aclocal} program will automatically generate |
| @file{aclocal.m4} files based on the contents of @file{configure.ac}. |
| This provides a convenient way to get Automake-provided macros, |
| without having to search around. The @command{aclocal} mechanism |
| allows other packages to supply their own macros (@pxref{Extending |
| aclocal}). You can also use it to maintain your own set of custom |
| macros (@pxref{Local Macros}). |
| |
| At startup, @command{aclocal} scans all the @file{.m4} files it can |
| find, looking for macro definitions (@pxref{Macro Search Path}). Then |
| it scans @file{configure.ac}. Any mention of one of the macros found |
| in the first step causes that macro, and any macros it in turn |
| requires, to be put into @file{aclocal.m4}. |
| |
| @emph{Putting} the file that contains the macro definition into |
| @file{aclocal.m4} is usually done by copying the entire text of this |
| file, including unused macro definitions as well as both @samp{#} and |
| @samp{dnl} comments. If you want to make a comment that will be |
| completely ignored by @command{aclocal}, use @samp{##} as the comment |
| leader. |
| |
| When a file selected by @command{aclocal} is located in a subdirectory |
| specified as a relative search path with @command{aclocal}'s @option{-I} |
| argument, @command{aclocal} assumes the file belongs to the package |
| and uses @code{m4_include} instead of copying it into |
| @file{aclocal.m4}. This makes the package smaller, eases dependency |
| tracking, and cause the file to be distributed automatically. |
| (@xref{Local Macros}, for an example.) Any macro that is found in a |
| system-wide directory, or via an absolute search path will be copied. |
| So use @samp{-I `pwd`/reldir} instead of @samp{-I reldir} whenever |
| some relative directory should be considered outside the package. |
| |
| The contents of @file{acinclude.m4}, if this file exists, are also |
| automatically included in @file{aclocal.m4}. We recommend against |
| using @file{acinclude.m4} in new packages (@pxref{Local Macros}). |
| |
| @vindex AUTOM4TE |
| @cindex autom4te |
| While computing @file{aclocal.m4}, @command{aclocal} runs |
| @command{autom4te} (@pxref{Using autom4te, , Using @command{Autom4te}, |
| autoconf, The Autoconf Manual}) in order to trace the macros that are |
| really used, and omit from @file{aclocal.m4} all macros that are |
| mentioned but otherwise unexpanded (this can happen when a macro is |
| called conditionally). @command{autom4te} is expected to be in the |
| @env{PATH}, just as @command{autoconf}. Its location can be |
| overridden using the @env{AUTOM4TE} environment variable. |
| |
| @menu |
| * aclocal Options:: Options supported by aclocal |
| * Macro Search Path:: How aclocal finds .m4 files |
| * Extending aclocal:: Writing your own aclocal macros |
| * Local Macros:: Organizing local macros |
| * Serials:: Serial lines in Autoconf macros |
| * Future of aclocal:: aclocal's scheduled death |
| @end menu |
| |
| @node aclocal Options |
| @subsection aclocal Options |
| |
| @cindex @command{aclocal}, Options |
| @cindex Options, @command{aclocal} |
| |
| @command{aclocal} accepts the following options: |
| |
| @table @code |
| @item --automake-acdir=@var{dir} |
| @opindex --automake-acdir |
| Look for the automake-provided macro files in @var{dir} instead of |
| in the installation directory. This is typically used for debugging. |
| |
| @item --system-acdir=@var{dir} |
| @opindex --system-acdir |
| Look for the system-wide third-party macro files (and the special |
| @file{dirlist} file) in @var{dir} instead of in the installation |
| directory. This is typically used for debugging. |
| |
| @item --diff[=@var{command}] |
| @opindex --diff |
| Run @var{command} on M4 file that would be installed or overwritten |
| by @option{--install}. The default @var{command} is @samp{diff -u}. |
| This option implies @option{--install} and @option{--dry-run}. |
| |
| @item --dry-run |
| @opindex --dry-run |
| Do not actually overwrite (or create) @file{aclocal.m4} and M4 |
| files installed by @option{--install}. |
| |
| @item --help |
| @opindex --help |
| Print a summary of the command line options and exit. |
| |
| @item -I @var{dir} |
| @opindex -I |
| Add the directory @var{dir} to the list of directories searched for |
| @file{.m4} files. |
| |
| @item --install |
| @opindex --install |
| Install system-wide third-party macros into the first directory |
| specified with @samp{-I @var{dir}} instead of copying them in the |
| output file. |
| @c Keep in sync with aclocal-install-absdir.sh |
| Note that this will happen also if @var{dir} is an absolute path. |
| |
| @cindex serial number and @option{--install} |
| When this option is used, and only when this option is used, |
| @command{aclocal} will also honor @samp{#serial @var{number}} lines |
| that appear in macros: an M4 file is ignored if there exists another |
| M4 file with the same basename and a greater serial number in the |
| search path (@pxref{Serials}). |
| |
| @item --force |
| @opindex --force |
| Always overwrite the output file. The default is to overwrite the output |
| file only when really needed, i.e., when its contents changes or if one |
| of its dependencies is younger. |
| |
| This option forces the update of @file{aclocal.m4} (or the file |
| specified with @file{--output} below) and only this file, it has |
| absolutely no influence on files that may need to be installed by |
| @option{--install}. |
| |
| @item --output=@var{file} |
| @opindex --output |
| Cause the output to be put into @var{file} instead of @file{aclocal.m4}. |
| |
| @item --print-ac-dir |
| @opindex --print-ac-dir |
| Prints the name of the directory that @command{aclocal} will search to |
| find third-party @file{.m4} files. When this option is given, normal |
| processing is suppressed. This option was used @emph{in the past} by |
| third-party packages to determine where to install @file{.m4} macro |
| files, but @emph{this usage is today discouraged}, since it causes |
| @samp{$(prefix)} not to be thoroughly honoured (which violates the |
| GNU Coding Standards), and a similar semantics can be better obtained |
| with the @env{ACLOCAL_PATH} environment variable; @pxref{Extending aclocal}. |
| |
| @item --verbose |
| @opindex --verbose |
| Print the names of the files it examines. |
| |
| @item --version |
| @opindex --version |
| Print the version number of Automake and exit. |
| |
| @item -W CATEGORY |
| @item --warnings=@var{category} |
| @opindex -W |
| @opindex --warnings |
| Output warnings falling in @var{category}. @var{category} can be |
| one of: |
| @table @code |
| @item syntax |
| dubious syntactic constructs, underquoted macros, unused macros, etc. |
| @item unsupported |
| unknown macros |
| @item all |
| all the warnings, this is the default |
| @item none |
| turn off all the warnings |
| @item error |
| treat warnings as errors |
| @end table |
| |
| All warnings are output by default. |
| |
| @vindex WARNINGS |
| The environment variable @env{WARNINGS} is honored in the same |
| way as it is for @command{automake} (@pxref{automake Invocation}). |
| |
| @end table |
| |
| @node Macro Search Path |
| @subsection Macro Search Path |
| |
| @cindex Macro search path |
| @cindex @command{aclocal} search path |
| |
| By default, @command{aclocal} searches for @file{.m4} files in the following |
| directories, in this order: |
| |
| @table @code |
| @item @var{acdir-APIVERSION} |
| This is where the @file{.m4} macros distributed with Automake itself |
| are stored. @var{APIVERSION} depends on the Automake release used; |
| for example, for Automake 1.11.x, @var{APIVERSION} = @code{1.11}. |
| |
| @item @var{acdir} |
| This directory is intended for third party @file{.m4} files, and is |
| configured when @command{automake} itself is built. This is |
| @file{@@datadir@@/aclocal/}, which typically |
| expands to @file{$@{prefix@}/share/aclocal/}. To find the compiled-in |
| value of @var{acdir}, use the @option{--print-ac-dir} option |
| (@pxref{aclocal Options}). |
| @end table |
| |
| As an example, suppose that @command{automake-1.11.2} was configured with |
| @option{--prefix=@-/usr/local}. Then, the search path would be: |
| |
| @enumerate |
| @item @file{/usr/local/share/aclocal-1.11.2/} |
| @item @file{/usr/local/share/aclocal/} |
| @end enumerate |
| |
| The paths for the @var{acdir} and @var{acdir-APIVERSION} directories can |
| be changed respectively through aclocal options @option{--system-acdir} |
| and @option{--automake-acdir} (@pxref{aclocal Options}). Note however |
| that these options are only intended for use by the internal Automake |
| test suite, or for debugging under highly unusual situations; they are |
| not ordinarily needed by end-users. |
| |
| As explained in (@pxref{aclocal Options}), there are several options that |
| can be used to change or extend this search path. |
| |
| @subsubheading Modifying the Macro Search Path: @samp{-I @var{dir}} |
| |
| Any extra directories specified using @option{-I} options |
| (@pxref{aclocal Options}) are @emph{prepended} to this search list. Thus, |
| @samp{aclocal -I /foo -I /bar} results in the following search path: |
| |
| @enumerate |
| @item @file{/foo} |
| @item @file{/bar} |
| @item @var{acdir}-@var{APIVERSION} |
| @item @var{acdir} |
| @end enumerate |
| |
| @subsubheading Modifying the Macro Search Path: @file{dirlist} |
| @cindex @file{dirlist} |
| |
| There is a third mechanism for customizing the search path. If a |
| @file{dirlist} file exists in @var{acdir}, then that file is assumed to |
| contain a list of directory patterns, one per line. @command{aclocal} |
| expands these patterns to directory names, and adds them to the search |
| list @emph{after} all other directories. @file{dirlist} entries may |
| use shell wildcards such as @samp{*}, @samp{?}, or @code{[...]}. |
| |
| For example, suppose |
| @file{@var{acdir}/dirlist} contains the following: |
| |
| @example |
| /test1 |
| /test2 |
| /test3* |
| @end example |
| |
| @noindent |
| and that @command{aclocal} was called with the @samp{-I /foo -I /bar} options. |
| Then, the search path would be |
| |
| @c @code looks better than @file here |
| @enumerate |
| @item @code{/foo} |
| @item @code{/bar} |
| @item @var{acdir}-@var{APIVERSION} |
| @item @var{acdir} |
| @item @code{/test1} |
| @item @code{/test2} |
| @end enumerate |
| |
| @noindent |
| and all directories with path names starting with @code{/test3}. |
| |
| If the @option{--system-acdir=@var{dir}} option is used, then |
| @command{aclocal} will search for the @file{dirlist} file in |
| @var{dir}; but remember the warnings above against the use of |
| @option{--system-acdir}. |
| |
| @file{dirlist} is useful in the following situation: suppose that |
| @command{automake} version @code{1.11.2} is installed with |
| @samp{--prefix=/usr} by the system vendor. Thus, the default search |
| directories are |
| |
| @c @code looks better than @file here |
| @enumerate |
| @item @code{/usr/share/aclocal-1.11/} |
| @item @code{/usr/share/aclocal/} |
| @end enumerate |
| |
| However, suppose further that many packages have been manually |
| installed on the system, with $prefix=/usr/local, as is typical. In |
| that case, many of these ``extra'' @file{.m4} files are in |
| @file{/usr/local/share/aclocal}. The only way to force |
| @file{/usr/bin/aclocal} to find these ``extra'' @file{.m4} files is to |
| always call @samp{aclocal -I /usr/local/share/aclocal}. This is |
| inconvenient. With @file{dirlist}, one may create a file |
| @file{/usr/share/aclocal/dirlist} containing only the single line |
| |
| @example |
| /usr/local/share/aclocal |
| @end example |
| |
| Now, the ``default'' search path on the affected system is |
| |
| @c @code looks better than @file here |
| @enumerate |
| @item @code{/usr/share/aclocal-1.11/} |
| @item @code{/usr/share/aclocal/} |
| @item @code{/usr/local/share/aclocal/} |
| @end enumerate |
| |
| without the need for @option{-I} options; @option{-I} options can be reserved |
| for project-specific needs (@file{my-source-dir/m4/}), rather than |
| using it to work around local system-dependent tool installation |
| directories. |
| |
| Similarly, @file{dirlist} can be handy if you have installed a local |
| copy of Automake in your account and want @command{aclocal} to look for |
| macros installed at other places on the system. |
| |
| @anchor{ACLOCAL_PATH} |
| @subsubheading Modifying the Macro Search Path: @file{ACLOCAL_PATH} |
| @cindex @env{ACLOCAL_PATH} |
| |
| The fourth and last mechanism to customize the macro search path is |
| also the simplest. Any directory included in the colon-separated |
| environment variable @env{ACLOCAL_PATH} is added to the search path |
| @c Keep in sync with aclocal-path-precedence.sh |
| and takes precedence over system directories (including those found via |
| @file{dirlist}), with the exception of the versioned directory |
| @var{acdir-APIVERSION} (@pxref{Macro Search Path}). However, directories |
| passed via @option{-I} will take precedence over directories in |
| @env{ACLOCAL_PATH}. |
| |
| @c Keep in sync with aclocal-path-installed.sh |
| Also note that, if the @option{--install} option is used, any @file{.m4} |
| file containing a required macro that is found in a directory listed in |
| @env{ACLOCAL_PATH} will be installed locally. |
| @c Keep in sync with aclocal-path-installed-serial.sh |
| In this case, serial numbers in @file{.m4} are honoured too, |
| @pxref{Serials}. |
| |
| Conversely to @file{dirlist}, @env{ACLOCAL_PATH} is useful if you are |
| using a global copy of Automake and want @command{aclocal} to look for |
| macros somewhere under your home directory. |
| |
| @subsubheading Planned future incompatibilities |
| |
| The order in which the directories in the macro search path are currently |
| looked up is confusing and/or suboptimal in various aspects, and is |
| probably going to be changed in the future Automake release. In |
| particular, directories in @env{ACLOCAL_PATH} and @file{@var{acdir}} |
| might end up taking precedence over @file{@var{acdir-APIVERSION}}, and |
| directories in @file{@var{acdir}/dirlist} might end up taking precedence |
| over @file{@var{acdir}}. @emph{This is a possible future incompatibility!} |
| |
| @node Extending aclocal |
| @subsection Writing your own aclocal macros |
| |
| @cindex @command{aclocal}, extending |
| @cindex Extending @command{aclocal} |
| |
| The @command{aclocal} program doesn't have any built-in knowledge of any |
| macros, so it is easy to extend it with your own macros. |
| |
| This can be used by libraries that want to supply their own Autoconf |
| macros for use by other programs. For instance, the @command{gettext} |
| library supplies a macro @code{AM_GNU_GETTEXT} that should be used by |
| any package using @command{gettext}. When the library is installed, it |
| installs this macro so that @command{aclocal} will find it. |
| |
| A macro file's name should end in @file{.m4}. Such files should be |
| installed in @file{$(datadir)/aclocal}. This is as simple as writing: |
| |
| @c Keep in sync with primary-prefix-couples-documented-valid.sh |
| @example |
| aclocaldir = $(datadir)/aclocal |
| aclocal_DATA = mymacro.m4 myothermacro.m4 |
| @end example |
| |
| @noindent |
| Please do use @file{$(datadir)/aclocal}, and not something based on |
| the result of @samp{aclocal --print-ac-dir} (@pxref{Hard-Coded Install |
| Paths}, for arguments). It might also be helpful to suggest to |
| the user to add the @file{$(datadir)/aclocal} directory to his |
| @env{ACLOCAL_PATH} variable (@pxref{ACLOCAL_PATH}) so that |
| @command{aclocal} will find the @file{.m4} files installed by your |
| package automatically. |
| |
| A file of macros should be a series of properly quoted |
| @code{AC_DEFUN}'s (@pxref{Macro Definitions, , , autoconf, The |
| Autoconf Manual}). The @command{aclocal} programs also understands |
| @code{AC_REQUIRE} (@pxref{Prerequisite Macros, , , autoconf, The |
| Autoconf Manual}), so it is safe to put each macro in a separate file. |
| Each file should have no side effects but macro definitions. |
| Especially, any call to @code{AC_PREREQ} should be done inside the |
| defined macro, not at the beginning of the file. |
| |
| @cindex underquoted @code{AC_DEFUN} |
| @acindex AC_DEFUN |
| @acindex AC_PREREQ |
| |
| Starting with Automake 1.8, @command{aclocal} will warn about all |
| underquoted calls to @code{AC_DEFUN}. We realize this will annoy a |
| lot of people, because @command{aclocal} was not so strict in the past |
| and many third party macros are underquoted; and we have to apologize |
| for this temporary inconvenience. The reason we have to be stricter |
| is that a future implementation of @command{aclocal} (@pxref{Future of |
| aclocal}) will have to temporarily include all of these third party |
| @file{.m4} files, maybe several times, including even files that are |
| not actually needed. Doing so should alleviate many problems of the |
| current implementation, however it requires a stricter style from the |
| macro authors. Hopefully it is easy to revise the existing macros. |
| For instance, |
| |
| @example |
| # bad style |
| AC_PREREQ(2.68) |
| AC_DEFUN(AX_FOOBAR, |
| [AC_REQUIRE([AX_SOMETHING])dnl |
| AX_FOO |
| AX_BAR |
| ]) |
| @end example |
| |
| @noindent |
| should be rewritten as |
| |
| @example |
| AC_DEFUN([AX_FOOBAR], |
| [AC_PREREQ([2.68])dnl |
| AC_REQUIRE([AX_SOMETHING])dnl |
| AX_FOO |
| AX_BAR |
| ]) |
| @end example |
| |
| Wrapping the @code{AC_PREREQ} call inside the macro ensures that |
| Autoconf 2.68 will not be required if @code{AX_FOOBAR} is not actually |
| used. Most importantly, quoting the first argument of @code{AC_DEFUN} |
| allows the macro to be redefined or included twice (otherwise this |
| first argument would be expanded during the second definition). For |
| consistency we like to quote even arguments such as @code{2.68} that |
| do not require it. |
| |
| If you have been directed here by the @command{aclocal} diagnostic but |
| are not the maintainer of the implicated macro, you will want to |
| contact the maintainer of that macro. Please make sure you have the |
| latest version of the macro and that the problem hasn't already been |
| reported before doing so: people tend to work faster when they aren't |
| flooded by mails. |
| |
| Another situation where @command{aclocal} is commonly used is to |
| manage macros that are used locally by the package, @ref{Local |
| Macros}. |
| |
| @node Local Macros |
| @subsection Handling Local Macros |
| |
| Feature tests offered by Autoconf do not cover all needs. People |
| often have to supplement existing tests with their own macros, or |
| with third-party macros. |
| |
| There are two ways to organize custom macros in a package. |
| |
| The first possibility (the historical practice) is to list all your |
| macros in @file{acinclude.m4}. This file will be included in |
| @file{aclocal.m4} when you run @command{aclocal}, and its macro(s) will |
| henceforth be visible to @command{autoconf}. However if it contains |
| numerous macros, it will rapidly become difficult to maintain, and it |
| will be almost impossible to share macros between packages. |
| |
| The second possibility, which we do recommend, is to write each macro |
| in its own file and gather all these files in a directory. This |
| directory is usually called @file{m4/}. Then it's enough to update |
| @file{configure.ac} by adding a proper call to @code{AC_CONFIG_MACRO_DIR}: |
| |
| @example |
| AC_CONFIG_MACRO_DIR([m4]) |
| @end example |
| |
| @command{aclocal} will then take care of automatically adding @file{m4/} |
| to its search path for m4 files. |
| |
| When @samp{aclocal} is run, it will build an @file{aclocal.m4} |
| that @code{m4_include}s any file from @file{m4/} that defines a |
| required macro. Macros not found locally will still be searched in |
| system-wide directories, as explained in @ref{Macro Search Path}. |
| |
| Custom macros should be distributed for the same reason that |
| @file{configure.ac} is: so that other people have all the sources of |
| your package if they want to work on it. Actually, this distribution |
| happens automatically because all @code{m4_include}d files are |
| distributed. |
| |
| However there is no consensus on the distribution of third-party |
| macros that your package may use. Many libraries install their own |
| macro in the system-wide @command{aclocal} directory (@pxref{Extending |
| aclocal}). For instance, Guile ships with a file called |
| @file{guile.m4} that contains the macro @code{GUILE_FLAGS} that can |
| be used to define setup compiler and linker flags appropriate for |
| using Guile. Using @code{GUILE_FLAGS} in @file{configure.ac} will |
| cause @command{aclocal} to copy @file{guile.m4} into |
| @file{aclocal.m4}, but as @file{guile.m4} is not part of the project, |
| it will not be distributed. Technically, that means a user who |
| needs to rebuild @file{aclocal.m4} will have to install Guile first. |
| This is probably OK, if Guile already is a requirement to build the |
| package. However, if Guile is only an optional feature, or if your |
| package might run on architectures where Guile cannot be installed, |
| this requirement will hinder development. An easy solution is to copy |
| such third-party macros in your local @file{m4/} directory so they get |
| distributed. |
| |
| Since Automake 1.10, @command{aclocal} offers the option @code{--install} |
| to copy these system-wide third-party macros in your local macro directory, |
| helping to solve the above problem. |
| |
| With this setup, system-wide macros will be copied to @file{m4/} |
| the first time you run @command{aclocal}. Then the locally installed |
| macros will have precedence over the system-wide installed macros |
| each time @command{aclocal} is run again. |
| |
| One reason why you should keep @option{--install} in the flags even |
| after the first run is that when you later edit @file{configure.ac} |
| and depend on a new macro, this macro will be installed in your |
| @file{m4/} automatically. Another one is that serial numbers |
| (@pxref{Serials}) can be used to update the macros in your source tree |
| automatically when new system-wide versions are installed. A serial |
| number should be a single line of the form |
| |
| @example |
| #serial @var{nnn} |
| @end example |
| |
| @noindent |
| where @var{nnn} contains only digits and dots. It should appear in |
| the M4 file before any macro definition. It is a good practice to |
| maintain a serial number for each macro you distribute, even if you do |
| not use the @option{--install} option of @command{aclocal}: this allows |
| other people to use it. |
| |
| |
| @node Serials |
| @subsection Serial Numbers |
| @cindex serial numbers in macros |
| @cindex macro serial numbers |
| @cindex @code{#serial} syntax |
| @cindex @command{aclocal} and serial numbers |
| |
| Because third-party macros defined in @file{*.m4} files are naturally |
| shared between multiple projects, some people like to version them. |
| This makes it easier to tell which of two M4 files is newer. Since at |
| least 1996, the tradition is to use a @samp{#serial} line for this. |
| |
| A serial number should be a single line of the form |
| |
| @example |
| # serial @var{version} |
| @end example |
| |
| @noindent |
| where @var{version} is a version number containing only digits and |
| dots. Usually people use a single integer, and they increment it each |
| time they change the macro (hence the name of ``serial''). Such a |
| line should appear in the M4 file before any macro definition. |
| |
| The @samp{#} must be the first character on the line, |
| and it is OK to have extra words after the version, as in |
| |
| @example |
| #serial @var{version} @var{garbage} |
| @end example |
| |
| Normally these serial numbers are completely ignored by |
| @command{aclocal} and @command{autoconf}, like any genuine comment. |
| However when using @command{aclocal}'s @option{--install} feature, these |
| serial numbers will modify the way @command{aclocal} selects the |
| macros to install in the package: if two files with the same basename |
| exist in your search path, and if at least one of them uses a |
| @samp{#serial} line, @command{aclocal} will ignore the file that has |
| the older @samp{#serial} line (or the file that has none). |
| |
| Note that a serial number applies to a whole M4 file, not to any macro |
| it contains. A file can contains multiple macros, but only one |
| serial. |
| |
| Here is a use case that illustrates the use of @option{--install} and |
| its interaction with serial numbers. Let's assume we maintain a |
| package called MyPackage, the @file{configure.ac} of which requires a |
| third-party macro @code{AX_THIRD_PARTY} defined in |
| @file{/usr/share/aclocal/thirdparty.m4} as follows: |
| |
| @example |
| # serial 1 |
| AC_DEFUN([AX_THIRD_PARTY], [...]) |
| @end example |
| |
| MyPackage uses an @file{m4/} directory to store local macros as |
| explained in @ref{Local Macros}, and has |
| |
| @example |
| AC_CONFIG_MACRO_DIR([m4]) |
| @end example |
| |
| @noindent |
| in its @file{configure.ac}. |
| |
| Initially the @file{m4/} directory is empty. The first time we run |
| @command{aclocal --install}, it will notice that |
| |
| @itemize @bullet |
| @item |
| @file{configure.ac} uses @code{AX_THIRD_PARTY} |
| @item |
| No local macros define @code{AX_THIRD_PARTY} |
| @item |
| @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY} |
| with serial 1. |
| @end itemize |
| |
| @noindent |
| Because @file{/usr/share/aclocal/thirdparty.m4} is a system-wide macro |
| and @command{aclocal} was given the @option{--install} option, it will |
| copy this file in @file{m4/thirdparty.m4}, and output an |
| @file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}. |
| |
| The next time @samp{aclocal --install} is run, something different |
| happens. @command{aclocal} notices that |
| |
| @itemize @bullet |
| @item |
| @file{configure.ac} uses @code{AX_THIRD_PARTY} |
| @item |
| @file{m4/thirdparty.m4} defines @code{AX_THIRD_PARTY} |
| with serial 1. |
| @item |
| @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY} |
| with serial 1. |
| @end itemize |
| |
| @noindent |
| Because both files have the same serial number, @command{aclocal} uses |
| the first it found in its search path order (@pxref{Macro Search |
| Path}). @command{aclocal} therefore ignores |
| @file{/usr/share/aclocal/thirdparty.m4} and outputs an |
| @file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}. |
| |
| Local directories specified with @option{-I} are always searched before |
| system-wide directories, so a local file will always be preferred to |
| the system-wide file in case of equal serial numbers. |
| |
| Now suppose the system-wide third-party macro is changed. This can |
| happen if the package installing this macro is updated. Let's suppose |
| the new macro has serial number 2. The next time @samp{aclocal --install} |
| is run the situation is the following: |
| |
| @itemize @bullet |
| @item |
| @file{configure.ac} uses @code{AX_THIRD_PARTY} |
| @item |
| @file{m4/thirdparty.m4} defines @code{AX_THIRD_PARTY} |
| with serial 1. |
| @item |
| @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY} |
| with serial 2. |
| @end itemize |
| |
| @noindent |
| When @command{aclocal} sees a greater serial number, it immediately |
| forgets anything it knows from files that have the same basename and a |
| smaller serial number. So after it has found |
| @file{/usr/share/aclocal/thirdparty.m4} with serial 2, |
| @command{aclocal} will proceed as if it had never seen |
| @file{m4/thirdparty.m4}. This brings us back to a situation similar |
| to that at the beginning of our example, where no local file defined |
| the macro. @command{aclocal} will install the new version of the |
| macro in @file{m4/thirdparty.m4}, in this case overriding the old |
| version. MyPackage just had its macro updated as a side effect of |
| running @command{aclocal}. |
| |
| If you are leery of letting @command{aclocal} update your local |
| macro, you can run @samp{aclocal --diff} to review the changes |
| @samp{aclocal --install} would perform on these macros. |
| |
| Finally, note that the @option{--force} option of @command{aclocal} has |
| absolutely no effect on the files installed by @option{--install}. For |
| instance, if you have modified your local macros, do not expect |
| @option{--install --force} to replace the local macros by their |
| system-wide versions. If you want to do so, simply erase the local |
| macros you want to revert, and run @samp{aclocal --install}. |
| |
| |
| @node Future of aclocal |
| @subsection The Future of @command{aclocal} |
| @cindex @command{aclocal}'s scheduled death |
| |
| @command{aclocal} is expected to disappear. This feature really |
| should not be offered by Automake. Automake should focus on |
| generating @file{Makefile}s; dealing with M4 macros really is |
| Autoconf's job. The fact that some people install Automake just to use |
| @command{aclocal}, but do not use @command{automake} otherwise is an |
| indication of how that feature is misplaced. |
| |
| The new implementation will probably be done slightly differently. |
| For instance, it could enforce the @file{m4/}-style layout discussed in |
| @ref{Local Macros}. |
| |
| We have no idea when and how this will happen. This has been |
| discussed several times in the past, but someone still has to commit |
| to that non-trivial task. |
| |
| From the user point of view, @command{aclocal}'s removal might turn |
| out to be painful. There is a simple precaution that you may take to |
| make that switch more seamless: never call @command{aclocal} yourself. |
| Keep this guy under the exclusive control of @command{autoreconf} and |
| Automake's rebuild rules. Hopefully you won't need to worry about |
| things breaking, when @command{aclocal} disappears, because everything |
| will have been taken care of. If otherwise you used to call |
| @command{aclocal} directly yourself or from some script, you will |
| quickly notice the change. |
| |
| Many packages come with a script called @file{bootstrap.sh} or |
| @file{autogen.sh}, that will just call @command{aclocal}, |
| @command{libtoolize}, @command{gettextize} or @command{autopoint}, |
| @command{autoconf}, @command{autoheader}, and @command{automake} in |
| the right order. Actually this is precisely what @command{autoreconf} |
| can do for you. If your package has such a @file{bootstrap.sh} or |
| @file{autogen.sh} script, consider using @command{autoreconf}. That |
| should simplify its logic a lot (less things to maintain, yum!), it's |
| even likely you will not need the script anymore, and more to the point |
| you will not call @command{aclocal} directly anymore. |
| |
| For the time being, third-party packages should continue to install |
| public macros into @file{/usr/share/aclocal/}. If @command{aclocal} |
| is replaced by another tool it might make sense to rename the |
| directory, but supporting @file{/usr/share/aclocal/} for backward |
| compatibility should be really easy provided all macros are properly |
| written (@pxref{Extending aclocal}). |
| |
| |
| |
| @node Macros |
| @section Autoconf macros supplied with Automake |
| |
| Automake ships with several Autoconf macros that you can use from your |
| @file{configure.ac}. When you use one of them it will be included by |
| @command{aclocal} in @file{aclocal.m4}. |
| |
| @menu |
| * Public Macros:: Macros that you can use. |
| * Private Macros:: Macros that you should not use. |
| @end menu |
| |
| @c consider generating the following subsections automatically from m4 files. |
| |
| @node Public Macros |
| @subsection Public Macros |
| |
| @table @code |
| |
| @item AM_INIT_AUTOMAKE([OPTIONS]) |
| @acindex AM_INIT_AUTOMAKE |
| Runs many macros required for proper operation of the generated Makefiles. |
| |
| @vindex AUTOMAKE_OPTIONS |
| @code{AM_INIT_AUTOMAKE} is called with a single argument: a space-separated |
| list of Automake options that should be applied to every @file{Makefile.am} |
| in the tree. The effect is as if each option were listed in |
| @code{AUTOMAKE_OPTIONS} (@pxref{Options}). |
| |
| @c FIXME: Remove this "modernization advice" in Automake 1.14 (and adjust |
| @c FIXME: the error message in m4/init.m4:AM_INIT_AUTOMAKE accordingly). |
| |
| @acindex AC_INIT |
| This macro could once (before Automake 1.13) also be called in the |
| @emph{now obsolete and completely unsupported} form |
| @code{AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])}. In this form, |
| there were two required arguments: the package and the version number. |
| |
| @anchor{Modernize AM_INIT_AUTOMAKE invocation} |
| If your @file{configure.ac} has: |
| |
| @example |
| AC_INIT([src/foo.c]) |
| AM_INIT_AUTOMAKE([mumble], [1.5]) |
| @end example |
| |
| @noindent |
| you must modernize it as follows in order to make it work with Automake |
| 1.13 or later: |
| |
| @example |
| AC_INIT([mumble], [1.5]) |
| AC_CONFIG_SRCDIR([src/foo.c]) |
| AM_INIT_AUTOMAKE |
| @end example |
| |
| Note that if you're upgrading your @file{configure.ac} from an earlier |
| version of Automake, it is not always correct to simply move the |
| package and version arguments from @code{AM_INIT_AUTOMAKE} directly to |
| @code{AC_INIT}, as in the example above. The first argument to |
| @code{AC_INIT} should be the name of your package (e.g., @samp{GNU |
| Automake}), not the tarball name (e.g., @samp{automake}) that you used |
| to pass to @code{AM_INIT_AUTOMAKE}. Autoconf tries to derive a |
| tarball name from the package name, which should work for most but not |
| all package names. (If it doesn't work for yours, you can use the |
| four-argument form of @code{AC_INIT} to provide the tarball name |
| explicitly). |
| |
| @cindex @code{PACKAGE}, prevent definition |
| @cindex @code{VERSION}, prevent definition |
| @opindex no-define |
| By default this macro @code{AC_DEFINE}'s @code{PACKAGE} and |
| @code{VERSION}. This can be avoided by passing the @option{no-define} |
| option: |
| @example |
| AM_INIT_AUTOMAKE([gnits 1.11.6 no-define parallel-tests]) |
| @end example |
| |
| @item AM_PATH_LISPDIR |
| @acindex AM_PATH_LISPDIR |
| @vindex EMACS |
| @vindex lispdir |
| Searches for the program @command{emacs}, and, if found, sets the |
| output variable @code{lispdir} to the full path to Emacs' site-lisp |
| directory. |
| |
| Note that this test assumes the @command{emacs} found to be a version |
| that supports Emacs Lisp (such as GNU Emacs or XEmacs). Other |
| emacsen can cause this test to hang (some, like old versions of |
| MicroEmacs, start up in interactive mode, requiring @kbd{C-x C-c} to |
| exit, which is hardly obvious for a non-emacs user). In most cases, |
| however, you should be able to use @kbd{C-c} to kill the test. In |
| order to avoid problems, you can set @env{EMACS} to ``no'' in the |
| environment, or use the @option{--with-lispdir} option to |
| @command{configure} to explicitly set the correct path (if you're sure |
| you have an @command{emacs} that supports Emacs Lisp). |
| |
| @item AM_PROG_AR(@ovar{act-if-fail}) |
| @acindex AM_PROG_AR |
| @vindex AR |
| You must use this macro when you use the archiver in your project, if |
| you want support for unusual archivers such as Microsoft @command{lib}. |
| The content of the optional argument is executed if the archiver |
| interface is not recognized; the default action is to abort configure |
| with an error message. |
| |
| @item AM_PROG_AS |
| @acindex AM_PROG_AS |
| @vindex CCAS |
| @vindex CCASFLAGS |
| Use this macro when you have assembly code in your project. This will |
| choose the assembler for you (by default the C compiler) and set |
| @code{CCAS}, and will also set @code{CCASFLAGS} if required. |
| |
| @item AM_PROG_CC_C_O |
| @acindex AM_PROG_CC_C_O |
| @acindex AC_PROG_CC_C_O |
| This is like @code{AC_PROG_CC_C_O}, but it generates its results in |
| the manner required by Automake. You must use this instead of |
| @code{AC_PROG_CC_C_O} when you need this functionality, that is, when |
| using per-target flags or subdir objects with C sources. |
| |
| @item AM_PROG_LEX |
| @acindex AM_PROG_LEX |
| @acindex AC_PROG_LEX |
| @cindex HP-UX 10, @command{lex} problems |
| @cindex @command{lex} problems with HP-UX 10 |
| Like @code{AC_PROG_LEX} (@pxref{Particular Programs, , Particular |
| Program Checks, autoconf, The Autoconf Manual}), but uses the |
| @command{missing} script on systems that do not have @command{lex}. |
| HP-UX 10 is one such system. |
| |
| @item AM_PROG_GCJ |
| @acindex AM_PROG_GCJ |
| @vindex GCJ |
| @vindex GCJFLAGS |
| This macro finds the @command{gcj} program or causes an error. It sets |
| @code{GCJ} and @code{GCJFLAGS}. @command{gcj} is the Java front-end to the |
| GNU Compiler Collection. |
| |
| @item AM_PROG_UPC([@var{compiler-search-list}]) |
| @acindex AM_PROG_UPC |
| @vindex UPC |
| Find a compiler for Unified Parallel C and define the @code{UPC} |
| variable. The default @var{compiler-search-list} is @samp{upcc upc}. |
| This macro will abort @command{configure} if no Unified Parallel C |
| compiler is found. |
| |
| @item AM_MISSING_PROG(@var{name}, @var{program}) |
| @acindex AM_MISSING_PROG |
| @vindex MISSING |
| Find a maintainer tool @var{program} and define the @var{name} |
| environment variable with its location. If @var{program} is not |
| detected, then @var{name} will instead invoke the @command{missing} |
| script, in order to give useful advice to the user about the missing |
| maintainer tool. @xref{maintainer tools}, for more information on |
| when the @command{missing} script is appropriate. |
| |
| @item AM_SILENT_RULES |
| @acindex AM_SILENT_RULES |
| Control the machinery for less verbose build output |
| (@pxref{Automake Silent Rules}). |
| |
| @item AM_WITH_DMALLOC |
| @acindex AM_WITH_DMALLOC |
| @cindex @command{dmalloc}, support for |
| @vindex WITH_DMALLOC |
| @opindex --with-dmalloc |
| Add support for the @uref{http://dmalloc.com/, Dmalloc package}. If |
| the user runs @command{configure} with @option{--with-dmalloc}, then |
| define @code{WITH_DMALLOC} and add @option{-ldmalloc} to @code{LIBS}. |
| |
| @end table |
| |
| |
| @node Private Macros |
| @subsection Private Macros |
| |
| The following macros are private macros you should not call directly. |
| They are called by the other public macros when appropriate. Do not |
| rely on them, as they might be changed in a future version. Consider |
| them as implementation details; or better, do not consider them at all: |
| skip this section! |
| |
| @ftable @code |
| @item _AM_DEPENDENCIES |
| @itemx AM_SET_DEPDIR |
| @itemx AM_DEP_TRACK |
| These macros are used to implement Automake's automatic dependency |
| tracking scheme. They are called automatically by Automake when |
| required, and there should be no need to invoke them manually. |
| |
| @item AM_PROG_INSTALL_STRIP |
| This is used to find a version of @code{install} that can be used to |
| strip a program at installation time. This macro is automatically |
| included when required. |
| |
| @item AM_SANITY_CHECK |
| This checks to make sure that a file created in the build directory is |
| newer than a file in the source directory. This can fail on systems |
| where the clock is set incorrectly. This macro is automatically run |
| from @code{AM_INIT_AUTOMAKE}. |
| |
| @end ftable |
| |
| |
| @node Directories |
| @chapter Directories |
| |
| For simple projects that distribute all files in the same directory |
| it is enough to have a single @file{Makefile.am} that builds |
| everything in place. |
| |
| In larger projects, it is common to organize files in different |
| directories, in a tree. For example, there could be a directory |
| for the program's source, one for the testsuite, and one for the |
| documentation; or, for very large projects, there could be one |
| directory per program, per library or per module. |
| |
| The traditional approach is to build these subdirectories recursively, |
| employing @emph{make recursion}: each directory contains its |
| own @file{Makefile}, and when @command{make} is run from the top-level |
| directory, it enters each subdirectory in turn, and invokes there a |
| new @command{make} instance to build the directory's contents. |
| |
| Because this approach is very widespread, Automake offers built-in |
| support for it. However, it is worth nothing that the use of make |
| recursion has its own serious issues and drawbacks, and that it's |
| well possible to have packages with a multi directory layout that |
| make little or no use of such recursion (examples of such packages |
| are GNU Bison and GNU Automake itself); see also the @ref{Alternative} |
| section below. |
| |
| @menu |
| * Subdirectories:: Building subdirectories recursively |
| * Conditional Subdirectories:: Conditionally not building directories |
| * Alternative:: Subdirectories without recursion |
| * Subpackages:: Nesting packages |
| @end menu |
| |
| @node Subdirectories |
| @section Recursing subdirectories |
| |
| @cindex @code{SUBDIRS}, explained |
| |
| In packages using make recursion, the top level @file{Makefile.am} must |
| tell Automake which subdirectories are to be built. This is done via |
| the @code{SUBDIRS} variable. |
| @vindex SUBDIRS |
| |
| The @code{SUBDIRS} variable holds a list of subdirectories in which |
| building of various sorts can occur. The rules for many targets |
| (e.g., @code{all}) in the generated @file{Makefile} will run commands |
| both locally and in all specified subdirectories. Note that the |
| directories listed in @code{SUBDIRS} are not required to contain |
| @file{Makefile.am}s; only @file{Makefile}s (after configuration). |
| This allows inclusion of libraries from packages that do not use |
| Automake (such as @code{gettext}; see also @ref{Third-Party |
| Makefiles}). |
| |
| In packages that use subdirectories, the top-level @file{Makefile.am} is |
| often very short. For instance, here is the @file{Makefile.am} from the |
| GNU Hello distribution: |
| |
| @example |
| EXTRA_DIST = BUGS ChangeLog.O README-alpha |
| SUBDIRS = doc intl po src tests |
| @end example |
| |
| When Automake invokes @command{make} in a subdirectory, it uses the value |
| of the @code{MAKE} variable. |
| @vindex MAKE |
| |
| The directories mentioned in @code{SUBDIRS} are usually direct |
| children of the current directory, each subdirectory containing its |
| own @file{Makefile.am} with a @code{SUBDIRS} pointing to deeper |
| subdirectories. Automake can be used to construct packages of |
| arbitrary depth this way. |
| |
| By default, Automake generates @file{Makefiles} that work depth-first |
| in postfix order: the subdirectories are built before the current |
| directory. However, it is possible to change this ordering. You can |
| do this by putting @samp{.} into @code{SUBDIRS}. For instance, |
| putting @samp{.} first will cause a prefix ordering of |
| directories. |
| |
| Using |
| |
| @example |
| SUBDIRS = lib src . test |
| @end example |
| |
| @noindent |
| will cause @file{lib/} to be built before @file{src/}, then the |
| current directory will be built, finally the @file{test/} directory |
| will be built. It is customary to arrange test directories to be |
| built after everything else since they are meant to test what has |
| been constructed. |
| |
| In addition to the built-in recursive targets defined by Automake |
| (@code{all}, @code{check}, etc.), the developer can also define his |
| own recursive targets. That is done by passing the names of such |
| targets as arguments to the m4 macro @code{AM_EXTRA_RECURSIVE_TARGETS} |
| in @file{configure.ac}. Automake generates rules to handle the |
| recursion for such targets; and the developer can define real actions |
| for them by defining corresponding @code{-local} targets. |
| |
| @example |
| % @kbd{cat configure.ac} |
| AC_INIT([pkg-name], [1.0] |
| AM_INIT_AUTOMAKE |
| AM_EXTRA_RECURSIVE_TARGETS([foo]) |
| AC_CONFIG_FILES([Makefile sub/Makefile sub/src/Makefile]) |
| AC_OUTPUT |
| % @kbd{cat Makefile.am} |
| SUBDIRS = sub |
| foo-local: |
| @@echo This will be run by "make foo". |
| % @kbd{cat sub/Makefile.am} |
| SUBDIRS = src |
| % @kbd{cat sub/src/Makefile.am} |
| foo-local: |
| @@echo This too will be run by a "make foo" issued either in |
| @@echo the 'sub/src/' directory, the 'sub/' directory, or the |
| @@echo top-level directory. |
| @end example |
| |
| @node Conditional Subdirectories |
| @section Conditional Subdirectories |
| @cindex Subdirectories, building conditionally |
| @cindex Conditional subdirectories |
| @cindex @code{SUBDIRS}, conditional |
| @cindex Conditional @code{SUBDIRS} |
| |
| It is possible to define the @code{SUBDIRS} variable conditionally if, |
| like in the case of GNU Inetutils, you want to only build a subset of |
| the entire package. |
| |
| To illustrate how this works, let's assume we have two directories |
| @file{src/} and @file{opt/}. @file{src/} should always be built, but we |
| want to decide in @command{configure} whether @file{opt/} will be built |
| or not. (For this example we will assume that @file{opt/} should be |
| built when the variable @samp{$want_opt} was set to @samp{yes}.) |
| |
| Running @command{make} should thus recurse into @file{src/} always, and |
| then maybe in @file{opt/}. |
| |
| However @samp{make dist} should always recurse into both @file{src/} |
| and @file{opt/}. Because @file{opt/} should be distributed even if it |
| is not needed in the current configuration. This means |
| @file{opt/Makefile} should be created @emph{unconditionally}. |
| |
| There are two ways to setup a project like this. You can use Automake |
| conditionals (@pxref{Conditionals}) or use Autoconf @code{AC_SUBST} |
| variables (@pxref{Setting Output Variables, , Setting Output |
| Variables, autoconf, The Autoconf Manual}). Using Automake |
| conditionals is the preferred solution. Before we illustrate these |
| two possibilities, let's introduce @code{DIST_SUBDIRS}. |
| |
| @menu |
| * SUBDIRS vs DIST_SUBDIRS:: Two sets of directories |
| * Subdirectories with AM_CONDITIONAL:: Specifying conditional subdirectories |
| * Subdirectories with AC_SUBST:: Another way for conditional recursion |
| * Unconfigured Subdirectories:: Not even creating a @samp{Makefile} |
| @end menu |
| |
| @node SUBDIRS vs DIST_SUBDIRS |
| @subsection @code{SUBDIRS} vs.@: @code{DIST_SUBDIRS} |
| @cindex @code{DIST_SUBDIRS}, explained |
| |
| Automake considers two sets of directories, defined by the variables |
| @code{SUBDIRS} and @code{DIST_SUBDIRS}. |
| |
| @code{SUBDIRS} contains the subdirectories of the current directory |
| that must be built (@pxref{Subdirectories}). It must be defined |
| manually; Automake will never guess a directory is to be built. As we |
| will see in the next two sections, it is possible to define it |
| conditionally so that some directory will be omitted from the build. |
| |
| @code{DIST_SUBDIRS} is used in rules that need to recurse in all |
| directories, even those that have been conditionally left out of the |
| build. Recall our example where we may not want to build subdirectory |
| @file{opt/}, but yet we want to distribute it? This is where |
| @code{DIST_SUBDIRS} comes into play: @samp{opt} may not appear in |
|