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 * Objective C++ Support:: Compiling Objective C++ sources
222 * Unified Parallel C Support:: Compiling Unified Parallel C sources
223 * Assembly Support:: Compiling assembly sources
224 * Fortran 77 Support:: Compiling Fortran 77 sources
225 * Fortran 9x Support:: Compiling Fortran 9x sources
226 * Java Support with gcj:: Compiling Java sources using gcj
227 * Vala Support:: Compiling Vala sources
228 * Support for Other Languages:: Compiling other languages
229 * Dependencies:: Automatic dependency tracking
230 * EXEEXT:: Support for executable extensions
234 * Program Sources:: Defining program sources
235 * Linking:: Linking with libraries or extra objects
236 * Conditional Sources:: Handling conditional sources
237 * Conditional Programs:: Building a program conditionally
239 Building a Shared Library
241 * Libtool Concept:: Introducing Libtool
242 * Libtool Libraries:: Declaring Libtool Libraries
243 * Conditional Libtool Libraries:: Building Libtool Libraries Conditionally
244 * Conditional Libtool Sources:: Choosing Library Sources Conditionally
245 * Libtool Convenience Libraries:: Building Convenience Libtool Libraries
246 * Libtool Modules:: Building Libtool Modules
247 * Libtool Flags:: Using _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS
248 * LTLIBOBJS:: Using $(LTLIBOBJS) and $(LTALLOCA)
249 * Libtool Issues:: Common Issues Related to Libtool's Use
251 Common Issues Related to Libtool's Use
253 * Error required file ltmain.sh not found:: The need to run libtoolize
254 * Objects created both with libtool and without:: Avoid a specific build race
258 * Preprocessing Fortran 77:: Preprocessing Fortran 77 sources
259 * Compiling Fortran 77 Files:: Compiling Fortran 77 sources
260 * Mixing Fortran 77 With C and C++:: Mixing Fortran 77 With C and C++
262 Mixing Fortran 77 With C and C++
264 * How the Linker is Chosen:: Automatic linker selection
268 * Compiling Fortran 9x Files:: Compiling Fortran 9x sources
270 Other Derived Objects
272 * Scripts:: Executable scripts
273 * Headers:: Header files
274 * Data:: Architecture-independent data files
275 * Sources:: Derived sources
279 * Built Sources Example:: Several ways to handle built sources.
283 * Emacs Lisp:: Emacs Lisp
286 * Java:: Java bytecode compilation (deprecated)
289 Building documentation
292 * Man Pages:: Man pages
296 * Basics of Installation:: What gets installed where
297 * The Two Parts of Install:: Installing data and programs separately
298 * Extending Installation:: Adding your own rules for installation
299 * Staged Installs:: Installation in a temporary location
300 * Install Rules for the User:: Useful additional rules
302 What Goes in a Distribution
304 * Basics of Distribution:: Files distributed by default
305 * Fine-grained Distribution Control:: @code{dist_} and @code{nodist_} prefixes
306 * The dist Hook:: A target for last-minute distribution changes
307 * Checking the Distribution:: @samp{make distcheck} explained
308 * The Types of Distributions:: A variety of formats and compression methods
310 Support for test suites
312 * Generalities about Testing:: Generic concepts and terminology about testing
313 * Simple Tests:: Listing test scripts in @code{TESTS}
314 * Custom Test Drivers:: Writing and using custom test drivers
315 * Using the TAP test protocol:: Integrating test scripts that use the TAP protocol
316 * DejaGnu Tests:: Interfacing with the @command{dejagnu} testing framework
317 * Install Tests:: Running tests on installed packages
321 * Scripts-based Testsuites:: Automake-specific concepts and terminology
322 * Serial Test Harness:: Older (and obsolescent) serial test harness
323 * Parallel Test Harness:: Generic concurrent test harness
325 Using the TAP test protocol
327 * Introduction to TAP::
328 * Use TAP with the Automake test harness::
329 * Incompatibilities with other TAP parsers and drivers::
330 * Links and external resources on TAP::
334 * Overview of Custom Test Drivers Support::
335 * Declaring Custom Test Drivers::
336 * API for Custom Test Drivers::
338 API for Custom Test Drivers
340 * Command-line arguments for test drivers::
341 * Log files generation and test results recording::
342 * Testsuite progress output::
344 Changing Automake's Behavior
346 * Options generalities:: Semantics of Automake option
347 * List of Automake options:: A comprehensive list of Automake options
351 * Tags:: Interfacing to cscope, etags and mkid
352 * Suffixes:: Handling new file extensions
356 * Usage of Conditionals:: Declaring conditional content
357 * Limits of Conditionals:: Enclosing complete statements
361 * Make verbosity:: Make is verbose by default
362 * Tricks For Silencing Make:: Standard and generic ways to silence make
363 * Automake Silent Rules:: How Automake can help in silencing make
365 When Automake Isn't Enough
367 * Extending:: Adding new rules or overriding existing ones.
368 * Third-Party Makefiles:: Integrating Non-Automake @file{Makefile}s.
370 Frequently Asked Questions about Automake
372 * CVS:: CVS and generated files
373 * maintainer-mode:: missing and AM_MAINTAINER_MODE
374 * Wildcards:: Why doesn't Automake support wildcards?
375 * Limitations on File Names:: Limitations on source and installed file names
376 * Errors with distclean:: Files left in build directory after distclean
377 * Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS
378 * Renamed Objects:: Why are object files sometimes renamed?
379 * Per-Object Flags:: How to simulate per-object flags?
380 * Multiple Outputs:: Writing rules for tools with many output files
381 * Hard-Coded Install Paths:: Installing to hard-coded locations
382 * Debugging Make Rules:: Strategies when things don't work as expected
383 * Reporting Bugs:: Feedback on bugs and feature requests
387 * GNU Free Documentation License:: License for copying this manual
391 * Macro Index:: Index of Autoconf macros
392 * Variable Index:: Index of Makefile variables
393 * General Index:: General index
402 @chapter Introduction
404 Automake is a tool for automatically generating @file{Makefile.in}s
405 from files called @file{Makefile.am}. Each @file{Makefile.am} is
406 basically a series of @command{make} variable
407 definitions@footnote{These variables are also called @dfn{make macros}
408 in Make terminology, however in this manual we reserve the term
409 @dfn{macro} for Autoconf's macros.}, with rules being thrown in
410 occasionally. The generated @file{Makefile.in}s are compliant with
411 the GNU Makefile standards.
413 @cindex GNU Makefile standards
415 The GNU Makefile Standards Document
416 (@pxref{Makefile Conventions, , , standards, The GNU Coding Standards})
417 is long, complicated, and subject to change. The goal of Automake is to
418 remove the burden of Makefile maintenance from the back of the
419 individual GNU maintainer (and put it on the back of the Automake
422 The typical Automake input file is simply a series of variable definitions.
423 Each such file is processed to create a @file{Makefile.in}. There
424 should generally be one @file{Makefile.am} per directory of a project.
426 @cindex Constraints of Automake
427 @cindex Automake constraints
429 Automake does constrain a project in certain ways; for instance, it
430 assumes that the project uses Autoconf (@pxref{Top, , Introduction,
431 autoconf, The Autoconf Manual}), and enforces certain restrictions on
432 the @file{configure.ac} contents.
434 @cindex Automake requirements
435 @cindex Requirements, Automake
437 Automake requires @command{perl} in order to generate the
438 @file{Makefile.in}s. However, the distributions created by Automake are
439 fully GNU standards-compliant, and do not require @command{perl} in order
442 @cindex Bugs, reporting
443 @cindex Reporting bugs
444 @cindex E-mail, bug reports
446 For more information on bug reports, @xref{Reporting Bugs}.
448 @node Autotools Introduction
449 @chapter An Introduction to the Autotools
451 If you are new to Automake, maybe you know that it is part of a set of
452 tools called @emph{The Autotools}. Maybe you've already delved into a
453 package full of files named @file{configure}, @file{configure.ac},
454 @file{Makefile.in}, @file{Makefile.am}, @file{aclocal.m4}, @dots{},
455 some of them claiming to be @emph{generated by} Autoconf or Automake.
456 But the exact purpose of these files and their relations is probably
457 fuzzy. The goal of this chapter is to introduce you to this machinery,
458 to show you how it works and how powerful it is. If you've never
459 installed or seen such a package, do not worry: this chapter will walk
462 If you need some teaching material, more illustrations, or a less
463 @command{automake}-centered continuation, some slides for this
464 introduction are available in Alexandre Duret-Lutz's
465 @uref{http://www.lrde.epita.fr/@/~adl/@/autotools.html,
467 This chapter is the written version of the first part of his tutorial.
470 * GNU Build System:: Introducing the GNU Build System
471 * Use Cases:: Use Cases for the GNU Build System
472 * Why Autotools:: How Autotools Help
473 * Hello World:: A Small Hello World Package
476 @node GNU Build System
477 @section Introducing the GNU Build System
478 @cindex GNU Build System, introduction
480 It is a truth universally acknowledged, that as a developer in
481 possession of a new package, you must be in want of a build system.
483 In the Unix world, such a build system is traditionally achieved using
484 the command @command{make} (@pxref{Top, , Overview, make, The GNU Make
485 Manual}). You express the recipe to build your package in a
486 @file{Makefile}. This file is a set of rules to build the files in
487 the package. For instance the program @file{prog} may be built by
488 running the linker on the files @file{main.o}, @file{foo.o}, and
489 @file{bar.o}; the file @file{main.o} may be built by running the
490 compiler on @file{main.c}; etc. Each time @command{make} is run, it
491 reads @file{Makefile}, checks the existence and modification time of
492 the files mentioned, decides what files need to be built (or rebuilt),
493 and runs the associated commands.
495 When a package needs to be built on a different platform than the one
496 it was developed on, its @file{Makefile} usually needs to be adjusted.
497 For instance the compiler may have another name or require more
498 options. In 1991, David J. MacKenzie got tired of customizing
499 @file{Makefile} for the 20 platforms he had to deal with. Instead, he
500 handcrafted a little shell script called @file{configure} to
501 automatically adjust the @file{Makefile} (@pxref{Genesis, , Genesis,
502 autoconf, The Autoconf Manual}). Compiling his package was now
503 as simple as running @code{./configure && make}.
505 @cindex GNU Coding Standards
507 Today this process has been standardized in the GNU project. The GNU
508 Coding Standards (@pxref{Managing Releases, The Release Process, ,
509 standards, The GNU Coding Standards}) explains how each package of the
510 GNU project should have a @file{configure} script, and the minimal
511 interface it should have. The @file{Makefile} too should follow some
512 established conventions. The result? A unified build system that
513 makes all packages almost indistinguishable by the installer. In its
514 simplest scenario, all the installer has to do is to unpack the
515 package, run @code{./configure && make && make install}, and repeat
516 with the next package to install.
518 We call this build system the @dfn{GNU Build System}, since it was
519 grown out of the GNU project. However it is used by a vast number of
520 other packages: following any existing convention has its advantages.
522 @cindex Autotools, introduction
524 The Autotools are tools that will create a GNU Build System for your
525 package. Autoconf mostly focuses on @file{configure} and Automake on
526 @file{Makefile}s. It is entirely possible to create a GNU Build
527 System without the help of these tools. However it is rather
528 burdensome and error-prone. We will discuss this again after some
529 illustration of the GNU Build System in action.
532 @section Use Cases for the GNU Build System
533 @cindex GNU Build System, use cases
534 @cindex GNU Build System, features
535 @cindex Features of the GNU Build System
536 @cindex Use Cases for the GNU Build System
537 @cindex @file{amhello-1.0.tar.gz}, location
538 @cindex @file{amhello-1.0.tar.gz}, use cases
540 In this section we explore several use cases for the GNU Build System.
541 You can replay all of these examples on the @file{amhello-1.0.tar.gz}
542 package distributed with Automake. If Automake is installed on your
543 system, you should find a copy of this file in
544 @file{@var{prefix}/share/doc/automake/amhello-1.0.tar.gz}, where
545 @var{prefix} is the installation prefix specified during configuration
546 (@var{prefix} defaults to @file{/usr/local}, however if Automake was
547 installed by some GNU/Linux distribution it most likely has been set
548 to @file{/usr}). If you do not have a copy of Automake installed,
549 you can find a copy of this file inside the @file{doc/} directory of
550 the Automake package.
552 Some of the following use cases present features that are in fact
553 extensions to the GNU Build System. Read: they are not specified by
554 the GNU Coding Standards, but they are nonetheless part of the build
555 system created by the Autotools. To keep things simple, we do not
556 point out the difference. Our objective is to show you many of the
557 features that the build system created by the Autotools will offer to
561 * Basic Installation:: Common installation procedure
562 * Standard Targets:: A list of standard Makefile targets
563 * Standard Directory Variables:: A list of standard directory variables
564 * Standard Configuration Variables:: Using configuration variables
565 * config.site:: Using a config.site file
566 * VPATH Builds:: Parallel build trees
567 * Two-Part Install:: Installing data and programs separately
568 * Cross-Compilation:: Building for other architectures
569 * Renaming:: Renaming programs at install time
570 * DESTDIR:: Building binary packages with DESTDIR
571 * Preparing Distributions:: Rolling out tarballs
572 * Dependency Tracking:: Automatic dependency tracking
573 * Nested Packages:: The GNU Build Systems can be nested
576 @node Basic Installation
577 @subsection Basic Installation
578 @cindex Configuration, basics
579 @cindex Installation, basics
580 @cindex GNU Build System, basics
582 The most common installation procedure looks as follows.
585 ~ % @kbd{tar zxf amhello-1.0.tar.gz}
586 ~ % @kbd{cd amhello-1.0}
587 ~/amhello-1.0 % @kbd{./configure}
589 config.status: creating Makefile
590 config.status: creating src/Makefile
592 ~/amhello-1.0 % @kbd{make}
594 ~/amhello-1.0 % @kbd{make check}
596 ~/amhello-1.0 % @kbd{su}
598 /home/adl/amhello-1.0 # @kbd{make install}
600 /home/adl/amhello-1.0 # @kbd{exit}
601 ~/amhello-1.0 % @kbd{make installcheck}
607 The user first unpacks the package. Here, and in the following
608 examples, we will use the non-portable @code{tar zxf} command for
609 simplicity. On a system without GNU @command{tar} installed, this
610 command should read @code{gunzip -c amhello-1.0.tar.gz | tar xf -}.
612 The user then enters the newly created directory to run the
613 @file{configure} script. This script probes the system for various
614 features, and finally creates the @file{Makefile}s. In this toy
615 example there are only two @file{Makefile}s, but in real-world projects,
616 there may be many more, usually one @file{Makefile} per directory.
618 It is now possible to run @code{make}. This will construct all the
619 programs, libraries, and scripts that need to be constructed for the
620 package. In our example, this compiles the @file{hello} program.
621 All files are constructed in place, in the source tree; we will see
622 later how this can be changed.
624 @code{make check} causes the package's tests to be run. This step is
625 not mandatory, but it is often good to make sure the programs that
626 have been built behave as they should, before you decide to install
627 them. Our example does not contain any tests, so running @code{make
630 @cindex su, before @code{make install}
631 After everything has been built, and maybe tested, it is time to
632 install it on the system. That means copying the programs,
633 libraries, header files, scripts, and other data files from the
634 source directory to their final destination on the system. The
635 command @code{make install} will do that. However, by default
636 everything will be installed in subdirectories of @file{/usr/local}:
637 binaries will go into @file{/usr/local/bin}, libraries will end up in
638 @file{/usr/local/lib}, etc. This destination is usually not writable
639 by any user, so we assume that we have to become root before we can
640 run @code{make install}. In our example, running @code{make install}
641 will copy the program @file{hello} into @file{/usr/local/bin}
642 and @file{README} into @file{/usr/local/share/doc/amhello}.
644 A last and optional step is to run @code{make installcheck}. This
645 command may run tests on the installed files. @code{make check} tests
646 the files in the source tree, while @code{make installcheck} tests
647 their installed copies. The tests run by the latter can be different
648 from those run by the former. For instance, there are tests that
649 cannot be run in the source tree. Conversely, some packages are set
650 up so that @code{make installcheck} will run the very same tests as
651 @code{make check}, only on different files (non-installed
652 vs.@: installed). It can make a difference, for instance when the
653 source tree's layout is different from that of the installation.
654 Furthermore it may help to diagnose an incomplete installation.
656 Presently most packages do not have any @code{installcheck} tests
657 because the existence of @code{installcheck} is little known, and its
658 usefulness is neglected. Our little toy package is no better: @code{make
659 installcheck} does nothing.
661 @node Standard Targets
662 @subsection Standard @file{Makefile} Targets
664 So far we have come across four ways to run @command{make} in the GNU
665 Build System: @code{make}, @code{make check}, @code{make install}, and
666 @code{make installcheck}. The words @code{check}, @code{install}, and
667 @code{installcheck}, passed as arguments to @command{make}, are called
668 @dfn{targets}. @code{make} is a shorthand for @code{make all},
669 @code{all} being the default target in the GNU Build System.
671 Here is a list of the most useful targets that the GNU Coding Standards
677 Build programs, libraries, documentation, etc.@: (same as @code{make}).
680 Install what needs to be installed, copying the files from the
681 package's tree to system-wide directories.
682 @item make install-strip
683 @trindex install-strip
684 Same as @code{make install}, then strip debugging symbols. Some
685 users like to trade space for useful bug reports@enddots{}
688 The opposite of @code{make install}: erase the installed files.
689 (This needs to be run from the same build tree that was installed.)
692 Erase from the build tree the files built by @code{make all}.
695 Additionally erase anything @code{./configure} created.
698 Run the test suite, if any.
699 @item make installcheck
700 @trindex installcheck
701 Check the installed programs or libraries, if supported.
704 Recreate @file{@var{package}-@var{version}.tar.gz} from all the source
708 @node Standard Directory Variables
709 @subsection Standard Directory Variables
710 @cindex directory variables
712 The GNU Coding Standards also specify a hierarchy of variables to
713 denote installation directories. Some of these are:
715 @multitable {Directory variable} {@code{$@{datarootdir@}/doc/$@{PACKAGE@}}}
716 @headitem Directory variable @tab Default value
717 @item @code{prefix} @tab @code{/usr/local}
718 @item @w{@ @ @code{exec_prefix}} @tab @code{$@{prefix@}}
719 @item @w{@ @ @ @ @code{bindir}} @tab @code{$@{exec_prefix@}/bin}
720 @item @w{@ @ @ @ @code{libdir}} @tab @code{$@{exec_prefix@}/lib}
721 @item @w{@ @ @ @ @dots{}}
722 @item @w{@ @ @code{includedir}} @tab @code{$@{prefix@}/include}
723 @item @w{@ @ @code{datarootdir}} @tab @code{$@{prefix@}/share}
724 @item @w{@ @ @ @ @code{datadir}} @tab @code{$@{datarootdir@}}
725 @item @w{@ @ @ @ @code{mandir}} @tab @code{$@{datarootdir@}/man}
726 @item @w{@ @ @ @ @code{infodir}} @tab @code{$@{datarootdir@}/info}
727 @item @w{@ @ @ @ @code{docdir}} @tab @code{$@{datarootdir@}/doc/$@{PACKAGE@}}
728 @item @w{@ @ @dots{}}
731 @c We should provide a complete table somewhere, but not here. The
732 @c complete list of directory variables it too confusing as-is. It
733 @c requires some explanations that are too complicated for this
734 @c introduction. Besides listing directories like localstatedir
735 @c would make the explanations in ``Two-Part Install'' harder.
737 Each of these directories has a role which is often obvious from its
738 name. In a package, any installable file will be installed in one of
739 these directories. For instance in @code{amhello-1.0}, the program
740 @file{hello} is to be installed in @var{bindir}, the directory for
741 binaries. The default value for this directory is
742 @file{/usr/local/bin}, but the user can supply a different value when
743 calling @command{configure}. Also the file @file{README} will be
744 installed into @var{docdir}, which defaults to
745 @file{/usr/local/share/doc/amhello}.
749 As a user, if you wish to install a package on your own account, you
750 could proceed as follows:
753 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr}
755 ~/amhello-1.0 % @kbd{make}
757 ~/amhello-1.0 % @kbd{make install}
761 This would install @file{~/usr/bin/hello} and
762 @file{~/usr/share/doc/amhello/README}.
764 The list of all such directory options is shown by
765 @code{./configure --help}.
767 @node Standard Configuration Variables
768 @subsection Standard Configuration Variables
769 @cindex configuration variables, overriding
771 The GNU Coding Standards also define a set of standard configuration
772 variables used during the build. Here are some:
781 @item @code{CXXFLAGS}
785 @item @code{CPPFLAGS}
786 C/C++ preprocessor flags
790 @command{configure} usually does a good job at setting appropriate
791 values for these variables, but there are cases where you may want to
792 override them. For instance you may have several versions of a
793 compiler installed and would like to use another one, you may have
794 header files installed outside the default search path of the
795 compiler, or even libraries out of the way of the linker.
797 Here is how one would call @command{configure} to force it to use
798 @command{gcc-3} as C compiler, use header files from
799 @file{~/usr/include} when compiling, and libraries from
800 @file{~/usr/lib} when linking.
803 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr CC=gcc-3 \
804 CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib}
807 Again, a full list of these variables appears in the output of
808 @code{./configure --help}.
811 @subsection Overriding Default Configuration Setting with @file{config.site}
812 @cindex @file{config.site} example
814 When installing several packages using the same setup, it can be
815 convenient to create a file to capture common settings.
816 If a file named @file{@var{prefix}/share/config.site} exists,
817 @command{configure} will source it at the beginning of its execution.
819 Recall the command from the previous section:
822 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr CC=gcc-3 \
823 CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib}
826 Assuming we are installing many package in @file{~/usr}, and will
827 always want to use these definitions of @code{CC}, @code{CPPFLAGS}, and
828 @code{LDFLAGS}, we can automate this by creating the following
829 @file{~/usr/share/config.site} file:
832 test -z "$CC" && CC=gcc-3
833 test -z "$CPPFLAGS" && CPPFLAGS=-I$HOME/usr/include
834 test -z "$LDFLAGS" && LDFLAGS=-L$HOME/usr/lib
837 Now, any time a @file{configure} script is using the @file{~/usr}
838 prefix, it will execute the above @file{config.site} and define
839 these three variables.
842 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr}
843 configure: loading site script /home/adl/usr/share/config.site
847 @xref{Site Defaults, , Setting Site Defaults, autoconf, The Autoconf
848 Manual}, for more information about this feature.
852 @subsection Parallel Build Trees (a.k.a.@: VPATH Builds)
853 @cindex Parallel build trees
855 @cindex source tree and build tree
856 @cindex build tree and source tree
857 @cindex trees, source vs.@: build
859 The GNU Build System distinguishes two trees: the source tree, and
862 The source tree is rooted in the directory containing
863 @file{configure}. It contains all the sources files (those that are
864 distributed), and may be arranged using several subdirectories.
866 The build tree is rooted in the directory in which @file{configure}
867 was run, and is populated with all object files, programs, libraries,
868 and other derived files built from the sources (and hence not
869 distributed). The build tree usually has the same subdirectory layout
870 as the source tree; its subdirectories are created automatically by
873 If @file{configure} is executed in its own directory, the source and
874 build trees are combined: derived files are constructed in the same
875 directories as their sources. This was the case in our first
876 installation example (@pxref{Basic Installation}).
878 A common request from users is that they want to confine all derived
879 files to a single directory, to keep their source directories
880 uncluttered. Here is how we could run @file{configure} to build
881 everything in a subdirectory called @file{build/}.
884 ~ % @kbd{tar zxf ~/amhello-1.0.tar.gz}
885 ~ % @kbd{cd amhello-1.0}
886 ~/amhello-1.0 % @kbd{mkdir build && cd build}
887 ~/amhello-1.0/build % @kbd{../configure}
889 ~/amhello-1.0/build % @kbd{make}
893 These setups, where source and build trees are different, are often
894 called @dfn{parallel builds} or @dfn{VPATH builds}. The expression
895 @emph{parallel build} is misleading: the word @emph{parallel} is a
896 reference to the way the build tree shadows the source tree, it is not
897 about some concurrency in the way build commands are run. For this
898 reason we refer to such setups using the name @emph{VPATH builds} in
899 the following. @emph{VPATH} is the name of the @command{make} feature
900 used by the @file{Makefile}s to allow these builds (@pxref{General
901 Search, , @code{VPATH} Search Path for All Prerequisites, make, The
904 @cindex multiple configurations, example
905 @cindex debug build, example
906 @cindex optimized build, example
908 VPATH builds have other interesting uses. One is to build the same
909 sources with multiple configurations. For instance:
911 @c Keep in sync with amhello-cflags.sh
913 ~ % @kbd{tar zxf ~/amhello-1.0.tar.gz}
914 ~ % @kbd{cd amhello-1.0}
915 ~/amhello-1.0 % @kbd{mkdir debug optim && cd debug}
916 ~/amhello-1.0/debug % @kbd{../configure CFLAGS='-g -O0'}
918 ~/amhello-1.0/debug % @kbd{make}
920 ~/amhello-1.0/debug % cd ../optim
921 ~/amhello-1.0/optim % @kbd{../configure CFLAGS='-O3 -fomit-frame-pointer'}
923 ~/amhello-1.0/optim % @kbd{make}
927 With network file systems, a similar approach can be used to build the
928 same sources on different machines. For instance, suppose that the
929 sources are installed on a directory shared by two hosts: @code{HOST1}
930 and @code{HOST2}, which may be different platforms.
933 ~ % @kbd{cd /nfs/src}
934 /nfs/src % @kbd{tar zxf ~/amhello-1.0.tar.gz}
937 On the first host, you could create a local build directory:
939 [HOST1] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
940 [HOST1] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure}
942 [HOST1] /tmp/amh % @kbd{make && sudo make install}
947 (Here we assume that the installer has configured @command{sudo} so it
948 can execute @code{make install} with root privileges; it is more convenient
949 than using @command{su} like in @ref{Basic Installation}).
951 On the second host, you would do exactly the same, possibly at
954 [HOST2] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
955 [HOST2] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure}
957 [HOST2] /tmp/amh % @kbd{make && sudo make install}
961 @cindex read-only source tree
962 @cindex source tree, read-only
964 In this scenario, nothing forbids the @file{/nfs/src/amhello-1.0}
965 directory from being read-only. In fact VPATH builds are also a means
966 of building packages from a read-only medium such as a CD-ROM. (The
967 FSF used to sell CD-ROM with unpacked source code, before the GNU
968 project grew so big.)
970 @node Two-Part Install
971 @subsection Two-Part Installation
973 In our last example (@pxref{VPATH Builds}), a source tree was shared
974 by two hosts, but compilation and installation were done separately on
977 The GNU Build System also supports networked setups where part of the
978 installed files should be shared amongst multiple hosts. It does so
979 by distinguishing architecture-dependent files from
980 architecture-independent files, and providing two @file{Makefile}
981 targets to install each of these classes of files.
983 @trindex install-exec
984 @trindex install-data
986 These targets are @code{install-exec} for architecture-dependent files
987 and @code{install-data} for architecture-independent files.
988 The command we used up to now, @code{make install}, can be thought of
989 as a shorthand for @code{make install-exec install-data}.
991 From the GNU Build System point of view, the distinction between
992 architecture-dependent files and architecture-independent files is
993 based exclusively on the directory variable used to specify their
994 installation destination. In the list of directory variables we
995 provided earlier (@pxref{Standard Directory Variables}), all the
996 variables based on @var{exec-prefix} designate architecture-dependent
997 directories whose files will be installed by @code{make install-exec}.
998 The others designate architecture-independent directories and will
999 serve files installed by @code{make install-data}. @xref{The Two Parts
1000 of Install}, for more details.
1002 Here is how we could revisit our two-host installation example,
1003 assuming that (1) we want to install the package directly in
1004 @file{/usr}, and (2) the directory @file{/usr/share} is shared by the
1007 On the first host we would run
1009 [HOST1] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
1010 [HOST1] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure --prefix /usr}
1012 [HOST1] /tmp/amh % @kbd{make && sudo make install}
1016 On the second host, however, we need only install the
1017 architecture-specific files.
1019 [HOST2] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
1020 [HOST2] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure --prefix /usr}
1022 [HOST2] /tmp/amh % @kbd{make && sudo make install-exec}
1026 In packages that have installation checks, it would make sense to run
1027 @code{make installcheck} (@pxref{Basic Installation}) to verify that
1028 the package works correctly despite the apparent partial installation.
1030 @node Cross-Compilation
1031 @subsection Cross-Compilation
1032 @cindex cross-compilation
1034 To @dfn{cross-compile} is to build on one platform a binary that will
1035 run on another platform. When speaking of cross-compilation, it is
1036 important to distinguish between the @dfn{build platform} on which
1037 the compilation is performed, and the @dfn{host platform} on which the
1038 resulting executable is expected to run. The following
1039 @command{configure} options are used to specify each of them:
1042 @item --build=@var{build}
1043 @opindex --build=@var{build}
1044 The system on which the package is built.
1045 @item --host=@var{host}
1046 @opindex --host=@var{host}
1047 The system where built programs and libraries will run.
1050 When the @option{--host} is used, @command{configure} will search for
1051 the cross-compiling suite for this platform. Cross-compilation tools
1052 commonly have their target architecture as prefix of their name. For
1053 instance my cross-compiler for MinGW32 has its binaries called
1054 @code{i586-mingw32msvc-gcc}, @code{i586-mingw32msvc-ld},
1055 @code{i586-mingw32msvc-as}, etc.
1057 @cindex MinGW cross-compilation example
1058 @cindex cross-compilation example
1060 Here is how we could build @code{amhello-1.0} for
1061 @code{i586-mingw32msvc} on a GNU/Linux PC.
1063 @c Keep in sync with amhello-cross-compile.sh
1065 ~/amhello-1.0 % @kbd{./configure --build i686-pc-linux-gnu --host i586-mingw32msvc}
1066 checking for a BSD-compatible install... /usr/bin/install -c
1067 checking whether build environment is sane... yes
1068 checking for gawk... gawk
1069 checking whether make sets $(MAKE)... yes
1070 checking for i586-mingw32msvc-strip... i586-mingw32msvc-strip
1071 checking for i586-mingw32msvc-gcc... i586-mingw32msvc-gcc
1072 checking for C compiler default output file name... a.exe
1073 checking whether the C compiler works... yes
1074 checking whether we are cross compiling... yes
1075 checking for suffix of executables... .exe
1076 checking for suffix of object files... o
1077 checking whether we are using the GNU C compiler... yes
1078 checking whether i586-mingw32msvc-gcc accepts -g... yes
1079 checking for i586-mingw32msvc-gcc option to accept ANSI C...
1081 ~/amhello-1.0 % @kbd{make}
1083 ~/amhello-1.0 % @kbd{cd src; file hello.exe}
1084 hello.exe: MS Windows PE 32-bit Intel 80386 console executable not relocatable
1087 The @option{--host} and @option{--build} options are usually all we
1088 need for cross-compiling. The only exception is if the package being
1089 built is itself a cross-compiler: we need a third option to specify
1090 its target architecture.
1093 @item --target=@var{target}
1094 @opindex --target=@var{target}
1095 When building compiler tools: the system for which the tools will
1099 For instance when installing GCC, the GNU Compiler Collection, we can
1100 use @option{--target=@/@var{target}} to specify that we want to build
1101 GCC as a cross-compiler for @var{target}. Mixing @option{--build} and
1102 @option{--target}, we can actually cross-compile a cross-compiler;
1103 such a three-way cross-compilation is known as a @dfn{Canadian cross}.
1105 @xref{Specifying Names, , Specifying the System Type, autoconf, The
1106 Autoconf Manual}, for more information about these @command{configure}
1110 @subsection Renaming Programs at Install Time
1111 @cindex Renaming programs
1112 @cindex Transforming program names
1113 @cindex Programs, renaming during installation
1115 The GNU Build System provides means to automatically rename
1116 executables and manpages before they are installed (@pxref{Man Pages}).
1117 This is especially convenient
1118 when installing a GNU package on a system that already has a
1119 proprietary implementation you do not want to overwrite. For instance,
1120 you may want to install GNU @command{tar} as @command{gtar} so you can
1121 distinguish it from your vendor's @command{tar}.
1123 This can be done using one of these three @command{configure} options.
1126 @item --program-prefix=@var{prefix}
1127 @opindex --program-prefix=@var{prefix}
1128 Prepend @var{prefix} to installed program names.
1129 @item --program-suffix=@var{suffix}
1130 @opindex --program-suffix=@var{suffix}
1131 Append @var{suffix} to installed program names.
1132 @item --program-transform-name=@var{program}
1133 @opindex --program-transform-name=@var{program}
1134 Run @code{sed @var{program}} on installed program names.
1137 The following commands would install @file{hello}
1138 as @file{/usr/local/bin/test-hello}, for instance.
1141 ~/amhello-1.0 % @kbd{./configure --program-prefix test-}
1143 ~/amhello-1.0 % @kbd{make}
1145 ~/amhello-1.0 % @kbd{sudo make install}
1150 @subsection Building Binary Packages Using DESTDIR
1153 The GNU Build System's @code{make install} and @code{make uninstall}
1154 interface does not exactly fit the needs of a system administrator
1155 who has to deploy and upgrade packages on lots of hosts. In other
1156 words, the GNU Build System does not replace a package manager.
1158 Such package managers usually need to know which files have been
1159 installed by a package, so a mere @code{make install} is
1162 @cindex Staged installation
1164 The @code{DESTDIR} variable can be used to perform a staged
1165 installation. The package should be configured as if it was going to
1166 be installed in its final location (e.g., @code{--prefix /usr}), but
1167 when running @code{make install}, the @code{DESTDIR} should be set to
1168 the absolute name of a directory into which the installation will be
1169 diverted. From this directory it is easy to review which files are
1170 being installed where, and finally copy them to their final location
1173 @cindex Binary package
1175 For instance here is how we could create a binary package containing a
1176 snapshot of all the files to be installed.
1178 @c Keep in sync with amhello-binpkg.sh
1180 ~/amhello-1.0 % @kbd{./configure --prefix /usr}
1182 ~/amhello-1.0 % @kbd{make}
1184 ~/amhello-1.0 % @kbd{make DESTDIR=$HOME/inst install}
1186 ~/amhello-1.0 % @kbd{cd ~/inst}
1187 ~/inst % @kbd{find . -type f -print > ../files.lst}
1188 ~/inst % @kbd{tar zcvf ~/amhello-1.0-i686.tar.gz `cat ../files.lst`}
1190 ./usr/share/doc/amhello/README
1193 After this example, @code{amhello-1.0-i686.tar.gz} is ready to be
1194 uncompressed in @file{/} on many hosts. (Using @code{`cat ../files.lst`}
1195 instead of @samp{.} as argument for @command{tar} avoids entries for
1196 each subdirectory in the archive: we would not like @command{tar} to
1197 restore the modification time of @file{/}, @file{/usr/}, etc.)
1199 Note that when building packages for several architectures, it might
1200 be convenient to use @code{make install-data} and @code{make
1201 install-exec} (@pxref{Two-Part Install}) to gather
1202 architecture-independent files in a single package.
1204 @xref{Install}, for more information.
1206 @c We should document PRE_INSTALL/POST_INSTALL/NORMAL_INSTALL and their
1207 @c UNINSTALL counterparts.
1209 @node Preparing Distributions
1210 @subsection Preparing Distributions
1211 @cindex Preparing distributions
1212 @cindex Packages, preparation
1213 @cindex Distributions, preparation
1215 We have already mentioned @code{make dist}. This target collects all
1216 your source files and the necessary parts of the build system to
1217 create a tarball named @file{@var{package}-@var{version}.tar.gz}.
1219 @cindex @code{distcheck} better than @code{dist}
1221 Another, more useful command is @code{make distcheck}. The
1222 @code{distcheck} target constructs
1223 @file{@var{package}-@var{version}.tar.gz} just as well as @code{dist},
1224 but it additionally ensures most of the use cases presented so far
1229 It attempts a full compilation of the package (@pxref{Basic
1230 Installation}), unpacking the newly constructed tarball, running
1231 @code{make}, @code{make check}, @code{make install}, as well as
1232 @code{make installcheck}, and even @code{make dist},
1234 it tests VPATH builds with read-only source tree (@pxref{VPATH Builds}),
1236 it makes sure @code{make clean}, @code{make distclean}, and @code{make
1237 uninstall} do not omit any file (@pxref{Standard Targets}),
1239 and it checks that @code{DESTDIR} installations work (@pxref{DESTDIR}).
1242 All of these actions are performed in a temporary subdirectory, so
1243 that no root privileges are required.
1245 Releasing a package that fails @code{make distcheck} means that one of
1246 the scenarios we presented will not work and some users will be
1247 disappointed. Therefore it is a good practice to release a package
1248 only after a successful @code{make distcheck}. This of course does
1249 not imply that the package will be flawless, but at least it will
1250 prevent some of the embarrassing errors you may find in packages
1251 released by people who have never heard about @code{distcheck} (like
1252 @code{DESTDIR} not working because of a typo, or a distributed file
1253 being erased by @code{make clean}, or even @code{VPATH} builds not
1256 @xref{Creating amhello}, to recreate @file{amhello-1.0.tar.gz} using
1257 @code{make distcheck}. @xref{Checking the Distribution}, for more
1258 information about @code{distcheck}.
1260 @node Dependency Tracking
1261 @subsection Automatic Dependency Tracking
1262 @cindex Dependency tracking
1264 Dependency tracking is performed as a side-effect of compilation.
1265 Each time the build system compiles a source file, it computes its
1266 list of dependencies (in C these are the header files included by the
1267 source being compiled). Later, any time @command{make} is run and a
1268 dependency appears to have changed, the dependent files will be
1271 Automake generates code for automatic dependency tracking by default,
1272 unless the developer chooses to override it; for more information,
1273 @pxref{Dependencies}.
1275 When @command{configure} is executed, you can see it probing each
1276 compiler for the dependency mechanism it supports (several mechanisms
1280 ~/amhello-1.0 % @kbd{./configure --prefix /usr}
1282 checking dependency style of gcc... gcc3
1286 Because dependencies are only computed as a side-effect of the
1287 compilation, no dependency information exists the first time a package
1288 is built. This is OK because all the files need to be built anyway:
1289 @code{make} does not have to decide which files need to be rebuilt.
1290 In fact, dependency tracking is completely useless for one-time builds
1291 and there is a @command{configure} option to disable this:
1294 @item --disable-dependency-tracking
1295 @opindex --disable-dependency-tracking
1296 Speed up one-time builds.
1299 Some compilers do not offer any practical way to derive the list of
1300 dependencies as a side-effect of the compilation, requiring a separate
1301 run (maybe of another tool) to compute these dependencies. The
1302 performance penalty implied by these methods is important enough to
1303 disable them by default. The option @option{--enable-dependency-tracking}
1304 must be passed to @command{configure} to activate them.
1307 @item --enable-dependency-tracking
1308 @opindex --enable-dependency-tracking
1309 Do not reject slow dependency extractors.
1312 @xref{Dependency Tracking Evolution, , Dependency Tracking Evolution,
1313 automake-history, Brief History of Automake}, for some discussion about
1314 the different dependency tracking schemes used by Automake over the years.
1316 @node Nested Packages
1317 @subsection Nested Packages
1318 @cindex Nested packages
1319 @cindex Packages, nested
1322 Although nesting packages isn't something we would recommend to
1323 someone who is discovering the Autotools, it is a nice feature worthy
1324 of mention in this small advertising tour.
1326 Autoconfiscated packages (that means packages whose build system have
1327 been created by Autoconf and friends) can be nested to arbitrary
1330 A typical setup is that package A will distribute one of the libraries
1331 it needs in a subdirectory. This library B is a complete package with
1332 its own GNU Build System. The @command{configure} script of A will
1333 run the @command{configure} script of B as part of its execution,
1334 building and installing A will also build and install B. Generating a
1335 distribution for A will also include B.
1337 It is possible to gather several packages like this. GCC is a heavy
1338 user of this feature. This gives installers a single package to
1339 configure, build and install, while it allows developers to work on
1340 subpackages independently.
1342 When configuring nested packages, the @command{configure} options
1343 given to the top-level @command{configure} are passed recursively to
1344 nested @command{configure}s. A package that does not understand an
1345 option will ignore it, assuming it is meaningful to some other
1348 @opindex --help=recursive
1350 The command @code{configure --help=recursive} can be used to display
1351 the options supported by all the included packages.
1353 @xref{Subpackages}, for an example setup.
1356 @section How Autotools Help
1357 @cindex Autotools, purpose
1359 There are several reasons why you may not want to implement the GNU
1360 Build System yourself (read: write a @file{configure} script and
1361 @file{Makefile}s yourself).
1365 As we have seen, the GNU Build System has a lot of
1366 features (@pxref{Use Cases}).
1367 Some users may expect features you have not implemented because
1368 you did not need them.
1370 Implementing these features portably is difficult and exhausting.
1371 Think of writing portable shell scripts, and portable
1372 @file{Makefile}s, for systems you may not have handy. @xref{Portable
1373 Shell, , Portable Shell Programming, autoconf, The Autoconf Manual}, to
1376 You will have to upgrade your setup to follow changes to the GNU
1380 The GNU Autotools take all this burden off your back and provide:
1384 Tools to create a portable, complete, and self-contained GNU Build
1385 System, from simple instructions.
1386 @emph{Self-contained} meaning the resulting build system does not
1387 require the GNU Autotools.
1389 A central place where fixes and improvements are made:
1390 a bug-fix for a portability issue will benefit every package.
1393 Yet there also exist reasons why you may want NOT to use the
1394 Autotools@enddots{} For instance you may be already using (or used to)
1395 another incompatible build system. Autotools will only be useful if
1396 you do accept the concepts of the GNU Build System. People who have their
1397 own idea of how a build system should work will feel frustrated by the
1401 @section A Small Hello World
1402 @cindex Example Hello World
1403 @cindex Hello World example
1404 @cindex @file{amhello-1.0.tar.gz}, creation
1406 In this section we recreate the @file{amhello-1.0} package from
1407 scratch. The first subsection shows how to call the Autotools to
1408 instantiate the GNU Build System, while the second explains the
1409 meaning of the @file{configure.ac} and @file{Makefile.am} files read
1412 @anchor{amhello Explained}
1414 * Creating amhello:: Create @file{amhello-1.0.tar.gz} from scratch
1415 * amhello's configure.ac Setup Explained::
1416 * amhello's Makefile.am Setup Explained::
1419 @node Creating amhello
1420 @subsection Creating @file{amhello-1.0.tar.gz}
1422 Here is how we can recreate @file{amhello-1.0.tar.gz} from scratch.
1423 The package is simple enough so that we will only need to write 5
1424 files. (You may copy them from the final @file{amhello-1.0.tar.gz}
1425 that is distributed with Automake if you do not want to write them.)
1427 Create the following files in an empty directory.
1432 @file{src/main.c} is the source file for the @file{hello} program. We
1433 store it in the @file{src/} subdirectory, because later, when the package
1434 evolves, it will ease the addition of a @file{man/} directory for man
1435 pages, a @file{data/} directory for data files, etc.
1437 ~/amhello % @kbd{cat src/main.c}
1444 puts ("Hello World!");
1445 puts ("This is " PACKAGE_STRING ".");
1451 @file{README} contains some very limited documentation for our little
1454 ~/amhello % @kbd{cat README}
1455 This is a demonstration package for GNU Automake.
1456 Type 'info Automake' to read the Automake manual.
1460 @file{Makefile.am} and @file{src/Makefile.am} contain Automake
1461 instructions for these two directories.
1464 ~/amhello % @kbd{cat src/Makefile.am}
1465 bin_PROGRAMS = hello
1466 hello_SOURCES = main.c
1467 ~/amhello % @kbd{cat Makefile.am}
1469 dist_doc_DATA = README
1473 Finally, @file{configure.ac} contains Autoconf instructions to
1474 create the @command{configure} script.
1477 ~/amhello % @kbd{cat configure.ac}
1478 AC_INIT([amhello], [1.0], [@value{PACKAGE_BUGREPORT}])
1479 AM_INIT_AUTOMAKE([-Wall -Werror foreign])
1481 AC_CONFIG_HEADERS([config.h])
1490 @cindex @command{autoreconf}, example
1492 Once you have these five files, it is time to run the Autotools to
1493 instantiate the build system. Do this using the @command{autoreconf}
1497 ~/amhello % @kbd{autoreconf --install}
1498 configure.ac: installing './install-sh'
1499 configure.ac: installing './missing'
1500 src/Makefile.am: installing './depcomp'
1503 At this point the build system is complete.
1505 In addition to the three scripts mentioned in its output, you can see
1506 that @command{autoreconf} created four other files: @file{configure},
1507 @file{config.h.in}, @file{Makefile.in}, and @file{src/Makefile.in}.
1508 The latter three files are templates that will be adapted to the
1509 system by @command{configure} under the names @file{config.h},
1510 @file{Makefile}, and @file{src/Makefile}. Let's do this:
1513 ~/amhello % @kbd{./configure}
1514 checking for a BSD-compatible install... /usr/bin/install -c
1515 checking whether build environment is sane... yes
1516 checking for gawk... no
1517 checking for mawk... mawk
1518 checking whether make sets $(MAKE)... yes
1519 checking for gcc... gcc
1520 checking for C compiler default output file name... a.out
1521 checking whether the C compiler works... yes
1522 checking whether we are cross compiling... no
1523 checking for suffix of executables...
1524 checking for suffix of object files... o
1525 checking whether we are using the GNU C compiler... yes
1526 checking whether gcc accepts -g... yes
1527 checking for gcc option to accept ISO C89... none needed
1528 checking for style of include used by make... GNU
1529 checking dependency style of gcc... gcc3
1530 configure: creating ./config.status
1531 config.status: creating Makefile
1532 config.status: creating src/Makefile
1533 config.status: creating config.h
1534 config.status: executing depfiles commands
1538 @cindex @code{distcheck} example
1540 You can see @file{Makefile}, @file{src/Makefile}, and @file{config.h}
1541 being created at the end after @command{configure} has probed the
1542 system. It is now possible to run all the targets we wish
1543 (@pxref{Standard Targets}). For instance:
1546 ~/amhello % @kbd{make}
1548 ~/amhello % @kbd{src/hello}
1550 This is amhello 1.0.
1551 ~/amhello % @kbd{make distcheck}
1553 =============================================
1554 amhello-1.0 archives ready for distribution:
1556 =============================================
1559 Note that running @command{autoreconf} is only needed initially when
1560 the GNU Build System does not exist. When you later change some
1561 instructions in a @file{Makefile.am} or @file{configure.ac}, the
1562 relevant part of the build system will be regenerated automatically
1563 when you execute @command{make}.
1565 @command{autoreconf} is a script that calls @command{autoconf},
1566 @command{automake}, and a bunch of other commands in the right order.
1567 If you are beginning with these tools, it is not important to figure
1568 out in which order all of these tools should be invoked and why. However,
1569 because Autoconf and Automake have separate manuals, the important
1570 point to understand is that @command{autoconf} is in charge of
1571 creating @file{configure} from @file{configure.ac}, while
1572 @command{automake} is in charge of creating @file{Makefile.in}s from
1573 @file{Makefile.am}s and @file{configure.ac}. This should at least
1574 direct you to the right manual when seeking answers.
1577 @node amhello's configure.ac Setup Explained
1578 @subsection @code{amhello}'s @file{configure.ac} Setup Explained
1580 @cindex @file{configure.ac}, Hello World
1582 Let us begin with the contents of @file{configure.ac}.
1585 AC_INIT([amhello], [1.0], [@value{PACKAGE_BUGREPORT}])
1586 AM_INIT_AUTOMAKE([-Wall -Werror foreign])
1588 AC_CONFIG_HEADERS([config.h])
1596 This file is read by both @command{autoconf} (to create
1597 @file{configure}) and @command{automake} (to create the various
1598 @file{Makefile.in}s). It contains a series of M4 macros that will be
1599 expanded as shell code to finally form the @file{configure} script.
1600 We will not elaborate on the syntax of this file, because the Autoconf
1601 manual has a whole section about it (@pxref{Writing Autoconf Input, ,
1602 Writing @file{configure.ac}, autoconf, The Autoconf Manual}).
1604 The macros prefixed with @code{AC_} are Autoconf macros, documented
1605 in the Autoconf manual (@pxref{Autoconf Macro Index, , Autoconf Macro
1606 Index, autoconf, The Autoconf Manual}). The macros that start with
1607 @code{AM_} are Automake macros, documented later in this manual
1608 (@pxref{Macro Index}).
1610 The first two lines of @file{configure.ac} initialize Autoconf and
1611 Automake. @code{AC_INIT} takes in as parameters the name of the package,
1612 its version number, and a contact address for bug-reports about the
1613 package (this address is output at the end of @code{./configure
1614 --help}, for instance). When adapting this setup to your own package,
1615 by all means please do not blindly copy Automake's address: use the
1616 mailing list of your package, or your own mail address.
1622 The argument to @code{AM_INIT_AUTOMAKE} is a list of options for
1623 @command{automake} (@pxref{Options}). @option{-Wall} and
1624 @option{-Werror} ask @command{automake} to turn on all warnings and
1625 report them as errors. We are speaking of @strong{Automake} warnings
1626 here, such as dubious instructions in @file{Makefile.am}. This has
1627 absolutely nothing to do with how the compiler will be called, even
1628 though it may support options with similar names. Using @option{-Wall
1629 -Werror} is a safe setting when starting to work on a package: you do
1630 not want to miss any issues. Later you may decide to relax things a
1631 bit. The @option{foreign} option tells Automake that this package
1632 will not follow the GNU Standards. GNU packages should always
1633 distribute additional files such as @file{ChangeLog}, @file{AUTHORS},
1634 etc. We do not want @command{automake} to complain about these
1635 missing files in our small example.
1637 The @code{AC_PROG_CC} line causes the @command{configure} script to
1638 search for a C compiler and define the variable @code{CC} with its
1639 name. The @file{src/Makefile.in} file generated by Automake uses the
1640 variable @code{CC} to build @file{hello}, so when @command{configure}
1641 creates @file{src/Makefile} from @file{src/Makefile.in}, it will define
1642 @code{CC} with the value it has found. If Automake is asked to create
1643 a @file{Makefile.in} that uses @code{CC} but @file{configure.ac} does
1644 not define it, it will suggest you add a call to @code{AC_PROG_CC}.
1646 The @code{AC_CONFIG_HEADERS([config.h])} invocation causes the
1647 @command{configure} script to create a @file{config.h} file gathering
1648 @samp{#define}s defined by other macros in @file{configure.ac}. In our
1649 case, the @code{AC_INIT} macro already defined a few of them. Here
1650 is an excerpt of @file{config.h} after @command{configure} has run:
1654 /* Define to the address where bug reports for this package should be sent. */
1655 #define PACKAGE_BUGREPORT "@value{PACKAGE_BUGREPORT}"
1657 /* Define to the full name and version of this package. */
1658 #define PACKAGE_STRING "amhello 1.0"
1662 As you probably noticed, @file{src/main.c} includes @file{config.h} so
1663 it can use @code{PACKAGE_STRING}. In a real-world project,
1664 @file{config.h} can grow really big, with one @samp{#define} per
1665 feature probed on the system.
1667 The @code{AC_CONFIG_FILES} macro declares the list of files that
1668 @command{configure} should create from their @file{*.in} templates.
1669 Automake also scans this list to find the @file{Makefile.am} files it must
1670 process. (This is important to remember: when adding a new directory
1671 to your project, you should add its @file{Makefile} to this list,
1672 otherwise Automake will never process the new @file{Makefile.am} you
1673 wrote in that directory.)
1675 Finally, the @code{AC_OUTPUT} line is a closing command that actually
1676 produces the part of the script in charge of creating the files
1677 registered with @code{AC_CONFIG_HEADERS} and @code{AC_CONFIG_FILES}.
1679 @cindex @command{autoscan}
1681 When starting a new project, we suggest you start with such a simple
1682 @file{configure.ac}, and gradually add the other tests it requires.
1683 The command @command{autoscan} can also suggest a few of the tests
1684 your package may need (@pxref{autoscan Invocation, , Using
1685 @command{autoscan} to Create @file{configure.ac}, autoconf, The
1689 @node amhello's Makefile.am Setup Explained
1690 @subsection @code{amhello}'s @file{Makefile.am} Setup Explained
1692 @cindex @file{Makefile.am}, Hello World
1694 We now turn to @file{src/Makefile.am}. This file contains
1695 Automake instructions to build and install @file{hello}.
1698 bin_PROGRAMS = hello
1699 hello_SOURCES = main.c
1702 A @file{Makefile.am} has the same syntax as an ordinary
1703 @file{Makefile}. When @command{automake} processes a
1704 @file{Makefile.am} it copies the entire file into the output
1705 @file{Makefile.in} (that will be later turned into @file{Makefile} by
1706 @command{configure}) but will react to certain variable definitions
1707 by generating some build rules and other variables.
1708 Often @file{Makefile.am}s contain only a list of variable definitions as
1709 above, but they can also contain other variable and rule definitions that
1710 @command{automake} will pass along without interpretation.
1712 Variables that end with @code{_PROGRAMS} are special variables
1713 that list programs that the resulting @file{Makefile} should build.
1714 In Automake speak, this @code{_PROGRAMS} suffix is called a
1715 @dfn{primary}; Automake recognizes other primaries such as
1716 @code{_SCRIPTS}, @code{_DATA}, @code{_LIBRARIES}, etc.@: corresponding
1717 to different types of files.
1719 The @samp{bin} part of the @code{bin_PROGRAMS} tells
1720 @command{automake} that the resulting programs should be installed in
1721 @var{bindir}. Recall that the GNU Build System uses a set of variables
1722 to denote destination directories and allow users to customize these
1723 locations (@pxref{Standard Directory Variables}). Any such directory
1724 variable can be put in front of a primary (omitting the @code{dir}
1725 suffix) to tell @command{automake} where to install the listed files.
1727 Programs need to be built from source files, so for each program
1728 @code{@var{prog}} listed in a @code{@w{_PROGRAMS}} variable,
1729 @command{automake} will look for another variable named
1730 @code{@var{prog}_SOURCES} listing its source files. There may be more
1731 than one source file: they will all be compiled and linked together.
1733 Automake also knows that source files need to be distributed when
1734 creating a tarball (unlike built programs). So a side-effect of this
1735 @code{hello_SOURCES} declaration is that @file{main.c} will be
1736 part of the tarball created by @code{make dist}.
1738 Finally here are some explanations regarding the top-level
1743 dist_doc_DATA = README
1746 @code{SUBDIRS} is a special variable listing all directories that
1747 @command{make} should recurse into before processing the current
1748 directory. So this line is responsible for @command{make} building
1749 @file{src/hello} even though we run it from the top-level. This line
1750 also causes @code{make install} to install @file{src/hello} before
1751 installing @file{README} (not that this order matters).
1753 The line @code{dist_doc_DATA = README} causes @file{README} to be
1754 distributed and installed in @var{docdir}. Files listed with the
1755 @code{_DATA} primary are not automatically part of the tarball built
1756 with @code{make dist}, so we add the @code{dist_} prefix so they get
1757 distributed. However, for @file{README} it would not have been
1758 necessary: @command{automake} automatically distributes any
1759 @file{README} file it encounters (the list of other files
1760 automatically distributed is presented by @code{automake --help}).
1761 The only important effect of this second line is therefore to install
1762 @file{README} during @code{make install}.
1764 One thing not covered in this example is accessing the installation
1765 directory values (@pxref{Standard Directory Variables}) from your
1766 program code, that is, converting them into defined macros. For this,
1767 @pxref{Defining Directories,,, autoconf, The Autoconf Manual}.
1771 @chapter General ideas
1773 The following sections cover a few basic ideas that will help you
1774 understand how Automake works.
1777 * General Operation:: General operation of Automake
1778 * Strictness:: Standards conformance checking
1779 * Uniform:: The Uniform Naming Scheme
1780 * Length Limitations:: Staying below the command line length limit
1781 * Canonicalization:: How derived variables are named
1782 * User Variables:: Variables reserved for the user
1783 * Auxiliary Programs:: Programs automake might require
1787 @node General Operation
1788 @section General Operation
1790 Automake works by reading a @file{Makefile.am} and generating a
1791 @file{Makefile.in}. Certain variables and rules defined in the
1792 @file{Makefile.am} instruct Automake to generate more specialized code;
1793 for instance, a @code{bin_PROGRAMS} variable definition will cause rules
1794 for compiling and linking programs to be generated.
1796 @cindex Non-standard targets
1797 @cindex @code{git-dist}, non-standard example
1800 The variable definitions and rules in the @file{Makefile.am} are
1801 copied mostly verbatim into the generated file, with all variable
1802 definitions preceding all rules. This allows you to add almost
1803 arbitrary code into the generated @file{Makefile.in}. For instance,
1804 the Automake distribution includes a non-standard rule for the
1805 @code{git-dist} target, which the Automake maintainer uses to make
1806 distributions from the source control system.
1808 @cindex GNU make extensions
1810 Note that most GNU make extensions are not recognized by Automake. Using
1811 such extensions in a @file{Makefile.am} will lead to errors or confusing
1814 @cindex Append operator
1816 A special exception is that the GNU make append operator, @samp{+=}, is
1817 supported. This operator appends its right hand argument to the variable
1818 specified on the left. Automake will translate the operator into
1819 an ordinary @samp{=} operator; @samp{+=} will thus work with any make program.
1821 Automake tries to keep comments grouped with any adjoining rules or
1822 variable definitions.
1824 @cindex Limitations of automake parser
1825 @cindex Automake parser, limitations of
1826 @cindex indentation in Makefile.am
1827 Generally, Automake is not particularly smart in the parsing of unusual
1828 Makefile constructs, so you're advised to avoid fancy constructs or
1829 ``creative'' use of whitespaces.
1830 @c Keep this in sync with doc-parsing-buglets-tabs.sh
1831 For example, @key{TAB} characters cannot be used between a target name
1832 and the following ``@code{:}'' character, and variable assignments
1833 shouldn't be indented with @key{TAB} characters.
1834 @c Keep this in sync with doc-parsing-buglets-colneq-subst.sh
1835 Also, using more complex macro in target names can cause trouble:
1838 % @kbd{cat Makefile.am}
1841 Makefile.am:1: bad characters in variable name '$(FOO'
1842 Makefile.am:1: ':='-style assignments are not portable
1845 @cindex Make targets, overriding
1846 @cindex Make rules, overriding
1847 @cindex Overriding make rules
1848 @cindex Overriding make targets
1850 A rule defined in @file{Makefile.am} generally overrides any such
1851 rule of a similar name that would be automatically generated by
1852 @command{automake}. Although this is a supported feature, it is generally
1853 best to avoid making use of it, as sometimes the generated rules are
1856 @cindex Variables, overriding
1857 @cindex Overriding make variables
1859 Similarly, a variable defined in @file{Makefile.am} or
1860 @code{AC_SUBST}ed from @file{configure.ac} will override any
1861 definition of the variable that @command{automake} would ordinarily
1862 create. This feature is more often useful than the ability to
1863 override a rule. Be warned that many of the variables generated by
1864 @command{automake} are considered to be for internal use only, and their
1865 names might change in future releases.
1867 @cindex Recursive operation of Automake
1868 @cindex Automake, recursive operation
1869 @cindex Example of recursive operation
1871 When examining a variable definition, Automake will recursively examine
1872 variables referenced in the definition. For example, if Automake is
1873 looking at the content of @code{foo_SOURCES} in this snippet
1875 @c Keep in sync with interp.sh
1878 foo_SOURCES = c.c $(xs)
1881 it would use the files @file{a.c}, @file{b.c}, and @file{c.c} as the
1882 contents of @code{foo_SOURCES}.
1884 @cindex @code{##} (special Automake comment)
1885 @cindex Special Automake comment
1886 @cindex Comment, special to Automake
1888 Automake also allows a form of comment that is @emph{not} copied into
1889 the output; all lines beginning with @samp{##} (leading spaces allowed)
1890 are completely ignored by Automake.
1892 It is customary to make the first line of @file{Makefile.am} read:
1894 @cindex Makefile.am, first line
1895 @cindex First line of Makefile.am
1898 ## Process this file with automake to produce Makefile.in
1901 @c FIXME discuss putting a copyright into Makefile.am here? I would but
1902 @c I don't know quite what to say.
1904 @c FIXME document customary ordering of Makefile.am here!
1910 @cindex Non-GNU packages
1912 While Automake is intended to be used by maintainers of GNU packages, it
1913 does make some effort to accommodate those who wish to use it, but do
1914 not want to use all the GNU conventions.
1916 @cindex Strictness, defined
1917 @cindex Strictness, @option{foreign}
1918 @cindex @option{foreign} strictness
1919 @cindex Strictness, @option{gnu}
1920 @cindex @option{gnu} strictness
1921 @cindex Strictness, @option{gnits}
1922 @cindex @option{gnits} strictness
1924 To this end, Automake supports three levels of @dfn{strictness}---the
1925 strictness indicating how stringently Automake should check standards
1928 The valid strictness levels are:
1932 Automake will check for only those things that are absolutely
1933 required for proper operations. For instance, whereas GNU standards
1934 dictate the existence of a @file{NEWS} file, it will not be required in
1935 this mode. This strictness will also turn off some warnings by default
1936 (among them, portability warnings).
1937 The name comes from the fact that Automake is intended to be
1938 used for GNU programs; these relaxed rules are not the standard mode of
1942 Automake will check---as much as possible---for compliance to the GNU
1943 standards for packages. This is the default.
1946 Automake will check for compliance to the as-yet-unwritten @dfn{Gnits
1947 standards}. These are based on the GNU standards, but are even more
1948 detailed. Unless you are a Gnits standards contributor, it is
1949 recommended that you avoid this option until such time as the Gnits
1950 standard is actually published (which may never happen).
1953 @xref{Gnits}, for more information on the precise implications of the
1958 @section The Uniform Naming Scheme
1960 @cindex Uniform naming scheme
1962 Automake variables generally follow a @dfn{uniform naming scheme} that
1963 makes it easy to decide how programs (and other derived objects) are
1964 built, and how they are installed. This scheme also supports
1965 @command{configure} time determination of what should be built.
1967 @cindex @code{_PROGRAMS} primary variable
1968 @cindex @code{PROGRAMS} primary variable
1969 @cindex Primary variable, @code{PROGRAMS}
1970 @cindex Primary variable, defined
1973 At @command{make} time, certain variables are used to determine which
1974 objects are to be built. The variable names are made of several pieces
1975 that are concatenated together.
1977 The piece that tells @command{automake} what is being built is commonly called
1978 the @dfn{primary}. For instance, the primary @code{PROGRAMS} holds a
1979 list of programs that are to be compiled and linked.
1982 @cindex @code{pkgdatadir}, defined
1983 @cindex @code{pkgincludedir}, defined
1984 @cindex @code{pkglibdir}, defined
1985 @cindex @code{pkglibexecdir}, defined
1988 @vindex pkgincludedir
1990 @vindex pkglibexecdir
1992 @cindex @code{PACKAGE}, directory
1993 A different set of names is used to decide where the built objects
1994 should be installed. These names are prefixes to the primary, and they
1995 indicate which standard directory should be used as the installation
1996 directory. The standard directory names are given in the GNU standards
1997 (@pxref{Directory Variables, , , standards, The GNU Coding Standards}).
1998 Automake extends this list with @code{pkgdatadir}, @code{pkgincludedir},
1999 @code{pkglibdir}, and @code{pkglibexecdir}; these are the same as the
2000 non-@samp{pkg} versions, but with @samp{$(PACKAGE)} appended. For instance,
2001 @code{pkglibdir} is defined as @samp{$(libdir)/$(PACKAGE)}.
2003 @cindex @code{EXTRA_}, prepending
2004 For each primary, there is one additional variable named by prepending
2005 @samp{EXTRA_} to the primary name. This variable is used to list
2006 objects that may or may not be built, depending on what
2007 @command{configure} decides. This variable is required because Automake
2008 must statically know the entire list of objects that may be built in
2009 order to generate a @file{Makefile.in} that will work in all cases.
2011 @cindex @code{EXTRA_PROGRAMS}, defined
2012 @cindex Example, @code{EXTRA_PROGRAMS}
2013 @cindex @command{cpio} example
2015 For instance, @command{cpio} decides at configure time which programs
2016 should be built. Some of the programs are installed in @code{bindir},
2017 and some are installed in @code{sbindir}:
2020 EXTRA_PROGRAMS = mt rmt
2021 bin_PROGRAMS = cpio pax
2022 sbin_PROGRAMS = $(MORE_PROGRAMS)
2025 Defining a primary without a prefix as a variable, e.g.,
2026 @samp{PROGRAMS}, is an error.
2028 Note that the common @samp{dir} suffix is left off when constructing the
2029 variable names; thus one writes @samp{bin_PROGRAMS} and not
2030 @samp{bindir_PROGRAMS}.
2032 Not every sort of object can be installed in every directory. Automake
2033 will flag those attempts it finds in error (but see below how to override
2034 the check if you really need to).
2035 Automake will also diagnose obvious misspellings in directory names.
2037 @cindex Extending list of installation directories
2038 @cindex Installation directories, extending list
2040 Sometimes the standard directories---even as augmented by
2041 Automake---are not enough. In particular it is sometimes useful, for
2042 clarity, to install objects in a subdirectory of some predefined
2043 directory. To this end, Automake allows you to extend the list of
2044 possible installation directories. A given prefix (e.g., @samp{zar})
2045 is valid if a variable of the same name with @samp{dir} appended is
2046 defined (e.g., @samp{zardir}).
2048 For instance, the following snippet will install @file{file.xml} into
2049 @samp{$(datadir)/xml}.
2051 @c Keep in sync with primary-prefix-couples-documented-valid.sh
2053 xmldir = $(datadir)/xml
2057 This feature can also be used to override the sanity checks Automake
2058 performs to diagnose suspicious directory/primary couples (in the
2059 unlikely case these checks are undesirable, and you really know what
2060 you're doing). For example, Automake would error out on this input:
2062 @c Should be tested in primary-prefix-invalid-couples.sh
2064 # Forbidden directory combinations, automake will error out on this.
2065 pkglib_PROGRAMS = foo
2066 doc_LIBRARIES = libquux.a
2070 but it will succeed with this:
2072 @c Keep in sync with primary-prefix-couples-documented-valid.sh
2074 # Work around forbidden directory combinations. Do not use this
2075 # without a very good reason!
2076 my_execbindir = $(pkglibdir)
2077 my_doclibdir = $(docdir)
2078 my_execbin_PROGRAMS = foo
2079 my_doclib_LIBRARIES = libquux.a
2082 The @samp{exec} substring of the @samp{my_execbindir} variable lets
2083 the files be installed at the right time (@pxref{The Two Parts of
2086 @cindex @samp{noinst_} primary prefix, definition
2089 The special prefix @samp{noinst_} indicates that the objects in question
2090 should be built but not installed at all. This is usually used for
2091 objects required to build the rest of your package, for instance static
2092 libraries (@pxref{A Library}), or helper scripts.
2094 @cindex @samp{check_} primary prefix, definition
2097 The special prefix @samp{check_} indicates that the objects in question
2098 should not be built until the @samp{make check} command is run. Those
2099 objects are not installed either.
2101 The current primary names are @samp{PROGRAMS}, @samp{LIBRARIES},
2102 @samp{LTLIBRARIES}, @samp{LISP}, @samp{PYTHON}, @samp{JAVA},
2103 @samp{SCRIPTS}, @samp{DATA}, @samp{HEADERS}, @samp{MANS}, and
2117 Some primaries also allow additional prefixes that control other
2118 aspects of @command{automake}'s behavior. The currently defined prefixes
2119 are @samp{dist_}, @samp{nodist_}, @samp{nobase_}, and @samp{notrans_}.
2120 These prefixes are explained later (@pxref{Program and Library Variables})
2121 (@pxref{Man Pages}).
2124 @node Length Limitations
2125 @section Staying below the command line length limit
2127 @cindex command line length limit
2130 Traditionally, most unix-like systems have a length limitation for the
2131 command line arguments and environment contents when creating new
2132 processes (see for example
2133 @uref{http://www.in-ulm.de/@/~mascheck/@/various/@/argmax/} for an
2134 overview on this issue),
2135 which of course also applies to commands spawned by @command{make}.
2136 POSIX requires this limit to be at least 4096 bytes, and most modern
2137 systems have quite high limits (or are unlimited).
2139 In order to create portable Makefiles that do not trip over these
2140 limits, it is necessary to keep the length of file lists bounded.
2141 Unfortunately, it is not possible to do so fully transparently within
2142 Automake, so your help may be needed. Typically, you can split long
2143 file lists manually and use different installation directory names for
2144 each list. For example,
2147 data_DATA = file1 @dots{} file@var{N} file@var{N+1} @dots{} file@var{2N}
2151 may also be written as
2153 @c Keep in sync with primary-prefix-couples-documented-valid.sh
2155 data_DATA = file1 @dots{} file@var{N}
2156 data2dir = $(datadir)
2157 data2_DATA = file@var{N+1} @dots{} file@var{2N}
2161 and will cause Automake to treat the two lists separately during
2162 @code{make install}. See @ref{The Two Parts of Install} for choosing
2163 directory names that will keep the ordering of the two parts of
2164 installation Note that @code{make dist} may still only work on a host
2165 with a higher length limit in this example.
2167 Automake itself employs a couple of strategies to avoid long command
2168 lines. For example, when @samp{$@{srcdir@}/} is prepended to file
2169 names, as can happen with above @code{$(data_DATA)} lists, it limits
2170 the amount of arguments passed to external commands.
2172 Unfortunately, some system's @command{make} commands may prepend
2173 @code{VPATH} prefixes like @samp{$@{srcdir@}/} to file names from the
2174 source tree automatically (@pxref{Automatic Rule Rewriting, , Automatic
2175 Rule Rewriting, autoconf, The Autoconf Manual}). In this case, the user
2176 may have to switch to use GNU Make, or refrain from using VPATH builds,
2177 in order to stay below the length limit.
2179 For libraries and programs built from many sources, convenience archives
2180 may be used as intermediates in order to limit the object list length
2181 (@pxref{Libtool Convenience Libraries}).
2184 @node Canonicalization
2185 @section How derived variables are named
2187 @cindex canonicalizing Automake variables
2189 Sometimes a Makefile variable name is derived from some text the
2190 maintainer supplies. For instance, a program name listed in
2191 @samp{_PROGRAMS} is rewritten into the name of a @samp{_SOURCES}
2192 variable. In cases like this, Automake canonicalizes the text, so that
2193 program names and the like do not have to follow Makefile variable naming
2194 rules. All characters in the name except for letters, numbers, the
2195 strudel (@@), and the underscore are turned into underscores when making
2196 variable references.
2198 For example, if your program is named @file{sniff-glue}, the derived
2199 variable name would be @samp{sniff_glue_SOURCES}, not
2200 @samp{sniff-glue_SOURCES}. Similarly the sources for a library named
2201 @file{libmumble++.a} should be listed in the
2202 @samp{libmumble___a_SOURCES} variable.
2204 The strudel is an addition, to make the use of Autoconf substitutions in
2205 variable names less obfuscating.
2208 @node User Variables
2209 @section Variables reserved for the user
2211 @cindex variables, reserved for the user
2212 @cindex user variables
2214 Some @file{Makefile} variables are reserved by the GNU Coding Standards
2215 for the use of the ``user''---the person building the package. For
2216 instance, @code{CFLAGS} is one such variable.
2218 Sometimes package developers are tempted to set user variables such as
2219 @code{CFLAGS} because it appears to make their job easier. However,
2220 the package itself should never set a user variable, particularly not
2221 to include switches that are required for proper compilation of the
2222 package. Since these variables are documented as being for the
2223 package builder, that person rightfully expects to be able to override
2224 any of these variables at build time.
2226 To get around this problem, Automake introduces an automake-specific
2227 shadow variable for each user flag variable. (Shadow variables are
2228 not introduced for variables like @code{CC}, where they would make no
2229 sense.) The shadow variable is named by prepending @samp{AM_} to the
2230 user variable's name. For instance, the shadow variable for
2231 @code{YFLAGS} is @code{AM_YFLAGS}. The package maintainer---that is,
2232 the author(s) of the @file{Makefile.am} and @file{configure.ac}
2233 files---may adjust these shadow variables however necessary.
2235 @xref{Flag Variables Ordering}, for more discussion about these
2236 variables and how they interact with per-target variables.
2238 @node Auxiliary Programs
2239 @section Programs automake might require
2241 @cindex Programs, auxiliary
2242 @cindex Auxiliary programs
2244 Automake sometimes requires helper programs so that the generated
2245 @file{Makefile} can do its work properly. There are a fairly large
2246 number of them, and we list them here.
2248 Although all of these files are distributed and installed with
2249 Automake, a couple of them are maintained separately. The Automake
2250 copies are updated before each release, but we mention the original
2251 source in case you need more recent versions.
2255 This is a wrapper primarily for the Microsoft lib archiver, to make
2259 This is a wrapper for compilers that do not accept options @option{-c}
2260 and @option{-o} at the same time. It is only used when absolutely
2261 required. Such compilers are rare, with the Microsoft C/C++ Compiler
2262 as the most notable exception. This wrapper also makes the following
2263 common options available for that compiler, while performing file name
2264 translation where needed: @option{-I}, @option{-L}, @option{-l},
2265 @option{-Wl,} and @option{-Xlinker}.
2269 These two programs compute the canonical triplets for the given build,
2270 host, or target architecture. These programs are updated regularly to
2271 support new architectures and fix probes broken by changes in new
2272 kernel versions. Each new release of Automake comes with up-to-date
2273 copies of these programs. If your copy of Automake is getting old,
2274 you are encouraged to fetch the latest versions of these files from
2275 @url{http://savannah.gnu.org/git/?group=config} before making a
2279 This program understands how to run a compiler so that it will
2280 generate not only the desired output but also dependency information
2281 that is then used by the automatic dependency tracking feature
2282 (@pxref{Dependencies}).
2285 This is a replacement for the @command{install} program that works on
2286 platforms where @command{install} is unavailable or unusable.
2289 This script is used to generate a @file{version.texi} file. It examines
2290 a file and prints some date information about it.
2293 This wraps a number of programs that are typically only required by
2294 maintainers. If the program in question doesn't exist, or seems to old,
2295 @command{missing} will print an informative warning before failing out,
2296 to provide the user with more context and information.
2299 This script used to be a wrapper around @samp{mkdir -p}, which is not
2300 portable. Now we prefer to use @samp{install-sh -d} when @command{configure}
2301 finds that @samp{mkdir -p} does not work, this makes one less script to
2304 For backward compatibility @file{mkinstalldirs} is still used and
2305 distributed when @command{automake} finds it in a package. But it is no
2306 longer installed automatically, and it should be safe to remove it.
2309 This is used to byte-compile Python scripts.
2312 This implements the default test driver offered by the parallel
2316 Not a program, this file is required for @samp{make dvi}, @samp{make
2317 ps} and @samp{make pdf} to work when Texinfo sources are in the
2318 package. The latest version can be downloaded from
2319 @url{http://www.gnu.org/software/texinfo/}.
2322 This program wraps @command{lex} and @command{yacc} to rename their
2323 output files. It also ensures that, for instance, multiple
2324 @command{yacc} instances can be invoked in a single directory in
2331 @chapter Some example packages
2333 This section contains two small examples.
2335 The first example (@pxref{Complete}) assumes you have an existing
2336 project already using Autoconf, with handcrafted @file{Makefile}s, and
2337 that you want to convert it to using Automake. If you are discovering
2338 both tools, it is probably better that you look at the Hello World
2339 example presented earlier (@pxref{Hello World}).
2341 The second example (@pxref{true}) shows how two programs can be built
2342 from the same file, using different compilation parameters. It
2343 contains some technical digressions that are probably best skipped on
2347 * Complete:: A simple example, start to finish
2348 * true:: Building true and false
2353 @section A simple example, start to finish
2355 @cindex Complete example
2357 Let's suppose you just finished writing @code{zardoz}, a program to make
2358 your head float from vortex to vortex. You've been using Autoconf to
2359 provide a portability framework, but your @file{Makefile.in}s have been
2360 ad-hoc. You want to make them bulletproof, so you turn to Automake.
2362 @cindex @code{AM_INIT_AUTOMAKE}, example use
2364 The first step is to update your @file{configure.ac} to include the
2365 commands that @command{automake} needs. The way to do this is to add an
2366 @code{AM_INIT_AUTOMAKE} call just after @code{AC_INIT}:
2369 AC_INIT([zardoz], [1.0])
2374 Since your program doesn't have any complicating factors (e.g., it
2375 doesn't use @code{gettext}, it doesn't want to build a shared library),
2376 you're done with this part. That was easy!
2378 @cindex @command{aclocal} program, introduction
2379 @cindex @file{aclocal.m4}, preexisting
2380 @cindex @file{acinclude.m4}, defined
2382 Now you must regenerate @file{configure}. But to do that, you'll need
2383 to tell @command{autoconf} how to find the new macro you've used. The
2384 easiest way to do this is to use the @command{aclocal} program to
2385 generate your @file{aclocal.m4} for you. But wait@dots{} maybe you
2386 already have an @file{aclocal.m4}, because you had to write some hairy
2387 macros for your program. The @command{aclocal} program lets you put
2388 your own macros into @file{acinclude.m4}, so simply rename and then
2392 mv aclocal.m4 acinclude.m4
2397 @cindex @command{zardoz} example
2399 Now it is time to write your @file{Makefile.am} for @code{zardoz}.
2400 Since @code{zardoz} is a user program, you want to install it where the
2401 rest of the user programs go: @code{bindir}. Additionally,
2402 @code{zardoz} has some Texinfo documentation. Your @file{configure.ac}
2403 script uses @code{AC_REPLACE_FUNCS}, so you need to link against
2404 @samp{$(LIBOBJS)}. So here's what you'd write:
2407 bin_PROGRAMS = zardoz
2408 zardoz_SOURCES = main.c head.c float.c vortex9.c gun.c
2409 zardoz_LDADD = $(LIBOBJS)
2411 info_TEXINFOS = zardoz.texi
2414 Now you can run @samp{automake --add-missing} to generate your
2415 @file{Makefile.in} and grab any auxiliary files you might need, and
2420 @section Building true and false
2422 @cindex Example, @command{false} and @command{true}
2423 @cindex @command{false} Example
2424 @cindex @command{true} Example
2426 Here is another, trickier example. It shows how to generate two
2427 programs (@code{true} and @code{false}) from the same source file
2428 (@file{true.c}). The difficult part is that each compilation of
2429 @file{true.c} requires different @code{cpp} flags.
2432 bin_PROGRAMS = true false
2434 false_LDADD = false.o
2437 $(COMPILE) -DEXIT_CODE=0 -c true.c
2440 $(COMPILE) -DEXIT_CODE=1 -o false.o -c true.c
2443 Note that there is no @code{true_SOURCES} definition. Automake will
2444 implicitly assume that there is a source file named @file{true.c}
2445 (@pxref{Default _SOURCES}), and
2446 define rules to compile @file{true.o} and link @file{true}. The
2447 @samp{true.o: true.c} rule supplied by the above @file{Makefile.am},
2448 will override the Automake generated rule to build @file{true.o}.
2450 @code{false_SOURCES} is defined to be empty---that way no implicit value
2451 is substituted. Because we have not listed the source of
2452 @file{false}, we have to tell Automake how to link the program. This is
2453 the purpose of the @code{false_LDADD} line. A @code{false_DEPENDENCIES}
2454 variable, holding the dependencies of the @file{false} target will be
2455 automatically generated by Automake from the content of
2458 The above rules won't work if your compiler doesn't accept both
2459 @option{-c} and @option{-o}. The simplest fix for this is to introduce a
2460 bogus dependency (to avoid problems with a parallel @command{make}):
2463 true.o: true.c false.o
2464 $(COMPILE) -DEXIT_CODE=0 -c true.c
2467 $(COMPILE) -DEXIT_CODE=1 -c true.c && mv true.o false.o
2470 As it turns out, there is also a much easier way to do this same task.
2471 Some of the above technique is useful enough that we've kept the
2472 example in the manual. However if you were to build @code{true} and
2473 @code{false} in real life, you would probably use per-program
2474 compilation flags, like so:
2476 @c Keep in sync with specflg7.sh and specflg8.sh
2478 bin_PROGRAMS = false true
2480 false_SOURCES = true.c
2481 false_CPPFLAGS = -DEXIT_CODE=1
2483 true_SOURCES = true.c
2484 true_CPPFLAGS = -DEXIT_CODE=0
2487 In this case Automake will cause @file{true.c} to be compiled twice,
2488 with different flags. In this instance, the names of the object files
2489 would be chosen by automake; they would be @file{false-true.o} and
2490 @file{true-true.o}. (The name of the object files rarely matters.)
2492 @node automake Invocation
2493 @chapter Creating a @file{Makefile.in}
2494 @c This node used to be named "Invoking automake". This @anchor
2495 @c allows old links to still work.
2496 @anchor{Invoking automake}
2498 @cindex Multiple @file{configure.ac} files
2499 @cindex Invoking @command{automake}
2500 @cindex @command{automake}, invoking
2501 @cindex Invocation of @command{automake}
2502 @cindex @command{automake}, invocation
2504 To create all the @file{Makefile.in}s for a package, run the
2505 @command{automake} program in the top level directory, with no
2506 arguments. @command{automake} will automatically find each
2507 appropriate @file{Makefile.am} (by scanning @file{configure.ac};
2508 @pxref{configure}) and generate the corresponding @file{Makefile.in}.
2509 Note that @command{automake} has a rather simplistic view of what
2510 constitutes a package; it assumes that a package has only one
2511 @file{configure.ac}, at the top. If your package has multiple
2512 @file{configure.ac}s, then you must run @command{automake} in each
2513 directory holding a @file{configure.ac}. (Alternatively, you may rely
2514 on Autoconf's @command{autoreconf}, which is able to recurse your
2515 package tree and run @command{automake} where appropriate.)
2517 You can optionally give @command{automake} an argument; @file{.am} is
2518 appended to the argument and the result is used as the name of the
2519 input file. This feature is generally only used to automatically
2520 rebuild an out-of-date @file{Makefile.in}. Note that
2521 @command{automake} must always be run from the topmost directory of a
2522 project, even if being used to regenerate the @file{Makefile.in} in
2523 some subdirectory. This is necessary because @command{automake} must
2524 scan @file{configure.ac}, and because @command{automake} uses the
2525 knowledge that a @file{Makefile.in} is in a subdirectory to change its
2526 behavior in some cases.
2529 Automake will run @command{autoconf} to scan @file{configure.ac} and
2530 its dependencies (i.e., @file{aclocal.m4} and any included file),
2531 therefore @command{autoconf} must be in your @env{PATH}. If there is
2532 an @env{AUTOCONF} variable in your environment it will be used
2533 instead of @command{autoconf}, this allows you to select a particular
2534 version of Autoconf. By the way, don't misunderstand this paragraph:
2535 @command{automake} runs @command{autoconf} to @strong{scan} your
2536 @file{configure.ac}, this won't build @file{configure} and you still
2537 have to run @command{autoconf} yourself for this purpose.
2539 @cindex @command{automake} options
2540 @cindex Options, @command{automake}
2541 @cindex Strictness, command line
2543 @command{automake} accepts the following options:
2545 @cindex Extra files distributed with Automake
2546 @cindex Files distributed with Automake
2547 @cindex @file{config.guess}
2551 @itemx --add-missing
2553 @opindex --add-missing
2554 Automake requires certain common files to exist in certain situations;
2555 for instance, @file{config.guess} is required if @file{configure.ac} invokes
2556 @code{AC_CANONICAL_HOST}. Automake is distributed with several of these
2557 files (@pxref{Auxiliary Programs}); this option will cause the missing
2558 ones to be automatically added to the package, whenever possible. In
2559 general if Automake tells you a file is missing, try using this option.
2560 By default Automake tries to make a symbolic link pointing to its own
2561 copy of the missing file; this can be changed with @option{--copy}.
2563 Many of the potentially-missing files are common scripts whose
2564 location may be specified via the @code{AC_CONFIG_AUX_DIR} macro.
2565 Therefore, @code{AC_CONFIG_AUX_DIR}'s setting affects whether a
2566 file is considered missing, and where the missing file is added
2569 In some strictness modes, additional files are installed, see @ref{Gnits}
2570 for more information.
2572 @item --libdir=@var{dir}
2574 Look for Automake data files in directory @var{dir} instead of in the
2575 installation directory. This is typically used for debugging.
2577 @item --print-libdir
2578 @opindex --print-libdir
2579 Print the path of the installation directory containing Automake-provided
2580 scripts and data files (like e.g., @file{texinfo.texi} and
2587 When used with @option{--add-missing}, causes installed files to be
2588 copied. The default is to make a symbolic link.
2592 @itemx --force-missing
2593 @opindex --force-missing
2594 When used with @option{--add-missing}, causes standard files to be reinstalled
2595 even if they already exist in the source tree. This involves removing
2596 the file from the source tree before creating the new symlink (or, with
2597 @option{--copy}, copying the new file).
2601 Set the global strictness to @option{foreign}. For more information, see
2606 Set the global strictness to @option{gnits}. For more information, see
2611 Set the global strictness to @option{gnu}. For more information, see
2612 @ref{Gnits}. This is the default strictness.
2616 Print a summary of the command line options and exit.
2619 @itemx --ignore-deps
2621 This disables the dependency tracking feature in generated
2622 @file{Makefile}s; see @ref{Dependencies}.
2624 @item --include-deps
2625 @opindex --include-deps
2626 This enables the dependency tracking feature. This feature is enabled
2627 by default. This option is provided for historical reasons only and
2628 probably should not be used.
2632 Ordinarily @command{automake} creates all @file{Makefile.in}s mentioned in
2633 @file{configure.ac}. This option causes it to only update those
2634 @file{Makefile.in}s that are out of date with respect to one of their
2638 @itemx --output-dir=@var{dir}
2640 @opindex --output-dir
2641 Put the generated @file{Makefile.in} in the directory @var{dir}.
2642 Ordinarily each @file{Makefile.in} is created in the directory of the
2643 corresponding @file{Makefile.am}. This option is deprecated and will be
2644 removed in a future release.
2650 Cause Automake to print information about which files are being read or
2655 Print the version number of Automake and exit.
2658 @itemx --warnings=@var{category}
2661 Output warnings falling in @var{category}. @var{category} can be
2665 warnings related to the GNU Coding Standards
2666 (@pxref{Top, , , standards, The GNU Coding Standards}).
2668 obsolete features or constructions
2670 user redefinitions of Automake rules or variables
2672 portability issues (e.g., use of @command{make} features that are
2673 known to be not portable)
2674 @item extra-portability
2675 extra portability issues related to obscure tools. One example of such
2676 a tool is the Microsoft @command{lib} archiver.
2678 weird syntax, unused variables, typos
2680 unsupported or incomplete features
2684 turn off all the warnings
2686 treat warnings as errors
2689 A category can be turned off by prefixing its name with @samp{no-}. For
2690 instance, @option{-Wno-syntax} will hide the warnings about unused
2693 The categories output by default are @samp{syntax} and
2694 @samp{unsupported}. Additionally, @samp{gnu} and @samp{portability}
2695 are enabled in @option{--gnu} and @option{--gnits} strictness.
2697 @c Checked by extra-portability.sh
2698 Turning off @samp{portability} will also turn off @samp{extra-portability},
2699 and similarly turning on @samp{extra-portability} will also turn on
2700 @samp{portability}. However, turning on @samp{portability} or turning
2701 off @samp{extra-portability} will not affect the other category.
2704 The environment variable @env{WARNINGS} can contain a comma separated
2705 list of categories to enable. It will be taken into account before the
2706 command-line switches, this way @option{-Wnone} will also ignore any
2707 warning category enabled by @env{WARNINGS}. This variable is also used
2708 by other tools like @command{autoconf}; unknown categories are ignored
2713 @vindex AUTOMAKE_JOBS
2714 If the environment variable @env{AUTOMAKE_JOBS} contains a positive
2715 number, it is taken as the maximum number of Perl threads to use in
2716 @command{automake} for generating multiple @file{Makefile.in} files
2717 concurrently. This is an experimental feature.
2721 @chapter Scanning @file{configure.ac}, using @command{aclocal}
2723 @cindex @file{configure.ac}, scanning
2724 @cindex Scanning @file{configure.ac}
2725 @cindex Using @command{aclocal}
2726 @cindex @command{aclocal}, using
2728 Automake scans the package's @file{configure.ac} to determine certain
2729 information about the package. Some @command{autoconf} macros are required
2730 and some variables must be defined in @file{configure.ac}. Automake
2731 will also use information from @file{configure.ac} to further tailor its
2734 Automake also supplies some Autoconf macros to make the maintenance
2735 easier. These macros can automatically be put into your
2736 @file{aclocal.m4} using the @command{aclocal} program.
2739 * Requirements:: Configuration requirements
2740 * Optional:: Other things Automake recognizes
2741 * aclocal Invocation:: Auto-generating aclocal.m4
2742 * Macros:: Autoconf macros supplied with Automake
2747 @section Configuration requirements
2749 @cindex Automake requirements
2750 @cindex Requirements of Automake
2752 @acindex AM_INIT_AUTOMAKE
2753 The one real requirement of Automake is that your @file{configure.ac}
2754 call @code{AM_INIT_AUTOMAKE}. This macro does several things that are
2755 required for proper Automake operation (@pxref{Macros}).
2757 Here are the other macros that Automake requires but which are not run
2758 by @code{AM_INIT_AUTOMAKE}:
2761 @item AC_CONFIG_FILES
2763 @acindex AC_CONFIG_FILES
2765 These two macros are usually invoked as follows near the end of
2766 @file{configure.ac}.
2780 Automake uses these to determine which files to create (@pxref{Output, ,
2781 Creating Output Files, autoconf, The Autoconf Manual}). A listed file
2782 is considered to be an Automake generated @file{Makefile} if there
2783 exists a file with the same name and the @file{.am} extension appended.
2784 Typically, @samp{AC_CONFIG_FILES([foo/Makefile])} will cause Automake to
2785 generate @file{foo/Makefile.in} if @file{foo/Makefile.am} exists.
2787 When using @code{AC_CONFIG_FILES} with multiple input files, as in
2790 AC_CONFIG_FILES([Makefile:top.in:Makefile.in:bot.in])
2794 @command{automake} will generate the first @file{.in} input file for
2795 which a @file{.am} file exists. If no such file exists the output
2796 file is not considered to be generated by Automake.
2798 Files created by @code{AC_CONFIG_FILES}, be they Automake
2799 @file{Makefile}s or not, are all removed by @samp{make distclean}.
2800 Their inputs are automatically distributed, unless they
2801 are the output of prior @code{AC_CONFIG_FILES} commands.
2802 Finally, rebuild rules are generated in the Automake @file{Makefile}
2803 existing in the subdirectory of the output file, if there is one, or
2804 in the top-level @file{Makefile} otherwise.
2806 The above machinery (cleaning, distributing, and rebuilding) works
2807 fine if the @code{AC_CONFIG_FILES} specifications contain only
2808 literals. If part of the specification uses shell variables,
2809 @command{automake} will not be able to fulfill this setup, and you will
2810 have to complete the missing bits by hand. For instance, on
2812 @c Keep in sync with output11.sh
2816 AC_CONFIG_FILES([output:$file],, [file=$file])
2820 @command{automake} will output rules to clean @file{output}, and
2821 rebuild it. However the rebuild rule will not depend on @file{input},
2822 and this file will not be distributed either. (You must add
2823 @samp{EXTRA_DIST = input} to your @file{Makefile.am} if @file{input} is a
2828 @c Keep in sync with output11.sh
2833 AC_CONFIG_FILES([$file:input],, [file=$file])
2834 AC_CONFIG_FILES([$file2],, [file2=$file2])
2838 will only cause @file{input} to be distributed. No file will be
2839 cleaned automatically (add @samp{DISTCLEANFILES = output out}
2840 yourself), and no rebuild rule will be output.
2842 Obviously @command{automake} cannot guess what value @samp{$file} is
2843 going to hold later when @file{configure} is run, and it cannot use
2844 the shell variable @samp{$file} in a @file{Makefile}. However, if you
2845 make reference to @samp{$file} as @samp{$@{file@}} (i.e., in a way
2846 that is compatible with @command{make}'s syntax) and furthermore use
2847 @code{AC_SUBST} to ensure that @samp{$@{file@}} is meaningful in a
2848 @file{Makefile}, then @command{automake} will be able to use
2849 @samp{$@{file@}} to generate all of these rules. For instance, here is
2850 how the Automake package itself generates versioned scripts for its
2854 AC_SUBST([APIVERSION], @dots{})
2857 [tests/aclocal-$@{APIVERSION@}:tests/aclocal.in],
2858 [chmod +x tests/aclocal-$@{APIVERSION@}],
2859 [APIVERSION=$APIVERSION])
2861 [tests/automake-$@{APIVERSION@}:tests/automake.in],
2862 [chmod +x tests/automake-$@{APIVERSION@}])
2866 Here cleaning, distributing, and rebuilding are done automatically,
2867 because @samp{$@{APIVERSION@}} is known at @command{make}-time.
2869 Note that you should not use shell variables to declare
2870 @file{Makefile} files for which @command{automake} must create
2871 @file{Makefile.in}. Even @code{AC_SUBST} does not help here, because
2872 @command{automake} needs to know the file name when it runs in order
2873 to check whether @file{Makefile.am} exists. (In the very hairy case
2874 that your setup requires such use of variables, you will have to tell
2875 Automake which @file{Makefile.in}s to generate on the command-line.)
2877 It is possible to let @command{automake} emit conditional rules for
2878 @code{AC_CONFIG_FILES} with the help of @code{AM_COND_IF}
2884 Use literals for @file{Makefile}s, and for other files whenever possible.
2886 Use @samp{$file} (or @samp{$@{file@}} without @samp{AC_SUBST([file])})
2887 for files that @command{automake} should ignore.
2889 Use @samp{$@{file@}} and @samp{AC_SUBST([file])} for files
2890 that @command{automake} should not ignore.
2897 @section Other things Automake recognizes
2899 @cindex Macros Automake recognizes
2900 @cindex Recognized macros by Automake
2902 Every time Automake is run it calls Autoconf to trace
2903 @file{configure.ac}. This way it can recognize the use of certain
2904 macros and tailor the generated @file{Makefile.in} appropriately.
2905 Currently recognized macros and their effects are:
2908 @item AC_CANONICAL_BUILD
2909 @itemx AC_CANONICAL_HOST
2910 @itemx AC_CANONICAL_TARGET
2911 @vindex build_triplet
2912 @vindex host_triplet
2913 @vindex target_triplet
2914 Automake will ensure that @file{config.guess} and @file{config.sub}
2915 exist. Also, the @file{Makefile} variables @code{build_triplet},
2916 @code{host_triplet} and @code{target_triplet} are introduced. See
2917 @ref{Canonicalizing, , Getting the Canonical System Type, autoconf,
2918 The Autoconf Manual}.
2920 @item AC_CONFIG_AUX_DIR
2921 Automake will look for various helper scripts, such as
2922 @file{install-sh}, in the directory named in this macro invocation.
2923 @c This list is accurate relative to version 1.11
2924 (The full list of scripts is:
2926 @file{config.guess},
2934 @file{mkinstalldirs},
2939 Not all scripts are always searched for; some scripts
2940 will only be sought if the generated @file{Makefile.in} requires them.
2942 If @code{AC_CONFIG_AUX_DIR} is not given, the scripts are looked for in
2943 their standard locations. For @file{mdate-sh},
2944 @file{texinfo.tex}, and @file{ylwrap}, the standard location is the
2945 source directory corresponding to the current @file{Makefile.am}. For
2946 the rest, the standard location is the first one of @file{.}, @file{..},
2947 or @file{../..} (relative to the top source directory) that provides any
2948 one of the helper scripts. @xref{Input, , Finding `configure' Input,
2949 autoconf, The Autoconf Manual}.
2951 Required files from @code{AC_CONFIG_AUX_DIR} are automatically
2952 distributed, even if there is no @file{Makefile.am} in this directory.
2954 @item AC_CONFIG_LIBOBJ_DIR
2955 Automake will require the sources file declared with
2956 @code{AC_LIBSOURCE} (see below) in the directory specified by this
2959 @item AC_CONFIG_HEADERS
2960 Automake will generate rules to rebuild these headers. Older versions
2961 of Automake required the use of @code{AM_CONFIG_HEADER}; this is no
2962 longer the case, and that macro has indeed been removed.
2964 As with @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the
2965 specification using shell variables will be ignored as far as
2966 cleaning, distributing, and rebuilding is concerned.
2968 @item AC_CONFIG_LINKS
2969 Automake will generate rules to remove @file{configure} generated
2970 links on @samp{make distclean} and to distribute named source files as
2971 part of @samp{make dist}.
2973 As for @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the
2974 specification using shell variables will be ignored as far as cleaning
2975 and distributing is concerned. (There are no rebuild rules for links.)
2979 @itemx AC_LIBSOURCES
2981 Automake will automatically distribute any file listed in
2982 @code{AC_LIBSOURCE} or @code{AC_LIBSOURCES}.
2984 Note that the @code{AC_LIBOBJ} macro calls @code{AC_LIBSOURCE}. So if
2985 an Autoconf macro is documented to call @samp{AC_LIBOBJ([file])}, then
2986 @file{file.c} will be distributed automatically by Automake. This
2987 encompasses many macros like @code{AC_FUNC_ALLOCA},
2988 @code{AC_FUNC_MEMCMP}, @code{AC_REPLACE_FUNCS}, and others.
2990 By the way, direct assignments to @code{LIBOBJS} are no longer
2991 supported. You should always use @code{AC_LIBOBJ} for this purpose.
2992 @xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs.@: @code{LIBOBJS},
2993 autoconf, The Autoconf Manual}.
2995 @item AC_PROG_RANLIB
2996 This is required if any libraries are built in the package.
2997 @xref{Particular Programs, , Particular Program Checks, autoconf, The
3001 This is required if any C++ source is included. @xref{Particular
3002 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
3005 This is required if any Objective C source is included. @xref{Particular
3006 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
3008 @item AC_PROG_OBJCXX
3009 This is required if any Objective C++ source is included. @xref{Particular
3010 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
3013 This is required if any Fortran 77 source is included. @xref{Particular
3014 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
3016 @item AC_F77_LIBRARY_LDFLAGS
3017 This is required for programs and shared libraries that are a mixture of
3018 languages that include Fortran 77 (@pxref{Mixing Fortran 77 With C and
3019 C++}). @xref{Macros, , Autoconf macros supplied with Automake}.
3022 Automake will add the flags computed by @code{AC_FC_SRCEXT} to compilation
3023 of files with the respective source extension (@pxref{Fortran Compiler, ,
3024 Fortran Compiler Characteristics, autoconf, The Autoconf Manual}).
3027 This is required if any Fortran 90/95 source is included. This macro is
3028 distributed with Autoconf version 2.58 and later. @xref{Particular
3029 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
3031 @item AC_PROG_LIBTOOL
3032 Automake will turn on processing for @command{libtool} (@pxref{Top, ,
3033 Introduction, libtool, The Libtool Manual}).
3037 If a Yacc source file is seen, then you must either use this macro or
3038 define the variable @code{YACC} in @file{configure.ac}. The former is
3039 preferred (@pxref{Particular Programs, , Particular Program Checks,
3040 autoconf, The Autoconf Manual}).
3043 If a Lex source file is seen, then this macro must be used.
3044 @xref{Particular Programs, , Particular Program Checks, autoconf, The
3047 @item AC_REQUIRE_AUX_FILE
3048 For each @code{AC_REQUIRE_AUX_FILE([@var{file}])},
3049 @command{automake} will ensure that @file{@var{file}} exists in the
3050 aux directory, and will complain otherwise. It
3051 will also automatically distribute the file. This macro should be
3052 used by third-party Autoconf macros that require some supporting
3053 files in the aux directory specified with @code{AC_CONFIG_AUX_DIR}
3054 above. @xref{Input, , Finding @command{configure} Input, autoconf,
3055 The Autoconf Manual}.
3058 The first argument is automatically defined as a variable in each
3059 generated @file{Makefile.in}, unless @code{AM_SUBST_NOTMAKE} is also
3060 used for this variable. @xref{Setting Output Variables, , Setting
3061 Output Variables, autoconf, The Autoconf Manual}.
3063 For every substituted variable @var{var}, @command{automake} will add
3064 a line @code{@var{var} = @var{value}} to each @file{Makefile.in} file.
3065 Many Autoconf macros invoke @code{AC_SUBST} to set output variables
3066 this way, e.g., @code{AC_PATH_XTRA} defines @code{X_CFLAGS} and
3067 @code{X_LIBS}. Thus, you can access these variables as
3068 @code{$(X_CFLAGS)} and @code{$(X_LIBS)} in any @file{Makefile.am}
3069 if @code{AC_PATH_XTRA} is called.
3071 @item AM_CONDITIONAL
3072 This introduces an Automake conditional (@pxref{Conditionals}).
3075 This macro allows @code{automake} to detect subsequent access within
3076 @file{configure.ac} to a conditional previously introduced with
3077 @code{AM_CONDITIONAL}, thus enabling conditional @code{AC_CONFIG_FILES}
3078 (@pxref{Usage of Conditionals}).
3080 @item AM_GNU_GETTEXT
3081 This macro is required for packages that use GNU gettext
3082 (@pxref{gettext}). It is distributed with gettext. If Automake sees
3083 this macro it ensures that the package meets some of gettext's
3086 @item AM_GNU_GETTEXT_INTL_SUBDIR
3087 This macro specifies that the @file{intl/} subdirectory is to be built,
3088 even if the @code{AM_GNU_GETTEXT} macro was invoked with a first argument
3091 @item AM_MAINTAINER_MODE(@ovar{default-mode})
3092 @opindex --enable-maintainer-mode
3093 @opindex --disable-maintainer-mode
3094 This macro adds an @option{--enable-maintainer-mode} option to
3095 @command{configure}. If this is used, @command{automake} will cause
3096 ``maintainer-only'' rules to be turned off by default in the
3097 generated @file{Makefile.in}s, unless @var{default-mode} is
3098 @samp{enable}. This macro defines the @code{MAINTAINER_MODE}
3099 conditional, which you can use in your own @file{Makefile.am}.
3100 @xref{maintainer-mode}.
3102 @item AM_SUBST_NOTMAKE(@var{var})
3103 Prevent Automake from defining a variable @var{var}, even if it is
3104 substituted by @command{config.status}. Normally, Automake defines a
3105 @command{make} variable for each @command{configure} substitution,
3106 i.e., for each @code{AC_SUBST([@var{var}])}. This macro prevents that
3107 definition from Automake. If @code{AC_SUBST} has not been called
3108 for this variable, then @code{AM_SUBST_NOTMAKE} has no effects.
3109 Preventing variable definitions may be useful for substitution of
3110 multi-line values, where @code{@var{var} = @@@var{value}@@} might yield
3114 Files included by @file{configure.ac} using this macro will be
3115 detected by Automake and automatically distributed. They will also
3116 appear as dependencies in @file{Makefile} rules.
3118 @code{m4_include} is seldom used by @file{configure.ac} authors, but
3119 can appear in @file{aclocal.m4} when @command{aclocal} detects that
3120 some required macros come from files local to your package (as opposed to
3121 macros installed in a system-wide directory, @pxref{aclocal Invocation}).
3125 @node aclocal Invocation
3126 @section Auto-generating aclocal.m4
3127 @c This node used to be named "Invoking automake". This @anchor
3128 @c allows old links to still work.
3129 @anchor{Invoking aclocal}
3131 @cindex Invocation of @command{aclocal}
3132 @cindex @command{aclocal}, Invocation
3133 @cindex Invoking @command{aclocal}
3134 @cindex @command{aclocal}, Invoking
3136 Automake includes a number of Autoconf macros that can be used in
3137 your package (@pxref{Macros}); some of them are actually required by
3138 Automake in certain situations. These macros must be defined in your
3139 @file{aclocal.m4}; otherwise they will not be seen by
3142 The @command{aclocal} program will automatically generate
3143 @file{aclocal.m4} files based on the contents of @file{configure.ac}.
3144 This provides a convenient way to get Automake-provided macros,
3145 without having to search around. The @command{aclocal} mechanism
3146 allows other packages to supply their own macros (@pxref{Extending
3147 aclocal}). You can also use it to maintain your own set of custom
3148 macros (@pxref{Local Macros}).
3150 At startup, @command{aclocal} scans all the @file{.m4} files it can
3151 find, looking for macro definitions (@pxref{Macro Search Path}). Then
3152 it scans @file{configure.ac}. Any mention of one of the macros found
3153 in the first step causes that macro, and any macros it in turn
3154 requires, to be put into @file{aclocal.m4}.
3156 @emph{Putting} the file that contains the macro definition into
3157 @file{aclocal.m4} is usually done by copying the entire text of this
3158 file, including unused macro definitions as well as both @samp{#} and
3159 @samp{dnl} comments. If you want to make a comment that will be
3160 completely ignored by @command{aclocal}, use @samp{##} as the comment
3163 When a file selected by @command{aclocal} is located in a subdirectory
3164 specified as a relative search path with @command{aclocal}'s @option{-I}
3165 argument, @command{aclocal} assumes the file belongs to the package
3166 and uses @code{m4_include} instead of copying it into
3167 @file{aclocal.m4}. This makes the package smaller, eases dependency
3168 tracking, and cause the file to be distributed automatically.
3169 (@xref{Local Macros}, for an example.) Any macro that is found in a
3170 system-wide directory, or via an absolute search path will be copied.
3171 So use @samp{-I `pwd`/reldir} instead of @samp{-I reldir} whenever
3172 some relative directory should be considered outside the package.
3174 The contents of @file{acinclude.m4}, if this file exists, are also
3175 automatically included in @file{aclocal.m4}. We recommend against
3176 using @file{acinclude.m4} in new packages (@pxref{Local Macros}).
3180 While computing @file{aclocal.m4}, @command{aclocal} runs
3181 @command{autom4te} (@pxref{Using autom4te, , Using @command{Autom4te},
3182 autoconf, The Autoconf Manual}) in order to trace the macros that are
3183 really used, and omit from @file{aclocal.m4} all macros that are
3184 mentioned but otherwise unexpanded (this can happen when a macro is
3185 called conditionally). @command{autom4te} is expected to be in the
3186 @env{PATH}, just as @command{autoconf}. Its location can be
3187 overridden using the @env{AUTOM4TE} environment variable.
3190 * aclocal Options:: Options supported by aclocal
3191 * Macro Search Path:: How aclocal finds .m4 files
3192 * Extending aclocal:: Writing your own aclocal macros
3193 * Local Macros:: Organizing local macros
3194 * Serials:: Serial lines in Autoconf macros
3195 * Future of aclocal:: aclocal's scheduled death
3198 @node aclocal Options
3199 @subsection aclocal Options
3201 @cindex @command{aclocal}, Options
3202 @cindex Options, @command{aclocal}
3204 @command{aclocal} accepts the following options:
3207 @item --automake-acdir=@var{dir}
3208 @opindex --automake-acdir
3209 Look for the automake-provided macro files in @var{dir} instead of
3210 in the installation directory. This is typically used for debugging.
3212 @item --system-acdir=@var{dir}
3213 @opindex --system-acdir
3214 Look for the system-wide third-party macro files (and the special
3215 @file{dirlist} file) in @var{dir} instead of in the installation
3216 directory. This is typically used for debugging.
3218 @item --diff[=@var{command}]
3220 Run @var{command} on M4 file that would be installed or overwritten
3221 by @option{--install}. The default @var{command} is @samp{diff -u}.
3222 This option implies @option{--install} and @option{--dry-run}.
3226 Do not actually overwrite (or create) @file{aclocal.m4} and M4
3227 files installed by @option{--install}.
3231 Print a summary of the command line options and exit.
3235 Add the directory @var{dir} to the list of directories searched for
3240 Install system-wide third-party macros into the first directory
3241 specified with @samp{-I @var{dir}} instead of copying them in the
3243 @c Keep in sync with aclocal-install-absdir.sh
3244 Note that this will happen also if @var{dir} is an absolute path.
3246 @cindex serial number and @option{--install}
3247 When this option is used, and only when this option is used,
3248 @command{aclocal} will also honor @samp{#serial @var{number}} lines
3249 that appear in macros: an M4 file is ignored if there exists another
3250 M4 file with the same basename and a greater serial number in the
3251 search path (@pxref{Serials}).
3255 Always overwrite the output file. The default is to overwrite the output
3256 file only when really needed, i.e., when its contents changes or if one
3257 of its dependencies is younger.
3259 This option forces the update of @file{aclocal.m4} (or the file
3260 specified with @file{--output} below) and only this file, it has
3261 absolutely no influence on files that may need to be installed by
3264 @item --output=@var{file}
3266 Cause the output to be put into @var{file} instead of @file{aclocal.m4}.
3268 @item --print-ac-dir
3269 @opindex --print-ac-dir
3270 Prints the name of the directory that @command{aclocal} will search to
3271 find third-party @file{.m4} files. When this option is given, normal
3272 processing is suppressed. This option was used @emph{in the past} by
3273 third-party packages to determine where to install @file{.m4} macro
3274 files, but @emph{this usage is today discouraged}, since it causes
3275 @samp{$(prefix)} not to be thoroughly honoured (which violates the
3276 GNU Coding Standards), and a similar semantics can be better obtained
3277 with the @env{ACLOCAL_PATH} environment variable; @pxref{Extending aclocal}.
3281 Print the names of the files it examines.
3285 Print the version number of Automake and exit.
3288 @item --warnings=@var{category}
3291 Output warnings falling in @var{category}. @var{category} can be
3295 dubious syntactic constructs, underquoted macros, unused macros, etc.
3299 all the warnings, this is the default
3301 turn off all the warnings
3303 treat warnings as errors
3306 All warnings are output by default.
3309 The environment variable @env{WARNINGS} is honored in the same
3310 way as it is for @command{automake} (@pxref{automake Invocation}).
3314 @node Macro Search Path
3315 @subsection Macro Search Path
3317 @cindex Macro search path
3318 @cindex @command{aclocal} search path
3320 By default, @command{aclocal} searches for @file{.m4} files in the following
3321 directories, in this order:
3324 @item @var{acdir-APIVERSION}
3325 This is where the @file{.m4} macros distributed with Automake itself
3326 are stored. @var{APIVERSION} depends on the Automake release used;
3327 for example, for Automake 1.11.x, @var{APIVERSION} = @code{1.11}.
3330 This directory is intended for third party @file{.m4} files, and is
3331 configured when @command{automake} itself is built. This is
3332 @file{@@datadir@@/aclocal/}, which typically
3333 expands to @file{$@{prefix@}/share/aclocal/}. To find the compiled-in
3334 value of @var{acdir}, use the @option{--print-ac-dir} option
3335 (@pxref{aclocal Options}).
3338 As an example, suppose that @command{automake-1.11.2} was configured with
3339 @option{--prefix=@-/usr/local}. Then, the search path would be:
3342 @item @file{/usr/local/share/aclocal-1.11.2/}
3343 @item @file{/usr/local/share/aclocal/}
3346 The paths for the @var{acdir} and @var{acdir-APIVERSION} directories can
3347 be changed respectively through aclocal options @option{--system-acdir}
3348 and @option{--automake-acdir} (@pxref{aclocal Options}). Note however
3349 that these options are only intended for use by the internal Automake
3350 test suite, or for debugging under highly unusual situations; they are
3351 not ordinarily needed by end-users.
3353 As explained in (@pxref{aclocal Options}), there are several options that
3354 can be used to change or extend this search path.
3356 @subsubheading Modifying the Macro Search Path: @samp{-I @var{dir}}
3358 Any extra directories specified using @option{-I} options
3359 (@pxref{aclocal Options}) are @emph{prepended} to this search list. Thus,
3360 @samp{aclocal -I /foo -I /bar} results in the following search path:
3365 @item @var{acdir}-@var{APIVERSION}
3369 @subsubheading Modifying the Macro Search Path: @file{dirlist}
3370 @cindex @file{dirlist}
3372 There is a third mechanism for customizing the search path. If a
3373 @file{dirlist} file exists in @var{acdir}, then that file is assumed to
3374 contain a list of directory patterns, one per line. @command{aclocal}
3375 expands these patterns to directory names, and adds them to the search
3376 list @emph{after} all other directories. @file{dirlist} entries may
3377 use shell wildcards such as @samp{*}, @samp{?}, or @code{[...]}.
3379 For example, suppose
3380 @file{@var{acdir}/dirlist} contains the following:
3389 and that @command{aclocal} was called with the @samp{-I /foo -I /bar} options.
3390 Then, the search path would be
3392 @c @code looks better than @file here
3396 @item @var{acdir}-@var{APIVERSION}
3403 and all directories with path names starting with @code{/test3}.
3405 If the @option{--system-acdir=@var{dir}} option is used, then
3406 @command{aclocal} will search for the @file{dirlist} file in
3407 @var{dir}; but remember the warnings above against the use of
3408 @option{--system-acdir}.
3410 @file{dirlist} is useful in the following situation: suppose that
3411 @command{automake} version @code{1.11.2} is installed with
3412 @samp{--prefix=/usr} by the system vendor. Thus, the default search
3415 @c @code looks better than @file here
3417 @item @code{/usr/share/aclocal-1.11/}
3418 @item @code{/usr/share/aclocal/}
3421 However, suppose further that many packages have been manually
3422 installed on the system, with $prefix=/usr/local, as is typical. In
3423 that case, many of these ``extra'' @file{.m4} files are in
3424 @file{/usr/local/share/aclocal}. The only way to force
3425 @file{/usr/bin/aclocal} to find these ``extra'' @file{.m4} files is to
3426 always call @samp{aclocal -I /usr/local/share/aclocal}. This is
3427 inconvenient. With @file{dirlist}, one may create a file
3428 @file{/usr/share/aclocal/dirlist} containing only the single line
3431 /usr/local/share/aclocal
3434 Now, the ``default'' search path on the affected system is
3436 @c @code looks better than @file here
3438 @item @code{/usr/share/aclocal-1.11/}
3439 @item @code{/usr/share/aclocal/}
3440 @item @code{/usr/local/share/aclocal/}
3443 without the need for @option{-I} options; @option{-I} options can be reserved
3444 for project-specific needs (@file{my-source-dir/m4/}), rather than
3445 using it to work around local system-dependent tool installation
3448 Similarly, @file{dirlist} can be handy if you have installed a local
3449 copy of Automake in your account and want @command{aclocal} to look for
3450 macros installed at other places on the system.
3452 @anchor{ACLOCAL_PATH}
3453 @subsubheading Modifying the Macro Search Path: @file{ACLOCAL_PATH}
3454 @cindex @env{ACLOCAL_PATH}
3456 The fourth and last mechanism to customize the macro search path is
3457 also the simplest. Any directory included in the colon-separated
3458 environment variable @env{ACLOCAL_PATH} is added to the search path
3459 @c Keep in sync with aclocal-path-precedence.sh
3460 and takes precedence over system directories (including those found via
3461 @file{dirlist}), with the exception of the versioned directory
3462 @var{acdir-APIVERSION} (@pxref{Macro Search Path}). However, directories
3463 passed via @option{-I} will take precedence over directories in
3466 @c Keep in sync with aclocal-path-installed.sh
3467 Also note that, if the @option{--install} option is used, any @file{.m4}
3468 file containing a required macro that is found in a directory listed in
3469 @env{ACLOCAL_PATH} will be installed locally.
3470 @c Keep in sync with aclocal-path-installed-serial.sh
3471 In this case, serial numbers in @file{.m4} are honoured too,
3474 Conversely to @file{dirlist}, @env{ACLOCAL_PATH} is useful if you are
3475 using a global copy of Automake and want @command{aclocal} to look for
3476 macros somewhere under your home directory.
3478 @subsubheading Planned future incompatibilities
3480 The order in which the directories in the macro search path are currently
3481 looked up is confusing and/or suboptimal in various aspects, and is
3482 probably going to be changed in the future Automake release. In
3483 particular, directories in @env{ACLOCAL_PATH} and @file{@var{acdir}}
3484 might end up taking precedence over @file{@var{acdir-APIVERSION}}, and
3485 directories in @file{@var{acdir}/dirlist} might end up taking precedence
3486 over @file{@var{acdir}}. @emph{This is a possible future incompatibility!}
3488 @node Extending aclocal
3489 @subsection Writing your own aclocal macros
3491 @cindex @command{aclocal}, extending
3492 @cindex Extending @command{aclocal}
3494 The @command{aclocal} program doesn't have any built-in knowledge of any
3495 macros, so it is easy to extend it with your own macros.
3497 This can be used by libraries that want to supply their own Autoconf
3498 macros for use by other programs. For instance, the @command{gettext}
3499 library supplies a macro @code{AM_GNU_GETTEXT} that should be used by
3500 any package using @command{gettext}. When the library is installed, it
3501 installs this macro so that @command{aclocal} will find it.
3503 A macro file's name should end in @file{.m4}. Such files should be
3504 installed in @file{$(datadir)/aclocal}. This is as simple as writing:
3506 @c Keep in sync with primary-prefix-couples-documented-valid.sh
3508 aclocaldir = $(datadir)/aclocal
3509 aclocal_DATA = mymacro.m4 myothermacro.m4
3513 Please do use @file{$(datadir)/aclocal}, and not something based on
3514 the result of @samp{aclocal --print-ac-dir} (@pxref{Hard-Coded Install
3515 Paths}, for arguments). It might also be helpful to suggest to
3516 the user to add the @file{$(datadir)/aclocal} directory to his
3517 @env{ACLOCAL_PATH} variable (@pxref{ACLOCAL_PATH}) so that
3518 @command{aclocal} will find the @file{.m4} files installed by your
3519 package automatically.
3521 A file of macros should be a series of properly quoted
3522 @code{AC_DEFUN}'s (@pxref{Macro Definitions, , , autoconf, The
3523 Autoconf Manual}). The @command{aclocal} programs also understands
3524 @code{AC_REQUIRE} (@pxref{Prerequisite Macros, , , autoconf, The
3525 Autoconf Manual}), so it is safe to put each macro in a separate file.
3526 Each file should have no side effects but macro definitions.
3527 Especially, any call to @code{AC_PREREQ} should be done inside the
3528 defined macro, not at the beginning of the file.
3530 @cindex underquoted @code{AC_DEFUN}
3534 Starting with Automake 1.8, @command{aclocal} will warn about all
3535 underquoted calls to @code{AC_DEFUN}. We realize this will annoy a
3536 lot of people, because @command{aclocal} was not so strict in the past
3537 and many third party macros are underquoted; and we have to apologize
3538 for this temporary inconvenience. The reason we have to be stricter
3539 is that a future implementation of @command{aclocal} (@pxref{Future of
3540 aclocal}) will have to temporarily include all of these third party
3541 @file{.m4} files, maybe several times, including even files that are
3542 not actually needed. Doing so should alleviate many problems of the
3543 current implementation, however it requires a stricter style from the
3544 macro authors. Hopefully it is easy to revise the existing macros.
3551 [AC_REQUIRE([AX_SOMETHING])dnl
3558 should be rewritten as
3561 AC_DEFUN([AX_FOOBAR],
3562 [AC_PREREQ([2.68])dnl
3563 AC_REQUIRE([AX_SOMETHING])dnl
3569 Wrapping the @code{AC_PREREQ} call inside the macro ensures that
3570 Autoconf 2.68 will not be required if @code{AX_FOOBAR} is not actually
3571 used. Most importantly, quoting the first argument of @code{AC_DEFUN}
3572 allows the macro to be redefined or included twice (otherwise this
3573 first argument would be expanded during the second definition). For
3574 consistency we like to quote even arguments such as @code{2.68} that
3577 If you have been directed here by the @command{aclocal} diagnostic but
3578 are not the maintainer of the implicated macro, you will want to
3579 contact the maintainer of that macro. Please make sure you have the
3580 latest version of the macro and that the problem hasn't already been
3581 reported before doing so: people tend to work faster when they aren't
3584 Another situation where @command{aclocal} is commonly used is to
3585 manage macros that are used locally by the package, @ref{Local
3589 @subsection Handling Local Macros
3591 Feature tests offered by Autoconf do not cover all needs. People
3592 often have to supplement existing tests with their own macros, or
3593 with third-party macros.
3595 There are two ways to organize custom macros in a package.
3597 The first possibility (the historical practice) is to list all your
3598 macros in @file{acinclude.m4}. This file will be included in
3599 @file{aclocal.m4} when you run @command{aclocal}, and its macro(s) will
3600 henceforth be visible to @command{autoconf}. However if it contains
3601 numerous macros, it will rapidly become difficult to maintain, and it
3602 will be almost impossible to share macros between packages.
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/}. Then it's enough to update
3607 @file{configure.ac} by adding a proper call to @code{AC_CONFIG_MACRO_DIR}:
3610 AC_CONFIG_MACRO_DIR([m4])
3613 @command{aclocal} will then take care of automatically adding @file{m4/}
3614 to its search path for m4 files.
3616 When @samp{aclocal} is run, it will build an @file{aclocal.m4}
3617 that @code{m4_include}s any file from @file{m4/} that defines a
3618 required macro. Macros not found locally will still be searched in
3619 system-wide directories, as explained in @ref{Macro Search Path}.
3621 Custom macros should be distributed for the same reason that
3622 @file{configure.ac} is: so that other people have all the sources of
3623 your package if they want to work on it. Actually, this distribution
3624 happens automatically because all @code{m4_include}d files are
3627 However there is no consensus on the distribution of third-party
3628 macros that your package may use. Many libraries install their own
3629 macro in the system-wide @command{aclocal} directory (@pxref{Extending
3630 aclocal}). For instance, Guile ships with a file called
3631 @file{guile.m4} that contains the macro @code{GUILE_FLAGS} that can
3632 be used to define setup compiler and linker flags appropriate for
3633 using Guile. Using @code{GUILE_FLAGS} in @file{configure.ac} will
3634 cause @command{aclocal} to copy @file{guile.m4} into
3635 @file{aclocal.m4}, but as @file{guile.m4} is not part of the project,
3636 it will not be distributed. Technically, that means a user who
3637 needs to rebuild @file{aclocal.m4} will have to install Guile first.
3638 This is probably OK, if Guile already is a requirement to build the
3639 package. However, if Guile is only an optional feature, or if your
3640 package might run on architectures where Guile cannot be installed,
3641 this requirement will hinder development. An easy solution is to copy
3642 such third-party macros in your local @file{m4/} directory so they get
3645 Since Automake 1.10, @command{aclocal} offers the option @code{--install}
3646 to copy these system-wide third-party macros in your local macro directory,
3647 helping to solve the above problem.
3649 With this setup, system-wide macros will be copied to @file{m4/}
3650 the first time you run @command{aclocal}. Then the locally installed
3651 macros will have precedence over the system-wide installed macros
3652 each time @command{aclocal} is run again.
3654 One reason why you should keep @option{--install} in the flags even
3655 after the first run is that when you later edit @file{configure.ac}
3656 and depend on a new macro, this macro will be installed in your
3657 @file{m4/} automatically. Another one is that serial numbers
3658 (@pxref{Serials}) can be used to update the macros in your source tree
3659 automatically when new system-wide versions are installed. A serial
3660 number should be a single line of the form
3667 where @var{nnn} contains only digits and dots. It should appear in
3668 the M4 file before any macro definition. It is a good practice to
3669 maintain a serial number for each macro you distribute, even if you do
3670 not use the @option{--install} option of @command{aclocal}: this allows
3671 other people to use it.
3675 @subsection Serial Numbers
3676 @cindex serial numbers in macros
3677 @cindex macro serial numbers
3678 @cindex @code{#serial} syntax
3679 @cindex @command{aclocal} and serial numbers
3681 Because third-party macros defined in @file{*.m4} files are naturally
3682 shared between multiple projects, some people like to version them.
3683 This makes it easier to tell which of two M4 files is newer. Since at
3684 least 1996, the tradition is to use a @samp{#serial} line for this.
3686 A serial number should be a single line of the form
3689 # serial @var{version}
3693 where @var{version} is a version number containing only digits and
3694 dots. Usually people use a single integer, and they increment it each
3695 time they change the macro (hence the name of ``serial''). Such a
3696 line should appear in the M4 file before any macro definition.
3698 The @samp{#} must be the first character on the line,
3699 and it is OK to have extra words after the version, as in
3702 #serial @var{version} @var{garbage}
3705 Normally these serial numbers are completely ignored by
3706 @command{aclocal} and @command{autoconf}, like any genuine comment.
3707 However when using @command{aclocal}'s @option{--install} feature, these
3708 serial numbers will modify the way @command{aclocal} selects the
3709 macros to install in the package: if two files with the same basename
3710 exist in your search path, and if at least one of them uses a
3711 @samp{#serial} line, @command{aclocal} will ignore the file that has
3712 the older @samp{#serial} line (or the file that has none).
3714 Note that a serial number applies to a whole M4 file, not to any macro
3715 it contains. A file can contains multiple macros, but only one
3718 Here is a use case that illustrates the use of @option{--install} and
3719 its interaction with serial numbers. Let's assume we maintain a
3720 package called MyPackage, the @file{configure.ac} of which requires a
3721 third-party macro @code{AX_THIRD_PARTY} defined in
3722 @file{/usr/share/aclocal/thirdparty.m4} as follows:
3726 AC_DEFUN([AX_THIRD_PARTY], [...])
3729 MyPackage uses an @file{m4/} directory to store local macros as
3730 explained in @ref{Local Macros}, and has
3733 AC_CONFIG_MACRO_DIR([m4])
3737 in its @file{configure.ac}.
3739 Initially the @file{m4/} directory is empty. The first time we run
3740 @command{aclocal --install}, it will notice that
3744 @file{configure.ac} uses @code{AX_THIRD_PARTY}
3746 No local macros define @code{AX_THIRD_PARTY}
3748 @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3753 Because @file{/usr/share/aclocal/thirdparty.m4} is a system-wide macro
3754 and @command{aclocal} was given the @option{--install} option, it will
3755 copy this file in @file{m4/thirdparty.m4}, and output an
3756 @file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}.
3758 The next time @samp{aclocal --install} is run, something different
3759 happens. @command{aclocal} notices that
3763 @file{configure.ac} uses @code{AX_THIRD_PARTY}
3765 @file{m4/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3768 @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3773 Because both files have the same serial number, @command{aclocal} uses
3774 the first it found in its search path order (@pxref{Macro Search
3775 Path}). @command{aclocal} therefore ignores
3776 @file{/usr/share/aclocal/thirdparty.m4} and outputs an
3777 @file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}.
3779 Local directories specified with @option{-I} are always searched before
3780 system-wide directories, so a local file will always be preferred to
3781 the system-wide file in case of equal serial numbers.
3783 Now suppose the system-wide third-party macro is changed. This can
3784 happen if the package installing this macro is updated. Let's suppose
3785 the new macro has serial number 2. The next time @samp{aclocal --install}
3786 is run the situation is the following:
3790 @file{configure.ac} uses @code{AX_THIRD_PARTY}
3792 @file{m4/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3795 @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3800 When @command{aclocal} sees a greater serial number, it immediately
3801 forgets anything it knows from files that have the same basename and a
3802 smaller serial number. So after it has found
3803 @file{/usr/share/aclocal/thirdparty.m4} with serial 2,
3804 @command{aclocal} will proceed as if it had never seen
3805 @file{m4/thirdparty.m4}. This brings us back to a situation similar
3806 to that at the beginning of our example, where no local file defined
3807 the macro. @command{aclocal} will install the new version of the
3808 macro in @file{m4/thirdparty.m4}, in this case overriding the old
3809 version. MyPackage just had its macro updated as a side effect of
3810 running @command{aclocal}.
3812 If you are leery of letting @command{aclocal} update your local
3813 macro, you can run @samp{aclocal --diff} to review the changes
3814 @samp{aclocal --install} would perform on these macros.
3816 Finally, note that the @option{--force} option of @command{aclocal} has
3817 absolutely no effect on the files installed by @option{--install}. For
3818 instance, if you have modified your local macros, do not expect
3819 @option{--install --force} to replace the local macros by their
3820 system-wide versions. If you want to do so, simply erase the local
3821 macros you want to revert, and run @samp{aclocal --install}.
3824 @node Future of aclocal
3825 @subsection The Future of @command{aclocal}
3826 @cindex @command{aclocal}'s scheduled death
3828 @command{aclocal} is expected to disappear. This feature really
3829 should not be offered by Automake. Automake should focus on
3830 generating @file{Makefile}s; dealing with M4 macros really is
3831 Autoconf's job. The fact that some people install Automake just to use
3832 @command{aclocal}, but do not use @command{automake} otherwise is an
3833 indication of how that feature is misplaced.
3835 The new implementation will probably be done slightly differently.
3836 For instance, it could enforce the @file{m4/}-style layout discussed in
3839 We have no idea when and how this will happen. This has been
3840 discussed several times in the past, but someone still has to commit
3841 to that non-trivial task.
3843 From the user point of view, @command{aclocal}'s removal might turn
3844 out to be painful. There is a simple precaution that you may take to
3845 make that switch more seamless: never call @command{aclocal} yourself.
3846 Keep this guy under the exclusive control of @command{autoreconf} and
3847 Automake's rebuild rules. Hopefully you won't need to worry about
3848 things breaking, when @command{aclocal} disappears, because everything
3849 will have been taken care of. If otherwise you used to call
3850 @command{aclocal} directly yourself or from some script, you will
3851 quickly notice the change.
3853 Many packages come with a script called @file{bootstrap.sh} or
3854 @file{autogen.sh}, that will just call @command{aclocal},
3855 @command{libtoolize}, @command{gettextize} or @command{autopoint},
3856 @command{autoconf}, @command{autoheader}, and @command{automake} in
3857 the right order. Actually this is precisely what @command{autoreconf}
3858 can do for you. If your package has such a @file{bootstrap.sh} or
3859 @file{autogen.sh} script, consider using @command{autoreconf}. That
3860 should simplify its logic a lot (less things to maintain, yum!), it's
3861 even likely you will not need the script anymore, and more to the point
3862 you will not call @command{aclocal} directly anymore.
3864 For the time being, third-party packages should continue to install
3865 public macros into @file{/usr/share/aclocal/}. If @command{aclocal}
3866 is replaced by another tool it might make sense to rename the
3867 directory, but supporting @file{/usr/share/aclocal/} for backward
3868 compatibility should be really easy provided all macros are properly
3869 written (@pxref{Extending aclocal}).
3874 @section Autoconf macros supplied with Automake
3876 Automake ships with several Autoconf macros that you can use from your
3877 @file{configure.ac}. When you use one of them it will be included by
3878 @command{aclocal} in @file{aclocal.m4}.
3881 * Public Macros:: Macros that you can use.
3882 * Private Macros:: Macros that you should not use.
3885 @c consider generating the following subsections automatically from m4 files.
3888 @subsection Public Macros
3892 @item AM_INIT_AUTOMAKE([OPTIONS])
3893 @acindex AM_INIT_AUTOMAKE
3894 Runs many macros required for proper operation of the generated Makefiles.
3896 @vindex AUTOMAKE_OPTIONS
3897 @code{AM_INIT_AUTOMAKE} is called with a single argument: a space-separated
3898 list of Automake options that should be applied to every @file{Makefile.am}
3899 in the tree. The effect is as if each option were listed in
3900 @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
3902 @c FIXME: Remove this "modernization advice" in Automake 1.14 (and adjust
3903 @c FIXME: the error message in m4/init.m4:AM_INIT_AUTOMAKE accordingly).
3906 This macro could once (before Automake 1.13) also be called in the
3907 @emph{now obsolete and completely unsupported} form
3908 @code{AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])}. In this form,
3909 there were two required arguments: the package and the version number.
3911 @anchor{Modernize AM_INIT_AUTOMAKE invocation}
3912 If your @file{configure.ac} has:
3915 AC_INIT([src/foo.c])
3916 AM_INIT_AUTOMAKE([mumble], [1.5])
3920 you must modernize it as follows in order to make it work with Automake
3924 AC_INIT([mumble], [1.5])
3925 AC_CONFIG_SRCDIR([src/foo.c])
3929 Note that if you're upgrading your @file{configure.ac} from an earlier
3930 version of Automake, it is not always correct to simply move the
3931 package and version arguments from @code{AM_INIT_AUTOMAKE} directly to
3932 @code{AC_INIT}, as in the example above. The first argument to
3933 @code{AC_INIT} should be the name of your package (e.g., @samp{GNU
3934 Automake}), not the tarball name (e.g., @samp{automake}) that you used
3935 to pass to @code{AM_INIT_AUTOMAKE}. Autoconf tries to derive a
3936 tarball name from the package name, which should work for most but not
3937 all package names. (If it doesn't work for yours, you can use the
3938 four-argument form of @code{AC_INIT} to provide the tarball name
3941 @cindex @code{PACKAGE}, prevent definition
3942 @cindex @code{VERSION}, prevent definition
3944 By default this macro @code{AC_DEFINE}'s @code{PACKAGE} and
3945 @code{VERSION}. This can be avoided by passing the @option{no-define}
3948 AM_INIT_AUTOMAKE([gnits 1.5 no-define dist-bzip2])
3951 @item AM_PATH_LISPDIR
3952 @acindex AM_PATH_LISPDIR
3955 Searches for the program @command{emacs}, and, if found, sets the
3956 output variable @code{lispdir} to the full path to Emacs' site-lisp
3959 Note that this test assumes the @command{emacs} found to be a version
3960 that supports Emacs Lisp (such as GNU Emacs or XEmacs). Other
3961 emacsen can cause this test to hang (some, like old versions of
3962 MicroEmacs, start up in interactive mode, requiring @kbd{C-x C-c} to
3963 exit, which is hardly obvious for a non-emacs user). In most cases,
3964 however, you should be able to use @kbd{C-c} to kill the test. In
3965 order to avoid problems, you can set @env{EMACS} to ``no'' in the
3966 environment, or use the @option{--with-lispdir} option to
3967 @command{configure} to explicitly set the correct path (if you're sure
3968 you have an @command{emacs} that supports Emacs Lisp).
3970 @item AM_PROG_AR(@ovar{act-if-fail})
3973 You must use this macro when you use the archiver in your project, if
3974 you want support for unusual archivers such as Microsoft @command{lib}.
3975 The content of the optional argument is executed if the archiver
3976 interface is not recognized; the default action is to abort configure
3977 with an error message.
3983 Use this macro when you have assembly code in your project. This will
3984 choose the assembler for you (by default the C compiler) and set
3985 @code{CCAS}, and will also set @code{CCASFLAGS} if required.
3987 @item AM_PROG_CC_C_O
3988 @acindex AM_PROG_CC_C_O
3989 @acindex AC_PROG_CC_C_O
3990 This is like @code{AC_PROG_CC_C_O}, but it generates its results in
3991 the manner required by Automake. You must use this instead of
3992 @code{AC_PROG_CC_C_O} when you need this functionality, that is, when
3993 using per-target flags or subdir-objects with C sources.
3996 @acindex AM_PROG_LEX
3997 @acindex AC_PROG_LEX
3998 @cindex HP-UX 10, @command{lex} problems
3999 @cindex @command{lex} problems with HP-UX 10
4000 Like @code{AC_PROG_LEX} (@pxref{Particular Programs, , Particular
4001 Program Checks, autoconf, The Autoconf Manual}), but uses the
4002 @command{missing} script on systems that do not have @command{lex}.
4003 HP-UX 10 is one such system.
4006 @acindex AM_PROG_GCJ
4009 This macro finds the @command{gcj} program or causes an error. It sets
4010 @code{GCJ} and @code{GCJFLAGS}. @command{gcj} is the Java front-end to the
4011 GNU Compiler Collection.
4013 @item AM_PROG_UPC([@var{compiler-search-list}])
4014 @acindex AM_PROG_UPC
4016 Find a compiler for Unified Parallel C and define the @code{UPC}
4017 variable. The default @var{compiler-search-list} is @samp{upcc upc}.
4018 This macro will abort @command{configure} if no Unified Parallel C
4021 @item AM_MISSING_PROG(@var{name}, @var{program})
4022 @acindex AM_MISSING_PROG
4024 Find a maintainer tool @var{program} and define the @var{name}
4025 environment variable with its location. If @var{program} is not
4026 detected, then @var{name} will instead invoke the @command{missing}
4027 script, in order to give useful advice to the user about the missing
4028 maintainer tool. @xref{maintainer-mode}, for more information on when
4029 the @command{missing} script is appropriate.
4031 @item AM_SILENT_RULES
4032 @acindex AM_SILENT_RULES
4033 Control the machinery for less verbose build output
4034 (@pxref{Automake Silent Rules}).
4036 @item AM_WITH_DMALLOC
4037 @acindex AM_WITH_DMALLOC
4038 @cindex @command{dmalloc}, support for
4039 @vindex WITH_DMALLOC
4040 @opindex --with-dmalloc
4041 Add support for the @uref{http://dmalloc.com/, Dmalloc package}. If
4042 the user runs @command{configure} with @option{--with-dmalloc}, then
4043 define @code{WITH_DMALLOC} and add @option{-ldmalloc} to @code{LIBS}.
4048 @node Private Macros
4049 @subsection Private Macros
4051 The following macros are private macros you should not call directly.
4052 They are called by the other public macros when appropriate. Do not
4053 rely on them, as they might be changed in a future version. Consider
4054 them as implementation details; or better, do not consider them at all:
4058 @item _AM_DEPENDENCIES
4059 @itemx AM_SET_DEPDIR
4061 @itemx AM_OUTPUT_DEPENDENCY_COMMANDS
4062 These macros are used to implement Automake's automatic dependency
4063 tracking scheme. They are called automatically by Automake when
4064 required, and there should be no need to invoke them manually.
4066 @item AM_MAKE_INCLUDE
4067 This macro is used to discover how the user's @command{make} handles
4068 @code{include} statements. This macro is automatically invoked when
4069 needed; there should be no need to invoke it manually.
4071 @item AM_PROG_INSTALL_STRIP
4072 This is used to find a version of @code{install} that can be used to
4073 strip a program at installation time. This macro is automatically
4074 included when required.
4076 @item AM_SANITY_CHECK
4077 This checks to make sure that a file created in the build directory is
4078 newer than a file in the source directory. This can fail on systems
4079 where the clock is set incorrectly. This macro is automatically run
4080 from @code{AM_INIT_AUTOMAKE}.
4086 @chapter Directories
4088 For simple projects that distribute all files in the same directory
4089 it is enough to have a single @file{Makefile.am} that builds
4090 everything in place.
4092 In larger projects, it is common to organize files in different
4093 directories, in a tree. For example, there could be a directory
4094 for the program's source, one for the testsuite, and one for the
4095 documentation; or, for very large projects, there could be one
4096 directory per program, per library or per module.
4098 The traditional approach is to build these subdirectories recursively,
4099 employing @emph{make recursion}: each directory contains its
4100 own @file{Makefile}, and when @command{make} is run from the top-level
4101 directory, it enters each subdirectory in turn, and invokes there a
4102 new @command{make} instance to build the directory's contents.
4104 Because this approach is very widespread, Automake offers built-in
4105 support for it. However, it is worth nothing that the use of make
4106 recursion has its own serious issues and drawbacks, and that it's
4107 well possible to have packages with a multi directory layout that
4108 make little or no use of such recursion (examples of such packages
4109 are GNU Bison and GNU Automake itself); see also the @ref{Alternative}
4113 * Subdirectories:: Building subdirectories recursively
4114 * Conditional Subdirectories:: Conditionally not building directories
4115 * Alternative:: Subdirectories without recursion
4116 * Subpackages:: Nesting packages
4119 @node Subdirectories
4120 @section Recursing subdirectories
4122 @cindex @code{SUBDIRS}, explained
4124 In packages using make recursion, the top level @file{Makefile.am} must
4125 tell Automake which subdirectories are to be built. This is done via
4126 the @code{SUBDIRS} variable.
4129 The @code{SUBDIRS} variable holds a list of subdirectories in which
4130 building of various sorts can occur. The rules for many targets
4131 (e.g., @code{all}) in the generated @file{Makefile} will run commands
4132 both locally and in all specified subdirectories. Note that the
4133 directories listed in @code{SUBDIRS} are not required to contain
4134 @file{Makefile.am}s; only @file{Makefile}s (after configuration).
4135 This allows inclusion of libraries from packages that do not use
4136 Automake (such as @code{gettext}; see also @ref{Third-Party
4139 In packages that use subdirectories, the top-level @file{Makefile.am} is
4140 often very short. For instance, here is the @file{Makefile.am} from the
4141 GNU Hello distribution:
4144 EXTRA_DIST = BUGS ChangeLog.O README-alpha
4145 SUBDIRS = doc intl po src tests
4148 When Automake invokes @command{make} in a subdirectory, it uses the value
4149 of the @code{MAKE} variable. It passes the value of the variable
4150 @code{AM_MAKEFLAGS} to the @command{make} invocation; this can be set in
4151 @file{Makefile.am} if there are flags you must always pass to
4154 @vindex AM_MAKEFLAGS
4156 The directories mentioned in @code{SUBDIRS} are usually direct
4157 children of the current directory, each subdirectory containing its
4158 own @file{Makefile.am} with a @code{SUBDIRS} pointing to deeper
4159 subdirectories. Automake can be used to construct packages of
4160 arbitrary depth this way.
4162 By default, Automake generates @file{Makefiles} that work depth-first
4163 in postfix order: the subdirectories are built before the current
4164 directory. However, it is possible to change this ordering. You can
4165 do this by putting @samp{.} into @code{SUBDIRS}. For instance,
4166 putting @samp{.} first will cause a prefix ordering of
4172 SUBDIRS = lib src . test
4176 will cause @file{lib/} to be built before @file{src/}, then the
4177 current directory will be built, finally the @file{test/} directory
4178 will be built. It is customary to arrange test directories to be
4179 built after everything else since they are meant to test what has
4182 In addition to the built-in recursive targets defined by Automake
4183 (@code{all}, @code{check}, etc.), the developer can also define his
4184 own recursive targets. That is done by passing the names of such
4185 targets as arguments to the m4 macro @code{AM_EXTRA_RECURSIVE_TARGETS}
4186 in @file{configure.ac}. Automake generates rules to handle the
4187 recursion for such targets; and the developer can define real actions
4188 for them by defining corresponding @code{-local} targets.
4191 % @kbd{cat configure.ac}
4192 AC_INIT([pkg-name], [1.0]
4194 AM_EXTRA_RECURSIVE_TARGETS([foo])
4195 AC_CONFIG_FILES([Makefile sub/Makefile sub/src/Makefile])
4197 % @kbd{cat Makefile.am}
4200 @@echo This will be run by "make foo".
4201 % @kbd{cat sub/Makefile.am}
4203 % @kbd{cat sub/src/Makefile.am}
4205 @@echo This too will be run by a "make foo" issued either in
4206 @@echo the 'sub/src/' directory, the 'sub/' directory, or the
4207 @@echo top-level directory.
4210 @node Conditional Subdirectories
4211 @section Conditional Subdirectories
4212 @cindex Subdirectories, building conditionally
4213 @cindex Conditional subdirectories
4214 @cindex @code{SUBDIRS}, conditional
4215 @cindex Conditional @code{SUBDIRS}
4217 It is possible to define the @code{SUBDIRS} variable conditionally if,
4218 like in the case of GNU Inetutils, you want to only build a subset of
4221 To illustrate how this works, let's assume we have two directories
4222 @file{src/} and @file{opt/}. @file{src/} should always be built, but we
4223 want to decide in @command{configure} whether @file{opt/} will be built
4224 or not. (For this example we will assume that @file{opt/} should be
4225 built when the variable @samp{$want_opt} was set to @samp{yes}.)
4227 Running @command{make} should thus recurse into @file{src/} always, and
4228 then maybe in @file{opt/}.
4230 However @samp{make dist} should always recurse into both @file{src/}
4231 and @file{opt/}. Because @file{opt/} should be distributed even if it
4232 is not needed in the current configuration. This means
4233 @file{opt/Makefile} should be created @emph{unconditionally}.
4235 There are two ways to setup a project like this. You can use Automake
4236 conditionals (@pxref{Conditionals}) or use Autoconf @code{AC_SUBST}
4237 variables (@pxref{Setting Output Variables, , Setting Output
4238 Variables, autoconf, The Autoconf Manual}). Using Automake
4239 conditionals is the preferred solution. Before we illustrate these
4240 two possibilities, let's introduce @code{DIST_SUBDIRS}.
4243 * SUBDIRS vs DIST_SUBDIRS:: Two sets of directories
4244 * Subdirectories with AM_CONDITIONAL:: Specifying conditional subdirectories
4245 * Subdirectories with AC_SUBST:: Another way for conditional recursion
4246 * Unconfigured Subdirectories:: Not even creating a @samp{Makefile}
4249 @node SUBDIRS vs DIST_SUBDIRS
4250 @subsection @code{SUBDIRS} vs.@: @code{DIST_SUBDIRS}
4251 @cindex @code{DIST_SUBDIRS}, explained
4253 Automake considers two sets of directories, defined by the variables
4254 @code{SUBDIRS} and @code{DIST_SUBDIRS}.
4256 @code{SUBDIRS} contains the subdirectories of the current directory
4257 that must be built (@pxref{Subdirectories}). It must be defined
4258 manually; Automake will never guess a directory is to be built. As we
4259 will see in the next two sections, it is possible to define it
4260 conditionally so that some directory will be omitted from the build.
4262 @code{DIST_SUBDIRS} is used in rules that need to recurse in all
4263 directories, even those that have been conditionally left out of the
4264 build. Recall our example where we may not want to build subdirectory
4265 @file{opt/}, but yet we want to distribute it? This is where
4266 @code{DIST_SUBDIRS} comes into play: @samp{opt} may not appear in
4267 @code{SUBDIRS}, but it must appear in @code{DIST_SUBDIRS}.
4269 Precisely, @code{DIST_SUBDIRS} is used by @samp{make
4270 maintainer-clean}, @samp{make distclean} and @samp{make dist}. All
4271 other recursive rules use @code{SUBDIRS}.
4273 If @code{SUBDIRS} is defined conditionally using Automake
4274 conditionals, Automake will define @code{DIST_SUBDIRS} automatically
4275 from the possible values of @code{SUBDIRS} in all conditions.
4277 If @code{SUBDIRS} contains @code{AC_SUBST} variables,
4278 @code{DIST_SUBDIRS} will not be defined correctly because Automake
4279 does not know the possible values of these variables. In this case
4280 @code{DIST_SUBDIRS} needs to be defined manually.
4282 @node Subdirectories with AM_CONDITIONAL
4283 @subsection Subdirectories with @code{AM_CONDITIONAL}
4284 @cindex @code{SUBDIRS} and @code{AM_CONDITIONAL}
4285 @cindex @code{AM_CONDITIONAL} and @code{SUBDIRS}
4287 @c Keep in sync with subdir-am-cond.sh
4289 @file{configure} should output the @file{Makefile} for each directory
4290 and define a condition into which @file{opt/} should be built.
4294 AM_CONDITIONAL([COND_OPT], [test "$want_opt" = yes])
4295 AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
4299 Then @code{SUBDIRS} can be defined in the top-level @file{Makefile.am}
4306 SUBDIRS = src $(MAYBE_OPT)
4309 As you can see, running @command{make} will rightly recurse into
4310 @file{src/} and maybe @file{opt/}.
4312 @vindex DIST_SUBDIRS
4313 As you can't see, running @samp{make dist} will recurse into both
4314 @file{src/} and @file{opt/} directories because @samp{make dist}, unlike
4315 @samp{make all}, doesn't use the @code{SUBDIRS} variable. It uses the
4316 @code{DIST_SUBDIRS} variable.
4318 In this case Automake will define @samp{DIST_SUBDIRS = src opt}
4319 automatically because it knows that @code{MAYBE_OPT} can contain
4320 @samp{opt} in some condition.
4322 @node Subdirectories with AC_SUBST
4323 @subsection Subdirectories with @code{AC_SUBST}
4324 @cindex @code{SUBDIRS} and @code{AC_SUBST}
4325 @cindex @code{AC_SUBST} and @code{SUBDIRS}
4327 @c Keep in sync with subdir-ac-subst.sh
4329 Another possibility is to define @code{MAYBE_OPT} from
4330 @file{./configure} using @code{AC_SUBST}:
4334 if test "$want_opt" = yes; then
4339 AC_SUBST([MAYBE_OPT])
4340 AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
4344 In this case the top-level @file{Makefile.am} should look as follows.
4347 SUBDIRS = src $(MAYBE_OPT)
4348 DIST_SUBDIRS = src opt
4351 The drawback is that since Automake cannot guess what the possible
4352 values of @code{MAYBE_OPT} are, it is necessary to define
4353 @code{DIST_SUBDIRS}.
4355 @node Unconfigured Subdirectories
4356 @subsection Unconfigured Subdirectories
4357 @cindex Subdirectories, configured conditionally
4359 The semantics of @code{DIST_SUBDIRS} are often misunderstood by some
4360 users that try to @emph{configure and build} subdirectories
4361 conditionally. Here by configuring we mean creating the
4362 @file{Makefile} (it might also involve running a nested
4363 @command{configure} script: this is a costly operation that explains
4364 why people want to do it conditionally, but only the @file{Makefile}
4365 is relevant to the discussion).
4367 The above examples all assume that every @file{Makefile} is created,
4368 even in directories that are not going to be built. The simple reason
4369 is that we want @samp{make dist} to distribute even the directories
4370 that are not being built (e.g., platform-dependent code), hence
4371 @file{make dist} must recurse into the subdirectory, hence this
4372 directory must be configured and appear in @code{DIST_SUBDIRS}.
4374 Building packages that do not configure every subdirectory is a tricky
4375 business, and we do not recommend it to the novice as it is easy to
4376 produce an incomplete tarball by mistake. We will not discuss this
4377 topic in depth here, yet for the adventurous here are a few rules to
4382 @item @code{SUBDIRS} should always be a subset of @code{DIST_SUBDIRS}.
4384 It makes little sense to have a directory in @code{SUBDIRS} that
4385 is not in @code{DIST_SUBDIRS}. Think of the former as a way to tell
4386 which directories listed in the latter should be built.
4387 @item Any directory listed in @code{DIST_SUBDIRS} and @code{SUBDIRS}
4390 I.e., the @file{Makefile} must exists or the recursive @command{make}
4391 rules will not be able to process the directory.
4392 @item Any configured directory must be listed in @code{DIST_SUBDIRS}.
4394 So that the cleaning rules remove the generated @file{Makefile}s.
4395 It would be correct to see @code{DIST_SUBDIRS} as a variable that
4396 lists all the directories that have been configured.
4400 In order to prevent recursion in some unconfigured directory you
4401 must therefore ensure that this directory does not appear in
4402 @code{DIST_SUBDIRS} (and @code{SUBDIRS}). For instance, if you define
4403 @code{SUBDIRS} conditionally using @code{AC_SUBST} and do not define
4404 @code{DIST_SUBDIRS} explicitly, it will be default to
4405 @samp{$(SUBDIRS)}; another possibility is to force @code{DIST_SUBDIRS
4408 Of course, directories that are omitted from @code{DIST_SUBDIRS} will
4409 not be distributed unless you make other arrangements for this to
4410 happen (for instance, always running @samp{make dist} in a
4411 configuration where all directories are known to appear in
4412 @code{DIST_SUBDIRS}; or writing a @code{dist-hook} target to
4413 distribute these directories).
4415 @cindex Subdirectories, not distributed
4416 In few packages, unconfigured directories are not even expected to
4417 be distributed. Although these packages do not require the
4418 aforementioned extra arrangements, there is another pitfall. If the
4419 name of a directory appears in @code{SUBDIRS} or @code{DIST_SUBDIRS},
4420 @command{automake} will make sure the directory exists. Consequently
4421 @command{automake} cannot be run on such a distribution when one
4422 directory has been omitted. One way to avoid this check is to use the
4423 @code{AC_SUBST} method to declare conditional directories; since
4424 @command{automake} does not know the values of @code{AC_SUBST}
4425 variables it cannot ensure the corresponding directory exists.
4428 @section An Alternative Approach to Subdirectories
4430 If you've ever read Peter Miller's excellent paper,
4431 @uref{http://miller.emu.id.au/pmiller/books/rmch/,
4432 Recursive Make Considered Harmful}, the preceding sections on the use of
4433 make recursion will probably come as unwelcome advice. For those who
4434 haven't read the paper, Miller's main thesis is that recursive
4435 @command{make} invocations are both slow and error-prone.
4437 Automake provides sufficient cross-directory support @footnote{We
4438 believe. This work is new and there are probably warts.
4439 @xref{Introduction}, for information on reporting bugs.} to enable you
4440 to write a single @file{Makefile.am} for a complex multi-directory
4443 By default an installable file specified in a subdirectory will have its
4444 directory name stripped before installation. For instance, in this
4445 example, the header file will be installed as
4446 @file{$(includedir)/stdio.h}:
4449 include_HEADERS = inc/stdio.h
4453 @cindex @code{nobase_} prefix
4454 @cindex Path stripping, avoiding
4455 @cindex Avoiding path stripping
4457 However, the @samp{nobase_} prefix can be used to circumvent this path
4458 stripping. In this example, the header file will be installed as
4459 @file{$(includedir)/sys/types.h}:
4462 nobase_include_HEADERS = sys/types.h
4465 @cindex @code{nobase_} and @code{dist_} or @code{nodist_}
4466 @cindex @code{dist_} and @code{nobase_}
4467 @cindex @code{nodist_} and @code{nobase_}
4471 @samp{nobase_} should be specified first when used in conjunction with
4472 either @samp{dist_} or @samp{nodist_} (@pxref{Fine-grained Distribution
4473 Control}). For instance:
4476 nobase_dist_pkgdata_DATA = images/vortex.pgm sounds/whirl.ogg
4479 Finally, note that a variable using the @samp{nobase_} prefix can
4480 often be replaced by several variables, one for each destination
4481 directory (@pxref{Uniform}). For instance, the last example could be
4482 rewritten as follows:
4484 @c Keep in sync with primary-prefix-couples-documented-valid.sh
4486 imagesdir = $(pkgdatadir)/images
4487 soundsdir = $(pkgdatadir)/sounds
4488 dist_images_DATA = images/vortex.pgm
4489 dist_sounds_DATA = sounds/whirl.ogg
4493 This latter syntax makes it possible to change one destination
4494 directory without changing the layout of the source tree.
4496 Currently, @samp{nobase_*_LTLIBRARIES} are the only exception to this
4497 rule, in that there is no particular installation order guarantee for
4498 an otherwise equivalent set of variables without @samp{nobase_} prefix.
4501 @section Nesting Packages
4502 @cindex Nesting packages
4504 @acindex AC_CONFIG_SUBDIRS
4505 @acindex AC_CONFIG_AUX_DIR
4508 In the GNU Build System, packages can be nested to arbitrary depth.
4509 This means that a package can embed other packages with their own
4510 @file{configure}, @file{Makefile}s, etc.
4512 These other packages should just appear as subdirectories of their
4513 parent package. They must be listed in @code{SUBDIRS} like other
4514 ordinary directories. However the subpackage's @file{Makefile}s
4515 should be output by its own @file{configure} script, not by the
4516 parent's @file{configure}. This is achieved using the
4517 @code{AC_CONFIG_SUBDIRS} Autoconf macro (@pxref{Subdirectories,
4518 AC_CONFIG_SUBDIRS, Configuring Other Packages in Subdirectories,
4519 autoconf, The Autoconf Manual}).
4521 Here is an example package for an @code{arm} program that links with
4522 a @code{hand} library that is a nested package in subdirectory
4525 @code{arm}'s @file{configure.ac}:
4528 AC_INIT([arm], [1.0])
4529 AC_CONFIG_AUX_DIR([.])
4532 AC_CONFIG_FILES([Makefile])
4533 # Call hand's ./configure script recursively.
4534 AC_CONFIG_SUBDIRS([hand])
4538 @code{arm}'s @file{Makefile.am}:
4541 # Build the library in the hand subdirectory first.
4544 # Include hand's header when compiling this directory.
4545 AM_CPPFLAGS = -I$(srcdir)/hand
4549 # link with the hand library.
4550 arm_LDADD = hand/libhand.a
4553 Now here is @code{hand}'s @file{hand/configure.ac}:
4556 AC_INIT([hand], [1.2])
4557 AC_CONFIG_AUX_DIR([.])
4562 AC_CONFIG_FILES([Makefile])
4567 and its @file{hand/Makefile.am}:
4570 lib_LIBRARIES = libhand.a
4571 libhand_a_SOURCES = hand.c
4574 When @samp{make dist} is run from the top-level directory it will
4575 create an archive @file{arm-1.0.tar.gz} that contains the @code{arm}
4576 code as well as the @file{hand} subdirectory. This package can be
4577 built and installed like any ordinary package, with the usual
4578 @samp{./configure && make && make install} sequence (the @code{hand}
4579 subpackage will be built and installed by the process).
4581 When @samp{make dist} is run from the hand directory, it will create a
4582 self-contained @file{hand-1.2.tar.gz} archive. So although it appears
4583 to be embedded in another package, it can still be used separately.
4585 The purpose of the @samp{AC_CONFIG_AUX_DIR([.])} instruction is to
4586 force Automake and Autoconf to search for auxiliary scripts in the
4587 current directory. For instance, this means that there will be two
4588 copies of @file{install-sh}: one in the top-level of the @code{arm}
4589 package, and another one in the @file{hand/} subdirectory for the
4590 @code{hand} package.
4592 The historical default is to search for these auxiliary scripts in
4593 the parent directory and the grandparent directory. So if the
4594 @samp{AC_CONFIG_AUX_DIR([.])} line was removed from
4595 @file{hand/configure.ac}, that subpackage would share the auxiliary
4596 script of the @code{arm} package. This may looks like a gain in size
4597 (a few kilobytes), but it is actually a loss of modularity as the
4598 @code{hand} subpackage is no longer self-contained (@samp{make dist}
4599 in the subdirectory will not work anymore).
4601 Packages that do not use Automake need more work to be integrated this
4602 way. @xref{Third-Party Makefiles}.
4605 @chapter Building Programs and Libraries
4607 A large part of Automake's functionality is dedicated to making it easy
4608 to build programs and libraries.
4611 * A Program:: Building a program
4612 * A Library:: Building a library
4613 * A Shared Library:: Building a Libtool library
4614 * Program and Library Variables:: Variables controlling program and
4616 * Default _SOURCES:: Default source files
4617 * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
4618 * Program Variables:: Variables used when building a program
4619 * Yacc and Lex:: Yacc and Lex support
4620 * C++ Support:: Compiling C++ sources
4621 * Objective C Support:: Compiling Objective C sources
4622 * Objective C++ Support:: Compiling Objective C++ sources
4623 * Unified Parallel C Support:: Compiling Unified Parallel C sources
4624 * Assembly Support:: Compiling assembly sources
4625 * Fortran 77 Support:: Compiling Fortran 77 sources
4626 * Fortran 9x Support:: Compiling Fortran 9x sources
4627 * Java Support with gcj:: Compiling Java sources using gcj
4628 * Vala Support:: Compiling Vala sources
4629 * Support for Other Languages:: Compiling other languages
4630 * Dependencies:: Automatic dependency tracking
4631 * EXEEXT:: Support for executable extensions
4636 @section Building a program
4638 In order to build a program, you need to tell Automake which sources
4639 are part of it, and which libraries it should be linked with.
4641 This section also covers conditional compilation of sources or
4642 programs. Most of the comments about these also apply to libraries
4643 (@pxref{A Library}) and libtool libraries (@pxref{A Shared Library}).
4646 * Program Sources:: Defining program sources
4647 * Linking:: Linking with libraries or extra objects
4648 * Conditional Sources:: Handling conditional sources
4649 * Conditional Programs:: Building a program conditionally
4652 @node Program Sources
4653 @subsection Defining program sources
4655 @cindex @code{PROGRAMS}, @code{bindir}
4657 @vindex bin_PROGRAMS
4658 @vindex sbin_PROGRAMS
4659 @vindex libexec_PROGRAMS
4660 @vindex pkglibexec_PROGRAMS
4661 @vindex noinst_PROGRAMS
4662 @vindex check_PROGRAMS
4664 In a directory containing source that gets built into a program (as
4665 opposed to a library or a script), the @code{PROGRAMS} primary is used.
4666 Programs can be installed in @code{bindir}, @code{sbindir},
4667 @code{libexecdir}, @code{pkglibexecdir}, or not at all
4668 (@code{noinst_}). They can also be built only for @samp{make check}, in
4669 which case the prefix is @samp{check_}.
4674 bin_PROGRAMS = hello
4677 In this simple case, the resulting @file{Makefile.in} will contain code
4678 to generate a program named @code{hello}.
4680 Associated with each program are several assisting variables that are
4681 named after the program. These variables are all optional, and have
4682 reasonable defaults. Each variable, its use, and default is spelled out
4683 below; we use the ``hello'' example throughout.
4685 The variable @code{hello_SOURCES} is used to specify which source files
4686 get built into an executable:
4689 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
4692 This causes each mentioned @file{.c} file to be compiled into the
4693 corresponding @file{.o}. Then all are linked to produce @file{hello}.
4695 @cindex @code{_SOURCES} primary, defined
4696 @cindex @code{SOURCES} primary, defined
4697 @cindex Primary variable, @code{SOURCES}
4700 If @code{hello_SOURCES} is not specified, then it defaults to the single
4701 file @file{hello.c} (@pxref{Default _SOURCES}).
4705 Multiple programs can be built in a single directory. Multiple programs
4706 can share a single source file, which must be listed in each
4707 @code{_SOURCES} definition.
4709 @cindex Header files in @code{_SOURCES}
4710 @cindex @code{_SOURCES} and header files
4712 Header files listed in a @code{_SOURCES} definition will be included in
4713 the distribution but otherwise ignored. In case it isn't obvious, you
4714 should not include the header file generated by @file{configure} in a
4715 @code{_SOURCES} variable; this file should not be distributed. Lex
4716 (@file{.l}) and Yacc (@file{.y}) files can also be listed; see @ref{Yacc
4721 @subsection Linking the program
4723 If you need to link against libraries that are not found by
4724 @command{configure}, you can use @code{LDADD} to do so. This variable is
4725 used to specify additional objects or libraries to link with; it is
4726 inappropriate for specifying specific linker flags, you should use
4727 @code{AM_LDFLAGS} for this purpose.
4731 @cindex @code{prog_LDADD}, defined
4733 Sometimes, multiple programs are built in one directory but do not share
4734 the same link-time requirements. In this case, you can use the
4735 @code{@var{prog}_LDADD} variable (where @var{prog} is the name of the
4736 program as it appears in some @code{_PROGRAMS} variable, and usually
4737 written in lowercase) to override @code{LDADD}. If this variable exists
4738 for a given program, then that program is not linked using @code{LDADD}.
4741 For instance, in GNU cpio, @code{pax}, @code{cpio} and @code{mt} are
4742 linked against the library @file{libcpio.a}. However, @code{rmt} is
4743 built in the same directory, and has no such link requirement. Also,
4744 @code{mt} and @code{rmt} are only built on certain architectures. Here
4745 is what cpio's @file{src/Makefile.am} looks like (abridged):
4748 bin_PROGRAMS = cpio pax $(MT)
4749 libexec_PROGRAMS = $(RMT)
4750 EXTRA_PROGRAMS = mt rmt
4752 LDADD = ../lib/libcpio.a $(INTLLIBS)
4755 cpio_SOURCES = @dots{}
4756 pax_SOURCES = @dots{}
4757 mt_SOURCES = @dots{}
4758 rmt_SOURCES = @dots{}
4761 @cindex @code{_LDFLAGS}, defined
4762 @vindex maude_LDFLAGS
4763 @code{@var{prog}_LDADD} is inappropriate for passing program-specific
4764 linker flags (except for @option{-l}, @option{-L}, @option{-dlopen} and
4765 @option{-dlpreopen}). So, use the @code{@var{prog}_LDFLAGS} variable for
4768 @cindex @code{_DEPENDENCIES}, defined
4769 @vindex maude_DEPENDENCIES
4770 @vindex EXTRA_maude_DEPENDENCIES
4771 It is also occasionally useful to have a program depend on some other
4772 target that is not actually part of that program. This can be done
4773 using either the @code{@var{prog}_DEPENDENCIES} or the
4774 @code{EXTRA_@var{prog}_DEPENDENCIES} variable. Each program depends on
4775 the contents both variables, but no further interpretation is done.
4777 Since these dependencies are associated to the link rule used to
4778 create the programs they should normally list files used by the link
4779 command. That is @file{*.$(OBJEXT)}, @file{*.a}, or @file{*.la}
4780 files. In rare cases you may need to add other kinds of files such as
4781 linker scripts, but @emph{listing a source file in
4782 @code{_DEPENDENCIES} is wrong}. If some source file needs to be built
4783 before all the components of a program are built, consider using the
4784 @code{BUILT_SOURCES} variable instead (@pxref{Sources}).
4786 If @code{@var{prog}_DEPENDENCIES} is not supplied, it is computed by
4787 Automake. The automatically-assigned value is the contents of
4788 @code{@var{prog}_LDADD}, with most configure substitutions, @option{-l},
4789 @option{-L}, @option{-dlopen} and @option{-dlpreopen} options removed. The
4790 configure substitutions that are left in are only @samp{$(LIBOBJS)} and
4791 @samp{$(ALLOCA)}; these are left because it is known that they will not
4792 cause an invalid value for @code{@var{prog}_DEPENDENCIES} to be
4795 @ref{Conditional Sources} shows a situation where @code{_DEPENDENCIES}
4798 The @code{EXTRA_@var{prog}_DEPENDENCIES} may be useful for cases where
4799 you merely want to augment the @command{automake}-generated
4800 @code{@var{prog}_DEPENDENCIES} rather than replacing it.
4802 @cindex @code{LDADD} and @option{-l}
4803 @cindex @option{-l} and @code{LDADD}
4804 We recommend that you avoid using @option{-l} options in @code{LDADD}
4805 or @code{@var{prog}_LDADD} when referring to libraries built by your
4806 package. Instead, write the file name of the library explicitly as in
4807 the above @code{cpio} example. Use @option{-l} only to list
4808 third-party libraries. If you follow this rule, the default value of
4809 @code{@var{prog}_DEPENDENCIES} will list all your local libraries and
4810 omit the other ones.
4813 @node Conditional Sources
4814 @subsection Conditional compilation of sources
4816 You can't put a configure substitution (e.g., @samp{@@FOO@@} or
4817 @samp{$(FOO)} where @code{FOO} is defined via @code{AC_SUBST}) into a
4818 @code{_SOURCES} variable. The reason for this is a bit hard to
4819 explain, but suffice to say that it simply won't work. Automake will
4820 give an error if you try to do this.
4822 Fortunately there are two other ways to achieve the same result. One is
4823 to use configure substitutions in @code{_LDADD} variables, the other is
4824 to use an Automake conditional.
4826 @subsubheading Conditional Compilation using @code{_LDADD} Substitutions
4828 @cindex @code{EXTRA_prog_SOURCES}, defined
4830 Automake must know all the source files that could possibly go into a
4831 program, even if not all the files are built in every circumstance. Any
4832 files that are only conditionally built should be listed in the
4833 appropriate @code{EXTRA_} variable. For instance, if
4834 @file{hello-linux.c} or @file{hello-generic.c} were conditionally included
4835 in @code{hello}, the @file{Makefile.am} would contain:
4838 bin_PROGRAMS = hello
4839 hello_SOURCES = hello-common.c
4840 EXTRA_hello_SOURCES = hello-linux.c hello-generic.c
4841 hello_LDADD = $(HELLO_SYSTEM)
4842 hello_DEPENDENCIES = $(HELLO_SYSTEM)
4846 You can then setup the @samp{$(HELLO_SYSTEM)} substitution from
4847 @file{configure.ac}:
4852 *linux*) HELLO_SYSTEM='hello-linux.$(OBJEXT)' ;;
4853 *) HELLO_SYSTEM='hello-generic.$(OBJEXT)' ;;
4855 AC_SUBST([HELLO_SYSTEM])
4859 In this case, the variable @code{HELLO_SYSTEM} should be replaced by
4860 either @file{hello-linux.o} or @file{hello-generic.o}, and added to
4861 both @code{hello_DEPENDENCIES} and @code{hello_LDADD} in order to be
4862 built and linked in.
4864 @subsubheading Conditional Compilation using Automake Conditionals
4866 An often simpler way to compile source files conditionally is to use
4867 Automake conditionals. For instance, you could use this
4868 @file{Makefile.am} construct to build the same @file{hello} example:
4871 bin_PROGRAMS = hello
4873 hello_SOURCES = hello-linux.c hello-common.c
4875 hello_SOURCES = hello-generic.c hello-common.c
4879 In this case, @file{configure.ac} should setup the @code{LINUX}
4880 conditional using @code{AM_CONDITIONAL} (@pxref{Conditionals}).
4882 When using conditionals like this you don't need to use the
4883 @code{EXTRA_} variable, because Automake will examine the contents of
4884 each variable to construct the complete list of source files.
4886 If your program uses a lot of files, you will probably prefer a
4887 conditional @samp{+=}.
4890 bin_PROGRAMS = hello
4891 hello_SOURCES = hello-common.c
4893 hello_SOURCES += hello-linux.c
4895 hello_SOURCES += hello-generic.c
4899 @node Conditional Programs
4900 @subsection Conditional compilation of programs
4901 @cindex Conditional programs
4902 @cindex Programs, conditional
4904 Sometimes it is useful to determine the programs that are to be built
4905 at configure time. For instance, GNU @code{cpio} only builds
4906 @code{mt} and @code{rmt} under special circumstances. The means to
4907 achieve conditional compilation of programs are the same you can use
4908 to compile source files conditionally: substitutions or conditionals.
4910 @subsubheading Conditional Programs using @command{configure} Substitutions
4912 @vindex EXTRA_PROGRAMS
4913 @cindex @code{EXTRA_PROGRAMS}, defined
4914 In this case, you must notify Automake of all the programs that can
4915 possibly be built, but at the same time cause the generated
4916 @file{Makefile.in} to use the programs specified by @command{configure}.
4917 This is done by having @command{configure} substitute values into each
4918 @code{_PROGRAMS} definition, while listing all optionally built programs
4919 in @code{EXTRA_PROGRAMS}.
4922 bin_PROGRAMS = cpio pax $(MT)
4923 libexec_PROGRAMS = $(RMT)
4924 EXTRA_PROGRAMS = mt rmt
4927 As explained in @ref{EXEEXT}, Automake will rewrite
4928 @code{bin_PROGRAMS}, @code{libexec_PROGRAMS}, and
4929 @code{EXTRA_PROGRAMS}, appending @samp{$(EXEEXT)} to each binary.
4930 Obviously it cannot rewrite values obtained at run-time through
4931 @command{configure} substitutions, therefore you should take care of
4932 appending @samp{$(EXEEXT)} yourself, as in @samp{AC_SUBST([MT],
4933 ['mt$@{EXEEXT@}'])}.
4935 @subsubheading Conditional Programs using Automake Conditionals
4937 You can also use Automake conditionals (@pxref{Conditionals}) to
4938 select programs to be built. In this case you don't have to worry
4939 about @samp{$(EXEEXT)} or @code{EXTRA_PROGRAMS}.
4941 @c Keep in sync with exeext.sh
4943 bin_PROGRAMS = cpio pax
4948 libexec_PROGRAMS = rmt
4954 @section Building a library
4956 @cindex @code{_LIBRARIES} primary, defined
4957 @cindex @code{LIBRARIES} primary, defined
4958 @cindex Primary variable, @code{LIBRARIES}
4961 @vindex lib_LIBRARIES
4962 @vindex pkglib_LIBRARIES
4963 @vindex noinst_LIBRARIES
4965 Building a library is much like building a program. In this case, the
4966 name of the primary is @code{LIBRARIES}. Libraries can be installed in
4967 @code{libdir} or @code{pkglibdir}.
4969 @xref{A Shared Library}, for information on how to build shared
4970 libraries using libtool and the @code{LTLIBRARIES} primary.
4972 Each @code{_LIBRARIES} variable is a list of the libraries to be built.
4973 For instance, to create a library named @file{libcpio.a}, but not install
4974 it, you would write:
4977 noinst_LIBRARIES = libcpio.a
4978 libcpio_a_SOURCES = @dots{}
4981 The sources that go into a library are determined exactly as they are
4982 for programs, via the @code{_SOURCES} variables. Note that the library
4983 name is canonicalized (@pxref{Canonicalization}), so the @code{_SOURCES}
4984 variable corresponding to @file{libcpio.a} is @samp{libcpio_a_SOURCES},
4985 not @samp{libcpio.a_SOURCES}.
4987 @vindex maude_LIBADD
4988 Extra objects can be added to a library using the
4989 @code{@var{library}_LIBADD} variable. This should be used for objects
4990 determined by @command{configure}. Again from @code{cpio}:
4992 @c Keep in sync with pr401c.sh
4994 libcpio_a_LIBADD = $(LIBOBJS) $(ALLOCA)
4997 In addition, sources for extra objects that will not exist until
4998 configure-time must be added to the @code{BUILT_SOURCES} variable
5001 Building a static library is done by compiling all object files, then
5002 by invoking @samp{$(AR) $(ARFLAGS)} followed by the name of the
5003 library and the list of objects, and finally by calling
5004 @samp{$(RANLIB)} on that library. You should call
5005 @code{AC_PROG_RANLIB} from your @file{configure.ac} to define
5006 @code{RANLIB} (Automake will complain otherwise). You should also
5007 call @code{AM_PROG_AR} to define @code{AR}, in order to support unusual
5008 archivers such as Microsoft lib. @code{ARFLAGS} will default to
5009 @code{cru}; you can override this variable by setting it in your
5010 @file{Makefile.am} or by @code{AC_SUBST}ing it from your
5011 @file{configure.ac}. You can override the @code{AR} variable by
5012 defining a per-library @code{maude_AR} variable (@pxref{Program and
5013 Library Variables}).
5015 @cindex Empty libraries
5016 Be careful when selecting library components conditionally. Because
5017 building an empty library is not portable, you should ensure that any
5018 library always contains at least one object.
5020 To use a static library when building a program, add it to
5021 @code{LDADD} for this program. In the following example, the program
5022 @file{cpio} is statically linked with the library @file{libcpio.a}.
5025 noinst_LIBRARIES = libcpio.a
5026 libcpio_a_SOURCES = @dots{}
5029 cpio_SOURCES = cpio.c @dots{}
5030 cpio_LDADD = libcpio.a
5034 @node A Shared Library
5035 @section Building a Shared Library
5037 @cindex Shared libraries, support for
5039 Building shared libraries portably is a relatively complex matter.
5040 For this reason, GNU Libtool (@pxref{Top, , Introduction, libtool, The
5041 Libtool Manual}) was created to help build shared libraries in a
5042 platform-independent way.
5045 * Libtool Concept:: Introducing Libtool
5046 * Libtool Libraries:: Declaring Libtool Libraries
5047 * Conditional Libtool Libraries:: Building Libtool Libraries Conditionally
5048 * Conditional Libtool Sources:: Choosing Library Sources Conditionally
5049 * Libtool Convenience Libraries:: Building Convenience Libtool Libraries
5050 * Libtool Modules:: Building Libtool Modules
5051 * Libtool Flags:: Using _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS
5052 * LTLIBOBJS:: Using $(LTLIBOBJS) and $(LTALLOCA)
5053 * Libtool Issues:: Common Issues Related to Libtool's Use
5056 @node Libtool Concept
5057 @subsection The Libtool Concept
5059 @cindex @command{libtool}, introduction
5060 @cindex libtool library, definition
5061 @cindex suffix @file{.la}, defined
5062 @cindex @file{.la} suffix, defined
5064 Libtool abstracts shared and static libraries into a unified concept
5065 henceforth called @dfn{libtool libraries}. Libtool libraries are
5066 files using the @file{.la} suffix, and can designate a static library,
5067 a shared library, or maybe both. Their exact nature cannot be
5068 determined until @file{./configure} is run: not all platforms support
5069 all kinds of libraries, and users can explicitly select which
5070 libraries should be built. (However the package's maintainers can
5071 tune the default, @pxref{AC_PROG_LIBTOOL, , The @code{AC_PROG_LIBTOOL}
5072 macro, libtool, The Libtool Manual}.)
5074 @cindex suffix @file{.lo}, defined
5075 Because object files for shared and static libraries must be compiled
5076 differently, libtool is also used during compilation. Object files
5077 built by libtool are called @dfn{libtool objects}: these are files
5078 using the @file{.lo} suffix. Libtool libraries are built from these
5081 You should not assume anything about the structure of @file{.la} or
5082 @file{.lo} files and how libtool constructs them: this is libtool's
5083 concern, and the last thing one wants is to learn about libtool's
5084 guts. However the existence of these files matters, because they are
5085 used as targets and dependencies in @file{Makefile}s rules when
5086 building libtool libraries. There are situations where you may have
5087 to refer to these, for instance when expressing dependencies for
5088 building source files conditionally (@pxref{Conditional Libtool
5091 @cindex @file{libltdl}, introduction
5093 People considering writing a plug-in system, with dynamically loaded
5094 modules, should look into @file{libltdl}: libtool's dlopening library
5095 (@pxref{Using libltdl, , Using libltdl, libtool, The Libtool Manual}).
5096 This offers a portable dlopening facility to load libtool libraries
5097 dynamically, and can also achieve static linking where unavoidable.
5099 Before we discuss how to use libtool with Automake in details, it
5100 should be noted that the libtool manual also has a section about how
5101 to use Automake with libtool (@pxref{Using Automake, , Using Automake
5102 with Libtool, libtool, The Libtool Manual}).
5104 @node Libtool Libraries
5105 @subsection Building Libtool Libraries
5107 @cindex @code{_LTLIBRARIES} primary, defined
5108 @cindex @code{LTLIBRARIES} primary, defined
5109 @cindex Primary variable, @code{LTLIBRARIES}
5110 @cindex Example of shared libraries
5111 @vindex lib_LTLIBRARIES
5112 @vindex pkglib_LTLIBRARIES
5113 @vindex _LTLIBRARIES
5115 Automake uses libtool to build libraries declared with the
5116 @code{LTLIBRARIES} primary. Each @code{_LTLIBRARIES} variable is a
5117 list of libtool libraries to build. For instance, to create a libtool
5118 library named @file{libgettext.la}, and install it in @code{libdir},
5122 lib_LTLIBRARIES = libgettext.la
5123 libgettext_la_SOURCES = gettext.c gettext.h @dots{}
5126 Automake predefines the variable @code{pkglibdir}, so you can use
5127 @code{pkglib_LTLIBRARIES} to install libraries in
5128 @samp{$(libdir)/@@PACKAGE@@/}.
5130 If @file{gettext.h} is a public header file that needs to be installed
5131 in order for people to use the library, it should be declared using a
5132 @code{_HEADERS} variable, not in @code{libgettext_la_SOURCES}.
5133 Headers listed in the latter should be internal headers that are not
5134 part of the public interface.
5137 lib_LTLIBRARIES = libgettext.la
5138 libgettext_la_SOURCES = gettext.c @dots{}
5139 include_HEADERS = gettext.h @dots{}
5142 A package can build and install such a library along with other
5143 programs that use it. This dependency should be specified using
5144 @code{LDADD}. The following example builds a program named
5145 @file{hello} that is linked with @file{libgettext.la}.
5148 lib_LTLIBRARIES = libgettext.la
5149 libgettext_la_SOURCES = gettext.c @dots{}
5151 bin_PROGRAMS = hello
5152 hello_SOURCES = hello.c @dots{}
5153 hello_LDADD = libgettext.la
5157 Whether @file{hello} is statically or dynamically linked with
5158 @file{libgettext.la} is not yet known: this will depend on the
5159 configuration of libtool and the capabilities of the host.
5162 @node Conditional Libtool Libraries
5163 @subsection Building Libtool Libraries Conditionally
5164 @cindex libtool libraries, conditional
5165 @cindex conditional libtool libraries
5167 Like conditional programs (@pxref{Conditional Programs}), there are
5168 two main ways to build conditional libraries: using Automake
5169 conditionals or using Autoconf @code{AC_SUBST}itutions.
5171 The important implementation detail you have to be aware of is that
5172 the place where a library will be installed matters to libtool: it
5173 needs to be indicated @emph{at link-time} using the @option{-rpath}
5176 For libraries whose destination directory is known when Automake runs,
5177 Automake will automatically supply the appropriate @option{-rpath}
5178 option to libtool. This is the case for libraries listed explicitly in
5179 some installable @code{_LTLIBRARIES} variables such as
5180 @code{lib_LTLIBRARIES}.
5182 However, for libraries determined at configure time (and thus
5183 mentioned in @code{EXTRA_LTLIBRARIES}), Automake does not know the
5184 final installation directory. For such libraries you must add the
5185 @option{-rpath} option to the appropriate @code{_LDFLAGS} variable by
5188 The examples below illustrate the differences between these two methods.
5190 Here is an example where @code{WANTEDLIBS} is an @code{AC_SUBST}ed
5191 variable set at @file{./configure}-time to either @file{libfoo.la},
5192 @file{libbar.la}, both, or none. Although @samp{$(WANTEDLIBS)}
5193 appears in the @code{lib_LTLIBRARIES}, Automake cannot guess it
5194 relates to @file{libfoo.la} or @file{libbar.la} at the time it creates
5195 the link rule for these two libraries. Therefore the @option{-rpath}
5196 argument must be explicitly supplied.
5198 @c Keep in sync with ltcond.sh
5200 EXTRA_LTLIBRARIES = libfoo.la libbar.la
5201 lib_LTLIBRARIES = $(WANTEDLIBS)
5202 libfoo_la_SOURCES = foo.c @dots{}
5203 libfoo_la_LDFLAGS = -rpath '$(libdir)'
5204 libbar_la_SOURCES = bar.c @dots{}
5205 libbar_la_LDFLAGS = -rpath '$(libdir)'
5208 Here is how the same @file{Makefile.am} would look using Automake
5209 conditionals named @code{WANT_LIBFOO} and @code{WANT_LIBBAR}. Now
5210 Automake is able to compute the @option{-rpath} setting itself, because
5211 it's clear that both libraries will end up in @samp{$(libdir)} if they
5214 @c Keep in sync with ltcond.sh
5218 lib_LTLIBRARIES += libfoo.la
5221 lib_LTLIBRARIES += libbar.la
5223 libfoo_la_SOURCES = foo.c @dots{}
5224 libbar_la_SOURCES = bar.c @dots{}
5227 @node Conditional Libtool Sources
5228 @subsection Libtool Libraries with Conditional Sources
5230 Conditional compilation of sources in a library can be achieved in the
5231 same way as conditional compilation of sources in a program
5232 (@pxref{Conditional Sources}). The only difference is that
5233 @code{_LIBADD} should be used instead of @code{_LDADD} and that it
5234 should mention libtool objects (@file{.lo} files).
5236 So, to mimic the @file{hello} example from @ref{Conditional Sources},
5237 we could build a @file{libhello.la} library using either
5238 @file{hello-linux.c} or @file{hello-generic.c} with the following
5241 @c Keep in sync with ltcond2.sh
5243 lib_LTLIBRARIES = libhello.la
5244 libhello_la_SOURCES = hello-common.c
5245 EXTRA_libhello_la_SOURCES = hello-linux.c hello-generic.c
5246 libhello_la_LIBADD = $(HELLO_SYSTEM)
5247 libhello_la_DEPENDENCIES = $(HELLO_SYSTEM)
5251 And make sure @command{configure} defines @code{HELLO_SYSTEM} as
5252 either @file{hello-linux.lo} or @file{hello-@-generic.lo}.
5254 Or we could simply use an Automake conditional as follows.
5256 @c Keep in sync with ltcond2.sh
5258 lib_LTLIBRARIES = libhello.la
5259 libhello_la_SOURCES = hello-common.c
5261 libhello_la_SOURCES += hello-linux.c
5263 libhello_la_SOURCES += hello-generic.c
5267 @node Libtool Convenience Libraries
5268 @subsection Libtool Convenience Libraries
5269 @cindex convenience libraries, libtool
5270 @cindex libtool convenience libraries
5271 @vindex noinst_LTLIBRARIES
5272 @vindex check_LTLIBRARIES
5274 Sometimes you want to build libtool libraries that should not be
5275 installed. These are called @dfn{libtool convenience libraries} and
5276 are typically used to encapsulate many sublibraries, later gathered
5277 into one big installed library.
5279 Libtool convenience libraries are declared by directory-less variables
5280 such as @code{noinst_LTLIBRARIES}, @code{check_LTLIBRARIES}, or even
5281 @code{EXTRA_LTLIBRARIES}. Unlike installed libtool libraries they do
5282 not need an @option{-rpath} flag at link time (actually this is the only
5285 Convenience libraries listed in @code{noinst_LTLIBRARIES} are always
5286 built. Those listed in @code{check_LTLIBRARIES} are built only upon
5287 @samp{make check}. Finally, libraries listed in
5288 @code{EXTRA_LTLIBRARIES} are never built explicitly: Automake outputs
5289 rules to build them, but if the library does not appear as a Makefile
5290 dependency anywhere it won't be built (this is why
5291 @code{EXTRA_LTLIBRARIES} is used for conditional compilation).
5293 Here is a sample setup merging libtool convenience libraries from
5294 subdirectories into one main @file{libtop.la} library.
5296 @c Keep in sync with ltconv.sh
5298 # -- Top-level Makefile.am --
5299 SUBDIRS = sub1 sub2 @dots{}
5300 lib_LTLIBRARIES = libtop.la
5302 libtop_la_LIBADD = \
5307 # -- sub1/Makefile.am --
5308 noinst_LTLIBRARIES = libsub1.la
5309 libsub1_la_SOURCES = @dots{}
5311 # -- sub2/Makefile.am --
5312 # showing nested convenience libraries
5313 SUBDIRS = sub2.1 sub2.2 @dots{}
5314 noinst_LTLIBRARIES = libsub2.la
5315 libsub2_la_SOURCES =
5316 libsub2_la_LIBADD = \
5322 When using such setup, beware that @command{automake} will assume
5323 @file{libtop.la} is to be linked with the C linker. This is because
5324 @code{libtop_la_SOURCES} is empty, so @command{automake} picks C as
5325 default language. If @code{libtop_la_SOURCES} was not empty,
5326 @command{automake} would select the linker as explained in @ref{How
5327 the Linker is Chosen}.
5329 If one of the sublibraries contains non-C source, it is important that
5330 the appropriate linker be chosen. One way to achieve this is to
5331 pretend that there is such a non-C file among the sources of the
5332 library, thus forcing @command{automake} to select the appropriate
5333 linker. Here is the top-level @file{Makefile} of our example updated
5334 to force C++ linking.
5337 SUBDIRS = sub1 sub2 @dots{}
5338 lib_LTLIBRARIES = libtop.la
5340 # Dummy C++ source to cause C++ linking.
5341 nodist_EXTRA_libtop_la_SOURCES = dummy.cxx
5342 libtop_la_LIBADD = \
5348 @samp{EXTRA_*_SOURCES} variables are used to keep track of source
5349 files that might be compiled (this is mostly useful when doing
5350 conditional compilation using @code{AC_SUBST}, @pxref{Conditional
5351 Libtool Sources}), and the @code{nodist_} prefix means the listed
5352 sources are not to be distributed (@pxref{Program and Library
5353 Variables}). In effect the file @file{dummy.cxx} does not need to
5354 exist in the source tree. Of course if you have some real source file
5355 to list in @code{libtop_la_SOURCES} there is no point in cheating with
5356 @code{nodist_EXTRA_libtop_la_SOURCES}.
5359 @node Libtool Modules
5360 @subsection Libtool Modules
5361 @cindex modules, libtool
5362 @cindex libtool modules
5363 @cindex @option{-module}, libtool
5365 These are libtool libraries meant to be dlopened. They are
5366 indicated to libtool by passing @option{-module} at link-time.
5369 pkglib_LTLIBRARIES = mymodule.la
5370 mymodule_la_SOURCES = doit.c
5371 mymodule_la_LDFLAGS = -module
5374 Ordinarily, Automake requires that a library's name start with
5375 @code{lib}. However, when building a dynamically loadable module you
5376 might wish to use a "nonstandard" name. Automake will not complain
5377 about such nonstandard names if it knows the library being built is a
5378 libtool module, i.e., if @option{-module} explicitly appears in the
5379 library's @code{_LDFLAGS} variable (or in the common @code{AM_LDFLAGS}
5380 variable when no per-library @code{_LDFLAGS} variable is defined).
5382 As always, @code{AC_SUBST} variables are black boxes to Automake since
5383 their values are not yet known when @command{automake} is run.
5384 Therefore if @option{-module} is set via such a variable, Automake
5385 cannot notice it and will proceed as if the library was an ordinary
5386 libtool library, with strict naming.
5388 If @code{mymodule_la_SOURCES} is not specified, then it defaults to
5389 the single file @file{mymodule.c} (@pxref{Default _SOURCES}).
5392 @subsection @code{_LIBADD}, @code{_LDFLAGS}, and @code{_LIBTOOLFLAGS}
5393 @cindex @code{_LIBADD}, libtool
5394 @cindex @code{_LDFLAGS}, libtool
5395 @cindex @code{_LIBTOOLFLAGS}, libtool
5396 @vindex AM_LIBTOOLFLAGS
5397 @vindex LIBTOOLFLAGS
5398 @vindex maude_LIBTOOLFLAGS
5400 As shown in previous sections, the @samp{@var{library}_LIBADD}
5401 variable should be used to list extra libtool objects (@file{.lo}
5402 files) or libtool libraries (@file{.la}) to add to @var{library}.
5404 The @samp{@var{library}_LDFLAGS} variable is the place to list
5405 additional libtool linking flags, such as @option{-version-info},
5406 @option{-static}, and a lot more. @xref{Link mode, , Link mode,
5407 libtool, The Libtool Manual}.
5409 The @command{libtool} command has two kinds of options: mode-specific
5410 options and generic options. Mode-specific options such as the
5411 aforementioned linking flags should be lumped with the other flags
5412 passed to the tool invoked by @command{libtool} (hence the use of
5413 @samp{@var{library}_LDFLAGS} for libtool linking flags). Generic
5414 options include @option{--tag=@var{tag}} and @option{--silent}
5415 (@pxref{Invoking libtool, , Invoking @command{libtool}, libtool, The
5416 Libtool Manual} for more options) should appear before the mode
5417 selection on the command line; in @file{Makefile.am}s they should
5418 be listed in the @samp{@var{library}_LIBTOOLFLAGS} variable.
5420 If @samp{@var{library}_LIBTOOLFLAGS} is not defined, then the variable
5421 @code{AM_LIBTOOLFLAGS} is used instead.
5423 These flags are passed to libtool after the @option{--tag=@var{tag}}
5424 option computed by Automake (if any), so
5425 @samp{@var{library}_LIBTOOLFLAGS} (or @code{AM_LIBTOOLFLAGS}) is a
5426 good place to override or supplement the @option{--tag=@var{tag}}
5429 The libtool rules also use a @code{LIBTOOLFLAGS} variable that should
5430 not be set in @file{Makefile.am}: this is a user variable (@pxref{Flag
5431 Variables Ordering}. It allows users to run @samp{make
5432 LIBTOOLFLAGS=--silent}, for instance. Note that the verbosity of
5433 @command{libtool} can also be influenced by the Automake support
5434 for silent rules (@pxref{Automake Silent Rules}).
5436 @node LTLIBOBJS, Libtool Issues, Libtool Flags, A Shared Library
5437 @subsection @code{LTLIBOBJS} and @code{LTALLOCA}
5438 @cindex @code{LTLIBOBJS}, special handling
5439 @cindex @code{LIBOBJS}, and Libtool
5440 @cindex @code{LTALLOCA}, special handling
5441 @cindex @code{ALLOCA}, and Libtool
5448 Where an ordinary library might include @samp{$(LIBOBJS)} or
5449 @samp{$(ALLOCA)} (@pxref{LIBOBJS}), a libtool library must use
5450 @samp{$(LTLIBOBJS)} or @samp{$(LTALLOCA)}. This is required because
5451 the object files that libtool operates on do not necessarily end in
5454 Nowadays, the computation of @code{LTLIBOBJS} from @code{LIBOBJS} is
5455 performed automatically by Autoconf (@pxref{AC_LIBOBJ vs LIBOBJS, ,
5456 @code{AC_LIBOBJ} vs.@: @code{LIBOBJS}, autoconf, The Autoconf Manual}).
5458 @node Libtool Issues
5459 @subsection Common Issues Related to Libtool's Use
5462 * Error required file ltmain.sh not found:: The need to run libtoolize
5463 * Objects created both with libtool and without:: Avoid a specific build race
5466 @node Error required file ltmain.sh not found
5467 @subsubsection Error: @samp{required file `./ltmain.sh' not found}
5468 @cindex @file{ltmain.sh} not found
5469 @cindex @command{libtoolize}, no longer run by @command{automake}
5470 @cindex @command{libtoolize} and @command{autoreconf}
5471 @cindex @command{autoreconf} and @command{libtoolize}
5472 @cindex @file{bootstrap.sh} and @command{autoreconf}
5473 @cindex @file{autogen.sh} and @command{autoreconf}
5475 Libtool comes with a tool called @command{libtoolize} that will
5476 install libtool's supporting files into a package. Running this
5477 command will install @file{ltmain.sh}. You should execute it before
5478 @command{aclocal} and @command{automake}.
5480 People upgrading old packages to newer autotools are likely to face
5481 this issue because older Automake versions used to call
5482 @command{libtoolize}. Therefore old build scripts do not call
5483 @command{libtoolize}.
5485 Since Automake 1.6, it has been decided that running
5486 @command{libtoolize} was none of Automake's business. Instead, that
5487 functionality has been moved into the @command{autoreconf} command
5488 (@pxref{autoreconf Invocation, , Using @command{autoreconf}, autoconf,
5489 The Autoconf Manual}). If you do not want to remember what to run and
5490 when, just learn the @command{autoreconf} command. Hopefully,
5491 replacing existing @file{bootstrap.sh} or @file{autogen.sh} scripts by
5492 a call to @command{autoreconf} should also free you from any similar
5493 incompatible change in the future.
5495 @node Objects created both with libtool and without
5496 @subsubsection Objects @samp{created with both libtool and without}
5498 Sometimes, the same source file is used both to build a libtool
5499 library and to build another non-libtool target (be it a program or
5502 Let's consider the following @file{Makefile.am}.
5506 prog_SOURCES = prog.c foo.c @dots{}
5508 lib_LTLIBRARIES = libfoo.la
5509 libfoo_la_SOURCES = foo.c @dots{}
5513 (In this trivial case the issue could be avoided by linking
5514 @file{libfoo.la} with @file{prog} instead of listing @file{foo.c} in
5515 @code{prog_SOURCES}. But let's assume we really want to keep
5516 @file{prog} and @file{libfoo.la} separate.)
5518 Technically, it means that we should build @file{foo.$(OBJEXT)} for
5519 @file{prog}, and @file{foo.lo} for @file{libfoo.la}. The problem is
5520 that in the course of creating @file{foo.lo}, libtool may erase (or
5521 replace) @file{foo.$(OBJEXT)}, and this cannot be avoided.
5523 Therefore, when Automake detects this situation it will complain
5524 with a message such as
5526 object 'foo.$(OBJEXT)' created both with libtool and without
5529 A workaround for this issue is to ensure that these two objects get
5530 different basenames. As explained in @ref{Renamed Objects}, this
5531 happens automatically when per-targets flags are used.
5535 prog_SOURCES = prog.c foo.c @dots{}
5536 prog_CFLAGS = $(AM_CFLAGS)
5538 lib_LTLIBRARIES = libfoo.la
5539 libfoo_la_SOURCES = foo.c @dots{}
5543 Adding @samp{prog_CFLAGS = $(AM_CFLAGS)} is almost a no-op, because
5544 when the @code{prog_CFLAGS} is defined, it is used instead of
5545 @code{AM_CFLAGS}. However as a side effect it will cause
5546 @file{prog.c} and @file{foo.c} to be compiled as
5547 @file{prog-prog.$(OBJEXT)} and @file{prog-foo.$(OBJEXT)}, which solves
5550 @node Program and Library Variables
5551 @section Program and Library Variables
5553 Associated with each program is a collection of variables that can be
5554 used to modify how that program is built. There is a similar list of
5555 such variables for each library. The canonical name of the program (or
5556 library) is used as a base for naming these variables.
5558 In the list below, we use the name ``maude'' to refer to the program or
5559 library. In your @file{Makefile.am} you would replace this with the
5560 canonical name of your program. This list also refers to ``maude'' as a
5561 program, but in general the same rules apply for both static and dynamic
5562 libraries; the documentation below notes situations where programs and
5567 This variable, if it exists, lists all the source files that are
5568 compiled to build the program. These files are added to the
5569 distribution by default. When building the program, Automake will cause
5570 each source file to be compiled to a single @file{.o} file (or
5571 @file{.lo} when using libtool). Normally these object files are named
5572 after the source file, but other factors can change this. If a file in
5573 the @code{_SOURCES} variable has an unrecognized extension, Automake
5574 will do one of two things with it. If a suffix rule exists for turning
5575 files with the unrecognized extension into @file{.o} files, then
5576 @command{automake} will treat this file as it will any other source file
5577 (@pxref{Support for Other Languages}). Otherwise, the file will be
5578 ignored as though it were a header file.
5580 The prefixes @code{dist_} and @code{nodist_} can be used to control
5581 whether files listed in a @code{_SOURCES} variable are distributed.
5582 @code{dist_} is redundant, as sources are distributed by default, but it
5583 can be specified for clarity if desired.
5585 It is possible to have both @code{dist_} and @code{nodist_} variants of
5586 a given @code{_SOURCES} variable at once; this lets you easily
5587 distribute some files and not others, for instance:
5590 nodist_maude_SOURCES = nodist.c
5591 dist_maude_SOURCES = dist-me.c
5594 By default the output file (on Unix systems, the @file{.o} file) will
5595 be put into the current build directory. However, if the option
5596 @option{subdir-objects} is in effect in the current directory then the
5597 @file{.o} file will be put into the subdirectory named after the
5598 source file. For instance, with @option{subdir-objects} enabled,
5599 @file{sub/dir/file.c} will be compiled to @file{sub/dir/file.o}. Some
5600 people prefer this mode of operation. You can specify
5601 @option{subdir-objects} in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
5602 @cindex Subdirectory, objects in
5603 @cindex Objects in subdirectory
5606 @item EXTRA_maude_SOURCES
5607 Automake needs to know the list of files you intend to compile
5608 @emph{statically}. For one thing, this is the only way Automake has of
5609 knowing what sort of language support a given @file{Makefile.in}
5610 requires. @footnote{There are other, more obscure reasons for
5611 this limitation as well.} This means that, for example, you can't put a
5612 configure substitution like @samp{@@my_sources@@} into a @samp{_SOURCES}
5613 variable. If you intend to conditionally compile source files and use
5614 @file{configure} to substitute the appropriate object names into, e.g.,
5615 @code{_LDADD} (see below), then you should list the corresponding source
5616 files in the @code{EXTRA_} variable.
5618 This variable also supports @code{dist_} and @code{nodist_} prefixes.
5619 For instance, @code{nodist_EXTRA_maude_SOURCES} would list extra
5620 sources that may need to be built, but should not be distributed.
5623 A static library is created by default by invoking @samp{$(AR)
5624 $(ARFLAGS)} followed by the name of the library and then the objects
5625 being put into the library. You can override this by setting the
5626 @code{_AR} variable. This is usually used with C++; some C++
5627 compilers require a special invocation in order to instantiate all the
5628 templates that should go into a library. For instance, the SGI C++
5629 compiler likes this variable set like so:
5631 libmaude_a_AR = $(CXX) -ar -o
5635 Extra objects can be added to a @emph{library} using the @code{_LIBADD}
5636 variable. For instance, this should be used for objects determined by
5637 @command{configure} (@pxref{A Library}).
5639 In the case of libtool libraries, @code{maude_LIBADD} can also refer
5640 to other libtool libraries.
5643 Extra objects (@file{*.$(OBJEXT)}) and libraries (@file{*.a},
5644 @file{*.la}) can be added to a @emph{program} by listing them in the
5645 @code{_LDADD} variable. For instance, this should be used for objects
5646 determined by @command{configure} (@pxref{Linking}).
5648 @code{_LDADD} and @code{_LIBADD} are inappropriate for passing
5649 program-specific linker flags (except for @option{-l}, @option{-L},
5650 @option{-dlopen} and @option{-dlpreopen}). Use the @code{_LDFLAGS} variable
5653 For instance, if your @file{configure.ac} uses @code{AC_PATH_XTRA}, you
5654 could link your program against the X libraries like so:
5657 maude_LDADD = $(X_PRE_LIBS) $(X_LIBS) $(X_EXTRA_LIBS)
5660 We recommend that you use @option{-l} and @option{-L} only when
5661 referring to third-party libraries, and give the explicit file names
5662 of any library built by your package. Doing so will ensure that
5663 @code{maude_DEPENDENCIES} (see below) is correctly defined by default.
5666 This variable is used to pass extra flags to the link step of a program
5667 or a shared library. It overrides the @code{AM_LDFLAGS} variable.
5669 @item maude_LIBTOOLFLAGS
5670 This variable is used to pass extra options to @command{libtool}.
5671 It overrides the @code{AM_LIBTOOLFLAGS} variable.
5672 These options are output before @command{libtool}'s @option{--mode=@var{mode}}
5673 option, so they should not be mode-specific options (those belong to
5674 the compiler or linker flags). @xref{Libtool Flags}.
5676 @item maude_DEPENDENCIES
5677 @itemx EXTRA_maude_DEPENDENCIES
5678 It is also occasionally useful to have a target (program or library)
5679 depend on some other file that is not actually part of that target.
5680 This can be done using the @code{_DEPENDENCIES} variable. Each
5681 target depends on the contents of such a variable, but no further
5682 interpretation is done.
5684 Since these dependencies are associated to the link rule used to
5685 create the programs they should normally list files used by the link
5686 command. That is @file{*.$(OBJEXT)}, @file{*.a}, or @file{*.la} files
5687 for programs; @file{*.lo} and @file{*.la} files for Libtool libraries;
5688 and @file{*.$(OBJEXT)} files for static libraries. In rare cases you
5689 may need to add other kinds of files such as linker scripts, but
5690 @emph{listing a source file in @code{_DEPENDENCIES} is wrong}. If
5691 some source file needs to be built before all the components of a
5692 program are built, consider using the @code{BUILT_SOURCES} variable
5695 If @code{_DEPENDENCIES} is not supplied, it is computed by Automake.
5696 The automatically-assigned value is the contents of @code{_LDADD} or
5697 @code{_LIBADD}, with most configure substitutions, @option{-l}, @option{-L},
5698 @option{-dlopen} and @option{-dlpreopen} options removed. The configure
5699 substitutions that are left in are only @samp{$(LIBOBJS)} and
5700 @samp{$(ALLOCA)}; these are left because it is known that they will not
5701 cause an invalid value for @code{_DEPENDENCIES} to be generated.
5703 @code{_DEPENDENCIES} is more likely used to perform conditional
5704 compilation using an @code{AC_SUBST} variable that contains a list of
5705 objects. @xref{Conditional Sources}, and @ref{Conditional Libtool
5708 The @code{EXTRA_*_DEPENDENCIES} variable may be useful for cases where
5709 you merely want to augment the @command{automake}-generated
5710 @code{_DEPENDENCIES} variable rather than replacing it.
5713 You can override the linker on a per-program basis. By default the
5714 linker is chosen according to the languages used by the program. For
5715 instance, a program that includes C++ source code would use the C++
5716 compiler to link. The @code{_LINK} variable must hold the name of a
5717 command that can be passed all the @file{.o} file names and libraries
5718 to link against as arguments. Note that the name of the underlying
5719 program is @emph{not} passed to @code{_LINK}; typically one uses
5723 maude_LINK = $(CCLD) -magic -o $@@
5726 If a @code{_LINK} variable is not supplied, it may still be generated
5727 and used by Automake due to the use of per-target link flags such as
5728 @code{_CFLAGS}, @code{_LDFLAGS} or @code{_LIBTOOLFLAGS}, in cases where
5731 @item maude_CCASFLAGS
5733 @itemx maude_CPPFLAGS
5734 @itemx maude_CXXFLAGS
5736 @itemx maude_GCJFLAGS
5738 @itemx maude_OBJCFLAGS
5739 @itemx maude_OBJCXXFLAGS
5741 @itemx maude_UPCFLAGS
5743 @cindex per-target compilation flags, defined
5744 Automake allows you to set compilation flags on a per-program (or
5745 per-library) basis. A single source file can be included in several
5746 programs, and it will potentially be compiled with different flags for
5747 each program. This works for any language directly supported by
5748 Automake. These @dfn{per-target compilation flags} are
5757 @samp{_OBJCXXFLAGS},
5759 @samp{_UPCFLAGS}, and
5762 When using a per-target compilation flag, Automake will choose a
5763 different name for the intermediate object files. Ordinarily a file
5764 like @file{sample.c} will be compiled to produce @file{sample.o}.
5765 However, if the program's @code{_CFLAGS} variable is set, then the
5766 object file will be named, for instance, @file{maude-sample.o}. (See
5767 also @ref{Renamed Objects}.) The use of per-target compilation flags
5768 with C sources requires that the macro @code{AM_PROG_CC_C_O} be called
5769 from @file{configure.ac}.
5771 In compilations with per-target flags, the ordinary @samp{AM_} form of
5772 the flags variable is @emph{not} automatically included in the
5773 compilation (however, the user form of the variable @emph{is} included).
5774 So for instance, if you want the hypothetical @file{maude} compilations
5775 to also use the value of @code{AM_CFLAGS}, you would need to write:
5778 maude_CFLAGS = @dots{} your flags @dots{} $(AM_CFLAGS)
5781 @xref{Flag Variables Ordering}, for more discussion about the
5782 interaction between user variables, @samp{AM_} shadow variables, and
5783 per-target variables.
5785 @item maude_SHORTNAME
5786 On some platforms the allowable file names are very short. In order to
5787 support these systems and per-target compilation flags at the same
5788 time, Automake allows you to set a ``short name'' that will influence
5789 how intermediate object files are named. For instance, in the following
5793 bin_PROGRAMS = maude
5794 maude_CPPFLAGS = -DSOMEFLAG
5796 maude_SOURCES = sample.c @dots{}
5800 the object file would be named @file{m-sample.o} rather than
5801 @file{maude-sample.o}.
5803 This facility is rarely needed in practice,
5804 and we recommend avoiding it until you find it is required.
5807 @node Default _SOURCES
5808 @section Default @code{_SOURCES}
5812 @cindex @code{_SOURCES}, default
5813 @cindex default @code{_SOURCES}
5814 @vindex AM_DEFAULT_SOURCE_EXT
5816 @code{_SOURCES} variables are used to specify source files of programs
5817 (@pxref{A Program}), libraries (@pxref{A Library}), and Libtool
5818 libraries (@pxref{A Shared Library}).
5820 When no such variable is specified for a target, Automake will define
5821 one itself. The default is to compile a single C file whose base name
5822 is the name of the target itself, with any extension replaced by
5823 @code{AM_DEFAULT_SOURCE_EXT}, which defaults to @file{.c}.
5825 For example if you have the following somewhere in your
5826 @file{Makefile.am} with no corresponding @code{libfoo_a_SOURCES}:
5829 lib_LIBRARIES = libfoo.a sub/libc++.a
5833 @file{libfoo.a} will be built using a default source file named
5834 @file{libfoo.c}, and @file{sub/libc++.a} will be built from
5835 @file{sub/libc++.c}. (In older versions @file{sub/libc++.a}
5836 would be built from @file{sub_libc___a.c}, i.e., the default source
5837 was the canonized name of the target, with @file{.c} appended.
5838 We believe the new behavior is more sensible, but for backward
5839 compatibility @command{automake} will use the old name if a file or a rule
5840 with that name exists and @code{AM_DEFAULT_SOURCE_EXT} is not used.)
5842 @cindex @code{check_PROGRAMS} example
5843 @vindex check_PROGRAMS
5844 Default sources are mainly useful in test suites, when building many
5845 test programs each from a single source. For instance, in
5848 check_PROGRAMS = test1 test2 test3
5849 AM_DEFAULT_SOURCE_EXT = .cpp
5853 @file{test1}, @file{test2}, and @file{test3} will be built
5854 from @file{test1.cpp}, @file{test2.cpp}, and @file{test3.cpp}.
5855 Without the last line, they will be built from @file{test1.c},
5856 @file{test2.c}, and @file{test3.c}.
5858 @cindex Libtool modules, default source example
5859 @cindex default source, Libtool modules example
5860 Another case where this is convenient is building many Libtool modules
5861 (@file{module@var{n}.la}), each defined in its own file
5862 (@file{module@var{n}.c}).
5865 AM_LDFLAGS = -module
5866 lib_LTLIBRARIES = module1.la module2.la module3.la
5869 @cindex empty @code{_SOURCES}
5870 @cindex @code{_SOURCES}, empty
5871 Finally, there is one situation where this default source computation
5872 needs to be avoided: when a target should not be built from sources.
5873 We already saw such an example in @ref{true}; this happens when all
5874 the constituents of a target have already been compiled and just need
5875 to be combined using a @code{_LDADD} variable. Then it is necessary
5876 to define an empty @code{_SOURCES} variable, so that @command{automake}
5877 does not compute a default.
5880 bin_PROGRAMS = target
5882 target_LDADD = libmain.a libmisc.a
5886 @section Special handling for @code{LIBOBJS} and @code{ALLOCA}
5888 @cindex @code{LIBOBJS}, example
5889 @cindex @code{ALLOCA}, example
5890 @cindex @code{LIBOBJS}, special handling
5891 @cindex @code{ALLOCA}, special handling
5897 The @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} variables list object
5898 files that should be compiled into the project to provide an
5899 implementation for functions that are missing or broken on the host
5900 system. They are substituted by @file{configure}.
5904 These variables are defined by Autoconf macros such as
5905 @code{AC_LIBOBJ}, @code{AC_REPLACE_FUNCS} (@pxref{Generic Functions, ,
5906 Generic Function Checks, autoconf, The Autoconf Manual}), or
5907 @code{AC_FUNC_ALLOCA} (@pxref{Particular Functions, , Particular
5908 Function Checks, autoconf, The Autoconf Manual}). Many other Autoconf
5909 macros call @code{AC_LIBOBJ} or @code{AC_REPLACE_FUNCS} to
5910 populate @samp{$(LIBOBJS)}.
5912 @acindex AC_LIBSOURCE
5914 Using these variables is very similar to doing conditional compilation
5915 using @code{AC_SUBST} variables, as described in @ref{Conditional
5916 Sources}. That is, when building a program, @samp{$(LIBOBJS)} and
5917 @samp{$(ALLOCA)} should be added to the associated @samp{*_LDADD}
5918 variable, or to the @samp{*_LIBADD} variable when building a library.
5919 However there is no need to list the corresponding sources in
5920 @samp{EXTRA_*_SOURCES} nor to define @samp{*_DEPENDENCIES}. Automake
5921 automatically adds @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} to the
5922 dependencies, and it will discover the list of corresponding source
5923 files automatically (by tracing the invocations of the
5924 @code{AC_LIBSOURCE} Autoconf macros). If you have already defined
5925 @samp{*_DEPENDENCIES} explicitly for an unrelated reason, then you
5926 either need to add these variables manually, or use
5927 @samp{EXTRA_*_DEPENDENCIES} instead of @samp{*_DEPENDENCIES}.
5929 These variables are usually used to build a portability library that
5930 is linked with all the programs of the project. We now review a
5931 sample setup. First, @file{configure.ac} contains some checks that
5932 affect either @code{LIBOBJS} or @code{ALLOCA}.
5937 AC_CONFIG_LIBOBJ_DIR([lib])
5939 AC_FUNC_MALLOC dnl May add malloc.$(OBJEXT) to LIBOBJS
5940 AC_FUNC_MEMCMP dnl May add memcmp.$(OBJEXT) to LIBOBJS
5941 AC_REPLACE_FUNCS([strdup]) dnl May add strdup.$(OBJEXT) to LIBOBJS
5942 AC_FUNC_ALLOCA dnl May add alloca.$(OBJEXT) to ALLOCA
5951 @acindex AC_CONFIG_LIBOBJ_DIR
5953 The @code{AC_CONFIG_LIBOBJ_DIR} tells Autoconf that the source files
5954 of these object files are to be found in the @file{lib/} directory.
5955 Automake can also use this information, otherwise it expects the
5956 source files are to be in the directory where the @samp{$(LIBOBJS)}
5957 and @samp{$(ALLOCA)} variables are used.
5959 The @file{lib/} directory should therefore contain @file{malloc.c},
5960 @file{memcmp.c}, @file{strdup.c}, @file{alloca.c}. Here is its
5966 noinst_LIBRARIES = libcompat.a
5967 libcompat_a_SOURCES =
5968 libcompat_a_LIBADD = $(LIBOBJS) $(ALLOCA)
5971 The library can have any name, of course, and anyway it is not going
5972 to be installed: it just holds the replacement versions of the missing
5973 or broken functions so we can later link them in. Many projects
5974 also include extra functions, specific to the project, in that
5975 library: they are simply added on the @code{_SOURCES} line.
5977 @cindex Empty libraries and @samp{$(LIBOBJS)}
5978 @cindex @samp{$(LIBOBJS)} and empty libraries
5979 There is a small trap here, though: @samp{$(LIBOBJS)} and
5980 @samp{$(ALLOCA)} might be empty, and building an empty library is not
5981 portable. You should ensure that there is always something to put in
5982 @file{libcompat.a}. Most projects will also add some utility
5983 functions in that directory, and list them in
5984 @code{libcompat_a_SOURCES}, so in practice @file{libcompat.a} cannot
5987 Finally here is how this library could be used from the @file{src/}
5993 # Link all programs in this directory with libcompat.a
5994 LDADD = ../lib/libcompat.a
5996 bin_PROGRAMS = tool1 tool2 @dots{}
5997 tool1_SOURCES = @dots{}
5998 tool2_SOURCES = @dots{}
6001 When option @option{subdir-objects} is not used, as in the above
6002 example, the variables @samp{$(LIBOBJS)} or @samp{$(ALLOCA)} can only
6003 be used in the directory where their sources lie. E.g., here it would
6004 be wrong to use @samp{$(LIBOBJS)} or @samp{$(ALLOCA)} in
6005 @file{src/Makefile.am}. However if both @option{subdir-objects} and
6006 @code{AC_CONFIG_LIBOBJ_DIR} are used, it is OK to use these variables
6007 in other directories. For instance @file{src/Makefile.am} could be
6013 AUTOMAKE_OPTIONS = subdir-objects
6014 LDADD = $(LIBOBJS) $(ALLOCA)
6016 bin_PROGRAMS = tool1 tool2 @dots{}
6017 tool1_SOURCES = @dots{}
6018 tool2_SOURCES = @dots{}
6021 Because @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} contain object
6022 file names that end with @samp{.$(OBJEXT)}, they are not suitable for
6023 Libtool libraries (where the expected object extension is @file{.lo}):
6024 @code{LTLIBOBJS} and @code{LTALLOCA} should be used instead.
6026 @code{LTLIBOBJS} is defined automatically by Autoconf and should not
6027 be defined by hand (as in the past), however at the time of writing
6028 @code{LTALLOCA} still needs to be defined from @code{ALLOCA} manually.
6029 @xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs.@: @code{LIBOBJS},
6030 autoconf, The Autoconf Manual}.
6033 @node Program Variables
6034 @section Variables used when building a program
6036 Occasionally it is useful to know which @file{Makefile} variables
6037 Automake uses for compilations, and in which order (@pxref{Flag
6038 Variables Ordering}); for instance, you might need to do your own
6039 compilation in some special cases.
6041 Some variables are inherited from Autoconf; these are @code{CC},
6042 @code{CFLAGS}, @code{CPPFLAGS}, @code{DEFS}, @code{LDFLAGS}, and
6051 There are some additional variables that Automake defines on its own:
6055 The contents of this variable are passed to every compilation that invokes
6056 the C preprocessor; it is a list of arguments to the preprocessor. For
6057 instance, @option{-I} and @option{-D} options should be listed here.
6059 Automake already provides some @option{-I} options automatically, in a
6060 separate variable that is also passed to every compilation that invokes
6061 the C preprocessor. In particular it generates @samp{-I.},
6062 @samp{-I$(srcdir)}, and a @option{-I} pointing to the directory holding
6063 @file{config.h} (if you've used @code{AC_CONFIG_HEADERS}). You can
6064 disable the default @option{-I} options using the @option{nostdinc}
6067 When a file to be included is generated during the build and not part
6068 of a distribution tarball, its location is under @code{$(builddir)},
6069 not under @code{$(srcdir)}. This matters especially for packages that
6070 use header files placed in sub-directories and want to allow builds
6071 outside the source tree (@pxref{VPATH Builds}). In that case we
6072 recommend to use a pair of @option{-I} options, such as, e.g.,
6073 @samp{-Isome/subdir -I$(srcdir)/some/subdir} or
6074 @samp{-I$(top_builddir)/some/subdir -I$(top_srcdir)/some/subdir}.
6075 Note that the reference to the build tree should come before the
6076 reference to the source tree, so that accidentally leftover generated
6077 files in the source directory are ignored.
6079 @code{AM_CPPFLAGS} is ignored in preference to a per-executable (or
6080 per-library) @code{_CPPFLAGS} variable if it is defined.
6083 This does the same job as @code{AM_CPPFLAGS} (or any per-target
6084 @code{_CPPFLAGS} variable if it is used). It is an older name for the
6085 same functionality. This variable is deprecated; we suggest using
6086 @code{AM_CPPFLAGS} and per-target @code{_CPPFLAGS} instead.
6089 This is the variable the @file{Makefile.am} author can use to pass
6090 in additional C compiler flags. It is more fully documented elsewhere.
6091 In some situations, this is not used, in preference to the
6092 per-executable (or per-library) @code{_CFLAGS}.
6095 This is the command used to actually compile a C source file. The
6096 file name is appended to form the complete command line.
6099 This is the variable the @file{Makefile.am} author can use to pass
6100 in additional linker flags. In some situations, this is not used, in
6101 preference to the per-executable (or per-library) @code{_LDFLAGS}.
6104 This is the command used to actually link a C program. It already
6105 includes @samp{-o $@@} and the usual variable references (for instance,
6106 @code{CFLAGS}); it takes as ``arguments'' the names of the object files
6107 and libraries to link in. This variable is not used when the linker is
6108 overridden with a per-target @code{_LINK} variable or per-target flags
6109 cause Automake to define such a @code{_LINK} variable.
6114 @section Yacc and Lex support
6116 Automake has somewhat idiosyncratic support for Yacc and Lex.
6118 Automake assumes that the @file{.c} file generated by @command{yacc}
6119 (or @command{lex}) should be named using the basename of the input
6120 file. That is, for a yacc source file @file{foo.y}, Automake will
6121 cause the intermediate file to be named @file{foo.c} (as opposed to
6122 @file{y.tab.c}, which is more traditional).
6124 The extension of a yacc source file is used to determine the extension
6125 of the resulting C or C++ source and header files. Note that header
6126 files are generated only when the @option{-d} Yacc option is used; see
6127 below for more information about this flag, and how to specify it.
6128 Files with the extension @file{.y} will thus be turned into @file{.c}
6129 sources and @file{.h} headers; likewise, @file{.yy} will become
6130 @file{.cc} and @file{.hh}, @file{.y++} will become @file{c++} and
6131 @file{h++}, @file{.yxx} will become @file{.cxx} and @file{.hxx},
6132 and @file{.ypp} will become @file{.cpp} and @file{.hpp}.
6134 Similarly, lex source files can be used to generate C or C++; the
6135 extensions @file{.l}, @file{.ll}, @file{.l++}, @file{.lxx}, and
6136 @file{.lpp} are recognized.
6138 You should never explicitly mention the intermediate (C or C++) file
6139 in any @code{SOURCES} variable; only list the source file.
6141 The intermediate files generated by @command{yacc} (or @command{lex})
6142 will be included in any distribution that is made. That way the user
6143 doesn't need to have @command{yacc} or @command{lex}.
6145 If a @command{yacc} source file is seen, then your @file{configure.ac} must
6146 define the variable @code{YACC}. This is most easily done by invoking
6147 the macro @code{AC_PROG_YACC} (@pxref{Particular Programs, , Particular
6148 Program Checks, autoconf, The Autoconf Manual}).
6152 When @code{yacc} is invoked, it is passed @code{AM_YFLAGS} and
6153 @code{YFLAGS}. The latter is a user variable and the former is
6154 intended for the @file{Makefile.am} author.
6156 @code{AM_YFLAGS} is usually used to pass the @option{-d} option to
6157 @command{yacc}. Automake knows what this means and will automatically
6158 adjust its rules to update and distribute the header file built by
6159 @samp{yacc -d}@footnote{Please note that @command{automake} recognizes
6160 @option{-d} in @code{AM_YFLAGS} only if it is not clustered with other
6161 options; for example, it won't be recognized if @code{AM_YFLAGS} is
6162 @option{-dt}, but it will be if @code{AM_YFLAGS} is @option{-d -t} or
6164 What Automake cannot guess, though, is where this
6165 header will be used: it is up to you to ensure the header gets built
6166 before it is first used. Typically this is necessary in order for
6167 dependency tracking to work when the header is included by another
6168 file. The common solution is listing the header file in
6169 @code{BUILT_SOURCES} (@pxref{Sources}) as follows.
6172 BUILT_SOURCES = parser.h
6175 foo_SOURCES = @dots{} parser.y @dots{}
6178 If a @command{lex} source file is seen, then your @file{configure.ac}
6179 must define the variable @code{LEX}. You can use @code{AC_PROG_LEX}
6180 to do this (@pxref{Particular Programs, , Particular Program Checks,
6181 autoconf, The Autoconf Manual}), but using @code{AM_PROG_LEX} macro
6182 (@pxref{Macros}) is recommended.
6186 When @command{lex} is invoked, it is passed @code{AM_LFLAGS} and
6187 @code{LFLAGS}. The latter is a user variable and the former is
6188 intended for the @file{Makefile.am} author.
6190 When @code{AM_MAINTAINER_MODE} (@pxref{maintainer-mode}) is used, the
6191 rebuild rule for distributed Yacc and Lex sources are only used when
6192 @code{maintainer-mode} is enabled, or when the files have been erased.
6194 @cindex @command{ylwrap}
6195 @cindex @command{yacc}, multiple parsers
6196 @cindex Multiple @command{yacc} parsers
6197 @cindex Multiple @command{lex} lexers
6198 @cindex @command{lex}, multiple lexers
6200 When @command{lex} or @command{yacc} sources are used, @code{automake
6201 -i} automatically installs an auxiliary program called
6202 @command{ylwrap} in your package (@pxref{Auxiliary Programs}). This
6203 program is used by the build rules to rename the output of these
6204 tools, and makes it possible to include multiple @command{yacc} (or
6205 @command{lex}) source files in a single directory. (This is necessary
6206 because yacc's output file name is fixed, and a parallel make could
6207 conceivably invoke more than one instance of @command{yacc}
6210 For @command{yacc}, simply managing locking is insufficient. The output of
6211 @command{yacc} always uses the same symbol names internally, so it isn't
6212 possible to link two @command{yacc} parsers into the same executable.
6214 We recommend using the following renaming hack used in @command{gdb}:
6216 #define yymaxdepth c_maxdepth
6217 #define yyparse c_parse
6219 #define yyerror c_error
6220 #define yylval c_lval
6221 #define yychar c_char
6222 #define yydebug c_debug
6223 #define yypact c_pact
6230 #define yyexca c_exca
6231 #define yyerrflag c_errflag
6232 #define yynerrs c_nerrs
6236 #define yy_yys c_yys
6237 #define yystate c_state
6240 #define yy_yyv c_yyv
6242 #define yylloc c_lloc
6243 #define yyreds c_reds
6244 #define yytoks c_toks
6245 #define yylhs c_yylhs
6246 #define yylen c_yylen
6247 #define yydefred c_yydefred
6248 #define yydgoto c_yydgoto
6249 #define yysindex c_yysindex
6250 #define yyrindex c_yyrindex
6251 #define yygindex c_yygindex
6252 #define yytable c_yytable
6253 #define yycheck c_yycheck
6254 #define yyname c_yyname
6255 #define yyrule c_yyrule
6258 For each define, replace the @samp{c_} prefix with whatever you like.
6259 These defines work for @command{bison}, @command{byacc}, and
6260 traditional @code{yacc}s. If you find a parser generator that uses a
6261 symbol not covered here, please report the new name so it can be added
6266 @section C++ Support
6269 @cindex Support for C++
6271 Automake includes full support for C++.
6273 Any package including C++ code must define the output variable
6274 @code{CXX} in @file{configure.ac}; the simplest way to do this is to use
6275 the @code{AC_PROG_CXX} macro (@pxref{Particular Programs, , Particular
6276 Program Checks, autoconf, The Autoconf Manual}).
6278 A few additional variables are defined when a C++ source file is seen:
6282 The name of the C++ compiler.
6285 Any flags to pass to the C++ compiler.
6288 The maintainer's variant of @code{CXXFLAGS}.
6291 The command used to actually compile a C++ source file. The file name
6292 is appended to form the complete command line.
6295 The command used to actually link a C++ program.
6299 @node Objective C Support
6300 @section Objective C Support
6302 @cindex Objective C support
6303 @cindex Support for Objective C
6305 Automake includes some support for Objective C.
6307 Any package including Objective C code must define the output variable
6308 @code{OBJC} in @file{configure.ac}; the simplest way to do this is to use
6309 the @code{AC_PROG_OBJC} macro (@pxref{Particular Programs, , Particular
6310 Program Checks, autoconf, The Autoconf Manual}).
6312 A few additional variables are defined when an Objective C source file
6317 The name of the Objective C compiler.
6320 Any flags to pass to the Objective C compiler.
6323 The maintainer's variant of @code{OBJCFLAGS}.
6326 The command used to actually compile an Objective C source file. The
6327 file name is appended to form the complete command line.
6330 The command used to actually link an Objective C program.
6334 @node Objective C++ Support
6335 @section Objective C++ Support
6337 @cindex Objective C++ support
6338 @cindex Support for Objective C++
6340 Automake includes some support for Objective C++.
6342 Any package including Objective C++ code must define the output variable
6343 @code{OBJCXX} in @file{configure.ac}; the simplest way to do this is to use
6344 the @code{AC_PROG_OBJCXX} macro (@pxref{Particular Programs, , Particular
6345 Program Checks, autoconf, The Autoconf Manual}).
6347 A few additional variables are defined when an Objective C++ source file
6352 The name of the Objective C++ compiler.
6355 Any flags to pass to the Objective C++ compiler.
6357 @item AM_OBJCXXFLAGS
6358 The maintainer's variant of @code{OBJCXXFLAGS}.
6361 The command used to actually compile an Objective C++ source file. The
6362 file name is appended to form the complete command line.
6365 The command used to actually link an Objective C++ program.
6369 @node Unified Parallel C Support
6370 @section Unified Parallel C Support
6372 @cindex Unified Parallel C support
6373 @cindex Support for Unified Parallel C
6375 Automake includes some support for Unified Parallel C.
6377 Any package including Unified Parallel C code must define the output
6378 variable @code{UPC} in @file{configure.ac}; the simplest way to do
6379 this is to use the @code{AM_PROG_UPC} macro (@pxref{Public Macros}).
6381 A few additional variables are defined when a Unified Parallel C
6382 source file is seen:
6386 The name of the Unified Parallel C compiler.
6389 Any flags to pass to the Unified Parallel C compiler.
6392 The maintainer's variant of @code{UPCFLAGS}.
6395 The command used to actually compile a Unified Parallel C source file.
6396 The file name is appended to form the complete command line.
6399 The command used to actually link a Unified Parallel C program.
6403 @node Assembly Support
6404 @section Assembly Support
6406 Automake includes some support for assembly code. There are two forms
6407 of assembler files: normal (@file{*.s}) and preprocessed by @code{CPP}
6408 (@file{*.S} or @file{*.sx}).
6413 @vindex AM_CCASFLAGS
6415 The variable @code{CCAS} holds the name of the compiler used to build
6416 assembly code. This compiler must work a bit like a C compiler; in
6417 particular it must accept @option{-c} and @option{-o}. The values of
6418 @code{CCASFLAGS} and @code{AM_CCASFLAGS} (or its per-target
6419 definition) is passed to the compilation. For preprocessed files,
6420 @code{DEFS}, @code{DEFAULT_INCLUDES}, @code{INCLUDES}, @code{CPPFLAGS}
6421 and @code{AM_CPPFLAGS} are also used.
6423 The autoconf macro @code{AM_PROG_AS} will define @code{CCAS} and
6424 @code{CCASFLAGS} for you (unless they are already set, it simply sets
6425 @code{CCAS} to the C compiler and @code{CCASFLAGS} to the C compiler
6426 flags), but you are free to define these variables by other means.
6428 Only the suffixes @file{.s}, @file{.S}, and @file{.sx} are recognized by
6429 @command{automake} as being files containing assembly code.
6432 @node Fortran 77 Support
6433 @comment node-name, next, previous, up
6434 @section Fortran 77 Support
6436 @cindex Fortran 77 support
6437 @cindex Support for Fortran 77
6439 Automake includes full support for Fortran 77.
6441 Any package including Fortran 77 code must define the output variable
6442 @code{F77} in @file{configure.ac}; the simplest way to do this is to use
6443 the @code{AC_PROG_F77} macro (@pxref{Particular Programs, , Particular
6444 Program Checks, autoconf, The Autoconf Manual}).
6446 A few additional variables are defined when a Fortran 77 source file is
6452 The name of the Fortran 77 compiler.
6455 Any flags to pass to the Fortran 77 compiler.
6458 The maintainer's variant of @code{FFLAGS}.
6461 Any flags to pass to the Ratfor compiler.
6464 The maintainer's variant of @code{RFLAGS}.
6467 The command used to actually compile a Fortran 77 source file. The file
6468 name is appended to form the complete command line.
6471 The command used to actually link a pure Fortran 77 program or shared
6476 Automake can handle preprocessing Fortran 77 and Ratfor source files in
6477 addition to compiling them@footnote{Much, if not most, of the
6478 information in the following sections pertaining to preprocessing
6479 Fortran 77 programs was taken almost verbatim from @ref{Catalogue of
6480 Rules, , Catalogue of Rules, make, The GNU Make Manual}.}. Automake
6481 also contains some support for creating programs and shared libraries
6482 that are a mixture of Fortran 77 and other languages (@pxref{Mixing
6483 Fortran 77 With C and C++}).
6485 These issues are covered in the following sections.
6488 * Preprocessing Fortran 77:: Preprocessing Fortran 77 sources
6489 * Compiling Fortran 77 Files:: Compiling Fortran 77 sources
6490 * Mixing Fortran 77 With C and C++:: Mixing Fortran 77 With C and C++
6494 @node Preprocessing Fortran 77
6495 @comment node-name, next, previous, up
6496 @subsection Preprocessing Fortran 77
6498 @cindex Preprocessing Fortran 77
6499 @cindex Fortran 77, Preprocessing
6500 @cindex Ratfor programs
6502 @file{N.f} is made automatically from @file{N.F} or @file{N.r}. This
6503 rule runs just the preprocessor to convert a preprocessable Fortran 77
6504 or Ratfor source file into a strict Fortran 77 source file. The precise
6505 command used is as follows:
6510 @code{$(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)@*
6511 $(AM_FFLAGS) $(FFLAGS)}
6514 @code{$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
6519 @node Compiling Fortran 77 Files
6520 @comment node-name, next, previous, up
6521 @subsection Compiling Fortran 77 Files
6523 @file{N.o} is made automatically from @file{N.f}, @file{N.F} or
6524 @file{N.r} by running the Fortran 77 compiler. The precise command used
6530 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS)}
6533 @code{$(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)@*
6534 $(AM_FFLAGS) $(FFLAGS)}
6537 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
6542 @node Mixing Fortran 77 With C and C++
6543 @comment node-name, next, previous, up
6544 @subsection Mixing Fortran 77 With C and C++
6546 @cindex Fortran 77, mixing with C and C++
6547 @cindex Mixing Fortran 77 with C and C++
6548 @cindex Linking Fortran 77 with C and C++
6550 @cindex Mixing Fortran 77 with C and/or C++
6552 Automake currently provides @emph{limited} support for creating programs
6553 and shared libraries that are a mixture of Fortran 77 and C and/or C++.
6554 However, there are many other issues related to mixing Fortran 77 with
6555 other languages that are @emph{not} (currently) handled by Automake, but
6556 that are handled by other packages@footnote{For example,
6557 @uref{http://www-zeus.desy.de/~burow/cfortran/, the cfortran package}
6558 addresses all of these inter-language issues, and runs under nearly all
6559 Fortran 77, C and C++ compilers on nearly all platforms. However,
6560 @command{cfortran} is not yet Free Software, but it will be in the next
6563 Automake can help in two ways:
6567 Automatic selection of the linker depending on which combinations of
6571 Automatic selection of the appropriate linker flags (e.g., @option{-L} and
6572 @option{-l}) to pass to the automatically selected linker in order to link
6573 in the appropriate Fortran 77 intrinsic and run-time libraries.
6575 @cindex @code{FLIBS}, defined
6577 These extra Fortran 77 linker flags are supplied in the output variable
6578 @code{FLIBS} by the @code{AC_F77_LIBRARY_LDFLAGS} Autoconf macro.
6579 @xref{Fortran Compiler, , Fortran Compiler Characteristics, autoconf,
6580 The Autoconf Manual}.
6583 If Automake detects that a program or shared library (as mentioned in
6584 some @code{_PROGRAMS} or @code{_LTLIBRARIES} primary) contains source
6585 code that is a mixture of Fortran 77 and C and/or C++, then it requires
6586 that the macro @code{AC_F77_LIBRARY_LDFLAGS} be called in
6587 @file{configure.ac}, and that either @code{$(FLIBS)}
6588 appear in the appropriate @code{_LDADD} (for programs) or @code{_LIBADD}
6589 (for shared libraries) variables. It is the responsibility of the
6590 person writing the @file{Makefile.am} to make sure that @samp{$(FLIBS)}
6591 appears in the appropriate @code{_LDADD} or
6592 @code{_LIBADD} variable.
6594 @cindex Mixed language example
6595 @cindex Example, mixed language
6597 For example, consider the following @file{Makefile.am}:
6601 foo_SOURCES = main.cc foo.f
6602 foo_LDADD = libfoo.la $(FLIBS)
6604 pkglib_LTLIBRARIES = libfoo.la
6605 libfoo_la_SOURCES = bar.f baz.c zardoz.cc
6606 libfoo_la_LIBADD = $(FLIBS)
6609 In this case, Automake will insist that @code{AC_F77_LIBRARY_LDFLAGS}
6610 is mentioned in @file{configure.ac}. Also, if @samp{$(FLIBS)} hadn't
6611 been mentioned in @code{foo_LDADD} and @code{libfoo_la_LIBADD}, then
6612 Automake would have issued a warning.
6615 * How the Linker is Chosen:: Automatic linker selection
6618 @node How the Linker is Chosen
6619 @comment node-name, next, previous, up
6620 @subsubsection How the Linker is Chosen
6622 @cindex Automatic linker selection
6623 @cindex Selecting the linker automatically
6625 When a program or library mixes several languages, Automake choose the
6626 linker according to the following priorities. (The names in
6627 parentheses are the variables containing the link command.)
6632 Native Java (@code{GCJLINK})
6635 Objective C++ (@code{OBJCXXLINK})
6638 C++ (@code{CXXLINK})
6641 Fortran 77 (@code{F77LINK})
6644 Fortran (@code{FCLINK})
6647 Objective C (@code{OBJCLINK})
6650 Unified Parallel C (@code{UPCLINK})
6656 For example, if Fortran 77, C and C++ source code is compiled
6657 into a program, then the C++ linker will be used. In this case, if the
6658 C or Fortran 77 linkers required any special libraries that weren't
6659 included by the C++ linker, then they must be manually added to an
6660 @code{_LDADD} or @code{_LIBADD} variable by the user writing the
6663 Automake only looks at the file names listed in @file{_SOURCES}
6664 variables to choose the linker, and defaults to the C linker.
6665 Sometimes this is inconvenient because you are linking against a
6666 library written in another language and would like to set the linker
6667 more appropriately. @xref{Libtool Convenience Libraries}, for a
6668 trick with @code{nodist_EXTRA_@dots{}_SOURCES}.
6670 A per-target @code{_LINK} variable will override the above selection.
6671 Per-target link flags will cause Automake to write a per-target
6672 @code{_LINK} variable according to the language chosen as above.
6675 @node Fortran 9x Support
6676 @comment node-name, next, previous, up
6677 @section Fortran 9x Support
6679 @cindex Fortran 9x support
6680 @cindex Support for Fortran 9x
6682 Automake includes support for Fortran 9x.
6684 Any package including Fortran 9x code must define the output variable
6685 @code{FC} in @file{configure.ac}; the simplest way to do this is to use
6686 the @code{AC_PROG_FC} macro (@pxref{Particular Programs, , Particular
6687 Program Checks, autoconf, The Autoconf Manual}).
6689 A few additional variables are defined when a Fortran 9x source file is
6695 The name of the Fortran 9x compiler.
6698 Any flags to pass to the Fortran 9x compiler.
6701 The maintainer's variant of @code{FCFLAGS}.
6704 The command used to actually compile a Fortran 9x source file. The file
6705 name is appended to form the complete command line.
6708 The command used to actually link a pure Fortran 9x program or shared
6714 * Compiling Fortran 9x Files:: Compiling Fortran 9x sources
6717 @node Compiling Fortran 9x Files
6718 @comment node-name, next, previous, up
6719 @subsection Compiling Fortran 9x Files
6721 @file{@var{file}.o} is made automatically from @file{@var{file}.f90},
6722 @file{@var{file}.f95}, @file{@var{file}.f03}, or @file{@var{file}.f08}
6723 by running the Fortran 9x compiler. The precise command used
6729 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f90) $<}
6732 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f95) $<}
6735 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f03) $<}
6738 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f08) $<}
6742 @node Java Support with gcj
6743 @comment node-name, next, previous, up
6744 @section Compiling Java sources using gcj
6746 @cindex Java support with gcj
6747 @cindex Support for Java with gcj
6748 @cindex Java to native code, compilation
6749 @cindex Compilation of Java to native code
6751 Automake includes support for natively compiled Java, using @command{gcj},
6752 the Java front end to the GNU Compiler Collection (rudimentary support
6753 for compiling Java to bytecode using the @command{javac} compiler is
6754 also present, @emph{albeit deprecated}; @pxref{Java}).
6756 Any package including Java code to be compiled must define the output
6757 variable @code{GCJ} in @file{configure.ac}; the variable @code{GCJFLAGS}
6758 must also be defined somehow (either in @file{configure.ac} or
6759 @file{Makefile.am}). The simplest way to do this is to use the
6760 @code{AM_PROG_GCJ} macro.
6764 By default, programs including Java source files are linked with
6767 As always, the contents of @code{AM_GCJFLAGS} are passed to every
6768 compilation invoking @command{gcj} (in its role as an ahead-of-time
6769 compiler, when invoking it to create @file{.class} files,
6770 @code{AM_JAVACFLAGS} is used instead). If it is necessary to pass
6771 options to @command{gcj} from @file{Makefile.am}, this variable, and not
6772 the user variable @code{GCJFLAGS}, should be used.
6776 @command{gcj} can be used to compile @file{.java}, @file{.class},
6777 @file{.zip}, or @file{.jar} files.
6779 When linking, @command{gcj} requires that the main class be specified
6780 using the @option{--main=} option. The easiest way to do this is to use
6781 the @code{_LDFLAGS} variable for the program.
6785 @comment node-name, next, previous, up
6786 @section Vala Support
6788 @cindex Vala Support
6789 @cindex Support for Vala
6791 Automake provides initial support for Vala
6792 (@uref{http://www.vala-project.org/}).
6793 This requires valac version 0.7.0 or later, and currently requires
6794 the user to use GNU @command{make}.
6797 foo_SOURCES = foo.vala bar.vala zardoc.c
6800 Any @file{.vala} file listed in a @code{_SOURCES} variable will be
6801 compiled into C code by the Vala compiler. The generated @file{.c} files are
6802 distributed. The end user does not need to have a Vala compiler installed.
6804 Automake ships with an Autoconf macro called @code{AM_PROG_VALAC}
6805 that will locate the Vala compiler and optionally check its version
6808 @defmac AM_PROG_VALAC (@ovar{minimum-version})
6809 Try to find a Vala compiler in @env{PATH}. If it is found, the variable
6810 @code{VALAC} is set. Optionally a minimum release number of the compiler
6814 AM_PROG_VALAC([0.7.0])
6818 There are a few variables that are used when compiling Vala sources:
6822 Path to the Vala compiler.
6825 Additional arguments for the Vala compiler.
6828 The maintainer's variant of @code{VALAFLAGS}.
6831 lib_LTLIBRARIES = libfoo.la
6832 libfoo_la_SOURCES = foo.vala
6836 Note that currently, you cannot use per-target @code{*_VALAFLAGS}
6837 (@pxref{Renamed Objects}) to produce different C files from one Vala
6841 @node Support for Other Languages
6842 @comment node-name, next, previous, up
6843 @section Support for Other Languages
6845 Automake currently only includes full support for C, C++ (@pxref{C++
6846 Support}), Objective C (@pxref{Objective C Support}),
6847 Objective C++ (@pxref{Objective C++ Support}),
6849 (@pxref{Fortran 77 Support}), Fortran 9x (@pxref{Fortran 9x Support}),
6850 and Java (@pxref{Java Support with gcj}). There is only rudimentary
6851 support for other languages, support for which will be improved based
6854 Some limited support for adding your own languages is available via the
6855 suffix rule handling (@pxref{Suffixes}).
6858 @section Automatic dependency tracking
6860 As a developer it is often painful to continually update the
6861 @file{Makefile.am} whenever the include-file dependencies change in a
6862 project. Automake supplies a way to automatically track dependency
6863 changes (@pxref{Dependency Tracking}).
6865 @cindex Dependency tracking
6866 @cindex Automatic dependency tracking
6868 Automake always uses complete dependencies for a compilation,
6869 including system headers. Automake's model is that dependency
6870 computation should be a side effect of the build. To this end,
6871 dependencies are computed by running all compilations through a
6872 special wrapper program called @command{depcomp}. @command{depcomp}
6873 understands how to coax many different C and C++ compilers into
6874 generating dependency information in the format it requires.
6875 @samp{automake -a} will install @command{depcomp} into your source
6876 tree for you. If @command{depcomp} can't figure out how to properly
6877 invoke your compiler, dependency tracking will simply be disabled for
6880 @cindex @command{depcomp}
6882 Experience with earlier versions of Automake (@pxref{Dependency Tracking
6883 Evolution, , Dependency Tracking Evolution, automake-history, Brief History
6884 of Automake}) taught us that it is not reliable to generate dependencies
6885 only on the maintainer's system, as configurations vary too much. So
6886 instead Automake implements dependency tracking at build time.
6888 Automatic dependency tracking can be suppressed by putting
6889 @option{no-dependencies} in the variable @code{AUTOMAKE_OPTIONS}, or
6890 passing @option{no-dependencies} as an argument to @code{AM_INIT_AUTOMAKE}
6891 (this should be the preferred way). Or, you can invoke @command{automake}
6892 with the @option{-i} option. Dependency tracking is enabled by default.
6894 @vindex AUTOMAKE_OPTIONS
6895 @opindex no-dependencies
6897 The person building your package also can choose to disable dependency
6898 tracking by configuring with @option{--disable-dependency-tracking}.
6900 @cindex Disabling dependency tracking
6901 @cindex Dependency tracking, disabling
6905 @section Support for executable extensions
6907 @cindex Executable extension
6908 @cindex Extension, executable
6911 On some platforms, such as Windows, executables are expected to have an
6912 extension such as @file{.exe}. On these platforms, some compilers (GCC
6913 among them) will automatically generate @file{foo.exe} when asked to
6914 generate @file{foo}.
6916 Automake provides mostly-transparent support for this. Unfortunately
6917 @emph{mostly} doesn't yet mean @emph{fully}. Until the English
6918 dictionary is revised, you will have to assist Automake if your package
6919 must support those platforms.
6921 One thing you must be aware of is that, internally, Automake rewrites
6922 something like this:
6925 bin_PROGRAMS = liver
6931 bin_PROGRAMS = liver$(EXEEXT)
6934 The targets Automake generates are likewise given the @samp{$(EXEEXT)}
6937 The variables @code{TESTS} and @code{XFAIL_TESTS} (@pxref{Simple Tests})
6938 are also rewritten if they contain filenames that have been declared as
6939 programs in the same @file{Makefile}. (This is mostly useful when some
6940 programs from @code{check_PROGRAMS} are listed in @code{TESTS}.)
6942 However, Automake cannot apply this rewriting to @command{configure}
6943 substitutions. This means that if you are conditionally building a
6944 program using such a substitution, then your @file{configure.ac} must
6945 take care to add @samp{$(EXEEXT)} when constructing the output variable.
6947 Sometimes maintainers like to write an explicit link rule for their
6948 program. Without executable extension support, this is easy---you
6949 simply write a rule whose target is the name of the program. However,
6950 when executable extension support is enabled, you must instead add the
6951 @samp{$(EXEEXT)} suffix.
6953 This might be a nuisance for maintainers who know their package will
6954 never run on a platform that has
6955 executable extensions. For those maintainers, the @option{no-exeext}
6956 option (@pxref{Options}) will disable this feature. This works in a
6957 fairly ugly way; if @option{no-exeext} is seen, then the presence of a
6958 rule for a target named @code{foo} in @file{Makefile.am} will override
6959 an @command{automake}-generated rule for @samp{foo$(EXEEXT)}. Without
6960 the @option{no-exeext} option, this use will give a diagnostic.
6964 @chapter Other Derived Objects
6966 Automake can handle derived objects that are not C programs. Sometimes
6967 the support for actually building such objects must be explicitly
6968 supplied, but Automake will still automatically handle installation and
6972 * Scripts:: Executable scripts
6973 * Headers:: Header files
6974 * Data:: Architecture-independent data files
6975 * Sources:: Derived sources
6980 @section Executable Scripts
6982 @cindex @code{_SCRIPTS} primary, defined
6983 @cindex @code{SCRIPTS} primary, defined
6984 @cindex Primary variable, @code{SCRIPTS}
6986 @cindex Installing scripts
6988 It is possible to define and install programs that are scripts. Such
6989 programs are listed using the @code{SCRIPTS} primary name. When the
6990 script is distributed in its final, installable form, the
6991 @file{Makefile} usually looks as follows:
6995 # Install my_script in $(bindir) and distribute it.
6996 dist_bin_SCRIPTS = my_script
6999 Scripts are not distributed by default; as we have just seen, those
7000 that should be distributed can be specified using a @code{dist_}
7001 prefix as with other primaries.
7003 @cindex @code{SCRIPTS}, installation directories
7005 @vindex sbin_SCRIPTS
7006 @vindex libexec_SCRIPTS
7007 @vindex pkgdata_SCRIPTS
7008 @vindex pkglibexec_SCRIPTS
7009 @vindex noinst_SCRIPTS
7010 @vindex check_SCRIPTS
7012 Scripts can be installed in @code{bindir}, @code{sbindir},
7013 @code{libexecdir}, @code{pkglibexecdir}, or @code{pkgdatadir}.
7015 Scripts that need not be installed can be listed in
7016 @code{noinst_SCRIPTS}, and among them, those which are needed only by
7017 @samp{make check} should go in @code{check_SCRIPTS}.
7019 When a script needs to be built, the @file{Makefile.am} should include
7020 the appropriate rules. For instance the @command{automake} program
7021 itself is a Perl script that is generated from @file{automake.in}.
7022 Here is how this is handled:
7025 bin_SCRIPTS = automake
7026 CLEANFILES = $(bin_SCRIPTS)
7027 EXTRA_DIST = automake.in
7029 do_subst = sed -e 's,[@@]datadir[@@],$(datadir),g' \
7030 -e 's,[@@]PERL[@@],$(PERL),g' \
7031 -e 's,[@@]PACKAGE[@@],$(PACKAGE),g' \
7032 -e 's,[@@]VERSION[@@],$(VERSION),g' \
7035 automake: automake.in Makefile
7036 $(do_subst) < $(srcdir)/automake.in > automake
7040 Such scripts for which a build rule has been supplied need to be
7041 deleted explicitly using @code{CLEANFILES} (@pxref{Clean}), and their
7042 sources have to be distributed, usually with @code{EXTRA_DIST}
7043 (@pxref{Basics of Distribution}).
7045 Another common way to build scripts is to process them from
7046 @file{configure} with @code{AC_CONFIG_FILES}. In this situation
7047 Automake knows which files should be cleaned and distributed, and what
7048 the rebuild rules should look like.
7050 For instance if @file{configure.ac} contains
7053 AC_CONFIG_FILES([src/my_script], [chmod +x src/my_script])
7057 to build @file{src/my_script} from @file{src/my_script.in}, then a
7058 @file{src/Makefile.am} to install this script in @code{$(bindir)} can
7062 bin_SCRIPTS = my_script
7063 CLEANFILES = $(bin_SCRIPTS)
7067 There is no need for @code{EXTRA_DIST} or any build rule: Automake
7068 infers them from @code{AC_CONFIG_FILES} (@pxref{Requirements}).
7069 @code{CLEANFILES} is still useful, because by default Automake will
7070 clean targets of @code{AC_CONFIG_FILES} in @code{distclean}, not
7073 Although this looks simpler, building scripts this way has one
7074 drawback: directory variables such as @code{$(datadir)} are not fully
7075 expanded and may refer to other directory variables.
7078 @section Header files
7080 @cindex @code{_HEADERS} primary, defined
7081 @cindex @code{HEADERS} primary, defined
7082 @cindex Primary variable, @code{HEADERS}
7084 @vindex noinst_HEADERS
7085 @cindex @code{HEADERS}, installation directories
7086 @cindex Installing headers
7087 @vindex include_HEADERS
7088 @vindex oldinclude_HEADERS
7089 @vindex pkginclude_HEADERS
7092 Header files that must be installed are specified by the
7093 @code{HEADERS} family of variables. Headers can be installed in
7094 @code{includedir}, @code{oldincludedir}, @code{pkgincludedir} or any
7095 other directory you may have defined (@pxref{Uniform}). For instance,
7098 include_HEADERS = foo.h bar/bar.h
7102 will install the two files as @file{$(includedir)/foo.h} and
7103 @file{$(includedir)/bar.h}.
7105 The @code{nobase_} prefix is also supported,
7108 nobase_include_HEADERS = foo.h bar/bar.h
7112 will install the two files as @file{$(includedir)/foo.h} and
7113 @file{$(includedir)/bar/bar.h} (@pxref{Alternative}).
7115 @vindex noinst_HEADERS
7116 Usually, only header files that accompany installed libraries need to
7117 be installed. Headers used by programs or convenience libraries are
7118 not installed. The @code{noinst_HEADERS} variable can be used for
7119 such headers. However when the header actually belongs to a single
7120 convenience library or program, we recommend listing it in the
7121 program's or library's @code{_SOURCES} variable (@pxref{Program
7122 Sources}) instead of in @code{noinst_HEADERS}. This is clearer for
7123 the @file{Makefile.am} reader. @code{noinst_HEADERS} would be the
7124 right variable to use in a directory containing only headers and no
7125 associated library or program.
7127 All header files must be listed somewhere; in a @code{_SOURCES}
7128 variable or in a @code{_HEADERS} variable. Missing ones will not
7129 appear in the distribution.
7131 For header files that are built and must not be distributed, use the
7132 @code{nodist_} prefix as in @code{nodist_include_HEADERS} or
7133 @code{nodist_prog_SOURCES}. If these generated headers are needed
7134 during the build, you must also ensure they exist before they are
7135 used (@pxref{Sources}).
7139 @section Architecture-independent data files
7141 @cindex @code{_DATA} primary, defined
7142 @cindex @code{DATA} primary, defined
7143 @cindex Primary variable, @code{DATA}
7146 Automake supports the installation of miscellaneous data files using the
7147 @code{DATA} family of variables.
7151 @vindex sysconf_DATA
7152 @vindex sharedstate_DATA
7153 @vindex localstate_DATA
7154 @vindex pkgdata_DATA
7156 Such data can be installed in the directories @code{datadir},
7157 @code{sysconfdir}, @code{sharedstatedir}, @code{localstatedir}, or
7160 By default, data files are @emph{not} included in a distribution. Of
7161 course, you can use the @code{dist_} prefix to change this on a
7164 Here is how Automake declares its auxiliary data files:
7167 dist_pkgdata_DATA = clean-kr.am clean.am @dots{}
7172 @section Built Sources
7174 Because Automake's automatic dependency tracking works as a side-effect
7175 of compilation (@pxref{Dependencies}) there is a bootstrap issue: a
7176 target should not be compiled before its dependencies are made, but
7177 these dependencies are unknown until the target is first compiled.
7179 Ordinarily this is not a problem, because dependencies are distributed
7180 sources: they preexist and do not need to be built. Suppose that
7181 @file{foo.c} includes @file{foo.h}. When it first compiles
7182 @file{foo.o}, @command{make} only knows that @file{foo.o} depends on
7183 @file{foo.c}. As a side-effect of this compilation @command{depcomp}
7184 records the @file{foo.h} dependency so that following invocations of
7185 @command{make} will honor it. In these conditions, it's clear there is
7186 no problem: either @file{foo.o} doesn't exist and has to be built
7187 (regardless of the dependencies), or accurate dependencies exist and
7188 they can be used to decide whether @file{foo.o} should be rebuilt.
7190 It's a different story if @file{foo.h} doesn't exist by the first
7191 @command{make} run. For instance, there might be a rule to build
7192 @file{foo.h}. This time @file{file.o}'s build will fail because the
7193 compiler can't find @file{foo.h}. @command{make} failed to trigger the
7194 rule to build @file{foo.h} first by lack of dependency information.
7196 @vindex BUILT_SOURCES
7197 @cindex @code{BUILT_SOURCES}, defined
7199 The @code{BUILT_SOURCES} variable is a workaround for this problem. A
7200 source file listed in @code{BUILT_SOURCES} is made on @samp{make all}
7201 or @samp{make check} (or even @samp{make install}) before other
7202 targets are processed. However, such a source file is not
7203 @emph{compiled} unless explicitly requested by mentioning it in some
7204 other @code{_SOURCES} variable.
7206 So, to conclude our introductory example, we could use
7207 @samp{BUILT_SOURCES = foo.h} to ensure @file{foo.h} gets built before
7208 any other target (including @file{foo.o}) during @samp{make all} or
7211 @code{BUILT_SOURCES} is actually a bit of a misnomer, as any file which
7212 must be created early in the build process can be listed in this
7213 variable. Moreover, all built sources do not necessarily have to be
7214 listed in @code{BUILT_SOURCES}. For instance, a generated @file{.c} file
7215 doesn't need to appear in @code{BUILT_SOURCES} (unless it is included by
7216 another source), because it's a known dependency of the associated
7219 It might be important to emphasize that @code{BUILT_SOURCES} is
7220 honored only by @samp{make all}, @samp{make check} and @samp{make
7221 install}. This means you cannot build a specific target (e.g.,
7222 @samp{make foo}) in a clean tree if it depends on a built source.
7223 However it will succeed if you have run @samp{make all} earlier,
7224 because accurate dependencies are already available.
7226 The next section illustrates and discusses the handling of built sources
7230 * Built Sources Example:: Several ways to handle built sources.
7233 @node Built Sources Example
7234 @subsection Built Sources Example
7236 Suppose that @file{foo.c} includes @file{bindir.h}, which is
7237 installation-dependent and not distributed: it needs to be built. Here
7238 @file{bindir.h} defines the preprocessor macro @code{bindir} to the
7239 value of the @command{make} variable @code{bindir} (inherited from
7242 We suggest several implementations below. It's not meant to be an
7243 exhaustive listing of all ways to handle built sources, but it will give
7244 you a few ideas if you encounter this issue.
7246 @subsubheading First Try
7248 This first implementation will illustrate the bootstrap issue mentioned
7249 in the previous section (@pxref{Sources}).
7251 Here is a tentative @file{Makefile.am}.
7257 nodist_foo_SOURCES = bindir.h
7258 CLEANFILES = bindir.h
7260 echo '#define bindir "$(bindir)"' >$@@
7263 This setup doesn't work, because Automake doesn't know that @file{foo.c}
7264 includes @file{bindir.h}. Remember, automatic dependency tracking works
7265 as a side-effect of compilation, so the dependencies of @file{foo.o} will
7266 be known only after @file{foo.o} has been compiled (@pxref{Dependencies}).
7267 The symptom is as follows.
7271 source='foo.c' object='foo.o' libtool=no \
7272 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
7273 depmode=gcc /bin/sh ./depcomp \
7274 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
7275 foo.c:2: bindir.h: No such file or directory
7276 make: *** [foo.o] Error 1
7279 In this example @file{bindir.h} is not distributed nor installed, and
7280 it is not even being built on-time. One may wonder if the
7281 @samp{nodist_foo_SOURCES = bindir.h} line has any use at all. This
7282 line simply states that @file{bindir.h} is a source of @code{foo}, so
7283 for instance, it should be inspected while generating tags
7284 (@pxref{Tags}). In other words, it does not help our present problem,
7285 and the build would fail identically without it.
7287 @subsubheading Using @code{BUILT_SOURCES}
7289 A solution is to require @file{bindir.h} to be built before anything
7290 else. This is what @code{BUILT_SOURCES} is meant for (@pxref{Sources}).
7295 nodist_foo_SOURCES = bindir.h
7296 BUILT_SOURCES = bindir.h
7297 CLEANFILES = bindir.h
7299 echo '#define bindir "$(bindir)"' >$@@
7302 See how @file{bindir.h} gets built first:
7306 echo '#define bindir "/usr/local/bin"' >bindir.h
7308 make[1]: Entering directory `/home/adl/tmp'
7309 source='foo.c' object='foo.o' libtool=no \
7310 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
7311 depmode=gcc /bin/sh ./depcomp \
7312 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
7313 gcc -g -O2 -o foo foo.o
7314 make[1]: Leaving directory `/home/adl/tmp'
7317 However, as said earlier, @code{BUILT_SOURCES} applies only to the
7318 @code{all}, @code{check}, and @code{install} targets. It still fails
7319 if you try to run @samp{make foo} explicitly:
7323 test -z "bindir.h" || rm -f bindir.h
7324 test -z "foo" || rm -f foo
7326 % : > .deps/foo.Po # Suppress previously recorded dependencies
7328 source='foo.c' object='foo.o' libtool=no \
7329 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
7330 depmode=gcc /bin/sh ./depcomp \
7331 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
7332 foo.c:2: bindir.h: No such file or directory
7333 make: *** [foo.o] Error 1
7336 @subsubheading Recording Dependencies manually
7338 Usually people are happy enough with @code{BUILT_SOURCES} because they
7339 never build targets such as @samp{make foo} before @samp{make all}, as
7340 in the previous example. However if this matters to you, you can
7341 avoid @code{BUILT_SOURCES} and record such dependencies explicitly in
7342 the @file{Makefile.am}.
7347 nodist_foo_SOURCES = bindir.h
7348 foo.$(OBJEXT): bindir.h
7349 CLEANFILES = bindir.h
7351 echo '#define bindir "$(bindir)"' >$@@
7354 You don't have to list @emph{all} the dependencies of @file{foo.o}
7355 explicitly, only those that might need to be built. If a dependency
7356 already exists, it will not hinder the first compilation and will be
7357 recorded by the normal dependency tracking code. (Note that after
7358 this first compilation the dependency tracking code will also have
7359 recorded the dependency between @file{foo.o} and
7360 @file{bindir.h}; so our explicit dependency is really useful to
7361 the first build only.)
7363 Adding explicit dependencies like this can be a bit dangerous if you are
7364 not careful enough. This is due to the way Automake tries not to
7365 overwrite your rules (it assumes you know better than it).
7366 @samp{foo.$(OBJEXT): bindir.h} supersedes any rule Automake may want to
7367 output to build @samp{foo.$(OBJEXT)}. It happens to work in this case
7368 because Automake doesn't have to output any @samp{foo.$(OBJEXT):}
7369 target: it relies on a suffix rule instead (i.e., @samp{.c.$(OBJEXT):}).
7370 Always check the generated @file{Makefile.in} if you do this.
7372 @subsubheading Build @file{bindir.h} from @file{configure}
7374 It's possible to define this preprocessor macro from @file{configure},
7375 either in @file{config.h} (@pxref{Defining Directories, , Defining
7376 Directories, autoconf, The Autoconf Manual}), or by processing a
7377 @file{bindir.h.in} file using @code{AC_CONFIG_FILES}
7378 (@pxref{Configuration Actions, ,Configuration Actions, autoconf, The
7381 At this point it should be clear that building @file{bindir.h} from
7382 @file{configure} works well for this example. @file{bindir.h} will exist
7383 before you build any target, hence will not cause any dependency issue.
7385 The Makefile can be shrunk as follows. We do not even have to mention
7393 However, it's not always possible to build sources from
7394 @file{configure}, especially when these sources are generated by a tool
7395 that needs to be built first.
7397 @subsubheading Build @file{bindir.c}, not @file{bindir.h}.
7399 Another attractive idea is to define @code{bindir} as a variable or
7400 function exported from @file{bindir.o}, and build @file{bindir.c}
7401 instead of @file{bindir.h}.
7404 noinst_PROGRAMS = foo
7405 foo_SOURCES = foo.c bindir.h
7406 nodist_foo_SOURCES = bindir.c
7407 CLEANFILES = bindir.c
7409 echo 'const char bindir[] = "$(bindir)";' >$@@
7412 @file{bindir.h} contains just the variable's declaration and doesn't
7413 need to be built, so it won't cause any trouble. @file{bindir.o} is
7414 always dependent on @file{bindir.c}, so @file{bindir.c} will get built
7417 @subsubheading Which is best?
7419 There is no panacea, of course. Each solution has its merits and
7422 You cannot use @code{BUILT_SOURCES} if the ability to run @samp{make
7423 foo} on a clean tree is important to you.
7425 You won't add explicit dependencies if you are leery of overriding
7426 an Automake rule by mistake.
7428 Building files from @file{./configure} is not always possible, neither
7429 is converting @file{.h} files into @file{.c} files.
7432 @node Other GNU Tools
7433 @chapter Other GNU Tools
7435 Since Automake is primarily intended to generate @file{Makefile.in}s for
7436 use in GNU programs, it tries hard to interoperate with other GNU tools.
7439 * Emacs Lisp:: Emacs Lisp
7442 * Java:: Java bytecode compilation (deprecated)
7450 @cindex @code{_LISP} primary, defined
7451 @cindex @code{LISP} primary, defined
7452 @cindex Primary variable, @code{LISP}
7458 Automake provides some support for Emacs Lisp. The @code{LISP} primary
7459 is used to hold a list of @file{.el} files. Possible prefixes for this
7460 primary are @code{lisp_} and @code{noinst_}. Note that if
7461 @code{lisp_LISP} is defined, then @file{configure.ac} must run
7462 @code{AM_PATH_LISPDIR} (@pxref{Macros}).
7464 @vindex dist_lisp_LISP
7465 @vindex dist_noinst_LISP
7466 Lisp sources are not distributed by default. You can prefix the
7467 @code{LISP} primary with @code{dist_}, as in @code{dist_lisp_LISP} or
7468 @code{dist_noinst_LISP}, to indicate that these files should be
7471 Automake will byte-compile all Emacs Lisp source files using the Emacs
7472 found by @code{AM_PATH_LISPDIR}, if any was found. When performing such
7473 byte-compilation, the flags specified in the (developer-reserved)
7474 @code{AM_ELCFLAGS} and (user-reserved) @code{ELCFLAGS} make variables
7475 will be passed to the Emacs invocation.
7477 Byte-compiled Emacs Lisp files are not portable among all versions of
7478 Emacs, so it makes sense to turn this off if you expect sites to have
7479 more than one version of Emacs installed. Furthermore, many packages
7480 don't actually benefit from byte-compilation. Still, we recommend
7481 that you byte-compile your Emacs Lisp sources. It is probably better
7482 for sites with strange setups to cope for themselves than to make the
7483 installation less nice for everybody else.
7485 There are two ways to avoid byte-compiling. Historically, we have
7486 recommended the following construct.
7489 lisp_LISP = file1.el file2.el
7494 @code{ELCFILES} is an internal Automake variable that normally lists
7495 all @file{.elc} files that must be byte-compiled. Automake defines
7496 @code{ELCFILES} automatically from @code{lisp_LISP}. Emptying this
7497 variable explicitly prevents byte-compilation.
7499 Since Automake 1.8, we now recommend using @code{lisp_DATA} instead:
7501 @c Keep in sync with primary-prefix-couples-documented-valid.sh
7503 lisp_DATA = file1.el file2.el
7506 Note that these two constructs are not equivalent. @code{_LISP} will
7507 not install a file if Emacs is not installed, while @code{_DATA} will
7508 always install its files.
7513 @cindex GNU Gettext support
7514 @cindex Gettext support
7515 @cindex Support for GNU Gettext
7517 If @code{AM_GNU_GETTEXT} is seen in @file{configure.ac}, then Automake
7518 turns on support for GNU gettext, a message catalog system for
7519 internationalization
7520 (@pxref{Top, , Introduction, gettext, GNU gettext utilities}).
7522 The @code{gettext} support in Automake requires the addition of one or
7523 two subdirectories to the package: @file{po} and possibly also @file{intl}.
7524 The latter is needed if @code{AM_GNU_GETTEXT} is not invoked with the
7525 @samp{external} argument, or if @code{AM_GNU_GETTEXT_INTL_SUBDIR} is used.
7526 Automake ensures that these directories exist and are mentioned in
7532 Automake provides support for GNU Libtool (@pxref{Top, , Introduction,
7533 libtool, The Libtool Manual}) with the @code{LTLIBRARIES} primary.
7534 @xref{A Shared Library}.
7538 @section Java bytecode compilation (deprecated)
7540 @cindex @code{_JAVA} primary, defined
7541 @cindex @code{JAVA} primary, defined
7542 @cindex Primary variable, @code{JAVA}
7543 @cindex Java to bytecode, compilation
7544 @cindex Compilation of Java to bytecode
7546 Automake provides some minimal support for Java bytecode compilation with
7547 the @code{JAVA} primary (in addition to the support for compiling Java to
7548 native machine code; @pxref{Java Support with gcj}). Note however that
7549 @emph{the interface and most features described here are deprecated}; the
7550 next automake release will strive to provide a better and cleaner
7551 interface, which however @emph{won't be backward-compatible}; the present
7552 interface will probably be removed altogether in future automake releases
7553 (1.13 or later), so don't use it in new code.
7555 Any @file{.java} files listed in a @code{_JAVA} variable will be
7556 compiled with @code{JAVAC} at build time. By default, @file{.java}
7557 files are not included in the distribution, you should use the
7558 @code{dist_} prefix to distribute them.
7560 Here is a typical setup for distributing @file{.java} files and
7561 installing the @file{.class} files resulting from their compilation.
7563 @c Keep in sync with primary-prefix-couples-documented-valid.sh
7565 javadir = $(datadir)/java
7566 dist_java_JAVA = a.java b.java @dots{}
7569 @cindex @code{JAVA} restrictions
7570 @cindex Restrictions for @code{JAVA}
7572 Currently Automake enforces the restriction that only one @code{_JAVA}
7573 primary can be used in a given @file{Makefile.am}. The reason for this
7574 restriction is that, in general, it isn't possible to know which
7575 @file{.class} files were generated from which @file{.java} files, so
7576 it would be impossible to know which files to install where. For
7577 instance, a @file{.java} file can define multiple classes; the resulting
7578 @file{.class} file names cannot be predicted without parsing the
7581 There are a few variables that are used when compiling Java sources:
7585 The name of the Java compiler. This defaults to @samp{javac}.
7588 The flags to pass to the compiler. This is considered to be a user
7589 variable (@pxref{User Variables}).
7592 More flags to pass to the Java compiler. This, and not
7593 @code{JAVACFLAGS}, should be used when it is necessary to put Java
7594 compiler flags into @file{Makefile.am}.
7597 The value of this variable is passed to the @option{-d} option to
7598 @code{javac}. It defaults to @samp{$(top_builddir)}.
7601 This variable is a shell expression that is used to set the
7602 @env{CLASSPATH} environment variable on the @code{javac} command line.
7603 (In the future we will probably handle class path setting differently.)
7610 @cindex @code{_PYTHON} primary, defined
7611 @cindex @code{PYTHON} primary, defined
7612 @cindex Primary variable, @code{PYTHON}
7615 Automake provides support for Python compilation with the
7616 @code{PYTHON} primary. A typical setup is to call
7617 @code{AM_PATH_PYTHON} in @file{configure.ac} and use a line like the
7618 following in @file{Makefile.am}:
7621 python_PYTHON = tree.py leave.py
7624 Any files listed in a @code{_PYTHON} variable will be byte-compiled
7625 with @command{py-compile} at install time. @command{py-compile}
7626 actually creates both standard (@file{.pyc}) and optimized
7627 (@file{.pyo}) byte-compiled versions of the source files. Note that
7628 because byte-compilation occurs at install time, any files listed in
7629 @code{noinst_PYTHON} will not be compiled. Python source files are
7630 included in the distribution by default, prepend @code{nodist_} (as in
7631 @code{nodist_python_PYTHON}) to omit them.
7633 Automake ships with an Autoconf macro called @code{AM_PATH_PYTHON}
7634 that will determine some Python-related directory variables (see
7635 below). If you have called @code{AM_PATH_PYTHON} from
7636 @file{configure.ac}, then you may use the variables
7637 @c Keep in sync with primary-prefix-couples-documented-valid.sh
7638 @code{python_PYTHON} or @code{pkgpython_PYTHON} to list Python source
7639 files in your @file{Makefile.am}, depending on where you want your files
7640 installed (see the definitions of @code{pythondir} and
7641 @code{pkgpythondir} below).
7643 @defmac AM_PATH_PYTHON (@ovar{version}, @ovar{action-if-found},
7644 @ovar{action-if-not-found})
7646 Search for a Python interpreter on the system. This macro takes three
7647 optional arguments. The first argument, if present, is the minimum
7648 version of Python required for this package: @code{AM_PATH_PYTHON}
7649 will skip any Python interpreter that is older than @var{version}.
7650 If an interpreter is found and satisfies @var{version}, then
7651 @var{action-if-found} is run. Otherwise, @var{action-if-not-found} is
7654 If @var{action-if-not-found} is not specified, as in the following
7655 example, the default is to abort @command{configure}.
7658 AM_PATH_PYTHON([2.2])
7662 This is fine when Python is an absolute requirement for the package.
7663 If Python >= 2.5 was only @emph{optional} to the package,
7664 @code{AM_PATH_PYTHON} could be called as follows.
7667 AM_PATH_PYTHON([2.5],, [:])
7670 If the @env{PYTHON} variable is set when @code{AM_PATH_PYTHON} is
7671 called, then that will be the only Python interpreter that is tried.
7673 @code{AM_PATH_PYTHON} creates the following output variables based on
7674 the Python installation found during configuration.
7679 The name of the Python executable, or @samp{:} if no suitable
7680 interpreter could be found.
7682 Assuming @var{action-if-not-found} is used (otherwise @file{./configure}
7683 will abort if Python is absent), the value of @code{PYTHON} can be used
7684 to setup a conditional in order to disable the relevant part of a build
7688 AM_PATH_PYTHON(,, [:])
7689 AM_CONDITIONAL([HAVE_PYTHON], [test "$PYTHON" != :])
7692 @item PYTHON_VERSION
7693 The Python version number, in the form @var{major}.@var{minor}
7694 (e.g., @samp{2.5}). This is currently the value of
7695 @samp{sys.version[:3]}.
7698 The string @samp{$@{prefix@}}. This term may be used in future work
7699 that needs the contents of Python's @samp{sys.prefix}, but general
7700 consensus is to always use the value from @command{configure}.
7702 @item PYTHON_EXEC_PREFIX
7703 The string @samp{$@{exec_prefix@}}. This term may be used in future work
7704 that needs the contents of Python's @samp{sys.exec_prefix}, but general
7705 consensus is to always use the value from @command{configure}.
7707 @item PYTHON_PLATFORM
7708 The canonical name used by Python to describe the operating system, as
7709 given by @samp{sys.platform}. This value is sometimes needed when
7710 building Python extensions.
7713 The directory name for the @file{site-packages} subdirectory of the
7714 standard Python install tree.
7717 This is the directory under @code{pythondir} that is named after the
7718 package. That is, it is @samp{$(pythondir)/$(PACKAGE)}. It is provided
7722 This is the directory where Python extension modules (shared libraries)
7723 should be installed. An extension module written in C could be declared
7724 as follows to Automake:
7726 @c Keep in sync with primary-prefix-couples-documented-valid.sh
7728 pyexec_LTLIBRARIES = quaternion.la
7729 quaternion_la_SOURCES = quaternion.c support.c support.h
7730 quaternion_la_LDFLAGS = -avoid-version -module
7734 This is a convenience variable that is defined as
7735 @samp{$(pyexecdir)/$(PACKAGE)}.
7738 All of these directory variables have values that start with either
7739 @samp{$@{prefix@}} or @samp{$@{exec_prefix@}} unexpanded. This works
7740 fine in @file{Makefiles}, but it makes these variables hard to use in
7741 @file{configure}. This is mandated by the GNU coding standards, so
7742 that the user can run @samp{make prefix=/foo install}. The Autoconf
7743 manual has a section with more details on this topic
7744 (@pxref{Installation Directory Variables, , Installation Directory
7745 Variables, autoconf, The Autoconf Manual}). See also @ref{Hard-Coded
7750 @chapter Building documentation
7752 Currently Automake provides support for Texinfo and man pages.
7756 * Man Pages:: Man pages
7763 @cindex @code{_TEXINFOS} primary, defined
7764 @cindex @code{TEXINFOS} primary, defined
7765 @cindex Primary variable, @code{TEXINFOS}
7766 @cindex HTML output using Texinfo
7767 @cindex PDF output using Texinfo
7768 @cindex PS output using Texinfo
7769 @cindex DVI output using Texinfo
7771 @vindex info_TEXINFOS
7773 If the current directory contains Texinfo source, you must declare it
7774 with the @code{TEXINFOS} primary. Generally Texinfo files are converted
7775 into info, and thus the @code{info_TEXINFOS} variable is most commonly used
7776 here. Any Texinfo source file must end in the @file{.texi},
7777 @file{.txi}, or @file{.texinfo} extension. We recommend @file{.texi}
7780 Automake generates rules to build @file{.info}, @file{.dvi},
7781 @file{.ps}, @file{.pdf} and @file{.html} files from your Texinfo
7782 sources. Following the GNU Coding Standards, only the @file{.info}
7783 files are built by @samp{make all} and installed by @samp{make
7784 install} (unless you use @option{no-installinfo}, see below).
7785 Furthermore, @file{.info} files are automatically distributed so that
7786 Texinfo is not a prerequisite for installing your package.
7792 @trindex install-dvi
7793 @trindex install-html
7794 @trindex install-pdf
7796 Other documentation formats can be built on request by @samp{make
7797 dvi}, @samp{make ps}, @samp{make pdf} and @samp{make html}, and they
7798 can be installed with @samp{make install-dvi}, @samp{make install-ps},
7799 @samp{make install-pdf} and @samp{make install-html} explicitly.
7800 @samp{make uninstall} will remove everything: the Texinfo
7801 documentation installed by default as well as all the above optional
7804 All of these targets can be extended using @samp{-local} rules
7805 (@pxref{Extending}).
7807 @cindex Texinfo flag, @code{VERSION}
7808 @cindex Texinfo flag, @code{UPDATED}
7809 @cindex Texinfo flag, @code{EDITION}
7810 @cindex Texinfo flag, @code{UPDATED-MONTH}
7812 @cindex @code{VERSION} Texinfo flag
7813 @cindex @code{UPDATED} Texinfo flag
7814 @cindex @code{EDITION} Texinfo flag
7815 @cindex @code{UPDATED-MONTH} Texinfo flag
7817 @cindex @file{mdate-sh}
7819 If the @file{.texi} file @code{@@include}s @file{version.texi}, then
7820 that file will be automatically generated. The file @file{version.texi}
7821 defines four Texinfo flag you can reference using
7822 @code{@@value@{EDITION@}}, @code{@@value@{VERSION@}},
7823 @code{@@value@{UPDATED@}}, and @code{@@value@{UPDATED-MONTH@}}.
7828 Both of these flags hold the version number of your program. They are
7829 kept separate for clarity.
7832 This holds the date the primary @file{.texi} file was last modified.
7835 This holds the name of the month in which the primary @file{.texi} file
7839 The @file{version.texi} support requires the @command{mdate-sh}
7840 script; this script is supplied with Automake and automatically
7841 included when @command{automake} is invoked with the
7842 @option{--add-missing} option.
7844 If you have multiple Texinfo files, and you want to use the
7845 @file{version.texi} feature, then you have to have a separate version
7846 file for each Texinfo file. Automake will treat any include in a
7847 Texinfo file that matches @file{vers*.texi} just as an automatically
7848 generated version file.
7850 Sometimes an info file actually depends on more than one @file{.texi}
7851 file. For instance, in GNU Hello, @file{hello.texi} includes the file
7852 @file{fdl.texi}. You can tell Automake about these dependencies using
7853 the @code{@var{texi}_TEXINFOS} variable. Here is how GNU Hello does it:
7858 info_TEXINFOS = hello.texi
7859 hello_TEXINFOS = fdl.texi
7862 @cindex @file{texinfo.tex}
7864 By default, Automake requires the file @file{texinfo.tex} to appear in
7865 the same directory as the @file{Makefile.am} file that lists the
7866 @file{.texi} files. If you used @code{AC_CONFIG_AUX_DIR} in
7867 @file{configure.ac} (@pxref{Input, , Finding `configure' Input,
7868 autoconf, The Autoconf Manual}), then @file{texinfo.tex} is looked for
7869 there. In both cases, @command{automake} then supplies @file{texinfo.tex} if
7870 @option{--add-missing} is given, and takes care of its distribution.
7871 However, if you set the @code{TEXINFO_TEX} variable (see below),
7872 it overrides the location of the file and turns off its installation
7873 into the source as well as its distribution.
7875 The option @option{no-texinfo.tex} can be used to eliminate the
7876 requirement for the file @file{texinfo.tex}. Use of the variable
7877 @code{TEXINFO_TEX} is preferable, however, because that allows the
7878 @code{dvi}, @code{ps}, and @code{pdf} targets to still work.
7880 @cindex Option, @code{no-installinfo}
7881 @cindex Target, @code{install-info}
7882 @cindex @code{install-info} target
7883 @cindex @code{no-installinfo} option
7885 @opindex no-installinfo
7886 @trindex install-info
7888 Automake generates an @code{install-info} rule; some people apparently
7889 use this. By default, info pages are installed by @samp{make
7890 install}, so running @code{make install-info} is pointless. This can
7891 be prevented via the @code{no-installinfo} option. In this case,
7892 @file{.info} files are not installed by default, and user must
7893 request this explicitly using @samp{make install-info}.
7895 @vindex AM_UPDATE_INFO_DIR
7896 By default, @code{make install-info} and @code{make install-info}
7897 will try to run the @command{install-info} program (if available)
7898 to update (or create) the @file{@code{$@{infodir@}}/dir} index.
7899 If this is undesired, it can be prevented by exporting the
7900 @code{AM_UPDATE_INFO_DIR} variable to "@code{no}".
7902 The following variables are used by the Texinfo build rules.
7906 The name of the program invoked to build @file{.info} files. This
7907 variable is defined by Automake. If the @command{makeinfo} program is
7908 found on the system then it will be used by default; otherwise
7909 @command{missing} will be used instead.
7912 The command invoked to build @file{.html} files. Automake
7913 defines this to @samp{$(MAKEINFO) --html}.
7916 User flags passed to each invocation of @samp{$(MAKEINFO)} and
7917 @samp{$(MAKEINFOHTML)}. This user variable (@pxref{User Variables}) is
7918 not expected to be defined in any @file{Makefile}; it can be used by
7919 users to pass extra flags to suit their needs.
7921 @item AM_MAKEINFOFLAGS
7922 @itemx AM_MAKEINFOHTMLFLAGS
7923 Maintainer flags passed to each @command{makeinfo} invocation. Unlike
7924 @code{MAKEINFOFLAGS}, these variables are meant to be defined by
7925 maintainers in @file{Makefile.am}. @samp{$(AM_MAKEINFOFLAGS)} is
7926 passed to @code{makeinfo} when building @file{.info} files; and
7927 @samp{$(AM_MAKEINFOHTMLFLAGS)} is used when building @file{.html}
7930 @c Keep in sync with txinfo21.sh
7931 For instance, the following setting can be used to obtain one single
7932 @file{.html} file per manual, without node separators.
7934 AM_MAKEINFOHTMLFLAGS = --no-headers --no-split
7937 @code{AM_MAKEINFOHTMLFLAGS} defaults to @samp{$(AM_MAKEINFOFLAGS)}.
7938 This means that defining @code{AM_MAKEINFOFLAGS} without defining
7939 @code{AM_MAKEINFOHTMLFLAGS} will impact builds of both @file{.info}
7940 and @file{.html} files.
7943 The name of the command that converts a @file{.texi} file into a
7944 @file{.dvi} file. This defaults to @samp{texi2dvi}, a script that ships
7945 with the Texinfo package.
7948 The name of the command that translates a @file{.texi} file into a
7949 @file{.pdf} file. This defaults to @samp{$(TEXI2DVI) --pdf --batch}.
7952 The name of the command that builds a @file{.ps} file out of a
7953 @file{.dvi} file. This defaults to @samp{dvips}.
7957 If your package has Texinfo files in many directories, you can use the
7958 variable @code{TEXINFO_TEX} to tell Automake where to find the canonical
7959 @file{texinfo.tex} for your package. The value of this variable should
7960 be the relative path from the current @file{Makefile.am} to
7964 TEXINFO_TEX = ../doc/texinfo.tex
7972 @cindex @code{_MANS} primary, defined
7973 @cindex @code{MANS} primary, defined
7974 @cindex Primary variable, @code{MANS}
7978 A package can also include man pages (but see the GNU standards on this
7979 matter, @ref{Man Pages, , , standards, The GNU Coding Standards}.) Man
7980 pages are declared using the @code{MANS} primary. Generally the
7981 @code{man_MANS} variable is used. Man pages are automatically installed in
7982 the correct subdirectory of @code{mandir}, based on the file extension.
7984 File extensions such as @file{.1c} are handled by looking for the valid
7985 part of the extension and using that to determine the correct
7986 subdirectory of @code{mandir}. Valid section names are the digits
7987 @samp{0} through @samp{9}, and the letters @samp{l} and @samp{n}.
7989 Sometimes developers prefer to name a man page something like
7990 @file{foo.man} in the source, and then rename it to have the correct
7991 suffix, for example @file{foo.1}, when installing the file. Automake
7992 also supports this mode. For a valid section named @var{section},
7993 there is a corresponding directory named @samp{man@var{section}dir},
7994 and a corresponding @code{_MANS} variable. Files listed in such a
7995 variable are installed in the indicated section. If the file already
7996 has a valid suffix, then it is installed as-is; otherwise the file
7997 suffix is changed to match the section.
7999 For instance, consider this example:
8001 man1_MANS = rename.man thesame.1 alsothesame.1c
8005 In this case, @file{rename.man} will be renamed to @file{rename.1} when
8006 installed, but the other files will keep their names.
8008 @cindex Target, @code{install-man}
8009 @cindex Option, @option{no-installman}
8010 @cindex @code{install-man} target
8011 @cindex @option{no-installman} option
8012 @opindex no-installman
8013 @trindex install-man
8015 By default, man pages are installed by @samp{make install}. However,
8016 since the GNU project does not require man pages, many maintainers do
8017 not expend effort to keep the man pages up to date. In these cases, the
8018 @option{no-installman} option will prevent the man pages from being
8019 installed by default. The user can still explicitly install them via
8020 @samp{make install-man}.
8022 For fast installation, with many files it is preferable to use
8023 @samp{man@var{section}_MANS} over @samp{man_MANS} as well as files that
8024 do not need to be renamed.
8026 Man pages are not currently considered to be source, because it is not
8027 uncommon for man pages to be automatically generated. Therefore they
8028 are not automatically included in the distribution. However, this can
8029 be changed by use of the @code{dist_} prefix. For instance here is
8030 how to distribute and install the two man pages of GNU @command{cpio}
8031 (which includes both Texinfo documentation and man pages):
8034 dist_man_MANS = cpio.1 mt.1
8037 The @code{nobase_} prefix is meaningless for man pages and is
8041 @cindex @code{notrans_} prefix
8042 @cindex Man page renaming, avoiding
8043 @cindex Avoiding man page renaming
8045 Executables and manpages may be renamed upon installation
8046 (@pxref{Renaming}). For manpages this can be avoided by use of the
8047 @code{notrans_} prefix. For instance, suppose an executable @samp{foo}
8048 allowing to access a library function @samp{foo} from the command line.
8049 The way to avoid renaming of the @file{foo.3} manpage is:
8053 notrans_man_MANS = foo.3
8056 @cindex @code{notrans_} and @code{dist_} or @code{nodist_}
8057 @cindex @code{dist_} and @code{notrans_}
8058 @cindex @code{nodist_} and @code{notrans_}
8060 @samp{notrans_} must be specified first when used in conjunction with
8061 either @samp{dist_} or @samp{nodist_} (@pxref{Fine-grained Distribution
8062 Control}). For instance:
8065 notrans_dist_man3_MANS = bar.3
8069 @chapter What Gets Installed
8071 @cindex Installation support
8072 @cindex @samp{make install} support
8074 Naturally, Automake handles the details of actually installing your
8075 program once it has been built. All files named by the various
8076 primaries are automatically installed in the appropriate places when the
8077 user runs @samp{make install}.
8080 * Basics of Installation:: What gets installed where
8081 * The Two Parts of Install:: Installing data and programs separately
8082 * Extending Installation:: Adding your own rules for installation
8083 * Staged Installs:: Installation in a temporary location
8084 * Install Rules for the User:: Useful additional rules
8087 @node Basics of Installation
8088 @section Basics of Installation
8090 A file named in a primary is installed by copying the built file into
8091 the appropriate directory. The base name of the file is used when
8095 bin_PROGRAMS = hello subdir/goodbye
8098 In this example, both @samp{hello} and @samp{goodbye} will be installed
8099 in @samp{$(bindir)}.
8101 Sometimes it is useful to avoid the basename step at install time. For
8102 instance, you might have a number of header files in subdirectories of
8103 the source tree that are laid out precisely how you want to install
8104 them. In this situation you can use the @code{nobase_} prefix to
8105 suppress the base name step. For example:
8108 nobase_include_HEADERS = stdio.h sys/types.h
8112 will install @file{stdio.h} in @samp{$(includedir)} and @file{types.h}
8113 in @samp{$(includedir)/sys}.
8115 For most file types, Automake will install multiple files at once, while
8116 avoiding command line length issues (@pxref{Length Limitations}). Since
8117 some @command{install} programs will not install the same file twice in
8118 one invocation, you may need to ensure that file lists are unique within
8119 one variable such as @samp{nobase_include_HEADERS} above.
8121 You should not rely on the order in which files listed in one variable
8122 are installed. Likewise, to cater for parallel make, you should not
8123 rely on any particular file installation order even among different
8124 file types (library dependencies are an exception here).
8127 @node The Two Parts of Install
8128 @section The Two Parts of Install
8130 Automake generates separate @code{install-data} and @code{install-exec}
8131 rules, in case the installer is installing on multiple machines that
8132 share directory structure---these targets allow the machine-independent
8133 parts to be installed only once. @code{install-exec} installs
8134 platform-dependent files, and @code{install-data} installs
8135 platform-independent files. The @code{install} target depends on both
8136 of these targets. While Automake tries to automatically segregate
8137 objects into the correct category, the @file{Makefile.am} author is, in
8138 the end, responsible for making sure this is done correctly.
8139 @trindex install-data
8140 @trindex install-exec
8142 @cindex Install, two parts of
8144 Variables using the standard directory prefixes @samp{data},
8145 @samp{info}, @samp{man}, @samp{include}, @samp{oldinclude},
8146 @samp{pkgdata}, or @samp{pkginclude} are installed by
8147 @code{install-data}.
8149 Variables using the standard directory prefixes @samp{bin},
8150 @samp{sbin}, @samp{libexec}, @samp{sysconf}, @samp{localstate},
8151 @samp{lib}, or @samp{pkglib} are installed by @code{install-exec}.
8153 For instance, @code{data_DATA} files are installed by @code{install-data},
8154 while @code{bin_PROGRAMS} files are installed by @code{install-exec}.
8156 Any variable using a user-defined directory prefix with
8157 @samp{exec} in the name (e.g.,
8158 @c Keep in sync with primary-prefix-couples-documented-valid.sh
8159 @code{myexecbin_PROGRAMS}) is installed by @code{install-exec}. All
8160 other user-defined prefixes are installed by @code{install-data}.
8162 @node Extending Installation
8163 @section Extending Installation
8165 It is possible to extend this mechanism by defining an
8166 @code{install-exec-local} or @code{install-data-local} rule. If these
8167 rules exist, they will be run at @samp{make install} time. These
8168 rules can do almost anything; care is required.
8169 @trindex install-exec-local
8170 @trindex install-data-local
8172 Automake also supports two install hooks, @code{install-exec-hook} and
8173 @code{install-data-hook}. These hooks are run after all other install
8174 rules of the appropriate type, exec or data, have completed. So, for
8175 instance, it is possible to perform post-installation modifications
8176 using an install hook. @xref{Extending}, for some examples.
8177 @cindex Install hook
8179 @node Staged Installs
8180 @section Staged Installs
8183 Automake generates support for the @code{DESTDIR} variable in all
8184 install rules. @code{DESTDIR} is used during the @samp{make install}
8185 step to relocate install objects into a staging area. Each object and
8186 path is prefixed with the value of @code{DESTDIR} before being copied
8187 into the install area. Here is an example of typical DESTDIR usage:
8190 mkdir /tmp/staging &&
8191 make DESTDIR=/tmp/staging install
8194 The @command{mkdir} command avoids a security problem if the attacker
8195 creates a symbolic link from @file{/tmp/staging} to a victim area;
8196 then @command{make} places install objects in a directory tree built under
8197 @file{/tmp/staging}. If @file{/gnu/bin/foo} and
8198 @file{/gnu/share/aclocal/foo.m4} are to be installed, the above command
8199 would install @file{/tmp/staging/gnu/bin/foo} and
8200 @file{/tmp/staging/gnu/share/aclocal/foo.m4}.
8202 This feature is commonly used to build install images and packages
8205 Support for @code{DESTDIR} is implemented by coding it directly into
8206 the install rules. If your @file{Makefile.am} uses a local install
8207 rule (e.g., @code{install-exec-local}) or an install hook, then you
8208 must write that code to respect @code{DESTDIR}.
8210 @xref{Makefile Conventions, , , standards, The GNU Coding Standards},
8211 for another usage example.
8213 @node Install Rules for the User
8214 @section Install Rules for the User
8216 Automake also generates rules for targets @code{uninstall},
8217 @code{installdirs}, and @code{install-strip}.
8219 @trindex installdirs
8220 @trindex install-strip
8222 Automake supports @code{uninstall-local} and @code{uninstall-hook}.
8223 There is no notion of separate uninstalls for ``exec'' and ``data'', as
8224 these features would not provide additional functionality.
8226 Note that @code{uninstall} is not meant as a replacement for a real
8231 @chapter What Gets Cleaned
8233 @cindex @samp{make clean} support
8235 The GNU Makefile Standards specify a number of different clean rules.
8236 @xref{Standard Targets, , Standard Targets for Users, standards,
8237 The GNU Coding Standards}.
8239 Generally the files that can be cleaned are determined automatically by
8240 Automake. Of course, Automake also recognizes some variables that can
8241 be defined to specify additional files to clean. These variables are
8242 @code{MOSTLYCLEANFILES}, @code{CLEANFILES}, @code{DISTCLEANFILES}, and
8243 @code{MAINTAINERCLEANFILES}.
8244 @vindex MOSTLYCLEANFILES
8246 @vindex DISTCLEANFILES
8247 @vindex MAINTAINERCLEANFILES
8249 @trindex mostlyclean-local
8250 @trindex clean-local
8251 @trindex distclean-local
8252 @trindex maintainer-clean-local
8253 When cleaning involves more than deleting some hard-coded list of
8254 files, it is also possible to supplement the cleaning rules with your
8255 own commands. Simply define a rule for any of the
8256 @code{mostlyclean-local}, @code{clean-local}, @code{distclean-local},
8257 or @code{maintainer-clean-local} targets (@pxref{Extending}). A common
8258 case is deleting a directory, for instance, a directory created by the
8266 Since @command{make} allows only one set of rules for a given target,
8267 a more extensible way of writing this is to use a separate target
8268 listed as a dependency:
8271 clean-local: clean-local-check
8272 .PHONY: clean-local-check
8277 As the GNU Standards aren't always explicit as to which files should
8278 be removed by which rule, we've adopted a heuristic that we believe
8279 was first formulated by Fran@,{c}ois Pinard:
8283 If @command{make} built it, and it is commonly something that one would
8284 want to rebuild (for instance, a @file{.o} file), then
8285 @code{mostlyclean} should delete it.
8288 Otherwise, if @command{make} built it, then @code{clean} should delete it.
8291 If @command{configure} built it, then @code{distclean} should delete it.
8294 If the maintainer built it (for instance, a @file{.info} file), then
8295 @code{maintainer-clean} should delete it. However
8296 @code{maintainer-clean} should not delete anything that needs to exist
8297 in order to run @samp{./configure && make}.
8300 We recommend that you follow this same set of heuristics in your
8305 @chapter What Goes in a Distribution
8308 * Basics of Distribution:: Files distributed by default
8309 * Fine-grained Distribution Control:: @code{dist_} and @code{nodist_} prefixes
8310 * The dist Hook:: A target for last-minute distribution changes
8311 * Checking the Distribution:: @samp{make distcheck} explained
8312 * The Types of Distributions:: A variety of formats and compression methods
8315 @node Basics of Distribution
8316 @section Basics of Distribution
8318 @cindex @samp{make dist}
8323 The @code{dist} rule in the generated @file{Makefile.in} can be used
8324 to generate a gzipped @code{tar} file and other flavors of archive for
8325 distribution. The file is named based on the @code{PACKAGE} and
8326 @code{VERSION} variables defined by @code{AM_INIT_AUTOMAKE}
8327 (@pxref{Macros}); more precisely the gzipped @code{tar} file is named
8328 @samp{@var{package}-@var{version}.tar.gz}.
8330 You can use the @command{make} variable @code{GZIP_ENV} to control how gzip
8331 is run. The default setting is @option{--best}.
8333 @cindex @code{m4_include}, distribution
8334 @cindex @code{include}, distribution
8337 For the most part, the files to distribute are automatically found by
8338 Automake: all source files are automatically included in a distribution,
8339 as are all @file{Makefile.am} and @file{Makefile.in} files. Automake also
8340 has a built-in list of commonly used files that are automatically
8341 included if they are found in the current directory (either physically,
8342 or as the target of a @file{Makefile.am} rule); this list is printed by
8343 @samp{automake --help}. Note that some files in this list are actually
8344 distributed only if other certain conditions hold (for example,
8345 @c Keep in sync with autodist-config-headers.sh
8346 the @file{config.h.top} and @file{config.h.bot} files are automatically
8347 distributed only if, e.g., @samp{AC_CONFIG_HEADERS([config.h])} is used
8348 in @file{configure.ac}). Also, files that are read by @command{configure}
8349 (i.e.@: the source files corresponding to the files specified in various
8350 Autoconf macros such as @code{AC_CONFIG_FILES} and siblings) are
8351 automatically distributed. Files included in a @file{Makefile.am} (using
8352 @code{include}) or in @file{configure.ac} (using @code{m4_include}), and
8353 helper scripts installed with @samp{automake --add-missing} are also
8357 Still, sometimes there are files that must be distributed, but which
8358 are not covered in the automatic rules. These files should be listed in
8359 the @code{EXTRA_DIST} variable. You can mention files from
8360 subdirectories in @code{EXTRA_DIST}.
8362 You can also mention a directory in @code{EXTRA_DIST}; in this case the
8363 entire directory will be recursively copied into the distribution.
8364 Please note that this will also copy @emph{everything} in the directory,
8365 including, e.g., Subversion's @file{.svn} private directories or CVS/RCS
8366 version control files. We recommend against using this feature.
8369 @vindex DIST_SUBDIRS
8370 If you define @code{SUBDIRS}, Automake will recursively include the
8371 subdirectories in the distribution. If @code{SUBDIRS} is defined
8372 conditionally (@pxref{Conditionals}), Automake will normally include
8373 all directories that could possibly appear in @code{SUBDIRS} in the
8374 distribution. If you need to specify the set of directories
8375 conditionally, you can set the variable @code{DIST_SUBDIRS} to the
8376 exact list of subdirectories to include in the distribution
8377 (@pxref{Conditional Subdirectories}).
8380 @node Fine-grained Distribution Control
8381 @section Fine-grained Distribution Control
8385 Sometimes you need tighter control over what does @emph{not} go into the
8386 distribution; for instance, you might have source files that are
8387 generated and that you do not want to distribute. In this case
8388 Automake gives fine-grained control using the @code{dist} and
8389 @code{nodist} prefixes. Any primary or @code{_SOURCES} variable can be
8390 prefixed with @code{dist_} to add the listed files to the distribution.
8391 Similarly, @code{nodist_} can be used to omit the files from the
8394 As an example, here is how you would cause some data to be distributed
8395 while leaving some source code out of the distribution:
8398 dist_data_DATA = distribute-this
8400 nodist_foo_SOURCES = do-not-distribute.c
8404 @section The dist Hook
8408 Occasionally it is useful to be able to change the distribution before
8409 it is packaged up. If the @code{dist-hook} rule exists, it is run
8410 after the distribution directory is filled, but before the actual
8411 distribution archives are created. One way to use this is for
8412 removing unnecessary files that get recursively included by specifying
8413 a directory in @code{EXTRA_DIST}:
8418 rm -rf `find $(distdir)/doc -type d -name .svn`
8421 @c The caveates described here should be documented in 'disthook.test'.
8423 Note that the @code{dist-hook} recipe shouldn't assume that the regular
8424 files in the distribution directory are writable; this might not be the
8425 case if one is packaging from a read-only source tree, or when a
8426 @code{make distcheck} is being done. For similar reasons, the recipe
8427 shouldn't assume that the subdirectories put into the distribution
8428 directory as effect of having them listed in @code{EXTRA_DIST} are
8429 writable. So, if the @code{dist-hook} recipe wants to modify the
8430 content of an existing file (or @code{EXTRA_DIST} subdirectory) in the
8431 distribution directory, it should explicitly to make it writable first:
8434 EXTRA_DIST = README doc
8436 chmod u+w $(distdir)/README $(distdir)/doc
8437 echo "Distribution date: `date`" >> README
8438 rm -f $(distdir)/doc/HACKING
8443 Two variables that come handy when writing @code{dist-hook} rules are
8444 @samp{$(distdir)} and @samp{$(top_distdir)}.
8446 @samp{$(distdir)} points to the directory where the @code{dist} rule
8447 will copy files from the current directory before creating the
8448 tarball. If you are at the top-level directory, then @samp{distdir =
8449 $(PACKAGE)-$(VERSION)}. When used from subdirectory named
8450 @file{foo/}, then @samp{distdir = ../$(PACKAGE)-$(VERSION)/foo}.
8451 @samp{$(distdir)} can be a relative or absolute path, do not assume
8454 @samp{$(top_distdir)} always points to the root directory of the
8455 distributed tree. At the top-level it's equal to @samp{$(distdir)}.
8456 In the @file{foo/} subdirectory
8457 @samp{top_distdir = ../$(PACKAGE)-$(VERSION)}.
8458 @samp{$(top_distdir)} too can be a relative or absolute path.
8460 Note that when packages are nested using @code{AC_CONFIG_SUBDIRS}
8461 (@pxref{Subpackages}), then @samp{$(distdir)} and
8462 @samp{$(top_distdir)} are relative to the package where @samp{make
8463 dist} was run, not to any sub-packages involved.
8465 @node Checking the Distribution
8466 @section Checking the Distribution
8468 @cindex @samp{make distcheck}
8470 Automake also generates a @code{distcheck} rule that can be of help
8471 to ensure that a given distribution will actually work. Simplifying
8472 a bit, we can say this rule first makes a distribution, and then,
8473 @emph{operating from it}, takes the following steps:
8476 tries to do a @code{VPATH} build (@pxref{VPATH Builds}), with the
8477 @code{srcdir} and all its content made @emph{read-only};
8479 runs the test suite (with @command{make check}) on this fresh build;
8481 installs the package in a temporary directory (with @command{make
8482 install}), and tries runs the test suite on the resulting installation
8483 (with @command{make installcheck});
8485 checks that the package can be correctly uninstalled (by @command{make
8486 uninstall}) and cleaned (by @code{make distclean});
8488 finally, makes another tarball to ensure the distribution is
8492 @vindex AM_DISTCHECK_CONFIGURE_FLAGS
8493 @vindex DISTCHECK_CONFIGURE_FLAGS
8494 @subheading DISTCHECK_CONFIGURE_FLAGS
8495 Building the package involves running @samp{./configure}. If you need
8496 to supply additional flags to @command{configure}, define them in the
8497 @code{AM_DISTCHECK_CONFIGURE_FLAGS} variable in your top-level
8498 @file{Makefile.am}. The user can still extend or override the flags
8499 provided there by defining the @code{DISTCHECK_CONFIGURE_FLAGS} variable,
8500 on the command line when invoking @command{make}.
8502 Still, developers are encouraged to strive to make their code buildable
8503 without requiring any special configure option; thus, in general, you
8504 shouldn't define @code{AM_DISTCHECK_CONFIGURE_FLAGS}. However, there
8505 might be few scenarios in which the use of this variable is justified.
8506 GNU @command{m4} offers an example. GNU @command{m4} configures by
8507 default with its experimental and seldom used "changeword" feature
8508 disabled; so in its case it is useful to have @command{make distcheck}
8509 run configure with the @option{--with-changeword} option, to ensure that
8510 the code for changeword support still compiles correctly.
8511 GNU @command{m4} also employs the @code{AM_DISTCHECK_CONFIGURE_FLAGS}
8512 variable to stress-test the use of @option{--program-prefix=g}, since at
8513 one point the @command{m4} build system had a bug where @command{make
8514 installcheck} was wrongly assuming it could blindly test "@command{m4}",
8515 rather than the just-installed "@command{gm4}".
8517 @trindex distcheck-hook
8518 @subheading distcheck-hook
8519 If the @code{distcheck-hook} rule is defined in your top-level
8520 @file{Makefile.am}, then it will be invoked by @code{distcheck} after
8521 the new distribution has been unpacked, but before the unpacked copy
8522 is configured and built. Your @code{distcheck-hook} can do almost
8523 anything, though as always caution is advised. Generally this hook is
8524 used to check for potential distribution errors not caught by the
8525 standard mechanism. Note that @code{distcheck-hook} as well as
8526 @code{AM_DISTCHECK_CONFIGURE_FLAGS} and @code{DISTCHECK_CONFIGURE_FLAGS}
8527 are not honored in a subpackage @file{Makefile.am}, but the flags from
8528 @code{AM_DISTCHECK_CONFIGURE_FLAGS} and @code{DISTCHECK_CONFIGURE_FLAGS}
8529 are passed down to the @command{configure} script of the subpackage.
8531 @cindex @samp{make distcleancheck}
8532 @trindex distcleancheck
8533 @vindex DISTCLEANFILES
8534 @vindex distcleancheck_listfiles
8536 @subheading distcleancheck
8537 Speaking of potential distribution errors, @code{distcheck} also
8538 ensures that the @code{distclean} rule actually removes all built
8539 files. This is done by running @samp{make distcleancheck} at the end of
8540 the @code{VPATH} build. By default, @code{distcleancheck} will run
8541 @code{distclean} and then make sure the build tree has been emptied by
8542 running @samp{$(distcleancheck_listfiles)}. Usually this check will
8543 find generated files that you forgot to add to the @code{DISTCLEANFILES}
8544 variable (@pxref{Clean}).
8546 The @code{distcleancheck} behavior should be OK for most packages,
8547 otherwise you have the possibility to override the definition of
8548 either the @code{distcleancheck} rule, or the
8549 @samp{$(distcleancheck_listfiles)} variable. For instance, to disable
8550 @code{distcleancheck} completely, add the following rule to your
8551 top-level @file{Makefile.am}:
8558 If you want @code{distcleancheck} to ignore built files that have not
8559 been cleaned because they are also part of the distribution, add the
8560 following definition instead:
8562 @c Keep in sync with distcleancheck.sh
8564 distcleancheck_listfiles = \
8565 find . -type f -exec sh -c 'test -f $(srcdir)/$$1 || echo $$1' \
8569 The above definition is not the default because it's usually an error if
8570 your Makefiles cause some distributed files to be rebuilt when the user
8571 build the package. (Think about the user missing the tool required to
8572 build the file; or if the required tool is built by your package,
8573 consider the cross-compilation case where it can't be run.) There is
8574 an entry in the FAQ about this (@pxref{Errors with distclean}), make
8575 sure you read it before playing with @code{distcleancheck_listfiles}.
8577 @cindex @samp{make distuninstallcheck}
8578 @trindex distuninstallcheck
8579 @vindex distuninstallcheck_listfiles
8581 @subheading distuninstallcheck
8582 @code{distcheck} also checks that the @code{uninstall} rule works
8583 properly, both for ordinary and @code{DESTDIR} builds. It does this
8584 by invoking @samp{make uninstall}, and then it checks the install tree
8585 to see if any files are left over. This check will make sure that you
8586 correctly coded your @code{uninstall}-related rules.
8588 By default, the checking is done by the @code{distuninstallcheck} rule,
8589 and the list of files in the install tree is generated by
8590 @samp{$(distuninstallcheck_listfiles)} (this is a variable whose value is
8591 a shell command to run that prints the list of files to stdout).
8593 Either of these can be overridden to modify the behavior of
8594 @code{distcheck}. For instance, to disable this check completely, you
8602 @node The Types of Distributions
8603 @section The Types of Distributions
8605 Automake generates rules to provide archives of the project for
8606 distributions in various formats. Their targets are:
8610 @item @code{dist-bzip2}
8611 Generate a bzip2 tar archive of the distribution. bzip2 archives are
8612 frequently smaller than gzipped archives.
8613 By default, this rule makes @samp{bzip2} use a compression option of @option{-9}.
8614 To make it use a different one, set the @env{BZIP2} environment variable.
8615 For example, @samp{make dist-bzip2 BZIP2=-7}.
8618 @item @code{dist-gzip}
8619 Generate a gzip tar archive of the distribution.
8622 @item @code{dist-lzip}
8623 Generate an @samp{lzip} tar archive of the distribution. @command{lzip}
8624 archives are frequently smaller than @command{bzip2}-compressed archives.
8627 @item @code{dist-shar}
8628 Generate a shar archive of the distribution.
8632 @item @code{dist-xz}
8633 Generate an @samp{xz} tar archive of the distribution. @command{xz}
8634 archives are frequently smaller than @command{bzip2}-compressed archives.
8635 By default, this rule makes @samp{xz} use a compression option of
8636 @option{-e}. To make it use a different one, set the @env{XZ_OPT}
8637 environment variable. For example, run this command to use the
8638 default compression ratio, but with a progress indicator:
8639 @samp{make dist-xz XZ_OPT=-7e}.
8642 @item @code{dist-zip}
8643 Generate a zip archive of the distribution.
8646 @item @code{dist-tarZ}
8647 Generate a compressed tar archive of
8652 The rule @code{dist} (and its historical synonym @code{dist-all}) will
8653 create archives in all the enabled formats, @ref{Options}. By
8654 default, only the @code{dist-gzip} target is hooked to @code{dist}.
8658 @chapter Support for test suites
8661 @cindex @code{make check}
8664 Automake can generate code to handle two kinds of test suites. One is
8665 based on integration with the @command{dejagnu} framework. The other
8666 (and most used) form is based on the use of generic test scripts, and
8667 its activation is triggered by the definition of the special @code{TESTS}
8668 variable. This second form allows for various degrees of sophistication
8669 and customization; in particular, it allows for concurrent execution
8670 of test scripts, use of established test protocols such as TAP, and
8671 definition of custom test drivers and test runners.
8674 In either case, the testsuite is invoked via @samp{make check}.
8677 * Generalities about Testing:: Concepts and terminology about testing
8678 * Simple Tests:: Listing test scripts in @code{TESTS}
8679 * Custom Test Drivers:: Writing and using custom test drivers
8680 * Using the TAP test protocol:: Integrating test scripts that use the TAP protocol
8681 * DejaGnu Tests:: Interfacing with the @command{dejagnu} testing framework
8682 * Install Tests:: Running tests on installed packages
8685 @node Generalities about Testing
8686 @section Generalities about Testing
8688 The purpose of testing is to determine whether a program or system behaves
8689 as expected (e.g., known inputs produce the expected outputs, error
8690 conditions are correctly handled or reported, and older bugs do not
8694 The minimal unit of testing is usually called @emph{test case}, or simply
8695 @emph{test}. How a test case is defined or delimited, and even what
8696 exactly @emph{constitutes} a test case, depends heavily on the testing
8697 paradigm and/or framework in use, so we won't attempt any more precise
8698 definition. The set of the test cases for a given program or system
8699 constitutes its @emph{testsuite}.
8701 @cindex test harness
8702 @cindex testsuite harness
8703 A @emph{test harness} (also @emph{testsuite harness}) is a program or
8704 software component that executes all (or part of) the defined test cases,
8705 analyzes their outcomes, and report or register these outcomes
8706 appropriately. Again, the details of how this is accomplished (and how
8707 the developer and user can influence it or interface with it) varies
8708 wildly, and we'll attempt no precise definition.
8711 @cindex test failure
8712 A test is said to @emph{pass} when it can determine that the condition or
8713 behaviour it means to verify holds, and is said to @emph{fail} when it can
8714 determine that such condition of behaviour does @emph{not} hold.
8717 Sometimes, tests can rely on non-portable tools or prerequisites, or
8718 simply make no sense on a given system (for example, a test checking a
8719 Windows-specific feature makes no sense on a GNU/Linux system). In this
8720 case, accordingly to the definition above, the tests can neither be
8721 considered passed nor failed; instead, they are @emph{skipped} -- i.e.,
8722 they are not run, or their result is anyway ignored for what concerns
8723 the count of failures an successes. Skips are usually explicitly
8724 reported though, so that the user will be aware that not all of the
8725 testsuite has really run.
8728 @cindex expected failure
8729 @cindex expected test failure
8731 @cindex unexpected pass
8732 @cindex unexpected test pass
8733 It's not uncommon, especially during early development stages, that some
8734 tests fail for known reasons, and that the developer doesn't want to
8735 tackle these failures immediately (this is especially true when the
8736 failing tests deal with corner cases). In this situation, the better
8737 policy is to declare that each of those failures is an @emph{expected
8738 failure} (or @emph{xfail}). In case a test that is expected to fail ends
8739 up passing instead, many testing environments will flag the result as a
8740 special kind of failure called @emph{unexpected pass} (or @emph{xpass}).
8743 @cindex Distinction between errors and failures in testsuites
8744 Many testing environments and frameworks distinguish between test failures
8745 and hard errors. As we've seen, a test failure happens when some invariant
8746 or expected behaviour of the software under test is not met. An @emph{hard
8747 error} happens when e.g., the set-up of a test case scenario fails, or when
8748 some other unexpected or highly undesirable condition is encountered (for
8749 example, the program under test experiences a segmentation fault).
8751 @emph{TODO}: Links to other test harnesses (esp. those sharing our
8755 @section Simple Tests
8758 * Scripts-based Testsuites:: Automake-specific concepts and terminology
8759 * Serial Test Harness:: Older (and obsolescent) serial test harness
8760 * Parallel Test Harness:: Generic concurrent test harness
8763 @node Scripts-based Testsuites
8764 @subsection Scripts-based Testsuites
8766 If the special variable @code{TESTS} is defined, its value is taken to be
8767 a list of programs or scripts to run in order to do the testing. Under
8768 the appropriate circumstances, it's possible for @code{TESTS} to list
8769 also data files to be passed to one or more test scripts defined by
8770 different means (the so-called ``log compilers'', @pxref{Parallel Test
8773 Test scripts can be executed serially or concurrently. Automake supports
8774 both these kinds of test execution, with the parallel test harness being
8775 the default. The concurrent test harness relies on the concurrence
8776 capabilities (if any) offered by the underlying @command{make}
8777 implementation, and can thus only be as good as those are.
8779 By default, only the exit statuses of the test scripts are considered when
8780 determining the testsuite outcome. But Automake allows also the use of
8781 more complex test protocols, either standard (@pxref{Using the TAP test
8782 protocol}) or custom (@pxref{Custom Test Drivers}). Note that you can't
8783 enable such protocols when the serial harness is used, though.
8784 In the rest of this section we are going to concentrate mostly on
8785 protocol-less tests, since we cover test protocols in a later section
8786 (again, @pxref{Custom Test Drivers}).
8788 @cindex Exit status 77, special interpretation
8789 @cindex Exit status 99, special interpretation
8790 When no test protocol is in use, an exit status of 0 from a test script will
8791 denote a success, an exit status of 77 a skipped test, an exit status of 99
8792 an hard error, and any other exit status will denote a failure.
8794 @cindex Tests, expected failure
8795 @cindex Expected test failure
8797 @vindex DISABLE_HARD_ERRORS
8798 @cindex Disabling hard errors
8799 You may define the variable @code{XFAIL_TESTS} to a list of tests
8800 (usually a subset of @code{TESTS}) that are expected to fail; this will
8801 effectively reverse the result of those tests (with the provision that
8802 skips and hard errors remain untouched). You may also instruct the
8803 testsuite harness to treat hard errors like simple failures, by defining
8804 the @code{DISABLE_HARD_ERRORS} make variable to a nonempty value.
8806 Note however that, for tests based on more complex test protocols,
8807 the exact effects of @code{XFAIL_TESTS} and @code{DISABLE_HARD_ERRORS}
8808 might change, or they might even have no effect at all (for example,
8809 @c Keep this in sync with tap-no-disable-hard-errors.sh
8810 in tests using TAP, there is not way to disable hard errors, and the
8811 @code{DISABLE_HARD_ERRORS} variable has no effect on them).
8813 @anchor{Testsuite progress on console}
8814 @cindex Testsuite progress on console
8815 The result of each test case run by the scripts in @code{TESTS} will be
8816 printed on standard output, along with the test name. For test protocols
8817 that allow more test cases per test script (such as TAP), a number,
8818 identifier and/or brief description specific for the single test case is
8819 expected to be printed in addition to the name of the test script. The
8820 possible results (whose meanings should be clear from the previous
8821 @ref{Generalities about Testing}) are @code{PASS}, @code{FAIL},
8822 @code{SKIP}, @code{XFAIL}, @code{XPASS} and @code{ERROR}. Here is an
8823 example of output from an hypothetical testsuite that uses both plain
8825 @c Keep in sync with tap-doc.sh
8828 PASS: zardoz.tap 1 - Daemon started
8829 PASS: zardoz.tap 2 - Daemon responding
8830 SKIP: zardoz.tap 3 - Daemon uses /proc # SKIP /proc is not mounted
8831 PASS: zardoz.tap 4 - Daemon stopped
8834 XFAIL: mu.tap 2 # TODO frobnication not yet implemented
8838 A testsuite summary (expected to report at least the number of run,
8839 skipped and failed tests) will be printed at the end of the testsuite
8842 @anchor{Simple tests and color-tests}
8843 @vindex AM_COLOR_TESTS
8844 @cindex Colorized testsuite output
8845 If the standard output is connected to a capable terminal, then the test
8846 results and the summary are colored appropriately. The developer and the
8847 user can disable colored output by setting the @command{make} variable
8848 @samp{AM_COLOR_TESTS=no}; the user can in addition force colored output
8849 even without a connecting terminal with @samp{AM_COLOR_TESTS=always}.
8850 It's also worth noting that some @command{make} implementations,
8851 when used in parallel mode, have slightly different semantics
8852 (@pxref{Parallel make,,, autoconf, The Autoconf Manual}), which can
8853 break the automatic detection of a connection to a capable terminal.
8854 If this is the case, the user will have to resort to the use of
8855 @samp{AM_COLOR_TESTS=always} in order to have the testsuite output
8858 Test programs that need data files should look for them in @code{srcdir}
8859 (which is both a make variable and an environment variable made available
8860 to the tests), so that they work when building in a separate directory
8861 (@pxref{Build Directories, , Build Directories , autoconf,
8862 The Autoconf Manual}), and in particular for the @code{distcheck} rule
8863 (@pxref{Checking the Distribution}).
8866 @vindex TESTS_ENVIRONMENT
8867 @vindex AM_TESTS_ENVIRONMENT
8868 The @code{AM_TESTS_ENVIRONMENT} and @code{TESTS_ENVIRONMENT} variables can
8869 be used to run initialization code and set environment variables for the
8870 test scripts. The former variable is developer-reserved, and can be
8871 defined in the @file{Makefile.am}, while the latter is reserved for the
8872 user, which can employ it to extend or override the settings in the
8873 former; for this to work portably, however, the contents of a non-empty
8874 @code{AM_TESTS_ENVIRONMENT} @emph{must} be terminated by a semicolon.
8876 @vindex AM_TESTS_FD_REDIRECT
8877 The @code{AM_TESTS_FD_REDIRECT} variable can be used to define file
8878 descriptor redirections for the test scripts. One might think that
8879 @code{AM_TESTS_ENVIRONMENT} could be used for this purpose, but experience
8880 has shown that doing so portably is practically impossible. The main
8881 hurdle is constituted by Korn shells, which usually set the close-on-exec
8882 flag on file descriptors opened with the @command{exec} builtin, thus
8883 rendering an idiom like @code{AM_TESTS_ENVIRONMENT = exec 9>&2;}
8884 ineffectual. This issue also affects some Bourne shells, such as the
8885 HP-UX's @command{/bin/sh},
8886 @c FIXME: should we offer a link to the relevant discussions on the
8887 @c bug-autoconf list?
8889 @c Keep in sync with tests-environment-backcompat.sh
8891 AM_TESTS_ENVIRONMENT = \
8892 ## Some environment initializations are kept in a separate shell
8893 ## file 'tests-env.sh', which can make it easier to also run tests
8894 ## from the command line.
8895 . $(srcdir)/tests-env.sh; \
8896 ## On Solaris, prefer more POSIX-compliant versions of the standard
8897 ## tools by default.
8898 if test -d /usr/xpg4/bin; then \
8899 PATH=/usr/xpg4/bin:$$PATH; export PATH; \
8901 @c $$ restore font-lock
8902 ## With this, the test scripts will be able to print diagnostic
8903 ## messages to the original standard error stream, even if the test
8904 ## driver redirects the stderr of the test scripts to a log file
8905 ## before executing them.
8906 AM_TESTS_FD_REDIRECT = 9>&2
8910 Note however that @code{AM_TESTS_ENVIRONMENT} is, for historical and
8911 implementation reasons, @emph{not} supported by the serial harness
8912 (@pxref{Serial Test Harness}).
8914 Automake ensures that each file listed in @code{TESTS} is built before
8915 it is run; you can list both source and derived programs (or scripts)
8916 in @code{TESTS}; the generated rule will look both in @code{srcdir} and
8917 @file{.}. For instance, you might want to run a C program as a test.
8918 To do this you would list its name in @code{TESTS} and also in
8919 @code{check_PROGRAMS}, and then specify it as you would any other
8922 Programs listed in @code{check_PROGRAMS} (and @code{check_LIBRARIES},
8923 @code{check_LTLIBRARIES}...) are only built during @code{make check},
8924 not during @code{make all}. You should list there any program needed
8925 by your tests that does not need to be built by @code{make all}. Note
8926 that @code{check_PROGRAMS} are @emph{not} automatically added to
8927 @code{TESTS} because @code{check_PROGRAMS} usually lists programs used
8928 by the tests, not the tests themselves. Of course you can set
8929 @code{TESTS = $(check_PROGRAMS)} if all your programs are test cases.
8931 @node Serial Test Harness
8932 @subsection Older (and obsolescent) serial test harness
8933 @cindex @option{serial-tests}, Using
8935 @emph{This harness is obsolescent}, and kept for backward-compatibility
8936 reasons only. The user is strongly advised to just use the parallel test
8937 harness instead (@pxref{Parallel Test Harness}).
8939 The serial test harness is enabled by the Automake option
8940 @option{serial-tests}. It operates by simply running the tests serially,
8941 one at the time, without any I/O redirection. It's up to the user to
8942 implement logging of tests' output, if that's requited or desired.
8943 @c TODO: give an example of how this can be done.
8945 For historical and implementation reasons, the @code{AM_TESTS_ENVIRONMENT}
8946 variable is @emph{not} supported by this harness (it will be silently
8947 ignored if defined); only @code{TESTS_ENVIRONMENT} is, and it is to be
8948 considered a developer-reserved variable. This is done so that, when
8949 using the serial harness, @code{TESTS_ENVIRONMENT} can be defined to an
8950 invocation of an interpreter through which the tests are to be run.
8951 For instance, the following setup may be used to run tests with Perl:
8954 TESTS_ENVIRONMENT = $(PERL) -Mstrict -w
8955 TESTS = foo.pl bar.pl baz.pl
8959 It's important to note that the use of @code{TESTS_ENVIRONMENT} endorsed
8960 here would be @emph{invalid} with the parallel harness. That harness
8961 provides a more elegant way to achieve the same effect, with the further
8962 benefit of freeing the @code{TESTS_ENVIRONMENT} variable for the user
8963 (@pxref{Parallel Test Harness}).
8965 Another, less serious limit of the serial harness is that it doesn't
8966 really distinguish between simple failures and hard errors; this is
8967 due to historical reasons only, and might be fixed in future Automake
8970 @node Parallel Test Harness
8971 @subsection Parallel Test Harness
8973 By default, Automake generated a parallel (concurrent) test harness. It
8974 features automatic collection of the test scripts output in @file{.log}
8975 files, concurrent execution of tests with @code{make -j}, specification
8976 of inter-test dependencies, lazy reruns of tests that have not completed
8977 in a prior run, and hard errors for exceptional failures.
8979 This harness is still somewhat experimental and may undergo changes in
8980 order to satisfy additional portability requirements.
8982 @anchor{Basics of test metadata}
8983 @vindex TEST_SUITE_LOG
8985 @cindex @file{.log} files
8986 @cindex @file{.trs} files
8987 @cindex test metadata
8988 The parallel test harness operates by defining a set of @command{make}
8989 rules that run the test scripts listed in @code{TESTS}, and, for each
8990 such script, save its output in a corresponding @file{.log} file and
8991 its results (and other ``metadata'', @pxref{API for Custom Test Drivers})
8992 in a corresponding @file{.trs} (as in @b{T}est @b{R}e@b{S}ults) file.
8993 @c We choose the '.trs' extension also because, at the time of writing,
8994 @c it isn't already used for other significant purposes; see e.g.:
8995 @c - http://filext.com/file-extension/trs
8996 @c - http://www.file-extensions.org/search/?searchstring=trs
8997 The @file{.log} file will contain all the output emitted by the test on
8998 its standard output and its standard error. The @file{.trs} file will
8999 contain, among the other things, the results of the test cases run by
9002 The parallel test harness will also create a summary log file,
9003 @code{TEST_SUITE_LOG}, which defaults to @file{test-suite.log} and requires
9004 a @file{.log} suffix. This file depends upon all the @file{.log} and
9005 @file{.trs} files created for the test scripts listed in @code{TESTS}.
9008 As with the serial harness above, by default one status line is printed
9009 per completed test, and a short summary after the suite has completed.
9010 However, standard output and standard error of the test are redirected
9011 to a per-test log file, so that parallel execution does not produce
9012 intermingled output. The output from failed tests is collected in the
9013 @file{test-suite.log} file. If the variable @samp{VERBOSE} is set, this
9014 file is output after the summary.
9015 @c FIXME: we should be clearer about what we mean exactly here ...
9016 For best results, the tests should be verbose by default now.
9018 @vindex TEST_EXTENSIONS
9020 Each couple of @file{.log} and @file{.trs} files is created when the
9021 corresponding test has completed. The set of log files is listed in
9022 the read-only variable @code{TEST_LOGS}, and defaults to @code{TESTS},
9023 with the executable extension if any (@pxref{EXEEXT}), as well as any
9024 suffix listed in @code{TEST_EXTENSIONS} removed, and @file{.log} appended.
9025 Results are undefined if a test file name ends in several concatenated
9026 suffixes. @code{TEST_EXTENSIONS} defaults to @file{.test}; it can be
9027 overridden by the user, in which case any extension listed in it must be
9028 constituted by a dot, followed by a non-digit alphabetic character,
9029 followed by any number of alphabetic characters.
9030 @c Keep in sync with test-extensions.sh
9031 For example, @samp{.sh}, @samp{.T} and @samp{.t1} are valid extensions,
9032 while @samp{.x-y}, @samp{.6c} and @samp{.t.1} are not.
9034 @vindex _LOG_COMPILE
9035 @vindex _LOG_COMPILER
9038 @vindex LOG_COMPILER
9040 @vindex @var{ext}_LOG_COMPILE
9041 @vindex @var{ext}_LOG_COMPILER
9042 @vindex @var{ext}_LOG_FLAGS
9043 @vindex AM_@var{ext}_LOG_FLAGS
9044 @vindex AM_LOG_FLAGS
9045 For tests that match an extension @code{.@var{ext}} listed in
9046 @code{TEST_EXTENSIONS}, you can provide a custom ``test runner'' using
9047 the variable @code{@var{ext}_LOG_COMPILER} (note the upper-case
9048 extension) and pass options in @code{AM_@var{ext}_LOG_FLAGS} and allow
9049 the user to pass options in @code{@var{ext}_LOG_FLAGS}. It will cause
9050 all tests with this extension to be called with this runner. For all
9051 tests without a registered extension, the variables @code{LOG_COMPILER},
9052 @code{AM_LOG_FLAGS}, and @code{LOG_FLAGS} may be used. For example,
9054 @c Keep in sync with parallel-tests-log-compiler-example.sh
9056 TESTS = foo.pl bar.py baz
9057 TEST_EXTENSIONS = .pl .py
9058 PL_LOG_COMPILER = $(PERL)
9059 AM_PL_LOG_FLAGS = -w
9060 PY_LOG_COMPILER = $(PYTHON)
9061 AM_PY_LOG_FLAGS = -v
9062 LOG_COMPILER = ./wrapper-script
9067 will invoke @samp{$(PERL) -w foo.pl}, @samp{$(PYTHON) -v bar.py},
9068 and @samp{./wrapper-script -d baz} to produce @file{foo.log},
9069 @file{bar.log}, and @file{baz.log}, respectively. The @file{foo.trs},
9070 @file{bar.trs} and @file{baz.trs} files will be automatically produced
9073 It's important to note that, differently from what we've seen for the
9074 serial test harness (@pxref{Parallel Test Harness}), the
9075 @code{AM_TESTS_ENVIRONMENT} and @code{TESTS_ENVIRONMENT} variables
9076 @emph{cannot} be use to define a custom test runner; the
9077 @code{LOG_COMPILER} and @code{LOG_FLAGS} (or their extension-specific
9078 counterparts) should be used instead:
9082 AM_TESTS_ENVIRONMENT = PERL5LIB='$(srcdir)/lib' $(PERL) -Mstrict -w
9087 AM_TESTS_ENVIRONMENT = PERL5LIB='$(srcdir)/lib'; export PERL5LIB;
9088 LOG_COMPILER = $(PERL)
9089 AM_LOG_FLAGS = -Mstrict -w
9092 By default, the test suite harness will run all tests, but there are
9093 several ways to limit the set of tests that are run:
9097 You can set the @code{TESTS} variable. For example, you can use a
9098 command like this to run only a subset of the tests:
9101 env TESTS="foo.test bar.test" make -e check
9104 Note however that the command above will unconditionally overwrite the
9105 @file{test-suite.log} file, thus clobbering the recorded results
9106 of any previous testsuite run. This might be undesirable for packages
9107 whose testsuite takes long time to execute. Luckily, this problem can
9108 easily be avoided by overriding also @code{TEST_SUITE_LOG} at runtime;
9111 @c Keep in sync with parallel-tests-log-override-2.sh
9113 env TEST_SUITE_LOG=partial.log TESTS="..." make -e check
9116 will write the result of the partial testsuite runs to the
9117 @file{partial.log}, without touching @file{test-suite.log}.
9120 You can set the @code{TEST_LOGS} variable. By default, this variable is
9121 computed at @command{make} run time from the value of @code{TESTS} as
9122 described above. For example, you can use the following:
9125 set x subset*.log; shift
9126 env TEST_LOGS="foo.log $*" make -e check
9129 The comments made above about @code{TEST_SUITE_LOG} overriding applies
9133 @vindex RECHECK_LOGS
9134 @cindex lazy test execution
9135 By default, the test harness removes all old per-test @file{.log} and
9136 @file{.trs} files before it starts running tests to regenerate them. The
9137 variable @code{RECHECK_LOGS} contains the set of @file{.log} (and, by
9138 implication, @file{.trs}) files which are removed. @code{RECHECK_LOGS}
9139 defaults to @code{TEST_LOGS}, which means all tests need to be rechecked.
9140 By overriding this variable, you can choose which tests need to be
9141 reconsidered. For example, you can lazily rerun only those tests which
9142 are outdated, i.e., older than their prerequisite test files, by setting
9143 this variable to the empty value:
9146 env RECHECK_LOGS= make -e check
9151 You can ensure that all tests are rerun which have failed or passed
9152 unexpectedly, by running @code{make recheck} in the test directory.
9153 This convenience target will set @code{RECHECK_LOGS} appropriately
9154 before invoking the main test harness.
9158 In order to guarantee an ordering between tests even with @code{make
9159 -j@var{N}}, dependencies between the corresponding @file{.log} files
9160 may be specified through usual @command{make} dependencies. For example,
9161 the following snippet lets the test named @file{foo-execute.test} depend
9162 upon completion of the test @file{foo-compile.test}:
9165 TESTS = foo-compile.test foo-execute.test
9166 foo-execute.log: foo-compile.log
9170 Please note that this ordering ignores the @emph{results} of required
9171 tests, thus the test @file{foo-execute.test} is run even if the test
9172 @file{foo-compile.test} failed or was skipped beforehand. Further,
9173 please note that specifying such dependencies currently works only for
9174 tests that end in one of the suffixes listed in @code{TEST_EXTENSIONS}.
9176 Tests without such specified dependencies may be run concurrently with
9177 parallel @command{make -j@var{N}}, so be sure they are prepared for
9178 concurrent execution.
9181 @c Keep in sync with 'parallel-tests-extra-programs.test'.
9182 The combination of lazy test execution and correct dependencies between
9183 tests and their sources may be exploited for efficient unit testing
9184 during development. To further speed up the edit-compile-test cycle, it
9185 may even be useful to specify compiled programs in @code{EXTRA_PROGRAMS}
9186 instead of with @code{check_PROGRAMS}, as the former allows intertwined
9187 compilation and test execution (but note that @code{EXTRA_PROGRAMS} are
9188 not cleaned automatically, @pxref{Uniform}).
9190 The variables @code{TESTS} and @code{XFAIL_TESTS} may contain
9191 conditional parts as well as configure substitutions. In the latter
9192 case, however, certain restrictions apply: substituted test names
9193 must end with a nonempty test suffix like @file{.test}, so that one of
9194 the inference rules generated by @command{automake} can apply. For
9195 literal test names, @command{automake} can generate per-target rules
9196 to avoid this limitation.
9198 Please note that it is currently not possible to use @code{$(srcdir)/}
9199 or @code{$(top_srcdir)/} in the @code{TESTS} variable. This technical
9200 limitation is necessary to avoid generating test logs in the source tree
9201 and has the unfortunate consequence that it is not possible to specify
9202 distributed tests that are themselves generated by means of explicit
9203 rules, in a way that is portable to all @command{make} implementations
9204 (@pxref{Make Target Lookup,,, autoconf, The Autoconf Manual}, the
9205 semantics of FreeBSD and OpenBSD @command{make} conflict with this).
9206 In case of doubt you may want to require to use GNU @command{make},
9207 or work around the issue with inference rules to generate the tests.
9209 @node Custom Test Drivers
9210 @section Custom Test Drivers
9213 * Overview of Custom Test Drivers Support::
9214 * Declaring Custom Test Drivers::
9215 * API for Custom Test Drivers::
9218 @node Overview of Custom Test Drivers Support
9219 @subsection Overview of Custom Test Drivers Support
9221 Starting from Automake version 1.12, the parallel test harness allows
9222 the package authors to use third-party custom test drivers, in case the
9223 default ones are inadequate for their purposes, or do not support their
9224 testing protocol of choice.
9226 A custom test driver is expected to properly run the test programs passed
9227 to it (including the command-line arguments passed to those programs, if
9228 any), to analyze their execution and outcome, to create the @file{.log}
9229 and @file{.trs} files associated to these test runs, and to display the test
9230 results on the console. It is responsibility of the author of the test
9231 driver to ensure that it implements all the above steps meaningfully and
9232 correctly; Automake isn't and can't be of any help here. On the other
9233 hand, the Automake-provided code for testsuite summary generation offers
9234 support for test drivers allowing several test results per test script,
9235 if they take care to register such results properly (@pxref{Log files
9236 generation and test results recording}).
9238 The exact details of how test scripts' results are to be determined and
9239 analyzed is left to the individual drivers. Some drivers might only
9240 consider the test script exit status (this is done for example by the
9241 default test driver used by the parallel test harness, described
9242 in the previous section). Other drivers might implement more complex and
9243 advanced test protocols, which might require them to parse and interpreter
9244 the output emitted by the test script they're running (examples of such
9245 protocols are TAP and SubUnit).
9247 It's very important to note that, even when using custom test drivers,
9248 most of the infrastructure described in the previous section about the
9249 parallel harness remains in place; this includes:
9253 list of test scripts defined in @code{TESTS}, and overridable at
9254 runtime through the redefinition of @code{TESTS} or @code{TEST_LOGS};
9256 concurrency through the use of @command{make}'s option @option{-j};
9258 per-test @file{.log} and @file{.trs} files, and generation of a summary
9259 @file{.log} file from them;
9261 @code{recheck} target, @code{RECHECK_LOGS} variable, and lazy reruns
9264 inter-test dependencies;
9266 support for @code{check_*} variables (@code{check_PROGRAMS},
9267 @code{check_LIBRARIES}, ...);
9269 use of @code{VERBOSE} environment variable to get verbose output on
9272 definition and honoring of @code{TESTS_ENVIRONMENT},
9273 @code{AM_TESTS_ENVIRONMENT} and @code{AM_TESTS_FD_REDIRECT}
9276 definition of generic and extension-specific @code{LOG_COMPILER} and
9277 @code{LOG_FLAGS} variables.
9281 On the other hand, the exact semantics of how (and if) testsuite output
9282 colorization, @code{XFAIL_TESTS}, and hard errors are supported and
9283 handled is left to the individual test drivers.
9285 @c TODO: We should really add a working example in the doc/ directory,
9286 @c TODO: and reference if from here.
9288 @node Declaring Custom Test Drivers
9289 @subsection Declaring Custom Test Drivers
9292 @vindex _LOG_DRIVER_FLAGS
9294 @vindex LOG_DRIVER_FLAGS
9295 @vindex @var{ext}_LOG_DRIVER
9296 @vindex @var{ext}_LOG_DRIVER_FLAGS
9297 @vindex AM_@var{ext}_LOG_DRIVER_FLAGS
9298 @vindex AM_LOG_DRIVER_FLAGS
9299 Custom testsuite drivers are declared by defining the make variables
9300 @code{LOG_DRIVER} or @code{@var{ext}_LOG_DRIVER} (where @var{ext} must
9301 be declared in @code{TEST_EXTENSIONS}). They must be defined to
9302 programs or scripts that will be used to drive the execution, logging,
9303 and outcome report of the tests with corresponding extensions (or of
9304 those with no registered extension in the case of @code{LOG_DRIVER}).
9305 Clearly, multiple distinct test drivers can be declared in the same
9306 @file{Makefile.am}. Note moreover that the @code{LOG_DRIVER} variables
9307 are @emph{not} a substitute for the @code{LOG_COMPILER} variables: the
9308 two sets of variables can, and often do, usefully and legitimately
9311 @c TODO: We should really be able to point to a clarifying example here!
9313 The developer-reserved variable @code{AM_LOG_DRIVER_FLAGS} and the
9314 user-reserved variable @code{LOG_DRIVER_FLAGS} can be used to define
9315 flags that will be passed to each invocation of @code{LOG_DRIVER},
9316 with the user-defined flags obviously taking precedence over the
9317 developer-reserved ones. Similarly, for each extension @var{ext}
9318 declared in @code{TEST_EXTENSIONS}, flags listed in
9319 @code{AM_@var{ext}_LOG_DRIVER_FLAGS} and
9320 @code{@var{ext}_LOG_DRIVER_FLAGS} will be passed to
9321 invocations of @code{@var{ext}_LOG_DRIVER}.
9323 @node API for Custom Test Drivers
9324 @subsection API for Custom Test Drivers
9326 Note that @emph{the APIs described here are still highly experimental},
9327 and will very likely undergo tightenings and likely also extensive changes
9328 in the future, to accommodate for new features or to satisfy additional
9329 portability requirements.
9331 The main characteristic of these APIs is that they are designed to share
9332 as much infrastructure, semantics, and implementation details as possible
9333 with the parallel test harness and its default driver.
9336 * Command-line arguments for test drivers::
9337 * Log files generation and test results recording::
9338 * Testsuite progress output::
9341 @node Command-line arguments for test drivers
9342 @subsubsection Command-line arguments for test drivers
9344 A custom driver can rely on various command-line options and arguments
9345 being passed to it automatically by the Automake-generated test harness.
9346 It is @emph{mandatory} that it understands all of them (even if the exact
9347 interpretation of the associated semantics can legitimately change
9348 between a test driver and another, and even be a no-op in some drivers).
9351 Here is the list of options:
9354 @item --test-name=@var{NAME}
9355 The name of the test, with VPATH prefix (if any) removed. This can have a
9356 suffix and a directory component (as in e.g., @file{sub/foo.test}), and is
9357 mostly meant to be used in console reports about testsuite advancements and
9358 results (@pxref{Testsuite progress output}).
9359 @item --log-file=@file{@var{PATH}.log}
9360 The @file{.log} file the test driver must create (@pxref{Basics of
9361 test metadata}). If it has a directory component (as in e.g.,
9362 @file{sub/foo.log}), the test harness will ensure that such directory
9363 exists @emph{before} the test driver is called.
9364 @item --trs-file=@file{@var{PATH}.trs}
9365 The @file{.trs} file the test driver must create (@pxref{Basics of
9366 test metadata}). If it has a directory component (as in e.g.,
9367 @file{sub/foo.trs}), the test harness will ensure that such directory
9368 exists @emph{before} the test driver is called.
9369 @item --color-tests=@{yes|no@}
9370 Whether the console output should be colorized or not (@pxref{Simple
9371 tests and color-tests}, to learn when this option gets activated and
9373 @item --expect-failure=@{yes|no@}
9374 Whether the tested program is expected to fail.
9375 @item --enable-hard-errors=@{yes|no@}
9376 Whether ``hard errors'' in the tested program should be treated differently
9377 from normal failures or not (the default should be @code{yes}). The exact
9378 meaning of ``hard error'' is highly dependent from the test protocols or
9381 Explicitly terminate the list of options.
9385 The first non-option argument passed to the test driver is the program to
9386 be run, and all the following ones are command-line options and arguments
9389 Note that the exact semantics attached to the @option{--color-tests},
9390 @option{--expect-failure} and @option{--enable-hard-errors} options are
9391 left up to the individual test drivers. Still, having a behaviour
9392 compatible or at least similar to that provided by the default driver
9393 is advised, as that would offer a better consistency and a more pleasant
9396 @node Log files generation and test results recording
9397 @subsubsection Log files generation and test results recording
9399 The test driver must correctly generate the files specified by the
9400 @option{--log-file} and @option{--trs-file} option (even when the tested
9401 program fails or crashes).
9403 The @file{.log} file should ideally contain all the output produced by the
9404 tested program, plus optionally other information that might facilitate
9405 debugging or analysis of bug reports. Apart from that, its format is
9408 The @file{.trs} file is used to register some metadata through the use
9409 of custom reStructuredText fields. This metadata is expected to be
9410 employed in various ways by the parallel test harness; for example, to
9411 count the test results when printing the testsuite summary, or to decide
9412 which tests to re-run upon @command{make reheck}. Unrecognized metadata
9413 in a @file{.trs} file is currently ignored by the harness, but this might
9414 change in the future. The list of currently recognized metadata follows.
9419 @cindex Register test result
9420 @cindex Register test case result
9421 @cindex Test result, registering
9422 @cindex Test case result, registering
9423 @cindex @code{:test-result:}
9424 @cindex reStructuredText field, @code{:test-result:}
9425 The test driver must use this field to register the results of @emph{each}
9426 test case run by a test script file. Several @code{:test-result:} fields
9427 can be present in the same @file{.trs} file; this is done in order to
9428 support test protocols that allow a single test script to run more test
9431 @c Keep this in sync with lib/am/check-am:$(TEST_SUITE_LOG).
9432 The only recognized test results are currently @code{PASS}, @code{XFAIL},
9433 @code{SKIP}, @code{FAIL}, @code{XPASS} and @code{ERROR}. These results,
9434 when declared with @code{:test-result:}, can be optionally followed by
9435 text holding the name and/or a brief description of the corresponding
9436 test; the harness will ignore such extra text when generating
9437 @file{test-suite.log} and preparing the testsuite summary.
9439 @c Keep in sync with 'test-metadata-recheck.test'.
9440 @item @code{:recheck:}
9442 @cindex reStructuredText field, @code{:recheck:}
9443 If this field is present and defined to @code{no}, then the corresponding
9444 test script will @emph{not} be run upon a @command{make recheck}. What
9445 happens when two or more @code{:recheck:} fields are present in the same
9446 @file{.trs} file is undefined behaviour.
9448 @c Keep in sync with 'test-metadata-global-log.test'.
9449 @item @code{:copy-in-global-log:}
9450 @cindex :copy-in-global-log:
9451 @cindex reStructuredText field, @code{:copy-in-global-log:}
9452 If this field is present and defined to @code{no}, then the content
9453 of the @file{.log} file will @emph{not} be copied into the global
9454 @file{test-suite.log}. We allow to forsake such copying because, while
9455 it can be useful in debugging and analysis of bug report, it can also be
9456 just a waste of space in normal situations, e.g., when a test script is
9457 successful. What happens when two or more @code{:copy-in-global-log:}
9458 fields are present in the same @file{.trs} file is undefined behaviour.
9460 @c Keep in sync with 'test-metadata-global-result.test'.
9461 @item @code{:test-global-result:}
9462 @cindex :test-global-result:
9463 @cindex reStructuredText field, @code{:test-global-result:}
9464 This is used to declare the "global result" of the script. Currently,
9465 the value of this field is needed only to be reported (more or less
9466 verbatim) in the generated global log file @code{$(TEST_SUITE_LOG)},
9467 so it's quite free-form. For example, a test script which run 10 test
9468 cases, 6 of which pass and 4 of which are skipped, could reasonably have
9469 a @code{PASS/SKIP} value for this field, while a test script which run
9470 19 successful tests and one failed test could have an @code{ALMOST
9471 PASSED} value. What happens when two or more @code{:test-global-result:}
9472 fields are present in the same @file{.trs} file is undefined behaviour.
9476 Let's see a small example. Assume a @file{.trs} file contains the
9480 :test-result: PASS server starts
9481 :global-log-copy: no
9482 :test-result: PASS HTTP/1.1 request
9483 :test-result: FAIL HTTP/1.0 request
9485 :test-result: SKIP HTTPS request (TLS library wasn't available)
9486 :test-result: PASS server stops
9490 Then the corresponding test script will be re-run by @command{make check},
9491 will contribute with @emph{five} test results to the testsuite summary
9492 (three of these tests being successful, one failed, and one skipped), and
9493 the content of the corresponding @file{.log} file will @emph{not} be
9494 copied in the global log file @file{test-suite.log}.
9496 @node Testsuite progress output
9497 @subsubsection Testsuite progress output
9499 A custom test driver also has the task of displaying, on the standard
9500 output, the test results as soon as they become available. Depending on
9501 the protocol in use, it can also display the reasons for failures and
9502 skips, and, more generally, any useful diagnostic output (but remember
9503 that each line on the screen is precious, so that cluttering the screen
9504 with overly verbose information is bad idea). The exact format of this
9505 progress output is left up to the test driver; in fact, a custom test
9506 driver might @emph{theoretically} even decide not to do any such report,
9507 leaving it all to the testsuite summary (that would be a very lousy idea,
9508 of course, and serves only to illustrate the flexibility that is
9511 Remember that consistency is good; so, if possible, try to be consistent
9512 with the output of the built-in Automake test drivers, providing a similar
9513 ``look & feel''. In particular, the testsuite progress output should be
9514 colorized when the @option{--color-tests} is passed to the driver. On the
9515 other end, if you are using a known and widespread test protocol with
9516 well-established implementations, being consistent with those
9517 implementations' output might be a good idea too.
9519 @c TODO: Give an example, maybe inspired to py.test-style output.
9520 @c TODO: That is a good idea because it shows a test driver that allows
9521 @c TODO: for different levels of verbosity in the progress output (could
9522 @c TODO: be implemented either using a driver cmdline flag, or an
9523 @c TODO: environment variable, or both).
9525 @node Using the TAP test protocol
9526 @section Using the TAP test protocol
9529 * Introduction to TAP::
9530 * Use TAP with the Automake test harness::
9531 * Incompatibilities with other TAP parsers and drivers::
9532 * Links and external resources on TAP::
9535 @node Introduction to TAP
9536 @subsection Introduction to TAP
9538 TAP, the Test Anything Protocol, is a simple text-based interface between
9539 testing modules or programs and a test harness. The tests (also called
9540 ``TAP producers'' in this context) write test results in a simple format
9541 on standard output; a test harness (also called ``TAP consumer'') will
9542 parse and interpret these results, and properly present them to the user,
9543 and/or register them for later analysis. The exact details of how this
9544 is accomplished can vary among different test harnesses. The Automake
9545 harness will present the results on the console in the usual
9546 fashion (@pxref{Testsuite progress on console}), and will use the
9547 @file{.trs} files (@pxref{Basics of test metadata}) to store the test
9548 results and related metadata. Apart from that, it will try to remain
9549 as much compatible as possible with pre-existing and widespread utilities,
9550 such as the @uref{http://search.cpan.org/~andya/Test-Harness/bin/prove,
9551 @command{prove} utility}, at least for the simpler usages.
9553 TAP started its life as part of the test harness for Perl, but today
9554 it has been (mostly) standardized, and has various independent
9555 implementations in different languages; among them, C, C++, Perl,
9556 Python, PHP, and Java. For a semi-official specification of the
9557 TAP protocol, please refer to the documentation of
9558 @uref{http://search.cpan.org/~petdance/Test-Harness/lib/Test/Harness/TAP.pod,
9559 @samp{Test::Harness::TAP}}.
9561 The most relevant real-world usages of TAP are obviously in the testsuites
9562 of @command{perl} and of many perl modules. Still, also other important
9563 third-party packages, such as @uref{http://git-scm.com/, @command{git}},
9564 use TAP in their testsuite.
9566 @node Use TAP with the Automake test harness
9567 @subsection Use TAP with the Automake test harness
9569 Currently, the TAP driver that comes with Automake requires some by-hand
9570 steps on the developer's part (this situation should hopefully be improved
9571 in future Automake versions). You'll have to grab the @file{tap-driver.sh}
9572 script from the Automake distribution by hand, copy it in your source tree,
9573 add a call to @code{AC_PROG_AWK} in @file{configure.ac} to search for a
9574 proper awk program, and use the Automake support for third-party test
9575 drivers to instruct the harness to use the @file{tap-driver.sh} script
9576 and that awk program to run your TAP-producing tests. See the example
9577 below for clarification.
9579 Apart from the options common to all the Automake test drivers
9580 (@pxref{Command-line arguments for test drivers}), the @file{tap-driver.sh}
9581 supports the following options, whose names are chosen for enhanced
9582 compatibility with the @command{prove} utility.
9585 @c Keep in sync with 'tap-exit.test' and 'tap-signal.tap'.
9587 Causes the test driver to ignore the exit status of the test scripts;
9588 by default, the driver will report an error if the script exits with a
9589 non-zero status. This option has effect also on non-zero exit statuses
9590 due to termination by a signal.
9592 Instruct the test driver to display TAP diagnostic (i.e., lines beginning
9593 with the @samp{#} character) in the testsuite progress output too; by
9594 default, TAP diagnostic is only copied to the @file{.log} file.
9596 Revert the effects of @option{--comments}.
9598 Instruct the test driver to merge the test scripts' standard error into
9599 their standard output. This is necessary if you want to ensure that
9600 diagnostics from the test scripts are displayed in the correct order
9601 relative to test results; this can be of great help in debugging
9602 (especially if your test scripts are shell scripts run with shell
9603 tracing active). As a downside, this option might cause the test
9604 harness to get confused if anything that appears on standard error
9605 looks like a test result.
9607 Revert the effects of @option{--merge}.
9608 @item --diagnostic-string=@var{STRING}
9609 Change the string that introduces TAP diagnostic from the default value
9610 of ``@code{#}'' to @code{@var{STRING}}. This can be useful if your
9611 TAP-based test scripts produce verbose output on which they have limited
9612 control (because, say, the output comes from other tools invoked in the
9613 scripts), and it might contain text that gets spuriously interpreted as
9614 TAP diagnostic: such an issue can be solved by redefining the string that
9615 activates TAP diagnostic to a value you know won't appear by chance in
9616 the tests' output. Note however that this feature is non-standard, as
9617 the ``official'' TAP protocol does not allow for such a customization; so
9618 don't use it if you can avoid it.
9622 Here is an example of how the TAP driver can be set up and used.
9624 @c Keep in sync with tap-doc2.sh
9626 % @kbd{cat configure.ac}
9627 AC_INIT([GNU Try Tap], [1.0], [bug-automake@@gnu.org])
9628 AC_CONFIG_AUX_DIR([build-aux])
9629 AM_INIT_AUTOMAKE([foreign -Wall -Werror])
9630 AC_CONFIG_FILES([Makefile])
9631 AC_REQUIRE_AUX_FILE([tap-driver.sh])
9635 % @kbd{cat Makefile.am}
9636 TEST_LOG_DRIVER = env AM_TAP_AWK='$(AWK)' $(SHELL) \
9637 $(top_srcdir)/build-aux/tap-driver.sh
9638 TESTS = foo.test bar.test baz.test
9639 EXTRA_DIST = $(TESTS)
9641 % @kbd{cat foo.test}
9643 echo 1..4 # Number of tests to be executed.
9644 echo 'ok 1 - Swallows fly'
9645 echo 'not ok 2 - Caterpillars fly # TODO metamorphosis in progress'
9646 echo 'ok 3 - Pigs fly # SKIP not enough acid'
9647 echo '# I just love word plays ...'
9648 echo 'ok 4 - Flies fly too :-)'
9650 % @kbd{cat bar.test}
9653 echo 'not ok 1 - Bummer, this test has failed.'
9654 echo 'ok 2 - This passed though.'
9655 echo 'Bail out! Ennui kicking in, sorry...'
9656 echo 'ok 3 - This will not be seen.'
9658 % @kbd{cat baz.test}
9662 # Exit with error, even if all the tests have been successful.
9665 % @kbd{cp @var{PREFIX}/share/automake-@var{APIVERSION}/tap-driver.pl .}
9666 % @kbd{autoreconf -vi && ./configure && make check}
9668 PASS: foo.test 1 - Swallows fly
9669 XFAIL: foo.test 2 - Caterpillars fly # TODO metamorphosis in progress
9670 SKIP: foo.test 3 - Pigs fly # SKIP not enough acid
9671 PASS: foo.test 4 - Flies fly too :-)
9672 FAIL: bar.test 1 - Bummer, this test has failed.
9673 PASS: bar.test 2 - This passed though.
9674 ERROR: bar.test - Bail out! Ennui kicking in, sorry...
9676 ERROR: baz.test - exited with status 7
9678 Please report to bug-automake@@gnu.org
9680 % @kbd{echo exit status: $?}
9683 @c Keep the "skewed" indentation below, it produces pretty PDF output.
9684 % @kbd{env TEST_LOG_DRIVER_FLAGS='--comments --ignore-exit' \
9685 TESTS='foo.test baz.test' make -e check}
9687 PASS: foo.test 1 - Swallows fly
9688 XFAIL: foo.test 2 - Caterpillars fly # TODO metamorphosis in progress
9689 SKIP: foo.test 3 - Pigs fly # SKIP not enough acid
9690 # foo.test: I just love word plays...
9691 PASS: foo.test 4 - Flies fly too :-)
9694 % @kbd{echo exit status: $?}
9698 @node Incompatibilities with other TAP parsers and drivers
9699 @subsection Incompatibilities with other TAP parsers and drivers
9701 For implementation or historical reasons, the TAP driver and harness as
9702 implemented by Automake have some minors incompatibilities with the
9703 mainstream versions, which you should be aware of.
9707 A @code{Bail out!} directive doesn't stop the whole testsuite, but only
9708 the test script it occurs in. This doesn't follow TAP specifications,
9709 but on the other hand it maximizes compatibility (and code sharing) with
9710 the ``hard error'' concept of the default testsuite driver.
9712 The @code{version} and @code{pragma} directives are not supported.
9714 The @option{--diagnostic-string} option of our driver allows to modify
9715 the string that introduces TAP diagnostic from the default value
9716 of ``@code{#}''. The standard TAP protocol has currently no way to
9717 allow this, so if you use it your diagnostic will be lost to more
9718 compliant tools like @command{prove} and @code{Test::Harness}
9720 And there are probably some other small and yet undiscovered
9721 incompatibilities, especially in corner cases or with rare usages.
9724 @node Links and external resources on TAP
9725 @subsection Links and external resources on TAP
9728 Here are some links to more extensive official or third-party
9729 documentation and resources about the TAP protocol and related
9730 tools and libraries.
9733 @uref{http://search.cpan.org/~petdance/Test-Harness/lib/Test/Harness/TAP.pod,
9734 @samp{Test::Harness::TAP}},
9735 the (mostly) official documentation about the TAP format and protocol.
9737 @uref{http://search.cpan.org/~andya/Test-Harness/bin/prove,
9739 the most famous command-line TAP test driver, included in the distribution
9740 of @command{perl} and
9741 @uref{http://search.cpan.org/~andya/Test-Harness/lib/Test/Harness.pm,
9742 @samp{Test::Harness}}.
9744 The @uref{http://testanything.org/wiki/index.php/Main_Page,TAP wiki}.
9746 A ``gentle introduction'' to testing for perl coders:
9747 @uref{http://search.cpan.org/dist/Test-Simple/lib/Test/Tutorial.pod,
9748 @samp{Test::Tutorial}}.
9750 @uref{http://search.cpan.org/~mschwern/Test-Simple/lib/Test/Simple.pm,
9751 @samp{Test::Simple}}
9753 @uref{http://search.cpan.org/~mschwern/Test-Simple/lib/Test/More.pm,
9755 the standard perl testing libraries, which are based on TAP.
9757 @uref{http://www.eyrie.org/~eagle/software/c-tap-harness/,C TAP Harness},
9758 a C-based project implementing both a TAP producer and a TAP consumer.
9760 @uref{http://www.tap4j.org/,tap4j},
9761 a Java-based project implementing both a TAP producer and a TAP consumer.
9765 @section DejaGnu Tests
9767 If @uref{ftp://ftp.gnu.org/gnu/dejagnu/, @command{dejagnu}} appears in
9768 @code{AUTOMAKE_OPTIONS}, then a @command{dejagnu}-based test suite is
9769 assumed. The variable @code{DEJATOOL} is a list of names that are
9770 passed, one at a time, as the @option{--tool} argument to
9771 @command{runtest} invocations; it defaults to the name of the package.
9773 The variable @code{RUNTESTDEFAULTFLAGS} holds the @option{--tool} and
9774 @option{--srcdir} flags that are passed to dejagnu by default; this can be
9775 overridden if necessary.
9776 @vindex RUNTESTDEFAULTFLAGS
9778 The variables @code{EXPECT} and @code{RUNTEST} can
9779 also be overridden to provide project-specific values. For instance,
9780 you will need to do this if you are testing a compiler toolchain,
9781 because the default values do not take into account host and target
9788 The contents of the variable @code{RUNTESTFLAGS} are passed to the
9789 @code{runtest} invocation. This is considered a ``user variable''
9790 (@pxref{User Variables}). If you need to set @command{runtest} flags in
9791 @file{Makefile.am}, you can use @code{AM_RUNTESTFLAGS} instead.
9792 @vindex RUNTESTFLAGS
9793 @vindex AM_RUNTESTFLAGS
9795 @cindex @file{site.exp}
9796 Automake will generate rules to create a local @file{site.exp} file,
9797 defining various variables detected by @command{configure}. This file
9798 is automatically read by DejaGnu. It is OK for the user of a package
9799 to edit this file in order to tune the test suite. However this is
9800 not the place where the test suite author should define new variables:
9801 this should be done elsewhere in the real test suite code.
9802 Especially, @file{site.exp} should not be distributed.
9804 Still, if the package author has legitimate reasons to extend
9805 @file{site.exp} at @command{make} time, he can do so by defining
9806 the variable @code{EXTRA_DEJAGNU_SITE_CONFIG}; the files listed
9807 there will be considered @file{site.exp} prerequisites, and their
9808 content will be appended to it (in the same order in which they
9809 appear in @code{EXTRA_DEJAGNU_SITE_CONFIG}). Note that files are
9810 @emph{not} distributed by default.
9812 For more information regarding DejaGnu test suites, see @ref{Top, , ,
9813 dejagnu, The DejaGnu Manual}.
9816 @section Install Tests
9818 The @code{installcheck} target is available to the user as a way to
9819 run any tests after the package has been installed. You can add tests
9820 to this by writing an @code{installcheck-local} rule.
9824 @chapter Rebuilding Makefiles
9825 @cindex rebuild rules
9827 Automake generates rules to automatically rebuild @file{Makefile}s,
9828 @file{configure}, and other derived files like @file{Makefile.in}.
9830 @acindex AM_MAINTAINER_MODE
9831 If you are using @code{AM_MAINTAINER_MODE} in @file{configure.ac}, then
9832 these automatic rebuilding rules are only enabled in maintainer mode.
9834 @vindex CONFIG_STATUS_DEPENDENCIES
9835 @vindex CONFIGURE_DEPENDENCIES
9836 @cindex @file{version.sh}, example
9837 @cindex @file{version.m4}, example
9839 Sometimes it is convenient to supplement the rebuild rules for
9840 @file{configure} or @file{config.status} with additional dependencies.
9841 The variables @code{CONFIGURE_DEPENDENCIES} and
9842 @code{CONFIG_STATUS_DEPENDENCIES} can be used to list these extra
9843 dependencies. These variables should be defined in all
9844 @file{Makefile}s of the tree (because these two rebuild rules are
9845 output in all them), so it is safer and easier to @code{AC_SUBST} them
9846 from @file{configure.ac}. For instance, the following statement will
9847 cause @file{configure} to be rerun each time @file{version.sh} is
9851 AC_SUBST([CONFIG_STATUS_DEPENDENCIES], ['$(top_srcdir)/version.sh'])
9855 Note the @samp{$(top_srcdir)/} in the file name. Since this variable
9856 is to be used in all @file{Makefile}s, its value must be sensible at
9857 any level in the build hierarchy.
9859 Beware not to mistake @code{CONFIGURE_DEPENDENCIES} for
9860 @code{CONFIG_STATUS_DEPENDENCIES}.
9862 @code{CONFIGURE_DEPENDENCIES} adds dependencies to the
9863 @file{configure} rule, whose effect is to run @command{autoconf}. This
9864 variable should be seldom used, because @command{automake} already tracks
9865 @code{m4_include}d files. However it can be useful when playing
9866 tricky games with @code{m4_esyscmd} or similar non-recommendable
9867 macros with side effects.
9869 @code{CONFIG_STATUS_DEPENDENCIES} adds dependencies to the
9870 @file{config.status} rule, whose effect is to run @file{configure}.
9871 This variable should therefore carry any non-standard source that may
9872 be read as a side effect of running @command{configure}, like @file{version.sh}
9873 in the example above.
9875 Speaking of @file{version.sh} scripts, we recommend against them
9876 today. We recommend that @file{version.sh} be replaced by an M4 file
9877 that is included by @file{configure.ac}:
9880 m4_include([version.m4])
9881 AC_INIT([name], VERSION_NUMBER)
9887 Here @file{version.m4} could contain something like
9888 @samp{m4_define([VERSION_NUMBER], [1.2])}. The advantage of this
9889 second form is that @command{automake} will take care of the
9890 dependencies when defining the rebuild rule, and will also distribute
9891 the file automatically.
9895 @chapter Changing Automake's Behavior
9898 * Options generalities:: Semantics of Automake option
9899 * List of Automake options:: A comprehensive list of Automake options
9902 @node Options generalities
9903 @section Options generalities
9905 Various features of Automake can be controlled by options. Except where
9906 noted otherwise, options can be specified in one of several ways. Most
9907 options can be applied on a per-@file{Makefile} basis when listed in a
9908 special @file{Makefile} variable named @code{AUTOMAKE_OPTIONS}. Some
9909 of these options only make sense when specified in the toplevel
9910 @file{Makefile.am} file. Options are applied globally to all processed
9911 @file{Makefile} files when listed in the first argument of
9912 @code{AM_INIT_AUTOMAKE} in @file{configure.ac}, and some options which
9913 require changes to the @command{configure} script can only be specified
9914 there. These are annotated below.
9916 As a general rule, options specified in @code{AUTOMAKE_OPTIONS} take
9917 precedence over those specified in @code{AM_INIT_AUTOMAKE}, which in
9918 turn take precedence over those specified on the command line.
9920 Also, some care must be taken about the interactions among strictness
9921 level and warning categories. As a general rule, strictness-implied
9922 warnings are overridden by those specified by explicit options. For
9923 example, even if @samp{portability} warnings are disabled by default
9924 in @option{foreign} strictness, an usage like this will end up enabling
9928 AUTOMAKE_OPTIONS = -Wportability foreign
9931 However, a strictness level specified in a higher-priority context
9932 will override all the explicit warnings specified in a lower-priority
9933 context. For example, if @file{configure.ac} contains:
9936 AM_INIT_AUTOMAKE([-Wportability])
9940 and @file{Makefile.am} contains:
9943 AUTOMAKE_OPTIONS = foreign
9947 then @samp{portability} warnings will be @emph{disabled} in
9950 @node List of Automake options
9951 @section List of Automake options
9953 @vindex AUTOMAKE_OPTIONS
9956 @item @option{gnits}
9958 @itemx @option{foreign}
9959 @cindex Option, @option{gnits}
9960 @cindex Option, @option{gnu}
9961 @cindex Option, @option{foreign}
9966 Set the strictness as appropriate. The @option{gnits} option also
9967 implies options @option{readme-alpha} and @option{check-news}.
9969 @item @option{check-news}
9970 @cindex Option, @option{check-news}
9972 Cause @samp{make dist} to fail unless the current version number appears
9973 in the first few lines of the @file{NEWS} file.
9975 @item @option{dejagnu}
9976 @cindex Option, @option{dejagnu}
9978 Cause @command{dejagnu}-specific rules to be generated. @xref{DejaGnu Tests}.
9980 @item @option{dist-bzip2}
9981 @cindex Option, @option{dist-bzip2}
9983 Hook @code{dist-bzip2} to @code{dist}.
9986 @item @option{dist-lzip}
9987 @cindex Option, @option{dist-lzip}
9989 Hook @code{dist-lzip} to @code{dist}.
9992 @item @option{dist-shar}
9993 @cindex Option, @option{dist-shar}
9995 Hook @code{dist-shar} to @code{dist}.
9998 @item @option{dist-zip}
9999 @cindex Option, @option{dist-zip}
10001 Hook @code{dist-zip} to @code{dist}.
10004 @item @option{dist-tarZ}
10005 @cindex Option, @option{dist-tarZ}
10007 Hook @code{dist-tarZ} to @code{dist}.
10010 @item @option{filename-length-max=99}
10011 @cindex Option, @option{filename-length-max=99}
10012 @opindex filename-length-max=99
10013 Abort if file names longer than 99 characters are found during
10014 @samp{make dist}. Such long file names are generally considered not to
10015 be portable in tarballs. See the @option{tar-v7} and @option{tar-ustar}
10016 options below. This option should be used in the top-level
10017 @file{Makefile.am} or as an argument of @code{AM_INIT_AUTOMAKE} in
10018 @file{configure.ac}, it will be ignored otherwise. It will also be
10019 ignored in sub-packages of nested packages (@pxref{Subpackages}).
10021 @item @option{no-define}
10022 @cindex Option, @option{no-define}
10024 This option is meaningful only when passed as an argument to
10025 @code{AM_INIT_AUTOMAKE}. It will prevent the @code{PACKAGE} and
10026 @code{VERSION} variables from being @code{AC_DEFINE}d.
10028 @item @option{no-dependencies}
10029 @cindex Option, @option{no-dependencies}
10030 @opindex no-dependencies
10031 This is similar to using @option{--ignore-deps} on the command line,
10032 but is useful for those situations where you don't have the necessary
10033 bits to make automatic dependency tracking work
10034 (@pxref{Dependencies}). In this case the effect is to effectively
10035 disable automatic dependency tracking.
10037 @item @option{no-dist}
10038 @cindex Option, @option{no-dist}
10040 Don't emit any code related to @code{dist} target. This is useful
10041 when a package has its own method for making distributions.
10043 @item @option{no-dist-gzip}
10044 @cindex Option, @option{no-dist-gzip}
10045 @opindex no-dist-gzip
10046 Do not hook @code{dist-gzip} to @code{dist}.
10047 @trindex no-dist-gzip
10049 @item @option{no-exeext}
10050 @cindex Option, @option{no-exeext}
10052 If your @file{Makefile.am} defines a rule for target @code{foo}, it
10053 will override a rule for a target named @samp{foo$(EXEEXT)}. This is
10054 necessary when @code{EXEEXT} is found to be empty. However, by
10055 default @command{automake} will generate an error for this use. The
10056 @option{no-exeext} option will disable this error. This is intended for
10057 use only where it is known in advance that the package will not be
10058 ported to Windows, or any other operating system using extensions on
10061 @item @option{no-installinfo}
10062 @cindex Option, @option{no-installinfo}
10063 @opindex no-installinfo
10064 The generated @file{Makefile.in} will not cause info pages to be built
10065 or installed by default. However, @code{info} and @code{install-info}
10066 targets will still be available. This option is disallowed at
10067 @option{gnu} strictness and above.
10069 @trindex install-info
10071 @item @option{no-installman}
10072 @cindex Option, @option{no-installman}
10073 @opindex no-installman
10074 The generated @file{Makefile.in} will not cause man pages to be
10075 installed by default. However, an @code{install-man} target will still
10076 be available for optional installation. This option is disallowed at
10077 @option{gnu} strictness and above.
10078 @trindex install-man
10080 @item @option{nostdinc}
10081 @cindex Option, @option{nostdinc}
10083 This option can be used to disable the standard @option{-I} options that
10084 are ordinarily automatically provided by Automake.
10086 @item @option{no-texinfo.tex}
10087 @cindex Option, @option{no-texinfo.tex}
10088 @opindex no-texinfo.tex
10089 Don't require @file{texinfo.tex}, even if there are texinfo files in
10092 @item @option{serial-tests}
10093 @cindex Option, @option{serial-tests}
10094 @opindex serial-tests
10095 Enable the older serial test suite harness for @code{TESTS} (@pxref{Serial
10096 Test Harness}, for more information).
10098 @item @option{parallel-tests}
10099 @cindex Option, @option{parallel-tests}
10100 @opindex parallel-tests
10101 Enable test suite harness for @code{TESTS} that can run tests in parallel
10102 (@pxref{Parallel Test Harness}, for more information). This option is
10103 only kept for backward-compatibility, since the parallel test harness is
10106 @item @option{readme-alpha}
10107 @cindex Option, @option{readme-alpha}
10108 @opindex readme-alpha
10109 If this release is an alpha release, and the file @file{README-alpha}
10110 exists, then it will be added to the distribution. If this option is
10111 given, version numbers are expected to follow one of two forms. The
10112 first form is @samp{@var{major}.@var{minor}.@var{alpha}}, where each
10113 element is a number; the final period and number should be left off for
10114 non-alpha releases. The second form is
10115 @samp{@var{major}.@var{minor}@var{alpha}}, where @var{alpha} is a
10116 letter; it should be omitted for non-alpha releases.
10118 @item @option{std-options}
10119 @cindex Options, @option{std-options}
10120 @cindex @samp{make installcheck}, testing @option{--help} and @option{--version}
10121 @cindex @option{--help} check
10122 @cindex @option{--version} check
10123 @opindex std-options
10125 Make the @code{installcheck} rule check that installed scripts and
10126 programs support the @option{--help} and @option{--version} options.
10127 This also provides a basic check that the program's
10128 run-time dependencies are satisfied after installation.
10130 @vindex AM_INSTALLCHECK_STD_OPTIONS_EXEMPT
10131 In a few situations, programs (or scripts) have to be exempted from this
10132 test. For instance, @command{false} (from GNU coreutils) is never
10133 successful, even for @option{--help} or @option{--version}. You can list
10134 such programs in the variable @code{AM_INSTALLCHECK_STD_OPTIONS_EXEMPT}.
10135 Programs (not scripts) listed in this variable should be suffixed by
10136 @samp{$(EXEEXT)} for the sake of Windows or OS/2. For instance, suppose we
10137 build @file{false} as a program but @file{true.sh} as a script, and that
10138 neither of them support @option{--help} or @option{--version}:
10141 AUTOMAKE_OPTIONS = std-options
10142 bin_PROGRAMS = false ...
10143 bin_SCRIPTS = true.sh ...
10144 AM_INSTALLCHECK_STD_OPTIONS_EXEMPT = false$(EXEEXT) true.sh
10147 @item @option{subdir-objects}
10148 @cindex Options, @option{subdir-objects}
10149 @opindex subdir-objects
10150 If this option is specified, then objects are placed into the
10151 subdirectory of the build directory corresponding to the subdirectory of
10152 the source file. For instance, if the source file is
10153 @file{subdir/file.cxx}, then the output file would be
10154 @file{subdir/file.o}.
10156 In order to use this option with C sources, you should add
10157 @code{AM_PROG_CC_C_O} to @file{configure.ac}.
10159 @anchor{tar-formats}
10160 @item @option{tar-v7}
10161 @itemx @option{tar-ustar}
10162 @itemx @option{tar-pax}
10163 @cindex Option, @option{tar-v7}
10164 @cindex Option, @option{tar-ustar}
10165 @cindex Option, @option{tar-pax}
10166 @cindex @command{tar} formats
10167 @cindex v7 @command{tar} format
10168 @cindex ustar format
10174 These three mutually exclusive options select the tar format to use
10175 when generating tarballs with @samp{make dist}. (The tar file created
10176 is then compressed according to the set of @option{no-dist-gzip},
10177 @option{dist-bzip2}, @option{dist-lzip}, @option{dist-xz} and
10178 @option{dist-tarZ} options in use.)
10180 These options must be passed as arguments to @code{AM_INIT_AUTOMAKE}
10181 (@pxref{Macros}) because they can require additional configure checks.
10182 Automake will complain if it sees such options in an
10183 @code{AUTOMAKE_OPTIONS} variable.
10185 @option{tar-v7} selects the old V7 tar format. This is the historical
10186 default. This antiquated format is understood by all tar
10187 implementations and supports file names with up to 99 characters. When
10188 given longer file names some tar implementations will diagnose the
10189 problem while other will generate broken tarballs or use non-portable
10190 extensions. Furthermore, the V7 format cannot store empty
10191 directories. When using this format, consider using the
10192 @option{filename-length-max=99} option to catch file names too long.
10194 @option{tar-ustar} selects the ustar format defined by POSIX
10195 1003.1-1988. This format is believed to be old enough to be portable.
10196 It fully supports empty directories. It can store file names with up
10197 to 256 characters, provided that the file name can be split at
10198 directory separator in two parts, first of them being at most 155
10199 bytes long. So, in most cases the maximum file name length will be
10200 shorter than 256 characters. However you may run against broken tar
10201 implementations that incorrectly handle file names longer than 99
10202 characters (please report them to @email{@value{PACKAGE_BUGREPORT}} so we
10203 can document this accurately).
10205 @option{tar-pax} selects the new pax interchange format defined by POSIX
10206 1003.1-2001. It does not limit the length of file names. However,
10207 this format is very young and should probably be restricted to
10208 packages that target only very modern platforms. There are moves to
10209 change the pax format in an upward-compatible way, so this option may
10210 refer to a more recent version in the future.
10212 @xref{Formats, , Controlling the Archive Format, tar, GNU Tar}, for
10213 further discussion about tar formats.
10215 @command{configure} knows several ways to construct these formats. It
10216 will not abort if it cannot find a tool up to the task (so that the
10217 package can still be built), but @samp{make dist} will fail.
10219 @item @var{version}
10220 @cindex Option, @var{version}
10221 A version number (e.g., @samp{0.30}) can be specified. If Automake is not
10222 newer than the version specified, creation of the @file{Makefile.in}
10223 will be suppressed.
10225 @item @option{-W@var{category}} or @option{--warnings=@var{category}}
10226 @cindex Option, warnings
10227 @cindex Option, @option{-W@var{category}}
10228 @cindex Option, @option{--warnings=@var{category}}
10229 These options behave exactly like their command-line counterpart
10230 (@pxref{automake Invocation}). This allows you to enable or disable some
10231 warning categories on a per-file basis. You can also setup some warnings
10232 for your entire project; for instance, try @samp{AM_INIT_AUTOMAKE([-Wall])}
10233 in your @file{configure.ac}.
10237 Unrecognized options are diagnosed by @command{automake}.
10239 If you want an option to apply to all the files in the tree, you can use
10240 the @code{AM_INIT_AUTOMAKE} macro in @file{configure.ac}.
10244 @node Miscellaneous
10245 @chapter Miscellaneous Rules
10247 There are a few rules and variables that didn't fit anywhere else.
10250 * Tags:: Interfacing to cscope, etags and mkid
10251 * Suffixes:: Handling new file extensions
10256 @section Interfacing to @command{etags}
10258 @cindex @file{TAGS} support
10260 Automake will generate rules to generate @file{TAGS} files for use with
10261 GNU Emacs under some circumstances.
10264 If any C, C++ or Fortran 77 source code or headers are present, then
10265 @code{tags} and @code{TAGS} rules will be generated for the directory.
10266 All files listed using the @code{_SOURCES}, @code{_HEADERS}, and
10267 @code{_LISP} primaries will be used to generate tags. Note that
10268 generated source files that are not distributed must be declared in
10269 variables like @code{nodist_noinst_HEADERS} or
10270 @code{nodist_@var{prog}_SOURCES} or they will be ignored.
10272 A @code{tags} rule will be output at the topmost directory of a
10273 multi-directory package. When run from this topmost directory,
10274 @samp{make tags} will generate a @file{TAGS} file that includes by
10275 reference all @file{TAGS} files from subdirectories.
10277 The @code{tags} rule will also be generated if the variable
10278 @code{ETAGS_ARGS} is defined. This variable is intended for use in
10279 directories that contain taggable source that @command{etags} does
10280 not understand. The user can use the @code{ETAGSFLAGS} to pass
10281 additional flags to @command{etags}; @code{AM_ETAGSFLAGS} is also
10282 available for use in @file{Makefile.am}.
10285 @vindex AM_ETAGSFLAGS
10287 Here is how Automake generates tags for its source, and for nodes in its
10291 ETAGS_ARGS = automake.in --lang=none \
10292 --regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi
10295 If you add file names to @code{ETAGS_ARGS}, you will probably also
10296 want to define @code{TAGS_DEPENDENCIES}. The contents of this variable
10297 are added directly to the dependencies for the @code{tags} rule.
10298 @vindex TAGS_DEPENDENCIES
10300 Automake also generates a @code{ctags} rule that can be used to
10301 build @command{vi}-style @file{tags} files. The variable @code{CTAGS}
10302 is the name of the program to invoke (by default @command{ctags});
10303 @code{CTAGSFLAGS} can be used by the user to pass additional flags,
10304 and @code{AM_CTAGSFLAGS} can be used by the @file{Makefile.am}.
10307 Automake will also generate an @code{ID} rule that will run
10308 @command{mkid} on the source. This is only supported on a
10309 directory-by-directory basis.
10311 Similarly, the @code{cscope} rule will create a list of all the source
10312 files in the tree and run @command{cscope} to build an inverted index
10313 database. The variable @code{CSCOPE} is the name of the program to invoke
10314 (by default @command{cscope}); @code{CSCOPEFLAGS} and
10315 @code{CSCOPE_ARGS} can be used by the user to pass additional flags and
10316 file names respectively, while @code{AM_CSCOPEFLAGS} can be used by the
10317 @file{Makefile.am}. Note that, currently, the Automake-provided
10318 @code{cscope} support, when used in a VPATH build, might not work well
10319 with non-GNU make implementations (especially with make implementations
10320 performing @ref{Automatic Rule Rewriting, , VPATH rewrites, autoconf,
10321 The Autoconf Manual}).
10323 Finally, Automake also emits rules to support the
10324 @uref{http://www.gnu.org/software/global/, GNU Global Tags program}.
10325 The @code{GTAGS} rule runs Global Tags and puts the
10326 result in the top build directory. The variable @code{GTAGS_ARGS}
10327 holds arguments that are passed to @command{gtags}.
10332 @section Handling new file extensions
10334 @cindex Adding new @code{SUFFIXES}
10335 @cindex @code{SUFFIXES}, adding
10338 It is sometimes useful to introduce a new implicit rule to handle a file
10339 type that Automake does not know about.
10341 For instance, suppose you had a compiler that could compile @file{.foo}
10342 files to @file{.o} files. You would simply define a suffix rule for
10350 Then you could directly use a @file{.foo} file in a @code{_SOURCES}
10351 variable and expect the correct results:
10354 bin_PROGRAMS = doit
10355 doit_SOURCES = doit.foo
10358 This was the simpler and more common case. In other cases, you will
10359 have to help Automake to figure out which extensions you are defining your
10360 suffix rule for. This usually happens when your extension does not
10361 start with a dot. Then, all you have to do is to put a list of new
10362 suffixes in the @code{SUFFIXES} variable @strong{before} you define your
10365 For instance, the following definition prevents Automake from misinterpreting
10366 the @samp{.idlC.cpp:} rule as an attempt to transform @file{.idlC} files into
10369 @c Keep in sync with suffix7.sh
10371 SUFFIXES = .idl C.cpp
10376 As you may have noted, the @code{SUFFIXES} variable behaves like the
10377 @code{.SUFFIXES} special target of @command{make}. You should not touch
10378 @code{.SUFFIXES} yourself, but use @code{SUFFIXES} instead and let
10379 Automake generate the suffix list for @code{.SUFFIXES}. Any given
10380 @code{SUFFIXES} go at the start of the generated suffixes list, followed
10381 by Automake generated suffixes not already in the list.
10387 @cindex Including @file{Makefile} fragment
10388 @cindex @file{Makefile} fragment, including
10390 Automake supports an @code{include} directive that can be used to
10391 include other @file{Makefile} fragments when @command{automake} is run.
10392 Note that these fragments are read and interpreted by @command{automake},
10393 not by @command{make}. As with conditionals, @command{make} has no idea that
10394 @code{include} is in use.
10396 There are two forms of @code{include}:
10399 @item include $(srcdir)/file
10400 Include a fragment that is found relative to the current source
10403 @item include $(top_srcdir)/file
10404 Include a fragment that is found relative to the top source directory.
10407 Note that if a fragment is included inside a conditional, then the
10408 condition applies to the entire contents of that fragment.
10410 Makefile fragments included this way are always distributed because
10411 they are needed to rebuild @file{Makefile.in}.
10414 @chapter Conditionals
10416 @cindex Conditionals
10418 Automake supports a simple type of conditionals.
10420 These conditionals are not the same as conditionals in
10421 GNU Make. Automake conditionals are checked at configure time by the
10422 @file{configure} script, and affect the translation from
10423 @file{Makefile.in} to @file{Makefile}. They are based on options passed
10424 to @file{configure} and on results that @file{configure} has discovered
10425 about the host system. GNU Make conditionals are checked at @command{make}
10426 time, and are based on variables passed to the make program or defined
10427 in the @file{Makefile}.
10429 Automake conditionals will work with any make program.
10432 * Usage of Conditionals:: Declaring conditional content
10433 * Limits of Conditionals:: Enclosing complete statements
10436 @node Usage of Conditionals
10437 @section Usage of Conditionals
10439 @acindex AM_CONDITIONAL
10440 Before using a conditional, you must define it by using
10441 @code{AM_CONDITIONAL} in the @file{configure.ac} file (@pxref{Macros}).
10443 @defmac AM_CONDITIONAL (@var{conditional}, @var{condition})
10444 The conditional name, @var{conditional}, should be a simple string
10445 starting with a letter and containing only letters, digits, and
10446 underscores. It must be different from @samp{TRUE} and @samp{FALSE}
10447 that are reserved by Automake.
10449 The shell @var{condition} (suitable for use in a shell @code{if}
10450 statement) is evaluated when @command{configure} is run. Note that you
10451 must arrange for @emph{every} @code{AM_CONDITIONAL} to be invoked every
10452 time @command{configure} is run. If @code{AM_CONDITIONAL} is run
10453 conditionally (e.g., in a shell @code{if} statement), then the result
10454 will confuse @command{automake}.
10457 @cindex @option{--enable-debug}, example
10458 @cindex Example conditional @option{--enable-debug}
10459 @cindex Conditional example, @option{--enable-debug}
10461 Conditionals typically depend upon options that the user provides to
10462 the @command{configure} script. Here is an example of how to write a
10463 conditional that is true if the user uses the @option{--enable-debug}
10467 AC_ARG_ENABLE([debug],
10468 [ --enable-debug Turn on debugging],
10469 [case "$@{enableval@}" in
10472 *) AC_MSG_ERROR([bad value $@{enableval@} for --enable-debug]) ;;
10473 esac],[debug=false])
10474 AM_CONDITIONAL([DEBUG], [test x$debug = xtrue])
10477 Here is an example of how to use that conditional in @file{Makefile.am}:
10489 noinst_PROGRAMS = $(DBG)
10492 This trivial example could also be handled using @code{EXTRA_PROGRAMS}
10493 (@pxref{Conditional Programs}).
10495 You may only test a single variable in an @code{if} statement, possibly
10496 negated using @samp{!}. The @code{else} statement may be omitted.
10497 Conditionals may be nested to any depth. You may specify an argument to
10498 @code{else} in which case it must be the negation of the condition used
10499 for the current @code{if}. Similarly you may specify the condition
10500 that is closed on the @code{endif} line:
10511 Unbalanced conditions are errors. The @code{if}, @code{else}, and
10512 @code{endif} statements should not be indented, i.e., start on column
10515 The @code{else} branch of the above two examples could be omitted,
10516 since assigning the empty string to an otherwise undefined variable
10517 makes no difference.
10519 @acindex AM_COND_IF
10520 In order to allow access to the condition registered by
10521 @code{AM_CONDITIONAL} inside @file{configure.ac}, and to allow
10522 conditional @code{AC_CONFIG_FILES}, @code{AM_COND_IF} may be used:
10524 @defmac AM_COND_IF (@var{conditional}, @ovar{if-true}, @ovar{if-false})
10525 If @var{conditional} is fulfilled, execute @var{if-true}, otherwise
10526 execute @var{if-false}. If either branch contains @code{AC_CONFIG_FILES},
10527 it will cause @command{automake} to output the rules for the respective
10528 files only for the given condition.
10531 @code{AM_COND_IF} macros may be nested when m4 quotation is used
10532 properly (@pxref{M4 Quotation, ,, autoconf, The Autoconf Manual}).
10534 @cindex Example conditional @code{AC_CONFIG_FILES}
10535 @cindex @code{AC_CONFIG_FILES}, conditional
10537 Here is an example of how to define a conditional config file:
10540 AM_CONDITIONAL([SHELL_WRAPPER], [test "x$with_wrapper" = xtrue])
10541 AM_COND_IF([SHELL_WRAPPER],
10542 [AC_CONFIG_FILES([wrapper:wrapper.in])])
10545 @node Limits of Conditionals
10546 @section Limits of Conditionals
10548 Conditionals should enclose complete statements like variables or
10549 rules definitions. Automake cannot deal with conditionals used inside
10550 a variable definition, for instance, and is not even able to diagnose
10551 this situation. The following example would not work:
10554 # This syntax is not understood by Automake
10563 However the intended definition of @code{AM_CPPFLAGS} can be achieved
10568 DEBUGFLAGS = -DDEBUG
10570 AM_CPPFLAGS = -DFEATURE_A $(DEBUGFLAGS) -DFEATURE_B
10577 AM_CPPFLAGS = -DFEATURE_A
10579 AM_CPPFLAGS += -DDEBUG
10581 AM_CPPFLAGS += -DFEATURE_B
10584 More details and examples of conditionals are described alongside
10585 various Automake features in this manual (@pxref{Conditional
10586 Subdirectories}, @pxref{Conditional Sources}, @pxref{Conditional
10587 Programs}, @pxref{Conditional Libtool Libraries}, @pxref{Conditional
10590 @node Silencing Make
10591 @chapter Silencing @command{make}
10593 @cindex Silent @command{make}
10594 @cindex Silencing @command{make}
10595 @cindex Silent rules
10596 @cindex Silent @command{make} rules
10599 * Make verbosity:: Make is verbose by default
10600 * Tricks For Silencing Make:: Standard and generic ways to silence make
10601 * Automake Silent Rules:: How Automake can help in silencing make
10604 @node Make verbosity
10605 @section Make is verbose by default
10607 Normally, when executing the set of rules associated with a target,
10608 @command{make} prints each rule before it is executed. This behaviour,
10609 while having been in place for a long time, and being even mandated by
10610 the POSIX standard, starkly violates the ``silence is golden'' UNIX
10611 principle@footnote{See also
10612 @uref{http://catb.org/~esr/writings/taoup/html/ch11s09.html}.}:
10615 When a program has nothing interesting or surprising to say, it should
10616 say nothing. Well-behaved Unix programs do their jobs unobtrusively,
10617 with a minimum of fuss and bother. Silence is golden.
10620 In fact, while such verbosity of @command{make} can theoretically be
10621 useful to track bugs and understand reasons of failures right away, it
10622 can also hide warning and error messages from @command{make}-invoked
10623 tools, drowning them in a flood of uninteresting and seldom useful
10624 messages, and thus allowing them to go easily undetected.
10626 This problem can be very annoying, especially for developers, who usually
10627 know quite well what's going on behind the scenes, and for whom the
10628 verbose output from @command{make} ends up being mostly noise that hampers
10629 the easy detection of potentially important warning messages.
10631 @node Tricks For Silencing Make
10632 @section Standard and generic ways to silence make
10634 Here we describe some common idioms/tricks to obtain a quieter make
10635 output, with their relative advantages and drawbacks. In the next
10636 section (@ref{Automake Silent Rules}) we'll see how Automake can help
10637 in this respect, providing more elaborate and flexible idioms.
10641 @item @command{make -s}
10643 This simply causes @command{make} not to print @emph{any} rule before
10646 The @option{-s} flag is mandated by POSIX, universally supported, and
10647 its purpose and function are easy to understand.
10649 But it also has its serious limitations too. First of all, it embodies
10650 an ``all or nothing'' strategy, i.e., either everything is silenced, or
10651 nothing is; this lack of granularity can sometimes be a fatal flaw.
10652 Moreover, when the @option{-s} flag is used, the @command{make} output
10653 might turn out to be too much terse; in case of errors, the user won't
10654 be able to easily see what rule or command have caused them, or even,
10655 in case of tools with poor error reporting, what the errors were!
10657 @item @command{make >/dev/null || make}
10659 Apparently, this perfectly obeys the ``silence is golden'' rule: warnings
10660 from stderr are passed through, output reporting is done only in case of
10661 error, and in that case it should provide a verbose-enough report to allow
10662 an easy determination of the error location and causes.
10664 However, calling @command{make} two times in a row might hide errors
10665 (especially intermittent ones), or subtly change the expected semantic
10666 of the @command{make} calls --- things these which can clearly make
10667 debugging and error assessment very difficult.
10669 @item @command{make --no-print-directory}
10671 This is GNU @command{make} specific. When called with the
10672 @option{--no-print-directory} option, GNU @command{make} will disable
10673 printing of the working directory by invoked sub-@command{make}s (the
10674 well-known ``@i{Entering/Leaving directory ...}'' messages). This helps
10675 to decrease the verbosity of the output, but experience has shown that
10676 it can also often render debugging considerably harder in projects using
10677 deeply-nested @command{make} recursion.
10679 As an aside, notice that the @option{--no-print-directory} option is
10680 automatically activated if the @option{-s} flag is used.
10682 @c TODO: Other tricks?
10683 @c TODO: Maybe speak about the @code{.SILENT} target?
10684 @c TODO: - Pros: More granularity on what to silence.
10685 @c TODO: - Cons: No easy way to temporarily override.
10689 @node Automake Silent Rules
10690 @section How Automake can help in silencing make
10692 The tricks and idioms for silencing @command{make} described in the
10693 previous section can be useful from time to time, but we've seen that
10694 they all have their serious drawbacks and limitations. That's why
10695 automake provides support for a more advanced and flexible way of
10696 obtaining quieter output from @command{make} (for most rules at least).
10698 @c TODO: Maybe describe in brief the precedent set by the build system
10699 @c of the Linux Kernel, from which Automake took inspiration ... Links?
10701 To give the gist of what Automake can do in this respect, here is a simple
10702 comparison between a typical @command{make} output (where silent rules
10703 are disabled) and one with silent rules enabled:
10706 % @kbd{cat Makefile.am}
10708 foo_SOURCES = main.c func.c
10710 int main (void) @{ return func (); @} /* func used undeclared */
10712 int func (void) @{ int i; return i; @} /* i used uninitialized */
10714 @i{The make output is by default very verbose. This causes warnings
10715 from the compiler to be somewhat hidden, and not immediate to spot.}
10716 % @kbd{make CFLAGS=-Wall}
10717 gcc -DPACKAGE_NAME=\"foo\" -DPACKAGE_TARNAME=\"foo\" ...
10718 -DPACKAGE_STRING=\"foo\ 1.0\" -DPACKAGE_BUGREPORT=\"\" ...
10719 -DPACKAGE=\"foo\" -DVERSION=\"1.0\" -I. -Wall -MT main.o
10720 -MD -MP -MF .deps/main.Tpo -c -o main.o main.c
10721 main.c: In function ‘main’:
10722 main.c:3:3: warning: implicit declaration of function ‘func’
10723 mv -f .deps/main.Tpo .deps/main.Po
10724 gcc -DPACKAGE_NAME=\"foo\" -DPACKAGE_TARNAME=\"foo\" ...
10725 -DPACKAGE_STRING=\"foo\ 1.0\" -DPACKAGE_BUGREPORT=\"\" ...
10726 -DPACKAGE=\"foo\" -DVERSION=\"1.0\" -I. -Wall -MT func.o
10727 -MD -MP -MF .deps/func.Tpo -c -o func.o func.c
10728 func.c: In function ‘func’:
10729 func.c:4:3: warning: ‘i’ used uninitialized in this function
10730 mv -f .deps/func.Tpo .deps/func.Po
10731 gcc -Wall -o foo main.o func.o
10733 @i{Clean up, so that we we can rebuild everything from scratch.}
10735 test -z "foo" || rm -f foo
10738 @i{Silent rules enabled: the output is minimal but informative. In
10739 particular, the warnings from the compiler stick out very clearly.}
10740 % @kbd{make V=0 CFLAGS=-Wall}
10742 main.c: In function ‘main’:
10743 main.c:3:3: warning: implicit declaration of function ‘func’
10745 func.c: In function ‘func’:
10746 func.c:4:3: warning: ‘i’ used uninitialized in this function
10750 @cindex silent rules and libtool
10751 Also, in projects using @command{libtool}, the use of silent rules can
10752 automatically enable the @command{libtool}'s @option{--silent} option:
10755 % @kbd{cat Makefile.am}
10756 lib_LTLIBRARIES = libx.la
10758 % @kbd{make # Both make and libtool are verbose by default.}
10760 libtool: compile: gcc -DPACKAGE_NAME=\"foo\" ... -DLT_OBJDIR=\".libs/\"
10761 -I. -g -O2 -MT libx.lo -MD -MP -MF .deps/libx.Tpo -c libx.c -fPIC
10762 -DPIC -o .libs/libx.o
10763 mv -f .deps/libx.Tpo .deps/libx.Plo
10764 /bin/sh ./libtool --tag=CC --mode=link gcc -g -O2 -o libx.la -rpath
10765 /usr/local/lib libx.lo
10766 libtool: link: gcc -shared .libs/libx.o -Wl,-soname -Wl,libx.so.0
10767 -o .libs/libx.so.0.0.0
10768 libtool: link: cd .libs && rm -f libx.so && ln -s libx.so.0.0.0 libx.so
10776 For Automake-generated @file{Makefile}s, the user may influence the
10777 verbosity at @command{configure} run time as well as at @command{make}
10782 @opindex --enable-silent-rules
10783 @opindex --disable-silent-rules
10784 Passing @option{--enable-silent-rules} to @command{configure} will cause
10785 build rules to be less verbose; the option @option{--disable-silent-rules}
10786 will cause normal verbose output.
10789 At @command{make} run time, the default chosen at @command{configure}
10790 time may be overridden: @code{make V=1} will produce verbose output,
10791 @code{make V=0} less verbose output.
10794 @cindex default verbosity for silent rules
10795 Note that silent rules are @emph{disabled} by default; the user must
10796 enable them explicitly at either @command{configure} run time or at
10797 @command{make} run time. We think that this is a good policy, since
10798 it provides the casual user with enough information to prepare a good
10799 bug report in case anything breaks.
10801 Still, notwithstanding the rationales above, a developer who really
10802 wants to make silent rules enabled by default in his own package can
10803 do so by calling @code{AM_SILENT_RULES([yes])} in @file{configure.ac}.
10805 @c Keep in sync with silent-configsite.sh
10806 Users who prefer to have silent rules enabled by default can edit their
10807 @file{config.site} file to make the variable @code{enable_silent_rules}
10808 default to @samp{yes}. This should still allow disabling silent rules
10809 at @command{configure} time and at @command{make} time.
10811 @c FIXME: there's really a need to specify this explicitly?
10812 For portability to different @command{make} implementations, package authors
10813 are advised to not set the variable @code{V} inside the @file{Makefile.am}
10814 file, to allow the user to override the value for subdirectories as well.
10816 To work at its best, the current implementation of this feature normally
10817 uses nested variable expansion @samp{$(@var{var1}$(V))}, a @file{Makefile}
10818 feature that is not required by POSIX 2008 but is widely supported in
10819 practice. On the rare @command{make} implementations that do not support
10820 nested variable expansion, whether rules are silent is always determined at
10821 configure time, and cannot be overridden at make time. Future versions of
10822 POSIX are likely to require nested variable expansion, so this minor
10823 limitation should go away with time.
10825 @vindex @code{AM_V_GEN}
10826 @vindex @code{AM_V_at}
10827 @vindex @code{AM_DEFAULT_VERBOSITY}
10828 @vindex @code{AM_V}
10829 @vindex @code{AM_DEFAULT_V}
10830 To extend the silent mode to your own rules, you have few choices:
10835 You can use the predefined variable @code{AM_V_GEN} as a prefix to
10836 commands that should output a status line in silent mode, and
10837 @code{AM_V_at} as a prefix to commands that should not output anything
10838 in silent mode. When output is to be verbose, both of these variables
10839 will expand to the empty string.
10842 You can silence a recipe unconditionally with @code{@@}, and then use
10843 the predefined variable @code{AM_V_P} to know whether make is being run
10844 in silent or verbose mode, adjust the verbose information your recipe
10845 displays accordingly:
10850 ... [commands defining a shell variable '$headers'] ...; \
10851 if $(AM_V_P); then set -x; else echo " GEN [headers]"; fi; \
10852 rm -f $$headers && generate-header --flags $$headers
10856 You can add your own variables, so strings of your own choice are shown.
10857 The following snippet shows how you would define your own equivalent of
10861 pkg_verbose = $(pkg_verbose_@@AM_V@@)
10862 pkg_verbose_ = $(pkg_verbose_@@AM_DEFAULT_V@@)
10863 pkg_verbose_0 = @@echo PKG-GEN $@@;
10866 $(pkg_verbose)cp $(srcdir)/foo.in $@@
10871 As a final note, observe that, even when silent rules are enabled,
10872 the @option{--no-print-directory} option is still required with GNU
10873 @command{make} if the ``@i{Entering/Leaving directory ...}'' messages
10874 are to be disabled.
10877 @chapter The effect of @option{--gnu} and @option{--gnits}
10879 @cindex @option{--gnu}, required files
10880 @cindex @option{--gnu}, complete description
10882 The @option{--gnu} option (or @option{gnu} in the
10883 @code{AUTOMAKE_OPTIONS} variable) causes @command{automake} to check
10888 The files @file{INSTALL}, @file{NEWS}, @file{README}, @file{AUTHORS},
10889 and @file{ChangeLog}, plus one of @file{COPYING.LIB}, @file{COPYING.LESSER}
10890 or @file{COPYING}, are required at the topmost directory of the package.
10892 If the @option{--add-missing} option is given, @command{automake} will
10893 add a generic version of the @file{INSTALL} file as well as the
10894 @file{COPYING} file containing the text of the current version of the
10895 GNU General Public License existing at the time of this Automake release
10896 (version 3 as this is written, @uref{http://www.gnu.org/@/copyleft/@/gpl.html}).
10897 However, an existing @file{COPYING} file will never be overwritten by
10898 @command{automake}.
10901 The options @option{no-installman} and @option{no-installinfo} are
10905 Note that this option will be extended in the future to do even more
10906 checking; it is advisable to be familiar with the precise requirements
10907 of the GNU standards. Also, @option{--gnu} can require certain
10908 non-standard GNU programs to exist for use by various maintainer-only
10909 rules; for instance, in the future @command{pathchk} might be required for
10912 @cindex @option{--gnits}, complete description
10914 The @option{--gnits} option does everything that @option{--gnu} does, and
10915 checks the following as well:
10919 @samp{make installcheck} will check to make sure that the @option{--help}
10920 and @option{--version} really print a usage message and a version string,
10921 respectively. This is the @option{std-options} option (@pxref{Options}).
10924 @samp{make dist} will check to make sure the @file{NEWS} file has been
10925 updated to the current version.
10928 @code{VERSION} is checked to make sure its format complies with Gnits
10930 @c FIXME xref when standards are finished
10933 @cindex @file{README-alpha}
10934 If @code{VERSION} indicates that this is an alpha release, and the file
10935 @file{README-alpha} appears in the topmost directory of a package, then
10936 it is included in the distribution. This is done in @option{--gnits}
10937 mode, and no other, because this mode is the only one where version
10938 number formats are constrained, and hence the only mode where Automake
10939 can automatically determine whether @file{README-alpha} should be
10943 The file @file{THANKS} is required.
10948 @chapter When Automake Isn't Enough
10950 In some situations, where Automake is not up to one task, one has to
10951 resort to handwritten rules or even handwritten @file{Makefile}s.
10954 * Extending:: Adding new rules or overriding existing ones.
10955 * Third-Party Makefiles:: Integrating Non-Automake @file{Makefile}s.
10959 @section Extending Automake Rules
10961 With some minor exceptions (for example @code{_PROGRAMS} variables,
10962 @code{TESTS}, or @code{XFAIL_TESTS}) being rewritten to append
10963 @samp{$(EXEEXT)}), the contents of a @file{Makefile.am} is copied to
10964 @file{Makefile.in} verbatim.
10966 @cindex copying semantics
10968 These copying semantics mean that many problems can be worked around
10969 by simply adding some @command{make} variables and rules to
10970 @file{Makefile.am}. Automake will ignore these additions.
10972 @cindex conflicting definitions
10973 @cindex rules, conflicting
10974 @cindex variables, conflicting
10975 @cindex definitions, conflicts
10977 Since a @file{Makefile.in} is built from data gathered from three
10978 different places (@file{Makefile.am}, @file{configure.ac}, and
10979 @command{automake} itself), it is possible to have conflicting
10980 definitions of rules or variables. When building @file{Makefile.in}
10981 the following priorities are respected by @command{automake} to ensure
10982 the user always has the last word:
10986 User defined variables in @file{Makefile.am} have priority over
10987 variables @code{AC_SUBST}ed from @file{configure.ac}, and
10988 @code{AC_SUBST}ed variables have priority over
10989 @command{automake}-defined variables.
10991 As far as rules are concerned, a user-defined rule overrides any
10992 @command{automake}-defined rule for the same target.
10995 @cindex overriding rules
10996 @cindex overriding semantics
10997 @cindex rules, overriding
10999 These overriding semantics make it possible to fine tune some default
11000 settings of Automake, or replace some of its rules. Overriding
11001 Automake rules is often inadvisable, particularly in the topmost
11002 directory of a package with subdirectories. The @option{-Woverride}
11003 option (@pxref{automake Invocation}) comes in handy to catch overridden
11006 Note that Automake does not make any distinction between rules with
11007 commands and rules that only specify dependencies. So it is not
11008 possible to append new dependencies to an @command{automake}-defined
11009 target without redefining the entire rule.
11011 @cindex @option{-local} targets
11012 @cindex local targets
11014 However, various useful targets have a @samp{-local} version you can
11015 specify in your @file{Makefile.am}. Automake will supplement the
11016 standard target with these user-supplied targets.
11021 @trindex info-local
11029 @trindex html-local
11031 @trindex check-local
11033 @trindex install-data
11034 @trindex install-data-local
11035 @trindex install-dvi
11036 @trindex install-dvi-local
11037 @trindex install-exec
11038 @trindex install-exec-local
11039 @trindex install-html
11040 @trindex install-html-local
11041 @trindex install-info
11042 @trindex install-info-local
11043 @trindex install-pdf
11044 @trindex install-pdf-local
11045 @trindex install-ps
11046 @trindex install-ps-local
11048 @trindex uninstall-local
11049 @trindex mostlyclean
11050 @trindex mostlyclean-local
11052 @trindex clean-local
11054 @trindex distclean-local
11055 @trindex installdirs
11056 @trindex installdirs-local
11057 @trindex installcheck
11058 @trindex installcheck-local
11060 The targets that support a local version are @code{all}, @code{info},
11061 @code{dvi}, @code{ps}, @code{pdf}, @code{html}, @code{check},
11062 @code{install-data}, @code{install-dvi}, @code{install-exec},
11063 @code{install-html}, @code{install-info}, @code{install-pdf},
11064 @code{install-ps}, @code{uninstall}, @code{installdirs},
11065 @code{installcheck} and the various @code{clean} targets
11066 (@code{mostlyclean}, @code{clean}, @code{distclean}, and
11067 @code{maintainer-clean}).
11069 Note that there are no @code{uninstall-exec-local} or
11070 @code{uninstall-data-local} targets; just use @code{uninstall-local}.
11071 It doesn't make sense to uninstall just data or just executables.
11073 For instance, here is one way to erase a subdirectory during
11074 @samp{make clean} (@pxref{Clean}).
11081 You may be tempted to use @code{install-data-local} to install a file
11082 to some hard-coded location, but you should avoid this
11083 (@pxref{Hard-Coded Install Paths}).
11085 With the @code{-local} targets, there is no particular guarantee of
11086 execution order; typically, they are run early, but with parallel
11087 make, there is no way to be sure of that.
11089 @cindex @option{-hook} targets
11090 @cindex hook targets
11091 @trindex install-data-hook
11092 @trindex install-exec-hook
11093 @trindex uninstall-hook
11096 In contrast, some rules also have a way to run another rule, called a
11097 @dfn{hook}; hooks are always executed after the main rule's work is done.
11098 The hook is named after the principal target, with @samp{-hook} appended.
11099 The targets allowing hooks are @code{install-data},
11100 @code{install-exec}, @code{uninstall}, @code{dist}, and
11103 For instance, here is how to create a hard link to an installed program:
11107 ln $(DESTDIR)$(bindir)/program$(EXEEXT) \
11108 $(DESTDIR)$(bindir)/proglink$(EXEEXT)
11111 Although cheaper and more portable than symbolic links, hard links
11112 will not work everywhere (for instance, OS/2 does not have
11113 @command{ln}). Ideally you should fall back to @samp{cp -p} when
11114 @command{ln} does not work. An easy way, if symbolic links are
11115 acceptable to you, is to add @code{AC_PROG_LN_S} to
11116 @file{configure.ac} (@pxref{Particular Programs, , Particular Program
11117 Checks, autoconf, The Autoconf Manual}) and use @samp{$(LN_S)} in
11118 @file{Makefile.am}.
11120 @cindex versioned binaries, installing
11121 @cindex installing versioned binaries
11122 @cindex @code{LN_S} example
11123 For instance, here is how you could install a versioned copy of a
11124 program using @samp{$(LN_S)}:
11126 @c Keep in sync with insthook.sh
11129 cd $(DESTDIR)$(bindir) && \
11130 mv -f prog$(EXEEXT) prog-$(VERSION)$(EXEEXT) && \
11131 $(LN_S) prog-$(VERSION)$(EXEEXT) prog$(EXEEXT)
11134 Note that we rename the program so that a new version will erase the
11135 symbolic link, not the real binary. Also we @command{cd} into the
11136 destination directory in order to create relative links.
11138 When writing @code{install-exec-hook} or @code{install-data-hook},
11139 please bear in mind that the exec/data distinction is based on the
11140 installation directory, not on the primary used (@pxref{The Two Parts of
11142 @c Keep in sync with primary-prefix-couples-documented-valid.sh
11143 So a @code{foo_SCRIPTS} will be installed by
11144 @code{install-data}, and a @code{barexec_SCRIPTS} will be installed by
11145 @code{install-exec}. You should define your hooks consequently.
11147 @c FIXME should include discussion of variables you can use in these
11150 @node Third-Party Makefiles
11151 @section Third-Party @file{Makefile}s
11153 @cindex Third-party packages, interfacing with
11154 @cindex Interfacing with third-party packages
11156 In most projects all @file{Makefile}s are generated by Automake. In
11157 some cases, however, projects need to embed subdirectories with
11158 handwritten @file{Makefile}s. For instance, one subdirectory could be
11159 a third-party project with its own build system, not using Automake.
11161 It is possible to list arbitrary directories in @code{SUBDIRS} or
11162 @code{DIST_SUBDIRS} provided each of these directories has a
11163 @file{Makefile} that recognizes all the following recursive targets.
11165 @cindex recursive targets and third-party @file{Makefile}s
11166 When a user runs one of these targets, that target is run recursively
11167 in all subdirectories. This is why it is important that even
11168 third-party @file{Makefile}s support them.
11172 Compile the entire package. This is the default target in
11173 Automake-generated @file{Makefile}s, but it does not need to be the
11174 default in third-party @file{Makefile}s.
11179 @vindex top_distdir
11180 Copy files to distribute into @samp{$(distdir)}, before a tarball is
11181 constructed. Of course this target is not required if the
11182 @option{no-dist} option (@pxref{Options}) is used.
11184 The variables @samp{$(top_distdir)} and @samp{$(distdir)}
11185 (@pxref{The dist Hook}) will be passed from the outer package to the subpackage
11186 when the @code{distdir} target is invoked. These two variables have
11187 been adjusted for the directory that is being recursed into, so they
11191 @itemx install-data
11192 @itemx install-exec
11194 Install or uninstall files (@pxref{Install}).
11197 @itemx install-html
11198 @itemx install-info
11201 Install only some specific documentation format (@pxref{Texinfo}).
11204 Create install directories, but do not install any files.
11207 @itemx installcheck
11208 Check the package (@pxref{Tests}).
11213 @itemx maintainer-clean
11214 Cleaning rules (@pxref{Clean}).
11221 Build the documentation in various formats (@pxref{Texinfo}).
11225 Build @file{TAGS} and @file{CTAGS} (@pxref{Tags}).
11228 If you have ever used Gettext in a project, this is a good example of
11229 how third-party @file{Makefile}s can be used with Automake. The
11230 @file{Makefile}s @command{gettextize} puts in the @file{po/} and
11231 @file{intl/} directories are handwritten @file{Makefile}s that
11232 implement all of these targets. That way they can be added to
11233 @code{SUBDIRS} in Automake packages.
11235 Directories that are only listed in @code{DIST_SUBDIRS} but not in
11236 @code{SUBDIRS} need only the @code{distclean},
11237 @code{maintainer-clean}, and @code{distdir} rules (@pxref{Conditional
11240 Usually, many of these rules are irrelevant to the third-party
11241 subproject, but they are required for the whole package to work. It's
11242 OK to have a rule that does nothing, so if you are integrating a
11243 third-party project with no documentation or tag support, you could
11244 simply augment its @file{Makefile} as follows:
11247 EMPTY_AUTOMAKE_TARGETS = dvi pdf ps info html tags ctags
11248 .PHONY: $(EMPTY_AUTOMAKE_TARGETS)
11249 $(EMPTY_AUTOMAKE_TARGETS):
11252 Another aspect of integrating third-party build systems is whether
11253 they support VPATH builds (@pxref{VPATH Builds}). Obviously if the
11254 subpackage does not support VPATH builds the whole package will not
11255 support VPATH builds. This in turns means that @samp{make distcheck}
11256 will not work, because it relies on VPATH builds. Some people can
11257 live without this (actually, many Automake users have never heard of
11258 @samp{make distcheck}). Other people may prefer to revamp the
11259 existing @file{Makefile}s to support VPATH@. Doing so does not
11260 necessarily require Automake, only Autoconf is needed (@pxref{Build
11261 Directories, , Build Directories, autoconf, The Autoconf Manual}).
11262 The necessary substitutions: @samp{@@srcdir@@}, @samp{@@top_srcdir@@},
11263 and @samp{@@top_builddir@@} are defined by @file{configure} when it
11264 processes a @file{Makefile} (@pxref{Preset Output Variables, , Preset
11265 Output Variables, autoconf, The Autoconf Manual}), they are not
11266 computed by the Makefile like the aforementioned @samp{$(distdir)} and
11267 @samp{$(top_distdir)} variables.
11269 It is sometimes inconvenient to modify a third-party @file{Makefile}
11270 to introduce the above required targets. For instance, one may want to
11271 keep the third-party sources untouched to ease upgrades to new
11274 @cindex @file{GNUmakefile} including @file{Makefile}
11275 Here are two other ideas. If GNU make is assumed, one possibility is
11276 to add to that subdirectory a @file{GNUmakefile} that defines the
11277 required targets and includes the third-party @file{Makefile}. For
11278 this to work in VPATH builds, @file{GNUmakefile} must lie in the build
11279 directory; the easiest way to do this is to write a
11280 @file{GNUmakefile.in} instead, and have it processed with
11281 @code{AC_CONFIG_FILES} from the outer package. For example if we
11282 assume @file{Makefile} defines all targets except the documentation
11283 targets, and that the @code{check} target is actually called
11284 @code{test}, we could write @file{GNUmakefile} (or
11285 @file{GNUmakefile.in}) like this:
11288 # First, include the real Makefile
11290 # Then, define the other targets needed by Automake Makefiles.
11291 .PHONY: dvi pdf ps info html check
11292 dvi pdf ps info html:
11296 @cindex Proxy @file{Makefile} for third-party packages
11297 A similar idea that does not use @code{include} is to write a proxy
11298 @file{Makefile} that dispatches rules to the real @file{Makefile},
11299 either with @samp{$(MAKE) -f Makefile.real $(AM_MAKEFLAGS) target} (if
11300 it's OK to rename the original @file{Makefile}) or with @samp{cd
11301 subdir && $(MAKE) $(AM_MAKEFLAGS) target} (if it's OK to store the
11302 subdirectory project one directory deeper). The good news is that
11303 this proxy @file{Makefile} can be generated with Automake. All we
11304 need are @option{-local} targets (@pxref{Extending}) that perform the
11305 dispatch. Of course the other Automake features are available, so you
11306 could decide to let Automake perform distribution or installation.
11307 Here is a possible @file{Makefile.am}:
11311 cd subdir && $(MAKE) $(AM_MAKEFLAGS) all
11313 cd subdir && $(MAKE) $(AM_MAKEFLAGS) test
11315 cd subdir && $(MAKE) $(AM_MAKEFLAGS) clean
11317 # Assuming the package knows how to install itself
11318 install-data-local:
11319 cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-data
11320 install-exec-local:
11321 cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-exec
11323 cd subdir && $(MAKE) $(AM_MAKEFLAGS) uninstall
11325 # Distribute files from here.
11326 EXTRA_DIST = subdir/Makefile subdir/program.c ...
11329 Pushing this idea to the extreme, it is also possible to ignore the
11330 subproject build system and build everything from this proxy
11331 @file{Makefile.am}. This might sound very sensible if you need VPATH
11332 builds but the subproject does not support them.
11335 @chapter Distributing @file{Makefile.in}s
11337 Automake places no restrictions on the distribution of the resulting
11338 @file{Makefile.in}s. We still encourage software authors to
11339 distribute their work under terms like those of the GPL, but doing so
11340 is not required to use Automake.
11342 Some of the files that can be automatically installed via the
11343 @option{--add-missing} switch do fall under the GPL@. However, these also
11344 have a special exception allowing you to distribute them with your
11345 package, regardless of the licensing you choose.
11348 @node API Versioning
11349 @chapter Automake API Versioning
11351 New Automake releases usually include bug fixes and new features.
11352 Unfortunately they may also introduce new bugs and incompatibilities.
11353 This makes four reasons why a package may require a particular Automake
11356 Things get worse when maintaining a large tree of packages, each one
11357 requiring a different version of Automake. In the past, this meant that
11358 any developer (and sometimes users) had to install several versions of
11359 Automake in different places, and switch @samp{$PATH} appropriately for
11362 Starting with version 1.6, Automake installs versioned binaries. This
11363 means you can install several versions of Automake in the same
11364 @samp{$prefix}, and can select an arbitrary Automake version by running
11365 @command{automake-1.6} or @command{automake-1.7} without juggling with
11366 @samp{$PATH}. Furthermore, @file{Makefile}'s generated by Automake 1.6
11367 will use @command{automake-1.6} explicitly in their rebuild rules.
11369 The number @samp{1.6} in @command{automake-1.6} is Automake's API version,
11370 not Automake's version. If a bug fix release is made, for instance
11371 Automake 1.6.1, the API version will remain 1.6. This means that a
11372 package that works with Automake 1.6 should also work with 1.6.1; after
11373 all, this is what people expect from bug fix releases.
11375 If your package relies on a feature or a bug fix introduced in
11376 a release, you can pass this version as an option to Automake to ensure
11377 older releases will not be used. For instance, use this in your
11378 @file{configure.ac}:
11381 AM_INIT_AUTOMAKE([1.6.1]) dnl Require Automake 1.6.1 or better.
11385 or, in a particular @file{Makefile.am}:
11388 AUTOMAKE_OPTIONS = 1.6.1 # Require Automake 1.6.1 or better.
11392 Automake will print an error message if its version is
11393 older than the requested version.
11396 @heading What is in the API
11398 Automake's programming interface is not easy to define. Basically it
11399 should include at least all @strong{documented} variables and targets
11400 that a @file{Makefile.am} author can use, any behavior associated with
11401 them (e.g., the places where @samp{-hook}'s are run), the command line
11402 interface of @command{automake} and @command{aclocal}, @dots{}
11404 @heading What is not in the API
11406 Every undocumented variable, target, or command line option, is not part
11407 of the API@. You should avoid using them, as they could change from one
11408 version to the other (even in bug fix releases, if this helps to fix a
11411 If it turns out you need to use such an undocumented feature, contact
11412 @email{automake@@gnu.org} and try to get it documented and exercised by
11416 @chapter Upgrading a Package to a Newer Automake Version
11418 Automake maintains three kind of files in a package.
11421 @item @file{aclocal.m4}
11422 @item @file{Makefile.in}s
11423 @item auxiliary tools like @file{install-sh} or @file{py-compile}
11426 @file{aclocal.m4} is generated by @command{aclocal} and contains some
11427 Automake-supplied M4 macros. Auxiliary tools are installed by
11428 @samp{automake --add-missing} when needed. @file{Makefile.in}s are
11429 built from @file{Makefile.am} by @command{automake}, and rely on the
11430 definitions of the M4 macros put in @file{aclocal.m4} as well as the
11431 behavior of the auxiliary tools installed.
11433 Because all of these files are closely related, it is important to
11434 regenerate all of them when upgrading to a newer Automake release.
11435 The usual way to do that is
11438 aclocal # with any option needed (such a -I m4)
11440 automake --add-missing --force-missing
11444 or more conveniently:
11450 The use of @option{--force-missing} ensures that auxiliary tools will be
11451 overridden by new versions (@pxref{automake Invocation}).
11453 It is important to regenerate all of these files each time Automake is
11454 upgraded, even between bug fixes releases. For instance, it is not
11455 unusual for a bug fix to involve changes to both the rules generated
11456 in @file{Makefile.in} and the supporting M4 macros copied to
11459 Presently @command{automake} is able to diagnose situations where
11460 @file{aclocal.m4} has been generated with another version of
11461 @command{aclocal}. However it never checks whether auxiliary scripts
11462 are up-to-date. In other words, @command{automake} will tell you when
11463 @command{aclocal} needs to be rerun, but it will never diagnose a
11464 missing @option{--force-missing}.
11466 Before upgrading to a new major release, it is a good idea to read the
11467 file @file{NEWS}. This file lists all changes between releases: new
11468 features, obsolete constructs, known incompatibilities, and
11472 @chapter Frequently Asked Questions about Automake
11474 This chapter covers some questions that often come up on the mailing
11478 * CVS:: CVS and generated files
11479 * maintainer-mode:: missing and AM_MAINTAINER_MODE
11480 * Wildcards:: Why doesn't Automake support wildcards?
11481 * Limitations on File Names:: Limitations on source and installed file names
11482 * Errors with distclean:: Files left in build directory after distclean
11483 * Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS
11484 * Renamed Objects:: Why are object files sometimes renamed?
11485 * Per-Object Flags:: How to simulate per-object flags?
11486 * Multiple Outputs:: Writing rules for tools with many output files
11487 * Hard-Coded Install Paths:: Installing to hard-coded locations
11488 * Debugging Make Rules:: Strategies when things don't work as expected
11489 * Reporting Bugs:: Feedback on bugs and feature requests
11493 @section CVS and generated files
11495 @subheading Background: distributed generated Files
11496 @cindex generated files, distributed
11497 @cindex rebuild rules
11499 Packages made with Autoconf and Automake ship with some generated
11500 files like @file{configure} or @file{Makefile.in}. These files were
11501 generated on the developer's machine and are distributed so that
11502 end-users do not have to install the maintainer tools required to
11503 rebuild them. Other generated files like Lex scanners, Yacc parsers,
11504 or Info documentation, are usually distributed on similar grounds.
11506 Automake output rules in @file{Makefile}s to rebuild these files. For
11507 instance, @command{make} will run @command{autoconf} to rebuild
11508 @file{configure} whenever @file{configure.ac} is changed. This makes
11509 development safer by ensuring a @file{configure} is never out-of-date
11510 with respect to @file{configure.ac}.
11512 As generated files shipped in packages are up-to-date, and because
11513 @command{tar} preserves times-tamps, these rebuild rules are not
11514 triggered when a user unpacks and builds a package.
11516 @subheading Background: CVS and Timestamps
11517 @cindex timestamps and CVS
11518 @cindex CVS and timestamps
11520 Unless you use CVS keywords (in which case files must be updated at
11521 commit time), CVS preserves timestamp during @samp{cvs commit} and
11522 @samp{cvs import -d} operations.
11524 When you check out a file using @samp{cvs checkout} its timestamp is
11525 set to that of the revision that is being checked out.
11527 However, during @command{cvs update}, files will have the date of the
11528 update, not the original timestamp of this revision. This is meant to
11529 make sure that @command{make} notices sources files have been updated.
11531 This timestamp shift is troublesome when both sources and generated
11532 files are kept under CVS@. Because CVS processes files in lexical
11533 order, @file{configure.ac} will appear newer than @file{configure}
11534 after a @command{cvs update} that updates both files, even if
11535 @file{configure} was newer than @file{configure.ac} when it was
11536 checked in. Calling @command{make} will then trigger a spurious rebuild
11537 of @file{configure}.
11539 @subheading Living with CVS in Autoconfiscated Projects
11540 @cindex CVS and generated files
11541 @cindex generated files and CVS
11543 There are basically two clans amongst maintainers: those who keep all
11544 distributed files under CVS, including generated files, and those who
11545 keep generated files @emph{out} of CVS.
11547 @subsubheading All Files in CVS
11551 The CVS repository contains all distributed files so you know exactly
11552 what is distributed, and you can checkout any prior version entirely.
11555 Maintainers can see how generated files evolve (for instance, you can
11556 see what happens to your @file{Makefile.in}s when you upgrade Automake
11557 and make sure they look OK).
11560 Users do not need the autotools to build a checkout of the project, it
11561 works just like a released tarball.
11564 If users use @command{cvs update} to update their copy, instead of
11565 @command{cvs checkout} to fetch a fresh one, timestamps will be
11566 inaccurate. Some rebuild rules will be triggered and attempt to
11567 run developer tools such as @command{autoconf} or @command{automake}.
11569 Calls to such tools are all wrapped into a call to the @command{missing}
11570 script discussed later (@pxref{maintainer-mode}), so that the user will
11571 see more descriptive warnings about missing or out-of-date tools, and
11572 possible suggestions about how to obtain them, rather than just some
11573 ``command not found'' error, or (worse) some obscure message from some
11574 older version of the required tool they happen to have installed.
11576 Maintainers interested in keeping their package buildable from a CVS
11577 checkout even for those users that lack maintainer-specific tools might
11578 want to provide an helper script (or to enhance their existing bootstrap
11579 script) to fix the timestamps after a
11580 @command{cvs update} or a @command{git checkout}, to prevent spurious
11581 rebuilds. In case of a project committing the Autotools-generated
11582 files, as well as the generated @file{.info} files, such script might
11583 look something like this:
11587 # fix-timestamp.sh: prevents useless rebuilds after "cvs update"
11589 # aclocal-generated aclocal.m4 depends on locally-installed
11590 # '.m4' macro files, as well as on 'configure.ac'
11593 # autoconf-generated configure depends on aclocal.m4 and on
11595 configure config.h.in
11596 # so does autoheader-generated config.h.in
11597 configure config.h.in
11598 # and all the automake-generated Makefile.in files
11599 touch `find . -name Makefile.in -print`
11600 # finally, the makeinfo-generated '.info' files depend on the
11601 # corresponding '.texi' files
11606 In distributed development, developers are likely to have different
11607 version of the maintainer tools installed. In this case rebuilds
11608 triggered by timestamp lossage will lead to spurious changes
11609 to generated files. There are several solutions to this:
11613 All developers should use the same versions, so that the rebuilt files
11614 are identical to files in CVS@. (This starts to be difficult when each
11615 project you work on uses different versions.)
11617 Or people use a script to fix the timestamp after a checkout (the GCC
11618 folks have such a script).
11620 Or @file{configure.ac} uses @code{AM_MAINTAINER_MODE}, which will
11621 disable all of these rebuild rules by default. This is further discussed
11622 in @ref{maintainer-mode}.
11626 Although we focused on spurious rebuilds, the converse can also
11627 happen. CVS's timestamp handling can also let you think an
11628 out-of-date file is up-to-date.
11630 For instance, suppose a developer has modified @file{Makefile.am} and
11631 has rebuilt @file{Makefile.in}, and then decides to do a last-minute
11632 change to @file{Makefile.am} right before checking in both files
11633 (without rebuilding @file{Makefile.in} to account for the change).
11635 This last change to @file{Makefile.am} makes the copy of
11636 @file{Makefile.in} out-of-date. Since CVS processes files
11637 alphabetically, when another developer @samp{cvs update}s his or her
11638 tree, @file{Makefile.in} will happen to be newer than
11639 @file{Makefile.am}. This other developer will not see that
11640 @file{Makefile.in} is out-of-date.
11644 @subsubheading Generated Files out of CVS
11646 One way to get CVS and @command{make} working peacefully is to never
11647 store generated files in CVS, i.e., do not CVS-control files that
11648 are @file{Makefile} targets (also called @emph{derived} files).
11650 This way developers are not annoyed by changes to generated files. It
11651 does not matter if they all have different versions (assuming they are
11652 compatible, of course). And finally, timestamps are not lost, changes
11653 to sources files can't be missed as in the
11654 @file{Makefile.am}/@file{Makefile.in} example discussed earlier.
11656 The drawback is that the CVS repository is not an exact copy of what
11657 is distributed and that users now need to install various development
11658 tools (maybe even specific versions) before they can build a checkout.
11659 But, after all, CVS's job is versioning, not distribution.
11661 Allowing developers to use different versions of their tools can also
11662 hide bugs during distributed development. Indeed, developers will be
11663 using (hence testing) their own generated files, instead of the
11664 generated files that will be released actually. The developer who
11665 prepares the tarball might be using a version of the tool that
11666 produces bogus output (for instance a non-portable C file), something
11667 other developers could have noticed if they weren't using their own
11668 versions of this tool.
11670 @subheading Third-party Files
11671 @cindex CVS and third-party files
11672 @cindex third-party files and CVS
11674 Another class of files not discussed here (because they do not cause
11675 timestamp issues) are files that are shipped with a package, but
11676 maintained elsewhere. For instance, tools like @command{gettextize}
11677 and @command{autopoint} (from Gettext) or @command{libtoolize} (from
11678 Libtool), will install or update files in your package.
11680 These files, whether they are kept under CVS or not, raise similar
11681 concerns about version mismatch between developers' tools. The
11682 Gettext manual has a section about this, see @ref{CVS Issues, CVS
11683 Issues, Integrating with CVS, gettext, GNU gettext tools}.
11685 @node maintainer-mode
11686 @section @command{missing} and @code{AM_MAINTAINER_MODE}
11688 @subheading @command{missing}
11689 @cindex @command{missing}, purpose
11691 The @command{missing} script is a wrapper around several maintainer
11692 tools, designed to warn users if a maintainer tool is required but
11693 missing. Typical maintainer tools are @command{autoconf},
11694 @command{automake}, @command{bison}, etc. Because file generated by
11695 these tools are shipped with the other sources of a package, these
11696 tools shouldn't be required during a user build and they are not
11697 checked for in @file{configure}.
11699 However, if for some reason a rebuild rule is triggered and involves a
11700 missing tool, @command{missing} will notice it and warn the user, even
11701 suggesting how to obtain such a tool (at least in case it is a well-known
11702 one, like @command{makeinfo} or @command{bison}). This is more helpful
11703 and user-friendly than just having the rebuild rules spewing out a terse
11704 error message like @samp{sh: @var{tool}: command not found}. Similarly,
11705 @command{missing} will warn the user if it detects that a maintainer
11706 tool it attempted to use seems too old (be warned that diagnosing this
11707 correctly is typically more difficult that detecting missing tools, and
11708 requires cooperation from the tool itself, so it won't always work).
11710 If the required tool is installed, @command{missing} will run it and
11711 won't attempt to continue after failures. This is correct during
11712 development: developers love fixing failures. However, users with
11713 missing or too old maintainer tools may get an error when the rebuild
11714 rule is spuriously triggered, halting the build. This failure to let
11715 the build continue is one of the arguments of the
11716 @code{AM_MAINTAINER_MODE} advocates.
11718 @subheading @code{AM_MAINTAINER_MODE}
11719 @cindex @code{AM_MAINTAINER_MODE}, purpose
11720 @acindex AM_MAINTAINER_MODE
11722 @code{AM_MAINTAINER_MODE} allows you to choose whether the so called
11723 "rebuild rules" should be enabled or disabled. With
11724 @code{AM_MAINTAINER_MODE([enable])}, they are enabled by default,
11725 otherwise they are disabled by default. In the latter case, if
11726 you have @code{AM_MAINTAINER_MODE} in @file{configure.ac}, and run
11727 @samp{./configure && make}, then @command{make} will *never* attempt to
11728 rebuild @file{configure}, @file{Makefile.in}s, Lex or Yacc outputs, etc.
11729 I.e., this disables build rules for files that are usually distributed
11730 and that users should normally not have to update.
11732 The user can override the default setting by passing either
11733 @samp{--enable-maintainer-mode} or @samp{--disable-maintainer-mode}
11734 to @command{configure}.
11736 People use @code{AM_MAINTAINER_MODE} either because they do not want their
11737 users (or themselves) annoyed by timestamps lossage (@pxref{CVS}), or
11738 because they simply can't stand the rebuild rules and prefer running
11739 maintainer tools explicitly.
11741 @code{AM_MAINTAINER_MODE} also allows you to disable some custom build
11742 rules conditionally. Some developers use this feature to disable
11743 rules that need exotic tools that users may not have available.
11745 Several years ago Fran@,{c}ois Pinard pointed out several arguments
11746 against this @code{AM_MAINTAINER_MODE} macro. Most of them relate to
11747 insecurity. By removing dependencies you get non-dependable builds:
11748 changes to sources files can have no effect on generated files and this
11749 can be very confusing when unnoticed. He adds that security shouldn't
11750 be reserved to maintainers (what @option{--enable-maintainer-mode}
11751 suggests), on the contrary. If one user has to modify a
11752 @file{Makefile.am}, then either @file{Makefile.in} should be updated
11753 or a warning should be output (this is what Automake uses
11754 @command{missing} for) but the last thing you want is that nothing
11755 happens and the user doesn't notice it (this is what happens when
11756 rebuild rules are disabled by @code{AM_MAINTAINER_MODE}).
11758 Jim Meyering, the inventor of the @code{AM_MAINTAINER_MODE} macro was
11759 swayed by Fran@,{c}ois's arguments, and got rid of
11760 @code{AM_MAINTAINER_MODE} in all of his packages.
11762 Still many people continue to use @code{AM_MAINTAINER_MODE}, because
11763 it helps them working on projects where all files are kept under version
11764 control, and because @command{missing} isn't enough if you have the
11765 wrong version of the tools.
11769 @section Why doesn't Automake support wildcards?
11772 Developers are lazy. They would often like to use wildcards in
11773 @file{Makefile.am}s, so that they would not need to remember to
11774 update @file{Makefile.am}s every time they add, delete, or rename
11777 There are several objections to this:
11780 When using CVS (or similar) developers need to remember they have to
11781 run @samp{cvs add} or @samp{cvs rm} anyway. Updating
11782 @file{Makefile.am} accordingly quickly becomes a reflex.
11784 Conversely, if your application doesn't compile
11785 because you forgot to add a file in @file{Makefile.am}, it will help
11786 you remember to @samp{cvs add} it.
11789 Using wildcards makes it easy to distribute files by mistake. For
11790 instance, some code a developer is experimenting with (a test case,
11791 say) that should not be part of the distribution.
11794 Using wildcards it's easy to omit some files by mistake. For
11795 instance, one developer creates a new file, uses it in many places,
11796 but forgets to commit it. Another developer then checks out the
11797 incomplete project and is able to run @samp{make dist} successfully,
11798 even though a file is missing. By listing files, @samp{make dist}
11799 @emph{will} complain.
11802 Wildcards are not portable to some non-GNU @command{make} implementations,
11803 e.g., NetBSD @command{make} will not expand globs such as @samp{*} in
11804 prerequisites of a target.
11807 Finally, it's really hard to @emph{forget} to add a file to
11808 @file{Makefile.am}: files that are not listed in @file{Makefile.am} are
11809 not compiled or installed, so you can't even test them.
11812 Still, these are philosophical objections, and as such you may disagree,
11813 or find enough value in wildcards to dismiss all of them. Before you
11814 start writing a patch against Automake to teach it about wildcards,
11815 let's see the main technical issue: portability.
11817 Although @samp{$(wildcard ...)} works with GNU @command{make}, it is
11818 not portable to other @command{make} implementations.
11820 The only way Automake could support @command{$(wildcard ...)} is by
11821 expending @command{$(wildcard ...)} when @command{automake} is run.
11822 The resulting @file{Makefile.in}s would be portable since they would
11823 list all files and not use @samp{$(wildcard ...)}. However that
11824 means developers would need to remember to run @command{automake} each
11825 time they add, delete, or rename files.
11827 Compared to editing @file{Makefile.am}, this is a very small gain. Sure,
11828 it's easier and faster to type @samp{automake; make} than to type
11829 @samp{emacs Makefile.am; make}. But nobody bothered enough to write a
11830 patch to add support for this syntax. Some people use scripts to
11831 generate file lists in @file{Makefile.am} or in separate
11832 @file{Makefile} fragments.
11834 Even if you don't care about portability, and are tempted to use
11835 @samp{$(wildcard ...)} anyway because you target only GNU Make, you
11836 should know there are many places where Automake needs to know exactly
11837 which files should be processed. As Automake doesn't know how to
11838 expand @samp{$(wildcard ...)}, you cannot use it in these places.
11839 @samp{$(wildcard ...)} is a black box comparable to @code{AC_SUBST}ed
11840 variables as far Automake is concerned.
11842 You can get warnings about @samp{$(wildcard ...}) constructs using the
11843 @option{-Wportability} flag.
11845 @node Limitations on File Names
11846 @section Limitations on File Names
11847 @cindex file names, limitations on
11849 Automake attempts to support all kinds of file names, even those that
11850 contain unusual characters or are unusually long. However, some
11851 limitations are imposed by the underlying operating system and tools.
11853 Most operating systems prohibit the use of the null byte in file
11854 names, and reserve @samp{/} as a directory separator. Also, they
11855 require that file names are properly encoded for the user's locale.
11856 Automake is subject to these limits.
11858 Portable packages should limit themselves to POSIX file
11859 names. These can contain ASCII letters and digits,
11860 @samp{_}, @samp{.}, and @samp{-}. File names consist of components
11861 separated by @samp{/}. File name components cannot begin with
11864 Portable POSIX file names cannot contain components that exceed a
11865 14-byte limit, but nowadays it's normally safe to assume the
11866 more-generous XOPEN limit of 255 bytes. POSIX
11867 limits file names to 255 bytes (XOPEN allows 1023 bytes),
11868 but you may want to limit a source tarball to file names of 99 bytes
11869 to avoid interoperability problems with old versions of @command{tar}.
11871 If you depart from these rules (e.g., by using non-ASCII
11872 characters in file names, or by using lengthy file names), your
11873 installers may have problems for reasons unrelated to Automake.
11874 However, if this does not concern you, you should know about the
11875 limitations imposed by Automake itself. These limitations are
11876 undesirable, but some of them seem to be inherent to underlying tools
11877 like Autoconf, Make, M4, and the shell. They fall into three
11878 categories: install directories, build directories, and file names.
11880 The following characters:
11883 @r{newline} " # $ ' `
11886 should not appear in the names of install directories. For example,
11887 the operand of @command{configure}'s @option{--prefix} option should
11888 not contain these characters.
11890 Build directories suffer the same limitations as install directories,
11891 and in addition should not contain the following characters:
11897 For example, the full name of the directory containing the source
11898 files should not contain these characters.
11900 Source and installation file names like @file{main.c} are limited even
11901 further: they should conform to the POSIX/XOPEN
11902 rules described above. In addition, if you plan to port to
11903 non-POSIX environments, you should avoid file names that
11904 differ only in case (e.g., @file{makefile} and @file{Makefile}).
11905 Nowadays it is no longer worth worrying about the 8.3 limits of
11908 @c FIXME This should probably be moved in the "Checking the Distribution"
11909 @c FIXME section...
11910 @node Errors with distclean
11911 @section Errors with distclean
11912 @cindex @code{distclean}, diagnostic
11913 @cindex @samp{make distclean}, diagnostic
11914 @cindex dependencies and distributed files
11917 This is a diagnostic you might encounter while running @samp{make
11920 As explained in @ref{Checking the Distribution}, @samp{make distcheck}
11921 attempts to build and check your package for errors like this one.
11923 @samp{make distcheck} will perform a @code{VPATH} build of your
11924 package (@pxref{VPATH Builds}), and then call @samp{make distclean}.
11925 Files left in the build directory after @samp{make distclean} has run
11926 are listed after this error.
11928 This diagnostic really covers two kinds of errors:
11932 files that are forgotten by distclean;
11934 distributed files that are erroneously rebuilt.
11937 The former left-over files are not distributed, so the fix is to mark
11938 them for cleaning (@pxref{Clean}), this is obvious and doesn't deserve
11941 The latter bug is not always easy to understand and fix, so let's
11942 proceed with an example. Suppose our package contains a program for
11943 which we want to build a man page using @command{help2man}. GNU
11944 @command{help2man} produces simple manual pages from the @option{--help}
11945 and @option{--version} output of other commands (@pxref{Top, , Overview,
11946 help2man, The Help2man Manual}). Because we don't want to force our
11947 users to install @command{help2man}, we decide to distribute the
11948 generated man page using the following setup.
11951 # This Makefile.am is bogus.
11953 foo_SOURCES = foo.c
11954 dist_man_MANS = foo.1
11956 foo.1: foo$(EXEEXT)
11957 help2man --output=foo.1 ./foo$(EXEEXT)
11960 This will effectively distribute the man page. However,
11961 @samp{make distcheck} will fail with:
11964 ERROR: files left in build directory after distclean:
11968 Why was @file{foo.1} rebuilt? Because although distributed,
11969 @file{foo.1} depends on a non-distributed built file:
11970 @file{foo$(EXEEXT)}. @file{foo$(EXEEXT)} is built by the user, so it
11971 will always appear to be newer than the distributed @file{foo.1}.
11973 @samp{make distcheck} caught an inconsistency in our package. Our
11974 intent was to distribute @file{foo.1} so users do not need to install
11975 @command{help2man}, however since this rule causes this file to be
11976 always rebuilt, users @emph{do} need @command{help2man}. Either we
11977 should ensure that @file{foo.1} is not rebuilt by users, or there is
11978 no point in distributing @file{foo.1}.
11980 More generally, the rule is that distributed files should never depend
11981 on non-distributed built files. If you distribute something
11982 generated, distribute its sources.
11984 One way to fix the above example, while still distributing
11985 @file{foo.1} is to not depend on @file{foo$(EXEEXT)}. For instance,
11986 assuming @command{foo --version} and @command{foo --help} do not
11987 change unless @file{foo.c} or @file{configure.ac} change, we could
11988 write the following @file{Makefile.am}:
11992 foo_SOURCES = foo.c
11993 dist_man_MANS = foo.1
11995 foo.1: foo.c $(top_srcdir)/configure.ac
11996 $(MAKE) $(AM_MAKEFLAGS) foo$(EXEEXT)
11997 help2man --output=foo.1 ./foo$(EXEEXT)
12000 This way, @file{foo.1} will not get rebuilt every time
12001 @file{foo$(EXEEXT)} changes. The @command{make} call makes sure
12002 @file{foo$(EXEEXT)} is up-to-date before @command{help2man}. Another
12003 way to ensure this would be to use separate directories for binaries
12004 and man pages, and set @code{SUBDIRS} so that binaries are built
12007 We could also decide not to distribute @file{foo.1}. In
12008 this case it's fine to have @file{foo.1} dependent upon
12009 @file{foo$(EXEEXT)}, since both will have to be rebuilt.
12010 However it would be impossible to build the package in a
12011 cross-compilation, because building @file{foo.1} involves
12012 an @emph{execution} of @file{foo$(EXEEXT)}.
12014 Another context where such errors are common is when distributed files
12015 are built by tools that are built by the package. The pattern is
12019 distributed-file: built-tools distributed-sources
12024 should be changed to
12027 distributed-file: distributed-sources
12028 $(MAKE) $(AM_MAKEFLAGS) built-tools
12033 or you could choose not to distribute @file{distributed-file}, if
12034 cross-compilation does not matter.
12036 The points made through these examples are worth a summary:
12041 Distributed files should never depend upon non-distributed built
12044 Distributed files should be distributed with all their dependencies.
12046 If a file is @emph{intended} to be rebuilt by users, then there is no point
12047 in distributing it.
12051 @vrindex distcleancheck_listfiles
12052 For desperate cases, it's always possible to disable this check by
12053 setting @code{distcleancheck_listfiles} as documented in @ref{Checking
12055 Make sure you do understand the reason why @samp{make distcheck}
12056 complains before you do this. @code{distcleancheck_listfiles} is a
12057 way to @emph{hide} errors, not to fix them. You can always do better.
12059 @node Flag Variables Ordering
12060 @section Flag Variables Ordering
12061 @cindex Ordering flag variables
12062 @cindex Flag variables, ordering
12065 What is the difference between @code{AM_CFLAGS}, @code{CFLAGS}, and
12066 @code{mumble_CFLAGS}?
12070 Why does @command{automake} output @code{CPPFLAGS} after
12071 @code{AM_CPPFLAGS} on compile lines? Shouldn't it be the converse?
12075 My @file{configure} adds some warning flags into @code{CXXFLAGS}. In
12076 one @file{Makefile.am} I would like to append a new flag, however if I
12077 put the flag into @code{AM_CXXFLAGS} it is prepended to the other
12078 flags, not appended.
12081 @subheading Compile Flag Variables
12082 @cindex Flag Variables, Ordering
12083 @cindex Compile Flag Variables
12084 @cindex @code{AM_CCASFLAGS} and @code{CCASFLAGS}
12085 @cindex @code{AM_CFLAGS} and @code{CFLAGS}
12086 @cindex @code{AM_CPPFLAGS} and @code{CPPFLAGS}
12087 @cindex @code{AM_CXXFLAGS} and @code{CXXFLAGS}
12088 @cindex @code{AM_FCFLAGS} and @code{FCFLAGS}
12089 @cindex @code{AM_FFLAGS} and @code{FFLAGS}
12090 @cindex @code{AM_GCJFLAGS} and @code{GCJFLAGS}
12091 @cindex @code{AM_LDFLAGS} and @code{LDFLAGS}
12092 @cindex @code{AM_LFLAGS} and @code{LFLAGS}
12093 @cindex @code{AM_LIBTOOLFLAGS} and @code{LIBTOOLFLAGS}
12094 @cindex @code{AM_OBJCFLAGS} and @code{OBJCFLAGS}
12095 @cindex @code{AM_OBJCXXFLAGS} and @code{OBJXXCFLAGS}
12096 @cindex @code{AM_RFLAGS} and @code{RFLAGS}
12097 @cindex @code{AM_UPCFLAGS} and @code{UPCFLAGS}
12098 @cindex @code{AM_YFLAGS} and @code{YFLAGS}
12099 @cindex @code{CCASFLAGS} and @code{AM_CCASFLAGS}
12100 @cindex @code{CFLAGS} and @code{AM_CFLAGS}
12101 @cindex @code{CPPFLAGS} and @code{AM_CPPFLAGS}
12102 @cindex @code{CXXFLAGS} and @code{AM_CXXFLAGS}
12103 @cindex @code{FCFLAGS} and @code{AM_FCFLAGS}
12104 @cindex @code{FFLAGS} and @code{AM_FFLAGS}
12105 @cindex @code{GCJFLAGS} and @code{AM_GCJFLAGS}
12106 @cindex @code{LDFLAGS} and @code{AM_LDFLAGS}
12107 @cindex @code{LFLAGS} and @code{AM_LFLAGS}
12108 @cindex @code{LIBTOOLFLAGS} and @code{AM_LIBTOOLFLAGS}
12109 @cindex @code{OBJCFLAGS} and @code{AM_OBJCFLAGS}
12110 @cindex @code{OBJCXXFLAGS} and @code{AM_OBJCXXFLAGS}
12111 @cindex @code{RFLAGS} and @code{AM_RFLAGS}
12112 @cindex @code{UPCFLAGS} and @code{AM_UPCFLAGS}
12113 @cindex @code{YFLAGS} and @code{AM_YFLAGS}
12115 This section attempts to answer all the above questions. We will
12116 mostly discuss @code{CPPFLAGS} in our examples, but actually the
12117 answer holds for all the compile flags used in Automake:
12118 @code{CCASFLAGS}, @code{CFLAGS}, @code{CPPFLAGS}, @code{CXXFLAGS},
12119 @code{FCFLAGS}, @code{FFLAGS}, @code{GCJFLAGS}, @code{LDFLAGS},
12120 @code{LFLAGS}, @code{LIBTOOLFLAGS}, @code{OBJCFLAGS}, @code{OBJCXXFLAGS},
12121 @code{RFLAGS}, @code{UPCFLAGS}, and @code{YFLAGS}.
12123 @code{CPPFLAGS}, @code{AM_CPPFLAGS}, and @code{mumble_CPPFLAGS} are
12124 three variables that can be used to pass flags to the C preprocessor
12125 (actually these variables are also used for other languages like C++
12126 or preprocessed Fortran). @code{CPPFLAGS} is the user variable
12127 (@pxref{User Variables}), @code{AM_CPPFLAGS} is the Automake variable,
12128 and @code{mumble_CPPFLAGS} is the variable specific to the
12129 @code{mumble} target (we call this a per-target variable,
12130 @pxref{Program and Library Variables}).
12132 Automake always uses two of these variables when compiling C sources
12133 files. When compiling an object file for the @code{mumble} target,
12134 the first variable will be @code{mumble_CPPFLAGS} if it is defined, or
12135 @code{AM_CPPFLAGS} otherwise. The second variable is always
12138 In the following example,
12141 bin_PROGRAMS = foo bar
12142 foo_SOURCES = xyz.c
12143 bar_SOURCES = main.c
12144 foo_CPPFLAGS = -DFOO
12145 AM_CPPFLAGS = -DBAZ
12149 @file{xyz.o} will be compiled with @samp{$(foo_CPPFLAGS) $(CPPFLAGS)},
12150 (because @file{xyz.o} is part of the @code{foo} target), while
12151 @file{main.o} will be compiled with @samp{$(AM_CPPFLAGS) $(CPPFLAGS)}
12152 (because there is no per-target variable for target @code{bar}).
12154 The difference between @code{mumble_CPPFLAGS} and @code{AM_CPPFLAGS}
12155 being clear enough, let's focus on @code{CPPFLAGS}. @code{CPPFLAGS}
12156 is a user variable, i.e., a variable that users are entitled to modify
12157 in order to compile the package. This variable, like many others,
12158 is documented at the end of the output of @samp{configure --help}.
12160 For instance, someone who needs to add @file{/home/my/usr/include} to
12161 the C compiler's search path would configure a package with
12164 ./configure CPPFLAGS='-I /home/my/usr/include'
12168 and this flag would be propagated to the compile rules of all
12171 It is also not uncommon to override a user variable at
12172 @command{make}-time. Many installers do this with @code{prefix}, but
12173 this can be useful with compiler flags too. For instance, if, while
12174 debugging a C++ project, you need to disable optimization in one
12175 specific object file, you can run something like
12179 make CXXFLAGS=-O0 file.o
12183 The reason @samp{$(CPPFLAGS)} appears after @samp{$(AM_CPPFLAGS)} or
12184 @samp{$(mumble_CPPFLAGS)} in the compile command is that users
12185 should always have the last say. It probably makes more sense if you
12186 think about it while looking at the @samp{CXXFLAGS=-O0} above, which
12187 should supersede any other switch from @code{AM_CXXFLAGS} or
12188 @code{mumble_CXXFLAGS} (and this of course replaces the previous value
12189 of @code{CXXFLAGS}).
12191 You should never redefine a user variable such as @code{CPPFLAGS} in
12192 @file{Makefile.am}. Use @samp{automake -Woverride} to diagnose such
12193 mistakes. Even something like
12196 CPPFLAGS = -DDATADIR=\"$(datadir)\" @@CPPFLAGS@@
12200 is erroneous. Although this preserves @file{configure}'s value of
12201 @code{CPPFLAGS}, the definition of @code{DATADIR} will disappear if a
12202 user attempts to override @code{CPPFLAGS} from the @command{make}
12206 AM_CPPFLAGS = -DDATADIR=\"$(datadir)\"
12210 is all that is needed here if no per-target flags are used.
12212 You should not add options to these user variables within
12213 @file{configure} either, for the same reason. Occasionally you need
12214 to modify these variables to perform a test, but you should reset
12215 their values afterwards. In contrast, it is OK to modify the
12216 @samp{AM_} variables within @file{configure} if you @code{AC_SUBST}
12217 them, but it is rather rare that you need to do this, unless you
12218 really want to change the default definitions of the @samp{AM_}
12219 variables in all @file{Makefile}s.
12221 What we recommend is that you define extra flags in separate
12222 variables. For instance, you may write an Autoconf macro that computes
12223 a set of warning options for the C compiler, and @code{AC_SUBST} them
12224 in @code{WARNINGCFLAGS}; you may also have an Autoconf macro that
12225 determines which compiler and which linker flags should be used to
12226 link with library @file{libfoo}, and @code{AC_SUBST} these in
12227 @code{LIBFOOCFLAGS} and @code{LIBFOOLDFLAGS}. Then, a
12228 @file{Makefile.am} could use these variables as follows:
12231 AM_CFLAGS = $(WARNINGCFLAGS)
12232 bin_PROGRAMS = prog1 prog2
12233 prog1_SOURCES = @dots{}
12234 prog2_SOURCES = @dots{}
12235 prog2_CFLAGS = $(LIBFOOCFLAGS) $(AM_CFLAGS)
12236 prog2_LDFLAGS = $(LIBFOOLDFLAGS)
12239 In this example both programs will be compiled with the flags
12240 substituted into @samp{$(WARNINGCFLAGS)}, and @code{prog2} will
12241 additionally be compiled with the flags required to link with
12244 Note that listing @code{AM_CFLAGS} in a per-target @code{CFLAGS}
12245 variable is a common idiom to ensure that @code{AM_CFLAGS} applies to
12246 every target in a @file{Makefile.in}.
12248 Using variables like this gives you full control over the ordering of
12249 the flags. For instance, if there is a flag in $(WARNINGCFLAGS) that
12250 you want to negate for a particular target, you can use something like
12251 @samp{prog1_CFLAGS = $(AM_CFLAGS) -no-flag}. If all of these flags had
12252 been forcefully appended to @code{CFLAGS}, there would be no way to
12253 disable one flag. Yet another reason to leave user variables to
12256 Finally, we have avoided naming the variable of the example
12257 @code{LIBFOO_LDFLAGS} (with an underscore) because that would cause
12258 Automake to think that this is actually a per-target variable (like
12259 @code{mumble_LDFLAGS}) for some non-declared @code{LIBFOO} target.
12261 @subheading Other Variables
12263 There are other variables in Automake that follow similar principles
12264 to allow user options. For instance, Texinfo rules (@pxref{Texinfo})
12265 use @code{MAKEINFOFLAGS} and @code{AM_MAKEINFOFLAGS}. Similarly,
12266 DejaGnu tests (@pxref{DejaGnu Tests}) use @code{RUNTESTDEFAULTFLAGS} and
12267 @code{AM_RUNTESTDEFAULTFLAGS}. The tags and ctags rules
12268 (@pxref{Tags}) use @code{ETAGSFLAGS}, @code{AM_ETAGSFLAGS},
12269 @code{CTAGSFLAGS}, and @code{AM_CTAGSFLAGS}. Java rules
12270 (@pxref{Java}) use @code{JAVACFLAGS} and @code{AM_JAVACFLAGS}. None
12271 of these rules support per-target flags (yet).
12273 To some extent, even @code{AM_MAKEFLAGS} (@pxref{Subdirectories})
12274 obeys this naming scheme. The slight difference is that
12275 @code{MAKEFLAGS} is passed to sub-@command{make}s implicitly by
12276 @command{make} itself.
12278 @code{ARFLAGS} (@pxref{A Library}) is usually defined by Automake and
12279 has neither @code{AM_} nor per-target cousin.
12281 Finally you should not think that the existence of a per-target
12282 variable implies the existence of an @code{AM_} variable or of a user
12283 variable. For instance, the @code{mumble_LDADD} per-target variable
12284 overrides the makefile-wide @code{LDADD} variable (which is not a user
12285 variable), and @code{mumble_LIBADD} exists only as a per-target
12286 variable. @xref{Program and Library Variables}.
12289 @node Renamed Objects
12290 @section Why are object files sometimes renamed?
12292 This happens when per-target compilation flags are used. Object
12293 files need to be renamed just in case they would clash with object
12294 files compiled from the same sources, but with different flags.
12295 Consider the following example.
12298 bin_PROGRAMS = true false
12299 true_SOURCES = generic.c
12300 true_CPPFLAGS = -DEXIT_CODE=0
12301 false_SOURCES = generic.c
12302 false_CPPFLAGS = -DEXIT_CODE=1
12306 Obviously the two programs are built from the same source, but it
12307 would be bad if they shared the same object, because @file{generic.o}
12308 cannot be built with both @samp{-DEXIT_CODE=0} @emph{and}
12309 @samp{-DEXIT_CODE=1}. Therefore @command{automake} outputs rules to
12310 build two different objects: @file{true-generic.o} and
12311 @file{false-generic.o}.
12313 @command{automake} doesn't actually look whether source files are
12314 shared to decide if it must rename objects. It will just rename all
12315 objects of a target as soon as it sees per-target compilation flags
12318 It's OK to share object files when per-target compilation flags are not
12319 used. For instance, @file{true} and @file{false} will both use
12320 @file{version.o} in the following example.
12323 AM_CPPFLAGS = -DVERSION=1.0
12324 bin_PROGRAMS = true false
12325 true_SOURCES = true.c version.c
12326 false_SOURCES = false.c version.c
12329 Note that the renaming of objects is also affected by the
12330 @code{_SHORTNAME} variable (@pxref{Program and Library Variables}).
12333 @node Per-Object Flags
12334 @section Per-Object Flags Emulation
12335 @cindex Per-object flags, emulated
12338 One of my source files needs to be compiled with different flags. How
12342 Automake supports per-program and per-library compilation flags (see
12343 @ref{Program and Library Variables} and @ref{Flag Variables
12344 Ordering}). With this you can define compilation flags that apply to
12345 all files compiled for a target. For instance, in
12349 foo_SOURCES = foo.c foo.h bar.c bar.h main.c
12350 foo_CFLAGS = -some -flags
12354 @file{foo-foo.o}, @file{foo-bar.o}, and @file{foo-main.o} will all be
12355 compiled with @samp{-some -flags}. (If you wonder about the names of
12356 these object files, see @ref{Renamed Objects}.) Note that
12357 @code{foo_CFLAGS} gives the flags to use when compiling all the C
12358 sources of the @emph{program} @code{foo}, it has nothing to do with
12359 @file{foo.c} or @file{foo-foo.o} specifically.
12361 What if @file{foo.c} needs to be compiled into @file{foo.o} using some
12362 specific flags, that none of the other files requires? Obviously
12363 per-program flags are not directly applicable here. Something like
12364 per-object flags are expected, i.e., flags that would be used only
12365 when creating @file{foo-foo.o}. Automake does not support that,
12366 however this is easy to simulate using a library that contains only
12367 that object, and compiling this library with per-library flags.
12371 foo_SOURCES = bar.c bar.h main.c
12372 foo_CFLAGS = -some -flags
12373 foo_LDADD = libfoo.a
12374 noinst_LIBRARIES = libfoo.a
12375 libfoo_a_SOURCES = foo.c foo.h
12376 libfoo_a_CFLAGS = -some -other -flags
12379 Here @file{foo-bar.o} and @file{foo-main.o} will all be
12380 compiled with @samp{-some -flags}, while @file{libfoo_a-foo.o} will
12381 be compiled using @samp{-some -other -flags}. Eventually, all
12382 three objects will be linked to form @file{foo}.
12384 This trick can also be achieved using Libtool convenience libraries,
12385 for instance @samp{noinst_LTLIBRARIES = libfoo.la} (@pxref{Libtool
12386 Convenience Libraries}).
12388 Another tempting idea to implement per-object flags is to override the
12389 compile rules @command{automake} would output for these files.
12390 Automake will not define a rule for a target you have defined, so you
12391 could think about defining the @samp{foo-foo.o: foo.c} rule yourself.
12392 We recommend against this, because this is error prone. For instance,
12393 if you add such a rule to the first example, it will break the day you
12394 decide to remove @code{foo_CFLAGS} (because @file{foo.c} will then be
12395 compiled as @file{foo.o} instead of @file{foo-foo.o}, @pxref{Renamed
12396 Objects}). Also in order to support dependency tracking, the two
12397 @file{.o}/@file{.obj} extensions, and all the other flags variables
12398 involved in a compilation, you will end up modifying a copy of the
12399 rule previously output by @command{automake} for this file. If a new
12400 release of Automake generates a different rule, your copy will need to
12401 be updated by hand.
12403 @node Multiple Outputs
12404 @section Handling Tools that Produce Many Outputs
12405 @cindex multiple outputs, rules with
12406 @cindex many outputs, rules with
12407 @cindex rules with multiple outputs
12409 This section describes a @command{make} idiom that can be used when a
12410 tool produces multiple output files. It is not specific to Automake
12411 and can be used in ordinary @file{Makefile}s.
12413 Suppose we have a program called @command{foo} that will read one file
12414 called @file{data.foo} and produce two files named @file{data.c} and
12415 @file{data.h}. We want to write a @file{Makefile} rule that captures
12416 this one-to-two dependency.
12418 The naive rule is incorrect:
12421 # This is incorrect.
12422 data.c data.h: data.foo
12427 What the above rule really says is that @file{data.c} and
12428 @file{data.h} each depend on @file{data.foo}, and can each be built by
12429 running @samp{foo data.foo}. In other words it is equivalent to:
12432 # We do not want this.
12440 which means that @command{foo} can be run twice. Usually it will not
12441 be run twice, because @command{make} implementations are smart enough
12442 to check for the existence of the second file after the first one has
12443 been built; they will therefore detect that it already exists.
12444 However there are a few situations where it can run twice anyway:
12448 The most worrying case is when running a parallel @command{make}. If
12449 @file{data.c} and @file{data.h} are built in parallel, two @samp{foo
12450 data.foo} commands will run concurrently. This is harmful.
12452 Another case is when the dependency (here @file{data.foo}) is
12453 (or depends upon) a phony target.
12456 A solution that works with parallel @command{make} but not with
12457 phony dependencies is the following:
12460 data.c data.h: data.foo
12466 The above rules are equivalent to
12471 data.h: data.foo data.c
12476 therefore a parallel @command{make} will have to serialize the builds
12477 of @file{data.c} and @file{data.h}, and will detect that the second is
12478 no longer needed once the first is over.
12480 Using this pattern is probably enough for most cases. However it does
12481 not scale easily to more output files (in this scheme all output files
12482 must be totally ordered by the dependency relation), so we will
12483 explore a more complicated solution.
12485 Another idea is to write the following:
12488 # There is still a problem with this one.
12495 The idea is that @samp{foo data.foo} is run only when @file{data.c}
12496 needs to be updated, but we further state that @file{data.h} depends
12497 upon @file{data.c}. That way, if @file{data.h} is required and
12498 @file{data.foo} is out of date, the dependency on @file{data.c} will
12501 This is almost perfect, but suppose we have built @file{data.h} and
12502 @file{data.c}, and then we erase @file{data.h}. Then, running
12503 @samp{make data.h} will not rebuild @file{data.h}. The above rules
12504 just state that @file{data.c} must be up-to-date with respect to
12505 @file{data.foo}, and this is already the case.
12507 What we need is a rule that forces a rebuild when @file{data.h} is
12508 missing. Here it is:
12514 ## Recover from the removal of $@@
12515 @@if test -f $@@; then :; else \
12517 $(MAKE) $(AM_MAKEFLAGS) data.c; \
12521 The above scheme can be extended to handle more outputs and more
12522 inputs. One of the outputs is selected to serve as a witness to the
12523 successful completion of the command, it depends upon all inputs, and
12524 all other outputs depend upon it. For instance, if @command{foo}
12525 should additionally read @file{data.bar} and also produce
12526 @file{data.w} and @file{data.x}, we would write:
12529 data.c: data.foo data.bar
12530 foo data.foo data.bar
12531 data.h data.w data.x: data.c
12532 ## Recover from the removal of $@@
12533 @@if test -f $@@; then :; else \
12535 $(MAKE) $(AM_MAKEFLAGS) data.c; \
12539 However there are now three minor problems in this setup. One is related
12540 to the timestamp ordering of @file{data.h}, @file{data.w},
12541 @file{data.x}, and @file{data.c}. Another one is a race condition
12542 if a parallel @command{make} attempts to run multiple instances of the
12543 recover block at once. Finally, the recursive rule breaks @samp{make -n}
12544 when run with GNU @command{make} (as well as some other @command{make}
12545 implementations), as it may remove @file{data.h} even when it should not
12546 (@pxref{MAKE Variable, , How the @code{MAKE} Variable Works, make,
12547 The GNU Make Manual}).
12549 Let us deal with the first problem. @command{foo} outputs four files,
12550 but we do not know in which order these files are created. Suppose
12551 that @file{data.h} is created before @file{data.c}. Then we have a
12552 weird situation. The next time @command{make} is run, @file{data.h}
12553 will appear older than @file{data.c}, the second rule will be
12554 triggered, a shell will be started to execute the @samp{if@dots{}fi}
12555 command, but actually it will just execute the @code{then} branch,
12556 that is: nothing. In other words, because the witness we selected is
12557 not the first file created by @command{foo}, @command{make} will start
12558 a shell to do nothing each time it is run.
12560 A simple riposte is to fix the timestamps when this happens.
12563 data.c: data.foo data.bar
12564 foo data.foo data.bar
12565 data.h data.w data.x: data.c
12566 @@if test -f $@@; then \
12569 ## Recover from the removal of $@@
12571 $(MAKE) $(AM_MAKEFLAGS) data.c; \
12575 Another solution is to use a different and dedicated file as witness,
12576 rather than using any of @command{foo}'s outputs.
12579 data.stamp: data.foo data.bar
12582 foo data.foo data.bar
12583 @@mv -f data.tmp $@@
12584 data.c data.h data.w data.x: data.stamp
12585 ## Recover from the removal of $@@
12586 @@if test -f $@@; then :; else \
12587 rm -f data.stamp; \
12588 $(MAKE) $(AM_MAKEFLAGS) data.stamp; \
12592 @file{data.tmp} is created before @command{foo} is run, so it has a
12593 timestamp older than output files output by @command{foo}. It is then
12594 renamed to @file{data.stamp} after @command{foo} has run, because we
12595 do not want to update @file{data.stamp} if @command{foo} fails.
12597 This solution still suffers from the second problem: the race
12598 condition in the recover rule. If, after a successful build, a user
12599 erases @file{data.c} and @file{data.h}, and runs @samp{make -j}, then
12600 @command{make} may start both recover rules in parallel. If the two
12601 instances of the rule execute @samp{$(MAKE) $(AM_MAKEFLAGS)
12602 data.stamp} concurrently the build is likely to fail (for instance, the
12603 two rules will create @file{data.tmp}, but only one can rename it).
12605 Admittedly, such a weird situation does not arise during ordinary
12606 builds. It occurs only when the build tree is mutilated. Here
12607 @file{data.c} and @file{data.h} have been explicitly removed without
12608 also removing @file{data.stamp} and the other output files.
12609 @code{make clean; make} will always recover from these situations even
12610 with parallel makes, so you may decide that the recover rule is solely
12611 to help non-parallel make users and leave things as-is. Fixing this
12612 requires some locking mechanism to ensure only one instance of the
12613 recover rule rebuilds @file{data.stamp}. One could imagine something
12614 along the following lines.
12617 data.c data.h data.w data.x: data.stamp
12618 ## Recover from the removal of $@@
12619 @@if test -f $@@; then :; else \
12620 trap 'rm -rf data.lock data.stamp' 1 2 13 15; \
12621 ## mkdir is a portable test-and-set
12622 if mkdir data.lock 2>/dev/null; then \
12623 ## This code is being executed by the first process.
12624 rm -f data.stamp; \
12625 $(MAKE) $(AM_MAKEFLAGS) data.stamp; \
12626 result=$$?; rm -rf data.lock; exit $$result; \
12628 ## This code is being executed by the follower processes.
12629 ## Wait until the first process is done.
12630 while test -d data.lock; do sleep 1; done; \
12631 ## Succeed if and only if the first process succeeded.
12632 test -f data.stamp; \
12637 Using a dedicated witness, like @file{data.stamp}, is very handy when
12638 the list of output files is not known beforehand. As an illustration,
12639 consider the following rules to compile many @file{*.el} files into
12640 @file{*.elc} files in a single command. It does not matter how
12641 @code{ELFILES} is defined (as long as it is not empty: empty targets
12642 are not accepted by POSIX).
12645 ELFILES = one.el two.el three.el @dots{}
12646 ELCFILES = $(ELFILES:=c)
12648 elc-stamp: $(ELFILES)
12651 $(elisp_comp) $(ELFILES)
12652 @@mv -f elc-temp $@@
12654 $(ELCFILES): elc-stamp
12655 @@if test -f $@@; then :; else \
12656 ## Recover from the removal of $@@
12657 trap 'rm -rf elc-lock elc-stamp' 1 2 13 15; \
12658 if mkdir elc-lock 2>/dev/null; then \
12659 ## This code is being executed by the first process.
12661 $(MAKE) $(AM_MAKEFLAGS) elc-stamp; \
12664 ## This code is being executed by the follower processes.
12665 ## Wait until the first process is done.
12666 while test -d elc-lock; do sleep 1; done; \
12667 ## Succeed if and only if the first process succeeded.
12668 test -f elc-stamp; exit $$?; \
12674 These solutions all still suffer from the third problem, namely that
12675 they break the promise that @samp{make -n} should not cause any actual
12676 changes to the tree. For those solutions that do not create lock files,
12677 it is possible to split the recover rules into two separate recipe
12678 commands, one of which does all work but the recursion, and the
12679 other invokes the recursive @samp{$(MAKE)}. The solutions involving
12680 locking could act upon the contents of the @samp{MAKEFLAGS} variable,
12681 but parsing that portably is not easy (@pxref{The Make Macro MAKEFLAGS,,,
12682 autoconf, The Autoconf Manual}). Here is an example:
12685 ELFILES = one.el two.el three.el @dots{}
12686 ELCFILES = $(ELFILES:=c)
12688 elc-stamp: $(ELFILES)
12691 $(elisp_comp) $(ELFILES)
12692 @@mv -f elc-temp $@@
12694 $(ELCFILES): elc-stamp
12695 ## Recover from the removal of $@@
12696 @@dry=; for f in x $$MAKEFLAGS; do \
12702 if test -f $@@; then :; else \
12703 $$dry trap 'rm -rf elc-lock elc-stamp' 1 2 13 15; \
12704 if $$dry mkdir elc-lock 2>/dev/null; then \
12705 ## This code is being executed by the first process.
12706 $$dry rm -f elc-stamp; \
12707 $(MAKE) $(AM_MAKEFLAGS) elc-stamp; \
12708 $$dry rmdir elc-lock; \
12710 ## This code is being executed by the follower processes.
12711 ## Wait until the first process is done.
12712 while test -d elc-lock && test -z "$$dry"; do \
12716 ## Succeed if and only if the first process succeeded.
12717 $$dry test -f elc-stamp; exit $$?; \
12722 For completeness it should be noted that GNU @command{make} is able to
12723 express rules with multiple output files using pattern rules
12724 (@pxref{Pattern Examples, , Pattern Rule Examples, make, The GNU Make
12725 Manual}). We do not discuss pattern rules here because they are not
12726 portable, but they can be convenient in packages that assume GNU
12730 @node Hard-Coded Install Paths
12731 @section Installing to Hard-Coded Locations
12734 My package needs to install some configuration file. I tried to use
12735 the following rule, but @samp{make distcheck} fails. Why?
12739 install-data-local:
12740 $(INSTALL_DATA) $(srcdir)/afile $(DESTDIR)/etc/afile
12745 My package needs to populate the installation directory of another
12746 package at install-time. I can easily compute that installation
12747 directory in @file{configure}, but if I install files therein,
12748 @samp{make distcheck} fails. How else should I do?
12751 These two setups share their symptoms: @samp{make distcheck} fails
12752 because they are installing files to hard-coded paths. In the later
12753 case the path is not really hard-coded in the package, but we can
12754 consider it to be hard-coded in the system (or in whichever tool that
12755 supplies the path). As long as the path does not use any of the
12756 standard directory variables (@samp{$(prefix)}, @samp{$(bindir)},
12757 @samp{$(datadir)}, etc.), the effect will be the same:
12758 user-installations are impossible.
12760 As a (non-root) user who wants to install a package, you usually have no
12761 right to install anything in @file{/usr} or @file{/usr/local}. So you
12762 do something like @samp{./configure --prefix ~/usr} to install a
12763 package in your own @file{~/usr} tree.
12765 If a package attempts to install something to some hard-coded path
12766 (e.g., @file{/etc/afile}), regardless of this @option{--prefix} setting,
12767 then the installation will fail. @samp{make distcheck} performs such
12768 a @option{--prefix} installation, hence it will fail too.
12770 Now, there are some easy solutions.
12772 The above @code{install-data-local} example for installing
12773 @file{/etc/afile} would be better replaced by
12776 sysconf_DATA = afile
12780 by default @code{sysconfdir} will be @samp{$(prefix)/etc}, because
12781 this is what the GNU Standards require. When such a package is
12782 installed on an FHS compliant system, the installer will have to set
12783 @samp{--sysconfdir=/etc}. As the maintainer of the package you
12784 should not be concerned by such site policies: use the appropriate
12785 standard directory variable to install your files so that the installer
12786 can easily redefine these variables to match their site conventions.
12788 Installing files that should be used by another package is slightly
12789 more involved. Let's take an example and assume you want to install
12790 a shared library that is a Python extension module. If you ask Python
12791 where to install the library, it will answer something like this:
12794 % @kbd{python -c 'from distutils import sysconfig;
12795 print sysconfig.get_python_lib(1,0)'}
12796 /usr/lib/python2.5/site-packages
12799 If you indeed use this absolute path to install your shared library,
12800 non-root users will not be able to install the package, hence
12803 Let's do better. The @samp{sysconfig.get_python_lib()} function
12804 actually accepts a third argument that will replace Python's
12805 installation prefix.
12808 % @kbd{python -c 'from distutils import sysconfig;
12809 print sysconfig.get_python_lib(1,0,"$@{exec_prefix@}")'}
12810 $@{exec_prefix@}/lib/python2.5/site-packages
12813 You can also use this new path. If you do
12816 root users can install your package with the same @option{--prefix}
12817 as Python (you get the behavior of the previous attempt)
12820 non-root users can install your package too, they will have the
12821 extension module in a place that is not searched by Python but they
12822 can work around this using environment variables (and if you installed
12823 scripts that use this shared library, it's easy to tell Python were to
12824 look in the beginning of your script, so the script works in both
12828 The @code{AM_PATH_PYTHON} macro uses similar commands to define
12829 @samp{$(pythondir)} and @samp{$(pyexecdir)} (@pxref{Python}).
12831 Of course not all tools are as advanced as Python regarding that
12832 substitution of @var{prefix}. So another strategy is to figure the
12833 part of the installation directory that must be preserved. For
12834 instance, here is how @code{AM_PATH_LISPDIR} (@pxref{Emacs Lisp})
12835 computes @samp{$(lispdir)}:
12838 $EMACS -batch -q -eval '(while load-path
12839 (princ (concat (car load-path) "\n"))
12840 (setq load-path (cdr load-path)))' >conftest.out
12843 -e '/.*\/lib\/x*emacs\/site-lisp$/@{
12844 s,.*/lib/\(x*emacs/site-lisp\)$,$@{libdir@}/\1,;p;q;
12846 -e '/.*\/share\/x*emacs\/site-lisp$/@{
12847 s,.*/share/\(x*emacs/site-lisp\),$@{datarootdir@}/\1,;p;q;
12852 I.e., it just picks the first directory that looks like
12853 @file{*/lib/*emacs/site-lisp} or @file{*/share/*emacs/site-lisp} in
12854 the search path of emacs, and then substitutes @samp{$@{libdir@}} or
12855 @samp{$@{datadir@}} appropriately.
12857 The emacs case looks complicated because it processes a list and
12858 expects two possible layouts, otherwise it's easy, and the benefits for
12859 non-root users are really worth the extra @command{sed} invocation.
12862 @node Debugging Make Rules
12863 @section Debugging Make Rules
12864 @cindex debugging rules
12865 @cindex rules, debugging
12867 The rules and dependency trees generated by @command{automake} can get
12868 rather complex, and leave the developer head-scratching when things
12869 don't work as expected. Besides the debug options provided by the
12870 @command{make} command (@pxref{Options Summary,,, make, The GNU Make
12871 Manual}), here's a couple of further hints for debugging makefiles
12872 generated by @command{automake} effectively:
12876 If less verbose output has been enabled in the package with the use
12877 of silent rules (@pxref{Automake Silent Rules}), you can use
12878 @code{make V=1} to see the commands being executed.
12880 @code{make -n} can help show what would be done without actually doing
12881 it. Note however, that this will @emph{still execute} commands prefixed
12882 with @samp{+}, and, when using GNU @command{make}, commands that contain
12883 the strings @samp{$(MAKE)} or @samp{$@{MAKE@}} (@pxref{Instead of
12884 Execution,,, make, The GNU Make Manual}).
12885 Typically, this is helpful to show what recursive rules would do, but it
12886 means that, in your own rules, you should not mix such recursion with
12887 actions that change any files.@footnote{Automake's @samp{dist} and
12888 @samp{distcheck} rules had a bug in this regard in that they created
12889 directories even with @option{-n}, but this has been fixed in Automake
12890 1.11.} Furthermore, note that GNU @command{make} will update
12891 prerequisites for the @file{Makefile} file itself even with @option{-n}
12892 (@pxref{Remaking Makefiles,,, make, The GNU Make Manual}).
12894 @code{make SHELL="/bin/bash -vx"} can help debug complex rules.
12895 @xref{The Make Macro SHELL,,, autoconf, The Autoconf Manual}, for some
12896 portability quirks associated with this construct.
12898 @code{echo 'print: ; @@echo "$(VAR)"' | make -f Makefile -f - print}
12899 can be handy to examine the expanded value of variables. You may need
12900 to use a target other than @samp{print} if that is already used or a
12901 file with that name exists.
12903 @url{http://bashdb.sourceforge.net/@/remake/} provides a modified
12904 GNU @command{make} command called @command{remake} that copes with
12905 complex GNU @command{make}-specific Makefiles and allows to trace
12906 execution, examine variables, and call rules interactively, much like
12911 @node Reporting Bugs
12912 @section Reporting Bugs
12914 Most nontrivial software has bugs. Automake is no exception. Although
12915 we cannot promise we can or will fix a bug, and we might not even agree
12916 that it is a bug, we want to hear about problems you encounter. Often we
12917 agree they are bugs and want to fix them.
12919 To make it possible for us to fix a bug, please report it. In order to
12920 do so effectively, it helps to know when and how to do it.
12922 Before reporting a bug, it is a good idea to see if it is already known.
12923 You can look at the @uref{http://debbugs.gnu.org/, GNU Bug Tracker}
12924 and the @uref{http://lists.gnu.org/@/archive/@/html/@/bug-automake/,
12925 bug-automake mailing list archives} for previous bug reports. We
12927 @uref{http://sourceware.org/@/cgi-bin/@/gnatsweb.pl?database=automake,
12928 Gnats database} for bug tracking, so some bugs might have been reported
12929 there already. Please do not use it for new bug reports, however.
12931 If the bug is not already known, it should be reported. It is very
12932 important to report bugs in a way that is useful and efficient. For
12933 this, please familiarize yourself with
12934 @uref{http://www.chiark.greenend.org.uk/@/~sgtatham/@/bugs.html, How to
12935 Report Bugs Effectively} and
12936 @uref{http://catb.org/@/~esr/@/faqs/@/smart-questions.html, How to Ask
12937 Questions the Smart Way}. This helps you and developers to save time
12938 which can then be spent on fixing more bugs and implementing more
12941 For a bug report, a feature request or other suggestions, please send
12942 email to @email{@value{PACKAGE_BUGREPORT}}. This will then open a new
12943 bug in the @uref{http://debbugs.gnu.org/@/automake, bug tracker}. Be
12944 sure to include the versions of Autoconf and Automake that you use.
12945 Ideally, post a minimal @file{Makefile.am} and @file{configure.ac} that
12946 reproduces the problem you encounter. If you have encountered test
12947 suite failures, please attach the @file{test-suite.log} file.
12949 @c ========================================================== Appendices
12952 @node Copying This Manual
12953 @appendix Copying This Manual
12956 * GNU Free Documentation License:: License for copying this manual
12959 @node GNU Free Documentation License
12960 @appendixsec GNU Free Documentation License
12968 * Macro Index:: Index of Autoconf macros
12969 * Variable Index:: Index of Makefile variables
12970 * General Index:: General index
12974 @appendixsec Macro Index
12978 @node Variable Index
12979 @appendixsec Variable Index
12983 @node General Index
12984 @appendixsec General Index
12991 @c LocalWords: texinfo setfilename settitle setchapternewpage texi direntry
12992 @c LocalWords: dircategory in's aclocal ifinfo titlepage Tromey vskip pt sp
12993 @c LocalWords: filll defcodeindex ov cv op tr syncodeindex fn cp vr ifnottex
12994 @c LocalWords: dir Automake's ac Dist Gnits gnits dfn Autoconf's pxref
12995 @c LocalWords: cindex Autoconf autoconf perl samp cvs dist trindex SUBST foo
12996 @c LocalWords: xs emph FIXME ref vindex pkglibdir pkgincludedir pkgdatadir mt
12997 @c LocalWords: pkg libdir cpio bindir sbindir rmt pax sbin zar zardir acindex
12998 @c LocalWords: HTML htmldir html noinst TEXINFOS nodist nobase strudel CFLAGS
12999 @c LocalWords: libmumble CC YFLAGS itemx de fication config url comp
13000 @c LocalWords: depcomp elisp sh mdate mkinstalldirs mkdir py tex dvi ps pdf
13001 @c LocalWords: ylwrap zardoz INIT gettext acinclude mv FUNCS LIBOBJS LDADD fr
13002 @c LocalWords: uref featureful dnl src LINGUAS es ko nl pl sl sv PROG ISC doc
13003 @c LocalWords: POSIX STDC fcntl FUNC ALLOCA blksize struct stat intl po chmod
13004 @c LocalWords: ChangeLog SUBDIRS gettextize gpl testdata getopt INTLLIBS cpp
13005 @c LocalWords: localedir datadir DLOCALEDIR DEXIT CPPFLAGS autoreconf opindex
13006 @c LocalWords: AUX var symlink deps Wno Wnone package's aclocal's distclean
13007 @c LocalWords: ltmain xref LIBSOURCE LIBSOURCES LIBOBJ MEMCMP vs RANLIB CXX
13008 @c LocalWords: LDFLAGS LIBTOOL libtool XTRA LIBS gettext's acdir APIVERSION
13009 @c LocalWords: dirlist noindent usr TIOCGWINSZ sc
13010 @c LocalWords: GWINSZ termios SRCDIR tarball bzip LISPDIR lispdir XEmacs CCAS
13011 @c LocalWords: emacsen MicroEmacs CCASFLAGS UX GCJ gcj GCJFLAGS posix DMALLOC
13012 @c LocalWords: dmalloc ldmalloc REGEX regex DEPDIR DEP DEFUN aclocaldir fi
13013 @c LocalWords: mymacro myothermacro AMFLAGS autopoint autogen libtoolize yum
13014 @c LocalWords: autoheader README MAKEFLAGS subdir Inetutils sync COND endif
13015 @c LocalWords: Miller's installable includedir inc pkgdata EXEEXT libexec bsd
13016 @c LocalWords: pkglib libexecdir prog libcpio cpio's dlopen dlpreopen linux
13017 @c LocalWords: subsubsection OBJEXT esac lib LTLIBRARIES liblob LIBADD AR ar
13018 @c LocalWords: ARFLAGS cru ing maude libgettext lo LTLIBOBJS rpath SGI PRE yy
13019 @c LocalWords: libmaude CCLD CXXFLAGS FFLAGS LFLAGS OBJCFLAGS RFLAGS DEFS cc
13020 @c LocalWords: OBJCXXFLAGS
13021 @c LocalWords: SHORTNAME vtable srcdir nostdinc basename yxx cxx ll lxx gdb
13022 @c LocalWords: lexers yymaxdepth maxdepth yyparse yylex yyerror yylval lval
13023 @c LocalWords: yychar yydebug yypact yyr yydef def yychk chk yypgo pgo yyact
13024 @c LocalWords: yyexca exca yyerrflag errflag yynerrs nerrs yyps yypv pv yys
13025 @c LocalWords: yystate yytmp tmp yyv yyval val yylloc lloc yyreds yytoks toks
13026 @c LocalWords: yylhs yylen yydefred yydgoto yysindex yyrindex yygindex yyname
13027 @c LocalWords: yytable yycheck yyrule byacc CXXCOMPILE CXXLINK FLINK cfortran
13028 @c LocalWords: Catalogue preprocessable FLIBS libfoo baz JAVACFLAGS java exe
13029 @c LocalWords: SunOS fying basenames exeext uninstalled oldinclude kr FSF's
13030 @c LocalWords: pkginclude oldincludedir sysconf sharedstate localstate gcc rm
13031 @c LocalWords: sysconfdir sharedstatedir localstatedir preexist CLEANFILES gz
13032 @c LocalWords: depfile tmpdepfile depmode const interoperate
13033 @c LocalWords: JAVAC javac JAVAROOT builddir CLASSPATH ENV pyc pyo pkgpython
13034 @c LocalWords: pyexecdir pkgpyexecdir Python's pythondir pkgpythondir txi ois
13035 @c LocalWords: installinfo vers MAKEINFO makeinfo MAKEINFOFLAGS noinstall rf
13036 @c LocalWords: mandir thesame alsothesame installman myexecbin DESTDIR Pinard
13037 @c LocalWords: uninstall installdirs uninstalls MOSTLYCLEANFILES mostlyclean
13038 @c LocalWords: DISTCLEANFILES MAINTAINERCLEANFILES GZIP gzip shar exp
13039 @c LocalWords: distdir distcheck distcleancheck listfiles distuninstallcheck
13040 @c LocalWords: VPATH tarfile stdout XFAIL DejaGnu dejagnu DEJATOOL runtest ln
13041 @c LocalWords: RUNTESTDEFAULTFLAGS toolchain RUNTESTFLAGS asis readme DVIPS
13042 @c LocalWords: installcheck gzipped tarZ std utils etags mkid cd
13043 @c LocalWords: ARGS taggable ETAGSFLAGS lang ctags CTAGSFLAGS GTAGS gtags idl
13044 @c LocalWords: foocc doit idlC multilibs ABIs cmindex defmac ARG enableval FC
13045 @c LocalWords: MSG xtrue DBG pathchk CYGWIN afile proglink versioned CVS's TE
13046 @c LocalWords: wildcards Autoconfiscated subsubheading autotools Meyering API
13047 @c LocalWords: ois's wildcard Wportability cartouche vrindex printindex Duret
13048 @c LocalWords: DSOMEFLAG DVERSION automake Lutz insertcopying versioning FAQ
13049 @c LocalWords: LTLIBOBJ Libtool's libtool's libltdl dlopening itutions libbar
13050 @c LocalWords: WANTEDLIBS libhello sublibraries libtop libsub dlopened Ratfor
13051 @c LocalWords: mymodule timestamps timestamp underquoted MAKEINFOHTMLFLAGS te
13052 @c LocalWords: GNUmakefile Subpackages subpackage's subpackages aux
13053 @c LocalWords: detailmenu Timeline pwd reldir AUTOM autom PREREQ FOOBAR libc
13054 @c LocalWords: libhand subpackage moduleN libmain libmisc FCFLAGS FCCOMPILE
13055 @c LocalWords: FCLINK subst sed ELCFILES elc MAKEINFOHTML dvips esyscmd ustar
13056 @c LocalWords: tarballs Woverride vfi ELFILES djm AutoMake honkin FSF
13057 @c LocalWords: fileutils precanned MacKenzie's reimplement termutils Tromey's
13058 @c LocalWords: cois gnitsians LIBPROGRAMS progs LIBLIBRARIES Textutils Ulrich
13059 @c LocalWords: Matzigkeit Drepper's Gord Matzigkeit's jm Dalley Debian org
13060 @c LocalWords: Administrivia ILU CORBA Sourceware Molenda sourceware Elliston
13061 @c LocalWords: dep Oliva Akim Demaille Aiieeee Demaillator Akim's sourcequake
13062 @c LocalWords: grep backported screenshots libgcj KB unnumberedsubsubsec pre
13063 @c LocalWords: precomputing hacky makedepend inline clearmake LD PRELOAD Rel
13064 @c LocalWords: syscalls perlhist acl pm multitable headitem fdl appendixsec
13065 @c LocalWords: LTALLOCA MALLOC malloc memcmp strdup alloca libcompat xyz DFOO
13066 @c LocalWords: unprefixed buildable preprocessed DBAZ DDATADIR WARNINGCFLAGS
13067 @c LocalWords: LIBFOOCFLAGS LIBFOOLDFLAGS ftable testSubDir obj LIBTOOLFLAGS
13068 @c LocalWords: barexec Pinard's automatize initialize lzip xz cscope