1 \input texinfo @c -*-texinfo-*-
3 @setfilename automake.info
10 @c @ovar(ARG, DEFAULT)
11 @c -------------------
12 @c The ARG is an optional argument. To be used for macro arguments in
13 @c their documentation (@defmac).
15 @r{[}@var{\varname\}@r{]}
18 @set PACKAGE_BUGREPORT bug-automake@@gnu.org
22 This manual is for GNU Automake (version @value{VERSION},
23 @value{UPDATED}), a program that creates GNU standards-compliant
24 Makefiles from template files.
26 Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
27 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012 Free Software
31 Permission is granted to copy, distribute and/or modify this document
32 under the terms of the GNU Free Documentation License,
33 Version 1.3 or any later version published by the Free Software
34 Foundation; with no Invariant Sections, with no Front-Cover texts,
35 and with no Back-Cover Texts. A copy of the license is included in the
36 section entitled ``GNU Free Documentation License.''
41 @dircategory Software development
43 * Automake: (automake). Making GNU standards-compliant Makefiles.
46 @dircategory Individual utilities
48 * aclocal-invocation: (automake)aclocal Invocation. Generating aclocal.m4.
49 * automake-invocation: (automake)automake Invocation. Generating Makefile.in.
54 @subtitle For version @value{VERSION}, @value{UPDATED}
55 @author David MacKenzie
57 @author Alexandre Duret-Lutz
59 @vskip 0pt plus 1filll
65 @c We use the following macros to define indices:
66 @c @cindex concepts, and anything that does not fit elsewhere
67 @c @vindex Makefile variables
69 @c @acindex Autoconf/Automake/Libtool/M4/... macros
70 @c @opindex tool options
72 @c Define an index of configure macros.
74 @c Define an index of options.
76 @c Define an index of targets.
78 @c Define an index of commands.
81 @c Put the macros in the function index.
84 @c Put everything else into one index (arbitrarily chosen to be the
92 @comment node-name, next, previous, up
98 * Introduction:: Automake's purpose
99 * Autotools Introduction:: An Introduction to the Autotools
100 * Generalities:: General ideas
101 * Examples:: Some example packages
102 * automake Invocation:: Creating a Makefile.in
103 * configure:: Scanning configure.ac, using aclocal
104 * Directories:: Declaring subdirectories
105 * Programs:: Building programs and libraries
106 * Other Objects:: Other derived objects
107 * Other GNU Tools:: Other GNU Tools
108 * Documentation:: Building documentation
109 * Install:: What gets installed
110 * Clean:: What gets cleaned
111 * Dist:: What goes in a distribution
112 * Tests:: Support for test suites
113 * Rebuilding:: Automatic rebuilding of Makefile
114 * Options:: Changing Automake's behavior
115 * Miscellaneous:: Miscellaneous rules
116 * Include:: Including extra files in an Automake template
117 * Conditionals:: Conditionals
118 * Silencing Make:: Obtain less verbose output from @command{make}
119 * Gnits:: The effect of @option{--gnu} and @option{--gnits}
120 * Cygnus:: The effect of @option{--cygnus}
121 * Not Enough:: When Automake is not Enough
122 * Distributing:: Distributing the Makefile.in
123 * API Versioning:: About compatibility between Automake versions
124 * Upgrading:: Upgrading to a Newer Automake Version
125 * FAQ:: Frequently Asked Questions
126 * Copying This Manual:: How to make copies of this manual
127 * Indices:: Indices of variables, macros, and concepts
130 --- The Detailed Node Listing ---
132 An Introduction to the Autotools
134 * GNU Build System:: Introducing the GNU Build System
135 * Use Cases:: Use Cases for the GNU Build System
136 * Why Autotools:: How Autotools Help
137 * Hello World:: A Small Hello World Package
139 Use Cases for the GNU Build System
141 * Basic Installation:: Common installation procedure
142 * Standard Targets:: A list of standard Makefile targets
143 * Standard Directory Variables:: A list of standard directory variables
144 * Standard Configuration Variables:: Using configuration variables
145 * config.site:: Using a config.site file
146 * VPATH Builds:: Parallel build trees
147 * Two-Part Install:: Installing data and programs separately
148 * Cross-Compilation:: Building for other architectures
149 * Renaming:: Renaming programs at install time
150 * DESTDIR:: Building binary packages with DESTDIR
151 * Preparing Distributions:: Rolling out tarballs
152 * Dependency Tracking:: Automatic dependency tracking
153 * Nested Packages:: The GNU Build Systems can be nested
157 * Creating amhello:: Create @file{amhello-1.0.tar.gz} from scratch
158 * amhello's configure.ac Setup Explained::
159 * amhello's Makefile.am Setup Explained::
163 * General Operation:: General operation of Automake
164 * Strictness:: Standards conformance checking
165 * Uniform:: The Uniform Naming Scheme
166 * Length Limitations:: Staying below the command line length limit
167 * Canonicalization:: How derived variables are named
168 * User Variables:: Variables reserved for the user
169 * Auxiliary Programs:: Programs automake might require
171 Some example packages
173 * Complete:: A simple example, start to finish
174 * true:: Building true and false
176 Scanning @file{configure.ac}, using @command{aclocal}
178 * Requirements:: Configuration requirements
179 * Optional:: Other things Automake recognizes
180 * aclocal Invocation:: Auto-generating aclocal.m4
181 * Macros:: Autoconf macros supplied with Automake
183 Auto-generating aclocal.m4
185 * aclocal Options:: Options supported by aclocal
186 * Macro Search Path:: How aclocal finds .m4 files
187 * Extending aclocal:: Writing your own aclocal macros
188 * Local Macros:: Organizing local macros
189 * Serials:: Serial lines in Autoconf macros
190 * Future of aclocal:: aclocal's scheduled death
192 Autoconf macros supplied with Automake
194 * Public Macros:: Macros that you can use.
195 * Obsolete Macros:: Macros that you should stop using.
196 * Private Macros:: Macros that you should not use.
200 * Subdirectories:: Building subdirectories recursively
201 * Conditional Subdirectories:: Conditionally not building directories
202 * Alternative:: Subdirectories without recursion
203 * Subpackages:: Nesting packages
205 Conditional Subdirectories
207 * SUBDIRS vs DIST_SUBDIRS:: Two sets of directories
208 * Subdirectories with AM_CONDITIONAL:: Specifying conditional subdirectories
209 * Subdirectories with AC_SUBST:: Another way for conditional recursion
210 * Unconfigured Subdirectories:: Not even creating a @samp{Makefile}
212 Building Programs and Libraries
214 * A Program:: Building a program
215 * A Library:: Building a library
216 * A Shared Library:: Building a Libtool library
217 * Program and Library Variables:: Variables controlling program and
219 * Default _SOURCES:: Default source files
220 * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
221 * Program Variables:: Variables used when building a program
222 * Yacc and Lex:: Yacc and Lex support
223 * C++ Support:: Compiling C++ sources
224 * Objective C Support:: Compiling Objective C sources
225 * Unified Parallel C Support:: Compiling Unified Parallel C sources
226 * Assembly Support:: Compiling assembly sources
227 * Fortran 77 Support:: Compiling Fortran 77 sources
228 * Fortran 9x Support:: Compiling Fortran 9x sources
229 * Java Support with gcj:: Compiling Java sources using gcj
230 * Vala Support:: Compiling Vala sources
231 * Support for Other Languages:: Compiling other languages
232 * Dependencies:: Automatic dependency tracking
233 * EXEEXT:: Support for executable extensions
237 * Program Sources:: Defining program sources
238 * Linking:: Linking with libraries or extra objects
239 * Conditional Sources:: Handling conditional sources
240 * Conditional Programs:: Building a program conditionally
242 Building a Shared Library
244 * Libtool Concept:: Introducing Libtool
245 * Libtool Libraries:: Declaring Libtool Libraries
246 * Conditional Libtool Libraries:: Building Libtool Libraries Conditionally
247 * Conditional Libtool Sources:: Choosing Library Sources Conditionally
248 * Libtool Convenience Libraries:: Building Convenience Libtool Libraries
249 * Libtool Modules:: Building Libtool Modules
250 * Libtool Flags:: Using _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS
251 * LTLIBOBJS:: Using $(LTLIBOBJS) and $(LTALLOCA)
252 * Libtool Issues:: Common Issues Related to Libtool's Use
254 Common Issues Related to Libtool's Use
256 * Error required file ltmain.sh not found:: The need to run libtoolize
257 * Objects created both with libtool and without:: Avoid a specific build race
261 * Preprocessing Fortran 77:: Preprocessing Fortran 77 sources
262 * Compiling Fortran 77 Files:: Compiling Fortran 77 sources
263 * Mixing Fortran 77 With C and C++:: Mixing Fortran 77 With C and C++
265 Mixing Fortran 77 With C and C++
267 * How the Linker is Chosen:: Automatic linker selection
271 * Compiling Fortran 9x Files:: Compiling Fortran 9x sources
273 Other Derived Objects
275 * Scripts:: Executable scripts
276 * Headers:: Header files
277 * Data:: Architecture-independent data files
278 * Sources:: Derived sources
282 * Built Sources Example:: Several ways to handle built sources.
286 * Emacs Lisp:: Emacs Lisp
289 * Java:: Java bytecode compilation (deprecated)
292 Building documentation
295 * Man Pages:: Man pages
299 * Basics of Installation:: What gets installed where
300 * The Two Parts of Install:: Installing data and programs separately
301 * Extending Installation:: Adding your own rules for installation
302 * Staged Installs:: Installation in a temporary location
303 * Install Rules for the User:: Useful additional rules
305 What Goes in a Distribution
307 * Basics of Distribution:: Files distributed by default
308 * Fine-grained Distribution Control:: @code{dist_} and @code{nodist_} prefixes
309 * The dist Hook:: A target for last-minute distribution changes
310 * Checking the Distribution:: @samp{make distcheck} explained
311 * The Types of Distributions:: A variety of formats and compression methods
313 Support for test suites
315 * Generalities about Testing:: Generic concepts and terminology about testing
316 * Simple Tests:: Listing test scripts in @code{TESTS}
317 * Custom Test Drivers:: Writing and using custom test drivers
318 * Using the TAP test protocol:: Integrating test scripts that use the TAP protocol
319 * DejaGnu Tests:: Interfacing with the @command{dejagnu} testing framework
320 * Install Tests:: Running tests on installed packages
324 * Scripts-based Testsuites:: Automake-specific concepts and terminology
325 * Serial Test Harness:: Older (and obsolescent) serial test harness
326 * Parallel Test Harness:: Generic concurrent test harness
328 Using the TAP test protocol
330 * Introduction to TAP::
331 * Use TAP with the Automake test harness::
332 * Incompatibilities with other TAP parsers and drivers::
333 * Links and external resources on TAP::
337 * Overview of Custom Test Drivers Support::
338 * Declaring Custom Test Drivers::
339 * API for Custom Test Drivers::
341 API for Custom Test Drivers
343 * Command-line arguments for test drivers::
344 * Log files generation and test results recording::
345 * Testsuite progress output::
347 Changing Automake's Behavior
349 * Options generalities:: Semantics of Automake option
350 * List of Automake options:: A comprehensive list of Automake options
354 * Tags:: Interfacing to cscope, etags and mkid
355 * Suffixes:: Handling new file extensions
359 * Usage of Conditionals:: Declaring conditional content
360 * Limits of Conditionals:: Enclosing complete statements
364 * Make verbosity:: Make is verbose by default
365 * Tricks For Silencing Make:: Standard and generic ways to silence make
366 * Automake silent-rules Option:: How Automake can help in silencing make
368 When Automake Isn't Enough
370 * Extending:: Adding new rules or overriding existing ones.
371 * Third-Party Makefiles:: Integrating Non-Automake @file{Makefile}s.
373 Frequently Asked Questions about Automake
375 * CVS:: CVS and generated files
376 * maintainer-mode:: missing and AM_MAINTAINER_MODE
377 * Wildcards:: Why doesn't Automake support wildcards?
378 * Limitations on File Names:: Limitations on source and installed file names
379 * distcleancheck:: Files left in build directory after distclean
380 * Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS
381 * Renamed Objects:: Why are object files sometimes renamed?
382 * Per-Object Flags:: How to simulate per-object flags?
383 * Multiple Outputs:: Writing rules for tools with many output files
384 * Hard-Coded Install Paths:: Installing to hard-coded locations
385 * Debugging Make Rules:: Strategies when things don't work as expected
386 * Reporting Bugs:: Feedback on bugs and feature requests
390 * GNU Free Documentation License:: License for copying this manual
394 * Macro Index:: Index of Autoconf macros
395 * Variable Index:: Index of Makefile variables
396 * General Index:: General index
405 @chapter Introduction
407 Automake is a tool for automatically generating @file{Makefile.in}s
408 from files called @file{Makefile.am}. Each @file{Makefile.am} is
409 basically a series of @command{make} variable
410 definitions@footnote{These variables are also called @dfn{make macros}
411 in Make terminology, however in this manual we reserve the term
412 @dfn{macro} for Autoconf's macros.}, with rules being thrown in
413 occasionally. The generated @file{Makefile.in}s are compliant with
414 the GNU Makefile standards.
416 @cindex GNU Makefile standards
418 The GNU Makefile Standards Document
419 (@pxref{Makefile Conventions, , , standards, The GNU Coding Standards})
420 is long, complicated, and subject to change. The goal of Automake is to
421 remove the burden of Makefile maintenance from the back of the
422 individual GNU maintainer (and put it on the back of the Automake
425 The typical Automake input file is simply a series of variable definitions.
426 Each such file is processed to create a @file{Makefile.in}. There
427 should generally be one @file{Makefile.am} per directory of a project.
429 @cindex Constraints of Automake
430 @cindex Automake constraints
432 Automake does constrain a project in certain ways; for instance, it
433 assumes that the project uses Autoconf (@pxref{Top, , Introduction,
434 autoconf, The Autoconf Manual}), and enforces certain restrictions on
435 the @file{configure.ac} contents@footnote{Older Autoconf versions used
436 @file{configure.in}. Autoconf 2.50 and greater promotes
437 @file{configure.ac} over @file{configure.in}. The rest of this
438 documentation will refer to @file{configure.ac}, but Automake also
439 supports @file{configure.in} for backward compatibility.}.
441 @cindex Automake requirements
442 @cindex Requirements, Automake
444 Automake requires @command{perl} in order to generate the
445 @file{Makefile.in}s. However, the distributions created by Automake are
446 fully GNU standards-compliant, and do not require @command{perl} in order
449 @cindex Bugs, reporting
450 @cindex Reporting bugs
451 @cindex E-mail, bug reports
453 For more information on bug reports, @xref{Reporting Bugs}.
455 @node Autotools Introduction
456 @chapter An Introduction to the Autotools
458 If you are new to Automake, maybe you know that it is part of a set of
459 tools called @emph{The Autotools}. Maybe you've already delved into a
460 package full of files named @file{configure}, @file{configure.ac},
461 @file{Makefile.in}, @file{Makefile.am}, @file{aclocal.m4}, @dots{},
462 some of them claiming to be @emph{generated by} Autoconf or Automake.
463 But the exact purpose of these files and their relations is probably
464 fuzzy. The goal of this chapter is to introduce you to this machinery,
465 to show you how it works and how powerful it is. If you've never
466 installed or seen such a package, do not worry: this chapter will walk
469 If you need some teaching material, more illustrations, or a less
470 @command{automake}-centered continuation, some slides for this
471 introduction are available in Alexandre Duret-Lutz's
472 @uref{http://www.lrde.epita.fr/@/~adl/@/autotools.html,
474 This chapter is the written version of the first part of his tutorial.
477 * GNU Build System:: Introducing the GNU Build System
478 * Use Cases:: Use Cases for the GNU Build System
479 * Why Autotools:: How Autotools Help
480 * Hello World:: A Small Hello World Package
483 @node GNU Build System
484 @section Introducing the GNU Build System
485 @cindex GNU Build System, introduction
487 It is a truth universally acknowledged, that as a developer in
488 possession of a new package, you must be in want of a build system.
490 In the Unix world, such a build system is traditionally achieved using
491 the command @command{make} (@pxref{Top, , Overview, make, The GNU Make
492 Manual}). You express the recipe to build your package in a
493 @file{Makefile}. This file is a set of rules to build the files in
494 the package. For instance the program @file{prog} may be built by
495 running the linker on the files @file{main.o}, @file{foo.o}, and
496 @file{bar.o}; the file @file{main.o} may be built by running the
497 compiler on @file{main.c}; etc. Each time @command{make} is run, it
498 reads @file{Makefile}, checks the existence and modification time of
499 the files mentioned, decides what files need to be built (or rebuilt),
500 and runs the associated commands.
502 When a package needs to be built on a different platform than the one
503 it was developed on, its @file{Makefile} usually needs to be adjusted.
504 For instance the compiler may have another name or require more
505 options. In 1991, David J. MacKenzie got tired of customizing
506 @file{Makefile} for the 20 platforms he had to deal with. Instead, he
507 handcrafted a little shell script called @file{configure} to
508 automatically adjust the @file{Makefile} (@pxref{Genesis, , Genesis,
509 autoconf, The Autoconf Manual}). Compiling his package was now
510 as simple as running @code{./configure && make}.
512 @cindex GNU Coding Standards
514 Today this process has been standardized in the GNU project. The GNU
515 Coding Standards (@pxref{Managing Releases, The Release Process, ,
516 standards, The GNU Coding Standards}) explains how each package of the
517 GNU project should have a @file{configure} script, and the minimal
518 interface it should have. The @file{Makefile} too should follow some
519 established conventions. The result? A unified build system that
520 makes all packages almost indistinguishable by the installer. In its
521 simplest scenario, all the installer has to do is to unpack the
522 package, run @code{./configure && make && make install}, and repeat
523 with the next package to install.
525 We call this build system the @dfn{GNU Build System}, since it was
526 grown out of the GNU project. However it is used by a vast number of
527 other packages: following any existing convention has its advantages.
529 @cindex Autotools, introduction
531 The Autotools are tools that will create a GNU Build System for your
532 package. Autoconf mostly focuses on @file{configure} and Automake on
533 @file{Makefile}s. It is entirely possible to create a GNU Build
534 System without the help of these tools. However it is rather
535 burdensome and error-prone. We will discuss this again after some
536 illustration of the GNU Build System in action.
539 @section Use Cases for the GNU Build System
540 @cindex GNU Build System, use cases
541 @cindex GNU Build System, features
542 @cindex Features of the GNU Build System
543 @cindex Use Cases for the GNU Build System
544 @cindex @file{amhello-1.0.tar.gz}, location
545 @cindex @file{amhello-1.0.tar.gz}, use cases
547 In this section we explore several use cases for the GNU Build System.
548 You can replay all these examples on the @file{amhello-1.0.tar.gz}
549 package distributed with Automake. If Automake is installed on your
550 system, you should find a copy of this file in
551 @file{@var{prefix}/share/doc/automake/amhello-1.0.tar.gz}, where
552 @var{prefix} is the installation prefix specified during configuration
553 (@var{prefix} defaults to @file{/usr/local}, however if Automake was
554 installed by some GNU/Linux distribution it most likely has been set
555 to @file{/usr}). If you do not have a copy of Automake installed,
556 you can find a copy of this file inside the @file{doc/} directory of
557 the Automake package.
559 Some of the following use cases present features that are in fact
560 extensions to the GNU Build System. Read: they are not specified by
561 the GNU Coding Standards, but they are nonetheless part of the build
562 system created by the Autotools. To keep things simple, we do not
563 point out the difference. Our objective is to show you many of the
564 features that the build system created by the Autotools will offer to
568 * Basic Installation:: Common installation procedure
569 * Standard Targets:: A list of standard Makefile targets
570 * Standard Directory Variables:: A list of standard directory variables
571 * Standard Configuration Variables:: Using configuration variables
572 * config.site:: Using a config.site file
573 * VPATH Builds:: Parallel build trees
574 * Two-Part Install:: Installing data and programs separately
575 * Cross-Compilation:: Building for other architectures
576 * Renaming:: Renaming programs at install time
577 * DESTDIR:: Building binary packages with DESTDIR
578 * Preparing Distributions:: Rolling out tarballs
579 * Dependency Tracking:: Automatic dependency tracking
580 * Nested Packages:: The GNU Build Systems can be nested
583 @node Basic Installation
584 @subsection Basic Installation
585 @cindex Configuration, basics
586 @cindex Installation, basics
587 @cindex GNU Build System, basics
589 The most common installation procedure looks as follows.
592 ~ % @kbd{tar zxf amhello-1.0.tar.gz}
593 ~ % @kbd{cd amhello-1.0}
594 ~/amhello-1.0 % @kbd{./configure}
596 config.status: creating Makefile
597 config.status: creating src/Makefile
599 ~/amhello-1.0 % @kbd{make}
601 ~/amhello-1.0 % @kbd{make check}
603 ~/amhello-1.0 % @kbd{su}
605 /home/adl/amhello-1.0 # @kbd{make install}
607 /home/adl/amhello-1.0 # @kbd{exit}
608 ~/amhello-1.0 % @kbd{make installcheck}
614 The user first unpacks the package. Here, and in the following
615 examples, we will use the non-portable @code{tar zxf} command for
616 simplicity. On a system without GNU @command{tar} installed, this
617 command should read @code{gunzip -c amhello-1.0.tar.gz | tar xf -}.
619 The user then enters the newly created directory to run the
620 @file{configure} script. This script probes the system for various
621 features, and finally creates the @file{Makefile}s. In this toy
622 example there are only two @file{Makefile}s, but in real-world projects,
623 there may be many more, usually one @file{Makefile} per directory.
625 It is now possible to run @code{make}. This will construct all the
626 programs, libraries, and scripts that need to be constructed for the
627 package. In our example, this compiles the @file{hello} program.
628 All files are constructed in place, in the source tree; we will see
629 later how this can be changed.
631 @code{make check} causes the package's tests to be run. This step is
632 not mandatory, but it is often good to make sure the programs that
633 have been built behave as they should, before you decide to install
634 them. Our example does not contain any tests, so running @code{make
637 @cindex su, before @code{make install}
638 After everything has been built, and maybe tested, it is time to
639 install it on the system. That means copying the programs,
640 libraries, header files, scripts, and other data files from the
641 source directory to their final destination on the system. The
642 command @code{make install} will do that. However, by default
643 everything will be installed in subdirectories of @file{/usr/local}:
644 binaries will go into @file{/usr/local/bin}, libraries will end up in
645 @file{/usr/local/lib}, etc. This destination is usually not writable
646 by any user, so we assume that we have to become root before we can
647 run @code{make install}. In our example, running @code{make install}
648 will copy the program @file{hello} into @file{/usr/local/bin}
649 and @file{README} into @file{/usr/local/share/doc/amhello}.
651 A last and optional step is to run @code{make installcheck}. This
652 command may run tests on the installed files. @code{make check} tests
653 the files in the source tree, while @code{make installcheck} tests
654 their installed copies. The tests run by the latter can be different
655 from those run by the former. For instance, there are tests that
656 cannot be run in the source tree. Conversely, some packages are set
657 up so that @code{make installcheck} will run the very same tests as
658 @code{make check}, only on different files (non-installed
659 vs.@: installed). It can make a difference, for instance when the
660 source tree's layout is different from that of the installation.
661 Furthermore it may help to diagnose an incomplete installation.
663 Presently most packages do not have any @code{installcheck} tests
664 because the existence of @code{installcheck} is little known, and its
665 usefulness is neglected. Our little toy package is no better: @code{make
666 installcheck} does nothing.
668 @node Standard Targets
669 @subsection Standard @file{Makefile} Targets
671 So far we have come across four ways to run @command{make} in the GNU
672 Build System: @code{make}, @code{make check}, @code{make install}, and
673 @code{make installcheck}. The words @code{check}, @code{install}, and
674 @code{installcheck}, passed as arguments to @command{make}, are called
675 @dfn{targets}. @code{make} is a shorthand for @code{make all},
676 @code{all} being the default target in the GNU Build System.
678 Here is a list of the most useful targets that the GNU Coding Standards
684 Build programs, libraries, documentation, etc.@: (same as @code{make}).
687 Install what needs to be installed, copying the files from the
688 package's tree to system-wide directories.
689 @item make install-strip
690 @trindex install-strip
691 Same as @code{make install}, then strip debugging symbols. Some
692 users like to trade space for useful bug reports@enddots{}
695 The opposite of @code{make install}: erase the installed files.
696 (This needs to be run from the same build tree that was installed.)
699 Erase from the build tree the files built by @code{make all}.
702 Additionally erase anything @code{./configure} created.
705 Run the test suite, if any.
706 @item make installcheck
707 @trindex installcheck
708 Check the installed programs or libraries, if supported.
711 Recreate @file{@var{package}-@var{version}.tar.gz} from all the source
715 @node Standard Directory Variables
716 @subsection Standard Directory Variables
717 @cindex directory variables
719 The GNU Coding Standards also specify a hierarchy of variables to
720 denote installation directories. Some of these are:
722 @multitable {Directory variable} {@code{$@{datarootdir@}/doc/$@{PACKAGE@}}}
723 @headitem Directory variable @tab Default value
724 @item @code{prefix} @tab @code{/usr/local}
725 @item @w{@ @ @code{exec_prefix}} @tab @code{$@{prefix@}}
726 @item @w{@ @ @ @ @code{bindir}} @tab @code{$@{exec_prefix@}/bin}
727 @item @w{@ @ @ @ @code{libdir}} @tab @code{$@{exec_prefix@}/lib}
728 @item @w{@ @ @ @ @dots{}}
729 @item @w{@ @ @code{includedir}} @tab @code{$@{prefix@}/include}
730 @item @w{@ @ @code{datarootdir}} @tab @code{$@{prefix@}/share}
731 @item @w{@ @ @ @ @code{datadir}} @tab @code{$@{datarootdir@}}
732 @item @w{@ @ @ @ @code{mandir}} @tab @code{$@{datarootdir@}/man}
733 @item @w{@ @ @ @ @code{infodir}} @tab @code{$@{datarootdir@}/info}
734 @item @w{@ @ @ @ @code{docdir}} @tab @code{$@{datarootdir@}/doc/$@{PACKAGE@}}
735 @item @w{@ @ @dots{}}
738 @c We should provide a complete table somewhere, but not here. The
739 @c complete list of directory variables it too confusing as-is. It
740 @c requires some explanations that are too complicated for this
741 @c introduction. Besides listing directories like localstatedir
742 @c would make the explanations in ``Two-Part Install'' harder.
744 Each of these directories has a role which is often obvious from its
745 name. In a package, any installable file will be installed in one of
746 these directories. For instance in @code{amhello-1.0}, the program
747 @file{hello} is to be installed in @var{bindir}, the directory for
748 binaries. The default value for this directory is
749 @file{/usr/local/bin}, but the user can supply a different value when
750 calling @command{configure}. Also the file @file{README} will be
751 installed into @var{docdir}, which defaults to
752 @file{/usr/local/share/doc/amhello}.
756 As a user, if you wish to install a package on your own account, you
757 could proceed as follows:
760 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr}
762 ~/amhello-1.0 % @kbd{make}
764 ~/amhello-1.0 % @kbd{make install}
768 This would install @file{~/usr/bin/hello} and
769 @file{~/usr/share/doc/amhello/README}.
771 The list of all such directory options is shown by
772 @code{./configure --help}.
774 @node Standard Configuration Variables
775 @subsection Standard Configuration Variables
776 @cindex configuration variables, overriding
778 The GNU Coding Standards also define a set of standard configuration
779 variables used during the build. Here are some:
788 @item @code{CXXFLAGS}
792 @item @code{CPPFLAGS}
793 C/C++ preprocessor flags
797 @command{configure} usually does a good job at setting appropriate
798 values for these variables, but there are cases where you may want to
799 override them. For instance you may have several versions of a
800 compiler installed and would like to use another one, you may have
801 header files installed outside the default search path of the
802 compiler, or even libraries out of the way of the linker.
804 Here is how one would call @command{configure} to force it to use
805 @command{gcc-3} as C compiler, use header files from
806 @file{~/usr/include} when compiling, and libraries from
807 @file{~/usr/lib} when linking.
810 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr CC=gcc-3 \
811 CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib}
814 Again, a full list of these variables appears in the output of
815 @code{./configure --help}.
818 @subsection Overriding Default Configuration Setting with @file{config.site}
819 @cindex @file{config.site} example
821 When installing several packages using the same setup, it can be
822 convenient to create a file to capture common settings.
823 If a file named @file{@var{prefix}/share/config.site} exists,
824 @command{configure} will source it at the beginning of its execution.
826 Recall the command from the previous section:
829 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr CC=gcc-3 \
830 CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib}
833 Assuming we are installing many package in @file{~/usr}, and will
834 always want to use these definitions of @code{CC}, @code{CPPFLAGS}, and
835 @code{LDFLAGS}, we can automate this by creating the following
836 @file{~/usr/share/config.site} file:
839 test -z "$CC" && CC=gcc-3
840 test -z "$CPPFLAGS" && CPPFLAGS=-I$HOME/usr/include
841 test -z "$LDFLAGS" && LDFLAGS=-L$HOME/usr/lib
844 Now, any time a @file{configure} script is using the @file{~/usr}
845 prefix, it will execute the above @file{config.site} and define
846 these three variables.
849 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr}
850 configure: loading site script /home/adl/usr/share/config.site
854 @xref{Site Defaults, , Setting Site Defaults, autoconf, The Autoconf
855 Manual}, for more information about this feature.
859 @subsection Parallel Build Trees (a.k.a.@: VPATH Builds)
860 @cindex Parallel build trees
862 @cindex source tree and build tree
863 @cindex build tree and source tree
864 @cindex trees, source vs.@: build
866 The GNU Build System distinguishes two trees: the source tree, and
869 The source tree is rooted in the directory containing
870 @file{configure}. It contains all the sources files (those that are
871 distributed), and may be arranged using several subdirectories.
873 The build tree is rooted in the directory in which @file{configure}
874 was run, and is populated with all object files, programs, libraries,
875 and other derived files built from the sources (and hence not
876 distributed). The build tree usually has the same subdirectory layout
877 as the source tree; its subdirectories are created automatically by
880 If @file{configure} is executed in its own directory, the source and
881 build trees are combined: derived files are constructed in the same
882 directories as their sources. This was the case in our first
883 installation example (@pxref{Basic Installation}).
885 A common request from users is that they want to confine all derived
886 files to a single directory, to keep their source directories
887 uncluttered. Here is how we could run @file{configure} to build
888 everything in a subdirectory called @file{build/}.
891 ~ % @kbd{tar zxf ~/amhello-1.0.tar.gz}
892 ~ % @kbd{cd amhello-1.0}
893 ~/amhello-1.0 % @kbd{mkdir build && cd build}
894 ~/amhello-1.0/build % @kbd{../configure}
896 ~/amhello-1.0/build % @kbd{make}
900 These setups, where source and build trees are different, are often
901 called @dfn{parallel builds} or @dfn{VPATH builds}. The expression
902 @emph{parallel build} is misleading: the word @emph{parallel} is a
903 reference to the way the build tree shadows the source tree, it is not
904 about some concurrency in the way build commands are run. For this
905 reason we refer to such setups using the name @emph{VPATH builds} in
906 the following. @emph{VPATH} is the name of the @command{make} feature
907 used by the @file{Makefile}s to allow these builds (@pxref{General
908 Search, , @code{VPATH} Search Path for All Prerequisites, make, The
911 @cindex multiple configurations, example
912 @cindex debug build, example
913 @cindex optimized build, example
915 VPATH builds have other interesting uses. One is to build the same
916 sources with multiple configurations. For instance:
918 @c Keep in sync with amhello-cflags.test.
920 ~ % @kbd{tar zxf ~/amhello-1.0.tar.gz}
921 ~ % @kbd{cd amhello-1.0}
922 ~/amhello-1.0 % @kbd{mkdir debug optim && cd debug}
923 ~/amhello-1.0/debug % @kbd{../configure CFLAGS='-g -O0'}
925 ~/amhello-1.0/debug % @kbd{make}
927 ~/amhello-1.0/debug % cd ../optim
928 ~/amhello-1.0/optim % @kbd{../configure CFLAGS='-O3 -fomit-frame-pointer'}
930 ~/amhello-1.0/optim % @kbd{make}
934 With network file systems, a similar approach can be used to build the
935 same sources on different machines. For instance, suppose that the
936 sources are installed on a directory shared by two hosts: @code{HOST1}
937 and @code{HOST2}, which may be different platforms.
940 ~ % @kbd{cd /nfs/src}
941 /nfs/src % @kbd{tar zxf ~/amhello-1.0.tar.gz}
944 On the first host, you could create a local build directory:
946 [HOST1] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
947 [HOST1] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure}
949 [HOST1] /tmp/amh % @kbd{make && sudo make install}
954 (Here we assume that the installer has configured @command{sudo} so it
955 can execute @code{make install} with root privileges; it is more convenient
956 than using @command{su} like in @ref{Basic Installation}).
958 On the second host, you would do exactly the same, possibly at
961 [HOST2] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
962 [HOST2] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure}
964 [HOST2] /tmp/amh % @kbd{make && sudo make install}
968 @cindex read-only source tree
969 @cindex source tree, read-only
971 In this scenario, nothing forbids the @file{/nfs/src/amhello-1.0}
972 directory from being read-only. In fact VPATH builds are also a means
973 of building packages from a read-only medium such as a CD-ROM. (The
974 FSF used to sell CD-ROM with unpacked source code, before the GNU
975 project grew so big.)
977 @node Two-Part Install
978 @subsection Two-Part Installation
980 In our last example (@pxref{VPATH Builds}), a source tree was shared
981 by two hosts, but compilation and installation were done separately on
984 The GNU Build System also supports networked setups where part of the
985 installed files should be shared amongst multiple hosts. It does so
986 by distinguishing architecture-dependent files from
987 architecture-independent files, and providing two @file{Makefile}
988 targets to install each of these classes of files.
990 @trindex install-exec
991 @trindex install-data
993 These targets are @code{install-exec} for architecture-dependent files
994 and @code{install-data} for architecture-independent files.
995 The command we used up to now, @code{make install}, can be thought of
996 as a shorthand for @code{make install-exec install-data}.
998 From the GNU Build System point of view, the distinction between
999 architecture-dependent files and architecture-independent files is
1000 based exclusively on the directory variable used to specify their
1001 installation destination. In the list of directory variables we
1002 provided earlier (@pxref{Standard Directory Variables}), all the
1003 variables based on @var{exec-prefix} designate architecture-dependent
1004 directories whose files will be installed by @code{make install-exec}.
1005 The others designate architecture-independent directories and will
1006 serve files installed by @code{make install-data}. @xref{The Two Parts
1007 of Install}, for more details.
1009 Here is how we could revisit our two-host installation example,
1010 assuming that (1) we want to install the package directly in
1011 @file{/usr}, and (2) the directory @file{/usr/share} is shared by the
1014 On the first host we would run
1016 [HOST1] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
1017 [HOST1] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure --prefix /usr}
1019 [HOST1] /tmp/amh % @kbd{make && sudo make install}
1023 On the second host, however, we need only install the
1024 architecture-specific files.
1026 [HOST2] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
1027 [HOST2] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure --prefix /usr}
1029 [HOST2] /tmp/amh % @kbd{make && sudo make install-exec}
1033 In packages that have installation checks, it would make sense to run
1034 @code{make installcheck} (@pxref{Basic Installation}) to verify that
1035 the package works correctly despite the apparent partial installation.
1037 @node Cross-Compilation
1038 @subsection Cross-Compilation
1039 @cindex cross-compilation
1041 To @dfn{cross-compile} is to build on one platform a binary that will
1042 run on another platform. When speaking of cross-compilation, it is
1043 important to distinguish between the @dfn{build platform} on which
1044 the compilation is performed, and the @dfn{host platform} on which the
1045 resulting executable is expected to run. The following
1046 @command{configure} options are used to specify each of them:
1049 @item --build=@var{build}
1050 @opindex --build=@var{build}
1051 The system on which the package is built.
1052 @item --host=@var{host}
1053 @opindex --host=@var{host}
1054 The system where built programs and libraries will run.
1057 When the @option{--host} is used, @command{configure} will search for
1058 the cross-compiling suite for this platform. Cross-compilation tools
1059 commonly have their target architecture as prefix of their name. For
1060 instance my cross-compiler for MinGW32 has its binaries called
1061 @code{i586-mingw32msvc-gcc}, @code{i586-mingw32msvc-ld},
1062 @code{i586-mingw32msvc-as}, etc.
1064 @cindex MinGW cross-compilation example
1065 @cindex cross-compilation example
1067 Here is how we could build @code{amhello-1.0} for
1068 @code{i586-mingw32msvc} on a GNU/Linux PC.
1070 @c Keep in sync with amhello-cross-compile.test.
1072 ~/amhello-1.0 % @kbd{./configure --build i686-pc-linux-gnu --host i586-mingw32msvc}
1073 checking for a BSD-compatible install... /usr/bin/install -c
1074 checking whether build environment is sane... yes
1075 checking for gawk... gawk
1076 checking whether make sets $(MAKE)... yes
1077 checking for i586-mingw32msvc-strip... i586-mingw32msvc-strip
1078 checking for i586-mingw32msvc-gcc... i586-mingw32msvc-gcc
1079 checking for C compiler default output file name... a.exe
1080 checking whether the C compiler works... yes
1081 checking whether we are cross compiling... yes
1082 checking for suffix of executables... .exe
1083 checking for suffix of object files... o
1084 checking whether we are using the GNU C compiler... yes
1085 checking whether i586-mingw32msvc-gcc accepts -g... yes
1086 checking for i586-mingw32msvc-gcc option to accept ANSI C...
1088 ~/amhello-1.0 % @kbd{make}
1090 ~/amhello-1.0 % @kbd{cd src; file hello.exe}
1091 hello.exe: MS Windows PE 32-bit Intel 80386 console executable not relocatable
1094 The @option{--host} and @option{--build} options are usually all we
1095 need for cross-compiling. The only exception is if the package being
1096 built is itself a cross-compiler: we need a third option to specify
1097 its target architecture.
1100 @item --target=@var{target}
1101 @opindex --target=@var{target}
1102 When building compiler tools: the system for which the tools will
1106 For instance when installing GCC, the GNU Compiler Collection, we can
1107 use @option{--target=@/@var{target}} to specify that we want to build
1108 GCC as a cross-compiler for @var{target}. Mixing @option{--build} and
1109 @option{--target}, we can actually cross-compile a cross-compiler;
1110 such a three-way cross-compilation is known as a @dfn{Canadian cross}.
1112 @xref{Specifying Names, , Specifying the System Type, autoconf, The
1113 Autoconf Manual}, for more information about these @command{configure}
1117 @subsection Renaming Programs at Install Time
1118 @cindex Renaming programs
1119 @cindex Transforming program names
1120 @cindex Programs, renaming during installation
1122 The GNU Build System provides means to automatically rename
1123 executables and manpages before they are installed (@pxref{Man Pages}).
1124 This is especially convenient
1125 when installing a GNU package on a system that already has a
1126 proprietary implementation you do not want to overwrite. For instance,
1127 you may want to install GNU @command{tar} as @command{gtar} so you can
1128 distinguish it from your vendor's @command{tar}.
1130 This can be done using one of these three @command{configure} options.
1133 @item --program-prefix=@var{prefix}
1134 @opindex --program-prefix=@var{prefix}
1135 Prepend @var{prefix} to installed program names.
1136 @item --program-suffix=@var{suffix}
1137 @opindex --program-suffix=@var{suffix}
1138 Append @var{suffix} to installed program names.
1139 @item --program-transform-name=@var{program}
1140 @opindex --program-transform-name=@var{program}
1141 Run @code{sed @var{program}} on installed program names.
1144 The following commands would install @file{hello}
1145 as @file{/usr/local/bin/test-hello}, for instance.
1148 ~/amhello-1.0 % @kbd{./configure --program-prefix test-}
1150 ~/amhello-1.0 % @kbd{make}
1152 ~/amhello-1.0 % @kbd{sudo make install}
1157 @subsection Building Binary Packages Using DESTDIR
1160 The GNU Build System's @code{make install} and @code{make uninstall}
1161 interface does not exactly fit the needs of a system administrator
1162 who has to deploy and upgrade packages on lots of hosts. In other
1163 words, the GNU Build System does not replace a package manager.
1165 Such package managers usually need to know which files have been
1166 installed by a package, so a mere @code{make install} is
1169 @cindex Staged installation
1171 The @code{DESTDIR} variable can be used to perform a staged
1172 installation. The package should be configured as if it was going to
1173 be installed in its final location (e.g., @code{--prefix /usr}), but
1174 when running @code{make install}, the @code{DESTDIR} should be set to
1175 the absolute name of a directory into which the installation will be
1176 diverted. From this directory it is easy to review which files are
1177 being installed where, and finally copy them to their final location
1180 @cindex Binary package
1182 For instance here is how we could create a binary package containing a
1183 snapshot of all the files to be installed.
1185 @c Keep in sync with amhello-binpkg.test.
1187 ~/amhello-1.0 % @kbd{./configure --prefix /usr}
1189 ~/amhello-1.0 % @kbd{make}
1191 ~/amhello-1.0 % @kbd{make DESTDIR=$HOME/inst install}
1193 ~/amhello-1.0 % @kbd{cd ~/inst}
1194 ~/inst % @kbd{find . -type f -print > ../files.lst}
1195 ~/inst % @kbd{tar zcvf ~/amhello-1.0-i686.tar.gz `cat ../files.lst`}
1197 ./usr/share/doc/amhello/README
1200 After this example, @code{amhello-1.0-i686.tar.gz} is ready to be
1201 uncompressed in @file{/} on many hosts. (Using @code{`cat ../files.lst`}
1202 instead of @samp{.} as argument for @command{tar} avoids entries for
1203 each subdirectory in the archive: we would not like @command{tar} to
1204 restore the modification time of @file{/}, @file{/usr/}, etc.)
1206 Note that when building packages for several architectures, it might
1207 be convenient to use @code{make install-data} and @code{make
1208 install-exec} (@pxref{Two-Part Install}) to gather
1209 architecture-independent files in a single package.
1211 @xref{Install}, for more information.
1213 @c We should document PRE_INSTALL/POST_INSTALL/NORMAL_INSTALL and their
1214 @c UNINSTALL counterparts.
1216 @node Preparing Distributions
1217 @subsection Preparing Distributions
1218 @cindex Preparing distributions
1219 @cindex Packages, preparation
1220 @cindex Distributions, preparation
1222 We have already mentioned @code{make dist}. This target collects all
1223 your source files and the necessary parts of the build system to
1224 create a tarball named @file{@var{package}-@var{version}.tar.gz}.
1226 @cindex @code{distcheck} better than @code{dist}
1228 Another, more useful command is @code{make distcheck}. The
1229 @code{distcheck} target constructs
1230 @file{@var{package}-@var{version}.tar.gz} just as well as @code{dist},
1231 but it additionally ensures most of the use cases presented so far
1236 It attempts a full compilation of the package (@pxref{Basic
1237 Installation}), unpacking the newly constructed tarball, running
1238 @code{make}, @code{make check}, @code{make install}, as well as
1239 @code{make installcheck}, and even @code{make dist},
1241 it tests VPATH builds with read-only source tree (@pxref{VPATH Builds}),
1243 it makes sure @code{make clean}, @code{make distclean}, and @code{make
1244 uninstall} do not omit any file (@pxref{Standard Targets}),
1246 and it checks that @code{DESTDIR} installations work (@pxref{DESTDIR}).
1249 All of these actions are performed in a temporary subdirectory, so
1250 that no root privileges are required.
1252 Releasing a package that fails @code{make distcheck} means that one of
1253 the scenarios we presented will not work and some users will be
1254 disappointed. Therefore it is a good practice to release a package
1255 only after a successful @code{make distcheck}. This of course does
1256 not imply that the package will be flawless, but at least it will
1257 prevent some of the embarrassing errors you may find in packages
1258 released by people who have never heard about @code{distcheck} (like
1259 @code{DESTDIR} not working because of a typo, or a distributed file
1260 being erased by @code{make clean}, or even @code{VPATH} builds not
1263 @xref{Creating amhello}, to recreate @file{amhello-1.0.tar.gz} using
1264 @code{make distcheck}. @xref{Checking the Distribution}, for more
1265 information about @code{distcheck}.
1267 @node Dependency Tracking
1268 @subsection Automatic Dependency Tracking
1269 @cindex Dependency tracking
1271 Dependency tracking is performed as a side-effect of compilation.
1272 Each time the build system compiles a source file, it computes its
1273 list of dependencies (in C these are the header files included by the
1274 source being compiled). Later, any time @command{make} is run and a
1275 dependency appears to have changed, the dependent files will be
1278 Automake generates code for automatic dependency tracking by default,
1279 unless the developer chooses to override it; for more information,
1280 @pxref{Dependencies}.
1282 When @command{configure} is executed, you can see it probing each
1283 compiler for the dependency mechanism it supports (several mechanisms
1287 ~/amhello-1.0 % @kbd{./configure --prefix /usr}
1289 checking dependency style of gcc... gcc3
1293 Because dependencies are only computed as a side-effect of the
1294 compilation, no dependency information exists the first time a package
1295 is built. This is OK because all the files need to be built anyway:
1296 @code{make} does not have to decide which files need to be rebuilt.
1297 In fact, dependency tracking is completely useless for one-time builds
1298 and there is a @command{configure} option to disable this:
1301 @item --disable-dependency-tracking
1302 @opindex --disable-dependency-tracking
1303 Speed up one-time builds.
1306 Some compilers do not offer any practical way to derive the list of
1307 dependencies as a side-effect of the compilation, requiring a separate
1308 run (maybe of another tool) to compute these dependencies. The
1309 performance penalty implied by these methods is important enough to
1310 disable them by default. The option @option{--enable-dependency-tracking}
1311 must be passed to @command{configure} to activate them.
1314 @item --enable-dependency-tracking
1315 @opindex --enable-dependency-tracking
1316 Do not reject slow dependency extractors.
1319 @xref{Dependency Tracking Evolution, , Dependency Tracking Evolution,
1320 automake-history, Brief History of Automake}, for some discussion about
1321 the different dependency tracking schemes used by Automake over the years.
1323 @node Nested Packages
1324 @subsection Nested Packages
1325 @cindex Nested packages
1326 @cindex Packages, nested
1329 Although nesting packages isn't something we would recommend to
1330 someone who is discovering the Autotools, it is a nice feature worthy
1331 of mention in this small advertising tour.
1333 Autoconfiscated packages (that means packages whose build system have
1334 been created by Autoconf and friends) can be nested to arbitrary
1337 A typical setup is that package A will distribute one of the libraries
1338 it needs in a subdirectory. This library B is a complete package with
1339 its own GNU Build System. The @command{configure} script of A will
1340 run the @command{configure} script of B as part of its execution,
1341 building and installing A will also build and install B. Generating a
1342 distribution for A will also include B.
1344 It is possible to gather several packages like this. GCC is a heavy
1345 user of this feature. This gives installers a single package to
1346 configure, build and install, while it allows developers to work on
1347 subpackages independently.
1349 When configuring nested packages, the @command{configure} options
1350 given to the top-level @command{configure} are passed recursively to
1351 nested @command{configure}s. A package that does not understand an
1352 option will ignore it, assuming it is meaningful to some other
1355 @opindex --help=recursive
1357 The command @code{configure --help=recursive} can be used to display
1358 the options supported by all the included packages.
1360 @xref{Subpackages}, for an example setup.
1363 @section How Autotools Help
1364 @cindex Autotools, purpose
1366 There are several reasons why you may not want to implement the GNU
1367 Build System yourself (read: write a @file{configure} script and
1368 @file{Makefile}s yourself).
1372 As we have seen, the GNU Build System has a lot of
1373 features (@pxref{Use Cases}).
1374 Some users may expect features you have not implemented because
1375 you did not need them.
1377 Implementing these features portably is difficult and exhausting.
1378 Think of writing portable shell scripts, and portable
1379 @file{Makefile}s, for systems you may not have handy. @xref{Portable
1380 Shell, , Portable Shell Programming, autoconf, The Autoconf Manual}, to
1383 You will have to upgrade your setup to follow changes to the GNU
1387 The GNU Autotools take all this burden off your back and provide:
1391 Tools to create a portable, complete, and self-contained GNU Build
1392 System, from simple instructions.
1393 @emph{Self-contained} meaning the resulting build system does not
1394 require the GNU Autotools.
1396 A central place where fixes and improvements are made:
1397 a bug-fix for a portability issue will benefit every package.
1400 Yet there also exist reasons why you may want NOT to use the
1401 Autotools@enddots{} For instance you may be already using (or used to)
1402 another incompatible build system. Autotools will only be useful if
1403 you do accept the concepts of the GNU Build System. People who have their
1404 own idea of how a build system should work will feel frustrated by the
1408 @section A Small Hello World
1409 @cindex Example Hello World
1410 @cindex Hello World example
1411 @cindex @file{amhello-1.0.tar.gz}, creation
1413 In this section we recreate the @file{amhello-1.0} package from
1414 scratch. The first subsection shows how to call the Autotools to
1415 instantiate the GNU Build System, while the second explains the
1416 meaning of the @file{configure.ac} and @file{Makefile.am} files read
1419 @anchor{amhello Explained}
1421 * Creating amhello:: Create @file{amhello-1.0.tar.gz} from scratch
1422 * amhello's configure.ac Setup Explained::
1423 * amhello's Makefile.am Setup Explained::
1426 @node Creating amhello
1427 @subsection Creating @file{amhello-1.0.tar.gz}
1429 Here is how we can recreate @file{amhello-1.0.tar.gz} from scratch.
1430 The package is simple enough so that we will only need to write 5
1431 files. (You may copy them from the final @file{amhello-1.0.tar.gz}
1432 that is distributed with Automake if you do not want to write them.)
1434 Create the following files in an empty directory.
1439 @file{src/main.c} is the source file for the @file{hello} program. We
1440 store it in the @file{src/} subdirectory, because later, when the package
1441 evolves, it will ease the addition of a @file{man/} directory for man
1442 pages, a @file{data/} directory for data files, etc.
1444 ~/amhello % @kbd{cat src/main.c}
1451 puts ("Hello World!");
1452 puts ("This is " PACKAGE_STRING ".");
1458 @file{README} contains some very limited documentation for our little
1461 ~/amhello % @kbd{cat README}
1462 This is a demonstration package for GNU Automake.
1463 Type `info Automake' to read the Automake manual.
1467 @file{Makefile.am} and @file{src/Makefile.am} contain Automake
1468 instructions for these two directories.
1471 ~/amhello % @kbd{cat src/Makefile.am}
1472 bin_PROGRAMS = hello
1473 hello_SOURCES = main.c
1474 ~/amhello % @kbd{cat Makefile.am}
1476 dist_doc_DATA = README
1480 Finally, @file{configure.ac} contains Autoconf instructions to
1481 create the @command{configure} script.
1484 ~/amhello % @kbd{cat configure.ac}
1485 AC_INIT([amhello], [1.0], [@value{PACKAGE_BUGREPORT}])
1486 AM_INIT_AUTOMAKE([-Wall -Werror foreign])
1488 AC_CONFIG_HEADERS([config.h])
1497 @cindex @command{autoreconf}, example
1499 Once you have these five files, it is time to run the Autotools to
1500 instantiate the build system. Do this using the @command{autoreconf}
1504 ~/amhello % @kbd{autoreconf --install}
1505 configure.ac: installing `./install-sh'
1506 configure.ac: installing `./missing'
1507 src/Makefile.am: installing `./depcomp'
1510 At this point the build system is complete.
1512 In addition to the three scripts mentioned in its output, you can see
1513 that @command{autoreconf} created four other files: @file{configure},
1514 @file{config.h.in}, @file{Makefile.in}, and @file{src/Makefile.in}.
1515 The latter three files are templates that will be adapted to the
1516 system by @command{configure} under the names @file{config.h},
1517 @file{Makefile}, and @file{src/Makefile}. Let's do this:
1520 ~/amhello % @kbd{./configure}
1521 checking for a BSD-compatible install... /usr/bin/install -c
1522 checking whether build environment is sane... yes
1523 checking for gawk... no
1524 checking for mawk... mawk
1525 checking whether make sets $(MAKE)... yes
1526 checking for gcc... gcc
1527 checking for C compiler default output file name... a.out
1528 checking whether the C compiler works... yes
1529 checking whether we are cross compiling... no
1530 checking for suffix of executables...
1531 checking for suffix of object files... o
1532 checking whether we are using the GNU C compiler... yes
1533 checking whether gcc accepts -g... yes
1534 checking for gcc option to accept ISO C89... none needed
1535 checking for style of include used by make... GNU
1536 checking dependency style of gcc... gcc3
1537 configure: creating ./config.status
1538 config.status: creating Makefile
1539 config.status: creating src/Makefile
1540 config.status: creating config.h
1541 config.status: executing depfiles commands
1545 @cindex @code{distcheck} example
1547 You can see @file{Makefile}, @file{src/Makefile}, and @file{config.h}
1548 being created at the end after @command{configure} has probed the
1549 system. It is now possible to run all the targets we wish
1550 (@pxref{Standard Targets}). For instance:
1553 ~/amhello % @kbd{make}
1555 ~/amhello % @kbd{src/hello}
1557 This is amhello 1.0.
1558 ~/amhello % @kbd{make distcheck}
1560 =============================================
1561 amhello-1.0 archives ready for distribution:
1563 =============================================
1566 Note that running @command{autoreconf} is only needed initially when
1567 the GNU Build System does not exist. When you later change some
1568 instructions in a @file{Makefile.am} or @file{configure.ac}, the
1569 relevant part of the build system will be regenerated automatically
1570 when you execute @command{make}.
1572 @command{autoreconf} is a script that calls @command{autoconf},
1573 @command{automake}, and a bunch of other commands in the right order.
1574 If you are beginning with these tools, it is not important to figure
1575 out in which order all these tools should be invoked and why. However,
1576 because Autoconf and Automake have separate manuals, the important
1577 point to understand is that @command{autoconf} is in charge of
1578 creating @file{configure} from @file{configure.ac}, while
1579 @command{automake} is in charge of creating @file{Makefile.in}s from
1580 @file{Makefile.am}s and @file{configure.ac}. This should at least
1581 direct you to the right manual when seeking answers.
1584 @node amhello's configure.ac Setup Explained
1585 @subsection @code{amhello}'s @file{configure.ac} Setup Explained
1587 @cindex @file{configure.ac}, Hello World
1589 Let us begin with the contents of @file{configure.ac}.
1592 AC_INIT([amhello], [1.0], [@value{PACKAGE_BUGREPORT}])
1593 AM_INIT_AUTOMAKE([-Wall -Werror foreign])
1595 AC_CONFIG_HEADERS([config.h])
1603 This file is read by both @command{autoconf} (to create
1604 @file{configure}) and @command{automake} (to create the various
1605 @file{Makefile.in}s). It contains a series of M4 macros that will be
1606 expanded as shell code to finally form the @file{configure} script.
1607 We will not elaborate on the syntax of this file, because the Autoconf
1608 manual has a whole section about it (@pxref{Writing Autoconf Input, ,
1609 Writing @file{configure.ac}, autoconf, The Autoconf Manual}).
1611 The macros prefixed with @code{AC_} are Autoconf macros, documented
1612 in the Autoconf manual (@pxref{Autoconf Macro Index, , Autoconf Macro
1613 Index, autoconf, The Autoconf Manual}). The macros that start with
1614 @code{AM_} are Automake macros, documented later in this manual
1615 (@pxref{Macro Index}).
1617 The first two lines of @file{configure.ac} initialize Autoconf and
1618 Automake. @code{AC_INIT} takes in as parameters the name of the package,
1619 its version number, and a contact address for bug-reports about the
1620 package (this address is output at the end of @code{./configure
1621 --help}, for instance). When adapting this setup to your own package,
1622 by all means please do not blindly copy Automake's address: use the
1623 mailing list of your package, or your own mail address.
1629 The argument to @code{AM_INIT_AUTOMAKE} is a list of options for
1630 @command{automake} (@pxref{Options}). @option{-Wall} and
1631 @option{-Werror} ask @command{automake} to turn on all warnings and
1632 report them as errors. We are speaking of @strong{Automake} warnings
1633 here, such as dubious instructions in @file{Makefile.am}. This has
1634 absolutely nothing to do with how the compiler will be called, even
1635 though it may support options with similar names. Using @option{-Wall
1636 -Werror} is a safe setting when starting to work on a package: you do
1637 not want to miss any issues. Later you may decide to relax things a
1638 bit. The @option{foreign} option tells Automake that this package
1639 will not follow the GNU Standards. GNU packages should always
1640 distribute additional files such as @file{ChangeLog}, @file{AUTHORS},
1641 etc. We do not want @command{automake} to complain about these
1642 missing files in our small example.
1644 The @code{AC_PROG_CC} line causes the @command{configure} script to
1645 search for a C compiler and define the variable @code{CC} with its
1646 name. The @file{src/Makefile.in} file generated by Automake uses the
1647 variable @code{CC} to build @file{hello}, so when @command{configure}
1648 creates @file{src/Makefile} from @file{src/Makefile.in}, it will define
1649 @code{CC} with the value it has found. If Automake is asked to create
1650 a @file{Makefile.in} that uses @code{CC} but @file{configure.ac} does
1651 not define it, it will suggest you add a call to @code{AC_PROG_CC}.
1653 The @code{AC_CONFIG_HEADERS([config.h])} invocation causes the
1654 @command{configure} script to create a @file{config.h} file gathering
1655 @samp{#define}s defined by other macros in @file{configure.ac}. In our
1656 case, the @code{AC_INIT} macro already defined a few of them. Here
1657 is an excerpt of @file{config.h} after @command{configure} has run:
1661 /* Define to the address where bug reports for this package should be sent. */
1662 #define PACKAGE_BUGREPORT "@value{PACKAGE_BUGREPORT}"
1664 /* Define to the full name and version of this package. */
1665 #define PACKAGE_STRING "amhello 1.0"
1669 As you probably noticed, @file{src/main.c} includes @file{config.h} so
1670 it can use @code{PACKAGE_STRING}. In a real-world project,
1671 @file{config.h} can grow really big, with one @samp{#define} per
1672 feature probed on the system.
1674 The @code{AC_CONFIG_FILES} macro declares the list of files that
1675 @command{configure} should create from their @file{*.in} templates.
1676 Automake also scans this list to find the @file{Makefile.am} files it must
1677 process. (This is important to remember: when adding a new directory
1678 to your project, you should add its @file{Makefile} to this list,
1679 otherwise Automake will never process the new @file{Makefile.am} you
1680 wrote in that directory.)
1682 Finally, the @code{AC_OUTPUT} line is a closing command that actually
1683 produces the part of the script in charge of creating the files
1684 registered with @code{AC_CONFIG_HEADERS} and @code{AC_CONFIG_FILES}.
1686 @cindex @command{autoscan}
1688 When starting a new project, we suggest you start with such a simple
1689 @file{configure.ac}, and gradually add the other tests it requires.
1690 The command @command{autoscan} can also suggest a few of the tests
1691 your package may need (@pxref{autoscan Invocation, , Using
1692 @command{autoscan} to Create @file{configure.ac}, autoconf, The
1696 @node amhello's Makefile.am Setup Explained
1697 @subsection @code{amhello}'s @file{Makefile.am} Setup Explained
1699 @cindex @file{Makefile.am}, Hello World
1701 We now turn to @file{src/Makefile.am}. This file contains
1702 Automake instructions to build and install @file{hello}.
1705 bin_PROGRAMS = hello
1706 hello_SOURCES = main.c
1709 A @file{Makefile.am} has the same syntax as an ordinary
1710 @file{Makefile}. When @command{automake} processes a
1711 @file{Makefile.am} it copies the entire file into the output
1712 @file{Makefile.in} (that will be later turned into @file{Makefile} by
1713 @command{configure}) but will react to certain variable definitions
1714 by generating some build rules and other variables.
1715 Often @file{Makefile.am}s contain only a list of variable definitions as
1716 above, but they can also contain other variable and rule definitions that
1717 @command{automake} will pass along without interpretation.
1719 Variables that end with @code{_PROGRAMS} are special variables
1720 that list programs that the resulting @file{Makefile} should build.
1721 In Automake speak, this @code{_PROGRAMS} suffix is called a
1722 @dfn{primary}; Automake recognizes other primaries such as
1723 @code{_SCRIPTS}, @code{_DATA}, @code{_LIBRARIES}, etc.@: corresponding
1724 to different types of files.
1726 The @samp{bin} part of the @code{bin_PROGRAMS} tells
1727 @command{automake} that the resulting programs should be installed in
1728 @var{bindir}. Recall that the GNU Build System uses a set of variables
1729 to denote destination directories and allow users to customize these
1730 locations (@pxref{Standard Directory Variables}). Any such directory
1731 variable can be put in front of a primary (omitting the @code{dir}
1732 suffix) to tell @command{automake} where to install the listed files.
1734 Programs need to be built from source files, so for each program
1735 @code{@var{prog}} listed in a @code{@w{_PROGRAMS}} variable,
1736 @command{automake} will look for another variable named
1737 @code{@var{prog}_SOURCES} listing its source files. There may be more
1738 than one source file: they will all be compiled and linked together.
1740 Automake also knows that source files need to be distributed when
1741 creating a tarball (unlike built programs). So a side-effect of this
1742 @code{hello_SOURCES} declaration is that @file{main.c} will be
1743 part of the tarball created by @code{make dist}.
1745 Finally here are some explanations regarding the top-level
1750 dist_doc_DATA = README
1753 @code{SUBDIRS} is a special variable listing all directories that
1754 @command{make} should recurse into before processing the current
1755 directory. So this line is responsible for @command{make} building
1756 @file{src/hello} even though we run it from the top-level. This line
1757 also causes @code{make install} to install @file{src/hello} before
1758 installing @file{README} (not that this order matters).
1760 The line @code{dist_doc_DATA = README} causes @file{README} to be
1761 distributed and installed in @var{docdir}. Files listed with the
1762 @code{_DATA} primary are not automatically part of the tarball built
1763 with @code{make dist}, so we add the @code{dist_} prefix so they get
1764 distributed. However, for @file{README} it would not have been
1765 necessary: @command{automake} automatically distributes any
1766 @file{README} file it encounters (the list of other files
1767 automatically distributed is presented by @code{automake --help}).
1768 The only important effect of this second line is therefore to install
1769 @file{README} during @code{make install}.
1771 One thing not covered in this example is accessing the installation
1772 directory values (@pxref{Standard Directory Variables}) from your
1773 program code, that is, converting them into defined macros. For this,
1774 @pxref{Defining Directories,,, autoconf, The Autoconf Manual}.
1778 @chapter General ideas
1780 The following sections cover a few basic ideas that will help you
1781 understand how Automake works.
1784 * General Operation:: General operation of Automake
1785 * Strictness:: Standards conformance checking
1786 * Uniform:: The Uniform Naming Scheme
1787 * Length Limitations:: Staying below the command line length limit
1788 * Canonicalization:: How derived variables are named
1789 * User Variables:: Variables reserved for the user
1790 * Auxiliary Programs:: Programs automake might require
1794 @node General Operation
1795 @section General Operation
1797 Automake works by reading a @file{Makefile.am} and generating a
1798 @file{Makefile.in}. Certain variables and rules defined in the
1799 @file{Makefile.am} instruct Automake to generate more specialized code;
1800 for instance, a @code{bin_PROGRAMS} variable definition will cause rules
1801 for compiling and linking programs to be generated.
1803 @cindex Non-standard targets
1804 @cindex @code{git-dist}, non-standard example
1807 The variable definitions and rules in the @file{Makefile.am} are
1808 copied mostly verbatim into the generated file, with all variable
1809 definitions preceding all rules. This allows you to add almost
1810 arbitrary code into the generated @file{Makefile.in}. For instance,
1811 the Automake distribution includes a non-standard rule for the
1812 @code{git-dist} target, which the Automake maintainer uses to make
1813 distributions from the source control system.
1815 @cindex GNU make extensions
1817 Note that most GNU make extensions are not recognized by Automake. Using
1818 such extensions in a @file{Makefile.am} will lead to errors or confusing
1821 @cindex Append operator
1823 A special exception is that the GNU make append operator, @samp{+=}, is
1824 supported. This operator appends its right hand argument to the variable
1825 specified on the left. Automake will translate the operator into
1826 an ordinary @samp{=} operator; @samp{+=} will thus work with any make program.
1828 Automake tries to keep comments grouped with any adjoining rules or
1829 variable definitions.
1831 @cindex Limitations of automake parser
1832 @cindex Automake parser, limitations of
1833 @cindex indentation in Makefile.am
1834 Generally, Automake is not particularly smart in the parsing of unusual
1835 Makefile constructs, so you're advised to avoid fancy constructs or
1836 ``creative'' use of whitespaces.
1837 @c Keep this in sync with doc-parsing-buglets-tabs.test.
1838 For example, @key{TAB} characters cannot be used between a target name
1839 and the following ``@code{:}'' character, and variable assignments
1840 shouldn't be indented with @key{TAB} characters.
1841 @c Keep this in sync with doc-parsing-buglets-colneq-subst.test.
1842 Also, using more complex macro in target names can cause trouble:
1845 % @kbd{cat Makefile.am}
1848 Makefile.am:1: bad characters in variable name `$(FOO'
1849 Makefile.am:1: `:='-style assignments are not portable
1852 @cindex Make targets, overriding
1853 @cindex Make rules, overriding
1854 @cindex Overriding make rules
1855 @cindex Overriding make targets
1857 A rule defined in @file{Makefile.am} generally overrides any such
1858 rule of a similar name that would be automatically generated by
1859 @command{automake}. Although this is a supported feature, it is generally
1860 best to avoid making use of it, as sometimes the generated rules are
1863 @cindex Variables, overriding
1864 @cindex Overriding make variables
1866 Similarly, a variable defined in @file{Makefile.am} or
1867 @code{AC_SUBST}ed from @file{configure.ac} will override any
1868 definition of the variable that @command{automake} would ordinarily
1869 create. This feature is more often useful than the ability to
1870 override a rule. Be warned that many of the variables generated by
1871 @command{automake} are considered to be for internal use only, and their
1872 names might change in future releases.
1874 @cindex Recursive operation of Automake
1875 @cindex Automake, recursive operation
1876 @cindex Example of recursive operation
1878 When examining a variable definition, Automake will recursively examine
1879 variables referenced in the definition. For example, if Automake is
1880 looking at the content of @code{foo_SOURCES} in this snippet
1882 @c Keep in sync with interp.test.
1885 foo_SOURCES = c.c $(xs)
1888 it would use the files @file{a.c}, @file{b.c}, and @file{c.c} as the
1889 contents of @code{foo_SOURCES}.
1891 @cindex @code{##} (special Automake comment)
1892 @cindex Special Automake comment
1893 @cindex Comment, special to Automake
1895 Automake also allows a form of comment that is @emph{not} copied into
1896 the output; all lines beginning with @samp{##} (leading spaces allowed)
1897 are completely ignored by Automake.
1899 It is customary to make the first line of @file{Makefile.am} read:
1901 @cindex Makefile.am, first line
1902 @cindex First line of Makefile.am
1905 ## Process this file with automake to produce Makefile.in
1908 @c FIXME discuss putting a copyright into Makefile.am here? I would but
1909 @c I don't know quite what to say.
1911 @c FIXME document customary ordering of Makefile.am here!
1917 @cindex Non-GNU packages
1919 While Automake is intended to be used by maintainers of GNU packages, it
1920 does make some effort to accommodate those who wish to use it, but do
1921 not want to use all the GNU conventions.
1923 @cindex Strictness, defined
1924 @cindex Strictness, @option{foreign}
1925 @cindex @option{foreign} strictness
1926 @cindex Strictness, @option{gnu}
1927 @cindex @option{gnu} strictness
1928 @cindex Strictness, @option{gnits}
1929 @cindex @option{gnits} strictness
1931 To this end, Automake supports three levels of @dfn{strictness}---the
1932 strictness indicating how stringently Automake should check standards
1935 The valid strictness levels are:
1939 Automake will check for only those things that are absolutely
1940 required for proper operations. For instance, whereas GNU standards
1941 dictate the existence of a @file{NEWS} file, it will not be required in
1942 this mode. This strictness will also turn off some warnings by default
1943 (among them, portability warnings).
1944 The name comes from the fact that Automake is intended to be
1945 used for GNU programs; these relaxed rules are not the standard mode of
1949 Automake will check---as much as possible---for compliance to the GNU
1950 standards for packages. This is the default.
1953 Automake will check for compliance to the as-yet-unwritten @dfn{Gnits
1954 standards}. These are based on the GNU standards, but are even more
1955 detailed. Unless you are a Gnits standards contributor, it is
1956 recommended that you avoid this option until such time as the Gnits
1957 standard is actually published (which may never happen).
1960 @xref{Gnits}, for more information on the precise implications of the
1963 Automake also has a special ``cygnus'' mode that is similar to
1964 strictness but handled differently. This mode is useful for packages
1965 that are put into a ``Cygnus'' style tree (e.g., the GCC tree).
1966 @xref{Cygnus}, for more information on this mode.
1970 @section The Uniform Naming Scheme
1972 @cindex Uniform naming scheme
1974 Automake variables generally follow a @dfn{uniform naming scheme} that
1975 makes it easy to decide how programs (and other derived objects) are
1976 built, and how they are installed. This scheme also supports
1977 @command{configure} time determination of what should be built.
1979 @cindex @code{_PROGRAMS} primary variable
1980 @cindex @code{PROGRAMS} primary variable
1981 @cindex Primary variable, @code{PROGRAMS}
1982 @cindex Primary variable, defined
1985 At @command{make} time, certain variables are used to determine which
1986 objects are to be built. The variable names are made of several pieces
1987 that are concatenated together.
1989 The piece that tells @command{automake} what is being built is commonly called
1990 the @dfn{primary}. For instance, the primary @code{PROGRAMS} holds a
1991 list of programs that are to be compiled and linked.
1994 @cindex @code{pkgdatadir}, defined
1995 @cindex @code{pkgincludedir}, defined
1996 @cindex @code{pkglibdir}, defined
1997 @cindex @code{pkglibexecdir}, defined
2000 @vindex pkgincludedir
2002 @vindex pkglibexecdir
2004 @cindex @code{PACKAGE}, directory
2005 A different set of names is used to decide where the built objects
2006 should be installed. These names are prefixes to the primary, and they
2007 indicate which standard directory should be used as the installation
2008 directory. The standard directory names are given in the GNU standards
2009 (@pxref{Directory Variables, , , standards, The GNU Coding Standards}).
2010 Automake extends this list with @code{pkgdatadir}, @code{pkgincludedir},
2011 @code{pkglibdir}, and @code{pkglibexecdir}; these are the same as the
2012 non-@samp{pkg} versions, but with @samp{$(PACKAGE)} appended. For instance,
2013 @code{pkglibdir} is defined as @samp{$(libdir)/$(PACKAGE)}.
2015 @cindex @code{EXTRA_}, prepending
2016 For each primary, there is one additional variable named by prepending
2017 @samp{EXTRA_} to the primary name. This variable is used to list
2018 objects that may or may not be built, depending on what
2019 @command{configure} decides. This variable is required because Automake
2020 must statically know the entire list of objects that may be built in
2021 order to generate a @file{Makefile.in} that will work in all cases.
2023 @cindex @code{EXTRA_PROGRAMS}, defined
2024 @cindex Example, @code{EXTRA_PROGRAMS}
2025 @cindex @command{cpio} example
2027 For instance, @command{cpio} decides at configure time which programs
2028 should be built. Some of the programs are installed in @code{bindir},
2029 and some are installed in @code{sbindir}:
2032 EXTRA_PROGRAMS = mt rmt
2033 bin_PROGRAMS = cpio pax
2034 sbin_PROGRAMS = $(MORE_PROGRAMS)
2037 Defining a primary without a prefix as a variable, e.g.,
2038 @samp{PROGRAMS}, is an error.
2040 Note that the common @samp{dir} suffix is left off when constructing the
2041 variable names; thus one writes @samp{bin_PROGRAMS} and not
2042 @samp{bindir_PROGRAMS}.
2044 Not every sort of object can be installed in every directory. Automake
2045 will flag those attempts it finds in error (but see below how to override
2046 the check if you really need to).
2047 Automake will also diagnose obvious misspellings in directory names.
2049 @cindex Extending list of installation directories
2050 @cindex Installation directories, extending list
2052 Sometimes the standard directories---even as augmented by
2053 Automake---are not enough. In particular it is sometimes useful, for
2054 clarity, to install objects in a subdirectory of some predefined
2055 directory. To this end, Automake allows you to extend the list of
2056 possible installation directories. A given prefix (e.g., @samp{zar})
2057 is valid if a variable of the same name with @samp{dir} appended is
2058 defined (e.g., @samp{zardir}).
2060 For instance, the following snippet will install @file{file.xml} into
2061 @samp{$(datadir)/xml}.
2063 @c Keep in sync with primary-prefix-couples-documented-valid.test.
2065 xmldir = $(datadir)/xml
2069 This feature can also be used to override the sanity checks Automake
2070 performs to diagnose suspicious directory/primary couples (in the
2071 unlikely case these checks are undesirable, and you really know what
2072 you're doing). For example, Automake would error out on this input:
2074 @c Should be tested in primary-prefix-invalid-couples.test.
2076 # Forbidden directory combinations, automake will error out on this.
2077 pkglib_PROGRAMS = foo
2078 doc_LIBRARIES = libquux.a
2082 but it will succeed with this:
2084 @c Keep in sync with primary-prefix-couples-documented-valid.test.
2086 # Work around forbidden directory combinations. Do not use this
2087 # without a very good reason!
2088 my_execbindir = $(pkglibdir)
2089 my_doclibdir = $(docdir)
2090 my_execbin_PROGRAMS = foo
2091 my_doclib_LIBRARIES = libquux.a
2094 The @samp{exec} substring of the @samp{my_execbindir} variable lets
2095 the files be installed at the right time (@pxref{The Two Parts of
2098 @cindex @samp{noinst_} primary prefix, definition
2101 The special prefix @samp{noinst_} indicates that the objects in question
2102 should be built but not installed at all. This is usually used for
2103 objects required to build the rest of your package, for instance static
2104 libraries (@pxref{A Library}), or helper scripts.
2106 @cindex @samp{check_} primary prefix, definition
2109 The special prefix @samp{check_} indicates that the objects in question
2110 should not be built until the @samp{make check} command is run. Those
2111 objects are not installed either.
2113 The current primary names are @samp{PROGRAMS}, @samp{LIBRARIES},
2114 @samp{LTLIBRARIES}, @samp{LISP}, @samp{PYTHON}, @samp{JAVA},
2115 @samp{SCRIPTS}, @samp{DATA}, @samp{HEADERS}, @samp{MANS}, and
2129 Some primaries also allow additional prefixes that control other
2130 aspects of @command{automake}'s behavior. The currently defined prefixes
2131 are @samp{dist_}, @samp{nodist_}, @samp{nobase_}, and @samp{notrans_}.
2132 These prefixes are explained later (@pxref{Program and Library Variables})
2133 (@pxref{Man Pages}).
2136 @node Length Limitations
2137 @section Staying below the command line length limit
2139 @cindex command line length limit
2142 Traditionally, most unix-like systems have a length limitation for the
2143 command line arguments and environment contents when creating new
2144 processes (see for example
2145 @uref{http://www.in-ulm.de/@/~mascheck/@/various/@/argmax/} for an
2146 overview on this issue),
2147 which of course also applies to commands spawned by @command{make}.
2148 POSIX requires this limit to be at least 4096 bytes, and most modern
2149 systems have quite high limits (or are unlimited).
2151 In order to create portable Makefiles that do not trip over these
2152 limits, it is necessary to keep the length of file lists bounded.
2153 Unfortunately, it is not possible to do so fully transparently within
2154 Automake, so your help may be needed. Typically, you can split long
2155 file lists manually and use different installation directory names for
2156 each list. For example,
2159 data_DATA = file1 @dots{} file@var{N} file@var{N+1} @dots{} file@var{2N}
2163 may also be written as
2165 @c Keep in sync with primary-prefix-couples-documented-valid.test.
2167 data_DATA = file1 @dots{} file@var{N}
2168 data2dir = $(datadir)
2169 data2_DATA = file@var{N+1} @dots{} file@var{2N}
2173 and will cause Automake to treat the two lists separately during
2174 @code{make install}. See @ref{The Two Parts of Install} for choosing
2175 directory names that will keep the ordering of the two parts of
2176 installation Note that @code{make dist} may still only work on a host
2177 with a higher length limit in this example.
2179 Automake itself employs a couple of strategies to avoid long command
2180 lines. For example, when @samp{$@{srcdir@}/} is prepended to file
2181 names, as can happen with above @code{$(data_DATA)} lists, it limits
2182 the amount of arguments passed to external commands.
2184 Unfortunately, some system's @command{make} commands may prepend
2185 @code{VPATH} prefixes like @samp{$@{srcdir@}/} to file names from the
2186 source tree automatically (@pxref{Automatic Rule Rewriting, , Automatic
2187 Rule Rewriting, autoconf, The Autoconf Manual}). In this case, the user
2188 may have to switch to use GNU Make, or refrain from using VPATH builds,
2189 in order to stay below the length limit.
2191 For libraries and programs built from many sources, convenience archives
2192 may be used as intermediates in order to limit the object list length
2193 (@pxref{Libtool Convenience Libraries}).
2196 @node Canonicalization
2197 @section How derived variables are named
2199 @cindex canonicalizing Automake variables
2201 Sometimes a Makefile variable name is derived from some text the
2202 maintainer supplies. For instance, a program name listed in
2203 @samp{_PROGRAMS} is rewritten into the name of a @samp{_SOURCES}
2204 variable. In cases like this, Automake canonicalizes the text, so that
2205 program names and the like do not have to follow Makefile variable naming
2206 rules. All characters in the name except for letters, numbers, the
2207 strudel (@@), and the underscore are turned into underscores when making
2208 variable references.
2210 For example, if your program is named @file{sniff-glue}, the derived
2211 variable name would be @samp{sniff_glue_SOURCES}, not
2212 @samp{sniff-glue_SOURCES}. Similarly the sources for a library named
2213 @file{libmumble++.a} should be listed in the
2214 @samp{libmumble___a_SOURCES} variable.
2216 The strudel is an addition, to make the use of Autoconf substitutions in
2217 variable names less obfuscating.
2220 @node User Variables
2221 @section Variables reserved for the user
2223 @cindex variables, reserved for the user
2224 @cindex user variables
2226 Some @file{Makefile} variables are reserved by the GNU Coding Standards
2227 for the use of the ``user''---the person building the package. For
2228 instance, @code{CFLAGS} is one such variable.
2230 Sometimes package developers are tempted to set user variables such as
2231 @code{CFLAGS} because it appears to make their job easier. However,
2232 the package itself should never set a user variable, particularly not
2233 to include switches that are required for proper compilation of the
2234 package. Since these variables are documented as being for the
2235 package builder, that person rightfully expects to be able to override
2236 any of these variables at build time.
2238 To get around this problem, Automake introduces an automake-specific
2239 shadow variable for each user flag variable. (Shadow variables are
2240 not introduced for variables like @code{CC}, where they would make no
2241 sense.) The shadow variable is named by prepending @samp{AM_} to the
2242 user variable's name. For instance, the shadow variable for
2243 @code{YFLAGS} is @code{AM_YFLAGS}. The package maintainer---that is,
2244 the author(s) of the @file{Makefile.am} and @file{configure.ac}
2245 files---may adjust these shadow variables however necessary.
2247 @xref{Flag Variables Ordering}, for more discussion about these
2248 variables and how they interact with per-target variables.
2250 @node Auxiliary Programs
2251 @section Programs automake might require
2253 @cindex Programs, auxiliary
2254 @cindex Auxiliary programs
2256 Automake sometimes requires helper programs so that the generated
2257 @file{Makefile} can do its work properly. There are a fairly large
2258 number of them, and we list them here.
2260 Although all of these files are distributed and installed with
2261 Automake, a couple of them are maintained separately. The Automake
2262 copies are updated before each release, but we mention the original
2263 source in case you need more recent versions.
2267 This is a wrapper primarily for the Microsoft lib archiver, to make
2271 This is a wrapper for compilers that do not accept options @option{-c}
2272 and @option{-o} at the same time. It is only used when absolutely
2273 required. Such compilers are rare, with the Microsoft C/C++ Compiler
2274 as the most notable exception. This wrapper also makes the following
2275 common options available for that compiler, while performing file name
2276 translation where needed: @option{-I}, @option{-L}, @option{-l},
2277 @option{-Wl,} and @option{-Xlinker}.
2281 These two programs compute the canonical triplets for the given build,
2282 host, or target architecture. These programs are updated regularly to
2283 support new architectures and fix probes broken by changes in new
2284 kernel versions. Each new release of Automake comes with up-to-date
2285 copies of these programs. If your copy of Automake is getting old,
2286 you are encouraged to fetch the latest versions of these files from
2287 @url{http://savannah.gnu.org/git/?group=config} before making a
2291 This program understands how to run a compiler so that it will
2292 generate not only the desired output but also dependency information
2293 that is then used by the automatic dependency tracking feature
2294 (@pxref{Dependencies}).
2297 This program is used to byte-compile Emacs Lisp code.
2300 This is a replacement for the @command{install} program that works on
2301 platforms where @command{install} is unavailable or unusable.
2304 This script is used to generate a @file{version.texi} file. It examines
2305 a file and prints some date information about it.
2308 This wraps a number of programs that are typically only required by
2309 maintainers. If the program in question doesn't exist,
2310 @command{missing} prints an informative warning and attempts to fix
2311 things so that the build can continue.
2314 This script used to be a wrapper around @samp{mkdir -p}, which is not
2315 portable. Now we prefer to use @samp{install-sh -d} when @command{configure}
2316 finds that @samp{mkdir -p} does not work, this makes one less script to
2319 For backward compatibility @file{mkinstalldirs} is still used and
2320 distributed when @command{automake} finds it in a package. But it is no
2321 longer installed automatically, and it should be safe to remove it.
2324 This is used to byte-compile Python scripts.
2327 This implements the default test driver offered by the parallel
2331 Not a program, this file is required for @samp{make dvi}, @samp{make
2332 ps} and @samp{make pdf} to work when Texinfo sources are in the
2333 package. The latest version can be downloaded from
2334 @url{http://www.gnu.org/software/texinfo/}.
2337 This program wraps @command{lex} and @command{yacc} to rename their
2338 output files. It also ensures that, for instance, multiple
2339 @command{yacc} instances can be invoked in a single directory in
2346 @chapter Some example packages
2348 This section contains two small examples.
2350 The first example (@pxref{Complete}) assumes you have an existing
2351 project already using Autoconf, with handcrafted @file{Makefile}s, and
2352 that you want to convert it to using Automake. If you are discovering
2353 both tools, it is probably better that you look at the Hello World
2354 example presented earlier (@pxref{Hello World}).
2356 The second example (@pxref{true}) shows how two programs can be built
2357 from the same file, using different compilation parameters. It
2358 contains some technical digressions that are probably best skipped on
2362 * Complete:: A simple example, start to finish
2363 * true:: Building true and false
2368 @section A simple example, start to finish
2370 @cindex Complete example
2372 Let's suppose you just finished writing @code{zardoz}, a program to make
2373 your head float from vortex to vortex. You've been using Autoconf to
2374 provide a portability framework, but your @file{Makefile.in}s have been
2375 ad-hoc. You want to make them bulletproof, so you turn to Automake.
2377 @cindex @code{AM_INIT_AUTOMAKE}, example use
2379 The first step is to update your @file{configure.ac} to include the
2380 commands that @command{automake} needs. The way to do this is to add an
2381 @code{AM_INIT_AUTOMAKE} call just after @code{AC_INIT}:
2384 AC_INIT([zardoz], [1.0])
2389 Since your program doesn't have any complicating factors (e.g., it
2390 doesn't use @code{gettext}, it doesn't want to build a shared library),
2391 you're done with this part. That was easy!
2393 @cindex @command{aclocal} program, introduction
2394 @cindex @file{aclocal.m4}, preexisting
2395 @cindex @file{acinclude.m4}, defined
2397 Now you must regenerate @file{configure}. But to do that, you'll need
2398 to tell @command{autoconf} how to find the new macro you've used. The
2399 easiest way to do this is to use the @command{aclocal} program to
2400 generate your @file{aclocal.m4} for you. But wait@dots{} maybe you
2401 already have an @file{aclocal.m4}, because you had to write some hairy
2402 macros for your program. The @command{aclocal} program lets you put
2403 your own macros into @file{acinclude.m4}, so simply rename and then
2407 mv aclocal.m4 acinclude.m4
2412 @cindex @command{zardoz} example
2414 Now it is time to write your @file{Makefile.am} for @code{zardoz}.
2415 Since @code{zardoz} is a user program, you want to install it where the
2416 rest of the user programs go: @code{bindir}. Additionally,
2417 @code{zardoz} has some Texinfo documentation. Your @file{configure.ac}
2418 script uses @code{AC_REPLACE_FUNCS}, so you need to link against
2419 @samp{$(LIBOBJS)}. So here's what you'd write:
2422 bin_PROGRAMS = zardoz
2423 zardoz_SOURCES = main.c head.c float.c vortex9.c gun.c
2424 zardoz_LDADD = $(LIBOBJS)
2426 info_TEXINFOS = zardoz.texi
2429 Now you can run @samp{automake --add-missing} to generate your
2430 @file{Makefile.in} and grab any auxiliary files you might need, and
2435 @section Building true and false
2437 @cindex Example, @command{false} and @command{true}
2438 @cindex @command{false} Example
2439 @cindex @command{true} Example
2441 Here is another, trickier example. It shows how to generate two
2442 programs (@code{true} and @code{false}) from the same source file
2443 (@file{true.c}). The difficult part is that each compilation of
2444 @file{true.c} requires different @code{cpp} flags.
2447 bin_PROGRAMS = true false
2449 false_LDADD = false.o
2452 $(COMPILE) -DEXIT_CODE=0 -c true.c
2455 $(COMPILE) -DEXIT_CODE=1 -o false.o -c true.c
2458 Note that there is no @code{true_SOURCES} definition. Automake will
2459 implicitly assume that there is a source file named @file{true.c}
2460 (@pxref{Default _SOURCES}), and
2461 define rules to compile @file{true.o} and link @file{true}. The
2462 @samp{true.o: true.c} rule supplied by the above @file{Makefile.am},
2463 will override the Automake generated rule to build @file{true.o}.
2465 @code{false_SOURCES} is defined to be empty---that way no implicit value
2466 is substituted. Because we have not listed the source of
2467 @file{false}, we have to tell Automake how to link the program. This is
2468 the purpose of the @code{false_LDADD} line. A @code{false_DEPENDENCIES}
2469 variable, holding the dependencies of the @file{false} target will be
2470 automatically generated by Automake from the content of
2473 The above rules won't work if your compiler doesn't accept both
2474 @option{-c} and @option{-o}. The simplest fix for this is to introduce a
2475 bogus dependency (to avoid problems with a parallel @command{make}):
2478 true.o: true.c false.o
2479 $(COMPILE) -DEXIT_CODE=0 -c true.c
2482 $(COMPILE) -DEXIT_CODE=1 -c true.c && mv true.o false.o
2485 As it turns out, there is also a much easier way to do this same task.
2486 Some of the above technique is useful enough that we've kept the
2487 example in the manual. However if you were to build @code{true} and
2488 @code{false} in real life, you would probably use per-program
2489 compilation flags, like so:
2491 @c Keep in sync with specflg7.test and specflg8.test.
2493 bin_PROGRAMS = false true
2495 false_SOURCES = true.c
2496 false_CPPFLAGS = -DEXIT_CODE=1
2498 true_SOURCES = true.c
2499 true_CPPFLAGS = -DEXIT_CODE=0
2502 In this case Automake will cause @file{true.c} to be compiled twice,
2503 with different flags. In this instance, the names of the object files
2504 would be chosen by automake; they would be @file{false-true.o} and
2505 @file{true-true.o}. (The name of the object files rarely matters.)
2507 @node automake Invocation
2508 @chapter Creating a @file{Makefile.in}
2509 @c This node used to be named "Invoking automake". This @anchor
2510 @c allows old links to still work.
2511 @anchor{Invoking automake}
2513 @cindex Multiple @file{configure.ac} files
2514 @cindex Invoking @command{automake}
2515 @cindex @command{automake}, invoking
2516 @cindex Invocation of @command{automake}
2517 @cindex @command{automake}, invocation
2519 To create all the @file{Makefile.in}s for a package, run the
2520 @command{automake} program in the top level directory, with no
2521 arguments. @command{automake} will automatically find each
2522 appropriate @file{Makefile.am} (by scanning @file{configure.ac};
2523 @pxref{configure}) and generate the corresponding @file{Makefile.in}.
2524 Note that @command{automake} has a rather simplistic view of what
2525 constitutes a package; it assumes that a package has only one
2526 @file{configure.ac}, at the top. If your package has multiple
2527 @file{configure.ac}s, then you must run @command{automake} in each
2528 directory holding a @file{configure.ac}. (Alternatively, you may rely
2529 on Autoconf's @command{autoreconf}, which is able to recurse your
2530 package tree and run @command{automake} where appropriate.)
2532 You can optionally give @command{automake} an argument; @file{.am} is
2533 appended to the argument and the result is used as the name of the
2534 input file. This feature is generally only used to automatically
2535 rebuild an out-of-date @file{Makefile.in}. Note that
2536 @command{automake} must always be run from the topmost directory of a
2537 project, even if being used to regenerate the @file{Makefile.in} in
2538 some subdirectory. This is necessary because @command{automake} must
2539 scan @file{configure.ac}, and because @command{automake} uses the
2540 knowledge that a @file{Makefile.in} is in a subdirectory to change its
2541 behavior in some cases.
2544 Automake will run @command{autoconf} to scan @file{configure.ac} and
2545 its dependencies (i.e., @file{aclocal.m4} and any included file),
2546 therefore @command{autoconf} must be in your @env{PATH}. If there is
2547 an @env{AUTOCONF} variable in your environment it will be used
2548 instead of @command{autoconf}, this allows you to select a particular
2549 version of Autoconf. By the way, don't misunderstand this paragraph:
2550 @command{automake} runs @command{autoconf} to @strong{scan} your
2551 @file{configure.ac}, this won't build @file{configure} and you still
2552 have to run @command{autoconf} yourself for this purpose.
2554 @cindex @command{automake} options
2555 @cindex Options, @command{automake}
2556 @cindex Strictness, command line
2558 @command{automake} accepts the following options:
2560 @cindex Extra files distributed with Automake
2561 @cindex Files distributed with Automake
2562 @cindex @file{config.guess}
2566 @itemx --add-missing
2568 @opindex --add-missing
2569 Automake requires certain common files to exist in certain situations;
2570 for instance, @file{config.guess} is required if @file{configure.ac} invokes
2571 @code{AC_CANONICAL_HOST}. Automake is distributed with several of these
2572 files (@pxref{Auxiliary Programs}); this option will cause the missing
2573 ones to be automatically added to the package, whenever possible. In
2574 general if Automake tells you a file is missing, try using this option.
2575 By default Automake tries to make a symbolic link pointing to its own
2576 copy of the missing file; this can be changed with @option{--copy}.
2578 Many of the potentially-missing files are common scripts whose
2579 location may be specified via the @code{AC_CONFIG_AUX_DIR} macro.
2580 Therefore, @code{AC_CONFIG_AUX_DIR}'s setting affects whether a
2581 file is considered missing, and where the missing file is added
2584 In some strictness modes, additional files are installed, see @ref{Gnits}
2585 for more information.
2587 @item --libdir=@var{dir}
2589 Look for Automake data files in directory @var{dir} instead of in the
2590 installation directory. This is typically used for debugging.
2596 When used with @option{--add-missing}, causes installed files to be
2597 copied. The default is to make a symbolic link.
2601 Causes the generated @file{Makefile.in}s to follow Cygnus rules, instead
2602 of GNU or Gnits rules. For more information, see @ref{Cygnus}.
2606 @itemx --force-missing
2607 @opindex --force-missing
2608 When used with @option{--add-missing}, causes standard files to be reinstalled
2609 even if they already exist in the source tree. This involves removing
2610 the file from the source tree before creating the new symlink (or, with
2611 @option{--copy}, copying the new file).
2615 Set the global strictness to @option{foreign}. For more information, see
2620 Set the global strictness to @option{gnits}. For more information, see
2625 Set the global strictness to @option{gnu}. For more information, see
2626 @ref{Gnits}. This is the default strictness.
2630 Print a summary of the command line options and exit.
2633 @itemx --ignore-deps
2635 This disables the dependency tracking feature in generated
2636 @file{Makefile}s; see @ref{Dependencies}.
2638 @item --include-deps
2639 @opindex --include-deps
2640 This enables the dependency tracking feature. This feature is enabled
2641 by default. This option is provided for historical reasons only and
2642 probably should not be used.
2646 Ordinarily @command{automake} creates all @file{Makefile.in}s mentioned in
2647 @file{configure.ac}. This option causes it to only update those
2648 @file{Makefile.in}s that are out of date with respect to one of their
2652 @itemx --output-dir=@var{dir}
2654 @opindex --output-dir
2655 Put the generated @file{Makefile.in} in the directory @var{dir}.
2656 Ordinarily each @file{Makefile.in} is created in the directory of the
2657 corresponding @file{Makefile.am}. This option is deprecated and will be
2658 removed in a future release.
2664 Cause Automake to print information about which files are being read or
2669 Print the version number of Automake and exit.
2672 @itemx --warnings=@var{category}
2675 Output warnings falling in @var{category}. @var{category} can be
2679 warnings related to the GNU Coding Standards
2680 (@pxref{Top, , , standards, The GNU Coding Standards}).
2682 obsolete features or constructions
2684 user redefinitions of Automake rules or variables
2686 portability issues (e.g., use of @command{make} features that are
2687 known to be not portable)
2688 @item extra-portability
2689 extra portability issues related to obscure tools. One example of such
2690 a tool is the Microsoft @command{lib} archiver.
2692 weird syntax, unused variables, typos
2694 unsupported or incomplete features
2698 turn off all the warnings
2700 treat warnings as errors
2703 A category can be turned off by prefixing its name with @samp{no-}. For
2704 instance, @option{-Wno-syntax} will hide the warnings about unused
2707 The categories output by default are @samp{syntax} and
2708 @samp{unsupported}. Additionally, @samp{gnu} and @samp{portability}
2709 are enabled in @option{--gnu} and @option{--gnits} strictness.
2710 On the other hand, the @option{silent-rules} options (@pxref{Options})
2711 turns off portability warnings about recursive variable expansions.
2713 @c Checked by extra-portability.test
2714 Turning off @samp{portability} will also turn off @samp{extra-portability},
2715 and similarly turning on @samp{extra-portability} will also turn on
2716 @samp{portability}. However, turning on @samp{portability} or turning
2717 off @samp{extra-portability} will not affect the other category.
2720 The environment variable @env{WARNINGS} can contain a comma separated
2721 list of categories to enable. It will be taken into account before the
2722 command-line switches, this way @option{-Wnone} will also ignore any
2723 warning category enabled by @env{WARNINGS}. This variable is also used
2724 by other tools like @command{autoconf}; unknown categories are ignored
2729 @vindex AUTOMAKE_JOBS
2730 If the environment variable @env{AUTOMAKE_JOBS} contains a positive
2731 number, it is taken as the maximum number of Perl threads to use in
2732 @command{automake} for generating multiple @file{Makefile.in} files
2733 concurrently. This is an experimental feature.
2737 @chapter Scanning @file{configure.ac}, using @command{aclocal}
2739 @cindex @file{configure.ac}, scanning
2740 @cindex Scanning @file{configure.ac}
2741 @cindex Using @command{aclocal}
2742 @cindex @command{aclocal}, using
2744 Automake scans the package's @file{configure.ac} to determine certain
2745 information about the package. Some @command{autoconf} macros are required
2746 and some variables must be defined in @file{configure.ac}. Automake
2747 will also use information from @file{configure.ac} to further tailor its
2750 Automake also supplies some Autoconf macros to make the maintenance
2751 easier. These macros can automatically be put into your
2752 @file{aclocal.m4} using the @command{aclocal} program.
2755 * Requirements:: Configuration requirements
2756 * Optional:: Other things Automake recognizes
2757 * aclocal Invocation:: Auto-generating aclocal.m4
2758 * Macros:: Autoconf macros supplied with Automake
2763 @section Configuration requirements
2765 @cindex Automake requirements
2766 @cindex Requirements of Automake
2768 @acindex AM_INIT_AUTOMAKE
2769 The one real requirement of Automake is that your @file{configure.ac}
2770 call @code{AM_INIT_AUTOMAKE}. This macro does several things that are
2771 required for proper Automake operation (@pxref{Macros}).
2773 Here are the other macros that Automake requires but which are not run
2774 by @code{AM_INIT_AUTOMAKE}:
2777 @item AC_CONFIG_FILES
2779 @acindex AC_CONFIG_FILES
2781 These two macros are usually invoked as follows near the end of
2782 @file{configure.ac}.
2796 Automake uses these to determine which files to create (@pxref{Output, ,
2797 Creating Output Files, autoconf, The Autoconf Manual}). A listed file
2798 is considered to be an Automake generated @file{Makefile} if there
2799 exists a file with the same name and the @file{.am} extension appended.
2800 Typically, @samp{AC_CONFIG_FILES([foo/Makefile])} will cause Automake to
2801 generate @file{foo/Makefile.in} if @file{foo/Makefile.am} exists.
2803 When using @code{AC_CONFIG_FILES} with multiple input files, as in
2806 AC_CONFIG_FILES([Makefile:top.in:Makefile.in:bot.in])
2810 @command{automake} will generate the first @file{.in} input file for
2811 which a @file{.am} file exists. If no such file exists the output
2812 file is not considered to be generated by Automake.
2814 Files created by @code{AC_CONFIG_FILES}, be they Automake
2815 @file{Makefile}s or not, are all removed by @samp{make distclean}.
2816 Their inputs are automatically distributed, unless they
2817 are the output of prior @code{AC_CONFIG_FILES} commands.
2818 Finally, rebuild rules are generated in the Automake @file{Makefile}
2819 existing in the subdirectory of the output file, if there is one, or
2820 in the top-level @file{Makefile} otherwise.
2822 The above machinery (cleaning, distributing, and rebuilding) works
2823 fine if the @code{AC_CONFIG_FILES} specifications contain only
2824 literals. If part of the specification uses shell variables,
2825 @command{automake} will not be able to fulfill this setup, and you will
2826 have to complete the missing bits by hand. For instance, on
2828 @c Keep in sync with output11.test.
2832 AC_CONFIG_FILES([output:$file],, [file=$file])
2836 @command{automake} will output rules to clean @file{output}, and
2837 rebuild it. However the rebuild rule will not depend on @file{input},
2838 and this file will not be distributed either. (You must add
2839 @samp{EXTRA_DIST = input} to your @file{Makefile.am} if @file{input} is a
2844 @c Keep in sync with output11.test.
2849 AC_CONFIG_FILES([$file:input],, [file=$file])
2850 AC_CONFIG_FILES([$file2],, [file2=$file2])
2854 will only cause @file{input} to be distributed. No file will be
2855 cleaned automatically (add @samp{DISTCLEANFILES = output out}
2856 yourself), and no rebuild rule will be output.
2858 Obviously @command{automake} cannot guess what value @samp{$file} is
2859 going to hold later when @file{configure} is run, and it cannot use
2860 the shell variable @samp{$file} in a @file{Makefile}. However, if you
2861 make reference to @samp{$file} as @samp{$@{file@}} (i.e., in a way
2862 that is compatible with @command{make}'s syntax) and furthermore use
2863 @code{AC_SUBST} to ensure that @samp{$@{file@}} is meaningful in a
2864 @file{Makefile}, then @command{automake} will be able to use
2865 @samp{$@{file@}} to generate all these rules. For instance, here is
2866 how the Automake package itself generates versioned scripts for its
2870 AC_SUBST([APIVERSION], @dots{})
2873 [tests/aclocal-$@{APIVERSION@}:tests/aclocal.in],
2874 [chmod +x tests/aclocal-$@{APIVERSION@}],
2875 [APIVERSION=$APIVERSION])
2877 [tests/automake-$@{APIVERSION@}:tests/automake.in],
2878 [chmod +x tests/automake-$@{APIVERSION@}])
2882 Here cleaning, distributing, and rebuilding are done automatically,
2883 because @samp{$@{APIVERSION@}} is known at @command{make}-time.
2885 Note that you should not use shell variables to declare
2886 @file{Makefile} files for which @command{automake} must create
2887 @file{Makefile.in}. Even @code{AC_SUBST} does not help here, because
2888 @command{automake} needs to know the file name when it runs in order
2889 to check whether @file{Makefile.am} exists. (In the very hairy case
2890 that your setup requires such use of variables, you will have to tell
2891 Automake which @file{Makefile.in}s to generate on the command-line.)
2893 It is possible to let @command{automake} emit conditional rules for
2894 @code{AC_CONFIG_FILES} with the help of @code{AM_COND_IF}
2900 Use literals for @file{Makefile}s, and for other files whenever possible.
2902 Use @samp{$file} (or @samp{$@{file@}} without @samp{AC_SUBST([file])})
2903 for files that @command{automake} should ignore.
2905 Use @samp{$@{file@}} and @samp{AC_SUBST([file])} for files
2906 that @command{automake} should not ignore.
2913 @section Other things Automake recognizes
2915 @cindex Macros Automake recognizes
2916 @cindex Recognized macros by Automake
2918 Every time Automake is run it calls Autoconf to trace
2919 @file{configure.ac}. This way it can recognize the use of certain
2920 macros and tailor the generated @file{Makefile.in} appropriately.
2921 Currently recognized macros and their effects are:
2924 @item AC_CANONICAL_BUILD
2925 @itemx AC_CANONICAL_HOST
2926 @itemx AC_CANONICAL_TARGET
2927 @vindex build_triplet
2928 @vindex host_triplet
2929 @vindex target_triplet
2930 Automake will ensure that @file{config.guess} and @file{config.sub}
2931 exist. Also, the @file{Makefile} variables @code{build_triplet},
2932 @code{host_triplet} and @code{target_triplet} are introduced. See
2933 @ref{Canonicalizing, , Getting the Canonical System Type, autoconf,
2934 The Autoconf Manual}.
2936 @item AC_CONFIG_AUX_DIR
2937 Automake will look for various helper scripts, such as
2938 @file{install-sh}, in the directory named in this macro invocation.
2939 @c This list is accurate relative to version 1.11
2940 (The full list of scripts is:
2942 @file{config.guess},
2951 @file{mkinstalldirs},
2956 Not all scripts are always searched for; some scripts
2957 will only be sought if the generated @file{Makefile.in} requires them.
2959 If @code{AC_CONFIG_AUX_DIR} is not given, the scripts are looked for in
2960 their standard locations. For @file{mdate-sh},
2961 @file{texinfo.tex}, and @file{ylwrap}, the standard location is the
2962 source directory corresponding to the current @file{Makefile.am}. For
2963 the rest, the standard location is the first one of @file{.}, @file{..},
2964 or @file{../..} (relative to the top source directory) that provides any
2965 one of the helper scripts. @xref{Input, , Finding `configure' Input,
2966 autoconf, The Autoconf Manual}.
2968 Required files from @code{AC_CONFIG_AUX_DIR} are automatically
2969 distributed, even if there is no @file{Makefile.am} in this directory.
2971 @item AC_CONFIG_LIBOBJ_DIR
2972 Automake will require the sources file declared with
2973 @code{AC_LIBSOURCE} (see below) in the directory specified by this
2976 @item AC_CONFIG_HEADERS
2977 Automake will generate rules to rebuild these headers. Older versions
2978 of Automake required the use of @code{AM_CONFIG_HEADER}
2979 (@pxref{Macros}); this is no longer the case.
2981 As with @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the
2982 specification using shell variables will be ignored as far as
2983 cleaning, distributing, and rebuilding is concerned.
2985 @item AC_CONFIG_LINKS
2986 Automake will generate rules to remove @file{configure} generated
2987 links on @samp{make distclean} and to distribute named source files as
2988 part of @samp{make dist}.
2990 As for @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the
2991 specification using shell variables will be ignored as far as cleaning
2992 and distributing is concerned. (There are no rebuild rules for links.)
2996 @itemx AC_LIBSOURCES
2998 Automake will automatically distribute any file listed in
2999 @code{AC_LIBSOURCE} or @code{AC_LIBSOURCES}.
3001 Note that the @code{AC_LIBOBJ} macro calls @code{AC_LIBSOURCE}. So if
3002 an Autoconf macro is documented to call @samp{AC_LIBOBJ([file])}, then
3003 @file{file.c} will be distributed automatically by Automake. This
3004 encompasses many macros like @code{AC_FUNC_ALLOCA},
3005 @code{AC_FUNC_MEMCMP}, @code{AC_REPLACE_FUNCS}, and others.
3007 By the way, direct assignments to @code{LIBOBJS} are no longer
3008 supported. You should always use @code{AC_LIBOBJ} for this purpose.
3009 @xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs.@: @code{LIBOBJS},
3010 autoconf, The Autoconf Manual}.
3012 @item AC_PROG_RANLIB
3013 This is required if any libraries are built in the package.
3014 @xref{Particular Programs, , Particular Program Checks, autoconf, The
3018 This is required if any C++ source is included. @xref{Particular
3019 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
3022 This is required if any Objective C source is included. @xref{Particular
3023 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
3026 This is required if any Fortran 77 source is included. This macro is
3027 distributed with Autoconf version 2.13 and later. @xref{Particular
3028 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
3030 @item AC_F77_LIBRARY_LDFLAGS
3031 This is required for programs and shared libraries that are a mixture of
3032 languages that include Fortran 77 (@pxref{Mixing Fortran 77 With C and
3033 C++}). @xref{Macros, , Autoconf macros supplied with Automake}.
3036 Automake will add the flags computed by @code{AC_FC_SRCEXT} to compilation
3037 of files with the respective source extension (@pxref{Fortran Compiler, ,
3038 Fortran Compiler Characteristics, autoconf, The Autoconf Manual}).
3041 This is required if any Fortran 90/95 source is included. This macro is
3042 distributed with Autoconf version 2.58 and later. @xref{Particular
3043 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
3045 @item AC_PROG_LIBTOOL
3046 Automake will turn on processing for @command{libtool} (@pxref{Top, ,
3047 Introduction, libtool, The Libtool Manual}).
3051 If a Yacc source file is seen, then you must either use this macro or
3052 define the variable @code{YACC} in @file{configure.ac}. The former is
3053 preferred (@pxref{Particular Programs, , Particular Program Checks,
3054 autoconf, The Autoconf Manual}).
3057 If a Lex source file is seen, then this macro must be used.
3058 @xref{Particular Programs, , Particular Program Checks, autoconf, The
3061 @item AC_REQUIRE_AUX_FILE
3062 For each @code{AC_REQUIRE_AUX_FILE([@var{file}])},
3063 @command{automake} will ensure that @file{@var{file}} exists in the
3064 aux directory, and will complain otherwise. It
3065 will also automatically distribute the file. This macro should be
3066 used by third-party Autoconf macros that require some supporting
3067 files in the aux directory specified with @code{AC_CONFIG_AUX_DIR}
3068 above. @xref{Input, , Finding @command{configure} Input, autoconf,
3069 The Autoconf Manual}.
3072 The first argument is automatically defined as a variable in each
3073 generated @file{Makefile.in}, unless @code{AM_SUBST_NOTMAKE} is also
3074 used for this variable. @xref{Setting Output Variables, , Setting
3075 Output Variables, autoconf, The Autoconf Manual}.
3077 For every substituted variable @var{var}, @command{automake} will add
3078 a line @code{@var{var} = @var{value}} to each @file{Makefile.in} file.
3079 Many Autoconf macros invoke @code{AC_SUBST} to set output variables
3080 this way, e.g., @code{AC_PATH_XTRA} defines @code{X_CFLAGS} and
3081 @code{X_LIBS}. Thus, you can access these variables as
3082 @code{$(X_CFLAGS)} and @code{$(X_LIBS)} in any @file{Makefile.am}
3083 if @code{AC_PATH_XTRA} is called.
3085 @item AM_CONDITIONAL
3086 This introduces an Automake conditional (@pxref{Conditionals}).
3089 This macro allows @code{automake} to detect subsequent access within
3090 @file{configure.ac} to a conditional previously introduced with
3091 @code{AM_CONDITIONAL}, thus enabling conditional @code{AC_CONFIG_FILES}
3092 (@pxref{Usage of Conditionals}).
3094 @item AM_GNU_GETTEXT
3095 This macro is required for packages that use GNU gettext
3096 (@pxref{gettext}). It is distributed with gettext. If Automake sees
3097 this macro it ensures that the package meets some of gettext's
3100 @item AM_GNU_GETTEXT_INTL_SUBDIR
3101 This macro specifies that the @file{intl/} subdirectory is to be built,
3102 even if the @code{AM_GNU_GETTEXT} macro was invoked with a first argument
3105 @item AM_MAINTAINER_MODE(@ovar{default-mode})
3106 @opindex --enable-maintainer-mode
3107 @opindex --disable-maintainer-mode
3108 This macro adds an @option{--enable-maintainer-mode} option to
3109 @command{configure}. If this is used, @command{automake} will cause
3110 ``maintainer-only'' rules to be turned off by default in the
3111 generated @file{Makefile.in}s, unless @var{default-mode} is
3112 @samp{enable}. This macro defines the @code{MAINTAINER_MODE}
3113 conditional, which you can use in your own @file{Makefile.am}.
3114 @xref{maintainer-mode}.
3116 @item AM_SUBST_NOTMAKE(@var{var})
3117 Prevent Automake from defining a variable @var{var}, even if it is
3118 substituted by @command{config.status}. Normally, Automake defines a
3119 @command{make} variable for each @command{configure} substitution,
3120 i.e., for each @code{AC_SUBST([@var{var}])}. This macro prevents that
3121 definition from Automake. If @code{AC_SUBST} has not been called
3122 for this variable, then @code{AM_SUBST_NOTMAKE} has no effects.
3123 Preventing variable definitions may be useful for substitution of
3124 multi-line values, where @code{@var{var} = @@@var{value}@@} might yield
3128 Files included by @file{configure.ac} using this macro will be
3129 detected by Automake and automatically distributed. They will also
3130 appear as dependencies in @file{Makefile} rules.
3132 @code{m4_include} is seldom used by @file{configure.ac} authors, but
3133 can appear in @file{aclocal.m4} when @command{aclocal} detects that
3134 some required macros come from files local to your package (as opposed to
3135 macros installed in a system-wide directory, @pxref{aclocal Invocation}).
3139 @node aclocal Invocation
3140 @section Auto-generating aclocal.m4
3141 @c This node used to be named "Invoking automake". This @anchor
3142 @c allows old links to still work.
3143 @anchor{Invoking aclocal}
3145 @cindex Invocation of @command{aclocal}
3146 @cindex @command{aclocal}, Invocation
3147 @cindex Invoking @command{aclocal}
3148 @cindex @command{aclocal}, Invoking
3150 Automake includes a number of Autoconf macros that can be used in
3151 your package (@pxref{Macros}); some of them are actually required by
3152 Automake in certain situations. These macros must be defined in your
3153 @file{aclocal.m4}; otherwise they will not be seen by
3156 The @command{aclocal} program will automatically generate
3157 @file{aclocal.m4} files based on the contents of @file{configure.ac}.
3158 This provides a convenient way to get Automake-provided macros,
3159 without having to search around. The @command{aclocal} mechanism
3160 allows other packages to supply their own macros (@pxref{Extending
3161 aclocal}). You can also use it to maintain your own set of custom
3162 macros (@pxref{Local Macros}).
3164 At startup, @command{aclocal} scans all the @file{.m4} files it can
3165 find, looking for macro definitions (@pxref{Macro Search Path}). Then
3166 it scans @file{configure.ac}. Any mention of one of the macros found
3167 in the first step causes that macro, and any macros it in turn
3168 requires, to be put into @file{aclocal.m4}.
3170 @emph{Putting} the file that contains the macro definition into
3171 @file{aclocal.m4} is usually done by copying the entire text of this
3172 file, including unused macro definitions as well as both @samp{#} and
3173 @samp{dnl} comments. If you want to make a comment that will be
3174 completely ignored by @command{aclocal}, use @samp{##} as the comment
3177 When a file selected by @command{aclocal} is located in a subdirectory
3178 specified as a relative search path with @command{aclocal}'s @option{-I}
3179 argument, @command{aclocal} assumes the file belongs to the package
3180 and uses @code{m4_include} instead of copying it into
3181 @file{aclocal.m4}. This makes the package smaller, eases dependency
3182 tracking, and cause the file to be distributed automatically.
3183 (@xref{Local Macros}, for an example.) Any macro that is found in a
3184 system-wide directory, or via an absolute search path will be copied.
3185 So use @samp{-I `pwd`/reldir} instead of @samp{-I reldir} whenever
3186 some relative directory should be considered outside the package.
3188 The contents of @file{acinclude.m4}, if this file exists, are also
3189 automatically included in @file{aclocal.m4}. We recommend against
3190 using @file{acinclude.m4} in new packages (@pxref{Local Macros}).
3194 While computing @file{aclocal.m4}, @command{aclocal} runs
3195 @command{autom4te} (@pxref{Using autom4te, , Using @command{Autom4te},
3196 autoconf, The Autoconf Manual}) in order to trace the macros that are
3197 really used, and omit from @file{aclocal.m4} all macros that are
3198 mentioned but otherwise unexpanded (this can happen when a macro is
3199 called conditionally). @command{autom4te} is expected to be in the
3200 @env{PATH}, just as @command{autoconf}. Its location can be
3201 overridden using the @env{AUTOM4TE} environment variable.
3204 * aclocal Options:: Options supported by aclocal
3205 * Macro Search Path:: How aclocal finds .m4 files
3206 * Extending aclocal:: Writing your own aclocal macros
3207 * Local Macros:: Organizing local macros
3208 * Serials:: Serial lines in Autoconf macros
3209 * Future of aclocal:: aclocal's scheduled death
3212 @node aclocal Options
3213 @subsection aclocal Options
3215 @cindex @command{aclocal}, Options
3216 @cindex Options, @command{aclocal}
3218 @command{aclocal} accepts the following options:
3221 @item --automake-acdir=@var{dir}
3222 @opindex --automake-acdir
3223 Look for the automake-provided macro files in @var{dir} instead of
3224 in the installation directory. This is typically used for debugging.
3226 @item --system-acdir=@var{dir}
3227 @opindex --system-acdir
3228 Look for the system-wide third-party macro files (and the special
3229 @file{dirlist} file) in @var{dir} instead of in the installation
3230 directory. This is typically used for debugging.
3232 @item --diff[=@var{command}]
3234 Run @var{command} on M4 file that would be installed or overwritten
3235 by @option{--install}. The default @var{command} is @samp{diff -u}.
3236 This option implies @option{--install} and @option{--dry-run}.
3240 Do not actually overwrite (or create) @file{aclocal.m4} and M4
3241 files installed by @option{--install}.
3245 Print a summary of the command line options and exit.
3249 Add the directory @var{dir} to the list of directories searched for
3254 Install system-wide third-party macros into the first directory
3255 specified with @samp{-I @var{dir}} instead of copying them in the
3257 @c The following semantics is checked by `aclocal-install-absdir.test'.
3258 Note that this will happen also if @var{dir} is an absolute path.
3260 @cindex serial number and @option{--install}
3261 When this option is used, and only when this option is used,
3262 @command{aclocal} will also honor @samp{#serial @var{number}} lines
3263 that appear in macros: an M4 file is ignored if there exists another
3264 M4 file with the same basename and a greater serial number in the
3265 search path (@pxref{Serials}).
3269 Always overwrite the output file. The default is to overwrite the output
3270 file only when really needed, i.e., when its contents changes or if one
3271 of its dependencies is younger.
3273 This option forces the update of @file{aclocal.m4} (or the file
3274 specified with @file{--output} below) and only this file, it has
3275 absolutely no influence on files that may need to be installed by
3278 @item --output=@var{file}
3280 Cause the output to be put into @var{file} instead of @file{aclocal.m4}.
3282 @item --print-ac-dir
3283 @opindex --print-ac-dir
3284 Prints the name of the directory that @command{aclocal} will search to
3285 find third-party @file{.m4} files. When this option is given, normal
3286 processing is suppressed. This option was used @emph{in the past} by
3287 third-party packages to determine where to install @file{.m4} macro
3288 files, but @emph{this usage is today discouraged}, since it causes
3289 @samp{$(prefix)} not to be thoroughly honoured (which violates the
3290 GNU Coding Standards), and a similar semantics can be better obtained
3291 with the @env{ACLOCAL_PATH} environment variable; @pxref{Extending aclocal}.
3295 Print the names of the files it examines.
3299 Print the version number of Automake and exit.
3302 @item --warnings=@var{category}
3305 Output warnings falling in @var{category}. @var{category} can be
3309 dubious syntactic constructs, underquoted macros, unused macros, etc.
3313 all the warnings, this is the default
3315 turn off all the warnings
3317 treat warnings as errors
3320 All warnings are output by default.
3323 The environment variable @env{WARNINGS} is honored in the same
3324 way as it is for @command{automake} (@pxref{automake Invocation}).
3328 @node Macro Search Path
3329 @subsection Macro Search Path
3331 @cindex Macro search path
3332 @cindex @command{aclocal} search path
3334 By default, @command{aclocal} searches for @file{.m4} files in the following
3335 directories, in this order:
3338 @item @var{acdir-APIVERSION}
3339 This is where the @file{.m4} macros distributed with Automake itself
3340 are stored. @var{APIVERSION} depends on the Automake release used;
3341 for example, for Automake 1.11.x, @var{APIVERSION} = @code{1.11}.
3344 This directory is intended for third party @file{.m4} files, and is
3345 configured when @command{automake} itself is built. This is
3346 @file{@@datadir@@/aclocal/}, which typically
3347 expands to @file{$@{prefix@}/share/aclocal/}. To find the compiled-in
3348 value of @var{acdir}, use the @option{--print-ac-dir} option
3349 (@pxref{aclocal Options}).
3352 As an example, suppose that @command{automake-1.11.2} was configured with
3353 @option{--prefix=@-/usr/local}. Then, the search path would be:
3356 @item @file{/usr/local/share/aclocal-1.11.2/}
3357 @item @file{/usr/local/share/aclocal/}
3360 The paths for the @var{acdir} and @var{acdir-APIVERSION} directories can
3361 be changed respectively through aclocal options @option{--system-acdir}
3362 and @option{--automake-acdir} (@pxref{aclocal Options}). Note however
3363 that these options are only intended for use by the internal Automake
3364 test suite, or for debugging under highly unusual situations; they are
3365 not ordinarily needed by end-users.
3367 As explained in (@pxref{aclocal Options}), there are several options that
3368 can be used to change or extend this search path.
3370 @subsubheading Modifying the Macro Search Path: @samp{-I @var{dir}}
3372 Any extra directories specified using @option{-I} options
3373 (@pxref{aclocal Options}) are @emph{prepended} to this search list. Thus,
3374 @samp{aclocal -I /foo -I /bar} results in the following search path:
3379 @item @var{acdir}-@var{APIVERSION}
3383 @subsubheading Modifying the Macro Search Path: @file{dirlist}
3384 @cindex @file{dirlist}
3386 There is a third mechanism for customizing the search path. If a
3387 @file{dirlist} file exists in @var{acdir}, then that file is assumed to
3388 contain a list of directory patterns, one per line. @command{aclocal}
3389 expands these patterns to directory names, and adds them to the search
3390 list @emph{after} all other directories. @file{dirlist} entries may
3391 use shell wildcards such as @samp{*}, @samp{?}, or @code{[...]}.
3393 For example, suppose
3394 @file{@var{acdir}/dirlist} contains the following:
3403 and that @command{aclocal} was called with the @samp{-I /foo -I /bar} options.
3404 Then, the search path would be
3406 @c @code looks better than @file here
3410 @item @var{acdir}-@var{APIVERSION}
3417 and all directories with path names starting with @code{/test3}.
3419 If the @option{--system-acdir=@var{dir}} option is used, then
3420 @command{aclocal} will search for the @file{dirlist} file in
3421 @var{dir}; but remember the warnings above against the use of
3422 @option{--system-acdir}.
3424 @file{dirlist} is useful in the following situation: suppose that
3425 @command{automake} version @code{1.11.2} is installed with
3426 @samp{--prefix=/usr} by the system vendor. Thus, the default search
3429 @c @code looks better than @file here
3431 @item @code{/usr/share/aclocal-1.11/}
3432 @item @code{/usr/share/aclocal/}
3435 However, suppose further that many packages have been manually
3436 installed on the system, with $prefix=/usr/local, as is typical. In
3437 that case, many of these ``extra'' @file{.m4} files are in
3438 @file{/usr/local/share/aclocal}. The only way to force
3439 @file{/usr/bin/aclocal} to find these ``extra'' @file{.m4} files is to
3440 always call @samp{aclocal -I /usr/local/share/aclocal}. This is
3441 inconvenient. With @file{dirlist}, one may create a file
3442 @file{/usr/share/aclocal/dirlist} containing only the single line
3445 /usr/local/share/aclocal
3448 Now, the ``default'' search path on the affected system is
3450 @c @code looks better than @file here
3452 @item @code{/usr/share/aclocal-1.11/}
3453 @item @code{/usr/share/aclocal/}
3454 @item @code{/usr/local/share/aclocal/}
3457 without the need for @option{-I} options; @option{-I} options can be reserved
3458 for project-specific needs (@file{my-source-dir/m4/}), rather than
3459 using it to work around local system-dependent tool installation
3462 Similarly, @file{dirlist} can be handy if you have installed a local
3463 copy of Automake in your account and want @command{aclocal} to look for
3464 macros installed at other places on the system.
3466 @anchor{ACLOCAL_PATH}
3467 @subsubheading Modifying the Macro Search Path: @file{ACLOCAL_PATH}
3468 @cindex @env{ACLOCAL_PATH}
3470 The fourth and last mechanism to customize the macro search path is
3471 also the simplest. Any directory included in the colon-separated
3472 environment variable @env{ACLOCAL_PATH} is added to the search path
3473 @c Keep in sync with aclocal-path-precedence.test.
3474 and takes precedence over system directories (including those found via
3475 @file{dirlist}), with the exception of the versioned directory
3476 @var{acdir-APIVERSION} (@pxref{Macro Search Path}). However, directories
3477 passed via @option{-I} will take precedence over directories in
3480 @c Keep in sync with aclocal-path-installed.test.
3481 Also note that, if the @option{--install} option is used, any @file{.m4}
3482 file containing a required macro that is found in a directory listed in
3483 @env{ACLOCAL_PATH} will be installed locally.
3484 @c Keep in sync with aclocal-path-installed-serial.test.
3485 In this case, serial numbers in @file{.m4} are honoured too,
3488 Conversely to @file{dirlist}, @env{ACLOCAL_PATH} is useful if you are
3489 using a global copy of Automake and want @command{aclocal} to look for
3490 macros somewhere under your home directory.
3492 @subsubheading Planned future incompatibilities
3494 The order in which the directories in the macro search path are currently
3495 looked up is confusing and/or suboptimal in various aspects, and is
3496 probably going to be changed in the future Automake release. In
3497 particular, directories in @env{ACLOCAL_PATH} and @file{@var{acdir}}
3498 might end up taking precedence over @file{@var{acdir-APIVERSION}}, and
3499 directories in @file{@var{acdir}/dirlist} might end up taking precedence
3500 over @file{@var{acdir}}. @emph{This is a possible future incompatibility!}
3502 @node Extending aclocal
3503 @subsection Writing your own aclocal macros
3505 @cindex @command{aclocal}, extending
3506 @cindex Extending @command{aclocal}
3508 The @command{aclocal} program doesn't have any built-in knowledge of any
3509 macros, so it is easy to extend it with your own macros.
3511 This can be used by libraries that want to supply their own Autoconf
3512 macros for use by other programs. For instance, the @command{gettext}
3513 library supplies a macro @code{AM_GNU_GETTEXT} that should be used by
3514 any package using @command{gettext}. When the library is installed, it
3515 installs this macro so that @command{aclocal} will find it.
3517 A macro file's name should end in @file{.m4}. Such files should be
3518 installed in @file{$(datadir)/aclocal}. This is as simple as writing:
3520 @c Keep in sync with primary-prefix-couples-documented-valid.test.
3522 aclocaldir = $(datadir)/aclocal
3523 aclocal_DATA = mymacro.m4 myothermacro.m4
3527 Please do use @file{$(datadir)/aclocal}, and not something based on
3528 the result of @samp{aclocal --print-ac-dir} (@pxref{Hard-Coded Install
3529 Paths}, for arguments). It might also be helpful to suggest to
3530 the user to add the @file{$(datadir)/aclocal} directory to his
3531 @env{ACLOCAL_PATH} variable (@pxref{ACLOCAL_PATH}) so that
3532 @command{aclocal} will find the @file{.m4} files installed by your
3533 package automatically.
3535 A file of macros should be a series of properly quoted
3536 @code{AC_DEFUN}'s (@pxref{Macro Definitions, , , autoconf, The
3537 Autoconf Manual}). The @command{aclocal} programs also understands
3538 @code{AC_REQUIRE} (@pxref{Prerequisite Macros, , , autoconf, The
3539 Autoconf Manual}), so it is safe to put each macro in a separate file.
3540 Each file should have no side effects but macro definitions.
3541 Especially, any call to @code{AC_PREREQ} should be done inside the
3542 defined macro, not at the beginning of the file.
3544 @cindex underquoted @code{AC_DEFUN}
3548 Starting with Automake 1.8, @command{aclocal} will warn about all
3549 underquoted calls to @code{AC_DEFUN}. We realize this will annoy a
3550 lot of people, because @command{aclocal} was not so strict in the past
3551 and many third party macros are underquoted; and we have to apologize
3552 for this temporary inconvenience. The reason we have to be stricter
3553 is that a future implementation of @command{aclocal} (@pxref{Future of
3554 aclocal}) will have to temporarily include all these third party
3555 @file{.m4} files, maybe several times, including even files that are
3556 not actually needed. Doing so should alleviate many problems of the
3557 current implementation, however it requires a stricter style from the
3558 macro authors. Hopefully it is easy to revise the existing macros.
3565 [AC_REQUIRE([AX_SOMETHING])dnl
3572 should be rewritten as
3575 AC_DEFUN([AX_FOOBAR],
3576 [AC_PREREQ([2.57])dnl
3577 AC_REQUIRE([AX_SOMETHING])dnl
3583 Wrapping the @code{AC_PREREQ} call inside the macro ensures that
3584 Autoconf 2.57 will not be required if @code{AX_FOOBAR} is not actually
3585 used. Most importantly, quoting the first argument of @code{AC_DEFUN}
3586 allows the macro to be redefined or included twice (otherwise this
3587 first argument would be expanded during the second definition). For
3588 consistency we like to quote even arguments such as @code{2.57} that
3591 If you have been directed here by the @command{aclocal} diagnostic but
3592 are not the maintainer of the implicated macro, you will want to
3593 contact the maintainer of that macro. Please make sure you have the
3594 latest version of the macro and that the problem hasn't already been
3595 reported before doing so: people tend to work faster when they aren't
3598 Another situation where @command{aclocal} is commonly used is to
3599 manage macros that are used locally by the package, @ref{Local
3603 @subsection Handling Local Macros
3605 Feature tests offered by Autoconf do not cover all needs. People
3606 often have to supplement existing tests with their own macros, or
3607 with third-party macros.
3609 There are two ways to organize custom macros in a package.
3611 The first possibility (the historical practice) is to list all your
3612 macros in @file{acinclude.m4}. This file will be included in
3613 @file{aclocal.m4} when you run @command{aclocal}, and its macro(s) will
3614 henceforth be visible to @command{autoconf}. However if it contains
3615 numerous macros, it will rapidly become difficult to maintain, and it
3616 will be almost impossible to share macros between packages.
3618 @vindex ACLOCAL_AMFLAGS
3619 The second possibility, which we do recommend, is to write each macro
3620 in its own file and gather all these files in a directory. This
3621 directory is usually called @file{m4/}. To build @file{aclocal.m4},
3622 one should therefore instruct @command{aclocal} to scan @file{m4/}.
3623 From the command line, this is done with @samp{aclocal -I m4}. The
3624 top-level @file{Makefile.am} should also be updated to define
3627 ACLOCAL_AMFLAGS = -I m4
3630 @code{ACLOCAL_AMFLAGS} contains options to pass to @command{aclocal}
3631 when @file{aclocal.m4} is to be rebuilt by @command{make}. This line is
3632 also used by @command{autoreconf} (@pxref{autoreconf Invocation, ,
3633 Using @command{autoreconf} to Update @file{configure} Scripts,
3634 autoconf, The Autoconf Manual}) to run @command{aclocal} with suitable
3635 options, or by @command{autopoint} (@pxref{autopoint Invocation, ,
3636 Invoking the @command{autopoint} Program, gettext, GNU gettext tools})
3637 and @command{gettextize} (@pxref{gettextize Invocation, , Invoking the
3638 @command{gettextize} Program, gettext, GNU gettext tools}) to locate
3639 the place where Gettext's macros should be installed. So even if you
3640 do not really care about the rebuild rules, you should define
3641 @code{ACLOCAL_AMFLAGS}.
3643 When @samp{aclocal -I m4} is run, it will build an @file{aclocal.m4}
3644 that @code{m4_include}s any file from @file{m4/} that defines a
3645 required macro. Macros not found locally will still be searched in
3646 system-wide directories, as explained in @ref{Macro Search Path}.
3648 Custom macros should be distributed for the same reason that
3649 @file{configure.ac} is: so that other people have all the sources of
3650 your package if they want to work on it. Actually, this distribution
3651 happens automatically because all @code{m4_include}d files are
3654 However there is no consensus on the distribution of third-party
3655 macros that your package may use. Many libraries install their own
3656 macro in the system-wide @command{aclocal} directory (@pxref{Extending
3657 aclocal}). For instance, Guile ships with a file called
3658 @file{guile.m4} that contains the macro @code{GUILE_FLAGS} that can
3659 be used to define setup compiler and linker flags appropriate for
3660 using Guile. Using @code{GUILE_FLAGS} in @file{configure.ac} will
3661 cause @command{aclocal} to copy @file{guile.m4} into
3662 @file{aclocal.m4}, but as @file{guile.m4} is not part of the project,
3663 it will not be distributed. Technically, that means a user who
3664 needs to rebuild @file{aclocal.m4} will have to install Guile first.
3665 This is probably OK, if Guile already is a requirement to build the
3666 package. However, if Guile is only an optional feature, or if your
3667 package might run on architectures where Guile cannot be installed,
3668 this requirement will hinder development. An easy solution is to copy
3669 such third-party macros in your local @file{m4/} directory so they get
3672 Since Automake 1.10, @command{aclocal} offers an option to copy these
3673 system-wide third-party macros in your local macro directory, solving
3674 the above problem. Simply use:
3677 ACLOCAL_AMFLAGS = -I m4 --install
3681 With this setup, system-wide macros will be copied to @file{m4/}
3682 the first time you run @command{autoreconf}. Then the locally
3683 installed macros will have precedence over the system-wide installed
3684 macros each time @command{aclocal} is run again.
3686 One reason why you should keep @option{--install} in the flags even
3687 after the first run is that when you later edit @file{configure.ac}
3688 and depend on a new macro, this macro will be installed in your
3689 @file{m4/} automatically. Another one is that serial numbers
3690 (@pxref{Serials}) can be used to update the macros in your source tree
3691 automatically when new system-wide versions are installed. A serial
3692 number should be a single line of the form
3699 where @var{nnn} contains only digits and dots. It should appear in
3700 the M4 file before any macro definition. It is a good practice to
3701 maintain a serial number for each macro you distribute, even if you do
3702 not use the @option{--install} option of @command{aclocal}: this allows
3703 other people to use it.
3707 @subsection Serial Numbers
3708 @cindex serial numbers in macros
3709 @cindex macro serial numbers
3710 @cindex @code{#serial} syntax
3711 @cindex @command{aclocal} and serial numbers
3713 Because third-party macros defined in @file{*.m4} files are naturally
3714 shared between multiple projects, some people like to version them.
3715 This makes it easier to tell which of two M4 files is newer. Since at
3716 least 1996, the tradition is to use a @samp{#serial} line for this.
3718 A serial number should be a single line of the form
3721 # serial @var{version}
3725 where @var{version} is a version number containing only digits and
3726 dots. Usually people use a single integer, and they increment it each
3727 time they change the macro (hence the name of ``serial''). Such a
3728 line should appear in the M4 file before any macro definition.
3730 The @samp{#} must be the first character on the line,
3731 and it is OK to have extra words after the version, as in
3734 #serial @var{version} @var{garbage}
3737 Normally these serial numbers are completely ignored by
3738 @command{aclocal} and @command{autoconf}, like any genuine comment.
3739 However when using @command{aclocal}'s @option{--install} feature, these
3740 serial numbers will modify the way @command{aclocal} selects the
3741 macros to install in the package: if two files with the same basename
3742 exist in your search path, and if at least one of them uses a
3743 @samp{#serial} line, @command{aclocal} will ignore the file that has
3744 the older @samp{#serial} line (or the file that has none).
3746 Note that a serial number applies to a whole M4 file, not to any macro
3747 it contains. A file can contains multiple macros, but only one
3750 Here is a use case that illustrates the use of @option{--install} and
3751 its interaction with serial numbers. Let's assume we maintain a
3752 package called MyPackage, the @file{configure.ac} of which requires a
3753 third-party macro @code{AX_THIRD_PARTY} defined in
3754 @file{/usr/share/aclocal/thirdparty.m4} as follows:
3758 AC_DEFUN([AX_THIRD_PARTY], [...])
3761 MyPackage uses an @file{m4/} directory to store local macros as
3762 explained in @ref{Local Macros}, and has
3765 ACLOCAL_AMFLAGS = -I m4 --install
3769 in its top-level @file{Makefile.am}.
3771 Initially the @file{m4/} directory is empty. The first time we run
3772 @command{autoreconf}, it will fetch the options to pass to
3773 @command{aclocal} in @file{Makefile.am}, and run @samp{aclocal -I m4
3774 --install}. @command{aclocal} will notice that
3778 @file{configure.ac} uses @code{AX_THIRD_PARTY}
3780 No local macros define @code{AX_THIRD_PARTY}
3782 @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3787 Because @file{/usr/share/aclocal/thirdparty.m4} is a system-wide macro
3788 and @command{aclocal} was given the @option{--install} option, it will
3789 copy this file in @file{m4/thirdparty.m4}, and output an
3790 @file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}.
3792 The next time @samp{aclocal -I m4 --install} is run (either via
3793 @command{autoreconf}, by hand, or from the @file{Makefile} rebuild
3794 rules) something different happens. @command{aclocal} notices that
3798 @file{configure.ac} uses @code{AX_THIRD_PARTY}
3800 @file{m4/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3803 @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3808 Because both files have the same serial number, @command{aclocal} uses
3809 the first it found in its search path order (@pxref{Macro Search
3810 Path}). @command{aclocal} therefore ignores
3811 @file{/usr/share/aclocal/thirdparty.m4} and outputs an
3812 @file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}.
3814 Local directories specified with @option{-I} are always searched before
3815 system-wide directories, so a local file will always be preferred to
3816 the system-wide file in case of equal serial numbers.
3818 Now suppose the system-wide third-party macro is changed. This can
3819 happen if the package installing this macro is updated. Let's suppose
3820 the new macro has serial number 2. The next time @samp{aclocal -I m4
3821 --install} is run the situation is the following:
3825 @file{configure.ac} uses @code{AX_THIRD_PARTY}
3827 @file{m4/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3830 @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3835 When @command{aclocal} sees a greater serial number, it immediately
3836 forgets anything it knows from files that have the same basename and a
3837 smaller serial number. So after it has found
3838 @file{/usr/share/aclocal/thirdparty.m4} with serial 2,
3839 @command{aclocal} will proceed as if it had never seen
3840 @file{m4/thirdparty.m4}. This brings us back to a situation similar
3841 to that at the beginning of our example, where no local file defined
3842 the macro. @command{aclocal} will install the new version of the
3843 macro in @file{m4/thirdparty.m4}, in this case overriding the old
3844 version. MyPackage just had its macro updated as a side effect of
3845 running @command{aclocal}.
3847 If you are leery of letting @command{aclocal} update your local macro,
3848 you can run @samp{aclocal -I m4 --diff} to review the changes
3849 @samp{aclocal -I m4 --install} would perform on these macros.
3851 Finally, note that the @option{--force} option of @command{aclocal} has
3852 absolutely no effect on the files installed by @option{--install}. For
3853 instance, if you have modified your local macros, do not expect
3854 @option{--install --force} to replace the local macros by their
3855 system-wide versions. If you want to do so, simply erase the local
3856 macros you want to revert, and run @samp{aclocal -I m4 --install}.
3859 @node Future of aclocal
3860 @subsection The Future of @command{aclocal}
3861 @cindex @command{aclocal}'s scheduled death
3863 @command{aclocal} is expected to disappear. This feature really
3864 should not be offered by Automake. Automake should focus on
3865 generating @file{Makefile}s; dealing with M4 macros really is
3866 Autoconf's job. The fact that some people install Automake just to use
3867 @command{aclocal}, but do not use @command{automake} otherwise is an
3868 indication of how that feature is misplaced.
3870 The new implementation will probably be done slightly differently.
3871 For instance, it could enforce the @file{m4/}-style layout discussed in
3874 We have no idea when and how this will happen. This has been
3875 discussed several times in the past, but someone still has to commit
3876 to that non-trivial task.
3878 From the user point of view, @command{aclocal}'s removal might turn
3879 out to be painful. There is a simple precaution that you may take to
3880 make that switch more seamless: never call @command{aclocal} yourself.
3881 Keep this guy under the exclusive control of @command{autoreconf} and
3882 Automake's rebuild rules. Hopefully you won't need to worry about
3883 things breaking, when @command{aclocal} disappears, because everything
3884 will have been taken care of. If otherwise you used to call
3885 @command{aclocal} directly yourself or from some script, you will
3886 quickly notice the change.
3888 Many packages come with a script called @file{bootstrap.sh} or
3889 @file{autogen.sh}, that will just call @command{aclocal},
3890 @command{libtoolize}, @command{gettextize} or @command{autopoint},
3891 @command{autoconf}, @command{autoheader}, and @command{automake} in
3892 the right order. Actually this is precisely what @command{autoreconf}
3893 can do for you. If your package has such a @file{bootstrap.sh} or
3894 @file{autogen.sh} script, consider using @command{autoreconf}. That
3895 should simplify its logic a lot (less things to maintain, yum!), it's
3896 even likely you will not need the script anymore, and more to the point
3897 you will not call @command{aclocal} directly anymore.
3899 For the time being, third-party packages should continue to install
3900 public macros into @file{/usr/share/aclocal/}. If @command{aclocal}
3901 is replaced by another tool it might make sense to rename the
3902 directory, but supporting @file{/usr/share/aclocal/} for backward
3903 compatibility should be really easy provided all macros are properly
3904 written (@pxref{Extending aclocal}).
3909 @section Autoconf macros supplied with Automake
3911 Automake ships with several Autoconf macros that you can use from your
3912 @file{configure.ac}. When you use one of them it will be included by
3913 @command{aclocal} in @file{aclocal.m4}.
3916 * Public Macros:: Macros that you can use.
3917 * Obsolete Macros:: Macros that you should stop using.
3918 * Private Macros:: Macros that you should not use.
3921 @c consider generating the following subsections automatically from m4 files.
3924 @subsection Public Macros
3928 @item AM_INIT_AUTOMAKE([OPTIONS])
3929 @itemx AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])
3930 @acindex AM_INIT_AUTOMAKE
3931 Runs many macros required for proper operation of the generated Makefiles.
3933 @vindex AUTOMAKE_OPTIONS
3934 This macro has two forms, the first of which is preferred.
3935 In this form, @code{AM_INIT_AUTOMAKE} is called with a
3936 single argument: a space-separated list of Automake options that should
3937 be applied to every @file{Makefile.am} in the tree. The effect is as if
3938 each option were listed in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
3941 The second, deprecated, form of @code{AM_INIT_AUTOMAKE} has two required
3942 arguments: the package and the version number. This form is
3943 obsolete because the @var{package} and @var{version} can be obtained
3944 from Autoconf's @code{AC_INIT} macro (which itself has an old and a new
3947 If your @file{configure.ac} has:
3950 AC_INIT([src/foo.c])
3951 AM_INIT_AUTOMAKE([mumble], [1.5])
3955 you can modernize it as follows:
3958 AC_INIT([mumble], [1.5])
3959 AC_CONFIG_SRCDIR([src/foo.c])
3963 Note that if you're upgrading your @file{configure.ac} from an earlier
3964 version of Automake, it is not always correct to simply move the
3965 package and version arguments from @code{AM_INIT_AUTOMAKE} directly to
3966 @code{AC_INIT}, as in the example above. The first argument to
3967 @code{AC_INIT} should be the name of your package (e.g., @samp{GNU
3968 Automake}), not the tarball name (e.g., @samp{automake}) that you used
3969 to pass to @code{AM_INIT_AUTOMAKE}. Autoconf tries to derive a
3970 tarball name from the package name, which should work for most but not
3971 all package names. (If it doesn't work for yours, you can use the
3972 four-argument form of @code{AC_INIT} to provide the tarball name
3975 @cindex @code{PACKAGE}, prevent definition
3976 @cindex @code{VERSION}, prevent definition
3978 By default this macro @code{AC_DEFINE}'s @code{PACKAGE} and
3979 @code{VERSION}. This can be avoided by passing the @option{no-define}
3982 AM_INIT_AUTOMAKE([gnits 1.5 no-define dist-bzip2])
3984 or by passing a third non-empty argument to the obsolete form.
3986 @item AM_PATH_LISPDIR
3987 @acindex AM_PATH_LISPDIR
3990 Searches for the program @command{emacs}, and, if found, sets the
3991 output variable @code{lispdir} to the full path to Emacs' site-lisp
3994 Note that this test assumes the @command{emacs} found to be a version
3995 that supports Emacs Lisp (such as GNU Emacs or XEmacs). Other
3996 emacsen can cause this test to hang (some, like old versions of
3997 MicroEmacs, start up in interactive mode, requiring @kbd{C-x C-c} to
3998 exit, which is hardly obvious for a non-emacs user). In most cases,
3999 however, you should be able to use @kbd{C-c} to kill the test. In
4000 order to avoid problems, you can set @env{EMACS} to ``no'' in the
4001 environment, or use the @option{--with-lispdir} option to
4002 @command{configure} to explicitly set the correct path (if you're sure
4003 you have an @command{emacs} that supports Emacs Lisp).
4005 @item AM_PROG_AR(@ovar{act-if-fail})
4008 You must use this macro when you use the archiver in your project, if
4009 you want support for unusual archivers such as Microsoft @command{lib}.
4010 The content of the optional argument is executed if the archiver
4011 interface is not recognized; the default action is to abort configure
4012 with an error message.
4018 Use this macro when you have assembly code in your project. This will
4019 choose the assembler for you (by default the C compiler) and set
4020 @code{CCAS}, and will also set @code{CCASFLAGS} if required.
4022 @item AM_PROG_CC_C_O
4023 @acindex AM_PROG_CC_C_O
4024 @acindex AC_PROG_CC_C_O
4025 This is like @code{AC_PROG_CC_C_O}, but it generates its results in
4026 the manner required by Automake. You must use this instead of
4027 @code{AC_PROG_CC_C_O} when you need this functionality, that is, when
4028 using per-target flags or subdir-objects with C sources.
4031 @acindex AM_PROG_LEX
4032 @acindex AC_PROG_LEX
4033 @cindex HP-UX 10, @command{lex} problems
4034 @cindex @command{lex} problems with HP-UX 10
4035 Like @code{AC_PROG_LEX} (@pxref{Particular Programs, , Particular
4036 Program Checks, autoconf, The Autoconf Manual}), but uses the
4037 @command{missing} script on systems that do not have @command{lex}.
4038 HP-UX 10 is one such system.
4041 @acindex AM_PROG_GCJ
4044 This macro finds the @command{gcj} program or causes an error. It sets
4045 @code{GCJ} and @code{GCJFLAGS}. @command{gcj} is the Java front-end to the
4046 GNU Compiler Collection.
4048 @item AM_PROG_UPC([@var{compiler-search-list}])
4049 @acindex AM_PROG_UPC
4051 Find a compiler for Unified Parallel C and define the @code{UPC}
4052 variable. The default @var{compiler-search-list} is @samp{upcc upc}.
4053 This macro will abort @command{configure} if no Unified Parallel C
4056 @item AM_SILENT_RULES
4057 @acindex AM_SILENT_RULES
4058 Enable the machinery for less verbose build output (@pxref{Options}).
4060 @item AM_WITH_DMALLOC
4061 @acindex AM_WITH_DMALLOC
4062 @cindex @command{dmalloc}, support for
4063 @vindex WITH_DMALLOC
4064 @opindex --with-dmalloc
4065 Add support for the @uref{http://dmalloc.com/, Dmalloc package}. If
4066 the user runs @command{configure} with @option{--with-dmalloc}, then
4067 define @code{WITH_DMALLOC} and add @option{-ldmalloc} to @code{LIBS}.
4072 @node Obsolete Macros
4073 @subsection Obsolete Macros
4074 @cindex obsolete macros
4077 Although using some of the following macros was required in past
4078 releases, you should not use any of them in new code. Running
4079 @command{autoupdate} should adjust your @file{configure.ac}
4080 automatically (@pxref{autoupdate Invocation, , Using
4081 @command{autoupdate} to Modernize @file{configure.ac}, autoconf, The
4086 @item AM_CONFIG_HEADER
4087 @acindex AM_CONFIG_HEADER
4088 Automake will generate rules to automatically regenerate the config
4089 header. This obsolete macro is a synonym of @code{AC_CONFIG_HEADERS}
4090 today (@pxref{Optional}).
4092 @item AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
4093 @acindex AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
4094 If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
4095 define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be
4096 found in @file{<termios.h>}. This macro is obsolete, you should
4097 use Autoconf's @code{AC_HEADER_TIOCGWINSZ} instead.
4099 @item AM_PROG_MKDIR_P
4100 @acindex AM_PROG_MKDIR_P
4101 @cindex @code{mkdir -p}, macro check
4105 From Automake 1.8 to 1.9.6 this macro used to define the output
4106 variable @code{mkdir_p} to one of @code{mkdir -p}, @code{install-sh
4107 -d}, or @code{mkinstalldirs}.
4109 Nowadays Autoconf provides a similar functionality with
4110 @code{AC_PROG_MKDIR_P} (@pxref{Particular Programs, , Particular
4111 Program Checks, autoconf, The Autoconf Manual}), however this defines
4112 the output variable @code{MKDIR_P} instead. Therefore
4113 @code{AM_PROG_MKDIR_P} has been rewritten as a thin wrapper around
4114 @code{AC_PROG_MKDIR_P} to define @code{mkdir_p} to the same value as
4115 @code{MKDIR_P} for backward compatibility.
4117 If you are using Automake, there is normally no reason to call this
4118 macro, because @code{AM_INIT_AUTOMAKE} already does so. However, make
4119 sure that the custom rules in your @file{Makefile}s use
4120 @code{$(MKDIR_P)} and not @code{$(mkdir_p)}. Even if both variables
4121 still work, the latter should be considered obsolete.
4123 If you are not using Automake, please call @code{AC_PROG_MKDIR_P}
4124 instead of @code{AM_PROG_MKDIR_P}.
4126 @item AM_SYS_POSIX_TERMIOS
4127 @acindex AM_SYS_POSIX_TERMIOS
4128 @cindex POSIX termios headers
4129 @cindex termios POSIX headers
4130 Check to see if POSIX termios headers and functions are available on the
4131 system. If so, set the shell variable @code{am_cv_sys_posix_termios} to
4132 @samp{yes}. If not, set the variable to @samp{no}. This macro is obsolete,
4133 you should use Autoconf's @code{AC_SYS_POSIX_TERMIOS} instead.
4138 @node Private Macros
4139 @subsection Private Macros
4141 The following macros are private macros you should not call directly.
4142 They are called by the other public macros when appropriate. Do not
4143 rely on them, as they might be changed in a future version. Consider
4144 them as implementation details; or better, do not consider them at all:
4148 @item _AM_DEPENDENCIES
4149 @itemx AM_SET_DEPDIR
4151 @itemx AM_OUTPUT_DEPENDENCY_COMMANDS
4152 These macros are used to implement Automake's automatic dependency
4153 tracking scheme. They are called automatically by Automake when
4154 required, and there should be no need to invoke them manually.
4156 @item AM_MAKE_INCLUDE
4157 This macro is used to discover how the user's @command{make} handles
4158 @code{include} statements. This macro is automatically invoked when
4159 needed; there should be no need to invoke it manually.
4161 @item AM_PROG_INSTALL_STRIP
4162 This is used to find a version of @code{install} that can be used to
4163 strip a program at installation time. This macro is automatically
4164 included when required.
4166 @item AM_SANITY_CHECK
4167 This checks to make sure that a file created in the build directory is
4168 newer than a file in the source directory. This can fail on systems
4169 where the clock is set incorrectly. This macro is automatically run
4170 from @code{AM_INIT_AUTOMAKE}.
4176 @chapter Directories
4178 For simple projects that distribute all files in the same directory
4179 it is enough to have a single @file{Makefile.am} that builds
4180 everything in place.
4182 In larger projects it is common to organize files in different
4183 directories, in a tree. For instance one directory per program, per
4184 library or per module. The traditional approach is to build these
4185 subdirectories recursively: each directory contains its @file{Makefile}
4186 (generated from @file{Makefile.am}), and when @command{make} is run
4187 from the top level directory it enters each subdirectory in turn to
4191 * Subdirectories:: Building subdirectories recursively
4192 * Conditional Subdirectories:: Conditionally not building directories
4193 * Alternative:: Subdirectories without recursion
4194 * Subpackages:: Nesting packages
4197 @node Subdirectories
4198 @section Recursing subdirectories
4200 @cindex @code{SUBDIRS}, explained
4202 In packages with subdirectories, the top level @file{Makefile.am} must
4203 tell Automake which subdirectories are to be built. This is done via
4204 the @code{SUBDIRS} variable.
4207 The @code{SUBDIRS} variable holds a list of subdirectories in which
4208 building of various sorts can occur. The rules for many targets
4209 (e.g., @code{all}) in the generated @file{Makefile} will run commands
4210 both locally and in all specified subdirectories. Note that the
4211 directories listed in @code{SUBDIRS} are not required to contain
4212 @file{Makefile.am}s; only @file{Makefile}s (after configuration).
4213 This allows inclusion of libraries from packages that do not use
4214 Automake (such as @code{gettext}; see also @ref{Third-Party
4217 In packages that use subdirectories, the top-level @file{Makefile.am} is
4218 often very short. For instance, here is the @file{Makefile.am} from the
4219 GNU Hello distribution:
4222 EXTRA_DIST = BUGS ChangeLog.O README-alpha
4223 SUBDIRS = doc intl po src tests
4226 When Automake invokes @command{make} in a subdirectory, it uses the value
4227 of the @code{MAKE} variable. It passes the value of the variable
4228 @code{AM_MAKEFLAGS} to the @command{make} invocation; this can be set in
4229 @file{Makefile.am} if there are flags you must always pass to
4232 @vindex AM_MAKEFLAGS
4234 The directories mentioned in @code{SUBDIRS} are usually direct
4235 children of the current directory, each subdirectory containing its
4236 own @file{Makefile.am} with a @code{SUBDIRS} pointing to deeper
4237 subdirectories. Automake can be used to construct packages of
4238 arbitrary depth this way.
4240 By default, Automake generates @file{Makefiles} that work depth-first
4241 in postfix order: the subdirectories are built before the current
4242 directory. However, it is possible to change this ordering. You can
4243 do this by putting @samp{.} into @code{SUBDIRS}. For instance,
4244 putting @samp{.} first will cause a prefix ordering of
4250 SUBDIRS = lib src . test
4254 will cause @file{lib/} to be built before @file{src/}, then the
4255 current directory will be built, finally the @file{test/} directory
4256 will be built. It is customary to arrange test directories to be
4257 built after everything else since they are meant to test what has
4260 All @code{clean} rules are run in reverse order of build rules.
4262 @node Conditional Subdirectories
4263 @section Conditional Subdirectories
4264 @cindex Subdirectories, building conditionally
4265 @cindex Conditional subdirectories
4266 @cindex @code{SUBDIRS}, conditional
4267 @cindex Conditional @code{SUBDIRS}
4269 It is possible to define the @code{SUBDIRS} variable conditionally if,
4270 like in the case of GNU Inetutils, you want to only build a subset of
4273 To illustrate how this works, let's assume we have two directories
4274 @file{src/} and @file{opt/}. @file{src/} should always be built, but we
4275 want to decide in @command{configure} whether @file{opt/} will be built
4276 or not. (For this example we will assume that @file{opt/} should be
4277 built when the variable @samp{$want_opt} was set to @samp{yes}.)
4279 Running @command{make} should thus recurse into @file{src/} always, and
4280 then maybe in @file{opt/}.
4282 However @samp{make dist} should always recurse into both @file{src/}
4283 and @file{opt/}. Because @file{opt/} should be distributed even if it
4284 is not needed in the current configuration. This means
4285 @file{opt/Makefile} should be created @emph{unconditionally}.
4287 There are two ways to setup a project like this. You can use Automake
4288 conditionals (@pxref{Conditionals}) or use Autoconf @code{AC_SUBST}
4289 variables (@pxref{Setting Output Variables, , Setting Output
4290 Variables, autoconf, The Autoconf Manual}). Using Automake
4291 conditionals is the preferred solution. Before we illustrate these
4292 two possibilities, let's introduce @code{DIST_SUBDIRS}.
4295 * SUBDIRS vs DIST_SUBDIRS:: Two sets of directories
4296 * Subdirectories with AM_CONDITIONAL:: Specifying conditional subdirectories
4297 * Subdirectories with AC_SUBST:: Another way for conditional recursion
4298 * Unconfigured Subdirectories:: Not even creating a @samp{Makefile}
4301 @node SUBDIRS vs DIST_SUBDIRS
4302 @subsection @code{SUBDIRS} vs.@: @code{DIST_SUBDIRS}
4303 @cindex @code{DIST_SUBDIRS}, explained
4305 Automake considers two sets of directories, defined by the variables
4306 @code{SUBDIRS} and @code{DIST_SUBDIRS}.
4308 @code{SUBDIRS} contains the subdirectories of the current directory
4309 that must be built (@pxref{Subdirectories}). It must be defined
4310 manually; Automake will never guess a directory is to be built. As we
4311 will see in the next two sections, it is possible to define it
4312 conditionally so that some directory will be omitted from the build.
4314 @code{DIST_SUBDIRS} is used in rules that need to recurse in all
4315 directories, even those that have been conditionally left out of the
4316 build. Recall our example where we may not want to build subdirectory
4317 @file{opt/}, but yet we want to distribute it? This is where
4318 @code{DIST_SUBDIRS} comes into play: @samp{opt} may not appear in
4319 @code{SUBDIRS}, but it must appear in @code{DIST_SUBDIRS}.
4321 Precisely, @code{DIST_SUBDIRS} is used by @samp{make
4322 maintainer-clean}, @samp{make distclean} and @samp{make dist}. All
4323 other recursive rules use @code{SUBDIRS}.
4325 If @code{SUBDIRS} is defined conditionally using Automake
4326 conditionals, Automake will define @code{DIST_SUBDIRS} automatically
4327 from the possible values of @code{SUBDIRS} in all conditions.
4329 If @code{SUBDIRS} contains @code{AC_SUBST} variables,
4330 @code{DIST_SUBDIRS} will not be defined correctly because Automake
4331 does not know the possible values of these variables. In this case
4332 @code{DIST_SUBDIRS} needs to be defined manually.
4334 @node Subdirectories with AM_CONDITIONAL
4335 @subsection Subdirectories with @code{AM_CONDITIONAL}
4336 @cindex @code{SUBDIRS} and @code{AM_CONDITIONAL}
4337 @cindex @code{AM_CONDITIONAL} and @code{SUBDIRS}
4339 @c Keep in sync with subcond2.test.
4341 @file{configure} should output the @file{Makefile} for each directory
4342 and define a condition into which @file{opt/} should be built.
4346 AM_CONDITIONAL([COND_OPT], [test "$want_opt" = yes])
4347 AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
4351 Then @code{SUBDIRS} can be defined in the top-level @file{Makefile.am}
4358 SUBDIRS = src $(MAYBE_OPT)
4361 As you can see, running @command{make} will rightly recurse into
4362 @file{src/} and maybe @file{opt/}.
4364 @vindex DIST_SUBDIRS
4365 As you can't see, running @samp{make dist} will recurse into both
4366 @file{src/} and @file{opt/} directories because @samp{make dist}, unlike
4367 @samp{make all}, doesn't use the @code{SUBDIRS} variable. It uses the
4368 @code{DIST_SUBDIRS} variable.
4370 In this case Automake will define @samp{DIST_SUBDIRS = src opt}
4371 automatically because it knows that @code{MAYBE_OPT} can contain
4372 @samp{opt} in some condition.
4374 @node Subdirectories with AC_SUBST
4375 @subsection Subdirectories with @code{AC_SUBST}
4376 @cindex @code{SUBDIRS} and @code{AC_SUBST}
4377 @cindex @code{AC_SUBST} and @code{SUBDIRS}
4379 @c Keep in sync with subcond3.test.
4381 Another possibility is to define @code{MAYBE_OPT} from
4382 @file{./configure} using @code{AC_SUBST}:
4386 if test "$want_opt" = yes; then
4391 AC_SUBST([MAYBE_OPT])
4392 AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
4396 In this case the top-level @file{Makefile.am} should look as follows.
4399 SUBDIRS = src $(MAYBE_OPT)
4400 DIST_SUBDIRS = src opt
4403 The drawback is that since Automake cannot guess what the possible
4404 values of @code{MAYBE_OPT} are, it is necessary to define
4405 @code{DIST_SUBDIRS}.
4407 @node Unconfigured Subdirectories
4408 @subsection Unconfigured Subdirectories
4409 @cindex Subdirectories, configured conditionally
4411 The semantics of @code{DIST_SUBDIRS} are often misunderstood by some
4412 users that try to @emph{configure and build} subdirectories
4413 conditionally. Here by configuring we mean creating the
4414 @file{Makefile} (it might also involve running a nested
4415 @command{configure} script: this is a costly operation that explains
4416 why people want to do it conditionally, but only the @file{Makefile}
4417 is relevant to the discussion).
4419 The above examples all assume that every @file{Makefile} is created,
4420 even in directories that are not going to be built. The simple reason
4421 is that we want @samp{make dist} to distribute even the directories
4422 that are not being built (e.g., platform-dependent code), hence
4423 @file{make dist} must recurse into the subdirectory, hence this
4424 directory must be configured and appear in @code{DIST_SUBDIRS}.
4426 Building packages that do not configure every subdirectory is a tricky
4427 business, and we do not recommend it to the novice as it is easy to
4428 produce an incomplete tarball by mistake. We will not discuss this
4429 topic in depth here, yet for the adventurous here are a few rules to
4434 @item @code{SUBDIRS} should always be a subset of @code{DIST_SUBDIRS}.
4436 It makes little sense to have a directory in @code{SUBDIRS} that
4437 is not in @code{DIST_SUBDIRS}. Think of the former as a way to tell
4438 which directories listed in the latter should be built.
4439 @item Any directory listed in @code{DIST_SUBDIRS} and @code{SUBDIRS}
4442 I.e., the @file{Makefile} must exists or the recursive @command{make}
4443 rules will not be able to process the directory.
4444 @item Any configured directory must be listed in @code{DIST_SUBDIRS}.
4446 So that the cleaning rules remove the generated @file{Makefile}s.
4447 It would be correct to see @code{DIST_SUBDIRS} as a variable that
4448 lists all the directories that have been configured.
4452 In order to prevent recursion in some unconfigured directory you
4453 must therefore ensure that this directory does not appear in
4454 @code{DIST_SUBDIRS} (and @code{SUBDIRS}). For instance, if you define
4455 @code{SUBDIRS} conditionally using @code{AC_SUBST} and do not define
4456 @code{DIST_SUBDIRS} explicitly, it will be default to
4457 @samp{$(SUBDIRS)}; another possibility is to force @code{DIST_SUBDIRS
4460 Of course, directories that are omitted from @code{DIST_SUBDIRS} will
4461 not be distributed unless you make other arrangements for this to
4462 happen (for instance, always running @samp{make dist} in a
4463 configuration where all directories are known to appear in
4464 @code{DIST_SUBDIRS}; or writing a @code{dist-hook} target to
4465 distribute these directories).
4467 @cindex Subdirectories, not distributed
4468 In few packages, unconfigured directories are not even expected to
4469 be distributed. Although these packages do not require the
4470 aforementioned extra arrangements, there is another pitfall. If the
4471 name of a directory appears in @code{SUBDIRS} or @code{DIST_SUBDIRS},
4472 @command{automake} will make sure the directory exists. Consequently
4473 @command{automake} cannot be run on such a distribution when one
4474 directory has been omitted. One way to avoid this check is to use the
4475 @code{AC_SUBST} method to declare conditional directories; since
4476 @command{automake} does not know the values of @code{AC_SUBST}
4477 variables it cannot ensure the corresponding directory exists.
4480 @section An Alternative Approach to Subdirectories
4482 If you've ever read Peter Miller's excellent paper,
4483 @uref{http://miller.emu.id.au/pmiller/books/rmch/,
4484 Recursive Make Considered Harmful}, the preceding sections on the use of
4485 subdirectories will probably come as unwelcome advice. For those who
4486 haven't read the paper, Miller's main thesis is that recursive
4487 @command{make} invocations are both slow and error-prone.
4489 Automake provides sufficient cross-directory support @footnote{We
4490 believe. This work is new and there are probably warts.
4491 @xref{Introduction}, for information on reporting bugs.} to enable you
4492 to write a single @file{Makefile.am} for a complex multi-directory
4496 By default an installable file specified in a subdirectory will have its
4497 directory name stripped before installation. For instance, in this
4498 example, the header file will be installed as
4499 @file{$(includedir)/stdio.h}:
4502 include_HEADERS = inc/stdio.h
4506 @cindex @code{nobase_} prefix
4507 @cindex Path stripping, avoiding
4508 @cindex Avoiding path stripping
4510 However, the @samp{nobase_} prefix can be used to circumvent this path
4511 stripping. In this example, the header file will be installed as
4512 @file{$(includedir)/sys/types.h}:
4515 nobase_include_HEADERS = sys/types.h
4518 @cindex @code{nobase_} and @code{dist_} or @code{nodist_}
4519 @cindex @code{dist_} and @code{nobase_}
4520 @cindex @code{nodist_} and @code{nobase_}
4524 @samp{nobase_} should be specified first when used in conjunction with
4525 either @samp{dist_} or @samp{nodist_} (@pxref{Fine-grained Distribution
4526 Control}). For instance:
4529 nobase_dist_pkgdata_DATA = images/vortex.pgm sounds/whirl.ogg
4532 Finally, note that a variable using the @samp{nobase_} prefix can
4533 often be replaced by several variables, one for each destination
4534 directory (@pxref{Uniform}). For instance, the last example could be
4535 rewritten as follows:
4537 @c Keep in sync with primary-prefix-couples-documented-valid.test.
4539 imagesdir = $(pkgdatadir)/images
4540 soundsdir = $(pkgdatadir)/sounds
4541 dist_images_DATA = images/vortex.pgm
4542 dist_sounds_DATA = sounds/whirl.ogg
4546 This latter syntax makes it possible to change one destination
4547 directory without changing the layout of the source tree.
4549 Currently, @samp{nobase_*_LTLIBRARIES} are the only exception to this
4550 rule, in that there is no particular installation order guarantee for
4551 an otherwise equivalent set of variables without @samp{nobase_} prefix.
4554 @section Nesting Packages
4555 @cindex Nesting packages
4557 @acindex AC_CONFIG_SUBDIRS
4558 @acindex AC_CONFIG_AUX_DIR
4561 In the GNU Build System, packages can be nested to arbitrary depth.
4562 This means that a package can embed other packages with their own
4563 @file{configure}, @file{Makefile}s, etc.
4565 These other packages should just appear as subdirectories of their
4566 parent package. They must be listed in @code{SUBDIRS} like other
4567 ordinary directories. However the subpackage's @file{Makefile}s
4568 should be output by its own @file{configure} script, not by the
4569 parent's @file{configure}. This is achieved using the
4570 @code{AC_CONFIG_SUBDIRS} Autoconf macro (@pxref{Subdirectories,
4571 AC_CONFIG_SUBDIRS, Configuring Other Packages in Subdirectories,
4572 autoconf, The Autoconf Manual}).
4574 Here is an example package for an @code{arm} program that links with
4575 a @code{hand} library that is a nested package in subdirectory
4578 @code{arm}'s @file{configure.ac}:
4581 AC_INIT([arm], [1.0])
4582 AC_CONFIG_AUX_DIR([.])
4585 AC_CONFIG_FILES([Makefile])
4586 # Call hand's ./configure script recursively.
4587 AC_CONFIG_SUBDIRS([hand])
4591 @code{arm}'s @file{Makefile.am}:
4594 # Build the library in the hand subdirectory first.
4597 # Include hand's header when compiling this directory.
4598 AM_CPPFLAGS = -I$(srcdir)/hand
4602 # link with the hand library.
4603 arm_LDADD = hand/libhand.a
4606 Now here is @code{hand}'s @file{hand/configure.ac}:
4609 AC_INIT([hand], [1.2])
4610 AC_CONFIG_AUX_DIR([.])
4615 AC_CONFIG_FILES([Makefile])
4620 and its @file{hand/Makefile.am}:
4623 lib_LIBRARIES = libhand.a
4624 libhand_a_SOURCES = hand.c
4627 When @samp{make dist} is run from the top-level directory it will
4628 create an archive @file{arm-1.0.tar.gz} that contains the @code{arm}
4629 code as well as the @file{hand} subdirectory. This package can be
4630 built and installed like any ordinary package, with the usual
4631 @samp{./configure && make && make install} sequence (the @code{hand}
4632 subpackage will be built and installed by the process).
4634 When @samp{make dist} is run from the hand directory, it will create a
4635 self-contained @file{hand-1.2.tar.gz} archive. So although it appears
4636 to be embedded in another package, it can still be used separately.
4638 The purpose of the @samp{AC_CONFIG_AUX_DIR([.])} instruction is to
4639 force Automake and Autoconf to search for auxiliary scripts in the
4640 current directory. For instance, this means that there will be two
4641 copies of @file{install-sh}: one in the top-level of the @code{arm}
4642 package, and another one in the @file{hand/} subdirectory for the
4643 @code{hand} package.
4645 The historical default is to search for these auxiliary scripts in
4646 the parent directory and the grandparent directory. So if the
4647 @samp{AC_CONFIG_AUX_DIR([.])} line was removed from
4648 @file{hand/configure.ac}, that subpackage would share the auxiliary
4649 script of the @code{arm} package. This may looks like a gain in size
4650 (a few kilobytes), but it is actually a loss of modularity as the
4651 @code{hand} subpackage is no longer self-contained (@samp{make dist}
4652 in the subdirectory will not work anymore).
4654 Packages that do not use Automake need more work to be integrated this
4655 way. @xref{Third-Party Makefiles}.
4658 @chapter Building Programs and Libraries
4660 A large part of Automake's functionality is dedicated to making it easy
4661 to build programs and libraries.
4664 * A Program:: Building a program
4665 * A Library:: Building a library
4666 * A Shared Library:: Building a Libtool library
4667 * Program and Library Variables:: Variables controlling program and
4669 * Default _SOURCES:: Default source files
4670 * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
4671 * Program Variables:: Variables used when building a program
4672 * Yacc and Lex:: Yacc and Lex support
4673 * C++ Support:: Compiling C++ sources
4674 * Objective C Support:: Compiling Objective C sources
4675 * Unified Parallel C Support:: Compiling Unified Parallel C sources
4676 * Assembly Support:: Compiling assembly sources
4677 * Fortran 77 Support:: Compiling Fortran 77 sources
4678 * Fortran 9x Support:: Compiling Fortran 9x sources
4679 * Java Support with gcj:: Compiling Java sources using gcj
4680 * Vala Support:: Compiling Vala sources
4681 * Support for Other Languages:: Compiling other languages
4682 * Dependencies:: Automatic dependency tracking
4683 * EXEEXT:: Support for executable extensions
4688 @section Building a program
4690 In order to build a program, you need to tell Automake which sources
4691 are part of it, and which libraries it should be linked with.
4693 This section also covers conditional compilation of sources or
4694 programs. Most of the comments about these also apply to libraries
4695 (@pxref{A Library}) and libtool libraries (@pxref{A Shared Library}).
4698 * Program Sources:: Defining program sources
4699 * Linking:: Linking with libraries or extra objects
4700 * Conditional Sources:: Handling conditional sources
4701 * Conditional Programs:: Building a program conditionally
4704 @node Program Sources
4705 @subsection Defining program sources
4707 @cindex @code{PROGRAMS}, @code{bindir}
4709 @vindex bin_PROGRAMS
4710 @vindex sbin_PROGRAMS
4711 @vindex libexec_PROGRAMS
4712 @vindex pkglibexec_PROGRAMS
4713 @vindex noinst_PROGRAMS
4714 @vindex check_PROGRAMS
4716 In a directory containing source that gets built into a program (as
4717 opposed to a library or a script), the @code{PROGRAMS} primary is used.
4718 Programs can be installed in @code{bindir}, @code{sbindir},
4719 @code{libexecdir}, @code{pkglibexecdir}, or not at all
4720 (@code{noinst_}). They can also be built only for @samp{make check}, in
4721 which case the prefix is @samp{check_}.
4726 bin_PROGRAMS = hello
4729 In this simple case, the resulting @file{Makefile.in} will contain code
4730 to generate a program named @code{hello}.
4732 Associated with each program are several assisting variables that are
4733 named after the program. These variables are all optional, and have
4734 reasonable defaults. Each variable, its use, and default is spelled out
4735 below; we use the ``hello'' example throughout.
4737 The variable @code{hello_SOURCES} is used to specify which source files
4738 get built into an executable:
4741 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
4744 This causes each mentioned @file{.c} file to be compiled into the
4745 corresponding @file{.o}. Then all are linked to produce @file{hello}.
4747 @cindex @code{_SOURCES} primary, defined
4748 @cindex @code{SOURCES} primary, defined
4749 @cindex Primary variable, @code{SOURCES}
4752 If @code{hello_SOURCES} is not specified, then it defaults to the single
4753 file @file{hello.c} (@pxref{Default _SOURCES}).
4757 Multiple programs can be built in a single directory. Multiple programs
4758 can share a single source file, which must be listed in each
4759 @code{_SOURCES} definition.
4761 @cindex Header files in @code{_SOURCES}
4762 @cindex @code{_SOURCES} and header files
4764 Header files listed in a @code{_SOURCES} definition will be included in
4765 the distribution but otherwise ignored. In case it isn't obvious, you
4766 should not include the header file generated by @file{configure} in a
4767 @code{_SOURCES} variable; this file should not be distributed. Lex
4768 (@file{.l}) and Yacc (@file{.y}) files can also be listed; see @ref{Yacc
4773 @subsection Linking the program
4775 If you need to link against libraries that are not found by
4776 @command{configure}, you can use @code{LDADD} to do so. This variable is
4777 used to specify additional objects or libraries to link with; it is
4778 inappropriate for specifying specific linker flags, you should use
4779 @code{AM_LDFLAGS} for this purpose.
4783 @cindex @code{prog_LDADD}, defined
4785 Sometimes, multiple programs are built in one directory but do not share
4786 the same link-time requirements. In this case, you can use the
4787 @code{@var{prog}_LDADD} variable (where @var{prog} is the name of the
4788 program as it appears in some @code{_PROGRAMS} variable, and usually
4789 written in lowercase) to override @code{LDADD}. If this variable exists
4790 for a given program, then that program is not linked using @code{LDADD}.
4793 For instance, in GNU cpio, @code{pax}, @code{cpio} and @code{mt} are
4794 linked against the library @file{libcpio.a}. However, @code{rmt} is
4795 built in the same directory, and has no such link requirement. Also,
4796 @code{mt} and @code{rmt} are only built on certain architectures. Here
4797 is what cpio's @file{src/Makefile.am} looks like (abridged):
4800 bin_PROGRAMS = cpio pax $(MT)
4801 libexec_PROGRAMS = $(RMT)
4802 EXTRA_PROGRAMS = mt rmt
4804 LDADD = ../lib/libcpio.a $(INTLLIBS)
4807 cpio_SOURCES = @dots{}
4808 pax_SOURCES = @dots{}
4809 mt_SOURCES = @dots{}
4810 rmt_SOURCES = @dots{}
4813 @cindex @code{_LDFLAGS}, defined
4814 @vindex maude_LDFLAGS
4815 @code{@var{prog}_LDADD} is inappropriate for passing program-specific
4816 linker flags (except for @option{-l}, @option{-L}, @option{-dlopen} and
4817 @option{-dlpreopen}). So, use the @code{@var{prog}_LDFLAGS} variable for
4820 @cindex @code{_DEPENDENCIES}, defined
4821 @vindex maude_DEPENDENCIES
4822 @vindex EXTRA_maude_DEPENDENCIES
4823 It is also occasionally useful to have a program depend on some other
4824 target that is not actually part of that program. This can be done
4825 using either the @code{@var{prog}_DEPENDENCIES} or the
4826 @code{EXTRA_@var{prog}_DEPENDENCIES} variable. Each program depends on
4827 the contents both variables, but no further interpretation is done.
4829 Since these dependencies are associated to the link rule used to
4830 create the programs they should normally list files used by the link
4831 command. That is @file{*.$(OBJEXT)}, @file{*.a}, or @file{*.la}
4832 files. In rare cases you may need to add other kinds of files such as
4833 linker scripts, but @emph{listing a source file in
4834 @code{_DEPENDENCIES} is wrong}. If some source file needs to be built
4835 before all the components of a program are built, consider using the
4836 @code{BUILT_SOURCES} variable instead (@pxref{Sources}).
4838 If @code{@var{prog}_DEPENDENCIES} is not supplied, it is computed by
4839 Automake. The automatically-assigned value is the contents of
4840 @code{@var{prog}_LDADD}, with most configure substitutions, @option{-l},
4841 @option{-L}, @option{-dlopen} and @option{-dlpreopen} options removed. The
4842 configure substitutions that are left in are only @samp{$(LIBOBJS)} and
4843 @samp{$(ALLOCA)}; these are left because it is known that they will not
4844 cause an invalid value for @code{@var{prog}_DEPENDENCIES} to be
4847 @ref{Conditional Sources} shows a situation where @code{_DEPENDENCIES}
4850 The @code{EXTRA_@var{prog}_DEPENDENCIES} may be useful for cases where
4851 you merely want to augment the @command{automake}-generated
4852 @code{@var{prog}_DEPENDENCIES} rather than replacing it.
4854 @cindex @code{LDADD} and @option{-l}
4855 @cindex @option{-l} and @code{LDADD}
4856 We recommend that you avoid using @option{-l} options in @code{LDADD}
4857 or @code{@var{prog}_LDADD} when referring to libraries built by your
4858 package. Instead, write the file name of the library explicitly as in
4859 the above @code{cpio} example. Use @option{-l} only to list
4860 third-party libraries. If you follow this rule, the default value of
4861 @code{@var{prog}_DEPENDENCIES} will list all your local libraries and
4862 omit the other ones.
4865 @node Conditional Sources
4866 @subsection Conditional compilation of sources
4868 You can't put a configure substitution (e.g., @samp{@@FOO@@} or
4869 @samp{$(FOO)} where @code{FOO} is defined via @code{AC_SUBST}) into a
4870 @code{_SOURCES} variable. The reason for this is a bit hard to
4871 explain, but suffice to say that it simply won't work. Automake will
4872 give an error if you try to do this.
4874 Fortunately there are two other ways to achieve the same result. One is
4875 to use configure substitutions in @code{_LDADD} variables, the other is
4876 to use an Automake conditional.
4878 @subsubheading Conditional Compilation using @code{_LDADD} Substitutions
4880 @cindex @code{EXTRA_prog_SOURCES}, defined
4882 Automake must know all the source files that could possibly go into a
4883 program, even if not all the files are built in every circumstance. Any
4884 files that are only conditionally built should be listed in the
4885 appropriate @code{EXTRA_} variable. For instance, if
4886 @file{hello-linux.c} or @file{hello-generic.c} were conditionally included
4887 in @code{hello}, the @file{Makefile.am} would contain:
4890 bin_PROGRAMS = hello
4891 hello_SOURCES = hello-common.c
4892 EXTRA_hello_SOURCES = hello-linux.c hello-generic.c
4893 hello_LDADD = $(HELLO_SYSTEM)
4894 hello_DEPENDENCIES = $(HELLO_SYSTEM)
4898 You can then setup the @samp{$(HELLO_SYSTEM)} substitution from
4899 @file{configure.ac}:
4904 *linux*) HELLO_SYSTEM='hello-linux.$(OBJEXT)' ;;
4905 *) HELLO_SYSTEM='hello-generic.$(OBJEXT)' ;;
4907 AC_SUBST([HELLO_SYSTEM])
4911 In this case, the variable @code{HELLO_SYSTEM} should be replaced by
4912 either @file{hello-linux.o} or @file{hello-generic.o}, and added to
4913 both @code{hello_DEPENDENCIES} and @code{hello_LDADD} in order to be
4914 built and linked in.
4916 @subsubheading Conditional Compilation using Automake Conditionals
4918 An often simpler way to compile source files conditionally is to use
4919 Automake conditionals. For instance, you could use this
4920 @file{Makefile.am} construct to build the same @file{hello} example:
4923 bin_PROGRAMS = hello
4925 hello_SOURCES = hello-linux.c hello-common.c
4927 hello_SOURCES = hello-generic.c hello-common.c
4931 In this case, @file{configure.ac} should setup the @code{LINUX}
4932 conditional using @code{AM_CONDITIONAL} (@pxref{Conditionals}).
4934 When using conditionals like this you don't need to use the
4935 @code{EXTRA_} variable, because Automake will examine the contents of
4936 each variable to construct the complete list of source files.
4938 If your program uses a lot of files, you will probably prefer a
4939 conditional @samp{+=}.
4942 bin_PROGRAMS = hello
4943 hello_SOURCES = hello-common.c
4945 hello_SOURCES += hello-linux.c
4947 hello_SOURCES += hello-generic.c
4951 @node Conditional Programs
4952 @subsection Conditional compilation of programs
4953 @cindex Conditional programs
4954 @cindex Programs, conditional
4956 Sometimes it is useful to determine the programs that are to be built
4957 at configure time. For instance, GNU @code{cpio} only builds
4958 @code{mt} and @code{rmt} under special circumstances. The means to
4959 achieve conditional compilation of programs are the same you can use
4960 to compile source files conditionally: substitutions or conditionals.
4962 @subsubheading Conditional Programs using @command{configure} Substitutions
4964 @vindex EXTRA_PROGRAMS
4965 @cindex @code{EXTRA_PROGRAMS}, defined
4966 In this case, you must notify Automake of all the programs that can
4967 possibly be built, but at the same time cause the generated
4968 @file{Makefile.in} to use the programs specified by @command{configure}.
4969 This is done by having @command{configure} substitute values into each
4970 @code{_PROGRAMS} definition, while listing all optionally built programs
4971 in @code{EXTRA_PROGRAMS}.
4974 bin_PROGRAMS = cpio pax $(MT)
4975 libexec_PROGRAMS = $(RMT)
4976 EXTRA_PROGRAMS = mt rmt
4979 As explained in @ref{EXEEXT}, Automake will rewrite
4980 @code{bin_PROGRAMS}, @code{libexec_PROGRAMS}, and
4981 @code{EXTRA_PROGRAMS}, appending @samp{$(EXEEXT)} to each binary.
4982 Obviously it cannot rewrite values obtained at run-time through
4983 @command{configure} substitutions, therefore you should take care of
4984 appending @samp{$(EXEEXT)} yourself, as in @samp{AC_SUBST([MT],
4985 ['mt$@{EXEEXT@}'])}.
4987 @subsubheading Conditional Programs using Automake Conditionals
4989 You can also use Automake conditionals (@pxref{Conditionals}) to
4990 select programs to be built. In this case you don't have to worry
4991 about @samp{$(EXEEXT)} or @code{EXTRA_PROGRAMS}.
4993 @c Keep in sync with exeext.test.
4995 bin_PROGRAMS = cpio pax
5000 libexec_PROGRAMS = rmt
5006 @section Building a library
5008 @cindex @code{_LIBRARIES} primary, defined
5009 @cindex @code{LIBRARIES} primary, defined
5010 @cindex Primary variable, @code{LIBRARIES}
5013 @vindex lib_LIBRARIES
5014 @vindex pkglib_LIBRARIES
5015 @vindex noinst_LIBRARIES
5017 Building a library is much like building a program. In this case, the
5018 name of the primary is @code{LIBRARIES}. Libraries can be installed in
5019 @code{libdir} or @code{pkglibdir}.
5021 @xref{A Shared Library}, for information on how to build shared
5022 libraries using libtool and the @code{LTLIBRARIES} primary.
5024 Each @code{_LIBRARIES} variable is a list of the libraries to be built.
5025 For instance, to create a library named @file{libcpio.a}, but not install
5026 it, you would write:
5029 noinst_LIBRARIES = libcpio.a
5030 libcpio_a_SOURCES = @dots{}
5033 The sources that go into a library are determined exactly as they are
5034 for programs, via the @code{_SOURCES} variables. Note that the library
5035 name is canonicalized (@pxref{Canonicalization}), so the @code{_SOURCES}
5036 variable corresponding to @file{libcpio.a} is @samp{libcpio_a_SOURCES},
5037 not @samp{libcpio.a_SOURCES}.
5039 @vindex maude_LIBADD
5040 Extra objects can be added to a library using the
5041 @code{@var{library}_LIBADD} variable. This should be used for objects
5042 determined by @command{configure}. Again from @code{cpio}:
5044 @c Keep in sync with pr401c.test.
5046 libcpio_a_LIBADD = $(LIBOBJS) $(ALLOCA)
5049 In addition, sources for extra objects that will not exist until
5050 configure-time must be added to the @code{BUILT_SOURCES} variable
5053 Building a static library is done by compiling all object files, then
5054 by invoking @samp{$(AR) $(ARFLAGS)} followed by the name of the
5055 library and the list of objects, and finally by calling
5056 @samp{$(RANLIB)} on that library. You should call
5057 @code{AC_PROG_RANLIB} from your @file{configure.ac} to define
5058 @code{RANLIB} (Automake will complain otherwise). You should also
5059 call @code{AM_PROG_AR} to define @code{AR}, in order to support unusual
5060 archivers such as Microsoft lib. @code{ARFLAGS} will default to
5061 @code{cru}; you can override this variable by setting it in your
5062 @file{Makefile.am} or by @code{AC_SUBST}ing it from your
5063 @file{configure.ac}. You can override the @code{AR} variable by
5064 defining a per-library @code{maude_AR} variable (@pxref{Program and
5065 Library Variables}).
5067 @cindex Empty libraries
5068 Be careful when selecting library components conditionally. Because
5069 building an empty library is not portable, you should ensure that any
5070 library always contains at least one object.
5072 To use a static library when building a program, add it to
5073 @code{LDADD} for this program. In the following example, the program
5074 @file{cpio} is statically linked with the library @file{libcpio.a}.
5077 noinst_LIBRARIES = libcpio.a
5078 libcpio_a_SOURCES = @dots{}
5081 cpio_SOURCES = cpio.c @dots{}
5082 cpio_LDADD = libcpio.a
5086 @node A Shared Library
5087 @section Building a Shared Library
5089 @cindex Shared libraries, support for
5091 Building shared libraries portably is a relatively complex matter.
5092 For this reason, GNU Libtool (@pxref{Top, , Introduction, libtool, The
5093 Libtool Manual}) was created to help build shared libraries in a
5094 platform-independent way.
5097 * Libtool Concept:: Introducing Libtool
5098 * Libtool Libraries:: Declaring Libtool Libraries
5099 * Conditional Libtool Libraries:: Building Libtool Libraries Conditionally
5100 * Conditional Libtool Sources:: Choosing Library Sources Conditionally
5101 * Libtool Convenience Libraries:: Building Convenience Libtool Libraries
5102 * Libtool Modules:: Building Libtool Modules
5103 * Libtool Flags:: Using _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS
5104 * LTLIBOBJS:: Using $(LTLIBOBJS) and $(LTALLOCA)
5105 * Libtool Issues:: Common Issues Related to Libtool's Use
5108 @node Libtool Concept
5109 @subsection The Libtool Concept
5111 @cindex @command{libtool}, introduction
5112 @cindex libtool library, definition
5113 @cindex suffix @file{.la}, defined
5114 @cindex @file{.la} suffix, defined
5116 Libtool abstracts shared and static libraries into a unified concept
5117 henceforth called @dfn{libtool libraries}. Libtool libraries are
5118 files using the @file{.la} suffix, and can designate a static library,
5119 a shared library, or maybe both. Their exact nature cannot be
5120 determined until @file{./configure} is run: not all platforms support
5121 all kinds of libraries, and users can explicitly select which
5122 libraries should be built. (However the package's maintainers can
5123 tune the default, @pxref{AC_PROG_LIBTOOL, , The @code{AC_PROG_LIBTOOL}
5124 macro, libtool, The Libtool Manual}.)
5126 @cindex suffix @file{.lo}, defined
5127 Because object files for shared and static libraries must be compiled
5128 differently, libtool is also used during compilation. Object files
5129 built by libtool are called @dfn{libtool objects}: these are files
5130 using the @file{.lo} suffix. Libtool libraries are built from these
5133 You should not assume anything about the structure of @file{.la} or
5134 @file{.lo} files and how libtool constructs them: this is libtool's
5135 concern, and the last thing one wants is to learn about libtool's
5136 guts. However the existence of these files matters, because they are
5137 used as targets and dependencies in @file{Makefile}s rules when
5138 building libtool libraries. There are situations where you may have
5139 to refer to these, for instance when expressing dependencies for
5140 building source files conditionally (@pxref{Conditional Libtool
5143 @cindex @file{libltdl}, introduction
5145 People considering writing a plug-in system, with dynamically loaded
5146 modules, should look into @file{libltdl}: libtool's dlopening library
5147 (@pxref{Using libltdl, , Using libltdl, libtool, The Libtool Manual}).
5148 This offers a portable dlopening facility to load libtool libraries
5149 dynamically, and can also achieve static linking where unavoidable.
5151 Before we discuss how to use libtool with Automake in details, it
5152 should be noted that the libtool manual also has a section about how
5153 to use Automake with libtool (@pxref{Using Automake, , Using Automake
5154 with Libtool, libtool, The Libtool Manual}).
5156 @node Libtool Libraries
5157 @subsection Building Libtool Libraries
5159 @cindex @code{_LTLIBRARIES} primary, defined
5160 @cindex @code{LTLIBRARIES} primary, defined
5161 @cindex Primary variable, @code{LTLIBRARIES}
5162 @cindex Example of shared libraries
5163 @vindex lib_LTLIBRARIES
5164 @vindex pkglib_LTLIBRARIES
5165 @vindex _LTLIBRARIES
5167 Automake uses libtool to build libraries declared with the
5168 @code{LTLIBRARIES} primary. Each @code{_LTLIBRARIES} variable is a
5169 list of libtool libraries to build. For instance, to create a libtool
5170 library named @file{libgettext.la}, and install it in @code{libdir},
5174 lib_LTLIBRARIES = libgettext.la
5175 libgettext_la_SOURCES = gettext.c gettext.h @dots{}
5178 Automake predefines the variable @code{pkglibdir}, so you can use
5179 @code{pkglib_LTLIBRARIES} to install libraries in
5180 @samp{$(libdir)/@@PACKAGE@@/}.
5182 If @file{gettext.h} is a public header file that needs to be installed
5183 in order for people to use the library, it should be declared using a
5184 @code{_HEADERS} variable, not in @code{libgettext_la_SOURCES}.
5185 Headers listed in the latter should be internal headers that are not
5186 part of the public interface.
5189 lib_LTLIBRARIES = libgettext.la
5190 libgettext_la_SOURCES = gettext.c @dots{}
5191 include_HEADERS = gettext.h @dots{}
5194 A package can build and install such a library along with other
5195 programs that use it. This dependency should be specified using
5196 @code{LDADD}. The following example builds a program named
5197 @file{hello} that is linked with @file{libgettext.la}.
5200 lib_LTLIBRARIES = libgettext.la
5201 libgettext_la_SOURCES = gettext.c @dots{}
5203 bin_PROGRAMS = hello
5204 hello_SOURCES = hello.c @dots{}
5205 hello_LDADD = libgettext.la
5209 Whether @file{hello} is statically or dynamically linked with
5210 @file{libgettext.la} is not yet known: this will depend on the
5211 configuration of libtool and the capabilities of the host.
5214 @node Conditional Libtool Libraries
5215 @subsection Building Libtool Libraries Conditionally
5216 @cindex libtool libraries, conditional
5217 @cindex conditional libtool libraries
5219 Like conditional programs (@pxref{Conditional Programs}), there are
5220 two main ways to build conditional libraries: using Automake
5221 conditionals or using Autoconf @code{AC_SUBST}itutions.
5223 The important implementation detail you have to be aware of is that
5224 the place where a library will be installed matters to libtool: it
5225 needs to be indicated @emph{at link-time} using the @option{-rpath}
5228 For libraries whose destination directory is known when Automake runs,
5229 Automake will automatically supply the appropriate @option{-rpath}
5230 option to libtool. This is the case for libraries listed explicitly in
5231 some installable @code{_LTLIBRARIES} variables such as
5232 @code{lib_LTLIBRARIES}.
5234 However, for libraries determined at configure time (and thus
5235 mentioned in @code{EXTRA_LTLIBRARIES}), Automake does not know the
5236 final installation directory. For such libraries you must add the
5237 @option{-rpath} option to the appropriate @code{_LDFLAGS} variable by
5240 The examples below illustrate the differences between these two methods.
5242 Here is an example where @code{WANTEDLIBS} is an @code{AC_SUBST}ed
5243 variable set at @file{./configure}-time to either @file{libfoo.la},
5244 @file{libbar.la}, both, or none. Although @samp{$(WANTEDLIBS)}
5245 appears in the @code{lib_LTLIBRARIES}, Automake cannot guess it
5246 relates to @file{libfoo.la} or @file{libbar.la} at the time it creates
5247 the link rule for these two libraries. Therefore the @option{-rpath}
5248 argument must be explicitly supplied.
5250 @c Keep in sync with ltcond.test.
5252 EXTRA_LTLIBRARIES = libfoo.la libbar.la
5253 lib_LTLIBRARIES = $(WANTEDLIBS)
5254 libfoo_la_SOURCES = foo.c @dots{}
5255 libfoo_la_LDFLAGS = -rpath '$(libdir)'
5256 libbar_la_SOURCES = bar.c @dots{}
5257 libbar_la_LDFLAGS = -rpath '$(libdir)'
5260 Here is how the same @file{Makefile.am} would look using Automake
5261 conditionals named @code{WANT_LIBFOO} and @code{WANT_LIBBAR}. Now
5262 Automake is able to compute the @option{-rpath} setting itself, because
5263 it's clear that both libraries will end up in @samp{$(libdir)} if they
5266 @c Keep in sync with ltcond.test.
5270 lib_LTLIBRARIES += libfoo.la
5273 lib_LTLIBRARIES += libbar.la
5275 libfoo_la_SOURCES = foo.c @dots{}
5276 libbar_la_SOURCES = bar.c @dots{}
5279 @node Conditional Libtool Sources
5280 @subsection Libtool Libraries with Conditional Sources
5282 Conditional compilation of sources in a library can be achieved in the
5283 same way as conditional compilation of sources in a program
5284 (@pxref{Conditional Sources}). The only difference is that
5285 @code{_LIBADD} should be used instead of @code{_LDADD} and that it
5286 should mention libtool objects (@file{.lo} files).
5288 So, to mimic the @file{hello} example from @ref{Conditional Sources},
5289 we could build a @file{libhello.la} library using either
5290 @file{hello-linux.c} or @file{hello-generic.c} with the following
5293 @c Keep in sync with ltcond2.test.
5295 lib_LTLIBRARIES = libhello.la
5296 libhello_la_SOURCES = hello-common.c
5297 EXTRA_libhello_la_SOURCES = hello-linux.c hello-generic.c
5298 libhello_la_LIBADD = $(HELLO_SYSTEM)
5299 libhello_la_DEPENDENCIES = $(HELLO_SYSTEM)
5303 And make sure @command{configure} defines @code{HELLO_SYSTEM} as
5304 either @file{hello-linux.lo} or @file{hello-@-generic.lo}.
5306 Or we could simply use an Automake conditional as follows.
5308 @c Keep in sync with ltcond2.test.
5310 lib_LTLIBRARIES = libhello.la
5311 libhello_la_SOURCES = hello-common.c
5313 libhello_la_SOURCES += hello-linux.c
5315 libhello_la_SOURCES += hello-generic.c
5319 @node Libtool Convenience Libraries
5320 @subsection Libtool Convenience Libraries
5321 @cindex convenience libraries, libtool
5322 @cindex libtool convenience libraries
5323 @vindex noinst_LTLIBRARIES
5324 @vindex check_LTLIBRARIES
5326 Sometimes you want to build libtool libraries that should not be
5327 installed. These are called @dfn{libtool convenience libraries} and
5328 are typically used to encapsulate many sublibraries, later gathered
5329 into one big installed library.
5331 Libtool convenience libraries are declared by directory-less variables
5332 such as @code{noinst_LTLIBRARIES}, @code{check_LTLIBRARIES}, or even
5333 @code{EXTRA_LTLIBRARIES}. Unlike installed libtool libraries they do
5334 not need an @option{-rpath} flag at link time (actually this is the only
5337 Convenience libraries listed in @code{noinst_LTLIBRARIES} are always
5338 built. Those listed in @code{check_LTLIBRARIES} are built only upon
5339 @samp{make check}. Finally, libraries listed in
5340 @code{EXTRA_LTLIBRARIES} are never built explicitly: Automake outputs
5341 rules to build them, but if the library does not appear as a Makefile
5342 dependency anywhere it won't be built (this is why
5343 @code{EXTRA_LTLIBRARIES} is used for conditional compilation).
5345 Here is a sample setup merging libtool convenience libraries from
5346 subdirectories into one main @file{libtop.la} library.
5348 @c Keep in sync with ltconv.test.
5350 # -- Top-level Makefile.am --
5351 SUBDIRS = sub1 sub2 @dots{}
5352 lib_LTLIBRARIES = libtop.la
5354 libtop_la_LIBADD = \
5359 # -- sub1/Makefile.am --
5360 noinst_LTLIBRARIES = libsub1.la
5361 libsub1_la_SOURCES = @dots{}
5363 # -- sub2/Makefile.am --
5364 # showing nested convenience libraries
5365 SUBDIRS = sub2.1 sub2.2 @dots{}
5366 noinst_LTLIBRARIES = libsub2.la
5367 libsub2_la_SOURCES =
5368 libsub2_la_LIBADD = \
5374 When using such setup, beware that @command{automake} will assume
5375 @file{libtop.la} is to be linked with the C linker. This is because
5376 @code{libtop_la_SOURCES} is empty, so @command{automake} picks C as
5377 default language. If @code{libtop_la_SOURCES} was not empty,
5378 @command{automake} would select the linker as explained in @ref{How
5379 the Linker is Chosen}.
5381 If one of the sublibraries contains non-C source, it is important that
5382 the appropriate linker be chosen. One way to achieve this is to
5383 pretend that there is such a non-C file among the sources of the
5384 library, thus forcing @command{automake} to select the appropriate
5385 linker. Here is the top-level @file{Makefile} of our example updated
5386 to force C++ linking.
5389 SUBDIRS = sub1 sub2 @dots{}
5390 lib_LTLIBRARIES = libtop.la
5392 # Dummy C++ source to cause C++ linking.
5393 nodist_EXTRA_libtop_la_SOURCES = dummy.cxx
5394 libtop_la_LIBADD = \
5400 @samp{EXTRA_*_SOURCES} variables are used to keep track of source
5401 files that might be compiled (this is mostly useful when doing
5402 conditional compilation using @code{AC_SUBST}, @pxref{Conditional
5403 Libtool Sources}), and the @code{nodist_} prefix means the listed
5404 sources are not to be distributed (@pxref{Program and Library
5405 Variables}). In effect the file @file{dummy.cxx} does not need to
5406 exist in the source tree. Of course if you have some real source file
5407 to list in @code{libtop_la_SOURCES} there is no point in cheating with
5408 @code{nodist_EXTRA_libtop_la_SOURCES}.
5411 @node Libtool Modules
5412 @subsection Libtool Modules
5413 @cindex modules, libtool
5414 @cindex libtool modules
5415 @cindex @option{-module}, libtool
5417 These are libtool libraries meant to be dlopened. They are
5418 indicated to libtool by passing @option{-module} at link-time.
5421 pkglib_LTLIBRARIES = mymodule.la
5422 mymodule_la_SOURCES = doit.c
5423 mymodule_la_LDFLAGS = -module
5426 Ordinarily, Automake requires that a library's name start with
5427 @code{lib}. However, when building a dynamically loadable module you
5428 might wish to use a "nonstandard" name. Automake will not complain
5429 about such nonstandard names if it knows the library being built is a
5430 libtool module, i.e., if @option{-module} explicitly appears in the
5431 library's @code{_LDFLAGS} variable (or in the common @code{AM_LDFLAGS}
5432 variable when no per-library @code{_LDFLAGS} variable is defined).
5434 As always, @code{AC_SUBST} variables are black boxes to Automake since
5435 their values are not yet known when @command{automake} is run.
5436 Therefore if @option{-module} is set via such a variable, Automake
5437 cannot notice it and will proceed as if the library was an ordinary
5438 libtool library, with strict naming.
5440 If @code{mymodule_la_SOURCES} is not specified, then it defaults to
5441 the single file @file{mymodule.c} (@pxref{Default _SOURCES}).
5444 @subsection @code{_LIBADD}, @code{_LDFLAGS}, and @code{_LIBTOOLFLAGS}
5445 @cindex @code{_LIBADD}, libtool
5446 @cindex @code{_LDFLAGS}, libtool
5447 @cindex @code{_LIBTOOLFLAGS}, libtool
5448 @vindex AM_LIBTOOLFLAGS
5449 @vindex LIBTOOLFLAGS
5450 @vindex maude_LIBTOOLFLAGS
5452 As shown in previous sections, the @samp{@var{library}_LIBADD}
5453 variable should be used to list extra libtool objects (@file{.lo}
5454 files) or libtool libraries (@file{.la}) to add to @var{library}.
5456 The @samp{@var{library}_LDFLAGS} variable is the place to list
5457 additional libtool linking flags, such as @option{-version-info},
5458 @option{-static}, and a lot more. @xref{Link mode, , Link mode,
5459 libtool, The Libtool Manual}.
5461 The @command{libtool} command has two kinds of options: mode-specific
5462 options and generic options. Mode-specific options such as the
5463 aforementioned linking flags should be lumped with the other flags
5464 passed to the tool invoked by @command{libtool} (hence the use of
5465 @samp{@var{library}_LDFLAGS} for libtool linking flags). Generic
5466 options include @option{--tag=@var{tag}} and @option{--silent}
5467 (@pxref{Invoking libtool, , Invoking @command{libtool}, libtool, The
5468 Libtool Manual} for more options) should appear before the mode
5469 selection on the command line; in @file{Makefile.am}s they should
5470 be listed in the @samp{@var{library}_LIBTOOLFLAGS} variable.
5472 If @samp{@var{library}_LIBTOOLFLAGS} is not defined, then the variable
5473 @code{AM_LIBTOOLFLAGS} is used instead.
5475 These flags are passed to libtool after the @option{--tag=@var{tag}}
5476 option computed by Automake (if any), so
5477 @samp{@var{library}_LIBTOOLFLAGS} (or @code{AM_LIBTOOLFLAGS}) is a
5478 good place to override or supplement the @option{--tag=@var{tag}}
5481 The libtool rules also use a @code{LIBTOOLFLAGS} variable that should
5482 not be set in @file{Makefile.am}: this is a user variable (@pxref{Flag
5483 Variables Ordering}. It allows users to run @samp{make
5484 LIBTOOLFLAGS=--silent}, for instance. Note that the verbosity of
5485 @command{libtool} can also be influenced with the Automake
5486 @option{silent-rules} option (@pxref{Options}).
5489 @node LTLIBOBJS, Libtool Issues, Libtool Flags, A Shared Library
5490 @subsection @code{LTLIBOBJS} and @code{LTALLOCA}
5491 @cindex @code{LTLIBOBJS}, special handling
5492 @cindex @code{LIBOBJS}, and Libtool
5493 @cindex @code{LTALLOCA}, special handling
5494 @cindex @code{ALLOCA}, and Libtool
5501 Where an ordinary library might include @samp{$(LIBOBJS)} or
5502 @samp{$(ALLOCA)} (@pxref{LIBOBJS}), a libtool library must use
5503 @samp{$(LTLIBOBJS)} or @samp{$(LTALLOCA)}. This is required because
5504 the object files that libtool operates on do not necessarily end in
5507 Nowadays, the computation of @code{LTLIBOBJS} from @code{LIBOBJS} is
5508 performed automatically by Autoconf (@pxref{AC_LIBOBJ vs LIBOBJS, ,
5509 @code{AC_LIBOBJ} vs.@: @code{LIBOBJS}, autoconf, The Autoconf Manual}).
5511 @node Libtool Issues
5512 @subsection Common Issues Related to Libtool's Use
5515 * Error required file ltmain.sh not found:: The need to run libtoolize
5516 * Objects created both with libtool and without:: Avoid a specific build race
5519 @node Error required file ltmain.sh not found
5520 @subsubsection Error: @samp{required file `./ltmain.sh' not found}
5521 @cindex @file{ltmain.sh} not found
5522 @cindex @command{libtoolize}, no longer run by @command{automake}
5523 @cindex @command{libtoolize} and @command{autoreconf}
5524 @cindex @command{autoreconf} and @command{libtoolize}
5525 @cindex @file{bootstrap.sh} and @command{autoreconf}
5526 @cindex @file{autogen.sh} and @command{autoreconf}
5528 Libtool comes with a tool called @command{libtoolize} that will
5529 install libtool's supporting files into a package. Running this
5530 command will install @file{ltmain.sh}. You should execute it before
5531 @command{aclocal} and @command{automake}.
5533 People upgrading old packages to newer autotools are likely to face
5534 this issue because older Automake versions used to call
5535 @command{libtoolize}. Therefore old build scripts do not call
5536 @command{libtoolize}.
5538 Since Automake 1.6, it has been decided that running
5539 @command{libtoolize} was none of Automake's business. Instead, that
5540 functionality has been moved into the @command{autoreconf} command
5541 (@pxref{autoreconf Invocation, , Using @command{autoreconf}, autoconf,
5542 The Autoconf Manual}). If you do not want to remember what to run and
5543 when, just learn the @command{autoreconf} command. Hopefully,
5544 replacing existing @file{bootstrap.sh} or @file{autogen.sh} scripts by
5545 a call to @command{autoreconf} should also free you from any similar
5546 incompatible change in the future.
5548 @node Objects created both with libtool and without
5549 @subsubsection Objects @samp{created with both libtool and without}
5551 Sometimes, the same source file is used both to build a libtool
5552 library and to build another non-libtool target (be it a program or
5555 Let's consider the following @file{Makefile.am}.
5559 prog_SOURCES = prog.c foo.c @dots{}
5561 lib_LTLIBRARIES = libfoo.la
5562 libfoo_la_SOURCES = foo.c @dots{}
5566 (In this trivial case the issue could be avoided by linking
5567 @file{libfoo.la} with @file{prog} instead of listing @file{foo.c} in
5568 @code{prog_SOURCES}. But let's assume we really want to keep
5569 @file{prog} and @file{libfoo.la} separate.)
5571 Technically, it means that we should build @file{foo.$(OBJEXT)} for
5572 @file{prog}, and @file{foo.lo} for @file{libfoo.la}. The problem is
5573 that in the course of creating @file{foo.lo}, libtool may erase (or
5574 replace) @file{foo.$(OBJEXT)}, and this cannot be avoided.
5576 Therefore, when Automake detects this situation it will complain
5577 with a message such as
5579 object `foo.$(OBJEXT)' created both with libtool and without
5582 A workaround for this issue is to ensure that these two objects get
5583 different basenames. As explained in @ref{Renamed Objects}, this
5584 happens automatically when per-targets flags are used.
5588 prog_SOURCES = prog.c foo.c @dots{}
5589 prog_CFLAGS = $(AM_CFLAGS)
5591 lib_LTLIBRARIES = libfoo.la
5592 libfoo_la_SOURCES = foo.c @dots{}
5596 Adding @samp{prog_CFLAGS = $(AM_CFLAGS)} is almost a no-op, because
5597 when the @code{prog_CFLAGS} is defined, it is used instead of
5598 @code{AM_CFLAGS}. However as a side effect it will cause
5599 @file{prog.c} and @file{foo.c} to be compiled as
5600 @file{prog-prog.$(OBJEXT)} and @file{prog-foo.$(OBJEXT)}, which solves
5603 @node Program and Library Variables
5604 @section Program and Library Variables
5606 Associated with each program is a collection of variables that can be
5607 used to modify how that program is built. There is a similar list of
5608 such variables for each library. The canonical name of the program (or
5609 library) is used as a base for naming these variables.
5611 In the list below, we use the name ``maude'' to refer to the program or
5612 library. In your @file{Makefile.am} you would replace this with the
5613 canonical name of your program. This list also refers to ``maude'' as a
5614 program, but in general the same rules apply for both static and dynamic
5615 libraries; the documentation below notes situations where programs and
5620 This variable, if it exists, lists all the source files that are
5621 compiled to build the program. These files are added to the
5622 distribution by default. When building the program, Automake will cause
5623 each source file to be compiled to a single @file{.o} file (or
5624 @file{.lo} when using libtool). Normally these object files are named
5625 after the source file, but other factors can change this. If a file in
5626 the @code{_SOURCES} variable has an unrecognized extension, Automake
5627 will do one of two things with it. If a suffix rule exists for turning
5628 files with the unrecognized extension into @file{.o} files, then
5629 @command{automake} will treat this file as it will any other source file
5630 (@pxref{Support for Other Languages}). Otherwise, the file will be
5631 ignored as though it were a header file.
5633 The prefixes @code{dist_} and @code{nodist_} can be used to control
5634 whether files listed in a @code{_SOURCES} variable are distributed.
5635 @code{dist_} is redundant, as sources are distributed by default, but it
5636 can be specified for clarity if desired.
5638 It is possible to have both @code{dist_} and @code{nodist_} variants of
5639 a given @code{_SOURCES} variable at once; this lets you easily
5640 distribute some files and not others, for instance:
5643 nodist_maude_SOURCES = nodist.c
5644 dist_maude_SOURCES = dist-me.c
5647 By default the output file (on Unix systems, the @file{.o} file) will
5648 be put into the current build directory. However, if the option
5649 @option{subdir-objects} is in effect in the current directory then the
5650 @file{.o} file will be put into the subdirectory named after the
5651 source file. For instance, with @option{subdir-objects} enabled,
5652 @file{sub/dir/file.c} will be compiled to @file{sub/dir/file.o}. Some
5653 people prefer this mode of operation. You can specify
5654 @option{subdir-objects} in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
5655 @cindex Subdirectory, objects in
5656 @cindex Objects in subdirectory
5659 @item EXTRA_maude_SOURCES
5660 Automake needs to know the list of files you intend to compile
5661 @emph{statically}. For one thing, this is the only way Automake has of
5662 knowing what sort of language support a given @file{Makefile.in}
5663 requires. @footnote{There are other, more obscure reasons for
5664 this limitation as well.} This means that, for example, you can't put a
5665 configure substitution like @samp{@@my_sources@@} into a @samp{_SOURCES}
5666 variable. If you intend to conditionally compile source files and use
5667 @file{configure} to substitute the appropriate object names into, e.g.,
5668 @code{_LDADD} (see below), then you should list the corresponding source
5669 files in the @code{EXTRA_} variable.
5671 This variable also supports @code{dist_} and @code{nodist_} prefixes.
5672 For instance, @code{nodist_EXTRA_maude_SOURCES} would list extra
5673 sources that may need to be built, but should not be distributed.
5676 A static library is created by default by invoking @samp{$(AR)
5677 $(ARFLAGS)} followed by the name of the library and then the objects
5678 being put into the library. You can override this by setting the
5679 @code{_AR} variable. This is usually used with C++; some C++
5680 compilers require a special invocation in order to instantiate all the
5681 templates that should go into a library. For instance, the SGI C++
5682 compiler likes this variable set like so:
5684 libmaude_a_AR = $(CXX) -ar -o
5688 Extra objects can be added to a @emph{library} using the @code{_LIBADD}
5689 variable. For instance, this should be used for objects determined by
5690 @command{configure} (@pxref{A Library}).
5692 In the case of libtool libraries, @code{maude_LIBADD} can also refer
5693 to other libtool libraries.
5696 Extra objects (@file{*.$(OBJEXT)}) and libraries (@file{*.a},
5697 @file{*.la}) can be added to a @emph{program} by listing them in the
5698 @code{_LDADD} variable. For instance, this should be used for objects
5699 determined by @command{configure} (@pxref{Linking}).
5701 @code{_LDADD} and @code{_LIBADD} are inappropriate for passing
5702 program-specific linker flags (except for @option{-l}, @option{-L},
5703 @option{-dlopen} and @option{-dlpreopen}). Use the @code{_LDFLAGS} variable
5706 For instance, if your @file{configure.ac} uses @code{AC_PATH_XTRA}, you
5707 could link your program against the X libraries like so:
5710 maude_LDADD = $(X_PRE_LIBS) $(X_LIBS) $(X_EXTRA_LIBS)
5713 We recommend that you use @option{-l} and @option{-L} only when
5714 referring to third-party libraries, and give the explicit file names
5715 of any library built by your package. Doing so will ensure that
5716 @code{maude_DEPENDENCIES} (see below) is correctly defined by default.
5719 This variable is used to pass extra flags to the link step of a program
5720 or a shared library. It overrides the @code{AM_LDFLAGS} variable.
5722 @item maude_LIBTOOLFLAGS
5723 This variable is used to pass extra options to @command{libtool}.
5724 It overrides the @code{AM_LIBTOOLFLAGS} variable.
5725 These options are output before @command{libtool}'s @option{--mode=@var{mode}}
5726 option, so they should not be mode-specific options (those belong to
5727 the compiler or linker flags). @xref{Libtool Flags}.
5729 @item maude_DEPENDENCIES
5730 @itemx EXTRA_maude_DEPENDENCIES
5731 It is also occasionally useful to have a target (program or library)
5732 depend on some other file that is not actually part of that target.
5733 This can be done using the @code{_DEPENDENCIES} variable. Each
5734 target depends on the contents of such a variable, but no further
5735 interpretation is done.
5737 Since these dependencies are associated to the link rule used to
5738 create the programs they should normally list files used by the link
5739 command. That is @file{*.$(OBJEXT)}, @file{*.a}, or @file{*.la} files
5740 for programs; @file{*.lo} and @file{*.la} files for Libtool libraries;
5741 and @file{*.$(OBJEXT)} files for static libraries. In rare cases you
5742 may need to add other kinds of files such as linker scripts, but
5743 @emph{listing a source file in @code{_DEPENDENCIES} is wrong}. If
5744 some source file needs to be built before all the components of a
5745 program are built, consider using the @code{BUILT_SOURCES} variable
5748 If @code{_DEPENDENCIES} is not supplied, it is computed by Automake.
5749 The automatically-assigned value is the contents of @code{_LDADD} or
5750 @code{_LIBADD}, with most configure substitutions, @option{-l}, @option{-L},
5751 @option{-dlopen} and @option{-dlpreopen} options removed. The configure
5752 substitutions that are left in are only @samp{$(LIBOBJS)} and
5753 @samp{$(ALLOCA)}; these are left because it is known that they will not
5754 cause an invalid value for @code{_DEPENDENCIES} to be generated.
5756 @code{_DEPENDENCIES} is more likely used to perform conditional
5757 compilation using an @code{AC_SUBST} variable that contains a list of
5758 objects. @xref{Conditional Sources}, and @ref{Conditional Libtool
5761 The @code{EXTRA_*_DEPENDENCIES} variable may be useful for cases where
5762 you merely want to augment the @command{automake}-generated
5763 @code{_DEPENDENCIES} variable rather than replacing it.
5766 You can override the linker on a per-program basis. By default the
5767 linker is chosen according to the languages used by the program. For
5768 instance, a program that includes C++ source code would use the C++
5769 compiler to link. The @code{_LINK} variable must hold the name of a
5770 command that can be passed all the @file{.o} file names and libraries
5771 to link against as arguments. Note that the name of the underlying
5772 program is @emph{not} passed to @code{_LINK}; typically one uses
5776 maude_LINK = $(CCLD) -magic -o $@@
5779 If a @code{_LINK} variable is not supplied, it may still be generated
5780 and used by Automake due to the use of per-target link flags such as
5781 @code{_CFLAGS}, @code{_LDFLAGS} or @code{_LIBTOOLFLAGS}, in cases where
5784 @item maude_CCASFLAGS
5786 @itemx maude_CPPFLAGS
5787 @itemx maude_CXXFLAGS
5789 @itemx maude_GCJFLAGS
5791 @itemx maude_OBJCFLAGS
5793 @itemx maude_UPCFLAGS
5795 @cindex per-target compilation flags, defined
5796 Automake allows you to set compilation flags on a per-program (or
5797 per-library) basis. A single source file can be included in several
5798 programs, and it will potentially be compiled with different flags for
5799 each program. This works for any language directly supported by
5800 Automake. These @dfn{per-target compilation flags} are
5810 @samp{_UPCFLAGS}, and
5813 When using a per-target compilation flag, Automake will choose a
5814 different name for the intermediate object files. Ordinarily a file
5815 like @file{sample.c} will be compiled to produce @file{sample.o}.
5816 However, if the program's @code{_CFLAGS} variable is set, then the
5817 object file will be named, for instance, @file{maude-sample.o}. (See
5818 also @ref{Renamed Objects}.) The use of per-target compilation flags
5819 with C sources requires that the macro @code{AM_PROG_CC_C_O} be called
5820 from @file{configure.ac}.
5822 In compilations with per-target flags, the ordinary @samp{AM_} form of
5823 the flags variable is @emph{not} automatically included in the
5824 compilation (however, the user form of the variable @emph{is} included).
5825 So for instance, if you want the hypothetical @file{maude} compilations
5826 to also use the value of @code{AM_CFLAGS}, you would need to write:
5829 maude_CFLAGS = @dots{} your flags @dots{} $(AM_CFLAGS)
5832 @xref{Flag Variables Ordering}, for more discussion about the
5833 interaction between user variables, @samp{AM_} shadow variables, and
5834 per-target variables.
5836 @item maude_SHORTNAME
5837 On some platforms the allowable file names are very short. In order to
5838 support these systems and per-target compilation flags at the same
5839 time, Automake allows you to set a ``short name'' that will influence
5840 how intermediate object files are named. For instance, in the following
5844 bin_PROGRAMS = maude
5845 maude_CPPFLAGS = -DSOMEFLAG
5847 maude_SOURCES = sample.c @dots{}
5851 the object file would be named @file{m-sample.o} rather than
5852 @file{maude-sample.o}.
5854 This facility is rarely needed in practice,
5855 and we recommend avoiding it until you find it is required.
5858 @node Default _SOURCES
5859 @section Default @code{_SOURCES}
5863 @cindex @code{_SOURCES}, default
5864 @cindex default @code{_SOURCES}
5865 @vindex AM_DEFAULT_SOURCE_EXT
5867 @code{_SOURCES} variables are used to specify source files of programs
5868 (@pxref{A Program}), libraries (@pxref{A Library}), and Libtool
5869 libraries (@pxref{A Shared Library}).
5871 When no such variable is specified for a target, Automake will define
5872 one itself. The default is to compile a single C file whose base name
5873 is the name of the target itself, with any extension replaced by
5874 @code{AM_DEFAULT_SOURCE_EXT}, which defaults to @file{.c}.
5876 For example if you have the following somewhere in your
5877 @file{Makefile.am} with no corresponding @code{libfoo_a_SOURCES}:
5880 lib_LIBRARIES = libfoo.a sub/libc++.a
5884 @file{libfoo.a} will be built using a default source file named
5885 @file{libfoo.c}, and @file{sub/libc++.a} will be built from
5886 @file{sub/libc++.c}. (In older versions @file{sub/libc++.a}
5887 would be built from @file{sub_libc___a.c}, i.e., the default source
5888 was the canonized name of the target, with @file{.c} appended.
5889 We believe the new behavior is more sensible, but for backward
5890 compatibility @command{automake} will use the old name if a file or a rule
5891 with that name exists and @code{AM_DEFAULT_SOURCE_EXT} is not used.)
5893 @cindex @code{check_PROGRAMS} example
5894 @vindex check_PROGRAMS
5895 Default sources are mainly useful in test suites, when building many
5896 test programs each from a single source. For instance, in
5899 check_PROGRAMS = test1 test2 test3
5900 AM_DEFAULT_SOURCE_EXT = .cpp
5904 @file{test1}, @file{test2}, and @file{test3} will be built
5905 from @file{test1.cpp}, @file{test2.cpp}, and @file{test3.cpp}.
5906 Without the last line, they will be built from @file{test1.c},
5907 @file{test2.c}, and @file{test3.c}.
5909 @cindex Libtool modules, default source example
5910 @cindex default source, Libtool modules example
5911 Another case where this is convenient is building many Libtool modules
5912 (@file{module@var{n}.la}), each defined in its own file
5913 (@file{module@var{n}.c}).
5916 AM_LDFLAGS = -module
5917 lib_LTLIBRARIES = module1.la module2.la module3.la
5920 @cindex empty @code{_SOURCES}
5921 @cindex @code{_SOURCES}, empty
5922 Finally, there is one situation where this default source computation
5923 needs to be avoided: when a target should not be built from sources.
5924 We already saw such an example in @ref{true}; this happens when all
5925 the constituents of a target have already been compiled and just need
5926 to be combined using a @code{_LDADD} variable. Then it is necessary
5927 to define an empty @code{_SOURCES} variable, so that @command{automake}
5928 does not compute a default.
5931 bin_PROGRAMS = target
5933 target_LDADD = libmain.a libmisc.a
5937 @section Special handling for @code{LIBOBJS} and @code{ALLOCA}
5939 @cindex @code{LIBOBJS}, example
5940 @cindex @code{ALLOCA}, example
5941 @cindex @code{LIBOBJS}, special handling
5942 @cindex @code{ALLOCA}, special handling
5948 The @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} variables list object
5949 files that should be compiled into the project to provide an
5950 implementation for functions that are missing or broken on the host
5951 system. They are substituted by @file{configure}.
5955 These variables are defined by Autoconf macros such as
5956 @code{AC_LIBOBJ}, @code{AC_REPLACE_FUNCS} (@pxref{Generic Functions, ,
5957 Generic Function Checks, autoconf, The Autoconf Manual}), or
5958 @code{AC_FUNC_ALLOCA} (@pxref{Particular Functions, , Particular
5959 Function Checks, autoconf, The Autoconf Manual}). Many other Autoconf
5960 macros call @code{AC_LIBOBJ} or @code{AC_REPLACE_FUNCS} to
5961 populate @samp{$(LIBOBJS)}.
5963 @acindex AC_LIBSOURCE
5965 Using these variables is very similar to doing conditional compilation
5966 using @code{AC_SUBST} variables, as described in @ref{Conditional
5967 Sources}. That is, when building a program, @samp{$(LIBOBJS)} and
5968 @samp{$(ALLOCA)} should be added to the associated @samp{*_LDADD}
5969 variable, or to the @samp{*_LIBADD} variable when building a library.
5970 However there is no need to list the corresponding sources in
5971 @samp{EXTRA_*_SOURCES} nor to define @samp{*_DEPENDENCIES}. Automake
5972 automatically adds @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} to the
5973 dependencies, and it will discover the list of corresponding source
5974 files automatically (by tracing the invocations of the
5975 @code{AC_LIBSOURCE} Autoconf macros). If you have already defined
5976 @samp{*_DEPENDENCIES} explicitly for an unrelated reason, then you
5977 either need to add these variables manually, or use
5978 @samp{EXTRA_*_DEPENDENCIES} instead of @samp{*_DEPENDENCIES}.
5980 These variables are usually used to build a portability library that
5981 is linked with all the programs of the project. We now review a
5982 sample setup. First, @file{configure.ac} contains some checks that
5983 affect either @code{LIBOBJS} or @code{ALLOCA}.
5988 AC_CONFIG_LIBOBJ_DIR([lib])
5990 AC_FUNC_MALLOC dnl May add malloc.$(OBJEXT) to LIBOBJS
5991 AC_FUNC_MEMCMP dnl May add memcmp.$(OBJEXT) to LIBOBJS
5992 AC_REPLACE_FUNCS([strdup]) dnl May add strdup.$(OBJEXT) to LIBOBJS
5993 AC_FUNC_ALLOCA dnl May add alloca.$(OBJEXT) to ALLOCA
6002 @acindex AC_CONFIG_LIBOBJ_DIR
6004 The @code{AC_CONFIG_LIBOBJ_DIR} tells Autoconf that the source files
6005 of these object files are to be found in the @file{lib/} directory.
6006 Automake can also use this information, otherwise it expects the
6007 source files are to be in the directory where the @samp{$(LIBOBJS)}
6008 and @samp{$(ALLOCA)} variables are used.
6010 The @file{lib/} directory should therefore contain @file{malloc.c},
6011 @file{memcmp.c}, @file{strdup.c}, @file{alloca.c}. Here is its
6017 noinst_LIBRARIES = libcompat.a
6018 libcompat_a_SOURCES =
6019 libcompat_a_LIBADD = $(LIBOBJS) $(ALLOCA)
6022 The library can have any name, of course, and anyway it is not going
6023 to be installed: it just holds the replacement versions of the missing
6024 or broken functions so we can later link them in. Many projects
6025 also include extra functions, specific to the project, in that
6026 library: they are simply added on the @code{_SOURCES} line.
6028 @cindex Empty libraries and @samp{$(LIBOBJS)}
6029 @cindex @samp{$(LIBOBJS)} and empty libraries
6030 There is a small trap here, though: @samp{$(LIBOBJS)} and
6031 @samp{$(ALLOCA)} might be empty, and building an empty library is not
6032 portable. You should ensure that there is always something to put in
6033 @file{libcompat.a}. Most projects will also add some utility
6034 functions in that directory, and list them in
6035 @code{libcompat_a_SOURCES}, so in practice @file{libcompat.a} cannot
6038 Finally here is how this library could be used from the @file{src/}
6044 # Link all programs in this directory with libcompat.a
6045 LDADD = ../lib/libcompat.a
6047 bin_PROGRAMS = tool1 tool2 @dots{}
6048 tool1_SOURCES = @dots{}
6049 tool2_SOURCES = @dots{}
6052 When option @option{subdir-objects} is not used, as in the above
6053 example, the variables @samp{$(LIBOBJS)} or @samp{$(ALLOCA)} can only
6054 be used in the directory where their sources lie. E.g., here it would
6055 be wrong to use @samp{$(LIBOBJS)} or @samp{$(ALLOCA)} in
6056 @file{src/Makefile.am}. However if both @option{subdir-objects} and
6057 @code{AC_CONFIG_LIBOBJ_DIR} are used, it is OK to use these variables
6058 in other directories. For instance @file{src/Makefile.am} could be
6064 AUTOMAKE_OPTIONS = subdir-objects
6065 LDADD = $(LIBOBJS) $(ALLOCA)
6067 bin_PROGRAMS = tool1 tool2 @dots{}
6068 tool1_SOURCES = @dots{}
6069 tool2_SOURCES = @dots{}
6072 Because @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} contain object
6073 file names that end with @samp{.$(OBJEXT)}, they are not suitable for
6074 Libtool libraries (where the expected object extension is @file{.lo}):
6075 @code{LTLIBOBJS} and @code{LTALLOCA} should be used instead.
6077 @code{LTLIBOBJS} is defined automatically by Autoconf and should not
6078 be defined by hand (as in the past), however at the time of writing
6079 @code{LTALLOCA} still needs to be defined from @code{ALLOCA} manually.
6080 @xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs.@: @code{LIBOBJS},
6081 autoconf, The Autoconf Manual}.
6084 @node Program Variables
6085 @section Variables used when building a program
6087 Occasionally it is useful to know which @file{Makefile} variables
6088 Automake uses for compilations, and in which order (@pxref{Flag
6089 Variables Ordering}); for instance, you might need to do your own
6090 compilation in some special cases.
6092 Some variables are inherited from Autoconf; these are @code{CC},
6093 @code{CFLAGS}, @code{CPPFLAGS}, @code{DEFS}, @code{LDFLAGS}, and
6102 There are some additional variables that Automake defines on its own:
6106 The contents of this variable are passed to every compilation that invokes
6107 the C preprocessor; it is a list of arguments to the preprocessor. For
6108 instance, @option{-I} and @option{-D} options should be listed here.
6110 Automake already provides some @option{-I} options automatically, in a
6111 separate variable that is also passed to every compilation that invokes
6112 the C preprocessor. In particular it generates @samp{-I.},
6113 @samp{-I$(srcdir)}, and a @option{-I} pointing to the directory holding
6114 @file{config.h} (if you've used @code{AC_CONFIG_HEADERS} or
6115 @code{AM_CONFIG_HEADER}). You can disable the default @option{-I}
6116 options using the @option{nostdinc} option.
6118 When a file to be included is generated during the build and not part
6119 of a distribution tarball, its location is under @code{$(builddir)},
6120 not under @code{$(srcdir)}. This matters especially for packages that
6121 use header files placed in sub-directories and want to allow builds
6122 outside the source tree (@pxref{VPATH Builds}). In that case we
6123 recommend to use a pair of @option{-I} options, such as, e.g.,
6124 @samp{-Isome/subdir -I$(srcdir)/some/subdir} or
6125 @samp{-I$(top_builddir)/some/subdir -I$(top_srcdir)/some/subdir}.
6126 Note that the reference to the build tree should come before the
6127 reference to the source tree, so that accidentally leftover generated
6128 files in the source directory are ignored.
6130 @code{AM_CPPFLAGS} is ignored in preference to a per-executable (or
6131 per-library) @code{_CPPFLAGS} variable if it is defined.
6134 This does the same job as @code{AM_CPPFLAGS} (or any per-target
6135 @code{_CPPFLAGS} variable if it is used). It is an older name for the
6136 same functionality. This variable is deprecated; we suggest using
6137 @code{AM_CPPFLAGS} and per-target @code{_CPPFLAGS} instead.
6140 This is the variable the @file{Makefile.am} author can use to pass
6141 in additional C compiler flags. It is more fully documented elsewhere.
6142 In some situations, this is not used, in preference to the
6143 per-executable (or per-library) @code{_CFLAGS}.
6146 This is the command used to actually compile a C source file. The
6147 file name is appended to form the complete command line.
6150 This is the variable the @file{Makefile.am} author can use to pass
6151 in additional linker flags. In some situations, this is not used, in
6152 preference to the per-executable (or per-library) @code{_LDFLAGS}.
6155 This is the command used to actually link a C program. It already
6156 includes @samp{-o $@@} and the usual variable references (for instance,
6157 @code{CFLAGS}); it takes as ``arguments'' the names of the object files
6158 and libraries to link in. This variable is not used when the linker is
6159 overridden with a per-target @code{_LINK} variable or per-target flags
6160 cause Automake to define such a @code{_LINK} variable.
6165 @section Yacc and Lex support
6167 Automake has somewhat idiosyncratic support for Yacc and Lex.
6169 Automake assumes that the @file{.c} file generated by @command{yacc}
6170 (or @command{lex}) should be named using the basename of the input
6171 file. That is, for a yacc source file @file{foo.y}, Automake will
6172 cause the intermediate file to be named @file{foo.c} (as opposed to
6173 @file{y.tab.c}, which is more traditional).
6175 The extension of a yacc source file is used to determine the extension
6176 of the resulting C or C++ source and header files. Note that header
6177 files are generated only when the @option{-d} Yacc option is used; see
6178 below for more information about this flag, and how to specify it.
6179 Files with the extension @file{.y} will thus be turned into @file{.c}
6180 sources and @file{.h} headers; likewise, @file{.yy} will become
6181 @file{.cc} and @file{.hh}, @file{.y++} will become @file{c++} and
6182 @file{h++}, @file{.yxx} will become @file{.cxx} and @file{.hxx},
6183 and @file{.ypp} will become @file{.cpp} and @file{.hpp}.
6185 Similarly, lex source files can be used to generate C or C++; the
6186 extensions @file{.l}, @file{.ll}, @file{.l++}, @file{.lxx}, and
6187 @file{.lpp} are recognized.
6189 You should never explicitly mention the intermediate (C or C++) file
6190 in any @code{SOURCES} variable; only list the source file.
6192 The intermediate files generated by @command{yacc} (or @command{lex})
6193 will be included in any distribution that is made. That way the user
6194 doesn't need to have @command{yacc} or @command{lex}.
6196 If a @command{yacc} source file is seen, then your @file{configure.ac} must
6197 define the variable @code{YACC}. This is most easily done by invoking
6198 the macro @code{AC_PROG_YACC} (@pxref{Particular Programs, , Particular
6199 Program Checks, autoconf, The Autoconf Manual}).
6203 When @code{yacc} is invoked, it is passed @code{AM_YFLAGS} and
6204 @code{YFLAGS}. The latter is a user variable and the former is
6205 intended for the @file{Makefile.am} author.
6207 @code{AM_YFLAGS} is usually used to pass the @option{-d} option to
6208 @command{yacc}. Automake knows what this means and will automatically
6209 adjust its rules to update and distribute the header file built by
6210 @samp{yacc -d}@footnote{Please note that @command{automake} recognizes
6211 @option{-d} in @code{AM_YFLAGS} only if it is not clustered with other
6212 options; for example, it won't be recognized if @code{AM_YFLAGS} is
6213 @option{-dt}, but it will be if @code{AM_YFLAGS} is @option{-d -t} or
6215 What Automake cannot guess, though, is where this
6216 header will be used: it is up to you to ensure the header gets built
6217 before it is first used. Typically this is necessary in order for
6218 dependency tracking to work when the header is included by another
6219 file. The common solution is listing the header file in
6220 @code{BUILT_SOURCES} (@pxref{Sources}) as follows.
6223 BUILT_SOURCES = parser.h
6226 foo_SOURCES = @dots{} parser.y @dots{}
6229 If a @command{lex} source file is seen, then your @file{configure.ac}
6230 must define the variable @code{LEX}. You can use @code{AC_PROG_LEX}
6231 to do this (@pxref{Particular Programs, , Particular Program Checks,
6232 autoconf, The Autoconf Manual}), but using @code{AM_PROG_LEX} macro
6233 (@pxref{Macros}) is recommended.
6237 When @command{lex} is invoked, it is passed @code{AM_LFLAGS} and
6238 @code{LFLAGS}. The latter is a user variable and the former is
6239 intended for the @file{Makefile.am} author.
6241 When @code{AM_MAINTAINER_MODE} (@pxref{maintainer-mode}) is used, the
6242 rebuild rule for distributed Yacc and Lex sources are only used when
6243 @code{maintainer-mode} is enabled, or when the files have been erased.
6245 @cindex @command{ylwrap}
6246 @cindex @command{yacc}, multiple parsers
6247 @cindex Multiple @command{yacc} parsers
6248 @cindex Multiple @command{lex} lexers
6249 @cindex @command{lex}, multiple lexers
6251 When @command{lex} or @command{yacc} sources are used, @code{automake
6252 -i} automatically installs an auxiliary program called
6253 @command{ylwrap} in your package (@pxref{Auxiliary Programs}). This
6254 program is used by the build rules to rename the output of these
6255 tools, and makes it possible to include multiple @command{yacc} (or
6256 @command{lex}) source files in a single directory. (This is necessary
6257 because yacc's output file name is fixed, and a parallel make could
6258 conceivably invoke more than one instance of @command{yacc}
6261 For @command{yacc}, simply managing locking is insufficient. The output of
6262 @command{yacc} always uses the same symbol names internally, so it isn't
6263 possible to link two @command{yacc} parsers into the same executable.
6265 We recommend using the following renaming hack used in @command{gdb}:
6267 #define yymaxdepth c_maxdepth
6268 #define yyparse c_parse
6270 #define yyerror c_error
6271 #define yylval c_lval
6272 #define yychar c_char
6273 #define yydebug c_debug
6274 #define yypact c_pact
6281 #define yyexca c_exca
6282 #define yyerrflag c_errflag
6283 #define yynerrs c_nerrs
6287 #define yy_yys c_yys
6288 #define yystate c_state
6291 #define yy_yyv c_yyv
6293 #define yylloc c_lloc
6294 #define yyreds c_reds
6295 #define yytoks c_toks
6296 #define yylhs c_yylhs
6297 #define yylen c_yylen
6298 #define yydefred c_yydefred
6299 #define yydgoto c_yydgoto
6300 #define yysindex c_yysindex
6301 #define yyrindex c_yyrindex
6302 #define yygindex c_yygindex
6303 #define yytable c_yytable
6304 #define yycheck c_yycheck
6305 #define yyname c_yyname
6306 #define yyrule c_yyrule
6309 For each define, replace the @samp{c_} prefix with whatever you like.
6310 These defines work for @command{bison}, @command{byacc}, and
6311 traditional @code{yacc}s. If you find a parser generator that uses a
6312 symbol not covered here, please report the new name so it can be added
6317 @section C++ Support
6320 @cindex Support for C++
6322 Automake includes full support for C++.
6324 Any package including C++ code must define the output variable
6325 @code{CXX} in @file{configure.ac}; the simplest way to do this is to use
6326 the @code{AC_PROG_CXX} macro (@pxref{Particular Programs, , Particular
6327 Program Checks, autoconf, The Autoconf Manual}).
6329 A few additional variables are defined when a C++ source file is seen:
6333 The name of the C++ compiler.
6336 Any flags to pass to the C++ compiler.
6339 The maintainer's variant of @code{CXXFLAGS}.
6342 The command used to actually compile a C++ source file. The file name
6343 is appended to form the complete command line.
6346 The command used to actually link a C++ program.
6350 @node Objective C Support
6351 @section Objective C Support
6353 @cindex Objective C support
6354 @cindex Support for Objective C
6356 Automake includes some support for Objective C.
6358 Any package including Objective C code must define the output variable
6359 @code{OBJC} in @file{configure.ac}; the simplest way to do this is to use
6360 the @code{AC_PROG_OBJC} macro (@pxref{Particular Programs, , Particular
6361 Program Checks, autoconf, The Autoconf Manual}).
6363 A few additional variables are defined when an Objective C source file
6368 The name of the Objective C compiler.
6371 Any flags to pass to the Objective C compiler.
6374 The maintainer's variant of @code{OBJCFLAGS}.
6377 The command used to actually compile an Objective C source file. The
6378 file name is appended to form the complete command line.
6381 The command used to actually link an Objective C program.
6385 @node Unified Parallel C Support
6386 @section Unified Parallel C Support
6388 @cindex Unified Parallel C support
6389 @cindex Support for Unified Parallel C
6391 Automake includes some support for Unified Parallel C.
6393 Any package including Unified Parallel C code must define the output
6394 variable @code{UPC} in @file{configure.ac}; the simplest way to do
6395 this is to use the @code{AM_PROG_UPC} macro (@pxref{Public Macros}).
6397 A few additional variables are defined when a Unified Parallel C
6398 source file is seen:
6402 The name of the Unified Parallel C compiler.
6405 Any flags to pass to the Unified Parallel C compiler.
6408 The maintainer's variant of @code{UPCFLAGS}.
6411 The command used to actually compile a Unified Parallel C source file.
6412 The file name is appended to form the complete command line.
6415 The command used to actually link a Unified Parallel C program.
6419 @node Assembly Support
6420 @section Assembly Support
6422 Automake includes some support for assembly code. There are two forms
6423 of assembler files: normal (@file{*.s}) and preprocessed by @code{CPP}
6424 (@file{*.S} or @file{*.sx}).
6429 @vindex AM_CCASFLAGS
6431 The variable @code{CCAS} holds the name of the compiler used to build
6432 assembly code. This compiler must work a bit like a C compiler; in
6433 particular it must accept @option{-c} and @option{-o}. The values of
6434 @code{CCASFLAGS} and @code{AM_CCASFLAGS} (or its per-target
6435 definition) is passed to the compilation. For preprocessed files,
6436 @code{DEFS}, @code{DEFAULT_INCLUDES}, @code{INCLUDES}, @code{CPPFLAGS}
6437 and @code{AM_CPPFLAGS} are also used.
6439 The autoconf macro @code{AM_PROG_AS} will define @code{CCAS} and
6440 @code{CCASFLAGS} for you (unless they are already set, it simply sets
6441 @code{CCAS} to the C compiler and @code{CCASFLAGS} to the C compiler
6442 flags), but you are free to define these variables by other means.
6444 Only the suffixes @file{.s}, @file{.S}, and @file{.sx} are recognized by
6445 @command{automake} as being files containing assembly code.
6448 @node Fortran 77 Support
6449 @comment node-name, next, previous, up
6450 @section Fortran 77 Support
6452 @cindex Fortran 77 support
6453 @cindex Support for Fortran 77
6455 Automake includes full support for Fortran 77.
6457 Any package including Fortran 77 code must define the output variable
6458 @code{F77} in @file{configure.ac}; the simplest way to do this is to use
6459 the @code{AC_PROG_F77} macro (@pxref{Particular Programs, , Particular
6460 Program Checks, autoconf, The Autoconf Manual}).
6462 A few additional variables are defined when a Fortran 77 source file is
6468 The name of the Fortran 77 compiler.
6471 Any flags to pass to the Fortran 77 compiler.
6474 The maintainer's variant of @code{FFLAGS}.
6477 Any flags to pass to the Ratfor compiler.
6480 The maintainer's variant of @code{RFLAGS}.
6483 The command used to actually compile a Fortran 77 source file. The file
6484 name is appended to form the complete command line.
6487 The command used to actually link a pure Fortran 77 program or shared
6492 Automake can handle preprocessing Fortran 77 and Ratfor source files in
6493 addition to compiling them@footnote{Much, if not most, of the
6494 information in the following sections pertaining to preprocessing
6495 Fortran 77 programs was taken almost verbatim from @ref{Catalogue of
6496 Rules, , Catalogue of Rules, make, The GNU Make Manual}.}. Automake
6497 also contains some support for creating programs and shared libraries
6498 that are a mixture of Fortran 77 and other languages (@pxref{Mixing
6499 Fortran 77 With C and C++}).
6501 These issues are covered in the following sections.
6504 * Preprocessing Fortran 77:: Preprocessing Fortran 77 sources
6505 * Compiling Fortran 77 Files:: Compiling Fortran 77 sources
6506 * Mixing Fortran 77 With C and C++:: Mixing Fortran 77 With C and C++
6510 @node Preprocessing Fortran 77
6511 @comment node-name, next, previous, up
6512 @subsection Preprocessing Fortran 77
6514 @cindex Preprocessing Fortran 77
6515 @cindex Fortran 77, Preprocessing
6516 @cindex Ratfor programs
6518 @file{N.f} is made automatically from @file{N.F} or @file{N.r}. This
6519 rule runs just the preprocessor to convert a preprocessable Fortran 77
6520 or Ratfor source file into a strict Fortran 77 source file. The precise
6521 command used is as follows:
6526 @code{$(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)@*
6527 $(AM_FFLAGS) $(FFLAGS)}
6530 @code{$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
6535 @node Compiling Fortran 77 Files
6536 @comment node-name, next, previous, up
6537 @subsection Compiling Fortran 77 Files
6539 @file{N.o} is made automatically from @file{N.f}, @file{N.F} or
6540 @file{N.r} by running the Fortran 77 compiler. The precise command used
6546 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS)}
6549 @code{$(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)@*
6550 $(AM_FFLAGS) $(FFLAGS)}
6553 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
6558 @node Mixing Fortran 77 With C and C++
6559 @comment node-name, next, previous, up
6560 @subsection Mixing Fortran 77 With C and C++
6562 @cindex Fortran 77, mixing with C and C++
6563 @cindex Mixing Fortran 77 with C and C++
6564 @cindex Linking Fortran 77 with C and C++
6566 @cindex Mixing Fortran 77 with C and/or C++
6568 Automake currently provides @emph{limited} support for creating programs
6569 and shared libraries that are a mixture of Fortran 77 and C and/or C++.
6570 However, there are many other issues related to mixing Fortran 77 with
6571 other languages that are @emph{not} (currently) handled by Automake, but
6572 that are handled by other packages@footnote{For example,
6573 @uref{http://www-zeus.desy.de/~burow/cfortran/, the cfortran package}
6574 addresses all of these inter-language issues, and runs under nearly all
6575 Fortran 77, C and C++ compilers on nearly all platforms. However,
6576 @command{cfortran} is not yet Free Software, but it will be in the next
6579 Automake can help in two ways:
6583 Automatic selection of the linker depending on which combinations of
6587 Automatic selection of the appropriate linker flags (e.g., @option{-L} and
6588 @option{-l}) to pass to the automatically selected linker in order to link
6589 in the appropriate Fortran 77 intrinsic and run-time libraries.
6591 @cindex @code{FLIBS}, defined
6593 These extra Fortran 77 linker flags are supplied in the output variable
6594 @code{FLIBS} by the @code{AC_F77_LIBRARY_LDFLAGS} Autoconf macro
6595 supplied with newer versions of Autoconf (Autoconf version 2.13 and
6596 later). @xref{Fortran Compiler, , Fortran Compiler Characteristics,
6597 autoconf, The Autoconf Manual}.
6600 If Automake detects that a program or shared library (as mentioned in
6601 some @code{_PROGRAMS} or @code{_LTLIBRARIES} primary) contains source
6602 code that is a mixture of Fortran 77 and C and/or C++, then it requires
6603 that the macro @code{AC_F77_LIBRARY_LDFLAGS} be called in
6604 @file{configure.ac}, and that either @code{$(FLIBS)}
6605 appear in the appropriate @code{_LDADD} (for programs) or @code{_LIBADD}
6606 (for shared libraries) variables. It is the responsibility of the
6607 person writing the @file{Makefile.am} to make sure that @samp{$(FLIBS)}
6608 appears in the appropriate @code{_LDADD} or
6609 @code{_LIBADD} variable.
6611 @cindex Mixed language example
6612 @cindex Example, mixed language
6614 For example, consider the following @file{Makefile.am}:
6618 foo_SOURCES = main.cc foo.f
6619 foo_LDADD = libfoo.la $(FLIBS)
6621 pkglib_LTLIBRARIES = libfoo.la
6622 libfoo_la_SOURCES = bar.f baz.c zardoz.cc
6623 libfoo_la_LIBADD = $(FLIBS)
6626 In this case, Automake will insist that @code{AC_F77_LIBRARY_LDFLAGS}
6627 is mentioned in @file{configure.ac}. Also, if @samp{$(FLIBS)} hadn't
6628 been mentioned in @code{foo_LDADD} and @code{libfoo_la_LIBADD}, then
6629 Automake would have issued a warning.
6632 * How the Linker is Chosen:: Automatic linker selection
6635 @node How the Linker is Chosen
6636 @comment node-name, next, previous, up
6637 @subsubsection How the Linker is Chosen
6639 @cindex Automatic linker selection
6640 @cindex Selecting the linker automatically
6642 When a program or library mixes several languages, Automake choose the
6643 linker according to the following priorities. (The names in
6644 parentheses are the variables containing the link command.)
6649 Native Java (@code{GCJLINK})
6652 C++ (@code{CXXLINK})
6655 Fortran 77 (@code{F77LINK})
6658 Fortran (@code{FCLINK})
6661 Objective C (@code{OBJCLINK})
6664 Unified Parallel C (@code{UPCLINK})
6670 For example, if Fortran 77, C and C++ source code is compiled
6671 into a program, then the C++ linker will be used. In this case, if the
6672 C or Fortran 77 linkers required any special libraries that weren't
6673 included by the C++ linker, then they must be manually added to an
6674 @code{_LDADD} or @code{_LIBADD} variable by the user writing the
6677 Automake only looks at the file names listed in @file{_SOURCES}
6678 variables to choose the linker, and defaults to the C linker.
6679 Sometimes this is inconvenient because you are linking against a
6680 library written in another language and would like to set the linker
6681 more appropriately. @xref{Libtool Convenience Libraries}, for a
6682 trick with @code{nodist_EXTRA_@dots{}_SOURCES}.
6684 A per-target @code{_LINK} variable will override the above selection.
6685 Per-target link flags will cause Automake to write a per-target
6686 @code{_LINK} variable according to the language chosen as above.
6689 @node Fortran 9x Support
6690 @comment node-name, next, previous, up
6691 @section Fortran 9x Support
6693 @cindex Fortran 9x support
6694 @cindex Support for Fortran 9x
6696 Automake includes support for Fortran 9x.
6698 Any package including Fortran 9x code must define the output variable
6699 @code{FC} in @file{configure.ac}; the simplest way to do this is to use
6700 the @code{AC_PROG_FC} macro (@pxref{Particular Programs, , Particular
6701 Program Checks, autoconf, The Autoconf Manual}).
6703 A few additional variables are defined when a Fortran 9x source file is
6709 The name of the Fortran 9x compiler.
6712 Any flags to pass to the Fortran 9x compiler.
6715 The maintainer's variant of @code{FCFLAGS}.
6718 The command used to actually compile a Fortran 9x source file. The file
6719 name is appended to form the complete command line.
6722 The command used to actually link a pure Fortran 9x program or shared
6728 * Compiling Fortran 9x Files:: Compiling Fortran 9x sources
6731 @node Compiling Fortran 9x Files
6732 @comment node-name, next, previous, up
6733 @subsection Compiling Fortran 9x Files
6735 @file{@var{file}.o} is made automatically from @file{@var{file}.f90},
6736 @file{@var{file}.f95}, @file{@var{file}.f03}, or @file{@var{file}.f08}
6737 by running the Fortran 9x compiler. The precise command used
6743 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f90) $<}
6746 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f95) $<}
6749 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f03) $<}
6752 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f08) $<}
6756 @node Java Support with gcj
6757 @comment node-name, next, previous, up
6758 @section Compiling Java sources using gcj
6760 @cindex Java support with gcj
6761 @cindex Support for Java with gcj
6762 @cindex Java to native code, compilation
6763 @cindex Compilation of Java to native code
6765 Automake includes support for natively compiled Java, using @command{gcj},
6766 the Java front end to the GNU Compiler Collection (rudimentary support
6767 for compiling Java to bytecode using the @command{javac} compiler is
6768 also present, @emph{albeit deprecated}; @pxref{Java}).
6770 Any package including Java code to be compiled must define the output
6771 variable @code{GCJ} in @file{configure.ac}; the variable @code{GCJFLAGS}
6772 must also be defined somehow (either in @file{configure.ac} or
6773 @file{Makefile.am}). The simplest way to do this is to use the
6774 @code{AM_PROG_GCJ} macro.
6778 By default, programs including Java source files are linked with
6781 As always, the contents of @code{AM_GCJFLAGS} are passed to every
6782 compilation invoking @command{gcj} (in its role as an ahead-of-time
6783 compiler, when invoking it to create @file{.class} files,
6784 @code{AM_JAVACFLAGS} is used instead). If it is necessary to pass
6785 options to @command{gcj} from @file{Makefile.am}, this variable, and not
6786 the user variable @code{GCJFLAGS}, should be used.
6790 @command{gcj} can be used to compile @file{.java}, @file{.class},
6791 @file{.zip}, or @file{.jar} files.
6793 When linking, @command{gcj} requires that the main class be specified
6794 using the @option{--main=} option. The easiest way to do this is to use
6795 the @code{_LDFLAGS} variable for the program.
6799 @comment node-name, next, previous, up
6800 @section Vala Support
6802 @cindex Vala Support
6803 @cindex Support for Vala
6805 Automake provides initial support for Vala
6806 (@uref{http://www.vala-project.org/}).
6807 This requires valac version 0.7.0 or later, and currently requires
6808 the user to use GNU @command{make}.
6811 foo_SOURCES = foo.vala bar.vala zardoc.c
6814 Any @file{.vala} file listed in a @code{_SOURCES} variable will be
6815 compiled into C code by the Vala compiler. The generated @file{.c} files are
6816 distributed. The end user does not need to have a Vala compiler installed.
6818 Automake ships with an Autoconf macro called @code{AM_PROG_VALAC}
6819 that will locate the Vala compiler and optionally check its version
6822 @defmac AM_PROG_VALAC (@ovar{minimum-version})
6823 Try to find a Vala compiler in @env{PATH}. If it is found, the variable
6824 @code{VALAC} is set. Optionally a minimum release number of the compiler
6828 AM_PROG_VALAC([0.7.0])
6832 There are a few variables that are used when compiling Vala sources:
6836 Path to the Vala compiler.
6839 Additional arguments for the Vala compiler.
6842 The maintainer's variant of @code{VALAFLAGS}.
6845 lib_LTLIBRARIES = libfoo.la
6846 libfoo_la_SOURCES = foo.vala
6850 Note that currently, you cannot use per-target @code{*_VALAFLAGS}
6851 (@pxref{Renamed Objects}) to produce different C files from one Vala
6855 @node Support for Other Languages
6856 @comment node-name, next, previous, up
6857 @section Support for Other Languages
6859 Automake currently only includes full support for C, C++ (@pxref{C++
6860 Support}), Objective C (@pxref{Objective C Support}), Fortran 77
6861 (@pxref{Fortran 77 Support}), Fortran 9x (@pxref{Fortran 9x Support}),
6862 and Java (@pxref{Java Support with gcj}). There is only rudimentary
6863 support for other languages, support for which will be improved based
6866 Some limited support for adding your own languages is available via the
6867 suffix rule handling (@pxref{Suffixes}).
6870 @section Automatic dependency tracking
6872 As a developer it is often painful to continually update the
6873 @file{Makefile.am} whenever the include-file dependencies change in a
6874 project. Automake supplies a way to automatically track dependency
6875 changes (@pxref{Dependency Tracking}).
6877 @cindex Dependency tracking
6878 @cindex Automatic dependency tracking
6880 Automake always uses complete dependencies for a compilation,
6881 including system headers. Automake's model is that dependency
6882 computation should be a side effect of the build. To this end,
6883 dependencies are computed by running all compilations through a
6884 special wrapper program called @command{depcomp}. @command{depcomp}
6885 understands how to coax many different C and C++ compilers into
6886 generating dependency information in the format it requires.
6887 @samp{automake -a} will install @command{depcomp} into your source
6888 tree for you. If @command{depcomp} can't figure out how to properly
6889 invoke your compiler, dependency tracking will simply be disabled for
6892 @cindex @command{depcomp}
6894 Experience with earlier versions of Automake (@pxref{Dependency Tracking
6895 Evolution, , Dependency Tracking Evolution, automake-history, Brief History
6896 of Automake}) taught us that it is not reliable to generate dependencies
6897 only on the maintainer's system, as configurations vary too much. So
6898 instead Automake implements dependency tracking at build time.
6900 Automatic dependency tracking can be suppressed by putting
6901 @option{no-dependencies} in the variable @code{AUTOMAKE_OPTIONS}, or
6902 passing @option{no-dependencies} as an argument to @code{AM_INIT_AUTOMAKE}
6903 (this should be the preferred way). Or, you can invoke @command{automake}
6904 with the @option{-i} option. Dependency tracking is enabled by default.
6906 @vindex AUTOMAKE_OPTIONS
6907 @opindex no-dependencies
6909 The person building your package also can choose to disable dependency
6910 tracking by configuring with @option{--disable-dependency-tracking}.
6912 @cindex Disabling dependency tracking
6913 @cindex Dependency tracking, disabling
6917 @section Support for executable extensions
6919 @cindex Executable extension
6920 @cindex Extension, executable
6923 On some platforms, such as Windows, executables are expected to have an
6924 extension such as @file{.exe}. On these platforms, some compilers (GCC
6925 among them) will automatically generate @file{foo.exe} when asked to
6926 generate @file{foo}.
6928 Automake provides mostly-transparent support for this. Unfortunately
6929 @emph{mostly} doesn't yet mean @emph{fully}. Until the English
6930 dictionary is revised, you will have to assist Automake if your package
6931 must support those platforms.
6933 One thing you must be aware of is that, internally, Automake rewrites
6934 something like this:
6937 bin_PROGRAMS = liver
6943 bin_PROGRAMS = liver$(EXEEXT)
6946 The targets Automake generates are likewise given the @samp{$(EXEEXT)}
6949 The variables @code{TESTS} and @code{XFAIL_TESTS} (@pxref{Simple Tests})
6950 are also rewritten if they contain filenames that have been declared as
6951 programs in the same @file{Makefile}. (This is mostly useful when some
6952 programs from @code{check_PROGRAMS} are listed in @code{TESTS}.)
6954 However, Automake cannot apply this rewriting to @command{configure}
6955 substitutions. This means that if you are conditionally building a
6956 program using such a substitution, then your @file{configure.ac} must
6957 take care to add @samp{$(EXEEXT)} when constructing the output variable.
6959 With Autoconf 2.13 and earlier, you must explicitly use @code{AC_EXEEXT}
6960 to get this support. With Autoconf 2.50, @code{AC_EXEEXT} is run
6961 automatically if you configure a compiler (say, through
6964 Sometimes maintainers like to write an explicit link rule for their
6965 program. Without executable extension support, this is easy---you
6966 simply write a rule whose target is the name of the program. However,
6967 when executable extension support is enabled, you must instead add the
6968 @samp{$(EXEEXT)} suffix.
6970 Unfortunately, due to the change in Autoconf 2.50, this means you must
6971 always add this extension. However, this is a problem for maintainers
6972 who know their package will never run on a platform that has
6973 executable extensions. For those maintainers, the @option{no-exeext}
6974 option (@pxref{Options}) will disable this feature. This works in a
6975 fairly ugly way; if @option{no-exeext} is seen, then the presence of a
6976 rule for a target named @code{foo} in @file{Makefile.am} will override
6977 an @command{automake}-generated rule for @samp{foo$(EXEEXT)}. Without
6978 the @option{no-exeext} option, this use will give a diagnostic.
6982 @chapter Other Derived Objects
6984 Automake can handle derived objects that are not C programs. Sometimes
6985 the support for actually building such objects must be explicitly
6986 supplied, but Automake will still automatically handle installation and
6990 * Scripts:: Executable scripts
6991 * Headers:: Header files
6992 * Data:: Architecture-independent data files
6993 * Sources:: Derived sources
6998 @section Executable Scripts
7000 @cindex @code{_SCRIPTS} primary, defined
7001 @cindex @code{SCRIPTS} primary, defined
7002 @cindex Primary variable, @code{SCRIPTS}
7004 @cindex Installing scripts
7006 It is possible to define and install programs that are scripts. Such
7007 programs are listed using the @code{SCRIPTS} primary name. When the
7008 script is distributed in its final, installable form, the
7009 @file{Makefile} usually looks as follows:
7013 # Install my_script in $(bindir) and distribute it.
7014 dist_bin_SCRIPTS = my_script
7017 Scripts are not distributed by default; as we have just seen, those
7018 that should be distributed can be specified using a @code{dist_}
7019 prefix as with other primaries.
7021 @cindex @code{SCRIPTS}, installation directories
7023 @vindex sbin_SCRIPTS
7024 @vindex libexec_SCRIPTS
7025 @vindex pkgdata_SCRIPTS
7026 @vindex pkglibexec_SCRIPTS
7027 @vindex noinst_SCRIPTS
7028 @vindex check_SCRIPTS
7030 Scripts can be installed in @code{bindir}, @code{sbindir},
7031 @code{libexecdir}, @code{pkglibexecdir}, or @code{pkgdatadir}.
7033 Scripts that need not be installed can be listed in
7034 @code{noinst_SCRIPTS}, and among them, those which are needed only by
7035 @samp{make check} should go in @code{check_SCRIPTS}.
7037 When a script needs to be built, the @file{Makefile.am} should include
7038 the appropriate rules. For instance the @command{automake} program
7039 itself is a Perl script that is generated from @file{automake.in}.
7040 Here is how this is handled:
7043 bin_SCRIPTS = automake
7044 CLEANFILES = $(bin_SCRIPTS)
7045 EXTRA_DIST = automake.in
7047 do_subst = sed -e 's,[@@]datadir[@@],$(datadir),g' \
7048 -e 's,[@@]PERL[@@],$(PERL),g' \
7049 -e 's,[@@]PACKAGE[@@],$(PACKAGE),g' \
7050 -e 's,[@@]VERSION[@@],$(VERSION),g' \
7053 automake: automake.in Makefile
7054 $(do_subst) < $(srcdir)/automake.in > automake
7058 Such scripts for which a build rule has been supplied need to be
7059 deleted explicitly using @code{CLEANFILES} (@pxref{Clean}), and their
7060 sources have to be distributed, usually with @code{EXTRA_DIST}
7061 (@pxref{Basics of Distribution}).
7063 Another common way to build scripts is to process them from
7064 @file{configure} with @code{AC_CONFIG_FILES}. In this situation
7065 Automake knows which files should be cleaned and distributed, and what
7066 the rebuild rules should look like.
7068 For instance if @file{configure.ac} contains
7071 AC_CONFIG_FILES([src/my_script], [chmod +x src/my_script])
7075 to build @file{src/my_script} from @file{src/my_script.in}, then a
7076 @file{src/Makefile.am} to install this script in @code{$(bindir)} can
7080 bin_SCRIPTS = my_script
7081 CLEANFILES = $(bin_SCRIPTS)
7085 There is no need for @code{EXTRA_DIST} or any build rule: Automake
7086 infers them from @code{AC_CONFIG_FILES} (@pxref{Requirements}).
7087 @code{CLEANFILES} is still useful, because by default Automake will
7088 clean targets of @code{AC_CONFIG_FILES} in @code{distclean}, not
7091 Although this looks simpler, building scripts this way has one
7092 drawback: directory variables such as @code{$(datadir)} are not fully
7093 expanded and may refer to other directory variables.
7096 @section Header files
7098 @cindex @code{_HEADERS} primary, defined
7099 @cindex @code{HEADERS} primary, defined
7100 @cindex Primary variable, @code{HEADERS}
7102 @vindex noinst_HEADERS
7103 @cindex @code{HEADERS}, installation directories
7104 @cindex Installing headers
7105 @vindex include_HEADERS
7106 @vindex oldinclude_HEADERS
7107 @vindex pkginclude_HEADERS
7110 Header files that must be installed are specified by the
7111 @code{HEADERS} family of variables. Headers can be installed in
7112 @code{includedir}, @code{oldincludedir}, @code{pkgincludedir} or any
7113 other directory you may have defined (@pxref{Uniform}). For instance,
7116 include_HEADERS = foo.h bar/bar.h
7120 will install the two files as @file{$(includedir)/foo.h} and
7121 @file{$(includedir)/bar.h}.
7123 The @code{nobase_} prefix is also supported,
7126 nobase_include_HEADERS = foo.h bar/bar.h
7130 will install the two files as @file{$(includedir)/foo.h} and
7131 @file{$(includedir)/bar/bar.h} (@pxref{Alternative}).
7133 @vindex noinst_HEADERS
7134 Usually, only header files that accompany installed libraries need to
7135 be installed. Headers used by programs or convenience libraries are
7136 not installed. The @code{noinst_HEADERS} variable can be used for
7137 such headers. However when the header actually belongs to a single
7138 convenience library or program, we recommend listing it in the
7139 program's or library's @code{_SOURCES} variable (@pxref{Program
7140 Sources}) instead of in @code{noinst_HEADERS}. This is clearer for
7141 the @file{Makefile.am} reader. @code{noinst_HEADERS} would be the
7142 right variable to use in a directory containing only headers and no
7143 associated library or program.
7145 All header files must be listed somewhere; in a @code{_SOURCES}
7146 variable or in a @code{_HEADERS} variable. Missing ones will not
7147 appear in the distribution.
7149 For header files that are built and must not be distributed, use the
7150 @code{nodist_} prefix as in @code{nodist_include_HEADERS} or
7151 @code{nodist_prog_SOURCES}. If these generated headers are needed
7152 during the build, you must also ensure they exist before they are
7153 used (@pxref{Sources}).
7157 @section Architecture-independent data files
7159 @cindex @code{_DATA} primary, defined
7160 @cindex @code{DATA} primary, defined
7161 @cindex Primary variable, @code{DATA}
7164 Automake supports the installation of miscellaneous data files using the
7165 @code{DATA} family of variables.
7169 @vindex sysconf_DATA
7170 @vindex sharedstate_DATA
7171 @vindex localstate_DATA
7172 @vindex pkgdata_DATA
7174 Such data can be installed in the directories @code{datadir},
7175 @code{sysconfdir}, @code{sharedstatedir}, @code{localstatedir}, or
7178 By default, data files are @emph{not} included in a distribution. Of
7179 course, you can use the @code{dist_} prefix to change this on a
7182 Here is how Automake declares its auxiliary data files:
7185 dist_pkgdata_DATA = clean-kr.am clean.am @dots{}
7190 @section Built Sources
7192 Because Automake's automatic dependency tracking works as a side-effect
7193 of compilation (@pxref{Dependencies}) there is a bootstrap issue: a
7194 target should not be compiled before its dependencies are made, but
7195 these dependencies are unknown until the target is first compiled.
7197 Ordinarily this is not a problem, because dependencies are distributed
7198 sources: they preexist and do not need to be built. Suppose that
7199 @file{foo.c} includes @file{foo.h}. When it first compiles
7200 @file{foo.o}, @command{make} only knows that @file{foo.o} depends on
7201 @file{foo.c}. As a side-effect of this compilation @command{depcomp}
7202 records the @file{foo.h} dependency so that following invocations of
7203 @command{make} will honor it. In these conditions, it's clear there is
7204 no problem: either @file{foo.o} doesn't exist and has to be built
7205 (regardless of the dependencies), or accurate dependencies exist and
7206 they can be used to decide whether @file{foo.o} should be rebuilt.
7208 It's a different story if @file{foo.h} doesn't exist by the first
7209 @command{make} run. For instance, there might be a rule to build
7210 @file{foo.h}. This time @file{file.o}'s build will fail because the
7211 compiler can't find @file{foo.h}. @command{make} failed to trigger the
7212 rule to build @file{foo.h} first by lack of dependency information.
7214 @vindex BUILT_SOURCES
7215 @cindex @code{BUILT_SOURCES}, defined
7217 The @code{BUILT_SOURCES} variable is a workaround for this problem. A
7218 source file listed in @code{BUILT_SOURCES} is made on @samp{make all}
7219 or @samp{make check} (or even @samp{make install}) before other
7220 targets are processed. However, such a source file is not
7221 @emph{compiled} unless explicitly requested by mentioning it in some
7222 other @code{_SOURCES} variable.
7224 So, to conclude our introductory example, we could use
7225 @samp{BUILT_SOURCES = foo.h} to ensure @file{foo.h} gets built before
7226 any other target (including @file{foo.o}) during @samp{make all} or
7229 @code{BUILT_SOURCES} is actually a bit of a misnomer, as any file which
7230 must be created early in the build process can be listed in this
7231 variable. Moreover, all built sources do not necessarily have to be
7232 listed in @code{BUILT_SOURCES}. For instance, a generated @file{.c} file
7233 doesn't need to appear in @code{BUILT_SOURCES} (unless it is included by
7234 another source), because it's a known dependency of the associated
7237 It might be important to emphasize that @code{BUILT_SOURCES} is
7238 honored only by @samp{make all}, @samp{make check} and @samp{make
7239 install}. This means you cannot build a specific target (e.g.,
7240 @samp{make foo}) in a clean tree if it depends on a built source.
7241 However it will succeed if you have run @samp{make all} earlier,
7242 because accurate dependencies are already available.
7244 The next section illustrates and discusses the handling of built sources
7248 * Built Sources Example:: Several ways to handle built sources.
7251 @node Built Sources Example
7252 @subsection Built Sources Example
7254 Suppose that @file{foo.c} includes @file{bindir.h}, which is
7255 installation-dependent and not distributed: it needs to be built. Here
7256 @file{bindir.h} defines the preprocessor macro @code{bindir} to the
7257 value of the @command{make} variable @code{bindir} (inherited from
7260 We suggest several implementations below. It's not meant to be an
7261 exhaustive listing of all ways to handle built sources, but it will give
7262 you a few ideas if you encounter this issue.
7264 @subsubheading First Try
7266 This first implementation will illustrate the bootstrap issue mentioned
7267 in the previous section (@pxref{Sources}).
7269 Here is a tentative @file{Makefile.am}.
7275 nodist_foo_SOURCES = bindir.h
7276 CLEANFILES = bindir.h
7278 echo '#define bindir "$(bindir)"' >$@@
7281 This setup doesn't work, because Automake doesn't know that @file{foo.c}
7282 includes @file{bindir.h}. Remember, automatic dependency tracking works
7283 as a side-effect of compilation, so the dependencies of @file{foo.o} will
7284 be known only after @file{foo.o} has been compiled (@pxref{Dependencies}).
7285 The symptom is as follows.
7289 source='foo.c' object='foo.o' libtool=no \
7290 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
7291 depmode=gcc /bin/sh ./depcomp \
7292 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
7293 foo.c:2: bindir.h: No such file or directory
7294 make: *** [foo.o] Error 1
7297 In this example @file{bindir.h} is not distributed nor installed, and
7298 it is not even being built on-time. One may wonder if the
7299 @samp{nodist_foo_SOURCES = bindir.h} line has any use at all. This
7300 line simply states that @file{bindir.h} is a source of @code{foo}, so
7301 for instance, it should be inspected while generating tags
7302 (@pxref{Tags}). In other words, it does not help our present problem,
7303 and the build would fail identically without it.
7305 @subsubheading Using @code{BUILT_SOURCES}
7307 A solution is to require @file{bindir.h} to be built before anything
7308 else. This is what @code{BUILT_SOURCES} is meant for (@pxref{Sources}).
7313 nodist_foo_SOURCES = bindir.h
7314 BUILT_SOURCES = bindir.h
7315 CLEANFILES = bindir.h
7317 echo '#define bindir "$(bindir)"' >$@@
7320 See how @file{bindir.h} gets built first:
7324 echo '#define bindir "/usr/local/bin"' >bindir.h
7326 make[1]: Entering directory `/home/adl/tmp'
7327 source='foo.c' object='foo.o' libtool=no \
7328 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
7329 depmode=gcc /bin/sh ./depcomp \
7330 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
7331 gcc -g -O2 -o foo foo.o
7332 make[1]: Leaving directory `/home/adl/tmp'
7335 However, as said earlier, @code{BUILT_SOURCES} applies only to the
7336 @code{all}, @code{check}, and @code{install} targets. It still fails
7337 if you try to run @samp{make foo} explicitly:
7341 test -z "bindir.h" || rm -f bindir.h
7342 test -z "foo" || rm -f foo
7344 % : > .deps/foo.Po # Suppress previously recorded dependencies
7346 source='foo.c' object='foo.o' libtool=no \
7347 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
7348 depmode=gcc /bin/sh ./depcomp \
7349 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
7350 foo.c:2: bindir.h: No such file or directory
7351 make: *** [foo.o] Error 1
7354 @subsubheading Recording Dependencies manually
7356 Usually people are happy enough with @code{BUILT_SOURCES} because they
7357 never build targets such as @samp{make foo} before @samp{make all}, as
7358 in the previous example. However if this matters to you, you can
7359 avoid @code{BUILT_SOURCES} and record such dependencies explicitly in
7360 the @file{Makefile.am}.
7365 nodist_foo_SOURCES = bindir.h
7366 foo.$(OBJEXT): bindir.h
7367 CLEANFILES = bindir.h
7369 echo '#define bindir "$(bindir)"' >$@@
7372 You don't have to list @emph{all} the dependencies of @file{foo.o}
7373 explicitly, only those that might need to be built. If a dependency
7374 already exists, it will not hinder the first compilation and will be
7375 recorded by the normal dependency tracking code. (Note that after
7376 this first compilation the dependency tracking code will also have
7377 recorded the dependency between @file{foo.o} and
7378 @file{bindir.h}; so our explicit dependency is really useful to
7379 the first build only.)
7381 Adding explicit dependencies like this can be a bit dangerous if you are
7382 not careful enough. This is due to the way Automake tries not to
7383 overwrite your rules (it assumes you know better than it).
7384 @samp{foo.$(OBJEXT): bindir.h} supersedes any rule Automake may want to
7385 output to build @samp{foo.$(OBJEXT)}. It happens to work in this case
7386 because Automake doesn't have to output any @samp{foo.$(OBJEXT):}
7387 target: it relies on a suffix rule instead (i.e., @samp{.c.$(OBJEXT):}).
7388 Always check the generated @file{Makefile.in} if you do this.
7390 @subsubheading Build @file{bindir.h} from @file{configure}
7392 It's possible to define this preprocessor macro from @file{configure},
7393 either in @file{config.h} (@pxref{Defining Directories, , Defining
7394 Directories, autoconf, The Autoconf Manual}), or by processing a
7395 @file{bindir.h.in} file using @code{AC_CONFIG_FILES}
7396 (@pxref{Configuration Actions, ,Configuration Actions, autoconf, The
7399 At this point it should be clear that building @file{bindir.h} from
7400 @file{configure} works well for this example. @file{bindir.h} will exist
7401 before you build any target, hence will not cause any dependency issue.
7403 The Makefile can be shrunk as follows. We do not even have to mention
7411 However, it's not always possible to build sources from
7412 @file{configure}, especially when these sources are generated by a tool
7413 that needs to be built first.
7415 @subsubheading Build @file{bindir.c}, not @file{bindir.h}.
7417 Another attractive idea is to define @code{bindir} as a variable or
7418 function exported from @file{bindir.o}, and build @file{bindir.c}
7419 instead of @file{bindir.h}.
7422 noinst_PROGRAMS = foo
7423 foo_SOURCES = foo.c bindir.h
7424 nodist_foo_SOURCES = bindir.c
7425 CLEANFILES = bindir.c
7427 echo 'const char bindir[] = "$(bindir)";' >$@@
7430 @file{bindir.h} contains just the variable's declaration and doesn't
7431 need to be built, so it won't cause any trouble. @file{bindir.o} is
7432 always dependent on @file{bindir.c}, so @file{bindir.c} will get built
7435 @subsubheading Which is best?
7437 There is no panacea, of course. Each solution has its merits and
7440 You cannot use @code{BUILT_SOURCES} if the ability to run @samp{make
7441 foo} on a clean tree is important to you.
7443 You won't add explicit dependencies if you are leery of overriding
7444 an Automake rule by mistake.
7446 Building files from @file{./configure} is not always possible, neither
7447 is converting @file{.h} files into @file{.c} files.
7450 @node Other GNU Tools
7451 @chapter Other GNU Tools
7453 Since Automake is primarily intended to generate @file{Makefile.in}s for
7454 use in GNU programs, it tries hard to interoperate with other GNU tools.
7457 * Emacs Lisp:: Emacs Lisp
7460 * Java:: Java bytecode compilation (deprecated)
7468 @cindex @code{_LISP} primary, defined
7469 @cindex @code{LISP} primary, defined
7470 @cindex Primary variable, @code{LISP}
7476 Automake provides some support for Emacs Lisp. The @code{LISP} primary
7477 is used to hold a list of @file{.el} files. Possible prefixes for this
7478 primary are @code{lisp_} and @code{noinst_}. Note that if
7479 @code{lisp_LISP} is defined, then @file{configure.ac} must run
7480 @code{AM_PATH_LISPDIR} (@pxref{Macros}).
7482 @vindex dist_lisp_LISP
7483 @vindex dist_noinst_LISP
7484 Lisp sources are not distributed by default. You can prefix the
7485 @code{LISP} primary with @code{dist_}, as in @code{dist_lisp_LISP} or
7486 @code{dist_noinst_LISP}, to indicate that these files should be
7489 Automake will byte-compile all Emacs Lisp source files using the Emacs
7490 found by @code{AM_PATH_LISPDIR}, if any was found.
7492 Byte-compiled Emacs Lisp files are not portable among all versions of
7493 Emacs, so it makes sense to turn this off if you expect sites to have
7494 more than one version of Emacs installed. Furthermore, many packages
7495 don't actually benefit from byte-compilation. Still, we recommend
7496 that you byte-compile your Emacs Lisp sources. It is probably better
7497 for sites with strange setups to cope for themselves than to make the
7498 installation less nice for everybody else.
7500 There are two ways to avoid byte-compiling. Historically, we have
7501 recommended the following construct.
7504 lisp_LISP = file1.el file2.el
7509 @code{ELCFILES} is an internal Automake variable that normally lists
7510 all @file{.elc} files that must be byte-compiled. Automake defines
7511 @code{ELCFILES} automatically from @code{lisp_LISP}. Emptying this
7512 variable explicitly prevents byte-compilation.
7514 Since Automake 1.8, we now recommend using @code{lisp_DATA} instead:
7516 @c Keep in sync with primary-prefix-couples-documented-valid.test.
7518 lisp_DATA = file1.el file2.el
7521 Note that these two constructs are not equivalent. @code{_LISP} will
7522 not install a file if Emacs is not installed, while @code{_DATA} will
7523 always install its files.
7528 @cindex GNU Gettext support
7529 @cindex Gettext support
7530 @cindex Support for GNU Gettext
7532 If @code{AM_GNU_GETTEXT} is seen in @file{configure.ac}, then Automake
7533 turns on support for GNU gettext, a message catalog system for
7534 internationalization
7535 (@pxref{Top, , Introduction, gettext, GNU gettext utilities}).
7537 The @code{gettext} support in Automake requires the addition of one or
7538 two subdirectories to the package: @file{po} and possibly also @file{intl}.
7539 The latter is needed if @code{AM_GNU_GETTEXT} is not invoked with the
7540 @samp{external} argument, or if @code{AM_GNU_GETTEXT_INTL_SUBDIR} is used.
7541 Automake ensures that these directories exist and are mentioned in
7547 Automake provides support for GNU Libtool (@pxref{Top, , Introduction,
7548 libtool, The Libtool Manual}) with the @code{LTLIBRARIES} primary.
7549 @xref{A Shared Library}.
7553 @section Java bytecode compilation (deprecated)
7555 @cindex @code{_JAVA} primary, defined
7556 @cindex @code{JAVA} primary, defined
7557 @cindex Primary variable, @code{JAVA}
7558 @cindex Java to bytecode, compilation
7559 @cindex Compilation of Java to bytecode
7561 Automake provides some minimal support for Java bytecode compilation with
7562 the @code{JAVA} primary (in addition to the support for compiling Java to
7563 native machine code; @pxref{Java Support with gcj}). Note however that
7564 @emph{the interface and most features described here are deprecated}; the
7565 next automake release will strive to provide a better and cleaner
7566 interface, which however @emph{won't be backward-compatible}; the present
7567 interface will probably be removed altogether in future automake releases
7568 (1.13 or later), so don't use it in new code.
7570 Any @file{.java} files listed in a @code{_JAVA} variable will be
7571 compiled with @code{JAVAC} at build time. By default, @file{.java}
7572 files are not included in the distribution, you should use the
7573 @code{dist_} prefix to distribute them.
7575 Here is a typical setup for distributing @file{.java} files and
7576 installing the @file{.class} files resulting from their compilation.
7578 @c Keep in sync with primary-prefix-couples-documented-valid.test.
7580 javadir = $(datadir)/java
7581 dist_java_JAVA = a.java b.java @dots{}
7584 @cindex @code{JAVA} restrictions
7585 @cindex Restrictions for @code{JAVA}
7587 Currently Automake enforces the restriction that only one @code{_JAVA}
7588 primary can be used in a given @file{Makefile.am}. The reason for this
7589 restriction is that, in general, it isn't possible to know which
7590 @file{.class} files were generated from which @file{.java} files, so
7591 it would be impossible to know which files to install where. For
7592 instance, a @file{.java} file can define multiple classes; the resulting
7593 @file{.class} file names cannot be predicted without parsing the
7596 There are a few variables that are used when compiling Java sources:
7600 The name of the Java compiler. This defaults to @samp{javac}.
7603 The flags to pass to the compiler. This is considered to be a user
7604 variable (@pxref{User Variables}).
7607 More flags to pass to the Java compiler. This, and not
7608 @code{JAVACFLAGS}, should be used when it is necessary to put Java
7609 compiler flags into @file{Makefile.am}.
7612 The value of this variable is passed to the @option{-d} option to
7613 @code{javac}. It defaults to @samp{$(top_builddir)}.
7616 This variable is a shell expression that is used to set the
7617 @env{CLASSPATH} environment variable on the @code{javac} command line.
7618 (In the future we will probably handle class path setting differently.)
7625 @cindex @code{_PYTHON} primary, defined
7626 @cindex @code{PYTHON} primary, defined
7627 @cindex Primary variable, @code{PYTHON}
7630 Automake provides support for Python compilation with the
7631 @code{PYTHON} primary. A typical setup is to call
7632 @code{AM_PATH_PYTHON} in @file{configure.ac} and use a line like the
7633 following in @file{Makefile.am}:
7636 python_PYTHON = tree.py leave.py
7639 Any files listed in a @code{_PYTHON} variable will be byte-compiled
7640 with @command{py-compile} at install time. @command{py-compile}
7641 actually creates both standard (@file{.pyc}) and optimized
7642 (@file{.pyo}) byte-compiled versions of the source files. Note that
7643 because byte-compilation occurs at install time, any files listed in
7644 @code{noinst_PYTHON} will not be compiled. Python source files are
7645 included in the distribution by default, prepend @code{nodist_} (as in
7646 @code{nodist_python_PYTHON}) to omit them.
7648 Automake ships with an Autoconf macro called @code{AM_PATH_PYTHON}
7649 that will determine some Python-related directory variables (see
7650 below). If you have called @code{AM_PATH_PYTHON} from
7651 @file{configure.ac}, then you may use the variables
7652 @c Keep in sync with primary-prefix-couples-documented-valid.test.
7653 @code{python_PYTHON} or @code{pkgpython_PYTHON} to list Python source
7654 files in your @file{Makefile.am}, depending on where you want your files
7655 installed (see the definitions of @code{pythondir} and
7656 @code{pkgpythondir} below).
7658 @defmac AM_PATH_PYTHON (@ovar{version}, @ovar{action-if-found},
7659 @ovar{action-if-not-found})
7661 Search for a Python interpreter on the system. This macro takes three
7662 optional arguments. The first argument, if present, is the minimum
7663 version of Python required for this package: @code{AM_PATH_PYTHON}
7664 will skip any Python interpreter that is older than @var{version}.
7665 If an interpreter is found and satisfies @var{version}, then
7666 @var{action-if-found} is run. Otherwise, @var{action-if-not-found} is
7669 If @var{action-if-not-found} is not specified, as in the following
7670 example, the default is to abort @command{configure}.
7673 AM_PATH_PYTHON([2.2])
7677 This is fine when Python is an absolute requirement for the package.
7678 If Python >= 2.5 was only @emph{optional} to the package,
7679 @code{AM_PATH_PYTHON} could be called as follows.
7682 AM_PATH_PYTHON([2.5],, [:])
7685 If the @env{PYTHON} variable is set when @code{AM_PATH_PYTHON} is
7686 called, then that will be the only Python interpreter that is tried.
7688 @code{AM_PATH_PYTHON} creates the following output variables based on
7689 the Python installation found during configuration.
7694 The name of the Python executable, or @samp{:} if no suitable
7695 interpreter could be found.
7697 Assuming @var{action-if-not-found} is used (otherwise @file{./configure}
7698 will abort if Python is absent), the value of @code{PYTHON} can be used
7699 to setup a conditional in order to disable the relevant part of a build
7703 AM_PATH_PYTHON(,, [:])
7704 AM_CONDITIONAL([HAVE_PYTHON], [test "$PYTHON" != :])
7707 @item PYTHON_VERSION
7708 The Python version number, in the form @var{major}.@var{minor}
7709 (e.g., @samp{2.5}). This is currently the value of
7710 @samp{sys.version[:3]}.
7713 The string @samp{$@{prefix@}}. This term may be used in future work
7714 that needs the contents of Python's @samp{sys.prefix}, but general
7715 consensus is to always use the value from @command{configure}.
7717 @item PYTHON_EXEC_PREFIX
7718 The string @samp{$@{exec_prefix@}}. This term may be used in future work
7719 that needs the contents of Python's @samp{sys.exec_prefix}, but general
7720 consensus is to always use the value from @command{configure}.
7722 @item PYTHON_PLATFORM
7723 The canonical name used by Python to describe the operating system, as
7724 given by @samp{sys.platform}. This value is sometimes needed when
7725 building Python extensions.
7728 The directory name for the @file{site-packages} subdirectory of the
7729 standard Python install tree.
7732 This is the directory under @code{pythondir} that is named after the
7733 package. That is, it is @samp{$(pythondir)/$(PACKAGE)}. It is provided
7737 This is the directory where Python extension modules (shared libraries)
7738 should be installed. An extension module written in C could be declared
7739 as follows to Automake:
7741 @c Keep in sync with primary-prefix-couples-documented-valid.test.
7743 pyexec_LTLIBRARIES = quaternion.la
7744 quaternion_la_SOURCES = quaternion.c support.c support.h
7745 quaternion_la_LDFLAGS = -avoid-version -module
7749 This is a convenience variable that is defined as
7750 @samp{$(pyexecdir)/$(PACKAGE)}.
7753 All these directory variables have values that start with either
7754 @samp{$@{prefix@}} or @samp{$@{exec_prefix@}} unexpanded. This works
7755 fine in @file{Makefiles}, but it makes these variables hard to use in
7756 @file{configure}. This is mandated by the GNU coding standards, so
7757 that the user can run @samp{make prefix=/foo install}. The Autoconf
7758 manual has a section with more details on this topic
7759 (@pxref{Installation Directory Variables, , Installation Directory
7760 Variables, autoconf, The Autoconf Manual}). See also @ref{Hard-Coded
7765 @chapter Building documentation
7767 Currently Automake provides support for Texinfo and man pages.
7771 * Man Pages:: Man pages
7778 @cindex @code{_TEXINFOS} primary, defined
7779 @cindex @code{TEXINFOS} primary, defined
7780 @cindex Primary variable, @code{TEXINFOS}
7781 @cindex HTML output using Texinfo
7782 @cindex PDF output using Texinfo
7783 @cindex PS output using Texinfo
7784 @cindex DVI output using Texinfo
7786 @vindex info_TEXINFOS
7788 If the current directory contains Texinfo source, you must declare it
7789 with the @code{TEXINFOS} primary. Generally Texinfo files are converted
7790 into info, and thus the @code{info_TEXINFOS} variable is most commonly used
7791 here. Any Texinfo source file must end in the @file{.texi},
7792 @file{.txi}, or @file{.texinfo} extension. We recommend @file{.texi}
7795 Automake generates rules to build @file{.info}, @file{.dvi},
7796 @file{.ps}, @file{.pdf} and @file{.html} files from your Texinfo
7797 sources. Following the GNU Coding Standards, only the @file{.info}
7798 files are built by @samp{make all} and installed by @samp{make
7799 install} (unless you use @option{no-installinfo}, see below).
7800 Furthermore, @file{.info} files are automatically distributed so that
7801 Texinfo is not a prerequisite for installing your package.
7807 @trindex install-dvi
7808 @trindex install-html
7809 @trindex install-pdf
7811 Other documentation formats can be built on request by @samp{make
7812 dvi}, @samp{make ps}, @samp{make pdf} and @samp{make html}, and they
7813 can be installed with @samp{make install-dvi}, @samp{make install-ps},
7814 @samp{make install-pdf} and @samp{make install-html} explicitly.
7815 @samp{make uninstall} will remove everything: the Texinfo
7816 documentation installed by default as well as all the above optional
7819 All these targets can be extended using @samp{-local} rules
7820 (@pxref{Extending}).
7822 @cindex Texinfo flag, @code{VERSION}
7823 @cindex Texinfo flag, @code{UPDATED}
7824 @cindex Texinfo flag, @code{EDITION}
7825 @cindex Texinfo flag, @code{UPDATED-MONTH}
7827 @cindex @code{VERSION} Texinfo flag
7828 @cindex @code{UPDATED} Texinfo flag
7829 @cindex @code{EDITION} Texinfo flag
7830 @cindex @code{UPDATED-MONTH} Texinfo flag
7832 @cindex @file{mdate-sh}
7834 If the @file{.texi} file @code{@@include}s @file{version.texi}, then
7835 that file will be automatically generated. The file @file{version.texi}
7836 defines four Texinfo flag you can reference using
7837 @code{@@value@{EDITION@}}, @code{@@value@{VERSION@}},
7838 @code{@@value@{UPDATED@}}, and @code{@@value@{UPDATED-MONTH@}}.
7843 Both of these flags hold the version number of your program. They are
7844 kept separate for clarity.
7847 This holds the date the primary @file{.texi} file was last modified.
7850 This holds the name of the month in which the primary @file{.texi} file
7854 The @file{version.texi} support requires the @command{mdate-sh}
7855 script; this script is supplied with Automake and automatically
7856 included when @command{automake} is invoked with the
7857 @option{--add-missing} option.
7859 If you have multiple Texinfo files, and you want to use the
7860 @file{version.texi} feature, then you have to have a separate version
7861 file for each Texinfo file. Automake will treat any include in a
7862 Texinfo file that matches @file{vers*.texi} just as an automatically
7863 generated version file.
7865 Sometimes an info file actually depends on more than one @file{.texi}
7866 file. For instance, in GNU Hello, @file{hello.texi} includes the file
7867 @file{fdl.texi}. You can tell Automake about these dependencies using
7868 the @code{@var{texi}_TEXINFOS} variable. Here is how GNU Hello does it:
7873 info_TEXINFOS = hello.texi
7874 hello_TEXINFOS = fdl.texi
7877 @cindex @file{texinfo.tex}
7879 By default, Automake requires the file @file{texinfo.tex} to appear in
7880 the same directory as the @file{Makefile.am} file that lists the
7881 @file{.texi} files. If you used @code{AC_CONFIG_AUX_DIR} in
7882 @file{configure.ac} (@pxref{Input, , Finding `configure' Input,
7883 autoconf, The Autoconf Manual}), then @file{texinfo.tex} is looked for
7884 there. In both cases, @command{automake} then supplies @file{texinfo.tex} if
7885 @option{--add-missing} is given, and takes care of its distribution.
7886 However, if you set the @code{TEXINFO_TEX} variable (see below),
7887 it overrides the location of the file and turns off its installation
7888 into the source as well as its distribution.
7890 The option @option{no-texinfo.tex} can be used to eliminate the
7891 requirement for the file @file{texinfo.tex}. Use of the variable
7892 @code{TEXINFO_TEX} is preferable, however, because that allows the
7893 @code{dvi}, @code{ps}, and @code{pdf} targets to still work.
7895 @cindex Option, @code{no-installinfo}
7896 @cindex Target, @code{install-info}
7897 @cindex @code{install-info} target
7898 @cindex @code{no-installinfo} option
7900 @opindex no-installinfo
7901 @trindex install-info
7903 Automake generates an @code{install-info} rule; some people apparently
7904 use this. By default, info pages are installed by @samp{make
7905 install}, so running @code{make install-info} is pointless. This can
7906 be prevented via the @code{no-installinfo} option. In this case,
7907 @file{.info} files are not installed by default, and user must
7908 request this explicitly using @samp{make install-info}.
7910 @vindex AM_UPDATE_INFO_DIR
7911 By default, @code{make install-info} will try to run the
7912 @command{install-info} program (if available) to update (or create)
7913 the @file{@code{$@{infodir@}}/dir} index. If this is undesired, it
7914 can be prevented by exporting the @code{AM_UPDATE_INFO_DIR} variable
7917 The following variables are used by the Texinfo build rules.
7921 The name of the program invoked to build @file{.info} files. This
7922 variable is defined by Automake. If the @command{makeinfo} program is
7923 found on the system then it will be used by default; otherwise
7924 @command{missing} will be used instead.
7927 The command invoked to build @file{.html} files. Automake
7928 defines this to @samp{$(MAKEINFO) --html}.
7931 User flags passed to each invocation of @samp{$(MAKEINFO)} and
7932 @samp{$(MAKEINFOHTML)}. This user variable (@pxref{User Variables}) is
7933 not expected to be defined in any @file{Makefile}; it can be used by
7934 users to pass extra flags to suit their needs.
7936 @item AM_MAKEINFOFLAGS
7937 @itemx AM_MAKEINFOHTMLFLAGS
7938 Maintainer flags passed to each @command{makeinfo} invocation. Unlike
7939 @code{MAKEINFOFLAGS}, these variables are meant to be defined by
7940 maintainers in @file{Makefile.am}. @samp{$(AM_MAKEINFOFLAGS)} is
7941 passed to @code{makeinfo} when building @file{.info} files; and
7942 @samp{$(AM_MAKEINFOHTMLFLAGS)} is used when building @file{.html}
7945 @c Keep in sync with txinfo21.test.
7946 For instance, the following setting can be used to obtain one single
7947 @file{.html} file per manual, without node separators.
7949 AM_MAKEINFOHTMLFLAGS = --no-headers --no-split
7952 @code{AM_MAKEINFOHTMLFLAGS} defaults to @samp{$(AM_MAKEINFOFLAGS)}.
7953 This means that defining @code{AM_MAKEINFOFLAGS} without defining
7954 @code{AM_MAKEINFOHTMLFLAGS} will impact builds of both @file{.info}
7955 and @file{.html} files.
7958 The name of the command that converts a @file{.texi} file into a
7959 @file{.dvi} file. This defaults to @samp{texi2dvi}, a script that ships
7960 with the Texinfo package.
7963 The name of the command that translates a @file{.texi} file into a
7964 @file{.pdf} file. This defaults to @samp{$(TEXI2DVI) --pdf --batch}.
7967 The name of the command that builds a @file{.ps} file out of a
7968 @file{.dvi} file. This defaults to @samp{dvips}.
7972 If your package has Texinfo files in many directories, you can use the
7973 variable @code{TEXINFO_TEX} to tell Automake where to find the canonical
7974 @file{texinfo.tex} for your package. The value of this variable should
7975 be the relative path from the current @file{Makefile.am} to
7979 TEXINFO_TEX = ../doc/texinfo.tex
7987 @cindex @code{_MANS} primary, defined
7988 @cindex @code{MANS} primary, defined
7989 @cindex Primary variable, @code{MANS}
7993 A package can also include man pages (but see the GNU standards on this
7994 matter, @ref{Man Pages, , , standards, The GNU Coding Standards}.) Man
7995 pages are declared using the @code{MANS} primary. Generally the
7996 @code{man_MANS} variable is used. Man pages are automatically installed in
7997 the correct subdirectory of @code{mandir}, based on the file extension.
7999 File extensions such as @file{.1c} are handled by looking for the valid
8000 part of the extension and using that to determine the correct
8001 subdirectory of @code{mandir}. Valid section names are the digits
8002 @samp{0} through @samp{9}, and the letters @samp{l} and @samp{n}.
8004 Sometimes developers prefer to name a man page something like
8005 @file{foo.man} in the source, and then rename it to have the correct
8006 suffix, for example @file{foo.1}, when installing the file. Automake
8007 also supports this mode. For a valid section named @var{section},
8008 there is a corresponding directory named @samp{man@var{section}dir},
8009 and a corresponding @code{_MANS} variable. Files listed in such a
8010 variable are installed in the indicated section. If the file already
8011 has a valid suffix, then it is installed as-is; otherwise the file
8012 suffix is changed to match the section.
8014 For instance, consider this example:
8016 man1_MANS = rename.man thesame.1 alsothesame.1c
8020 In this case, @file{rename.man} will be renamed to @file{rename.1} when
8021 installed, but the other files will keep their names.
8023 @cindex Target, @code{install-man}
8024 @cindex Option, @option{no-installman}
8025 @cindex @code{install-man} target
8026 @cindex @option{no-installman} option
8027 @opindex no-installman
8028 @trindex install-man
8030 By default, man pages are installed by @samp{make install}. However,
8031 since the GNU project does not require man pages, many maintainers do
8032 not expend effort to keep the man pages up to date. In these cases, the
8033 @option{no-installman} option will prevent the man pages from being
8034 installed by default. The user can still explicitly install them via
8035 @samp{make install-man}.
8037 For fast installation, with many files it is preferable to use
8038 @samp{man@var{section}_MANS} over @samp{man_MANS} as well as files that
8039 do not need to be renamed.
8041 Man pages are not currently considered to be source, because it is not
8042 uncommon for man pages to be automatically generated. Therefore they
8043 are not automatically included in the distribution. However, this can
8044 be changed by use of the @code{dist_} prefix. For instance here is
8045 how to distribute and install the two man pages of GNU @command{cpio}
8046 (which includes both Texinfo documentation and man pages):
8049 dist_man_MANS = cpio.1 mt.1
8052 The @code{nobase_} prefix is meaningless for man pages and is
8056 @cindex @code{notrans_} prefix
8057 @cindex Man page renaming, avoiding
8058 @cindex Avoiding man page renaming
8060 Executables and manpages may be renamed upon installation
8061 (@pxref{Renaming}). For manpages this can be avoided by use of the
8062 @code{notrans_} prefix. For instance, suppose an executable @samp{foo}
8063 allowing to access a library function @samp{foo} from the command line.
8064 The way to avoid renaming of the @file{foo.3} manpage is:
8068 notrans_man_MANS = foo.3
8071 @cindex @code{notrans_} and @code{dist_} or @code{nodist_}
8072 @cindex @code{dist_} and @code{notrans_}
8073 @cindex @code{nodist_} and @code{notrans_}
8075 @samp{notrans_} must be specified first when used in conjunction with
8076 either @samp{dist_} or @samp{nodist_} (@pxref{Fine-grained Distribution
8077 Control}). For instance:
8080 notrans_dist_man3_MANS = bar.3
8084 @chapter What Gets Installed
8086 @cindex Installation support
8087 @cindex @samp{make install} support
8089 Naturally, Automake handles the details of actually installing your
8090 program once it has been built. All files named by the various
8091 primaries are automatically installed in the appropriate places when the
8092 user runs @samp{make install}.
8095 * Basics of Installation:: What gets installed where
8096 * The Two Parts of Install:: Installing data and programs separately
8097 * Extending Installation:: Adding your own rules for installation
8098 * Staged Installs:: Installation in a temporary location
8099 * Install Rules for the User:: Useful additional rules
8102 @node Basics of Installation
8103 @section Basics of Installation
8105 A file named in a primary is installed by copying the built file into
8106 the appropriate directory. The base name of the file is used when
8110 bin_PROGRAMS = hello subdir/goodbye
8113 In this example, both @samp{hello} and @samp{goodbye} will be installed
8114 in @samp{$(bindir)}.
8116 Sometimes it is useful to avoid the basename step at install time. For
8117 instance, you might have a number of header files in subdirectories of
8118 the source tree that are laid out precisely how you want to install
8119 them. In this situation you can use the @code{nobase_} prefix to
8120 suppress the base name step. For example:
8123 nobase_include_HEADERS = stdio.h sys/types.h
8127 will install @file{stdio.h} in @samp{$(includedir)} and @file{types.h}
8128 in @samp{$(includedir)/sys}.
8130 For most file types, Automake will install multiple files at once, while
8131 avoiding command line length issues (@pxref{Length Limitations}). Since
8132 some @command{install} programs will not install the same file twice in
8133 one invocation, you may need to ensure that file lists are unique within
8134 one variable such as @samp{nobase_include_HEADERS} above.
8136 You should not rely on the order in which files listed in one variable
8137 are installed. Likewise, to cater for parallel make, you should not
8138 rely on any particular file installation order even among different
8139 file types (library dependencies are an exception here).
8142 @node The Two Parts of Install
8143 @section The Two Parts of Install
8145 Automake generates separate @code{install-data} and @code{install-exec}
8146 rules, in case the installer is installing on multiple machines that
8147 share directory structure---these targets allow the machine-independent
8148 parts to be installed only once. @code{install-exec} installs
8149 platform-dependent files, and @code{install-data} installs
8150 platform-independent files. The @code{install} target depends on both
8151 of these targets. While Automake tries to automatically segregate
8152 objects into the correct category, the @file{Makefile.am} author is, in
8153 the end, responsible for making sure this is done correctly.
8154 @trindex install-data
8155 @trindex install-exec
8157 @cindex Install, two parts of
8159 Variables using the standard directory prefixes @samp{data},
8160 @samp{info}, @samp{man}, @samp{include}, @samp{oldinclude},
8161 @samp{pkgdata}, or @samp{pkginclude} are installed by
8162 @code{install-data}.
8164 Variables using the standard directory prefixes @samp{bin},
8165 @samp{sbin}, @samp{libexec}, @samp{sysconf}, @samp{localstate},
8166 @samp{lib}, or @samp{pkglib} are installed by @code{install-exec}.
8168 For instance, @code{data_DATA} files are installed by @code{install-data},
8169 while @code{bin_PROGRAMS} files are installed by @code{install-exec}.
8171 Any variable using a user-defined directory prefix with
8172 @samp{exec} in the name (e.g.,
8173 @c Keep in sync with primary-prefix-couples-documented-valid.test.
8174 @code{myexecbin_PROGRAMS}) is installed by @code{install-exec}. All
8175 other user-defined prefixes are installed by @code{install-data}.
8177 @node Extending Installation
8178 @section Extending Installation
8180 It is possible to extend this mechanism by defining an
8181 @code{install-exec-local} or @code{install-data-local} rule. If these
8182 rules exist, they will be run at @samp{make install} time. These
8183 rules can do almost anything; care is required.
8184 @trindex install-exec-local
8185 @trindex install-data-local
8187 Automake also supports two install hooks, @code{install-exec-hook} and
8188 @code{install-data-hook}. These hooks are run after all other install
8189 rules of the appropriate type, exec or data, have completed. So, for
8190 instance, it is possible to perform post-installation modifications
8191 using an install hook. @xref{Extending}, for some examples.
8192 @cindex Install hook
8194 @node Staged Installs
8195 @section Staged Installs
8198 Automake generates support for the @code{DESTDIR} variable in all
8199 install rules. @code{DESTDIR} is used during the @samp{make install}
8200 step to relocate install objects into a staging area. Each object and
8201 path is prefixed with the value of @code{DESTDIR} before being copied
8202 into the install area. Here is an example of typical DESTDIR usage:
8205 mkdir /tmp/staging &&
8206 make DESTDIR=/tmp/staging install
8209 The @command{mkdir} command avoids a security problem if the attacker
8210 creates a symbolic link from @file{/tmp/staging} to a victim area;
8211 then @command{make} places install objects in a directory tree built under
8212 @file{/tmp/staging}. If @file{/gnu/bin/foo} and
8213 @file{/gnu/share/aclocal/foo.m4} are to be installed, the above command
8214 would install @file{/tmp/staging/gnu/bin/foo} and
8215 @file{/tmp/staging/gnu/share/aclocal/foo.m4}.
8217 This feature is commonly used to build install images and packages
8220 Support for @code{DESTDIR} is implemented by coding it directly into
8221 the install rules. If your @file{Makefile.am} uses a local install
8222 rule (e.g., @code{install-exec-local}) or an install hook, then you
8223 must write that code to respect @code{DESTDIR}.
8225 @xref{Makefile Conventions, , , standards, The GNU Coding Standards},
8226 for another usage example.
8228 @node Install Rules for the User
8229 @section Install Rules for the User
8231 Automake also generates rules for targets @code{uninstall},
8232 @code{installdirs}, and @code{install-strip}.
8234 @trindex installdirs
8235 @trindex install-strip
8237 Automake supports @code{uninstall-local} and @code{uninstall-hook}.
8238 There is no notion of separate uninstalls for ``exec'' and ``data'', as
8239 these features would not provide additional functionality.
8241 Note that @code{uninstall} is not meant as a replacement for a real
8246 @chapter What Gets Cleaned
8248 @cindex @samp{make clean} support
8250 The GNU Makefile Standards specify a number of different clean rules.
8251 @xref{Standard Targets, , Standard Targets for Users, standards,
8252 The GNU Coding Standards}.
8254 Generally the files that can be cleaned are determined automatically by
8255 Automake. Of course, Automake also recognizes some variables that can
8256 be defined to specify additional files to clean. These variables are
8257 @code{MOSTLYCLEANFILES}, @code{CLEANFILES}, @code{DISTCLEANFILES}, and
8258 @code{MAINTAINERCLEANFILES}.
8259 @vindex MOSTLYCLEANFILES
8261 @vindex DISTCLEANFILES
8262 @vindex MAINTAINERCLEANFILES
8264 @trindex mostlyclean-local
8265 @trindex clean-local
8266 @trindex distclean-local
8267 @trindex maintainer-clean-local
8268 When cleaning involves more than deleting some hard-coded list of
8269 files, it is also possible to supplement the cleaning rules with your
8270 own commands. Simply define a rule for any of the
8271 @code{mostlyclean-local}, @code{clean-local}, @code{distclean-local},
8272 or @code{maintainer-clean-local} targets (@pxref{Extending}). A common
8273 case is deleting a directory, for instance, a directory created by the
8281 Since @command{make} allows only one set of rules for a given target,
8282 a more extensible way of writing this is to use a separate target
8283 listed as a dependency:
8286 clean-local: clean-local-check
8287 .PHONY: clean-local-check
8292 As the GNU Standards aren't always explicit as to which files should
8293 be removed by which rule, we've adopted a heuristic that we believe
8294 was first formulated by Fran@,{c}ois Pinard:
8298 If @command{make} built it, and it is commonly something that one would
8299 want to rebuild (for instance, a @file{.o} file), then
8300 @code{mostlyclean} should delete it.
8303 Otherwise, if @command{make} built it, then @code{clean} should delete it.
8306 If @command{configure} built it, then @code{distclean} should delete it.
8309 If the maintainer built it (for instance, a @file{.info} file), then
8310 @code{maintainer-clean} should delete it. However
8311 @code{maintainer-clean} should not delete anything that needs to exist
8312 in order to run @samp{./configure && make}.
8315 We recommend that you follow this same set of heuristics in your
8320 @chapter What Goes in a Distribution
8323 * Basics of Distribution:: Files distributed by default
8324 * Fine-grained Distribution Control:: @code{dist_} and @code{nodist_} prefixes
8325 * The dist Hook:: A target for last-minute distribution changes
8326 * Checking the Distribution:: @samp{make distcheck} explained
8327 * The Types of Distributions:: A variety of formats and compression methods
8330 @node Basics of Distribution
8331 @section Basics of Distribution
8333 @cindex @samp{make dist}
8338 The @code{dist} rule in the generated @file{Makefile.in} can be used
8339 to generate a gzipped @code{tar} file and other flavors of archive for
8340 distribution. The file is named based on the @code{PACKAGE} and
8341 @code{VERSION} variables defined by @code{AM_INIT_AUTOMAKE}
8342 (@pxref{Macros}); more precisely the gzipped @code{tar} file is named
8343 @samp{@var{package}-@var{version}.tar.gz}.
8345 You can use the @command{make} variable @code{GZIP_ENV} to control how gzip
8346 is run. The default setting is @option{--best}.
8348 @cindex @code{m4_include}, distribution
8349 @cindex @code{include}, distribution
8352 For the most part, the files to distribute are automatically found by
8353 Automake: all source files are automatically included in a distribution,
8354 as are all @file{Makefile.am} and @file{Makefile.in} files. Automake also
8355 has a built-in list of commonly used files that are automatically
8356 included if they are found in the current directory (either physically,
8357 or as the target of a @file{Makefile.am} rule); this list is printed by
8358 @samp{automake --help}. Note that some files in this list are actually
8359 distributed only if other certain conditions hold (for example,
8360 @c Keep in sync with autodist-config-headers.test.
8361 the @file{config.h.top} and @file{config.h.bot} files are automatically
8362 distributed only if, e.g., @samp{AC_CONFIG_HEADERS([config.h])} is used
8363 in @file{configure.ac}). Also, files that are read by @command{configure}
8364 (i.e.@: the source files corresponding to the files specified in various
8365 Autoconf macros such as @code{AC_CONFIG_FILES} and siblings) are
8366 automatically distributed. Files included in a @file{Makefile.am} (using
8367 @code{include}) or in @file{configure.ac} (using @code{m4_include}), and
8368 helper scripts installed with @samp{automake --add-missing} are also
8372 Still, sometimes there are files that must be distributed, but which
8373 are not covered in the automatic rules. These files should be listed in
8374 the @code{EXTRA_DIST} variable. You can mention files from
8375 subdirectories in @code{EXTRA_DIST}.
8377 You can also mention a directory in @code{EXTRA_DIST}; in this case the
8378 entire directory will be recursively copied into the distribution.
8379 Please note that this will also copy @emph{everything} in the directory,
8380 including, e.g., Subversion's @file{.svn} private directories or CVS/RCS
8381 version control files. We recommend against using this feature.
8384 @vindex DIST_SUBDIRS
8385 If you define @code{SUBDIRS}, Automake will recursively include the
8386 subdirectories in the distribution. If @code{SUBDIRS} is defined
8387 conditionally (@pxref{Conditionals}), Automake will normally include
8388 all directories that could possibly appear in @code{SUBDIRS} in the
8389 distribution. If you need to specify the set of directories
8390 conditionally, you can set the variable @code{DIST_SUBDIRS} to the
8391 exact list of subdirectories to include in the distribution
8392 (@pxref{Conditional Subdirectories}).
8395 @node Fine-grained Distribution Control
8396 @section Fine-grained Distribution Control
8400 Sometimes you need tighter control over what does @emph{not} go into the
8401 distribution; for instance, you might have source files that are
8402 generated and that you do not want to distribute. In this case
8403 Automake gives fine-grained control using the @code{dist} and
8404 @code{nodist} prefixes. Any primary or @code{_SOURCES} variable can be
8405 prefixed with @code{dist_} to add the listed files to the distribution.
8406 Similarly, @code{nodist_} can be used to omit the files from the
8409 As an example, here is how you would cause some data to be distributed
8410 while leaving some source code out of the distribution:
8413 dist_data_DATA = distribute-this
8415 nodist_foo_SOURCES = do-not-distribute.c
8419 @section The dist Hook
8423 Occasionally it is useful to be able to change the distribution before
8424 it is packaged up. If the @code{dist-hook} rule exists, it is run
8425 after the distribution directory is filled, but before the actual tar
8426 (or shar) file is created. One way to use this is for distributing
8427 files in subdirectories for which a new @file{Makefile.am} is overkill:
8431 mkdir $(distdir)/random
8432 cp -p $(srcdir)/random/a1 $(srcdir)/random/a2 $(distdir)/random
8435 Another way to use this is for removing unnecessary files that get
8436 recursively included by specifying a directory in EXTRA_DIST:
8442 rm -rf `find $(distdir)/doc -type d -name .svn`
8447 Two variables that come handy when writing @code{dist-hook} rules are
8448 @samp{$(distdir)} and @samp{$(top_distdir)}.
8450 @samp{$(distdir)} points to the directory where the @code{dist} rule
8451 will copy files from the current directory before creating the
8452 tarball. If you are at the top-level directory, then @samp{distdir =
8453 $(PACKAGE)-$(VERSION)}. When used from subdirectory named
8454 @file{foo/}, then @samp{distdir = ../$(PACKAGE)-$(VERSION)/foo}.
8455 @samp{$(distdir)} can be a relative or absolute path, do not assume
8458 @samp{$(top_distdir)} always points to the root directory of the
8459 distributed tree. At the top-level it's equal to @samp{$(distdir)}.
8460 In the @file{foo/} subdirectory
8461 @samp{top_distdir = ../$(PACKAGE)-$(VERSION)}.
8462 @samp{$(top_distdir)} too can be a relative or absolute path.
8464 Note that when packages are nested using @code{AC_CONFIG_SUBDIRS}
8465 (@pxref{Subpackages}), then @samp{$(distdir)} and
8466 @samp{$(top_distdir)} are relative to the package where @samp{make
8467 dist} was run, not to any sub-packages involved.
8469 @node Checking the Distribution
8470 @section Checking the Distribution
8472 @cindex @samp{make distcheck}
8473 @cindex @samp{make distcleancheck}
8474 @vindex distcleancheck_listfiles
8475 @cindex @samp{make distuninstallcheck}
8476 @vindex distuninstallcheck_listfiles
8479 Automake also generates a @code{distcheck} rule that can be of help to
8480 ensure that a given distribution will actually work. @code{distcheck}
8481 makes a distribution, then tries to do a @code{VPATH} build
8482 (@pxref{VPATH Builds}), run the test suite, and finally make another
8483 tarball to ensure the distribution is self-contained.
8485 @vindex AM_DISTCHECK_CONFIGURE_FLAGS
8486 @vindex DISTCHECK_CONFIGURE_FLAGS
8487 Building the package involves running @samp{./configure}. If you need
8488 to supply additional flags to @command{configure}, define them in the
8489 @code{AM_DISTCHECK_CONFIGURE_FLAGS} variable in your top-level
8490 @file{Makefile.am}. The user can still extend or override the flags
8491 provided there by defining the @code{DISTCHECK_CONFIGURE_FLAGS} variable,
8492 on the command line when invoking @command{make}.
8494 Still, developers are encouraged to strive to make their code buildable
8495 without requiring any special configure option; thus, in general, you
8496 shouldn't define @code{AM_DISTCHECK_CONFIGURE_FLAGS}. However, there
8497 might be few scenarios in which the use of this variable is justified.
8498 GNU @command{m4} offers an example. GNU @command{m4} configures by
8499 default with its experimental and seldom used "changeword" feature
8500 disabled; so in its case it is useful to have @command{make distcheck}
8501 run configure with the @option{--with-changeword} option, to ensure that
8502 the code for changeword support still compiles correctly.
8503 GNU @command{m4} also employs the @code{AM_DISTCHECK_CONFIGURE_FLAGS}
8504 variable to stress-test the use of @option{--program-prefix=g}, since at
8505 one point the @command{m4} build system had a bug where @command{make
8506 installcheck} was wrongly assuming it could blindly test "@command{m4}",
8507 rather than the just-installed "@command{gm4}".
8509 @trindex distcheck-hook
8510 If the @code{distcheck-hook} rule is defined in your top-level
8511 @file{Makefile.am}, then it will be invoked by @code{distcheck} after
8512 the new distribution has been unpacked, but before the unpacked copy
8513 is configured and built. Your @code{distcheck-hook} can do almost
8514 anything, though as always caution is advised. Generally this hook is
8515 used to check for potential distribution errors not caught by the
8516 standard mechanism. Note that @code{distcheck-hook} as well as
8517 @code{AM_DISTCHECK_CONFIGURE_FLAGS} and @code{DISTCHECK_CONFIGURE_FLAGS}
8518 are not honored in a subpackage @file{Makefile.am}, but the flags from
8519 @code{AM_DISTCHECK_CONFIGURE_FLAGS} and @code{DISTCHECK_CONFIGURE_FLAGS}
8520 are passed down to the @command{configure} script of the subpackage.
8522 @trindex distcleancheck
8523 @vindex DISTCLEANFILES
8524 @vindex distcleancheck_listfiles
8525 Speaking of potential distribution errors, @code{distcheck} also
8526 ensures that the @code{distclean} rule actually removes all built
8527 files. This is done by running @samp{make distcleancheck} at the end of
8528 the @code{VPATH} build. By default, @code{distcleancheck} will run
8529 @code{distclean} and then make sure the build tree has been emptied by
8530 running @samp{$(distcleancheck_listfiles)}. Usually this check will
8531 find generated files that you forgot to add to the @code{DISTCLEANFILES}
8532 variable (@pxref{Clean}).
8534 The @code{distcleancheck} behavior should be OK for most packages,
8535 otherwise you have the possibility to override the definition of
8536 either the @code{distcleancheck} rule, or the
8537 @samp{$(distcleancheck_listfiles)} variable. For instance, to disable
8538 @code{distcleancheck} completely, add the following rule to your
8539 top-level @file{Makefile.am}:
8546 If you want @code{distcleancheck} to ignore built files that have not
8547 been cleaned because they are also part of the distribution, add the
8548 following definition instead:
8550 @c Keep in sync with distcleancheck.test.
8552 distcleancheck_listfiles = \
8553 find . -type f -exec sh -c 'test -f $(srcdir)/$$1 || echo $$1' \
8557 The above definition is not the default because it's usually an error if
8558 your Makefiles cause some distributed files to be rebuilt when the user
8559 build the package. (Think about the user missing the tool required to
8560 build the file; or if the required tool is built by your package,
8561 consider the cross-compilation case where it can't be run.) There is
8562 an entry in the FAQ about this (@pxref{distcleancheck}), make sure you
8563 read it before playing with @code{distcleancheck_listfiles}.
8565 @code{distcheck} also checks that the @code{uninstall} rule works
8566 properly, both for ordinary and @code{DESTDIR} builds. It does this
8567 by invoking @samp{make uninstall}, and then it checks the install tree
8568 to see if any files are left over. This check will make sure that you
8569 correctly coded your @code{uninstall}-related rules.
8571 By default, the checking is done by the @code{distuninstallcheck} rule,
8572 and the list of files in the install tree is generated by
8573 @samp{$(distuninstallcheck_listfiles)} (this is a variable whose value is
8574 a shell command to run that prints the list of files to stdout).
8576 Either of these can be overridden to modify the behavior of
8577 @code{distcheck}. For instance, to disable this check completely, you
8585 @node The Types of Distributions
8586 @section The Types of Distributions
8588 Automake generates rules to provide archives of the project for
8589 distributions in various formats. Their targets are:
8593 @item @code{dist-bzip2}
8594 Generate a bzip2 tar archive of the distribution. bzip2 archives are
8595 frequently smaller than gzipped archives.
8596 By default, this rule makes @samp{bzip2} use a compression option of @option{-9}.
8597 To make it use a different one, set the @env{BZIP2} environment variable.
8598 For example, @samp{make dist-bzip2 BZIP2=-7}.
8601 @item @code{dist-gzip}
8602 Generate a gzip tar archive of the distribution.
8605 @item @code{dist-lzip}
8606 Generate an @samp{lzip} tar archive of the distribution. @command{lzip}
8607 archives are frequently smaller than @command{bzip2}-compressed archives.
8610 @item @code{dist-lzma}
8611 Generate an @samp{lzma} tar archive of the distribution.
8612 The @samp{lzma} format is obsolete, you should use the @samp{xz} format
8613 instead. @emph{Support for @samp{lzma}-compressed archives will be
8614 removed in the next major Automake release.}
8617 @item @code{dist-shar}
8618 Generate a shar archive of the distribution.
8622 @item @code{dist-xz}
8623 Generate an @samp{xz} tar archive of the distribution. @command{xz}
8624 archives are frequently smaller than @command{bzip2}-compressed archives.
8625 The @samp{xz} format displaces the obsolete @samp{lzma} format.
8626 By default, this rule makes @samp{xz} use a compression option of
8627 @option{-e}. To make it use a different one, set the @env{XZ_OPT}
8628 environment variable. For example, run this command to use the
8629 default compression ratio, but with a progress indicator:
8630 @samp{make dist-xz XZ_OPT=-7e}.
8633 @item @code{dist-zip}
8634 Generate a zip archive of the distribution.
8637 @item @code{dist-tarZ}
8638 Generate a compressed tar archive of
8643 The rule @code{dist} (and its historical synonym @code{dist-all}) will
8644 create archives in all the enabled formats, @ref{Options}. By
8645 default, only the @code{dist-gzip} target is hooked to @code{dist}.
8649 @chapter Support for test suites
8652 @cindex @code{make check}
8655 Automake can generate code to handle two kinds of test suites. One is
8656 based on integration with the @command{dejagnu} framework. The other
8657 (and most used) form is based on the use of generic test scripts, and
8658 its activation is triggered by the definition of the special @code{TESTS}
8659 variable. This second form allows for various degrees of sophistication
8660 and customization; in particular, it allows for concurrent execution
8661 of test scripts, use of established test protocols such as TAP, and
8662 definition of custom test drivers and test runners.
8665 In either case, the testsuite is invoked via @samp{make check}.
8668 * Generalities about Testing:: Concepts and terminology about testing
8669 * Simple Tests:: Listing test scripts in @code{TESTS}
8670 * Custom Test Drivers:: Writing and using custom test drivers
8671 * Using the TAP test protocol:: Integrating test scripts that use the TAP protocol
8672 * DejaGnu Tests:: Interfacing with the @command{dejagnu} testing framework
8673 * Install Tests:: Running tests on installed packages
8676 @node Generalities about Testing
8677 @section Generalities about Testing
8679 The purpose of testing is to determine whether a program or system behaves
8680 as expected (e.g., known inputs produce the expected outputs, error
8681 conditions are correctly handled or reported, and older bugs do not
8685 The minimal unit of testing is usually called @emph{test case}, or simply
8686 @emph{test}. How a test case is defined or delimited, and even what
8687 exactly @emph{constitutes} a test case, depends heavily on the testing
8688 paradigm and/or framework in use, so we won't attempt any more precise
8689 definition. The set of the test cases for a given program or system
8690 constitutes its @emph{testsuite}.
8692 @cindex test harness
8693 @cindex testsuite harness
8694 A @emph{test harness} (also @emph{testsuite harness}) is a program or
8695 software component that executes all (or part of) the defined test cases,
8696 analyzes their outcomes, and report or register these outcomes
8697 appropriately. Again, the details of how this is accomplished (and how
8698 the developer and user can influence it or interface with it) varies
8699 wildly, and we'll attempt no precise definition.
8702 @cindex test failure
8703 A test is said to @emph{pass} when it can determine that the condition or
8704 behaviour it means to verify holds, and is said to @emph{fail} when it can
8705 determine that such condition of behaviour does @emph{not} hold.
8708 Sometimes, tests can rely on non-portable tools or prerequisites, or
8709 simply make no sense on a given system (for example, a test checking a
8710 Windows-specific feature makes no sense on a GNU/Linux system). In this
8711 case, accordingly to the definition above, the tests can neither be
8712 considered passed nor failed; instead, they are @emph{skipped} -- i.e.,
8713 they are not run, or their result is anyway ignored for what concerns
8714 the count of failures an successes. Skips are usually explicitly
8715 reported though, so that the user will be aware that not all of the
8716 testsuite has really run.
8719 @cindex expected failure
8720 @cindex expected test failure
8722 @cindex unexpected pass
8723 @cindex unexpected test pass
8724 It's not uncommon, especially during early development stages, that some
8725 tests fail for known reasons, and that the developer doesn't want to
8726 tackle these failures immediately (this is especially true when the
8727 failing tests deal with corner cases). In this situation, the better
8728 policy is to declare that each of those failures is an @emph{expected
8729 failure} (or @emph{xfail}). In case a test that is expected to fail ends
8730 up passing instead, many testing environments will flag the result as a
8731 special kind of failure called @emph{unexpected pass} (or @emph{xpass}).
8734 @cindex Distinction between errors and failures in testsuites
8735 Many testing environments and frameworks distinguish between test failures
8736 and hard errors. As we've seen, a test failure happens when some invariant
8737 or expected behaviour of the software under test is not met. An @emph{hard
8738 error} happens when e.g., the set-up of a test case scenario fails, or when
8739 some other unexpected or highly undesirable condition is encountered (for
8740 example, the program under test experiences a segmentation fault).
8742 @emph{TODO}: Links to other test harnesses (esp. those sharing our
8746 @section Simple Tests
8749 * Scripts-based Testsuites:: Automake-specific concepts and terminology
8750 * Serial Test Harness:: Older (and obsolescent) serial test harness
8751 * Parallel Test Harness:: Generic concurrent test harness
8754 @node Scripts-based Testsuites
8755 @subsection Scripts-based Testsuites
8757 If the special variable @code{TESTS} is defined, its value is taken to be
8758 a list of programs or scripts to run in order to do the testing. Under
8759 the appropriate circumstances, it's possible for @code{TESTS} to list
8760 also data files to be passed to one or more test scripts defined by
8761 different means (the so-called ``log compilers'', @pxref{Parallel Test
8764 Test scripts can be executed serially or concurrently. Automake
8765 supports both these kinds of test execution, with the serial test harness
8766 being the default (for backward-compatibility reasons only, as its use
8767 is nowadays discouraged). The concurrent test harness relies on the
8768 concurrence capabilities (if any) offered by the underlying @command{make}
8769 implementation, and can thus only be as good as those are.
8771 By default, only the exit statuses of the test scripts are considered when
8772 determining the testsuite outcome. But Automake allows also the use of
8773 more complex test protocols, either standard (@pxref{Using the TAP test
8774 protocol}) or custom (@pxref{Custom Test Drivers}). Note that you can
8775 enable such protocols only when the parallel harness is used: they won't
8776 work with the serial test harness. In the rest of this section we are
8777 going to concentrate mostly on protocol-less tests, since we'll have later
8778 a whole section devoted to the use of test protocols (again, @pxref{Custom
8781 @cindex Exit status 77, special interpretation
8782 @cindex Exit status 99, special interpretation
8783 When no test protocol is in use, an exit status of 0 from a test script will
8784 denote a success, an exit status of 77 a skipped test, an exit status of 99
8785 an hard error, and any other exit status will denote a failure.
8787 @cindex Tests, expected failure
8788 @cindex Expected test failure
8790 @vindex DISABLE_HARD_ERRORS
8791 @cindex Disabling hard errors
8792 You may define the variable @code{XFAIL_TESTS} to a list of tests
8793 (usually a subset of @code{TESTS}) that are expected to fail; this will
8794 effectively reverse the result of those tests (with the provision that
8795 skips and hard errors remain untouched). You may also instruct the
8796 testsuite harness to treat hard errors like simple failures, by defining
8797 the @code{DISABLE_HARD_ERRORS} make variable to a nonempty value.
8799 Note however that, for tests based on more complex test protocols,
8800 the exact effects of @code{XFAIL_TESTS} and @code{DISABLE_HARD_ERRORS}
8801 might change, or they might even have no effect at all (for example,
8802 @c Keep this in sync with tap-no-disable-hard-errors.test.
8803 in tests using TAP, there is not way to disable hard errors, and the
8804 @code{DISABLE_HARD_ERRORS} variable has no effect on them).
8806 @anchor{Testsuite progress on console}
8807 @cindex Testsuite progress on console
8808 The result of each test case run by the scripts in @code{TESTS} will be
8809 printed on standard output, along with the test name. For test protocols
8810 that allow more test cases per test script (such as TAP), a number,
8811 identifier and/or brief description specific for the single test case is
8812 expected to be printed in addition to the name of the test script. The
8813 possible results (whose meanings should be clear from the previous
8814 @ref{Generalities about Testing}) are @code{PASS}, @code{FAIL},
8815 @code{SKIP}, @code{XFAIL}, @code{XPASS} and @code{ERROR}. Here is an
8816 example of output from an hypothetical testsuite that uses both plain
8818 @c Keep in sync with tap-doc.test.
8821 PASS: zardoz.tap 1 - Daemon started
8822 PASS: zardoz.tap 2 - Daemon responding
8823 SKIP: zardoz.tap 3 - Daemon uses /proc # SKIP /proc is not mounted
8824 PASS: zardoz.tap 4 - Daemon stopped
8827 XFAIL: mu.tap 2 # TODO frobnication not yet implemented
8831 A testsuite summary (expected to report at least the number of run,
8832 skipped and failed tests) will be printed at the end of the testsuite
8835 @anchor{Simple tests and color-tests}
8836 @vindex AM_COLOR_TESTS
8837 @cindex Colorized testsuite output
8838 If the Automake option @code{color-tests} is used (@pxref{Options})
8839 and standard output is connected to a capable terminal, then the test
8840 results and the summary are colored appropriately. The user can disable
8841 colored output by setting the @command{make} variable
8842 @samp{AM_COLOR_TESTS=no}, or force colored output even without a connecting
8843 terminal with @samp{AM_COLOR_TESTS=always}. It's also worth noting that
8844 some @command{make} implementations, when used in parallel mode, have
8845 slightly different semantics (@pxref{Parallel make,,, autoconf,
8846 The Autoconf Manual}), which can break the automatic detection of a
8847 connection to a capable terminal. If this is the case, you'll have to
8848 resort to the use of @samp{AM_COLOR_TESTS=always} in order to have the
8849 testsuite output colorized.
8851 Test programs that need data files should look for them in @code{srcdir}
8852 (which is both a make variable and an environment variable made available
8853 to the tests), so that they work when building in a separate directory
8854 (@pxref{Build Directories, , Build Directories , autoconf,
8855 The Autoconf Manual}), and in particular for the @code{distcheck} rule
8856 (@pxref{Checking the Distribution}).
8859 @vindex TESTS_ENVIRONMENT
8860 @vindex AM_TESTS_ENVIRONMENT
8861 The @code{AM_TESTS_ENVIRONMENT} and @code{TESTS_ENVIRONMENT} variables can
8862 be used to run initialization code and set environment variables for the
8863 test scripts. The former variable is developer-reserved, and can be
8864 defined in the @file{Makefile.am}, while the latter is reserved for the
8865 user, which can employ it to extend or override the settings in the
8866 former; for this to work portably, however, the contents of a non-empty
8867 @code{AM_TESTS_ENVIRONMENT} @emph{must} be terminated by a semicolon.
8869 @vindex AM_TESTS_FD_REDIRECT
8870 The @code{AM_TESTS_FD_REDIRECT} variable can be used to define file
8871 descriptor redirections for the test scripts. One might think that
8872 @code{AM_TESTS_ENVIRONMENT} could be used for this purpose, but experience
8873 has shown that doing so portably is practically impossible. The main
8874 hurdle is constituted by Korn shells, which usually set the close-on-exec
8875 flag on file descriptors opened with the @command{exec} builtin, thus
8876 rendering an idiom like @code{AM_TESTS_ENVIRONMENT = exec 9>&2;}
8877 ineffectual. This issue also affects some Bourne shells, such as the
8878 HP-UX's @command{/bin/sh},
8879 @c FIXME: should we offer a link to the relevant discussions on the
8880 @c bug-autoconf list?
8882 @c Keep in sync with tests-environment-backcompat.test.
8884 AM_TESTS_ENVIRONMENT = \
8885 ## Some environment initializations are kept in a separate shell
8886 ## file `tests-env.sh', which can make it easier to also run tests
8887 ## from the command line.
8888 . $(srcdir)/tests-env.sh; \
8889 ## On Solaris, prefer more POSIX-compliant versions of the standard
8890 ## tools by default.
8891 if test -d /usr/xpg4/bin; then \
8892 PATH=/usr/xpg4/bin:$$PATH; export PATH; \
8894 @c $$ restore font-lock
8895 ## With this, the test scripts will be able to print diagnostic
8896 ## messages to the original standard error stream, even if the test
8897 ## driver redirects the stderr of the test scripts to a log file
8898 ## before executing them.
8899 AM_TESTS_FD_REDIRECT = 9>&2
8903 Note however that @code{AM_TESTS_ENVIRONMENT} is, for historical and
8904 implementation reasons, @emph{not} supported by the serial harness
8905 (@pxref{Serial Test Harness}).
8907 Automake ensures that each file listed in @code{TESTS} is built before
8908 it is run; you can list both source and derived programs (or scripts)
8909 in @code{TESTS}; the generated rule will look both in @code{srcdir} and
8910 @file{.}. For instance, you might want to run a C program as a test.
8911 To do this you would list its name in @code{TESTS} and also in
8912 @code{check_PROGRAMS}, and then specify it as you would any other
8915 Programs listed in @code{check_PROGRAMS} (and @code{check_LIBRARIES},
8916 @code{check_LTLIBRARIES}...) are only built during @code{make check},
8917 not during @code{make all}. You should list there any program needed
8918 by your tests that does not need to be built by @code{make all}. Note
8919 that @code{check_PROGRAMS} are @emph{not} automatically added to
8920 @code{TESTS} because @code{check_PROGRAMS} usually lists programs used
8921 by the tests, not the tests themselves. Of course you can set
8922 @code{TESTS = $(check_PROGRAMS)} if all your programs are test cases.
8924 @node Serial Test Harness
8925 @subsection Serial Test Harness
8927 @emph{NOTE:} This harness, while still being the default one, is
8928 obsolescent, and kept mostly for backward-compatibility reasons.
8929 The user is advised to use the parallel test harness instead
8930 (@pxref{Parallel Test Harness}).
8932 The serial harness operates by simply running the tests serially, one at
8933 the time, without any I/O redirection. It's up to the user to implement
8934 logging of tests' output, if that's requited or desired.
8935 @c TODO: give an example of how this can be done.
8937 For historical and implementation reasons, the @code{AM_TESTS_ENVIRONMENT}
8938 variable is @emph{not} supported by this harness (it will be silently
8939 ignored if defined); only @code{TESTS_ENVIRONMENT} is, and it is to be
8940 considered a developer-reserved variable. This is done so that, when
8941 using the serial harness, @code{TESTS_ENVIRONMENT} can be defined to an
8942 invocation of an interpreter through which the tests are to be run.
8943 For instance, the following setup may be used to run tests with Perl:
8946 TESTS_ENVIRONMENT = $(PERL) -Mstrict -w
8947 TESTS = foo.pl bar.pl baz.pl
8951 It's important to note that the use of @code{TESTS_ENVIRONMENT} endorsed
8952 here would be @emph{invalid} with the parallel harness. That harness
8953 provides a more elegant way to achieve the same effect, with the further
8954 benefit of freeing the @code{TESTS_ENVIRONMENT} variable for the user
8955 (@pxref{Parallel Test Harness}).
8957 Another, less serious limit of the serial harness is that it doesn't
8958 really distinguish between simple failures and hard errors; this is
8959 due to historical reasons only, and might be fixed in future Automake
8962 @node Parallel Test Harness
8963 @subsection Parallel Test Harness
8964 @cindex @option{parallel-tests}, Using
8966 The parallel (or concurrent) test harness is enabled by the Automake option
8967 @option{parallel-tests}. It features automatic collection of the test
8968 scripts output in @file{.log} files, concurrent execution of tests with
8969 @code{make -j}, specification of inter-test dependencies, lazy reruns of
8970 tests that have not completed in a prior run, and hard errors for exceptional
8973 This harness is still somewhat experimental and may undergo changes in
8974 order to satisfy additional portability requirements.
8976 @anchor{Basics of test metadata}
8977 @vindex TEST_SUITE_LOG
8979 @cindex @file{.log} files
8980 @cindex @file{.trs} files
8981 @cindex test metadata
8982 The parallel test harness operates by defining a set of @command{make}
8983 rules that run the test scripts listed in @code{TESTS}, and, for each
8984 such script, save its output in a corresponding @file{.log} file and
8985 its results (and other ``metadata'', @pxref{API for Custom Test Drivers})
8986 in a corresponding @file{.trs} (as in @b{T}est @b{R}e@b{S}ults) file.
8987 @c We choose the `.trs' extension also because, at the time of writing,
8988 @c it isn't already used for other significant purposes; see e.g.:
8989 @c - http://filext.com/file-extension/trs
8990 @c - http://www.file-extensions.org/search/?searchstring=trs
8991 The @file{.log} file will contain all the output emitted by the test on
8992 its standard output and its standard error. The @file{.trs} file will
8993 contain, among the other things, the results of the test cases run by
8996 The parallel test harness will also create a summary log file,
8997 @code{TEST_SUITE_LOG}, which defaults to @file{test-suite.log} and requires
8998 a @file{.log} suffix. This file depends upon all the @file{.log} and
8999 @file{.trs} files created for the test scripts listed in @code{TESTS}.
9002 As with the serial harness above, by default one status line is printed
9003 per completed test, and a short summary after the suite has completed.
9004 However, standard output and standard error of the test are redirected
9005 to a per-test log file, so that parallel execution does not produce
9006 intermingled output. The output from failed tests is collected in the
9007 @file{test-suite.log} file. If the variable @samp{VERBOSE} is set, this
9008 file is output after the summary.
9009 @c FIXME: we should be clearer about what we mean exactly here ...
9010 For best results, the tests should be verbose by default now.
9012 @vindex TEST_EXTENSIONS
9014 Each couple of @file{.log} and @file{.trs} files is created when the
9015 corresponding test has completed. The set of log files is listed in
9016 the read-only variable @code{TEST_LOGS}, and defaults to @code{TESTS},
9017 with the executable extension if any (@pxref{EXEEXT}), as well as any
9018 suffix listed in @code{TEST_EXTENSIONS} removed, and @file{.log} appended.
9019 Results are undefined if a test file name ends in several concatenated
9020 suffixes. @code{TEST_EXTENSIONS} defaults to @file{.test}; it can be
9021 overridden by the user, in which case any extension listed in it must be
9022 constituted by a dot, followed by a non-digit alphabetic character,
9023 followed by any number of alphabetic characters.
9024 @c Keep in sync with test-extensions.test.
9025 For example, @samp{.sh}, @samp{.T} and @samp{.t1} are valid extensions,
9026 while @samp{.x-y}, @samp{.6c} and @samp{.t.1} are not.
9028 @vindex _LOG_COMPILE
9029 @vindex _LOG_COMPILER
9032 @vindex LOG_COMPILER
9034 @vindex @var{ext}_LOG_COMPILE
9035 @vindex @var{ext}_LOG_COMPILER
9036 @vindex @var{ext}_LOG_FLAGS
9037 @vindex AM_@var{ext}_LOG_FLAGS
9038 @vindex AM_LOG_FLAGS
9039 For tests that match an extension @code{.@var{ext}} listed in
9040 @code{TEST_EXTENSIONS}, you can provide a custom ``test runner'' using
9041 the variable @code{@var{ext}_LOG_COMPILER} (note the upper-case
9042 extension) and pass options in @code{AM_@var{ext}_LOG_FLAGS} and allow
9043 the user to pass options in @code{@var{ext}_LOG_FLAGS}. It will cause
9044 all tests with this extension to be called with this runner. For all
9045 tests without a registered extension, the variables @code{LOG_COMPILER},
9046 @code{AM_LOG_FLAGS}, and @code{LOG_FLAGS} may be used. For example,
9048 @c Keep in sync with parallel-tests-log-compiler-example.test.
9050 TESTS = foo.pl bar.py baz
9051 TEST_EXTENSIONS = .pl .py
9052 PL_LOG_COMPILER = $(PERL)
9053 AM_PL_LOG_FLAGS = -w
9054 PY_LOG_COMPILER = $(PYTHON)
9055 AM_PY_LOG_FLAGS = -v
9056 LOG_COMPILER = ./wrapper-script
9061 will invoke @samp{$(PERL) -w foo.pl}, @samp{$(PYTHON) -v bar.py},
9062 and @samp{./wrapper-script -d baz} to produce @file{foo.log},
9063 @file{bar.log}, and @file{baz.log}, respectively. The @file{foo.trs},
9064 @file{bar.trs} and @file{baz.trs} files will be automatically produced
9067 It's important to note that, differently from what we've seen for the
9068 serial test harness (@pxref{Parallel Test Harness}), the
9069 @code{AM_TESTS_ENVIRONMENT} and @code{TESTS_ENVIRONMENT} variables
9070 @emph{cannot} be use to define a custom test runner; the
9071 @code{LOG_COMPILER} and @code{LOG_FLAGS} (or their extension-specific
9072 counterparts) should be used instead:
9076 AM_TESTS_ENVIRONMENT = PERL5LIB='$(srcdir)/lib' $(PERL) -Mstrict -w
9081 AM_TESTS_ENVIRONMENT = PERL5LIB='$(srcdir)/lib'; export PERL5LIB;
9082 LOG_COMPILER = $(PERL)
9083 AM_LOG_FLAGS = -Mstrict -w
9086 By default, the test suite harness will run all tests, but there are
9087 several ways to limit the set of tests that are run:
9091 You can set the @code{TESTS} variable. For example, you can use a
9092 command like this to run only a subset of the tests:
9095 env TESTS="foo.test bar.test" make -e check
9098 Note however that the command above will unconditionally overwrite the
9099 @file{test-suite.log} file, thus clobbering the recorded results
9100 of any previous testsuite run. This might be undesirable for packages
9101 whose testsuite takes long time to execute. Luckily, this problem can
9102 easily be avoided by overriding also @code{TEST_SUITE_LOG} at runtime;
9105 @c Keep in sync with parallel-tests-log-override-2.test.
9107 env TEST_SUITE_LOG=partial.log TESTS="..." make -e check
9110 will write the result of the partial testsuite runs to the
9111 @file{partial.log}, without touching @file{test-suite.log}.
9114 You can set the @code{TEST_LOGS} variable. By default, this variable is
9115 computed at @command{make} run time from the value of @code{TESTS} as
9116 described above. For example, you can use the following:
9119 set x subset*.log; shift
9120 env TEST_LOGS="foo.log $*" make -e check
9123 The comments made above about @code{TEST_SUITE_LOG} overriding applies
9127 @vindex RECHECK_LOGS
9128 @cindex lazy test execution
9129 By default, the test harness removes all old per-test @file{.log} and
9130 @file{.trs} files before it starts running tests to regenerate them. The
9131 variable @code{RECHECK_LOGS} contains the set of @file{.log} (and, by
9132 implication, @file{.trs}) files which are removed. @code{RECHECK_LOGS}
9133 defaults to @code{TEST_LOGS}, which means all tests need to be rechecked.
9134 By overriding this variable, you can choose which tests need to be
9135 reconsidered. For example, you can lazily rerun only those tests which
9136 are outdated, i.e., older than their prerequisite test files, by setting
9137 this variable to the empty value:
9140 env RECHECK_LOGS= make -e check
9145 You can ensure that all tests are rerun which have failed or passed
9146 unexpectedly, by running @code{make recheck} in the test directory.
9147 This convenience target will set @code{RECHECK_LOGS} appropriately
9148 before invoking the main test harness.
9152 In order to guarantee an ordering between tests even with @code{make
9153 -j@var{N}}, dependencies between the corresponding @file{.log} files
9154 may be specified through usual @command{make} dependencies. For example,
9155 the following snippet lets the test named @file{foo-execute.test} depend
9156 upon completion of the test @file{foo-compile.test}:
9159 TESTS = foo-compile.test foo-execute.test
9160 foo-execute.log: foo-compile.log
9164 Please note that this ordering ignores the @emph{results} of required
9165 tests, thus the test @file{foo-execute.test} is run even if the test
9166 @file{foo-compile.test} failed or was skipped beforehand. Further,
9167 please note that specifying such dependencies currently works only for
9168 tests that end in one of the suffixes listed in @code{TEST_EXTENSIONS}.
9170 Tests without such specified dependencies may be run concurrently with
9171 parallel @command{make -j@var{N}}, so be sure they are prepared for
9172 concurrent execution.
9175 @c Keep in sync with 'parallel-tests-extra-programs.test'.
9176 The combination of lazy test execution and correct dependencies between
9177 tests and their sources may be exploited for efficient unit testing
9178 during development. To further speed up the edit-compile-test cycle, it
9179 may even be useful to specify compiled programs in @code{EXTRA_PROGRAMS}
9180 instead of with @code{check_PROGRAMS}, as the former allows intertwined
9181 compilation and test execution (but note that @code{EXTRA_PROGRAMS} are
9182 not cleaned automatically, @pxref{Uniform}).
9184 The variables @code{TESTS} and @code{XFAIL_TESTS} may contain
9185 conditional parts as well as configure substitutions. In the latter
9186 case, however, certain restrictions apply: substituted test names
9187 must end with a nonempty test suffix like @file{.test}, so that one of
9188 the inference rules generated by @command{automake} can apply. For
9189 literal test names, @command{automake} can generate per-target rules
9190 to avoid this limitation.
9192 Please note that it is currently not possible to use @code{$(srcdir)/}
9193 or @code{$(top_srcdir)/} in the @code{TESTS} variable. This technical
9194 limitation is necessary to avoid generating test logs in the source tree
9195 and has the unfortunate consequence that it is not possible to specify
9196 distributed tests that are themselves generated by means of explicit
9197 rules, in a way that is portable to all @command{make} implementations
9198 (@pxref{Make Target Lookup,,, autoconf, The Autoconf Manual}, the
9199 semantics of FreeBSD and OpenBSD @command{make} conflict with this).
9200 In case of doubt you may want to require to use GNU @command{make},
9201 or work around the issue with inference rules to generate the tests.
9203 @node Custom Test Drivers
9204 @section Custom Test Drivers
9207 * Overview of Custom Test Drivers Support::
9208 * Declaring Custom Test Drivers::
9209 * API for Custom Test Drivers::
9212 @node Overview of Custom Test Drivers Support
9213 @subsection Overview of Custom Test Drivers Support
9215 Starting from Automake version 1.12, the parallel test harness allows
9216 the package authors to use third-party custom test drivers, in case the
9217 default ones are inadequate for their purposes, or do not support their
9218 testing protocol of choice.
9220 A custom test driver is expected to properly run the test programs passed
9221 to it (including the command-line arguments passed to those programs, if
9222 any), to analyze their execution and outcome, to create the @file{.log}
9223 and @file{.trs} files associated to these test runs, and to display the test
9224 results on the console. It is responsibility of the author of the test
9225 driver to ensure that it implements all the above steps meaningfully and
9226 correctly; Automake isn't and can't be of any help here. On the other
9227 hand, the Automake-provided code for testsuite summary generation offers
9228 support for test drivers allowing several test results per test script,
9229 if they take care to register such results properly (@pxref{Log files
9230 generation and test results recording}).
9232 The exact details of how test scripts' results are to be determined and
9233 analyzed is left to the individual drivers. Some drivers might only
9234 consider the test script exit status (this is done for example by the
9235 default test driver used by the parallel test harness, described
9236 in the previous section). Other drivers might implement more complex and
9237 advanced test protocols, which might require them to parse and interpreter
9238 the output emitted by the test script they're running (examples of such
9239 protocols are TAP and SubUnit).
9241 It's very important to note that, even when using custom test drivers,
9242 most of the infrastructure described in the previous section about the
9243 parallel harness remains in place; this includes:
9247 list of test scripts defined in @code{TESTS}, and overridable at
9248 runtime through the redefinition of @code{TESTS} or @code{TEST_LOGS};
9250 concurrency through the use of @command{make}'s option @option{-j};
9252 per-test @file{.log} and @file{.trs} files, and generation of a summary
9253 @file{.log} file from them;
9255 @code{recheck} target, @code{RECHECK_LOGS} variable, and lazy reruns
9258 inter-test dependencies;
9260 support for @code{check_*} variables (@code{check_PROGRAMS},
9261 @code{check_LIBRARIES}, ...);
9263 use of @code{VERBOSE} environment variable to get verbose output on
9266 definition and honoring of @code{TESTS_ENVIRONMENT},
9267 @code{AM_TESTS_ENVIRONMENT} and @code{AM_TESTS_FD_REDIRECT}
9270 definition of generic and extension-specific @code{LOG_COMPILER} and
9271 @code{LOG_FLAGS} variables.
9275 On the other hand, the exact semantics of how (and if)
9276 @option{color-tests}, @code{XFAIL_TESTS}, and hard errors are supported
9277 and handled is left to the individual test drivers.
9279 @c TODO: We should really add a working example in the doc/ directory,
9280 @c TODO: and reference if from here.
9282 @node Declaring Custom Test Drivers
9283 @subsection Declaring Custom Test Drivers
9286 @vindex _LOG_DRIVER_FLAGS
9288 @vindex LOG_DRIVER_FLAGS
9289 @vindex @var{ext}_LOG_DRIVER
9290 @vindex @var{ext}_LOG_DRIVER_FLAGS
9291 @vindex AM_@var{ext}_LOG_DRIVER_FLAGS
9292 @vindex AM_LOG_DRIVER_FLAGS
9293 Custom testsuite drivers are declared by defining the make variables
9294 @code{LOG_DRIVER} or @code{@var{ext}_LOG_DRIVER} (where @var{ext} must
9295 be declared in @code{TEST_EXTENSIONS}). They must be defined to
9296 programs or scripts that will be used to drive the execution, logging,
9297 and outcome report of the tests with corresponding extensions (or of
9298 those with no registered extension in the case of @code{LOG_DRIVER}).
9299 Clearly, multiple distinct test drivers can be declared in the same
9300 @file{Makefile.am}. Note moreover that the @code{LOG_DRIVER} variables
9301 are @emph{not} a substitute for the @code{LOG_COMPILER} variables: the
9302 two sets of variables can, and often do, usefully and legitimately
9305 @c TODO: We should really be able to point to a clarifying example here!
9307 The developer-reserved variable @code{AM_LOG_DRIVER_FLAGS} and the
9308 user-reserved variable @code{LOG_DRIVER_FLAGS} can be used to define
9309 flags that will be passed to each invocation of @code{LOG_DRIVER},
9310 with the user-defined flags obviously taking precedence over the
9311 developer-reserved ones. Similarly, for each extension @var{ext}
9312 declared in @code{TEST_EXTENSIONS}, flags listed in
9313 @code{AM_@var{ext}_LOG_DRIVER_FLAGS} and
9314 @code{@var{ext}_LOG_DRIVER_FLAGS} will be passed to
9315 invocations of @code{@var{ext}_LOG_DRIVER}.
9317 @node API for Custom Test Drivers
9318 @subsection API for Custom Test Drivers
9320 Note that @emph{the APIs described here are still highly experimental},
9321 and will very likely undergo tightenings and likely also extensive changes
9322 in the future, to accommodate for new features or to satisfy additional
9323 portability requirements.
9325 The main characteristic of these APIs is that they are designed to share
9326 as much infrastructure, semantics, and implementation details as possible
9327 with the parallel test harness and its default driver.
9330 * Command-line arguments for test drivers::
9331 * Log files generation and test results recording::
9332 * Testsuite progress output::
9335 @node Command-line arguments for test drivers
9336 @subsubsection Command-line arguments for test drivers
9338 A custom driver can rely on various command-line options and arguments
9339 being passed to it automatically by the Automake's @option{parallel-tests}
9340 harness. It is @emph{mandatory} that it understands all of them (even
9341 if the exact interpretation of the associated semantics can legitimately
9342 change between a test driver and another, and even be a no-op in some
9346 Here is the list of options:
9349 @item --test-name=@var{NAME}
9350 The name of the test, with VPATH prefix (if any) removed. This can have a
9351 suffix and a directory component (as in e.g., @file{sub/foo.test}), and is
9352 mostly meant to be used in console reports about testsuite advancements and
9353 results (@pxref{Testsuite progress output}).
9354 @item --log-file=@file{@var{PATH}.log}
9355 The @file{.log} file the test driver must create (@pxref{Basics of
9356 test metadata}). If it has a directory component (as in e.g.,
9357 @file{sub/foo.log}), the test harness will ensure that such directory
9358 exists @emph{before} the test driver is called.
9359 @item --trs-file=@file{@var{PATH}.trs}
9360 The @file{.trs} file the test driver must create (@pxref{Basics of
9361 test metadata}). If it has a directory component (as in e.g.,
9362 @file{sub/foo.trs}), the test harness will ensure that such directory
9363 exists @emph{before} the test driver is called.
9364 @item --color-tests=@{yes|no@}
9365 Whether the console output should be colorized or not (@pxref{Simple
9366 tests and color-tests}, to learn when this option gets activated and
9368 @item --expect-failure=@{yes|no@}
9369 Whether the tested program is expected to fail.
9370 @item --enable-hard-errors=@{yes|no@}
9371 Whether ``hard errors'' in the tested program should be treated differently
9372 from normal failures or not (the default should be @code{yes}). The exact
9373 meaning of ``hard error'' is highly dependent from the test protocols or
9376 Explicitly terminate the list of options.
9380 The first non-option argument passed to the test driver is the program to
9381 be run, and all the following ones are command-line options and arguments
9384 Note that the exact semantics attached to the @option{--color-tests},
9385 @option{--expect-failure} and @option{--enable-hard-errors} options are
9386 left up to the individual test drivers. Still, having a behaviour
9387 compatible or at least similar to that provided by the default
9388 @option{parallel-tests} driver is advised, as that would offer a better
9389 consistency and a more pleasant user experience.
9391 @node Log files generation and test results recording
9392 @subsubsection Log files generation and test results recording
9394 The test driver must correctly generate the files specified by the
9395 @option{--log-file} and @option{--trs-file} option (even when the tested
9396 program fails or crashes).
9398 The @file{.log} file should ideally contain all the output produced by the
9399 tested program, plus optionally other information that might facilitate
9400 debugging or analysis of bug reports. Apart from that, its format is
9403 The @file{.trs} file is used to register some metadata through the use
9404 of custom reStructuredText fields. This metadata is expected to be
9405 employed in various ways by the parallel test harness; for example, to
9406 count the test results when printing the testsuite summary, or to decide
9407 which tests to re-run upon @command{make reheck}. Unrecognized metadata
9408 in a @file{.trs} file is currently ignored by the harness, but this might
9409 change in the future. The list of currently recognized metadata follows.
9414 @cindex Register test result
9415 @cindex Register test case result
9416 @cindex Test result, registering
9417 @cindex Test case result, registering
9418 @cindex @code{:test-result:}
9419 @cindex reStructuredText field, @code{:test-result:}
9420 The test driver must use this field to register the results of @emph{each}
9421 test case run by a test script file. Several @code{:test-result:} fields
9422 can be present in the same @file{.trs} file; this is done in order to
9423 support test protocols that allow a single test script to run more test
9426 @c Keep this in sync with lib/am/check-am:$(TEST_SUITE_LOG).
9427 The only recognized test results are currently @code{PASS}, @code{XFAIL},
9428 @code{SKIP}, @code{FAIL}, @code{XPASS} and @code{ERROR}. These results,
9429 when declared with @code{:test-result:}, can be optionally followed by
9430 text holding the name and/or a brief description of the corresponding
9431 test; the @option{parallel-tests} harness will ignore such extra text when
9432 generating @file{test-suite.log} and preparing the testsuite summary.
9434 @c Keep in sync with 'test-metadata-recheck.test'.
9435 @item @code{:recheck:}
9437 @cindex reStructuredText field, @code{:recheck:}
9438 If this field is present and defined to @code{no}, then the corresponding
9439 test script will @emph{not} be run upon a @command{make recheck}. What
9440 happens when two or more @code{:recheck:} fields are present in the same
9441 @file{.trs} file is undefined behaviour.
9443 @c Keep in sync with 'test-metadata-global-log.test'.
9444 @item @code{:copy-in-global-log:}
9445 @cindex :copy-in-global-log:
9446 @cindex reStructuredText field, @code{:copy-in-global-log:}
9447 If this field is present and defined to @code{no}, then the content
9448 of the @file{.log} file will @emph{not} be copied into the global
9449 @file{test-suite.log}. We allow to forsake such copying because, while
9450 it can be useful in debugging and analysis of bug report, it can also be
9451 just a waste of space in normal situations, e.g., when a test script is
9452 successful. What happens when two or more @code{:copy-in-global-log:}
9453 fields are present in the same @file{.trs} file is undefined behaviour.
9455 @c Keep in sync with 'test-metadata-global-result.test'.
9456 @item @code{:test-global-result:}
9457 @cindex :test-global-result:
9458 @cindex reStructuredText field, @code{:test-global-result:}
9459 This is used to declare the "global result" of the script. Currently,
9460 the value of this field is needed only to be reported (more or less
9461 verbatim) in the generated global log file @code{$(TEST_SUITE_LOG)},
9462 so it's quite free-form. For example, a test script which run 10 test
9463 cases, 6 of which pass and 4 of which are skipped, could reasonably have
9464 a @code{PASS/SKIP} value for this field, while a test script which run
9465 19 successful tests and one failed test could have an @code{ALMOST
9466 PASSED} value. What happens when two or more @code{:test-global-result:}
9467 fields are present in the same @file{.trs} file is undefined behaviour.
9471 Let's see a small example. Assume a @file{.trs} file contains the
9475 :test-result: PASS server starts
9476 :global-log-copy: no
9477 :test-result: PASS HTTP/1.1 request
9478 :test-result: FAIL HTTP/1.0 request
9480 :test-result: SKIP HTTPS request (TLS library wasn't available)
9481 :test-result: PASS server stops
9485 Then the corresponding test script will be re-run by @command{make check},
9486 will contribute with @emph{five} test results to the testsuite summary
9487 (three of these tests being successful, one failed, and one skipped), and
9488 the content of the corresponding @file{.log} file will @emph{not} be
9489 copied in the global log file @file{test-suite.log}.
9491 @node Testsuite progress output
9492 @subsubsection Testsuite progress output
9494 A custom test driver also has the task of displaying, on the standard
9495 output, the test results as soon as they become available. Depending on
9496 the protocol in use, it can also display the reasons for failures and
9497 skips, and, more generally, any useful diagnostic output (but remember
9498 that each line on the screen is precious, so that cluttering the screen
9499 with overly verbose information is bad idea). The exact format of this
9500 progress output is left up to the test driver; in fact, a custom test
9501 driver might @emph{theoretically} even decide not to do any such report,
9502 leaving it all to the testsuite summary (that would be a very lousy idea,
9503 of course, and serves only to illustrate the flexibility that is
9506 Remember that consistency is good; so, if possible, try to be consistent
9507 with the output of the built-in Automake test drivers, providing a similar
9508 ``look & feel''. In particular, the testsuite progress output should be
9509 colorized when the @option{--color-tests} is passed to the driver. On the
9510 other end, if you are using a known and widespread test protocol with
9511 well-established implementations, being consistent with those
9512 implementations' output might be a good idea too.
9514 @c TODO: Give an example, maybe inspired to py.test-style output.
9515 @c TODO: That is a good idea because it shows a test driver that allows
9516 @c TODO: for different levels of verbosity in the progress output (could
9517 @c TODO: be implemented either using a driver cmdline flag, or an
9518 @c TODO: environment variable, or both).
9520 @node Using the TAP test protocol
9521 @section Using the TAP test protocol
9524 * Introduction to TAP::
9525 * Use TAP with the Automake test harness::
9526 * Incompatibilities with other TAP parsers and drivers::
9527 * Links and external resources on TAP::
9530 @node Introduction to TAP
9531 @subsection Introduction to TAP
9533 TAP, the Test Anything Protocol, is a simple text-based interface between
9534 testing modules or programs and a test harness. The tests (also called
9535 ``TAP producers'' in this context) write test results in a simple format
9536 on standard output; a test harness (also called ``TAP consumer'') will
9537 parse and interpret these results, and properly present them to the user,
9538 and/or register them for later analysis. The exact details of how this
9539 is accomplished can vary among different test harnesses. The Automake
9540 parallel harness will present the results on the console in the usual
9541 fashion (@pxref{Testsuite progress on console}), and will use the
9542 @file{.trs} files (@pxref{Basics of test metadata}) to store the test
9543 results and related metadata. Apart from that, it will try to remain
9544 as much compatible as possible with pre-existing and widespread utilities,
9545 such as the @uref{http://search.cpan.org/~andya/Test-Harness/bin/prove,
9546 @command{prove} utility}, at least for the simpler usages.
9548 TAP started its life as part of the test harness for Perl, but today
9549 it has been (mostly) standardized, and has various independent
9550 implementations in different languages; among them, C, C++, Perl,
9551 Python, PHP, and Java. For a semi-official specification of the
9552 TAP protocol, please refer to the documentation of
9553 @uref{http://search.cpan.org/~petdance/Test-Harness/lib/Test/Harness/TAP.pod,
9554 @samp{Test::Harness::TAP}}.
9556 The most relevant real-world usages of TAP are obviously in the testsuites
9557 of @command{perl} and of many perl modules. Still, also other important
9558 third-party packages, such as @uref{http://git-scm.com/, @command{git}},
9559 use TAP in their testsuite.
9561 @node Use TAP with the Automake test harness
9562 @subsection Use TAP with the Automake test harness
9564 Currently, the TAP driver that comes with Automake requires a perl
9565 interpreter to work, and requires various by-hand steps on the
9566 developer's part (this should be fixed in future Automake versions).
9567 You'll have grab the @file{tap-driver.pl} script from the Automake
9568 distribution by hand, copy it in your source tree, add code to
9569 @file{configure.ac} to search a perl interpreter and to define the
9570 @code{$(PERL)} variable accordingly, and use the Automake support
9571 for third-party test drivers to instruct the harness to use the
9572 @file{tap-driver.pl} to run your TAP-producing tests. See the example
9573 below for clarification.
9575 Apart from the options common to all the Automake test drivers
9576 (@pxref{Command-line arguments for test drivers}), the @file{tap-driver.pl}
9577 supports the following options, whose names are chosen for enhanced
9578 compatibility with the @command{prove} utility.
9581 @c Keep in sync with 'tap-exit.test' and 'tap-signal.test'.
9583 Causes the test driver to ignore the exit status of the test scripts;
9584 by default, the driver will report an error if the script exit with a
9585 non-zero status. This option has effect also
9587 Instruct the test driver to display TAP diagnostic (i.e., lines beginning
9588 with the @samp{#} character) in the testsuite progress output too; by
9589 default, TAP diagnostic is only copied in the @file{.log} file.
9591 Revert the effects of @option{--comments}.
9593 Instruct the test driver to merge the test scripts' standard error into
9594 their standard output. This is necessary if you want to ensure that
9595 diagnostics from the test scripts are displayed in the correct order
9596 relative to test results; this can be of great help in debugging
9597 (especially if your test scripts are shell scripts run with shell
9598 tracing active). As a downside, this option might cause the test
9599 harness to get confused if anything that appears on standard error
9600 looks like a test result.
9602 Revert the effects of @option{--merge}.
9603 @item --diagnostic-string=@var{STRING}
9604 Change the string that introduces TAP diagnostic from the default value
9605 of ``@code{#}'' to @code{@var{STRING}}. This can be useful if your
9606 TAP-based test scripts produce verbose output on which they have limited
9607 control (because, say, the output comes by other tools invoked in the
9608 scripts), and it might contain text that gets spuriously interpreted as
9609 TAP diagnostic: such an issue can be solved by redefining the string that
9610 activates TAP diagnostic to a value you know won't appear by chance in
9611 the tests' output. Note however that this feature is non-standard, as
9612 the ``official'' TAP protocol does not allow for such a customization; so
9613 don't use it if you can avoid it.
9617 Here is an example of how the TAP driver can be set up and used.
9619 @c Keep in sync with tap-doc2.test.
9621 % @kbd{cat configure.ac}
9622 AC_INIT([GNU Try Tap], [1.0], [bug-automake@@gnu.org])
9623 AC_CONFIG_AUX_DIR([build-aux])
9624 AM_INIT_AUTOMAKE([foreign parallel-tests -Wall -Werror])
9625 AC_CONFIG_FILES([Makefile])
9626 AC_REQUIRE_AUX_FILE([tap-driver.pl])
9627 AC_PATH_PROG([PERL], [perl])
9628 test -n "$PERL" || AC_MSG_ERROR([perl not found])
9629 $PERL -MTAP::Parser -e 1 || AC_MSG_ERROR([TAP::Parser not found])
9632 % @kbd{cat Makefile.am}
9633 TEST_LOG_DRIVER = $(PERL) $(srcdir)/build-aux/tap-driver.pl
9634 TESTS = foo.test bar.test baz.test
9635 EXTRA_DIST = $(TESTS)
9637 % @kbd{cat foo.test}
9639 echo 1..4 # Number of tests to be executed.
9640 echo 'ok 1 - Swallows fly'
9641 echo 'not ok 2 - Caterpillars fly # TODO metamorphosis in progress'
9642 echo 'ok 3 - Pigs fly # SKIP not enough acid'
9643 echo '# I just love word plays ...'
9644 echo 'ok 4 - Flies fly too :-)'
9646 % @kbd{cat bar.test}
9649 echo 'not ok 1 - Bummer, this test has failed.'
9650 echo 'ok 2 - This passed though.'
9651 echo 'Bail out! Ennui kicking in, sorry...'
9652 echo 'ok 3 - This will not be seen.'
9654 % @kbd{cat baz.test}
9658 # Exit with error, even if all the test case has been successful.
9661 % @kbd{cp @var{PREFIX}/share/automake-@var{APIVERSION}/tap-driver.pl .}
9662 % @kbd{autoreconf -vi && ./configure && make check}
9664 PASS: foo.test 1 - Swallows fly
9665 XFAIL: foo.test 2 - Caterpillars fly # TODO metamorphosis in progress
9666 SKIP: foo.test 3 - Pigs fly # SKIP not enough acid
9667 PASS: foo.test 4 - Flies fly too :-)
9668 FAIL: bar.test 1 - Bummer, this test has failed.
9669 PASS: bar.test 2 - This passed though.
9670 ERROR: bar.test - Bail out! Ennui kicking in, sorry...
9672 ERROR: baz.test - exited with status 7
9674 Please report to bug-automake@@gnu.org
9676 % @kbd{echo exit status: $?}
9679 @c Keep the "skewed" indentation below, it produces pretty PDF output.
9680 % @kbd{env TEST_LOG_DRIVER_FLAGS='--comments --ignore-exit' \
9681 TESTS='foo.test baz.test' make -e check}
9683 PASS: foo.test 1 - Swallows fly
9684 XFAIL: foo.test 2 - Caterpillars fly # TODO metamorphosis in progress
9685 SKIP: foo.test 3 - Pigs fly # SKIP not enough acid
9686 # foo.test: I just love word plays...
9687 PASS: foo.test 4 - Flies fly too :-)
9690 % @kbd{echo exit status: $?}
9694 @node Incompatibilities with other TAP parsers and drivers
9695 @subsection Incompatibilities with other TAP parsers and drivers
9697 For implementation or historical reasons, the TAP driver and harness as
9698 implemented by Automake have some minors incompatibilities with the
9699 mainstream versions, which you should be aware of.
9703 A @code{Bail out!} directive doesn't stop the whole testsuite, but only
9704 the test script it occurs into. This doesn't follows TAP specifications,
9705 but on the other hand it maximizes compatibility (and code sharing) with
9706 the ``hard error'' concept of the default @option{parallel-tests} driver.
9708 The @code{version} and @code{pragma} directives are not supported.
9710 The @option{--diagnostic-string} option of out driver allows to modify
9711 the string that introduces TAP diagnostic from the default value
9712 of ``@code{#}''. The standard TAP protocol has currently no way to
9713 allow this, so if you use it your diagnostic will be lost to more
9714 compliant tools like @command{prove} and @code{Test::Harness}
9716 And there are probably some other small and yet undiscovered
9717 incompatibilities, especially in corner cases or with rare usages.
9720 @node Links and external resources on TAP
9721 @subsection Links and external resources on TAP
9724 Here are some links to more extensive official or third-party
9725 documentation and resources about the TAP protocol and related
9726 tools and libraries.
9729 @uref{http://search.cpan.org/~petdance/Test-Harness/lib/Test/Harness/TAP.pod,
9730 @samp{Test::Harness::TAP}},
9731 the (mostly) official documentation about the TAP format and protocol.
9733 @uref{http://search.cpan.org/~andya/Test-Harness/bin/prove,
9735 the most famous command-line TAP test driver, included in the distribution
9736 of @command{perl} and
9737 @uref{http://search.cpan.org/~andya/Test-Harness/lib/Test/Harness.pm,
9738 @samp{Test::Harness}}.
9740 The @uref{http://testanything.org/wiki/index.php/Main_Page,TAP wiki}.
9742 A ``gentle introduction'' to testing for perl coders:
9743 @uref{http://search.cpan.org/dist/Test-Simple/lib/Test/Tutorial.pod,
9744 @samp{Test::Tutorial}}.
9746 @uref{http://search.cpan.org/~mschwern/Test-Simple/lib/Test/Simple.pm,
9747 @samp{Test::Simple}}
9749 @uref{http://search.cpan.org/~mschwern/Test-Simple/lib/Test/More.pm,
9751 the standard perl testing libraries, which are based on TAP.
9753 @uref{http://www.eyrie.org/~eagle/software/c-tap-harness/,C TAP Harness},
9754 a C-based project implementing both a TAP producer and a TAP consumer.
9756 @uref{http://www.tap4j.org/,tap4j},
9757 a Java-based project implementing both a TAP producer and a TAP consumer.
9761 @section DejaGnu Tests
9763 If @uref{ftp://ftp.gnu.org/gnu/dejagnu/, @command{dejagnu}} appears in
9764 @code{AUTOMAKE_OPTIONS}, then a @command{dejagnu}-based test suite is
9765 assumed. The variable @code{DEJATOOL} is a list of names that are
9766 passed, one at a time, as the @option{--tool} argument to
9767 @command{runtest} invocations; it defaults to the name of the package.
9769 The variable @code{RUNTESTDEFAULTFLAGS} holds the @option{--tool} and
9770 @option{--srcdir} flags that are passed to dejagnu by default; this can be
9771 overridden if necessary.
9772 @vindex RUNTESTDEFAULTFLAGS
9774 The variables @code{EXPECT} and @code{RUNTEST} can
9775 also be overridden to provide project-specific values. For instance,
9776 you will need to do this if you are testing a compiler toolchain,
9777 because the default values do not take into account host and target
9784 The contents of the variable @code{RUNTESTFLAGS} are passed to the
9785 @code{runtest} invocation. This is considered a ``user variable''
9786 (@pxref{User Variables}). If you need to set @command{runtest} flags in
9787 @file{Makefile.am}, you can use @code{AM_RUNTESTFLAGS} instead.
9788 @vindex RUNTESTFLAGS
9789 @vindex AM_RUNTESTFLAGS
9791 @cindex @file{site.exp}
9792 Automake will generate rules to create a local @file{site.exp} file,
9793 defining various variables detected by @command{configure}. This file
9794 is automatically read by DejaGnu. It is OK for the user of a package
9795 to edit this file in order to tune the test suite. However this is
9796 not the place where the test suite author should define new variables:
9797 this should be done elsewhere in the real test suite code.
9798 Especially, @file{site.exp} should not be distributed.
9800 Still, if the package author has legitimate reasons to extend
9801 @file{site.exp} at @command{make} time, he can do so by defining
9802 the variable @code{EXTRA_DEJAGNU_SITE_CONFIG}; the files listed
9803 there will be considered @file{site.exp} prerequisites, and their
9804 content will be appended to it (in the same order in which they
9805 appear in @code{EXTRA_DEJAGNU_SITE_CONFIG}). Note that files are
9806 @emph{not} distributed by default.
9808 For more information regarding DejaGnu test suites, see @ref{Top, , ,
9809 dejagnu, The DejaGnu Manual}.
9812 @section Install Tests
9814 The @code{installcheck} target is available to the user as a way to
9815 run any tests after the package has been installed. You can add tests
9816 to this by writing an @code{installcheck-local} rule.
9820 @chapter Rebuilding Makefiles
9821 @cindex rebuild rules
9823 Automake generates rules to automatically rebuild @file{Makefile}s,
9824 @file{configure}, and other derived files like @file{Makefile.in}.
9826 @acindex AM_MAINTAINER_MODE
9827 If you are using @code{AM_MAINTAINER_MODE} in @file{configure.ac}, then
9828 these automatic rebuilding rules are only enabled in maintainer mode.
9830 @vindex ACLOCAL_AMFLAGS
9831 Sometimes you need to run @command{aclocal} with an argument like
9832 @option{-I} to tell it where to find @file{.m4} files. Since
9833 sometimes @command{make} will automatically run @command{aclocal}, you
9834 need a way to specify these arguments. You can do this by defining
9835 @code{ACLOCAL_AMFLAGS}; this holds arguments that are passed verbatim
9836 to @command{aclocal}. This variable is only useful in the top-level
9839 @vindex CONFIG_STATUS_DEPENDENCIES
9840 @vindex CONFIGURE_DEPENDENCIES
9841 @cindex @file{version.sh}, example
9842 @cindex @file{version.m4}, example
9844 Sometimes it is convenient to supplement the rebuild rules for
9845 @file{configure} or @file{config.status} with additional dependencies.
9846 The variables @code{CONFIGURE_DEPENDENCIES} and
9847 @code{CONFIG_STATUS_DEPENDENCIES} can be used to list these extra
9848 dependencies. These variables should be defined in all
9849 @file{Makefile}s of the tree (because these two rebuild rules are
9850 output in all them), so it is safer and easier to @code{AC_SUBST} them
9851 from @file{configure.ac}. For instance, the following statement will
9852 cause @file{configure} to be rerun each time @file{version.sh} is
9856 AC_SUBST([CONFIG_STATUS_DEPENDENCIES], ['$(top_srcdir)/version.sh'])
9860 Note the @samp{$(top_srcdir)/} in the file name. Since this variable
9861 is to be used in all @file{Makefile}s, its value must be sensible at
9862 any level in the build hierarchy.
9864 Beware not to mistake @code{CONFIGURE_DEPENDENCIES} for
9865 @code{CONFIG_STATUS_DEPENDENCIES}.
9867 @code{CONFIGURE_DEPENDENCIES} adds dependencies to the
9868 @file{configure} rule, whose effect is to run @command{autoconf}. This
9869 variable should be seldom used, because @command{automake} already tracks
9870 @code{m4_include}d files. However it can be useful when playing
9871 tricky games with @code{m4_esyscmd} or similar non-recommendable
9872 macros with side effects.
9874 @code{CONFIG_STATUS_DEPENDENCIES} adds dependencies to the
9875 @file{config.status} rule, whose effect is to run @file{configure}.
9876 This variable should therefore carry any non-standard source that may
9877 be read as a side effect of running @command{configure}, like @file{version.sh}
9878 in the example above.
9880 Speaking of @file{version.sh} scripts, we recommend against them
9881 today. They are mainly used when the version of a package is updated
9882 automatically by a script (e.g., in daily builds). Here is what some
9883 old-style @file{configure.ac}s may look like:
9887 . $srcdir/version.sh
9888 AM_INIT_AUTOMAKE([name], $VERSION_NUMBER)
9893 Here, @file{version.sh} is a shell fragment that sets
9894 @code{VERSION_NUMBER}. The problem with this example is that
9895 @command{automake} cannot track dependencies (listing @file{version.sh}
9896 in @command{CONFIG_STATUS_DEPENDENCIES}, and distributing this file is up
9897 to the user), and that it uses the obsolete form of @code{AC_INIT} and
9898 @code{AM_INIT_AUTOMAKE}. Upgrading to the new syntax is not
9899 straightforward, because shell variables are not allowed in
9900 @code{AC_INIT}'s arguments. We recommend that @file{version.sh} be
9901 replaced by an M4 file that is included by @file{configure.ac}:
9904 m4_include([version.m4])
9905 AC_INIT([name], VERSION_NUMBER)
9911 Here @file{version.m4} could contain something like
9912 @samp{m4_define([VERSION_NUMBER], [1.2])}. The advantage of this
9913 second form is that @command{automake} will take care of the
9914 dependencies when defining the rebuild rule, and will also distribute
9915 the file automatically. An inconvenience is that @command{autoconf}
9916 will now be rerun each time the version number is bumped, when only
9917 @file{configure} had to be rerun in the previous setup.
9921 @chapter Changing Automake's Behavior
9924 * Options generalities:: Semantics of Automake option
9925 * List of Automake options:: A comprehensive list of Automake options
9928 @node Options generalities
9929 @section Options generalities
9931 Various features of Automake can be controlled by options. Except where
9932 noted otherwise, options can be specified in one of several ways. Most
9933 options can be applied on a per-@file{Makefile} basis when listed in a
9934 special @file{Makefile} variable named @code{AUTOMAKE_OPTIONS}. Some
9935 of these options only make sense when specified in the toplevel
9936 @file{Makefile.am} file. Options are applied globally to all processed
9937 @file{Makefile} files when listed in the first argument of
9938 @code{AM_INIT_AUTOMAKE} in @file{configure.ac}, and some options which
9939 require changes to the @command{configure} script can only be specified
9940 there. These are annotated below.
9942 As a general rule, options specified in @code{AUTOMAKE_OPTIONS} take
9943 precedence over those specified in @code{AM_INIT_AUTOMAKE}, which in
9944 turn take precedence over those specified on the command line.
9946 Also, some care must be taken about the interactions among strictness
9947 level and warning categories. As a general rule, strictness-implied
9948 warnings are overridden by those specified by explicit options. For
9949 example, even if @samp{portability} warnings are disabled by default
9950 in @option{foreign} strictness, an usage like this will end up enabling
9954 AUTOMAKE_OPTIONS = -Wportability foreign
9957 However, a strictness level specified in a higher-priority context
9958 will override all the explicit warnings specified in a lower-priority
9959 context. For example, if @file{configure.ac} contains:
9962 AM_INIT_AUTOMAKE([-Wportability])
9966 and @file{Makefile.am} contains:
9969 AUTOMAKE_OPTIONS = foreign
9973 then @samp{portability} warnings will be @emph{disabled} in
9976 @node List of Automake options
9977 @section List of Automake options
9979 @vindex AUTOMAKE_OPTIONS
9982 @item @option{gnits}
9984 @itemx @option{foreign}
9985 @itemx @option{cygnus}
9986 @cindex Option, @option{gnits}
9987 @cindex Option, @option{gnu}
9988 @cindex Option, @option{foreign}
9989 @cindex Option, @option{cygnus}
9995 Set the strictness as appropriate. The @option{gnits} option also
9996 implies options @option{readme-alpha} and @option{check-news}.
9998 @item @option{check-news}
9999 @cindex Option, @option{check-news}
10000 @opindex check-news
10001 Cause @samp{make dist} to fail unless the current version number appears
10002 in the first few lines of the @file{NEWS} file.
10004 @item @option{color-tests}
10005 @cindex Option, @option{color-tests}
10006 @opindex color-tests
10007 Cause output of the serial and parallel test harnesses (see @ref{Simple
10008 Tests}) and of properly-written custom test drivers (@pxref{Custom Test
10009 Drivers}) to be colorized on capable terminals.
10011 @item @option{dejagnu}
10012 @cindex Option, @option{dejagnu}
10014 Cause @command{dejagnu}-specific rules to be generated. @xref{DejaGnu Tests}.
10016 @item @option{dist-bzip2}
10017 @cindex Option, @option{dist-bzip2}
10018 @opindex dist-bzip2
10019 Hook @code{dist-bzip2} to @code{dist}.
10020 @trindex dist-bzip2
10022 @item @option{dist-lzip}
10023 @cindex Option, @option{dist-lzip}
10025 Hook @code{dist-lzip} to @code{dist}.
10028 @item @option{dist-lzma}
10029 @cindex Option, @option{dist-lzma}
10031 Hook @code{dist-lzma} to @code{dist}. Obsoleted by @code{dist-xz}.
10034 @item @option{dist-shar}
10035 @cindex Option, @option{dist-shar}
10037 Hook @code{dist-shar} to @code{dist}.
10040 @item @option{dist-zip}
10041 @cindex Option, @option{dist-zip}
10043 Hook @code{dist-zip} to @code{dist}.
10046 @item @option{dist-tarZ}
10047 @cindex Option, @option{dist-tarZ}
10049 Hook @code{dist-tarZ} to @code{dist}.
10052 @item @option{filename-length-max=99}
10053 @cindex Option, @option{filename-length-max=99}
10054 @opindex filename-length-max=99
10055 Abort if file names longer than 99 characters are found during
10056 @samp{make dist}. Such long file names are generally considered not to
10057 be portable in tarballs. See the @option{tar-v7} and @option{tar-ustar}
10058 options below. This option should be used in the top-level
10059 @file{Makefile.am} or as an argument of @code{AM_INIT_AUTOMAKE} in
10060 @file{configure.ac}, it will be ignored otherwise. It will also be
10061 ignored in sub-packages of nested packages (@pxref{Subpackages}).
10063 @item @option{no-define}
10064 @cindex Option, @option{no-define}
10066 This option is meaningful only when passed as an argument to
10067 @code{AM_INIT_AUTOMAKE}. It will prevent the @code{PACKAGE} and
10068 @code{VERSION} variables from being @code{AC_DEFINE}d.
10070 @item @option{no-dependencies}
10071 @cindex Option, @option{no-dependencies}
10072 @opindex no-dependencies
10073 This is similar to using @option{--ignore-deps} on the command line,
10074 but is useful for those situations where you don't have the necessary
10075 bits to make automatic dependency tracking work
10076 (@pxref{Dependencies}). In this case the effect is to effectively
10077 disable automatic dependency tracking.
10079 @item @option{no-dist}
10080 @cindex Option, @option{no-dist}
10082 Don't emit any code related to @code{dist} target. This is useful
10083 when a package has its own method for making distributions.
10085 @item @option{no-dist-gzip}
10086 @cindex Option, @option{no-dist-gzip}
10087 @opindex no-dist-gzip
10088 Do not hook @code{dist-gzip} to @code{dist}.
10089 @trindex no-dist-gzip
10091 @item @option{no-exeext}
10092 @cindex Option, @option{no-exeext}
10094 If your @file{Makefile.am} defines a rule for target @code{foo}, it
10095 will override a rule for a target named @samp{foo$(EXEEXT)}. This is
10096 necessary when @code{EXEEXT} is found to be empty. However, by
10097 default @command{automake} will generate an error for this use. The
10098 @option{no-exeext} option will disable this error. This is intended for
10099 use only where it is known in advance that the package will not be
10100 ported to Windows, or any other operating system using extensions on
10103 @item @option{no-installinfo}
10104 @cindex Option, @option{no-installinfo}
10105 @opindex no-installinfo
10106 The generated @file{Makefile.in} will not cause info pages to be built
10107 or installed by default. However, @code{info} and @code{install-info}
10108 targets will still be available. This option is disallowed at
10109 @option{gnu} strictness and above.
10111 @trindex install-info
10113 @item @option{no-installman}
10114 @cindex Option, @option{no-installman}
10115 @opindex no-installman
10116 The generated @file{Makefile.in} will not cause man pages to be
10117 installed by default. However, an @code{install-man} target will still
10118 be available for optional installation. This option is disallowed at
10119 @option{gnu} strictness and above.
10120 @trindex install-man
10122 @item @option{nostdinc}
10123 @cindex Option, @option{nostdinc}
10125 This option can be used to disable the standard @option{-I} options that
10126 are ordinarily automatically provided by Automake.
10128 @item @option{no-texinfo.tex}
10129 @cindex Option, @option{no-texinfo.tex}
10130 @opindex no-texinfo.tex
10131 Don't require @file{texinfo.tex}, even if there are texinfo files in
10134 @item @option{parallel-tests}
10135 @cindex Option, @option{parallel-tests}
10136 @opindex parallel-tests
10137 Enable test suite harness for @code{TESTS} that can run tests in parallel
10138 (@pxref{Parallel Test Harness}, for more information).
10140 @item @option{readme-alpha}
10141 @cindex Option, @option{readme-alpha}
10142 @opindex readme-alpha
10143 If this release is an alpha release, and the file @file{README-alpha}
10144 exists, then it will be added to the distribution. If this option is
10145 given, version numbers are expected to follow one of two forms. The
10146 first form is @samp{@var{major}.@var{minor}.@var{alpha}}, where each
10147 element is a number; the final period and number should be left off for
10148 non-alpha releases. The second form is
10149 @samp{@var{major}.@var{minor}@var{alpha}}, where @var{alpha} is a
10150 letter; it should be omitted for non-alpha releases.
10152 @item @option{silent-rules}
10153 @cindex Option, @option{silent-rules}
10154 @opindex silent-rules
10155 Enable less verbose build rules. This can be used to let build rules
10156 output status lines of the form:
10158 GEN @var{output-file}
10159 CC @var{object-file}
10162 instead of printing the command that will be executed to update
10163 @var{output-file} or to compile @var{object-file}. It can also
10164 silence @command{libtool} output.
10166 For more information about how to use, enable, or disable silent
10167 rules, @pxref{Automake silent-rules Option}.
10169 @item @option{std-options}
10170 @cindex Options, @option{std-options}
10171 @cindex @samp{make installcheck}, testing @option{--help} and @option{--version}
10172 @cindex @option{--help} check
10173 @cindex @option{--version} check
10174 @opindex std-options
10176 Make the @code{installcheck} rule check that installed scripts and
10177 programs support the @option{--help} and @option{--version} options.
10178 This also provides a basic check that the program's
10179 run-time dependencies are satisfied after installation.
10181 @vindex AM_INSTALLCHECK_STD_OPTIONS_EXEMPT
10182 In a few situations, programs (or scripts) have to be exempted from this
10183 test. For instance, @command{false} (from GNU coreutils) is never
10184 successful, even for @option{--help} or @option{--version}. You can list
10185 such programs in the variable @code{AM_INSTALLCHECK_STD_OPTIONS_EXEMPT}.
10186 Programs (not scripts) listed in this variable should be suffixed by
10187 @samp{$(EXEEXT)} for the sake of Windows or OS/2. For instance, suppose we
10188 build @file{false} as a program but @file{true.sh} as a script, and that
10189 neither of them support @option{--help} or @option{--version}:
10192 AUTOMAKE_OPTIONS = std-options
10193 bin_PROGRAMS = false ...
10194 bin_SCRIPTS = true.sh ...
10195 AM_INSTALLCHECK_STD_OPTIONS_EXEMPT = false$(EXEEXT) true.sh
10198 @item @option{subdir-objects}
10199 @cindex Options, @option{subdir-objects}
10200 @opindex subdir-objects
10201 If this option is specified, then objects are placed into the
10202 subdirectory of the build directory corresponding to the subdirectory of
10203 the source file. For instance, if the source file is
10204 @file{subdir/file.cxx}, then the output file would be
10205 @file{subdir/file.o}.
10207 In order to use this option with C sources, you should add
10208 @code{AM_PROG_CC_C_O} to @file{configure.ac}.
10210 @anchor{tar-formats}
10211 @item @option{tar-v7}
10212 @itemx @option{tar-ustar}
10213 @itemx @option{tar-pax}
10214 @cindex Option, @option{tar-v7}
10215 @cindex Option, @option{tar-ustar}
10216 @cindex Option, @option{tar-pax}
10217 @cindex @command{tar} formats
10218 @cindex v7 @command{tar} format
10219 @cindex ustar format
10225 These three mutually exclusive options select the tar format to use
10226 when generating tarballs with @samp{make dist}. (The tar file created
10227 is then compressed according to the set of @option{no-dist-gzip},
10228 @option{dist-bzip2}, @option{dist-lzip}, @option{dist-xz} and
10229 @option{dist-tarZ} options in use.)
10231 These options must be passed as arguments to @code{AM_INIT_AUTOMAKE}
10232 (@pxref{Macros}) because they can require additional configure checks.
10233 Automake will complain if it sees such options in an
10234 @code{AUTOMAKE_OPTIONS} variable.
10236 @option{tar-v7} selects the old V7 tar format. This is the historical
10237 default. This antiquated format is understood by all tar
10238 implementations and supports file names with up to 99 characters. When
10239 given longer file names some tar implementations will diagnose the
10240 problem while other will generate broken tarballs or use non-portable
10241 extensions. Furthermore, the V7 format cannot store empty
10242 directories. When using this format, consider using the
10243 @option{filename-length-max=99} option to catch file names too long.
10245 @option{tar-ustar} selects the ustar format defined by POSIX
10246 1003.1-1988. This format is believed to be old enough to be portable.
10247 It fully supports empty directories. It can store file names with up
10248 to 256 characters, provided that the file name can be split at
10249 directory separator in two parts, first of them being at most 155
10250 bytes long. So, in most cases the maximum file name length will be
10251 shorter than 256 characters. However you may run against broken tar
10252 implementations that incorrectly handle file names longer than 99
10253 characters (please report them to @email{@value{PACKAGE_BUGREPORT}} so we
10254 can document this accurately).
10256 @option{tar-pax} selects the new pax interchange format defined by POSIX
10257 1003.1-2001. It does not limit the length of file names. However,
10258 this format is very young and should probably be restricted to
10259 packages that target only very modern platforms. There are moves to
10260 change the pax format in an upward-compatible way, so this option may
10261 refer to a more recent version in the future.
10263 @xref{Formats, , Controlling the Archive Format, tar, GNU Tar}, for
10264 further discussion about tar formats.
10266 @command{configure} knows several ways to construct these formats. It
10267 will not abort if it cannot find a tool up to the task (so that the
10268 package can still be built), but @samp{make dist} will fail.
10270 @item @var{version}
10271 @cindex Option, @var{version}
10272 A version number (e.g., @samp{0.30}) can be specified. If Automake is not
10273 newer than the version specified, creation of the @file{Makefile.in}
10274 will be suppressed.
10276 @item @option{-W@var{category}} or @option{--warnings=@var{category}}
10277 @cindex Option, warnings
10278 @cindex Option, @option{-W@var{category}}
10279 @cindex Option, @option{--warnings=@var{category}}
10280 These options behave exactly like their command-line counterpart
10281 (@pxref{automake Invocation}). This allows you to enable or disable some
10282 warning categories on a per-file basis. You can also setup some warnings
10283 for your entire project; for instance, try @samp{AM_INIT_AUTOMAKE([-Wall])}
10284 in your @file{configure.ac}.
10288 Unrecognized options are diagnosed by @command{automake}.
10290 If you want an option to apply to all the files in the tree, you can use
10291 the @code{AM_INIT_AUTOMAKE} macro in @file{configure.ac}.
10295 @node Miscellaneous
10296 @chapter Miscellaneous Rules
10298 There are a few rules and variables that didn't fit anywhere else.
10301 * Tags:: Interfacing to cscope, etags and mkid
10302 * Suffixes:: Handling new file extensions
10307 @section Interfacing to @command{etags}
10309 @cindex @file{TAGS} support
10311 Automake will generate rules to generate @file{TAGS} files for use with
10312 GNU Emacs under some circumstances.
10315 If any C, C++ or Fortran 77 source code or headers are present, then
10316 @code{tags} and @code{TAGS} rules will be generated for the directory.
10317 All files listed using the @code{_SOURCES}, @code{_HEADERS}, and
10318 @code{_LISP} primaries will be used to generate tags. Note that
10319 generated source files that are not distributed must be declared in
10320 variables like @code{nodist_noinst_HEADERS} or
10321 @code{nodist_@var{prog}_SOURCES} or they will be ignored.
10323 A @code{tags} rule will be output at the topmost directory of a
10324 multi-directory package. When run from this topmost directory,
10325 @samp{make tags} will generate a @file{TAGS} file that includes by
10326 reference all @file{TAGS} files from subdirectories.
10328 The @code{tags} rule will also be generated if the variable
10329 @code{ETAGS_ARGS} is defined. This variable is intended for use in
10330 directories that contain taggable source that @command{etags} does
10331 not understand. The user can use the @code{ETAGSFLAGS} to pass
10332 additional flags to @command{etags}; @code{AM_ETAGSFLAGS} is also
10333 available for use in @file{Makefile.am}.
10336 @vindex AM_ETAGSFLAGS
10338 Here is how Automake generates tags for its source, and for nodes in its
10342 ETAGS_ARGS = automake.in --lang=none \
10343 --regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi
10346 If you add file names to @code{ETAGS_ARGS}, you will probably also
10347 want to define @code{TAGS_DEPENDENCIES}. The contents of this variable
10348 are added directly to the dependencies for the @code{tags} rule.
10349 @vindex TAGS_DEPENDENCIES
10351 Automake also generates a @code{ctags} rule that can be used to
10352 build @command{vi}-style @file{tags} files. The variable @code{CTAGS}
10353 is the name of the program to invoke (by default @command{ctags});
10354 @code{CTAGSFLAGS} can be used by the user to pass additional flags,
10355 and @code{AM_CTAGSFLAGS} can be used by the @file{Makefile.am}.
10358 Automake will also generate an @code{ID} rule that will run
10359 @command{mkid} on the source. This is only supported on a
10360 directory-by-directory basis.
10362 Similarly, the @code{cscope} rule will create a list of all the source
10363 files in the tree and run @command{cscope} to build an inverted index
10364 database. The variable @code{CSCOPE} is the name of the program to invoke
10365 (by default @command{cscope}); @code{CSCOPEFLAGS} and
10366 @code{CSCOPE_ARGS} can be used by the user to pass additional flags and
10367 file names respectively, while @code{AM_CSCOPEFLAGS} can be used by the
10368 @file{Makefile.am}. Note that, currently, the Automake-provided
10369 @code{cscope} support, when used in a VPATH build, might not work well
10370 with non-GNU make implementations (especially with make implementations
10371 performing @ref{Automatic Rule Rewriting, , VPATH rewrites, autoconf,
10372 The Autoconf Manual}).
10374 Finally, Automake also emits rules to support the
10375 @uref{http://www.gnu.org/software/global/, GNU Global Tags program}.
10376 The @code{GTAGS} rule runs Global Tags and puts the
10377 result in the top build directory. The variable @code{GTAGS_ARGS}
10378 holds arguments that are passed to @command{gtags}.
10383 @section Handling new file extensions
10385 @cindex Adding new @code{SUFFIXES}
10386 @cindex @code{SUFFIXES}, adding
10389 It is sometimes useful to introduce a new implicit rule to handle a file
10390 type that Automake does not know about.
10392 For instance, suppose you had a compiler that could compile @file{.foo}
10393 files to @file{.o} files. You would simply define a suffix rule for
10401 Then you could directly use a @file{.foo} file in a @code{_SOURCES}
10402 variable and expect the correct results:
10405 bin_PROGRAMS = doit
10406 doit_SOURCES = doit.foo
10409 This was the simpler and more common case. In other cases, you will
10410 have to help Automake to figure out which extensions you are defining your
10411 suffix rule for. This usually happens when your extension does not
10412 start with a dot. Then, all you have to do is to put a list of new
10413 suffixes in the @code{SUFFIXES} variable @strong{before} you define your
10416 For instance, the following definition prevents Automake from misinterpreting
10417 the @samp{.idlC.cpp:} rule as an attempt to transform @file{.idlC} files into
10420 @c Keep in sync with suffix7.test.
10422 SUFFIXES = .idl C.cpp
10427 As you may have noted, the @code{SUFFIXES} variable behaves like the
10428 @code{.SUFFIXES} special target of @command{make}. You should not touch
10429 @code{.SUFFIXES} yourself, but use @code{SUFFIXES} instead and let
10430 Automake generate the suffix list for @code{.SUFFIXES}. Any given
10431 @code{SUFFIXES} go at the start of the generated suffixes list, followed
10432 by Automake generated suffixes not already in the list.
10438 @cindex Including @file{Makefile} fragment
10439 @cindex @file{Makefile} fragment, including
10441 Automake supports an @code{include} directive that can be used to
10442 include other @file{Makefile} fragments when @command{automake} is run.
10443 Note that these fragments are read and interpreted by @command{automake},
10444 not by @command{make}. As with conditionals, @command{make} has no idea that
10445 @code{include} is in use.
10447 There are two forms of @code{include}:
10450 @item include $(srcdir)/file
10451 Include a fragment that is found relative to the current source
10454 @item include $(top_srcdir)/file
10455 Include a fragment that is found relative to the top source directory.
10458 Note that if a fragment is included inside a conditional, then the
10459 condition applies to the entire contents of that fragment.
10461 Makefile fragments included this way are always distributed because
10462 they are needed to rebuild @file{Makefile.in}.
10465 @chapter Conditionals
10467 @cindex Conditionals
10469 Automake supports a simple type of conditionals.
10471 These conditionals are not the same as conditionals in
10472 GNU Make. Automake conditionals are checked at configure time by the
10473 @file{configure} script, and affect the translation from
10474 @file{Makefile.in} to @file{Makefile}. They are based on options passed
10475 to @file{configure} and on results that @file{configure} has discovered
10476 about the host system. GNU Make conditionals are checked at @command{make}
10477 time, and are based on variables passed to the make program or defined
10478 in the @file{Makefile}.
10480 Automake conditionals will work with any make program.
10483 * Usage of Conditionals:: Declaring conditional content
10484 * Limits of Conditionals:: Enclosing complete statements
10487 @node Usage of Conditionals
10488 @section Usage of Conditionals
10490 @acindex AM_CONDITIONAL
10491 Before using a conditional, you must define it by using
10492 @code{AM_CONDITIONAL} in the @file{configure.ac} file (@pxref{Macros}).
10494 @defmac AM_CONDITIONAL (@var{conditional}, @var{condition})
10495 The conditional name, @var{conditional}, should be a simple string
10496 starting with a letter and containing only letters, digits, and
10497 underscores. It must be different from @samp{TRUE} and @samp{FALSE}
10498 that are reserved by Automake.
10500 The shell @var{condition} (suitable for use in a shell @code{if}
10501 statement) is evaluated when @command{configure} is run. Note that you
10502 must arrange for @emph{every} @code{AM_CONDITIONAL} to be invoked every
10503 time @command{configure} is run. If @code{AM_CONDITIONAL} is run
10504 conditionally (e.g., in a shell @code{if} statement), then the result
10505 will confuse @command{automake}.
10508 @cindex @option{--enable-debug}, example
10509 @cindex Example conditional @option{--enable-debug}
10510 @cindex Conditional example, @option{--enable-debug}
10512 Conditionals typically depend upon options that the user provides to
10513 the @command{configure} script. Here is an example of how to write a
10514 conditional that is true if the user uses the @option{--enable-debug}
10518 AC_ARG_ENABLE([debug],
10519 [ --enable-debug Turn on debugging],
10520 [case "$@{enableval@}" in
10523 *) AC_MSG_ERROR([bad value $@{enableval@} for --enable-debug]) ;;
10524 esac],[debug=false])
10525 AM_CONDITIONAL([DEBUG], [test x$debug = xtrue])
10528 Here is an example of how to use that conditional in @file{Makefile.am}:
10540 noinst_PROGRAMS = $(DBG)
10543 This trivial example could also be handled using @code{EXTRA_PROGRAMS}
10544 (@pxref{Conditional Programs}).
10546 You may only test a single variable in an @code{if} statement, possibly
10547 negated using @samp{!}. The @code{else} statement may be omitted.
10548 Conditionals may be nested to any depth. You may specify an argument to
10549 @code{else} in which case it must be the negation of the condition used
10550 for the current @code{if}. Similarly you may specify the condition
10551 that is closed on the @code{endif} line:
10562 Unbalanced conditions are errors. The @code{if}, @code{else}, and
10563 @code{endif} statements should not be indented, i.e., start on column
10566 The @code{else} branch of the above two examples could be omitted,
10567 since assigning the empty string to an otherwise undefined variable
10568 makes no difference.
10570 @acindex AM_COND_IF
10571 In order to allow access to the condition registered by
10572 @code{AM_CONDITIONAL} inside @file{configure.ac}, and to allow
10573 conditional @code{AC_CONFIG_FILES}, @code{AM_COND_IF} may be used:
10575 @defmac AM_COND_IF (@var{conditional}, @ovar{if-true}, @ovar{if-false})
10576 If @var{conditional} is fulfilled, execute @var{if-true}, otherwise
10577 execute @var{if-false}. If either branch contains @code{AC_CONFIG_FILES},
10578 it will cause @command{automake} to output the rules for the respective
10579 files only for the given condition.
10582 @code{AM_COND_IF} macros may be nested when m4 quotation is used
10583 properly (@pxref{M4 Quotation, ,, autoconf, The Autoconf Manual}).
10585 @cindex Example conditional @code{AC_CONFIG_FILES}
10586 @cindex @code{AC_CONFIG_FILES}, conditional
10588 Here is an example of how to define a conditional config file:
10591 AM_CONDITIONAL([SHELL_WRAPPER], [test "x$with_wrapper" = xtrue])
10592 AM_COND_IF([SHELL_WRAPPER],
10593 [AC_CONFIG_FILES([wrapper:wrapper.in])])
10596 @node Limits of Conditionals
10597 @section Limits of Conditionals
10599 Conditionals should enclose complete statements like variables or
10600 rules definitions. Automake cannot deal with conditionals used inside
10601 a variable definition, for instance, and is not even able to diagnose
10602 this situation. The following example would not work:
10605 # This syntax is not understood by Automake
10614 However the intended definition of @code{AM_CPPFLAGS} can be achieved
10619 DEBUGFLAGS = -DDEBUG
10621 AM_CPPFLAGS = -DFEATURE_A $(DEBUGFLAGS) -DFEATURE_B
10628 AM_CPPFLAGS = -DFEATURE_A
10630 AM_CPPFLAGS += -DDEBUG
10632 AM_CPPFLAGS += -DFEATURE_B
10635 More details and examples of conditionals are described alongside
10636 various Automake features in this manual (@pxref{Conditional
10637 Subdirectories}, @pxref{Conditional Sources}, @pxref{Conditional
10638 Programs}, @pxref{Conditional Libtool Libraries}, @pxref{Conditional
10641 @node Silencing Make
10642 @chapter Silencing @command{make}
10644 @cindex Silent @command{make}
10645 @cindex Silencing @command{make}
10646 @cindex Silent rules
10647 @cindex Silent @command{make} rules
10650 * Make verbosity:: Make is verbose by default
10651 * Tricks For Silencing Make:: Standard and generic ways to silence make
10652 * Automake silent-rules Option:: How Automake can help in silencing make
10655 @node Make verbosity
10656 @section Make is verbose by default
10658 Normally, when executing the set of rules associated with a target,
10659 @command{make} prints each rule before it is executed. This behaviour,
10660 while having been in place for a long time, and being even mandated by
10661 the POSIX standard, starkly violates the ``silence is golden'' UNIX
10662 principle@footnote{See also
10663 @uref{http://catb.org/~esr/writings/taoup/html/ch11s09.html}.}:
10666 When a program has nothing interesting or surprising to say, it should
10667 say nothing. Well-behaved Unix programs do their jobs unobtrusively,
10668 with a minimum of fuss and bother. Silence is golden.
10671 In fact, while such verbosity of @command{make} can theoretically be
10672 useful to track bugs and understand reasons of failures right away, it
10673 can also hide warning and error messages from @command{make}-invoked
10674 tools, drowning them in a flood of uninteresting and seldom useful
10675 messages, and thus allowing them to go easily undetected.
10677 This problem can be very annoying, especially for developers, who usually
10678 know quite well what's going on behind the scenes, and for whom the
10679 verbose output from @command{make} ends up being mostly noise that hampers
10680 the easy detection of potentially important warning messages.
10682 @node Tricks For Silencing Make
10683 @section Standard and generic ways to silence make
10685 Here we describe some common idioms/tricks to obtain a quieter make
10686 output, with their relative advantages and drawbacks. In the next
10687 section (@ref{Automake silent-rules Option}) we'll see how Automake
10688 can help in this respect.
10692 @item @command{make -s}
10694 This simply causes @command{make} not to print @emph{any} rule before
10697 The @option{-s} flag is mandated by POSIX, universally supported, and
10698 its purpose and function are easy to understand.
10700 But it also has its serious limitations too. First of all, it embodies
10701 an ``all or nothing'' strategy, i.e., either everything is silenced, or
10702 nothing is; this lack of granularity can sometimes be a fatal flaw.
10703 Moreover, when the @option{-s} flag is used, the @command{make} output
10704 might turn out to be too much terse; in case of errors, the user won't
10705 be able to easily see what rule or command have caused them, or even,
10706 in case of tools with poor error reporting, what the errors were!
10708 @item @command{make >/dev/null || make}
10710 Apparently, this perfectly obeys the ``silence is golden'' rule: warnings
10711 from stderr are passed through, output reporting is done only in case of
10712 error, and in that case it should provide a verbose-enough report to allow
10713 an easy determination of the error location and causes.
10715 However, calling @command{make} two times in a row might hide errors
10716 (especially intermittent ones), or subtly change the expected semantic
10717 of the @command{make} calls --- things these which can clearly make
10718 debugging and error assessment very difficult.
10720 @item @command{make --no-print-directory}
10722 This is GNU @command{make} specific. When called with the
10723 @option{--no-print-directory} option, GNU @command{make} will disable
10724 printing of the working directory by invoked sub-@command{make}s (the
10725 well-known ``@i{Entering/Leaving directory ...}'' messages). This helps
10726 to decrease the verbosity of the output, but experience has shown that
10727 it can also often render debugging considerably harder in projects using
10728 deeply-nested @command{make} recursion.
10730 As an aside, notice that the @option{--no-print-directory} option is
10731 automatically activated if the @option{-s} flag is used.
10733 @c TODO: Other tricks?
10734 @c TODO: Maybe speak about the @code{.SILENT} target?
10735 @c TODO: - Pros: More granularity on what to silence.
10736 @c TODO: - Cons: No easy way to temporarily override.
10740 @node Automake silent-rules Option
10741 @section How Automake can help in silencing make
10743 The tricks and idioms for silencing @command{make} described in the
10744 previous section can be useful from time to time, but we've seen that
10745 they all have their serious drawbacks and limitations. That's why
10746 automake provides support for a more advanced and flexible way of
10747 obtaining quieter output from @command{make}: the @option{silent-rules}
10750 @c TODO: Maybe describe in brief the precedent set by the build system
10751 @c of the Linux Kernel, from which Automake took inspiration ... Links?
10753 To give the gist of what @option{silent-rules} can do, here is a simple
10754 comparison between a typical @command{make} output (where silent rules
10755 are disabled) and one with silent rules enabled:
10758 % @kbd{cat Makefile.am}
10760 foo_SOURCES = main.c func.c
10762 int main (void) @{ return func (); @} /* func used undeclared */
10764 int func (void) @{ int i; return i; @} /* i used uninitialized */
10766 @i{The make output is by default very verbose. This causes warnings
10767 from the compiler to be somewhat hidden, and not immediate to spot.}
10768 % @kbd{make CFLAGS=-Wall}
10769 gcc -DPACKAGE_NAME=\"foo\" -DPACKAGE_TARNAME=\"foo\" ...
10770 -DPACKAGE_STRING=\"foo\ 1.0\" -DPACKAGE_BUGREPORT=\"\" ...
10771 -DPACKAGE=\"foo\" -DVERSION=\"1.0\" -I. -Wall -MT main.o
10772 -MD -MP -MF .deps/main.Tpo -c -o main.o main.c
10773 main.c: In function ‘main’:
10774 main.c:3:3: warning: implicit declaration of function ‘func’
10775 mv -f .deps/main.Tpo .deps/main.Po
10776 gcc -DPACKAGE_NAME=\"foo\" -DPACKAGE_TARNAME=\"foo\" ...
10777 -DPACKAGE_STRING=\"foo\ 1.0\" -DPACKAGE_BUGREPORT=\"\" ...
10778 -DPACKAGE=\"foo\" -DVERSION=\"1.0\" -I. -Wall -MT func.o
10779 -MD -MP -MF .deps/func.Tpo -c -o func.o func.c
10780 func.c: In function ‘func’:
10781 func.c:4:3: warning: ‘i’ used uninitialized in this function
10782 mv -f .deps/func.Tpo .deps/func.Po
10783 gcc -Wall -o foo main.o func.o
10785 @i{Clean up, so that we we can rebuild everything from scratch.}
10787 test -z "foo" || rm -f foo
10790 @i{Silent rules enabled: the output is minimal but informative. In
10791 particular, the warnings from the compiler stick out very clearly.}
10792 % @kbd{make V=0 CFLAGS=-Wall}
10794 main.c: In function ‘main’:
10795 main.c:3:3: warning: implicit declaration of function ‘func’
10797 func.c: In function ‘func’:
10798 func.c:4:3: warning: ‘i’ used uninitialized in this function
10802 @cindex silent-rules and libtool
10803 Also, in projects using @command{libtool}, the use of silent rules can
10804 automatically enable the @command{libtool}'s @option{--silent} option:
10807 % @kbd{cat Makefile.am}
10808 lib_LTLIBRARIES = libx.la
10810 % @kbd{make # Both make and libtool are verbose by default.}
10812 libtool: compile: gcc -DPACKAGE_NAME=\"foo\" ... -DLT_OBJDIR=\".libs/\"
10813 -I. -g -O2 -MT libx.lo -MD -MP -MF .deps/libx.Tpo -c libx.c -fPIC
10814 -DPIC -o .libs/libx.o
10815 mv -f .deps/libx.Tpo .deps/libx.Plo
10816 /bin/sh ./libtool --tag=CC --mode=link gcc -g -O2 -o libx.la -rpath
10817 /usr/local/lib libx.lo
10818 libtool: link: gcc -shared .libs/libx.o -Wl,-soname -Wl,libx.so.0
10819 -o .libs/libx.so.0.0.0
10820 libtool: link: cd .libs && rm -f libx.so && ln -s libx.so.0.0.0 libx.so
10828 Let's now see how the @option{silent-rules} mode interfaces with the
10829 package developer and the package user.
10831 To enable the use of @option{silent-rules} in his package, a developer
10832 needs to do either of the following:
10836 Add the @option{silent-rules} option as argument to @code{AM_INIT_AUTOMAKE}.
10838 Call the @code{AM_SILENT_RULES} macro from within the @file{configure.ac}
10842 It is not possible to instead specify @option{silent-rules} in a
10843 @file{Makefile.am} file.
10845 If the developer has done either of the above, then the user of the
10846 package may influence the verbosity at @command{configure} run time as
10847 well as at @command{make} run time:
10851 @opindex --enable-silent-rules
10852 @opindex --disable-silent-rules
10853 Passing @option{--enable-silent-rules} to @command{configure} will cause
10854 build rules to be less verbose; the option @option{--disable-silent-rules}
10855 will cause normal verbose output.
10858 At @command{make} run time, the default chosen at @command{configure}
10859 time may be overridden: @code{make V=1} will produce verbose output,
10860 @code{make V=0} less verbose output.
10863 @cindex default verbosity for silent-rules
10864 Note that silent rules are @emph{disabled} by default; the user must
10865 enable them explicitly at either @command{configure} run time or at
10866 @command{make} run time. We think that this is a good policy, since
10867 it provides the casual user with enough information to prepare a good
10868 bug report in case anything breaks.
10870 Still, notwithstanding the rationales above, a developer who wants to
10871 make silent rules enabled by default in his own package can do so by
10872 adding a @samp{yes} argument to the @code{AM_SILENT_RULES} call in
10873 @file{configure.ac}. We advise against this approach, though.
10875 @c Keep in sync with silent-configsite.test
10876 Users who prefer to have silent rules enabled by default can edit their
10877 @file{config.site} file to make the variable @code{enable_silent_rules}
10878 default to @samp{yes}. This should still allow disabling silent rules
10879 at @command{configure} time and at @command{make} time.
10881 @c FIXME: there's really a need to specify this explicitly?
10882 For portability to different @command{make} implementations, package authors
10883 are advised to not set the variable @code{V} inside the @file{Makefile.am}
10884 file, to allow the user to override the value for subdirectories as well.
10886 The current implementation of this feature normally uses nested
10887 variable expansion @samp{$(@var{var1}$(V))}, a @file{Makefile} feature
10888 that is not required by POSIX 2008 but is widely supported in
10889 practice. The @option{silent-rules} option thus turns off warnings
10890 about recursive variable expansion, which are in turn enabled by
10891 @option{-Wportability} (@pxref{automake Invocation}). On the rare
10892 @command{make} implementations that do not support nested variable
10893 expansion, whether rules are silent is always determined at configure
10894 time, and cannot be overridden at make time. Future versions of POSIX
10895 are likely to require nested variable expansion, so this minor
10896 limitation should go away with time.
10898 @vindex @code{AM_V_GEN}
10899 @vindex @code{AM_V_at}
10900 @vindex @code{AM_DEFAULT_VERBOSITY}
10901 @vindex @code{AM_V}
10902 @vindex @code{AM_DEFAULT_V}
10903 To extend the silent mode to your own rules, you have two choices:
10907 You can use the predefined variable @code{AM_V_GEN} as a prefix to
10908 commands that should output a status line in silent mode, and
10909 @code{AM_V_at} as a prefix to commands that should not output anything
10910 in silent mode. When output is to be verbose, both of these variables
10911 will expand to the empty string.
10913 You can add your own variables, so strings of your own choice are shown.
10914 The following snippet shows how you would define your own equivalent of
10918 pkg_verbose = $(pkg_verbose_@@AM_V@@)
10919 pkg_verbose_ = $(pkg_verbose_@@AM_DEFAULT_V@@)
10920 pkg_verbose_0 = @@echo PKG-GEN $@@;
10923 $(pkg_verbose)cp $(srcdir)/foo.in $@@
10928 As a final note, observe that, even when silent rules are enabled,
10929 the @option{--no-print-directory} option is still required with GNU
10930 @command{make} if the ``@i{Entering/Leaving directory ...}'' messages
10931 are to be disabled.
10934 @chapter The effect of @option{--gnu} and @option{--gnits}
10936 @cindex @option{--gnu}, required files
10937 @cindex @option{--gnu}, complete description
10939 The @option{--gnu} option (or @option{gnu} in the
10940 @code{AUTOMAKE_OPTIONS} variable) causes @command{automake} to check
10945 The files @file{INSTALL}, @file{NEWS}, @file{README}, @file{AUTHORS},
10946 and @file{ChangeLog}, plus one of @file{COPYING.LIB}, @file{COPYING.LESSER}
10947 or @file{COPYING}, are required at the topmost directory of the package.
10949 If the @option{--add-missing} option is given, @command{automake} will
10950 add a generic version of the @file{INSTALL} file as well as the
10951 @file{COPYING} file containing the text of the current version of the
10952 GNU General Public License existing at the time of this Automake release
10953 (version 3 as this is written, @uref{http://www.gnu.org/@/copyleft/@/gpl.html}).
10954 However, an existing @file{COPYING} file will never be overwritten by
10955 @command{automake}.
10958 The options @option{no-installman} and @option{no-installinfo} are
10962 Note that this option will be extended in the future to do even more
10963 checking; it is advisable to be familiar with the precise requirements
10964 of the GNU standards. Also, @option{--gnu} can require certain
10965 non-standard GNU programs to exist for use by various maintainer-only
10966 rules; for instance, in the future @command{pathchk} might be required for
10969 @cindex @option{--gnits}, complete description
10971 The @option{--gnits} option does everything that @option{--gnu} does, and
10972 checks the following as well:
10976 @samp{make installcheck} will check to make sure that the @option{--help}
10977 and @option{--version} really print a usage message and a version string,
10978 respectively. This is the @option{std-options} option (@pxref{Options}).
10981 @samp{make dist} will check to make sure the @file{NEWS} file has been
10982 updated to the current version.
10985 @code{VERSION} is checked to make sure its format complies with Gnits
10987 @c FIXME xref when standards are finished
10990 @cindex @file{README-alpha}
10991 If @code{VERSION} indicates that this is an alpha release, and the file
10992 @file{README-alpha} appears in the topmost directory of a package, then
10993 it is included in the distribution. This is done in @option{--gnits}
10994 mode, and no other, because this mode is the only one where version
10995 number formats are constrained, and hence the only mode where Automake
10996 can automatically determine whether @file{README-alpha} should be
11000 The file @file{THANKS} is required.
11005 @chapter The effect of @option{--cygnus}
11007 @cindex @option{cygnus} strictness
11009 Some packages, notably GNU GCC and GNU gdb, have a build environment
11010 originally written at Cygnus Support (subsequently renamed Cygnus
11011 Solutions, and then later purchased by Red Hat). Packages with this
11012 ancestry are sometimes referred to as ``Cygnus'' trees.
11014 A Cygnus tree has slightly different rules for how a
11015 @file{Makefile.in} is to be constructed. Passing @option{--cygnus} to
11016 @command{automake} will cause any generated @file{Makefile.in} to
11017 comply with Cygnus rules.
11019 Here are the precise effects of @option{--cygnus}:
11023 Info files are always created in the build directory, and not in the
11027 @file{texinfo.tex} is not required if a Texinfo source file is
11028 specified. The assumption is that the file will be supplied, but in a
11029 place that Automake cannot find. This assumption is an artifact of how
11030 Cygnus packages are typically bundled.
11033 @samp{make dist} is not supported, and the rules for it are not
11034 generated. Cygnus-style trees use their own distribution mechanism.
11037 Certain tools will be searched for in the build tree as well as in the
11038 user's @env{PATH}. These tools are @command{runtest}, @command{expect},
11039 @command{makeinfo} and @command{texi2dvi}.
11042 @option{--foreign} is implied.
11045 The options @option{no-installinfo} and @option{no-dependencies} are
11049 The macro @code{AM_MAINTAINER_MODE} is required.
11052 The @code{check} target doesn't depend on @code{all}.
11055 GNU maintainers are advised to use @option{gnu} strictness in preference
11056 to the special Cygnus mode. Some day, perhaps, the differences between
11057 Cygnus trees and GNU trees will disappear (for instance, as GCC is made
11058 more standards compliant). At that time the special Cygnus mode will be
11063 @chapter When Automake Isn't Enough
11065 In some situations, where Automake is not up to one task, one has to
11066 resort to handwritten rules or even handwritten @file{Makefile}s.
11069 * Extending:: Adding new rules or overriding existing ones.
11070 * Third-Party Makefiles:: Integrating Non-Automake @file{Makefile}s.
11074 @section Extending Automake Rules
11076 With some minor exceptions (for example @code{_PROGRAMS} variables,
11077 @code{TESTS}, or @code{XFAIL_TESTS}) being rewritten to append
11078 @samp{$(EXEEXT)}), the contents of a @file{Makefile.am} is copied to
11079 @file{Makefile.in} verbatim.
11081 @cindex copying semantics
11083 These copying semantics mean that many problems can be worked around
11084 by simply adding some @command{make} variables and rules to
11085 @file{Makefile.am}. Automake will ignore these additions.
11087 @cindex conflicting definitions
11088 @cindex rules, conflicting
11089 @cindex variables, conflicting
11090 @cindex definitions, conflicts
11092 Since a @file{Makefile.in} is built from data gathered from three
11093 different places (@file{Makefile.am}, @file{configure.ac}, and
11094 @command{automake} itself), it is possible to have conflicting
11095 definitions of rules or variables. When building @file{Makefile.in}
11096 the following priorities are respected by @command{automake} to ensure
11097 the user always has the last word:
11101 User defined variables in @file{Makefile.am} have priority over
11102 variables @code{AC_SUBST}ed from @file{configure.ac}, and
11103 @code{AC_SUBST}ed variables have priority over
11104 @command{automake}-defined variables.
11106 As far as rules are concerned, a user-defined rule overrides any
11107 @command{automake}-defined rule for the same target.
11110 @cindex overriding rules
11111 @cindex overriding semantics
11112 @cindex rules, overriding
11114 These overriding semantics make it possible to fine tune some default
11115 settings of Automake, or replace some of its rules. Overriding
11116 Automake rules is often inadvisable, particularly in the topmost
11117 directory of a package with subdirectories. The @option{-Woverride}
11118 option (@pxref{automake Invocation}) comes in handy to catch overridden
11121 Note that Automake does not make any distinction between rules with
11122 commands and rules that only specify dependencies. So it is not
11123 possible to append new dependencies to an @command{automake}-defined
11124 target without redefining the entire rule.
11126 @cindex @option{-local} targets
11127 @cindex local targets
11129 However, various useful targets have a @samp{-local} version you can
11130 specify in your @file{Makefile.am}. Automake will supplement the
11131 standard target with these user-supplied targets.
11136 @trindex info-local
11144 @trindex html-local
11146 @trindex check-local
11148 @trindex install-data
11149 @trindex install-data-local
11150 @trindex install-dvi
11151 @trindex install-dvi-local
11152 @trindex install-exec
11153 @trindex install-exec-local
11154 @trindex install-html
11155 @trindex install-html-local
11156 @trindex install-info
11157 @trindex install-info-local
11158 @trindex install-pdf
11159 @trindex install-pdf-local
11160 @trindex install-ps
11161 @trindex install-ps-local
11163 @trindex uninstall-local
11164 @trindex mostlyclean
11165 @trindex mostlyclean-local
11167 @trindex clean-local
11169 @trindex distclean-local
11170 @trindex installdirs
11171 @trindex installdirs-local
11172 @trindex installcheck
11173 @trindex installcheck-local
11175 The targets that support a local version are @code{all}, @code{info},
11176 @code{dvi}, @code{ps}, @code{pdf}, @code{html}, @code{check},
11177 @code{install-data}, @code{install-dvi}, @code{install-exec},
11178 @code{install-html}, @code{install-info}, @code{install-pdf},
11179 @code{install-ps}, @code{uninstall}, @code{installdirs},
11180 @code{installcheck} and the various @code{clean} targets
11181 (@code{mostlyclean}, @code{clean}, @code{distclean}, and
11182 @code{maintainer-clean}).
11184 Note that there are no @code{uninstall-exec-local} or
11185 @code{uninstall-data-local} targets; just use @code{uninstall-local}.
11186 It doesn't make sense to uninstall just data or just executables.
11188 For instance, here is one way to erase a subdirectory during
11189 @samp{make clean} (@pxref{Clean}).
11196 You may be tempted to use @code{install-data-local} to install a file
11197 to some hard-coded location, but you should avoid this
11198 (@pxref{Hard-Coded Install Paths}).
11200 With the @code{-local} targets, there is no particular guarantee of
11201 execution order; typically, they are run early, but with parallel
11202 make, there is no way to be sure of that.
11204 @cindex @option{-hook} targets
11205 @cindex hook targets
11206 @trindex install-data-hook
11207 @trindex install-exec-hook
11208 @trindex uninstall-hook
11211 In contrast, some rules also have a way to run another rule, called a
11212 @dfn{hook}; hooks are always executed after the main rule's work is done.
11213 The hook is named after the principal target, with @samp{-hook} appended.
11214 The targets allowing hooks are @code{install-data},
11215 @code{install-exec}, @code{uninstall}, @code{dist}, and
11218 For instance, here is how to create a hard link to an installed program:
11222 ln $(DESTDIR)$(bindir)/program$(EXEEXT) \
11223 $(DESTDIR)$(bindir)/proglink$(EXEEXT)
11226 Although cheaper and more portable than symbolic links, hard links
11227 will not work everywhere (for instance, OS/2 does not have
11228 @command{ln}). Ideally you should fall back to @samp{cp -p} when
11229 @command{ln} does not work. An easy way, if symbolic links are
11230 acceptable to you, is to add @code{AC_PROG_LN_S} to
11231 @file{configure.ac} (@pxref{Particular Programs, , Particular Program
11232 Checks, autoconf, The Autoconf Manual}) and use @samp{$(LN_S)} in
11233 @file{Makefile.am}.
11235 @cindex versioned binaries, installing
11236 @cindex installing versioned binaries
11237 @cindex @code{LN_S} example
11238 For instance, here is how you could install a versioned copy of a
11239 program using @samp{$(LN_S)}:
11241 @c Keep in sync with insthook.test
11244 cd $(DESTDIR)$(bindir) && \
11245 mv -f prog$(EXEEXT) prog-$(VERSION)$(EXEEXT) && \
11246 $(LN_S) prog-$(VERSION)$(EXEEXT) prog$(EXEEXT)
11249 Note that we rename the program so that a new version will erase the
11250 symbolic link, not the real binary. Also we @command{cd} into the
11251 destination directory in order to create relative links.
11253 When writing @code{install-exec-hook} or @code{install-data-hook},
11254 please bear in mind that the exec/data distinction is based on the
11255 installation directory, not on the primary used (@pxref{The Two Parts of
11257 @c Keep in sync with primary-prefix-couples-documented-valid.test.
11258 So a @code{foo_SCRIPTS} will be installed by
11259 @code{install-data}, and a @code{barexec_SCRIPTS} will be installed by
11260 @code{install-exec}. You should define your hooks consequently.
11262 @c FIXME should include discussion of variables you can use in these
11265 @node Third-Party Makefiles
11266 @section Third-Party @file{Makefile}s
11268 @cindex Third-party packages, interfacing with
11269 @cindex Interfacing with third-party packages
11271 In most projects all @file{Makefile}s are generated by Automake. In
11272 some cases, however, projects need to embed subdirectories with
11273 handwritten @file{Makefile}s. For instance, one subdirectory could be
11274 a third-party project with its own build system, not using Automake.
11276 It is possible to list arbitrary directories in @code{SUBDIRS} or
11277 @code{DIST_SUBDIRS} provided each of these directories has a
11278 @file{Makefile} that recognizes all the following recursive targets.
11280 @cindex recursive targets and third-party @file{Makefile}s
11281 When a user runs one of these targets, that target is run recursively
11282 in all subdirectories. This is why it is important that even
11283 third-party @file{Makefile}s support them.
11287 Compile the entire package. This is the default target in
11288 Automake-generated @file{Makefile}s, but it does not need to be the
11289 default in third-party @file{Makefile}s.
11294 @vindex top_distdir
11295 Copy files to distribute into @samp{$(distdir)}, before a tarball is
11296 constructed. Of course this target is not required if the
11297 @option{no-dist} option (@pxref{Options}) is used.
11299 The variables @samp{$(top_distdir)} and @samp{$(distdir)}
11300 (@pxref{The dist Hook}) will be passed from the outer package to the subpackage
11301 when the @code{distdir} target is invoked. These two variables have
11302 been adjusted for the directory that is being recursed into, so they
11306 @itemx install-data
11307 @itemx install-exec
11309 Install or uninstall files (@pxref{Install}).
11312 @itemx install-html
11313 @itemx install-info
11316 Install only some specific documentation format (@pxref{Texinfo}).
11319 Create install directories, but do not install any files.
11322 @itemx installcheck
11323 Check the package (@pxref{Tests}).
11328 @itemx maintainer-clean
11329 Cleaning rules (@pxref{Clean}).
11336 Build the documentation in various formats (@pxref{Texinfo}).
11340 Build @file{TAGS} and @file{CTAGS} (@pxref{Tags}).
11343 If you have ever used Gettext in a project, this is a good example of
11344 how third-party @file{Makefile}s can be used with Automake. The
11345 @file{Makefile}s @command{gettextize} puts in the @file{po/} and
11346 @file{intl/} directories are handwritten @file{Makefile}s that
11347 implement all these targets. That way they can be added to
11348 @code{SUBDIRS} in Automake packages.
11350 Directories that are only listed in @code{DIST_SUBDIRS} but not in
11351 @code{SUBDIRS} need only the @code{distclean},
11352 @code{maintainer-clean}, and @code{distdir} rules (@pxref{Conditional
11355 Usually, many of these rules are irrelevant to the third-party
11356 subproject, but they are required for the whole package to work. It's
11357 OK to have a rule that does nothing, so if you are integrating a
11358 third-party project with no documentation or tag support, you could
11359 simply augment its @file{Makefile} as follows:
11362 EMPTY_AUTOMAKE_TARGETS = dvi pdf ps info html tags ctags
11363 .PHONY: $(EMPTY_AUTOMAKE_TARGETS)
11364 $(EMPTY_AUTOMAKE_TARGETS):
11367 Another aspect of integrating third-party build systems is whether
11368 they support VPATH builds (@pxref{VPATH Builds}). Obviously if the
11369 subpackage does not support VPATH builds the whole package will not
11370 support VPATH builds. This in turns means that @samp{make distcheck}
11371 will not work, because it relies on VPATH builds. Some people can
11372 live without this (actually, many Automake users have never heard of
11373 @samp{make distcheck}). Other people may prefer to revamp the
11374 existing @file{Makefile}s to support VPATH@. Doing so does not
11375 necessarily require Automake, only Autoconf is needed (@pxref{Build
11376 Directories, , Build Directories, autoconf, The Autoconf Manual}).
11377 The necessary substitutions: @samp{@@srcdir@@}, @samp{@@top_srcdir@@},
11378 and @samp{@@top_builddir@@} are defined by @file{configure} when it
11379 processes a @file{Makefile} (@pxref{Preset Output Variables, , Preset
11380 Output Variables, autoconf, The Autoconf Manual}), they are not
11381 computed by the Makefile like the aforementioned @samp{$(distdir)} and
11382 @samp{$(top_distdir)} variables.
11384 It is sometimes inconvenient to modify a third-party @file{Makefile}
11385 to introduce the above required targets. For instance, one may want to
11386 keep the third-party sources untouched to ease upgrades to new
11389 @cindex @file{GNUmakefile} including @file{Makefile}
11390 Here are two other ideas. If GNU make is assumed, one possibility is
11391 to add to that subdirectory a @file{GNUmakefile} that defines the
11392 required targets and includes the third-party @file{Makefile}. For
11393 this to work in VPATH builds, @file{GNUmakefile} must lie in the build
11394 directory; the easiest way to do this is to write a
11395 @file{GNUmakefile.in} instead, and have it processed with
11396 @code{AC_CONFIG_FILES} from the outer package. For example if we
11397 assume @file{Makefile} defines all targets except the documentation
11398 targets, and that the @code{check} target is actually called
11399 @code{test}, we could write @file{GNUmakefile} (or
11400 @file{GNUmakefile.in}) like this:
11403 # First, include the real Makefile
11405 # Then, define the other targets needed by Automake Makefiles.
11406 .PHONY: dvi pdf ps info html check
11407 dvi pdf ps info html:
11411 @cindex Proxy @file{Makefile} for third-party packages
11412 A similar idea that does not use @code{include} is to write a proxy
11413 @file{Makefile} that dispatches rules to the real @file{Makefile},
11414 either with @samp{$(MAKE) -f Makefile.real $(AM_MAKEFLAGS) target} (if
11415 it's OK to rename the original @file{Makefile}) or with @samp{cd
11416 subdir && $(MAKE) $(AM_MAKEFLAGS) target} (if it's OK to store the
11417 subdirectory project one directory deeper). The good news is that
11418 this proxy @file{Makefile} can be generated with Automake. All we
11419 need are @option{-local} targets (@pxref{Extending}) that perform the
11420 dispatch. Of course the other Automake features are available, so you
11421 could decide to let Automake perform distribution or installation.
11422 Here is a possible @file{Makefile.am}:
11426 cd subdir && $(MAKE) $(AM_MAKEFLAGS) all
11428 cd subdir && $(MAKE) $(AM_MAKEFLAGS) test
11430 cd subdir && $(MAKE) $(AM_MAKEFLAGS) clean
11432 # Assuming the package knows how to install itself
11433 install-data-local:
11434 cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-data
11435 install-exec-local:
11436 cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-exec
11438 cd subdir && $(MAKE) $(AM_MAKEFLAGS) uninstall
11440 # Distribute files from here.
11441 EXTRA_DIST = subdir/Makefile subdir/program.c ...
11444 Pushing this idea to the extreme, it is also possible to ignore the
11445 subproject build system and build everything from this proxy
11446 @file{Makefile.am}. This might sound very sensible if you need VPATH
11447 builds but the subproject does not support them.
11450 @chapter Distributing @file{Makefile.in}s
11452 Automake places no restrictions on the distribution of the resulting
11453 @file{Makefile.in}s. We still encourage software authors to
11454 distribute their work under terms like those of the GPL, but doing so
11455 is not required to use Automake.
11457 Some of the files that can be automatically installed via the
11458 @option{--add-missing} switch do fall under the GPL@. However, these also
11459 have a special exception allowing you to distribute them with your
11460 package, regardless of the licensing you choose.
11463 @node API Versioning
11464 @chapter Automake API Versioning
11466 New Automake releases usually include bug fixes and new features.
11467 Unfortunately they may also introduce new bugs and incompatibilities.
11468 This makes four reasons why a package may require a particular Automake
11471 Things get worse when maintaining a large tree of packages, each one
11472 requiring a different version of Automake. In the past, this meant that
11473 any developer (and sometimes users) had to install several versions of
11474 Automake in different places, and switch @samp{$PATH} appropriately for
11477 Starting with version 1.6, Automake installs versioned binaries. This
11478 means you can install several versions of Automake in the same
11479 @samp{$prefix}, and can select an arbitrary Automake version by running
11480 @command{automake-1.6} or @command{automake-1.7} without juggling with
11481 @samp{$PATH}. Furthermore, @file{Makefile}'s generated by Automake 1.6
11482 will use @command{automake-1.6} explicitly in their rebuild rules.
11484 The number @samp{1.6} in @command{automake-1.6} is Automake's API version,
11485 not Automake's version. If a bug fix release is made, for instance
11486 Automake 1.6.1, the API version will remain 1.6. This means that a
11487 package that works with Automake 1.6 should also work with 1.6.1; after
11488 all, this is what people expect from bug fix releases.
11490 If your package relies on a feature or a bug fix introduced in
11491 a release, you can pass this version as an option to Automake to ensure
11492 older releases will not be used. For instance, use this in your
11493 @file{configure.ac}:
11496 AM_INIT_AUTOMAKE([1.6.1]) dnl Require Automake 1.6.1 or better.
11500 or, in a particular @file{Makefile.am}:
11503 AUTOMAKE_OPTIONS = 1.6.1 # Require Automake 1.6.1 or better.
11507 Automake will print an error message if its version is
11508 older than the requested version.
11511 @heading What is in the API
11513 Automake's programming interface is not easy to define. Basically it
11514 should include at least all @strong{documented} variables and targets
11515 that a @file{Makefile.am} author can use, any behavior associated with
11516 them (e.g., the places where @samp{-hook}'s are run), the command line
11517 interface of @command{automake} and @command{aclocal}, @dots{}
11519 @heading What is not in the API
11521 Every undocumented variable, target, or command line option, is not part
11522 of the API@. You should avoid using them, as they could change from one
11523 version to the other (even in bug fix releases, if this helps to fix a
11526 If it turns out you need to use such an undocumented feature, contact
11527 @email{automake@@gnu.org} and try to get it documented and exercised by
11531 @chapter Upgrading a Package to a Newer Automake Version
11533 Automake maintains three kind of files in a package.
11536 @item @file{aclocal.m4}
11537 @item @file{Makefile.in}s
11538 @item auxiliary tools like @file{install-sh} or @file{py-compile}
11541 @file{aclocal.m4} is generated by @command{aclocal} and contains some
11542 Automake-supplied M4 macros. Auxiliary tools are installed by
11543 @samp{automake --add-missing} when needed. @file{Makefile.in}s are
11544 built from @file{Makefile.am} by @command{automake}, and rely on the
11545 definitions of the M4 macros put in @file{aclocal.m4} as well as the
11546 behavior of the auxiliary tools installed.
11548 Because all these files are closely related, it is important to
11549 regenerate all of them when upgrading to a newer Automake release.
11550 The usual way to do that is
11553 aclocal # with any option needed (such a -I m4)
11555 automake --add-missing --force-missing
11559 or more conveniently:
11565 The use of @option{--force-missing} ensures that auxiliary tools will be
11566 overridden by new versions (@pxref{automake Invocation}).
11568 It is important to regenerate all these files each time Automake is
11569 upgraded, even between bug fixes releases. For instance, it is not
11570 unusual for a bug fix to involve changes to both the rules generated
11571 in @file{Makefile.in} and the supporting M4 macros copied to
11574 Presently @command{automake} is able to diagnose situations where
11575 @file{aclocal.m4} has been generated with another version of
11576 @command{aclocal}. However it never checks whether auxiliary scripts
11577 are up-to-date. In other words, @command{automake} will tell you when
11578 @command{aclocal} needs to be rerun, but it will never diagnose a
11579 missing @option{--force-missing}.
11581 Before upgrading to a new major release, it is a good idea to read the
11582 file @file{NEWS}. This file lists all changes between releases: new
11583 features, obsolete constructs, known incompatibilities, and
11587 @chapter Frequently Asked Questions about Automake
11589 This chapter covers some questions that often come up on the mailing
11593 * CVS:: CVS and generated files
11594 * maintainer-mode:: missing and AM_MAINTAINER_MODE
11595 * Wildcards:: Why doesn't Automake support wildcards?
11596 * Limitations on File Names:: Limitations on source and installed file names
11597 * distcleancheck:: Files left in build directory after distclean
11598 * Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS
11599 * Renamed Objects:: Why are object files sometimes renamed?
11600 * Per-Object Flags:: How to simulate per-object flags?
11601 * Multiple Outputs:: Writing rules for tools with many output files
11602 * Hard-Coded Install Paths:: Installing to hard-coded locations
11603 * Debugging Make Rules:: Strategies when things don't work as expected
11604 * Reporting Bugs:: Feedback on bugs and feature requests
11608 @section CVS and generated files
11610 @subheading Background: distributed generated Files
11611 @cindex generated files, distributed
11612 @cindex rebuild rules
11614 Packages made with Autoconf and Automake ship with some generated
11615 files like @file{configure} or @file{Makefile.in}. These files were
11616 generated on the developer's host and are distributed so that
11617 end-users do not have to install the maintainer tools required to
11618 rebuild them. Other generated files like Lex scanners, Yacc parsers,
11619 or Info documentation, are usually distributed on similar grounds.
11621 Automake outputs rules in @file{Makefile}s to rebuild these files. For
11622 instance, @command{make} will run @command{autoconf} to rebuild
11623 @file{configure} whenever @file{configure.ac} is changed. This makes
11624 development safer by ensuring a @file{configure} is never out-of-date
11625 with respect to @file{configure.ac}.
11627 As generated files shipped in packages are up-to-date, and because
11628 @command{tar} preserves times-tamps, these rebuild rules are not
11629 triggered when a user unpacks and builds a package.
11631 @subheading Background: CVS and Timestamps
11632 @cindex timestamps and CVS
11633 @cindex CVS and timestamps
11635 Unless you use CVS keywords (in which case files must be updated at
11636 commit time), CVS preserves timestamp during @samp{cvs commit} and
11637 @samp{cvs import -d} operations.
11639 When you check out a file using @samp{cvs checkout} its timestamp is
11640 set to that of the revision that is being checked out.
11642 However, during @command{cvs update}, files will have the date of the
11643 update, not the original timestamp of this revision. This is meant to
11644 make sure that @command{make} notices sources files have been updated.
11646 This timestamp shift is troublesome when both sources and generated
11647 files are kept under CVS@. Because CVS processes files in lexical
11648 order, @file{configure.ac} will appear newer than @file{configure}
11649 after a @command{cvs update} that updates both files, even if
11650 @file{configure} was newer than @file{configure.ac} when it was
11651 checked in. Calling @command{make} will then trigger a spurious rebuild
11652 of @file{configure}.
11654 @subheading Living with CVS in Autoconfiscated Projects
11655 @cindex CVS and generated files
11656 @cindex generated files and CVS
11658 There are basically two clans amongst maintainers: those who keep all
11659 distributed files under CVS, including generated files, and those who
11660 keep generated files @emph{out} of CVS.
11662 @subsubheading All Files in CVS
11666 The CVS repository contains all distributed files so you know exactly
11667 what is distributed, and you can checkout any prior version entirely.
11670 Maintainers can see how generated files evolve (for instance, you can
11671 see what happens to your @file{Makefile.in}s when you upgrade Automake
11672 and make sure they look OK).
11675 Users do not need the autotools to build a checkout of the project, it
11676 works just like a released tarball.
11679 If users use @command{cvs update} to update their copy, instead of
11680 @command{cvs checkout} to fetch a fresh one, timestamps will be
11681 inaccurate. Some rebuild rules will be triggered and attempt to
11682 run developer tools such as @command{autoconf} or @command{automake}.
11684 Actually, calls to such tools are all wrapped into a call to the
11685 @command{missing} script discussed later (@pxref{maintainer-mode}).
11686 @command{missing} will take care of fixing the timestamps when these
11687 tools are not installed, so that the build can continue.
11690 In distributed development, developers are likely to have different
11691 version of the maintainer tools installed. In this case rebuilds
11692 triggered by timestamp lossage will lead to spurious changes
11693 to generated files. There are several solutions to this:
11697 All developers should use the same versions, so that the rebuilt files
11698 are identical to files in CVS@. (This starts to be difficult when each
11699 project you work on uses different versions.)
11701 Or people use a script to fix the timestamp after a checkout (the GCC
11702 folks have such a script).
11704 Or @file{configure.ac} uses @code{AM_MAINTAINER_MODE}, which will
11705 disable all these rebuild rules by default. This is further discussed
11706 in @ref{maintainer-mode}.
11710 Although we focused on spurious rebuilds, the converse can also
11711 happen. CVS's timestamp handling can also let you think an
11712 out-of-date file is up-to-date.
11714 For instance, suppose a developer has modified @file{Makefile.am} and
11715 has rebuilt @file{Makefile.in}, and then decides to do a last-minute
11716 change to @file{Makefile.am} right before checking in both files
11717 (without rebuilding @file{Makefile.in} to account for the change).
11719 This last change to @file{Makefile.am} makes the copy of
11720 @file{Makefile.in} out-of-date. Since CVS processes files
11721 alphabetically, when another developer @samp{cvs update}s his or her
11722 tree, @file{Makefile.in} will happen to be newer than
11723 @file{Makefile.am}. This other developer will not see that
11724 @file{Makefile.in} is out-of-date.
11728 @subsubheading Generated Files out of CVS
11730 One way to get CVS and @command{make} working peacefully is to never
11731 store generated files in CVS, i.e., do not CVS-control files that
11732 are @file{Makefile} targets (also called @emph{derived} files).
11734 This way developers are not annoyed by changes to generated files. It
11735 does not matter if they all have different versions (assuming they are
11736 compatible, of course). And finally, timestamps are not lost, changes
11737 to sources files can't be missed as in the
11738 @file{Makefile.am}/@file{Makefile.in} example discussed earlier.
11740 The drawback is that the CVS repository is not an exact copy of what
11741 is distributed and that users now need to install various development
11742 tools (maybe even specific versions) before they can build a checkout.
11743 But, after all, CVS's job is versioning, not distribution.
11745 Allowing developers to use different versions of their tools can also
11746 hide bugs during distributed development. Indeed, developers will be
11747 using (hence testing) their own generated files, instead of the
11748 generated files that will be released actually. The developer who
11749 prepares the tarball might be using a version of the tool that
11750 produces bogus output (for instance a non-portable C file), something
11751 other developers could have noticed if they weren't using their own
11752 versions of this tool.
11754 @subheading Third-party Files
11755 @cindex CVS and third-party files
11756 @cindex third-party files and CVS
11758 Another class of files not discussed here (because they do not cause
11759 timestamp issues) are files that are shipped with a package, but
11760 maintained elsewhere. For instance, tools like @command{gettextize}
11761 and @command{autopoint} (from Gettext) or @command{libtoolize} (from
11762 Libtool), will install or update files in your package.
11764 These files, whether they are kept under CVS or not, raise similar
11765 concerns about version mismatch between developers' tools. The
11766 Gettext manual has a section about this, see @ref{CVS Issues, CVS
11767 Issues, Integrating with CVS, gettext, GNU gettext tools}.
11769 @node maintainer-mode
11770 @section @command{missing} and @code{AM_MAINTAINER_MODE}
11772 @subheading @command{missing}
11773 @cindex @command{missing}, purpose
11775 The @command{missing} script is a wrapper around several maintainer
11776 tools, designed to warn users if a maintainer tool is required but
11777 missing. Typical maintainer tools are @command{autoconf},
11778 @command{automake}, @command{bison}, etc. Because file generated by
11779 these tools are shipped with the other sources of a package, these
11780 tools shouldn't be required during a user build and they are not
11781 checked for in @file{configure}.
11783 However, if for some reason a rebuild rule is triggered and involves a
11784 missing tool, @command{missing} will notice it and warn the user.
11785 Besides the warning, when a tool is missing, @command{missing} will
11786 attempt to fix timestamps in a way that allows the build to continue.
11787 For instance, @command{missing} will touch @file{configure} if
11788 @command{autoconf} is not installed. When all distributed files are
11789 kept under version control, this feature of @command{missing} allows a
11790 user @emph{with no maintainer tools} to build a package off its version
11791 control repository, bypassing any timestamp inconsistency (implied by
11792 e.g.@: @samp{cvs update} or @samp{git clone}).
11794 If the required tool is installed, @command{missing} will run it and
11795 won't attempt to continue after failures. This is correct during
11796 development: developers love fixing failures. However, users with
11797 wrong versions of maintainer tools may get an error when the rebuild
11798 rule is spuriously triggered, halting the build. This failure to let
11799 the build continue is one of the arguments of the
11800 @code{AM_MAINTAINER_MODE} advocates.
11802 @subheading @code{AM_MAINTAINER_MODE}
11803 @cindex @code{AM_MAINTAINER_MODE}, purpose
11804 @acindex AM_MAINTAINER_MODE
11806 @code{AM_MAINTAINER_MODE} allows you to choose whether the so called
11807 "rebuild rules" should be enabled or disabled. With
11808 @code{AM_MAINTAINER_MODE([enable])}, they are enabled by default,
11809 otherwise they are disabled by default. In the latter case, if
11810 you have @code{AM_MAINTAINER_MODE} in @file{configure.ac}, and run
11811 @samp{./configure && make}, then @command{make} will *never* attempt to
11812 rebuild @file{configure}, @file{Makefile.in}s, Lex or Yacc outputs, etc.
11813 I.e., this disables build rules for files that are usually distributed
11814 and that users should normally not have to update.
11816 The user can override the default setting by passing either
11817 @samp{--enable-maintainer-mode} or @samp{--disable-maintainer-mode}
11818 to @command{configure}.
11820 People use @code{AM_MAINTAINER_MODE} either because they do not want their
11821 users (or themselves) annoyed by timestamps lossage (@pxref{CVS}), or
11822 because they simply can't stand the rebuild rules and prefer running
11823 maintainer tools explicitly.
11825 @code{AM_MAINTAINER_MODE} also allows you to disable some custom build
11826 rules conditionally. Some developers use this feature to disable
11827 rules that need exotic tools that users may not have available.
11829 Several years ago Fran@,{c}ois Pinard pointed out several arguments
11830 against this @code{AM_MAINTAINER_MODE} macro. Most of them relate to
11831 insecurity. By removing dependencies you get non-dependable builds:
11832 changes to sources files can have no effect on generated files and this
11833 can be very confusing when unnoticed. He adds that security shouldn't
11834 be reserved to maintainers (what @option{--enable-maintainer-mode}
11835 suggests), on the contrary. If one user has to modify a
11836 @file{Makefile.am}, then either @file{Makefile.in} should be updated
11837 or a warning should be output (this is what Automake uses
11838 @command{missing} for) but the last thing you want is that nothing
11839 happens and the user doesn't notice it (this is what happens when
11840 rebuild rules are disabled by @code{AM_MAINTAINER_MODE}).
11842 Jim Meyering, the inventor of the @code{AM_MAINTAINER_MODE} macro was
11843 swayed by Fran@,{c}ois's arguments, and got rid of
11844 @code{AM_MAINTAINER_MODE} in all of his packages.
11846 Still many people continue to use @code{AM_MAINTAINER_MODE}, because
11847 it helps them working on projects where all files are kept under version
11848 control, and because @command{missing} isn't enough if you have the
11849 wrong version of the tools.
11853 @section Why doesn't Automake support wildcards?
11856 Developers are lazy. They would often like to use wildcards in
11857 @file{Makefile.am}s, so that they would not need to remember to
11858 update @file{Makefile.am}s every time they add, delete, or rename
11861 There are several objections to this:
11864 When using CVS (or similar) developers need to remember they have to
11865 run @samp{cvs add} or @samp{cvs rm} anyway. Updating
11866 @file{Makefile.am} accordingly quickly becomes a reflex.
11868 Conversely, if your application doesn't compile
11869 because you forgot to add a file in @file{Makefile.am}, it will help
11870 you remember to @samp{cvs add} it.
11873 Using wildcards makes it easy to distribute files by mistake. For
11874 instance, some code a developer is experimenting with (a test case,
11875 say) that should not be part of the distribution.
11878 Using wildcards it's easy to omit some files by mistake. For
11879 instance, one developer creates a new file, uses it in many places,
11880 but forgets to commit it. Another developer then checks out the
11881 incomplete project and is able to run @samp{make dist} successfully,
11882 even though a file is missing. By listing files, @samp{make dist}
11883 @emph{will} complain.
11886 Wildcards are not portable to some non-GNU @command{make} implementations,
11887 e.g., NetBSD @command{make} will not expand globs such as @samp{*} in
11888 prerequisites of a target.
11891 Finally, it's really hard to @emph{forget} to add a file to
11892 @file{Makefile.am}: files that are not listed in @file{Makefile.am} are
11893 not compiled or installed, so you can't even test them.
11896 Still, these are philosophical objections, and as such you may disagree,
11897 or find enough value in wildcards to dismiss all of them. Before you
11898 start writing a patch against Automake to teach it about wildcards,
11899 let's see the main technical issue: portability.
11901 Although @samp{$(wildcard ...)} works with GNU @command{make}, it is
11902 not portable to other @command{make} implementations.
11904 The only way Automake could support @command{$(wildcard ...)} is by
11905 expending @command{$(wildcard ...)} when @command{automake} is run.
11906 The resulting @file{Makefile.in}s would be portable since they would
11907 list all files and not use @samp{$(wildcard ...)}. However that
11908 means developers would need to remember to run @command{automake} each
11909 time they add, delete, or rename files.
11911 Compared to editing @file{Makefile.am}, this is a very small gain. Sure,
11912 it's easier and faster to type @samp{automake; make} than to type
11913 @samp{emacs Makefile.am; make}. But nobody bothered enough to write a
11914 patch to add support for this syntax. Some people use scripts to
11915 generate file lists in @file{Makefile.am} or in separate
11916 @file{Makefile} fragments.
11918 Even if you don't care about portability, and are tempted to use
11919 @samp{$(wildcard ...)} anyway because you target only GNU Make, you
11920 should know there are many places where Automake needs to know exactly
11921 which files should be processed. As Automake doesn't know how to
11922 expand @samp{$(wildcard ...)}, you cannot use it in these places.
11923 @samp{$(wildcard ...)} is a black box comparable to @code{AC_SUBST}ed
11924 variables as far Automake is concerned.
11926 You can get warnings about @samp{$(wildcard ...}) constructs using the
11927 @option{-Wportability} flag.
11929 @node Limitations on File Names
11930 @section Limitations on File Names
11931 @cindex file names, limitations on
11933 Automake attempts to support all kinds of file names, even those that
11934 contain unusual characters or are unusually long. However, some
11935 limitations are imposed by the underlying operating system and tools.
11937 Most operating systems prohibit the use of the null byte in file
11938 names, and reserve @samp{/} as a directory separator. Also, they
11939 require that file names are properly encoded for the user's locale.
11940 Automake is subject to these limits.
11942 Portable packages should limit themselves to POSIX file
11943 names. These can contain ASCII letters and digits,
11944 @samp{_}, @samp{.}, and @samp{-}. File names consist of components
11945 separated by @samp{/}. File name components cannot begin with
11948 Portable POSIX file names cannot contain components that exceed a
11949 14-byte limit, but nowadays it's normally safe to assume the
11950 more-generous XOPEN limit of 255 bytes. POSIX
11951 limits file names to 255 bytes (XOPEN allows 1023 bytes),
11952 but you may want to limit a source tarball to file names of 99 bytes
11953 to avoid interoperability problems with old versions of @command{tar}.
11955 If you depart from these rules (e.g., by using non-ASCII
11956 characters in file names, or by using lengthy file names), your
11957 installers may have problems for reasons unrelated to Automake.
11958 However, if this does not concern you, you should know about the
11959 limitations imposed by Automake itself. These limitations are
11960 undesirable, but some of them seem to be inherent to underlying tools
11961 like Autoconf, Make, M4, and the shell. They fall into three
11962 categories: install directories, build directories, and file names.
11964 The following characters:
11967 @r{newline} " # $ ' `
11970 should not appear in the names of install directories. For example,
11971 the operand of @command{configure}'s @option{--prefix} option should
11972 not contain these characters.
11974 Build directories suffer the same limitations as install directories,
11975 and in addition should not contain the following characters:
11981 For example, the full name of the directory containing the source
11982 files should not contain these characters.
11984 Source and installation file names like @file{main.c} are limited even
11985 further: they should conform to the POSIX/XOPEN
11986 rules described above. In addition, if you plan to port to
11987 non-POSIX environments, you should avoid file names that
11988 differ only in case (e.g., @file{makefile} and @file{Makefile}).
11989 Nowadays it is no longer worth worrying about the 8.3 limits of
11992 @node distcleancheck
11993 @section Files left in build directory after distclean
11994 @cindex @code{distclean}, diagnostic
11995 @cindex @samp{make distclean}, diagnostic
11996 @cindex dependencies and distributed files
11998 @trindex distcleancheck
12000 This is a diagnostic you might encounter while running @samp{make
12003 As explained in @ref{Checking the Distribution}, @samp{make distcheck}
12004 attempts to build and check your package for errors like this one.
12006 @samp{make distcheck} will perform a @code{VPATH} build of your
12007 package (@pxref{VPATH Builds}), and then call @samp{make distclean}.
12008 Files left in the build directory after @samp{make distclean} has run
12009 are listed after this error.
12011 This diagnostic really covers two kinds of errors:
12015 files that are forgotten by distclean;
12017 distributed files that are erroneously rebuilt.
12020 The former left-over files are not distributed, so the fix is to mark
12021 them for cleaning (@pxref{Clean}), this is obvious and doesn't deserve
12024 The latter bug is not always easy to understand and fix, so let's
12025 proceed with an example. Suppose our package contains a program for
12026 which we want to build a man page using @command{help2man}. GNU
12027 @command{help2man} produces simple manual pages from the @option{--help}
12028 and @option{--version} output of other commands (@pxref{Top, , Overview,
12029 help2man, The Help2man Manual}). Because we don't want to force our
12030 users to install @command{help2man}, we decide to distribute the
12031 generated man page using the following setup.
12034 # This Makefile.am is bogus.
12036 foo_SOURCES = foo.c
12037 dist_man_MANS = foo.1
12039 foo.1: foo$(EXEEXT)
12040 help2man --output=foo.1 ./foo$(EXEEXT)
12043 This will effectively distribute the man page. However,
12044 @samp{make distcheck} will fail with:
12047 ERROR: files left in build directory after distclean:
12051 Why was @file{foo.1} rebuilt? Because although distributed,
12052 @file{foo.1} depends on a non-distributed built file:
12053 @file{foo$(EXEEXT)}. @file{foo$(EXEEXT)} is built by the user, so it
12054 will always appear to be newer than the distributed @file{foo.1}.
12056 @samp{make distcheck} caught an inconsistency in our package. Our
12057 intent was to distribute @file{foo.1} so users do not need to install
12058 @command{help2man}, however since this rule causes this file to be
12059 always rebuilt, users @emph{do} need @command{help2man}. Either we
12060 should ensure that @file{foo.1} is not rebuilt by users, or there is
12061 no point in distributing @file{foo.1}.
12063 More generally, the rule is that distributed files should never depend
12064 on non-distributed built files. If you distribute something
12065 generated, distribute its sources.
12067 One way to fix the above example, while still distributing
12068 @file{foo.1} is to not depend on @file{foo$(EXEEXT)}. For instance,
12069 assuming @command{foo --version} and @command{foo --help} do not
12070 change unless @file{foo.c} or @file{configure.ac} change, we could
12071 write the following @file{Makefile.am}:
12075 foo_SOURCES = foo.c
12076 dist_man_MANS = foo.1
12078 foo.1: foo.c $(top_srcdir)/configure.ac
12079 $(MAKE) $(AM_MAKEFLAGS) foo$(EXEEXT)
12080 help2man --output=foo.1 ./foo$(EXEEXT)
12083 This way, @file{foo.1} will not get rebuilt every time
12084 @file{foo$(EXEEXT)} changes. The @command{make} call makes sure
12085 @file{foo$(EXEEXT)} is up-to-date before @command{help2man}. Another
12086 way to ensure this would be to use separate directories for binaries
12087 and man pages, and set @code{SUBDIRS} so that binaries are built
12090 We could also decide not to distribute @file{foo.1}. In
12091 this case it's fine to have @file{foo.1} dependent upon
12092 @file{foo$(EXEEXT)}, since both will have to be rebuilt.
12093 However it would be impossible to build the package in a
12094 cross-compilation, because building @file{foo.1} involves
12095 an @emph{execution} of @file{foo$(EXEEXT)}.
12097 Another context where such errors are common is when distributed files
12098 are built by tools that are built by the package. The pattern is
12102 distributed-file: built-tools distributed-sources
12107 should be changed to
12110 distributed-file: distributed-sources
12111 $(MAKE) $(AM_MAKEFLAGS) built-tools
12116 or you could choose not to distribute @file{distributed-file}, if
12117 cross-compilation does not matter.
12119 The points made through these examples are worth a summary:
12124 Distributed files should never depend upon non-distributed built
12127 Distributed files should be distributed with all their dependencies.
12129 If a file is @emph{intended} to be rebuilt by users, then there is no point
12130 in distributing it.
12134 @vrindex distcleancheck_listfiles
12135 For desperate cases, it's always possible to disable this check by
12136 setting @code{distcleancheck_listfiles} as documented in @ref{Checking
12138 Make sure you do understand the reason why @samp{make distcheck}
12139 complains before you do this. @code{distcleancheck_listfiles} is a
12140 way to @emph{hide} errors, not to fix them. You can always do better.
12142 @node Flag Variables Ordering
12143 @section Flag Variables Ordering
12144 @cindex Ordering flag variables
12145 @cindex Flag variables, ordering
12148 What is the difference between @code{AM_CFLAGS}, @code{CFLAGS}, and
12149 @code{mumble_CFLAGS}?
12153 Why does @command{automake} output @code{CPPFLAGS} after
12154 @code{AM_CPPFLAGS} on compile lines? Shouldn't it be the converse?
12158 My @file{configure} adds some warning flags into @code{CXXFLAGS}. In
12159 one @file{Makefile.am} I would like to append a new flag, however if I
12160 put the flag into @code{AM_CXXFLAGS} it is prepended to the other
12161 flags, not appended.
12164 @subheading Compile Flag Variables
12165 @cindex Flag Variables, Ordering
12166 @cindex Compile Flag Variables
12167 @cindex @code{AM_CCASFLAGS} and @code{CCASFLAGS}
12168 @cindex @code{AM_CFLAGS} and @code{CFLAGS}
12169 @cindex @code{AM_CPPFLAGS} and @code{CPPFLAGS}
12170 @cindex @code{AM_CXXFLAGS} and @code{CXXFLAGS}
12171 @cindex @code{AM_FCFLAGS} and @code{FCFLAGS}
12172 @cindex @code{AM_FFLAGS} and @code{FFLAGS}
12173 @cindex @code{AM_GCJFLAGS} and @code{GCJFLAGS}
12174 @cindex @code{AM_LDFLAGS} and @code{LDFLAGS}
12175 @cindex @code{AM_LFLAGS} and @code{LFLAGS}
12176 @cindex @code{AM_LIBTOOLFLAGS} and @code{LIBTOOLFLAGS}
12177 @cindex @code{AM_OBJCFLAGS} and @code{OBJCFLAGS}
12178 @cindex @code{AM_RFLAGS} and @code{RFLAGS}
12179 @cindex @code{AM_UPCFLAGS} and @code{UPCFLAGS}
12180 @cindex @code{AM_YFLAGS} and @code{YFLAGS}
12181 @cindex @code{CCASFLAGS} and @code{AM_CCASFLAGS}
12182 @cindex @code{CFLAGS} and @code{AM_CFLAGS}
12183 @cindex @code{CPPFLAGS} and @code{AM_CPPFLAGS}
12184 @cindex @code{CXXFLAGS} and @code{AM_CXXFLAGS}
12185 @cindex @code{FCFLAGS} and @code{AM_FCFLAGS}
12186 @cindex @code{FFLAGS} and @code{AM_FFLAGS}
12187 @cindex @code{GCJFLAGS} and @code{AM_GCJFLAGS}
12188 @cindex @code{LDFLAGS} and @code{AM_LDFLAGS}
12189 @cindex @code{LFLAGS} and @code{AM_LFLAGS}
12190 @cindex @code{LIBTOOLFLAGS} and @code{AM_LIBTOOLFLAGS}
12191 @cindex @code{OBJCFLAGS} and @code{AM_OBJCFLAGS}
12192 @cindex @code{RFLAGS} and @code{AM_RFLAGS}
12193 @cindex @code{UPCFLAGS} and @code{AM_UPCFLAGS}
12194 @cindex @code{YFLAGS} and @code{AM_YFLAGS}
12196 This section attempts to answer all the above questions. We will
12197 mostly discuss @code{CPPFLAGS} in our examples, but actually the
12198 answer holds for all the compile flags used in Automake:
12199 @code{CCASFLAGS}, @code{CFLAGS}, @code{CPPFLAGS}, @code{CXXFLAGS},
12200 @code{FCFLAGS}, @code{FFLAGS}, @code{GCJFLAGS}, @code{LDFLAGS},
12201 @code{LFLAGS}, @code{LIBTOOLFLAGS}, @code{OBJCFLAGS}, @code{RFLAGS},
12202 @code{UPCFLAGS}, and @code{YFLAGS}.
12204 @code{CPPFLAGS}, @code{AM_CPPFLAGS}, and @code{mumble_CPPFLAGS} are
12205 three variables that can be used to pass flags to the C preprocessor
12206 (actually these variables are also used for other languages like C++
12207 or preprocessed Fortran). @code{CPPFLAGS} is the user variable
12208 (@pxref{User Variables}), @code{AM_CPPFLAGS} is the Automake variable,
12209 and @code{mumble_CPPFLAGS} is the variable specific to the
12210 @code{mumble} target (we call this a per-target variable,
12211 @pxref{Program and Library Variables}).
12213 Automake always uses two of these variables when compiling C sources
12214 files. When compiling an object file for the @code{mumble} target,
12215 the first variable will be @code{mumble_CPPFLAGS} if it is defined, or
12216 @code{AM_CPPFLAGS} otherwise. The second variable is always
12219 In the following example,
12222 bin_PROGRAMS = foo bar
12223 foo_SOURCES = xyz.c
12224 bar_SOURCES = main.c
12225 foo_CPPFLAGS = -DFOO
12226 AM_CPPFLAGS = -DBAZ
12230 @file{xyz.o} will be compiled with @samp{$(foo_CPPFLAGS) $(CPPFLAGS)},
12231 (because @file{xyz.o} is part of the @code{foo} target), while
12232 @file{main.o} will be compiled with @samp{$(AM_CPPFLAGS) $(CPPFLAGS)}
12233 (because there is no per-target variable for target @code{bar}).
12235 The difference between @code{mumble_CPPFLAGS} and @code{AM_CPPFLAGS}
12236 being clear enough, let's focus on @code{CPPFLAGS}. @code{CPPFLAGS}
12237 is a user variable, i.e., a variable that users are entitled to modify
12238 in order to compile the package. This variable, like many others,
12239 is documented at the end of the output of @samp{configure --help}.
12241 For instance, someone who needs to add @file{/home/my/usr/include} to
12242 the C compiler's search path would configure a package with
12245 ./configure CPPFLAGS='-I /home/my/usr/include'
12249 and this flag would be propagated to the compile rules of all
12252 It is also not uncommon to override a user variable at
12253 @command{make}-time. Many installers do this with @code{prefix}, but
12254 this can be useful with compiler flags too. For instance, if, while
12255 debugging a C++ project, you need to disable optimization in one
12256 specific object file, you can run something like
12260 make CXXFLAGS=-O0 file.o
12264 The reason @samp{$(CPPFLAGS)} appears after @samp{$(AM_CPPFLAGS)} or
12265 @samp{$(mumble_CPPFLAGS)} in the compile command is that users
12266 should always have the last say. It probably makes more sense if you
12267 think about it while looking at the @samp{CXXFLAGS=-O0} above, which
12268 should supersede any other switch from @code{AM_CXXFLAGS} or
12269 @code{mumble_CXXFLAGS} (and this of course replaces the previous value
12270 of @code{CXXFLAGS}).
12272 You should never redefine a user variable such as @code{CPPFLAGS} in
12273 @file{Makefile.am}. Use @samp{automake -Woverride} to diagnose such
12274 mistakes. Even something like
12277 CPPFLAGS = -DDATADIR=\"$(datadir)\" @@CPPFLAGS@@
12281 is erroneous. Although this preserves @file{configure}'s value of
12282 @code{CPPFLAGS}, the definition of @code{DATADIR} will disappear if a
12283 user attempts to override @code{CPPFLAGS} from the @command{make}
12287 AM_CPPFLAGS = -DDATADIR=\"$(datadir)\"
12291 is all that is needed here if no per-target flags are used.
12293 You should not add options to these user variables within
12294 @file{configure} either, for the same reason. Occasionally you need
12295 to modify these variables to perform a test, but you should reset
12296 their values afterwards. In contrast, it is OK to modify the
12297 @samp{AM_} variables within @file{configure} if you @code{AC_SUBST}
12298 them, but it is rather rare that you need to do this, unless you
12299 really want to change the default definitions of the @samp{AM_}
12300 variables in all @file{Makefile}s.
12302 What we recommend is that you define extra flags in separate
12303 variables. For instance, you may write an Autoconf macro that computes
12304 a set of warning options for the C compiler, and @code{AC_SUBST} them
12305 in @code{WARNINGCFLAGS}; you may also have an Autoconf macro that
12306 determines which compiler and which linker flags should be used to
12307 link with library @file{libfoo}, and @code{AC_SUBST} these in
12308 @code{LIBFOOCFLAGS} and @code{LIBFOOLDFLAGS}. Then, a
12309 @file{Makefile.am} could use these variables as follows:
12312 AM_CFLAGS = $(WARNINGCFLAGS)
12313 bin_PROGRAMS = prog1 prog2
12314 prog1_SOURCES = @dots{}
12315 prog2_SOURCES = @dots{}
12316 prog2_CFLAGS = $(LIBFOOCFLAGS) $(AM_CFLAGS)
12317 prog2_LDFLAGS = $(LIBFOOLDFLAGS)
12320 In this example both programs will be compiled with the flags
12321 substituted into @samp{$(WARNINGCFLAGS)}, and @code{prog2} will
12322 additionally be compiled with the flags required to link with
12325 Note that listing @code{AM_CFLAGS} in a per-target @code{CFLAGS}
12326 variable is a common idiom to ensure that @code{AM_CFLAGS} applies to
12327 every target in a @file{Makefile.in}.
12329 Using variables like this gives you full control over the ordering of
12330 the flags. For instance, if there is a flag in $(WARNINGCFLAGS) that
12331 you want to negate for a particular target, you can use something like
12332 @samp{prog1_CFLAGS = $(AM_CFLAGS) -no-flag}. If all these flags had
12333 been forcefully appended to @code{CFLAGS}, there would be no way to
12334 disable one flag. Yet another reason to leave user variables to
12337 Finally, we have avoided naming the variable of the example
12338 @code{LIBFOO_LDFLAGS} (with an underscore) because that would cause
12339 Automake to think that this is actually a per-target variable (like
12340 @code{mumble_LDFLAGS}) for some non-declared @code{LIBFOO} target.
12342 @subheading Other Variables
12344 There are other variables in Automake that follow similar principles
12345 to allow user options. For instance, Texinfo rules (@pxref{Texinfo})
12346 use @code{MAKEINFOFLAGS} and @code{AM_MAKEINFOFLAGS}. Similarly,
12347 DejaGnu tests (@pxref{DejaGnu Tests}) use @code{RUNTESTDEFAULTFLAGS} and
12348 @code{AM_RUNTESTDEFAULTFLAGS}. The tags and ctags rules
12349 (@pxref{Tags}) use @code{ETAGSFLAGS}, @code{AM_ETAGSFLAGS},
12350 @code{CTAGSFLAGS}, and @code{AM_CTAGSFLAGS}. Java rules
12351 (@pxref{Java}) use @code{JAVACFLAGS} and @code{AM_JAVACFLAGS}. None
12352 of these rules support per-target flags (yet).
12354 To some extent, even @code{AM_MAKEFLAGS} (@pxref{Subdirectories})
12355 obeys this naming scheme. The slight difference is that
12356 @code{MAKEFLAGS} is passed to sub-@command{make}s implicitly by
12357 @command{make} itself.
12359 However you should not think that all variables ending with
12360 @code{FLAGS} follow this convention. For instance,
12361 @code{DISTCHECK_CONFIGURE_FLAGS} (@pxref{Checking the Distribution}) and
12362 @code{ACLOCAL_AMFLAGS} (see @ref{Rebuilding} and @ref{Local Macros}),
12363 are two variables that are only useful to the maintainer and have no
12366 @code{ARFLAGS} (@pxref{A Library}) is usually defined by Automake and
12367 has neither @code{AM_} nor per-target cousin.
12369 Finally you should not think that the existence of a per-target
12370 variable implies the existence of an @code{AM_} variable or of a user
12371 variable. For instance, the @code{mumble_LDADD} per-target variable
12372 overrides the makefile-wide @code{LDADD} variable (which is not a user
12373 variable), and @code{mumble_LIBADD} exists only as a per-target
12374 variable. @xref{Program and Library Variables}.
12377 @node Renamed Objects
12378 @section Why are object files sometimes renamed?
12380 This happens when per-target compilation flags are used. Object
12381 files need to be renamed just in case they would clash with object
12382 files compiled from the same sources, but with different flags.
12383 Consider the following example.
12386 bin_PROGRAMS = true false
12387 true_SOURCES = generic.c
12388 true_CPPFLAGS = -DEXIT_CODE=0
12389 false_SOURCES = generic.c
12390 false_CPPFLAGS = -DEXIT_CODE=1
12394 Obviously the two programs are built from the same source, but it
12395 would be bad if they shared the same object, because @file{generic.o}
12396 cannot be built with both @samp{-DEXIT_CODE=0} @emph{and}
12397 @samp{-DEXIT_CODE=1}. Therefore @command{automake} outputs rules to
12398 build two different objects: @file{true-generic.o} and
12399 @file{false-generic.o}.
12401 @command{automake} doesn't actually look whether source files are
12402 shared to decide if it must rename objects. It will just rename all
12403 objects of a target as soon as it sees per-target compilation flags
12406 It's OK to share object files when per-target compilation flags are not
12407 used. For instance, @file{true} and @file{false} will both use
12408 @file{version.o} in the following example.
12411 AM_CPPFLAGS = -DVERSION=1.0
12412 bin_PROGRAMS = true false
12413 true_SOURCES = true.c version.c
12414 false_SOURCES = false.c version.c
12417 Note that the renaming of objects is also affected by the
12418 @code{_SHORTNAME} variable (@pxref{Program and Library Variables}).
12421 @node Per-Object Flags
12422 @section Per-Object Flags Emulation
12423 @cindex Per-object flags, emulated
12426 One of my source files needs to be compiled with different flags. How
12430 Automake supports per-program and per-library compilation flags (see
12431 @ref{Program and Library Variables} and @ref{Flag Variables
12432 Ordering}). With this you can define compilation flags that apply to
12433 all files compiled for a target. For instance, in
12437 foo_SOURCES = foo.c foo.h bar.c bar.h main.c
12438 foo_CFLAGS = -some -flags
12442 @file{foo-foo.o}, @file{foo-bar.o}, and @file{foo-main.o} will all be
12443 compiled with @samp{-some -flags}. (If you wonder about the names of
12444 these object files, see @ref{Renamed Objects}.) Note that
12445 @code{foo_CFLAGS} gives the flags to use when compiling all the C
12446 sources of the @emph{program} @code{foo}, it has nothing to do with
12447 @file{foo.c} or @file{foo-foo.o} specifically.
12449 What if @file{foo.c} needs to be compiled into @file{foo.o} using some
12450 specific flags, that none of the other files requires? Obviously
12451 per-program flags are not directly applicable here. Something like
12452 per-object flags are expected, i.e., flags that would be used only
12453 when creating @file{foo-foo.o}. Automake does not support that,
12454 however this is easy to simulate using a library that contains only
12455 that object, and compiling this library with per-library flags.
12459 foo_SOURCES = bar.c bar.h main.c
12460 foo_CFLAGS = -some -flags
12461 foo_LDADD = libfoo.a
12462 noinst_LIBRARIES = libfoo.a
12463 libfoo_a_SOURCES = foo.c foo.h
12464 libfoo_a_CFLAGS = -some -other -flags
12467 Here @file{foo-bar.o} and @file{foo-main.o} will all be
12468 compiled with @samp{-some -flags}, while @file{libfoo_a-foo.o} will
12469 be compiled using @samp{-some -other -flags}. Eventually, all
12470 three objects will be linked to form @file{foo}.
12472 This trick can also be achieved using Libtool convenience libraries,
12473 for instance @samp{noinst_LTLIBRARIES = libfoo.la} (@pxref{Libtool
12474 Convenience Libraries}).
12476 Another tempting idea to implement per-object flags is to override the
12477 compile rules @command{automake} would output for these files.
12478 Automake will not define a rule for a target you have defined, so you
12479 could think about defining the @samp{foo-foo.o: foo.c} rule yourself.
12480 We recommend against this, because this is error prone. For instance,
12481 if you add such a rule to the first example, it will break the day you
12482 decide to remove @code{foo_CFLAGS} (because @file{foo.c} will then be
12483 compiled as @file{foo.o} instead of @file{foo-foo.o}, @pxref{Renamed
12484 Objects}). Also in order to support dependency tracking, the two
12485 @file{.o}/@file{.obj} extensions, and all the other flags variables
12486 involved in a compilation, you will end up modifying a copy of the
12487 rule previously output by @command{automake} for this file. If a new
12488 release of Automake generates a different rule, your copy will need to
12489 be updated by hand.
12491 @node Multiple Outputs
12492 @section Handling Tools that Produce Many Outputs
12493 @cindex multiple outputs, rules with
12494 @cindex many outputs, rules with
12495 @cindex rules with multiple outputs
12497 This section describes a @command{make} idiom that can be used when a
12498 tool produces multiple output files. It is not specific to Automake
12499 and can be used in ordinary @file{Makefile}s.
12501 Suppose we have a program called @command{foo} that will read one file
12502 called @file{data.foo} and produce two files named @file{data.c} and
12503 @file{data.h}. We want to write a @file{Makefile} rule that captures
12504 this one-to-two dependency.
12506 The naive rule is incorrect:
12509 # This is incorrect.
12510 data.c data.h: data.foo
12515 What the above rule really says is that @file{data.c} and
12516 @file{data.h} each depend on @file{data.foo}, and can each be built by
12517 running @samp{foo data.foo}. In other words it is equivalent to:
12520 # We do not want this.
12528 which means that @command{foo} can be run twice. Usually it will not
12529 be run twice, because @command{make} implementations are smart enough
12530 to check for the existence of the second file after the first one has
12531 been built; they will therefore detect that it already exists.
12532 However there are a few situations where it can run twice anyway:
12536 The most worrying case is when running a parallel @command{make}. If
12537 @file{data.c} and @file{data.h} are built in parallel, two @samp{foo
12538 data.foo} commands will run concurrently. This is harmful.
12540 Another case is when the dependency (here @file{data.foo}) is
12541 (or depends upon) a phony target.
12544 A solution that works with parallel @command{make} but not with
12545 phony dependencies is the following:
12548 data.c data.h: data.foo
12554 The above rules are equivalent to
12559 data.h: data.foo data.c
12564 therefore a parallel @command{make} will have to serialize the builds
12565 of @file{data.c} and @file{data.h}, and will detect that the second is
12566 no longer needed once the first is over.
12568 Using this pattern is probably enough for most cases. However it does
12569 not scale easily to more output files (in this scheme all output files
12570 must be totally ordered by the dependency relation), so we will
12571 explore a more complicated solution.
12573 Another idea is to write the following:
12576 # There is still a problem with this one.
12583 The idea is that @samp{foo data.foo} is run only when @file{data.c}
12584 needs to be updated, but we further state that @file{data.h} depends
12585 upon @file{data.c}. That way, if @file{data.h} is required and
12586 @file{data.foo} is out of date, the dependency on @file{data.c} will
12589 This is almost perfect, but suppose we have built @file{data.h} and
12590 @file{data.c}, and then we erase @file{data.h}. Then, running
12591 @samp{make data.h} will not rebuild @file{data.h}. The above rules
12592 just state that @file{data.c} must be up-to-date with respect to
12593 @file{data.foo}, and this is already the case.
12595 What we need is a rule that forces a rebuild when @file{data.h} is
12596 missing. Here it is:
12602 ## Recover from the removal of $@@
12603 @@if test -f $@@; then :; else \
12605 $(MAKE) $(AM_MAKEFLAGS) data.c; \
12609 The above scheme can be extended to handle more outputs and more
12610 inputs. One of the outputs is selected to serve as a witness to the
12611 successful completion of the command, it depends upon all inputs, and
12612 all other outputs depend upon it. For instance, if @command{foo}
12613 should additionally read @file{data.bar} and also produce
12614 @file{data.w} and @file{data.x}, we would write:
12617 data.c: data.foo data.bar
12618 foo data.foo data.bar
12619 data.h data.w data.x: data.c
12620 ## Recover from the removal of $@@
12621 @@if test -f $@@; then :; else \
12623 $(MAKE) $(AM_MAKEFLAGS) data.c; \
12627 However there are now three minor problems in this setup. One is related
12628 to the timestamp ordering of @file{data.h}, @file{data.w},
12629 @file{data.x}, and @file{data.c}. Another one is a race condition
12630 if a parallel @command{make} attempts to run multiple instances of the
12631 recover block at once. Finally, the recursive rule breaks @samp{make -n}
12632 when run with GNU @command{make} (as well as some other @command{make}
12633 implementations), as it may remove @file{data.h} even when it should not
12634 (@pxref{MAKE Variable, , How the @code{MAKE} Variable Works, make,
12635 The GNU Make Manual}).
12637 Let us deal with the first problem. @command{foo} outputs four files,
12638 but we do not know in which order these files are created. Suppose
12639 that @file{data.h} is created before @file{data.c}. Then we have a
12640 weird situation. The next time @command{make} is run, @file{data.h}
12641 will appear older than @file{data.c}, the second rule will be
12642 triggered, a shell will be started to execute the @samp{if@dots{}fi}
12643 command, but actually it will just execute the @code{then} branch,
12644 that is: nothing. In other words, because the witness we selected is
12645 not the first file created by @command{foo}, @command{make} will start
12646 a shell to do nothing each time it is run.
12648 A simple riposte is to fix the timestamps when this happens.
12651 data.c: data.foo data.bar
12652 foo data.foo data.bar
12653 data.h data.w data.x: data.c
12654 @@if test -f $@@; then \
12657 ## Recover from the removal of $@@
12659 $(MAKE) $(AM_MAKEFLAGS) data.c; \
12663 Another solution is to use a different and dedicated file as witness,
12664 rather than using any of @command{foo}'s outputs.
12667 data.stamp: data.foo data.bar
12670 foo data.foo data.bar
12671 @@mv -f data.tmp $@@
12672 data.c data.h data.w data.x: data.stamp
12673 ## Recover from the removal of $@@
12674 @@if test -f $@@; then :; else \
12675 rm -f data.stamp; \
12676 $(MAKE) $(AM_MAKEFLAGS) data.stamp; \
12680 @file{data.tmp} is created before @command{foo} is run, so it has a
12681 timestamp older than output files output by @command{foo}. It is then
12682 renamed to @file{data.stamp} after @command{foo} has run, because we
12683 do not want to update @file{data.stamp} if @command{foo} fails.
12685 This solution still suffers from the second problem: the race
12686 condition in the recover rule. If, after a successful build, a user
12687 erases @file{data.c} and @file{data.h}, and runs @samp{make -j}, then
12688 @command{make} may start both recover rules in parallel. If the two
12689 instances of the rule execute @samp{$(MAKE) $(AM_MAKEFLAGS)
12690 data.stamp} concurrently the build is likely to fail (for instance, the
12691 two rules will create @file{data.tmp}, but only one can rename it).
12693 Admittedly, such a weird situation does not arise during ordinary
12694 builds. It occurs only when the build tree is mutilated. Here
12695 @file{data.c} and @file{data.h} have been explicitly removed without
12696 also removing @file{data.stamp} and the other output files.
12697 @code{make clean; make} will always recover from these situations even
12698 with parallel makes, so you may decide that the recover rule is solely
12699 to help non-parallel make users and leave things as-is. Fixing this
12700 requires some locking mechanism to ensure only one instance of the
12701 recover rule rebuilds @file{data.stamp}. One could imagine something
12702 along the following lines.
12705 data.c data.h data.w data.x: data.stamp
12706 ## Recover from the removal of $@@
12707 @@if test -f $@@; then :; else \
12708 trap 'rm -rf data.lock data.stamp' 1 2 13 15; \
12709 ## mkdir is a portable test-and-set
12710 if mkdir data.lock 2>/dev/null; then \
12711 ## This code is being executed by the first process.
12712 rm -f data.stamp; \
12713 $(MAKE) $(AM_MAKEFLAGS) data.stamp; \
12714 result=$$?; rm -rf data.lock; exit $$result; \
12716 ## This code is being executed by the follower processes.
12717 ## Wait until the first process is done.
12718 while test -d data.lock; do sleep 1; done; \
12719 ## Succeed if and only if the first process succeeded.
12720 test -f data.stamp; \
12725 Using a dedicated witness, like @file{data.stamp}, is very handy when
12726 the list of output files is not known beforehand. As an illustration,
12727 consider the following rules to compile many @file{*.el} files into
12728 @file{*.elc} files in a single command. It does not matter how
12729 @code{ELFILES} is defined (as long as it is not empty: empty targets
12730 are not accepted by POSIX).
12733 ELFILES = one.el two.el three.el @dots{}
12734 ELCFILES = $(ELFILES:=c)
12736 elc-stamp: $(ELFILES)
12739 $(elisp_comp) $(ELFILES)
12740 @@mv -f elc-temp $@@
12742 $(ELCFILES): elc-stamp
12743 @@if test -f $@@; then :; else \
12744 ## Recover from the removal of $@@
12745 trap 'rm -rf elc-lock elc-stamp' 1 2 13 15; \
12746 if mkdir elc-lock 2>/dev/null; then \
12747 ## This code is being executed by the first process.
12749 $(MAKE) $(AM_MAKEFLAGS) elc-stamp; \
12752 ## This code is being executed by the follower processes.
12753 ## Wait until the first process is done.
12754 while test -d elc-lock; do sleep 1; done; \
12755 ## Succeed if and only if the first process succeeded.
12756 test -f elc-stamp; exit $$?; \
12762 These solutions all still suffer from the third problem, namely that
12763 they break the promise that @samp{make -n} should not cause any actual
12764 changes to the tree. For those solutions that do not create lock files,
12765 it is possible to split the recover rules into two separate recipe
12766 commands, one of which does all work but the recursion, and the
12767 other invokes the recursive @samp{$(MAKE)}. The solutions involving
12768 locking could act upon the contents of the @samp{MAKEFLAGS} variable,
12769 but parsing that portably is not easy (@pxref{The Make Macro MAKEFLAGS,,,
12770 autoconf, The Autoconf Manual}). Here is an example:
12773 ELFILES = one.el two.el three.el @dots{}
12774 ELCFILES = $(ELFILES:=c)
12776 elc-stamp: $(ELFILES)
12779 $(elisp_comp) $(ELFILES)
12780 @@mv -f elc-temp $@@
12782 $(ELCFILES): elc-stamp
12783 ## Recover from the removal of $@@
12784 @@dry=; for f in x $$MAKEFLAGS; do \
12790 if test -f $@@; then :; else \
12791 $$dry trap 'rm -rf elc-lock elc-stamp' 1 2 13 15; \
12792 if $$dry mkdir elc-lock 2>/dev/null; then \
12793 ## This code is being executed by the first process.
12794 $$dry rm -f elc-stamp; \
12795 $(MAKE) $(AM_MAKEFLAGS) elc-stamp; \
12796 $$dry rmdir elc-lock; \
12798 ## This code is being executed by the follower processes.
12799 ## Wait until the first process is done.
12800 while test -d elc-lock && test -z "$$dry"; do \
12804 ## Succeed if and only if the first process succeeded.
12805 $$dry test -f elc-stamp; exit $$?; \
12810 For completeness it should be noted that GNU @command{make} is able to
12811 express rules with multiple output files using pattern rules
12812 (@pxref{Pattern Examples, , Pattern Rule Examples, make, The GNU Make
12813 Manual}). We do not discuss pattern rules here because they are not
12814 portable, but they can be convenient in packages that assume GNU
12818 @node Hard-Coded Install Paths
12819 @section Installing to Hard-Coded Locations
12822 My package needs to install some configuration file. I tried to use
12823 the following rule, but @samp{make distcheck} fails. Why?
12827 install-data-local:
12828 $(INSTALL_DATA) $(srcdir)/afile $(DESTDIR)/etc/afile
12833 My package needs to populate the installation directory of another
12834 package at install-time. I can easily compute that installation
12835 directory in @file{configure}, but if I install files therein,
12836 @samp{make distcheck} fails. How else should I do?
12839 These two setups share their symptoms: @samp{make distcheck} fails
12840 because they are installing files to hard-coded paths. In the later
12841 case the path is not really hard-coded in the package, but we can
12842 consider it to be hard-coded in the system (or in whichever tool that
12843 supplies the path). As long as the path does not use any of the
12844 standard directory variables (@samp{$(prefix)}, @samp{$(bindir)},
12845 @samp{$(datadir)}, etc.), the effect will be the same:
12846 user-installations are impossible.
12848 As a (non-root) user who wants to install a package, you usually have no
12849 right to install anything in @file{/usr} or @file{/usr/local}. So you
12850 do something like @samp{./configure --prefix ~/usr} to install a
12851 package in your own @file{~/usr} tree.
12853 If a package attempts to install something to some hard-coded path
12854 (e.g., @file{/etc/afile}), regardless of this @option{--prefix} setting,
12855 then the installation will fail. @samp{make distcheck} performs such
12856 a @option{--prefix} installation, hence it will fail too.
12858 Now, there are some easy solutions.
12860 The above @code{install-data-local} example for installing
12861 @file{/etc/afile} would be better replaced by
12864 sysconf_DATA = afile
12868 by default @code{sysconfdir} will be @samp{$(prefix)/etc}, because
12869 this is what the GNU Standards require. When such a package is
12870 installed on an FHS compliant system, the installer will have to set
12871 @samp{--sysconfdir=/etc}. As the maintainer of the package you
12872 should not be concerned by such site policies: use the appropriate
12873 standard directory variable to install your files so that the installer
12874 can easily redefine these variables to match their site conventions.
12876 Installing files that should be used by another package is slightly
12877 more involved. Let's take an example and assume you want to install
12878 a shared library that is a Python extension module. If you ask Python
12879 where to install the library, it will answer something like this:
12882 % @kbd{python -c 'from distutils import sysconfig;
12883 print sysconfig.get_python_lib(1,0)'}
12884 /usr/lib/python2.5/site-packages
12887 If you indeed use this absolute path to install your shared library,
12888 non-root users will not be able to install the package, hence
12891 Let's do better. The @samp{sysconfig.get_python_lib()} function
12892 actually accepts a third argument that will replace Python's
12893 installation prefix.
12896 % @kbd{python -c 'from distutils import sysconfig;
12897 print sysconfig.get_python_lib(1,0,"$@{exec_prefix@}")'}
12898 $@{exec_prefix@}/lib/python2.5/site-packages
12901 You can also use this new path. If you do
12904 root users can install your package with the same @option{--prefix}
12905 as Python (you get the behavior of the previous attempt)
12908 non-root users can install your package too, they will have the
12909 extension module in a place that is not searched by Python but they
12910 can work around this using environment variables (and if you installed
12911 scripts that use this shared library, it's easy to tell Python were to
12912 look in the beginning of your script, so the script works in both
12916 The @code{AM_PATH_PYTHON} macro uses similar commands to define
12917 @samp{$(pythondir)} and @samp{$(pyexecdir)} (@pxref{Python}).
12919 Of course not all tools are as advanced as Python regarding that
12920 substitution of @var{prefix}. So another strategy is to figure the
12921 part of the installation directory that must be preserved. For
12922 instance, here is how @code{AM_PATH_LISPDIR} (@pxref{Emacs Lisp})
12923 computes @samp{$(lispdir)}:
12926 $EMACS -batch -q -eval '(while load-path
12927 (princ (concat (car load-path) "\n"))
12928 (setq load-path (cdr load-path)))' >conftest.out
12931 -e '/.*\/lib\/x*emacs\/site-lisp$/@{
12932 s,.*/lib/\(x*emacs/site-lisp\)$,$@{libdir@}/\1,;p;q;
12934 -e '/.*\/share\/x*emacs\/site-lisp$/@{
12935 s,.*/share/\(x*emacs/site-lisp\),$@{datarootdir@}/\1,;p;q;
12940 I.e., it just picks the first directory that looks like
12941 @file{*/lib/*emacs/site-lisp} or @file{*/share/*emacs/site-lisp} in
12942 the search path of emacs, and then substitutes @samp{$@{libdir@}} or
12943 @samp{$@{datadir@}} appropriately.
12945 The emacs case looks complicated because it processes a list and
12946 expects two possible layouts, otherwise it's easy, and the benefits for
12947 non-root users are really worth the extra @command{sed} invocation.
12950 @node Debugging Make Rules
12951 @section Debugging Make Rules
12952 @cindex debugging rules
12953 @cindex rules, debugging
12955 The rules and dependency trees generated by @command{automake} can get
12956 rather complex, and leave the developer head-scratching when things
12957 don't work as expected. Besides the debug options provided by the
12958 @command{make} command (@pxref{Options Summary,,, make, The GNU Make
12959 Manual}), here's a couple of further hints for debugging makefiles
12960 generated by @command{automake} effectively:
12964 If less verbose output has been enabled in the package with the
12965 @samp{silent-rules} option (@pxref{Options}), you can use
12966 @code{make V=1} to see the commands being executed.
12968 @code{make -n} can help show what would be done without actually doing
12969 it. Note however, that this will @emph{still execute} commands prefixed
12970 with @samp{+}, and, when using GNU @command{make}, commands that contain
12971 the strings @samp{$(MAKE)} or @samp{$@{MAKE@}} (@pxref{Instead of
12972 Execution,,, make, The GNU Make Manual}).
12973 Typically, this is helpful to show what recursive rules would do, but it
12974 means that, in your own rules, you should not mix such recursion with
12975 actions that change any files.@footnote{Automake's @samp{dist} and
12976 @samp{distcheck} rules had a bug in this regard in that they created
12977 directories even with @option{-n}, but this has been fixed in Automake
12978 1.11.} Furthermore, note that GNU @command{make} will update
12979 prerequisites for the @file{Makefile} file itself even with @option{-n}
12980 (@pxref{Remaking Makefiles,,, make, The GNU Make Manual}).
12982 @code{make SHELL="/bin/bash -vx"} can help debug complex rules.
12983 @xref{The Make Macro SHELL,,, autoconf, The Autoconf Manual}, for some
12984 portability quirks associated with this construct.
12986 @code{echo 'print: ; @@echo "$(VAR)"' | make -f Makefile -f - print}
12987 can be handy to examine the expanded value of variables. You may need
12988 to use a target other than @samp{print} if that is already used or a
12989 file with that name exists.
12991 @url{http://bashdb.sourceforge.net/@/remake/} provides a modified
12992 GNU @command{make} command called @command{remake} that copes with
12993 complex GNU @command{make}-specific Makefiles and allows to trace
12994 execution, examine variables, and call rules interactively, much like
12999 @node Reporting Bugs
13000 @section Reporting Bugs
13002 Most nontrivial software has bugs. Automake is no exception. Although
13003 we cannot promise we can or will fix a bug, and we might not even agree
13004 that it is a bug, we want to hear about problems you encounter. Often we
13005 agree they are bugs and want to fix them.
13007 To make it possible for us to fix a bug, please report it. In order to
13008 do so effectively, it helps to know when and how to do it.
13010 Before reporting a bug, it is a good idea to see if it is already known.
13011 You can look at the @uref{http://debbugs.gnu.org/, GNU Bug Tracker}
13012 and the @uref{http://lists.gnu.org/@/archive/@/html/@/bug-automake/,
13013 bug-automake mailing list archives} for previous bug reports. We
13015 @uref{http://sourceware.org/@/cgi-bin/@/gnatsweb.pl?database=automake,
13016 Gnats database} for bug tracking, so some bugs might have been reported
13017 there already. Please do not use it for new bug reports, however.
13019 If the bug is not already known, it should be reported. It is very
13020 important to report bugs in a way that is useful and efficient. For
13021 this, please familiarize yourself with
13022 @uref{http://www.chiark.greenend.org.uk/@/~sgtatham/@/bugs.html, How to
13023 Report Bugs Effectively} and
13024 @uref{http://catb.org/@/~esr/@/faqs/@/smart-questions.html, How to Ask
13025 Questions the Smart Way}. This helps you and developers to save time
13026 which can then be spent on fixing more bugs and implementing more
13029 For a bug report, a feature request or other suggestions, please send
13030 email to @email{@value{PACKAGE_BUGREPORT}}. This will then open a new
13031 bug in the @uref{http://debbugs.gnu.org/@/automake, bug tracker}. Be
13032 sure to include the versions of Autoconf and Automake that you use.
13033 Ideally, post a minimal @file{Makefile.am} and @file{configure.ac} that
13034 reproduces the problem you encounter. If you have encountered test
13035 suite failures, please attach the @file{tests/test-suite.log} file.
13037 @c ========================================================== Appendices
13040 @node Copying This Manual
13041 @appendix Copying This Manual
13044 * GNU Free Documentation License:: License for copying this manual
13047 @node GNU Free Documentation License
13048 @appendixsec GNU Free Documentation License
13056 * Macro Index:: Index of Autoconf macros
13057 * Variable Index:: Index of Makefile variables
13058 * General Index:: General index
13062 @appendixsec Macro Index
13066 @node Variable Index
13067 @appendixsec Variable Index
13071 @node General Index
13072 @appendixsec General Index
13079 @c LocalWords: texinfo setfilename settitle setchapternewpage texi direntry
13080 @c LocalWords: dircategory in's aclocal ifinfo titlepage Tromey vskip pt sp
13081 @c LocalWords: filll defcodeindex ov cv op tr syncodeindex fn cp vr ifnottex
13082 @c LocalWords: dir Automake's ac Dist Gnits gnits cygnus dfn Autoconf's pxref
13083 @c LocalWords: cindex Autoconf autoconf perl samp cvs dist trindex SUBST foo
13084 @c LocalWords: xs emph FIXME ref vindex pkglibdir pkgincludedir pkgdatadir mt
13085 @c LocalWords: pkg libdir cpio bindir sbindir rmt pax sbin zar zardir acindex
13086 @c LocalWords: HTML htmldir html noinst TEXINFOS nodist nobase strudel CFLAGS
13087 @c LocalWords: libmumble CC YFLAGS itemx de fication config url comp
13088 @c LocalWords: depcomp elisp sh mdate mkinstalldirs mkdir py tex dvi ps pdf
13089 @c LocalWords: ylwrap zardoz INIT gettext acinclude mv FUNCS LIBOBJS LDADD fr
13090 @c LocalWords: uref featureful dnl src LINGUAS es ko nl pl sl sv PROG ISC doc
13091 @c LocalWords: POSIX STDC fcntl FUNC ALLOCA blksize struct stat intl po chmod
13092 @c LocalWords: ChangeLog SUBDIRS gettextize gpl testdata getopt INTLLIBS cpp
13093 @c LocalWords: localedir datadir DLOCALEDIR DEXIT CPPFLAGS autoreconf opindex
13094 @c LocalWords: AUX var symlink deps Wno Wnone package's aclocal's distclean
13095 @c LocalWords: ltmain xref LIBSOURCE LIBSOURCES LIBOBJ MEMCMP vs RANLIB CXX
13096 @c LocalWords: LDFLAGS LIBTOOL libtool XTRA LIBS gettext's acdir APIVERSION
13097 @c LocalWords: dirlist noindent usr TIOCGWINSZ sc
13098 @c LocalWords: GWINSZ termios SRCDIR tarball bzip LISPDIR lispdir XEmacs CCAS
13099 @c LocalWords: emacsen MicroEmacs CCASFLAGS UX GCJ gcj GCJFLAGS posix DMALLOC
13100 @c LocalWords: dmalloc ldmalloc REGEX regex DEPDIR DEP DEFUN aclocaldir fi
13101 @c LocalWords: mymacro myothermacro AMFLAGS autopoint autogen libtoolize yum
13102 @c LocalWords: autoheader README MAKEFLAGS subdir Inetutils sync COND endif
13103 @c LocalWords: Miller's installable includedir inc pkgdata EXEEXT libexec bsd
13104 @c LocalWords: pkglib libexecdir prog libcpio cpio's dlopen dlpreopen linux
13105 @c LocalWords: subsubsection OBJEXT esac lib LTLIBRARIES liblob LIBADD AR ar
13106 @c LocalWords: ARFLAGS cru ing maude libgettext lo LTLIBOBJS rpath SGI PRE yy
13107 @c LocalWords: libmaude CCLD CXXFLAGS FFLAGS LFLAGS OBJCFLAGS RFLAGS DEFS cc
13108 @c LocalWords: SHORTNAME vtable srcdir nostdinc basename yxx cxx ll lxx gdb
13109 @c LocalWords: lexers yymaxdepth maxdepth yyparse yylex yyerror yylval lval
13110 @c LocalWords: yychar yydebug yypact yyr yydef def yychk chk yypgo pgo yyact
13111 @c LocalWords: yyexca exca yyerrflag errflag yynerrs nerrs yyps yypv pv yys
13112 @c LocalWords: yystate yytmp tmp yyv yyval val yylloc lloc yyreds yytoks toks
13113 @c LocalWords: yylhs yylen yydefred yydgoto yysindex yyrindex yygindex yyname
13114 @c LocalWords: yytable yycheck yyrule byacc CXXCOMPILE CXXLINK FLINK cfortran
13115 @c LocalWords: Catalogue preprocessable FLIBS libfoo baz JAVACFLAGS java exe
13116 @c LocalWords: SunOS fying basenames exeext uninstalled oldinclude kr FSF's
13117 @c LocalWords: pkginclude oldincludedir sysconf sharedstate localstate gcc rm
13118 @c LocalWords: sysconfdir sharedstatedir localstatedir preexist CLEANFILES gz
13119 @c LocalWords: depfile tmpdepfile depmode const interoperate
13120 @c LocalWords: JAVAC javac JAVAROOT builddir CLASSPATH ENV pyc pyo pkgpython
13121 @c LocalWords: pyexecdir pkgpyexecdir Python's pythondir pkgpythondir txi ois
13122 @c LocalWords: installinfo vers MAKEINFO makeinfo MAKEINFOFLAGS noinstall rf
13123 @c LocalWords: mandir thesame alsothesame installman myexecbin DESTDIR Pinard
13124 @c LocalWords: uninstall installdirs uninstalls MOSTLYCLEANFILES mostlyclean
13125 @c LocalWords: DISTCLEANFILES MAINTAINERCLEANFILES GZIP gzip shar exp
13126 @c LocalWords: distdir distcheck distcleancheck listfiles distuninstallcheck
13127 @c LocalWords: VPATH tarfile stdout XFAIL DejaGnu dejagnu DEJATOOL runtest ln
13128 @c LocalWords: RUNTESTDEFAULTFLAGS toolchain RUNTESTFLAGS asis readme DVIPS
13129 @c LocalWords: installcheck gzipped tarZ std utils etags mkid cd
13130 @c LocalWords: ARGS taggable ETAGSFLAGS lang ctags CTAGSFLAGS GTAGS gtags idl
13131 @c LocalWords: foocc doit idlC multilibs ABIs cmindex defmac ARG enableval FC
13132 @c LocalWords: MSG xtrue DBG pathchk CYGWIN afile proglink versioned CVS's TE
13133 @c LocalWords: wildcards Autoconfiscated subsubheading autotools Meyering API
13134 @c LocalWords: ois's wildcard Wportability cartouche vrindex printindex Duret
13135 @c LocalWords: DSOMEFLAG DVERSION automake Lutz insertcopying versioning FAQ
13136 @c LocalWords: LTLIBOBJ Libtool's libtool's libltdl dlopening itutions libbar
13137 @c LocalWords: WANTEDLIBS libhello sublibraries libtop libsub dlopened Ratfor
13138 @c LocalWords: mymodule timestamps timestamp underquoted MAKEINFOHTMLFLAGS te
13139 @c LocalWords: GNUmakefile Subpackages subpackage's subpackages aux
13140 @c LocalWords: detailmenu Timeline pwd reldir AUTOM autom PREREQ FOOBAR libc
13141 @c LocalWords: libhand subpackage moduleN libmain libmisc FCFLAGS FCCOMPILE
13142 @c LocalWords: FCLINK subst sed ELCFILES elc MAKEINFOHTML dvips esyscmd ustar
13143 @c LocalWords: tarballs Woverride vfi ELFILES djm AutoMake honkin FSF
13144 @c LocalWords: fileutils precanned MacKenzie's reimplement termutils Tromey's
13145 @c LocalWords: cois gnitsians LIBPROGRAMS progs LIBLIBRARIES Textutils Ulrich
13146 @c LocalWords: Matzigkeit Drepper's Gord Matzigkeit's jm Dalley Debian org
13147 @c LocalWords: Administrivia ILU CORBA Sourceware Molenda sourceware Elliston
13148 @c LocalWords: dep Oliva Akim Demaille Aiieeee Demaillator Akim's sourcequake
13149 @c LocalWords: grep backported screenshots libgcj KB unnumberedsubsubsec pre
13150 @c LocalWords: precomputing hacky makedepend inline clearmake LD PRELOAD Rel
13151 @c LocalWords: syscalls perlhist acl pm multitable headitem fdl appendixsec
13152 @c LocalWords: LTALLOCA MALLOC malloc memcmp strdup alloca libcompat xyz DFOO
13153 @c LocalWords: unprefixed buildable preprocessed DBAZ DDATADIR WARNINGCFLAGS
13154 @c LocalWords: LIBFOOCFLAGS LIBFOOLDFLAGS ftable testSubDir obj LIBTOOLFLAGS
13155 @c LocalWords: barexec Pinard's automatize initialize lzip lzma xz cscope