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-2012 Free Software Foundation, Inc.
29 Permission is granted to copy, distribute and/or modify this document
30 under the terms of the GNU Free Documentation License,
31 Version 1.3 or any later version published by the Free Software
32 Foundation; with no Invariant Sections, with no Front-Cover texts,
33 and with no Back-Cover Texts. A copy of the license is included in the
34 section entitled ``GNU Free Documentation License.''
39 @dircategory Software development
41 * Automake: (automake). Making GNU standards-compliant Makefiles.
44 @dircategory Individual utilities
46 * aclocal-invocation: (automake)aclocal Invocation. Generating aclocal.m4.
47 * automake-invocation: (automake)automake Invocation. Generating Makefile.in.
52 @subtitle For version @value{VERSION}, @value{UPDATED}
53 @author David MacKenzie
55 @author Alexandre Duret-Lutz
57 @vskip 0pt plus 1filll
63 @c We use the following macros to define indices:
64 @c @cindex concepts, and anything that does not fit elsewhere
65 @c @vindex Makefile variables
67 @c @acindex Autoconf/Automake/Libtool/M4/... macros
68 @c @opindex tool options
70 @c Define an index of configure macros.
72 @c Define an index of options.
74 @c Define an index of targets.
76 @c Define an index of commands.
79 @c Put the macros in the function index.
82 @c Put everything else into one index (arbitrarily chosen to be the
90 @comment node-name, next, previous, up
96 * Introduction:: Automake's purpose
97 * Autotools Introduction:: An Introduction to the Autotools
98 * Generalities:: General ideas
99 * Examples:: Some example packages
100 * automake Invocation:: Creating a Makefile.in
101 * configure:: Scanning configure.ac, using aclocal
102 * Directories:: Declaring subdirectories
103 * Programs:: Building programs and libraries
104 * Other Objects:: Other derived objects
105 * Other GNU Tools:: Other GNU Tools
106 * Documentation:: Building documentation
107 * Install:: What gets installed
108 * Clean:: What gets cleaned
109 * Dist:: What goes in a distribution
110 * Tests:: Support for test suites
111 * Rebuilding:: Automatic rebuilding of Makefile
112 * Options:: Changing Automake's behavior
113 * Miscellaneous:: Miscellaneous rules
114 * Include:: Including extra files in an Automake template
115 * Conditionals:: Conditionals
116 * Silencing Make:: Obtain less verbose output from @command{make}
117 * Gnits:: The effect of @option{--gnu} and @option{--gnits}
118 * Not Enough:: When Automake is not Enough
119 * Distributing:: Distributing the Makefile.in
120 * API Versioning:: About compatibility between Automake versions
121 * Upgrading:: Upgrading to a Newer Automake Version
122 * FAQ:: Frequently Asked Questions
123 * Copying This Manual:: How to make copies of this manual
124 * Indices:: Indices of variables, macros, and concepts
127 --- The Detailed Node Listing ---
129 An Introduction to the Autotools
131 * GNU Build System:: Introducing the GNU Build System
132 * Use Cases:: Use Cases for the GNU Build System
133 * Why Autotools:: How Autotools Help
134 * Hello World:: A Small Hello World Package
136 Use Cases for the GNU Build System
138 * Basic Installation:: Common installation procedure
139 * Standard Targets:: A list of standard Makefile targets
140 * Standard Directory Variables:: A list of standard directory variables
141 * Standard Configuration Variables:: Using configuration variables
142 * config.site:: Using a config.site file
143 * VPATH Builds:: Parallel build trees
144 * Two-Part Install:: Installing data and programs separately
145 * Cross-Compilation:: Building for other architectures
146 * Renaming:: Renaming programs at install time
147 * DESTDIR:: Building binary packages with DESTDIR
148 * Preparing Distributions:: Rolling out tarballs
149 * Dependency Tracking:: Automatic dependency tracking
150 * Nested Packages:: The GNU Build Systems can be nested
154 * Creating amhello:: Create @file{amhello-1.0.tar.gz} from scratch
155 * amhello's configure.ac Setup Explained::
156 * amhello's Makefile.am Setup Explained::
160 * General Operation:: General operation of Automake
161 * Strictness:: Standards conformance checking
162 * Uniform:: The Uniform Naming Scheme
163 * Length Limitations:: Staying below the command line length limit
164 * Canonicalization:: How derived variables are named
165 * User Variables:: Variables reserved for the user
166 * Auxiliary Programs:: Programs automake might require
168 Some example packages
170 * Complete:: A simple example, start to finish
171 * true:: Building true and false
173 Scanning @file{configure.ac}, using @command{aclocal}
175 * Requirements:: Configuration requirements
176 * Optional:: Other things Automake recognizes
177 * aclocal Invocation:: Auto-generating aclocal.m4
178 * Macros:: Autoconf macros supplied with Automake
180 Auto-generating aclocal.m4
182 * aclocal Options:: Options supported by aclocal
183 * Macro Search Path:: How aclocal finds .m4 files
184 * Extending aclocal:: Writing your own aclocal macros
185 * Local Macros:: Organizing local macros
186 * Serials:: Serial lines in Autoconf macros
187 * Future of aclocal:: aclocal's scheduled death
189 Autoconf macros supplied with Automake
191 * Public Macros:: Macros that you can use.
192 * Private Macros:: Macros that you should not use.
196 * Subdirectories:: Building subdirectories recursively
197 * Conditional Subdirectories:: Conditionally not building directories
198 * Alternative:: Subdirectories without recursion
199 * Subpackages:: Nesting packages
201 Conditional Subdirectories
203 * SUBDIRS vs DIST_SUBDIRS:: Two sets of directories
204 * Subdirectories with AM_CONDITIONAL:: Specifying conditional subdirectories
205 * Subdirectories with AC_SUBST:: Another way for conditional recursion
206 * Unconfigured Subdirectories:: Not even creating a @samp{Makefile}
208 Building Programs and Libraries
210 * A Program:: Building a program
211 * A Library:: Building a library
212 * A Shared Library:: Building a Libtool library
213 * Program and Library Variables:: Variables controlling program and
215 * Default _SOURCES:: Default source files
216 * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
217 * Program Variables:: Variables used when building a program
218 * Yacc and Lex:: Yacc and Lex support
219 * C++ Support:: Compiling C++ sources
220 * Objective C Support:: Compiling Objective C sources
221 * Unified Parallel C Support:: Compiling Unified Parallel C sources
222 * Assembly Support:: Compiling assembly sources
223 * Fortran 77 Support:: Compiling Fortran 77 sources
224 * Fortran 9x Support:: Compiling Fortran 9x sources
225 * Java Support with gcj:: Compiling Java sources using gcj
226 * Vala Support:: Compiling Vala sources
227 * Support for Other Languages:: Compiling other languages
228 * Dependencies:: Automatic dependency tracking
229 * EXEEXT:: Support for executable extensions
233 * Program Sources:: Defining program sources
234 * Linking:: Linking with libraries or extra objects
235 * Conditional Sources:: Handling conditional sources
236 * Conditional Programs:: Building a program conditionally
238 Building a Shared Library
240 * Libtool Concept:: Introducing Libtool
241 * Libtool Libraries:: Declaring Libtool Libraries
242 * Conditional Libtool Libraries:: Building Libtool Libraries Conditionally
243 * Conditional Libtool Sources:: Choosing Library Sources Conditionally
244 * Libtool Convenience Libraries:: Building Convenience Libtool Libraries
245 * Libtool Modules:: Building Libtool Modules
246 * Libtool Flags:: Using _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS
247 * LTLIBOBJS:: Using $(LTLIBOBJS) and $(LTALLOCA)
248 * Libtool Issues:: Common Issues Related to Libtool's Use
250 Common Issues Related to Libtool's Use
252 * Error required file ltmain.sh not found:: The need to run libtoolize
253 * Objects created both with libtool and without:: Avoid a specific build race
257 * Preprocessing Fortran 77:: Preprocessing Fortran 77 sources
258 * Compiling Fortran 77 Files:: Compiling Fortran 77 sources
259 * Mixing Fortran 77 With C and C++:: Mixing Fortran 77 With C and C++
261 Mixing Fortran 77 With C and C++
263 * How the Linker is Chosen:: Automatic linker selection
267 * Compiling Fortran 9x Files:: Compiling Fortran 9x sources
269 Other Derived Objects
271 * Scripts:: Executable scripts
272 * Headers:: Header files
273 * Data:: Architecture-independent data files
274 * Sources:: Derived sources
278 * Built Sources Example:: Several ways to handle built sources.
282 * Emacs Lisp:: Emacs Lisp
285 * Java:: Java bytecode compilation (deprecated)
288 Building documentation
291 * Man Pages:: Man pages
295 * Basics of Installation:: What gets installed where
296 * The Two Parts of Install:: Installing data and programs separately
297 * Extending Installation:: Adding your own rules for installation
298 * Staged Installs:: Installation in a temporary location
299 * Install Rules for the User:: Useful additional rules
301 What Goes in a Distribution
303 * Basics of Distribution:: Files distributed by default
304 * Fine-grained Distribution Control:: @code{dist_} and @code{nodist_} prefixes
305 * The dist Hook:: A target for last-minute distribution changes
306 * Checking the Distribution:: @samp{make distcheck} explained
307 * The Types of Distributions:: A variety of formats and compression methods
309 Support for test suites
311 * Generalities about Testing:: Generic concepts and terminology about testing
312 * Simple Tests:: Listing test scripts in @code{TESTS}
313 * Custom Test Drivers:: Writing and using custom test drivers
314 * Using the TAP test protocol:: Integrating test scripts that use the TAP protocol
315 * DejaGnu Tests:: Interfacing with the @command{dejagnu} testing framework
316 * Install Tests:: Running tests on installed packages
320 * Scripts-based Testsuites:: Automake-specific concepts and terminology
321 * Serial Test Harness:: Older (and obsolescent) serial test harness
322 * Parallel Test Harness:: Generic concurrent test harness
324 Using the TAP test protocol
326 * Introduction to TAP::
327 * Use TAP with the Automake test harness::
328 * Incompatibilities with other TAP parsers and drivers::
329 * Links and external resources on TAP::
333 * Overview of Custom Test Drivers Support::
334 * Declaring Custom Test Drivers::
335 * API for Custom Test Drivers::
337 API for Custom Test Drivers
339 * Command-line arguments for test drivers::
340 * Log files generation and test results recording::
341 * Testsuite progress output::
343 Changing Automake's Behavior
345 * Options generalities:: Semantics of Automake option
346 * List of Automake options:: A comprehensive list of Automake options
350 * Tags:: Interfacing to cscope, etags and mkid
351 * Suffixes:: Handling new file extensions
355 * Usage of Conditionals:: Declaring conditional content
356 * Limits of Conditionals:: Enclosing complete statements
360 * Make verbosity:: Make is verbose by default
361 * Tricks For Silencing Make:: Standard and generic ways to silence make
362 * Automake Silent Rules:: How Automake can help in silencing make
364 When Automake Isn't Enough
366 * Extending:: Adding new rules or overriding existing ones.
367 * Third-Party Makefiles:: Integrating Non-Automake @file{Makefile}s.
369 Frequently Asked Questions about Automake
371 * CVS:: CVS and generated files
372 * maintainer-mode:: missing and AM_MAINTAINER_MODE
373 * Wildcards:: Why doesn't Automake support wildcards?
374 * Limitations on File Names:: Limitations on source and installed file names
375 * Errors with distclean:: Files left in build directory after distclean
376 * Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS
377 * Renamed Objects:: Why are object files sometimes renamed?
378 * Per-Object Flags:: How to simulate per-object flags?
379 * Multiple Outputs:: Writing rules for tools with many output files
380 * Hard-Coded Install Paths:: Installing to hard-coded locations
381 * Debugging Make Rules:: Strategies when things don't work as expected
382 * Reporting Bugs:: Feedback on bugs and feature requests
386 * GNU Free Documentation License:: License for copying this manual
390 * Macro Index:: Index of Autoconf macros
391 * Variable Index:: Index of Makefile variables
392 * General Index:: General index
401 @chapter Introduction
403 Automake is a tool for automatically generating @file{Makefile.in}s
404 from files called @file{Makefile.am}. Each @file{Makefile.am} is
405 basically a series of @command{make} variable
406 definitions@footnote{These variables are also called @dfn{make macros}
407 in Make terminology, however in this manual we reserve the term
408 @dfn{macro} for Autoconf's macros.}, with rules being thrown in
409 occasionally. The generated @file{Makefile.in}s are compliant with
410 the GNU Makefile standards.
412 @cindex GNU Makefile standards
414 The GNU Makefile Standards Document
415 (@pxref{Makefile Conventions, , , standards, The GNU Coding Standards})
416 is long, complicated, and subject to change. The goal of Automake is to
417 remove the burden of Makefile maintenance from the back of the
418 individual GNU maintainer (and put it on the back of the Automake
421 The typical Automake input file is simply a series of variable definitions.
422 Each such file is processed to create a @file{Makefile.in}. There
423 should generally be one @file{Makefile.am} per directory of a project.
425 @cindex Constraints of Automake
426 @cindex Automake constraints
428 Automake does constrain a project in certain ways; for instance, it
429 assumes that the project uses Autoconf (@pxref{Top, , Introduction,
430 autoconf, The Autoconf Manual}), and enforces certain restrictions on
431 the @file{configure.ac} contents.
433 @cindex Automake requirements
434 @cindex Requirements, Automake
436 Automake requires @command{perl} in order to generate the
437 @file{Makefile.in}s. However, the distributions created by Automake are
438 fully GNU standards-compliant, and do not require @command{perl} in order
441 @cindex Bugs, reporting
442 @cindex Reporting bugs
443 @cindex E-mail, bug reports
445 For more information on bug reports, @xref{Reporting Bugs}.
447 @node Autotools Introduction
448 @chapter An Introduction to the Autotools
450 If you are new to Automake, maybe you know that it is part of a set of
451 tools called @emph{The Autotools}. Maybe you've already delved into a
452 package full of files named @file{configure}, @file{configure.ac},
453 @file{Makefile.in}, @file{Makefile.am}, @file{aclocal.m4}, @dots{},
454 some of them claiming to be @emph{generated by} Autoconf or Automake.
455 But the exact purpose of these files and their relations is probably
456 fuzzy. The goal of this chapter is to introduce you to this machinery,
457 to show you how it works and how powerful it is. If you've never
458 installed or seen such a package, do not worry: this chapter will walk
461 If you need some teaching material, more illustrations, or a less
462 @command{automake}-centered continuation, some slides for this
463 introduction are available in Alexandre Duret-Lutz's
464 @uref{http://www.lrde.epita.fr/@/~adl/@/autotools.html,
466 This chapter is the written version of the first part of his tutorial.
469 * GNU Build System:: Introducing the GNU Build System
470 * Use Cases:: Use Cases for the GNU Build System
471 * Why Autotools:: How Autotools Help
472 * Hello World:: A Small Hello World Package
475 @node GNU Build System
476 @section Introducing the GNU Build System
477 @cindex GNU Build System, introduction
479 It is a truth universally acknowledged, that as a developer in
480 possession of a new package, you must be in want of a build system.
482 In the Unix world, such a build system is traditionally achieved using
483 the command @command{make} (@pxref{Top, , Overview, make, The GNU Make
484 Manual}). You express the recipe to build your package in a
485 @file{Makefile}. This file is a set of rules to build the files in
486 the package. For instance the program @file{prog} may be built by
487 running the linker on the files @file{main.o}, @file{foo.o}, and
488 @file{bar.o}; the file @file{main.o} may be built by running the
489 compiler on @file{main.c}; etc. Each time @command{make} is run, it
490 reads @file{Makefile}, checks the existence and modification time of
491 the files mentioned, decides what files need to be built (or rebuilt),
492 and runs the associated commands.
494 When a package needs to be built on a different platform than the one
495 it was developed on, its @file{Makefile} usually needs to be adjusted.
496 For instance the compiler may have another name or require more
497 options. In 1991, David J. MacKenzie got tired of customizing
498 @file{Makefile} for the 20 platforms he had to deal with. Instead, he
499 handcrafted a little shell script called @file{configure} to
500 automatically adjust the @file{Makefile} (@pxref{Genesis, , Genesis,
501 autoconf, The Autoconf Manual}). Compiling his package was now
502 as simple as running @code{./configure && make}.
504 @cindex GNU Coding Standards
506 Today this process has been standardized in the GNU project. The GNU
507 Coding Standards (@pxref{Managing Releases, The Release Process, ,
508 standards, The GNU Coding Standards}) explains how each package of the
509 GNU project should have a @file{configure} script, and the minimal
510 interface it should have. The @file{Makefile} too should follow some
511 established conventions. The result? A unified build system that
512 makes all packages almost indistinguishable by the installer. In its
513 simplest scenario, all the installer has to do is to unpack the
514 package, run @code{./configure && make && make install}, and repeat
515 with the next package to install.
517 We call this build system the @dfn{GNU Build System}, since it was
518 grown out of the GNU project. However it is used by a vast number of
519 other packages: following any existing convention has its advantages.
521 @cindex Autotools, introduction
523 The Autotools are tools that will create a GNU Build System for your
524 package. Autoconf mostly focuses on @file{configure} and Automake on
525 @file{Makefile}s. It is entirely possible to create a GNU Build
526 System without the help of these tools. However it is rather
527 burdensome and error-prone. We will discuss this again after some
528 illustration of the GNU Build System in action.
531 @section Use Cases for the GNU Build System
532 @cindex GNU Build System, use cases
533 @cindex GNU Build System, features
534 @cindex Features of the GNU Build System
535 @cindex Use Cases for the GNU Build System
536 @cindex @file{amhello-1.0.tar.gz}, location
537 @cindex @file{amhello-1.0.tar.gz}, use cases
539 In this section we explore several use cases for the GNU Build System.
540 You can replay all these examples on the @file{amhello-1.0.tar.gz}
541 package distributed with Automake. If Automake is installed on your
542 system, you should find a copy of this file in
543 @file{@var{prefix}/share/doc/automake/amhello-1.0.tar.gz}, where
544 @var{prefix} is the installation prefix specified during configuration
545 (@var{prefix} defaults to @file{/usr/local}, however if Automake was
546 installed by some GNU/Linux distribution it most likely has been set
547 to @file{/usr}). If you do not have a copy of Automake installed,
548 you can find a copy of this file inside the @file{doc/} directory of
549 the Automake package.
551 Some of the following use cases present features that are in fact
552 extensions to the GNU Build System. Read: they are not specified by
553 the GNU Coding Standards, but they are nonetheless part of the build
554 system created by the Autotools. To keep things simple, we do not
555 point out the difference. Our objective is to show you many of the
556 features that the build system created by the Autotools will offer to
560 * Basic Installation:: Common installation procedure
561 * Standard Targets:: A list of standard Makefile targets
562 * Standard Directory Variables:: A list of standard directory variables
563 * Standard Configuration Variables:: Using configuration variables
564 * config.site:: Using a config.site file
565 * VPATH Builds:: Parallel build trees
566 * Two-Part Install:: Installing data and programs separately
567 * Cross-Compilation:: Building for other architectures
568 * Renaming:: Renaming programs at install time
569 * DESTDIR:: Building binary packages with DESTDIR
570 * Preparing Distributions:: Rolling out tarballs
571 * Dependency Tracking:: Automatic dependency tracking
572 * Nested Packages:: The GNU Build Systems can be nested
575 @node Basic Installation
576 @subsection Basic Installation
577 @cindex Configuration, basics
578 @cindex Installation, basics
579 @cindex GNU Build System, basics
581 The most common installation procedure looks as follows.
584 ~ % @kbd{tar zxf amhello-1.0.tar.gz}
585 ~ % @kbd{cd amhello-1.0}
586 ~/amhello-1.0 % @kbd{./configure}
588 config.status: creating Makefile
589 config.status: creating src/Makefile
591 ~/amhello-1.0 % @kbd{make}
593 ~/amhello-1.0 % @kbd{make check}
595 ~/amhello-1.0 % @kbd{su}
597 /home/adl/amhello-1.0 # @kbd{make install}
599 /home/adl/amhello-1.0 # @kbd{exit}
600 ~/amhello-1.0 % @kbd{make installcheck}
606 The user first unpacks the package. Here, and in the following
607 examples, we will use the non-portable @code{tar zxf} command for
608 simplicity. On a system without GNU @command{tar} installed, this
609 command should read @code{gunzip -c amhello-1.0.tar.gz | tar xf -}.
611 The user then enters the newly created directory to run the
612 @file{configure} script. This script probes the system for various
613 features, and finally creates the @file{Makefile}s. In this toy
614 example there are only two @file{Makefile}s, but in real-world projects,
615 there may be many more, usually one @file{Makefile} per directory.
617 It is now possible to run @code{make}. This will construct all the
618 programs, libraries, and scripts that need to be constructed for the
619 package. In our example, this compiles the @file{hello} program.
620 All files are constructed in place, in the source tree; we will see
621 later how this can be changed.
623 @code{make check} causes the package's tests to be run. This step is
624 not mandatory, but it is often good to make sure the programs that
625 have been built behave as they should, before you decide to install
626 them. Our example does not contain any tests, so running @code{make
629 @cindex su, before @code{make install}
630 After everything has been built, and maybe tested, it is time to
631 install it on the system. That means copying the programs,
632 libraries, header files, scripts, and other data files from the
633 source directory to their final destination on the system. The
634 command @code{make install} will do that. However, by default
635 everything will be installed in subdirectories of @file{/usr/local}:
636 binaries will go into @file{/usr/local/bin}, libraries will end up in
637 @file{/usr/local/lib}, etc. This destination is usually not writable
638 by any user, so we assume that we have to become root before we can
639 run @code{make install}. In our example, running @code{make install}
640 will copy the program @file{hello} into @file{/usr/local/bin}
641 and @file{README} into @file{/usr/local/share/doc/amhello}.
643 A last and optional step is to run @code{make installcheck}. This
644 command may run tests on the installed files. @code{make check} tests
645 the files in the source tree, while @code{make installcheck} tests
646 their installed copies. The tests run by the latter can be different
647 from those run by the former. For instance, there are tests that
648 cannot be run in the source tree. Conversely, some packages are set
649 up so that @code{make installcheck} will run the very same tests as
650 @code{make check}, only on different files (non-installed
651 vs.@: installed). It can make a difference, for instance when the
652 source tree's layout is different from that of the installation.
653 Furthermore it may help to diagnose an incomplete installation.
655 Presently most packages do not have any @code{installcheck} tests
656 because the existence of @code{installcheck} is little known, and its
657 usefulness is neglected. Our little toy package is no better: @code{make
658 installcheck} does nothing.
660 @node Standard Targets
661 @subsection Standard @file{Makefile} Targets
663 So far we have come across four ways to run @command{make} in the GNU
664 Build System: @code{make}, @code{make check}, @code{make install}, and
665 @code{make installcheck}. The words @code{check}, @code{install}, and
666 @code{installcheck}, passed as arguments to @command{make}, are called
667 @dfn{targets}. @code{make} is a shorthand for @code{make all},
668 @code{all} being the default target in the GNU Build System.
670 Here is a list of the most useful targets that the GNU Coding Standards
676 Build programs, libraries, documentation, etc.@: (same as @code{make}).
679 Install what needs to be installed, copying the files from the
680 package's tree to system-wide directories.
681 @item make install-strip
682 @trindex install-strip
683 Same as @code{make install}, then strip debugging symbols. Some
684 users like to trade space for useful bug reports@enddots{}
687 The opposite of @code{make install}: erase the installed files.
688 (This needs to be run from the same build tree that was installed.)
691 Erase from the build tree the files built by @code{make all}.
694 Additionally erase anything @code{./configure} created.
697 Run the test suite, if any.
698 @item make installcheck
699 @trindex installcheck
700 Check the installed programs or libraries, if supported.
703 Recreate @file{@var{package}-@var{version}.tar.gz} from all the source
707 @node Standard Directory Variables
708 @subsection Standard Directory Variables
709 @cindex directory variables
711 The GNU Coding Standards also specify a hierarchy of variables to
712 denote installation directories. Some of these are:
714 @multitable {Directory variable} {@code{$@{datarootdir@}/doc/$@{PACKAGE@}}}
715 @headitem Directory variable @tab Default value
716 @item @code{prefix} @tab @code{/usr/local}
717 @item @w{@ @ @code{exec_prefix}} @tab @code{$@{prefix@}}
718 @item @w{@ @ @ @ @code{bindir}} @tab @code{$@{exec_prefix@}/bin}
719 @item @w{@ @ @ @ @code{libdir}} @tab @code{$@{exec_prefix@}/lib}
720 @item @w{@ @ @ @ @dots{}}
721 @item @w{@ @ @code{includedir}} @tab @code{$@{prefix@}/include}
722 @item @w{@ @ @code{datarootdir}} @tab @code{$@{prefix@}/share}
723 @item @w{@ @ @ @ @code{datadir}} @tab @code{$@{datarootdir@}}
724 @item @w{@ @ @ @ @code{mandir}} @tab @code{$@{datarootdir@}/man}
725 @item @w{@ @ @ @ @code{infodir}} @tab @code{$@{datarootdir@}/info}
726 @item @w{@ @ @ @ @code{docdir}} @tab @code{$@{datarootdir@}/doc/$@{PACKAGE@}}
727 @item @w{@ @ @dots{}}
730 @c We should provide a complete table somewhere, but not here. The
731 @c complete list of directory variables it too confusing as-is. It
732 @c requires some explanations that are too complicated for this
733 @c introduction. Besides listing directories like localstatedir
734 @c would make the explanations in ``Two-Part Install'' harder.
736 Each of these directories has a role which is often obvious from its
737 name. In a package, any installable file will be installed in one of
738 these directories. For instance in @code{amhello-1.0}, the program
739 @file{hello} is to be installed in @var{bindir}, the directory for
740 binaries. The default value for this directory is
741 @file{/usr/local/bin}, but the user can supply a different value when
742 calling @command{configure}. Also the file @file{README} will be
743 installed into @var{docdir}, which defaults to
744 @file{/usr/local/share/doc/amhello}.
748 As a user, if you wish to install a package on your own account, you
749 could proceed as follows:
752 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr}
754 ~/amhello-1.0 % @kbd{make}
756 ~/amhello-1.0 % @kbd{make install}
760 This would install @file{~/usr/bin/hello} and
761 @file{~/usr/share/doc/amhello/README}.
763 The list of all such directory options is shown by
764 @code{./configure --help}.
766 @node Standard Configuration Variables
767 @subsection Standard Configuration Variables
768 @cindex configuration variables, overriding
770 The GNU Coding Standards also define a set of standard configuration
771 variables used during the build. Here are some:
780 @item @code{CXXFLAGS}
784 @item @code{CPPFLAGS}
785 C/C++ preprocessor flags
789 @command{configure} usually does a good job at setting appropriate
790 values for these variables, but there are cases where you may want to
791 override them. For instance you may have several versions of a
792 compiler installed and would like to use another one, you may have
793 header files installed outside the default search path of the
794 compiler, or even libraries out of the way of the linker.
796 Here is how one would call @command{configure} to force it to use
797 @command{gcc-3} as C compiler, use header files from
798 @file{~/usr/include} when compiling, and libraries from
799 @file{~/usr/lib} when linking.
802 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr CC=gcc-3 \
803 CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib}
806 Again, a full list of these variables appears in the output of
807 @code{./configure --help}.
810 @subsection Overriding Default Configuration Setting with @file{config.site}
811 @cindex @file{config.site} example
813 When installing several packages using the same setup, it can be
814 convenient to create a file to capture common settings.
815 If a file named @file{@var{prefix}/share/config.site} exists,
816 @command{configure} will source it at the beginning of its execution.
818 Recall the command from the previous section:
821 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr CC=gcc-3 \
822 CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib}
825 Assuming we are installing many package in @file{~/usr}, and will
826 always want to use these definitions of @code{CC}, @code{CPPFLAGS}, and
827 @code{LDFLAGS}, we can automate this by creating the following
828 @file{~/usr/share/config.site} file:
831 test -z "$CC" && CC=gcc-3
832 test -z "$CPPFLAGS" && CPPFLAGS=-I$HOME/usr/include
833 test -z "$LDFLAGS" && LDFLAGS=-L$HOME/usr/lib
836 Now, any time a @file{configure} script is using the @file{~/usr}
837 prefix, it will execute the above @file{config.site} and define
838 these three variables.
841 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr}
842 configure: loading site script /home/adl/usr/share/config.site
846 @xref{Site Defaults, , Setting Site Defaults, autoconf, The Autoconf
847 Manual}, for more information about this feature.
851 @subsection Parallel Build Trees (a.k.a.@: VPATH Builds)
852 @cindex Parallel build trees
854 @cindex source tree and build tree
855 @cindex build tree and source tree
856 @cindex trees, source vs.@: build
858 The GNU Build System distinguishes two trees: the source tree, and
861 The source tree is rooted in the directory containing
862 @file{configure}. It contains all the sources files (those that are
863 distributed), and may be arranged using several subdirectories.
865 The build tree is rooted in the directory in which @file{configure}
866 was run, and is populated with all object files, programs, libraries,
867 and other derived files built from the sources (and hence not
868 distributed). The build tree usually has the same subdirectory layout
869 as the source tree; its subdirectories are created automatically by
872 If @file{configure} is executed in its own directory, the source and
873 build trees are combined: derived files are constructed in the same
874 directories as their sources. This was the case in our first
875 installation example (@pxref{Basic Installation}).
877 A common request from users is that they want to confine all derived
878 files to a single directory, to keep their source directories
879 uncluttered. Here is how we could run @file{configure} to build
880 everything in a subdirectory called @file{build/}.
883 ~ % @kbd{tar zxf ~/amhello-1.0.tar.gz}
884 ~ % @kbd{cd amhello-1.0}
885 ~/amhello-1.0 % @kbd{mkdir build && cd build}
886 ~/amhello-1.0/build % @kbd{../configure}
888 ~/amhello-1.0/build % @kbd{make}
892 These setups, where source and build trees are different, are often
893 called @dfn{parallel builds} or @dfn{VPATH builds}. The expression
894 @emph{parallel build} is misleading: the word @emph{parallel} is a
895 reference to the way the build tree shadows the source tree, it is not
896 about some concurrency in the way build commands are run. For this
897 reason we refer to such setups using the name @emph{VPATH builds} in
898 the following. @emph{VPATH} is the name of the @command{make} feature
899 used by the @file{Makefile}s to allow these builds (@pxref{General
900 Search, , @code{VPATH} Search Path for All Prerequisites, make, The
903 @cindex multiple configurations, example
904 @cindex debug build, example
905 @cindex optimized build, example
907 VPATH builds have other interesting uses. One is to build the same
908 sources with multiple configurations. For instance:
910 @c Keep in sync with amhello-cflags.sh
912 ~ % @kbd{tar zxf ~/amhello-1.0.tar.gz}
913 ~ % @kbd{cd amhello-1.0}
914 ~/amhello-1.0 % @kbd{mkdir debug optim && cd debug}
915 ~/amhello-1.0/debug % @kbd{../configure CFLAGS='-g -O0'}
917 ~/amhello-1.0/debug % @kbd{make}
919 ~/amhello-1.0/debug % cd ../optim
920 ~/amhello-1.0/optim % @kbd{../configure CFLAGS='-O3 -fomit-frame-pointer'}
922 ~/amhello-1.0/optim % @kbd{make}
926 With network file systems, a similar approach can be used to build the
927 same sources on different machines. For instance, suppose that the
928 sources are installed on a directory shared by two hosts: @code{HOST1}
929 and @code{HOST2}, which may be different platforms.
932 ~ % @kbd{cd /nfs/src}
933 /nfs/src % @kbd{tar zxf ~/amhello-1.0.tar.gz}
936 On the first host, you could create a local build directory:
938 [HOST1] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
939 [HOST1] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure}
941 [HOST1] /tmp/amh % @kbd{make && sudo make install}
946 (Here we assume that the installer has configured @command{sudo} so it
947 can execute @code{make install} with root privileges; it is more convenient
948 than using @command{su} like in @ref{Basic Installation}).
950 On the second host, you would do exactly the same, possibly at
953 [HOST2] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
954 [HOST2] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure}
956 [HOST2] /tmp/amh % @kbd{make && sudo make install}
960 @cindex read-only source tree
961 @cindex source tree, read-only
963 In this scenario, nothing forbids the @file{/nfs/src/amhello-1.0}
964 directory from being read-only. In fact VPATH builds are also a means
965 of building packages from a read-only medium such as a CD-ROM. (The
966 FSF used to sell CD-ROM with unpacked source code, before the GNU
967 project grew so big.)
969 @node Two-Part Install
970 @subsection Two-Part Installation
972 In our last example (@pxref{VPATH Builds}), a source tree was shared
973 by two hosts, but compilation and installation were done separately on
976 The GNU Build System also supports networked setups where part of the
977 installed files should be shared amongst multiple hosts. It does so
978 by distinguishing architecture-dependent files from
979 architecture-independent files, and providing two @file{Makefile}
980 targets to install each of these classes of files.
982 @trindex install-exec
983 @trindex install-data
985 These targets are @code{install-exec} for architecture-dependent files
986 and @code{install-data} for architecture-independent files.
987 The command we used up to now, @code{make install}, can be thought of
988 as a shorthand for @code{make install-exec install-data}.
990 From the GNU Build System point of view, the distinction between
991 architecture-dependent files and architecture-independent files is
992 based exclusively on the directory variable used to specify their
993 installation destination. In the list of directory variables we
994 provided earlier (@pxref{Standard Directory Variables}), all the
995 variables based on @var{exec-prefix} designate architecture-dependent
996 directories whose files will be installed by @code{make install-exec}.
997 The others designate architecture-independent directories and will
998 serve files installed by @code{make install-data}. @xref{The Two Parts
999 of Install}, for more details.
1001 Here is how we could revisit our two-host installation example,
1002 assuming that (1) we want to install the package directly in
1003 @file{/usr}, and (2) the directory @file{/usr/share} is shared by the
1006 On the first host we would run
1008 [HOST1] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
1009 [HOST1] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure --prefix /usr}
1011 [HOST1] /tmp/amh % @kbd{make && sudo make install}
1015 On the second host, however, we need only install the
1016 architecture-specific files.
1018 [HOST2] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
1019 [HOST2] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure --prefix /usr}
1021 [HOST2] /tmp/amh % @kbd{make && sudo make install-exec}
1025 In packages that have installation checks, it would make sense to run
1026 @code{make installcheck} (@pxref{Basic Installation}) to verify that
1027 the package works correctly despite the apparent partial installation.
1029 @node Cross-Compilation
1030 @subsection Cross-Compilation
1031 @cindex cross-compilation
1033 To @dfn{cross-compile} is to build on one platform a binary that will
1034 run on another platform. When speaking of cross-compilation, it is
1035 important to distinguish between the @dfn{build platform} on which
1036 the compilation is performed, and the @dfn{host platform} on which the
1037 resulting executable is expected to run. The following
1038 @command{configure} options are used to specify each of them:
1041 @item --build=@var{build}
1042 @opindex --build=@var{build}
1043 The system on which the package is built.
1044 @item --host=@var{host}
1045 @opindex --host=@var{host}
1046 The system where built programs and libraries will run.
1049 When the @option{--host} is used, @command{configure} will search for
1050 the cross-compiling suite for this platform. Cross-compilation tools
1051 commonly have their target architecture as prefix of their name. For
1052 instance my cross-compiler for MinGW32 has its binaries called
1053 @code{i586-mingw32msvc-gcc}, @code{i586-mingw32msvc-ld},
1054 @code{i586-mingw32msvc-as}, etc.
1056 @cindex MinGW cross-compilation example
1057 @cindex cross-compilation example
1059 Here is how we could build @code{amhello-1.0} for
1060 @code{i586-mingw32msvc} on a GNU/Linux PC.
1062 @c Keep in sync with amhello-cross-compile.sh
1064 ~/amhello-1.0 % @kbd{./configure --build i686-pc-linux-gnu --host i586-mingw32msvc}
1065 checking for a BSD-compatible install... /usr/bin/install -c
1066 checking whether build environment is sane... yes
1067 checking for gawk... gawk
1068 checking whether make sets $(MAKE)... yes
1069 checking for i586-mingw32msvc-strip... i586-mingw32msvc-strip
1070 checking for i586-mingw32msvc-gcc... i586-mingw32msvc-gcc
1071 checking for C compiler default output file name... a.exe
1072 checking whether the C compiler works... yes
1073 checking whether we are cross compiling... yes
1074 checking for suffix of executables... .exe
1075 checking for suffix of object files... o
1076 checking whether we are using the GNU C compiler... yes
1077 checking whether i586-mingw32msvc-gcc accepts -g... yes
1078 checking for i586-mingw32msvc-gcc option to accept ANSI C...
1080 ~/amhello-1.0 % @kbd{make}
1082 ~/amhello-1.0 % @kbd{cd src; file hello.exe}
1083 hello.exe: MS Windows PE 32-bit Intel 80386 console executable not relocatable
1086 The @option{--host} and @option{--build} options are usually all we
1087 need for cross-compiling. The only exception is if the package being
1088 built is itself a cross-compiler: we need a third option to specify
1089 its target architecture.
1092 @item --target=@var{target}
1093 @opindex --target=@var{target}
1094 When building compiler tools: the system for which the tools will
1098 For instance when installing GCC, the GNU Compiler Collection, we can
1099 use @option{--target=@/@var{target}} to specify that we want to build
1100 GCC as a cross-compiler for @var{target}. Mixing @option{--build} and
1101 @option{--target}, we can actually cross-compile a cross-compiler;
1102 such a three-way cross-compilation is known as a @dfn{Canadian cross}.
1104 @xref{Specifying Names, , Specifying the System Type, autoconf, The
1105 Autoconf Manual}, for more information about these @command{configure}
1109 @subsection Renaming Programs at Install Time
1110 @cindex Renaming programs
1111 @cindex Transforming program names
1112 @cindex Programs, renaming during installation
1114 The GNU Build System provides means to automatically rename
1115 executables and manpages before they are installed (@pxref{Man Pages}).
1116 This is especially convenient
1117 when installing a GNU package on a system that already has a
1118 proprietary implementation you do not want to overwrite. For instance,
1119 you may want to install GNU @command{tar} as @command{gtar} so you can
1120 distinguish it from your vendor's @command{tar}.
1122 This can be done using one of these three @command{configure} options.
1125 @item --program-prefix=@var{prefix}
1126 @opindex --program-prefix=@var{prefix}
1127 Prepend @var{prefix} to installed program names.
1128 @item --program-suffix=@var{suffix}
1129 @opindex --program-suffix=@var{suffix}
1130 Append @var{suffix} to installed program names.
1131 @item --program-transform-name=@var{program}
1132 @opindex --program-transform-name=@var{program}
1133 Run @code{sed @var{program}} on installed program names.
1136 The following commands would install @file{hello}
1137 as @file{/usr/local/bin/test-hello}, for instance.
1140 ~/amhello-1.0 % @kbd{./configure --program-prefix test-}
1142 ~/amhello-1.0 % @kbd{make}
1144 ~/amhello-1.0 % @kbd{sudo make install}
1149 @subsection Building Binary Packages Using DESTDIR
1152 The GNU Build System's @code{make install} and @code{make uninstall}
1153 interface does not exactly fit the needs of a system administrator
1154 who has to deploy and upgrade packages on lots of hosts. In other
1155 words, the GNU Build System does not replace a package manager.
1157 Such package managers usually need to know which files have been
1158 installed by a package, so a mere @code{make install} is
1161 @cindex Staged installation
1163 The @code{DESTDIR} variable can be used to perform a staged
1164 installation. The package should be configured as if it was going to
1165 be installed in its final location (e.g., @code{--prefix /usr}), but
1166 when running @code{make install}, the @code{DESTDIR} should be set to
1167 the absolute name of a directory into which the installation will be
1168 diverted. From this directory it is easy to review which files are
1169 being installed where, and finally copy them to their final location
1172 @cindex Binary package
1174 For instance here is how we could create a binary package containing a
1175 snapshot of all the files to be installed.
1177 @c Keep in sync with amhello-binpkg.sh
1179 ~/amhello-1.0 % @kbd{./configure --prefix /usr}
1181 ~/amhello-1.0 % @kbd{make}
1183 ~/amhello-1.0 % @kbd{make DESTDIR=$HOME/inst install}
1185 ~/amhello-1.0 % @kbd{cd ~/inst}
1186 ~/inst % @kbd{find . -type f -print > ../files.lst}
1187 ~/inst % @kbd{tar zcvf ~/amhello-1.0-i686.tar.gz `cat ../files.lst`}
1189 ./usr/share/doc/amhello/README
1192 After this example, @code{amhello-1.0-i686.tar.gz} is ready to be
1193 uncompressed in @file{/} on many hosts. (Using @code{`cat ../files.lst`}
1194 instead of @samp{.} as argument for @command{tar} avoids entries for
1195 each subdirectory in the archive: we would not like @command{tar} to
1196 restore the modification time of @file{/}, @file{/usr/}, etc.)
1198 Note that when building packages for several architectures, it might
1199 be convenient to use @code{make install-data} and @code{make
1200 install-exec} (@pxref{Two-Part Install}) to gather
1201 architecture-independent files in a single package.
1203 @xref{Install}, for more information.
1205 @c We should document PRE_INSTALL/POST_INSTALL/NORMAL_INSTALL and their
1206 @c UNINSTALL counterparts.
1208 @node Preparing Distributions
1209 @subsection Preparing Distributions
1210 @cindex Preparing distributions
1211 @cindex Packages, preparation
1212 @cindex Distributions, preparation
1214 We have already mentioned @code{make dist}. This target collects all
1215 your source files and the necessary parts of the build system to
1216 create a tarball named @file{@var{package}-@var{version}.tar.gz}.
1218 @cindex @code{distcheck} better than @code{dist}
1220 Another, more useful command is @code{make distcheck}. The
1221 @code{distcheck} target constructs
1222 @file{@var{package}-@var{version}.tar.gz} just as well as @code{dist},
1223 but it additionally ensures most of the use cases presented so far
1228 It attempts a full compilation of the package (@pxref{Basic
1229 Installation}), unpacking the newly constructed tarball, running
1230 @code{make}, @code{make check}, @code{make install}, as well as
1231 @code{make installcheck}, and even @code{make dist},
1233 it tests VPATH builds with read-only source tree (@pxref{VPATH Builds}),
1235 it makes sure @code{make clean}, @code{make distclean}, and @code{make
1236 uninstall} do not omit any file (@pxref{Standard Targets}),
1238 and it checks that @code{DESTDIR} installations work (@pxref{DESTDIR}).
1241 All of these actions are performed in a temporary subdirectory, so
1242 that no root privileges are required.
1244 Releasing a package that fails @code{make distcheck} means that one of
1245 the scenarios we presented will not work and some users will be
1246 disappointed. Therefore it is a good practice to release a package
1247 only after a successful @code{make distcheck}. This of course does
1248 not imply that the package will be flawless, but at least it will
1249 prevent some of the embarrassing errors you may find in packages
1250 released by people who have never heard about @code{distcheck} (like
1251 @code{DESTDIR} not working because of a typo, or a distributed file
1252 being erased by @code{make clean}, or even @code{VPATH} builds not
1255 @xref{Creating amhello}, to recreate @file{amhello-1.0.tar.gz} using
1256 @code{make distcheck}. @xref{Checking the Distribution}, for more
1257 information about @code{distcheck}.
1259 @node Dependency Tracking
1260 @subsection Automatic Dependency Tracking
1261 @cindex Dependency tracking
1263 Dependency tracking is performed as a side-effect of compilation.
1264 Each time the build system compiles a source file, it computes its
1265 list of dependencies (in C these are the header files included by the
1266 source being compiled). Later, any time @command{make} is run and a
1267 dependency appears to have changed, the dependent files will be
1270 Automake generates code for automatic dependency tracking by default,
1271 unless the developer chooses to override it; for more information,
1272 @pxref{Dependencies}.
1274 When @command{configure} is executed, you can see it probing each
1275 compiler for the dependency mechanism it supports (several mechanisms
1279 ~/amhello-1.0 % @kbd{./configure --prefix /usr}
1281 checking dependency style of gcc... gcc3
1285 Because dependencies are only computed as a side-effect of the
1286 compilation, no dependency information exists the first time a package
1287 is built. This is OK because all the files need to be built anyway:
1288 @code{make} does not have to decide which files need to be rebuilt.
1289 In fact, dependency tracking is completely useless for one-time builds
1290 and there is a @command{configure} option to disable this:
1293 @item --disable-dependency-tracking
1294 @opindex --disable-dependency-tracking
1295 Speed up one-time builds.
1298 Some compilers do not offer any practical way to derive the list of
1299 dependencies as a side-effect of the compilation, requiring a separate
1300 run (maybe of another tool) to compute these dependencies. The
1301 performance penalty implied by these methods is important enough to
1302 disable them by default. The option @option{--enable-dependency-tracking}
1303 must be passed to @command{configure} to activate them.
1306 @item --enable-dependency-tracking
1307 @opindex --enable-dependency-tracking
1308 Do not reject slow dependency extractors.
1311 @xref{Dependency Tracking Evolution, , Dependency Tracking Evolution,
1312 automake-history, Brief History of Automake}, for some discussion about
1313 the different dependency tracking schemes used by Automake over the years.
1315 @node Nested Packages
1316 @subsection Nested Packages
1317 @cindex Nested packages
1318 @cindex Packages, nested
1321 Although nesting packages isn't something we would recommend to
1322 someone who is discovering the Autotools, it is a nice feature worthy
1323 of mention in this small advertising tour.
1325 Autoconfiscated packages (that means packages whose build system have
1326 been created by Autoconf and friends) can be nested to arbitrary
1329 A typical setup is that package A will distribute one of the libraries
1330 it needs in a subdirectory. This library B is a complete package with
1331 its own GNU Build System. The @command{configure} script of A will
1332 run the @command{configure} script of B as part of its execution,
1333 building and installing A will also build and install B. Generating a
1334 distribution for A will also include B.
1336 It is possible to gather several packages like this. GCC is a heavy
1337 user of this feature. This gives installers a single package to
1338 configure, build and install, while it allows developers to work on
1339 subpackages independently.
1341 When configuring nested packages, the @command{configure} options
1342 given to the top-level @command{configure} are passed recursively to
1343 nested @command{configure}s. A package that does not understand an
1344 option will ignore it, assuming it is meaningful to some other
1347 @opindex --help=recursive
1349 The command @code{configure --help=recursive} can be used to display
1350 the options supported by all the included packages.
1352 @xref{Subpackages}, for an example setup.
1355 @section How Autotools Help
1356 @cindex Autotools, purpose
1358 There are several reasons why you may not want to implement the GNU
1359 Build System yourself (read: write a @file{configure} script and
1360 @file{Makefile}s yourself).
1364 As we have seen, the GNU Build System has a lot of
1365 features (@pxref{Use Cases}).
1366 Some users may expect features you have not implemented because
1367 you did not need them.
1369 Implementing these features portably is difficult and exhausting.
1370 Think of writing portable shell scripts, and portable
1371 @file{Makefile}s, for systems you may not have handy. @xref{Portable
1372 Shell, , Portable Shell Programming, autoconf, The Autoconf Manual}, to
1375 You will have to upgrade your setup to follow changes to the GNU
1379 The GNU Autotools take all this burden off your back and provide:
1383 Tools to create a portable, complete, and self-contained GNU Build
1384 System, from simple instructions.
1385 @emph{Self-contained} meaning the resulting build system does not
1386 require the GNU Autotools.
1388 A central place where fixes and improvements are made:
1389 a bug-fix for a portability issue will benefit every package.
1392 Yet there also exist reasons why you may want NOT to use the
1393 Autotools@enddots{} For instance you may be already using (or used to)
1394 another incompatible build system. Autotools will only be useful if
1395 you do accept the concepts of the GNU Build System. People who have their
1396 own idea of how a build system should work will feel frustrated by the
1400 @section A Small Hello World
1401 @cindex Example Hello World
1402 @cindex Hello World example
1403 @cindex @file{amhello-1.0.tar.gz}, creation
1405 In this section we recreate the @file{amhello-1.0} package from
1406 scratch. The first subsection shows how to call the Autotools to
1407 instantiate the GNU Build System, while the second explains the
1408 meaning of the @file{configure.ac} and @file{Makefile.am} files read
1411 @anchor{amhello Explained}
1413 * Creating amhello:: Create @file{amhello-1.0.tar.gz} from scratch
1414 * amhello's configure.ac Setup Explained::
1415 * amhello's Makefile.am Setup Explained::
1418 @node Creating amhello
1419 @subsection Creating @file{amhello-1.0.tar.gz}
1421 Here is how we can recreate @file{amhello-1.0.tar.gz} from scratch.
1422 The package is simple enough so that we will only need to write 5
1423 files. (You may copy them from the final @file{amhello-1.0.tar.gz}
1424 that is distributed with Automake if you do not want to write them.)
1426 Create the following files in an empty directory.
1431 @file{src/main.c} is the source file for the @file{hello} program. We
1432 store it in the @file{src/} subdirectory, because later, when the package
1433 evolves, it will ease the addition of a @file{man/} directory for man
1434 pages, a @file{data/} directory for data files, etc.
1436 ~/amhello % @kbd{cat src/main.c}
1443 puts ("Hello World!");
1444 puts ("This is " PACKAGE_STRING ".");
1450 @file{README} contains some very limited documentation for our little
1453 ~/amhello % @kbd{cat README}
1454 This is a demonstration package for GNU Automake.
1455 Type `info Automake' to read the Automake manual.
1459 @file{Makefile.am} and @file{src/Makefile.am} contain Automake
1460 instructions for these two directories.
1463 ~/amhello % @kbd{cat src/Makefile.am}
1464 bin_PROGRAMS = hello
1465 hello_SOURCES = main.c
1466 ~/amhello % @kbd{cat Makefile.am}
1468 dist_doc_DATA = README
1472 Finally, @file{configure.ac} contains Autoconf instructions to
1473 create the @command{configure} script.
1476 ~/amhello % @kbd{cat configure.ac}
1477 AC_INIT([amhello], [1.0], [@value{PACKAGE_BUGREPORT}])
1478 AM_INIT_AUTOMAKE([-Wall -Werror foreign])
1480 AC_CONFIG_HEADERS([config.h])
1489 @cindex @command{autoreconf}, example
1491 Once you have these five files, it is time to run the Autotools to
1492 instantiate the build system. Do this using the @command{autoreconf}
1496 ~/amhello % @kbd{autoreconf --install}
1497 configure.ac: installing `./install-sh'
1498 configure.ac: installing `./missing'
1499 src/Makefile.am: installing `./depcomp'
1502 At this point the build system is complete.
1504 In addition to the three scripts mentioned in its output, you can see
1505 that @command{autoreconf} created four other files: @file{configure},
1506 @file{config.h.in}, @file{Makefile.in}, and @file{src/Makefile.in}.
1507 The latter three files are templates that will be adapted to the
1508 system by @command{configure} under the names @file{config.h},
1509 @file{Makefile}, and @file{src/Makefile}. Let's do this:
1512 ~/amhello % @kbd{./configure}
1513 checking for a BSD-compatible install... /usr/bin/install -c
1514 checking whether build environment is sane... yes
1515 checking for gawk... no
1516 checking for mawk... mawk
1517 checking whether make sets $(MAKE)... yes
1518 checking for gcc... gcc
1519 checking for C compiler default output file name... a.out
1520 checking whether the C compiler works... yes
1521 checking whether we are cross compiling... no
1522 checking for suffix of executables...
1523 checking for suffix of object files... o
1524 checking whether we are using the GNU C compiler... yes
1525 checking whether gcc accepts -g... yes
1526 checking for gcc option to accept ISO C89... none needed
1527 checking for style of include used by make... GNU
1528 checking dependency style of gcc... gcc3
1529 configure: creating ./config.status
1530 config.status: creating Makefile
1531 config.status: creating src/Makefile
1532 config.status: creating config.h
1533 config.status: executing depfiles commands
1537 @cindex @code{distcheck} example
1539 You can see @file{Makefile}, @file{src/Makefile}, and @file{config.h}
1540 being created at the end after @command{configure} has probed the
1541 system. It is now possible to run all the targets we wish
1542 (@pxref{Standard Targets}). For instance:
1545 ~/amhello % @kbd{make}
1547 ~/amhello % @kbd{src/hello}
1549 This is amhello 1.0.
1550 ~/amhello % @kbd{make distcheck}
1552 =============================================
1553 amhello-1.0 archives ready for distribution:
1555 =============================================
1558 Note that running @command{autoreconf} is only needed initially when
1559 the GNU Build System does not exist. When you later change some
1560 instructions in a @file{Makefile.am} or @file{configure.ac}, the
1561 relevant part of the build system will be regenerated automatically
1562 when you execute @command{make}.
1564 @command{autoreconf} is a script that calls @command{autoconf},
1565 @command{automake}, and a bunch of other commands in the right order.
1566 If you are beginning with these tools, it is not important to figure
1567 out in which order all these tools should be invoked and why. However,
1568 because Autoconf and Automake have separate manuals, the important
1569 point to understand is that @command{autoconf} is in charge of
1570 creating @file{configure} from @file{configure.ac}, while
1571 @command{automake} is in charge of creating @file{Makefile.in}s from
1572 @file{Makefile.am}s and @file{configure.ac}. This should at least
1573 direct you to the right manual when seeking answers.
1576 @node amhello's configure.ac Setup Explained
1577 @subsection @code{amhello}'s @file{configure.ac} Setup Explained
1579 @cindex @file{configure.ac}, Hello World
1581 Let us begin with the contents of @file{configure.ac}.
1584 AC_INIT([amhello], [1.0], [@value{PACKAGE_BUGREPORT}])
1585 AM_INIT_AUTOMAKE([-Wall -Werror foreign])
1587 AC_CONFIG_HEADERS([config.h])
1595 This file is read by both @command{autoconf} (to create
1596 @file{configure}) and @command{automake} (to create the various
1597 @file{Makefile.in}s). It contains a series of M4 macros that will be
1598 expanded as shell code to finally form the @file{configure} script.
1599 We will not elaborate on the syntax of this file, because the Autoconf
1600 manual has a whole section about it (@pxref{Writing Autoconf Input, ,
1601 Writing @file{configure.ac}, autoconf, The Autoconf Manual}).
1603 The macros prefixed with @code{AC_} are Autoconf macros, documented
1604 in the Autoconf manual (@pxref{Autoconf Macro Index, , Autoconf Macro
1605 Index, autoconf, The Autoconf Manual}). The macros that start with
1606 @code{AM_} are Automake macros, documented later in this manual
1607 (@pxref{Macro Index}).
1609 The first two lines of @file{configure.ac} initialize Autoconf and
1610 Automake. @code{AC_INIT} takes in as parameters the name of the package,
1611 its version number, and a contact address for bug-reports about the
1612 package (this address is output at the end of @code{./configure
1613 --help}, for instance). When adapting this setup to your own package,
1614 by all means please do not blindly copy Automake's address: use the
1615 mailing list of your package, or your own mail address.
1621 The argument to @code{AM_INIT_AUTOMAKE} is a list of options for
1622 @command{automake} (@pxref{Options}). @option{-Wall} and
1623 @option{-Werror} ask @command{automake} to turn on all warnings and
1624 report them as errors. We are speaking of @strong{Automake} warnings
1625 here, such as dubious instructions in @file{Makefile.am}. This has
1626 absolutely nothing to do with how the compiler will be called, even
1627 though it may support options with similar names. Using @option{-Wall
1628 -Werror} is a safe setting when starting to work on a package: you do
1629 not want to miss any issues. Later you may decide to relax things a
1630 bit. The @option{foreign} option tells Automake that this package
1631 will not follow the GNU Standards. GNU packages should always
1632 distribute additional files such as @file{ChangeLog}, @file{AUTHORS},
1633 etc. We do not want @command{automake} to complain about these
1634 missing files in our small example.
1636 The @code{AC_PROG_CC} line causes the @command{configure} script to
1637 search for a C compiler and define the variable @code{CC} with its
1638 name. The @file{src/Makefile.in} file generated by Automake uses the
1639 variable @code{CC} to build @file{hello}, so when @command{configure}
1640 creates @file{src/Makefile} from @file{src/Makefile.in}, it will define
1641 @code{CC} with the value it has found. If Automake is asked to create
1642 a @file{Makefile.in} that uses @code{CC} but @file{configure.ac} does
1643 not define it, it will suggest you add a call to @code{AC_PROG_CC}.
1645 The @code{AC_CONFIG_HEADERS([config.h])} invocation causes the
1646 @command{configure} script to create a @file{config.h} file gathering
1647 @samp{#define}s defined by other macros in @file{configure.ac}. In our
1648 case, the @code{AC_INIT} macro already defined a few of them. Here
1649 is an excerpt of @file{config.h} after @command{configure} has run:
1653 /* Define to the address where bug reports for this package should be sent. */
1654 #define PACKAGE_BUGREPORT "@value{PACKAGE_BUGREPORT}"
1656 /* Define to the full name and version of this package. */
1657 #define PACKAGE_STRING "amhello 1.0"
1661 As you probably noticed, @file{src/main.c} includes @file{config.h} so
1662 it can use @code{PACKAGE_STRING}. In a real-world project,
1663 @file{config.h} can grow really big, with one @samp{#define} per
1664 feature probed on the system.
1666 The @code{AC_CONFIG_FILES} macro declares the list of files that
1667 @command{configure} should create from their @file{*.in} templates.
1668 Automake also scans this list to find the @file{Makefile.am} files it must
1669 process. (This is important to remember: when adding a new directory
1670 to your project, you should add its @file{Makefile} to this list,
1671 otherwise Automake will never process the new @file{Makefile.am} you
1672 wrote in that directory.)
1674 Finally, the @code{AC_OUTPUT} line is a closing command that actually
1675 produces the part of the script in charge of creating the files
1676 registered with @code{AC_CONFIG_HEADERS} and @code{AC_CONFIG_FILES}.
1678 @cindex @command{autoscan}
1680 When starting a new project, we suggest you start with such a simple
1681 @file{configure.ac}, and gradually add the other tests it requires.
1682 The command @command{autoscan} can also suggest a few of the tests
1683 your package may need (@pxref{autoscan Invocation, , Using
1684 @command{autoscan} to Create @file{configure.ac}, autoconf, The
1688 @node amhello's Makefile.am Setup Explained
1689 @subsection @code{amhello}'s @file{Makefile.am} Setup Explained
1691 @cindex @file{Makefile.am}, Hello World
1693 We now turn to @file{src/Makefile.am}. This file contains
1694 Automake instructions to build and install @file{hello}.
1697 bin_PROGRAMS = hello
1698 hello_SOURCES = main.c
1701 A @file{Makefile.am} has the same syntax as an ordinary
1702 @file{Makefile}. When @command{automake} processes a
1703 @file{Makefile.am} it copies the entire file into the output
1704 @file{Makefile.in} (that will be later turned into @file{Makefile} by
1705 @command{configure}) but will react to certain variable definitions
1706 by generating some build rules and other variables.
1707 Often @file{Makefile.am}s contain only a list of variable definitions as
1708 above, but they can also contain other variable and rule definitions that
1709 @command{automake} will pass along without interpretation.
1711 Variables that end with @code{_PROGRAMS} are special variables
1712 that list programs that the resulting @file{Makefile} should build.
1713 In Automake speak, this @code{_PROGRAMS} suffix is called a
1714 @dfn{primary}; Automake recognizes other primaries such as
1715 @code{_SCRIPTS}, @code{_DATA}, @code{_LIBRARIES}, etc.@: corresponding
1716 to different types of files.
1718 The @samp{bin} part of the @code{bin_PROGRAMS} tells
1719 @command{automake} that the resulting programs should be installed in
1720 @var{bindir}. Recall that the GNU Build System uses a set of variables
1721 to denote destination directories and allow users to customize these
1722 locations (@pxref{Standard Directory Variables}). Any such directory
1723 variable can be put in front of a primary (omitting the @code{dir}
1724 suffix) to tell @command{automake} where to install the listed files.
1726 Programs need to be built from source files, so for each program
1727 @code{@var{prog}} listed in a @code{@w{_PROGRAMS}} variable,
1728 @command{automake} will look for another variable named
1729 @code{@var{prog}_SOURCES} listing its source files. There may be more
1730 than one source file: they will all be compiled and linked together.
1732 Automake also knows that source files need to be distributed when
1733 creating a tarball (unlike built programs). So a side-effect of this
1734 @code{hello_SOURCES} declaration is that @file{main.c} will be
1735 part of the tarball created by @code{make dist}.
1737 Finally here are some explanations regarding the top-level
1742 dist_doc_DATA = README
1745 @code{SUBDIRS} is a special variable listing all directories that
1746 @command{make} should recurse into before processing the current
1747 directory. So this line is responsible for @command{make} building
1748 @file{src/hello} even though we run it from the top-level. This line
1749 also causes @code{make install} to install @file{src/hello} before
1750 installing @file{README} (not that this order matters).
1752 The line @code{dist_doc_DATA = README} causes @file{README} to be
1753 distributed and installed in @var{docdir}. Files listed with the
1754 @code{_DATA} primary are not automatically part of the tarball built
1755 with @code{make dist}, so we add the @code{dist_} prefix so they get
1756 distributed. However, for @file{README} it would not have been
1757 necessary: @command{automake} automatically distributes any
1758 @file{README} file it encounters (the list of other files
1759 automatically distributed is presented by @code{automake --help}).
1760 The only important effect of this second line is therefore to install
1761 @file{README} during @code{make install}.
1763 One thing not covered in this example is accessing the installation
1764 directory values (@pxref{Standard Directory Variables}) from your
1765 program code, that is, converting them into defined macros. For this,
1766 @pxref{Defining Directories,,, autoconf, The Autoconf Manual}.
1770 @chapter General ideas
1772 The following sections cover a few basic ideas that will help you
1773 understand how Automake works.
1776 * General Operation:: General operation of Automake
1777 * Strictness:: Standards conformance checking
1778 * Uniform:: The Uniform Naming Scheme
1779 * Length Limitations:: Staying below the command line length limit
1780 * Canonicalization:: How derived variables are named
1781 * User Variables:: Variables reserved for the user
1782 * Auxiliary Programs:: Programs automake might require
1786 @node General Operation
1787 @section General Operation
1789 Automake works by reading a @file{Makefile.am} and generating a
1790 @file{Makefile.in}. Certain variables and rules defined in the
1791 @file{Makefile.am} instruct Automake to generate more specialized code;
1792 for instance, a @code{bin_PROGRAMS} variable definition will cause rules
1793 for compiling and linking programs to be generated.
1795 @cindex Non-standard targets
1796 @cindex @code{git-dist}, non-standard example
1799 The variable definitions and rules in the @file{Makefile.am} are
1800 copied mostly verbatim into the generated file, with all variable
1801 definitions preceding all rules. This allows you to add almost
1802 arbitrary code into the generated @file{Makefile.in}. For instance,
1803 the Automake distribution includes a non-standard rule for the
1804 @code{git-dist} target, which the Automake maintainer uses to make
1805 distributions from the source control system.
1807 @cindex GNU make extensions
1809 Note that most GNU make extensions are not recognized by Automake. Using
1810 such extensions in a @file{Makefile.am} will lead to errors or confusing
1813 @cindex Append operator
1815 A special exception is that the GNU make append operator, @samp{+=}, is
1816 supported. This operator appends its right hand argument to the variable
1817 specified on the left. Automake will translate the operator into
1818 an ordinary @samp{=} operator; @samp{+=} will thus work with any make program.
1820 Automake tries to keep comments grouped with any adjoining rules or
1821 variable definitions.
1823 @cindex Limitations of automake parser
1824 @cindex Automake parser, limitations of
1825 @cindex indentation in Makefile.am
1826 Generally, Automake is not particularly smart in the parsing of unusual
1827 Makefile constructs, so you're advised to avoid fancy constructs or
1828 ``creative'' use of whitespaces.
1829 @c Keep this in sync with doc-parsing-buglets-tabs.sh
1830 For example, @key{TAB} characters cannot be used between a target name
1831 and the following ``@code{:}'' character, and variable assignments
1832 shouldn't be indented with @key{TAB} characters.
1833 @c Keep this in sync with doc-parsing-buglets-colneq-subst.sh
1834 Also, using more complex macro in target names can cause trouble:
1837 % @kbd{cat Makefile.am}
1840 Makefile.am:1: bad characters in variable name `$(FOO'
1841 Makefile.am:1: `:='-style assignments are not portable
1844 @cindex Make targets, overriding
1845 @cindex Make rules, overriding
1846 @cindex Overriding make rules
1847 @cindex Overriding make targets
1849 A rule defined in @file{Makefile.am} generally overrides any such
1850 rule of a similar name that would be automatically generated by
1851 @command{automake}. Although this is a supported feature, it is generally
1852 best to avoid making use of it, as sometimes the generated rules are
1855 @cindex Variables, overriding
1856 @cindex Overriding make variables
1858 Similarly, a variable defined in @file{Makefile.am} or
1859 @code{AC_SUBST}ed from @file{configure.ac} will override any
1860 definition of the variable that @command{automake} would ordinarily
1861 create. This feature is more often useful than the ability to
1862 override a rule. Be warned that many of the variables generated by
1863 @command{automake} are considered to be for internal use only, and their
1864 names might change in future releases.
1866 @cindex Recursive operation of Automake
1867 @cindex Automake, recursive operation
1868 @cindex Example of recursive operation
1870 When examining a variable definition, Automake will recursively examine
1871 variables referenced in the definition. For example, if Automake is
1872 looking at the content of @code{foo_SOURCES} in this snippet
1874 @c Keep in sync with interp.sh
1877 foo_SOURCES = c.c $(xs)
1880 it would use the files @file{a.c}, @file{b.c}, and @file{c.c} as the
1881 contents of @code{foo_SOURCES}.
1883 @cindex @code{##} (special Automake comment)
1884 @cindex Special Automake comment
1885 @cindex Comment, special to Automake
1887 Automake also allows a form of comment that is @emph{not} copied into
1888 the output; all lines beginning with @samp{##} (leading spaces allowed)
1889 are completely ignored by Automake.
1891 It is customary to make the first line of @file{Makefile.am} read:
1893 @cindex Makefile.am, first line
1894 @cindex First line of Makefile.am
1897 ## Process this file with automake to produce Makefile.in
1900 @c FIXME discuss putting a copyright into Makefile.am here? I would but
1901 @c I don't know quite what to say.
1903 @c FIXME document customary ordering of Makefile.am here!
1909 @cindex Non-GNU packages
1911 While Automake is intended to be used by maintainers of GNU packages, it
1912 does make some effort to accommodate those who wish to use it, but do
1913 not want to use all the GNU conventions.
1915 @cindex Strictness, defined
1916 @cindex Strictness, @option{foreign}
1917 @cindex @option{foreign} strictness
1918 @cindex Strictness, @option{gnu}
1919 @cindex @option{gnu} strictness
1920 @cindex Strictness, @option{gnits}
1921 @cindex @option{gnits} strictness
1923 To this end, Automake supports three levels of @dfn{strictness}---the
1924 strictness indicating how stringently Automake should check standards
1927 The valid strictness levels are:
1931 Automake will check for only those things that are absolutely
1932 required for proper operations. For instance, whereas GNU standards
1933 dictate the existence of a @file{NEWS} file, it will not be required in
1934 this mode. This strictness will also turn off some warnings by default
1935 (among them, portability warnings).
1936 The name comes from the fact that Automake is intended to be
1937 used for GNU programs; these relaxed rules are not the standard mode of
1941 Automake will check---as much as possible---for compliance to the GNU
1942 standards for packages. This is the default.
1945 Automake will check for compliance to the as-yet-unwritten @dfn{Gnits
1946 standards}. These are based on the GNU standards, but are even more
1947 detailed. Unless you are a Gnits standards contributor, it is
1948 recommended that you avoid this option until such time as the Gnits
1949 standard is actually published (which may never happen).
1952 @xref{Gnits}, for more information on the precise implications of the
1957 @section The Uniform Naming Scheme
1959 @cindex Uniform naming scheme
1961 Automake variables generally follow a @dfn{uniform naming scheme} that
1962 makes it easy to decide how programs (and other derived objects) are
1963 built, and how they are installed. This scheme also supports
1964 @command{configure} time determination of what should be built.
1966 @cindex @code{_PROGRAMS} primary variable
1967 @cindex @code{PROGRAMS} primary variable
1968 @cindex Primary variable, @code{PROGRAMS}
1969 @cindex Primary variable, defined
1972 At @command{make} time, certain variables are used to determine which
1973 objects are to be built. The variable names are made of several pieces
1974 that are concatenated together.
1976 The piece that tells @command{automake} what is being built is commonly called
1977 the @dfn{primary}. For instance, the primary @code{PROGRAMS} holds a
1978 list of programs that are to be compiled and linked.
1981 @cindex @code{pkgdatadir}, defined
1982 @cindex @code{pkgincludedir}, defined
1983 @cindex @code{pkglibdir}, defined
1984 @cindex @code{pkglibexecdir}, defined
1987 @vindex pkgincludedir
1989 @vindex pkglibexecdir
1991 @cindex @code{PACKAGE}, directory
1992 A different set of names is used to decide where the built objects
1993 should be installed. These names are prefixes to the primary, and they
1994 indicate which standard directory should be used as the installation
1995 directory. The standard directory names are given in the GNU standards
1996 (@pxref{Directory Variables, , , standards, The GNU Coding Standards}).
1997 Automake extends this list with @code{pkgdatadir}, @code{pkgincludedir},
1998 @code{pkglibdir}, and @code{pkglibexecdir}; these are the same as the
1999 non-@samp{pkg} versions, but with @samp{$(PACKAGE)} appended. For instance,
2000 @code{pkglibdir} is defined as @samp{$(libdir)/$(PACKAGE)}.
2002 @cindex @code{EXTRA_}, prepending
2003 For each primary, there is one additional variable named by prepending
2004 @samp{EXTRA_} to the primary name. This variable is used to list
2005 objects that may or may not be built, depending on what
2006 @command{configure} decides. This variable is required because Automake
2007 must statically know the entire list of objects that may be built in
2008 order to generate a @file{Makefile.in} that will work in all cases.
2010 @cindex @code{EXTRA_PROGRAMS}, defined
2011 @cindex Example, @code{EXTRA_PROGRAMS}
2012 @cindex @command{cpio} example
2014 For instance, @command{cpio} decides at configure time which programs
2015 should be built. Some of the programs are installed in @code{bindir},
2016 and some are installed in @code{sbindir}:
2019 EXTRA_PROGRAMS = mt rmt
2020 bin_PROGRAMS = cpio pax
2021 sbin_PROGRAMS = $(MORE_PROGRAMS)
2024 Defining a primary without a prefix as a variable, e.g.,
2025 @samp{PROGRAMS}, is an error.
2027 Note that the common @samp{dir} suffix is left off when constructing the
2028 variable names; thus one writes @samp{bin_PROGRAMS} and not
2029 @samp{bindir_PROGRAMS}.
2031 Not every sort of object can be installed in every directory. Automake
2032 will flag those attempts it finds in error (but see below how to override
2033 the check if you really need to).
2034 Automake will also diagnose obvious misspellings in directory names.
2036 @cindex Extending list of installation directories
2037 @cindex Installation directories, extending list
2039 Sometimes the standard directories---even as augmented by
2040 Automake---are not enough. In particular it is sometimes useful, for
2041 clarity, to install objects in a subdirectory of some predefined
2042 directory. To this end, Automake allows you to extend the list of
2043 possible installation directories. A given prefix (e.g., @samp{zar})
2044 is valid if a variable of the same name with @samp{dir} appended is
2045 defined (e.g., @samp{zardir}).
2047 For instance, the following snippet will install @file{file.xml} into
2048 @samp{$(datadir)/xml}.
2050 @c Keep in sync with primary-prefix-couples-documented-valid.sh
2052 xmldir = $(datadir)/xml
2056 This feature can also be used to override the sanity checks Automake
2057 performs to diagnose suspicious directory/primary couples (in the
2058 unlikely case these checks are undesirable, and you really know what
2059 you're doing). For example, Automake would error out on this input:
2061 @c Should be tested in primary-prefix-invalid-couples.sh
2063 # Forbidden directory combinations, automake will error out on this.
2064 pkglib_PROGRAMS = foo
2065 doc_LIBRARIES = libquux.a
2069 but it will succeed with this:
2071 @c Keep in sync with primary-prefix-couples-documented-valid.sh
2073 # Work around forbidden directory combinations. Do not use this
2074 # without a very good reason!
2075 my_execbindir = $(pkglibdir)
2076 my_doclibdir = $(docdir)
2077 my_execbin_PROGRAMS = foo
2078 my_doclib_LIBRARIES = libquux.a
2081 The @samp{exec} substring of the @samp{my_execbindir} variable lets
2082 the files be installed at the right time (@pxref{The Two Parts of
2085 @cindex @samp{noinst_} primary prefix, definition
2088 The special prefix @samp{noinst_} indicates that the objects in question
2089 should be built but not installed at all. This is usually used for
2090 objects required to build the rest of your package, for instance static
2091 libraries (@pxref{A Library}), or helper scripts.
2093 @cindex @samp{check_} primary prefix, definition
2096 The special prefix @samp{check_} indicates that the objects in question
2097 should not be built until the @samp{make check} command is run. Those
2098 objects are not installed either.
2100 The current primary names are @samp{PROGRAMS}, @samp{LIBRARIES},
2101 @samp{LTLIBRARIES}, @samp{LISP}, @samp{PYTHON}, @samp{JAVA},
2102 @samp{SCRIPTS}, @samp{DATA}, @samp{HEADERS}, @samp{MANS}, and
2116 Some primaries also allow additional prefixes that control other
2117 aspects of @command{automake}'s behavior. The currently defined prefixes
2118 are @samp{dist_}, @samp{nodist_}, @samp{nobase_}, and @samp{notrans_}.
2119 These prefixes are explained later (@pxref{Program and Library Variables})
2120 (@pxref{Man Pages}).
2123 @node Length Limitations
2124 @section Staying below the command line length limit
2126 @cindex command line length limit
2129 Traditionally, most unix-like systems have a length limitation for the
2130 command line arguments and environment contents when creating new
2131 processes (see for example
2132 @uref{http://www.in-ulm.de/@/~mascheck/@/various/@/argmax/} for an
2133 overview on this issue),
2134 which of course also applies to commands spawned by @command{make}.
2135 POSIX requires this limit to be at least 4096 bytes, and most modern
2136 systems have quite high limits (or are unlimited).
2138 In order to create portable Makefiles that do not trip over these
2139 limits, it is necessary to keep the length of file lists bounded.
2140 Unfortunately, it is not possible to do so fully transparently within
2141 Automake, so your help may be needed. Typically, you can split long
2142 file lists manually and use different installation directory names for
2143 each list. For example,
2146 data_DATA = file1 @dots{} file@var{N} file@var{N+1} @dots{} file@var{2N}
2150 may also be written as
2152 @c Keep in sync with primary-prefix-couples-documented-valid.sh
2154 data_DATA = file1 @dots{} file@var{N}
2155 data2dir = $(datadir)
2156 data2_DATA = file@var{N+1} @dots{} file@var{2N}
2160 and will cause Automake to treat the two lists separately during
2161 @code{make install}. See @ref{The Two Parts of Install} for choosing
2162 directory names that will keep the ordering of the two parts of
2163 installation Note that @code{make dist} may still only work on a host
2164 with a higher length limit in this example.
2166 Automake itself employs a couple of strategies to avoid long command
2167 lines. For example, when @samp{$@{srcdir@}/} is prepended to file
2168 names, as can happen with above @code{$(data_DATA)} lists, it limits
2169 the amount of arguments passed to external commands.
2171 Unfortunately, some system's @command{make} commands may prepend
2172 @code{VPATH} prefixes like @samp{$@{srcdir@}/} to file names from the
2173 source tree automatically (@pxref{Automatic Rule Rewriting, , Automatic
2174 Rule Rewriting, autoconf, The Autoconf Manual}). In this case, the user
2175 may have to switch to use GNU Make, or refrain from using VPATH builds,
2176 in order to stay below the length limit.
2178 For libraries and programs built from many sources, convenience archives
2179 may be used as intermediates in order to limit the object list length
2180 (@pxref{Libtool Convenience Libraries}).
2183 @node Canonicalization
2184 @section How derived variables are named
2186 @cindex canonicalizing Automake variables
2188 Sometimes a Makefile variable name is derived from some text the
2189 maintainer supplies. For instance, a program name listed in
2190 @samp{_PROGRAMS} is rewritten into the name of a @samp{_SOURCES}
2191 variable. In cases like this, Automake canonicalizes the text, so that
2192 program names and the like do not have to follow Makefile variable naming
2193 rules. All characters in the name except for letters, numbers, the
2194 strudel (@@), and the underscore are turned into underscores when making
2195 variable references.
2197 For example, if your program is named @file{sniff-glue}, the derived
2198 variable name would be @samp{sniff_glue_SOURCES}, not
2199 @samp{sniff-glue_SOURCES}. Similarly the sources for a library named
2200 @file{libmumble++.a} should be listed in the
2201 @samp{libmumble___a_SOURCES} variable.
2203 The strudel is an addition, to make the use of Autoconf substitutions in
2204 variable names less obfuscating.
2207 @node User Variables
2208 @section Variables reserved for the user
2210 @cindex variables, reserved for the user
2211 @cindex user variables
2213 Some @file{Makefile} variables are reserved by the GNU Coding Standards
2214 for the use of the ``user''---the person building the package. For
2215 instance, @code{CFLAGS} is one such variable.
2217 Sometimes package developers are tempted to set user variables such as
2218 @code{CFLAGS} because it appears to make their job easier. However,
2219 the package itself should never set a user variable, particularly not
2220 to include switches that are required for proper compilation of the
2221 package. Since these variables are documented as being for the
2222 package builder, that person rightfully expects to be able to override
2223 any of these variables at build time.
2225 To get around this problem, Automake introduces an automake-specific
2226 shadow variable for each user flag variable. (Shadow variables are
2227 not introduced for variables like @code{CC}, where they would make no
2228 sense.) The shadow variable is named by prepending @samp{AM_} to the
2229 user variable's name. For instance, the shadow variable for
2230 @code{YFLAGS} is @code{AM_YFLAGS}. The package maintainer---that is,
2231 the author(s) of the @file{Makefile.am} and @file{configure.ac}
2232 files---may adjust these shadow variables however necessary.
2234 @xref{Flag Variables Ordering}, for more discussion about these
2235 variables and how they interact with per-target variables.
2237 @node Auxiliary Programs
2238 @section Programs automake might require
2240 @cindex Programs, auxiliary
2241 @cindex Auxiliary programs
2243 Automake sometimes requires helper programs so that the generated
2244 @file{Makefile} can do its work properly. There are a fairly large
2245 number of them, and we list them here.
2247 Although all of these files are distributed and installed with
2248 Automake, a couple of them are maintained separately. The Automake
2249 copies are updated before each release, but we mention the original
2250 source in case you need more recent versions.
2254 This is a wrapper primarily for the Microsoft lib archiver, to make
2258 This is a wrapper for compilers that do not accept options @option{-c}
2259 and @option{-o} at the same time. It is only used when absolutely
2260 required. Such compilers are rare, with the Microsoft C/C++ Compiler
2261 as the most notable exception. This wrapper also makes the following
2262 common options available for that compiler, while performing file name
2263 translation where needed: @option{-I}, @option{-L}, @option{-l},
2264 @option{-Wl,} and @option{-Xlinker}.
2268 These two programs compute the canonical triplets for the given build,
2269 host, or target architecture. These programs are updated regularly to
2270 support new architectures and fix probes broken by changes in new
2271 kernel versions. Each new release of Automake comes with up-to-date
2272 copies of these programs. If your copy of Automake is getting old,
2273 you are encouraged to fetch the latest versions of these files from
2274 @url{http://savannah.gnu.org/git/?group=config} before making a
2278 This program understands how to run a compiler so that it will
2279 generate not only the desired output but also dependency information
2280 that is then used by the automatic dependency tracking feature
2281 (@pxref{Dependencies}).
2284 This program is used to byte-compile Emacs Lisp code.
2287 This is a replacement for the @command{install} program that works on
2288 platforms where @command{install} is unavailable or unusable.
2291 This script is used to generate a @file{version.texi} file. It examines
2292 a file and prints some date information about it.
2295 This wraps a number of programs that are typically only required by
2296 maintainers. If the program in question doesn't exist,
2297 @command{missing} prints an informative warning and attempts to fix
2298 things so that the build can continue.
2301 This script used to be a wrapper around @samp{mkdir -p}, which is not
2302 portable. Now we prefer to use @samp{install-sh -d} when @command{configure}
2303 finds that @samp{mkdir -p} does not work, this makes one less script to
2306 For backward compatibility @file{mkinstalldirs} is still used and
2307 distributed when @command{automake} finds it in a package. But it is no
2308 longer installed automatically, and it should be safe to remove it.
2311 This is used to byte-compile Python scripts.
2314 This implements the default test driver offered by the parallel
2318 Not a program, this file is required for @samp{make dvi}, @samp{make
2319 ps} and @samp{make pdf} to work when Texinfo sources are in the
2320 package. The latest version can be downloaded from
2321 @url{http://www.gnu.org/software/texinfo/}.
2324 This program wraps @command{lex} and @command{yacc} to rename their
2325 output files. It also ensures that, for instance, multiple
2326 @command{yacc} instances can be invoked in a single directory in
2333 @chapter Some example packages
2335 This section contains two small examples.
2337 The first example (@pxref{Complete}) assumes you have an existing
2338 project already using Autoconf, with handcrafted @file{Makefile}s, and
2339 that you want to convert it to using Automake. If you are discovering
2340 both tools, it is probably better that you look at the Hello World
2341 example presented earlier (@pxref{Hello World}).
2343 The second example (@pxref{true}) shows how two programs can be built
2344 from the same file, using different compilation parameters. It
2345 contains some technical digressions that are probably best skipped on
2349 * Complete:: A simple example, start to finish
2350 * true:: Building true and false
2355 @section A simple example, start to finish
2357 @cindex Complete example
2359 Let's suppose you just finished writing @code{zardoz}, a program to make
2360 your head float from vortex to vortex. You've been using Autoconf to
2361 provide a portability framework, but your @file{Makefile.in}s have been
2362 ad-hoc. You want to make them bulletproof, so you turn to Automake.
2364 @cindex @code{AM_INIT_AUTOMAKE}, example use
2366 The first step is to update your @file{configure.ac} to include the
2367 commands that @command{automake} needs. The way to do this is to add an
2368 @code{AM_INIT_AUTOMAKE} call just after @code{AC_INIT}:
2371 AC_INIT([zardoz], [1.0])
2376 Since your program doesn't have any complicating factors (e.g., it
2377 doesn't use @code{gettext}, it doesn't want to build a shared library),
2378 you're done with this part. That was easy!
2380 @cindex @command{aclocal} program, introduction
2381 @cindex @file{aclocal.m4}, preexisting
2382 @cindex @file{acinclude.m4}, defined
2384 Now you must regenerate @file{configure}. But to do that, you'll need
2385 to tell @command{autoconf} how to find the new macro you've used. The
2386 easiest way to do this is to use the @command{aclocal} program to
2387 generate your @file{aclocal.m4} for you. But wait@dots{} maybe you
2388 already have an @file{aclocal.m4}, because you had to write some hairy
2389 macros for your program. The @command{aclocal} program lets you put
2390 your own macros into @file{acinclude.m4}, so simply rename and then
2394 mv aclocal.m4 acinclude.m4
2399 @cindex @command{zardoz} example
2401 Now it is time to write your @file{Makefile.am} for @code{zardoz}.
2402 Since @code{zardoz} is a user program, you want to install it where the
2403 rest of the user programs go: @code{bindir}. Additionally,
2404 @code{zardoz} has some Texinfo documentation. Your @file{configure.ac}
2405 script uses @code{AC_REPLACE_FUNCS}, so you need to link against
2406 @samp{$(LIBOBJS)}. So here's what you'd write:
2409 bin_PROGRAMS = zardoz
2410 zardoz_SOURCES = main.c head.c float.c vortex9.c gun.c
2411 zardoz_LDADD = $(LIBOBJS)
2413 info_TEXINFOS = zardoz.texi
2416 Now you can run @samp{automake --add-missing} to generate your
2417 @file{Makefile.in} and grab any auxiliary files you might need, and
2422 @section Building true and false
2424 @cindex Example, @command{false} and @command{true}
2425 @cindex @command{false} Example
2426 @cindex @command{true} Example
2428 Here is another, trickier example. It shows how to generate two
2429 programs (@code{true} and @code{false}) from the same source file
2430 (@file{true.c}). The difficult part is that each compilation of
2431 @file{true.c} requires different @code{cpp} flags.
2434 bin_PROGRAMS = true false
2436 false_LDADD = false.o
2439 $(COMPILE) -DEXIT_CODE=0 -c true.c
2442 $(COMPILE) -DEXIT_CODE=1 -o false.o -c true.c
2445 Note that there is no @code{true_SOURCES} definition. Automake will
2446 implicitly assume that there is a source file named @file{true.c}
2447 (@pxref{Default _SOURCES}), and
2448 define rules to compile @file{true.o} and link @file{true}. The
2449 @samp{true.o: true.c} rule supplied by the above @file{Makefile.am},
2450 will override the Automake generated rule to build @file{true.o}.
2452 @code{false_SOURCES} is defined to be empty---that way no implicit value
2453 is substituted. Because we have not listed the source of
2454 @file{false}, we have to tell Automake how to link the program. This is
2455 the purpose of the @code{false_LDADD} line. A @code{false_DEPENDENCIES}
2456 variable, holding the dependencies of the @file{false} target will be
2457 automatically generated by Automake from the content of
2460 The above rules won't work if your compiler doesn't accept both
2461 @option{-c} and @option{-o}. The simplest fix for this is to introduce a
2462 bogus dependency (to avoid problems with a parallel @command{make}):
2465 true.o: true.c false.o
2466 $(COMPILE) -DEXIT_CODE=0 -c true.c
2469 $(COMPILE) -DEXIT_CODE=1 -c true.c && mv true.o false.o
2472 As it turns out, there is also a much easier way to do this same task.
2473 Some of the above technique is useful enough that we've kept the
2474 example in the manual. However if you were to build @code{true} and
2475 @code{false} in real life, you would probably use per-program
2476 compilation flags, like so:
2478 @c Keep in sync with specflg7.sh and specflg8.sh
2480 bin_PROGRAMS = false true
2482 false_SOURCES = true.c
2483 false_CPPFLAGS = -DEXIT_CODE=1
2485 true_SOURCES = true.c
2486 true_CPPFLAGS = -DEXIT_CODE=0
2489 In this case Automake will cause @file{true.c} to be compiled twice,
2490 with different flags. In this instance, the names of the object files
2491 would be chosen by automake; they would be @file{false-true.o} and
2492 @file{true-true.o}. (The name of the object files rarely matters.)
2494 @node automake Invocation
2495 @chapter Creating a @file{Makefile.in}
2496 @c This node used to be named "Invoking automake". This @anchor
2497 @c allows old links to still work.
2498 @anchor{Invoking automake}
2500 @cindex Multiple @file{configure.ac} files
2501 @cindex Invoking @command{automake}
2502 @cindex @command{automake}, invoking
2503 @cindex Invocation of @command{automake}
2504 @cindex @command{automake}, invocation
2506 To create all the @file{Makefile.in}s for a package, run the
2507 @command{automake} program in the top level directory, with no
2508 arguments. @command{automake} will automatically find each
2509 appropriate @file{Makefile.am} (by scanning @file{configure.ac};
2510 @pxref{configure}) and generate the corresponding @file{Makefile.in}.
2511 Note that @command{automake} has a rather simplistic view of what
2512 constitutes a package; it assumes that a package has only one
2513 @file{configure.ac}, at the top. If your package has multiple
2514 @file{configure.ac}s, then you must run @command{automake} in each
2515 directory holding a @file{configure.ac}. (Alternatively, you may rely
2516 on Autoconf's @command{autoreconf}, which is able to recurse your
2517 package tree and run @command{automake} where appropriate.)
2519 You can optionally give @command{automake} an argument; @file{.am} is
2520 appended to the argument and the result is used as the name of the
2521 input file. This feature is generally only used to automatically
2522 rebuild an out-of-date @file{Makefile.in}. Note that
2523 @command{automake} must always be run from the topmost directory of a
2524 project, even if being used to regenerate the @file{Makefile.in} in
2525 some subdirectory. This is necessary because @command{automake} must
2526 scan @file{configure.ac}, and because @command{automake} uses the
2527 knowledge that a @file{Makefile.in} is in a subdirectory to change its
2528 behavior in some cases.
2531 Automake will run @command{autoconf} to scan @file{configure.ac} and
2532 its dependencies (i.e., @file{aclocal.m4} and any included file),
2533 therefore @command{autoconf} must be in your @env{PATH}. If there is
2534 an @env{AUTOCONF} variable in your environment it will be used
2535 instead of @command{autoconf}, this allows you to select a particular
2536 version of Autoconf. By the way, don't misunderstand this paragraph:
2537 @command{automake} runs @command{autoconf} to @strong{scan} your
2538 @file{configure.ac}, this won't build @file{configure} and you still
2539 have to run @command{autoconf} yourself for this purpose.
2541 @cindex @command{automake} options
2542 @cindex Options, @command{automake}
2543 @cindex Strictness, command line
2545 @command{automake} accepts the following options:
2547 @cindex Extra files distributed with Automake
2548 @cindex Files distributed with Automake
2549 @cindex @file{config.guess}
2553 @itemx --add-missing
2555 @opindex --add-missing
2556 Automake requires certain common files to exist in certain situations;
2557 for instance, @file{config.guess} is required if @file{configure.ac} invokes
2558 @code{AC_CANONICAL_HOST}. Automake is distributed with several of these
2559 files (@pxref{Auxiliary Programs}); this option will cause the missing
2560 ones to be automatically added to the package, whenever possible. In
2561 general if Automake tells you a file is missing, try using this option.
2562 By default Automake tries to make a symbolic link pointing to its own
2563 copy of the missing file; this can be changed with @option{--copy}.
2565 Many of the potentially-missing files are common scripts whose
2566 location may be specified via the @code{AC_CONFIG_AUX_DIR} macro.
2567 Therefore, @code{AC_CONFIG_AUX_DIR}'s setting affects whether a
2568 file is considered missing, and where the missing file is added
2571 In some strictness modes, additional files are installed, see @ref{Gnits}
2572 for more information.
2574 @item --libdir=@var{dir}
2576 Look for Automake data files in directory @var{dir} instead of in the
2577 installation directory. This is typically used for debugging.
2579 @item --print-libdir
2580 @opindex --print-libdir
2581 Print the path of the installation directory containing Automake-provided
2582 scripts and data files (like e.g., @file{texinfo.texi} and
2589 When used with @option{--add-missing}, causes installed files to be
2590 copied. The default is to make a symbolic link.
2594 @itemx --force-missing
2595 @opindex --force-missing
2596 When used with @option{--add-missing}, causes standard files to be reinstalled
2597 even if they already exist in the source tree. This involves removing
2598 the file from the source tree before creating the new symlink (or, with
2599 @option{--copy}, copying the new file).
2603 Set the global strictness to @option{foreign}. For more information, see
2608 Set the global strictness to @option{gnits}. For more information, see
2613 Set the global strictness to @option{gnu}. For more information, see
2614 @ref{Gnits}. This is the default strictness.
2618 Print a summary of the command line options and exit.
2621 @itemx --ignore-deps
2623 This disables the dependency tracking feature in generated
2624 @file{Makefile}s; see @ref{Dependencies}.
2626 @item --include-deps
2627 @opindex --include-deps
2628 This enables the dependency tracking feature. This feature is enabled
2629 by default. This option is provided for historical reasons only and
2630 probably should not be used.
2634 Ordinarily @command{automake} creates all @file{Makefile.in}s mentioned in
2635 @file{configure.ac}. This option causes it to only update those
2636 @file{Makefile.in}s that are out of date with respect to one of their
2640 @itemx --output-dir=@var{dir}
2642 @opindex --output-dir
2643 Put the generated @file{Makefile.in} in the directory @var{dir}.
2644 Ordinarily each @file{Makefile.in} is created in the directory of the
2645 corresponding @file{Makefile.am}. This option is deprecated and will be
2646 removed in a future release.
2652 Cause Automake to print information about which files are being read or
2657 Print the version number of Automake and exit.
2660 @itemx --warnings=@var{category}
2663 Output warnings falling in @var{category}. @var{category} can be
2667 warnings related to the GNU Coding Standards
2668 (@pxref{Top, , , standards, The GNU Coding Standards}).
2670 obsolete features or constructions
2672 user redefinitions of Automake rules or variables
2674 portability issues (e.g., use of @command{make} features that are
2675 known to be not portable)
2676 @item extra-portability
2677 extra portability issues related to obscure tools. One example of such
2678 a tool is the Microsoft @command{lib} archiver.
2680 weird syntax, unused variables, typos
2682 unsupported or incomplete features
2686 turn off all the warnings
2688 treat warnings as errors
2691 A category can be turned off by prefixing its name with @samp{no-}. For
2692 instance, @option{-Wno-syntax} will hide the warnings about unused
2695 The categories output by default are @samp{syntax} and
2696 @samp{unsupported}. Additionally, @samp{gnu} and @samp{portability}
2697 are enabled in @option{--gnu} and @option{--gnits} strictness.
2699 @c Checked by extra-portability.sh
2700 Turning off @samp{portability} will also turn off @samp{extra-portability},
2701 and similarly turning on @samp{extra-portability} will also turn on
2702 @samp{portability}. However, turning on @samp{portability} or turning
2703 off @samp{extra-portability} will not affect the other category.
2706 The environment variable @env{WARNINGS} can contain a comma separated
2707 list of categories to enable. It will be taken into account before the
2708 command-line switches, this way @option{-Wnone} will also ignore any
2709 warning category enabled by @env{WARNINGS}. This variable is also used
2710 by other tools like @command{autoconf}; unknown categories are ignored
2715 @vindex AUTOMAKE_JOBS
2716 If the environment variable @env{AUTOMAKE_JOBS} contains a positive
2717 number, it is taken as the maximum number of Perl threads to use in
2718 @command{automake} for generating multiple @file{Makefile.in} files
2719 concurrently. This is an experimental feature.
2723 @chapter Scanning @file{configure.ac}, using @command{aclocal}
2725 @cindex @file{configure.ac}, scanning
2726 @cindex Scanning @file{configure.ac}
2727 @cindex Using @command{aclocal}
2728 @cindex @command{aclocal}, using
2730 Automake scans the package's @file{configure.ac} to determine certain
2731 information about the package. Some @command{autoconf} macros are required
2732 and some variables must be defined in @file{configure.ac}. Automake
2733 will also use information from @file{configure.ac} to further tailor its
2736 Automake also supplies some Autoconf macros to make the maintenance
2737 easier. These macros can automatically be put into your
2738 @file{aclocal.m4} using the @command{aclocal} program.
2741 * Requirements:: Configuration requirements
2742 * Optional:: Other things Automake recognizes
2743 * aclocal Invocation:: Auto-generating aclocal.m4
2744 * Macros:: Autoconf macros supplied with Automake
2749 @section Configuration requirements
2751 @cindex Automake requirements
2752 @cindex Requirements of Automake
2754 @acindex AM_INIT_AUTOMAKE
2755 The one real requirement of Automake is that your @file{configure.ac}
2756 call @code{AM_INIT_AUTOMAKE}. This macro does several things that are
2757 required for proper Automake operation (@pxref{Macros}).
2759 Here are the other macros that Automake requires but which are not run
2760 by @code{AM_INIT_AUTOMAKE}:
2763 @item AC_CONFIG_FILES
2765 @acindex AC_CONFIG_FILES
2767 These two macros are usually invoked as follows near the end of
2768 @file{configure.ac}.
2782 Automake uses these to determine which files to create (@pxref{Output, ,
2783 Creating Output Files, autoconf, The Autoconf Manual}). A listed file
2784 is considered to be an Automake generated @file{Makefile} if there
2785 exists a file with the same name and the @file{.am} extension appended.
2786 Typically, @samp{AC_CONFIG_FILES([foo/Makefile])} will cause Automake to
2787 generate @file{foo/Makefile.in} if @file{foo/Makefile.am} exists.
2789 When using @code{AC_CONFIG_FILES} with multiple input files, as in
2792 AC_CONFIG_FILES([Makefile:top.in:Makefile.in:bot.in])
2796 @command{automake} will generate the first @file{.in} input file for
2797 which a @file{.am} file exists. If no such file exists the output
2798 file is not considered to be generated by Automake.
2800 Files created by @code{AC_CONFIG_FILES}, be they Automake
2801 @file{Makefile}s or not, are all removed by @samp{make distclean}.
2802 Their inputs are automatically distributed, unless they
2803 are the output of prior @code{AC_CONFIG_FILES} commands.
2804 Finally, rebuild rules are generated in the Automake @file{Makefile}
2805 existing in the subdirectory of the output file, if there is one, or
2806 in the top-level @file{Makefile} otherwise.
2808 The above machinery (cleaning, distributing, and rebuilding) works
2809 fine if the @code{AC_CONFIG_FILES} specifications contain only
2810 literals. If part of the specification uses shell variables,
2811 @command{automake} will not be able to fulfill this setup, and you will
2812 have to complete the missing bits by hand. For instance, on
2814 @c Keep in sync with output11.sh
2818 AC_CONFIG_FILES([output:$file],, [file=$file])
2822 @command{automake} will output rules to clean @file{output}, and
2823 rebuild it. However the rebuild rule will not depend on @file{input},
2824 and this file will not be distributed either. (You must add
2825 @samp{EXTRA_DIST = input} to your @file{Makefile.am} if @file{input} is a
2830 @c Keep in sync with output11.sh
2835 AC_CONFIG_FILES([$file:input],, [file=$file])
2836 AC_CONFIG_FILES([$file2],, [file2=$file2])
2840 will only cause @file{input} to be distributed. No file will be
2841 cleaned automatically (add @samp{DISTCLEANFILES = output out}
2842 yourself), and no rebuild rule will be output.
2844 Obviously @command{automake} cannot guess what value @samp{$file} is
2845 going to hold later when @file{configure} is run, and it cannot use
2846 the shell variable @samp{$file} in a @file{Makefile}. However, if you
2847 make reference to @samp{$file} as @samp{$@{file@}} (i.e., in a way
2848 that is compatible with @command{make}'s syntax) and furthermore use
2849 @code{AC_SUBST} to ensure that @samp{$@{file@}} is meaningful in a
2850 @file{Makefile}, then @command{automake} will be able to use
2851 @samp{$@{file@}} to generate all these rules. For instance, here is
2852 how the Automake package itself generates versioned scripts for its
2856 AC_SUBST([APIVERSION], @dots{})
2859 [tests/aclocal-$@{APIVERSION@}:tests/aclocal.in],
2860 [chmod +x tests/aclocal-$@{APIVERSION@}],
2861 [APIVERSION=$APIVERSION])
2863 [tests/automake-$@{APIVERSION@}:tests/automake.in],
2864 [chmod +x tests/automake-$@{APIVERSION@}])
2868 Here cleaning, distributing, and rebuilding are done automatically,
2869 because @samp{$@{APIVERSION@}} is known at @command{make}-time.
2871 Note that you should not use shell variables to declare
2872 @file{Makefile} files for which @command{automake} must create
2873 @file{Makefile.in}. Even @code{AC_SUBST} does not help here, because
2874 @command{automake} needs to know the file name when it runs in order
2875 to check whether @file{Makefile.am} exists. (In the very hairy case
2876 that your setup requires such use of variables, you will have to tell
2877 Automake which @file{Makefile.in}s to generate on the command-line.)
2879 It is possible to let @command{automake} emit conditional rules for
2880 @code{AC_CONFIG_FILES} with the help of @code{AM_COND_IF}
2886 Use literals for @file{Makefile}s, and for other files whenever possible.
2888 Use @samp{$file} (or @samp{$@{file@}} without @samp{AC_SUBST([file])})
2889 for files that @command{automake} should ignore.
2891 Use @samp{$@{file@}} and @samp{AC_SUBST([file])} for files
2892 that @command{automake} should not ignore.
2899 @section Other things Automake recognizes
2901 @cindex Macros Automake recognizes
2902 @cindex Recognized macros by Automake
2904 Every time Automake is run it calls Autoconf to trace
2905 @file{configure.ac}. This way it can recognize the use of certain
2906 macros and tailor the generated @file{Makefile.in} appropriately.
2907 Currently recognized macros and their effects are:
2910 @item AC_CANONICAL_BUILD
2911 @itemx AC_CANONICAL_HOST
2912 @itemx AC_CANONICAL_TARGET
2913 @vindex build_triplet
2914 @vindex host_triplet
2915 @vindex target_triplet
2916 Automake will ensure that @file{config.guess} and @file{config.sub}
2917 exist. Also, the @file{Makefile} variables @code{build_triplet},
2918 @code{host_triplet} and @code{target_triplet} are introduced. See
2919 @ref{Canonicalizing, , Getting the Canonical System Type, autoconf,
2920 The Autoconf Manual}.
2922 @item AC_CONFIG_AUX_DIR
2923 Automake will look for various helper scripts, such as
2924 @file{install-sh}, in the directory named in this macro invocation.
2925 @c This list is accurate relative to version 1.11
2926 (The full list of scripts is:
2928 @file{config.guess},
2937 @file{mkinstalldirs},
2942 Not all scripts are always searched for; some scripts
2943 will only be sought if the generated @file{Makefile.in} requires them.
2945 If @code{AC_CONFIG_AUX_DIR} is not given, the scripts are looked for in
2946 their standard locations. For @file{mdate-sh},
2947 @file{texinfo.tex}, and @file{ylwrap}, the standard location is the
2948 source directory corresponding to the current @file{Makefile.am}. For
2949 the rest, the standard location is the first one of @file{.}, @file{..},
2950 or @file{../..} (relative to the top source directory) that provides any
2951 one of the helper scripts. @xref{Input, , Finding `configure' Input,
2952 autoconf, The Autoconf Manual}.
2954 Required files from @code{AC_CONFIG_AUX_DIR} are automatically
2955 distributed, even if there is no @file{Makefile.am} in this directory.
2957 @item AC_CONFIG_LIBOBJ_DIR
2958 Automake will require the sources file declared with
2959 @code{AC_LIBSOURCE} (see below) in the directory specified by this
2962 @item AC_CONFIG_HEADERS
2963 Automake will generate rules to rebuild these headers. Older versions
2964 of Automake required the use of @code{AM_CONFIG_HEADER}; this is no
2965 longer the case, and that macro has indeed been removed.
2967 As with @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the
2968 specification using shell variables will be ignored as far as
2969 cleaning, distributing, and rebuilding is concerned.
2971 @item AC_CONFIG_LINKS
2972 Automake will generate rules to remove @file{configure} generated
2973 links on @samp{make distclean} and to distribute named source files as
2974 part of @samp{make dist}.
2976 As for @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the
2977 specification using shell variables will be ignored as far as cleaning
2978 and distributing is concerned. (There are no rebuild rules for links.)
2982 @itemx AC_LIBSOURCES
2984 Automake will automatically distribute any file listed in
2985 @code{AC_LIBSOURCE} or @code{AC_LIBSOURCES}.
2987 Note that the @code{AC_LIBOBJ} macro calls @code{AC_LIBSOURCE}. So if
2988 an Autoconf macro is documented to call @samp{AC_LIBOBJ([file])}, then
2989 @file{file.c} will be distributed automatically by Automake. This
2990 encompasses many macros like @code{AC_FUNC_ALLOCA},
2991 @code{AC_FUNC_MEMCMP}, @code{AC_REPLACE_FUNCS}, and others.
2993 By the way, direct assignments to @code{LIBOBJS} are no longer
2994 supported. You should always use @code{AC_LIBOBJ} for this purpose.
2995 @xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs.@: @code{LIBOBJS},
2996 autoconf, The Autoconf Manual}.
2998 @item AC_PROG_RANLIB
2999 This is required if any libraries are built in the package.
3000 @xref{Particular Programs, , Particular Program Checks, autoconf, The
3004 This is required if any C++ source is included. @xref{Particular
3005 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
3008 This is required if any Objective C source is included. @xref{Particular
3009 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
3012 This is required if any Fortran 77 source is included. @xref{Particular
3013 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
3015 @item AC_F77_LIBRARY_LDFLAGS
3016 This is required for programs and shared libraries that are a mixture of
3017 languages that include Fortran 77 (@pxref{Mixing Fortran 77 With C and
3018 C++}). @xref{Macros, , Autoconf macros supplied with Automake}.
3021 Automake will add the flags computed by @code{AC_FC_SRCEXT} to compilation
3022 of files with the respective source extension (@pxref{Fortran Compiler, ,
3023 Fortran Compiler Characteristics, autoconf, The Autoconf Manual}).
3026 This is required if any Fortran 90/95 source is included. This macro is
3027 distributed with Autoconf version 2.58 and later. @xref{Particular
3028 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
3030 @item AC_PROG_LIBTOOL
3031 Automake will turn on processing for @command{libtool} (@pxref{Top, ,
3032 Introduction, libtool, The Libtool Manual}).
3036 If a Yacc source file is seen, then you must either use this macro or
3037 define the variable @code{YACC} in @file{configure.ac}. The former is
3038 preferred (@pxref{Particular Programs, , Particular Program Checks,
3039 autoconf, The Autoconf Manual}).
3042 If a Lex source file is seen, then this macro must be used.
3043 @xref{Particular Programs, , Particular Program Checks, autoconf, The
3046 @item AC_REQUIRE_AUX_FILE
3047 For each @code{AC_REQUIRE_AUX_FILE([@var{file}])},
3048 @command{automake} will ensure that @file{@var{file}} exists in the
3049 aux directory, and will complain otherwise. It
3050 will also automatically distribute the file. This macro should be
3051 used by third-party Autoconf macros that require some supporting
3052 files in the aux directory specified with @code{AC_CONFIG_AUX_DIR}
3053 above. @xref{Input, , Finding @command{configure} Input, autoconf,
3054 The Autoconf Manual}.
3057 The first argument is automatically defined as a variable in each
3058 generated @file{Makefile.in}, unless @code{AM_SUBST_NOTMAKE} is also
3059 used for this variable. @xref{Setting Output Variables, , Setting
3060 Output Variables, autoconf, The Autoconf Manual}.
3062 For every substituted variable @var{var}, @command{automake} will add
3063 a line @code{@var{var} = @var{value}} to each @file{Makefile.in} file.
3064 Many Autoconf macros invoke @code{AC_SUBST} to set output variables
3065 this way, e.g., @code{AC_PATH_XTRA} defines @code{X_CFLAGS} and
3066 @code{X_LIBS}. Thus, you can access these variables as
3067 @code{$(X_CFLAGS)} and @code{$(X_LIBS)} in any @file{Makefile.am}
3068 if @code{AC_PATH_XTRA} is called.
3070 @item AM_CONDITIONAL
3071 This introduces an Automake conditional (@pxref{Conditionals}).
3074 This macro allows @code{automake} to detect subsequent access within
3075 @file{configure.ac} to a conditional previously introduced with
3076 @code{AM_CONDITIONAL}, thus enabling conditional @code{AC_CONFIG_FILES}
3077 (@pxref{Usage of Conditionals}).
3079 @item AM_GNU_GETTEXT
3080 This macro is required for packages that use GNU gettext
3081 (@pxref{gettext}). It is distributed with gettext. If Automake sees
3082 this macro it ensures that the package meets some of gettext's
3085 @item AM_GNU_GETTEXT_INTL_SUBDIR
3086 This macro specifies that the @file{intl/} subdirectory is to be built,
3087 even if the @code{AM_GNU_GETTEXT} macro was invoked with a first argument
3090 @item AM_MAINTAINER_MODE(@ovar{default-mode})
3091 @opindex --enable-maintainer-mode
3092 @opindex --disable-maintainer-mode
3093 This macro adds an @option{--enable-maintainer-mode} option to
3094 @command{configure}. If this is used, @command{automake} will cause
3095 ``maintainer-only'' rules to be turned off by default in the
3096 generated @file{Makefile.in}s, unless @var{default-mode} is
3097 @samp{enable}. This macro defines the @code{MAINTAINER_MODE}
3098 conditional, which you can use in your own @file{Makefile.am}.
3099 @xref{maintainer-mode}.
3101 @item AM_SUBST_NOTMAKE(@var{var})
3102 Prevent Automake from defining a variable @var{var}, even if it is
3103 substituted by @command{config.status}. Normally, Automake defines a
3104 @command{make} variable for each @command{configure} substitution,
3105 i.e., for each @code{AC_SUBST([@var{var}])}. This macro prevents that
3106 definition from Automake. If @code{AC_SUBST} has not been called
3107 for this variable, then @code{AM_SUBST_NOTMAKE} has no effects.
3108 Preventing variable definitions may be useful for substitution of
3109 multi-line values, where @code{@var{var} = @@@var{value}@@} might yield
3113 Files included by @file{configure.ac} using this macro will be
3114 detected by Automake and automatically distributed. They will also
3115 appear as dependencies in @file{Makefile} rules.
3117 @code{m4_include} is seldom used by @file{configure.ac} authors, but
3118 can appear in @file{aclocal.m4} when @command{aclocal} detects that
3119 some required macros come from files local to your package (as opposed to
3120 macros installed in a system-wide directory, @pxref{aclocal Invocation}).
3124 @node aclocal Invocation
3125 @section Auto-generating aclocal.m4
3126 @c This node used to be named "Invoking automake". This @anchor
3127 @c allows old links to still work.
3128 @anchor{Invoking aclocal}
3130 @cindex Invocation of @command{aclocal}
3131 @cindex @command{aclocal}, Invocation
3132 @cindex Invoking @command{aclocal}
3133 @cindex @command{aclocal}, Invoking
3135 Automake includes a number of Autoconf macros that can be used in
3136 your package (@pxref{Macros}); some of them are actually required by
3137 Automake in certain situations. These macros must be defined in your
3138 @file{aclocal.m4}; otherwise they will not be seen by
3141 The @command{aclocal} program will automatically generate
3142 @file{aclocal.m4} files based on the contents of @file{configure.ac}.
3143 This provides a convenient way to get Automake-provided macros,
3144 without having to search around. The @command{aclocal} mechanism
3145 allows other packages to supply their own macros (@pxref{Extending
3146 aclocal}). You can also use it to maintain your own set of custom
3147 macros (@pxref{Local Macros}).
3149 At startup, @command{aclocal} scans all the @file{.m4} files it can
3150 find, looking for macro definitions (@pxref{Macro Search Path}). Then
3151 it scans @file{configure.ac}. Any mention of one of the macros found
3152 in the first step causes that macro, and any macros it in turn
3153 requires, to be put into @file{aclocal.m4}.
3155 @emph{Putting} the file that contains the macro definition into
3156 @file{aclocal.m4} is usually done by copying the entire text of this
3157 file, including unused macro definitions as well as both @samp{#} and
3158 @samp{dnl} comments. If you want to make a comment that will be
3159 completely ignored by @command{aclocal}, use @samp{##} as the comment
3162 When a file selected by @command{aclocal} is located in a subdirectory
3163 specified as a relative search path with @command{aclocal}'s @option{-I}
3164 argument, @command{aclocal} assumes the file belongs to the package
3165 and uses @code{m4_include} instead of copying it into
3166 @file{aclocal.m4}. This makes the package smaller, eases dependency
3167 tracking, and cause the file to be distributed automatically.
3168 (@xref{Local Macros}, for an example.) Any macro that is found in a
3169 system-wide directory, or via an absolute search path will be copied.
3170 So use @samp{-I `pwd`/reldir} instead of @samp{-I reldir} whenever
3171 some relative directory should be considered outside the package.
3173 The contents of @file{acinclude.m4}, if this file exists, are also
3174 automatically included in @file{aclocal.m4}. We recommend against
3175 using @file{acinclude.m4} in new packages (@pxref{Local Macros}).
3179 While computing @file{aclocal.m4}, @command{aclocal} runs
3180 @command{autom4te} (@pxref{Using autom4te, , Using @command{Autom4te},
3181 autoconf, The Autoconf Manual}) in order to trace the macros that are
3182 really used, and omit from @file{aclocal.m4} all macros that are
3183 mentioned but otherwise unexpanded (this can happen when a macro is
3184 called conditionally). @command{autom4te} is expected to be in the
3185 @env{PATH}, just as @command{autoconf}. Its location can be
3186 overridden using the @env{AUTOM4TE} environment variable.
3189 * aclocal Options:: Options supported by aclocal
3190 * Macro Search Path:: How aclocal finds .m4 files
3191 * Extending aclocal:: Writing your own aclocal macros
3192 * Local Macros:: Organizing local macros
3193 * Serials:: Serial lines in Autoconf macros
3194 * Future of aclocal:: aclocal's scheduled death
3197 @node aclocal Options
3198 @subsection aclocal Options
3200 @cindex @command{aclocal}, Options
3201 @cindex Options, @command{aclocal}
3203 @command{aclocal} accepts the following options:
3206 @item --automake-acdir=@var{dir}
3207 @opindex --automake-acdir
3208 Look for the automake-provided macro files in @var{dir} instead of
3209 in the installation directory. This is typically used for debugging.
3211 @item --system-acdir=@var{dir}
3212 @opindex --system-acdir
3213 Look for the system-wide third-party macro files (and the special
3214 @file{dirlist} file) in @var{dir} instead of in the installation
3215 directory. This is typically used for debugging.
3217 @item --diff[=@var{command}]
3219 Run @var{command} on M4 file that would be installed or overwritten
3220 by @option{--install}. The default @var{command} is @samp{diff -u}.
3221 This option implies @option{--install} and @option{--dry-run}.
3225 Do not actually overwrite (or create) @file{aclocal.m4} and M4
3226 files installed by @option{--install}.
3230 Print a summary of the command line options and exit.
3234 Add the directory @var{dir} to the list of directories searched for
3239 Install system-wide third-party macros into the first directory
3240 specified with @samp{-I @var{dir}} instead of copying them in the
3242 @c Keep in sync with aclocal-install-absdir.sh
3243 Note that this will happen also if @var{dir} is an absolute path.
3245 @cindex serial number and @option{--install}
3246 When this option is used, and only when this option is used,
3247 @command{aclocal} will also honor @samp{#serial @var{number}} lines
3248 that appear in macros: an M4 file is ignored if there exists another
3249 M4 file with the same basename and a greater serial number in the
3250 search path (@pxref{Serials}).
3254 Always overwrite the output file. The default is to overwrite the output
3255 file only when really needed, i.e., when its contents changes or if one
3256 of its dependencies is younger.
3258 This option forces the update of @file{aclocal.m4} (or the file
3259 specified with @file{--output} below) and only this file, it has
3260 absolutely no influence on files that may need to be installed by
3263 @item --output=@var{file}
3265 Cause the output to be put into @var{file} instead of @file{aclocal.m4}.
3267 @item --print-ac-dir
3268 @opindex --print-ac-dir
3269 Prints the name of the directory that @command{aclocal} will search to
3270 find third-party @file{.m4} files. When this option is given, normal
3271 processing is suppressed. This option was used @emph{in the past} by
3272 third-party packages to determine where to install @file{.m4} macro
3273 files, but @emph{this usage is today discouraged}, since it causes
3274 @samp{$(prefix)} not to be thoroughly honoured (which violates the
3275 GNU Coding Standards), and a similar semantics can be better obtained
3276 with the @env{ACLOCAL_PATH} environment variable; @pxref{Extending aclocal}.
3280 Print the names of the files it examines.
3284 Print the version number of Automake and exit.
3287 @item --warnings=@var{category}
3290 Output warnings falling in @var{category}. @var{category} can be
3294 dubious syntactic constructs, underquoted macros, unused macros, etc.
3298 all the warnings, this is the default
3300 turn off all the warnings
3302 treat warnings as errors
3305 All warnings are output by default.
3308 The environment variable @env{WARNINGS} is honored in the same
3309 way as it is for @command{automake} (@pxref{automake Invocation}).
3313 @node Macro Search Path
3314 @subsection Macro Search Path
3316 @cindex Macro search path
3317 @cindex @command{aclocal} search path
3319 By default, @command{aclocal} searches for @file{.m4} files in the following
3320 directories, in this order:
3323 @item @var{acdir-APIVERSION}
3324 This is where the @file{.m4} macros distributed with Automake itself
3325 are stored. @var{APIVERSION} depends on the Automake release used;
3326 for example, for Automake 1.11.x, @var{APIVERSION} = @code{1.11}.
3329 This directory is intended for third party @file{.m4} files, and is
3330 configured when @command{automake} itself is built. This is
3331 @file{@@datadir@@/aclocal/}, which typically
3332 expands to @file{$@{prefix@}/share/aclocal/}. To find the compiled-in
3333 value of @var{acdir}, use the @option{--print-ac-dir} option
3334 (@pxref{aclocal Options}).
3337 As an example, suppose that @command{automake-1.11.2} was configured with
3338 @option{--prefix=@-/usr/local}. Then, the search path would be:
3341 @item @file{/usr/local/share/aclocal-1.11.2/}
3342 @item @file{/usr/local/share/aclocal/}
3345 The paths for the @var{acdir} and @var{acdir-APIVERSION} directories can
3346 be changed respectively through aclocal options @option{--system-acdir}
3347 and @option{--automake-acdir} (@pxref{aclocal Options}). Note however
3348 that these options are only intended for use by the internal Automake
3349 test suite, or for debugging under highly unusual situations; they are
3350 not ordinarily needed by end-users.
3352 As explained in (@pxref{aclocal Options}), there are several options that
3353 can be used to change or extend this search path.
3355 @subsubheading Modifying the Macro Search Path: @samp{-I @var{dir}}
3357 Any extra directories specified using @option{-I} options
3358 (@pxref{aclocal Options}) are @emph{prepended} to this search list. Thus,
3359 @samp{aclocal -I /foo -I /bar} results in the following search path:
3364 @item @var{acdir}-@var{APIVERSION}
3368 @subsubheading Modifying the Macro Search Path: @file{dirlist}
3369 @cindex @file{dirlist}
3371 There is a third mechanism for customizing the search path. If a
3372 @file{dirlist} file exists in @var{acdir}, then that file is assumed to
3373 contain a list of directory patterns, one per line. @command{aclocal}
3374 expands these patterns to directory names, and adds them to the search
3375 list @emph{after} all other directories. @file{dirlist} entries may
3376 use shell wildcards such as @samp{*}, @samp{?}, or @code{[...]}.
3378 For example, suppose
3379 @file{@var{acdir}/dirlist} contains the following:
3388 and that @command{aclocal} was called with the @samp{-I /foo -I /bar} options.
3389 Then, the search path would be
3391 @c @code looks better than @file here
3395 @item @var{acdir}-@var{APIVERSION}
3402 and all directories with path names starting with @code{/test3}.
3404 If the @option{--system-acdir=@var{dir}} option is used, then
3405 @command{aclocal} will search for the @file{dirlist} file in
3406 @var{dir}; but remember the warnings above against the use of
3407 @option{--system-acdir}.
3409 @file{dirlist} is useful in the following situation: suppose that
3410 @command{automake} version @code{1.11.2} is installed with
3411 @samp{--prefix=/usr} by the system vendor. Thus, the default search
3414 @c @code looks better than @file here
3416 @item @code{/usr/share/aclocal-1.11/}
3417 @item @code{/usr/share/aclocal/}
3420 However, suppose further that many packages have been manually
3421 installed on the system, with $prefix=/usr/local, as is typical. In
3422 that case, many of these ``extra'' @file{.m4} files are in
3423 @file{/usr/local/share/aclocal}. The only way to force
3424 @file{/usr/bin/aclocal} to find these ``extra'' @file{.m4} files is to
3425 always call @samp{aclocal -I /usr/local/share/aclocal}. This is
3426 inconvenient. With @file{dirlist}, one may create a file
3427 @file{/usr/share/aclocal/dirlist} containing only the single line
3430 /usr/local/share/aclocal
3433 Now, the ``default'' search path on the affected system is
3435 @c @code looks better than @file here
3437 @item @code{/usr/share/aclocal-1.11/}
3438 @item @code{/usr/share/aclocal/}
3439 @item @code{/usr/local/share/aclocal/}
3442 without the need for @option{-I} options; @option{-I} options can be reserved
3443 for project-specific needs (@file{my-source-dir/m4/}), rather than
3444 using it to work around local system-dependent tool installation
3447 Similarly, @file{dirlist} can be handy if you have installed a local
3448 copy of Automake in your account and want @command{aclocal} to look for
3449 macros installed at other places on the system.
3451 @anchor{ACLOCAL_PATH}
3452 @subsubheading Modifying the Macro Search Path: @file{ACLOCAL_PATH}
3453 @cindex @env{ACLOCAL_PATH}
3455 The fourth and last mechanism to customize the macro search path is
3456 also the simplest. Any directory included in the colon-separated
3457 environment variable @env{ACLOCAL_PATH} is added to the search path
3458 @c Keep in sync with aclocal-path-precedence.sh
3459 and takes precedence over system directories (including those found via
3460 @file{dirlist}), with the exception of the versioned directory
3461 @var{acdir-APIVERSION} (@pxref{Macro Search Path}). However, directories
3462 passed via @option{-I} will take precedence over directories in
3465 @c Keep in sync with aclocal-path-installed.sh
3466 Also note that, if the @option{--install} option is used, any @file{.m4}
3467 file containing a required macro that is found in a directory listed in
3468 @env{ACLOCAL_PATH} will be installed locally.
3469 @c Keep in sync with aclocal-path-installed-serial.sh
3470 In this case, serial numbers in @file{.m4} are honoured too,
3473 Conversely to @file{dirlist}, @env{ACLOCAL_PATH} is useful if you are
3474 using a global copy of Automake and want @command{aclocal} to look for
3475 macros somewhere under your home directory.
3477 @subsubheading Planned future incompatibilities
3479 The order in which the directories in the macro search path are currently
3480 looked up is confusing and/or suboptimal in various aspects, and is
3481 probably going to be changed in the future Automake release. In
3482 particular, directories in @env{ACLOCAL_PATH} and @file{@var{acdir}}
3483 might end up taking precedence over @file{@var{acdir-APIVERSION}}, and
3484 directories in @file{@var{acdir}/dirlist} might end up taking precedence
3485 over @file{@var{acdir}}. @emph{This is a possible future incompatibility!}
3487 @node Extending aclocal
3488 @subsection Writing your own aclocal macros
3490 @cindex @command{aclocal}, extending
3491 @cindex Extending @command{aclocal}
3493 The @command{aclocal} program doesn't have any built-in knowledge of any
3494 macros, so it is easy to extend it with your own macros.
3496 This can be used by libraries that want to supply their own Autoconf
3497 macros for use by other programs. For instance, the @command{gettext}
3498 library supplies a macro @code{AM_GNU_GETTEXT} that should be used by
3499 any package using @command{gettext}. When the library is installed, it
3500 installs this macro so that @command{aclocal} will find it.
3502 A macro file's name should end in @file{.m4}. Such files should be
3503 installed in @file{$(datadir)/aclocal}. This is as simple as writing:
3505 @c Keep in sync with primary-prefix-couples-documented-valid.sh
3507 aclocaldir = $(datadir)/aclocal
3508 aclocal_DATA = mymacro.m4 myothermacro.m4
3512 Please do use @file{$(datadir)/aclocal}, and not something based on
3513 the result of @samp{aclocal --print-ac-dir} (@pxref{Hard-Coded Install
3514 Paths}, for arguments). It might also be helpful to suggest to
3515 the user to add the @file{$(datadir)/aclocal} directory to his
3516 @env{ACLOCAL_PATH} variable (@pxref{ACLOCAL_PATH}) so that
3517 @command{aclocal} will find the @file{.m4} files installed by your
3518 package automatically.
3520 A file of macros should be a series of properly quoted
3521 @code{AC_DEFUN}'s (@pxref{Macro Definitions, , , autoconf, The
3522 Autoconf Manual}). The @command{aclocal} programs also understands
3523 @code{AC_REQUIRE} (@pxref{Prerequisite Macros, , , autoconf, The
3524 Autoconf Manual}), so it is safe to put each macro in a separate file.
3525 Each file should have no side effects but macro definitions.
3526 Especially, any call to @code{AC_PREREQ} should be done inside the
3527 defined macro, not at the beginning of the file.
3529 @cindex underquoted @code{AC_DEFUN}
3533 Starting with Automake 1.8, @command{aclocal} will warn about all
3534 underquoted calls to @code{AC_DEFUN}. We realize this will annoy a
3535 lot of people, because @command{aclocal} was not so strict in the past
3536 and many third party macros are underquoted; and we have to apologize
3537 for this temporary inconvenience. The reason we have to be stricter
3538 is that a future implementation of @command{aclocal} (@pxref{Future of
3539 aclocal}) will have to temporarily include all these third party
3540 @file{.m4} files, maybe several times, including even files that are
3541 not actually needed. Doing so should alleviate many problems of the
3542 current implementation, however it requires a stricter style from the
3543 macro authors. Hopefully it is easy to revise the existing macros.
3550 [AC_REQUIRE([AX_SOMETHING])dnl
3557 should be rewritten as
3560 AC_DEFUN([AX_FOOBAR],
3561 [AC_PREREQ([2.68])dnl
3562 AC_REQUIRE([AX_SOMETHING])dnl
3568 Wrapping the @code{AC_PREREQ} call inside the macro ensures that
3569 Autoconf 2.68 will not be required if @code{AX_FOOBAR} is not actually
3570 used. Most importantly, quoting the first argument of @code{AC_DEFUN}
3571 allows the macro to be redefined or included twice (otherwise this
3572 first argument would be expanded during the second definition). For
3573 consistency we like to quote even arguments such as @code{2.68} that
3576 If you have been directed here by the @command{aclocal} diagnostic but
3577 are not the maintainer of the implicated macro, you will want to
3578 contact the maintainer of that macro. Please make sure you have the
3579 latest version of the macro and that the problem hasn't already been
3580 reported before doing so: people tend to work faster when they aren't
3583 Another situation where @command{aclocal} is commonly used is to
3584 manage macros that are used locally by the package, @ref{Local
3588 @subsection Handling Local Macros
3590 Feature tests offered by Autoconf do not cover all needs. People
3591 often have to supplement existing tests with their own macros, or
3592 with third-party macros.
3594 There are two ways to organize custom macros in a package.
3596 The first possibility (the historical practice) is to list all your
3597 macros in @file{acinclude.m4}. This file will be included in
3598 @file{aclocal.m4} when you run @command{aclocal}, and its macro(s) will
3599 henceforth be visible to @command{autoconf}. However if it contains
3600 numerous macros, it will rapidly become difficult to maintain, and it
3601 will be almost impossible to share macros between packages.
3603 @vindex ACLOCAL_AMFLAGS
3604 The second possibility, which we do recommend, is to write each macro
3605 in its own file and gather all these files in a directory. This
3606 directory is usually called @file{m4/}. To build @file{aclocal.m4},
3607 one should therefore instruct @command{aclocal} to scan @file{m4/}.
3608 From the command line, this is done with @samp{aclocal -I m4}. The
3609 top-level @file{Makefile.am} should also be updated to define
3612 ACLOCAL_AMFLAGS = -I m4
3615 @code{ACLOCAL_AMFLAGS} contains options to pass to @command{aclocal}
3616 when @file{aclocal.m4} is to be rebuilt by @command{make}. This line is
3617 also used by @command{autoreconf} (@pxref{autoreconf Invocation, ,
3618 Using @command{autoreconf} to Update @file{configure} Scripts,
3619 autoconf, The Autoconf Manual}) to run @command{aclocal} with suitable
3620 options, or by @command{autopoint} (@pxref{autopoint Invocation, ,
3621 Invoking the @command{autopoint} Program, gettext, GNU gettext tools})
3622 and @command{gettextize} (@pxref{gettextize Invocation, , Invoking the
3623 @command{gettextize} Program, gettext, GNU gettext tools}) to locate
3624 the place where Gettext's macros should be installed. So even if you
3625 do not really care about the rebuild rules, you should define
3626 @code{ACLOCAL_AMFLAGS}.
3628 When @samp{aclocal -I m4} is run, it will build an @file{aclocal.m4}
3629 that @code{m4_include}s any file from @file{m4/} that defines a
3630 required macro. Macros not found locally will still be searched in
3631 system-wide directories, as explained in @ref{Macro Search Path}.
3633 Custom macros should be distributed for the same reason that
3634 @file{configure.ac} is: so that other people have all the sources of
3635 your package if they want to work on it. Actually, this distribution
3636 happens automatically because all @code{m4_include}d files are
3639 However there is no consensus on the distribution of third-party
3640 macros that your package may use. Many libraries install their own
3641 macro in the system-wide @command{aclocal} directory (@pxref{Extending
3642 aclocal}). For instance, Guile ships with a file called
3643 @file{guile.m4} that contains the macro @code{GUILE_FLAGS} that can
3644 be used to define setup compiler and linker flags appropriate for
3645 using Guile. Using @code{GUILE_FLAGS} in @file{configure.ac} will
3646 cause @command{aclocal} to copy @file{guile.m4} into
3647 @file{aclocal.m4}, but as @file{guile.m4} is not part of the project,
3648 it will not be distributed. Technically, that means a user who
3649 needs to rebuild @file{aclocal.m4} will have to install Guile first.
3650 This is probably OK, if Guile already is a requirement to build the
3651 package. However, if Guile is only an optional feature, or if your
3652 package might run on architectures where Guile cannot be installed,
3653 this requirement will hinder development. An easy solution is to copy
3654 such third-party macros in your local @file{m4/} directory so they get
3657 Since Automake 1.10, @command{aclocal} offers an option to copy these
3658 system-wide third-party macros in your local macro directory, solving
3659 the above problem. Simply use:
3662 ACLOCAL_AMFLAGS = -I m4 --install
3666 With this setup, system-wide macros will be copied to @file{m4/}
3667 the first time you run @command{autoreconf}. Then the locally
3668 installed macros will have precedence over the system-wide installed
3669 macros each time @command{aclocal} is run again.
3671 One reason why you should keep @option{--install} in the flags even
3672 after the first run is that when you later edit @file{configure.ac}
3673 and depend on a new macro, this macro will be installed in your
3674 @file{m4/} automatically. Another one is that serial numbers
3675 (@pxref{Serials}) can be used to update the macros in your source tree
3676 automatically when new system-wide versions are installed. A serial
3677 number should be a single line of the form
3684 where @var{nnn} contains only digits and dots. It should appear in
3685 the M4 file before any macro definition. It is a good practice to
3686 maintain a serial number for each macro you distribute, even if you do
3687 not use the @option{--install} option of @command{aclocal}: this allows
3688 other people to use it.
3692 @subsection Serial Numbers
3693 @cindex serial numbers in macros
3694 @cindex macro serial numbers
3695 @cindex @code{#serial} syntax
3696 @cindex @command{aclocal} and serial numbers
3698 Because third-party macros defined in @file{*.m4} files are naturally
3699 shared between multiple projects, some people like to version them.
3700 This makes it easier to tell which of two M4 files is newer. Since at
3701 least 1996, the tradition is to use a @samp{#serial} line for this.
3703 A serial number should be a single line of the form
3706 # serial @var{version}
3710 where @var{version} is a version number containing only digits and
3711 dots. Usually people use a single integer, and they increment it each
3712 time they change the macro (hence the name of ``serial''). Such a
3713 line should appear in the M4 file before any macro definition.
3715 The @samp{#} must be the first character on the line,
3716 and it is OK to have extra words after the version, as in
3719 #serial @var{version} @var{garbage}
3722 Normally these serial numbers are completely ignored by
3723 @command{aclocal} and @command{autoconf}, like any genuine comment.
3724 However when using @command{aclocal}'s @option{--install} feature, these
3725 serial numbers will modify the way @command{aclocal} selects the
3726 macros to install in the package: if two files with the same basename
3727 exist in your search path, and if at least one of them uses a
3728 @samp{#serial} line, @command{aclocal} will ignore the file that has
3729 the older @samp{#serial} line (or the file that has none).
3731 Note that a serial number applies to a whole M4 file, not to any macro
3732 it contains. A file can contains multiple macros, but only one
3735 Here is a use case that illustrates the use of @option{--install} and
3736 its interaction with serial numbers. Let's assume we maintain a
3737 package called MyPackage, the @file{configure.ac} of which requires a
3738 third-party macro @code{AX_THIRD_PARTY} defined in
3739 @file{/usr/share/aclocal/thirdparty.m4} as follows:
3743 AC_DEFUN([AX_THIRD_PARTY], [...])
3746 MyPackage uses an @file{m4/} directory to store local macros as
3747 explained in @ref{Local Macros}, and has
3750 ACLOCAL_AMFLAGS = -I m4 --install
3754 in its top-level @file{Makefile.am}.
3756 Initially the @file{m4/} directory is empty. The first time we run
3757 @command{autoreconf}, it will fetch the options to pass to
3758 @command{aclocal} in @file{Makefile.am}, and run @samp{aclocal -I m4
3759 --install}. @command{aclocal} will notice that
3763 @file{configure.ac} uses @code{AX_THIRD_PARTY}
3765 No local macros define @code{AX_THIRD_PARTY}
3767 @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3772 Because @file{/usr/share/aclocal/thirdparty.m4} is a system-wide macro
3773 and @command{aclocal} was given the @option{--install} option, it will
3774 copy this file in @file{m4/thirdparty.m4}, and output an
3775 @file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}.
3777 The next time @samp{aclocal -I m4 --install} is run (either via
3778 @command{autoreconf}, by hand, or from the @file{Makefile} rebuild
3779 rules) something different happens. @command{aclocal} notices that
3783 @file{configure.ac} uses @code{AX_THIRD_PARTY}
3785 @file{m4/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3788 @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3793 Because both files have the same serial number, @command{aclocal} uses
3794 the first it found in its search path order (@pxref{Macro Search
3795 Path}). @command{aclocal} therefore ignores
3796 @file{/usr/share/aclocal/thirdparty.m4} and outputs an
3797 @file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}.
3799 Local directories specified with @option{-I} are always searched before
3800 system-wide directories, so a local file will always be preferred to
3801 the system-wide file in case of equal serial numbers.
3803 Now suppose the system-wide third-party macro is changed. This can
3804 happen if the package installing this macro is updated. Let's suppose
3805 the new macro has serial number 2. The next time @samp{aclocal -I m4
3806 --install} is run the situation is the following:
3810 @file{configure.ac} uses @code{AX_THIRD_PARTY}
3812 @file{m4/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3815 @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3820 When @command{aclocal} sees a greater serial number, it immediately
3821 forgets anything it knows from files that have the same basename and a
3822 smaller serial number. So after it has found
3823 @file{/usr/share/aclocal/thirdparty.m4} with serial 2,
3824 @command{aclocal} will proceed as if it had never seen
3825 @file{m4/thirdparty.m4}. This brings us back to a situation similar
3826 to that at the beginning of our example, where no local file defined
3827 the macro. @command{aclocal} will install the new version of the
3828 macro in @file{m4/thirdparty.m4}, in this case overriding the old
3829 version. MyPackage just had its macro updated as a side effect of
3830 running @command{aclocal}.
3832 If you are leery of letting @command{aclocal} update your local macro,
3833 you can run @samp{aclocal -I m4 --diff} to review the changes
3834 @samp{aclocal -I m4 --install} would perform on these macros.
3836 Finally, note that the @option{--force} option of @command{aclocal} has
3837 absolutely no effect on the files installed by @option{--install}. For
3838 instance, if you have modified your local macros, do not expect
3839 @option{--install --force} to replace the local macros by their
3840 system-wide versions. If you want to do so, simply erase the local
3841 macros you want to revert, and run @samp{aclocal -I m4 --install}.
3844 @node Future of aclocal
3845 @subsection The Future of @command{aclocal}
3846 @cindex @command{aclocal}'s scheduled death
3848 @command{aclocal} is expected to disappear. This feature really
3849 should not be offered by Automake. Automake should focus on
3850 generating @file{Makefile}s; dealing with M4 macros really is
3851 Autoconf's job. The fact that some people install Automake just to use
3852 @command{aclocal}, but do not use @command{automake} otherwise is an
3853 indication of how that feature is misplaced.
3855 The new implementation will probably be done slightly differently.
3856 For instance, it could enforce the @file{m4/}-style layout discussed in
3859 We have no idea when and how this will happen. This has been
3860 discussed several times in the past, but someone still has to commit
3861 to that non-trivial task.
3863 From the user point of view, @command{aclocal}'s removal might turn
3864 out to be painful. There is a simple precaution that you may take to
3865 make that switch more seamless: never call @command{aclocal} yourself.
3866 Keep this guy under the exclusive control of @command{autoreconf} and
3867 Automake's rebuild rules. Hopefully you won't need to worry about
3868 things breaking, when @command{aclocal} disappears, because everything
3869 will have been taken care of. If otherwise you used to call
3870 @command{aclocal} directly yourself or from some script, you will
3871 quickly notice the change.
3873 Many packages come with a script called @file{bootstrap.sh} or
3874 @file{autogen.sh}, that will just call @command{aclocal},
3875 @command{libtoolize}, @command{gettextize} or @command{autopoint},
3876 @command{autoconf}, @command{autoheader}, and @command{automake} in
3877 the right order. Actually this is precisely what @command{autoreconf}
3878 can do for you. If your package has such a @file{bootstrap.sh} or
3879 @file{autogen.sh} script, consider using @command{autoreconf}. That
3880 should simplify its logic a lot (less things to maintain, yum!), it's
3881 even likely you will not need the script anymore, and more to the point
3882 you will not call @command{aclocal} directly anymore.
3884 For the time being, third-party packages should continue to install
3885 public macros into @file{/usr/share/aclocal/}. If @command{aclocal}
3886 is replaced by another tool it might make sense to rename the
3887 directory, but supporting @file{/usr/share/aclocal/} for backward
3888 compatibility should be really easy provided all macros are properly
3889 written (@pxref{Extending aclocal}).
3894 @section Autoconf macros supplied with Automake
3896 Automake ships with several Autoconf macros that you can use from your
3897 @file{configure.ac}. When you use one of them it will be included by
3898 @command{aclocal} in @file{aclocal.m4}.
3901 * Public Macros:: Macros that you can use.
3902 * Private Macros:: Macros that you should not use.
3905 @c consider generating the following subsections automatically from m4 files.
3908 @subsection Public Macros
3912 @item AM_INIT_AUTOMAKE([OPTIONS])
3913 @acindex AM_INIT_AUTOMAKE
3914 Runs many macros required for proper operation of the generated Makefiles.
3916 @vindex AUTOMAKE_OPTIONS
3917 Today, @code{AM_INIT_AUTOMAKE} is called with a single argument: a
3918 space-separated list of Automake options that should
3919 be applied to every @file{Makefile.am} in the tree. The effect is as if
3920 each option were listed in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
3923 This macro can also be called in @emph{another, deprecated form} (support
3924 for which will be @emph{removed in the next major Automake release}):
3925 @code{AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])}. In this form,
3926 there are two required arguments: the package and the version number.
3927 This form is obsolete because the @var{package} and @var{version} can
3928 be obtained from Autoconf's @code{AC_INIT} macro (which itself has an
3929 old and a new form).
3931 If your @file{configure.ac} has:
3934 AC_INIT([src/foo.c])
3935 AM_INIT_AUTOMAKE([mumble], [1.5])
3939 you should modernize it as follows:
3942 AC_INIT([mumble], [1.5])
3943 AC_CONFIG_SRCDIR([src/foo.c])
3947 Note that if you're upgrading your @file{configure.ac} from an earlier
3948 version of Automake, it is not always correct to simply move the
3949 package and version arguments from @code{AM_INIT_AUTOMAKE} directly to
3950 @code{AC_INIT}, as in the example above. The first argument to
3951 @code{AC_INIT} should be the name of your package (e.g., @samp{GNU
3952 Automake}), not the tarball name (e.g., @samp{automake}) that you used
3953 to pass to @code{AM_INIT_AUTOMAKE}. Autoconf tries to derive a
3954 tarball name from the package name, which should work for most but not
3955 all package names. (If it doesn't work for yours, you can use the
3956 four-argument form of @code{AC_INIT} to provide the tarball name
3959 @cindex @code{PACKAGE}, prevent definition
3960 @cindex @code{VERSION}, prevent definition
3962 By default this macro @code{AC_DEFINE}'s @code{PACKAGE} and
3963 @code{VERSION}. This can be avoided by passing the @option{no-define}
3966 AM_INIT_AUTOMAKE([gnits 1.5 no-define dist-bzip2])
3969 @item AM_PATH_LISPDIR
3970 @acindex AM_PATH_LISPDIR
3973 Searches for the program @command{emacs}, and, if found, sets the
3974 output variable @code{lispdir} to the full path to Emacs' site-lisp
3977 Note that this test assumes the @command{emacs} found to be a version
3978 that supports Emacs Lisp (such as GNU Emacs or XEmacs). Other
3979 emacsen can cause this test to hang (some, like old versions of
3980 MicroEmacs, start up in interactive mode, requiring @kbd{C-x C-c} to
3981 exit, which is hardly obvious for a non-emacs user). In most cases,
3982 however, you should be able to use @kbd{C-c} to kill the test. In
3983 order to avoid problems, you can set @env{EMACS} to ``no'' in the
3984 environment, or use the @option{--with-lispdir} option to
3985 @command{configure} to explicitly set the correct path (if you're sure
3986 you have an @command{emacs} that supports Emacs Lisp).
3988 @item AM_PROG_AR(@ovar{act-if-fail})
3991 You must use this macro when you use the archiver in your project, if
3992 you want support for unusual archivers such as Microsoft @command{lib}.
3993 The content of the optional argument is executed if the archiver
3994 interface is not recognized; the default action is to abort configure
3995 with an error message.
4001 Use this macro when you have assembly code in your project. This will
4002 choose the assembler for you (by default the C compiler) and set
4003 @code{CCAS}, and will also set @code{CCASFLAGS} if required.
4005 @item AM_PROG_CC_C_O
4006 @acindex AM_PROG_CC_C_O
4007 @acindex AC_PROG_CC_C_O
4008 This is like @code{AC_PROG_CC_C_O}, but it generates its results in
4009 the manner required by Automake. You must use this instead of
4010 @code{AC_PROG_CC_C_O} when you need this functionality, that is, when
4011 using per-target flags or subdir-objects with C sources.
4014 @acindex AM_PROG_LEX
4015 @acindex AC_PROG_LEX
4016 @cindex HP-UX 10, @command{lex} problems
4017 @cindex @command{lex} problems with HP-UX 10
4018 Like @code{AC_PROG_LEX} (@pxref{Particular Programs, , Particular
4019 Program Checks, autoconf, The Autoconf Manual}), but uses the
4020 @command{missing} script on systems that do not have @command{lex}.
4021 HP-UX 10 is one such system.
4024 @acindex AM_PROG_GCJ
4027 This macro finds the @command{gcj} program or causes an error. It sets
4028 @code{GCJ} and @code{GCJFLAGS}. @command{gcj} is the Java front-end to the
4029 GNU Compiler Collection.
4031 @item AM_PROG_UPC([@var{compiler-search-list}])
4032 @acindex AM_PROG_UPC
4034 Find a compiler for Unified Parallel C and define the @code{UPC}
4035 variable. The default @var{compiler-search-list} is @samp{upcc upc}.
4036 This macro will abort @command{configure} if no Unified Parallel C
4039 @item AM_SILENT_RULES
4040 @acindex AM_SILENT_RULES
4041 Control the machinery for less verbose build output
4042 (@pxref{Automake Silent Rules}).
4044 @item AM_WITH_DMALLOC
4045 @acindex AM_WITH_DMALLOC
4046 @cindex @command{dmalloc}, support for
4047 @vindex WITH_DMALLOC
4048 @opindex --with-dmalloc
4049 Add support for the @uref{http://dmalloc.com/, Dmalloc package}. If
4050 the user runs @command{configure} with @option{--with-dmalloc}, then
4051 define @code{WITH_DMALLOC} and add @option{-ldmalloc} to @code{LIBS}.
4056 @node Private Macros
4057 @subsection Private Macros
4059 The following macros are private macros you should not call directly.
4060 They are called by the other public macros when appropriate. Do not
4061 rely on them, as they might be changed in a future version. Consider
4062 them as implementation details; or better, do not consider them at all:
4066 @item _AM_DEPENDENCIES
4067 @itemx AM_SET_DEPDIR
4069 @itemx AM_OUTPUT_DEPENDENCY_COMMANDS
4070 These macros are used to implement Automake's automatic dependency
4071 tracking scheme. They are called automatically by Automake when
4072 required, and there should be no need to invoke them manually.
4074 @item AM_MAKE_INCLUDE
4075 This macro is used to discover how the user's @command{make} handles
4076 @code{include} statements. This macro is automatically invoked when
4077 needed; there should be no need to invoke it manually.
4079 @item AM_PROG_INSTALL_STRIP
4080 This is used to find a version of @code{install} that can be used to
4081 strip a program at installation time. This macro is automatically
4082 included when required.
4084 @item AM_SANITY_CHECK
4085 This checks to make sure that a file created in the build directory is
4086 newer than a file in the source directory. This can fail on systems
4087 where the clock is set incorrectly. This macro is automatically run
4088 from @code{AM_INIT_AUTOMAKE}.
4094 @chapter Directories
4096 For simple projects that distribute all files in the same directory
4097 it is enough to have a single @file{Makefile.am} that builds
4098 everything in place.
4100 In larger projects it is common to organize files in different
4101 directories, in a tree. For instance one directory per program, per
4102 library or per module. The traditional approach is to build these
4103 subdirectories recursively: each directory contains its @file{Makefile}
4104 (generated from @file{Makefile.am}), and when @command{make} is run
4105 from the top level directory it enters each subdirectory in turn to
4109 * Subdirectories:: Building subdirectories recursively
4110 * Conditional Subdirectories:: Conditionally not building directories
4111 * Alternative:: Subdirectories without recursion
4112 * Subpackages:: Nesting packages
4115 @node Subdirectories
4116 @section Recursing subdirectories
4118 @cindex @code{SUBDIRS}, explained
4120 In packages with subdirectories, the top level @file{Makefile.am} must
4121 tell Automake which subdirectories are to be built. This is done via
4122 the @code{SUBDIRS} variable.
4125 The @code{SUBDIRS} variable holds a list of subdirectories in which
4126 building of various sorts can occur. The rules for many targets
4127 (e.g., @code{all}) in the generated @file{Makefile} will run commands
4128 both locally and in all specified subdirectories. Note that the
4129 directories listed in @code{SUBDIRS} are not required to contain
4130 @file{Makefile.am}s; only @file{Makefile}s (after configuration).
4131 This allows inclusion of libraries from packages that do not use
4132 Automake (such as @code{gettext}; see also @ref{Third-Party
4135 In packages that use subdirectories, the top-level @file{Makefile.am} is
4136 often very short. For instance, here is the @file{Makefile.am} from the
4137 GNU Hello distribution:
4140 EXTRA_DIST = BUGS ChangeLog.O README-alpha
4141 SUBDIRS = doc intl po src tests
4144 When Automake invokes @command{make} in a subdirectory, it uses the value
4145 of the @code{MAKE} variable. It passes the value of the variable
4146 @code{AM_MAKEFLAGS} to the @command{make} invocation; this can be set in
4147 @file{Makefile.am} if there are flags you must always pass to
4150 @vindex AM_MAKEFLAGS
4152 The directories mentioned in @code{SUBDIRS} are usually direct
4153 children of the current directory, each subdirectory containing its
4154 own @file{Makefile.am} with a @code{SUBDIRS} pointing to deeper
4155 subdirectories. Automake can be used to construct packages of
4156 arbitrary depth this way.
4158 By default, Automake generates @file{Makefiles} that work depth-first
4159 in postfix order: the subdirectories are built before the current
4160 directory. However, it is possible to change this ordering. You can
4161 do this by putting @samp{.} into @code{SUBDIRS}. For instance,
4162 putting @samp{.} first will cause a prefix ordering of
4168 SUBDIRS = lib src . test
4172 will cause @file{lib/} to be built before @file{src/}, then the
4173 current directory will be built, finally the @file{test/} directory
4174 will be built. It is customary to arrange test directories to be
4175 built after everything else since they are meant to test what has
4178 All @code{clean} rules are run in reverse order of build rules.
4180 @node Conditional Subdirectories
4181 @section Conditional Subdirectories
4182 @cindex Subdirectories, building conditionally
4183 @cindex Conditional subdirectories
4184 @cindex @code{SUBDIRS}, conditional
4185 @cindex Conditional @code{SUBDIRS}
4187 It is possible to define the @code{SUBDIRS} variable conditionally if,
4188 like in the case of GNU Inetutils, you want to only build a subset of
4191 To illustrate how this works, let's assume we have two directories
4192 @file{src/} and @file{opt/}. @file{src/} should always be built, but we
4193 want to decide in @command{configure} whether @file{opt/} will be built
4194 or not. (For this example we will assume that @file{opt/} should be
4195 built when the variable @samp{$want_opt} was set to @samp{yes}.)
4197 Running @command{make} should thus recurse into @file{src/} always, and
4198 then maybe in @file{opt/}.
4200 However @samp{make dist} should always recurse into both @file{src/}
4201 and @file{opt/}. Because @file{opt/} should be distributed even if it
4202 is not needed in the current configuration. This means
4203 @file{opt/Makefile} should be created @emph{unconditionally}.
4205 There are two ways to setup a project like this. You can use Automake
4206 conditionals (@pxref{Conditionals}) or use Autoconf @code{AC_SUBST}
4207 variables (@pxref{Setting Output Variables, , Setting Output
4208 Variables, autoconf, The Autoconf Manual}). Using Automake
4209 conditionals is the preferred solution. Before we illustrate these
4210 two possibilities, let's introduce @code{DIST_SUBDIRS}.
4213 * SUBDIRS vs DIST_SUBDIRS:: Two sets of directories
4214 * Subdirectories with AM_CONDITIONAL:: Specifying conditional subdirectories
4215 * Subdirectories with AC_SUBST:: Another way for conditional recursion
4216 * Unconfigured Subdirectories:: Not even creating a @samp{Makefile}
4219 @node SUBDIRS vs DIST_SUBDIRS
4220 @subsection @code{SUBDIRS} vs.@: @code{DIST_SUBDIRS}
4221 @cindex @code{DIST_SUBDIRS}, explained
4223 Automake considers two sets of directories, defined by the variables
4224 @code{SUBDIRS} and @code{DIST_SUBDIRS}.
4226 @code{SUBDIRS} contains the subdirectories of the current directory
4227 that must be built (@pxref{Subdirectories}). It must be defined
4228 manually; Automake will never guess a directory is to be built. As we
4229 will see in the next two sections, it is possible to define it
4230 conditionally so that some directory will be omitted from the build.
4232 @code{DIST_SUBDIRS} is used in rules that need to recurse in all
4233 directories, even those that have been conditionally left out of the
4234 build. Recall our example where we may not want to build subdirectory
4235 @file{opt/}, but yet we want to distribute it? This is where
4236 @code{DIST_SUBDIRS} comes into play: @samp{opt} may not appear in
4237 @code{SUBDIRS}, but it must appear in @code{DIST_SUBDIRS}.
4239 Precisely, @code{DIST_SUBDIRS} is used by @samp{make
4240 maintainer-clean}, @samp{make distclean} and @samp{make dist}. All
4241 other recursive rules use @code{SUBDIRS}.
4243 If @code{SUBDIRS} is defined conditionally using Automake
4244 conditionals, Automake will define @code{DIST_SUBDIRS} automatically
4245 from the possible values of @code{SUBDIRS} in all conditions.
4247 If @code{SUBDIRS} contains @code{AC_SUBST} variables,
4248 @code{DIST_SUBDIRS} will not be defined correctly because Automake
4249 does not know the possible values of these variables. In this case
4250 @code{DIST_SUBDIRS} needs to be defined manually.
4252 @node Subdirectories with AM_CONDITIONAL
4253 @subsection Subdirectories with @code{AM_CONDITIONAL}
4254 @cindex @code{SUBDIRS} and @code{AM_CONDITIONAL}
4255 @cindex @code{AM_CONDITIONAL} and @code{SUBDIRS}
4257 @c Keep in sync with subcond2.sh
4259 @file{configure} should output the @file{Makefile} for each directory
4260 and define a condition into which @file{opt/} should be built.
4264 AM_CONDITIONAL([COND_OPT], [test "$want_opt" = yes])
4265 AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
4269 Then @code{SUBDIRS} can be defined in the top-level @file{Makefile.am}
4276 SUBDIRS = src $(MAYBE_OPT)
4279 As you can see, running @command{make} will rightly recurse into
4280 @file{src/} and maybe @file{opt/}.
4282 @vindex DIST_SUBDIRS
4283 As you can't see, running @samp{make dist} will recurse into both
4284 @file{src/} and @file{opt/} directories because @samp{make dist}, unlike
4285 @samp{make all}, doesn't use the @code{SUBDIRS} variable. It uses the
4286 @code{DIST_SUBDIRS} variable.
4288 In this case Automake will define @samp{DIST_SUBDIRS = src opt}
4289 automatically because it knows that @code{MAYBE_OPT} can contain
4290 @samp{opt} in some condition.
4292 @node Subdirectories with AC_SUBST
4293 @subsection Subdirectories with @code{AC_SUBST}
4294 @cindex @code{SUBDIRS} and @code{AC_SUBST}
4295 @cindex @code{AC_SUBST} and @code{SUBDIRS}
4297 @c Keep in sync with subcond3.sh
4299 Another possibility is to define @code{MAYBE_OPT} from
4300 @file{./configure} using @code{AC_SUBST}:
4304 if test "$want_opt" = yes; then
4309 AC_SUBST([MAYBE_OPT])
4310 AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
4314 In this case the top-level @file{Makefile.am} should look as follows.
4317 SUBDIRS = src $(MAYBE_OPT)
4318 DIST_SUBDIRS = src opt
4321 The drawback is that since Automake cannot guess what the possible
4322 values of @code{MAYBE_OPT} are, it is necessary to define
4323 @code{DIST_SUBDIRS}.
4325 @node Unconfigured Subdirectories
4326 @subsection Unconfigured Subdirectories
4327 @cindex Subdirectories, configured conditionally
4329 The semantics of @code{DIST_SUBDIRS} are often misunderstood by some
4330 users that try to @emph{configure and build} subdirectories
4331 conditionally. Here by configuring we mean creating the
4332 @file{Makefile} (it might also involve running a nested
4333 @command{configure} script: this is a costly operation that explains
4334 why people want to do it conditionally, but only the @file{Makefile}
4335 is relevant to the discussion).
4337 The above examples all assume that every @file{Makefile} is created,
4338 even in directories that are not going to be built. The simple reason
4339 is that we want @samp{make dist} to distribute even the directories
4340 that are not being built (e.g., platform-dependent code), hence
4341 @file{make dist} must recurse into the subdirectory, hence this
4342 directory must be configured and appear in @code{DIST_SUBDIRS}.
4344 Building packages that do not configure every subdirectory is a tricky
4345 business, and we do not recommend it to the novice as it is easy to
4346 produce an incomplete tarball by mistake. We will not discuss this
4347 topic in depth here, yet for the adventurous here are a few rules to
4352 @item @code{SUBDIRS} should always be a subset of @code{DIST_SUBDIRS}.
4354 It makes little sense to have a directory in @code{SUBDIRS} that
4355 is not in @code{DIST_SUBDIRS}. Think of the former as a way to tell
4356 which directories listed in the latter should be built.
4357 @item Any directory listed in @code{DIST_SUBDIRS} and @code{SUBDIRS}
4360 I.e., the @file{Makefile} must exists or the recursive @command{make}
4361 rules will not be able to process the directory.
4362 @item Any configured directory must be listed in @code{DIST_SUBDIRS}.
4364 So that the cleaning rules remove the generated @file{Makefile}s.
4365 It would be correct to see @code{DIST_SUBDIRS} as a variable that
4366 lists all the directories that have been configured.
4370 In order to prevent recursion in some unconfigured directory you
4371 must therefore ensure that this directory does not appear in
4372 @code{DIST_SUBDIRS} (and @code{SUBDIRS}). For instance, if you define
4373 @code{SUBDIRS} conditionally using @code{AC_SUBST} and do not define
4374 @code{DIST_SUBDIRS} explicitly, it will be default to
4375 @samp{$(SUBDIRS)}; another possibility is to force @code{DIST_SUBDIRS
4378 Of course, directories that are omitted from @code{DIST_SUBDIRS} will
4379 not be distributed unless you make other arrangements for this to
4380 happen (for instance, always running @samp{make dist} in a
4381 configuration where all directories are known to appear in
4382 @code{DIST_SUBDIRS}; or writing a @code{dist-hook} target to
4383 distribute these directories).
4385 @cindex Subdirectories, not distributed
4386 In few packages, unconfigured directories are not even expected to
4387 be distributed. Although these packages do not require the
4388 aforementioned extra arrangements, there is another pitfall. If the
4389 name of a directory appears in @code{SUBDIRS} or @code{DIST_SUBDIRS},
4390 @command{automake} will make sure the directory exists. Consequently
4391 @command{automake} cannot be run on such a distribution when one
4392 directory has been omitted. One way to avoid this check is to use the
4393 @code{AC_SUBST} method to declare conditional directories; since
4394 @command{automake} does not know the values of @code{AC_SUBST}
4395 variables it cannot ensure the corresponding directory exists.
4398 @section An Alternative Approach to Subdirectories
4400 If you've ever read Peter Miller's excellent paper,
4401 @uref{http://miller.emu.id.au/pmiller/books/rmch/,
4402 Recursive Make Considered Harmful}, the preceding sections on the use of
4403 subdirectories will probably come as unwelcome advice. For those who
4404 haven't read the paper, Miller's main thesis is that recursive
4405 @command{make} invocations are both slow and error-prone.
4407 Automake provides sufficient cross-directory support @footnote{We
4408 believe. This work is new and there are probably warts.
4409 @xref{Introduction}, for information on reporting bugs.} to enable you
4410 to write a single @file{Makefile.am} for a complex multi-directory
4414 By default an installable file specified in a subdirectory will have its
4415 directory name stripped before installation. For instance, in this
4416 example, the header file will be installed as
4417 @file{$(includedir)/stdio.h}:
4420 include_HEADERS = inc/stdio.h
4424 @cindex @code{nobase_} prefix
4425 @cindex Path stripping, avoiding
4426 @cindex Avoiding path stripping
4428 However, the @samp{nobase_} prefix can be used to circumvent this path
4429 stripping. In this example, the header file will be installed as
4430 @file{$(includedir)/sys/types.h}:
4433 nobase_include_HEADERS = sys/types.h
4436 @cindex @code{nobase_} and @code{dist_} or @code{nodist_}
4437 @cindex @code{dist_} and @code{nobase_}
4438 @cindex @code{nodist_} and @code{nobase_}
4442 @samp{nobase_} should be specified first when used in conjunction with
4443 either @samp{dist_} or @samp{nodist_} (@pxref{Fine-grained Distribution
4444 Control}). For instance:
4447 nobase_dist_pkgdata_DATA = images/vortex.pgm sounds/whirl.ogg
4450 Finally, note that a variable using the @samp{nobase_} prefix can
4451 often be replaced by several variables, one for each destination
4452 directory (@pxref{Uniform}). For instance, the last example could be
4453 rewritten as follows:
4455 @c Keep in sync with primary-prefix-couples-documented-valid.sh
4457 imagesdir = $(pkgdatadir)/images
4458 soundsdir = $(pkgdatadir)/sounds
4459 dist_images_DATA = images/vortex.pgm
4460 dist_sounds_DATA = sounds/whirl.ogg
4464 This latter syntax makes it possible to change one destination
4465 directory without changing the layout of the source tree.
4467 Currently, @samp{nobase_*_LTLIBRARIES} are the only exception to this
4468 rule, in that there is no particular installation order guarantee for
4469 an otherwise equivalent set of variables without @samp{nobase_} prefix.
4472 @section Nesting Packages
4473 @cindex Nesting packages
4475 @acindex AC_CONFIG_SUBDIRS
4476 @acindex AC_CONFIG_AUX_DIR
4479 In the GNU Build System, packages can be nested to arbitrary depth.
4480 This means that a package can embed other packages with their own
4481 @file{configure}, @file{Makefile}s, etc.
4483 These other packages should just appear as subdirectories of their
4484 parent package. They must be listed in @code{SUBDIRS} like other
4485 ordinary directories. However the subpackage's @file{Makefile}s
4486 should be output by its own @file{configure} script, not by the
4487 parent's @file{configure}. This is achieved using the
4488 @code{AC_CONFIG_SUBDIRS} Autoconf macro (@pxref{Subdirectories,
4489 AC_CONFIG_SUBDIRS, Configuring Other Packages in Subdirectories,
4490 autoconf, The Autoconf Manual}).
4492 Here is an example package for an @code{arm} program that links with
4493 a @code{hand} library that is a nested package in subdirectory
4496 @code{arm}'s @file{configure.ac}:
4499 AC_INIT([arm], [1.0])
4500 AC_CONFIG_AUX_DIR([.])
4503 AC_CONFIG_FILES([Makefile])
4504 # Call hand's ./configure script recursively.
4505 AC_CONFIG_SUBDIRS([hand])
4509 @code{arm}'s @file{Makefile.am}:
4512 # Build the library in the hand subdirectory first.
4515 # Include hand's header when compiling this directory.
4516 AM_CPPFLAGS = -I$(srcdir)/hand
4520 # link with the hand library.
4521 arm_LDADD = hand/libhand.a
4524 Now here is @code{hand}'s @file{hand/configure.ac}:
4527 AC_INIT([hand], [1.2])
4528 AC_CONFIG_AUX_DIR([.])
4533 AC_CONFIG_FILES([Makefile])
4538 and its @file{hand/Makefile.am}:
4541 lib_LIBRARIES = libhand.a
4542 libhand_a_SOURCES = hand.c
4545 When @samp{make dist} is run from the top-level directory it will
4546 create an archive @file{arm-1.0.tar.gz} that contains the @code{arm}
4547 code as well as the @file{hand} subdirectory. This package can be
4548 built and installed like any ordinary package, with the usual
4549 @samp{./configure && make && make install} sequence (the @code{hand}
4550 subpackage will be built and installed by the process).
4552 When @samp{make dist} is run from the hand directory, it will create a
4553 self-contained @file{hand-1.2.tar.gz} archive. So although it appears
4554 to be embedded in another package, it can still be used separately.
4556 The purpose of the @samp{AC_CONFIG_AUX_DIR([.])} instruction is to
4557 force Automake and Autoconf to search for auxiliary scripts in the
4558 current directory. For instance, this means that there will be two
4559 copies of @file{install-sh}: one in the top-level of the @code{arm}
4560 package, and another one in the @file{hand/} subdirectory for the
4561 @code{hand} package.
4563 The historical default is to search for these auxiliary scripts in
4564 the parent directory and the grandparent directory. So if the
4565 @samp{AC_CONFIG_AUX_DIR([.])} line was removed from
4566 @file{hand/configure.ac}, that subpackage would share the auxiliary
4567 script of the @code{arm} package. This may looks like a gain in size
4568 (a few kilobytes), but it is actually a loss of modularity as the
4569 @code{hand} subpackage is no longer self-contained (@samp{make dist}
4570 in the subdirectory will not work anymore).
4572 Packages that do not use Automake need more work to be integrated this
4573 way. @xref{Third-Party Makefiles}.
4576 @chapter Building Programs and Libraries
4578 A large part of Automake's functionality is dedicated to making it easy
4579 to build programs and libraries.
4582 * A Program:: Building a program
4583 * A Library:: Building a library
4584 * A Shared Library:: Building a Libtool library
4585 * Program and Library Variables:: Variables controlling program and
4587 * Default _SOURCES:: Default source files
4588 * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
4589 * Program Variables:: Variables used when building a program
4590 * Yacc and Lex:: Yacc and Lex support
4591 * C++ Support:: Compiling C++ sources
4592 * Objective C Support:: Compiling Objective C sources
4593 * Unified Parallel C Support:: Compiling Unified Parallel C sources
4594 * Assembly Support:: Compiling assembly sources
4595 * Fortran 77 Support:: Compiling Fortran 77 sources
4596 * Fortran 9x Support:: Compiling Fortran 9x sources
4597 * Java Support with gcj:: Compiling Java sources using gcj
4598 * Vala Support:: Compiling Vala sources
4599 * Support for Other Languages:: Compiling other languages
4600 * Dependencies:: Automatic dependency tracking
4601 * EXEEXT:: Support for executable extensions
4606 @section Building a program
4608 In order to build a program, you need to tell Automake which sources
4609 are part of it, and which libraries it should be linked with.
4611 This section also covers conditional compilation of sources or
4612 programs. Most of the comments about these also apply to libraries
4613 (@pxref{A Library}) and libtool libraries (@pxref{A Shared Library}).
4616 * Program Sources:: Defining program sources
4617 * Linking:: Linking with libraries or extra objects
4618 * Conditional Sources:: Handling conditional sources
4619 * Conditional Programs:: Building a program conditionally
4622 @node Program Sources
4623 @subsection Defining program sources
4625 @cindex @code{PROGRAMS}, @code{bindir}
4627 @vindex bin_PROGRAMS
4628 @vindex sbin_PROGRAMS
4629 @vindex libexec_PROGRAMS
4630 @vindex pkglibexec_PROGRAMS
4631 @vindex noinst_PROGRAMS
4632 @vindex check_PROGRAMS
4634 In a directory containing source that gets built into a program (as
4635 opposed to a library or a script), the @code{PROGRAMS} primary is used.
4636 Programs can be installed in @code{bindir}, @code{sbindir},
4637 @code{libexecdir}, @code{pkglibexecdir}, or not at all
4638 (@code{noinst_}). They can also be built only for @samp{make check}, in
4639 which case the prefix is @samp{check_}.
4644 bin_PROGRAMS = hello
4647 In this simple case, the resulting @file{Makefile.in} will contain code
4648 to generate a program named @code{hello}.
4650 Associated with each program are several assisting variables that are
4651 named after the program. These variables are all optional, and have
4652 reasonable defaults. Each variable, its use, and default is spelled out
4653 below; we use the ``hello'' example throughout.
4655 The variable @code{hello_SOURCES} is used to specify which source files
4656 get built into an executable:
4659 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
4662 This causes each mentioned @file{.c} file to be compiled into the
4663 corresponding @file{.o}. Then all are linked to produce @file{hello}.
4665 @cindex @code{_SOURCES} primary, defined
4666 @cindex @code{SOURCES} primary, defined
4667 @cindex Primary variable, @code{SOURCES}
4670 If @code{hello_SOURCES} is not specified, then it defaults to the single
4671 file @file{hello.c} (@pxref{Default _SOURCES}).
4675 Multiple programs can be built in a single directory. Multiple programs
4676 can share a single source file, which must be listed in each
4677 @code{_SOURCES} definition.
4679 @cindex Header files in @code{_SOURCES}
4680 @cindex @code{_SOURCES} and header files
4682 Header files listed in a @code{_SOURCES} definition will be included in
4683 the distribution but otherwise ignored. In case it isn't obvious, you
4684 should not include the header file generated by @file{configure} in a
4685 @code{_SOURCES} variable; this file should not be distributed. Lex
4686 (@file{.l}) and Yacc (@file{.y}) files can also be listed; see @ref{Yacc
4691 @subsection Linking the program
4693 If you need to link against libraries that are not found by
4694 @command{configure}, you can use @code{LDADD} to do so. This variable is
4695 used to specify additional objects or libraries to link with; it is
4696 inappropriate for specifying specific linker flags, you should use
4697 @code{AM_LDFLAGS} for this purpose.
4701 @cindex @code{prog_LDADD}, defined
4703 Sometimes, multiple programs are built in one directory but do not share
4704 the same link-time requirements. In this case, you can use the
4705 @code{@var{prog}_LDADD} variable (where @var{prog} is the name of the
4706 program as it appears in some @code{_PROGRAMS} variable, and usually
4707 written in lowercase) to override @code{LDADD}. If this variable exists
4708 for a given program, then that program is not linked using @code{LDADD}.
4711 For instance, in GNU cpio, @code{pax}, @code{cpio} and @code{mt} are
4712 linked against the library @file{libcpio.a}. However, @code{rmt} is
4713 built in the same directory, and has no such link requirement. Also,
4714 @code{mt} and @code{rmt} are only built on certain architectures. Here
4715 is what cpio's @file{src/Makefile.am} looks like (abridged):
4718 bin_PROGRAMS = cpio pax $(MT)
4719 libexec_PROGRAMS = $(RMT)
4720 EXTRA_PROGRAMS = mt rmt
4722 LDADD = ../lib/libcpio.a $(INTLLIBS)
4725 cpio_SOURCES = @dots{}
4726 pax_SOURCES = @dots{}
4727 mt_SOURCES = @dots{}
4728 rmt_SOURCES = @dots{}
4731 @cindex @code{_LDFLAGS}, defined
4732 @vindex maude_LDFLAGS
4733 @code{@var{prog}_LDADD} is inappropriate for passing program-specific
4734 linker flags (except for @option{-l}, @option{-L}, @option{-dlopen} and
4735 @option{-dlpreopen}). So, use the @code{@var{prog}_LDFLAGS} variable for
4738 @cindex @code{_DEPENDENCIES}, defined
4739 @vindex maude_DEPENDENCIES
4740 @vindex EXTRA_maude_DEPENDENCIES
4741 It is also occasionally useful to have a program depend on some other
4742 target that is not actually part of that program. This can be done
4743 using either the @code{@var{prog}_DEPENDENCIES} or the
4744 @code{EXTRA_@var{prog}_DEPENDENCIES} variable. Each program depends on
4745 the contents both variables, but no further interpretation is done.
4747 Since these dependencies are associated to the link rule used to
4748 create the programs they should normally list files used by the link
4749 command. That is @file{*.$(OBJEXT)}, @file{*.a}, or @file{*.la}
4750 files. In rare cases you may need to add other kinds of files such as
4751 linker scripts, but @emph{listing a source file in
4752 @code{_DEPENDENCIES} is wrong}. If some source file needs to be built
4753 before all the components of a program are built, consider using the
4754 @code{BUILT_SOURCES} variable instead (@pxref{Sources}).
4756 If @code{@var{prog}_DEPENDENCIES} is not supplied, it is computed by
4757 Automake. The automatically-assigned value is the contents of
4758 @code{@var{prog}_LDADD}, with most configure substitutions, @option{-l},
4759 @option{-L}, @option{-dlopen} and @option{-dlpreopen} options removed. The
4760 configure substitutions that are left in are only @samp{$(LIBOBJS)} and
4761 @samp{$(ALLOCA)}; these are left because it is known that they will not
4762 cause an invalid value for @code{@var{prog}_DEPENDENCIES} to be
4765 @ref{Conditional Sources} shows a situation where @code{_DEPENDENCIES}
4768 The @code{EXTRA_@var{prog}_DEPENDENCIES} may be useful for cases where
4769 you merely want to augment the @command{automake}-generated
4770 @code{@var{prog}_DEPENDENCIES} rather than replacing it.
4772 @cindex @code{LDADD} and @option{-l}
4773 @cindex @option{-l} and @code{LDADD}
4774 We recommend that you avoid using @option{-l} options in @code{LDADD}
4775 or @code{@var{prog}_LDADD} when referring to libraries built by your
4776 package. Instead, write the file name of the library explicitly as in
4777 the above @code{cpio} example. Use @option{-l} only to list
4778 third-party libraries. If you follow this rule, the default value of
4779 @code{@var{prog}_DEPENDENCIES} will list all your local libraries and
4780 omit the other ones.
4783 @node Conditional Sources
4784 @subsection Conditional compilation of sources
4786 You can't put a configure substitution (e.g., @samp{@@FOO@@} or
4787 @samp{$(FOO)} where @code{FOO} is defined via @code{AC_SUBST}) into a
4788 @code{_SOURCES} variable. The reason for this is a bit hard to
4789 explain, but suffice to say that it simply won't work. Automake will
4790 give an error if you try to do this.
4792 Fortunately there are two other ways to achieve the same result. One is
4793 to use configure substitutions in @code{_LDADD} variables, the other is
4794 to use an Automake conditional.
4796 @subsubheading Conditional Compilation using @code{_LDADD} Substitutions
4798 @cindex @code{EXTRA_prog_SOURCES}, defined
4800 Automake must know all the source files that could possibly go into a
4801 program, even if not all the files are built in every circumstance. Any
4802 files that are only conditionally built should be listed in the
4803 appropriate @code{EXTRA_} variable. For instance, if
4804 @file{hello-linux.c} or @file{hello-generic.c} were conditionally included
4805 in @code{hello}, the @file{Makefile.am} would contain:
4808 bin_PROGRAMS = hello
4809 hello_SOURCES = hello-common.c
4810 EXTRA_hello_SOURCES = hello-linux.c hello-generic.c
4811 hello_LDADD = $(HELLO_SYSTEM)
4812 hello_DEPENDENCIES = $(HELLO_SYSTEM)
4816 You can then setup the @samp{$(HELLO_SYSTEM)} substitution from
4817 @file{configure.ac}:
4822 *linux*) HELLO_SYSTEM='hello-linux.$(OBJEXT)' ;;
4823 *) HELLO_SYSTEM='hello-generic.$(OBJEXT)' ;;
4825 AC_SUBST([HELLO_SYSTEM])
4829 In this case, the variable @code{HELLO_SYSTEM} should be replaced by
4830 either @file{hello-linux.o} or @file{hello-generic.o}, and added to
4831 both @code{hello_DEPENDENCIES} and @code{hello_LDADD} in order to be
4832 built and linked in.
4834 @subsubheading Conditional Compilation using Automake Conditionals
4836 An often simpler way to compile source files conditionally is to use
4837 Automake conditionals. For instance, you could use this
4838 @file{Makefile.am} construct to build the same @file{hello} example:
4841 bin_PROGRAMS = hello
4843 hello_SOURCES = hello-linux.c hello-common.c
4845 hello_SOURCES = hello-generic.c hello-common.c
4849 In this case, @file{configure.ac} should setup the @code{LINUX}
4850 conditional using @code{AM_CONDITIONAL} (@pxref{Conditionals}).
4852 When using conditionals like this you don't need to use the
4853 @code{EXTRA_} variable, because Automake will examine the contents of
4854 each variable to construct the complete list of source files.
4856 If your program uses a lot of files, you will probably prefer a
4857 conditional @samp{+=}.
4860 bin_PROGRAMS = hello
4861 hello_SOURCES = hello-common.c
4863 hello_SOURCES += hello-linux.c
4865 hello_SOURCES += hello-generic.c
4869 @node Conditional Programs
4870 @subsection Conditional compilation of programs
4871 @cindex Conditional programs
4872 @cindex Programs, conditional
4874 Sometimes it is useful to determine the programs that are to be built
4875 at configure time. For instance, GNU @code{cpio} only builds
4876 @code{mt} and @code{rmt} under special circumstances. The means to
4877 achieve conditional compilation of programs are the same you can use
4878 to compile source files conditionally: substitutions or conditionals.
4880 @subsubheading Conditional Programs using @command{configure} Substitutions
4882 @vindex EXTRA_PROGRAMS
4883 @cindex @code{EXTRA_PROGRAMS}, defined
4884 In this case, you must notify Automake of all the programs that can
4885 possibly be built, but at the same time cause the generated
4886 @file{Makefile.in} to use the programs specified by @command{configure}.
4887 This is done by having @command{configure} substitute values into each
4888 @code{_PROGRAMS} definition, while listing all optionally built programs
4889 in @code{EXTRA_PROGRAMS}.
4892 bin_PROGRAMS = cpio pax $(MT)
4893 libexec_PROGRAMS = $(RMT)
4894 EXTRA_PROGRAMS = mt rmt
4897 As explained in @ref{EXEEXT}, Automake will rewrite
4898 @code{bin_PROGRAMS}, @code{libexec_PROGRAMS}, and
4899 @code{EXTRA_PROGRAMS}, appending @samp{$(EXEEXT)} to each binary.
4900 Obviously it cannot rewrite values obtained at run-time through
4901 @command{configure} substitutions, therefore you should take care of
4902 appending @samp{$(EXEEXT)} yourself, as in @samp{AC_SUBST([MT],
4903 ['mt$@{EXEEXT@}'])}.
4905 @subsubheading Conditional Programs using Automake Conditionals
4907 You can also use Automake conditionals (@pxref{Conditionals}) to
4908 select programs to be built. In this case you don't have to worry
4909 about @samp{$(EXEEXT)} or @code{EXTRA_PROGRAMS}.
4911 @c Keep in sync with exeext.sh
4913 bin_PROGRAMS = cpio pax
4918 libexec_PROGRAMS = rmt
4924 @section Building a library
4926 @cindex @code{_LIBRARIES} primary, defined
4927 @cindex @code{LIBRARIES} primary, defined
4928 @cindex Primary variable, @code{LIBRARIES}
4931 @vindex lib_LIBRARIES
4932 @vindex pkglib_LIBRARIES
4933 @vindex noinst_LIBRARIES
4935 Building a library is much like building a program. In this case, the
4936 name of the primary is @code{LIBRARIES}. Libraries can be installed in
4937 @code{libdir} or @code{pkglibdir}.
4939 @xref{A Shared Library}, for information on how to build shared
4940 libraries using libtool and the @code{LTLIBRARIES} primary.
4942 Each @code{_LIBRARIES} variable is a list of the libraries to be built.
4943 For instance, to create a library named @file{libcpio.a}, but not install
4944 it, you would write:
4947 noinst_LIBRARIES = libcpio.a
4948 libcpio_a_SOURCES = @dots{}
4951 The sources that go into a library are determined exactly as they are
4952 for programs, via the @code{_SOURCES} variables. Note that the library
4953 name is canonicalized (@pxref{Canonicalization}), so the @code{_SOURCES}
4954 variable corresponding to @file{libcpio.a} is @samp{libcpio_a_SOURCES},
4955 not @samp{libcpio.a_SOURCES}.
4957 @vindex maude_LIBADD
4958 Extra objects can be added to a library using the
4959 @code{@var{library}_LIBADD} variable. This should be used for objects
4960 determined by @command{configure}. Again from @code{cpio}:
4962 @c Keep in sync with pr401c.sh
4964 libcpio_a_LIBADD = $(LIBOBJS) $(ALLOCA)
4967 In addition, sources for extra objects that will not exist until
4968 configure-time must be added to the @code{BUILT_SOURCES} variable
4971 Building a static library is done by compiling all object files, then
4972 by invoking @samp{$(AR) $(ARFLAGS)} followed by the name of the
4973 library and the list of objects, and finally by calling
4974 @samp{$(RANLIB)} on that library. You should call
4975 @code{AC_PROG_RANLIB} from your @file{configure.ac} to define
4976 @code{RANLIB} (Automake will complain otherwise). You should also
4977 call @code{AM_PROG_AR} to define @code{AR}, in order to support unusual
4978 archivers such as Microsoft lib. @code{ARFLAGS} will default to
4979 @code{cru}; you can override this variable by setting it in your
4980 @file{Makefile.am} or by @code{AC_SUBST}ing it from your
4981 @file{configure.ac}. You can override the @code{AR} variable by
4982 defining a per-library @code{maude_AR} variable (@pxref{Program and
4983 Library Variables}).
4985 @cindex Empty libraries
4986 Be careful when selecting library components conditionally. Because
4987 building an empty library is not portable, you should ensure that any
4988 library always contains at least one object.
4990 To use a static library when building a program, add it to
4991 @code{LDADD} for this program. In the following example, the program
4992 @file{cpio} is statically linked with the library @file{libcpio.a}.
4995 noinst_LIBRARIES = libcpio.a
4996 libcpio_a_SOURCES = @dots{}
4999 cpio_SOURCES = cpio.c @dots{}
5000 cpio_LDADD = libcpio.a
5004 @node A Shared Library
5005 @section Building a Shared Library
5007 @cindex Shared libraries, support for
5009 Building shared libraries portably is a relatively complex matter.
5010 For this reason, GNU Libtool (@pxref{Top, , Introduction, libtool, The
5011 Libtool Manual}) was created to help build shared libraries in a
5012 platform-independent way.
5015 * Libtool Concept:: Introducing Libtool
5016 * Libtool Libraries:: Declaring Libtool Libraries
5017 * Conditional Libtool Libraries:: Building Libtool Libraries Conditionally
5018 * Conditional Libtool Sources:: Choosing Library Sources Conditionally
5019 * Libtool Convenience Libraries:: Building Convenience Libtool Libraries
5020 * Libtool Modules:: Building Libtool Modules
5021 * Libtool Flags:: Using _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS
5022 * LTLIBOBJS:: Using $(LTLIBOBJS) and $(LTALLOCA)
5023 * Libtool Issues:: Common Issues Related to Libtool's Use
5026 @node Libtool Concept
5027 @subsection The Libtool Concept
5029 @cindex @command{libtool}, introduction
5030 @cindex libtool library, definition
5031 @cindex suffix @file{.la}, defined
5032 @cindex @file{.la} suffix, defined
5034 Libtool abstracts shared and static libraries into a unified concept
5035 henceforth called @dfn{libtool libraries}. Libtool libraries are
5036 files using the @file{.la} suffix, and can designate a static library,
5037 a shared library, or maybe both. Their exact nature cannot be
5038 determined until @file{./configure} is run: not all platforms support
5039 all kinds of libraries, and users can explicitly select which
5040 libraries should be built. (However the package's maintainers can
5041 tune the default, @pxref{AC_PROG_LIBTOOL, , The @code{AC_PROG_LIBTOOL}
5042 macro, libtool, The Libtool Manual}.)
5044 @cindex suffix @file{.lo}, defined
5045 Because object files for shared and static libraries must be compiled
5046 differently, libtool is also used during compilation. Object files
5047 built by libtool are called @dfn{libtool objects}: these are files
5048 using the @file{.lo} suffix. Libtool libraries are built from these
5051 You should not assume anything about the structure of @file{.la} or
5052 @file{.lo} files and how libtool constructs them: this is libtool's
5053 concern, and the last thing one wants is to learn about libtool's
5054 guts. However the existence of these files matters, because they are
5055 used as targets and dependencies in @file{Makefile}s rules when
5056 building libtool libraries. There are situations where you may have
5057 to refer to these, for instance when expressing dependencies for
5058 building source files conditionally (@pxref{Conditional Libtool
5061 @cindex @file{libltdl}, introduction
5063 People considering writing a plug-in system, with dynamically loaded
5064 modules, should look into @file{libltdl}: libtool's dlopening library
5065 (@pxref{Using libltdl, , Using libltdl, libtool, The Libtool Manual}).
5066 This offers a portable dlopening facility to load libtool libraries
5067 dynamically, and can also achieve static linking where unavoidable.
5069 Before we discuss how to use libtool with Automake in details, it
5070 should be noted that the libtool manual also has a section about how
5071 to use Automake with libtool (@pxref{Using Automake, , Using Automake
5072 with Libtool, libtool, The Libtool Manual}).
5074 @node Libtool Libraries
5075 @subsection Building Libtool Libraries
5077 @cindex @code{_LTLIBRARIES} primary, defined
5078 @cindex @code{LTLIBRARIES} primary, defined
5079 @cindex Primary variable, @code{LTLIBRARIES}
5080 @cindex Example of shared libraries
5081 @vindex lib_LTLIBRARIES
5082 @vindex pkglib_LTLIBRARIES
5083 @vindex _LTLIBRARIES
5085 Automake uses libtool to build libraries declared with the
5086 @code{LTLIBRARIES} primary. Each @code{_LTLIBRARIES} variable is a
5087 list of libtool libraries to build. For instance, to create a libtool
5088 library named @file{libgettext.la}, and install it in @code{libdir},
5092 lib_LTLIBRARIES = libgettext.la
5093 libgettext_la_SOURCES = gettext.c gettext.h @dots{}
5096 Automake predefines the variable @code{pkglibdir}, so you can use
5097 @code{pkglib_LTLIBRARIES} to install libraries in
5098 @samp{$(libdir)/@@PACKAGE@@/}.
5100 If @file{gettext.h} is a public header file that needs to be installed
5101 in order for people to use the library, it should be declared using a
5102 @code{_HEADERS} variable, not in @code{libgettext_la_SOURCES}.
5103 Headers listed in the latter should be internal headers that are not
5104 part of the public interface.
5107 lib_LTLIBRARIES = libgettext.la
5108 libgettext_la_SOURCES = gettext.c @dots{}
5109 include_HEADERS = gettext.h @dots{}
5112 A package can build and install such a library along with other
5113 programs that use it. This dependency should be specified using
5114 @code{LDADD}. The following example builds a program named
5115 @file{hello} that is linked with @file{libgettext.la}.
5118 lib_LTLIBRARIES = libgettext.la
5119 libgettext_la_SOURCES = gettext.c @dots{}
5121 bin_PROGRAMS = hello
5122 hello_SOURCES = hello.c @dots{}
5123 hello_LDADD = libgettext.la
5127 Whether @file{hello} is statically or dynamically linked with
5128 @file{libgettext.la} is not yet known: this will depend on the
5129 configuration of libtool and the capabilities of the host.
5132 @node Conditional Libtool Libraries
5133 @subsection Building Libtool Libraries Conditionally
5134 @cindex libtool libraries, conditional
5135 @cindex conditional libtool libraries
5137 Like conditional programs (@pxref{Conditional Programs}), there are
5138 two main ways to build conditional libraries: using Automake
5139 conditionals or using Autoconf @code{AC_SUBST}itutions.
5141 The important implementation detail you have to be aware of is that
5142 the place where a library will be installed matters to libtool: it
5143 needs to be indicated @emph{at link-time} using the @option{-rpath}
5146 For libraries whose destination directory is known when Automake runs,
5147 Automake will automatically supply the appropriate @option{-rpath}
5148 option to libtool. This is the case for libraries listed explicitly in
5149 some installable @code{_LTLIBRARIES} variables such as
5150 @code{lib_LTLIBRARIES}.
5152 However, for libraries determined at configure time (and thus
5153 mentioned in @code{EXTRA_LTLIBRARIES}), Automake does not know the
5154 final installation directory. For such libraries you must add the
5155 @option{-rpath} option to the appropriate @code{_LDFLAGS} variable by
5158 The examples below illustrate the differences between these two methods.
5160 Here is an example where @code{WANTEDLIBS} is an @code{AC_SUBST}ed
5161 variable set at @file{./configure}-time to either @file{libfoo.la},
5162 @file{libbar.la}, both, or none. Although @samp{$(WANTEDLIBS)}
5163 appears in the @code{lib_LTLIBRARIES}, Automake cannot guess it
5164 relates to @file{libfoo.la} or @file{libbar.la} at the time it creates
5165 the link rule for these two libraries. Therefore the @option{-rpath}
5166 argument must be explicitly supplied.
5168 @c Keep in sync with ltcond.sh
5170 EXTRA_LTLIBRARIES = libfoo.la libbar.la
5171 lib_LTLIBRARIES = $(WANTEDLIBS)
5172 libfoo_la_SOURCES = foo.c @dots{}
5173 libfoo_la_LDFLAGS = -rpath '$(libdir)'
5174 libbar_la_SOURCES = bar.c @dots{}
5175 libbar_la_LDFLAGS = -rpath '$(libdir)'
5178 Here is how the same @file{Makefile.am} would look using Automake
5179 conditionals named @code{WANT_LIBFOO} and @code{WANT_LIBBAR}. Now
5180 Automake is able to compute the @option{-rpath} setting itself, because
5181 it's clear that both libraries will end up in @samp{$(libdir)} if they
5184 @c Keep in sync with ltcond.sh
5188 lib_LTLIBRARIES += libfoo.la
5191 lib_LTLIBRARIES += libbar.la
5193 libfoo_la_SOURCES = foo.c @dots{}
5194 libbar_la_SOURCES = bar.c @dots{}
5197 @node Conditional Libtool Sources
5198 @subsection Libtool Libraries with Conditional Sources
5200 Conditional compilation of sources in a library can be achieved in the
5201 same way as conditional compilation of sources in a program
5202 (@pxref{Conditional Sources}). The only difference is that
5203 @code{_LIBADD} should be used instead of @code{_LDADD} and that it
5204 should mention libtool objects (@file{.lo} files).
5206 So, to mimic the @file{hello} example from @ref{Conditional Sources},
5207 we could build a @file{libhello.la} library using either
5208 @file{hello-linux.c} or @file{hello-generic.c} with the following
5211 @c Keep in sync with ltcond2.sh
5213 lib_LTLIBRARIES = libhello.la
5214 libhello_la_SOURCES = hello-common.c
5215 EXTRA_libhello_la_SOURCES = hello-linux.c hello-generic.c
5216 libhello_la_LIBADD = $(HELLO_SYSTEM)
5217 libhello_la_DEPENDENCIES = $(HELLO_SYSTEM)
5221 And make sure @command{configure} defines @code{HELLO_SYSTEM} as
5222 either @file{hello-linux.lo} or @file{hello-@-generic.lo}.
5224 Or we could simply use an Automake conditional as follows.
5226 @c Keep in sync with ltcond2.sh
5228 lib_LTLIBRARIES = libhello.la
5229 libhello_la_SOURCES = hello-common.c
5231 libhello_la_SOURCES += hello-linux.c
5233 libhello_la_SOURCES += hello-generic.c
5237 @node Libtool Convenience Libraries
5238 @subsection Libtool Convenience Libraries
5239 @cindex convenience libraries, libtool
5240 @cindex libtool convenience libraries
5241 @vindex noinst_LTLIBRARIES
5242 @vindex check_LTLIBRARIES
5244 Sometimes you want to build libtool libraries that should not be
5245 installed. These are called @dfn{libtool convenience libraries} and
5246 are typically used to encapsulate many sublibraries, later gathered
5247 into one big installed library.
5249 Libtool convenience libraries are declared by directory-less variables
5250 such as @code{noinst_LTLIBRARIES}, @code{check_LTLIBRARIES}, or even
5251 @code{EXTRA_LTLIBRARIES}. Unlike installed libtool libraries they do
5252 not need an @option{-rpath} flag at link time (actually this is the only
5255 Convenience libraries listed in @code{noinst_LTLIBRARIES} are always
5256 built. Those listed in @code{check_LTLIBRARIES} are built only upon
5257 @samp{make check}. Finally, libraries listed in
5258 @code{EXTRA_LTLIBRARIES} are never built explicitly: Automake outputs
5259 rules to build them, but if the library does not appear as a Makefile
5260 dependency anywhere it won't be built (this is why
5261 @code{EXTRA_LTLIBRARIES} is used for conditional compilation).
5263 Here is a sample setup merging libtool convenience libraries from
5264 subdirectories into one main @file{libtop.la} library.
5266 @c Keep in sync with ltconv.sh
5268 # -- Top-level Makefile.am --
5269 SUBDIRS = sub1 sub2 @dots{}
5270 lib_LTLIBRARIES = libtop.la
5272 libtop_la_LIBADD = \
5277 # -- sub1/Makefile.am --
5278 noinst_LTLIBRARIES = libsub1.la
5279 libsub1_la_SOURCES = @dots{}
5281 # -- sub2/Makefile.am --
5282 # showing nested convenience libraries
5283 SUBDIRS = sub2.1 sub2.2 @dots{}
5284 noinst_LTLIBRARIES = libsub2.la
5285 libsub2_la_SOURCES =
5286 libsub2_la_LIBADD = \
5292 When using such setup, beware that @command{automake} will assume
5293 @file{libtop.la} is to be linked with the C linker. This is because
5294 @code{libtop_la_SOURCES} is empty, so @command{automake} picks C as
5295 default language. If @code{libtop_la_SOURCES} was not empty,
5296 @command{automake} would select the linker as explained in @ref{How
5297 the Linker is Chosen}.
5299 If one of the sublibraries contains non-C source, it is important that
5300 the appropriate linker be chosen. One way to achieve this is to
5301 pretend that there is such a non-C file among the sources of the
5302 library, thus forcing @command{automake} to select the appropriate
5303 linker. Here is the top-level @file{Makefile} of our example updated
5304 to force C++ linking.
5307 SUBDIRS = sub1 sub2 @dots{}
5308 lib_LTLIBRARIES = libtop.la
5310 # Dummy C++ source to cause C++ linking.
5311 nodist_EXTRA_libtop_la_SOURCES = dummy.cxx
5312 libtop_la_LIBADD = \
5318 @samp{EXTRA_*_SOURCES} variables are used to keep track of source
5319 files that might be compiled (this is mostly useful when doing
5320 conditional compilation using @code{AC_SUBST}, @pxref{Conditional
5321 Libtool Sources}), and the @code{nodist_} prefix means the listed
5322 sources are not to be distributed (@pxref{Program and Library
5323 Variables}). In effect the file @file{dummy.cxx} does not need to
5324 exist in the source tree. Of course if you have some real source file
5325 to list in @code{libtop_la_SOURCES} there is no point in cheating with
5326 @code{nodist_EXTRA_libtop_la_SOURCES}.
5329 @node Libtool Modules
5330 @subsection Libtool Modules
5331 @cindex modules, libtool
5332 @cindex libtool modules
5333 @cindex @option{-module}, libtool
5335 These are libtool libraries meant to be dlopened. They are
5336 indicated to libtool by passing @option{-module} at link-time.
5339 pkglib_LTLIBRARIES = mymodule.la
5340 mymodule_la_SOURCES = doit.c
5341 mymodule_la_LDFLAGS = -module
5344 Ordinarily, Automake requires that a library's name start with
5345 @code{lib}. However, when building a dynamically loadable module you
5346 might wish to use a "nonstandard" name. Automake will not complain
5347 about such nonstandard names if it knows the library being built is a
5348 libtool module, i.e., if @option{-module} explicitly appears in the
5349 library's @code{_LDFLAGS} variable (or in the common @code{AM_LDFLAGS}
5350 variable when no per-library @code{_LDFLAGS} variable is defined).
5352 As always, @code{AC_SUBST} variables are black boxes to Automake since
5353 their values are not yet known when @command{automake} is run.
5354 Therefore if @option{-module} is set via such a variable, Automake
5355 cannot notice it and will proceed as if the library was an ordinary
5356 libtool library, with strict naming.
5358 If @code{mymodule_la_SOURCES} is not specified, then it defaults to
5359 the single file @file{mymodule.c} (@pxref{Default _SOURCES}).
5362 @subsection @code{_LIBADD}, @code{_LDFLAGS}, and @code{_LIBTOOLFLAGS}
5363 @cindex @code{_LIBADD}, libtool
5364 @cindex @code{_LDFLAGS}, libtool
5365 @cindex @code{_LIBTOOLFLAGS}, libtool
5366 @vindex AM_LIBTOOLFLAGS
5367 @vindex LIBTOOLFLAGS
5368 @vindex maude_LIBTOOLFLAGS
5370 As shown in previous sections, the @samp{@var{library}_LIBADD}
5371 variable should be used to list extra libtool objects (@file{.lo}
5372 files) or libtool libraries (@file{.la}) to add to @var{library}.
5374 The @samp{@var{library}_LDFLAGS} variable is the place to list
5375 additional libtool linking flags, such as @option{-version-info},
5376 @option{-static}, and a lot more. @xref{Link mode, , Link mode,
5377 libtool, The Libtool Manual}.
5379 The @command{libtool} command has two kinds of options: mode-specific
5380 options and generic options. Mode-specific options such as the
5381 aforementioned linking flags should be lumped with the other flags
5382 passed to the tool invoked by @command{libtool} (hence the use of
5383 @samp{@var{library}_LDFLAGS} for libtool linking flags). Generic
5384 options include @option{--tag=@var{tag}} and @option{--silent}
5385 (@pxref{Invoking libtool, , Invoking @command{libtool}, libtool, The
5386 Libtool Manual} for more options) should appear before the mode
5387 selection on the command line; in @file{Makefile.am}s they should
5388 be listed in the @samp{@var{library}_LIBTOOLFLAGS} variable.
5390 If @samp{@var{library}_LIBTOOLFLAGS} is not defined, then the variable
5391 @code{AM_LIBTOOLFLAGS} is used instead.
5393 These flags are passed to libtool after the @option{--tag=@var{tag}}
5394 option computed by Automake (if any), so
5395 @samp{@var{library}_LIBTOOLFLAGS} (or @code{AM_LIBTOOLFLAGS}) is a
5396 good place to override or supplement the @option{--tag=@var{tag}}
5399 The libtool rules also use a @code{LIBTOOLFLAGS} variable that should
5400 not be set in @file{Makefile.am}: this is a user variable (@pxref{Flag
5401 Variables Ordering}. It allows users to run @samp{make
5402 LIBTOOLFLAGS=--silent}, for instance. Note that the verbosity of
5403 @command{libtool} can also be influenced by the Automake support
5404 for silent rules (@pxref{Automake Silent Rules}).
5406 @node LTLIBOBJS, Libtool Issues, Libtool Flags, A Shared Library
5407 @subsection @code{LTLIBOBJS} and @code{LTALLOCA}
5408 @cindex @code{LTLIBOBJS}, special handling
5409 @cindex @code{LIBOBJS}, and Libtool
5410 @cindex @code{LTALLOCA}, special handling
5411 @cindex @code{ALLOCA}, and Libtool
5418 Where an ordinary library might include @samp{$(LIBOBJS)} or
5419 @samp{$(ALLOCA)} (@pxref{LIBOBJS}), a libtool library must use
5420 @samp{$(LTLIBOBJS)} or @samp{$(LTALLOCA)}. This is required because
5421 the object files that libtool operates on do not necessarily end in
5424 Nowadays, the computation of @code{LTLIBOBJS} from @code{LIBOBJS} is
5425 performed automatically by Autoconf (@pxref{AC_LIBOBJ vs LIBOBJS, ,
5426 @code{AC_LIBOBJ} vs.@: @code{LIBOBJS}, autoconf, The Autoconf Manual}).
5428 @node Libtool Issues
5429 @subsection Common Issues Related to Libtool's Use
5432 * Error required file ltmain.sh not found:: The need to run libtoolize
5433 * Objects created both with libtool and without:: Avoid a specific build race
5436 @node Error required file ltmain.sh not found
5437 @subsubsection Error: @samp{required file `./ltmain.sh' not found}
5438 @cindex @file{ltmain.sh} not found
5439 @cindex @command{libtoolize}, no longer run by @command{automake}
5440 @cindex @command{libtoolize} and @command{autoreconf}
5441 @cindex @command{autoreconf} and @command{libtoolize}
5442 @cindex @file{bootstrap.sh} and @command{autoreconf}
5443 @cindex @file{autogen.sh} and @command{autoreconf}
5445 Libtool comes with a tool called @command{libtoolize} that will
5446 install libtool's supporting files into a package. Running this
5447 command will install @file{ltmain.sh}. You should execute it before
5448 @command{aclocal} and @command{automake}.
5450 People upgrading old packages to newer autotools are likely to face
5451 this issue because older Automake versions used to call
5452 @command{libtoolize}. Therefore old build scripts do not call
5453 @command{libtoolize}.
5455 Since Automake 1.6, it has been decided that running
5456 @command{libtoolize} was none of Automake's business. Instead, that
5457 functionality has been moved into the @command{autoreconf} command
5458 (@pxref{autoreconf Invocation, , Using @command{autoreconf}, autoconf,
5459 The Autoconf Manual}). If you do not want to remember what to run and
5460 when, just learn the @command{autoreconf} command. Hopefully,
5461 replacing existing @file{bootstrap.sh} or @file{autogen.sh} scripts by
5462 a call to @command{autoreconf} should also free you from any similar
5463 incompatible change in the future.
5465 @node Objects created both with libtool and without
5466 @subsubsection Objects @samp{created with both libtool and without}
5468 Sometimes, the same source file is used both to build a libtool
5469 library and to build another non-libtool target (be it a program or
5472 Let's consider the following @file{Makefile.am}.
5476 prog_SOURCES = prog.c foo.c @dots{}
5478 lib_LTLIBRARIES = libfoo.la
5479 libfoo_la_SOURCES = foo.c @dots{}
5483 (In this trivial case the issue could be avoided by linking
5484 @file{libfoo.la} with @file{prog} instead of listing @file{foo.c} in
5485 @code{prog_SOURCES}. But let's assume we really want to keep
5486 @file{prog} and @file{libfoo.la} separate.)
5488 Technically, it means that we should build @file{foo.$(OBJEXT)} for
5489 @file{prog}, and @file{foo.lo} for @file{libfoo.la}. The problem is
5490 that in the course of creating @file{foo.lo}, libtool may erase (or
5491 replace) @file{foo.$(OBJEXT)}, and this cannot be avoided.
5493 Therefore, when Automake detects this situation it will complain
5494 with a message such as
5496 object `foo.$(OBJEXT)' created both with libtool and without
5499 A workaround for this issue is to ensure that these two objects get
5500 different basenames. As explained in @ref{Renamed Objects}, this
5501 happens automatically when per-targets flags are used.
5505 prog_SOURCES = prog.c foo.c @dots{}
5506 prog_CFLAGS = $(AM_CFLAGS)
5508 lib_LTLIBRARIES = libfoo.la
5509 libfoo_la_SOURCES = foo.c @dots{}
5513 Adding @samp{prog_CFLAGS = $(AM_CFLAGS)} is almost a no-op, because
5514 when the @code{prog_CFLAGS} is defined, it is used instead of
5515 @code{AM_CFLAGS}. However as a side effect it will cause
5516 @file{prog.c} and @file{foo.c} to be compiled as
5517 @file{prog-prog.$(OBJEXT)} and @file{prog-foo.$(OBJEXT)}, which solves
5520 @node Program and Library Variables
5521 @section Program and Library Variables
5523 Associated with each program is a collection of variables that can be
5524 used to modify how that program is built. There is a similar list of
5525 such variables for each library. The canonical name of the program (or
5526 library) is used as a base for naming these variables.
5528 In the list below, we use the name ``maude'' to refer to the program or
5529 library. In your @file{Makefile.am} you would replace this with the
5530 canonical name of your program. This list also refers to ``maude'' as a
5531 program, but in general the same rules apply for both static and dynamic
5532 libraries; the documentation below notes situations where programs and
5537 This variable, if it exists, lists all the source files that are
5538 compiled to build the program. These files are added to the
5539 distribution by default. When building the program, Automake will cause
5540 each source file to be compiled to a single @file{.o} file (or
5541 @file{.lo} when using libtool). Normally these object files are named
5542 after the source file, but other factors can change this. If a file in
5543 the @code{_SOURCES} variable has an unrecognized extension, Automake
5544 will do one of two things with it. If a suffix rule exists for turning
5545 files with the unrecognized extension into @file{.o} files, then
5546 @command{automake} will treat this file as it will any other source file
5547 (@pxref{Support for Other Languages}). Otherwise, the file will be
5548 ignored as though it were a header file.
5550 The prefixes @code{dist_} and @code{nodist_} can be used to control
5551 whether files listed in a @code{_SOURCES} variable are distributed.
5552 @code{dist_} is redundant, as sources are distributed by default, but it
5553 can be specified for clarity if desired.
5555 It is possible to have both @code{dist_} and @code{nodist_} variants of
5556 a given @code{_SOURCES} variable at once; this lets you easily
5557 distribute some files and not others, for instance:
5560 nodist_maude_SOURCES = nodist.c
5561 dist_maude_SOURCES = dist-me.c
5564 By default the output file (on Unix systems, the @file{.o} file) will
5565 be put into the current build directory. However, if the option
5566 @option{subdir-objects} is in effect in the current directory then the
5567 @file{.o} file will be put into the subdirectory named after the
5568 source file. For instance, with @option{subdir-objects} enabled,
5569 @file{sub/dir/file.c} will be compiled to @file{sub/dir/file.o}. Some
5570 people prefer this mode of operation. You can specify
5571 @option{subdir-objects} in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
5572 @cindex Subdirectory, objects in
5573 @cindex Objects in subdirectory
5576 @item EXTRA_maude_SOURCES
5577 Automake needs to know the list of files you intend to compile
5578 @emph{statically}. For one thing, this is the only way Automake has of
5579 knowing what sort of language support a given @file{Makefile.in}
5580 requires. @footnote{There are other, more obscure reasons for
5581 this limitation as well.} This means that, for example, you can't put a
5582 configure substitution like @samp{@@my_sources@@} into a @samp{_SOURCES}
5583 variable. If you intend to conditionally compile source files and use
5584 @file{configure} to substitute the appropriate object names into, e.g.,
5585 @code{_LDADD} (see below), then you should list the corresponding source
5586 files in the @code{EXTRA_} variable.
5588 This variable also supports @code{dist_} and @code{nodist_} prefixes.
5589 For instance, @code{nodist_EXTRA_maude_SOURCES} would list extra
5590 sources that may need to be built, but should not be distributed.
5593 A static library is created by default by invoking @samp{$(AR)
5594 $(ARFLAGS)} followed by the name of the library and then the objects
5595 being put into the library. You can override this by setting the
5596 @code{_AR} variable. This is usually used with C++; some C++
5597 compilers require a special invocation in order to instantiate all the
5598 templates that should go into a library. For instance, the SGI C++
5599 compiler likes this variable set like so:
5601 libmaude_a_AR = $(CXX) -ar -o
5605 Extra objects can be added to a @emph{library} using the @code{_LIBADD}
5606 variable. For instance, this should be used for objects determined by
5607 @command{configure} (@pxref{A Library}).
5609 In the case of libtool libraries, @code{maude_LIBADD} can also refer
5610 to other libtool libraries.
5613 Extra objects (@file{*.$(OBJEXT)}) and libraries (@file{*.a},
5614 @file{*.la}) can be added to a @emph{program} by listing them in the
5615 @code{_LDADD} variable. For instance, this should be used for objects
5616 determined by @command{configure} (@pxref{Linking}).
5618 @code{_LDADD} and @code{_LIBADD} are inappropriate for passing
5619 program-specific linker flags (except for @option{-l}, @option{-L},
5620 @option{-dlopen} and @option{-dlpreopen}). Use the @code{_LDFLAGS} variable
5623 For instance, if your @file{configure.ac} uses @code{AC_PATH_XTRA}, you
5624 could link your program against the X libraries like so:
5627 maude_LDADD = $(X_PRE_LIBS) $(X_LIBS) $(X_EXTRA_LIBS)
5630 We recommend that you use @option{-l} and @option{-L} only when
5631 referring to third-party libraries, and give the explicit file names
5632 of any library built by your package. Doing so will ensure that
5633 @code{maude_DEPENDENCIES} (see below) is correctly defined by default.
5636 This variable is used to pass extra flags to the link step of a program
5637 or a shared library. It overrides the @code{AM_LDFLAGS} variable.
5639 @item maude_LIBTOOLFLAGS
5640 This variable is used to pass extra options to @command{libtool}.
5641 It overrides the @code{AM_LIBTOOLFLAGS} variable.
5642 These options are output before @command{libtool}'s @option{--mode=@var{mode}}
5643 option, so they should not be mode-specific options (those belong to
5644 the compiler or linker flags). @xref{Libtool Flags}.
5646 @item maude_DEPENDENCIES
5647 @itemx EXTRA_maude_DEPENDENCIES
5648 It is also occasionally useful to have a target (program or library)
5649 depend on some other file that is not actually part of that target.
5650 This can be done using the @code{_DEPENDENCIES} variable. Each
5651 target depends on the contents of such a variable, but no further
5652 interpretation is done.
5654 Since these dependencies are associated to the link rule used to
5655 create the programs they should normally list files used by the link
5656 command. That is @file{*.$(OBJEXT)}, @file{*.a}, or @file{*.la} files
5657 for programs; @file{*.lo} and @file{*.la} files for Libtool libraries;
5658 and @file{*.$(OBJEXT)} files for static libraries. In rare cases you
5659 may need to add other kinds of files such as linker scripts, but
5660 @emph{listing a source file in @code{_DEPENDENCIES} is wrong}. If
5661 some source file needs to be built before all the components of a
5662 program are built, consider using the @code{BUILT_SOURCES} variable
5665 If @code{_DEPENDENCIES} is not supplied, it is computed by Automake.
5666 The automatically-assigned value is the contents of @code{_LDADD} or
5667 @code{_LIBADD}, with most configure substitutions, @option{-l}, @option{-L},
5668 @option{-dlopen} and @option{-dlpreopen} options removed. The configure
5669 substitutions that are left in are only @samp{$(LIBOBJS)} and
5670 @samp{$(ALLOCA)}; these are left because it is known that they will not
5671 cause an invalid value for @code{_DEPENDENCIES} to be generated.
5673 @code{_DEPENDENCIES} is more likely used to perform conditional
5674 compilation using an @code{AC_SUBST} variable that contains a list of
5675 objects. @xref{Conditional Sources}, and @ref{Conditional Libtool
5678 The @code{EXTRA_*_DEPENDENCIES} variable may be useful for cases where
5679 you merely want to augment the @command{automake}-generated
5680 @code{_DEPENDENCIES} variable rather than replacing it.
5683 You can override the linker on a per-program basis. By default the
5684 linker is chosen according to the languages used by the program. For
5685 instance, a program that includes C++ source code would use the C++
5686 compiler to link. The @code{_LINK} variable must hold the name of a
5687 command that can be passed all the @file{.o} file names and libraries
5688 to link against as arguments. Note that the name of the underlying
5689 program is @emph{not} passed to @code{_LINK}; typically one uses
5693 maude_LINK = $(CCLD) -magic -o $@@
5696 If a @code{_LINK} variable is not supplied, it may still be generated
5697 and used by Automake due to the use of per-target link flags such as
5698 @code{_CFLAGS}, @code{_LDFLAGS} or @code{_LIBTOOLFLAGS}, in cases where
5701 @item maude_CCASFLAGS
5703 @itemx maude_CPPFLAGS
5704 @itemx maude_CXXFLAGS
5706 @itemx maude_GCJFLAGS
5708 @itemx maude_OBJCFLAGS
5710 @itemx maude_UPCFLAGS
5712 @cindex per-target compilation flags, defined
5713 Automake allows you to set compilation flags on a per-program (or
5714 per-library) basis. A single source file can be included in several
5715 programs, and it will potentially be compiled with different flags for
5716 each program. This works for any language directly supported by
5717 Automake. These @dfn{per-target compilation flags} are
5727 @samp{_UPCFLAGS}, and
5730 When using a per-target compilation flag, Automake will choose a
5731 different name for the intermediate object files. Ordinarily a file
5732 like @file{sample.c} will be compiled to produce @file{sample.o}.
5733 However, if the program's @code{_CFLAGS} variable is set, then the
5734 object file will be named, for instance, @file{maude-sample.o}. (See
5735 also @ref{Renamed Objects}.) The use of per-target compilation flags
5736 with C sources requires that the macro @code{AM_PROG_CC_C_O} be called
5737 from @file{configure.ac}.
5739 In compilations with per-target flags, the ordinary @samp{AM_} form of
5740 the flags variable is @emph{not} automatically included in the
5741 compilation (however, the user form of the variable @emph{is} included).
5742 So for instance, if you want the hypothetical @file{maude} compilations
5743 to also use the value of @code{AM_CFLAGS}, you would need to write:
5746 maude_CFLAGS = @dots{} your flags @dots{} $(AM_CFLAGS)
5749 @xref{Flag Variables Ordering}, for more discussion about the
5750 interaction between user variables, @samp{AM_} shadow variables, and
5751 per-target variables.
5753 @item maude_SHORTNAME
5754 On some platforms the allowable file names are very short. In order to
5755 support these systems and per-target compilation flags at the same
5756 time, Automake allows you to set a ``short name'' that will influence
5757 how intermediate object files are named. For instance, in the following
5761 bin_PROGRAMS = maude
5762 maude_CPPFLAGS = -DSOMEFLAG
5764 maude_SOURCES = sample.c @dots{}
5768 the object file would be named @file{m-sample.o} rather than
5769 @file{maude-sample.o}.
5771 This facility is rarely needed in practice,
5772 and we recommend avoiding it until you find it is required.
5775 @node Default _SOURCES
5776 @section Default @code{_SOURCES}
5780 @cindex @code{_SOURCES}, default
5781 @cindex default @code{_SOURCES}
5782 @vindex AM_DEFAULT_SOURCE_EXT
5784 @code{_SOURCES} variables are used to specify source files of programs
5785 (@pxref{A Program}), libraries (@pxref{A Library}), and Libtool
5786 libraries (@pxref{A Shared Library}).
5788 When no such variable is specified for a target, Automake will define
5789 one itself. The default is to compile a single C file whose base name
5790 is the name of the target itself, with any extension replaced by
5791 @code{AM_DEFAULT_SOURCE_EXT}, which defaults to @file{.c}.
5793 For example if you have the following somewhere in your
5794 @file{Makefile.am} with no corresponding @code{libfoo_a_SOURCES}:
5797 lib_LIBRARIES = libfoo.a sub/libc++.a
5801 @file{libfoo.a} will be built using a default source file named
5802 @file{libfoo.c}, and @file{sub/libc++.a} will be built from
5803 @file{sub/libc++.c}. (In older versions @file{sub/libc++.a}
5804 would be built from @file{sub_libc___a.c}, i.e., the default source
5805 was the canonized name of the target, with @file{.c} appended.
5806 We believe the new behavior is more sensible, but for backward
5807 compatibility @command{automake} will use the old name if a file or a rule
5808 with that name exists and @code{AM_DEFAULT_SOURCE_EXT} is not used.)
5810 @cindex @code{check_PROGRAMS} example
5811 @vindex check_PROGRAMS
5812 Default sources are mainly useful in test suites, when building many
5813 test programs each from a single source. For instance, in
5816 check_PROGRAMS = test1 test2 test3
5817 AM_DEFAULT_SOURCE_EXT = .cpp
5821 @file{test1}, @file{test2}, and @file{test3} will be built
5822 from @file{test1.cpp}, @file{test2.cpp}, and @file{test3.cpp}.
5823 Without the last line, they will be built from @file{test1.c},
5824 @file{test2.c}, and @file{test3.c}.
5826 @cindex Libtool modules, default source example
5827 @cindex default source, Libtool modules example
5828 Another case where this is convenient is building many Libtool modules
5829 (@file{module@var{n}.la}), each defined in its own file
5830 (@file{module@var{n}.c}).
5833 AM_LDFLAGS = -module
5834 lib_LTLIBRARIES = module1.la module2.la module3.la
5837 @cindex empty @code{_SOURCES}
5838 @cindex @code{_SOURCES}, empty
5839 Finally, there is one situation where this default source computation
5840 needs to be avoided: when a target should not be built from sources.
5841 We already saw such an example in @ref{true}; this happens when all
5842 the constituents of a target have already been compiled and just need
5843 to be combined using a @code{_LDADD} variable. Then it is necessary
5844 to define an empty @code{_SOURCES} variable, so that @command{automake}
5845 does not compute a default.
5848 bin_PROGRAMS = target
5850 target_LDADD = libmain.a libmisc.a
5854 @section Special handling for @code{LIBOBJS} and @code{ALLOCA}
5856 @cindex @code{LIBOBJS}, example
5857 @cindex @code{ALLOCA}, example
5858 @cindex @code{LIBOBJS}, special handling
5859 @cindex @code{ALLOCA}, special handling
5865 The @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} variables list object
5866 files that should be compiled into the project to provide an
5867 implementation for functions that are missing or broken on the host
5868 system. They are substituted by @file{configure}.
5872 These variables are defined by Autoconf macros such as
5873 @code{AC_LIBOBJ}, @code{AC_REPLACE_FUNCS} (@pxref{Generic Functions, ,
5874 Generic Function Checks, autoconf, The Autoconf Manual}), or
5875 @code{AC_FUNC_ALLOCA} (@pxref{Particular Functions, , Particular
5876 Function Checks, autoconf, The Autoconf Manual}). Many other Autoconf
5877 macros call @code{AC_LIBOBJ} or @code{AC_REPLACE_FUNCS} to
5878 populate @samp{$(LIBOBJS)}.
5880 @acindex AC_LIBSOURCE
5882 Using these variables is very similar to doing conditional compilation
5883 using @code{AC_SUBST} variables, as described in @ref{Conditional
5884 Sources}. That is, when building a program, @samp{$(LIBOBJS)} and
5885 @samp{$(ALLOCA)} should be added to the associated @samp{*_LDADD}
5886 variable, or to the @samp{*_LIBADD} variable when building a library.
5887 However there is no need to list the corresponding sources in
5888 @samp{EXTRA_*_SOURCES} nor to define @samp{*_DEPENDENCIES}. Automake
5889 automatically adds @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} to the
5890 dependencies, and it will discover the list of corresponding source
5891 files automatically (by tracing the invocations of the
5892 @code{AC_LIBSOURCE} Autoconf macros). If you have already defined
5893 @samp{*_DEPENDENCIES} explicitly for an unrelated reason, then you
5894 either need to add these variables manually, or use
5895 @samp{EXTRA_*_DEPENDENCIES} instead of @samp{*_DEPENDENCIES}.
5897 These variables are usually used to build a portability library that
5898 is linked with all the programs of the project. We now review a
5899 sample setup. First, @file{configure.ac} contains some checks that
5900 affect either @code{LIBOBJS} or @code{ALLOCA}.
5905 AC_CONFIG_LIBOBJ_DIR([lib])
5907 AC_FUNC_MALLOC dnl May add malloc.$(OBJEXT) to LIBOBJS
5908 AC_FUNC_MEMCMP dnl May add memcmp.$(OBJEXT) to LIBOBJS
5909 AC_REPLACE_FUNCS([strdup]) dnl May add strdup.$(OBJEXT) to LIBOBJS
5910 AC_FUNC_ALLOCA dnl May add alloca.$(OBJEXT) to ALLOCA
5919 @acindex AC_CONFIG_LIBOBJ_DIR
5921 The @code{AC_CONFIG_LIBOBJ_DIR} tells Autoconf that the source files
5922 of these object files are to be found in the @file{lib/} directory.
5923 Automake can also use this information, otherwise it expects the
5924 source files are to be in the directory where the @samp{$(LIBOBJS)}
5925 and @samp{$(ALLOCA)} variables are used.
5927 The @file{lib/} directory should therefore contain @file{malloc.c},
5928 @file{memcmp.c}, @file{strdup.c}, @file{alloca.c}. Here is its
5934 noinst_LIBRARIES = libcompat.a
5935 libcompat_a_SOURCES =
5936 libcompat_a_LIBADD = $(LIBOBJS) $(ALLOCA)
5939 The library can have any name, of course, and anyway it is not going
5940 to be installed: it just holds the replacement versions of the missing
5941 or broken functions so we can later link them in. Many projects
5942 also include extra functions, specific to the project, in that
5943 library: they are simply added on the @code{_SOURCES} line.
5945 @cindex Empty libraries and @samp{$(LIBOBJS)}
5946 @cindex @samp{$(LIBOBJS)} and empty libraries
5947 There is a small trap here, though: @samp{$(LIBOBJS)} and
5948 @samp{$(ALLOCA)} might be empty, and building an empty library is not
5949 portable. You should ensure that there is always something to put in
5950 @file{libcompat.a}. Most projects will also add some utility
5951 functions in that directory, and list them in
5952 @code{libcompat_a_SOURCES}, so in practice @file{libcompat.a} cannot
5955 Finally here is how this library could be used from the @file{src/}
5961 # Link all programs in this directory with libcompat.a
5962 LDADD = ../lib/libcompat.a
5964 bin_PROGRAMS = tool1 tool2 @dots{}
5965 tool1_SOURCES = @dots{}
5966 tool2_SOURCES = @dots{}
5969 When option @option{subdir-objects} is not used, as in the above
5970 example, the variables @samp{$(LIBOBJS)} or @samp{$(ALLOCA)} can only
5971 be used in the directory where their sources lie. E.g., here it would
5972 be wrong to use @samp{$(LIBOBJS)} or @samp{$(ALLOCA)} in
5973 @file{src/Makefile.am}. However if both @option{subdir-objects} and
5974 @code{AC_CONFIG_LIBOBJ_DIR} are used, it is OK to use these variables
5975 in other directories. For instance @file{src/Makefile.am} could be
5981 AUTOMAKE_OPTIONS = subdir-objects
5982 LDADD = $(LIBOBJS) $(ALLOCA)
5984 bin_PROGRAMS = tool1 tool2 @dots{}
5985 tool1_SOURCES = @dots{}
5986 tool2_SOURCES = @dots{}
5989 Because @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} contain object
5990 file names that end with @samp{.$(OBJEXT)}, they are not suitable for
5991 Libtool libraries (where the expected object extension is @file{.lo}):
5992 @code{LTLIBOBJS} and @code{LTALLOCA} should be used instead.
5994 @code{LTLIBOBJS} is defined automatically by Autoconf and should not
5995 be defined by hand (as in the past), however at the time of writing
5996 @code{LTALLOCA} still needs to be defined from @code{ALLOCA} manually.
5997 @xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs.@: @code{LIBOBJS},
5998 autoconf, The Autoconf Manual}.
6001 @node Program Variables
6002 @section Variables used when building a program
6004 Occasionally it is useful to know which @file{Makefile} variables
6005 Automake uses for compilations, and in which order (@pxref{Flag
6006 Variables Ordering}); for instance, you might need to do your own
6007 compilation in some special cases.
6009 Some variables are inherited from Autoconf; these are @code{CC},
6010 @code{CFLAGS}, @code{CPPFLAGS}, @code{DEFS}, @code{LDFLAGS}, and
6019 There are some additional variables that Automake defines on its own:
6023 The contents of this variable are passed to every compilation that invokes
6024 the C preprocessor; it is a list of arguments to the preprocessor. For
6025 instance, @option{-I} and @option{-D} options should be listed here.
6027 Automake already provides some @option{-I} options automatically, in a
6028 separate variable that is also passed to every compilation that invokes
6029 the C preprocessor. In particular it generates @samp{-I.},
6030 @samp{-I$(srcdir)}, and a @option{-I} pointing to the directory holding
6031 @file{config.h} (if you've used @code{AC_CONFIG_HEADERS} or
6032 @code{AM_CONFIG_HEADER}). You can disable the default @option{-I}
6033 options using the @option{nostdinc} option.
6035 When a file to be included is generated during the build and not part
6036 of a distribution tarball, its location is under @code{$(builddir)},
6037 not under @code{$(srcdir)}. This matters especially for packages that
6038 use header files placed in sub-directories and want to allow builds
6039 outside the source tree (@pxref{VPATH Builds}). In that case we
6040 recommend to use a pair of @option{-I} options, such as, e.g.,
6041 @samp{-Isome/subdir -I$(srcdir)/some/subdir} or
6042 @samp{-I$(top_builddir)/some/subdir -I$(top_srcdir)/some/subdir}.
6043 Note that the reference to the build tree should come before the
6044 reference to the source tree, so that accidentally leftover generated
6045 files in the source directory are ignored.
6047 @code{AM_CPPFLAGS} is ignored in preference to a per-executable (or
6048 per-library) @code{_CPPFLAGS} variable if it is defined.
6051 This does the same job as @code{AM_CPPFLAGS} (or any per-target
6052 @code{_CPPFLAGS} variable if it is used). It is an older name for the
6053 same functionality. This variable is deprecated; we suggest using
6054 @code{AM_CPPFLAGS} and per-target @code{_CPPFLAGS} instead.
6057 This is the variable the @file{Makefile.am} author can use to pass
6058 in additional C compiler flags. It is more fully documented elsewhere.
6059 In some situations, this is not used, in preference to the
6060 per-executable (or per-library) @code{_CFLAGS}.
6063 This is the command used to actually compile a C source file. The
6064 file name is appended to form the complete command line.
6067 This is the variable the @file{Makefile.am} author can use to pass
6068 in additional linker flags. In some situations, this is not used, in
6069 preference to the per-executable (or per-library) @code{_LDFLAGS}.
6072 This is the command used to actually link a C program. It already
6073 includes @samp{-o $@@} and the usual variable references (for instance,
6074 @code{CFLAGS}); it takes as ``arguments'' the names of the object files
6075 and libraries to link in. This variable is not used when the linker is
6076 overridden with a per-target @code{_LINK} variable or per-target flags
6077 cause Automake to define such a @code{_LINK} variable.
6082 @section Yacc and Lex support
6084 Automake has somewhat idiosyncratic support for Yacc and Lex.
6086 Automake assumes that the @file{.c} file generated by @command{yacc}
6087 (or @command{lex}) should be named using the basename of the input
6088 file. That is, for a yacc source file @file{foo.y}, Automake will
6089 cause the intermediate file to be named @file{foo.c} (as opposed to
6090 @file{y.tab.c}, which is more traditional).
6092 The extension of a yacc source file is used to determine the extension
6093 of the resulting C or C++ source and header files. Note that header
6094 files are generated only when the @option{-d} Yacc option is used; see
6095 below for more information about this flag, and how to specify it.
6096 Files with the extension @file{.y} will thus be turned into @file{.c}
6097 sources and @file{.h} headers; likewise, @file{.yy} will become
6098 @file{.cc} and @file{.hh}, @file{.y++} will become @file{c++} and
6099 @file{h++}, @file{.yxx} will become @file{.cxx} and @file{.hxx},
6100 and @file{.ypp} will become @file{.cpp} and @file{.hpp}.
6102 Similarly, lex source files can be used to generate C or C++; the
6103 extensions @file{.l}, @file{.ll}, @file{.l++}, @file{.lxx}, and
6104 @file{.lpp} are recognized.
6106 You should never explicitly mention the intermediate (C or C++) file
6107 in any @code{SOURCES} variable; only list the source file.
6109 The intermediate files generated by @command{yacc} (or @command{lex})
6110 will be included in any distribution that is made. That way the user
6111 doesn't need to have @command{yacc} or @command{lex}.
6113 If a @command{yacc} source file is seen, then your @file{configure.ac} must
6114 define the variable @code{YACC}. This is most easily done by invoking
6115 the macro @code{AC_PROG_YACC} (@pxref{Particular Programs, , Particular
6116 Program Checks, autoconf, The Autoconf Manual}).
6120 When @code{yacc} is invoked, it is passed @code{AM_YFLAGS} and
6121 @code{YFLAGS}. The latter is a user variable and the former is
6122 intended for the @file{Makefile.am} author.
6124 @code{AM_YFLAGS} is usually used to pass the @option{-d} option to
6125 @command{yacc}. Automake knows what this means and will automatically
6126 adjust its rules to update and distribute the header file built by
6127 @samp{yacc -d}@footnote{Please note that @command{automake} recognizes
6128 @option{-d} in @code{AM_YFLAGS} only if it is not clustered with other
6129 options; for example, it won't be recognized if @code{AM_YFLAGS} is
6130 @option{-dt}, but it will be if @code{AM_YFLAGS} is @option{-d -t} or
6132 What Automake cannot guess, though, is where this
6133 header will be used: it is up to you to ensure the header gets built
6134 before it is first used. Typically this is necessary in order for
6135 dependency tracking to work when the header is included by another
6136 file. The common solution is listing the header file in
6137 @code{BUILT_SOURCES} (@pxref{Sources}) as follows.
6140 BUILT_SOURCES = parser.h
6143 foo_SOURCES = @dots{} parser.y @dots{}
6146 If a @command{lex} source file is seen, then your @file{configure.ac}
6147 must define the variable @code{LEX}. You can use @code{AC_PROG_LEX}
6148 to do this (@pxref{Particular Programs, , Particular Program Checks,
6149 autoconf, The Autoconf Manual}), but using @code{AM_PROG_LEX} macro
6150 (@pxref{Macros}) is recommended.
6154 When @command{lex} is invoked, it is passed @code{AM_LFLAGS} and
6155 @code{LFLAGS}. The latter is a user variable and the former is
6156 intended for the @file{Makefile.am} author.
6158 When @code{AM_MAINTAINER_MODE} (@pxref{maintainer-mode}) is used, the
6159 rebuild rule for distributed Yacc and Lex sources are only used when
6160 @code{maintainer-mode} is enabled, or when the files have been erased.
6162 @cindex @command{ylwrap}
6163 @cindex @command{yacc}, multiple parsers
6164 @cindex Multiple @command{yacc} parsers
6165 @cindex Multiple @command{lex} lexers
6166 @cindex @command{lex}, multiple lexers
6168 When @command{lex} or @command{yacc} sources are used, @code{automake
6169 -i} automatically installs an auxiliary program called
6170 @command{ylwrap} in your package (@pxref{Auxiliary Programs}). This
6171 program is used by the build rules to rename the output of these
6172 tools, and makes it possible to include multiple @command{yacc} (or
6173 @command{lex}) source files in a single directory. (This is necessary
6174 because yacc's output file name is fixed, and a parallel make could
6175 conceivably invoke more than one instance of @command{yacc}
6178 For @command{yacc}, simply managing locking is insufficient. The output of
6179 @command{yacc} always uses the same symbol names internally, so it isn't
6180 possible to link two @command{yacc} parsers into the same executable.
6182 We recommend using the following renaming hack used in @command{gdb}:
6184 #define yymaxdepth c_maxdepth
6185 #define yyparse c_parse
6187 #define yyerror c_error
6188 #define yylval c_lval
6189 #define yychar c_char
6190 #define yydebug c_debug
6191 #define yypact c_pact
6198 #define yyexca c_exca
6199 #define yyerrflag c_errflag
6200 #define yynerrs c_nerrs
6204 #define yy_yys c_yys
6205 #define yystate c_state
6208 #define yy_yyv c_yyv
6210 #define yylloc c_lloc
6211 #define yyreds c_reds
6212 #define yytoks c_toks
6213 #define yylhs c_yylhs
6214 #define yylen c_yylen
6215 #define yydefred c_yydefred
6216 #define yydgoto c_yydgoto
6217 #define yysindex c_yysindex
6218 #define yyrindex c_yyrindex
6219 #define yygindex c_yygindex
6220 #define yytable c_yytable
6221 #define yycheck c_yycheck
6222 #define yyname c_yyname
6223 #define yyrule c_yyrule
6226 For each define, replace the @samp{c_} prefix with whatever you like.
6227 These defines work for @command{bison}, @command{byacc}, and
6228 traditional @code{yacc}s. If you find a parser generator that uses a
6229 symbol not covered here, please report the new name so it can be added
6234 @section C++ Support
6237 @cindex Support for C++
6239 Automake includes full support for C++.
6241 Any package including C++ code must define the output variable
6242 @code{CXX} in @file{configure.ac}; the simplest way to do this is to use
6243 the @code{AC_PROG_CXX} macro (@pxref{Particular Programs, , Particular
6244 Program Checks, autoconf, The Autoconf Manual}).
6246 A few additional variables are defined when a C++ source file is seen:
6250 The name of the C++ compiler.
6253 Any flags to pass to the C++ compiler.
6256 The maintainer's variant of @code{CXXFLAGS}.
6259 The command used to actually compile a C++ source file. The file name
6260 is appended to form the complete command line.
6263 The command used to actually link a C++ program.
6267 @node Objective C Support
6268 @section Objective C Support
6270 @cindex Objective C support
6271 @cindex Support for Objective C
6273 Automake includes some support for Objective C.
6275 Any package including Objective C code must define the output variable
6276 @code{OBJC} in @file{configure.ac}; the simplest way to do this is to use
6277 the @code{AC_PROG_OBJC} macro (@pxref{Particular Programs, , Particular
6278 Program Checks, autoconf, The Autoconf Manual}).
6280 A few additional variables are defined when an Objective C source file
6285 The name of the Objective C compiler.
6288 Any flags to pass to the Objective C compiler.
6291 The maintainer's variant of @code{OBJCFLAGS}.
6294 The command used to actually compile an Objective C source file. The
6295 file name is appended to form the complete command line.
6298 The command used to actually link an Objective C program.
6302 @node Unified Parallel C Support
6303 @section Unified Parallel C Support
6305 @cindex Unified Parallel C support
6306 @cindex Support for Unified Parallel C
6308 Automake includes some support for Unified Parallel C.
6310 Any package including Unified Parallel C code must define the output
6311 variable @code{UPC} in @file{configure.ac}; the simplest way to do
6312 this is to use the @code{AM_PROG_UPC} macro (@pxref{Public Macros}).
6314 A few additional variables are defined when a Unified Parallel C
6315 source file is seen:
6319 The name of the Unified Parallel C compiler.
6322 Any flags to pass to the Unified Parallel C compiler.
6325 The maintainer's variant of @code{UPCFLAGS}.
6328 The command used to actually compile a Unified Parallel C source file.
6329 The file name is appended to form the complete command line.
6332 The command used to actually link a Unified Parallel C program.
6336 @node Assembly Support
6337 @section Assembly Support
6339 Automake includes some support for assembly code. There are two forms
6340 of assembler files: normal (@file{*.s}) and preprocessed by @code{CPP}
6341 (@file{*.S} or @file{*.sx}).
6346 @vindex AM_CCASFLAGS
6348 The variable @code{CCAS} holds the name of the compiler used to build
6349 assembly code. This compiler must work a bit like a C compiler; in
6350 particular it must accept @option{-c} and @option{-o}. The values of
6351 @code{CCASFLAGS} and @code{AM_CCASFLAGS} (or its per-target
6352 definition) is passed to the compilation. For preprocessed files,
6353 @code{DEFS}, @code{DEFAULT_INCLUDES}, @code{INCLUDES}, @code{CPPFLAGS}
6354 and @code{AM_CPPFLAGS} are also used.
6356 The autoconf macro @code{AM_PROG_AS} will define @code{CCAS} and
6357 @code{CCASFLAGS} for you (unless they are already set, it simply sets
6358 @code{CCAS} to the C compiler and @code{CCASFLAGS} to the C compiler
6359 flags), but you are free to define these variables by other means.
6361 Only the suffixes @file{.s}, @file{.S}, and @file{.sx} are recognized by
6362 @command{automake} as being files containing assembly code.
6365 @node Fortran 77 Support
6366 @comment node-name, next, previous, up
6367 @section Fortran 77 Support
6369 @cindex Fortran 77 support
6370 @cindex Support for Fortran 77
6372 Automake includes full support for Fortran 77.
6374 Any package including Fortran 77 code must define the output variable
6375 @code{F77} in @file{configure.ac}; the simplest way to do this is to use
6376 the @code{AC_PROG_F77} macro (@pxref{Particular Programs, , Particular
6377 Program Checks, autoconf, The Autoconf Manual}).
6379 A few additional variables are defined when a Fortran 77 source file is
6385 The name of the Fortran 77 compiler.
6388 Any flags to pass to the Fortran 77 compiler.
6391 The maintainer's variant of @code{FFLAGS}.
6394 Any flags to pass to the Ratfor compiler.
6397 The maintainer's variant of @code{RFLAGS}.
6400 The command used to actually compile a Fortran 77 source file. The file
6401 name is appended to form the complete command line.
6404 The command used to actually link a pure Fortran 77 program or shared
6409 Automake can handle preprocessing Fortran 77 and Ratfor source files in
6410 addition to compiling them@footnote{Much, if not most, of the
6411 information in the following sections pertaining to preprocessing
6412 Fortran 77 programs was taken almost verbatim from @ref{Catalogue of
6413 Rules, , Catalogue of Rules, make, The GNU Make Manual}.}. Automake
6414 also contains some support for creating programs and shared libraries
6415 that are a mixture of Fortran 77 and other languages (@pxref{Mixing
6416 Fortran 77 With C and C++}).
6418 These issues are covered in the following sections.
6421 * Preprocessing Fortran 77:: Preprocessing Fortran 77 sources
6422 * Compiling Fortran 77 Files:: Compiling Fortran 77 sources
6423 * Mixing Fortran 77 With C and C++:: Mixing Fortran 77 With C and C++
6427 @node Preprocessing Fortran 77
6428 @comment node-name, next, previous, up
6429 @subsection Preprocessing Fortran 77
6431 @cindex Preprocessing Fortran 77
6432 @cindex Fortran 77, Preprocessing
6433 @cindex Ratfor programs
6435 @file{N.f} is made automatically from @file{N.F} or @file{N.r}. This
6436 rule runs just the preprocessor to convert a preprocessable Fortran 77
6437 or Ratfor source file into a strict Fortran 77 source file. The precise
6438 command used is as follows:
6443 @code{$(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)@*
6444 $(AM_FFLAGS) $(FFLAGS)}
6447 @code{$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
6452 @node Compiling Fortran 77 Files
6453 @comment node-name, next, previous, up
6454 @subsection Compiling Fortran 77 Files
6456 @file{N.o} is made automatically from @file{N.f}, @file{N.F} or
6457 @file{N.r} by running the Fortran 77 compiler. The precise command used
6463 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS)}
6466 @code{$(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)@*
6467 $(AM_FFLAGS) $(FFLAGS)}
6470 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
6475 @node Mixing Fortran 77 With C and C++
6476 @comment node-name, next, previous, up
6477 @subsection Mixing Fortran 77 With C and C++
6479 @cindex Fortran 77, mixing with C and C++
6480 @cindex Mixing Fortran 77 with C and C++
6481 @cindex Linking Fortran 77 with C and C++
6483 @cindex Mixing Fortran 77 with C and/or C++
6485 Automake currently provides @emph{limited} support for creating programs
6486 and shared libraries that are a mixture of Fortran 77 and C and/or C++.
6487 However, there are many other issues related to mixing Fortran 77 with
6488 other languages that are @emph{not} (currently) handled by Automake, but
6489 that are handled by other packages@footnote{For example,
6490 @uref{http://www-zeus.desy.de/~burow/cfortran/, the cfortran package}
6491 addresses all of these inter-language issues, and runs under nearly all
6492 Fortran 77, C and C++ compilers on nearly all platforms. However,
6493 @command{cfortran} is not yet Free Software, but it will be in the next
6496 Automake can help in two ways:
6500 Automatic selection of the linker depending on which combinations of
6504 Automatic selection of the appropriate linker flags (e.g., @option{-L} and
6505 @option{-l}) to pass to the automatically selected linker in order to link
6506 in the appropriate Fortran 77 intrinsic and run-time libraries.
6508 @cindex @code{FLIBS}, defined
6510 These extra Fortran 77 linker flags are supplied in the output variable
6511 @code{FLIBS} by the @code{AC_F77_LIBRARY_LDFLAGS} Autoconf macro.
6512 @xref{Fortran Compiler, , Fortran Compiler Characteristics, autoconf,
6513 The Autoconf Manual}.
6516 If Automake detects that a program or shared library (as mentioned in
6517 some @code{_PROGRAMS} or @code{_LTLIBRARIES} primary) contains source
6518 code that is a mixture of Fortran 77 and C and/or C++, then it requires
6519 that the macro @code{AC_F77_LIBRARY_LDFLAGS} be called in
6520 @file{configure.ac}, and that either @code{$(FLIBS)}
6521 appear in the appropriate @code{_LDADD} (for programs) or @code{_LIBADD}
6522 (for shared libraries) variables. It is the responsibility of the
6523 person writing the @file{Makefile.am} to make sure that @samp{$(FLIBS)}
6524 appears in the appropriate @code{_LDADD} or
6525 @code{_LIBADD} variable.
6527 @cindex Mixed language example
6528 @cindex Example, mixed language
6530 For example, consider the following @file{Makefile.am}:
6534 foo_SOURCES = main.cc foo.f
6535 foo_LDADD = libfoo.la $(FLIBS)
6537 pkglib_LTLIBRARIES = libfoo.la
6538 libfoo_la_SOURCES = bar.f baz.c zardoz.cc
6539 libfoo_la_LIBADD = $(FLIBS)
6542 In this case, Automake will insist that @code{AC_F77_LIBRARY_LDFLAGS}
6543 is mentioned in @file{configure.ac}. Also, if @samp{$(FLIBS)} hadn't
6544 been mentioned in @code{foo_LDADD} and @code{libfoo_la_LIBADD}, then
6545 Automake would have issued a warning.
6548 * How the Linker is Chosen:: Automatic linker selection
6551 @node How the Linker is Chosen
6552 @comment node-name, next, previous, up
6553 @subsubsection How the Linker is Chosen
6555 @cindex Automatic linker selection
6556 @cindex Selecting the linker automatically
6558 When a program or library mixes several languages, Automake choose the
6559 linker according to the following priorities. (The names in
6560 parentheses are the variables containing the link command.)
6565 Native Java (@code{GCJLINK})
6568 C++ (@code{CXXLINK})
6571 Fortran 77 (@code{F77LINK})
6574 Fortran (@code{FCLINK})
6577 Objective C (@code{OBJCLINK})
6580 Unified Parallel C (@code{UPCLINK})
6586 For example, if Fortran 77, C and C++ source code is compiled
6587 into a program, then the C++ linker will be used. In this case, if the
6588 C or Fortran 77 linkers required any special libraries that weren't
6589 included by the C++ linker, then they must be manually added to an
6590 @code{_LDADD} or @code{_LIBADD} variable by the user writing the
6593 Automake only looks at the file names listed in @file{_SOURCES}
6594 variables to choose the linker, and defaults to the C linker.
6595 Sometimes this is inconvenient because you are linking against a
6596 library written in another language and would like to set the linker
6597 more appropriately. @xref{Libtool Convenience Libraries}, for a
6598 trick with @code{nodist_EXTRA_@dots{}_SOURCES}.
6600 A per-target @code{_LINK} variable will override the above selection.
6601 Per-target link flags will cause Automake to write a per-target
6602 @code{_LINK} variable according to the language chosen as above.
6605 @node Fortran 9x Support
6606 @comment node-name, next, previous, up
6607 @section Fortran 9x Support
6609 @cindex Fortran 9x support
6610 @cindex Support for Fortran 9x
6612 Automake includes support for Fortran 9x.
6614 Any package including Fortran 9x code must define the output variable
6615 @code{FC} in @file{configure.ac}; the simplest way to do this is to use
6616 the @code{AC_PROG_FC} macro (@pxref{Particular Programs, , Particular
6617 Program Checks, autoconf, The Autoconf Manual}).
6619 A few additional variables are defined when a Fortran 9x source file is
6625 The name of the Fortran 9x compiler.
6628 Any flags to pass to the Fortran 9x compiler.
6631 The maintainer's variant of @code{FCFLAGS}.
6634 The command used to actually compile a Fortran 9x source file. The file
6635 name is appended to form the complete command line.
6638 The command used to actually link a pure Fortran 9x program or shared
6644 * Compiling Fortran 9x Files:: Compiling Fortran 9x sources
6647 @node Compiling Fortran 9x Files
6648 @comment node-name, next, previous, up
6649 @subsection Compiling Fortran 9x Files
6651 @file{@var{file}.o} is made automatically from @file{@var{file}.f90},
6652 @file{@var{file}.f95}, @file{@var{file}.f03}, or @file{@var{file}.f08}
6653 by running the Fortran 9x compiler. The precise command used
6659 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f90) $<}
6662 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f95) $<}
6665 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f03) $<}
6668 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f08) $<}
6672 @node Java Support with gcj
6673 @comment node-name, next, previous, up
6674 @section Compiling Java sources using gcj
6676 @cindex Java support with gcj
6677 @cindex Support for Java with gcj
6678 @cindex Java to native code, compilation
6679 @cindex Compilation of Java to native code
6681 Automake includes support for natively compiled Java, using @command{gcj},
6682 the Java front end to the GNU Compiler Collection (rudimentary support
6683 for compiling Java to bytecode using the @command{javac} compiler is
6684 also present, @emph{albeit deprecated}; @pxref{Java}).
6686 Any package including Java code to be compiled must define the output
6687 variable @code{GCJ} in @file{configure.ac}; the variable @code{GCJFLAGS}
6688 must also be defined somehow (either in @file{configure.ac} or
6689 @file{Makefile.am}). The simplest way to do this is to use the
6690 @code{AM_PROG_GCJ} macro.
6694 By default, programs including Java source files are linked with
6697 As always, the contents of @code{AM_GCJFLAGS} are passed to every
6698 compilation invoking @command{gcj} (in its role as an ahead-of-time
6699 compiler, when invoking it to create @file{.class} files,
6700 @code{AM_JAVACFLAGS} is used instead). If it is necessary to pass
6701 options to @command{gcj} from @file{Makefile.am}, this variable, and not
6702 the user variable @code{GCJFLAGS}, should be used.
6706 @command{gcj} can be used to compile @file{.java}, @file{.class},
6707 @file{.zip}, or @file{.jar} files.
6709 When linking, @command{gcj} requires that the main class be specified
6710 using the @option{--main=} option. The easiest way to do this is to use
6711 the @code{_LDFLAGS} variable for the program.
6715 @comment node-name, next, previous, up
6716 @section Vala Support
6718 @cindex Vala Support
6719 @cindex Support for Vala
6721 Automake provides initial support for Vala
6722 (@uref{http://www.vala-project.org/}).
6723 This requires valac version 0.7.0 or later, and currently requires
6724 the user to use GNU @command{make}.
6727 foo_SOURCES = foo.vala bar.vala zardoc.c
6730 Any @file{.vala} file listed in a @code{_SOURCES} variable will be
6731 compiled into C code by the Vala compiler. The generated @file{.c} files are
6732 distributed. The end user does not need to have a Vala compiler installed.
6734 Automake ships with an Autoconf macro called @code{AM_PROG_VALAC}
6735 that will locate the Vala compiler and optionally check its version
6738 @defmac AM_PROG_VALAC (@ovar{minimum-version})
6739 Try to find a Vala compiler in @env{PATH}. If it is found, the variable
6740 @code{VALAC} is set. Optionally a minimum release number of the compiler
6744 AM_PROG_VALAC([0.7.0])
6748 There are a few variables that are used when compiling Vala sources:
6752 Path to the Vala compiler.
6755 Additional arguments for the Vala compiler.
6758 The maintainer's variant of @code{VALAFLAGS}.
6761 lib_LTLIBRARIES = libfoo.la
6762 libfoo_la_SOURCES = foo.vala
6766 Note that currently, you cannot use per-target @code{*_VALAFLAGS}
6767 (@pxref{Renamed Objects}) to produce different C files from one Vala
6771 @node Support for Other Languages
6772 @comment node-name, next, previous, up
6773 @section Support for Other Languages
6775 Automake currently only includes full support for C, C++ (@pxref{C++
6776 Support}), Objective C (@pxref{Objective C Support}), Fortran 77
6777 (@pxref{Fortran 77 Support}), Fortran 9x (@pxref{Fortran 9x Support}),
6778 and Java (@pxref{Java Support with gcj}). There is only rudimentary
6779 support for other languages, support for which will be improved based
6782 Some limited support for adding your own languages is available via the
6783 suffix rule handling (@pxref{Suffixes}).
6786 @section Automatic dependency tracking
6788 As a developer it is often painful to continually update the
6789 @file{Makefile.am} whenever the include-file dependencies change in a
6790 project. Automake supplies a way to automatically track dependency
6791 changes (@pxref{Dependency Tracking}).
6793 @cindex Dependency tracking
6794 @cindex Automatic dependency tracking
6796 Automake always uses complete dependencies for a compilation,
6797 including system headers. Automake's model is that dependency
6798 computation should be a side effect of the build. To this end,
6799 dependencies are computed by running all compilations through a
6800 special wrapper program called @command{depcomp}. @command{depcomp}
6801 understands how to coax many different C and C++ compilers into
6802 generating dependency information in the format it requires.
6803 @samp{automake -a} will install @command{depcomp} into your source
6804 tree for you. If @command{depcomp} can't figure out how to properly
6805 invoke your compiler, dependency tracking will simply be disabled for
6808 @cindex @command{depcomp}
6810 Experience with earlier versions of Automake (@pxref{Dependency Tracking
6811 Evolution, , Dependency Tracking Evolution, automake-history, Brief History
6812 of Automake}) taught us that it is not reliable to generate dependencies
6813 only on the maintainer's system, as configurations vary too much. So
6814 instead Automake implements dependency tracking at build time.
6816 Automatic dependency tracking can be suppressed by putting
6817 @option{no-dependencies} in the variable @code{AUTOMAKE_OPTIONS}, or
6818 passing @option{no-dependencies} as an argument to @code{AM_INIT_AUTOMAKE}
6819 (this should be the preferred way). Or, you can invoke @command{automake}
6820 with the @option{-i} option. Dependency tracking is enabled by default.
6822 @vindex AUTOMAKE_OPTIONS
6823 @opindex no-dependencies
6825 The person building your package also can choose to disable dependency
6826 tracking by configuring with @option{--disable-dependency-tracking}.
6828 @cindex Disabling dependency tracking
6829 @cindex Dependency tracking, disabling
6833 @section Support for executable extensions
6835 @cindex Executable extension
6836 @cindex Extension, executable
6839 On some platforms, such as Windows, executables are expected to have an
6840 extension such as @file{.exe}. On these platforms, some compilers (GCC
6841 among them) will automatically generate @file{foo.exe} when asked to
6842 generate @file{foo}.
6844 Automake provides mostly-transparent support for this. Unfortunately
6845 @emph{mostly} doesn't yet mean @emph{fully}. Until the English
6846 dictionary is revised, you will have to assist Automake if your package
6847 must support those platforms.
6849 One thing you must be aware of is that, internally, Automake rewrites
6850 something like this:
6853 bin_PROGRAMS = liver
6859 bin_PROGRAMS = liver$(EXEEXT)
6862 The targets Automake generates are likewise given the @samp{$(EXEEXT)}
6865 The variables @code{TESTS} and @code{XFAIL_TESTS} (@pxref{Simple Tests})
6866 are also rewritten if they contain filenames that have been declared as
6867 programs in the same @file{Makefile}. (This is mostly useful when some
6868 programs from @code{check_PROGRAMS} are listed in @code{TESTS}.)
6870 However, Automake cannot apply this rewriting to @command{configure}
6871 substitutions. This means that if you are conditionally building a
6872 program using such a substitution, then your @file{configure.ac} must
6873 take care to add @samp{$(EXEEXT)} when constructing the output variable.
6875 Sometimes maintainers like to write an explicit link rule for their
6876 program. Without executable extension support, this is easy---you
6877 simply write a rule whose target is the name of the program. However,
6878 when executable extension support is enabled, you must instead add the
6879 @samp{$(EXEEXT)} suffix.
6881 This might be a nuisance for maintainers who know their package will
6882 never run on a platform that has
6883 executable extensions. For those maintainers, the @option{no-exeext}
6884 option (@pxref{Options}) will disable this feature. This works in a
6885 fairly ugly way; if @option{no-exeext} is seen, then the presence of a
6886 rule for a target named @code{foo} in @file{Makefile.am} will override
6887 an @command{automake}-generated rule for @samp{foo$(EXEEXT)}. Without
6888 the @option{no-exeext} option, this use will give a diagnostic.
6892 @chapter Other Derived Objects
6894 Automake can handle derived objects that are not C programs. Sometimes
6895 the support for actually building such objects must be explicitly
6896 supplied, but Automake will still automatically handle installation and
6900 * Scripts:: Executable scripts
6901 * Headers:: Header files
6902 * Data:: Architecture-independent data files
6903 * Sources:: Derived sources
6908 @section Executable Scripts
6910 @cindex @code{_SCRIPTS} primary, defined
6911 @cindex @code{SCRIPTS} primary, defined
6912 @cindex Primary variable, @code{SCRIPTS}
6914 @cindex Installing scripts
6916 It is possible to define and install programs that are scripts. Such
6917 programs are listed using the @code{SCRIPTS} primary name. When the
6918 script is distributed in its final, installable form, the
6919 @file{Makefile} usually looks as follows:
6923 # Install my_script in $(bindir) and distribute it.
6924 dist_bin_SCRIPTS = my_script
6927 Scripts are not distributed by default; as we have just seen, those
6928 that should be distributed can be specified using a @code{dist_}
6929 prefix as with other primaries.
6931 @cindex @code{SCRIPTS}, installation directories
6933 @vindex sbin_SCRIPTS
6934 @vindex libexec_SCRIPTS
6935 @vindex pkgdata_SCRIPTS
6936 @vindex pkglibexec_SCRIPTS
6937 @vindex noinst_SCRIPTS
6938 @vindex check_SCRIPTS
6940 Scripts can be installed in @code{bindir}, @code{sbindir},
6941 @code{libexecdir}, @code{pkglibexecdir}, or @code{pkgdatadir}.
6943 Scripts that need not be installed can be listed in
6944 @code{noinst_SCRIPTS}, and among them, those which are needed only by
6945 @samp{make check} should go in @code{check_SCRIPTS}.
6947 When a script needs to be built, the @file{Makefile.am} should include
6948 the appropriate rules. For instance the @command{automake} program
6949 itself is a Perl script that is generated from @file{automake.in}.
6950 Here is how this is handled:
6953 bin_SCRIPTS = automake
6954 CLEANFILES = $(bin_SCRIPTS)
6955 EXTRA_DIST = automake.in
6957 do_subst = sed -e 's,[@@]datadir[@@],$(datadir),g' \
6958 -e 's,[@@]PERL[@@],$(PERL),g' \
6959 -e 's,[@@]PACKAGE[@@],$(PACKAGE),g' \
6960 -e 's,[@@]VERSION[@@],$(VERSION),g' \
6963 automake: automake.in Makefile
6964 $(do_subst) < $(srcdir)/automake.in > automake
6968 Such scripts for which a build rule has been supplied need to be
6969 deleted explicitly using @code{CLEANFILES} (@pxref{Clean}), and their
6970 sources have to be distributed, usually with @code{EXTRA_DIST}
6971 (@pxref{Basics of Distribution}).
6973 Another common way to build scripts is to process them from
6974 @file{configure} with @code{AC_CONFIG_FILES}. In this situation
6975 Automake knows which files should be cleaned and distributed, and what
6976 the rebuild rules should look like.
6978 For instance if @file{configure.ac} contains
6981 AC_CONFIG_FILES([src/my_script], [chmod +x src/my_script])
6985 to build @file{src/my_script} from @file{src/my_script.in}, then a
6986 @file{src/Makefile.am} to install this script in @code{$(bindir)} can
6990 bin_SCRIPTS = my_script
6991 CLEANFILES = $(bin_SCRIPTS)
6995 There is no need for @code{EXTRA_DIST} or any build rule: Automake
6996 infers them from @code{AC_CONFIG_FILES} (@pxref{Requirements}).
6997 @code{CLEANFILES} is still useful, because by default Automake will
6998 clean targets of @code{AC_CONFIG_FILES} in @code{distclean}, not
7001 Although this looks simpler, building scripts this way has one
7002 drawback: directory variables such as @code{$(datadir)} are not fully
7003 expanded and may refer to other directory variables.
7006 @section Header files
7008 @cindex @code{_HEADERS} primary, defined
7009 @cindex @code{HEADERS} primary, defined
7010 @cindex Primary variable, @code{HEADERS}
7012 @vindex noinst_HEADERS
7013 @cindex @code{HEADERS}, installation directories
7014 @cindex Installing headers
7015 @vindex include_HEADERS
7016 @vindex oldinclude_HEADERS
7017 @vindex pkginclude_HEADERS
7020 Header files that must be installed are specified by the
7021 @code{HEADERS} family of variables. Headers can be installed in
7022 @code{includedir}, @code{oldincludedir}, @code{pkgincludedir} or any
7023 other directory you may have defined (@pxref{Uniform}). For instance,
7026 include_HEADERS = foo.h bar/bar.h
7030 will install the two files as @file{$(includedir)/foo.h} and
7031 @file{$(includedir)/bar.h}.
7033 The @code{nobase_} prefix is also supported,
7036 nobase_include_HEADERS = foo.h bar/bar.h
7040 will install the two files as @file{$(includedir)/foo.h} and
7041 @file{$(includedir)/bar/bar.h} (@pxref{Alternative}).
7043 @vindex noinst_HEADERS
7044 Usually, only header files that accompany installed libraries need to
7045 be installed. Headers used by programs or convenience libraries are
7046 not installed. The @code{noinst_HEADERS} variable can be used for
7047 such headers. However when the header actually belongs to a single
7048 convenience library or program, we recommend listing it in the
7049 program's or library's @code{_SOURCES} variable (@pxref{Program
7050 Sources}) instead of in @code{noinst_HEADERS}. This is clearer for
7051 the @file{Makefile.am} reader. @code{noinst_HEADERS} would be the
7052 right variable to use in a directory containing only headers and no
7053 associated library or program.
7055 All header files must be listed somewhere; in a @code{_SOURCES}
7056 variable or in a @code{_HEADERS} variable. Missing ones will not
7057 appear in the distribution.
7059 For header files that are built and must not be distributed, use the
7060 @code{nodist_} prefix as in @code{nodist_include_HEADERS} or
7061 @code{nodist_prog_SOURCES}. If these generated headers are needed
7062 during the build, you must also ensure they exist before they are
7063 used (@pxref{Sources}).
7067 @section Architecture-independent data files
7069 @cindex @code{_DATA} primary, defined
7070 @cindex @code{DATA} primary, defined
7071 @cindex Primary variable, @code{DATA}
7074 Automake supports the installation of miscellaneous data files using the
7075 @code{DATA} family of variables.
7079 @vindex sysconf_DATA
7080 @vindex sharedstate_DATA
7081 @vindex localstate_DATA
7082 @vindex pkgdata_DATA
7084 Such data can be installed in the directories @code{datadir},
7085 @code{sysconfdir}, @code{sharedstatedir}, @code{localstatedir}, or
7088 By default, data files are @emph{not} included in a distribution. Of
7089 course, you can use the @code{dist_} prefix to change this on a
7092 Here is how Automake declares its auxiliary data files:
7095 dist_pkgdata_DATA = clean-kr.am clean.am @dots{}
7100 @section Built Sources
7102 Because Automake's automatic dependency tracking works as a side-effect
7103 of compilation (@pxref{Dependencies}) there is a bootstrap issue: a
7104 target should not be compiled before its dependencies are made, but
7105 these dependencies are unknown until the target is first compiled.
7107 Ordinarily this is not a problem, because dependencies are distributed
7108 sources: they preexist and do not need to be built. Suppose that
7109 @file{foo.c} includes @file{foo.h}. When it first compiles
7110 @file{foo.o}, @command{make} only knows that @file{foo.o} depends on
7111 @file{foo.c}. As a side-effect of this compilation @command{depcomp}
7112 records the @file{foo.h} dependency so that following invocations of
7113 @command{make} will honor it. In these conditions, it's clear there is
7114 no problem: either @file{foo.o} doesn't exist and has to be built
7115 (regardless of the dependencies), or accurate dependencies exist and
7116 they can be used to decide whether @file{foo.o} should be rebuilt.
7118 It's a different story if @file{foo.h} doesn't exist by the first
7119 @command{make} run. For instance, there might be a rule to build
7120 @file{foo.h}. This time @file{file.o}'s build will fail because the
7121 compiler can't find @file{foo.h}. @command{make} failed to trigger the
7122 rule to build @file{foo.h} first by lack of dependency information.
7124 @vindex BUILT_SOURCES
7125 @cindex @code{BUILT_SOURCES}, defined
7127 The @code{BUILT_SOURCES} variable is a workaround for this problem. A
7128 source file listed in @code{BUILT_SOURCES} is made on @samp{make all}
7129 or @samp{make check} (or even @samp{make install}) before other
7130 targets are processed. However, such a source file is not
7131 @emph{compiled} unless explicitly requested by mentioning it in some
7132 other @code{_SOURCES} variable.
7134 So, to conclude our introductory example, we could use
7135 @samp{BUILT_SOURCES = foo.h} to ensure @file{foo.h} gets built before
7136 any other target (including @file{foo.o}) during @samp{make all} or
7139 @code{BUILT_SOURCES} is actually a bit of a misnomer, as any file which
7140 must be created early in the build process can be listed in this
7141 variable. Moreover, all built sources do not necessarily have to be
7142 listed in @code{BUILT_SOURCES}. For instance, a generated @file{.c} file
7143 doesn't need to appear in @code{BUILT_SOURCES} (unless it is included by
7144 another source), because it's a known dependency of the associated
7147 It might be important to emphasize that @code{BUILT_SOURCES} is
7148 honored only by @samp{make all}, @samp{make check} and @samp{make
7149 install}. This means you cannot build a specific target (e.g.,
7150 @samp{make foo}) in a clean tree if it depends on a built source.
7151 However it will succeed if you have run @samp{make all} earlier,
7152 because accurate dependencies are already available.
7154 The next section illustrates and discusses the handling of built sources
7158 * Built Sources Example:: Several ways to handle built sources.
7161 @node Built Sources Example
7162 @subsection Built Sources Example
7164 Suppose that @file{foo.c} includes @file{bindir.h}, which is
7165 installation-dependent and not distributed: it needs to be built. Here
7166 @file{bindir.h} defines the preprocessor macro @code{bindir} to the
7167 value of the @command{make} variable @code{bindir} (inherited from
7170 We suggest several implementations below. It's not meant to be an
7171 exhaustive listing of all ways to handle built sources, but it will give
7172 you a few ideas if you encounter this issue.
7174 @subsubheading First Try
7176 This first implementation will illustrate the bootstrap issue mentioned
7177 in the previous section (@pxref{Sources}).
7179 Here is a tentative @file{Makefile.am}.
7185 nodist_foo_SOURCES = bindir.h
7186 CLEANFILES = bindir.h
7188 echo '#define bindir "$(bindir)"' >$@@
7191 This setup doesn't work, because Automake doesn't know that @file{foo.c}
7192 includes @file{bindir.h}. Remember, automatic dependency tracking works
7193 as a side-effect of compilation, so the dependencies of @file{foo.o} will
7194 be known only after @file{foo.o} has been compiled (@pxref{Dependencies}).
7195 The symptom is as follows.
7199 source='foo.c' object='foo.o' libtool=no \
7200 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
7201 depmode=gcc /bin/sh ./depcomp \
7202 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
7203 foo.c:2: bindir.h: No such file or directory
7204 make: *** [foo.o] Error 1
7207 In this example @file{bindir.h} is not distributed nor installed, and
7208 it is not even being built on-time. One may wonder if the
7209 @samp{nodist_foo_SOURCES = bindir.h} line has any use at all. This
7210 line simply states that @file{bindir.h} is a source of @code{foo}, so
7211 for instance, it should be inspected while generating tags
7212 (@pxref{Tags}). In other words, it does not help our present problem,
7213 and the build would fail identically without it.
7215 @subsubheading Using @code{BUILT_SOURCES}
7217 A solution is to require @file{bindir.h} to be built before anything
7218 else. This is what @code{BUILT_SOURCES} is meant for (@pxref{Sources}).
7223 nodist_foo_SOURCES = bindir.h
7224 BUILT_SOURCES = bindir.h
7225 CLEANFILES = bindir.h
7227 echo '#define bindir "$(bindir)"' >$@@
7230 See how @file{bindir.h} gets built first:
7234 echo '#define bindir "/usr/local/bin"' >bindir.h
7236 make[1]: Entering directory `/home/adl/tmp'
7237 source='foo.c' object='foo.o' libtool=no \
7238 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
7239 depmode=gcc /bin/sh ./depcomp \
7240 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
7241 gcc -g -O2 -o foo foo.o
7242 make[1]: Leaving directory `/home/adl/tmp'
7245 However, as said earlier, @code{BUILT_SOURCES} applies only to the
7246 @code{all}, @code{check}, and @code{install} targets. It still fails
7247 if you try to run @samp{make foo} explicitly:
7251 test -z "bindir.h" || rm -f bindir.h
7252 test -z "foo" || rm -f foo
7254 % : > .deps/foo.Po # Suppress previously recorded dependencies
7256 source='foo.c' object='foo.o' libtool=no \
7257 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
7258 depmode=gcc /bin/sh ./depcomp \
7259 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
7260 foo.c:2: bindir.h: No such file or directory
7261 make: *** [foo.o] Error 1
7264 @subsubheading Recording Dependencies manually
7266 Usually people are happy enough with @code{BUILT_SOURCES} because they
7267 never build targets such as @samp{make foo} before @samp{make all}, as
7268 in the previous example. However if this matters to you, you can
7269 avoid @code{BUILT_SOURCES} and record such dependencies explicitly in
7270 the @file{Makefile.am}.
7275 nodist_foo_SOURCES = bindir.h
7276 foo.$(OBJEXT): bindir.h
7277 CLEANFILES = bindir.h
7279 echo '#define bindir "$(bindir)"' >$@@
7282 You don't have to list @emph{all} the dependencies of @file{foo.o}
7283 explicitly, only those that might need to be built. If a dependency
7284 already exists, it will not hinder the first compilation and will be
7285 recorded by the normal dependency tracking code. (Note that after
7286 this first compilation the dependency tracking code will also have
7287 recorded the dependency between @file{foo.o} and
7288 @file{bindir.h}; so our explicit dependency is really useful to
7289 the first build only.)
7291 Adding explicit dependencies like this can be a bit dangerous if you are
7292 not careful enough. This is due to the way Automake tries not to
7293 overwrite your rules (it assumes you know better than it).
7294 @samp{foo.$(OBJEXT): bindir.h} supersedes any rule Automake may want to
7295 output to build @samp{foo.$(OBJEXT)}. It happens to work in this case
7296 because Automake doesn't have to output any @samp{foo.$(OBJEXT):}
7297 target: it relies on a suffix rule instead (i.e., @samp{.c.$(OBJEXT):}).
7298 Always check the generated @file{Makefile.in} if you do this.
7300 @subsubheading Build @file{bindir.h} from @file{configure}
7302 It's possible to define this preprocessor macro from @file{configure},
7303 either in @file{config.h} (@pxref{Defining Directories, , Defining
7304 Directories, autoconf, The Autoconf Manual}), or by processing a
7305 @file{bindir.h.in} file using @code{AC_CONFIG_FILES}
7306 (@pxref{Configuration Actions, ,Configuration Actions, autoconf, The
7309 At this point it should be clear that building @file{bindir.h} from
7310 @file{configure} works well for this example. @file{bindir.h} will exist
7311 before you build any target, hence will not cause any dependency issue.
7313 The Makefile can be shrunk as follows. We do not even have to mention
7321 However, it's not always possible to build sources from
7322 @file{configure}, especially when these sources are generated by a tool
7323 that needs to be built first.
7325 @subsubheading Build @file{bindir.c}, not @file{bindir.h}.
7327 Another attractive idea is to define @code{bindir} as a variable or
7328 function exported from @file{bindir.o}, and build @file{bindir.c}
7329 instead of @file{bindir.h}.
7332 noinst_PROGRAMS = foo
7333 foo_SOURCES = foo.c bindir.h
7334 nodist_foo_SOURCES = bindir.c
7335 CLEANFILES = bindir.c
7337 echo 'const char bindir[] = "$(bindir)";' >$@@
7340 @file{bindir.h} contains just the variable's declaration and doesn't
7341 need to be built, so it won't cause any trouble. @file{bindir.o} is
7342 always dependent on @file{bindir.c}, so @file{bindir.c} will get built
7345 @subsubheading Which is best?
7347 There is no panacea, of course. Each solution has its merits and
7350 You cannot use @code{BUILT_SOURCES} if the ability to run @samp{make
7351 foo} on a clean tree is important to you.
7353 You won't add explicit dependencies if you are leery of overriding
7354 an Automake rule by mistake.
7356 Building files from @file{./configure} is not always possible, neither
7357 is converting @file{.h} files into @file{.c} files.
7360 @node Other GNU Tools
7361 @chapter Other GNU Tools
7363 Since Automake is primarily intended to generate @file{Makefile.in}s for
7364 use in GNU programs, it tries hard to interoperate with other GNU tools.
7367 * Emacs Lisp:: Emacs Lisp
7370 * Java:: Java bytecode compilation (deprecated)
7378 @cindex @code{_LISP} primary, defined
7379 @cindex @code{LISP} primary, defined
7380 @cindex Primary variable, @code{LISP}
7386 Automake provides some support for Emacs Lisp. The @code{LISP} primary
7387 is used to hold a list of @file{.el} files. Possible prefixes for this
7388 primary are @code{lisp_} and @code{noinst_}. Note that if
7389 @code{lisp_LISP} is defined, then @file{configure.ac} must run
7390 @code{AM_PATH_LISPDIR} (@pxref{Macros}).
7392 @vindex dist_lisp_LISP
7393 @vindex dist_noinst_LISP
7394 Lisp sources are not distributed by default. You can prefix the
7395 @code{LISP} primary with @code{dist_}, as in @code{dist_lisp_LISP} or
7396 @code{dist_noinst_LISP}, to indicate that these files should be
7399 Automake will byte-compile all Emacs Lisp source files using the Emacs
7400 found by @code{AM_PATH_LISPDIR}, if any was found.
7402 Byte-compiled Emacs Lisp files are not portable among all versions of
7403 Emacs, so it makes sense to turn this off if you expect sites to have
7404 more than one version of Emacs installed. Furthermore, many packages
7405 don't actually benefit from byte-compilation. Still, we recommend
7406 that you byte-compile your Emacs Lisp sources. It is probably better
7407 for sites with strange setups to cope for themselves than to make the
7408 installation less nice for everybody else.
7410 There are two ways to avoid byte-compiling. Historically, we have
7411 recommended the following construct.
7414 lisp_LISP = file1.el file2.el
7419 @code{ELCFILES} is an internal Automake variable that normally lists
7420 all @file{.elc} files that must be byte-compiled. Automake defines
7421 @code{ELCFILES} automatically from @code{lisp_LISP}. Emptying this
7422 variable explicitly prevents byte-compilation.
7424 Since Automake 1.8, we now recommend using @code{lisp_DATA} instead:
7426 @c Keep in sync with primary-prefix-couples-documented-valid.sh
7428 lisp_DATA = file1.el file2.el
7431 Note that these two constructs are not equivalent. @code{_LISP} will
7432 not install a file if Emacs is not installed, while @code{_DATA} will
7433 always install its files.
7438 @cindex GNU Gettext support
7439 @cindex Gettext support
7440 @cindex Support for GNU Gettext
7442 If @code{AM_GNU_GETTEXT} is seen in @file{configure.ac}, then Automake
7443 turns on support for GNU gettext, a message catalog system for
7444 internationalization
7445 (@pxref{Top, , Introduction, gettext, GNU gettext utilities}).
7447 The @code{gettext} support in Automake requires the addition of one or
7448 two subdirectories to the package: @file{po} and possibly also @file{intl}.
7449 The latter is needed if @code{AM_GNU_GETTEXT} is not invoked with the
7450 @samp{external} argument, or if @code{AM_GNU_GETTEXT_INTL_SUBDIR} is used.
7451 Automake ensures that these directories exist and are mentioned in
7457 Automake provides support for GNU Libtool (@pxref{Top, , Introduction,
7458 libtool, The Libtool Manual}) with the @code{LTLIBRARIES} primary.
7459 @xref{A Shared Library}.
7463 @section Java bytecode compilation (deprecated)
7465 @cindex @code{_JAVA} primary, defined
7466 @cindex @code{JAVA} primary, defined
7467 @cindex Primary variable, @code{JAVA}
7468 @cindex Java to bytecode, compilation
7469 @cindex Compilation of Java to bytecode
7471 Automake provides some minimal support for Java bytecode compilation with
7472 the @code{JAVA} primary (in addition to the support for compiling Java to
7473 native machine code; @pxref{Java Support with gcj}). Note however that
7474 @emph{the interface and most features described here are deprecated}; the
7475 next automake release will strive to provide a better and cleaner
7476 interface, which however @emph{won't be backward-compatible}; the present
7477 interface will probably be removed altogether in future automake releases
7478 (1.13 or later), so don't use it in new code.
7480 Any @file{.java} files listed in a @code{_JAVA} variable will be
7481 compiled with @code{JAVAC} at build time. By default, @file{.java}
7482 files are not included in the distribution, you should use the
7483 @code{dist_} prefix to distribute them.
7485 Here is a typical setup for distributing @file{.java} files and
7486 installing the @file{.class} files resulting from their compilation.
7488 @c Keep in sync with primary-prefix-couples-documented-valid.sh
7490 javadir = $(datadir)/java
7491 dist_java_JAVA = a.java b.java @dots{}
7494 @cindex @code{JAVA} restrictions
7495 @cindex Restrictions for @code{JAVA}
7497 Currently Automake enforces the restriction that only one @code{_JAVA}
7498 primary can be used in a given @file{Makefile.am}. The reason for this
7499 restriction is that, in general, it isn't possible to know which
7500 @file{.class} files were generated from which @file{.java} files, so
7501 it would be impossible to know which files to install where. For
7502 instance, a @file{.java} file can define multiple classes; the resulting
7503 @file{.class} file names cannot be predicted without parsing the
7506 There are a few variables that are used when compiling Java sources:
7510 The name of the Java compiler. This defaults to @samp{javac}.
7513 The flags to pass to the compiler. This is considered to be a user
7514 variable (@pxref{User Variables}).
7517 More flags to pass to the Java compiler. This, and not
7518 @code{JAVACFLAGS}, should be used when it is necessary to put Java
7519 compiler flags into @file{Makefile.am}.
7522 The value of this variable is passed to the @option{-d} option to
7523 @code{javac}. It defaults to @samp{$(top_builddir)}.
7526 This variable is a shell expression that is used to set the
7527 @env{CLASSPATH} environment variable on the @code{javac} command line.
7528 (In the future we will probably handle class path setting differently.)
7535 @cindex @code{_PYTHON} primary, defined
7536 @cindex @code{PYTHON} primary, defined
7537 @cindex Primary variable, @code{PYTHON}
7540 Automake provides support for Python compilation with the
7541 @code{PYTHON} primary. A typical setup is to call
7542 @code{AM_PATH_PYTHON} in @file{configure.ac} and use a line like the
7543 following in @file{Makefile.am}:
7546 python_PYTHON = tree.py leave.py
7549 Any files listed in a @code{_PYTHON} variable will be byte-compiled
7550 with @command{py-compile} at install time. @command{py-compile}
7551 actually creates both standard (@file{.pyc}) and optimized
7552 (@file{.pyo}) byte-compiled versions of the source files. Note that
7553 because byte-compilation occurs at install time, any files listed in
7554 @code{noinst_PYTHON} will not be compiled. Python source files are
7555 included in the distribution by default, prepend @code{nodist_} (as in
7556 @code{nodist_python_PYTHON}) to omit them.
7558 Automake ships with an Autoconf macro called @code{AM_PATH_PYTHON}
7559 that will determine some Python-related directory variables (see
7560 below). If you have called @code{AM_PATH_PYTHON} from
7561 @file{configure.ac}, then you may use the variables
7562 @c Keep in sync with primary-prefix-couples-documented-valid.sh
7563 @code{python_PYTHON} or @code{pkgpython_PYTHON} to list Python source
7564 files in your @file{Makefile.am}, depending on where you want your files
7565 installed (see the definitions of @code{pythondir} and
7566 @code{pkgpythondir} below).
7568 @defmac AM_PATH_PYTHON (@ovar{version}, @ovar{action-if-found},
7569 @ovar{action-if-not-found})
7571 Search for a Python interpreter on the system. This macro takes three
7572 optional arguments. The first argument, if present, is the minimum
7573 version of Python required for this package: @code{AM_PATH_PYTHON}
7574 will skip any Python interpreter that is older than @var{version}.
7575 If an interpreter is found and satisfies @var{version}, then
7576 @var{action-if-found} is run. Otherwise, @var{action-if-not-found} is
7579 If @var{action-if-not-found} is not specified, as in the following
7580 example, the default is to abort @command{configure}.
7583 AM_PATH_PYTHON([2.2])
7587 This is fine when Python is an absolute requirement for the package.
7588 If Python >= 2.5 was only @emph{optional} to the package,
7589 @code{AM_PATH_PYTHON} could be called as follows.
7592 AM_PATH_PYTHON([2.5],, [:])
7595 If the @env{PYTHON} variable is set when @code{AM_PATH_PYTHON} is
7596 called, then that will be the only Python interpreter that is tried.
7598 @code{AM_PATH_PYTHON} creates the following output variables based on
7599 the Python installation found during configuration.
7604 The name of the Python executable, or @samp{:} if no suitable
7605 interpreter could be found.
7607 Assuming @var{action-if-not-found} is used (otherwise @file{./configure}
7608 will abort if Python is absent), the value of @code{PYTHON} can be used
7609 to setup a conditional in order to disable the relevant part of a build
7613 AM_PATH_PYTHON(,, [:])
7614 AM_CONDITIONAL([HAVE_PYTHON], [test "$PYTHON" != :])
7617 @item PYTHON_VERSION
7618 The Python version number, in the form @var{major}.@var{minor}
7619 (e.g., @samp{2.5}). This is currently the value of
7620 @samp{sys.version[:3]}.
7623 The string @samp{$@{prefix@}}. This term may be used in future work
7624 that needs the contents of Python's @samp{sys.prefix}, but general
7625 consensus is to always use the value from @command{configure}.
7627 @item PYTHON_EXEC_PREFIX
7628 The string @samp{$@{exec_prefix@}}. This term may be used in future work
7629 that needs the contents of Python's @samp{sys.exec_prefix}, but general
7630 consensus is to always use the value from @command{configure}.
7632 @item PYTHON_PLATFORM
7633 The canonical name used by Python to describe the operating system, as
7634 given by @samp{sys.platform}. This value is sometimes needed when
7635 building Python extensions.
7638 The directory name for the @file{site-packages} subdirectory of the
7639 standard Python install tree.
7642 This is the directory under @code{pythondir} that is named after the
7643 package. That is, it is @samp{$(pythondir)/$(PACKAGE)}. It is provided
7647 This is the directory where Python extension modules (shared libraries)
7648 should be installed. An extension module written in C could be declared
7649 as follows to Automake:
7651 @c Keep in sync with primary-prefix-couples-documented-valid.sh
7653 pyexec_LTLIBRARIES = quaternion.la
7654 quaternion_la_SOURCES = quaternion.c support.c support.h
7655 quaternion_la_LDFLAGS = -avoid-version -module
7659 This is a convenience variable that is defined as
7660 @samp{$(pyexecdir)/$(PACKAGE)}.
7663 All these directory variables have values that start with either
7664 @samp{$@{prefix@}} or @samp{$@{exec_prefix@}} unexpanded. This works
7665 fine in @file{Makefiles}, but it makes these variables hard to use in
7666 @file{configure}. This is mandated by the GNU coding standards, so
7667 that the user can run @samp{make prefix=/foo install}. The Autoconf
7668 manual has a section with more details on this topic
7669 (@pxref{Installation Directory Variables, , Installation Directory
7670 Variables, autoconf, The Autoconf Manual}). See also @ref{Hard-Coded
7675 @chapter Building documentation
7677 Currently Automake provides support for Texinfo and man pages.
7681 * Man Pages:: Man pages
7688 @cindex @code{_TEXINFOS} primary, defined
7689 @cindex @code{TEXINFOS} primary, defined
7690 @cindex Primary variable, @code{TEXINFOS}
7691 @cindex HTML output using Texinfo
7692 @cindex PDF output using Texinfo
7693 @cindex PS output using Texinfo
7694 @cindex DVI output using Texinfo
7696 @vindex info_TEXINFOS
7698 If the current directory contains Texinfo source, you must declare it
7699 with the @code{TEXINFOS} primary. Generally Texinfo files are converted
7700 into info, and thus the @code{info_TEXINFOS} variable is most commonly used
7701 here. Any Texinfo source file must end in the @file{.texi},
7702 @file{.txi}, or @file{.texinfo} extension. We recommend @file{.texi}
7705 Automake generates rules to build @file{.info}, @file{.dvi},
7706 @file{.ps}, @file{.pdf} and @file{.html} files from your Texinfo
7707 sources. Following the GNU Coding Standards, only the @file{.info}
7708 files are built by @samp{make all} and installed by @samp{make
7709 install} (unless you use @option{no-installinfo}, see below).
7710 Furthermore, @file{.info} files are automatically distributed so that
7711 Texinfo is not a prerequisite for installing your package.
7717 @trindex install-dvi
7718 @trindex install-html
7719 @trindex install-pdf
7721 Other documentation formats can be built on request by @samp{make
7722 dvi}, @samp{make ps}, @samp{make pdf} and @samp{make html}, and they
7723 can be installed with @samp{make install-dvi}, @samp{make install-ps},
7724 @samp{make install-pdf} and @samp{make install-html} explicitly.
7725 @samp{make uninstall} will remove everything: the Texinfo
7726 documentation installed by default as well as all the above optional
7729 All these targets can be extended using @samp{-local} rules
7730 (@pxref{Extending}).
7732 @cindex Texinfo flag, @code{VERSION}
7733 @cindex Texinfo flag, @code{UPDATED}
7734 @cindex Texinfo flag, @code{EDITION}
7735 @cindex Texinfo flag, @code{UPDATED-MONTH}
7737 @cindex @code{VERSION} Texinfo flag
7738 @cindex @code{UPDATED} Texinfo flag
7739 @cindex @code{EDITION} Texinfo flag
7740 @cindex @code{UPDATED-MONTH} Texinfo flag
7742 @cindex @file{mdate-sh}
7744 If the @file{.texi} file @code{@@include}s @file{version.texi}, then
7745 that file will be automatically generated. The file @file{version.texi}
7746 defines four Texinfo flag you can reference using
7747 @code{@@value@{EDITION@}}, @code{@@value@{VERSION@}},
7748 @code{@@value@{UPDATED@}}, and @code{@@value@{UPDATED-MONTH@}}.
7753 Both of these flags hold the version number of your program. They are
7754 kept separate for clarity.
7757 This holds the date the primary @file{.texi} file was last modified.
7760 This holds the name of the month in which the primary @file{.texi} file
7764 The @file{version.texi} support requires the @command{mdate-sh}
7765 script; this script is supplied with Automake and automatically
7766 included when @command{automake} is invoked with the
7767 @option{--add-missing} option.
7769 If you have multiple Texinfo files, and you want to use the
7770 @file{version.texi} feature, then you have to have a separate version
7771 file for each Texinfo file. Automake will treat any include in a
7772 Texinfo file that matches @file{vers*.texi} just as an automatically
7773 generated version file.
7775 Sometimes an info file actually depends on more than one @file{.texi}
7776 file. For instance, in GNU Hello, @file{hello.texi} includes the file
7777 @file{fdl.texi}. You can tell Automake about these dependencies using
7778 the @code{@var{texi}_TEXINFOS} variable. Here is how GNU Hello does it:
7783 info_TEXINFOS = hello.texi
7784 hello_TEXINFOS = fdl.texi
7787 @cindex @file{texinfo.tex}
7789 By default, Automake requires the file @file{texinfo.tex} to appear in
7790 the same directory as the @file{Makefile.am} file that lists the
7791 @file{.texi} files. If you used @code{AC_CONFIG_AUX_DIR} in
7792 @file{configure.ac} (@pxref{Input, , Finding `configure' Input,
7793 autoconf, The Autoconf Manual}), then @file{texinfo.tex} is looked for
7794 there. In both cases, @command{automake} then supplies @file{texinfo.tex} if
7795 @option{--add-missing} is given, and takes care of its distribution.
7796 However, if you set the @code{TEXINFO_TEX} variable (see below),
7797 it overrides the location of the file and turns off its installation
7798 into the source as well as its distribution.
7800 The option @option{no-texinfo.tex} can be used to eliminate the
7801 requirement for the file @file{texinfo.tex}. Use of the variable
7802 @code{TEXINFO_TEX} is preferable, however, because that allows the
7803 @code{dvi}, @code{ps}, and @code{pdf} targets to still work.
7805 @cindex Option, @code{no-installinfo}
7806 @cindex Target, @code{install-info}
7807 @cindex @code{install-info} target
7808 @cindex @code{no-installinfo} option
7810 @opindex no-installinfo
7811 @trindex install-info
7813 Automake generates an @code{install-info} rule; some people apparently
7814 use this. By default, info pages are installed by @samp{make
7815 install}, so running @code{make install-info} is pointless. This can
7816 be prevented via the @code{no-installinfo} option. In this case,
7817 @file{.info} files are not installed by default, and user must
7818 request this explicitly using @samp{make install-info}.
7820 @vindex AM_UPDATE_INFO_DIR
7821 By default, @code{make install-info} and @code{make install-info}
7822 will try to run the @command{install-info} program (if available)
7823 to update (or create) the @file{@code{$@{infodir@}}/dir} index.
7824 If this is undesired, it can be prevented by exporting the
7825 @code{AM_UPDATE_INFO_DIR} variable to "@code{no}".
7827 The following variables are used by the Texinfo build rules.
7831 The name of the program invoked to build @file{.info} files. This
7832 variable is defined by Automake. If the @command{makeinfo} program is
7833 found on the system then it will be used by default; otherwise
7834 @command{missing} will be used instead.
7837 The command invoked to build @file{.html} files. Automake
7838 defines this to @samp{$(MAKEINFO) --html}.
7841 User flags passed to each invocation of @samp{$(MAKEINFO)} and
7842 @samp{$(MAKEINFOHTML)}. This user variable (@pxref{User Variables}) is
7843 not expected to be defined in any @file{Makefile}; it can be used by
7844 users to pass extra flags to suit their needs.
7846 @item AM_MAKEINFOFLAGS
7847 @itemx AM_MAKEINFOHTMLFLAGS
7848 Maintainer flags passed to each @command{makeinfo} invocation. Unlike
7849 @code{MAKEINFOFLAGS}, these variables are meant to be defined by
7850 maintainers in @file{Makefile.am}. @samp{$(AM_MAKEINFOFLAGS)} is
7851 passed to @code{makeinfo} when building @file{.info} files; and
7852 @samp{$(AM_MAKEINFOHTMLFLAGS)} is used when building @file{.html}
7855 @c Keep in sync with txinfo21.sh
7856 For instance, the following setting can be used to obtain one single
7857 @file{.html} file per manual, without node separators.
7859 AM_MAKEINFOHTMLFLAGS = --no-headers --no-split
7862 @code{AM_MAKEINFOHTMLFLAGS} defaults to @samp{$(AM_MAKEINFOFLAGS)}.
7863 This means that defining @code{AM_MAKEINFOFLAGS} without defining
7864 @code{AM_MAKEINFOHTMLFLAGS} will impact builds of both @file{.info}
7865 and @file{.html} files.
7868 The name of the command that converts a @file{.texi} file into a
7869 @file{.dvi} file. This defaults to @samp{texi2dvi}, a script that ships
7870 with the Texinfo package.
7873 The name of the command that translates a @file{.texi} file into a
7874 @file{.pdf} file. This defaults to @samp{$(TEXI2DVI) --pdf --batch}.
7877 The name of the command that builds a @file{.ps} file out of a
7878 @file{.dvi} file. This defaults to @samp{dvips}.
7882 If your package has Texinfo files in many directories, you can use the
7883 variable @code{TEXINFO_TEX} to tell Automake where to find the canonical
7884 @file{texinfo.tex} for your package. The value of this variable should
7885 be the relative path from the current @file{Makefile.am} to
7889 TEXINFO_TEX = ../doc/texinfo.tex
7897 @cindex @code{_MANS} primary, defined
7898 @cindex @code{MANS} primary, defined
7899 @cindex Primary variable, @code{MANS}
7903 A package can also include man pages (but see the GNU standards on this
7904 matter, @ref{Man Pages, , , standards, The GNU Coding Standards}.) Man
7905 pages are declared using the @code{MANS} primary. Generally the
7906 @code{man_MANS} variable is used. Man pages are automatically installed in
7907 the correct subdirectory of @code{mandir}, based on the file extension.
7909 File extensions such as @file{.1c} are handled by looking for the valid
7910 part of the extension and using that to determine the correct
7911 subdirectory of @code{mandir}. Valid section names are the digits
7912 @samp{0} through @samp{9}, and the letters @samp{l} and @samp{n}.
7914 Sometimes developers prefer to name a man page something like
7915 @file{foo.man} in the source, and then rename it to have the correct
7916 suffix, for example @file{foo.1}, when installing the file. Automake
7917 also supports this mode. For a valid section named @var{section},
7918 there is a corresponding directory named @samp{man@var{section}dir},
7919 and a corresponding @code{_MANS} variable. Files listed in such a
7920 variable are installed in the indicated section. If the file already
7921 has a valid suffix, then it is installed as-is; otherwise the file
7922 suffix is changed to match the section.
7924 For instance, consider this example:
7926 man1_MANS = rename.man thesame.1 alsothesame.1c
7930 In this case, @file{rename.man} will be renamed to @file{rename.1} when
7931 installed, but the other files will keep their names.
7933 @cindex Target, @code{install-man}
7934 @cindex Option, @option{no-installman}
7935 @cindex @code{install-man} target
7936 @cindex @option{no-installman} option
7937 @opindex no-installman
7938 @trindex install-man
7940 By default, man pages are installed by @samp{make install}. However,
7941 since the GNU project does not require man pages, many maintainers do
7942 not expend effort to keep the man pages up to date. In these cases, the
7943 @option{no-installman} option will prevent the man pages from being
7944 installed by default. The user can still explicitly install them via
7945 @samp{make install-man}.
7947 For fast installation, with many files it is preferable to use
7948 @samp{man@var{section}_MANS} over @samp{man_MANS} as well as files that
7949 do not need to be renamed.
7951 Man pages are not currently considered to be source, because it is not
7952 uncommon for man pages to be automatically generated. Therefore they
7953 are not automatically included in the distribution. However, this can
7954 be changed by use of the @code{dist_} prefix. For instance here is
7955 how to distribute and install the two man pages of GNU @command{cpio}
7956 (which includes both Texinfo documentation and man pages):
7959 dist_man_MANS = cpio.1 mt.1
7962 The @code{nobase_} prefix is meaningless for man pages and is
7966 @cindex @code{notrans_} prefix
7967 @cindex Man page renaming, avoiding
7968 @cindex Avoiding man page renaming
7970 Executables and manpages may be renamed upon installation
7971 (@pxref{Renaming}). For manpages this can be avoided by use of the
7972 @code{notrans_} prefix. For instance, suppose an executable @samp{foo}
7973 allowing to access a library function @samp{foo} from the command line.
7974 The way to avoid renaming of the @file{foo.3} manpage is:
7978 notrans_man_MANS = foo.3
7981 @cindex @code{notrans_} and @code{dist_} or @code{nodist_}
7982 @cindex @code{dist_} and @code{notrans_}
7983 @cindex @code{nodist_} and @code{notrans_}
7985 @samp{notrans_} must be specified first when used in conjunction with
7986 either @samp{dist_} or @samp{nodist_} (@pxref{Fine-grained Distribution
7987 Control}). For instance:
7990 notrans_dist_man3_MANS = bar.3
7994 @chapter What Gets Installed
7996 @cindex Installation support
7997 @cindex @samp{make install} support
7999 Naturally, Automake handles the details of actually installing your
8000 program once it has been built. All files named by the various
8001 primaries are automatically installed in the appropriate places when the
8002 user runs @samp{make install}.
8005 * Basics of Installation:: What gets installed where
8006 * The Two Parts of Install:: Installing data and programs separately
8007 * Extending Installation:: Adding your own rules for installation
8008 * Staged Installs:: Installation in a temporary location
8009 * Install Rules for the User:: Useful additional rules
8012 @node Basics of Installation
8013 @section Basics of Installation
8015 A file named in a primary is installed by copying the built file into
8016 the appropriate directory. The base name of the file is used when
8020 bin_PROGRAMS = hello subdir/goodbye
8023 In this example, both @samp{hello} and @samp{goodbye} will be installed
8024 in @samp{$(bindir)}.
8026 Sometimes it is useful to avoid the basename step at install time. For
8027 instance, you might have a number of header files in subdirectories of
8028 the source tree that are laid out precisely how you want to install
8029 them. In this situation you can use the @code{nobase_} prefix to
8030 suppress the base name step. For example:
8033 nobase_include_HEADERS = stdio.h sys/types.h
8037 will install @file{stdio.h} in @samp{$(includedir)} and @file{types.h}
8038 in @samp{$(includedir)/sys}.
8040 For most file types, Automake will install multiple files at once, while
8041 avoiding command line length issues (@pxref{Length Limitations}). Since
8042 some @command{install} programs will not install the same file twice in
8043 one invocation, you may need to ensure that file lists are unique within
8044 one variable such as @samp{nobase_include_HEADERS} above.
8046 You should not rely on the order in which files listed in one variable
8047 are installed. Likewise, to cater for parallel make, you should not
8048 rely on any particular file installation order even among different
8049 file types (library dependencies are an exception here).
8052 @node The Two Parts of Install
8053 @section The Two Parts of Install
8055 Automake generates separate @code{install-data} and @code{install-exec}
8056 rules, in case the installer is installing on multiple machines that
8057 share directory structure---these targets allow the machine-independent
8058 parts to be installed only once. @code{install-exec} installs
8059 platform-dependent files, and @code{install-data} installs
8060 platform-independent files. The @code{install} target depends on both
8061 of these targets. While Automake tries to automatically segregate
8062 objects into the correct category, the @file{Makefile.am} author is, in
8063 the end, responsible for making sure this is done correctly.
8064 @trindex install-data
8065 @trindex install-exec
8067 @cindex Install, two parts of
8069 Variables using the standard directory prefixes @samp{data},
8070 @samp{info}, @samp{man}, @samp{include}, @samp{oldinclude},
8071 @samp{pkgdata}, or @samp{pkginclude} are installed by
8072 @code{install-data}.
8074 Variables using the standard directory prefixes @samp{bin},
8075 @samp{sbin}, @samp{libexec}, @samp{sysconf}, @samp{localstate},
8076 @samp{lib}, or @samp{pkglib} are installed by @code{install-exec}.
8078 For instance, @code{data_DATA} files are installed by @code{install-data},
8079 while @code{bin_PROGRAMS} files are installed by @code{install-exec}.
8081 Any variable using a user-defined directory prefix with
8082 @samp{exec} in the name (e.g.,
8083 @c Keep in sync with primary-prefix-couples-documented-valid.sh
8084 @code{myexecbin_PROGRAMS}) is installed by @code{install-exec}. All
8085 other user-defined prefixes are installed by @code{install-data}.
8087 @node Extending Installation
8088 @section Extending Installation
8090 It is possible to extend this mechanism by defining an
8091 @code{install-exec-local} or @code{install-data-local} rule. If these
8092 rules exist, they will be run at @samp{make install} time. These
8093 rules can do almost anything; care is required.
8094 @trindex install-exec-local
8095 @trindex install-data-local
8097 Automake also supports two install hooks, @code{install-exec-hook} and
8098 @code{install-data-hook}. These hooks are run after all other install
8099 rules of the appropriate type, exec or data, have completed. So, for
8100 instance, it is possible to perform post-installation modifications
8101 using an install hook. @xref{Extending}, for some examples.
8102 @cindex Install hook
8104 @node Staged Installs
8105 @section Staged Installs
8108 Automake generates support for the @code{DESTDIR} variable in all
8109 install rules. @code{DESTDIR} is used during the @samp{make install}
8110 step to relocate install objects into a staging area. Each object and
8111 path is prefixed with the value of @code{DESTDIR} before being copied
8112 into the install area. Here is an example of typical DESTDIR usage:
8115 mkdir /tmp/staging &&
8116 make DESTDIR=/tmp/staging install
8119 The @command{mkdir} command avoids a security problem if the attacker
8120 creates a symbolic link from @file{/tmp/staging} to a victim area;
8121 then @command{make} places install objects in a directory tree built under
8122 @file{/tmp/staging}. If @file{/gnu/bin/foo} and
8123 @file{/gnu/share/aclocal/foo.m4} are to be installed, the above command
8124 would install @file{/tmp/staging/gnu/bin/foo} and
8125 @file{/tmp/staging/gnu/share/aclocal/foo.m4}.
8127 This feature is commonly used to build install images and packages
8130 Support for @code{DESTDIR} is implemented by coding it directly into
8131 the install rules. If your @file{Makefile.am} uses a local install
8132 rule (e.g., @code{install-exec-local}) or an install hook, then you
8133 must write that code to respect @code{DESTDIR}.
8135 @xref{Makefile Conventions, , , standards, The GNU Coding Standards},
8136 for another usage example.
8138 @node Install Rules for the User
8139 @section Install Rules for the User
8141 Automake also generates rules for targets @code{uninstall},
8142 @code{installdirs}, and @code{install-strip}.
8144 @trindex installdirs
8145 @trindex install-strip
8147 Automake supports @code{uninstall-local} and @code{uninstall-hook}.
8148 There is no notion of separate uninstalls for ``exec'' and ``data'', as
8149 these features would not provide additional functionality.
8151 Note that @code{uninstall} is not meant as a replacement for a real
8156 @chapter What Gets Cleaned
8158 @cindex @samp{make clean} support
8160 The GNU Makefile Standards specify a number of different clean rules.
8161 @xref{Standard Targets, , Standard Targets for Users, standards,
8162 The GNU Coding Standards}.
8164 Generally the files that can be cleaned are determined automatically by
8165 Automake. Of course, Automake also recognizes some variables that can
8166 be defined to specify additional files to clean. These variables are
8167 @code{MOSTLYCLEANFILES}, @code{CLEANFILES}, @code{DISTCLEANFILES}, and
8168 @code{MAINTAINERCLEANFILES}.
8169 @vindex MOSTLYCLEANFILES
8171 @vindex DISTCLEANFILES
8172 @vindex MAINTAINERCLEANFILES
8174 @trindex mostlyclean-local
8175 @trindex clean-local
8176 @trindex distclean-local
8177 @trindex maintainer-clean-local
8178 When cleaning involves more than deleting some hard-coded list of
8179 files, it is also possible to supplement the cleaning rules with your
8180 own commands. Simply define a rule for any of the
8181 @code{mostlyclean-local}, @code{clean-local}, @code{distclean-local},
8182 or @code{maintainer-clean-local} targets (@pxref{Extending}). A common
8183 case is deleting a directory, for instance, a directory created by the
8191 Since @command{make} allows only one set of rules for a given target,
8192 a more extensible way of writing this is to use a separate target
8193 listed as a dependency:
8196 clean-local: clean-local-check
8197 .PHONY: clean-local-check
8202 As the GNU Standards aren't always explicit as to which files should
8203 be removed by which rule, we've adopted a heuristic that we believe
8204 was first formulated by Fran@,{c}ois Pinard:
8208 If @command{make} built it, and it is commonly something that one would
8209 want to rebuild (for instance, a @file{.o} file), then
8210 @code{mostlyclean} should delete it.
8213 Otherwise, if @command{make} built it, then @code{clean} should delete it.
8216 If @command{configure} built it, then @code{distclean} should delete it.
8219 If the maintainer built it (for instance, a @file{.info} file), then
8220 @code{maintainer-clean} should delete it. However
8221 @code{maintainer-clean} should not delete anything that needs to exist
8222 in order to run @samp{./configure && make}.
8225 We recommend that you follow this same set of heuristics in your
8230 @chapter What Goes in a Distribution
8233 * Basics of Distribution:: Files distributed by default
8234 * Fine-grained Distribution Control:: @code{dist_} and @code{nodist_} prefixes
8235 * The dist Hook:: A target for last-minute distribution changes
8236 * Checking the Distribution:: @samp{make distcheck} explained
8237 * The Types of Distributions:: A variety of formats and compression methods
8240 @node Basics of Distribution
8241 @section Basics of Distribution
8243 @cindex @samp{make dist}
8248 The @code{dist} rule in the generated @file{Makefile.in} can be used
8249 to generate a gzipped @code{tar} file and other flavors of archive for
8250 distribution. The file is named based on the @code{PACKAGE} and
8251 @code{VERSION} variables defined by @code{AM_INIT_AUTOMAKE}
8252 (@pxref{Macros}); more precisely the gzipped @code{tar} file is named
8253 @samp{@var{package}-@var{version}.tar.gz}.
8255 You can use the @command{make} variable @code{GZIP_ENV} to control how gzip
8256 is run. The default setting is @option{--best}.
8258 @cindex @code{m4_include}, distribution
8259 @cindex @code{include}, distribution
8262 For the most part, the files to distribute are automatically found by
8263 Automake: all source files are automatically included in a distribution,
8264 as are all @file{Makefile.am} and @file{Makefile.in} files. Automake also
8265 has a built-in list of commonly used files that are automatically
8266 included if they are found in the current directory (either physically,
8267 or as the target of a @file{Makefile.am} rule); this list is printed by
8268 @samp{automake --help}. Note that some files in this list are actually
8269 distributed only if other certain conditions hold (for example,
8270 @c Keep in sync with autodist-config-headers.sh
8271 the @file{config.h.top} and @file{config.h.bot} files are automatically
8272 distributed only if, e.g., @samp{AC_CONFIG_HEADERS([config.h])} is used
8273 in @file{configure.ac}). Also, files that are read by @command{configure}
8274 (i.e.@: the source files corresponding to the files specified in various
8275 Autoconf macros such as @code{AC_CONFIG_FILES} and siblings) are
8276 automatically distributed. Files included in a @file{Makefile.am} (using
8277 @code{include}) or in @file{configure.ac} (using @code{m4_include}), and
8278 helper scripts installed with @samp{automake --add-missing} are also
8282 Still, sometimes there are files that must be distributed, but which
8283 are not covered in the automatic rules. These files should be listed in
8284 the @code{EXTRA_DIST} variable. You can mention files from
8285 subdirectories in @code{EXTRA_DIST}.
8287 You can also mention a directory in @code{EXTRA_DIST}; in this case the
8288 entire directory will be recursively copied into the distribution.
8289 Please note that this will also copy @emph{everything} in the directory,
8290 including, e.g., Subversion's @file{.svn} private directories or CVS/RCS
8291 version control files. We recommend against using this feature.
8294 @vindex DIST_SUBDIRS
8295 If you define @code{SUBDIRS}, Automake will recursively include the
8296 subdirectories in the distribution. If @code{SUBDIRS} is defined
8297 conditionally (@pxref{Conditionals}), Automake will normally include
8298 all directories that could possibly appear in @code{SUBDIRS} in the
8299 distribution. If you need to specify the set of directories
8300 conditionally, you can set the variable @code{DIST_SUBDIRS} to the
8301 exact list of subdirectories to include in the distribution
8302 (@pxref{Conditional Subdirectories}).
8305 @node Fine-grained Distribution Control
8306 @section Fine-grained Distribution Control
8310 Sometimes you need tighter control over what does @emph{not} go into the
8311 distribution; for instance, you might have source files that are
8312 generated and that you do not want to distribute. In this case
8313 Automake gives fine-grained control using the @code{dist} and
8314 @code{nodist} prefixes. Any primary or @code{_SOURCES} variable can be
8315 prefixed with @code{dist_} to add the listed files to the distribution.
8316 Similarly, @code{nodist_} can be used to omit the files from the
8319 As an example, here is how you would cause some data to be distributed
8320 while leaving some source code out of the distribution:
8323 dist_data_DATA = distribute-this
8325 nodist_foo_SOURCES = do-not-distribute.c
8329 @section The dist Hook
8333 Occasionally it is useful to be able to change the distribution before
8334 it is packaged up. If the @code{dist-hook} rule exists, it is run
8335 after the distribution directory is filled, but before the actual
8336 distribution archives are created. One way to use this is for
8337 removing unnecessary files that get recursively included by specifying
8338 a directory in @code{EXTRA_DIST}:
8343 rm -rf `find $(distdir)/doc -type d -name .svn`
8346 @c The caveates described here should be documented in 'disthook.test'.
8348 Note that the @code{dist-hook} recipe shouldn't assume that the regular
8349 files in the distribution directory are writable; this might not be the
8350 case if one is packaging from a read-only source tree, or when a
8351 @code{make distcheck} is being done. For similar reasons, the recipe
8352 shouldn't assume that the subdirectories put into the distribution
8353 directory as effect of having them listed in @code{EXTRA_DIST} are
8354 writable. So, if the @code{dist-hook} recipe wants to modify the
8355 content of an existing file (or @code{EXTRA_DIST} subdirectory) in the
8356 distribution directory, it should explicitly to make it writable first:
8359 EXTRA_DIST = README doc
8361 chmod u+w $(distdir)/README $(distdir)/doc
8362 echo "Distribution date: `date`" >> README
8363 rm -f $(distdir)/doc/HACKING
8368 Two variables that come handy when writing @code{dist-hook} rules are
8369 @samp{$(distdir)} and @samp{$(top_distdir)}.
8371 @samp{$(distdir)} points to the directory where the @code{dist} rule
8372 will copy files from the current directory before creating the
8373 tarball. If you are at the top-level directory, then @samp{distdir =
8374 $(PACKAGE)-$(VERSION)}. When used from subdirectory named
8375 @file{foo/}, then @samp{distdir = ../$(PACKAGE)-$(VERSION)/foo}.
8376 @samp{$(distdir)} can be a relative or absolute path, do not assume
8379 @samp{$(top_distdir)} always points to the root directory of the
8380 distributed tree. At the top-level it's equal to @samp{$(distdir)}.
8381 In the @file{foo/} subdirectory
8382 @samp{top_distdir = ../$(PACKAGE)-$(VERSION)}.
8383 @samp{$(top_distdir)} too can be a relative or absolute path.
8385 Note that when packages are nested using @code{AC_CONFIG_SUBDIRS}
8386 (@pxref{Subpackages}), then @samp{$(distdir)} and
8387 @samp{$(top_distdir)} are relative to the package where @samp{make
8388 dist} was run, not to any sub-packages involved.
8390 @node Checking the Distribution
8391 @section Checking the Distribution
8393 @cindex @samp{make distcheck}
8395 Automake also generates a @code{distcheck} rule that can be of help
8396 to ensure that a given distribution will actually work. Simplifying
8397 a bit, we can say this rule first makes a distribution, and then,
8398 @emph{operating from it}, takes the following steps:
8401 tries to do a @code{VPATH} build (@pxref{VPATH Builds}), with the
8402 @code{srcdir} and all its content made @emph{read-only};
8404 runs the test suite (with @command{make check}) on this fresh build;
8406 installs the package in a temporary directory (with @command{make
8407 install}), and tries runs the test suite on the resulting installation
8408 (with @command{make installcheck});
8410 checks that the package can be correctly uninstalled (by @command{make
8411 uninstall}) and cleaned (by @code{make distclean});
8413 finally, makes another tarball to ensure the distribution is
8417 @vindex AM_DISTCHECK_CONFIGURE_FLAGS
8418 @vindex DISTCHECK_CONFIGURE_FLAGS
8419 @subheading DISTCHECK_CONFIGURE_FLAGS
8420 Building the package involves running @samp{./configure}. If you need
8421 to supply additional flags to @command{configure}, define them in the
8422 @code{AM_DISTCHECK_CONFIGURE_FLAGS} variable in your top-level
8423 @file{Makefile.am}. The user can still extend or override the flags
8424 provided there by defining the @code{DISTCHECK_CONFIGURE_FLAGS} variable,
8425 on the command line when invoking @command{make}.
8427 Still, developers are encouraged to strive to make their code buildable
8428 without requiring any special configure option; thus, in general, you
8429 shouldn't define @code{AM_DISTCHECK_CONFIGURE_FLAGS}. However, there
8430 might be few scenarios in which the use of this variable is justified.
8431 GNU @command{m4} offers an example. GNU @command{m4} configures by
8432 default with its experimental and seldom used "changeword" feature
8433 disabled; so in its case it is useful to have @command{make distcheck}
8434 run configure with the @option{--with-changeword} option, to ensure that
8435 the code for changeword support still compiles correctly.
8436 GNU @command{m4} also employs the @code{AM_DISTCHECK_CONFIGURE_FLAGS}
8437 variable to stress-test the use of @option{--program-prefix=g}, since at
8438 one point the @command{m4} build system had a bug where @command{make
8439 installcheck} was wrongly assuming it could blindly test "@command{m4}",
8440 rather than the just-installed "@command{gm4}".
8442 @trindex distcheck-hook
8443 @subheading distcheck-hook
8444 If the @code{distcheck-hook} rule is defined in your top-level
8445 @file{Makefile.am}, then it will be invoked by @code{distcheck} after
8446 the new distribution has been unpacked, but before the unpacked copy
8447 is configured and built. Your @code{distcheck-hook} can do almost
8448 anything, though as always caution is advised. Generally this hook is
8449 used to check for potential distribution errors not caught by the
8450 standard mechanism. Note that @code{distcheck-hook} as well as
8451 @code{AM_DISTCHECK_CONFIGURE_FLAGS} and @code{DISTCHECK_CONFIGURE_FLAGS}
8452 are not honored in a subpackage @file{Makefile.am}, but the flags from
8453 @code{AM_DISTCHECK_CONFIGURE_FLAGS} and @code{DISTCHECK_CONFIGURE_FLAGS}
8454 are passed down to the @command{configure} script of the subpackage.
8456 @cindex @samp{make distcleancheck}
8457 @trindex distcleancheck
8458 @vindex DISTCLEANFILES
8459 @vindex distcleancheck_listfiles
8461 @subheading distcleancheck
8462 Speaking of potential distribution errors, @code{distcheck} also
8463 ensures that the @code{distclean} rule actually removes all built
8464 files. This is done by running @samp{make distcleancheck} at the end of
8465 the @code{VPATH} build. By default, @code{distcleancheck} will run
8466 @code{distclean} and then make sure the build tree has been emptied by
8467 running @samp{$(distcleancheck_listfiles)}. Usually this check will
8468 find generated files that you forgot to add to the @code{DISTCLEANFILES}
8469 variable (@pxref{Clean}).
8471 The @code{distcleancheck} behavior should be OK for most packages,
8472 otherwise you have the possibility to override the definition of
8473 either the @code{distcleancheck} rule, or the
8474 @samp{$(distcleancheck_listfiles)} variable. For instance, to disable
8475 @code{distcleancheck} completely, add the following rule to your
8476 top-level @file{Makefile.am}:
8483 If you want @code{distcleancheck} to ignore built files that have not
8484 been cleaned because they are also part of the distribution, add the
8485 following definition instead:
8487 @c Keep in sync with distcleancheck.sh
8489 distcleancheck_listfiles = \
8490 find . -type f -exec sh -c 'test -f $(srcdir)/$$1 || echo $$1' \
8494 The above definition is not the default because it's usually an error if
8495 your Makefiles cause some distributed files to be rebuilt when the user
8496 build the package. (Think about the user missing the tool required to
8497 build the file; or if the required tool is built by your package,
8498 consider the cross-compilation case where it can't be run.) There is
8499 an entry in the FAQ about this (@pxref{Errors with distclean}), make
8500 sure you read it before playing with @code{distcleancheck_listfiles}.
8502 @cindex @samp{make distuninstallcheck}
8503 @trindex distuninstallcheck
8504 @vindex distuninstallcheck_listfiles
8506 @subheading distuninstallcheck
8507 @code{distcheck} also checks that the @code{uninstall} rule works
8508 properly, both for ordinary and @code{DESTDIR} builds. It does this
8509 by invoking @samp{make uninstall}, and then it checks the install tree
8510 to see if any files are left over. This check will make sure that you
8511 correctly coded your @code{uninstall}-related rules.
8513 By default, the checking is done by the @code{distuninstallcheck} rule,
8514 and the list of files in the install tree is generated by
8515 @samp{$(distuninstallcheck_listfiles)} (this is a variable whose value is
8516 a shell command to run that prints the list of files to stdout).
8518 Either of these can be overridden to modify the behavior of
8519 @code{distcheck}. For instance, to disable this check completely, you
8527 @node The Types of Distributions
8528 @section The Types of Distributions
8530 Automake generates rules to provide archives of the project for
8531 distributions in various formats. Their targets are:
8535 @item @code{dist-bzip2}
8536 Generate a bzip2 tar archive of the distribution. bzip2 archives are
8537 frequently smaller than gzipped archives.
8538 By default, this rule makes @samp{bzip2} use a compression option of @option{-9}.
8539 To make it use a different one, set the @env{BZIP2} environment variable.
8540 For example, @samp{make dist-bzip2 BZIP2=-7}.
8543 @item @code{dist-gzip}
8544 Generate a gzip tar archive of the distribution.
8547 @item @code{dist-lzip}
8548 Generate an @samp{lzip} tar archive of the distribution. @command{lzip}
8549 archives are frequently smaller than @command{bzip2}-compressed archives.
8552 @item @code{dist-shar}
8553 Generate a shar archive of the distribution.
8557 @item @code{dist-xz}
8558 Generate an @samp{xz} tar archive of the distribution. @command{xz}
8559 archives are frequently smaller than @command{bzip2}-compressed archives.
8560 By default, this rule makes @samp{xz} use a compression option of
8561 @option{-e}. To make it use a different one, set the @env{XZ_OPT}
8562 environment variable. For example, run this command to use the
8563 default compression ratio, but with a progress indicator:
8564 @samp{make dist-xz XZ_OPT=-7e}.
8567 @item @code{dist-zip}
8568 Generate a zip archive of the distribution.
8571 @item @code{dist-tarZ}
8572 Generate a compressed tar archive of
8577 The rule @code{dist} (and its historical synonym @code{dist-all}) will
8578 create archives in all the enabled formats, @ref{Options}. By
8579 default, only the @code{dist-gzip} target is hooked to @code{dist}.
8583 @chapter Support for test suites
8586 @cindex @code{make check}
8589 Automake can generate code to handle two kinds of test suites. One is
8590 based on integration with the @command{dejagnu} framework. The other
8591 (and most used) form is based on the use of generic test scripts, and
8592 its activation is triggered by the definition of the special @code{TESTS}
8593 variable. This second form allows for various degrees of sophistication
8594 and customization; in particular, it allows for concurrent execution
8595 of test scripts, use of established test protocols such as TAP, and
8596 definition of custom test drivers and test runners.
8599 In either case, the testsuite is invoked via @samp{make check}.
8602 * Generalities about Testing:: Concepts and terminology about testing
8603 * Simple Tests:: Listing test scripts in @code{TESTS}
8604 * Custom Test Drivers:: Writing and using custom test drivers
8605 * Using the TAP test protocol:: Integrating test scripts that use the TAP protocol
8606 * DejaGnu Tests:: Interfacing with the @command{dejagnu} testing framework
8607 * Install Tests:: Running tests on installed packages
8610 @node Generalities about Testing
8611 @section Generalities about Testing
8613 The purpose of testing is to determine whether a program or system behaves
8614 as expected (e.g., known inputs produce the expected outputs, error
8615 conditions are correctly handled or reported, and older bugs do not
8619 The minimal unit of testing is usually called @emph{test case}, or simply
8620 @emph{test}. How a test case is defined or delimited, and even what
8621 exactly @emph{constitutes} a test case, depends heavily on the testing
8622 paradigm and/or framework in use, so we won't attempt any more precise
8623 definition. The set of the test cases for a given program or system
8624 constitutes its @emph{testsuite}.
8626 @cindex test harness
8627 @cindex testsuite harness
8628 A @emph{test harness} (also @emph{testsuite harness}) is a program or
8629 software component that executes all (or part of) the defined test cases,
8630 analyzes their outcomes, and report or register these outcomes
8631 appropriately. Again, the details of how this is accomplished (and how
8632 the developer and user can influence it or interface with it) varies
8633 wildly, and we'll attempt no precise definition.
8636 @cindex test failure
8637 A test is said to @emph{pass} when it can determine that the condition or
8638 behaviour it means to verify holds, and is said to @emph{fail} when it can
8639 determine that such condition of behaviour does @emph{not} hold.
8642 Sometimes, tests can rely on non-portable tools or prerequisites, or
8643 simply make no sense on a given system (for example, a test checking a
8644 Windows-specific feature makes no sense on a GNU/Linux system). In this
8645 case, accordingly to the definition above, the tests can neither be
8646 considered passed nor failed; instead, they are @emph{skipped} -- i.e.,
8647 they are not run, or their result is anyway ignored for what concerns
8648 the count of failures an successes. Skips are usually explicitly
8649 reported though, so that the user will be aware that not all of the
8650 testsuite has really run.
8653 @cindex expected failure
8654 @cindex expected test failure
8656 @cindex unexpected pass
8657 @cindex unexpected test pass
8658 It's not uncommon, especially during early development stages, that some
8659 tests fail for known reasons, and that the developer doesn't want to
8660 tackle these failures immediately (this is especially true when the
8661 failing tests deal with corner cases). In this situation, the better
8662 policy is to declare that each of those failures is an @emph{expected
8663 failure} (or @emph{xfail}). In case a test that is expected to fail ends
8664 up passing instead, many testing environments will flag the result as a
8665 special kind of failure called @emph{unexpected pass} (or @emph{xpass}).
8668 @cindex Distinction between errors and failures in testsuites
8669 Many testing environments and frameworks distinguish between test failures
8670 and hard errors. As we've seen, a test failure happens when some invariant
8671 or expected behaviour of the software under test is not met. An @emph{hard
8672 error} happens when e.g., the set-up of a test case scenario fails, or when
8673 some other unexpected or highly undesirable condition is encountered (for
8674 example, the program under test experiences a segmentation fault).
8676 @emph{TODO}: Links to other test harnesses (esp. those sharing our
8680 @section Simple Tests
8683 * Scripts-based Testsuites:: Automake-specific concepts and terminology
8684 * Serial Test Harness:: Older (and obsolescent) serial test harness
8685 * Parallel Test Harness:: Generic concurrent test harness
8688 @node Scripts-based Testsuites
8689 @subsection Scripts-based Testsuites
8691 If the special variable @code{TESTS} is defined, its value is taken to be
8692 a list of programs or scripts to run in order to do the testing. Under
8693 the appropriate circumstances, it's possible for @code{TESTS} to list
8694 also data files to be passed to one or more test scripts defined by
8695 different means (the so-called ``log compilers'', @pxref{Parallel Test
8698 Test scripts can be executed serially or concurrently. Automake
8699 supports both these kinds of test execution, with the serial test harness
8700 being the default (for backward-compatibility reasons only, as its use
8701 is nowadays discouraged). The concurrent test harness relies on the
8702 concurrence capabilities (if any) offered by the underlying @command{make}
8703 implementation, and can thus only be as good as those are.
8705 By default, only the exit statuses of the test scripts are considered when
8706 determining the testsuite outcome. But Automake allows also the use of
8707 more complex test protocols, either standard (@pxref{Using the TAP test
8708 protocol}) or custom (@pxref{Custom Test Drivers}). Note that you can
8709 enable such protocols only when the parallel harness is used: they won't
8710 work with the serial test harness. In the rest of this section we are
8711 going to concentrate mostly on protocol-less tests, since we'll have later
8712 a whole section devoted to the use of test protocols (again, @pxref{Custom
8715 @cindex Exit status 77, special interpretation
8716 @cindex Exit status 99, special interpretation
8717 When no test protocol is in use, an exit status of 0 from a test script will
8718 denote a success, an exit status of 77 a skipped test, an exit status of 99
8719 an hard error, and any other exit status will denote a failure.
8721 @cindex Tests, expected failure
8722 @cindex Expected test failure
8724 @vindex DISABLE_HARD_ERRORS
8725 @cindex Disabling hard errors
8726 You may define the variable @code{XFAIL_TESTS} to a list of tests
8727 (usually a subset of @code{TESTS}) that are expected to fail; this will
8728 effectively reverse the result of those tests (with the provision that
8729 skips and hard errors remain untouched). You may also instruct the
8730 testsuite harness to treat hard errors like simple failures, by defining
8731 the @code{DISABLE_HARD_ERRORS} make variable to a nonempty value.
8733 Note however that, for tests based on more complex test protocols,
8734 the exact effects of @code{XFAIL_TESTS} and @code{DISABLE_HARD_ERRORS}
8735 might change, or they might even have no effect at all (for example,
8736 @c Keep this in sync with tap-no-disable-hard-errors.sh
8737 in tests using TAP, there is not way to disable hard errors, and the
8738 @code{DISABLE_HARD_ERRORS} variable has no effect on them).
8740 @anchor{Testsuite progress on console}
8741 @cindex Testsuite progress on console
8742 The result of each test case run by the scripts in @code{TESTS} will be
8743 printed on standard output, along with the test name. For test protocols
8744 that allow more test cases per test script (such as TAP), a number,
8745 identifier and/or brief description specific for the single test case is
8746 expected to be printed in addition to the name of the test script. The
8747 possible results (whose meanings should be clear from the previous
8748 @ref{Generalities about Testing}) are @code{PASS}, @code{FAIL},
8749 @code{SKIP}, @code{XFAIL}, @code{XPASS} and @code{ERROR}. Here is an
8750 example of output from an hypothetical testsuite that uses both plain
8752 @c Keep in sync with tap-doc.sh
8755 PASS: zardoz.tap 1 - Daemon started
8756 PASS: zardoz.tap 2 - Daemon responding
8757 SKIP: zardoz.tap 3 - Daemon uses /proc # SKIP /proc is not mounted
8758 PASS: zardoz.tap 4 - Daemon stopped
8761 XFAIL: mu.tap 2 # TODO frobnication not yet implemented
8765 A testsuite summary (expected to report at least the number of run,
8766 skipped and failed tests) will be printed at the end of the testsuite
8769 @anchor{Simple tests and color-tests}
8770 @vindex AM_COLOR_TESTS
8771 @cindex Colorized testsuite output
8772 If the Automake option @code{color-tests} is used (@pxref{Options})
8773 and standard output is connected to a capable terminal, then the test
8774 results and the summary are colored appropriately. The user can disable
8775 colored output by setting the @command{make} variable
8776 @samp{AM_COLOR_TESTS=no}, or force colored output even without a connecting
8777 terminal with @samp{AM_COLOR_TESTS=always}. It's also worth noting that
8778 some @command{make} implementations, when used in parallel mode, have
8779 slightly different semantics (@pxref{Parallel make,,, autoconf,
8780 The Autoconf Manual}), which can break the automatic detection of a
8781 connection to a capable terminal. If this is the case, you'll have to
8782 resort to the use of @samp{AM_COLOR_TESTS=always} in order to have the
8783 testsuite output colorized.
8785 Test programs that need data files should look for them in @code{srcdir}
8786 (which is both a make variable and an environment variable made available
8787 to the tests), so that they work when building in a separate directory
8788 (@pxref{Build Directories, , Build Directories , autoconf,
8789 The Autoconf Manual}), and in particular for the @code{distcheck} rule
8790 (@pxref{Checking the Distribution}).
8793 @vindex TESTS_ENVIRONMENT
8794 @vindex AM_TESTS_ENVIRONMENT
8795 The @code{AM_TESTS_ENVIRONMENT} and @code{TESTS_ENVIRONMENT} variables can
8796 be used to run initialization code and set environment variables for the
8797 test scripts. The former variable is developer-reserved, and can be
8798 defined in the @file{Makefile.am}, while the latter is reserved for the
8799 user, which can employ it to extend or override the settings in the
8800 former; for this to work portably, however, the contents of a non-empty
8801 @code{AM_TESTS_ENVIRONMENT} @emph{must} be terminated by a semicolon.
8803 @vindex AM_TESTS_FD_REDIRECT
8804 The @code{AM_TESTS_FD_REDIRECT} variable can be used to define file
8805 descriptor redirections for the test scripts. One might think that
8806 @code{AM_TESTS_ENVIRONMENT} could be used for this purpose, but experience
8807 has shown that doing so portably is practically impossible. The main
8808 hurdle is constituted by Korn shells, which usually set the close-on-exec
8809 flag on file descriptors opened with the @command{exec} builtin, thus
8810 rendering an idiom like @code{AM_TESTS_ENVIRONMENT = exec 9>&2;}
8811 ineffectual. This issue also affects some Bourne shells, such as the
8812 HP-UX's @command{/bin/sh},
8813 @c FIXME: should we offer a link to the relevant discussions on the
8814 @c bug-autoconf list?
8816 @c Keep in sync with tests-environment-backcompat.sh
8818 AM_TESTS_ENVIRONMENT = \
8819 ## Some environment initializations are kept in a separate shell
8820 ## file `tests-env.sh', which can make it easier to also run tests
8821 ## from the command line.
8822 . $(srcdir)/tests-env.sh; \
8823 ## On Solaris, prefer more POSIX-compliant versions of the standard
8824 ## tools by default.
8825 if test -d /usr/xpg4/bin; then \
8826 PATH=/usr/xpg4/bin:$$PATH; export PATH; \
8828 @c $$ restore font-lock
8829 ## With this, the test scripts will be able to print diagnostic
8830 ## messages to the original standard error stream, even if the test
8831 ## driver redirects the stderr of the test scripts to a log file
8832 ## before executing them.
8833 AM_TESTS_FD_REDIRECT = 9>&2
8837 Note however that @code{AM_TESTS_ENVIRONMENT} is, for historical and
8838 implementation reasons, @emph{not} supported by the serial harness
8839 (@pxref{Serial Test Harness}).
8841 Automake ensures that each file listed in @code{TESTS} is built before
8842 it is run; you can list both source and derived programs (or scripts)
8843 in @code{TESTS}; the generated rule will look both in @code{srcdir} and
8844 @file{.}. For instance, you might want to run a C program as a test.
8845 To do this you would list its name in @code{TESTS} and also in
8846 @code{check_PROGRAMS}, and then specify it as you would any other
8849 Programs listed in @code{check_PROGRAMS} (and @code{check_LIBRARIES},
8850 @code{check_LTLIBRARIES}...) are only built during @code{make check},
8851 not during @code{make all}. You should list there any program needed
8852 by your tests that does not need to be built by @code{make all}. Note
8853 that @code{check_PROGRAMS} are @emph{not} automatically added to
8854 @code{TESTS} because @code{check_PROGRAMS} usually lists programs used
8855 by the tests, not the tests themselves. Of course you can set
8856 @code{TESTS = $(check_PROGRAMS)} if all your programs are test cases.
8858 @node Serial Test Harness
8859 @subsection Serial Test Harness
8860 @cindex @option{serial-tests}, Using
8862 @emph{NOTE:} This harness, while still being the default one, is
8863 obsolescent, and kept mostly for backward-compatibility reasons. The user
8864 is advised to use the parallel test harness instead (@pxref{Parallel Test
8865 Harness}). Be warned that future Automake versions might switch to use
8866 that more modern and feature-rich harness by default.
8868 The serial test harness is enabled by the Automake option
8869 @option{serial-tests}. It operates by simply running the tests serially,
8870 one at the time, without any I/O redirection. It's up to the user to
8871 implement logging of tests' output, if that's requited or desired.
8872 @c TODO: give an example of how this can be done.
8874 For historical and implementation reasons, the @code{AM_TESTS_ENVIRONMENT}
8875 variable is @emph{not} supported by this harness (it will be silently
8876 ignored if defined); only @code{TESTS_ENVIRONMENT} is, and it is to be
8877 considered a developer-reserved variable. This is done so that, when
8878 using the serial harness, @code{TESTS_ENVIRONMENT} can be defined to an
8879 invocation of an interpreter through which the tests are to be run.
8880 For instance, the following setup may be used to run tests with Perl:
8883 TESTS_ENVIRONMENT = $(PERL) -Mstrict -w
8884 TESTS = foo.pl bar.pl baz.pl
8888 It's important to note that the use of @code{TESTS_ENVIRONMENT} endorsed
8889 here would be @emph{invalid} with the parallel harness. That harness
8890 provides a more elegant way to achieve the same effect, with the further
8891 benefit of freeing the @code{TESTS_ENVIRONMENT} variable for the user
8892 (@pxref{Parallel Test Harness}).
8894 Another, less serious limit of the serial harness is that it doesn't
8895 really distinguish between simple failures and hard errors; this is
8896 due to historical reasons only, and might be fixed in future Automake
8899 @node Parallel Test Harness
8900 @subsection Parallel Test Harness
8901 @cindex @option{parallel-tests}, Using
8903 The parallel (or concurrent) test harness is enabled by the Automake option
8904 @option{parallel-tests}. It features automatic collection of the test
8905 scripts output in @file{.log} files, concurrent execution of tests with
8906 @code{make -j}, specification of inter-test dependencies, lazy reruns of
8907 tests that have not completed in a prior run, and hard errors for exceptional
8910 This harness is still somewhat experimental and may undergo changes in
8911 order to satisfy additional portability requirements.
8913 @anchor{Basics of test metadata}
8914 @vindex TEST_SUITE_LOG
8916 @cindex @file{.log} files
8917 @cindex @file{.trs} files
8918 @cindex test metadata
8919 The parallel test harness operates by defining a set of @command{make}
8920 rules that run the test scripts listed in @code{TESTS}, and, for each
8921 such script, save its output in a corresponding @file{.log} file and
8922 its results (and other ``metadata'', @pxref{API for Custom Test Drivers})
8923 in a corresponding @file{.trs} (as in @b{T}est @b{R}e@b{S}ults) file.
8924 @c We choose the `.trs' extension also because, at the time of writing,
8925 @c it isn't already used for other significant purposes; see e.g.:
8926 @c - http://filext.com/file-extension/trs
8927 @c - http://www.file-extensions.org/search/?searchstring=trs
8928 The @file{.log} file will contain all the output emitted by the test on
8929 its standard output and its standard error. The @file{.trs} file will
8930 contain, among the other things, the results of the test cases run by
8933 The parallel test harness will also create a summary log file,
8934 @code{TEST_SUITE_LOG}, which defaults to @file{test-suite.log} and requires
8935 a @file{.log} suffix. This file depends upon all the @file{.log} and
8936 @file{.trs} files created for the test scripts listed in @code{TESTS}.
8939 As with the serial harness above, by default one status line is printed
8940 per completed test, and a short summary after the suite has completed.
8941 However, standard output and standard error of the test are redirected
8942 to a per-test log file, so that parallel execution does not produce
8943 intermingled output. The output from failed tests is collected in the
8944 @file{test-suite.log} file. If the variable @samp{VERBOSE} is set, this
8945 file is output after the summary.
8946 @c FIXME: we should be clearer about what we mean exactly here ...
8947 For best results, the tests should be verbose by default now.
8949 @vindex TEST_EXTENSIONS
8951 Each couple of @file{.log} and @file{.trs} files is created when the
8952 corresponding test has completed. The set of log files is listed in
8953 the read-only variable @code{TEST_LOGS}, and defaults to @code{TESTS},
8954 with the executable extension if any (@pxref{EXEEXT}), as well as any
8955 suffix listed in @code{TEST_EXTENSIONS} removed, and @file{.log} appended.
8956 Results are undefined if a test file name ends in several concatenated
8957 suffixes. @code{TEST_EXTENSIONS} defaults to @file{.test}; it can be
8958 overridden by the user, in which case any extension listed in it must be
8959 constituted by a dot, followed by a non-digit alphabetic character,
8960 followed by any number of alphabetic characters.
8961 @c Keep in sync with test-extensions.sh
8962 For example, @samp{.sh}, @samp{.T} and @samp{.t1} are valid extensions,
8963 while @samp{.x-y}, @samp{.6c} and @samp{.t.1} are not.
8965 @vindex _LOG_COMPILE
8966 @vindex _LOG_COMPILER
8969 @vindex LOG_COMPILER
8971 @vindex @var{ext}_LOG_COMPILE
8972 @vindex @var{ext}_LOG_COMPILER
8973 @vindex @var{ext}_LOG_FLAGS
8974 @vindex AM_@var{ext}_LOG_FLAGS
8975 @vindex AM_LOG_FLAGS
8976 For tests that match an extension @code{.@var{ext}} listed in
8977 @code{TEST_EXTENSIONS}, you can provide a custom ``test runner'' using
8978 the variable @code{@var{ext}_LOG_COMPILER} (note the upper-case
8979 extension) and pass options in @code{AM_@var{ext}_LOG_FLAGS} and allow
8980 the user to pass options in @code{@var{ext}_LOG_FLAGS}. It will cause
8981 all tests with this extension to be called with this runner. For all
8982 tests without a registered extension, the variables @code{LOG_COMPILER},
8983 @code{AM_LOG_FLAGS}, and @code{LOG_FLAGS} may be used. For example,
8985 @c Keep in sync with parallel-tests-log-compiler-example.sh
8987 TESTS = foo.pl bar.py baz
8988 TEST_EXTENSIONS = .pl .py
8989 PL_LOG_COMPILER = $(PERL)
8990 AM_PL_LOG_FLAGS = -w
8991 PY_LOG_COMPILER = $(PYTHON)
8992 AM_PY_LOG_FLAGS = -v
8993 LOG_COMPILER = ./wrapper-script
8998 will invoke @samp{$(PERL) -w foo.pl}, @samp{$(PYTHON) -v bar.py},
8999 and @samp{./wrapper-script -d baz} to produce @file{foo.log},
9000 @file{bar.log}, and @file{baz.log}, respectively. The @file{foo.trs},
9001 @file{bar.trs} and @file{baz.trs} files will be automatically produced
9004 It's important to note that, differently from what we've seen for the
9005 serial test harness (@pxref{Parallel Test Harness}), the
9006 @code{AM_TESTS_ENVIRONMENT} and @code{TESTS_ENVIRONMENT} variables
9007 @emph{cannot} be use to define a custom test runner; the
9008 @code{LOG_COMPILER} and @code{LOG_FLAGS} (or their extension-specific
9009 counterparts) should be used instead:
9013 AM_TESTS_ENVIRONMENT = PERL5LIB='$(srcdir)/lib' $(PERL) -Mstrict -w
9018 AM_TESTS_ENVIRONMENT = PERL5LIB='$(srcdir)/lib'; export PERL5LIB;
9019 LOG_COMPILER = $(PERL)
9020 AM_LOG_FLAGS = -Mstrict -w
9023 By default, the test suite harness will run all tests, but there are
9024 several ways to limit the set of tests that are run:
9028 You can set the @code{TESTS} variable. For example, you can use a
9029 command like this to run only a subset of the tests:
9032 env TESTS="foo.test bar.test" make -e check
9035 Note however that the command above will unconditionally overwrite the
9036 @file{test-suite.log} file, thus clobbering the recorded results
9037 of any previous testsuite run. This might be undesirable for packages
9038 whose testsuite takes long time to execute. Luckily, this problem can
9039 easily be avoided by overriding also @code{TEST_SUITE_LOG} at runtime;
9042 @c Keep in sync with parallel-tests-log-override-2.sh
9044 env TEST_SUITE_LOG=partial.log TESTS="..." make -e check
9047 will write the result of the partial testsuite runs to the
9048 @file{partial.log}, without touching @file{test-suite.log}.
9051 You can set the @code{TEST_LOGS} variable. By default, this variable is
9052 computed at @command{make} run time from the value of @code{TESTS} as
9053 described above. For example, you can use the following:
9056 set x subset*.log; shift
9057 env TEST_LOGS="foo.log $*" make -e check
9060 The comments made above about @code{TEST_SUITE_LOG} overriding applies
9064 @vindex RECHECK_LOGS
9065 @cindex lazy test execution
9066 By default, the test harness removes all old per-test @file{.log} and
9067 @file{.trs} files before it starts running tests to regenerate them. The
9068 variable @code{RECHECK_LOGS} contains the set of @file{.log} (and, by
9069 implication, @file{.trs}) files which are removed. @code{RECHECK_LOGS}
9070 defaults to @code{TEST_LOGS}, which means all tests need to be rechecked.
9071 By overriding this variable, you can choose which tests need to be
9072 reconsidered. For example, you can lazily rerun only those tests which
9073 are outdated, i.e., older than their prerequisite test files, by setting
9074 this variable to the empty value:
9077 env RECHECK_LOGS= make -e check
9082 You can ensure that all tests are rerun which have failed or passed
9083 unexpectedly, by running @code{make recheck} in the test directory.
9084 This convenience target will set @code{RECHECK_LOGS} appropriately
9085 before invoking the main test harness.
9089 In order to guarantee an ordering between tests even with @code{make
9090 -j@var{N}}, dependencies between the corresponding @file{.log} files
9091 may be specified through usual @command{make} dependencies. For example,
9092 the following snippet lets the test named @file{foo-execute.test} depend
9093 upon completion of the test @file{foo-compile.test}:
9096 TESTS = foo-compile.test foo-execute.test
9097 foo-execute.log: foo-compile.log
9101 Please note that this ordering ignores the @emph{results} of required
9102 tests, thus the test @file{foo-execute.test} is run even if the test
9103 @file{foo-compile.test} failed or was skipped beforehand. Further,
9104 please note that specifying such dependencies currently works only for
9105 tests that end in one of the suffixes listed in @code{TEST_EXTENSIONS}.
9107 Tests without such specified dependencies may be run concurrently with
9108 parallel @command{make -j@var{N}}, so be sure they are prepared for
9109 concurrent execution.
9112 @c Keep in sync with 'parallel-tests-extra-programs.test'.
9113 The combination of lazy test execution and correct dependencies between
9114 tests and their sources may be exploited for efficient unit testing
9115 during development. To further speed up the edit-compile-test cycle, it
9116 may even be useful to specify compiled programs in @code{EXTRA_PROGRAMS}
9117 instead of with @code{check_PROGRAMS}, as the former allows intertwined
9118 compilation and test execution (but note that @code{EXTRA_PROGRAMS} are
9119 not cleaned automatically, @pxref{Uniform}).
9121 The variables @code{TESTS} and @code{XFAIL_TESTS} may contain
9122 conditional parts as well as configure substitutions. In the latter
9123 case, however, certain restrictions apply: substituted test names
9124 must end with a nonempty test suffix like @file{.test}, so that one of
9125 the inference rules generated by @command{automake} can apply. For
9126 literal test names, @command{automake} can generate per-target rules
9127 to avoid this limitation.
9129 Please note that it is currently not possible to use @code{$(srcdir)/}
9130 or @code{$(top_srcdir)/} in the @code{TESTS} variable. This technical
9131 limitation is necessary to avoid generating test logs in the source tree
9132 and has the unfortunate consequence that it is not possible to specify
9133 distributed tests that are themselves generated by means of explicit
9134 rules, in a way that is portable to all @command{make} implementations
9135 (@pxref{Make Target Lookup,,, autoconf, The Autoconf Manual}, the
9136 semantics of FreeBSD and OpenBSD @command{make} conflict with this).
9137 In case of doubt you may want to require to use GNU @command{make},
9138 or work around the issue with inference rules to generate the tests.
9140 @node Custom Test Drivers
9141 @section Custom Test Drivers
9144 * Overview of Custom Test Drivers Support::
9145 * Declaring Custom Test Drivers::
9146 * API for Custom Test Drivers::
9149 @node Overview of Custom Test Drivers Support
9150 @subsection Overview of Custom Test Drivers Support
9152 Starting from Automake version 1.12, the parallel test harness allows
9153 the package authors to use third-party custom test drivers, in case the
9154 default ones are inadequate for their purposes, or do not support their
9155 testing protocol of choice.
9157 A custom test driver is expected to properly run the test programs passed
9158 to it (including the command-line arguments passed to those programs, if
9159 any), to analyze their execution and outcome, to create the @file{.log}
9160 and @file{.trs} files associated to these test runs, and to display the test
9161 results on the console. It is responsibility of the author of the test
9162 driver to ensure that it implements all the above steps meaningfully and
9163 correctly; Automake isn't and can't be of any help here. On the other
9164 hand, the Automake-provided code for testsuite summary generation offers
9165 support for test drivers allowing several test results per test script,
9166 if they take care to register such results properly (@pxref{Log files
9167 generation and test results recording}).
9169 The exact details of how test scripts' results are to be determined and
9170 analyzed is left to the individual drivers. Some drivers might only
9171 consider the test script exit status (this is done for example by the
9172 default test driver used by the parallel test harness, described
9173 in the previous section). Other drivers might implement more complex and
9174 advanced test protocols, which might require them to parse and interpreter
9175 the output emitted by the test script they're running (examples of such
9176 protocols are TAP and SubUnit).
9178 It's very important to note that, even when using custom test drivers,
9179 most of the infrastructure described in the previous section about the
9180 parallel harness remains in place; this includes:
9184 list of test scripts defined in @code{TESTS}, and overridable at
9185 runtime through the redefinition of @code{TESTS} or @code{TEST_LOGS};
9187 concurrency through the use of @command{make}'s option @option{-j};
9189 per-test @file{.log} and @file{.trs} files, and generation of a summary
9190 @file{.log} file from them;
9192 @code{recheck} target, @code{RECHECK_LOGS} variable, and lazy reruns
9195 inter-test dependencies;
9197 support for @code{check_*} variables (@code{check_PROGRAMS},
9198 @code{check_LIBRARIES}, ...);
9200 use of @code{VERBOSE} environment variable to get verbose output on
9203 definition and honoring of @code{TESTS_ENVIRONMENT},
9204 @code{AM_TESTS_ENVIRONMENT} and @code{AM_TESTS_FD_REDIRECT}
9207 definition of generic and extension-specific @code{LOG_COMPILER} and
9208 @code{LOG_FLAGS} variables.
9212 On the other hand, the exact semantics of how (and if)
9213 @option{color-tests}, @code{XFAIL_TESTS}, and hard errors are supported
9214 and handled is left to the individual test drivers.
9216 @c TODO: We should really add a working example in the doc/ directory,
9217 @c TODO: and reference if from here.
9219 @node Declaring Custom Test Drivers
9220 @subsection Declaring Custom Test Drivers
9223 @vindex _LOG_DRIVER_FLAGS
9225 @vindex LOG_DRIVER_FLAGS
9226 @vindex @var{ext}_LOG_DRIVER
9227 @vindex @var{ext}_LOG_DRIVER_FLAGS
9228 @vindex AM_@var{ext}_LOG_DRIVER_FLAGS
9229 @vindex AM_LOG_DRIVER_FLAGS
9230 Custom testsuite drivers are declared by defining the make variables
9231 @code{LOG_DRIVER} or @code{@var{ext}_LOG_DRIVER} (where @var{ext} must
9232 be declared in @code{TEST_EXTENSIONS}). They must be defined to
9233 programs or scripts that will be used to drive the execution, logging,
9234 and outcome report of the tests with corresponding extensions (or of
9235 those with no registered extension in the case of @code{LOG_DRIVER}).
9236 Clearly, multiple distinct test drivers can be declared in the same
9237 @file{Makefile.am}. Note moreover that the @code{LOG_DRIVER} variables
9238 are @emph{not} a substitute for the @code{LOG_COMPILER} variables: the
9239 two sets of variables can, and often do, usefully and legitimately
9242 @c TODO: We should really be able to point to a clarifying example here!
9244 The developer-reserved variable @code{AM_LOG_DRIVER_FLAGS} and the
9245 user-reserved variable @code{LOG_DRIVER_FLAGS} can be used to define
9246 flags that will be passed to each invocation of @code{LOG_DRIVER},
9247 with the user-defined flags obviously taking precedence over the
9248 developer-reserved ones. Similarly, for each extension @var{ext}
9249 declared in @code{TEST_EXTENSIONS}, flags listed in
9250 @code{AM_@var{ext}_LOG_DRIVER_FLAGS} and
9251 @code{@var{ext}_LOG_DRIVER_FLAGS} will be passed to
9252 invocations of @code{@var{ext}_LOG_DRIVER}.
9254 @node API for Custom Test Drivers
9255 @subsection API for Custom Test Drivers
9257 Note that @emph{the APIs described here are still highly experimental},
9258 and will very likely undergo tightenings and likely also extensive changes
9259 in the future, to accommodate for new features or to satisfy additional
9260 portability requirements.
9262 The main characteristic of these APIs is that they are designed to share
9263 as much infrastructure, semantics, and implementation details as possible
9264 with the parallel test harness and its default driver.
9267 * Command-line arguments for test drivers::
9268 * Log files generation and test results recording::
9269 * Testsuite progress output::
9272 @node Command-line arguments for test drivers
9273 @subsubsection Command-line arguments for test drivers
9275 A custom driver can rely on various command-line options and arguments
9276 being passed to it automatically by the Automake's @option{parallel-tests}
9277 harness. It is @emph{mandatory} that it understands all of them (even
9278 if the exact interpretation of the associated semantics can legitimately
9279 change between a test driver and another, and even be a no-op in some
9283 Here is the list of options:
9286 @item --test-name=@var{NAME}
9287 The name of the test, with VPATH prefix (if any) removed. This can have a
9288 suffix and a directory component (as in e.g., @file{sub/foo.test}), and is
9289 mostly meant to be used in console reports about testsuite advancements and
9290 results (@pxref{Testsuite progress output}).
9291 @item --log-file=@file{@var{PATH}.log}
9292 The @file{.log} file the test driver must create (@pxref{Basics of
9293 test metadata}). If it has a directory component (as in e.g.,
9294 @file{sub/foo.log}), the test harness will ensure that such directory
9295 exists @emph{before} the test driver is called.
9296 @item --trs-file=@file{@var{PATH}.trs}
9297 The @file{.trs} file the test driver must create (@pxref{Basics of
9298 test metadata}). If it has a directory component (as in e.g.,
9299 @file{sub/foo.trs}), the test harness will ensure that such directory
9300 exists @emph{before} the test driver is called.
9301 @item --color-tests=@{yes|no@}
9302 Whether the console output should be colorized or not (@pxref{Simple
9303 tests and color-tests}, to learn when this option gets activated and
9305 @item --expect-failure=@{yes|no@}
9306 Whether the tested program is expected to fail.
9307 @item --enable-hard-errors=@{yes|no@}
9308 Whether ``hard errors'' in the tested program should be treated differently
9309 from normal failures or not (the default should be @code{yes}). The exact
9310 meaning of ``hard error'' is highly dependent from the test protocols or
9313 Explicitly terminate the list of options.
9317 The first non-option argument passed to the test driver is the program to
9318 be run, and all the following ones are command-line options and arguments
9321 Note that the exact semantics attached to the @option{--color-tests},
9322 @option{--expect-failure} and @option{--enable-hard-errors} options are
9323 left up to the individual test drivers. Still, having a behaviour
9324 compatible or at least similar to that provided by the default
9325 @option{parallel-tests} driver is advised, as that would offer a better
9326 consistency and a more pleasant user experience.
9328 @node Log files generation and test results recording
9329 @subsubsection Log files generation and test results recording
9331 The test driver must correctly generate the files specified by the
9332 @option{--log-file} and @option{--trs-file} option (even when the tested
9333 program fails or crashes).
9335 The @file{.log} file should ideally contain all the output produced by the
9336 tested program, plus optionally other information that might facilitate
9337 debugging or analysis of bug reports. Apart from that, its format is
9340 The @file{.trs} file is used to register some metadata through the use
9341 of custom reStructuredText fields. This metadata is expected to be
9342 employed in various ways by the parallel test harness; for example, to
9343 count the test results when printing the testsuite summary, or to decide
9344 which tests to re-run upon @command{make reheck}. Unrecognized metadata
9345 in a @file{.trs} file is currently ignored by the harness, but this might
9346 change in the future. The list of currently recognized metadata follows.
9351 @cindex Register test result
9352 @cindex Register test case result
9353 @cindex Test result, registering
9354 @cindex Test case result, registering
9355 @cindex @code{:test-result:}
9356 @cindex reStructuredText field, @code{:test-result:}
9357 The test driver must use this field to register the results of @emph{each}
9358 test case run by a test script file. Several @code{:test-result:} fields
9359 can be present in the same @file{.trs} file; this is done in order to
9360 support test protocols that allow a single test script to run more test
9363 @c Keep this in sync with lib/am/check-am:$(TEST_SUITE_LOG).
9364 The only recognized test results are currently @code{PASS}, @code{XFAIL},
9365 @code{SKIP}, @code{FAIL}, @code{XPASS} and @code{ERROR}. These results,
9366 when declared with @code{:test-result:}, can be optionally followed by
9367 text holding the name and/or a brief description of the corresponding
9368 test; the @option{parallel-tests} harness will ignore such extra text when
9369 generating @file{test-suite.log} and preparing the testsuite summary.
9371 @c Keep in sync with 'test-metadata-recheck.test'.
9372 @item @code{:recheck:}
9374 @cindex reStructuredText field, @code{:recheck:}
9375 If this field is present and defined to @code{no}, then the corresponding
9376 test script will @emph{not} be run upon a @command{make recheck}. What
9377 happens when two or more @code{:recheck:} fields are present in the same
9378 @file{.trs} file is undefined behaviour.
9380 @c Keep in sync with 'test-metadata-global-log.test'.
9381 @item @code{:copy-in-global-log:}
9382 @cindex :copy-in-global-log:
9383 @cindex reStructuredText field, @code{:copy-in-global-log:}
9384 If this field is present and defined to @code{no}, then the content
9385 of the @file{.log} file will @emph{not} be copied into the global
9386 @file{test-suite.log}. We allow to forsake such copying because, while
9387 it can be useful in debugging and analysis of bug report, it can also be
9388 just a waste of space in normal situations, e.g., when a test script is
9389 successful. What happens when two or more @code{:copy-in-global-log:}
9390 fields are present in the same @file{.trs} file is undefined behaviour.
9392 @c Keep in sync with 'test-metadata-global-result.test'.
9393 @item @code{:test-global-result:}
9394 @cindex :test-global-result:
9395 @cindex reStructuredText field, @code{:test-global-result:}
9396 This is used to declare the "global result" of the script. Currently,
9397 the value of this field is needed only to be reported (more or less
9398 verbatim) in the generated global log file @code{$(TEST_SUITE_LOG)},
9399 so it's quite free-form. For example, a test script which run 10 test
9400 cases, 6 of which pass and 4 of which are skipped, could reasonably have
9401 a @code{PASS/SKIP} value for this field, while a test script which run
9402 19 successful tests and one failed test could have an @code{ALMOST
9403 PASSED} value. What happens when two or more @code{:test-global-result:}
9404 fields are present in the same @file{.trs} file is undefined behaviour.
9408 Let's see a small example. Assume a @file{.trs} file contains the
9412 :test-result: PASS server starts
9413 :global-log-copy: no
9414 :test-result: PASS HTTP/1.1 request
9415 :test-result: FAIL HTTP/1.0 request
9417 :test-result: SKIP HTTPS request (TLS library wasn't available)
9418 :test-result: PASS server stops
9422 Then the corresponding test script will be re-run by @command{make check},
9423 will contribute with @emph{five} test results to the testsuite summary
9424 (three of these tests being successful, one failed, and one skipped), and
9425 the content of the corresponding @file{.log} file will @emph{not} be
9426 copied in the global log file @file{test-suite.log}.
9428 @node Testsuite progress output
9429 @subsubsection Testsuite progress output
9431 A custom test driver also has the task of displaying, on the standard
9432 output, the test results as soon as they become available. Depending on
9433 the protocol in use, it can also display the reasons for failures and
9434 skips, and, more generally, any useful diagnostic output (but remember
9435 that each line on the screen is precious, so that cluttering the screen
9436 with overly verbose information is bad idea). The exact format of this
9437 progress output is left up to the test driver; in fact, a custom test
9438 driver might @emph{theoretically} even decide not to do any such report,
9439 leaving it all to the testsuite summary (that would be a very lousy idea,
9440 of course, and serves only to illustrate the flexibility that is
9443 Remember that consistency is good; so, if possible, try to be consistent
9444 with the output of the built-in Automake test drivers, providing a similar
9445 ``look & feel''. In particular, the testsuite progress output should be
9446 colorized when the @option{--color-tests} is passed to the driver. On the
9447 other end, if you are using a known and widespread test protocol with
9448 well-established implementations, being consistent with those
9449 implementations' output might be a good idea too.
9451 @c TODO: Give an example, maybe inspired to py.test-style output.
9452 @c TODO: That is a good idea because it shows a test driver that allows
9453 @c TODO: for different levels of verbosity in the progress output (could
9454 @c TODO: be implemented either using a driver cmdline flag, or an
9455 @c TODO: environment variable, or both).
9457 @node Using the TAP test protocol
9458 @section Using the TAP test protocol
9461 * Introduction to TAP::
9462 * Use TAP with the Automake test harness::
9463 * Incompatibilities with other TAP parsers and drivers::
9464 * Links and external resources on TAP::
9467 @node Introduction to TAP
9468 @subsection Introduction to TAP
9470 TAP, the Test Anything Protocol, is a simple text-based interface between
9471 testing modules or programs and a test harness. The tests (also called
9472 ``TAP producers'' in this context) write test results in a simple format
9473 on standard output; a test harness (also called ``TAP consumer'') will
9474 parse and interpret these results, and properly present them to the user,
9475 and/or register them for later analysis. The exact details of how this
9476 is accomplished can vary among different test harnesses. The Automake
9477 parallel harness will present the results on the console in the usual
9478 fashion (@pxref{Testsuite progress on console}), and will use the
9479 @file{.trs} files (@pxref{Basics of test metadata}) to store the test
9480 results and related metadata. Apart from that, it will try to remain
9481 as much compatible as possible with pre-existing and widespread utilities,
9482 such as the @uref{http://search.cpan.org/~andya/Test-Harness/bin/prove,
9483 @command{prove} utility}, at least for the simpler usages.
9485 TAP started its life as part of the test harness for Perl, but today
9486 it has been (mostly) standardized, and has various independent
9487 implementations in different languages; among them, C, C++, Perl,
9488 Python, PHP, and Java. For a semi-official specification of the
9489 TAP protocol, please refer to the documentation of
9490 @uref{http://search.cpan.org/~petdance/Test-Harness/lib/Test/Harness/TAP.pod,
9491 @samp{Test::Harness::TAP}}.
9493 The most relevant real-world usages of TAP are obviously in the testsuites
9494 of @command{perl} and of many perl modules. Still, also other important
9495 third-party packages, such as @uref{http://git-scm.com/, @command{git}},
9496 use TAP in their testsuite.
9498 @node Use TAP with the Automake test harness
9499 @subsection Use TAP with the Automake test harness
9501 Currently, the TAP driver that comes with Automake requires some by-hand
9502 steps on the developer's part (this situation should hopefully be improved
9503 in future Automake versions). You'll have to grab the @file{tap-driver.sh}
9504 script from the Automake distribution by hand, copy it in your source tree,
9505 add a call to @code{AC_PROG_AWK} in @file{configure.ac} to search for a
9506 proper awk program, and use the Automake support for third-party test
9507 drivers to instruct the harness to use the @file{tap-driver.sh} script
9508 and that awk program to run your TAP-producing tests. See the example
9509 below for clarification.
9511 Apart from the options common to all the Automake test drivers
9512 (@pxref{Command-line arguments for test drivers}), the @file{tap-driver.sh}
9513 supports the following options, whose names are chosen for enhanced
9514 compatibility with the @command{prove} utility.
9517 @c Keep in sync with 'tap-exit.test' and 'tap-signal.tap'.
9519 Causes the test driver to ignore the exit status of the test scripts;
9520 by default, the driver will report an error if the script exits with a
9521 non-zero status. This option has effect also on non-zero exit statuses
9522 due to termination by a signal.
9524 Instruct the test driver to display TAP diagnostic (i.e., lines beginning
9525 with the @samp{#} character) in the testsuite progress output too; by
9526 default, TAP diagnostic is only copied to the @file{.log} file.
9528 Revert the effects of @option{--comments}.
9530 Instruct the test driver to merge the test scripts' standard error into
9531 their standard output. This is necessary if you want to ensure that
9532 diagnostics from the test scripts are displayed in the correct order
9533 relative to test results; this can be of great help in debugging
9534 (especially if your test scripts are shell scripts run with shell
9535 tracing active). As a downside, this option might cause the test
9536 harness to get confused if anything that appears on standard error
9537 looks like a test result.
9539 Revert the effects of @option{--merge}.
9540 @item --diagnostic-string=@var{STRING}
9541 Change the string that introduces TAP diagnostic from the default value
9542 of ``@code{#}'' to @code{@var{STRING}}. This can be useful if your
9543 TAP-based test scripts produce verbose output on which they have limited
9544 control (because, say, the output comes from other tools invoked in the
9545 scripts), and it might contain text that gets spuriously interpreted as
9546 TAP diagnostic: such an issue can be solved by redefining the string that
9547 activates TAP diagnostic to a value you know won't appear by chance in
9548 the tests' output. Note however that this feature is non-standard, as
9549 the ``official'' TAP protocol does not allow for such a customization; so
9550 don't use it if you can avoid it.
9554 Here is an example of how the TAP driver can be set up and used.
9556 @c Keep in sync with tap-doc2.sh
9558 % @kbd{cat configure.ac}
9559 AC_INIT([GNU Try Tap], [1.0], [bug-automake@@gnu.org])
9560 AC_CONFIG_AUX_DIR([build-aux])
9561 AM_INIT_AUTOMAKE([foreign parallel-tests -Wall -Werror])
9562 AC_CONFIG_FILES([Makefile])
9563 AC_REQUIRE_AUX_FILE([tap-driver.sh])
9567 % @kbd{cat Makefile.am}
9568 TEST_LOG_DRIVER = env AM_TAP_AWK='$(AWK)' $(SHELL) \
9569 $(top_srcdir)/build-aux/tap-driver.sh
9570 TESTS = foo.test bar.test baz.test
9571 EXTRA_DIST = $(TESTS)
9573 % @kbd{cat foo.test}
9575 echo 1..4 # Number of tests to be executed.
9576 echo 'ok 1 - Swallows fly'
9577 echo 'not ok 2 - Caterpillars fly # TODO metamorphosis in progress'
9578 echo 'ok 3 - Pigs fly # SKIP not enough acid'
9579 echo '# I just love word plays ...'
9580 echo 'ok 4 - Flies fly too :-)'
9582 % @kbd{cat bar.test}
9585 echo 'not ok 1 - Bummer, this test has failed.'
9586 echo 'ok 2 - This passed though.'
9587 echo 'Bail out! Ennui kicking in, sorry...'
9588 echo 'ok 3 - This will not be seen.'
9590 % @kbd{cat baz.test}
9594 # Exit with error, even if all the tests have been successful.
9597 % @kbd{cp @var{PREFIX}/share/automake-@var{APIVERSION}/tap-driver.pl .}
9598 % @kbd{autoreconf -vi && ./configure && make check}
9600 PASS: foo.test 1 - Swallows fly
9601 XFAIL: foo.test 2 - Caterpillars fly # TODO metamorphosis in progress
9602 SKIP: foo.test 3 - Pigs fly # SKIP not enough acid
9603 PASS: foo.test 4 - Flies fly too :-)
9604 FAIL: bar.test 1 - Bummer, this test has failed.
9605 PASS: bar.test 2 - This passed though.
9606 ERROR: bar.test - Bail out! Ennui kicking in, sorry...
9608 ERROR: baz.test - exited with status 7
9610 Please report to bug-automake@@gnu.org
9612 % @kbd{echo exit status: $?}
9615 @c Keep the "skewed" indentation below, it produces pretty PDF output.
9616 % @kbd{env TEST_LOG_DRIVER_FLAGS='--comments --ignore-exit' \
9617 TESTS='foo.test baz.test' make -e check}
9619 PASS: foo.test 1 - Swallows fly
9620 XFAIL: foo.test 2 - Caterpillars fly # TODO metamorphosis in progress
9621 SKIP: foo.test 3 - Pigs fly # SKIP not enough acid
9622 # foo.test: I just love word plays...
9623 PASS: foo.test 4 - Flies fly too :-)
9626 % @kbd{echo exit status: $?}
9630 @node Incompatibilities with other TAP parsers and drivers
9631 @subsection Incompatibilities with other TAP parsers and drivers
9633 For implementation or historical reasons, the TAP driver and harness as
9634 implemented by Automake have some minors incompatibilities with the
9635 mainstream versions, which you should be aware of.
9639 A @code{Bail out!} directive doesn't stop the whole testsuite, but only
9640 the test script it occurs in. This doesn't follow TAP specifications,
9641 but on the other hand it maximizes compatibility (and code sharing) with
9642 the ``hard error'' concept of the default @option{parallel-tests} driver.
9644 The @code{version} and @code{pragma} directives are not supported.
9646 The @option{--diagnostic-string} option of our driver allows to modify
9647 the string that introduces TAP diagnostic from the default value
9648 of ``@code{#}''. The standard TAP protocol has currently no way to
9649 allow this, so if you use it your diagnostic will be lost to more
9650 compliant tools like @command{prove} and @code{Test::Harness}
9652 And there are probably some other small and yet undiscovered
9653 incompatibilities, especially in corner cases or with rare usages.
9656 @node Links and external resources on TAP
9657 @subsection Links and external resources on TAP
9660 Here are some links to more extensive official or third-party
9661 documentation and resources about the TAP protocol and related
9662 tools and libraries.
9665 @uref{http://search.cpan.org/~petdance/Test-Harness/lib/Test/Harness/TAP.pod,
9666 @samp{Test::Harness::TAP}},
9667 the (mostly) official documentation about the TAP format and protocol.
9669 @uref{http://search.cpan.org/~andya/Test-Harness/bin/prove,
9671 the most famous command-line TAP test driver, included in the distribution
9672 of @command{perl} and
9673 @uref{http://search.cpan.org/~andya/Test-Harness/lib/Test/Harness.pm,
9674 @samp{Test::Harness}}.
9676 The @uref{http://testanything.org/wiki/index.php/Main_Page,TAP wiki}.
9678 A ``gentle introduction'' to testing for perl coders:
9679 @uref{http://search.cpan.org/dist/Test-Simple/lib/Test/Tutorial.pod,
9680 @samp{Test::Tutorial}}.
9682 @uref{http://search.cpan.org/~mschwern/Test-Simple/lib/Test/Simple.pm,
9683 @samp{Test::Simple}}
9685 @uref{http://search.cpan.org/~mschwern/Test-Simple/lib/Test/More.pm,
9687 the standard perl testing libraries, which are based on TAP.
9689 @uref{http://www.eyrie.org/~eagle/software/c-tap-harness/,C TAP Harness},
9690 a C-based project implementing both a TAP producer and a TAP consumer.
9692 @uref{http://www.tap4j.org/,tap4j},
9693 a Java-based project implementing both a TAP producer and a TAP consumer.
9697 @section DejaGnu Tests
9699 If @uref{ftp://ftp.gnu.org/gnu/dejagnu/, @command{dejagnu}} appears in
9700 @code{AUTOMAKE_OPTIONS}, then a @command{dejagnu}-based test suite is
9701 assumed. The variable @code{DEJATOOL} is a list of names that are
9702 passed, one at a time, as the @option{--tool} argument to
9703 @command{runtest} invocations; it defaults to the name of the package.
9705 The variable @code{RUNTESTDEFAULTFLAGS} holds the @option{--tool} and
9706 @option{--srcdir} flags that are passed to dejagnu by default; this can be
9707 overridden if necessary.
9708 @vindex RUNTESTDEFAULTFLAGS
9710 The variables @code{EXPECT} and @code{RUNTEST} can
9711 also be overridden to provide project-specific values. For instance,
9712 you will need to do this if you are testing a compiler toolchain,
9713 because the default values do not take into account host and target
9720 The contents of the variable @code{RUNTESTFLAGS} are passed to the
9721 @code{runtest} invocation. This is considered a ``user variable''
9722 (@pxref{User Variables}). If you need to set @command{runtest} flags in
9723 @file{Makefile.am}, you can use @code{AM_RUNTESTFLAGS} instead.
9724 @vindex RUNTESTFLAGS
9725 @vindex AM_RUNTESTFLAGS
9727 @cindex @file{site.exp}
9728 Automake will generate rules to create a local @file{site.exp} file,
9729 defining various variables detected by @command{configure}. This file
9730 is automatically read by DejaGnu. It is OK for the user of a package
9731 to edit this file in order to tune the test suite. However this is
9732 not the place where the test suite author should define new variables:
9733 this should be done elsewhere in the real test suite code.
9734 Especially, @file{site.exp} should not be distributed.
9736 Still, if the package author has legitimate reasons to extend
9737 @file{site.exp} at @command{make} time, he can do so by defining
9738 the variable @code{EXTRA_DEJAGNU_SITE_CONFIG}; the files listed
9739 there will be considered @file{site.exp} prerequisites, and their
9740 content will be appended to it (in the same order in which they
9741 appear in @code{EXTRA_DEJAGNU_SITE_CONFIG}). Note that files are
9742 @emph{not} distributed by default.
9744 For more information regarding DejaGnu test suites, see @ref{Top, , ,
9745 dejagnu, The DejaGnu Manual}.
9748 @section Install Tests
9750 The @code{installcheck} target is available to the user as a way to
9751 run any tests after the package has been installed. You can add tests
9752 to this by writing an @code{installcheck-local} rule.
9756 @chapter Rebuilding Makefiles
9757 @cindex rebuild rules
9759 Automake generates rules to automatically rebuild @file{Makefile}s,
9760 @file{configure}, and other derived files like @file{Makefile.in}.
9762 @acindex AM_MAINTAINER_MODE
9763 If you are using @code{AM_MAINTAINER_MODE} in @file{configure.ac}, then
9764 these automatic rebuilding rules are only enabled in maintainer mode.
9766 @vindex ACLOCAL_AMFLAGS
9767 Sometimes you need to run @command{aclocal} with an argument like
9768 @option{-I} to tell it where to find @file{.m4} files. Since
9769 sometimes @command{make} will automatically run @command{aclocal}, you
9770 need a way to specify these arguments. You can do this by defining
9771 @code{ACLOCAL_AMFLAGS}; this holds arguments that are passed verbatim
9772 to @command{aclocal}. This variable is only useful in the top-level
9775 @vindex CONFIG_STATUS_DEPENDENCIES
9776 @vindex CONFIGURE_DEPENDENCIES
9777 @cindex @file{version.sh}, example
9778 @cindex @file{version.m4}, example
9780 Sometimes it is convenient to supplement the rebuild rules for
9781 @file{configure} or @file{config.status} with additional dependencies.
9782 The variables @code{CONFIGURE_DEPENDENCIES} and
9783 @code{CONFIG_STATUS_DEPENDENCIES} can be used to list these extra
9784 dependencies. These variables should be defined in all
9785 @file{Makefile}s of the tree (because these two rebuild rules are
9786 output in all them), so it is safer and easier to @code{AC_SUBST} them
9787 from @file{configure.ac}. For instance, the following statement will
9788 cause @file{configure} to be rerun each time @file{version.sh} is
9792 AC_SUBST([CONFIG_STATUS_DEPENDENCIES], ['$(top_srcdir)/version.sh'])
9796 Note the @samp{$(top_srcdir)/} in the file name. Since this variable
9797 is to be used in all @file{Makefile}s, its value must be sensible at
9798 any level in the build hierarchy.
9800 Beware not to mistake @code{CONFIGURE_DEPENDENCIES} for
9801 @code{CONFIG_STATUS_DEPENDENCIES}.
9803 @code{CONFIGURE_DEPENDENCIES} adds dependencies to the
9804 @file{configure} rule, whose effect is to run @command{autoconf}. This
9805 variable should be seldom used, because @command{automake} already tracks
9806 @code{m4_include}d files. However it can be useful when playing
9807 tricky games with @code{m4_esyscmd} or similar non-recommendable
9808 macros with side effects.
9810 @code{CONFIG_STATUS_DEPENDENCIES} adds dependencies to the
9811 @file{config.status} rule, whose effect is to run @file{configure}.
9812 This variable should therefore carry any non-standard source that may
9813 be read as a side effect of running @command{configure}, like @file{version.sh}
9814 in the example above.
9816 Speaking of @file{version.sh} scripts, we recommend against them
9817 today. They are mainly used when the version of a package is updated
9818 automatically by a script (e.g., in daily builds). Here is what some
9819 old-style @file{configure.ac}s may look like:
9823 . $srcdir/version.sh
9824 AM_INIT_AUTOMAKE([name], $VERSION_NUMBER)
9829 Here, @file{version.sh} is a shell fragment that sets
9830 @code{VERSION_NUMBER}. The problem with this example is that
9831 @command{automake} cannot track dependencies (listing @file{version.sh}
9832 in @command{CONFIG_STATUS_DEPENDENCIES}, and distributing this file is up
9833 to the user), and that it uses the obsolete form of @code{AC_INIT} and
9834 @code{AM_INIT_AUTOMAKE}. Upgrading to the new syntax is not
9835 straightforward, because shell variables are not allowed in
9836 @code{AC_INIT}'s arguments. We recommend that @file{version.sh} be
9837 replaced by an M4 file that is included by @file{configure.ac}:
9840 m4_include([version.m4])
9841 AC_INIT([name], VERSION_NUMBER)
9847 Here @file{version.m4} could contain something like
9848 @samp{m4_define([VERSION_NUMBER], [1.2])}. The advantage of this
9849 second form is that @command{automake} will take care of the
9850 dependencies when defining the rebuild rule, and will also distribute
9851 the file automatically. An inconvenience is that @command{autoconf}
9852 will now be rerun each time the version number is bumped, when only
9853 @file{configure} had to be rerun in the previous setup.
9857 @chapter Changing Automake's Behavior
9860 * Options generalities:: Semantics of Automake option
9861 * List of Automake options:: A comprehensive list of Automake options
9864 @node Options generalities
9865 @section Options generalities
9867 Various features of Automake can be controlled by options. Except where
9868 noted otherwise, options can be specified in one of several ways. Most
9869 options can be applied on a per-@file{Makefile} basis when listed in a
9870 special @file{Makefile} variable named @code{AUTOMAKE_OPTIONS}. Some
9871 of these options only make sense when specified in the toplevel
9872 @file{Makefile.am} file. Options are applied globally to all processed
9873 @file{Makefile} files when listed in the first argument of
9874 @code{AM_INIT_AUTOMAKE} in @file{configure.ac}, and some options which
9875 require changes to the @command{configure} script can only be specified
9876 there. These are annotated below.
9878 As a general rule, options specified in @code{AUTOMAKE_OPTIONS} take
9879 precedence over those specified in @code{AM_INIT_AUTOMAKE}, which in
9880 turn take precedence over those specified on the command line.
9882 Also, some care must be taken about the interactions among strictness
9883 level and warning categories. As a general rule, strictness-implied
9884 warnings are overridden by those specified by explicit options. For
9885 example, even if @samp{portability} warnings are disabled by default
9886 in @option{foreign} strictness, an usage like this will end up enabling
9890 AUTOMAKE_OPTIONS = -Wportability foreign
9893 However, a strictness level specified in a higher-priority context
9894 will override all the explicit warnings specified in a lower-priority
9895 context. For example, if @file{configure.ac} contains:
9898 AM_INIT_AUTOMAKE([-Wportability])
9902 and @file{Makefile.am} contains:
9905 AUTOMAKE_OPTIONS = foreign
9909 then @samp{portability} warnings will be @emph{disabled} in
9912 @node List of Automake options
9913 @section List of Automake options
9915 @vindex AUTOMAKE_OPTIONS
9918 @item @option{gnits}
9920 @itemx @option{foreign}
9921 @cindex Option, @option{gnits}
9922 @cindex Option, @option{gnu}
9923 @cindex Option, @option{foreign}
9928 Set the strictness as appropriate. The @option{gnits} option also
9929 implies options @option{readme-alpha} and @option{check-news}.
9931 @item @option{check-news}
9932 @cindex Option, @option{check-news}
9934 Cause @samp{make dist} to fail unless the current version number appears
9935 in the first few lines of the @file{NEWS} file.
9937 @item @option{color-tests}
9938 @cindex Option, @option{color-tests}
9939 @opindex color-tests
9940 Cause output of the serial and parallel test harnesses (see @ref{Simple
9941 Tests}) and of properly-written custom test drivers (@pxref{Custom Test
9942 Drivers}) to be colorized on capable terminals.
9944 @item @option{dejagnu}
9945 @cindex Option, @option{dejagnu}
9947 Cause @command{dejagnu}-specific rules to be generated. @xref{DejaGnu Tests}.
9949 @item @option{dist-bzip2}
9950 @cindex Option, @option{dist-bzip2}
9952 Hook @code{dist-bzip2} to @code{dist}.
9955 @item @option{dist-lzip}
9956 @cindex Option, @option{dist-lzip}
9958 Hook @code{dist-lzip} to @code{dist}.
9961 @item @option{dist-shar}
9962 @cindex Option, @option{dist-shar}
9964 Hook @code{dist-shar} to @code{dist}.
9967 @item @option{dist-zip}
9968 @cindex Option, @option{dist-zip}
9970 Hook @code{dist-zip} to @code{dist}.
9973 @item @option{dist-tarZ}
9974 @cindex Option, @option{dist-tarZ}
9976 Hook @code{dist-tarZ} to @code{dist}.
9979 @item @option{filename-length-max=99}
9980 @cindex Option, @option{filename-length-max=99}
9981 @opindex filename-length-max=99
9982 Abort if file names longer than 99 characters are found during
9983 @samp{make dist}. Such long file names are generally considered not to
9984 be portable in tarballs. See the @option{tar-v7} and @option{tar-ustar}
9985 options below. This option should be used in the top-level
9986 @file{Makefile.am} or as an argument of @code{AM_INIT_AUTOMAKE} in
9987 @file{configure.ac}, it will be ignored otherwise. It will also be
9988 ignored in sub-packages of nested packages (@pxref{Subpackages}).
9990 @item @option{no-define}
9991 @cindex Option, @option{no-define}
9993 This option is meaningful only when passed as an argument to
9994 @code{AM_INIT_AUTOMAKE}. It will prevent the @code{PACKAGE} and
9995 @code{VERSION} variables from being @code{AC_DEFINE}d.
9997 @item @option{no-dependencies}
9998 @cindex Option, @option{no-dependencies}
9999 @opindex no-dependencies
10000 This is similar to using @option{--ignore-deps} on the command line,
10001 but is useful for those situations where you don't have the necessary
10002 bits to make automatic dependency tracking work
10003 (@pxref{Dependencies}). In this case the effect is to effectively
10004 disable automatic dependency tracking.
10006 @item @option{no-dist}
10007 @cindex Option, @option{no-dist}
10009 Don't emit any code related to @code{dist} target. This is useful
10010 when a package has its own method for making distributions.
10012 @item @option{no-dist-gzip}
10013 @cindex Option, @option{no-dist-gzip}
10014 @opindex no-dist-gzip
10015 Do not hook @code{dist-gzip} to @code{dist}.
10016 @trindex no-dist-gzip
10018 @item @option{no-exeext}
10019 @cindex Option, @option{no-exeext}
10021 If your @file{Makefile.am} defines a rule for target @code{foo}, it
10022 will override a rule for a target named @samp{foo$(EXEEXT)}. This is
10023 necessary when @code{EXEEXT} is found to be empty. However, by
10024 default @command{automake} will generate an error for this use. The
10025 @option{no-exeext} option will disable this error. This is intended for
10026 use only where it is known in advance that the package will not be
10027 ported to Windows, or any other operating system using extensions on
10030 @item @option{no-installinfo}
10031 @cindex Option, @option{no-installinfo}
10032 @opindex no-installinfo
10033 The generated @file{Makefile.in} will not cause info pages to be built
10034 or installed by default. However, @code{info} and @code{install-info}
10035 targets will still be available. This option is disallowed at
10036 @option{gnu} strictness and above.
10038 @trindex install-info
10040 @item @option{no-installman}
10041 @cindex Option, @option{no-installman}
10042 @opindex no-installman
10043 The generated @file{Makefile.in} will not cause man pages to be
10044 installed by default. However, an @code{install-man} target will still
10045 be available for optional installation. This option is disallowed at
10046 @option{gnu} strictness and above.
10047 @trindex install-man
10049 @item @option{nostdinc}
10050 @cindex Option, @option{nostdinc}
10052 This option can be used to disable the standard @option{-I} options that
10053 are ordinarily automatically provided by Automake.
10055 @item @option{no-texinfo.tex}
10056 @cindex Option, @option{no-texinfo.tex}
10057 @opindex no-texinfo.tex
10058 Don't require @file{texinfo.tex}, even if there are texinfo files in
10061 @item @option{parallel-tests}
10062 @cindex Option, @option{parallel-tests}
10063 @opindex parallel-tests
10064 Enable test suite harness for @code{TESTS} that can run tests in parallel
10065 (@pxref{Parallel Test Harness}, for more information).
10067 @item @option{serial-tests}
10068 @cindex Option, @option{serial-tests}
10069 @opindex serial-tests
10070 Enable the older serial test suite harness for @code{TESTS} (@pxref{Serial
10071 Test Harness}, for more information). This is still the default for the
10074 @item @option{readme-alpha}
10075 @cindex Option, @option{readme-alpha}
10076 @opindex readme-alpha
10077 If this release is an alpha release, and the file @file{README-alpha}
10078 exists, then it will be added to the distribution. If this option is
10079 given, version numbers are expected to follow one of two forms. The
10080 first form is @samp{@var{major}.@var{minor}.@var{alpha}}, where each
10081 element is a number; the final period and number should be left off for
10082 non-alpha releases. The second form is
10083 @samp{@var{major}.@var{minor}@var{alpha}}, where @var{alpha} is a
10084 letter; it should be omitted for non-alpha releases.
10086 @item @option{std-options}
10087 @cindex Options, @option{std-options}
10088 @cindex @samp{make installcheck}, testing @option{--help} and @option{--version}
10089 @cindex @option{--help} check
10090 @cindex @option{--version} check
10091 @opindex std-options
10093 Make the @code{installcheck} rule check that installed scripts and
10094 programs support the @option{--help} and @option{--version} options.
10095 This also provides a basic check that the program's
10096 run-time dependencies are satisfied after installation.
10098 @vindex AM_INSTALLCHECK_STD_OPTIONS_EXEMPT
10099 In a few situations, programs (or scripts) have to be exempted from this
10100 test. For instance, @command{false} (from GNU coreutils) is never
10101 successful, even for @option{--help} or @option{--version}. You can list
10102 such programs in the variable @code{AM_INSTALLCHECK_STD_OPTIONS_EXEMPT}.
10103 Programs (not scripts) listed in this variable should be suffixed by
10104 @samp{$(EXEEXT)} for the sake of Windows or OS/2. For instance, suppose we
10105 build @file{false} as a program but @file{true.sh} as a script, and that
10106 neither of them support @option{--help} or @option{--version}:
10109 AUTOMAKE_OPTIONS = std-options
10110 bin_PROGRAMS = false ...
10111 bin_SCRIPTS = true.sh ...
10112 AM_INSTALLCHECK_STD_OPTIONS_EXEMPT = false$(EXEEXT) true.sh
10115 @item @option{subdir-objects}
10116 @cindex Options, @option{subdir-objects}
10117 @opindex subdir-objects
10118 If this option is specified, then objects are placed into the
10119 subdirectory of the build directory corresponding to the subdirectory of
10120 the source file. For instance, if the source file is
10121 @file{subdir/file.cxx}, then the output file would be
10122 @file{subdir/file.o}.
10124 In order to use this option with C sources, you should add
10125 @code{AM_PROG_CC_C_O} to @file{configure.ac}.
10127 @anchor{tar-formats}
10128 @item @option{tar-v7}
10129 @itemx @option{tar-ustar}
10130 @itemx @option{tar-pax}
10131 @cindex Option, @option{tar-v7}
10132 @cindex Option, @option{tar-ustar}
10133 @cindex Option, @option{tar-pax}
10134 @cindex @command{tar} formats
10135 @cindex v7 @command{tar} format
10136 @cindex ustar format
10142 These three mutually exclusive options select the tar format to use
10143 when generating tarballs with @samp{make dist}. (The tar file created
10144 is then compressed according to the set of @option{no-dist-gzip},
10145 @option{dist-bzip2}, @option{dist-lzip}, @option{dist-xz} and
10146 @option{dist-tarZ} options in use.)
10148 These options must be passed as arguments to @code{AM_INIT_AUTOMAKE}
10149 (@pxref{Macros}) because they can require additional configure checks.
10150 Automake will complain if it sees such options in an
10151 @code{AUTOMAKE_OPTIONS} variable.
10153 @option{tar-v7} selects the old V7 tar format. This is the historical
10154 default. This antiquated format is understood by all tar
10155 implementations and supports file names with up to 99 characters. When
10156 given longer file names some tar implementations will diagnose the
10157 problem while other will generate broken tarballs or use non-portable
10158 extensions. Furthermore, the V7 format cannot store empty
10159 directories. When using this format, consider using the
10160 @option{filename-length-max=99} option to catch file names too long.
10162 @option{tar-ustar} selects the ustar format defined by POSIX
10163 1003.1-1988. This format is believed to be old enough to be portable.
10164 It fully supports empty directories. It can store file names with up
10165 to 256 characters, provided that the file name can be split at
10166 directory separator in two parts, first of them being at most 155
10167 bytes long. So, in most cases the maximum file name length will be
10168 shorter than 256 characters. However you may run against broken tar
10169 implementations that incorrectly handle file names longer than 99
10170 characters (please report them to @email{@value{PACKAGE_BUGREPORT}} so we
10171 can document this accurately).
10173 @option{tar-pax} selects the new pax interchange format defined by POSIX
10174 1003.1-2001. It does not limit the length of file names. However,
10175 this format is very young and should probably be restricted to
10176 packages that target only very modern platforms. There are moves to
10177 change the pax format in an upward-compatible way, so this option may
10178 refer to a more recent version in the future.
10180 @xref{Formats, , Controlling the Archive Format, tar, GNU Tar}, for
10181 further discussion about tar formats.
10183 @command{configure} knows several ways to construct these formats. It
10184 will not abort if it cannot find a tool up to the task (so that the
10185 package can still be built), but @samp{make dist} will fail.
10187 @item @var{version}
10188 @cindex Option, @var{version}
10189 A version number (e.g., @samp{0.30}) can be specified. If Automake is not
10190 newer than the version specified, creation of the @file{Makefile.in}
10191 will be suppressed.
10193 @item @option{-W@var{category}} or @option{--warnings=@var{category}}
10194 @cindex Option, warnings
10195 @cindex Option, @option{-W@var{category}}
10196 @cindex Option, @option{--warnings=@var{category}}
10197 These options behave exactly like their command-line counterpart
10198 (@pxref{automake Invocation}). This allows you to enable or disable some
10199 warning categories on a per-file basis. You can also setup some warnings
10200 for your entire project; for instance, try @samp{AM_INIT_AUTOMAKE([-Wall])}
10201 in your @file{configure.ac}.
10205 Unrecognized options are diagnosed by @command{automake}.
10207 If you want an option to apply to all the files in the tree, you can use
10208 the @code{AM_INIT_AUTOMAKE} macro in @file{configure.ac}.
10212 @node Miscellaneous
10213 @chapter Miscellaneous Rules
10215 There are a few rules and variables that didn't fit anywhere else.
10218 * Tags:: Interfacing to cscope, etags and mkid
10219 * Suffixes:: Handling new file extensions
10224 @section Interfacing to @command{etags}
10226 @cindex @file{TAGS} support
10228 Automake will generate rules to generate @file{TAGS} files for use with
10229 GNU Emacs under some circumstances.
10232 If any C, C++ or Fortran 77 source code or headers are present, then
10233 @code{tags} and @code{TAGS} rules will be generated for the directory.
10234 All files listed using the @code{_SOURCES}, @code{_HEADERS}, and
10235 @code{_LISP} primaries will be used to generate tags. Note that
10236 generated source files that are not distributed must be declared in
10237 variables like @code{nodist_noinst_HEADERS} or
10238 @code{nodist_@var{prog}_SOURCES} or they will be ignored.
10240 A @code{tags} rule will be output at the topmost directory of a
10241 multi-directory package. When run from this topmost directory,
10242 @samp{make tags} will generate a @file{TAGS} file that includes by
10243 reference all @file{TAGS} files from subdirectories.
10245 The @code{tags} rule will also be generated if the variable
10246 @code{ETAGS_ARGS} is defined. This variable is intended for use in
10247 directories that contain taggable source that @command{etags} does
10248 not understand. The user can use the @code{ETAGSFLAGS} to pass
10249 additional flags to @command{etags}; @code{AM_ETAGSFLAGS} is also
10250 available for use in @file{Makefile.am}.
10253 @vindex AM_ETAGSFLAGS
10255 Here is how Automake generates tags for its source, and for nodes in its
10259 ETAGS_ARGS = automake.in --lang=none \
10260 --regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi
10263 If you add file names to @code{ETAGS_ARGS}, you will probably also
10264 want to define @code{TAGS_DEPENDENCIES}. The contents of this variable
10265 are added directly to the dependencies for the @code{tags} rule.
10266 @vindex TAGS_DEPENDENCIES
10268 Automake also generates a @code{ctags} rule that can be used to
10269 build @command{vi}-style @file{tags} files. The variable @code{CTAGS}
10270 is the name of the program to invoke (by default @command{ctags});
10271 @code{CTAGSFLAGS} can be used by the user to pass additional flags,
10272 and @code{AM_CTAGSFLAGS} can be used by the @file{Makefile.am}.
10275 Automake will also generate an @code{ID} rule that will run
10276 @command{mkid} on the source. This is only supported on a
10277 directory-by-directory basis.
10279 Similarly, the @code{cscope} rule will create a list of all the source
10280 files in the tree and run @command{cscope} to build an inverted index
10281 database. The variable @code{CSCOPE} is the name of the program to invoke
10282 (by default @command{cscope}); @code{CSCOPEFLAGS} and
10283 @code{CSCOPE_ARGS} can be used by the user to pass additional flags and
10284 file names respectively, while @code{AM_CSCOPEFLAGS} can be used by the
10285 @file{Makefile.am}. Note that, currently, the Automake-provided
10286 @code{cscope} support, when used in a VPATH build, might not work well
10287 with non-GNU make implementations (especially with make implementations
10288 performing @ref{Automatic Rule Rewriting, , VPATH rewrites, autoconf,
10289 The Autoconf Manual}).
10291 Finally, Automake also emits rules to support the
10292 @uref{http://www.gnu.org/software/global/, GNU Global Tags program}.
10293 The @code{GTAGS} rule runs Global Tags and puts the
10294 result in the top build directory. The variable @code{GTAGS_ARGS}
10295 holds arguments that are passed to @command{gtags}.
10300 @section Handling new file extensions
10302 @cindex Adding new @code{SUFFIXES}
10303 @cindex @code{SUFFIXES}, adding
10306 It is sometimes useful to introduce a new implicit rule to handle a file
10307 type that Automake does not know about.
10309 For instance, suppose you had a compiler that could compile @file{.foo}
10310 files to @file{.o} files. You would simply define a suffix rule for
10318 Then you could directly use a @file{.foo} file in a @code{_SOURCES}
10319 variable and expect the correct results:
10322 bin_PROGRAMS = doit
10323 doit_SOURCES = doit.foo
10326 This was the simpler and more common case. In other cases, you will
10327 have to help Automake to figure out which extensions you are defining your
10328 suffix rule for. This usually happens when your extension does not
10329 start with a dot. Then, all you have to do is to put a list of new
10330 suffixes in the @code{SUFFIXES} variable @strong{before} you define your
10333 For instance, the following definition prevents Automake from misinterpreting
10334 the @samp{.idlC.cpp:} rule as an attempt to transform @file{.idlC} files into
10337 @c Keep in sync with suffix7.sh
10339 SUFFIXES = .idl C.cpp
10344 As you may have noted, the @code{SUFFIXES} variable behaves like the
10345 @code{.SUFFIXES} special target of @command{make}. You should not touch
10346 @code{.SUFFIXES} yourself, but use @code{SUFFIXES} instead and let
10347 Automake generate the suffix list for @code{.SUFFIXES}. Any given
10348 @code{SUFFIXES} go at the start of the generated suffixes list, followed
10349 by Automake generated suffixes not already in the list.
10355 @cindex Including @file{Makefile} fragment
10356 @cindex @file{Makefile} fragment, including
10358 Automake supports an @code{include} directive that can be used to
10359 include other @file{Makefile} fragments when @command{automake} is run.
10360 Note that these fragments are read and interpreted by @command{automake},
10361 not by @command{make}. As with conditionals, @command{make} has no idea that
10362 @code{include} is in use.
10364 There are two forms of @code{include}:
10367 @item include $(srcdir)/file
10368 Include a fragment that is found relative to the current source
10371 @item include $(top_srcdir)/file
10372 Include a fragment that is found relative to the top source directory.
10375 Note that if a fragment is included inside a conditional, then the
10376 condition applies to the entire contents of that fragment.
10378 Makefile fragments included this way are always distributed because
10379 they are needed to rebuild @file{Makefile.in}.
10382 @chapter Conditionals
10384 @cindex Conditionals
10386 Automake supports a simple type of conditionals.
10388 These conditionals are not the same as conditionals in
10389 GNU Make. Automake conditionals are checked at configure time by the
10390 @file{configure} script, and affect the translation from
10391 @file{Makefile.in} to @file{Makefile}. They are based on options passed
10392 to @file{configure} and on results that @file{configure} has discovered
10393 about the host system. GNU Make conditionals are checked at @command{make}
10394 time, and are based on variables passed to the make program or defined
10395 in the @file{Makefile}.
10397 Automake conditionals will work with any make program.
10400 * Usage of Conditionals:: Declaring conditional content
10401 * Limits of Conditionals:: Enclosing complete statements
10404 @node Usage of Conditionals
10405 @section Usage of Conditionals
10407 @acindex AM_CONDITIONAL
10408 Before using a conditional, you must define it by using
10409 @code{AM_CONDITIONAL} in the @file{configure.ac} file (@pxref{Macros}).
10411 @defmac AM_CONDITIONAL (@var{conditional}, @var{condition})
10412 The conditional name, @var{conditional}, should be a simple string
10413 starting with a letter and containing only letters, digits, and
10414 underscores. It must be different from @samp{TRUE} and @samp{FALSE}
10415 that are reserved by Automake.
10417 The shell @var{condition} (suitable for use in a shell @code{if}
10418 statement) is evaluated when @command{configure} is run. Note that you
10419 must arrange for @emph{every} @code{AM_CONDITIONAL} to be invoked every
10420 time @command{configure} is run. If @code{AM_CONDITIONAL} is run
10421 conditionally (e.g., in a shell @code{if} statement), then the result
10422 will confuse @command{automake}.
10425 @cindex @option{--enable-debug}, example
10426 @cindex Example conditional @option{--enable-debug}
10427 @cindex Conditional example, @option{--enable-debug}
10429 Conditionals typically depend upon options that the user provides to
10430 the @command{configure} script. Here is an example of how to write a
10431 conditional that is true if the user uses the @option{--enable-debug}
10435 AC_ARG_ENABLE([debug],
10436 [ --enable-debug Turn on debugging],
10437 [case "$@{enableval@}" in
10440 *) AC_MSG_ERROR([bad value $@{enableval@} for --enable-debug]) ;;
10441 esac],[debug=false])
10442 AM_CONDITIONAL([DEBUG], [test x$debug = xtrue])
10445 Here is an example of how to use that conditional in @file{Makefile.am}:
10457 noinst_PROGRAMS = $(DBG)
10460 This trivial example could also be handled using @code{EXTRA_PROGRAMS}
10461 (@pxref{Conditional Programs}).
10463 You may only test a single variable in an @code{if} statement, possibly
10464 negated using @samp{!}. The @code{else} statement may be omitted.
10465 Conditionals may be nested to any depth. You may specify an argument to
10466 @code{else} in which case it must be the negation of the condition used
10467 for the current @code{if}. Similarly you may specify the condition
10468 that is closed on the @code{endif} line:
10479 Unbalanced conditions are errors. The @code{if}, @code{else}, and
10480 @code{endif} statements should not be indented, i.e., start on column
10483 The @code{else} branch of the above two examples could be omitted,
10484 since assigning the empty string to an otherwise undefined variable
10485 makes no difference.
10487 @acindex AM_COND_IF
10488 In order to allow access to the condition registered by
10489 @code{AM_CONDITIONAL} inside @file{configure.ac}, and to allow
10490 conditional @code{AC_CONFIG_FILES}, @code{AM_COND_IF} may be used:
10492 @defmac AM_COND_IF (@var{conditional}, @ovar{if-true}, @ovar{if-false})
10493 If @var{conditional} is fulfilled, execute @var{if-true}, otherwise
10494 execute @var{if-false}. If either branch contains @code{AC_CONFIG_FILES},
10495 it will cause @command{automake} to output the rules for the respective
10496 files only for the given condition.
10499 @code{AM_COND_IF} macros may be nested when m4 quotation is used
10500 properly (@pxref{M4 Quotation, ,, autoconf, The Autoconf Manual}).
10502 @cindex Example conditional @code{AC_CONFIG_FILES}
10503 @cindex @code{AC_CONFIG_FILES}, conditional
10505 Here is an example of how to define a conditional config file:
10508 AM_CONDITIONAL([SHELL_WRAPPER], [test "x$with_wrapper" = xtrue])
10509 AM_COND_IF([SHELL_WRAPPER],
10510 [AC_CONFIG_FILES([wrapper:wrapper.in])])
10513 @node Limits of Conditionals
10514 @section Limits of Conditionals
10516 Conditionals should enclose complete statements like variables or
10517 rules definitions. Automake cannot deal with conditionals used inside
10518 a variable definition, for instance, and is not even able to diagnose
10519 this situation. The following example would not work:
10522 # This syntax is not understood by Automake
10531 However the intended definition of @code{AM_CPPFLAGS} can be achieved
10536 DEBUGFLAGS = -DDEBUG
10538 AM_CPPFLAGS = -DFEATURE_A $(DEBUGFLAGS) -DFEATURE_B
10545 AM_CPPFLAGS = -DFEATURE_A
10547 AM_CPPFLAGS += -DDEBUG
10549 AM_CPPFLAGS += -DFEATURE_B
10552 More details and examples of conditionals are described alongside
10553 various Automake features in this manual (@pxref{Conditional
10554 Subdirectories}, @pxref{Conditional Sources}, @pxref{Conditional
10555 Programs}, @pxref{Conditional Libtool Libraries}, @pxref{Conditional
10558 @node Silencing Make
10559 @chapter Silencing @command{make}
10561 @cindex Silent @command{make}
10562 @cindex Silencing @command{make}
10563 @cindex Silent rules
10564 @cindex Silent @command{make} rules
10567 * Make verbosity:: Make is verbose by default
10568 * Tricks For Silencing Make:: Standard and generic ways to silence make
10569 * Automake Silent Rules:: How Automake can help in silencing make
10572 @node Make verbosity
10573 @section Make is verbose by default
10575 Normally, when executing the set of rules associated with a target,
10576 @command{make} prints each rule before it is executed. This behaviour,
10577 while having been in place for a long time, and being even mandated by
10578 the POSIX standard, starkly violates the ``silence is golden'' UNIX
10579 principle@footnote{See also
10580 @uref{http://catb.org/~esr/writings/taoup/html/ch11s09.html}.}:
10583 When a program has nothing interesting or surprising to say, it should
10584 say nothing. Well-behaved Unix programs do their jobs unobtrusively,
10585 with a minimum of fuss and bother. Silence is golden.
10588 In fact, while such verbosity of @command{make} can theoretically be
10589 useful to track bugs and understand reasons of failures right away, it
10590 can also hide warning and error messages from @command{make}-invoked
10591 tools, drowning them in a flood of uninteresting and seldom useful
10592 messages, and thus allowing them to go easily undetected.
10594 This problem can be very annoying, especially for developers, who usually
10595 know quite well what's going on behind the scenes, and for whom the
10596 verbose output from @command{make} ends up being mostly noise that hampers
10597 the easy detection of potentially important warning messages.
10599 @node Tricks For Silencing Make
10600 @section Standard and generic ways to silence make
10602 Here we describe some common idioms/tricks to obtain a quieter make
10603 output, with their relative advantages and drawbacks. In the next
10604 section (@ref{Automake Silent Rules}) we'll see how Automake can help
10605 in this respect, providing more elaborate and flexible idioms.
10609 @item @command{make -s}
10611 This simply causes @command{make} not to print @emph{any} rule before
10614 The @option{-s} flag is mandated by POSIX, universally supported, and
10615 its purpose and function are easy to understand.
10617 But it also has its serious limitations too. First of all, it embodies
10618 an ``all or nothing'' strategy, i.e., either everything is silenced, or
10619 nothing is; this lack of granularity can sometimes be a fatal flaw.
10620 Moreover, when the @option{-s} flag is used, the @command{make} output
10621 might turn out to be too much terse; in case of errors, the user won't
10622 be able to easily see what rule or command have caused them, or even,
10623 in case of tools with poor error reporting, what the errors were!
10625 @item @command{make >/dev/null || make}
10627 Apparently, this perfectly obeys the ``silence is golden'' rule: warnings
10628 from stderr are passed through, output reporting is done only in case of
10629 error, and in that case it should provide a verbose-enough report to allow
10630 an easy determination of the error location and causes.
10632 However, calling @command{make} two times in a row might hide errors
10633 (especially intermittent ones), or subtly change the expected semantic
10634 of the @command{make} calls --- things these which can clearly make
10635 debugging and error assessment very difficult.
10637 @item @command{make --no-print-directory}
10639 This is GNU @command{make} specific. When called with the
10640 @option{--no-print-directory} option, GNU @command{make} will disable
10641 printing of the working directory by invoked sub-@command{make}s (the
10642 well-known ``@i{Entering/Leaving directory ...}'' messages). This helps
10643 to decrease the verbosity of the output, but experience has shown that
10644 it can also often render debugging considerably harder in projects using
10645 deeply-nested @command{make} recursion.
10647 As an aside, notice that the @option{--no-print-directory} option is
10648 automatically activated if the @option{-s} flag is used.
10650 @c TODO: Other tricks?
10651 @c TODO: Maybe speak about the @code{.SILENT} target?
10652 @c TODO: - Pros: More granularity on what to silence.
10653 @c TODO: - Cons: No easy way to temporarily override.
10657 @node Automake Silent Rules
10658 @section How Automake can help in silencing make
10660 The tricks and idioms for silencing @command{make} described in the
10661 previous section can be useful from time to time, but we've seen that
10662 they all have their serious drawbacks and limitations. That's why
10663 automake provides support for a more advanced and flexible way of
10664 obtaining quieter output from @command{make} (for most rules at least).
10666 @c TODO: Maybe describe in brief the precedent set by the build system
10667 @c of the Linux Kernel, from which Automake took inspiration ... Links?
10669 To give the gist of what Automake can do in this respect, here is a simple
10670 comparison between a typical @command{make} output (where silent rules
10671 are disabled) and one with silent rules enabled:
10674 % @kbd{cat Makefile.am}
10676 foo_SOURCES = main.c func.c
10678 int main (void) @{ return func (); @} /* func used undeclared */
10680 int func (void) @{ int i; return i; @} /* i used uninitialized */
10682 @i{The make output is by default very verbose. This causes warnings
10683 from the compiler to be somewhat hidden, and not immediate to spot.}
10684 % @kbd{make CFLAGS=-Wall}
10685 gcc -DPACKAGE_NAME=\"foo\" -DPACKAGE_TARNAME=\"foo\" ...
10686 -DPACKAGE_STRING=\"foo\ 1.0\" -DPACKAGE_BUGREPORT=\"\" ...
10687 -DPACKAGE=\"foo\" -DVERSION=\"1.0\" -I. -Wall -MT main.o
10688 -MD -MP -MF .deps/main.Tpo -c -o main.o main.c
10689 main.c: In function ‘main’:
10690 main.c:3:3: warning: implicit declaration of function ‘func’
10691 mv -f .deps/main.Tpo .deps/main.Po
10692 gcc -DPACKAGE_NAME=\"foo\" -DPACKAGE_TARNAME=\"foo\" ...
10693 -DPACKAGE_STRING=\"foo\ 1.0\" -DPACKAGE_BUGREPORT=\"\" ...
10694 -DPACKAGE=\"foo\" -DVERSION=\"1.0\" -I. -Wall -MT func.o
10695 -MD -MP -MF .deps/func.Tpo -c -o func.o func.c
10696 func.c: In function ‘func’:
10697 func.c:4:3: warning: ‘i’ used uninitialized in this function
10698 mv -f .deps/func.Tpo .deps/func.Po
10699 gcc -Wall -o foo main.o func.o
10701 @i{Clean up, so that we we can rebuild everything from scratch.}
10703 test -z "foo" || rm -f foo
10706 @i{Silent rules enabled: the output is minimal but informative. In
10707 particular, the warnings from the compiler stick out very clearly.}
10708 % @kbd{make V=0 CFLAGS=-Wall}
10710 main.c: In function ‘main’:
10711 main.c:3:3: warning: implicit declaration of function ‘func’
10713 func.c: In function ‘func’:
10714 func.c:4:3: warning: ‘i’ used uninitialized in this function
10718 @cindex silent rules and libtool
10719 Also, in projects using @command{libtool}, the use of silent rules can
10720 automatically enable the @command{libtool}'s @option{--silent} option:
10723 % @kbd{cat Makefile.am}
10724 lib_LTLIBRARIES = libx.la
10726 % @kbd{make # Both make and libtool are verbose by default.}
10728 libtool: compile: gcc -DPACKAGE_NAME=\"foo\" ... -DLT_OBJDIR=\".libs/\"
10729 -I. -g -O2 -MT libx.lo -MD -MP -MF .deps/libx.Tpo -c libx.c -fPIC
10730 -DPIC -o .libs/libx.o
10731 mv -f .deps/libx.Tpo .deps/libx.Plo
10732 /bin/sh ./libtool --tag=CC --mode=link gcc -g -O2 -o libx.la -rpath
10733 /usr/local/lib libx.lo
10734 libtool: link: gcc -shared .libs/libx.o -Wl,-soname -Wl,libx.so.0
10735 -o .libs/libx.so.0.0.0
10736 libtool: link: cd .libs && rm -f libx.so && ln -s libx.so.0.0.0 libx.so
10744 For Automake-generated @file{Makefile}s, the user may influence the
10745 verbosity at @command{configure} run time as well as at @command{make}
10750 @opindex --enable-silent-rules
10751 @opindex --disable-silent-rules
10752 Passing @option{--enable-silent-rules} to @command{configure} will cause
10753 build rules to be less verbose; the option @option{--disable-silent-rules}
10754 will cause normal verbose output.
10757 At @command{make} run time, the default chosen at @command{configure}
10758 time may be overridden: @code{make V=1} will produce verbose output,
10759 @code{make V=0} less verbose output.
10762 @cindex default verbosity for silent rules
10763 Note that silent rules are @emph{disabled} by default; the user must
10764 enable them explicitly at either @command{configure} run time or at
10765 @command{make} run time. We think that this is a good policy, since
10766 it provides the casual user with enough information to prepare a good
10767 bug report in case anything breaks.
10769 Still, notwithstanding the rationales above, a developer who really
10770 wants to make silent rules enabled by default in his own package can
10771 do so by calling @code{AM_SILENT_RULES([yes])} in @file{configure.ac}.
10773 @c Keep in sync with silent-configsite.sh
10774 Users who prefer to have silent rules enabled by default can edit their
10775 @file{config.site} file to make the variable @code{enable_silent_rules}
10776 default to @samp{yes}. This should still allow disabling silent rules
10777 at @command{configure} time and at @command{make} time.
10779 @c FIXME: there's really a need to specify this explicitly?
10780 For portability to different @command{make} implementations, package authors
10781 are advised to not set the variable @code{V} inside the @file{Makefile.am}
10782 file, to allow the user to override the value for subdirectories as well.
10784 To work at its best, the current implementation of this feature normally
10785 uses nested variable expansion @samp{$(@var{var1}$(V))}, a @file{Makefile}
10786 feature that is not required by POSIX 2008 but is widely supported in
10787 practice. On the rare @command{make} implementations that do not support
10788 nested variable expansion, whether rules are silent is always determined at
10789 configure time, and cannot be overridden at make time. Future versions of
10790 POSIX are likely to require nested variable expansion, so this minor
10791 limitation should go away with time.
10793 @vindex @code{AM_V_GEN}
10794 @vindex @code{AM_V_at}
10795 @vindex @code{AM_DEFAULT_VERBOSITY}
10796 @vindex @code{AM_V}
10797 @vindex @code{AM_DEFAULT_V}
10798 To extend the silent mode to your own rules, you have two choices:
10802 You can use the predefined variable @code{AM_V_GEN} as a prefix to
10803 commands that should output a status line in silent mode, and
10804 @code{AM_V_at} as a prefix to commands that should not output anything
10805 in silent mode. When output is to be verbose, both of these variables
10806 will expand to the empty string.
10808 You can add your own variables, so strings of your own choice are shown.
10809 The following snippet shows how you would define your own equivalent of
10813 pkg_verbose = $(pkg_verbose_@@AM_V@@)
10814 pkg_verbose_ = $(pkg_verbose_@@AM_DEFAULT_V@@)
10815 pkg_verbose_0 = @@echo PKG-GEN $@@;
10818 $(pkg_verbose)cp $(srcdir)/foo.in $@@
10823 As a final note, observe that, even when silent rules are enabled,
10824 the @option{--no-print-directory} option is still required with GNU
10825 @command{make} if the ``@i{Entering/Leaving directory ...}'' messages
10826 are to be disabled.
10829 @chapter The effect of @option{--gnu} and @option{--gnits}
10831 @cindex @option{--gnu}, required files
10832 @cindex @option{--gnu}, complete description
10834 The @option{--gnu} option (or @option{gnu} in the
10835 @code{AUTOMAKE_OPTIONS} variable) causes @command{automake} to check
10840 The files @file{INSTALL}, @file{NEWS}, @file{README}, @file{AUTHORS},
10841 and @file{ChangeLog}, plus one of @file{COPYING.LIB}, @file{COPYING.LESSER}
10842 or @file{COPYING}, are required at the topmost directory of the package.
10844 If the @option{--add-missing} option is given, @command{automake} will
10845 add a generic version of the @file{INSTALL} file as well as the
10846 @file{COPYING} file containing the text of the current version of the
10847 GNU General Public License existing at the time of this Automake release
10848 (version 3 as this is written, @uref{http://www.gnu.org/@/copyleft/@/gpl.html}).
10849 However, an existing @file{COPYING} file will never be overwritten by
10850 @command{automake}.
10853 The options @option{no-installman} and @option{no-installinfo} are
10857 Note that this option will be extended in the future to do even more
10858 checking; it is advisable to be familiar with the precise requirements
10859 of the GNU standards. Also, @option{--gnu} can require certain
10860 non-standard GNU programs to exist for use by various maintainer-only
10861 rules; for instance, in the future @command{pathchk} might be required for
10864 @cindex @option{--gnits}, complete description
10866 The @option{--gnits} option does everything that @option{--gnu} does, and
10867 checks the following as well:
10871 @samp{make installcheck} will check to make sure that the @option{--help}
10872 and @option{--version} really print a usage message and a version string,
10873 respectively. This is the @option{std-options} option (@pxref{Options}).
10876 @samp{make dist} will check to make sure the @file{NEWS} file has been
10877 updated to the current version.
10880 @code{VERSION} is checked to make sure its format complies with Gnits
10882 @c FIXME xref when standards are finished
10885 @cindex @file{README-alpha}
10886 If @code{VERSION} indicates that this is an alpha release, and the file
10887 @file{README-alpha} appears in the topmost directory of a package, then
10888 it is included in the distribution. This is done in @option{--gnits}
10889 mode, and no other, because this mode is the only one where version
10890 number formats are constrained, and hence the only mode where Automake
10891 can automatically determine whether @file{README-alpha} should be
10895 The file @file{THANKS} is required.
10900 @chapter When Automake Isn't Enough
10902 In some situations, where Automake is not up to one task, one has to
10903 resort to handwritten rules or even handwritten @file{Makefile}s.
10906 * Extending:: Adding new rules or overriding existing ones.
10907 * Third-Party Makefiles:: Integrating Non-Automake @file{Makefile}s.
10911 @section Extending Automake Rules
10913 With some minor exceptions (for example @code{_PROGRAMS} variables,
10914 @code{TESTS}, or @code{XFAIL_TESTS}) being rewritten to append
10915 @samp{$(EXEEXT)}), the contents of a @file{Makefile.am} is copied to
10916 @file{Makefile.in} verbatim.
10918 @cindex copying semantics
10920 These copying semantics mean that many problems can be worked around
10921 by simply adding some @command{make} variables and rules to
10922 @file{Makefile.am}. Automake will ignore these additions.
10924 @cindex conflicting definitions
10925 @cindex rules, conflicting
10926 @cindex variables, conflicting
10927 @cindex definitions, conflicts
10929 Since a @file{Makefile.in} is built from data gathered from three
10930 different places (@file{Makefile.am}, @file{configure.ac}, and
10931 @command{automake} itself), it is possible to have conflicting
10932 definitions of rules or variables. When building @file{Makefile.in}
10933 the following priorities are respected by @command{automake} to ensure
10934 the user always has the last word:
10938 User defined variables in @file{Makefile.am} have priority over
10939 variables @code{AC_SUBST}ed from @file{configure.ac}, and
10940 @code{AC_SUBST}ed variables have priority over
10941 @command{automake}-defined variables.
10943 As far as rules are concerned, a user-defined rule overrides any
10944 @command{automake}-defined rule for the same target.
10947 @cindex overriding rules
10948 @cindex overriding semantics
10949 @cindex rules, overriding
10951 These overriding semantics make it possible to fine tune some default
10952 settings of Automake, or replace some of its rules. Overriding
10953 Automake rules is often inadvisable, particularly in the topmost
10954 directory of a package with subdirectories. The @option{-Woverride}
10955 option (@pxref{automake Invocation}) comes in handy to catch overridden
10958 Note that Automake does not make any distinction between rules with
10959 commands and rules that only specify dependencies. So it is not
10960 possible to append new dependencies to an @command{automake}-defined
10961 target without redefining the entire rule.
10963 @cindex @option{-local} targets
10964 @cindex local targets
10966 However, various useful targets have a @samp{-local} version you can
10967 specify in your @file{Makefile.am}. Automake will supplement the
10968 standard target with these user-supplied targets.
10973 @trindex info-local
10981 @trindex html-local
10983 @trindex check-local
10985 @trindex install-data
10986 @trindex install-data-local
10987 @trindex install-dvi
10988 @trindex install-dvi-local
10989 @trindex install-exec
10990 @trindex install-exec-local
10991 @trindex install-html
10992 @trindex install-html-local
10993 @trindex install-info
10994 @trindex install-info-local
10995 @trindex install-pdf
10996 @trindex install-pdf-local
10997 @trindex install-ps
10998 @trindex install-ps-local
11000 @trindex uninstall-local
11001 @trindex mostlyclean
11002 @trindex mostlyclean-local
11004 @trindex clean-local
11006 @trindex distclean-local
11007 @trindex installdirs
11008 @trindex installdirs-local
11009 @trindex installcheck
11010 @trindex installcheck-local
11012 The targets that support a local version are @code{all}, @code{info},
11013 @code{dvi}, @code{ps}, @code{pdf}, @code{html}, @code{check},
11014 @code{install-data}, @code{install-dvi}, @code{install-exec},
11015 @code{install-html}, @code{install-info}, @code{install-pdf},
11016 @code{install-ps}, @code{uninstall}, @code{installdirs},
11017 @code{installcheck} and the various @code{clean} targets
11018 (@code{mostlyclean}, @code{clean}, @code{distclean}, and
11019 @code{maintainer-clean}).
11021 Note that there are no @code{uninstall-exec-local} or
11022 @code{uninstall-data-local} targets; just use @code{uninstall-local}.
11023 It doesn't make sense to uninstall just data or just executables.
11025 For instance, here is one way to erase a subdirectory during
11026 @samp{make clean} (@pxref{Clean}).
11033 You may be tempted to use @code{install-data-local} to install a file
11034 to some hard-coded location, but you should avoid this
11035 (@pxref{Hard-Coded Install Paths}).
11037 With the @code{-local} targets, there is no particular guarantee of
11038 execution order; typically, they are run early, but with parallel
11039 make, there is no way to be sure of that.
11041 @cindex @option{-hook} targets
11042 @cindex hook targets
11043 @trindex install-data-hook
11044 @trindex install-exec-hook
11045 @trindex uninstall-hook
11048 In contrast, some rules also have a way to run another rule, called a
11049 @dfn{hook}; hooks are always executed after the main rule's work is done.
11050 The hook is named after the principal target, with @samp{-hook} appended.
11051 The targets allowing hooks are @code{install-data},
11052 @code{install-exec}, @code{uninstall}, @code{dist}, and
11055 For instance, here is how to create a hard link to an installed program:
11059 ln $(DESTDIR)$(bindir)/program$(EXEEXT) \
11060 $(DESTDIR)$(bindir)/proglink$(EXEEXT)
11063 Although cheaper and more portable than symbolic links, hard links
11064 will not work everywhere (for instance, OS/2 does not have
11065 @command{ln}). Ideally you should fall back to @samp{cp -p} when
11066 @command{ln} does not work. An easy way, if symbolic links are
11067 acceptable to you, is to add @code{AC_PROG_LN_S} to
11068 @file{configure.ac} (@pxref{Particular Programs, , Particular Program
11069 Checks, autoconf, The Autoconf Manual}) and use @samp{$(LN_S)} in
11070 @file{Makefile.am}.
11072 @cindex versioned binaries, installing
11073 @cindex installing versioned binaries
11074 @cindex @code{LN_S} example
11075 For instance, here is how you could install a versioned copy of a
11076 program using @samp{$(LN_S)}:
11078 @c Keep in sync with insthook.sh
11081 cd $(DESTDIR)$(bindir) && \
11082 mv -f prog$(EXEEXT) prog-$(VERSION)$(EXEEXT) && \
11083 $(LN_S) prog-$(VERSION)$(EXEEXT) prog$(EXEEXT)
11086 Note that we rename the program so that a new version will erase the
11087 symbolic link, not the real binary. Also we @command{cd} into the
11088 destination directory in order to create relative links.
11090 When writing @code{install-exec-hook} or @code{install-data-hook},
11091 please bear in mind that the exec/data distinction is based on the
11092 installation directory, not on the primary used (@pxref{The Two Parts of
11094 @c Keep in sync with primary-prefix-couples-documented-valid.sh
11095 So a @code{foo_SCRIPTS} will be installed by
11096 @code{install-data}, and a @code{barexec_SCRIPTS} will be installed by
11097 @code{install-exec}. You should define your hooks consequently.
11099 @c FIXME should include discussion of variables you can use in these
11102 @node Third-Party Makefiles
11103 @section Third-Party @file{Makefile}s
11105 @cindex Third-party packages, interfacing with
11106 @cindex Interfacing with third-party packages
11108 In most projects all @file{Makefile}s are generated by Automake. In
11109 some cases, however, projects need to embed subdirectories with
11110 handwritten @file{Makefile}s. For instance, one subdirectory could be
11111 a third-party project with its own build system, not using Automake.
11113 It is possible to list arbitrary directories in @code{SUBDIRS} or
11114 @code{DIST_SUBDIRS} provided each of these directories has a
11115 @file{Makefile} that recognizes all the following recursive targets.
11117 @cindex recursive targets and third-party @file{Makefile}s
11118 When a user runs one of these targets, that target is run recursively
11119 in all subdirectories. This is why it is important that even
11120 third-party @file{Makefile}s support them.
11124 Compile the entire package. This is the default target in
11125 Automake-generated @file{Makefile}s, but it does not need to be the
11126 default in third-party @file{Makefile}s.
11131 @vindex top_distdir
11132 Copy files to distribute into @samp{$(distdir)}, before a tarball is
11133 constructed. Of course this target is not required if the
11134 @option{no-dist} option (@pxref{Options}) is used.
11136 The variables @samp{$(top_distdir)} and @samp{$(distdir)}
11137 (@pxref{The dist Hook}) will be passed from the outer package to the subpackage
11138 when the @code{distdir} target is invoked. These two variables have
11139 been adjusted for the directory that is being recursed into, so they
11143 @itemx install-data
11144 @itemx install-exec
11146 Install or uninstall files (@pxref{Install}).
11149 @itemx install-html
11150 @itemx install-info
11153 Install only some specific documentation format (@pxref{Texinfo}).
11156 Create install directories, but do not install any files.
11159 @itemx installcheck
11160 Check the package (@pxref{Tests}).
11165 @itemx maintainer-clean
11166 Cleaning rules (@pxref{Clean}).
11173 Build the documentation in various formats (@pxref{Texinfo}).
11177 Build @file{TAGS} and @file{CTAGS} (@pxref{Tags}).
11180 If you have ever used Gettext in a project, this is a good example of
11181 how third-party @file{Makefile}s can be used with Automake. The
11182 @file{Makefile}s @command{gettextize} puts in the @file{po/} and
11183 @file{intl/} directories are handwritten @file{Makefile}s that
11184 implement all these targets. That way they can be added to
11185 @code{SUBDIRS} in Automake packages.
11187 Directories that are only listed in @code{DIST_SUBDIRS} but not in
11188 @code{SUBDIRS} need only the @code{distclean},
11189 @code{maintainer-clean}, and @code{distdir} rules (@pxref{Conditional
11192 Usually, many of these rules are irrelevant to the third-party
11193 subproject, but they are required for the whole package to work. It's
11194 OK to have a rule that does nothing, so if you are integrating a
11195 third-party project with no documentation or tag support, you could
11196 simply augment its @file{Makefile} as follows:
11199 EMPTY_AUTOMAKE_TARGETS = dvi pdf ps info html tags ctags
11200 .PHONY: $(EMPTY_AUTOMAKE_TARGETS)
11201 $(EMPTY_AUTOMAKE_TARGETS):
11204 Another aspect of integrating third-party build systems is whether
11205 they support VPATH builds (@pxref{VPATH Builds}). Obviously if the
11206 subpackage does not support VPATH builds the whole package will not
11207 support VPATH builds. This in turns means that @samp{make distcheck}
11208 will not work, because it relies on VPATH builds. Some people can
11209 live without this (actually, many Automake users have never heard of
11210 @samp{make distcheck}). Other people may prefer to revamp the
11211 existing @file{Makefile}s to support VPATH@. Doing so does not
11212 necessarily require Automake, only Autoconf is needed (@pxref{Build
11213 Directories, , Build Directories, autoconf, The Autoconf Manual}).
11214 The necessary substitutions: @samp{@@srcdir@@}, @samp{@@top_srcdir@@},
11215 and @samp{@@top_builddir@@} are defined by @file{configure} when it
11216 processes a @file{Makefile} (@pxref{Preset Output Variables, , Preset
11217 Output Variables, autoconf, The Autoconf Manual}), they are not
11218 computed by the Makefile like the aforementioned @samp{$(distdir)} and
11219 @samp{$(top_distdir)} variables.
11221 It is sometimes inconvenient to modify a third-party @file{Makefile}
11222 to introduce the above required targets. For instance, one may want to
11223 keep the third-party sources untouched to ease upgrades to new
11226 @cindex @file{GNUmakefile} including @file{Makefile}
11227 Here are two other ideas. If GNU make is assumed, one possibility is
11228 to add to that subdirectory a @file{GNUmakefile} that defines the
11229 required targets and includes the third-party @file{Makefile}. For
11230 this to work in VPATH builds, @file{GNUmakefile} must lie in the build
11231 directory; the easiest way to do this is to write a
11232 @file{GNUmakefile.in} instead, and have it processed with
11233 @code{AC_CONFIG_FILES} from the outer package. For example if we
11234 assume @file{Makefile} defines all targets except the documentation
11235 targets, and that the @code{check} target is actually called
11236 @code{test}, we could write @file{GNUmakefile} (or
11237 @file{GNUmakefile.in}) like this:
11240 # First, include the real Makefile
11242 # Then, define the other targets needed by Automake Makefiles.
11243 .PHONY: dvi pdf ps info html check
11244 dvi pdf ps info html:
11248 @cindex Proxy @file{Makefile} for third-party packages
11249 A similar idea that does not use @code{include} is to write a proxy
11250 @file{Makefile} that dispatches rules to the real @file{Makefile},
11251 either with @samp{$(MAKE) -f Makefile.real $(AM_MAKEFLAGS) target} (if
11252 it's OK to rename the original @file{Makefile}) or with @samp{cd
11253 subdir && $(MAKE) $(AM_MAKEFLAGS) target} (if it's OK to store the
11254 subdirectory project one directory deeper). The good news is that
11255 this proxy @file{Makefile} can be generated with Automake. All we
11256 need are @option{-local} targets (@pxref{Extending}) that perform the
11257 dispatch. Of course the other Automake features are available, so you
11258 could decide to let Automake perform distribution or installation.
11259 Here is a possible @file{Makefile.am}:
11263 cd subdir && $(MAKE) $(AM_MAKEFLAGS) all
11265 cd subdir && $(MAKE) $(AM_MAKEFLAGS) test
11267 cd subdir && $(MAKE) $(AM_MAKEFLAGS) clean
11269 # Assuming the package knows how to install itself
11270 install-data-local:
11271 cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-data
11272 install-exec-local:
11273 cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-exec
11275 cd subdir && $(MAKE) $(AM_MAKEFLAGS) uninstall
11277 # Distribute files from here.
11278 EXTRA_DIST = subdir/Makefile subdir/program.c ...
11281 Pushing this idea to the extreme, it is also possible to ignore the
11282 subproject build system and build everything from this proxy
11283 @file{Makefile.am}. This might sound very sensible if you need VPATH
11284 builds but the subproject does not support them.
11287 @chapter Distributing @file{Makefile.in}s
11289 Automake places no restrictions on the distribution of the resulting
11290 @file{Makefile.in}s. We still encourage software authors to
11291 distribute their work under terms like those of the GPL, but doing so
11292 is not required to use Automake.
11294 Some of the files that can be automatically installed via the
11295 @option{--add-missing} switch do fall under the GPL@. However, these also
11296 have a special exception allowing you to distribute them with your
11297 package, regardless of the licensing you choose.
11300 @node API Versioning
11301 @chapter Automake API Versioning
11303 New Automake releases usually include bug fixes and new features.
11304 Unfortunately they may also introduce new bugs and incompatibilities.
11305 This makes four reasons why a package may require a particular Automake
11308 Things get worse when maintaining a large tree of packages, each one
11309 requiring a different version of Automake. In the past, this meant that
11310 any developer (and sometimes users) had to install several versions of
11311 Automake in different places, and switch @samp{$PATH} appropriately for
11314 Starting with version 1.6, Automake installs versioned binaries. This
11315 means you can install several versions of Automake in the same
11316 @samp{$prefix}, and can select an arbitrary Automake version by running
11317 @command{automake-1.6} or @command{automake-1.7} without juggling with
11318 @samp{$PATH}. Furthermore, @file{Makefile}'s generated by Automake 1.6
11319 will use @command{automake-1.6} explicitly in their rebuild rules.
11321 The number @samp{1.6} in @command{automake-1.6} is Automake's API version,
11322 not Automake's version. If a bug fix release is made, for instance
11323 Automake 1.6.1, the API version will remain 1.6. This means that a
11324 package that works with Automake 1.6 should also work with 1.6.1; after
11325 all, this is what people expect from bug fix releases.
11327 If your package relies on a feature or a bug fix introduced in
11328 a release, you can pass this version as an option to Automake to ensure
11329 older releases will not be used. For instance, use this in your
11330 @file{configure.ac}:
11333 AM_INIT_AUTOMAKE([1.6.1]) dnl Require Automake 1.6.1 or better.
11337 or, in a particular @file{Makefile.am}:
11340 AUTOMAKE_OPTIONS = 1.6.1 # Require Automake 1.6.1 or better.
11344 Automake will print an error message if its version is
11345 older than the requested version.
11348 @heading What is in the API
11350 Automake's programming interface is not easy to define. Basically it
11351 should include at least all @strong{documented} variables and targets
11352 that a @file{Makefile.am} author can use, any behavior associated with
11353 them (e.g., the places where @samp{-hook}'s are run), the command line
11354 interface of @command{automake} and @command{aclocal}, @dots{}
11356 @heading What is not in the API
11358 Every undocumented variable, target, or command line option, is not part
11359 of the API@. You should avoid using them, as they could change from one
11360 version to the other (even in bug fix releases, if this helps to fix a
11363 If it turns out you need to use such an undocumented feature, contact
11364 @email{automake@@gnu.org} and try to get it documented and exercised by
11368 @chapter Upgrading a Package to a Newer Automake Version
11370 Automake maintains three kind of files in a package.
11373 @item @file{aclocal.m4}
11374 @item @file{Makefile.in}s
11375 @item auxiliary tools like @file{install-sh} or @file{py-compile}
11378 @file{aclocal.m4} is generated by @command{aclocal} and contains some
11379 Automake-supplied M4 macros. Auxiliary tools are installed by
11380 @samp{automake --add-missing} when needed. @file{Makefile.in}s are
11381 built from @file{Makefile.am} by @command{automake}, and rely on the
11382 definitions of the M4 macros put in @file{aclocal.m4} as well as the
11383 behavior of the auxiliary tools installed.
11385 Because all these files are closely related, it is important to
11386 regenerate all of them when upgrading to a newer Automake release.
11387 The usual way to do that is
11390 aclocal # with any option needed (such a -I m4)
11392 automake --add-missing --force-missing
11396 or more conveniently:
11402 The use of @option{--force-missing} ensures that auxiliary tools will be
11403 overridden by new versions (@pxref{automake Invocation}).
11405 It is important to regenerate all these files each time Automake is
11406 upgraded, even between bug fixes releases. For instance, it is not
11407 unusual for a bug fix to involve changes to both the rules generated
11408 in @file{Makefile.in} and the supporting M4 macros copied to
11411 Presently @command{automake} is able to diagnose situations where
11412 @file{aclocal.m4} has been generated with another version of
11413 @command{aclocal}. However it never checks whether auxiliary scripts
11414 are up-to-date. In other words, @command{automake} will tell you when
11415 @command{aclocal} needs to be rerun, but it will never diagnose a
11416 missing @option{--force-missing}.
11418 Before upgrading to a new major release, it is a good idea to read the
11419 file @file{NEWS}. This file lists all changes between releases: new
11420 features, obsolete constructs, known incompatibilities, and
11424 @chapter Frequently Asked Questions about Automake
11426 This chapter covers some questions that often come up on the mailing
11430 * CVS:: CVS and generated files
11431 * maintainer-mode:: missing and AM_MAINTAINER_MODE
11432 * Wildcards:: Why doesn't Automake support wildcards?
11433 * Limitations on File Names:: Limitations on source and installed file names
11434 * Errors with distclean:: Files left in build directory after distclean
11435 * Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS
11436 * Renamed Objects:: Why are object files sometimes renamed?
11437 * Per-Object Flags:: How to simulate per-object flags?
11438 * Multiple Outputs:: Writing rules for tools with many output files
11439 * Hard-Coded Install Paths:: Installing to hard-coded locations
11440 * Debugging Make Rules:: Strategies when things don't work as expected
11441 * Reporting Bugs:: Feedback on bugs and feature requests
11445 @section CVS and generated files
11447 @subheading Background: distributed generated Files
11448 @cindex generated files, distributed
11449 @cindex rebuild rules
11451 Packages made with Autoconf and Automake ship with some generated
11452 files like @file{configure} or @file{Makefile.in}. These files were
11453 generated on the developer's host and are distributed so that
11454 end-users do not have to install the maintainer tools required to
11455 rebuild them. Other generated files like Lex scanners, Yacc parsers,
11456 or Info documentation, are usually distributed on similar grounds.
11458 Automake outputs rules in @file{Makefile}s to rebuild these files. For
11459 instance, @command{make} will run @command{autoconf} to rebuild
11460 @file{configure} whenever @file{configure.ac} is changed. This makes
11461 development safer by ensuring a @file{configure} is never out-of-date
11462 with respect to @file{configure.ac}.
11464 As generated files shipped in packages are up-to-date, and because
11465 @command{tar} preserves times-tamps, these rebuild rules are not
11466 triggered when a user unpacks and builds a package.
11468 @subheading Background: CVS and Timestamps
11469 @cindex timestamps and CVS
11470 @cindex CVS and timestamps
11472 Unless you use CVS keywords (in which case files must be updated at
11473 commit time), CVS preserves timestamp during @samp{cvs commit} and
11474 @samp{cvs import -d} operations.
11476 When you check out a file using @samp{cvs checkout} its timestamp is
11477 set to that of the revision that is being checked out.
11479 However, during @command{cvs update}, files will have the date of the
11480 update, not the original timestamp of this revision. This is meant to
11481 make sure that @command{make} notices sources files have been updated.
11483 This timestamp shift is troublesome when both sources and generated
11484 files are kept under CVS@. Because CVS processes files in lexical
11485 order, @file{configure.ac} will appear newer than @file{configure}
11486 after a @command{cvs update} that updates both files, even if
11487 @file{configure} was newer than @file{configure.ac} when it was
11488 checked in. Calling @command{make} will then trigger a spurious rebuild
11489 of @file{configure}.
11491 @subheading Living with CVS in Autoconfiscated Projects
11492 @cindex CVS and generated files
11493 @cindex generated files and CVS
11495 There are basically two clans amongst maintainers: those who keep all
11496 distributed files under CVS, including generated files, and those who
11497 keep generated files @emph{out} of CVS.
11499 @subsubheading All Files in CVS
11503 The CVS repository contains all distributed files so you know exactly
11504 what is distributed, and you can checkout any prior version entirely.
11507 Maintainers can see how generated files evolve (for instance, you can
11508 see what happens to your @file{Makefile.in}s when you upgrade Automake
11509 and make sure they look OK).
11512 Users do not need the autotools to build a checkout of the project, it
11513 works just like a released tarball.
11516 If users use @command{cvs update} to update their copy, instead of
11517 @command{cvs checkout} to fetch a fresh one, timestamps will be
11518 inaccurate. Some rebuild rules will be triggered and attempt to
11519 run developer tools such as @command{autoconf} or @command{automake}.
11521 Actually, calls to such tools are all wrapped into a call to the
11522 @command{missing} script discussed later (@pxref{maintainer-mode}).
11523 @command{missing} will take care of fixing the timestamps when these
11524 tools are not installed, so that the build can continue.
11527 In distributed development, developers are likely to have different
11528 version of the maintainer tools installed. In this case rebuilds
11529 triggered by timestamp lossage will lead to spurious changes
11530 to generated files. There are several solutions to this:
11534 All developers should use the same versions, so that the rebuilt files
11535 are identical to files in CVS@. (This starts to be difficult when each
11536 project you work on uses different versions.)
11538 Or people use a script to fix the timestamp after a checkout (the GCC
11539 folks have such a script).
11541 Or @file{configure.ac} uses @code{AM_MAINTAINER_MODE}, which will
11542 disable all these rebuild rules by default. This is further discussed
11543 in @ref{maintainer-mode}.
11547 Although we focused on spurious rebuilds, the converse can also
11548 happen. CVS's timestamp handling can also let you think an
11549 out-of-date file is up-to-date.
11551 For instance, suppose a developer has modified @file{Makefile.am} and
11552 has rebuilt @file{Makefile.in}, and then decides to do a last-minute
11553 change to @file{Makefile.am} right before checking in both files
11554 (without rebuilding @file{Makefile.in} to account for the change).
11556 This last change to @file{Makefile.am} makes the copy of
11557 @file{Makefile.in} out-of-date. Since CVS processes files
11558 alphabetically, when another developer @samp{cvs update}s his or her
11559 tree, @file{Makefile.in} will happen to be newer than
11560 @file{Makefile.am}. This other developer will not see that
11561 @file{Makefile.in} is out-of-date.
11565 @subsubheading Generated Files out of CVS
11567 One way to get CVS and @command{make} working peacefully is to never
11568 store generated files in CVS, i.e., do not CVS-control files that
11569 are @file{Makefile} targets (also called @emph{derived} files).
11571 This way developers are not annoyed by changes to generated files. It
11572 does not matter if they all have different versions (assuming they are
11573 compatible, of course). And finally, timestamps are not lost, changes
11574 to sources files can't be missed as in the
11575 @file{Makefile.am}/@file{Makefile.in} example discussed earlier.
11577 The drawback is that the CVS repository is not an exact copy of what
11578 is distributed and that users now need to install various development
11579 tools (maybe even specific versions) before they can build a checkout.
11580 But, after all, CVS's job is versioning, not distribution.
11582 Allowing developers to use different versions of their tools can also
11583 hide bugs during distributed development. Indeed, developers will be
11584 using (hence testing) their own generated files, instead of the
11585 generated files that will be released actually. The developer who
11586 prepares the tarball might be using a version of the tool that
11587 produces bogus output (for instance a non-portable C file), something
11588 other developers could have noticed if they weren't using their own
11589 versions of this tool.
11591 @subheading Third-party Files
11592 @cindex CVS and third-party files
11593 @cindex third-party files and CVS
11595 Another class of files not discussed here (because they do not cause
11596 timestamp issues) are files that are shipped with a package, but
11597 maintained elsewhere. For instance, tools like @command{gettextize}
11598 and @command{autopoint} (from Gettext) or @command{libtoolize} (from
11599 Libtool), will install or update files in your package.
11601 These files, whether they are kept under CVS or not, raise similar
11602 concerns about version mismatch between developers' tools. The
11603 Gettext manual has a section about this, see @ref{CVS Issues, CVS
11604 Issues, Integrating with CVS, gettext, GNU gettext tools}.
11606 @node maintainer-mode
11607 @section @command{missing} and @code{AM_MAINTAINER_MODE}
11609 @subheading @command{missing}
11610 @cindex @command{missing}, purpose
11612 The @command{missing} script is a wrapper around several maintainer
11613 tools, designed to warn users if a maintainer tool is required but
11614 missing. Typical maintainer tools are @command{autoconf},
11615 @command{automake}, @command{bison}, etc. Because file generated by
11616 these tools are shipped with the other sources of a package, these
11617 tools shouldn't be required during a user build and they are not
11618 checked for in @file{configure}.
11620 However, if for some reason a rebuild rule is triggered and involves a
11621 missing tool, @command{missing} will notice it and warn the user.
11622 Besides the warning, when a tool is missing, @command{missing} will
11623 attempt to fix timestamps in a way that allows the build to continue.
11624 For instance, @command{missing} will touch @file{configure} if
11625 @command{autoconf} is not installed. When all distributed files are
11626 kept under version control, this feature of @command{missing} allows a
11627 user @emph{with no maintainer tools} to build a package off its version
11628 control repository, bypassing any timestamp inconsistency (implied by
11629 e.g.@: @samp{cvs update} or @samp{git clone}).
11631 If the required tool is installed, @command{missing} will run it and
11632 won't attempt to continue after failures. This is correct during
11633 development: developers love fixing failures. However, users with
11634 wrong versions of maintainer tools may get an error when the rebuild
11635 rule is spuriously triggered, halting the build. This failure to let
11636 the build continue is one of the arguments of the
11637 @code{AM_MAINTAINER_MODE} advocates.
11639 @subheading @code{AM_MAINTAINER_MODE}
11640 @cindex @code{AM_MAINTAINER_MODE}, purpose
11641 @acindex AM_MAINTAINER_MODE
11643 @code{AM_MAINTAINER_MODE} allows you to choose whether the so called
11644 "rebuild rules" should be enabled or disabled. With
11645 @code{AM_MAINTAINER_MODE([enable])}, they are enabled by default,
11646 otherwise they are disabled by default. In the latter case, if
11647 you have @code{AM_MAINTAINER_MODE} in @file{configure.ac}, and run
11648 @samp{./configure && make}, then @command{make} will *never* attempt to
11649 rebuild @file{configure}, @file{Makefile.in}s, Lex or Yacc outputs, etc.
11650 I.e., this disables build rules for files that are usually distributed
11651 and that users should normally not have to update.
11653 The user can override the default setting by passing either
11654 @samp{--enable-maintainer-mode} or @samp{--disable-maintainer-mode}
11655 to @command{configure}.
11657 People use @code{AM_MAINTAINER_MODE} either because they do not want their
11658 users (or themselves) annoyed by timestamps lossage (@pxref{CVS}), or
11659 because they simply can't stand the rebuild rules and prefer running
11660 maintainer tools explicitly.
11662 @code{AM_MAINTAINER_MODE} also allows you to disable some custom build
11663 rules conditionally. Some developers use this feature to disable
11664 rules that need exotic tools that users may not have available.
11666 Several years ago Fran@,{c}ois Pinard pointed out several arguments
11667 against this @code{AM_MAINTAINER_MODE} macro. Most of them relate to
11668 insecurity. By removing dependencies you get non-dependable builds:
11669 changes to sources files can have no effect on generated files and this
11670 can be very confusing when unnoticed. He adds that security shouldn't
11671 be reserved to maintainers (what @option{--enable-maintainer-mode}
11672 suggests), on the contrary. If one user has to modify a
11673 @file{Makefile.am}, then either @file{Makefile.in} should be updated
11674 or a warning should be output (this is what Automake uses
11675 @command{missing} for) but the last thing you want is that nothing
11676 happens and the user doesn't notice it (this is what happens when
11677 rebuild rules are disabled by @code{AM_MAINTAINER_MODE}).
11679 Jim Meyering, the inventor of the @code{AM_MAINTAINER_MODE} macro was
11680 swayed by Fran@,{c}ois's arguments, and got rid of
11681 @code{AM_MAINTAINER_MODE} in all of his packages.
11683 Still many people continue to use @code{AM_MAINTAINER_MODE}, because
11684 it helps them working on projects where all files are kept under version
11685 control, and because @command{missing} isn't enough if you have the
11686 wrong version of the tools.
11690 @section Why doesn't Automake support wildcards?
11693 Developers are lazy. They would often like to use wildcards in
11694 @file{Makefile.am}s, so that they would not need to remember to
11695 update @file{Makefile.am}s every time they add, delete, or rename
11698 There are several objections to this:
11701 When using CVS (or similar) developers need to remember they have to
11702 run @samp{cvs add} or @samp{cvs rm} anyway. Updating
11703 @file{Makefile.am} accordingly quickly becomes a reflex.
11705 Conversely, if your application doesn't compile
11706 because you forgot to add a file in @file{Makefile.am}, it will help
11707 you remember to @samp{cvs add} it.
11710 Using wildcards makes it easy to distribute files by mistake. For
11711 instance, some code a developer is experimenting with (a test case,
11712 say) that should not be part of the distribution.
11715 Using wildcards it's easy to omit some files by mistake. For
11716 instance, one developer creates a new file, uses it in many places,
11717 but forgets to commit it. Another developer then checks out the
11718 incomplete project and is able to run @samp{make dist} successfully,
11719 even though a file is missing. By listing files, @samp{make dist}
11720 @emph{will} complain.
11723 Wildcards are not portable to some non-GNU @command{make} implementations,
11724 e.g., NetBSD @command{make} will not expand globs such as @samp{*} in
11725 prerequisites of a target.
11728 Finally, it's really hard to @emph{forget} to add a file to
11729 @file{Makefile.am}: files that are not listed in @file{Makefile.am} are
11730 not compiled or installed, so you can't even test them.
11733 Still, these are philosophical objections, and as such you may disagree,
11734 or find enough value in wildcards to dismiss all of them. Before you
11735 start writing a patch against Automake to teach it about wildcards,
11736 let's see the main technical issue: portability.
11738 Although @samp{$(wildcard ...)} works with GNU @command{make}, it is
11739 not portable to other @command{make} implementations.
11741 The only way Automake could support @command{$(wildcard ...)} is by
11742 expending @command{$(wildcard ...)} when @command{automake} is run.
11743 The resulting @file{Makefile.in}s would be portable since they would
11744 list all files and not use @samp{$(wildcard ...)}. However that
11745 means developers would need to remember to run @command{automake} each
11746 time they add, delete, or rename files.
11748 Compared to editing @file{Makefile.am}, this is a very small gain. Sure,
11749 it's easier and faster to type @samp{automake; make} than to type
11750 @samp{emacs Makefile.am; make}. But nobody bothered enough to write a
11751 patch to add support for this syntax. Some people use scripts to
11752 generate file lists in @file{Makefile.am} or in separate
11753 @file{Makefile} fragments.
11755 Even if you don't care about portability, and are tempted to use
11756 @samp{$(wildcard ...)} anyway because you target only GNU Make, you
11757 should know there are many places where Automake needs to know exactly
11758 which files should be processed. As Automake doesn't know how to
11759 expand @samp{$(wildcard ...)}, you cannot use it in these places.
11760 @samp{$(wildcard ...)} is a black box comparable to @code{AC_SUBST}ed
11761 variables as far Automake is concerned.
11763 You can get warnings about @samp{$(wildcard ...}) constructs using the
11764 @option{-Wportability} flag.
11766 @node Limitations on File Names
11767 @section Limitations on File Names
11768 @cindex file names, limitations on
11770 Automake attempts to support all kinds of file names, even those that
11771 contain unusual characters or are unusually long. However, some
11772 limitations are imposed by the underlying operating system and tools.
11774 Most operating systems prohibit the use of the null byte in file
11775 names, and reserve @samp{/} as a directory separator. Also, they
11776 require that file names are properly encoded for the user's locale.
11777 Automake is subject to these limits.
11779 Portable packages should limit themselves to POSIX file
11780 names. These can contain ASCII letters and digits,
11781 @samp{_}, @samp{.}, and @samp{-}. File names consist of components
11782 separated by @samp{/}. File name components cannot begin with
11785 Portable POSIX file names cannot contain components that exceed a
11786 14-byte limit, but nowadays it's normally safe to assume the
11787 more-generous XOPEN limit of 255 bytes. POSIX
11788 limits file names to 255 bytes (XOPEN allows 1023 bytes),
11789 but you may want to limit a source tarball to file names of 99 bytes
11790 to avoid interoperability problems with old versions of @command{tar}.
11792 If you depart from these rules (e.g., by using non-ASCII
11793 characters in file names, or by using lengthy file names), your
11794 installers may have problems for reasons unrelated to Automake.
11795 However, if this does not concern you, you should know about the
11796 limitations imposed by Automake itself. These limitations are
11797 undesirable, but some of them seem to be inherent to underlying tools
11798 like Autoconf, Make, M4, and the shell. They fall into three
11799 categories: install directories, build directories, and file names.
11801 The following characters:
11804 @r{newline} " # $ ' `
11807 should not appear in the names of install directories. For example,
11808 the operand of @command{configure}'s @option{--prefix} option should
11809 not contain these characters.
11811 Build directories suffer the same limitations as install directories,
11812 and in addition should not contain the following characters:
11818 For example, the full name of the directory containing the source
11819 files should not contain these characters.
11821 Source and installation file names like @file{main.c} are limited even
11822 further: they should conform to the POSIX/XOPEN
11823 rules described above. In addition, if you plan to port to
11824 non-POSIX environments, you should avoid file names that
11825 differ only in case (e.g., @file{makefile} and @file{Makefile}).
11826 Nowadays it is no longer worth worrying about the 8.3 limits of
11829 @c FIXME This should probably be moved in the "Checking the Distribution"
11830 @c FIXME section...
11831 @node Errors with distclean
11832 @section Errors with distclean
11833 @cindex @code{distclean}, diagnostic
11834 @cindex @samp{make distclean}, diagnostic
11835 @cindex dependencies and distributed files
11838 This is a diagnostic you might encounter while running @samp{make
11841 As explained in @ref{Checking the Distribution}, @samp{make distcheck}
11842 attempts to build and check your package for errors like this one.
11844 @samp{make distcheck} will perform a @code{VPATH} build of your
11845 package (@pxref{VPATH Builds}), and then call @samp{make distclean}.
11846 Files left in the build directory after @samp{make distclean} has run
11847 are listed after this error.
11849 This diagnostic really covers two kinds of errors:
11853 files that are forgotten by distclean;
11855 distributed files that are erroneously rebuilt.
11858 The former left-over files are not distributed, so the fix is to mark
11859 them for cleaning (@pxref{Clean}), this is obvious and doesn't deserve
11862 The latter bug is not always easy to understand and fix, so let's
11863 proceed with an example. Suppose our package contains a program for
11864 which we want to build a man page using @command{help2man}. GNU
11865 @command{help2man} produces simple manual pages from the @option{--help}
11866 and @option{--version} output of other commands (@pxref{Top, , Overview,
11867 help2man, The Help2man Manual}). Because we don't want to force our
11868 users to install @command{help2man}, we decide to distribute the
11869 generated man page using the following setup.
11872 # This Makefile.am is bogus.
11874 foo_SOURCES = foo.c
11875 dist_man_MANS = foo.1
11877 foo.1: foo$(EXEEXT)
11878 help2man --output=foo.1 ./foo$(EXEEXT)
11881 This will effectively distribute the man page. However,
11882 @samp{make distcheck} will fail with:
11885 ERROR: files left in build directory after distclean:
11889 Why was @file{foo.1} rebuilt? Because although distributed,
11890 @file{foo.1} depends on a non-distributed built file:
11891 @file{foo$(EXEEXT)}. @file{foo$(EXEEXT)} is built by the user, so it
11892 will always appear to be newer than the distributed @file{foo.1}.
11894 @samp{make distcheck} caught an inconsistency in our package. Our
11895 intent was to distribute @file{foo.1} so users do not need to install
11896 @command{help2man}, however since this rule causes this file to be
11897 always rebuilt, users @emph{do} need @command{help2man}. Either we
11898 should ensure that @file{foo.1} is not rebuilt by users, or there is
11899 no point in distributing @file{foo.1}.
11901 More generally, the rule is that distributed files should never depend
11902 on non-distributed built files. If you distribute something
11903 generated, distribute its sources.
11905 One way to fix the above example, while still distributing
11906 @file{foo.1} is to not depend on @file{foo$(EXEEXT)}. For instance,
11907 assuming @command{foo --version} and @command{foo --help} do not
11908 change unless @file{foo.c} or @file{configure.ac} change, we could
11909 write the following @file{Makefile.am}:
11913 foo_SOURCES = foo.c
11914 dist_man_MANS = foo.1
11916 foo.1: foo.c $(top_srcdir)/configure.ac
11917 $(MAKE) $(AM_MAKEFLAGS) foo$(EXEEXT)
11918 help2man --output=foo.1 ./foo$(EXEEXT)
11921 This way, @file{foo.1} will not get rebuilt every time
11922 @file{foo$(EXEEXT)} changes. The @command{make} call makes sure
11923 @file{foo$(EXEEXT)} is up-to-date before @command{help2man}. Another
11924 way to ensure this would be to use separate directories for binaries
11925 and man pages, and set @code{SUBDIRS} so that binaries are built
11928 We could also decide not to distribute @file{foo.1}. In
11929 this case it's fine to have @file{foo.1} dependent upon
11930 @file{foo$(EXEEXT)}, since both will have to be rebuilt.
11931 However it would be impossible to build the package in a
11932 cross-compilation, because building @file{foo.1} involves
11933 an @emph{execution} of @file{foo$(EXEEXT)}.
11935 Another context where such errors are common is when distributed files
11936 are built by tools that are built by the package. The pattern is
11940 distributed-file: built-tools distributed-sources
11945 should be changed to
11948 distributed-file: distributed-sources
11949 $(MAKE) $(AM_MAKEFLAGS) built-tools
11954 or you could choose not to distribute @file{distributed-file}, if
11955 cross-compilation does not matter.
11957 The points made through these examples are worth a summary:
11962 Distributed files should never depend upon non-distributed built
11965 Distributed files should be distributed with all their dependencies.
11967 If a file is @emph{intended} to be rebuilt by users, then there is no point
11968 in distributing it.
11972 @vrindex distcleancheck_listfiles
11973 For desperate cases, it's always possible to disable this check by
11974 setting @code{distcleancheck_listfiles} as documented in @ref{Checking
11976 Make sure you do understand the reason why @samp{make distcheck}
11977 complains before you do this. @code{distcleancheck_listfiles} is a
11978 way to @emph{hide} errors, not to fix them. You can always do better.
11980 @node Flag Variables Ordering
11981 @section Flag Variables Ordering
11982 @cindex Ordering flag variables
11983 @cindex Flag variables, ordering
11986 What is the difference between @code{AM_CFLAGS}, @code{CFLAGS}, and
11987 @code{mumble_CFLAGS}?
11991 Why does @command{automake} output @code{CPPFLAGS} after
11992 @code{AM_CPPFLAGS} on compile lines? Shouldn't it be the converse?
11996 My @file{configure} adds some warning flags into @code{CXXFLAGS}. In
11997 one @file{Makefile.am} I would like to append a new flag, however if I
11998 put the flag into @code{AM_CXXFLAGS} it is prepended to the other
11999 flags, not appended.
12002 @subheading Compile Flag Variables
12003 @cindex Flag Variables, Ordering
12004 @cindex Compile Flag Variables
12005 @cindex @code{AM_CCASFLAGS} and @code{CCASFLAGS}
12006 @cindex @code{AM_CFLAGS} and @code{CFLAGS}
12007 @cindex @code{AM_CPPFLAGS} and @code{CPPFLAGS}
12008 @cindex @code{AM_CXXFLAGS} and @code{CXXFLAGS}
12009 @cindex @code{AM_FCFLAGS} and @code{FCFLAGS}
12010 @cindex @code{AM_FFLAGS} and @code{FFLAGS}
12011 @cindex @code{AM_GCJFLAGS} and @code{GCJFLAGS}
12012 @cindex @code{AM_LDFLAGS} and @code{LDFLAGS}
12013 @cindex @code{AM_LFLAGS} and @code{LFLAGS}
12014 @cindex @code{AM_LIBTOOLFLAGS} and @code{LIBTOOLFLAGS}
12015 @cindex @code{AM_OBJCFLAGS} and @code{OBJCFLAGS}
12016 @cindex @code{AM_RFLAGS} and @code{RFLAGS}
12017 @cindex @code{AM_UPCFLAGS} and @code{UPCFLAGS}
12018 @cindex @code{AM_YFLAGS} and @code{YFLAGS}
12019 @cindex @code{CCASFLAGS} and @code{AM_CCASFLAGS}
12020 @cindex @code{CFLAGS} and @code{AM_CFLAGS}
12021 @cindex @code{CPPFLAGS} and @code{AM_CPPFLAGS}
12022 @cindex @code{CXXFLAGS} and @code{AM_CXXFLAGS}
12023 @cindex @code{FCFLAGS} and @code{AM_FCFLAGS}
12024 @cindex @code{FFLAGS} and @code{AM_FFLAGS}
12025 @cindex @code{GCJFLAGS} and @code{AM_GCJFLAGS}
12026 @cindex @code{LDFLAGS} and @code{AM_LDFLAGS}
12027 @cindex @code{LFLAGS} and @code{AM_LFLAGS}
12028 @cindex @code{LIBTOOLFLAGS} and @code{AM_LIBTOOLFLAGS}
12029 @cindex @code{OBJCFLAGS} and @code{AM_OBJCFLAGS}
12030 @cindex @code{RFLAGS} and @code{AM_RFLAGS}
12031 @cindex @code{UPCFLAGS} and @code{AM_UPCFLAGS}
12032 @cindex @code{YFLAGS} and @code{AM_YFLAGS}
12034 This section attempts to answer all the above questions. We will
12035 mostly discuss @code{CPPFLAGS} in our examples, but actually the
12036 answer holds for all the compile flags used in Automake:
12037 @code{CCASFLAGS}, @code{CFLAGS}, @code{CPPFLAGS}, @code{CXXFLAGS},
12038 @code{FCFLAGS}, @code{FFLAGS}, @code{GCJFLAGS}, @code{LDFLAGS},
12039 @code{LFLAGS}, @code{LIBTOOLFLAGS}, @code{OBJCFLAGS}, @code{RFLAGS},
12040 @code{UPCFLAGS}, and @code{YFLAGS}.
12042 @code{CPPFLAGS}, @code{AM_CPPFLAGS}, and @code{mumble_CPPFLAGS} are
12043 three variables that can be used to pass flags to the C preprocessor
12044 (actually these variables are also used for other languages like C++
12045 or preprocessed Fortran). @code{CPPFLAGS} is the user variable
12046 (@pxref{User Variables}), @code{AM_CPPFLAGS} is the Automake variable,
12047 and @code{mumble_CPPFLAGS} is the variable specific to the
12048 @code{mumble} target (we call this a per-target variable,
12049 @pxref{Program and Library Variables}).
12051 Automake always uses two of these variables when compiling C sources
12052 files. When compiling an object file for the @code{mumble} target,
12053 the first variable will be @code{mumble_CPPFLAGS} if it is defined, or
12054 @code{AM_CPPFLAGS} otherwise. The second variable is always
12057 In the following example,
12060 bin_PROGRAMS = foo bar
12061 foo_SOURCES = xyz.c
12062 bar_SOURCES = main.c
12063 foo_CPPFLAGS = -DFOO
12064 AM_CPPFLAGS = -DBAZ
12068 @file{xyz.o} will be compiled with @samp{$(foo_CPPFLAGS) $(CPPFLAGS)},
12069 (because @file{xyz.o} is part of the @code{foo} target), while
12070 @file{main.o} will be compiled with @samp{$(AM_CPPFLAGS) $(CPPFLAGS)}
12071 (because there is no per-target variable for target @code{bar}).
12073 The difference between @code{mumble_CPPFLAGS} and @code{AM_CPPFLAGS}
12074 being clear enough, let's focus on @code{CPPFLAGS}. @code{CPPFLAGS}
12075 is a user variable, i.e., a variable that users are entitled to modify
12076 in order to compile the package. This variable, like many others,
12077 is documented at the end of the output of @samp{configure --help}.
12079 For instance, someone who needs to add @file{/home/my/usr/include} to
12080 the C compiler's search path would configure a package with
12083 ./configure CPPFLAGS='-I /home/my/usr/include'
12087 and this flag would be propagated to the compile rules of all
12090 It is also not uncommon to override a user variable at
12091 @command{make}-time. Many installers do this with @code{prefix}, but
12092 this can be useful with compiler flags too. For instance, if, while
12093 debugging a C++ project, you need to disable optimization in one
12094 specific object file, you can run something like
12098 make CXXFLAGS=-O0 file.o
12102 The reason @samp{$(CPPFLAGS)} appears after @samp{$(AM_CPPFLAGS)} or
12103 @samp{$(mumble_CPPFLAGS)} in the compile command is that users
12104 should always have the last say. It probably makes more sense if you
12105 think about it while looking at the @samp{CXXFLAGS=-O0} above, which
12106 should supersede any other switch from @code{AM_CXXFLAGS} or
12107 @code{mumble_CXXFLAGS} (and this of course replaces the previous value
12108 of @code{CXXFLAGS}).
12110 You should never redefine a user variable such as @code{CPPFLAGS} in
12111 @file{Makefile.am}. Use @samp{automake -Woverride} to diagnose such
12112 mistakes. Even something like
12115 CPPFLAGS = -DDATADIR=\"$(datadir)\" @@CPPFLAGS@@
12119 is erroneous. Although this preserves @file{configure}'s value of
12120 @code{CPPFLAGS}, the definition of @code{DATADIR} will disappear if a
12121 user attempts to override @code{CPPFLAGS} from the @command{make}
12125 AM_CPPFLAGS = -DDATADIR=\"$(datadir)\"
12129 is all that is needed here if no per-target flags are used.
12131 You should not add options to these user variables within
12132 @file{configure} either, for the same reason. Occasionally you need
12133 to modify these variables to perform a test, but you should reset
12134 their values afterwards. In contrast, it is OK to modify the
12135 @samp{AM_} variables within @file{configure} if you @code{AC_SUBST}
12136 them, but it is rather rare that you need to do this, unless you
12137 really want to change the default definitions of the @samp{AM_}
12138 variables in all @file{Makefile}s.
12140 What we recommend is that you define extra flags in separate
12141 variables. For instance, you may write an Autoconf macro that computes
12142 a set of warning options for the C compiler, and @code{AC_SUBST} them
12143 in @code{WARNINGCFLAGS}; you may also have an Autoconf macro that
12144 determines which compiler and which linker flags should be used to
12145 link with library @file{libfoo}, and @code{AC_SUBST} these in
12146 @code{LIBFOOCFLAGS} and @code{LIBFOOLDFLAGS}. Then, a
12147 @file{Makefile.am} could use these variables as follows:
12150 AM_CFLAGS = $(WARNINGCFLAGS)
12151 bin_PROGRAMS = prog1 prog2
12152 prog1_SOURCES = @dots{}
12153 prog2_SOURCES = @dots{}
12154 prog2_CFLAGS = $(LIBFOOCFLAGS) $(AM_CFLAGS)
12155 prog2_LDFLAGS = $(LIBFOOLDFLAGS)
12158 In this example both programs will be compiled with the flags
12159 substituted into @samp{$(WARNINGCFLAGS)}, and @code{prog2} will
12160 additionally be compiled with the flags required to link with
12163 Note that listing @code{AM_CFLAGS} in a per-target @code{CFLAGS}
12164 variable is a common idiom to ensure that @code{AM_CFLAGS} applies to
12165 every target in a @file{Makefile.in}.
12167 Using variables like this gives you full control over the ordering of
12168 the flags. For instance, if there is a flag in $(WARNINGCFLAGS) that
12169 you want to negate for a particular target, you can use something like
12170 @samp{prog1_CFLAGS = $(AM_CFLAGS) -no-flag}. If all these flags had
12171 been forcefully appended to @code{CFLAGS}, there would be no way to
12172 disable one flag. Yet another reason to leave user variables to
12175 Finally, we have avoided naming the variable of the example
12176 @code{LIBFOO_LDFLAGS} (with an underscore) because that would cause
12177 Automake to think that this is actually a per-target variable (like
12178 @code{mumble_LDFLAGS}) for some non-declared @code{LIBFOO} target.
12180 @subheading Other Variables
12182 There are other variables in Automake that follow similar principles
12183 to allow user options. For instance, Texinfo rules (@pxref{Texinfo})
12184 use @code{MAKEINFOFLAGS} and @code{AM_MAKEINFOFLAGS}. Similarly,
12185 DejaGnu tests (@pxref{DejaGnu Tests}) use @code{RUNTESTDEFAULTFLAGS} and
12186 @code{AM_RUNTESTDEFAULTFLAGS}. The tags and ctags rules
12187 (@pxref{Tags}) use @code{ETAGSFLAGS}, @code{AM_ETAGSFLAGS},
12188 @code{CTAGSFLAGS}, and @code{AM_CTAGSFLAGS}. Java rules
12189 (@pxref{Java}) use @code{JAVACFLAGS} and @code{AM_JAVACFLAGS}. None
12190 of these rules support per-target flags (yet).
12192 To some extent, even @code{AM_MAKEFLAGS} (@pxref{Subdirectories})
12193 obeys this naming scheme. The slight difference is that
12194 @code{MAKEFLAGS} is passed to sub-@command{make}s implicitly by
12195 @command{make} itself.
12197 However you should not think that all variables ending with
12198 @code{FLAGS} follow this convention. For instance,
12199 @code{DISTCHECK_CONFIGURE_FLAGS} (@pxref{Checking the Distribution}) and
12200 @code{ACLOCAL_AMFLAGS} (see @ref{Rebuilding} and @ref{Local Macros}),
12201 are two variables that are only useful to the maintainer and have no
12204 @code{ARFLAGS} (@pxref{A Library}) is usually defined by Automake and
12205 has neither @code{AM_} nor per-target cousin.
12207 Finally you should not think that the existence of a per-target
12208 variable implies the existence of an @code{AM_} variable or of a user
12209 variable. For instance, the @code{mumble_LDADD} per-target variable
12210 overrides the makefile-wide @code{LDADD} variable (which is not a user
12211 variable), and @code{mumble_LIBADD} exists only as a per-target
12212 variable. @xref{Program and Library Variables}.
12215 @node Renamed Objects
12216 @section Why are object files sometimes renamed?
12218 This happens when per-target compilation flags are used. Object
12219 files need to be renamed just in case they would clash with object
12220 files compiled from the same sources, but with different flags.
12221 Consider the following example.
12224 bin_PROGRAMS = true false
12225 true_SOURCES = generic.c
12226 true_CPPFLAGS = -DEXIT_CODE=0
12227 false_SOURCES = generic.c
12228 false_CPPFLAGS = -DEXIT_CODE=1
12232 Obviously the two programs are built from the same source, but it
12233 would be bad if they shared the same object, because @file{generic.o}
12234 cannot be built with both @samp{-DEXIT_CODE=0} @emph{and}
12235 @samp{-DEXIT_CODE=1}. Therefore @command{automake} outputs rules to
12236 build two different objects: @file{true-generic.o} and
12237 @file{false-generic.o}.
12239 @command{automake} doesn't actually look whether source files are
12240 shared to decide if it must rename objects. It will just rename all
12241 objects of a target as soon as it sees per-target compilation flags
12244 It's OK to share object files when per-target compilation flags are not
12245 used. For instance, @file{true} and @file{false} will both use
12246 @file{version.o} in the following example.
12249 AM_CPPFLAGS = -DVERSION=1.0
12250 bin_PROGRAMS = true false
12251 true_SOURCES = true.c version.c
12252 false_SOURCES = false.c version.c
12255 Note that the renaming of objects is also affected by the
12256 @code{_SHORTNAME} variable (@pxref{Program and Library Variables}).
12259 @node Per-Object Flags
12260 @section Per-Object Flags Emulation
12261 @cindex Per-object flags, emulated
12264 One of my source files needs to be compiled with different flags. How
12268 Automake supports per-program and per-library compilation flags (see
12269 @ref{Program and Library Variables} and @ref{Flag Variables
12270 Ordering}). With this you can define compilation flags that apply to
12271 all files compiled for a target. For instance, in
12275 foo_SOURCES = foo.c foo.h bar.c bar.h main.c
12276 foo_CFLAGS = -some -flags
12280 @file{foo-foo.o}, @file{foo-bar.o}, and @file{foo-main.o} will all be
12281 compiled with @samp{-some -flags}. (If you wonder about the names of
12282 these object files, see @ref{Renamed Objects}.) Note that
12283 @code{foo_CFLAGS} gives the flags to use when compiling all the C
12284 sources of the @emph{program} @code{foo}, it has nothing to do with
12285 @file{foo.c} or @file{foo-foo.o} specifically.
12287 What if @file{foo.c} needs to be compiled into @file{foo.o} using some
12288 specific flags, that none of the other files requires? Obviously
12289 per-program flags are not directly applicable here. Something like
12290 per-object flags are expected, i.e., flags that would be used only
12291 when creating @file{foo-foo.o}. Automake does not support that,
12292 however this is easy to simulate using a library that contains only
12293 that object, and compiling this library with per-library flags.
12297 foo_SOURCES = bar.c bar.h main.c
12298 foo_CFLAGS = -some -flags
12299 foo_LDADD = libfoo.a
12300 noinst_LIBRARIES = libfoo.a
12301 libfoo_a_SOURCES = foo.c foo.h
12302 libfoo_a_CFLAGS = -some -other -flags
12305 Here @file{foo-bar.o} and @file{foo-main.o} will all be
12306 compiled with @samp{-some -flags}, while @file{libfoo_a-foo.o} will
12307 be compiled using @samp{-some -other -flags}. Eventually, all
12308 three objects will be linked to form @file{foo}.
12310 This trick can also be achieved using Libtool convenience libraries,
12311 for instance @samp{noinst_LTLIBRARIES = libfoo.la} (@pxref{Libtool
12312 Convenience Libraries}).
12314 Another tempting idea to implement per-object flags is to override the
12315 compile rules @command{automake} would output for these files.
12316 Automake will not define a rule for a target you have defined, so you
12317 could think about defining the @samp{foo-foo.o: foo.c} rule yourself.
12318 We recommend against this, because this is error prone. For instance,
12319 if you add such a rule to the first example, it will break the day you
12320 decide to remove @code{foo_CFLAGS} (because @file{foo.c} will then be
12321 compiled as @file{foo.o} instead of @file{foo-foo.o}, @pxref{Renamed
12322 Objects}). Also in order to support dependency tracking, the two
12323 @file{.o}/@file{.obj} extensions, and all the other flags variables
12324 involved in a compilation, you will end up modifying a copy of the
12325 rule previously output by @command{automake} for this file. If a new
12326 release of Automake generates a different rule, your copy will need to
12327 be updated by hand.
12329 @node Multiple Outputs
12330 @section Handling Tools that Produce Many Outputs
12331 @cindex multiple outputs, rules with
12332 @cindex many outputs, rules with
12333 @cindex rules with multiple outputs
12335 This section describes a @command{make} idiom that can be used when a
12336 tool produces multiple output files. It is not specific to Automake
12337 and can be used in ordinary @file{Makefile}s.
12339 Suppose we have a program called @command{foo} that will read one file
12340 called @file{data.foo} and produce two files named @file{data.c} and
12341 @file{data.h}. We want to write a @file{Makefile} rule that captures
12342 this one-to-two dependency.
12344 The naive rule is incorrect:
12347 # This is incorrect.
12348 data.c data.h: data.foo
12353 What the above rule really says is that @file{data.c} and
12354 @file{data.h} each depend on @file{data.foo}, and can each be built by
12355 running @samp{foo data.foo}. In other words it is equivalent to:
12358 # We do not want this.
12366 which means that @command{foo} can be run twice. Usually it will not
12367 be run twice, because @command{make} implementations are smart enough
12368 to check for the existence of the second file after the first one has
12369 been built; they will therefore detect that it already exists.
12370 However there are a few situations where it can run twice anyway:
12374 The most worrying case is when running a parallel @command{make}. If
12375 @file{data.c} and @file{data.h} are built in parallel, two @samp{foo
12376 data.foo} commands will run concurrently. This is harmful.
12378 Another case is when the dependency (here @file{data.foo}) is
12379 (or depends upon) a phony target.
12382 A solution that works with parallel @command{make} but not with
12383 phony dependencies is the following:
12386 data.c data.h: data.foo
12392 The above rules are equivalent to
12397 data.h: data.foo data.c
12402 therefore a parallel @command{make} will have to serialize the builds
12403 of @file{data.c} and @file{data.h}, and will detect that the second is
12404 no longer needed once the first is over.
12406 Using this pattern is probably enough for most cases. However it does
12407 not scale easily to more output files (in this scheme all output files
12408 must be totally ordered by the dependency relation), so we will
12409 explore a more complicated solution.
12411 Another idea is to write the following:
12414 # There is still a problem with this one.
12421 The idea is that @samp{foo data.foo} is run only when @file{data.c}
12422 needs to be updated, but we further state that @file{data.h} depends
12423 upon @file{data.c}. That way, if @file{data.h} is required and
12424 @file{data.foo} is out of date, the dependency on @file{data.c} will
12427 This is almost perfect, but suppose we have built @file{data.h} and
12428 @file{data.c}, and then we erase @file{data.h}. Then, running
12429 @samp{make data.h} will not rebuild @file{data.h}. The above rules
12430 just state that @file{data.c} must be up-to-date with respect to
12431 @file{data.foo}, and this is already the case.
12433 What we need is a rule that forces a rebuild when @file{data.h} is
12434 missing. Here it is:
12440 ## Recover from the removal of $@@
12441 @@if test -f $@@; then :; else \
12443 $(MAKE) $(AM_MAKEFLAGS) data.c; \
12447 The above scheme can be extended to handle more outputs and more
12448 inputs. One of the outputs is selected to serve as a witness to the
12449 successful completion of the command, it depends upon all inputs, and
12450 all other outputs depend upon it. For instance, if @command{foo}
12451 should additionally read @file{data.bar} and also produce
12452 @file{data.w} and @file{data.x}, we would write:
12455 data.c: data.foo data.bar
12456 foo data.foo data.bar
12457 data.h data.w data.x: data.c
12458 ## Recover from the removal of $@@
12459 @@if test -f $@@; then :; else \
12461 $(MAKE) $(AM_MAKEFLAGS) data.c; \
12465 However there are now three minor problems in this setup. One is related
12466 to the timestamp ordering of @file{data.h}, @file{data.w},
12467 @file{data.x}, and @file{data.c}. Another one is a race condition
12468 if a parallel @command{make} attempts to run multiple instances of the
12469 recover block at once. Finally, the recursive rule breaks @samp{make -n}
12470 when run with GNU @command{make} (as well as some other @command{make}
12471 implementations), as it may remove @file{data.h} even when it should not
12472 (@pxref{MAKE Variable, , How the @code{MAKE} Variable Works, make,
12473 The GNU Make Manual}).
12475 Let us deal with the first problem. @command{foo} outputs four files,
12476 but we do not know in which order these files are created. Suppose
12477 that @file{data.h} is created before @file{data.c}. Then we have a
12478 weird situation. The next time @command{make} is run, @file{data.h}
12479 will appear older than @file{data.c}, the second rule will be
12480 triggered, a shell will be started to execute the @samp{if@dots{}fi}
12481 command, but actually it will just execute the @code{then} branch,
12482 that is: nothing. In other words, because the witness we selected is
12483 not the first file created by @command{foo}, @command{make} will start
12484 a shell to do nothing each time it is run.
12486 A simple riposte is to fix the timestamps when this happens.
12489 data.c: data.foo data.bar
12490 foo data.foo data.bar
12491 data.h data.w data.x: data.c
12492 @@if test -f $@@; then \
12495 ## Recover from the removal of $@@
12497 $(MAKE) $(AM_MAKEFLAGS) data.c; \
12501 Another solution is to use a different and dedicated file as witness,
12502 rather than using any of @command{foo}'s outputs.
12505 data.stamp: data.foo data.bar
12508 foo data.foo data.bar
12509 @@mv -f data.tmp $@@
12510 data.c data.h data.w data.x: data.stamp
12511 ## Recover from the removal of $@@
12512 @@if test -f $@@; then :; else \
12513 rm -f data.stamp; \
12514 $(MAKE) $(AM_MAKEFLAGS) data.stamp; \
12518 @file{data.tmp} is created before @command{foo} is run, so it has a
12519 timestamp older than output files output by @command{foo}. It is then
12520 renamed to @file{data.stamp} after @command{foo} has run, because we
12521 do not want to update @file{data.stamp} if @command{foo} fails.
12523 This solution still suffers from the second problem: the race
12524 condition in the recover rule. If, after a successful build, a user
12525 erases @file{data.c} and @file{data.h}, and runs @samp{make -j}, then
12526 @command{make} may start both recover rules in parallel. If the two
12527 instances of the rule execute @samp{$(MAKE) $(AM_MAKEFLAGS)
12528 data.stamp} concurrently the build is likely to fail (for instance, the
12529 two rules will create @file{data.tmp}, but only one can rename it).
12531 Admittedly, such a weird situation does not arise during ordinary
12532 builds. It occurs only when the build tree is mutilated. Here
12533 @file{data.c} and @file{data.h} have been explicitly removed without
12534 also removing @file{data.stamp} and the other output files.
12535 @code{make clean; make} will always recover from these situations even
12536 with parallel makes, so you may decide that the recover rule is solely
12537 to help non-parallel make users and leave things as-is. Fixing this
12538 requires some locking mechanism to ensure only one instance of the
12539 recover rule rebuilds @file{data.stamp}. One could imagine something
12540 along the following lines.
12543 data.c data.h data.w data.x: data.stamp
12544 ## Recover from the removal of $@@
12545 @@if test -f $@@; then :; else \
12546 trap 'rm -rf data.lock data.stamp' 1 2 13 15; \
12547 ## mkdir is a portable test-and-set
12548 if mkdir data.lock 2>/dev/null; then \
12549 ## This code is being executed by the first process.
12550 rm -f data.stamp; \
12551 $(MAKE) $(AM_MAKEFLAGS) data.stamp; \
12552 result=$$?; rm -rf data.lock; exit $$result; \
12554 ## This code is being executed by the follower processes.
12555 ## Wait until the first process is done.
12556 while test -d data.lock; do sleep 1; done; \
12557 ## Succeed if and only if the first process succeeded.
12558 test -f data.stamp; \
12563 Using a dedicated witness, like @file{data.stamp}, is very handy when
12564 the list of output files is not known beforehand. As an illustration,
12565 consider the following rules to compile many @file{*.el} files into
12566 @file{*.elc} files in a single command. It does not matter how
12567 @code{ELFILES} is defined (as long as it is not empty: empty targets
12568 are not accepted by POSIX).
12571 ELFILES = one.el two.el three.el @dots{}
12572 ELCFILES = $(ELFILES:=c)
12574 elc-stamp: $(ELFILES)
12577 $(elisp_comp) $(ELFILES)
12578 @@mv -f elc-temp $@@
12580 $(ELCFILES): elc-stamp
12581 @@if test -f $@@; then :; else \
12582 ## Recover from the removal of $@@
12583 trap 'rm -rf elc-lock elc-stamp' 1 2 13 15; \
12584 if mkdir elc-lock 2>/dev/null; then \
12585 ## This code is being executed by the first process.
12587 $(MAKE) $(AM_MAKEFLAGS) elc-stamp; \
12590 ## This code is being executed by the follower processes.
12591 ## Wait until the first process is done.
12592 while test -d elc-lock; do sleep 1; done; \
12593 ## Succeed if and only if the first process succeeded.
12594 test -f elc-stamp; exit $$?; \
12600 These solutions all still suffer from the third problem, namely that
12601 they break the promise that @samp{make -n} should not cause any actual
12602 changes to the tree. For those solutions that do not create lock files,
12603 it is possible to split the recover rules into two separate recipe
12604 commands, one of which does all work but the recursion, and the
12605 other invokes the recursive @samp{$(MAKE)}. The solutions involving
12606 locking could act upon the contents of the @samp{MAKEFLAGS} variable,
12607 but parsing that portably is not easy (@pxref{The Make Macro MAKEFLAGS,,,
12608 autoconf, The Autoconf Manual}). Here is an example:
12611 ELFILES = one.el two.el three.el @dots{}
12612 ELCFILES = $(ELFILES:=c)
12614 elc-stamp: $(ELFILES)
12617 $(elisp_comp) $(ELFILES)
12618 @@mv -f elc-temp $@@
12620 $(ELCFILES): elc-stamp
12621 ## Recover from the removal of $@@
12622 @@dry=; for f in x $$MAKEFLAGS; do \
12628 if test -f $@@; then :; else \
12629 $$dry trap 'rm -rf elc-lock elc-stamp' 1 2 13 15; \
12630 if $$dry mkdir elc-lock 2>/dev/null; then \
12631 ## This code is being executed by the first process.
12632 $$dry rm -f elc-stamp; \
12633 $(MAKE) $(AM_MAKEFLAGS) elc-stamp; \
12634 $$dry rmdir elc-lock; \
12636 ## This code is being executed by the follower processes.
12637 ## Wait until the first process is done.
12638 while test -d elc-lock && test -z "$$dry"; do \
12642 ## Succeed if and only if the first process succeeded.
12643 $$dry test -f elc-stamp; exit $$?; \
12648 For completeness it should be noted that GNU @command{make} is able to
12649 express rules with multiple output files using pattern rules
12650 (@pxref{Pattern Examples, , Pattern Rule Examples, make, The GNU Make
12651 Manual}). We do not discuss pattern rules here because they are not
12652 portable, but they can be convenient in packages that assume GNU
12656 @node Hard-Coded Install Paths
12657 @section Installing to Hard-Coded Locations
12660 My package needs to install some configuration file. I tried to use
12661 the following rule, but @samp{make distcheck} fails. Why?
12665 install-data-local:
12666 $(INSTALL_DATA) $(srcdir)/afile $(DESTDIR)/etc/afile
12671 My package needs to populate the installation directory of another
12672 package at install-time. I can easily compute that installation
12673 directory in @file{configure}, but if I install files therein,
12674 @samp{make distcheck} fails. How else should I do?
12677 These two setups share their symptoms: @samp{make distcheck} fails
12678 because they are installing files to hard-coded paths. In the later
12679 case the path is not really hard-coded in the package, but we can
12680 consider it to be hard-coded in the system (or in whichever tool that
12681 supplies the path). As long as the path does not use any of the
12682 standard directory variables (@samp{$(prefix)}, @samp{$(bindir)},
12683 @samp{$(datadir)}, etc.), the effect will be the same:
12684 user-installations are impossible.
12686 As a (non-root) user who wants to install a package, you usually have no
12687 right to install anything in @file{/usr} or @file{/usr/local}. So you
12688 do something like @samp{./configure --prefix ~/usr} to install a
12689 package in your own @file{~/usr} tree.
12691 If a package attempts to install something to some hard-coded path
12692 (e.g., @file{/etc/afile}), regardless of this @option{--prefix} setting,
12693 then the installation will fail. @samp{make distcheck} performs such
12694 a @option{--prefix} installation, hence it will fail too.
12696 Now, there are some easy solutions.
12698 The above @code{install-data-local} example for installing
12699 @file{/etc/afile} would be better replaced by
12702 sysconf_DATA = afile
12706 by default @code{sysconfdir} will be @samp{$(prefix)/etc}, because
12707 this is what the GNU Standards require. When such a package is
12708 installed on an FHS compliant system, the installer will have to set
12709 @samp{--sysconfdir=/etc}. As the maintainer of the package you
12710 should not be concerned by such site policies: use the appropriate
12711 standard directory variable to install your files so that the installer
12712 can easily redefine these variables to match their site conventions.
12714 Installing files that should be used by another package is slightly
12715 more involved. Let's take an example and assume you want to install
12716 a shared library that is a Python extension module. If you ask Python
12717 where to install the library, it will answer something like this:
12720 % @kbd{python -c 'from distutils import sysconfig;
12721 print sysconfig.get_python_lib(1,0)'}
12722 /usr/lib/python2.5/site-packages
12725 If you indeed use this absolute path to install your shared library,
12726 non-root users will not be able to install the package, hence
12729 Let's do better. The @samp{sysconfig.get_python_lib()} function
12730 actually accepts a third argument that will replace Python's
12731 installation prefix.
12734 % @kbd{python -c 'from distutils import sysconfig;
12735 print sysconfig.get_python_lib(1,0,"$@{exec_prefix@}")'}
12736 $@{exec_prefix@}/lib/python2.5/site-packages
12739 You can also use this new path. If you do
12742 root users can install your package with the same @option{--prefix}
12743 as Python (you get the behavior of the previous attempt)
12746 non-root users can install your package too, they will have the
12747 extension module in a place that is not searched by Python but they
12748 can work around this using environment variables (and if you installed
12749 scripts that use this shared library, it's easy to tell Python were to
12750 look in the beginning of your script, so the script works in both
12754 The @code{AM_PATH_PYTHON} macro uses similar commands to define
12755 @samp{$(pythondir)} and @samp{$(pyexecdir)} (@pxref{Python}).
12757 Of course not all tools are as advanced as Python regarding that
12758 substitution of @var{prefix}. So another strategy is to figure the
12759 part of the installation directory that must be preserved. For
12760 instance, here is how @code{AM_PATH_LISPDIR} (@pxref{Emacs Lisp})
12761 computes @samp{$(lispdir)}:
12764 $EMACS -batch -q -eval '(while load-path
12765 (princ (concat (car load-path) "\n"))
12766 (setq load-path (cdr load-path)))' >conftest.out
12769 -e '/.*\/lib\/x*emacs\/site-lisp$/@{
12770 s,.*/lib/\(x*emacs/site-lisp\)$,$@{libdir@}/\1,;p;q;
12772 -e '/.*\/share\/x*emacs\/site-lisp$/@{
12773 s,.*/share/\(x*emacs/site-lisp\),$@{datarootdir@}/\1,;p;q;
12778 I.e., it just picks the first directory that looks like
12779 @file{*/lib/*emacs/site-lisp} or @file{*/share/*emacs/site-lisp} in
12780 the search path of emacs, and then substitutes @samp{$@{libdir@}} or
12781 @samp{$@{datadir@}} appropriately.
12783 The emacs case looks complicated because it processes a list and
12784 expects two possible layouts, otherwise it's easy, and the benefits for
12785 non-root users are really worth the extra @command{sed} invocation.
12788 @node Debugging Make Rules
12789 @section Debugging Make Rules
12790 @cindex debugging rules
12791 @cindex rules, debugging
12793 The rules and dependency trees generated by @command{automake} can get
12794 rather complex, and leave the developer head-scratching when things
12795 don't work as expected. Besides the debug options provided by the
12796 @command{make} command (@pxref{Options Summary,,, make, The GNU Make
12797 Manual}), here's a couple of further hints for debugging makefiles
12798 generated by @command{automake} effectively:
12802 If less verbose output has been enabled in the package with the use
12803 of silent rules (@pxref{Automake Silent Rules}), you can use
12804 @code{make V=1} to see the commands being executed.
12806 @code{make -n} can help show what would be done without actually doing
12807 it. Note however, that this will @emph{still execute} commands prefixed
12808 with @samp{+}, and, when using GNU @command{make}, commands that contain
12809 the strings @samp{$(MAKE)} or @samp{$@{MAKE@}} (@pxref{Instead of
12810 Execution,,, make, The GNU Make Manual}).
12811 Typically, this is helpful to show what recursive rules would do, but it
12812 means that, in your own rules, you should not mix such recursion with
12813 actions that change any files.@footnote{Automake's @samp{dist} and
12814 @samp{distcheck} rules had a bug in this regard in that they created
12815 directories even with @option{-n}, but this has been fixed in Automake
12816 1.11.} Furthermore, note that GNU @command{make} will update
12817 prerequisites for the @file{Makefile} file itself even with @option{-n}
12818 (@pxref{Remaking Makefiles,,, make, The GNU Make Manual}).
12820 @code{make SHELL="/bin/bash -vx"} can help debug complex rules.
12821 @xref{The Make Macro SHELL,,, autoconf, The Autoconf Manual}, for some
12822 portability quirks associated with this construct.
12824 @code{echo 'print: ; @@echo "$(VAR)"' | make -f Makefile -f - print}
12825 can be handy to examine the expanded value of variables. You may need
12826 to use a target other than @samp{print} if that is already used or a
12827 file with that name exists.
12829 @url{http://bashdb.sourceforge.net/@/remake/} provides a modified
12830 GNU @command{make} command called @command{remake} that copes with
12831 complex GNU @command{make}-specific Makefiles and allows to trace
12832 execution, examine variables, and call rules interactively, much like
12837 @node Reporting Bugs
12838 @section Reporting Bugs
12840 Most nontrivial software has bugs. Automake is no exception. Although
12841 we cannot promise we can or will fix a bug, and we might not even agree
12842 that it is a bug, we want to hear about problems you encounter. Often we
12843 agree they are bugs and want to fix them.
12845 To make it possible for us to fix a bug, please report it. In order to
12846 do so effectively, it helps to know when and how to do it.
12848 Before reporting a bug, it is a good idea to see if it is already known.
12849 You can look at the @uref{http://debbugs.gnu.org/, GNU Bug Tracker}
12850 and the @uref{http://lists.gnu.org/@/archive/@/html/@/bug-automake/,
12851 bug-automake mailing list archives} for previous bug reports. We
12853 @uref{http://sourceware.org/@/cgi-bin/@/gnatsweb.pl?database=automake,
12854 Gnats database} for bug tracking, so some bugs might have been reported
12855 there already. Please do not use it for new bug reports, however.
12857 If the bug is not already known, it should be reported. It is very
12858 important to report bugs in a way that is useful and efficient. For
12859 this, please familiarize yourself with
12860 @uref{http://www.chiark.greenend.org.uk/@/~sgtatham/@/bugs.html, How to
12861 Report Bugs Effectively} and
12862 @uref{http://catb.org/@/~esr/@/faqs/@/smart-questions.html, How to Ask
12863 Questions the Smart Way}. This helps you and developers to save time
12864 which can then be spent on fixing more bugs and implementing more
12867 For a bug report, a feature request or other suggestions, please send
12868 email to @email{@value{PACKAGE_BUGREPORT}}. This will then open a new
12869 bug in the @uref{http://debbugs.gnu.org/@/automake, bug tracker}. Be
12870 sure to include the versions of Autoconf and Automake that you use.
12871 Ideally, post a minimal @file{Makefile.am} and @file{configure.ac} that
12872 reproduces the problem you encounter. If you have encountered test
12873 suite failures, please attach the @file{tests/test-suite.log} file.
12875 @c ========================================================== Appendices
12878 @node Copying This Manual
12879 @appendix Copying This Manual
12882 * GNU Free Documentation License:: License for copying this manual
12885 @node GNU Free Documentation License
12886 @appendixsec GNU Free Documentation License
12894 * Macro Index:: Index of Autoconf macros
12895 * Variable Index:: Index of Makefile variables
12896 * General Index:: General index
12900 @appendixsec Macro Index
12904 @node Variable Index
12905 @appendixsec Variable Index
12909 @node General Index
12910 @appendixsec General Index
12917 @c LocalWords: texinfo setfilename settitle setchapternewpage texi direntry
12918 @c LocalWords: dircategory in's aclocal ifinfo titlepage Tromey vskip pt sp
12919 @c LocalWords: filll defcodeindex ov cv op tr syncodeindex fn cp vr ifnottex
12920 @c LocalWords: dir Automake's ac Dist Gnits gnits dfn Autoconf's pxref
12921 @c LocalWords: cindex Autoconf autoconf perl samp cvs dist trindex SUBST foo
12922 @c LocalWords: xs emph FIXME ref vindex pkglibdir pkgincludedir pkgdatadir mt
12923 @c LocalWords: pkg libdir cpio bindir sbindir rmt pax sbin zar zardir acindex
12924 @c LocalWords: HTML htmldir html noinst TEXINFOS nodist nobase strudel CFLAGS
12925 @c LocalWords: libmumble CC YFLAGS itemx de fication config url comp
12926 @c LocalWords: depcomp elisp sh mdate mkinstalldirs mkdir py tex dvi ps pdf
12927 @c LocalWords: ylwrap zardoz INIT gettext acinclude mv FUNCS LIBOBJS LDADD fr
12928 @c LocalWords: uref featureful dnl src LINGUAS es ko nl pl sl sv PROG ISC doc
12929 @c LocalWords: POSIX STDC fcntl FUNC ALLOCA blksize struct stat intl po chmod
12930 @c LocalWords: ChangeLog SUBDIRS gettextize gpl testdata getopt INTLLIBS cpp
12931 @c LocalWords: localedir datadir DLOCALEDIR DEXIT CPPFLAGS autoreconf opindex
12932 @c LocalWords: AUX var symlink deps Wno Wnone package's aclocal's distclean
12933 @c LocalWords: ltmain xref LIBSOURCE LIBSOURCES LIBOBJ MEMCMP vs RANLIB CXX
12934 @c LocalWords: LDFLAGS LIBTOOL libtool XTRA LIBS gettext's acdir APIVERSION
12935 @c LocalWords: dirlist noindent usr TIOCGWINSZ sc
12936 @c LocalWords: GWINSZ termios SRCDIR tarball bzip LISPDIR lispdir XEmacs CCAS
12937 @c LocalWords: emacsen MicroEmacs CCASFLAGS UX GCJ gcj GCJFLAGS posix DMALLOC
12938 @c LocalWords: dmalloc ldmalloc REGEX regex DEPDIR DEP DEFUN aclocaldir fi
12939 @c LocalWords: mymacro myothermacro AMFLAGS autopoint autogen libtoolize yum
12940 @c LocalWords: autoheader README MAKEFLAGS subdir Inetutils sync COND endif
12941 @c LocalWords: Miller's installable includedir inc pkgdata EXEEXT libexec bsd
12942 @c LocalWords: pkglib libexecdir prog libcpio cpio's dlopen dlpreopen linux
12943 @c LocalWords: subsubsection OBJEXT esac lib LTLIBRARIES liblob LIBADD AR ar
12944 @c LocalWords: ARFLAGS cru ing maude libgettext lo LTLIBOBJS rpath SGI PRE yy
12945 @c LocalWords: libmaude CCLD CXXFLAGS FFLAGS LFLAGS OBJCFLAGS RFLAGS DEFS cc
12946 @c LocalWords: SHORTNAME vtable srcdir nostdinc basename yxx cxx ll lxx gdb
12947 @c LocalWords: lexers yymaxdepth maxdepth yyparse yylex yyerror yylval lval
12948 @c LocalWords: yychar yydebug yypact yyr yydef def yychk chk yypgo pgo yyact
12949 @c LocalWords: yyexca exca yyerrflag errflag yynerrs nerrs yyps yypv pv yys
12950 @c LocalWords: yystate yytmp tmp yyv yyval val yylloc lloc yyreds yytoks toks
12951 @c LocalWords: yylhs yylen yydefred yydgoto yysindex yyrindex yygindex yyname
12952 @c LocalWords: yytable yycheck yyrule byacc CXXCOMPILE CXXLINK FLINK cfortran
12953 @c LocalWords: Catalogue preprocessable FLIBS libfoo baz JAVACFLAGS java exe
12954 @c LocalWords: SunOS fying basenames exeext uninstalled oldinclude kr FSF's
12955 @c LocalWords: pkginclude oldincludedir sysconf sharedstate localstate gcc rm
12956 @c LocalWords: sysconfdir sharedstatedir localstatedir preexist CLEANFILES gz
12957 @c LocalWords: depfile tmpdepfile depmode const interoperate
12958 @c LocalWords: JAVAC javac JAVAROOT builddir CLASSPATH ENV pyc pyo pkgpython
12959 @c LocalWords: pyexecdir pkgpyexecdir Python's pythondir pkgpythondir txi ois
12960 @c LocalWords: installinfo vers MAKEINFO makeinfo MAKEINFOFLAGS noinstall rf
12961 @c LocalWords: mandir thesame alsothesame installman myexecbin DESTDIR Pinard
12962 @c LocalWords: uninstall installdirs uninstalls MOSTLYCLEANFILES mostlyclean
12963 @c LocalWords: DISTCLEANFILES MAINTAINERCLEANFILES GZIP gzip shar exp
12964 @c LocalWords: distdir distcheck distcleancheck listfiles distuninstallcheck
12965 @c LocalWords: VPATH tarfile stdout XFAIL DejaGnu dejagnu DEJATOOL runtest ln
12966 @c LocalWords: RUNTESTDEFAULTFLAGS toolchain RUNTESTFLAGS asis readme DVIPS
12967 @c LocalWords: installcheck gzipped tarZ std utils etags mkid cd
12968 @c LocalWords: ARGS taggable ETAGSFLAGS lang ctags CTAGSFLAGS GTAGS gtags idl
12969 @c LocalWords: foocc doit idlC multilibs ABIs cmindex defmac ARG enableval FC
12970 @c LocalWords: MSG xtrue DBG pathchk CYGWIN afile proglink versioned CVS's TE
12971 @c LocalWords: wildcards Autoconfiscated subsubheading autotools Meyering API
12972 @c LocalWords: ois's wildcard Wportability cartouche vrindex printindex Duret
12973 @c LocalWords: DSOMEFLAG DVERSION automake Lutz insertcopying versioning FAQ
12974 @c LocalWords: LTLIBOBJ Libtool's libtool's libltdl dlopening itutions libbar
12975 @c LocalWords: WANTEDLIBS libhello sublibraries libtop libsub dlopened Ratfor
12976 @c LocalWords: mymodule timestamps timestamp underquoted MAKEINFOHTMLFLAGS te
12977 @c LocalWords: GNUmakefile Subpackages subpackage's subpackages aux
12978 @c LocalWords: detailmenu Timeline pwd reldir AUTOM autom PREREQ FOOBAR libc
12979 @c LocalWords: libhand subpackage moduleN libmain libmisc FCFLAGS FCCOMPILE
12980 @c LocalWords: FCLINK subst sed ELCFILES elc MAKEINFOHTML dvips esyscmd ustar
12981 @c LocalWords: tarballs Woverride vfi ELFILES djm AutoMake honkin FSF
12982 @c LocalWords: fileutils precanned MacKenzie's reimplement termutils Tromey's
12983 @c LocalWords: cois gnitsians LIBPROGRAMS progs LIBLIBRARIES Textutils Ulrich
12984 @c LocalWords: Matzigkeit Drepper's Gord Matzigkeit's jm Dalley Debian org
12985 @c LocalWords: Administrivia ILU CORBA Sourceware Molenda sourceware Elliston
12986 @c LocalWords: dep Oliva Akim Demaille Aiieeee Demaillator Akim's sourcequake
12987 @c LocalWords: grep backported screenshots libgcj KB unnumberedsubsubsec pre
12988 @c LocalWords: precomputing hacky makedepend inline clearmake LD PRELOAD Rel
12989 @c LocalWords: syscalls perlhist acl pm multitable headitem fdl appendixsec
12990 @c LocalWords: LTALLOCA MALLOC malloc memcmp strdup alloca libcompat xyz DFOO
12991 @c LocalWords: unprefixed buildable preprocessed DBAZ DDATADIR WARNINGCFLAGS
12992 @c LocalWords: LIBFOOCFLAGS LIBFOOLDFLAGS ftable testSubDir obj LIBTOOLFLAGS
12993 @c LocalWords: barexec Pinard's automatize initialize lzip xz cscope