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 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 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 program is used to byte-compile Emacs Lisp code.
2288 This is a replacement for the @command{install} program that works on
2289 platforms where @command{install} is unavailable or unusable.
2292 This script is used to generate a @file{version.texi} file. It examines
2293 a file and prints some date information about it.
2296 This wraps a number of programs that are typically only required by
2297 maintainers. If the program in question doesn't exist,
2298 @command{missing} prints an informative warning and attempts to fix
2299 things so that the build can continue.
2302 This script used to be a wrapper around @samp{mkdir -p}, which is not
2303 portable. Now we prefer to use @samp{install-sh -d} when @command{configure}
2304 finds that @samp{mkdir -p} does not work, this makes one less script to
2307 For backward compatibility @file{mkinstalldirs} is still used and
2308 distributed when @command{automake} finds it in a package. But it is no
2309 longer installed automatically, and it should be safe to remove it.
2312 This is used to byte-compile Python scripts.
2315 This implements the default test driver offered by the parallel
2319 Not a program, this file is required for @samp{make dvi}, @samp{make
2320 ps} and @samp{make pdf} to work when Texinfo sources are in the
2321 package. The latest version can be downloaded from
2322 @url{http://www.gnu.org/software/texinfo/}.
2325 This program wraps @command{lex} and @command{yacc} to rename their
2326 output files. It also ensures that, for instance, multiple
2327 @command{yacc} instances can be invoked in a single directory in
2334 @chapter Some example packages
2336 This section contains two small examples.
2338 The first example (@pxref{Complete}) assumes you have an existing
2339 project already using Autoconf, with handcrafted @file{Makefile}s, and
2340 that you want to convert it to using Automake. If you are discovering
2341 both tools, it is probably better that you look at the Hello World
2342 example presented earlier (@pxref{Hello World}).
2344 The second example (@pxref{true}) shows how two programs can be built
2345 from the same file, using different compilation parameters. It
2346 contains some technical digressions that are probably best skipped on
2350 * Complete:: A simple example, start to finish
2351 * true:: Building true and false
2356 @section A simple example, start to finish
2358 @cindex Complete example
2360 Let's suppose you just finished writing @code{zardoz}, a program to make
2361 your head float from vortex to vortex. You've been using Autoconf to
2362 provide a portability framework, but your @file{Makefile.in}s have been
2363 ad-hoc. You want to make them bulletproof, so you turn to Automake.
2365 @cindex @code{AM_INIT_AUTOMAKE}, example use
2367 The first step is to update your @file{configure.ac} to include the
2368 commands that @command{automake} needs. The way to do this is to add an
2369 @code{AM_INIT_AUTOMAKE} call just after @code{AC_INIT}:
2372 AC_INIT([zardoz], [1.0])
2377 Since your program doesn't have any complicating factors (e.g., it
2378 doesn't use @code{gettext}, it doesn't want to build a shared library),
2379 you're done with this part. That was easy!
2381 @cindex @command{aclocal} program, introduction
2382 @cindex @file{aclocal.m4}, preexisting
2383 @cindex @file{acinclude.m4}, defined
2385 Now you must regenerate @file{configure}. But to do that, you'll need
2386 to tell @command{autoconf} how to find the new macro you've used. The
2387 easiest way to do this is to use the @command{aclocal} program to
2388 generate your @file{aclocal.m4} for you. But wait@dots{} maybe you
2389 already have an @file{aclocal.m4}, because you had to write some hairy
2390 macros for your program. The @command{aclocal} program lets you put
2391 your own macros into @file{acinclude.m4}, so simply rename and then
2395 mv aclocal.m4 acinclude.m4
2400 @cindex @command{zardoz} example
2402 Now it is time to write your @file{Makefile.am} for @code{zardoz}.
2403 Since @code{zardoz} is a user program, you want to install it where the
2404 rest of the user programs go: @code{bindir}. Additionally,
2405 @code{zardoz} has some Texinfo documentation. Your @file{configure.ac}
2406 script uses @code{AC_REPLACE_FUNCS}, so you need to link against
2407 @samp{$(LIBOBJS)}. So here's what you'd write:
2410 bin_PROGRAMS = zardoz
2411 zardoz_SOURCES = main.c head.c float.c vortex9.c gun.c
2412 zardoz_LDADD = $(LIBOBJS)
2414 info_TEXINFOS = zardoz.texi
2417 Now you can run @samp{automake --add-missing} to generate your
2418 @file{Makefile.in} and grab any auxiliary files you might need, and
2423 @section Building true and false
2425 @cindex Example, @command{false} and @command{true}
2426 @cindex @command{false} Example
2427 @cindex @command{true} Example
2429 Here is another, trickier example. It shows how to generate two
2430 programs (@code{true} and @code{false}) from the same source file
2431 (@file{true.c}). The difficult part is that each compilation of
2432 @file{true.c} requires different @code{cpp} flags.
2435 bin_PROGRAMS = true false
2437 false_LDADD = false.o
2440 $(COMPILE) -DEXIT_CODE=0 -c true.c
2443 $(COMPILE) -DEXIT_CODE=1 -o false.o -c true.c
2446 Note that there is no @code{true_SOURCES} definition. Automake will
2447 implicitly assume that there is a source file named @file{true.c}
2448 (@pxref{Default _SOURCES}), and
2449 define rules to compile @file{true.o} and link @file{true}. The
2450 @samp{true.o: true.c} rule supplied by the above @file{Makefile.am},
2451 will override the Automake generated rule to build @file{true.o}.
2453 @code{false_SOURCES} is defined to be empty---that way no implicit value
2454 is substituted. Because we have not listed the source of
2455 @file{false}, we have to tell Automake how to link the program. This is
2456 the purpose of the @code{false_LDADD} line. A @code{false_DEPENDENCIES}
2457 variable, holding the dependencies of the @file{false} target will be
2458 automatically generated by Automake from the content of
2461 The above rules won't work if your compiler doesn't accept both
2462 @option{-c} and @option{-o}. The simplest fix for this is to introduce a
2463 bogus dependency (to avoid problems with a parallel @command{make}):
2466 true.o: true.c false.o
2467 $(COMPILE) -DEXIT_CODE=0 -c true.c
2470 $(COMPILE) -DEXIT_CODE=1 -c true.c && mv true.o false.o
2473 As it turns out, there is also a much easier way to do this same task.
2474 Some of the above technique is useful enough that we've kept the
2475 example in the manual. However if you were to build @code{true} and
2476 @code{false} in real life, you would probably use per-program
2477 compilation flags, like so:
2479 @c Keep in sync with specflg7.sh and specflg8.sh
2481 bin_PROGRAMS = false true
2483 false_SOURCES = true.c
2484 false_CPPFLAGS = -DEXIT_CODE=1
2486 true_SOURCES = true.c
2487 true_CPPFLAGS = -DEXIT_CODE=0
2490 In this case Automake will cause @file{true.c} to be compiled twice,
2491 with different flags. In this instance, the names of the object files
2492 would be chosen by automake; they would be @file{false-true.o} and
2493 @file{true-true.o}. (The name of the object files rarely matters.)
2495 @node automake Invocation
2496 @chapter Creating a @file{Makefile.in}
2497 @c This node used to be named "Invoking automake". This @anchor
2498 @c allows old links to still work.
2499 @anchor{Invoking automake}
2501 @cindex Multiple @file{configure.ac} files
2502 @cindex Invoking @command{automake}
2503 @cindex @command{automake}, invoking
2504 @cindex Invocation of @command{automake}
2505 @cindex @command{automake}, invocation
2507 To create all the @file{Makefile.in}s for a package, run the
2508 @command{automake} program in the top level directory, with no
2509 arguments. @command{automake} will automatically find each
2510 appropriate @file{Makefile.am} (by scanning @file{configure.ac};
2511 @pxref{configure}) and generate the corresponding @file{Makefile.in}.
2512 Note that @command{automake} has a rather simplistic view of what
2513 constitutes a package; it assumes that a package has only one
2514 @file{configure.ac}, at the top. If your package has multiple
2515 @file{configure.ac}s, then you must run @command{automake} in each
2516 directory holding a @file{configure.ac}. (Alternatively, you may rely
2517 on Autoconf's @command{autoreconf}, which is able to recurse your
2518 package tree and run @command{automake} where appropriate.)
2520 You can optionally give @command{automake} an argument; @file{.am} is
2521 appended to the argument and the result is used as the name of the
2522 input file. This feature is generally only used to automatically
2523 rebuild an out-of-date @file{Makefile.in}. Note that
2524 @command{automake} must always be run from the topmost directory of a
2525 project, even if being used to regenerate the @file{Makefile.in} in
2526 some subdirectory. This is necessary because @command{automake} must
2527 scan @file{configure.ac}, and because @command{automake} uses the
2528 knowledge that a @file{Makefile.in} is in a subdirectory to change its
2529 behavior in some cases.
2532 Automake will run @command{autoconf} to scan @file{configure.ac} and
2533 its dependencies (i.e., @file{aclocal.m4} and any included file),
2534 therefore @command{autoconf} must be in your @env{PATH}. If there is
2535 an @env{AUTOCONF} variable in your environment it will be used
2536 instead of @command{autoconf}, this allows you to select a particular
2537 version of Autoconf. By the way, don't misunderstand this paragraph:
2538 @command{automake} runs @command{autoconf} to @strong{scan} your
2539 @file{configure.ac}, this won't build @file{configure} and you still
2540 have to run @command{autoconf} yourself for this purpose.
2542 @cindex @command{automake} options
2543 @cindex Options, @command{automake}
2544 @cindex Strictness, command line
2546 @command{automake} accepts the following options:
2548 @cindex Extra files distributed with Automake
2549 @cindex Files distributed with Automake
2550 @cindex @file{config.guess}
2554 @itemx --add-missing
2556 @opindex --add-missing
2557 Automake requires certain common files to exist in certain situations;
2558 for instance, @file{config.guess} is required if @file{configure.ac} invokes
2559 @code{AC_CANONICAL_HOST}. Automake is distributed with several of these
2560 files (@pxref{Auxiliary Programs}); this option will cause the missing
2561 ones to be automatically added to the package, whenever possible. In
2562 general if Automake tells you a file is missing, try using this option.
2563 By default Automake tries to make a symbolic link pointing to its own
2564 copy of the missing file; this can be changed with @option{--copy}.
2566 Many of the potentially-missing files are common scripts whose
2567 location may be specified via the @code{AC_CONFIG_AUX_DIR} macro.
2568 Therefore, @code{AC_CONFIG_AUX_DIR}'s setting affects whether a
2569 file is considered missing, and where the missing file is added
2572 In some strictness modes, additional files are installed, see @ref{Gnits}
2573 for more information.
2575 @item --libdir=@var{dir}
2577 Look for Automake data files in directory @var{dir} instead of in the
2578 installation directory. This is typically used for debugging.
2580 @item --print-libdir
2581 @opindex --print-libdir
2582 Print the path of the installation directory containing Automake-provided
2583 scripts and data files (like e.g., @file{texinfo.texi} and
2590 When used with @option{--add-missing}, causes installed files to be
2591 copied. The default is to make a symbolic link.
2595 @itemx --force-missing
2596 @opindex --force-missing
2597 When used with @option{--add-missing}, causes standard files to be reinstalled
2598 even if they already exist in the source tree. This involves removing
2599 the file from the source tree before creating the new symlink (or, with
2600 @option{--copy}, copying the new file).
2604 Set the global strictness to @option{foreign}. For more information, see
2609 Set the global strictness to @option{gnits}. For more information, see
2614 Set the global strictness to @option{gnu}. For more information, see
2615 @ref{Gnits}. This is the default strictness.
2619 Print a summary of the command line options and exit.
2622 @itemx --ignore-deps
2624 This disables the dependency tracking feature in generated
2625 @file{Makefile}s; see @ref{Dependencies}.
2627 @item --include-deps
2628 @opindex --include-deps
2629 This enables the dependency tracking feature. This feature is enabled
2630 by default. This option is provided for historical reasons only and
2631 probably should not be used.
2635 Ordinarily @command{automake} creates all @file{Makefile.in}s mentioned in
2636 @file{configure.ac}. This option causes it to only update those
2637 @file{Makefile.in}s that are out of date with respect to one of their
2641 @itemx --output-dir=@var{dir}
2643 @opindex --output-dir
2644 Put the generated @file{Makefile.in} in the directory @var{dir}.
2645 Ordinarily each @file{Makefile.in} is created in the directory of the
2646 corresponding @file{Makefile.am}. This option is deprecated and will be
2647 removed in a future release.
2653 Cause Automake to print information about which files are being read or
2658 Print the version number of Automake and exit.
2661 @itemx --warnings=@var{category}
2664 Output warnings falling in @var{category}. @var{category} can be
2668 warnings related to the GNU Coding Standards
2669 (@pxref{Top, , , standards, The GNU Coding Standards}).
2671 obsolete features or constructions
2673 user redefinitions of Automake rules or variables
2675 portability issues (e.g., use of @command{make} features that are
2676 known to be not portable)
2677 @item extra-portability
2678 extra portability issues related to obscure tools. One example of such
2679 a tool is the Microsoft @command{lib} archiver.
2681 weird syntax, unused variables, typos
2683 unsupported or incomplete features
2687 turn off all the warnings
2689 treat warnings as errors
2692 A category can be turned off by prefixing its name with @samp{no-}. For
2693 instance, @option{-Wno-syntax} will hide the warnings about unused
2696 The categories output by default are @samp{syntax} and
2697 @samp{unsupported}. Additionally, @samp{gnu} and @samp{portability}
2698 are enabled in @option{--gnu} and @option{--gnits} strictness.
2700 @c Checked by extra-portability.sh
2701 Turning off @samp{portability} will also turn off @samp{extra-portability},
2702 and similarly turning on @samp{extra-portability} will also turn on
2703 @samp{portability}. However, turning on @samp{portability} or turning
2704 off @samp{extra-portability} will not affect the other category.
2707 The environment variable @env{WARNINGS} can contain a comma separated
2708 list of categories to enable. It will be taken into account before the
2709 command-line switches, this way @option{-Wnone} will also ignore any
2710 warning category enabled by @env{WARNINGS}. This variable is also used
2711 by other tools like @command{autoconf}; unknown categories are ignored
2716 @vindex AUTOMAKE_JOBS
2717 If the environment variable @env{AUTOMAKE_JOBS} contains a positive
2718 number, it is taken as the maximum number of Perl threads to use in
2719 @command{automake} for generating multiple @file{Makefile.in} files
2720 concurrently. This is an experimental feature.
2724 @chapter Scanning @file{configure.ac}, using @command{aclocal}
2726 @cindex @file{configure.ac}, scanning
2727 @cindex Scanning @file{configure.ac}
2728 @cindex Using @command{aclocal}
2729 @cindex @command{aclocal}, using
2731 Automake scans the package's @file{configure.ac} to determine certain
2732 information about the package. Some @command{autoconf} macros are required
2733 and some variables must be defined in @file{configure.ac}. Automake
2734 will also use information from @file{configure.ac} to further tailor its
2737 Automake also supplies some Autoconf macros to make the maintenance
2738 easier. These macros can automatically be put into your
2739 @file{aclocal.m4} using the @command{aclocal} program.
2742 * Requirements:: Configuration requirements
2743 * Optional:: Other things Automake recognizes
2744 * aclocal Invocation:: Auto-generating aclocal.m4
2745 * Macros:: Autoconf macros supplied with Automake
2750 @section Configuration requirements
2752 @cindex Automake requirements
2753 @cindex Requirements of Automake
2755 @acindex AM_INIT_AUTOMAKE
2756 The one real requirement of Automake is that your @file{configure.ac}
2757 call @code{AM_INIT_AUTOMAKE}. This macro does several things that are
2758 required for proper Automake operation (@pxref{Macros}).
2760 Here are the other macros that Automake requires but which are not run
2761 by @code{AM_INIT_AUTOMAKE}:
2764 @item AC_CONFIG_FILES
2766 @acindex AC_CONFIG_FILES
2768 These two macros are usually invoked as follows near the end of
2769 @file{configure.ac}.
2783 Automake uses these to determine which files to create (@pxref{Output, ,
2784 Creating Output Files, autoconf, The Autoconf Manual}). A listed file
2785 is considered to be an Automake generated @file{Makefile} if there
2786 exists a file with the same name and the @file{.am} extension appended.
2787 Typically, @samp{AC_CONFIG_FILES([foo/Makefile])} will cause Automake to
2788 generate @file{foo/Makefile.in} if @file{foo/Makefile.am} exists.
2790 When using @code{AC_CONFIG_FILES} with multiple input files, as in
2793 AC_CONFIG_FILES([Makefile:top.in:Makefile.in:bot.in])
2797 @command{automake} will generate the first @file{.in} input file for
2798 which a @file{.am} file exists. If no such file exists the output
2799 file is not considered to be generated by Automake.
2801 Files created by @code{AC_CONFIG_FILES}, be they Automake
2802 @file{Makefile}s or not, are all removed by @samp{make distclean}.
2803 Their inputs are automatically distributed, unless they
2804 are the output of prior @code{AC_CONFIG_FILES} commands.
2805 Finally, rebuild rules are generated in the Automake @file{Makefile}
2806 existing in the subdirectory of the output file, if there is one, or
2807 in the top-level @file{Makefile} otherwise.
2809 The above machinery (cleaning, distributing, and rebuilding) works
2810 fine if the @code{AC_CONFIG_FILES} specifications contain only
2811 literals. If part of the specification uses shell variables,
2812 @command{automake} will not be able to fulfill this setup, and you will
2813 have to complete the missing bits by hand. For instance, on
2815 @c Keep in sync with output11.sh
2819 AC_CONFIG_FILES([output:$file],, [file=$file])
2823 @command{automake} will output rules to clean @file{output}, and
2824 rebuild it. However the rebuild rule will not depend on @file{input},
2825 and this file will not be distributed either. (You must add
2826 @samp{EXTRA_DIST = input} to your @file{Makefile.am} if @file{input} is a
2831 @c Keep in sync with output11.sh
2836 AC_CONFIG_FILES([$file:input],, [file=$file])
2837 AC_CONFIG_FILES([$file2],, [file2=$file2])
2841 will only cause @file{input} to be distributed. No file will be
2842 cleaned automatically (add @samp{DISTCLEANFILES = output out}
2843 yourself), and no rebuild rule will be output.
2845 Obviously @command{automake} cannot guess what value @samp{$file} is
2846 going to hold later when @file{configure} is run, and it cannot use
2847 the shell variable @samp{$file} in a @file{Makefile}. However, if you
2848 make reference to @samp{$file} as @samp{$@{file@}} (i.e., in a way
2849 that is compatible with @command{make}'s syntax) and furthermore use
2850 @code{AC_SUBST} to ensure that @samp{$@{file@}} is meaningful in a
2851 @file{Makefile}, then @command{automake} will be able to use
2852 @samp{$@{file@}} to generate all these rules. For instance, here is
2853 how the Automake package itself generates versioned scripts for its
2857 AC_SUBST([APIVERSION], @dots{})
2860 [tests/aclocal-$@{APIVERSION@}:tests/aclocal.in],
2861 [chmod +x tests/aclocal-$@{APIVERSION@}],
2862 [APIVERSION=$APIVERSION])
2864 [tests/automake-$@{APIVERSION@}:tests/automake.in],
2865 [chmod +x tests/automake-$@{APIVERSION@}])
2869 Here cleaning, distributing, and rebuilding are done automatically,
2870 because @samp{$@{APIVERSION@}} is known at @command{make}-time.
2872 Note that you should not use shell variables to declare
2873 @file{Makefile} files for which @command{automake} must create
2874 @file{Makefile.in}. Even @code{AC_SUBST} does not help here, because
2875 @command{automake} needs to know the file name when it runs in order
2876 to check whether @file{Makefile.am} exists. (In the very hairy case
2877 that your setup requires such use of variables, you will have to tell
2878 Automake which @file{Makefile.in}s to generate on the command-line.)
2880 It is possible to let @command{automake} emit conditional rules for
2881 @code{AC_CONFIG_FILES} with the help of @code{AM_COND_IF}
2887 Use literals for @file{Makefile}s, and for other files whenever possible.
2889 Use @samp{$file} (or @samp{$@{file@}} without @samp{AC_SUBST([file])})
2890 for files that @command{automake} should ignore.
2892 Use @samp{$@{file@}} and @samp{AC_SUBST([file])} for files
2893 that @command{automake} should not ignore.
2900 @section Other things Automake recognizes
2902 @cindex Macros Automake recognizes
2903 @cindex Recognized macros by Automake
2905 Every time Automake is run it calls Autoconf to trace
2906 @file{configure.ac}. This way it can recognize the use of certain
2907 macros and tailor the generated @file{Makefile.in} appropriately.
2908 Currently recognized macros and their effects are:
2911 @item AC_CANONICAL_BUILD
2912 @itemx AC_CANONICAL_HOST
2913 @itemx AC_CANONICAL_TARGET
2914 @vindex build_triplet
2915 @vindex host_triplet
2916 @vindex target_triplet
2917 Automake will ensure that @file{config.guess} and @file{config.sub}
2918 exist. Also, the @file{Makefile} variables @code{build_triplet},
2919 @code{host_triplet} and @code{target_triplet} are introduced. See
2920 @ref{Canonicalizing, , Getting the Canonical System Type, autoconf,
2921 The Autoconf Manual}.
2923 @item AC_CONFIG_AUX_DIR
2924 Automake will look for various helper scripts, such as
2925 @file{install-sh}, in the directory named in this macro invocation.
2926 @c This list is accurate relative to version 1.11
2927 (The full list of scripts is:
2929 @file{config.guess},
2938 @file{mkinstalldirs},
2943 Not all scripts are always searched for; some scripts
2944 will only be sought if the generated @file{Makefile.in} requires them.
2946 If @code{AC_CONFIG_AUX_DIR} is not given, the scripts are looked for in
2947 their standard locations. For @file{mdate-sh},
2948 @file{texinfo.tex}, and @file{ylwrap}, the standard location is the
2949 source directory corresponding to the current @file{Makefile.am}. For
2950 the rest, the standard location is the first one of @file{.}, @file{..},
2951 or @file{../..} (relative to the top source directory) that provides any
2952 one of the helper scripts. @xref{Input, , Finding `configure' Input,
2953 autoconf, The Autoconf Manual}.
2955 Required files from @code{AC_CONFIG_AUX_DIR} are automatically
2956 distributed, even if there is no @file{Makefile.am} in this directory.
2958 @item AC_CONFIG_LIBOBJ_DIR
2959 Automake will require the sources file declared with
2960 @code{AC_LIBSOURCE} (see below) in the directory specified by this
2963 @item AC_CONFIG_HEADERS
2964 Automake will generate rules to rebuild these headers. Older versions
2965 of Automake required the use of @code{AM_CONFIG_HEADER}; this is no
2966 longer the case, and that macro has indeed been removed.
2968 As with @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the
2969 specification using shell variables will be ignored as far as
2970 cleaning, distributing, and rebuilding is concerned.
2972 @item AC_CONFIG_LINKS
2973 Automake will generate rules to remove @file{configure} generated
2974 links on @samp{make distclean} and to distribute named source files as
2975 part of @samp{make dist}.
2977 As for @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the
2978 specification using shell variables will be ignored as far as cleaning
2979 and distributing is concerned. (There are no rebuild rules for links.)
2983 @itemx AC_LIBSOURCES
2985 Automake will automatically distribute any file listed in
2986 @code{AC_LIBSOURCE} or @code{AC_LIBSOURCES}.
2988 Note that the @code{AC_LIBOBJ} macro calls @code{AC_LIBSOURCE}. So if
2989 an Autoconf macro is documented to call @samp{AC_LIBOBJ([file])}, then
2990 @file{file.c} will be distributed automatically by Automake. This
2991 encompasses many macros like @code{AC_FUNC_ALLOCA},
2992 @code{AC_FUNC_MEMCMP}, @code{AC_REPLACE_FUNCS}, and others.
2994 By the way, direct assignments to @code{LIBOBJS} are no longer
2995 supported. You should always use @code{AC_LIBOBJ} for this purpose.
2996 @xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs.@: @code{LIBOBJS},
2997 autoconf, The Autoconf Manual}.
2999 @item AC_PROG_RANLIB
3000 This is required if any libraries are built in the package.
3001 @xref{Particular Programs, , Particular Program Checks, autoconf, The
3005 This is required if any C++ source is included. @xref{Particular
3006 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
3009 This is required if any Objective C source is included. @xref{Particular
3010 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
3012 @item AC_PROG_OBJCXX
3013 This is required if any Objective C++ source is included. @xref{Particular
3014 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
3017 This is required if any Fortran 77 source is included. @xref{Particular
3018 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
3020 @item AC_F77_LIBRARY_LDFLAGS
3021 This is required for programs and shared libraries that are a mixture of
3022 languages that include Fortran 77 (@pxref{Mixing Fortran 77 With C and
3023 C++}). @xref{Macros, , Autoconf macros supplied with Automake}.
3026 Automake will add the flags computed by @code{AC_FC_SRCEXT} to compilation
3027 of files with the respective source extension (@pxref{Fortran Compiler, ,
3028 Fortran Compiler Characteristics, autoconf, The Autoconf Manual}).
3031 This is required if any Fortran 90/95 source is included. This macro is
3032 distributed with Autoconf version 2.58 and later. @xref{Particular
3033 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
3035 @item AC_PROG_LIBTOOL
3036 Automake will turn on processing for @command{libtool} (@pxref{Top, ,
3037 Introduction, libtool, The Libtool Manual}).
3041 If a Yacc source file is seen, then you must either use this macro or
3042 define the variable @code{YACC} in @file{configure.ac}. The former is
3043 preferred (@pxref{Particular Programs, , Particular Program Checks,
3044 autoconf, The Autoconf Manual}).
3047 If a Lex source file is seen, then this macro must be used.
3048 @xref{Particular Programs, , Particular Program Checks, autoconf, The
3051 @item AC_REQUIRE_AUX_FILE
3052 For each @code{AC_REQUIRE_AUX_FILE([@var{file}])},
3053 @command{automake} will ensure that @file{@var{file}} exists in the
3054 aux directory, and will complain otherwise. It
3055 will also automatically distribute the file. This macro should be
3056 used by third-party Autoconf macros that require some supporting
3057 files in the aux directory specified with @code{AC_CONFIG_AUX_DIR}
3058 above. @xref{Input, , Finding @command{configure} Input, autoconf,
3059 The Autoconf Manual}.
3062 The first argument is automatically defined as a variable in each
3063 generated @file{Makefile.in}, unless @code{AM_SUBST_NOTMAKE} is also
3064 used for this variable. @xref{Setting Output Variables, , Setting
3065 Output Variables, autoconf, The Autoconf Manual}.
3067 For every substituted variable @var{var}, @command{automake} will add
3068 a line @code{@var{var} = @var{value}} to each @file{Makefile.in} file.
3069 Many Autoconf macros invoke @code{AC_SUBST} to set output variables
3070 this way, e.g., @code{AC_PATH_XTRA} defines @code{X_CFLAGS} and
3071 @code{X_LIBS}. Thus, you can access these variables as
3072 @code{$(X_CFLAGS)} and @code{$(X_LIBS)} in any @file{Makefile.am}
3073 if @code{AC_PATH_XTRA} is called.
3075 @item AM_CONDITIONAL
3076 This introduces an Automake conditional (@pxref{Conditionals}).
3079 This macro allows @code{automake} to detect subsequent access within
3080 @file{configure.ac} to a conditional previously introduced with
3081 @code{AM_CONDITIONAL}, thus enabling conditional @code{AC_CONFIG_FILES}
3082 (@pxref{Usage of Conditionals}).
3084 @item AM_GNU_GETTEXT
3085 This macro is required for packages that use GNU gettext
3086 (@pxref{gettext}). It is distributed with gettext. If Automake sees
3087 this macro it ensures that the package meets some of gettext's
3090 @item AM_GNU_GETTEXT_INTL_SUBDIR
3091 This macro specifies that the @file{intl/} subdirectory is to be built,
3092 even if the @code{AM_GNU_GETTEXT} macro was invoked with a first argument
3095 @item AM_MAINTAINER_MODE(@ovar{default-mode})
3096 @opindex --enable-maintainer-mode
3097 @opindex --disable-maintainer-mode
3098 This macro adds an @option{--enable-maintainer-mode} option to
3099 @command{configure}. If this is used, @command{automake} will cause
3100 ``maintainer-only'' rules to be turned off by default in the
3101 generated @file{Makefile.in}s, unless @var{default-mode} is
3102 @samp{enable}. This macro defines the @code{MAINTAINER_MODE}
3103 conditional, which you can use in your own @file{Makefile.am}.
3104 @xref{maintainer-mode}.
3106 @item AM_SUBST_NOTMAKE(@var{var})
3107 Prevent Automake from defining a variable @var{var}, even if it is
3108 substituted by @command{config.status}. Normally, Automake defines a
3109 @command{make} variable for each @command{configure} substitution,
3110 i.e., for each @code{AC_SUBST([@var{var}])}. This macro prevents that
3111 definition from Automake. If @code{AC_SUBST} has not been called
3112 for this variable, then @code{AM_SUBST_NOTMAKE} has no effects.
3113 Preventing variable definitions may be useful for substitution of
3114 multi-line values, where @code{@var{var} = @@@var{value}@@} might yield
3118 Files included by @file{configure.ac} using this macro will be
3119 detected by Automake and automatically distributed. They will also
3120 appear as dependencies in @file{Makefile} rules.
3122 @code{m4_include} is seldom used by @file{configure.ac} authors, but
3123 can appear in @file{aclocal.m4} when @command{aclocal} detects that
3124 some required macros come from files local to your package (as opposed to
3125 macros installed in a system-wide directory, @pxref{aclocal Invocation}).
3129 @node aclocal Invocation
3130 @section Auto-generating aclocal.m4
3131 @c This node used to be named "Invoking automake". This @anchor
3132 @c allows old links to still work.
3133 @anchor{Invoking aclocal}
3135 @cindex Invocation of @command{aclocal}
3136 @cindex @command{aclocal}, Invocation
3137 @cindex Invoking @command{aclocal}
3138 @cindex @command{aclocal}, Invoking
3140 Automake includes a number of Autoconf macros that can be used in
3141 your package (@pxref{Macros}); some of them are actually required by
3142 Automake in certain situations. These macros must be defined in your
3143 @file{aclocal.m4}; otherwise they will not be seen by
3146 The @command{aclocal} program will automatically generate
3147 @file{aclocal.m4} files based on the contents of @file{configure.ac}.
3148 This provides a convenient way to get Automake-provided macros,
3149 without having to search around. The @command{aclocal} mechanism
3150 allows other packages to supply their own macros (@pxref{Extending
3151 aclocal}). You can also use it to maintain your own set of custom
3152 macros (@pxref{Local Macros}).
3154 At startup, @command{aclocal} scans all the @file{.m4} files it can
3155 find, looking for macro definitions (@pxref{Macro Search Path}). Then
3156 it scans @file{configure.ac}. Any mention of one of the macros found
3157 in the first step causes that macro, and any macros it in turn
3158 requires, to be put into @file{aclocal.m4}.
3160 @emph{Putting} the file that contains the macro definition into
3161 @file{aclocal.m4} is usually done by copying the entire text of this
3162 file, including unused macro definitions as well as both @samp{#} and
3163 @samp{dnl} comments. If you want to make a comment that will be
3164 completely ignored by @command{aclocal}, use @samp{##} as the comment
3167 When a file selected by @command{aclocal} is located in a subdirectory
3168 specified as a relative search path with @command{aclocal}'s @option{-I}
3169 argument, @command{aclocal} assumes the file belongs to the package
3170 and uses @code{m4_include} instead of copying it into
3171 @file{aclocal.m4}. This makes the package smaller, eases dependency
3172 tracking, and cause the file to be distributed automatically.
3173 (@xref{Local Macros}, for an example.) Any macro that is found in a
3174 system-wide directory, or via an absolute search path will be copied.
3175 So use @samp{-I `pwd`/reldir} instead of @samp{-I reldir} whenever
3176 some relative directory should be considered outside the package.
3178 The contents of @file{acinclude.m4}, if this file exists, are also
3179 automatically included in @file{aclocal.m4}. We recommend against
3180 using @file{acinclude.m4} in new packages (@pxref{Local Macros}).
3184 While computing @file{aclocal.m4}, @command{aclocal} runs
3185 @command{autom4te} (@pxref{Using autom4te, , Using @command{Autom4te},
3186 autoconf, The Autoconf Manual}) in order to trace the macros that are
3187 really used, and omit from @file{aclocal.m4} all macros that are
3188 mentioned but otherwise unexpanded (this can happen when a macro is
3189 called conditionally). @command{autom4te} is expected to be in the
3190 @env{PATH}, just as @command{autoconf}. Its location can be
3191 overridden using the @env{AUTOM4TE} environment variable.
3194 * aclocal Options:: Options supported by aclocal
3195 * Macro Search Path:: How aclocal finds .m4 files
3196 * Extending aclocal:: Writing your own aclocal macros
3197 * Local Macros:: Organizing local macros
3198 * Serials:: Serial lines in Autoconf macros
3199 * Future of aclocal:: aclocal's scheduled death
3202 @node aclocal Options
3203 @subsection aclocal Options
3205 @cindex @command{aclocal}, Options
3206 @cindex Options, @command{aclocal}
3208 @command{aclocal} accepts the following options:
3211 @item --automake-acdir=@var{dir}
3212 @opindex --automake-acdir
3213 Look for the automake-provided macro files in @var{dir} instead of
3214 in the installation directory. This is typically used for debugging.
3216 @item --system-acdir=@var{dir}
3217 @opindex --system-acdir
3218 Look for the system-wide third-party macro files (and the special
3219 @file{dirlist} file) in @var{dir} instead of in the installation
3220 directory. This is typically used for debugging.
3222 @item --diff[=@var{command}]
3224 Run @var{command} on M4 file that would be installed or overwritten
3225 by @option{--install}. The default @var{command} is @samp{diff -u}.
3226 This option implies @option{--install} and @option{--dry-run}.
3230 Do not actually overwrite (or create) @file{aclocal.m4} and M4
3231 files installed by @option{--install}.
3235 Print a summary of the command line options and exit.
3239 Add the directory @var{dir} to the list of directories searched for
3244 Install system-wide third-party macros into the first directory
3245 specified with @samp{-I @var{dir}} instead of copying them in the
3247 @c Keep in sync with aclocal-install-absdir.sh
3248 Note that this will happen also if @var{dir} is an absolute path.
3250 @cindex serial number and @option{--install}
3251 When this option is used, and only when this option is used,
3252 @command{aclocal} will also honor @samp{#serial @var{number}} lines
3253 that appear in macros: an M4 file is ignored if there exists another
3254 M4 file with the same basename and a greater serial number in the
3255 search path (@pxref{Serials}).
3259 Always overwrite the output file. The default is to overwrite the output
3260 file only when really needed, i.e., when its contents changes or if one
3261 of its dependencies is younger.
3263 This option forces the update of @file{aclocal.m4} (or the file
3264 specified with @file{--output} below) and only this file, it has
3265 absolutely no influence on files that may need to be installed by
3268 @item --output=@var{file}
3270 Cause the output to be put into @var{file} instead of @file{aclocal.m4}.
3272 @item --print-ac-dir
3273 @opindex --print-ac-dir
3274 Prints the name of the directory that @command{aclocal} will search to
3275 find third-party @file{.m4} files. When this option is given, normal
3276 processing is suppressed. This option was used @emph{in the past} by
3277 third-party packages to determine where to install @file{.m4} macro
3278 files, but @emph{this usage is today discouraged}, since it causes
3279 @samp{$(prefix)} not to be thoroughly honoured (which violates the
3280 GNU Coding Standards), and a similar semantics can be better obtained
3281 with the @env{ACLOCAL_PATH} environment variable; @pxref{Extending aclocal}.
3285 Print the names of the files it examines.
3289 Print the version number of Automake and exit.
3292 @item --warnings=@var{category}
3295 Output warnings falling in @var{category}. @var{category} can be
3299 dubious syntactic constructs, underquoted macros, unused macros, etc.
3303 all the warnings, this is the default
3305 turn off all the warnings
3307 treat warnings as errors
3310 All warnings are output by default.
3313 The environment variable @env{WARNINGS} is honored in the same
3314 way as it is for @command{automake} (@pxref{automake Invocation}).
3318 @node Macro Search Path
3319 @subsection Macro Search Path
3321 @cindex Macro search path
3322 @cindex @command{aclocal} search path
3324 By default, @command{aclocal} searches for @file{.m4} files in the following
3325 directories, in this order:
3328 @item @var{acdir-APIVERSION}
3329 This is where the @file{.m4} macros distributed with Automake itself
3330 are stored. @var{APIVERSION} depends on the Automake release used;
3331 for example, for Automake 1.11.x, @var{APIVERSION} = @code{1.11}.
3334 This directory is intended for third party @file{.m4} files, and is
3335 configured when @command{automake} itself is built. This is
3336 @file{@@datadir@@/aclocal/}, which typically
3337 expands to @file{$@{prefix@}/share/aclocal/}. To find the compiled-in
3338 value of @var{acdir}, use the @option{--print-ac-dir} option
3339 (@pxref{aclocal Options}).
3342 As an example, suppose that @command{automake-1.11.2} was configured with
3343 @option{--prefix=@-/usr/local}. Then, the search path would be:
3346 @item @file{/usr/local/share/aclocal-1.11.2/}
3347 @item @file{/usr/local/share/aclocal/}
3350 The paths for the @var{acdir} and @var{acdir-APIVERSION} directories can
3351 be changed respectively through aclocal options @option{--system-acdir}
3352 and @option{--automake-acdir} (@pxref{aclocal Options}). Note however
3353 that these options are only intended for use by the internal Automake
3354 test suite, or for debugging under highly unusual situations; they are
3355 not ordinarily needed by end-users.
3357 As explained in (@pxref{aclocal Options}), there are several options that
3358 can be used to change or extend this search path.
3360 @subsubheading Modifying the Macro Search Path: @samp{-I @var{dir}}
3362 Any extra directories specified using @option{-I} options
3363 (@pxref{aclocal Options}) are @emph{prepended} to this search list. Thus,
3364 @samp{aclocal -I /foo -I /bar} results in the following search path:
3369 @item @var{acdir}-@var{APIVERSION}
3373 @subsubheading Modifying the Macro Search Path: @file{dirlist}
3374 @cindex @file{dirlist}
3376 There is a third mechanism for customizing the search path. If a
3377 @file{dirlist} file exists in @var{acdir}, then that file is assumed to
3378 contain a list of directory patterns, one per line. @command{aclocal}
3379 expands these patterns to directory names, and adds them to the search
3380 list @emph{after} all other directories. @file{dirlist} entries may
3381 use shell wildcards such as @samp{*}, @samp{?}, or @code{[...]}.
3383 For example, suppose
3384 @file{@var{acdir}/dirlist} contains the following:
3393 and that @command{aclocal} was called with the @samp{-I /foo -I /bar} options.
3394 Then, the search path would be
3396 @c @code looks better than @file here
3400 @item @var{acdir}-@var{APIVERSION}
3407 and all directories with path names starting with @code{/test3}.
3409 If the @option{--system-acdir=@var{dir}} option is used, then
3410 @command{aclocal} will search for the @file{dirlist} file in
3411 @var{dir}; but remember the warnings above against the use of
3412 @option{--system-acdir}.
3414 @file{dirlist} is useful in the following situation: suppose that
3415 @command{automake} version @code{1.11.2} is installed with
3416 @samp{--prefix=/usr} by the system vendor. Thus, the default search
3419 @c @code looks better than @file here
3421 @item @code{/usr/share/aclocal-1.11/}
3422 @item @code{/usr/share/aclocal/}
3425 However, suppose further that many packages have been manually
3426 installed on the system, with $prefix=/usr/local, as is typical. In
3427 that case, many of these ``extra'' @file{.m4} files are in
3428 @file{/usr/local/share/aclocal}. The only way to force
3429 @file{/usr/bin/aclocal} to find these ``extra'' @file{.m4} files is to
3430 always call @samp{aclocal -I /usr/local/share/aclocal}. This is
3431 inconvenient. With @file{dirlist}, one may create a file
3432 @file{/usr/share/aclocal/dirlist} containing only the single line
3435 /usr/local/share/aclocal
3438 Now, the ``default'' search path on the affected system is
3440 @c @code looks better than @file here
3442 @item @code{/usr/share/aclocal-1.11/}
3443 @item @code{/usr/share/aclocal/}
3444 @item @code{/usr/local/share/aclocal/}
3447 without the need for @option{-I} options; @option{-I} options can be reserved
3448 for project-specific needs (@file{my-source-dir/m4/}), rather than
3449 using it to work around local system-dependent tool installation
3452 Similarly, @file{dirlist} can be handy if you have installed a local
3453 copy of Automake in your account and want @command{aclocal} to look for
3454 macros installed at other places on the system.
3456 @anchor{ACLOCAL_PATH}
3457 @subsubheading Modifying the Macro Search Path: @file{ACLOCAL_PATH}
3458 @cindex @env{ACLOCAL_PATH}
3460 The fourth and last mechanism to customize the macro search path is
3461 also the simplest. Any directory included in the colon-separated
3462 environment variable @env{ACLOCAL_PATH} is added to the search path
3463 @c Keep in sync with aclocal-path-precedence.sh
3464 and takes precedence over system directories (including those found via
3465 @file{dirlist}), with the exception of the versioned directory
3466 @var{acdir-APIVERSION} (@pxref{Macro Search Path}). However, directories
3467 passed via @option{-I} will take precedence over directories in
3470 @c Keep in sync with aclocal-path-installed.sh
3471 Also note that, if the @option{--install} option is used, any @file{.m4}
3472 file containing a required macro that is found in a directory listed in
3473 @env{ACLOCAL_PATH} will be installed locally.
3474 @c Keep in sync with aclocal-path-installed-serial.sh
3475 In this case, serial numbers in @file{.m4} are honoured too,
3478 Conversely to @file{dirlist}, @env{ACLOCAL_PATH} is useful if you are
3479 using a global copy of Automake and want @command{aclocal} to look for
3480 macros somewhere under your home directory.
3482 @subsubheading Planned future incompatibilities
3484 The order in which the directories in the macro search path are currently
3485 looked up is confusing and/or suboptimal in various aspects, and is
3486 probably going to be changed in the future Automake release. In
3487 particular, directories in @env{ACLOCAL_PATH} and @file{@var{acdir}}
3488 might end up taking precedence over @file{@var{acdir-APIVERSION}}, and
3489 directories in @file{@var{acdir}/dirlist} might end up taking precedence
3490 over @file{@var{acdir}}. @emph{This is a possible future incompatibility!}
3492 @node Extending aclocal
3493 @subsection Writing your own aclocal macros
3495 @cindex @command{aclocal}, extending
3496 @cindex Extending @command{aclocal}
3498 The @command{aclocal} program doesn't have any built-in knowledge of any
3499 macros, so it is easy to extend it with your own macros.
3501 This can be used by libraries that want to supply their own Autoconf
3502 macros for use by other programs. For instance, the @command{gettext}
3503 library supplies a macro @code{AM_GNU_GETTEXT} that should be used by
3504 any package using @command{gettext}. When the library is installed, it
3505 installs this macro so that @command{aclocal} will find it.
3507 A macro file's name should end in @file{.m4}. Such files should be
3508 installed in @file{$(datadir)/aclocal}. This is as simple as writing:
3510 @c Keep in sync with primary-prefix-couples-documented-valid.sh
3512 aclocaldir = $(datadir)/aclocal
3513 aclocal_DATA = mymacro.m4 myothermacro.m4
3517 Please do use @file{$(datadir)/aclocal}, and not something based on
3518 the result of @samp{aclocal --print-ac-dir} (@pxref{Hard-Coded Install
3519 Paths}, for arguments). It might also be helpful to suggest to
3520 the user to add the @file{$(datadir)/aclocal} directory to his
3521 @env{ACLOCAL_PATH} variable (@pxref{ACLOCAL_PATH}) so that
3522 @command{aclocal} will find the @file{.m4} files installed by your
3523 package automatically.
3525 A file of macros should be a series of properly quoted
3526 @code{AC_DEFUN}'s (@pxref{Macro Definitions, , , autoconf, The
3527 Autoconf Manual}). The @command{aclocal} programs also understands
3528 @code{AC_REQUIRE} (@pxref{Prerequisite Macros, , , autoconf, The
3529 Autoconf Manual}), so it is safe to put each macro in a separate file.
3530 Each file should have no side effects but macro definitions.
3531 Especially, any call to @code{AC_PREREQ} should be done inside the
3532 defined macro, not at the beginning of the file.
3534 @cindex underquoted @code{AC_DEFUN}
3538 Starting with Automake 1.8, @command{aclocal} will warn about all
3539 underquoted calls to @code{AC_DEFUN}. We realize this will annoy a
3540 lot of people, because @command{aclocal} was not so strict in the past
3541 and many third party macros are underquoted; and we have to apologize
3542 for this temporary inconvenience. The reason we have to be stricter
3543 is that a future implementation of @command{aclocal} (@pxref{Future of
3544 aclocal}) will have to temporarily include all these third party
3545 @file{.m4} files, maybe several times, including even files that are
3546 not actually needed. Doing so should alleviate many problems of the
3547 current implementation, however it requires a stricter style from the
3548 macro authors. Hopefully it is easy to revise the existing macros.
3555 [AC_REQUIRE([AX_SOMETHING])dnl
3562 should be rewritten as
3565 AC_DEFUN([AX_FOOBAR],
3566 [AC_PREREQ([2.68])dnl
3567 AC_REQUIRE([AX_SOMETHING])dnl
3573 Wrapping the @code{AC_PREREQ} call inside the macro ensures that
3574 Autoconf 2.68 will not be required if @code{AX_FOOBAR} is not actually
3575 used. Most importantly, quoting the first argument of @code{AC_DEFUN}
3576 allows the macro to be redefined or included twice (otherwise this
3577 first argument would be expanded during the second definition). For
3578 consistency we like to quote even arguments such as @code{2.68} that
3581 If you have been directed here by the @command{aclocal} diagnostic but
3582 are not the maintainer of the implicated macro, you will want to
3583 contact the maintainer of that macro. Please make sure you have the
3584 latest version of the macro and that the problem hasn't already been
3585 reported before doing so: people tend to work faster when they aren't
3588 Another situation where @command{aclocal} is commonly used is to
3589 manage macros that are used locally by the package, @ref{Local
3593 @subsection Handling Local Macros
3595 Feature tests offered by Autoconf do not cover all needs. People
3596 often have to supplement existing tests with their own macros, or
3597 with third-party macros.
3599 There are two ways to organize custom macros in a package.
3601 The first possibility (the historical practice) is to list all your
3602 macros in @file{acinclude.m4}. This file will be included in
3603 @file{aclocal.m4} when you run @command{aclocal}, and its macro(s) will
3604 henceforth be visible to @command{autoconf}. However if it contains
3605 numerous macros, it will rapidly become difficult to maintain, and it
3606 will be almost impossible to share macros between packages.
3608 @vindex ACLOCAL_AMFLAGS
3609 The second possibility, which we do recommend, is to write each macro
3610 in its own file and gather all these files in a directory. This
3611 directory is usually called @file{m4/}. To build @file{aclocal.m4},
3612 one should therefore instruct @command{aclocal} to scan @file{m4/}.
3613 From the command line, this is done with @samp{aclocal -I m4}. The
3614 top-level @file{Makefile.am} should also be updated to define
3617 ACLOCAL_AMFLAGS = -I m4
3620 @code{ACLOCAL_AMFLAGS} contains options to pass to @command{aclocal}
3621 when @file{aclocal.m4} is to be rebuilt by @command{make}. This line is
3622 also used by @command{autoreconf} (@pxref{autoreconf Invocation, ,
3623 Using @command{autoreconf} to Update @file{configure} Scripts,
3624 autoconf, The Autoconf Manual}) to run @command{aclocal} with suitable
3625 options, or by @command{autopoint} (@pxref{autopoint Invocation, ,
3626 Invoking the @command{autopoint} Program, gettext, GNU gettext tools})
3627 and @command{gettextize} (@pxref{gettextize Invocation, , Invoking the
3628 @command{gettextize} Program, gettext, GNU gettext tools}) to locate
3629 the place where Gettext's macros should be installed. So even if you
3630 do not really care about the rebuild rules, you should define
3631 @code{ACLOCAL_AMFLAGS}.
3633 When @samp{aclocal -I m4} is run, it will build an @file{aclocal.m4}
3634 that @code{m4_include}s any file from @file{m4/} that defines a
3635 required macro. Macros not found locally will still be searched in
3636 system-wide directories, as explained in @ref{Macro Search Path}.
3638 Custom macros should be distributed for the same reason that
3639 @file{configure.ac} is: so that other people have all the sources of
3640 your package if they want to work on it. Actually, this distribution
3641 happens automatically because all @code{m4_include}d files are
3644 However there is no consensus on the distribution of third-party
3645 macros that your package may use. Many libraries install their own
3646 macro in the system-wide @command{aclocal} directory (@pxref{Extending
3647 aclocal}). For instance, Guile ships with a file called
3648 @file{guile.m4} that contains the macro @code{GUILE_FLAGS} that can
3649 be used to define setup compiler and linker flags appropriate for
3650 using Guile. Using @code{GUILE_FLAGS} in @file{configure.ac} will
3651 cause @command{aclocal} to copy @file{guile.m4} into
3652 @file{aclocal.m4}, but as @file{guile.m4} is not part of the project,
3653 it will not be distributed. Technically, that means a user who
3654 needs to rebuild @file{aclocal.m4} will have to install Guile first.
3655 This is probably OK, if Guile already is a requirement to build the
3656 package. However, if Guile is only an optional feature, or if your
3657 package might run on architectures where Guile cannot be installed,
3658 this requirement will hinder development. An easy solution is to copy
3659 such third-party macros in your local @file{m4/} directory so they get
3662 Since Automake 1.10, @command{aclocal} offers an option to copy these
3663 system-wide third-party macros in your local macro directory, solving
3664 the above problem. Simply use:
3667 ACLOCAL_AMFLAGS = -I m4 --install
3671 With this setup, system-wide macros will be copied to @file{m4/}
3672 the first time you run @command{autoreconf}. Then the locally
3673 installed macros will have precedence over the system-wide installed
3674 macros each time @command{aclocal} is run again.
3676 One reason why you should keep @option{--install} in the flags even
3677 after the first run is that when you later edit @file{configure.ac}
3678 and depend on a new macro, this macro will be installed in your
3679 @file{m4/} automatically. Another one is that serial numbers
3680 (@pxref{Serials}) can be used to update the macros in your source tree
3681 automatically when new system-wide versions are installed. A serial
3682 number should be a single line of the form
3689 where @var{nnn} contains only digits and dots. It should appear in
3690 the M4 file before any macro definition. It is a good practice to
3691 maintain a serial number for each macro you distribute, even if you do
3692 not use the @option{--install} option of @command{aclocal}: this allows
3693 other people to use it.
3697 @subsection Serial Numbers
3698 @cindex serial numbers in macros
3699 @cindex macro serial numbers
3700 @cindex @code{#serial} syntax
3701 @cindex @command{aclocal} and serial numbers
3703 Because third-party macros defined in @file{*.m4} files are naturally
3704 shared between multiple projects, some people like to version them.
3705 This makes it easier to tell which of two M4 files is newer. Since at
3706 least 1996, the tradition is to use a @samp{#serial} line for this.
3708 A serial number should be a single line of the form
3711 # serial @var{version}
3715 where @var{version} is a version number containing only digits and
3716 dots. Usually people use a single integer, and they increment it each
3717 time they change the macro (hence the name of ``serial''). Such a
3718 line should appear in the M4 file before any macro definition.
3720 The @samp{#} must be the first character on the line,
3721 and it is OK to have extra words after the version, as in
3724 #serial @var{version} @var{garbage}
3727 Normally these serial numbers are completely ignored by
3728 @command{aclocal} and @command{autoconf}, like any genuine comment.
3729 However when using @command{aclocal}'s @option{--install} feature, these
3730 serial numbers will modify the way @command{aclocal} selects the
3731 macros to install in the package: if two files with the same basename
3732 exist in your search path, and if at least one of them uses a
3733 @samp{#serial} line, @command{aclocal} will ignore the file that has
3734 the older @samp{#serial} line (or the file that has none).
3736 Note that a serial number applies to a whole M4 file, not to any macro
3737 it contains. A file can contains multiple macros, but only one
3740 Here is a use case that illustrates the use of @option{--install} and
3741 its interaction with serial numbers. Let's assume we maintain a
3742 package called MyPackage, the @file{configure.ac} of which requires a
3743 third-party macro @code{AX_THIRD_PARTY} defined in
3744 @file{/usr/share/aclocal/thirdparty.m4} as follows:
3748 AC_DEFUN([AX_THIRD_PARTY], [...])
3751 MyPackage uses an @file{m4/} directory to store local macros as
3752 explained in @ref{Local Macros}, and has
3755 ACLOCAL_AMFLAGS = -I m4 --install
3759 in its top-level @file{Makefile.am}.
3761 Initially the @file{m4/} directory is empty. The first time we run
3762 @command{autoreconf}, it will fetch the options to pass to
3763 @command{aclocal} in @file{Makefile.am}, and run @samp{aclocal -I m4
3764 --install}. @command{aclocal} will notice that
3768 @file{configure.ac} uses @code{AX_THIRD_PARTY}
3770 No local macros define @code{AX_THIRD_PARTY}
3772 @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3777 Because @file{/usr/share/aclocal/thirdparty.m4} is a system-wide macro
3778 and @command{aclocal} was given the @option{--install} option, it will
3779 copy this file in @file{m4/thirdparty.m4}, and output an
3780 @file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}.
3782 The next time @samp{aclocal -I m4 --install} is run (either via
3783 @command{autoreconf}, by hand, or from the @file{Makefile} rebuild
3784 rules) something different happens. @command{aclocal} notices that
3788 @file{configure.ac} uses @code{AX_THIRD_PARTY}
3790 @file{m4/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3793 @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3798 Because both files have the same serial number, @command{aclocal} uses
3799 the first it found in its search path order (@pxref{Macro Search
3800 Path}). @command{aclocal} therefore ignores
3801 @file{/usr/share/aclocal/thirdparty.m4} and outputs an
3802 @file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}.
3804 Local directories specified with @option{-I} are always searched before
3805 system-wide directories, so a local file will always be preferred to
3806 the system-wide file in case of equal serial numbers.
3808 Now suppose the system-wide third-party macro is changed. This can
3809 happen if the package installing this macro is updated. Let's suppose
3810 the new macro has serial number 2. The next time @samp{aclocal -I m4
3811 --install} is run the situation is the following:
3815 @file{configure.ac} uses @code{AX_THIRD_PARTY}
3817 @file{m4/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3820 @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3825 When @command{aclocal} sees a greater serial number, it immediately
3826 forgets anything it knows from files that have the same basename and a
3827 smaller serial number. So after it has found
3828 @file{/usr/share/aclocal/thirdparty.m4} with serial 2,
3829 @command{aclocal} will proceed as if it had never seen
3830 @file{m4/thirdparty.m4}. This brings us back to a situation similar
3831 to that at the beginning of our example, where no local file defined
3832 the macro. @command{aclocal} will install the new version of the
3833 macro in @file{m4/thirdparty.m4}, in this case overriding the old
3834 version. MyPackage just had its macro updated as a side effect of
3835 running @command{aclocal}.
3837 If you are leery of letting @command{aclocal} update your local macro,
3838 you can run @samp{aclocal -I m4 --diff} to review the changes
3839 @samp{aclocal -I m4 --install} would perform on these macros.
3841 Finally, note that the @option{--force} option of @command{aclocal} has
3842 absolutely no effect on the files installed by @option{--install}. For
3843 instance, if you have modified your local macros, do not expect
3844 @option{--install --force} to replace the local macros by their
3845 system-wide versions. If you want to do so, simply erase the local
3846 macros you want to revert, and run @samp{aclocal -I m4 --install}.
3849 @node Future of aclocal
3850 @subsection The Future of @command{aclocal}
3851 @cindex @command{aclocal}'s scheduled death
3853 @command{aclocal} is expected to disappear. This feature really
3854 should not be offered by Automake. Automake should focus on
3855 generating @file{Makefile}s; dealing with M4 macros really is
3856 Autoconf's job. The fact that some people install Automake just to use
3857 @command{aclocal}, but do not use @command{automake} otherwise is an
3858 indication of how that feature is misplaced.
3860 The new implementation will probably be done slightly differently.
3861 For instance, it could enforce the @file{m4/}-style layout discussed in
3864 We have no idea when and how this will happen. This has been
3865 discussed several times in the past, but someone still has to commit
3866 to that non-trivial task.
3868 From the user point of view, @command{aclocal}'s removal might turn
3869 out to be painful. There is a simple precaution that you may take to
3870 make that switch more seamless: never call @command{aclocal} yourself.
3871 Keep this guy under the exclusive control of @command{autoreconf} and
3872 Automake's rebuild rules. Hopefully you won't need to worry about
3873 things breaking, when @command{aclocal} disappears, because everything
3874 will have been taken care of. If otherwise you used to call
3875 @command{aclocal} directly yourself or from some script, you will
3876 quickly notice the change.
3878 Many packages come with a script called @file{bootstrap.sh} or
3879 @file{autogen.sh}, that will just call @command{aclocal},
3880 @command{libtoolize}, @command{gettextize} or @command{autopoint},
3881 @command{autoconf}, @command{autoheader}, and @command{automake} in
3882 the right order. Actually this is precisely what @command{autoreconf}
3883 can do for you. If your package has such a @file{bootstrap.sh} or
3884 @file{autogen.sh} script, consider using @command{autoreconf}. That
3885 should simplify its logic a lot (less things to maintain, yum!), it's
3886 even likely you will not need the script anymore, and more to the point
3887 you will not call @command{aclocal} directly anymore.
3889 For the time being, third-party packages should continue to install
3890 public macros into @file{/usr/share/aclocal/}. If @command{aclocal}
3891 is replaced by another tool it might make sense to rename the
3892 directory, but supporting @file{/usr/share/aclocal/} for backward
3893 compatibility should be really easy provided all macros are properly
3894 written (@pxref{Extending aclocal}).
3899 @section Autoconf macros supplied with Automake
3901 Automake ships with several Autoconf macros that you can use from your
3902 @file{configure.ac}. When you use one of them it will be included by
3903 @command{aclocal} in @file{aclocal.m4}.
3906 * Public Macros:: Macros that you can use.
3907 * Private Macros:: Macros that you should not use.
3910 @c consider generating the following subsections automatically from m4 files.
3913 @subsection Public Macros
3917 @item AM_INIT_AUTOMAKE([OPTIONS])
3918 @acindex AM_INIT_AUTOMAKE
3919 Runs many macros required for proper operation of the generated Makefiles.
3921 @vindex AUTOMAKE_OPTIONS
3922 Today, @code{AM_INIT_AUTOMAKE} is called with a single argument: a
3923 space-separated list of Automake options that should
3924 be applied to every @file{Makefile.am} in the tree. The effect is as if
3925 each option were listed in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
3928 This macro can also be called in @emph{another, deprecated form} (support
3929 for which will be @emph{removed in the next major Automake release}):
3930 @code{AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])}. In this form,
3931 there are two required arguments: the package and the version number.
3932 This form is obsolete because the @var{package} and @var{version} can
3933 be obtained from Autoconf's @code{AC_INIT} macro (which itself has an
3934 old and a new form).
3936 If your @file{configure.ac} has:
3939 AC_INIT([src/foo.c])
3940 AM_INIT_AUTOMAKE([mumble], [1.5])
3944 you should modernize it as follows:
3947 AC_INIT([mumble], [1.5])
3948 AC_CONFIG_SRCDIR([src/foo.c])
3952 Note that if you're upgrading your @file{configure.ac} from an earlier
3953 version of Automake, it is not always correct to simply move the
3954 package and version arguments from @code{AM_INIT_AUTOMAKE} directly to
3955 @code{AC_INIT}, as in the example above. The first argument to
3956 @code{AC_INIT} should be the name of your package (e.g., @samp{GNU
3957 Automake}), not the tarball name (e.g., @samp{automake}) that you used
3958 to pass to @code{AM_INIT_AUTOMAKE}. Autoconf tries to derive a
3959 tarball name from the package name, which should work for most but not
3960 all package names. (If it doesn't work for yours, you can use the
3961 four-argument form of @code{AC_INIT} to provide the tarball name
3964 @cindex @code{PACKAGE}, prevent definition
3965 @cindex @code{VERSION}, prevent definition
3967 By default this macro @code{AC_DEFINE}'s @code{PACKAGE} and
3968 @code{VERSION}. This can be avoided by passing the @option{no-define}
3971 AM_INIT_AUTOMAKE([gnits 1.5 no-define dist-bzip2])
3974 @item AM_PATH_LISPDIR
3975 @acindex AM_PATH_LISPDIR
3978 Searches for the program @command{emacs}, and, if found, sets the
3979 output variable @code{lispdir} to the full path to Emacs' site-lisp
3982 Note that this test assumes the @command{emacs} found to be a version
3983 that supports Emacs Lisp (such as GNU Emacs or XEmacs). Other
3984 emacsen can cause this test to hang (some, like old versions of
3985 MicroEmacs, start up in interactive mode, requiring @kbd{C-x C-c} to
3986 exit, which is hardly obvious for a non-emacs user). In most cases,
3987 however, you should be able to use @kbd{C-c} to kill the test. In
3988 order to avoid problems, you can set @env{EMACS} to ``no'' in the
3989 environment, or use the @option{--with-lispdir} option to
3990 @command{configure} to explicitly set the correct path (if you're sure
3991 you have an @command{emacs} that supports Emacs Lisp).
3993 @item AM_PROG_AR(@ovar{act-if-fail})
3996 You must use this macro when you use the archiver in your project, if
3997 you want support for unusual archivers such as Microsoft @command{lib}.
3998 The content of the optional argument is executed if the archiver
3999 interface is not recognized; the default action is to abort configure
4000 with an error message.
4006 Use this macro when you have assembly code in your project. This will
4007 choose the assembler for you (by default the C compiler) and set
4008 @code{CCAS}, and will also set @code{CCASFLAGS} if required.
4010 @item AM_PROG_CC_C_O
4011 @acindex AM_PROG_CC_C_O
4012 @acindex AC_PROG_CC_C_O
4013 This is like @code{AC_PROG_CC_C_O}, but it generates its results in
4014 the manner required by Automake. You must use this instead of
4015 @code{AC_PROG_CC_C_O} when you need this functionality, that is, when
4016 using per-target flags or subdir-objects with C sources.
4019 @acindex AM_PROG_LEX
4020 @acindex AC_PROG_LEX
4021 @cindex HP-UX 10, @command{lex} problems
4022 @cindex @command{lex} problems with HP-UX 10
4023 Like @code{AC_PROG_LEX} (@pxref{Particular Programs, , Particular
4024 Program Checks, autoconf, The Autoconf Manual}), but uses the
4025 @command{missing} script on systems that do not have @command{lex}.
4026 HP-UX 10 is one such system.
4029 @acindex AM_PROG_GCJ
4032 This macro finds the @command{gcj} program or causes an error. It sets
4033 @code{GCJ} and @code{GCJFLAGS}. @command{gcj} is the Java front-end to the
4034 GNU Compiler Collection.
4036 @item AM_PROG_UPC([@var{compiler-search-list}])
4037 @acindex AM_PROG_UPC
4039 Find a compiler for Unified Parallel C and define the @code{UPC}
4040 variable. The default @var{compiler-search-list} is @samp{upcc upc}.
4041 This macro will abort @command{configure} if no Unified Parallel C
4044 @item AM_SILENT_RULES
4045 @acindex AM_SILENT_RULES
4046 Control the machinery for less verbose build output
4047 (@pxref{Automake Silent Rules}).
4049 @item AM_WITH_DMALLOC
4050 @acindex AM_WITH_DMALLOC
4051 @cindex @command{dmalloc}, support for
4052 @vindex WITH_DMALLOC
4053 @opindex --with-dmalloc
4054 Add support for the @uref{http://dmalloc.com/, Dmalloc package}. If
4055 the user runs @command{configure} with @option{--with-dmalloc}, then
4056 define @code{WITH_DMALLOC} and add @option{-ldmalloc} to @code{LIBS}.
4061 @node Private Macros
4062 @subsection Private Macros
4064 The following macros are private macros you should not call directly.
4065 They are called by the other public macros when appropriate. Do not
4066 rely on them, as they might be changed in a future version. Consider
4067 them as implementation details; or better, do not consider them at all:
4071 @item _AM_DEPENDENCIES
4072 @itemx AM_SET_DEPDIR
4074 @itemx AM_OUTPUT_DEPENDENCY_COMMANDS
4075 These macros are used to implement Automake's automatic dependency
4076 tracking scheme. They are called automatically by Automake when
4077 required, and there should be no need to invoke them manually.
4079 @item AM_MAKE_INCLUDE
4080 This macro is used to discover how the user's @command{make} handles
4081 @code{include} statements. This macro is automatically invoked when
4082 needed; there should be no need to invoke it manually.
4084 @item AM_PROG_INSTALL_STRIP
4085 This is used to find a version of @code{install} that can be used to
4086 strip a program at installation time. This macro is automatically
4087 included when required.
4089 @item AM_SANITY_CHECK
4090 This checks to make sure that a file created in the build directory is
4091 newer than a file in the source directory. This can fail on systems
4092 where the clock is set incorrectly. This macro is automatically run
4093 from @code{AM_INIT_AUTOMAKE}.
4099 @chapter Directories
4101 For simple projects that distribute all files in the same directory
4102 it is enough to have a single @file{Makefile.am} that builds
4103 everything in place.
4105 In larger projects it is common to organize files in different
4106 directories, in a tree. For instance one directory per program, per
4107 library or per module. The traditional approach is to build these
4108 subdirectories recursively: each directory contains its @file{Makefile}
4109 (generated from @file{Makefile.am}), and when @command{make} is run
4110 from the top level directory it enters each subdirectory in turn to
4114 * Subdirectories:: Building subdirectories recursively
4115 * Conditional Subdirectories:: Conditionally not building directories
4116 * Alternative:: Subdirectories without recursion
4117 * Subpackages:: Nesting packages
4120 @node Subdirectories
4121 @section Recursing subdirectories
4123 @cindex @code{SUBDIRS}, explained
4125 In packages with subdirectories, the top level @file{Makefile.am} must
4126 tell Automake which subdirectories are to be built. This is done via
4127 the @code{SUBDIRS} variable.
4130 The @code{SUBDIRS} variable holds a list of subdirectories in which
4131 building of various sorts can occur. The rules for many targets
4132 (e.g., @code{all}) in the generated @file{Makefile} will run commands
4133 both locally and in all specified subdirectories. Note that the
4134 directories listed in @code{SUBDIRS} are not required to contain
4135 @file{Makefile.am}s; only @file{Makefile}s (after configuration).
4136 This allows inclusion of libraries from packages that do not use
4137 Automake (such as @code{gettext}; see also @ref{Third-Party
4140 In packages that use subdirectories, the top-level @file{Makefile.am} is
4141 often very short. For instance, here is the @file{Makefile.am} from the
4142 GNU Hello distribution:
4145 EXTRA_DIST = BUGS ChangeLog.O README-alpha
4146 SUBDIRS = doc intl po src tests
4149 When Automake invokes @command{make} in a subdirectory, it uses the value
4150 of the @code{MAKE} variable. It passes the value of the variable
4151 @code{AM_MAKEFLAGS} to the @command{make} invocation; this can be set in
4152 @file{Makefile.am} if there are flags you must always pass to
4155 @vindex AM_MAKEFLAGS
4157 The directories mentioned in @code{SUBDIRS} are usually direct
4158 children of the current directory, each subdirectory containing its
4159 own @file{Makefile.am} with a @code{SUBDIRS} pointing to deeper
4160 subdirectories. Automake can be used to construct packages of
4161 arbitrary depth this way.
4163 By default, Automake generates @file{Makefiles} that work depth-first
4164 in postfix order: the subdirectories are built before the current
4165 directory. However, it is possible to change this ordering. You can
4166 do this by putting @samp{.} into @code{SUBDIRS}. For instance,
4167 putting @samp{.} first will cause a prefix ordering of
4173 SUBDIRS = lib src . test
4177 will cause @file{lib/} to be built before @file{src/}, then the
4178 current directory will be built, finally the @file{test/} directory
4179 will be built. It is customary to arrange test directories to be
4180 built after everything else since they are meant to test what has
4183 All @code{clean} rules are run in reverse order of build rules.
4185 @node Conditional Subdirectories
4186 @section Conditional Subdirectories
4187 @cindex Subdirectories, building conditionally
4188 @cindex Conditional subdirectories
4189 @cindex @code{SUBDIRS}, conditional
4190 @cindex Conditional @code{SUBDIRS}
4192 It is possible to define the @code{SUBDIRS} variable conditionally if,
4193 like in the case of GNU Inetutils, you want to only build a subset of
4196 To illustrate how this works, let's assume we have two directories
4197 @file{src/} and @file{opt/}. @file{src/} should always be built, but we
4198 want to decide in @command{configure} whether @file{opt/} will be built
4199 or not. (For this example we will assume that @file{opt/} should be
4200 built when the variable @samp{$want_opt} was set to @samp{yes}.)
4202 Running @command{make} should thus recurse into @file{src/} always, and
4203 then maybe in @file{opt/}.
4205 However @samp{make dist} should always recurse into both @file{src/}
4206 and @file{opt/}. Because @file{opt/} should be distributed even if it
4207 is not needed in the current configuration. This means
4208 @file{opt/Makefile} should be created @emph{unconditionally}.
4210 There are two ways to setup a project like this. You can use Automake
4211 conditionals (@pxref{Conditionals}) or use Autoconf @code{AC_SUBST}
4212 variables (@pxref{Setting Output Variables, , Setting Output
4213 Variables, autoconf, The Autoconf Manual}). Using Automake
4214 conditionals is the preferred solution. Before we illustrate these
4215 two possibilities, let's introduce @code{DIST_SUBDIRS}.
4218 * SUBDIRS vs DIST_SUBDIRS:: Two sets of directories
4219 * Subdirectories with AM_CONDITIONAL:: Specifying conditional subdirectories
4220 * Subdirectories with AC_SUBST:: Another way for conditional recursion
4221 * Unconfigured Subdirectories:: Not even creating a @samp{Makefile}
4224 @node SUBDIRS vs DIST_SUBDIRS
4225 @subsection @code{SUBDIRS} vs.@: @code{DIST_SUBDIRS}
4226 @cindex @code{DIST_SUBDIRS}, explained
4228 Automake considers two sets of directories, defined by the variables
4229 @code{SUBDIRS} and @code{DIST_SUBDIRS}.
4231 @code{SUBDIRS} contains the subdirectories of the current directory
4232 that must be built (@pxref{Subdirectories}). It must be defined
4233 manually; Automake will never guess a directory is to be built. As we
4234 will see in the next two sections, it is possible to define it
4235 conditionally so that some directory will be omitted from the build.
4237 @code{DIST_SUBDIRS} is used in rules that need to recurse in all
4238 directories, even those that have been conditionally left out of the
4239 build. Recall our example where we may not want to build subdirectory
4240 @file{opt/}, but yet we want to distribute it? This is where
4241 @code{DIST_SUBDIRS} comes into play: @samp{opt} may not appear in
4242 @code{SUBDIRS}, but it must appear in @code{DIST_SUBDIRS}.
4244 Precisely, @code{DIST_SUBDIRS} is used by @samp{make
4245 maintainer-clean}, @samp{make distclean} and @samp{make dist}. All
4246 other recursive rules use @code{SUBDIRS}.
4248 If @code{SUBDIRS} is defined conditionally using Automake
4249 conditionals, Automake will define @code{DIST_SUBDIRS} automatically
4250 from the possible values of @code{SUBDIRS} in all conditions.
4252 If @code{SUBDIRS} contains @code{AC_SUBST} variables,
4253 @code{DIST_SUBDIRS} will not be defined correctly because Automake
4254 does not know the possible values of these variables. In this case
4255 @code{DIST_SUBDIRS} needs to be defined manually.
4257 @node Subdirectories with AM_CONDITIONAL
4258 @subsection Subdirectories with @code{AM_CONDITIONAL}
4259 @cindex @code{SUBDIRS} and @code{AM_CONDITIONAL}
4260 @cindex @code{AM_CONDITIONAL} and @code{SUBDIRS}
4262 @c Keep in sync with subcond2.sh
4264 @file{configure} should output the @file{Makefile} for each directory
4265 and define a condition into which @file{opt/} should be built.
4269 AM_CONDITIONAL([COND_OPT], [test "$want_opt" = yes])
4270 AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
4274 Then @code{SUBDIRS} can be defined in the top-level @file{Makefile.am}
4281 SUBDIRS = src $(MAYBE_OPT)
4284 As you can see, running @command{make} will rightly recurse into
4285 @file{src/} and maybe @file{opt/}.
4287 @vindex DIST_SUBDIRS
4288 As you can't see, running @samp{make dist} will recurse into both
4289 @file{src/} and @file{opt/} directories because @samp{make dist}, unlike
4290 @samp{make all}, doesn't use the @code{SUBDIRS} variable. It uses the
4291 @code{DIST_SUBDIRS} variable.
4293 In this case Automake will define @samp{DIST_SUBDIRS = src opt}
4294 automatically because it knows that @code{MAYBE_OPT} can contain
4295 @samp{opt} in some condition.
4297 @node Subdirectories with AC_SUBST
4298 @subsection Subdirectories with @code{AC_SUBST}
4299 @cindex @code{SUBDIRS} and @code{AC_SUBST}
4300 @cindex @code{AC_SUBST} and @code{SUBDIRS}
4302 @c Keep in sync with subcond3.sh
4304 Another possibility is to define @code{MAYBE_OPT} from
4305 @file{./configure} using @code{AC_SUBST}:
4309 if test "$want_opt" = yes; then
4314 AC_SUBST([MAYBE_OPT])
4315 AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
4319 In this case the top-level @file{Makefile.am} should look as follows.
4322 SUBDIRS = src $(MAYBE_OPT)
4323 DIST_SUBDIRS = src opt
4326 The drawback is that since Automake cannot guess what the possible
4327 values of @code{MAYBE_OPT} are, it is necessary to define
4328 @code{DIST_SUBDIRS}.
4330 @node Unconfigured Subdirectories
4331 @subsection Unconfigured Subdirectories
4332 @cindex Subdirectories, configured conditionally
4334 The semantics of @code{DIST_SUBDIRS} are often misunderstood by some
4335 users that try to @emph{configure and build} subdirectories
4336 conditionally. Here by configuring we mean creating the
4337 @file{Makefile} (it might also involve running a nested
4338 @command{configure} script: this is a costly operation that explains
4339 why people want to do it conditionally, but only the @file{Makefile}
4340 is relevant to the discussion).
4342 The above examples all assume that every @file{Makefile} is created,
4343 even in directories that are not going to be built. The simple reason
4344 is that we want @samp{make dist} to distribute even the directories
4345 that are not being built (e.g., platform-dependent code), hence
4346 @file{make dist} must recurse into the subdirectory, hence this
4347 directory must be configured and appear in @code{DIST_SUBDIRS}.
4349 Building packages that do not configure every subdirectory is a tricky
4350 business, and we do not recommend it to the novice as it is easy to
4351 produce an incomplete tarball by mistake. We will not discuss this
4352 topic in depth here, yet for the adventurous here are a few rules to
4357 @item @code{SUBDIRS} should always be a subset of @code{DIST_SUBDIRS}.
4359 It makes little sense to have a directory in @code{SUBDIRS} that
4360 is not in @code{DIST_SUBDIRS}. Think of the former as a way to tell
4361 which directories listed in the latter should be built.
4362 @item Any directory listed in @code{DIST_SUBDIRS} and @code{SUBDIRS}
4365 I.e., the @file{Makefile} must exists or the recursive @command{make}
4366 rules will not be able to process the directory.
4367 @item Any configured directory must be listed in @code{DIST_SUBDIRS}.
4369 So that the cleaning rules remove the generated @file{Makefile}s.
4370 It would be correct to see @code{DIST_SUBDIRS} as a variable that
4371 lists all the directories that have been configured.
4375 In order to prevent recursion in some unconfigured directory you
4376 must therefore ensure that this directory does not appear in
4377 @code{DIST_SUBDIRS} (and @code{SUBDIRS}). For instance, if you define
4378 @code{SUBDIRS} conditionally using @code{AC_SUBST} and do not define
4379 @code{DIST_SUBDIRS} explicitly, it will be default to
4380 @samp{$(SUBDIRS)}; another possibility is to force @code{DIST_SUBDIRS
4383 Of course, directories that are omitted from @code{DIST_SUBDIRS} will
4384 not be distributed unless you make other arrangements for this to
4385 happen (for instance, always running @samp{make dist} in a
4386 configuration where all directories are known to appear in
4387 @code{DIST_SUBDIRS}; or writing a @code{dist-hook} target to
4388 distribute these directories).
4390 @cindex Subdirectories, not distributed
4391 In few packages, unconfigured directories are not even expected to
4392 be distributed. Although these packages do not require the
4393 aforementioned extra arrangements, there is another pitfall. If the
4394 name of a directory appears in @code{SUBDIRS} or @code{DIST_SUBDIRS},
4395 @command{automake} will make sure the directory exists. Consequently
4396 @command{automake} cannot be run on such a distribution when one
4397 directory has been omitted. One way to avoid this check is to use the
4398 @code{AC_SUBST} method to declare conditional directories; since
4399 @command{automake} does not know the values of @code{AC_SUBST}
4400 variables it cannot ensure the corresponding directory exists.
4403 @section An Alternative Approach to Subdirectories
4405 If you've ever read Peter Miller's excellent paper,
4406 @uref{http://miller.emu.id.au/pmiller/books/rmch/,
4407 Recursive Make Considered Harmful}, the preceding sections on the use of
4408 subdirectories will probably come as unwelcome advice. For those who
4409 haven't read the paper, Miller's main thesis is that recursive
4410 @command{make} invocations are both slow and error-prone.
4412 Automake provides sufficient cross-directory support @footnote{We
4413 believe. This work is new and there are probably warts.
4414 @xref{Introduction}, for information on reporting bugs.} to enable you
4415 to write a single @file{Makefile.am} for a complex multi-directory
4419 By default an installable file specified in a subdirectory will have its
4420 directory name stripped before installation. For instance, in this
4421 example, the header file will be installed as
4422 @file{$(includedir)/stdio.h}:
4425 include_HEADERS = inc/stdio.h
4429 @cindex @code{nobase_} prefix
4430 @cindex Path stripping, avoiding
4431 @cindex Avoiding path stripping
4433 However, the @samp{nobase_} prefix can be used to circumvent this path
4434 stripping. In this example, the header file will be installed as
4435 @file{$(includedir)/sys/types.h}:
4438 nobase_include_HEADERS = sys/types.h
4441 @cindex @code{nobase_} and @code{dist_} or @code{nodist_}
4442 @cindex @code{dist_} and @code{nobase_}
4443 @cindex @code{nodist_} and @code{nobase_}
4447 @samp{nobase_} should be specified first when used in conjunction with
4448 either @samp{dist_} or @samp{nodist_} (@pxref{Fine-grained Distribution
4449 Control}). For instance:
4452 nobase_dist_pkgdata_DATA = images/vortex.pgm sounds/whirl.ogg
4455 Finally, note that a variable using the @samp{nobase_} prefix can
4456 often be replaced by several variables, one for each destination
4457 directory (@pxref{Uniform}). For instance, the last example could be
4458 rewritten as follows:
4460 @c Keep in sync with primary-prefix-couples-documented-valid.sh
4462 imagesdir = $(pkgdatadir)/images
4463 soundsdir = $(pkgdatadir)/sounds
4464 dist_images_DATA = images/vortex.pgm
4465 dist_sounds_DATA = sounds/whirl.ogg
4469 This latter syntax makes it possible to change one destination
4470 directory without changing the layout of the source tree.
4472 Currently, @samp{nobase_*_LTLIBRARIES} are the only exception to this
4473 rule, in that there is no particular installation order guarantee for
4474 an otherwise equivalent set of variables without @samp{nobase_} prefix.
4477 @section Nesting Packages
4478 @cindex Nesting packages
4480 @acindex AC_CONFIG_SUBDIRS
4481 @acindex AC_CONFIG_AUX_DIR
4484 In the GNU Build System, packages can be nested to arbitrary depth.
4485 This means that a package can embed other packages with their own
4486 @file{configure}, @file{Makefile}s, etc.
4488 These other packages should just appear as subdirectories of their
4489 parent package. They must be listed in @code{SUBDIRS} like other
4490 ordinary directories. However the subpackage's @file{Makefile}s
4491 should be output by its own @file{configure} script, not by the
4492 parent's @file{configure}. This is achieved using the
4493 @code{AC_CONFIG_SUBDIRS} Autoconf macro (@pxref{Subdirectories,
4494 AC_CONFIG_SUBDIRS, Configuring Other Packages in Subdirectories,
4495 autoconf, The Autoconf Manual}).
4497 Here is an example package for an @code{arm} program that links with
4498 a @code{hand} library that is a nested package in subdirectory
4501 @code{arm}'s @file{configure.ac}:
4504 AC_INIT([arm], [1.0])
4505 AC_CONFIG_AUX_DIR([.])
4508 AC_CONFIG_FILES([Makefile])
4509 # Call hand's ./configure script recursively.
4510 AC_CONFIG_SUBDIRS([hand])
4514 @code{arm}'s @file{Makefile.am}:
4517 # Build the library in the hand subdirectory first.
4520 # Include hand's header when compiling this directory.
4521 AM_CPPFLAGS = -I$(srcdir)/hand
4525 # link with the hand library.
4526 arm_LDADD = hand/libhand.a
4529 Now here is @code{hand}'s @file{hand/configure.ac}:
4532 AC_INIT([hand], [1.2])
4533 AC_CONFIG_AUX_DIR([.])
4538 AC_CONFIG_FILES([Makefile])
4543 and its @file{hand/Makefile.am}:
4546 lib_LIBRARIES = libhand.a
4547 libhand_a_SOURCES = hand.c
4550 When @samp{make dist} is run from the top-level directory it will
4551 create an archive @file{arm-1.0.tar.gz} that contains the @code{arm}
4552 code as well as the @file{hand} subdirectory. This package can be
4553 built and installed like any ordinary package, with the usual
4554 @samp{./configure && make && make install} sequence (the @code{hand}
4555 subpackage will be built and installed by the process).
4557 When @samp{make dist} is run from the hand directory, it will create a
4558 self-contained @file{hand-1.2.tar.gz} archive. So although it appears
4559 to be embedded in another package, it can still be used separately.
4561 The purpose of the @samp{AC_CONFIG_AUX_DIR([.])} instruction is to
4562 force Automake and Autoconf to search for auxiliary scripts in the
4563 current directory. For instance, this means that there will be two
4564 copies of @file{install-sh}: one in the top-level of the @code{arm}
4565 package, and another one in the @file{hand/} subdirectory for the
4566 @code{hand} package.
4568 The historical default is to search for these auxiliary scripts in
4569 the parent directory and the grandparent directory. So if the
4570 @samp{AC_CONFIG_AUX_DIR([.])} line was removed from
4571 @file{hand/configure.ac}, that subpackage would share the auxiliary
4572 script of the @code{arm} package. This may looks like a gain in size
4573 (a few kilobytes), but it is actually a loss of modularity as the
4574 @code{hand} subpackage is no longer self-contained (@samp{make dist}
4575 in the subdirectory will not work anymore).
4577 Packages that do not use Automake need more work to be integrated this
4578 way. @xref{Third-Party Makefiles}.
4581 @chapter Building Programs and Libraries
4583 A large part of Automake's functionality is dedicated to making it easy
4584 to build programs and libraries.
4587 * A Program:: Building a program
4588 * A Library:: Building a library
4589 * A Shared Library:: Building a Libtool library
4590 * Program and Library Variables:: Variables controlling program and
4592 * Default _SOURCES:: Default source files
4593 * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
4594 * Program Variables:: Variables used when building a program
4595 * Yacc and Lex:: Yacc and Lex support
4596 * C++ Support:: Compiling C++ sources
4597 * Objective C Support:: Compiling Objective C sources
4598 * Objective C++ Support:: Compiling Objective C++ sources
4599 * Unified Parallel C Support:: Compiling Unified Parallel C sources
4600 * Assembly Support:: Compiling assembly sources
4601 * Fortran 77 Support:: Compiling Fortran 77 sources
4602 * Fortran 9x Support:: Compiling Fortran 9x sources
4603 * Java Support with gcj:: Compiling Java sources using gcj
4604 * Vala Support:: Compiling Vala sources
4605 * Support for Other Languages:: Compiling other languages
4606 * Dependencies:: Automatic dependency tracking
4607 * EXEEXT:: Support for executable extensions
4612 @section Building a program
4614 In order to build a program, you need to tell Automake which sources
4615 are part of it, and which libraries it should be linked with.
4617 This section also covers conditional compilation of sources or
4618 programs. Most of the comments about these also apply to libraries
4619 (@pxref{A Library}) and libtool libraries (@pxref{A Shared Library}).
4622 * Program Sources:: Defining program sources
4623 * Linking:: Linking with libraries or extra objects
4624 * Conditional Sources:: Handling conditional sources
4625 * Conditional Programs:: Building a program conditionally
4628 @node Program Sources
4629 @subsection Defining program sources
4631 @cindex @code{PROGRAMS}, @code{bindir}
4633 @vindex bin_PROGRAMS
4634 @vindex sbin_PROGRAMS
4635 @vindex libexec_PROGRAMS
4636 @vindex pkglibexec_PROGRAMS
4637 @vindex noinst_PROGRAMS
4638 @vindex check_PROGRAMS
4640 In a directory containing source that gets built into a program (as
4641 opposed to a library or a script), the @code{PROGRAMS} primary is used.
4642 Programs can be installed in @code{bindir}, @code{sbindir},
4643 @code{libexecdir}, @code{pkglibexecdir}, or not at all
4644 (@code{noinst_}). They can also be built only for @samp{make check}, in
4645 which case the prefix is @samp{check_}.
4650 bin_PROGRAMS = hello
4653 In this simple case, the resulting @file{Makefile.in} will contain code
4654 to generate a program named @code{hello}.
4656 Associated with each program are several assisting variables that are
4657 named after the program. These variables are all optional, and have
4658 reasonable defaults. Each variable, its use, and default is spelled out
4659 below; we use the ``hello'' example throughout.
4661 The variable @code{hello_SOURCES} is used to specify which source files
4662 get built into an executable:
4665 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
4668 This causes each mentioned @file{.c} file to be compiled into the
4669 corresponding @file{.o}. Then all are linked to produce @file{hello}.
4671 @cindex @code{_SOURCES} primary, defined
4672 @cindex @code{SOURCES} primary, defined
4673 @cindex Primary variable, @code{SOURCES}
4676 If @code{hello_SOURCES} is not specified, then it defaults to the single
4677 file @file{hello.c} (@pxref{Default _SOURCES}).
4681 Multiple programs can be built in a single directory. Multiple programs
4682 can share a single source file, which must be listed in each
4683 @code{_SOURCES} definition.
4685 @cindex Header files in @code{_SOURCES}
4686 @cindex @code{_SOURCES} and header files
4688 Header files listed in a @code{_SOURCES} definition will be included in
4689 the distribution but otherwise ignored. In case it isn't obvious, you
4690 should not include the header file generated by @file{configure} in a
4691 @code{_SOURCES} variable; this file should not be distributed. Lex
4692 (@file{.l}) and Yacc (@file{.y}) files can also be listed; see @ref{Yacc
4697 @subsection Linking the program
4699 If you need to link against libraries that are not found by
4700 @command{configure}, you can use @code{LDADD} to do so. This variable is
4701 used to specify additional objects or libraries to link with; it is
4702 inappropriate for specifying specific linker flags, you should use
4703 @code{AM_LDFLAGS} for this purpose.
4707 @cindex @code{prog_LDADD}, defined
4709 Sometimes, multiple programs are built in one directory but do not share
4710 the same link-time requirements. In this case, you can use the
4711 @code{@var{prog}_LDADD} variable (where @var{prog} is the name of the
4712 program as it appears in some @code{_PROGRAMS} variable, and usually
4713 written in lowercase) to override @code{LDADD}. If this variable exists
4714 for a given program, then that program is not linked using @code{LDADD}.
4717 For instance, in GNU cpio, @code{pax}, @code{cpio} and @code{mt} are
4718 linked against the library @file{libcpio.a}. However, @code{rmt} is
4719 built in the same directory, and has no such link requirement. Also,
4720 @code{mt} and @code{rmt} are only built on certain architectures. Here
4721 is what cpio's @file{src/Makefile.am} looks like (abridged):
4724 bin_PROGRAMS = cpio pax $(MT)
4725 libexec_PROGRAMS = $(RMT)
4726 EXTRA_PROGRAMS = mt rmt
4728 LDADD = ../lib/libcpio.a $(INTLLIBS)
4731 cpio_SOURCES = @dots{}
4732 pax_SOURCES = @dots{}
4733 mt_SOURCES = @dots{}
4734 rmt_SOURCES = @dots{}
4737 @cindex @code{_LDFLAGS}, defined
4738 @vindex maude_LDFLAGS
4739 @code{@var{prog}_LDADD} is inappropriate for passing program-specific
4740 linker flags (except for @option{-l}, @option{-L}, @option{-dlopen} and
4741 @option{-dlpreopen}). So, use the @code{@var{prog}_LDFLAGS} variable for
4744 @cindex @code{_DEPENDENCIES}, defined
4745 @vindex maude_DEPENDENCIES
4746 @vindex EXTRA_maude_DEPENDENCIES
4747 It is also occasionally useful to have a program depend on some other
4748 target that is not actually part of that program. This can be done
4749 using either the @code{@var{prog}_DEPENDENCIES} or the
4750 @code{EXTRA_@var{prog}_DEPENDENCIES} variable. Each program depends on
4751 the contents both variables, but no further interpretation is done.
4753 Since these dependencies are associated to the link rule used to
4754 create the programs they should normally list files used by the link
4755 command. That is @file{*.$(OBJEXT)}, @file{*.a}, or @file{*.la}
4756 files. In rare cases you may need to add other kinds of files such as
4757 linker scripts, but @emph{listing a source file in
4758 @code{_DEPENDENCIES} is wrong}. If some source file needs to be built
4759 before all the components of a program are built, consider using the
4760 @code{BUILT_SOURCES} variable instead (@pxref{Sources}).
4762 If @code{@var{prog}_DEPENDENCIES} is not supplied, it is computed by
4763 Automake. The automatically-assigned value is the contents of
4764 @code{@var{prog}_LDADD}, with most configure substitutions, @option{-l},
4765 @option{-L}, @option{-dlopen} and @option{-dlpreopen} options removed. The
4766 configure substitutions that are left in are only @samp{$(LIBOBJS)} and
4767 @samp{$(ALLOCA)}; these are left because it is known that they will not
4768 cause an invalid value for @code{@var{prog}_DEPENDENCIES} to be
4771 @ref{Conditional Sources} shows a situation where @code{_DEPENDENCIES}
4774 The @code{EXTRA_@var{prog}_DEPENDENCIES} may be useful for cases where
4775 you merely want to augment the @command{automake}-generated
4776 @code{@var{prog}_DEPENDENCIES} rather than replacing it.
4778 @cindex @code{LDADD} and @option{-l}
4779 @cindex @option{-l} and @code{LDADD}
4780 We recommend that you avoid using @option{-l} options in @code{LDADD}
4781 or @code{@var{prog}_LDADD} when referring to libraries built by your
4782 package. Instead, write the file name of the library explicitly as in
4783 the above @code{cpio} example. Use @option{-l} only to list
4784 third-party libraries. If you follow this rule, the default value of
4785 @code{@var{prog}_DEPENDENCIES} will list all your local libraries and
4786 omit the other ones.
4789 @node Conditional Sources
4790 @subsection Conditional compilation of sources
4792 You can't put a configure substitution (e.g., @samp{@@FOO@@} or
4793 @samp{$(FOO)} where @code{FOO} is defined via @code{AC_SUBST}) into a
4794 @code{_SOURCES} variable. The reason for this is a bit hard to
4795 explain, but suffice to say that it simply won't work. Automake will
4796 give an error if you try to do this.
4798 Fortunately there are two other ways to achieve the same result. One is
4799 to use configure substitutions in @code{_LDADD} variables, the other is
4800 to use an Automake conditional.
4802 @subsubheading Conditional Compilation using @code{_LDADD} Substitutions
4804 @cindex @code{EXTRA_prog_SOURCES}, defined
4806 Automake must know all the source files that could possibly go into a
4807 program, even if not all the files are built in every circumstance. Any
4808 files that are only conditionally built should be listed in the
4809 appropriate @code{EXTRA_} variable. For instance, if
4810 @file{hello-linux.c} or @file{hello-generic.c} were conditionally included
4811 in @code{hello}, the @file{Makefile.am} would contain:
4814 bin_PROGRAMS = hello
4815 hello_SOURCES = hello-common.c
4816 EXTRA_hello_SOURCES = hello-linux.c hello-generic.c
4817 hello_LDADD = $(HELLO_SYSTEM)
4818 hello_DEPENDENCIES = $(HELLO_SYSTEM)
4822 You can then setup the @samp{$(HELLO_SYSTEM)} substitution from
4823 @file{configure.ac}:
4828 *linux*) HELLO_SYSTEM='hello-linux.$(OBJEXT)' ;;
4829 *) HELLO_SYSTEM='hello-generic.$(OBJEXT)' ;;
4831 AC_SUBST([HELLO_SYSTEM])
4835 In this case, the variable @code{HELLO_SYSTEM} should be replaced by
4836 either @file{hello-linux.o} or @file{hello-generic.o}, and added to
4837 both @code{hello_DEPENDENCIES} and @code{hello_LDADD} in order to be
4838 built and linked in.
4840 @subsubheading Conditional Compilation using Automake Conditionals
4842 An often simpler way to compile source files conditionally is to use
4843 Automake conditionals. For instance, you could use this
4844 @file{Makefile.am} construct to build the same @file{hello} example:
4847 bin_PROGRAMS = hello
4849 hello_SOURCES = hello-linux.c hello-common.c
4851 hello_SOURCES = hello-generic.c hello-common.c
4855 In this case, @file{configure.ac} should setup the @code{LINUX}
4856 conditional using @code{AM_CONDITIONAL} (@pxref{Conditionals}).
4858 When using conditionals like this you don't need to use the
4859 @code{EXTRA_} variable, because Automake will examine the contents of
4860 each variable to construct the complete list of source files.
4862 If your program uses a lot of files, you will probably prefer a
4863 conditional @samp{+=}.
4866 bin_PROGRAMS = hello
4867 hello_SOURCES = hello-common.c
4869 hello_SOURCES += hello-linux.c
4871 hello_SOURCES += hello-generic.c
4875 @node Conditional Programs
4876 @subsection Conditional compilation of programs
4877 @cindex Conditional programs
4878 @cindex Programs, conditional
4880 Sometimes it is useful to determine the programs that are to be built
4881 at configure time. For instance, GNU @code{cpio} only builds
4882 @code{mt} and @code{rmt} under special circumstances. The means to
4883 achieve conditional compilation of programs are the same you can use
4884 to compile source files conditionally: substitutions or conditionals.
4886 @subsubheading Conditional Programs using @command{configure} Substitutions
4888 @vindex EXTRA_PROGRAMS
4889 @cindex @code{EXTRA_PROGRAMS}, defined
4890 In this case, you must notify Automake of all the programs that can
4891 possibly be built, but at the same time cause the generated
4892 @file{Makefile.in} to use the programs specified by @command{configure}.
4893 This is done by having @command{configure} substitute values into each
4894 @code{_PROGRAMS} definition, while listing all optionally built programs
4895 in @code{EXTRA_PROGRAMS}.
4898 bin_PROGRAMS = cpio pax $(MT)
4899 libexec_PROGRAMS = $(RMT)
4900 EXTRA_PROGRAMS = mt rmt
4903 As explained in @ref{EXEEXT}, Automake will rewrite
4904 @code{bin_PROGRAMS}, @code{libexec_PROGRAMS}, and
4905 @code{EXTRA_PROGRAMS}, appending @samp{$(EXEEXT)} to each binary.
4906 Obviously it cannot rewrite values obtained at run-time through
4907 @command{configure} substitutions, therefore you should take care of
4908 appending @samp{$(EXEEXT)} yourself, as in @samp{AC_SUBST([MT],
4909 ['mt$@{EXEEXT@}'])}.
4911 @subsubheading Conditional Programs using Automake Conditionals
4913 You can also use Automake conditionals (@pxref{Conditionals}) to
4914 select programs to be built. In this case you don't have to worry
4915 about @samp{$(EXEEXT)} or @code{EXTRA_PROGRAMS}.
4917 @c Keep in sync with exeext.sh
4919 bin_PROGRAMS = cpio pax
4924 libexec_PROGRAMS = rmt
4930 @section Building a library
4932 @cindex @code{_LIBRARIES} primary, defined
4933 @cindex @code{LIBRARIES} primary, defined
4934 @cindex Primary variable, @code{LIBRARIES}
4937 @vindex lib_LIBRARIES
4938 @vindex pkglib_LIBRARIES
4939 @vindex noinst_LIBRARIES
4941 Building a library is much like building a program. In this case, the
4942 name of the primary is @code{LIBRARIES}. Libraries can be installed in
4943 @code{libdir} or @code{pkglibdir}.
4945 @xref{A Shared Library}, for information on how to build shared
4946 libraries using libtool and the @code{LTLIBRARIES} primary.
4948 Each @code{_LIBRARIES} variable is a list of the libraries to be built.
4949 For instance, to create a library named @file{libcpio.a}, but not install
4950 it, you would write:
4953 noinst_LIBRARIES = libcpio.a
4954 libcpio_a_SOURCES = @dots{}
4957 The sources that go into a library are determined exactly as they are
4958 for programs, via the @code{_SOURCES} variables. Note that the library
4959 name is canonicalized (@pxref{Canonicalization}), so the @code{_SOURCES}
4960 variable corresponding to @file{libcpio.a} is @samp{libcpio_a_SOURCES},
4961 not @samp{libcpio.a_SOURCES}.
4963 @vindex maude_LIBADD
4964 Extra objects can be added to a library using the
4965 @code{@var{library}_LIBADD} variable. This should be used for objects
4966 determined by @command{configure}. Again from @code{cpio}:
4968 @c Keep in sync with pr401c.sh
4970 libcpio_a_LIBADD = $(LIBOBJS) $(ALLOCA)
4973 In addition, sources for extra objects that will not exist until
4974 configure-time must be added to the @code{BUILT_SOURCES} variable
4977 Building a static library is done by compiling all object files, then
4978 by invoking @samp{$(AR) $(ARFLAGS)} followed by the name of the
4979 library and the list of objects, and finally by calling
4980 @samp{$(RANLIB)} on that library. You should call
4981 @code{AC_PROG_RANLIB} from your @file{configure.ac} to define
4982 @code{RANLIB} (Automake will complain otherwise). You should also
4983 call @code{AM_PROG_AR} to define @code{AR}, in order to support unusual
4984 archivers such as Microsoft lib. @code{ARFLAGS} will default to
4985 @code{cru}; you can override this variable by setting it in your
4986 @file{Makefile.am} or by @code{AC_SUBST}ing it from your
4987 @file{configure.ac}. You can override the @code{AR} variable by
4988 defining a per-library @code{maude_AR} variable (@pxref{Program and
4989 Library Variables}).
4991 @cindex Empty libraries
4992 Be careful when selecting library components conditionally. Because
4993 building an empty library is not portable, you should ensure that any
4994 library always contains at least one object.
4996 To use a static library when building a program, add it to
4997 @code{LDADD} for this program. In the following example, the program
4998 @file{cpio} is statically linked with the library @file{libcpio.a}.
5001 noinst_LIBRARIES = libcpio.a
5002 libcpio_a_SOURCES = @dots{}
5005 cpio_SOURCES = cpio.c @dots{}
5006 cpio_LDADD = libcpio.a
5010 @node A Shared Library
5011 @section Building a Shared Library
5013 @cindex Shared libraries, support for
5015 Building shared libraries portably is a relatively complex matter.
5016 For this reason, GNU Libtool (@pxref{Top, , Introduction, libtool, The
5017 Libtool Manual}) was created to help build shared libraries in a
5018 platform-independent way.
5021 * Libtool Concept:: Introducing Libtool
5022 * Libtool Libraries:: Declaring Libtool Libraries
5023 * Conditional Libtool Libraries:: Building Libtool Libraries Conditionally
5024 * Conditional Libtool Sources:: Choosing Library Sources Conditionally
5025 * Libtool Convenience Libraries:: Building Convenience Libtool Libraries
5026 * Libtool Modules:: Building Libtool Modules
5027 * Libtool Flags:: Using _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS
5028 * LTLIBOBJS:: Using $(LTLIBOBJS) and $(LTALLOCA)
5029 * Libtool Issues:: Common Issues Related to Libtool's Use
5032 @node Libtool Concept
5033 @subsection The Libtool Concept
5035 @cindex @command{libtool}, introduction
5036 @cindex libtool library, definition
5037 @cindex suffix @file{.la}, defined
5038 @cindex @file{.la} suffix, defined
5040 Libtool abstracts shared and static libraries into a unified concept
5041 henceforth called @dfn{libtool libraries}. Libtool libraries are
5042 files using the @file{.la} suffix, and can designate a static library,
5043 a shared library, or maybe both. Their exact nature cannot be
5044 determined until @file{./configure} is run: not all platforms support
5045 all kinds of libraries, and users can explicitly select which
5046 libraries should be built. (However the package's maintainers can
5047 tune the default, @pxref{AC_PROG_LIBTOOL, , The @code{AC_PROG_LIBTOOL}
5048 macro, libtool, The Libtool Manual}.)
5050 @cindex suffix @file{.lo}, defined
5051 Because object files for shared and static libraries must be compiled
5052 differently, libtool is also used during compilation. Object files
5053 built by libtool are called @dfn{libtool objects}: these are files
5054 using the @file{.lo} suffix. Libtool libraries are built from these
5057 You should not assume anything about the structure of @file{.la} or
5058 @file{.lo} files and how libtool constructs them: this is libtool's
5059 concern, and the last thing one wants is to learn about libtool's
5060 guts. However the existence of these files matters, because they are
5061 used as targets and dependencies in @file{Makefile}s rules when
5062 building libtool libraries. There are situations where you may have
5063 to refer to these, for instance when expressing dependencies for
5064 building source files conditionally (@pxref{Conditional Libtool
5067 @cindex @file{libltdl}, introduction
5069 People considering writing a plug-in system, with dynamically loaded
5070 modules, should look into @file{libltdl}: libtool's dlopening library
5071 (@pxref{Using libltdl, , Using libltdl, libtool, The Libtool Manual}).
5072 This offers a portable dlopening facility to load libtool libraries
5073 dynamically, and can also achieve static linking where unavoidable.
5075 Before we discuss how to use libtool with Automake in details, it
5076 should be noted that the libtool manual also has a section about how
5077 to use Automake with libtool (@pxref{Using Automake, , Using Automake
5078 with Libtool, libtool, The Libtool Manual}).
5080 @node Libtool Libraries
5081 @subsection Building Libtool Libraries
5083 @cindex @code{_LTLIBRARIES} primary, defined
5084 @cindex @code{LTLIBRARIES} primary, defined
5085 @cindex Primary variable, @code{LTLIBRARIES}
5086 @cindex Example of shared libraries
5087 @vindex lib_LTLIBRARIES
5088 @vindex pkglib_LTLIBRARIES
5089 @vindex _LTLIBRARIES
5091 Automake uses libtool to build libraries declared with the
5092 @code{LTLIBRARIES} primary. Each @code{_LTLIBRARIES} variable is a
5093 list of libtool libraries to build. For instance, to create a libtool
5094 library named @file{libgettext.la}, and install it in @code{libdir},
5098 lib_LTLIBRARIES = libgettext.la
5099 libgettext_la_SOURCES = gettext.c gettext.h @dots{}
5102 Automake predefines the variable @code{pkglibdir}, so you can use
5103 @code{pkglib_LTLIBRARIES} to install libraries in
5104 @samp{$(libdir)/@@PACKAGE@@/}.
5106 If @file{gettext.h} is a public header file that needs to be installed
5107 in order for people to use the library, it should be declared using a
5108 @code{_HEADERS} variable, not in @code{libgettext_la_SOURCES}.
5109 Headers listed in the latter should be internal headers that are not
5110 part of the public interface.
5113 lib_LTLIBRARIES = libgettext.la
5114 libgettext_la_SOURCES = gettext.c @dots{}
5115 include_HEADERS = gettext.h @dots{}
5118 A package can build and install such a library along with other
5119 programs that use it. This dependency should be specified using
5120 @code{LDADD}. The following example builds a program named
5121 @file{hello} that is linked with @file{libgettext.la}.
5124 lib_LTLIBRARIES = libgettext.la
5125 libgettext_la_SOURCES = gettext.c @dots{}
5127 bin_PROGRAMS = hello
5128 hello_SOURCES = hello.c @dots{}
5129 hello_LDADD = libgettext.la
5133 Whether @file{hello} is statically or dynamically linked with
5134 @file{libgettext.la} is not yet known: this will depend on the
5135 configuration of libtool and the capabilities of the host.
5138 @node Conditional Libtool Libraries
5139 @subsection Building Libtool Libraries Conditionally
5140 @cindex libtool libraries, conditional
5141 @cindex conditional libtool libraries
5143 Like conditional programs (@pxref{Conditional Programs}), there are
5144 two main ways to build conditional libraries: using Automake
5145 conditionals or using Autoconf @code{AC_SUBST}itutions.
5147 The important implementation detail you have to be aware of is that
5148 the place where a library will be installed matters to libtool: it
5149 needs to be indicated @emph{at link-time} using the @option{-rpath}
5152 For libraries whose destination directory is known when Automake runs,
5153 Automake will automatically supply the appropriate @option{-rpath}
5154 option to libtool. This is the case for libraries listed explicitly in
5155 some installable @code{_LTLIBRARIES} variables such as
5156 @code{lib_LTLIBRARIES}.
5158 However, for libraries determined at configure time (and thus
5159 mentioned in @code{EXTRA_LTLIBRARIES}), Automake does not know the
5160 final installation directory. For such libraries you must add the
5161 @option{-rpath} option to the appropriate @code{_LDFLAGS} variable by
5164 The examples below illustrate the differences between these two methods.
5166 Here is an example where @code{WANTEDLIBS} is an @code{AC_SUBST}ed
5167 variable set at @file{./configure}-time to either @file{libfoo.la},
5168 @file{libbar.la}, both, or none. Although @samp{$(WANTEDLIBS)}
5169 appears in the @code{lib_LTLIBRARIES}, Automake cannot guess it
5170 relates to @file{libfoo.la} or @file{libbar.la} at the time it creates
5171 the link rule for these two libraries. Therefore the @option{-rpath}
5172 argument must be explicitly supplied.
5174 @c Keep in sync with ltcond.sh
5176 EXTRA_LTLIBRARIES = libfoo.la libbar.la
5177 lib_LTLIBRARIES = $(WANTEDLIBS)
5178 libfoo_la_SOURCES = foo.c @dots{}
5179 libfoo_la_LDFLAGS = -rpath '$(libdir)'
5180 libbar_la_SOURCES = bar.c @dots{}
5181 libbar_la_LDFLAGS = -rpath '$(libdir)'
5184 Here is how the same @file{Makefile.am} would look using Automake
5185 conditionals named @code{WANT_LIBFOO} and @code{WANT_LIBBAR}. Now
5186 Automake is able to compute the @option{-rpath} setting itself, because
5187 it's clear that both libraries will end up in @samp{$(libdir)} if they
5190 @c Keep in sync with ltcond.sh
5194 lib_LTLIBRARIES += libfoo.la
5197 lib_LTLIBRARIES += libbar.la
5199 libfoo_la_SOURCES = foo.c @dots{}
5200 libbar_la_SOURCES = bar.c @dots{}
5203 @node Conditional Libtool Sources
5204 @subsection Libtool Libraries with Conditional Sources
5206 Conditional compilation of sources in a library can be achieved in the
5207 same way as conditional compilation of sources in a program
5208 (@pxref{Conditional Sources}). The only difference is that
5209 @code{_LIBADD} should be used instead of @code{_LDADD} and that it
5210 should mention libtool objects (@file{.lo} files).
5212 So, to mimic the @file{hello} example from @ref{Conditional Sources},
5213 we could build a @file{libhello.la} library using either
5214 @file{hello-linux.c} or @file{hello-generic.c} with the following
5217 @c Keep in sync with ltcond2.sh
5219 lib_LTLIBRARIES = libhello.la
5220 libhello_la_SOURCES = hello-common.c
5221 EXTRA_libhello_la_SOURCES = hello-linux.c hello-generic.c
5222 libhello_la_LIBADD = $(HELLO_SYSTEM)
5223 libhello_la_DEPENDENCIES = $(HELLO_SYSTEM)
5227 And make sure @command{configure} defines @code{HELLO_SYSTEM} as
5228 either @file{hello-linux.lo} or @file{hello-@-generic.lo}.
5230 Or we could simply use an Automake conditional as follows.
5232 @c Keep in sync with ltcond2.sh
5234 lib_LTLIBRARIES = libhello.la
5235 libhello_la_SOURCES = hello-common.c
5237 libhello_la_SOURCES += hello-linux.c
5239 libhello_la_SOURCES += hello-generic.c
5243 @node Libtool Convenience Libraries
5244 @subsection Libtool Convenience Libraries
5245 @cindex convenience libraries, libtool
5246 @cindex libtool convenience libraries
5247 @vindex noinst_LTLIBRARIES
5248 @vindex check_LTLIBRARIES
5250 Sometimes you want to build libtool libraries that should not be
5251 installed. These are called @dfn{libtool convenience libraries} and
5252 are typically used to encapsulate many sublibraries, later gathered
5253 into one big installed library.
5255 Libtool convenience libraries are declared by directory-less variables
5256 such as @code{noinst_LTLIBRARIES}, @code{check_LTLIBRARIES}, or even
5257 @code{EXTRA_LTLIBRARIES}. Unlike installed libtool libraries they do
5258 not need an @option{-rpath} flag at link time (actually this is the only
5261 Convenience libraries listed in @code{noinst_LTLIBRARIES} are always
5262 built. Those listed in @code{check_LTLIBRARIES} are built only upon
5263 @samp{make check}. Finally, libraries listed in
5264 @code{EXTRA_LTLIBRARIES} are never built explicitly: Automake outputs
5265 rules to build them, but if the library does not appear as a Makefile
5266 dependency anywhere it won't be built (this is why
5267 @code{EXTRA_LTLIBRARIES} is used for conditional compilation).
5269 Here is a sample setup merging libtool convenience libraries from
5270 subdirectories into one main @file{libtop.la} library.
5272 @c Keep in sync with ltconv.sh
5274 # -- Top-level Makefile.am --
5275 SUBDIRS = sub1 sub2 @dots{}
5276 lib_LTLIBRARIES = libtop.la
5278 libtop_la_LIBADD = \
5283 # -- sub1/Makefile.am --
5284 noinst_LTLIBRARIES = libsub1.la
5285 libsub1_la_SOURCES = @dots{}
5287 # -- sub2/Makefile.am --
5288 # showing nested convenience libraries
5289 SUBDIRS = sub2.1 sub2.2 @dots{}
5290 noinst_LTLIBRARIES = libsub2.la
5291 libsub2_la_SOURCES =
5292 libsub2_la_LIBADD = \
5298 When using such setup, beware that @command{automake} will assume
5299 @file{libtop.la} is to be linked with the C linker. This is because
5300 @code{libtop_la_SOURCES} is empty, so @command{automake} picks C as
5301 default language. If @code{libtop_la_SOURCES} was not empty,
5302 @command{automake} would select the linker as explained in @ref{How
5303 the Linker is Chosen}.
5305 If one of the sublibraries contains non-C source, it is important that
5306 the appropriate linker be chosen. One way to achieve this is to
5307 pretend that there is such a non-C file among the sources of the
5308 library, thus forcing @command{automake} to select the appropriate
5309 linker. Here is the top-level @file{Makefile} of our example updated
5310 to force C++ linking.
5313 SUBDIRS = sub1 sub2 @dots{}
5314 lib_LTLIBRARIES = libtop.la
5316 # Dummy C++ source to cause C++ linking.
5317 nodist_EXTRA_libtop_la_SOURCES = dummy.cxx
5318 libtop_la_LIBADD = \
5324 @samp{EXTRA_*_SOURCES} variables are used to keep track of source
5325 files that might be compiled (this is mostly useful when doing
5326 conditional compilation using @code{AC_SUBST}, @pxref{Conditional
5327 Libtool Sources}), and the @code{nodist_} prefix means the listed
5328 sources are not to be distributed (@pxref{Program and Library
5329 Variables}). In effect the file @file{dummy.cxx} does not need to
5330 exist in the source tree. Of course if you have some real source file
5331 to list in @code{libtop_la_SOURCES} there is no point in cheating with
5332 @code{nodist_EXTRA_libtop_la_SOURCES}.
5335 @node Libtool Modules
5336 @subsection Libtool Modules
5337 @cindex modules, libtool
5338 @cindex libtool modules
5339 @cindex @option{-module}, libtool
5341 These are libtool libraries meant to be dlopened. They are
5342 indicated to libtool by passing @option{-module} at link-time.
5345 pkglib_LTLIBRARIES = mymodule.la
5346 mymodule_la_SOURCES = doit.c
5347 mymodule_la_LDFLAGS = -module
5350 Ordinarily, Automake requires that a library's name start with
5351 @code{lib}. However, when building a dynamically loadable module you
5352 might wish to use a "nonstandard" name. Automake will not complain
5353 about such nonstandard names if it knows the library being built is a
5354 libtool module, i.e., if @option{-module} explicitly appears in the
5355 library's @code{_LDFLAGS} variable (or in the common @code{AM_LDFLAGS}
5356 variable when no per-library @code{_LDFLAGS} variable is defined).
5358 As always, @code{AC_SUBST} variables are black boxes to Automake since
5359 their values are not yet known when @command{automake} is run.
5360 Therefore if @option{-module} is set via such a variable, Automake
5361 cannot notice it and will proceed as if the library was an ordinary
5362 libtool library, with strict naming.
5364 If @code{mymodule_la_SOURCES} is not specified, then it defaults to
5365 the single file @file{mymodule.c} (@pxref{Default _SOURCES}).
5368 @subsection @code{_LIBADD}, @code{_LDFLAGS}, and @code{_LIBTOOLFLAGS}
5369 @cindex @code{_LIBADD}, libtool
5370 @cindex @code{_LDFLAGS}, libtool
5371 @cindex @code{_LIBTOOLFLAGS}, libtool
5372 @vindex AM_LIBTOOLFLAGS
5373 @vindex LIBTOOLFLAGS
5374 @vindex maude_LIBTOOLFLAGS
5376 As shown in previous sections, the @samp{@var{library}_LIBADD}
5377 variable should be used to list extra libtool objects (@file{.lo}
5378 files) or libtool libraries (@file{.la}) to add to @var{library}.
5380 The @samp{@var{library}_LDFLAGS} variable is the place to list
5381 additional libtool linking flags, such as @option{-version-info},
5382 @option{-static}, and a lot more. @xref{Link mode, , Link mode,
5383 libtool, The Libtool Manual}.
5385 The @command{libtool} command has two kinds of options: mode-specific
5386 options and generic options. Mode-specific options such as the
5387 aforementioned linking flags should be lumped with the other flags
5388 passed to the tool invoked by @command{libtool} (hence the use of
5389 @samp{@var{library}_LDFLAGS} for libtool linking flags). Generic
5390 options include @option{--tag=@var{tag}} and @option{--silent}
5391 (@pxref{Invoking libtool, , Invoking @command{libtool}, libtool, The
5392 Libtool Manual} for more options) should appear before the mode
5393 selection on the command line; in @file{Makefile.am}s they should
5394 be listed in the @samp{@var{library}_LIBTOOLFLAGS} variable.
5396 If @samp{@var{library}_LIBTOOLFLAGS} is not defined, then the variable
5397 @code{AM_LIBTOOLFLAGS} is used instead.
5399 These flags are passed to libtool after the @option{--tag=@var{tag}}
5400 option computed by Automake (if any), so
5401 @samp{@var{library}_LIBTOOLFLAGS} (or @code{AM_LIBTOOLFLAGS}) is a
5402 good place to override or supplement the @option{--tag=@var{tag}}
5405 The libtool rules also use a @code{LIBTOOLFLAGS} variable that should
5406 not be set in @file{Makefile.am}: this is a user variable (@pxref{Flag
5407 Variables Ordering}. It allows users to run @samp{make
5408 LIBTOOLFLAGS=--silent}, for instance. Note that the verbosity of
5409 @command{libtool} can also be influenced by the Automake support
5410 for silent rules (@pxref{Automake Silent Rules}).
5412 @node LTLIBOBJS, Libtool Issues, Libtool Flags, A Shared Library
5413 @subsection @code{LTLIBOBJS} and @code{LTALLOCA}
5414 @cindex @code{LTLIBOBJS}, special handling
5415 @cindex @code{LIBOBJS}, and Libtool
5416 @cindex @code{LTALLOCA}, special handling
5417 @cindex @code{ALLOCA}, and Libtool
5424 Where an ordinary library might include @samp{$(LIBOBJS)} or
5425 @samp{$(ALLOCA)} (@pxref{LIBOBJS}), a libtool library must use
5426 @samp{$(LTLIBOBJS)} or @samp{$(LTALLOCA)}. This is required because
5427 the object files that libtool operates on do not necessarily end in
5430 Nowadays, the computation of @code{LTLIBOBJS} from @code{LIBOBJS} is
5431 performed automatically by Autoconf (@pxref{AC_LIBOBJ vs LIBOBJS, ,
5432 @code{AC_LIBOBJ} vs.@: @code{LIBOBJS}, autoconf, The Autoconf Manual}).
5434 @node Libtool Issues
5435 @subsection Common Issues Related to Libtool's Use
5438 * Error required file ltmain.sh not found:: The need to run libtoolize
5439 * Objects created both with libtool and without:: Avoid a specific build race
5442 @node Error required file ltmain.sh not found
5443 @subsubsection Error: @samp{required file `./ltmain.sh' not found}
5444 @cindex @file{ltmain.sh} not found
5445 @cindex @command{libtoolize}, no longer run by @command{automake}
5446 @cindex @command{libtoolize} and @command{autoreconf}
5447 @cindex @command{autoreconf} and @command{libtoolize}
5448 @cindex @file{bootstrap.sh} and @command{autoreconf}
5449 @cindex @file{autogen.sh} and @command{autoreconf}
5451 Libtool comes with a tool called @command{libtoolize} that will
5452 install libtool's supporting files into a package. Running this
5453 command will install @file{ltmain.sh}. You should execute it before
5454 @command{aclocal} and @command{automake}.
5456 People upgrading old packages to newer autotools are likely to face
5457 this issue because older Automake versions used to call
5458 @command{libtoolize}. Therefore old build scripts do not call
5459 @command{libtoolize}.
5461 Since Automake 1.6, it has been decided that running
5462 @command{libtoolize} was none of Automake's business. Instead, that
5463 functionality has been moved into the @command{autoreconf} command
5464 (@pxref{autoreconf Invocation, , Using @command{autoreconf}, autoconf,
5465 The Autoconf Manual}). If you do not want to remember what to run and
5466 when, just learn the @command{autoreconf} command. Hopefully,
5467 replacing existing @file{bootstrap.sh} or @file{autogen.sh} scripts by
5468 a call to @command{autoreconf} should also free you from any similar
5469 incompatible change in the future.
5471 @node Objects created both with libtool and without
5472 @subsubsection Objects @samp{created with both libtool and without}
5474 Sometimes, the same source file is used both to build a libtool
5475 library and to build another non-libtool target (be it a program or
5478 Let's consider the following @file{Makefile.am}.
5482 prog_SOURCES = prog.c foo.c @dots{}
5484 lib_LTLIBRARIES = libfoo.la
5485 libfoo_la_SOURCES = foo.c @dots{}
5489 (In this trivial case the issue could be avoided by linking
5490 @file{libfoo.la} with @file{prog} instead of listing @file{foo.c} in
5491 @code{prog_SOURCES}. But let's assume we really want to keep
5492 @file{prog} and @file{libfoo.la} separate.)
5494 Technically, it means that we should build @file{foo.$(OBJEXT)} for
5495 @file{prog}, and @file{foo.lo} for @file{libfoo.la}. The problem is
5496 that in the course of creating @file{foo.lo}, libtool may erase (or
5497 replace) @file{foo.$(OBJEXT)}, and this cannot be avoided.
5499 Therefore, when Automake detects this situation it will complain
5500 with a message such as
5502 object `foo.$(OBJEXT)' created both with libtool and without
5505 A workaround for this issue is to ensure that these two objects get
5506 different basenames. As explained in @ref{Renamed Objects}, this
5507 happens automatically when per-targets flags are used.
5511 prog_SOURCES = prog.c foo.c @dots{}
5512 prog_CFLAGS = $(AM_CFLAGS)
5514 lib_LTLIBRARIES = libfoo.la
5515 libfoo_la_SOURCES = foo.c @dots{}
5519 Adding @samp{prog_CFLAGS = $(AM_CFLAGS)} is almost a no-op, because
5520 when the @code{prog_CFLAGS} is defined, it is used instead of
5521 @code{AM_CFLAGS}. However as a side effect it will cause
5522 @file{prog.c} and @file{foo.c} to be compiled as
5523 @file{prog-prog.$(OBJEXT)} and @file{prog-foo.$(OBJEXT)}, which solves
5526 @node Program and Library Variables
5527 @section Program and Library Variables
5529 Associated with each program is a collection of variables that can be
5530 used to modify how that program is built. There is a similar list of
5531 such variables for each library. The canonical name of the program (or
5532 library) is used as a base for naming these variables.
5534 In the list below, we use the name ``maude'' to refer to the program or
5535 library. In your @file{Makefile.am} you would replace this with the
5536 canonical name of your program. This list also refers to ``maude'' as a
5537 program, but in general the same rules apply for both static and dynamic
5538 libraries; the documentation below notes situations where programs and
5543 This variable, if it exists, lists all the source files that are
5544 compiled to build the program. These files are added to the
5545 distribution by default. When building the program, Automake will cause
5546 each source file to be compiled to a single @file{.o} file (or
5547 @file{.lo} when using libtool). Normally these object files are named
5548 after the source file, but other factors can change this. If a file in
5549 the @code{_SOURCES} variable has an unrecognized extension, Automake
5550 will do one of two things with it. If a suffix rule exists for turning
5551 files with the unrecognized extension into @file{.o} files, then
5552 @command{automake} will treat this file as it will any other source file
5553 (@pxref{Support for Other Languages}). Otherwise, the file will be
5554 ignored as though it were a header file.
5556 The prefixes @code{dist_} and @code{nodist_} can be used to control
5557 whether files listed in a @code{_SOURCES} variable are distributed.
5558 @code{dist_} is redundant, as sources are distributed by default, but it
5559 can be specified for clarity if desired.
5561 It is possible to have both @code{dist_} and @code{nodist_} variants of
5562 a given @code{_SOURCES} variable at once; this lets you easily
5563 distribute some files and not others, for instance:
5566 nodist_maude_SOURCES = nodist.c
5567 dist_maude_SOURCES = dist-me.c
5570 By default the output file (on Unix systems, the @file{.o} file) will
5571 be put into the current build directory. However, if the option
5572 @option{subdir-objects} is in effect in the current directory then the
5573 @file{.o} file will be put into the subdirectory named after the
5574 source file. For instance, with @option{subdir-objects} enabled,
5575 @file{sub/dir/file.c} will be compiled to @file{sub/dir/file.o}. Some
5576 people prefer this mode of operation. You can specify
5577 @option{subdir-objects} in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
5578 @cindex Subdirectory, objects in
5579 @cindex Objects in subdirectory
5582 @item EXTRA_maude_SOURCES
5583 Automake needs to know the list of files you intend to compile
5584 @emph{statically}. For one thing, this is the only way Automake has of
5585 knowing what sort of language support a given @file{Makefile.in}
5586 requires. @footnote{There are other, more obscure reasons for
5587 this limitation as well.} This means that, for example, you can't put a
5588 configure substitution like @samp{@@my_sources@@} into a @samp{_SOURCES}
5589 variable. If you intend to conditionally compile source files and use
5590 @file{configure} to substitute the appropriate object names into, e.g.,
5591 @code{_LDADD} (see below), then you should list the corresponding source
5592 files in the @code{EXTRA_} variable.
5594 This variable also supports @code{dist_} and @code{nodist_} prefixes.
5595 For instance, @code{nodist_EXTRA_maude_SOURCES} would list extra
5596 sources that may need to be built, but should not be distributed.
5599 A static library is created by default by invoking @samp{$(AR)
5600 $(ARFLAGS)} followed by the name of the library and then the objects
5601 being put into the library. You can override this by setting the
5602 @code{_AR} variable. This is usually used with C++; some C++
5603 compilers require a special invocation in order to instantiate all the
5604 templates that should go into a library. For instance, the SGI C++
5605 compiler likes this variable set like so:
5607 libmaude_a_AR = $(CXX) -ar -o
5611 Extra objects can be added to a @emph{library} using the @code{_LIBADD}
5612 variable. For instance, this should be used for objects determined by
5613 @command{configure} (@pxref{A Library}).
5615 In the case of libtool libraries, @code{maude_LIBADD} can also refer
5616 to other libtool libraries.
5619 Extra objects (@file{*.$(OBJEXT)}) and libraries (@file{*.a},
5620 @file{*.la}) can be added to a @emph{program} by listing them in the
5621 @code{_LDADD} variable. For instance, this should be used for objects
5622 determined by @command{configure} (@pxref{Linking}).
5624 @code{_LDADD} and @code{_LIBADD} are inappropriate for passing
5625 program-specific linker flags (except for @option{-l}, @option{-L},
5626 @option{-dlopen} and @option{-dlpreopen}). Use the @code{_LDFLAGS} variable
5629 For instance, if your @file{configure.ac} uses @code{AC_PATH_XTRA}, you
5630 could link your program against the X libraries like so:
5633 maude_LDADD = $(X_PRE_LIBS) $(X_LIBS) $(X_EXTRA_LIBS)
5636 We recommend that you use @option{-l} and @option{-L} only when
5637 referring to third-party libraries, and give the explicit file names
5638 of any library built by your package. Doing so will ensure that
5639 @code{maude_DEPENDENCIES} (see below) is correctly defined by default.
5642 This variable is used to pass extra flags to the link step of a program
5643 or a shared library. It overrides the @code{AM_LDFLAGS} variable.
5645 @item maude_LIBTOOLFLAGS
5646 This variable is used to pass extra options to @command{libtool}.
5647 It overrides the @code{AM_LIBTOOLFLAGS} variable.
5648 These options are output before @command{libtool}'s @option{--mode=@var{mode}}
5649 option, so they should not be mode-specific options (those belong to
5650 the compiler or linker flags). @xref{Libtool Flags}.
5652 @item maude_DEPENDENCIES
5653 @itemx EXTRA_maude_DEPENDENCIES
5654 It is also occasionally useful to have a target (program or library)
5655 depend on some other file that is not actually part of that target.
5656 This can be done using the @code{_DEPENDENCIES} variable. Each
5657 target depends on the contents of such a variable, but no further
5658 interpretation is done.
5660 Since these dependencies are associated to the link rule used to
5661 create the programs they should normally list files used by the link
5662 command. That is @file{*.$(OBJEXT)}, @file{*.a}, or @file{*.la} files
5663 for programs; @file{*.lo} and @file{*.la} files for Libtool libraries;
5664 and @file{*.$(OBJEXT)} files for static libraries. In rare cases you
5665 may need to add other kinds of files such as linker scripts, but
5666 @emph{listing a source file in @code{_DEPENDENCIES} is wrong}. If
5667 some source file needs to be built before all the components of a
5668 program are built, consider using the @code{BUILT_SOURCES} variable
5671 If @code{_DEPENDENCIES} is not supplied, it is computed by Automake.
5672 The automatically-assigned value is the contents of @code{_LDADD} or
5673 @code{_LIBADD}, with most configure substitutions, @option{-l}, @option{-L},
5674 @option{-dlopen} and @option{-dlpreopen} options removed. The configure
5675 substitutions that are left in are only @samp{$(LIBOBJS)} and
5676 @samp{$(ALLOCA)}; these are left because it is known that they will not
5677 cause an invalid value for @code{_DEPENDENCIES} to be generated.
5679 @code{_DEPENDENCIES} is more likely used to perform conditional
5680 compilation using an @code{AC_SUBST} variable that contains a list of
5681 objects. @xref{Conditional Sources}, and @ref{Conditional Libtool
5684 The @code{EXTRA_*_DEPENDENCIES} variable may be useful for cases where
5685 you merely want to augment the @command{automake}-generated
5686 @code{_DEPENDENCIES} variable rather than replacing it.
5689 You can override the linker on a per-program basis. By default the
5690 linker is chosen according to the languages used by the program. For
5691 instance, a program that includes C++ source code would use the C++
5692 compiler to link. The @code{_LINK} variable must hold the name of a
5693 command that can be passed all the @file{.o} file names and libraries
5694 to link against as arguments. Note that the name of the underlying
5695 program is @emph{not} passed to @code{_LINK}; typically one uses
5699 maude_LINK = $(CCLD) -magic -o $@@
5702 If a @code{_LINK} variable is not supplied, it may still be generated
5703 and used by Automake due to the use of per-target link flags such as
5704 @code{_CFLAGS}, @code{_LDFLAGS} or @code{_LIBTOOLFLAGS}, in cases where
5707 @item maude_CCASFLAGS
5709 @itemx maude_CPPFLAGS
5710 @itemx maude_CXXFLAGS
5712 @itemx maude_GCJFLAGS
5714 @itemx maude_OBJCFLAGS
5715 @itemx maude_OBJCXXFLAGS
5717 @itemx maude_UPCFLAGS
5719 @cindex per-target compilation flags, defined
5720 Automake allows you to set compilation flags on a per-program (or
5721 per-library) basis. A single source file can be included in several
5722 programs, and it will potentially be compiled with different flags for
5723 each program. This works for any language directly supported by
5724 Automake. These @dfn{per-target compilation flags} are
5733 @samp{_OBJCXXFLAGS},
5735 @samp{_UPCFLAGS}, and
5738 When using a per-target compilation flag, Automake will choose a
5739 different name for the intermediate object files. Ordinarily a file
5740 like @file{sample.c} will be compiled to produce @file{sample.o}.
5741 However, if the program's @code{_CFLAGS} variable is set, then the
5742 object file will be named, for instance, @file{maude-sample.o}. (See
5743 also @ref{Renamed Objects}.) The use of per-target compilation flags
5744 with C sources requires that the macro @code{AM_PROG_CC_C_O} be called
5745 from @file{configure.ac}.
5747 In compilations with per-target flags, the ordinary @samp{AM_} form of
5748 the flags variable is @emph{not} automatically included in the
5749 compilation (however, the user form of the variable @emph{is} included).
5750 So for instance, if you want the hypothetical @file{maude} compilations
5751 to also use the value of @code{AM_CFLAGS}, you would need to write:
5754 maude_CFLAGS = @dots{} your flags @dots{} $(AM_CFLAGS)
5757 @xref{Flag Variables Ordering}, for more discussion about the
5758 interaction between user variables, @samp{AM_} shadow variables, and
5759 per-target variables.
5761 @item maude_SHORTNAME
5762 On some platforms the allowable file names are very short. In order to
5763 support these systems and per-target compilation flags at the same
5764 time, Automake allows you to set a ``short name'' that will influence
5765 how intermediate object files are named. For instance, in the following
5769 bin_PROGRAMS = maude
5770 maude_CPPFLAGS = -DSOMEFLAG
5772 maude_SOURCES = sample.c @dots{}
5776 the object file would be named @file{m-sample.o} rather than
5777 @file{maude-sample.o}.
5779 This facility is rarely needed in practice,
5780 and we recommend avoiding it until you find it is required.
5783 @node Default _SOURCES
5784 @section Default @code{_SOURCES}
5788 @cindex @code{_SOURCES}, default
5789 @cindex default @code{_SOURCES}
5790 @vindex AM_DEFAULT_SOURCE_EXT
5792 @code{_SOURCES} variables are used to specify source files of programs
5793 (@pxref{A Program}), libraries (@pxref{A Library}), and Libtool
5794 libraries (@pxref{A Shared Library}).
5796 When no such variable is specified for a target, Automake will define
5797 one itself. The default is to compile a single C file whose base name
5798 is the name of the target itself, with any extension replaced by
5799 @code{AM_DEFAULT_SOURCE_EXT}, which defaults to @file{.c}.
5801 For example if you have the following somewhere in your
5802 @file{Makefile.am} with no corresponding @code{libfoo_a_SOURCES}:
5805 lib_LIBRARIES = libfoo.a sub/libc++.a
5809 @file{libfoo.a} will be built using a default source file named
5810 @file{libfoo.c}, and @file{sub/libc++.a} will be built from
5811 @file{sub/libc++.c}. (In older versions @file{sub/libc++.a}
5812 would be built from @file{sub_libc___a.c}, i.e., the default source
5813 was the canonized name of the target, with @file{.c} appended.
5814 We believe the new behavior is more sensible, but for backward
5815 compatibility @command{automake} will use the old name if a file or a rule
5816 with that name exists and @code{AM_DEFAULT_SOURCE_EXT} is not used.)
5818 @cindex @code{check_PROGRAMS} example
5819 @vindex check_PROGRAMS
5820 Default sources are mainly useful in test suites, when building many
5821 test programs each from a single source. For instance, in
5824 check_PROGRAMS = test1 test2 test3
5825 AM_DEFAULT_SOURCE_EXT = .cpp
5829 @file{test1}, @file{test2}, and @file{test3} will be built
5830 from @file{test1.cpp}, @file{test2.cpp}, and @file{test3.cpp}.
5831 Without the last line, they will be built from @file{test1.c},
5832 @file{test2.c}, and @file{test3.c}.
5834 @cindex Libtool modules, default source example
5835 @cindex default source, Libtool modules example
5836 Another case where this is convenient is building many Libtool modules
5837 (@file{module@var{n}.la}), each defined in its own file
5838 (@file{module@var{n}.c}).
5841 AM_LDFLAGS = -module
5842 lib_LTLIBRARIES = module1.la module2.la module3.la
5845 @cindex empty @code{_SOURCES}
5846 @cindex @code{_SOURCES}, empty
5847 Finally, there is one situation where this default source computation
5848 needs to be avoided: when a target should not be built from sources.
5849 We already saw such an example in @ref{true}; this happens when all
5850 the constituents of a target have already been compiled and just need
5851 to be combined using a @code{_LDADD} variable. Then it is necessary
5852 to define an empty @code{_SOURCES} variable, so that @command{automake}
5853 does not compute a default.
5856 bin_PROGRAMS = target
5858 target_LDADD = libmain.a libmisc.a
5862 @section Special handling for @code{LIBOBJS} and @code{ALLOCA}
5864 @cindex @code{LIBOBJS}, example
5865 @cindex @code{ALLOCA}, example
5866 @cindex @code{LIBOBJS}, special handling
5867 @cindex @code{ALLOCA}, special handling
5873 The @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} variables list object
5874 files that should be compiled into the project to provide an
5875 implementation for functions that are missing or broken on the host
5876 system. They are substituted by @file{configure}.
5880 These variables are defined by Autoconf macros such as
5881 @code{AC_LIBOBJ}, @code{AC_REPLACE_FUNCS} (@pxref{Generic Functions, ,
5882 Generic Function Checks, autoconf, The Autoconf Manual}), or
5883 @code{AC_FUNC_ALLOCA} (@pxref{Particular Functions, , Particular
5884 Function Checks, autoconf, The Autoconf Manual}). Many other Autoconf
5885 macros call @code{AC_LIBOBJ} or @code{AC_REPLACE_FUNCS} to
5886 populate @samp{$(LIBOBJS)}.
5888 @acindex AC_LIBSOURCE
5890 Using these variables is very similar to doing conditional compilation
5891 using @code{AC_SUBST} variables, as described in @ref{Conditional
5892 Sources}. That is, when building a program, @samp{$(LIBOBJS)} and
5893 @samp{$(ALLOCA)} should be added to the associated @samp{*_LDADD}
5894 variable, or to the @samp{*_LIBADD} variable when building a library.
5895 However there is no need to list the corresponding sources in
5896 @samp{EXTRA_*_SOURCES} nor to define @samp{*_DEPENDENCIES}. Automake
5897 automatically adds @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} to the
5898 dependencies, and it will discover the list of corresponding source
5899 files automatically (by tracing the invocations of the
5900 @code{AC_LIBSOURCE} Autoconf macros). If you have already defined
5901 @samp{*_DEPENDENCIES} explicitly for an unrelated reason, then you
5902 either need to add these variables manually, or use
5903 @samp{EXTRA_*_DEPENDENCIES} instead of @samp{*_DEPENDENCIES}.
5905 These variables are usually used to build a portability library that
5906 is linked with all the programs of the project. We now review a
5907 sample setup. First, @file{configure.ac} contains some checks that
5908 affect either @code{LIBOBJS} or @code{ALLOCA}.
5913 AC_CONFIG_LIBOBJ_DIR([lib])
5915 AC_FUNC_MALLOC dnl May add malloc.$(OBJEXT) to LIBOBJS
5916 AC_FUNC_MEMCMP dnl May add memcmp.$(OBJEXT) to LIBOBJS
5917 AC_REPLACE_FUNCS([strdup]) dnl May add strdup.$(OBJEXT) to LIBOBJS
5918 AC_FUNC_ALLOCA dnl May add alloca.$(OBJEXT) to ALLOCA
5927 @acindex AC_CONFIG_LIBOBJ_DIR
5929 The @code{AC_CONFIG_LIBOBJ_DIR} tells Autoconf that the source files
5930 of these object files are to be found in the @file{lib/} directory.
5931 Automake can also use this information, otherwise it expects the
5932 source files are to be in the directory where the @samp{$(LIBOBJS)}
5933 and @samp{$(ALLOCA)} variables are used.
5935 The @file{lib/} directory should therefore contain @file{malloc.c},
5936 @file{memcmp.c}, @file{strdup.c}, @file{alloca.c}. Here is its
5942 noinst_LIBRARIES = libcompat.a
5943 libcompat_a_SOURCES =
5944 libcompat_a_LIBADD = $(LIBOBJS) $(ALLOCA)
5947 The library can have any name, of course, and anyway it is not going
5948 to be installed: it just holds the replacement versions of the missing
5949 or broken functions so we can later link them in. Many projects
5950 also include extra functions, specific to the project, in that
5951 library: they are simply added on the @code{_SOURCES} line.
5953 @cindex Empty libraries and @samp{$(LIBOBJS)}
5954 @cindex @samp{$(LIBOBJS)} and empty libraries
5955 There is a small trap here, though: @samp{$(LIBOBJS)} and
5956 @samp{$(ALLOCA)} might be empty, and building an empty library is not
5957 portable. You should ensure that there is always something to put in
5958 @file{libcompat.a}. Most projects will also add some utility
5959 functions in that directory, and list them in
5960 @code{libcompat_a_SOURCES}, so in practice @file{libcompat.a} cannot
5963 Finally here is how this library could be used from the @file{src/}
5969 # Link all programs in this directory with libcompat.a
5970 LDADD = ../lib/libcompat.a
5972 bin_PROGRAMS = tool1 tool2 @dots{}
5973 tool1_SOURCES = @dots{}
5974 tool2_SOURCES = @dots{}
5977 When option @option{subdir-objects} is not used, as in the above
5978 example, the variables @samp{$(LIBOBJS)} or @samp{$(ALLOCA)} can only
5979 be used in the directory where their sources lie. E.g., here it would
5980 be wrong to use @samp{$(LIBOBJS)} or @samp{$(ALLOCA)} in
5981 @file{src/Makefile.am}. However if both @option{subdir-objects} and
5982 @code{AC_CONFIG_LIBOBJ_DIR} are used, it is OK to use these variables
5983 in other directories. For instance @file{src/Makefile.am} could be
5989 AUTOMAKE_OPTIONS = subdir-objects
5990 LDADD = $(LIBOBJS) $(ALLOCA)
5992 bin_PROGRAMS = tool1 tool2 @dots{}
5993 tool1_SOURCES = @dots{}
5994 tool2_SOURCES = @dots{}
5997 Because @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} contain object
5998 file names that end with @samp{.$(OBJEXT)}, they are not suitable for
5999 Libtool libraries (where the expected object extension is @file{.lo}):
6000 @code{LTLIBOBJS} and @code{LTALLOCA} should be used instead.
6002 @code{LTLIBOBJS} is defined automatically by Autoconf and should not
6003 be defined by hand (as in the past), however at the time of writing
6004 @code{LTALLOCA} still needs to be defined from @code{ALLOCA} manually.
6005 @xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs.@: @code{LIBOBJS},
6006 autoconf, The Autoconf Manual}.
6009 @node Program Variables
6010 @section Variables used when building a program
6012 Occasionally it is useful to know which @file{Makefile} variables
6013 Automake uses for compilations, and in which order (@pxref{Flag
6014 Variables Ordering}); for instance, you might need to do your own
6015 compilation in some special cases.
6017 Some variables are inherited from Autoconf; these are @code{CC},
6018 @code{CFLAGS}, @code{CPPFLAGS}, @code{DEFS}, @code{LDFLAGS}, and
6027 There are some additional variables that Automake defines on its own:
6031 The contents of this variable are passed to every compilation that invokes
6032 the C preprocessor; it is a list of arguments to the preprocessor. For
6033 instance, @option{-I} and @option{-D} options should be listed here.
6035 Automake already provides some @option{-I} options automatically, in a
6036 separate variable that is also passed to every compilation that invokes
6037 the C preprocessor. In particular it generates @samp{-I.},
6038 @samp{-I$(srcdir)}, and a @option{-I} pointing to the directory holding
6039 @file{config.h} (if you've used @code{AC_CONFIG_HEADERS} or
6040 @code{AM_CONFIG_HEADER}). You can disable the default @option{-I}
6041 options using the @option{nostdinc} option.
6043 When a file to be included is generated during the build and not part
6044 of a distribution tarball, its location is under @code{$(builddir)},
6045 not under @code{$(srcdir)}. This matters especially for packages that
6046 use header files placed in sub-directories and want to allow builds
6047 outside the source tree (@pxref{VPATH Builds}). In that case we
6048 recommend to use a pair of @option{-I} options, such as, e.g.,
6049 @samp{-Isome/subdir -I$(srcdir)/some/subdir} or
6050 @samp{-I$(top_builddir)/some/subdir -I$(top_srcdir)/some/subdir}.
6051 Note that the reference to the build tree should come before the
6052 reference to the source tree, so that accidentally leftover generated
6053 files in the source directory are ignored.
6055 @code{AM_CPPFLAGS} is ignored in preference to a per-executable (or
6056 per-library) @code{_CPPFLAGS} variable if it is defined.
6059 This does the same job as @code{AM_CPPFLAGS} (or any per-target
6060 @code{_CPPFLAGS} variable if it is used). It is an older name for the
6061 same functionality. This variable is deprecated; we suggest using
6062 @code{AM_CPPFLAGS} and per-target @code{_CPPFLAGS} instead.
6065 This is the variable the @file{Makefile.am} author can use to pass
6066 in additional C compiler flags. It is more fully documented elsewhere.
6067 In some situations, this is not used, in preference to the
6068 per-executable (or per-library) @code{_CFLAGS}.
6071 This is the command used to actually compile a C source file. The
6072 file name is appended to form the complete command line.
6075 This is the variable the @file{Makefile.am} author can use to pass
6076 in additional linker flags. In some situations, this is not used, in
6077 preference to the per-executable (or per-library) @code{_LDFLAGS}.
6080 This is the command used to actually link a C program. It already
6081 includes @samp{-o $@@} and the usual variable references (for instance,
6082 @code{CFLAGS}); it takes as ``arguments'' the names of the object files
6083 and libraries to link in. This variable is not used when the linker is
6084 overridden with a per-target @code{_LINK} variable or per-target flags
6085 cause Automake to define such a @code{_LINK} variable.
6090 @section Yacc and Lex support
6092 Automake has somewhat idiosyncratic support for Yacc and Lex.
6094 Automake assumes that the @file{.c} file generated by @command{yacc}
6095 (or @command{lex}) should be named using the basename of the input
6096 file. That is, for a yacc source file @file{foo.y}, Automake will
6097 cause the intermediate file to be named @file{foo.c} (as opposed to
6098 @file{y.tab.c}, which is more traditional).
6100 The extension of a yacc source file is used to determine the extension
6101 of the resulting C or C++ source and header files. Note that header
6102 files are generated only when the @option{-d} Yacc option is used; see
6103 below for more information about this flag, and how to specify it.
6104 Files with the extension @file{.y} will thus be turned into @file{.c}
6105 sources and @file{.h} headers; likewise, @file{.yy} will become
6106 @file{.cc} and @file{.hh}, @file{.y++} will become @file{c++} and
6107 @file{h++}, @file{.yxx} will become @file{.cxx} and @file{.hxx},
6108 and @file{.ypp} will become @file{.cpp} and @file{.hpp}.
6110 Similarly, lex source files can be used to generate C or C++; the
6111 extensions @file{.l}, @file{.ll}, @file{.l++}, @file{.lxx}, and
6112 @file{.lpp} are recognized.
6114 You should never explicitly mention the intermediate (C or C++) file
6115 in any @code{SOURCES} variable; only list the source file.
6117 The intermediate files generated by @command{yacc} (or @command{lex})
6118 will be included in any distribution that is made. That way the user
6119 doesn't need to have @command{yacc} or @command{lex}.
6121 If a @command{yacc} source file is seen, then your @file{configure.ac} must
6122 define the variable @code{YACC}. This is most easily done by invoking
6123 the macro @code{AC_PROG_YACC} (@pxref{Particular Programs, , Particular
6124 Program Checks, autoconf, The Autoconf Manual}).
6128 When @code{yacc} is invoked, it is passed @code{AM_YFLAGS} and
6129 @code{YFLAGS}. The latter is a user variable and the former is
6130 intended for the @file{Makefile.am} author.
6132 @code{AM_YFLAGS} is usually used to pass the @option{-d} option to
6133 @command{yacc}. Automake knows what this means and will automatically
6134 adjust its rules to update and distribute the header file built by
6135 @samp{yacc -d}@footnote{Please note that @command{automake} recognizes
6136 @option{-d} in @code{AM_YFLAGS} only if it is not clustered with other
6137 options; for example, it won't be recognized if @code{AM_YFLAGS} is
6138 @option{-dt}, but it will be if @code{AM_YFLAGS} is @option{-d -t} or
6140 What Automake cannot guess, though, is where this
6141 header will be used: it is up to you to ensure the header gets built
6142 before it is first used. Typically this is necessary in order for
6143 dependency tracking to work when the header is included by another
6144 file. The common solution is listing the header file in
6145 @code{BUILT_SOURCES} (@pxref{Sources}) as follows.
6148 BUILT_SOURCES = parser.h
6151 foo_SOURCES = @dots{} parser.y @dots{}
6154 If a @command{lex} source file is seen, then your @file{configure.ac}
6155 must define the variable @code{LEX}. You can use @code{AC_PROG_LEX}
6156 to do this (@pxref{Particular Programs, , Particular Program Checks,
6157 autoconf, The Autoconf Manual}), but using @code{AM_PROG_LEX} macro
6158 (@pxref{Macros}) is recommended.
6162 When @command{lex} is invoked, it is passed @code{AM_LFLAGS} and
6163 @code{LFLAGS}. The latter is a user variable and the former is
6164 intended for the @file{Makefile.am} author.
6166 When @code{AM_MAINTAINER_MODE} (@pxref{maintainer-mode}) is used, the
6167 rebuild rule for distributed Yacc and Lex sources are only used when
6168 @code{maintainer-mode} is enabled, or when the files have been erased.
6170 @cindex @command{ylwrap}
6171 @cindex @command{yacc}, multiple parsers
6172 @cindex Multiple @command{yacc} parsers
6173 @cindex Multiple @command{lex} lexers
6174 @cindex @command{lex}, multiple lexers
6176 When @command{lex} or @command{yacc} sources are used, @code{automake
6177 -i} automatically installs an auxiliary program called
6178 @command{ylwrap} in your package (@pxref{Auxiliary Programs}). This
6179 program is used by the build rules to rename the output of these
6180 tools, and makes it possible to include multiple @command{yacc} (or
6181 @command{lex}) source files in a single directory. (This is necessary
6182 because yacc's output file name is fixed, and a parallel make could
6183 conceivably invoke more than one instance of @command{yacc}
6186 For @command{yacc}, simply managing locking is insufficient. The output of
6187 @command{yacc} always uses the same symbol names internally, so it isn't
6188 possible to link two @command{yacc} parsers into the same executable.
6190 We recommend using the following renaming hack used in @command{gdb}:
6192 #define yymaxdepth c_maxdepth
6193 #define yyparse c_parse
6195 #define yyerror c_error
6196 #define yylval c_lval
6197 #define yychar c_char
6198 #define yydebug c_debug
6199 #define yypact c_pact
6206 #define yyexca c_exca
6207 #define yyerrflag c_errflag
6208 #define yynerrs c_nerrs
6212 #define yy_yys c_yys
6213 #define yystate c_state
6216 #define yy_yyv c_yyv
6218 #define yylloc c_lloc
6219 #define yyreds c_reds
6220 #define yytoks c_toks
6221 #define yylhs c_yylhs
6222 #define yylen c_yylen
6223 #define yydefred c_yydefred
6224 #define yydgoto c_yydgoto
6225 #define yysindex c_yysindex
6226 #define yyrindex c_yyrindex
6227 #define yygindex c_yygindex
6228 #define yytable c_yytable
6229 #define yycheck c_yycheck
6230 #define yyname c_yyname
6231 #define yyrule c_yyrule
6234 For each define, replace the @samp{c_} prefix with whatever you like.
6235 These defines work for @command{bison}, @command{byacc}, and
6236 traditional @code{yacc}s. If you find a parser generator that uses a
6237 symbol not covered here, please report the new name so it can be added
6242 @section C++ Support
6245 @cindex Support for C++
6247 Automake includes full support for C++.
6249 Any package including C++ code must define the output variable
6250 @code{CXX} in @file{configure.ac}; the simplest way to do this is to use
6251 the @code{AC_PROG_CXX} macro (@pxref{Particular Programs, , Particular
6252 Program Checks, autoconf, The Autoconf Manual}).
6254 A few additional variables are defined when a C++ source file is seen:
6258 The name of the C++ compiler.
6261 Any flags to pass to the C++ compiler.
6264 The maintainer's variant of @code{CXXFLAGS}.
6267 The command used to actually compile a C++ source file. The file name
6268 is appended to form the complete command line.
6271 The command used to actually link a C++ program.
6275 @node Objective C Support
6276 @section Objective C Support
6278 @cindex Objective C support
6279 @cindex Support for Objective C
6281 Automake includes some support for Objective C.
6283 Any package including Objective C code must define the output variable
6284 @code{OBJC} in @file{configure.ac}; the simplest way to do this is to use
6285 the @code{AC_PROG_OBJC} macro (@pxref{Particular Programs, , Particular
6286 Program Checks, autoconf, The Autoconf Manual}).
6288 A few additional variables are defined when an Objective C source file
6293 The name of the Objective C compiler.
6296 Any flags to pass to the Objective C compiler.
6299 The maintainer's variant of @code{OBJCFLAGS}.
6302 The command used to actually compile an Objective C source file. The
6303 file name is appended to form the complete command line.
6306 The command used to actually link an Objective C program.
6310 @node Objective C++ Support
6311 @section Objective C++ Support
6313 @cindex Objective C++ support
6314 @cindex Support for Objective C++
6316 Automake includes some support for Objective C++.
6318 Any package including Objective C++ code must define the output variable
6319 @code{OBJCXX} in @file{configure.ac}; the simplest way to do this is to use
6320 the @code{AC_PROG_OBJCXX} macro (@pxref{Particular Programs, , Particular
6321 Program Checks, autoconf, The Autoconf Manual}).
6323 A few additional variables are defined when an Objective C++ source file
6328 The name of the Objective C++ compiler.
6331 Any flags to pass to the Objective C++ compiler.
6333 @item AM_OBJCXXFLAGS
6334 The maintainer's variant of @code{OBJCXXFLAGS}.
6337 The command used to actually compile an Objective C++ source file. The
6338 file name is appended to form the complete command line.
6341 The command used to actually link an Objective C++ program.
6345 @node Unified Parallel C Support
6346 @section Unified Parallel C Support
6348 @cindex Unified Parallel C support
6349 @cindex Support for Unified Parallel C
6351 Automake includes some support for Unified Parallel C.
6353 Any package including Unified Parallel C code must define the output
6354 variable @code{UPC} in @file{configure.ac}; the simplest way to do
6355 this is to use the @code{AM_PROG_UPC} macro (@pxref{Public Macros}).
6357 A few additional variables are defined when a Unified Parallel C
6358 source file is seen:
6362 The name of the Unified Parallel C compiler.
6365 Any flags to pass to the Unified Parallel C compiler.
6368 The maintainer's variant of @code{UPCFLAGS}.
6371 The command used to actually compile a Unified Parallel C source file.
6372 The file name is appended to form the complete command line.
6375 The command used to actually link a Unified Parallel C program.
6379 @node Assembly Support
6380 @section Assembly Support
6382 Automake includes some support for assembly code. There are two forms
6383 of assembler files: normal (@file{*.s}) and preprocessed by @code{CPP}
6384 (@file{*.S} or @file{*.sx}).
6389 @vindex AM_CCASFLAGS
6391 The variable @code{CCAS} holds the name of the compiler used to build
6392 assembly code. This compiler must work a bit like a C compiler; in
6393 particular it must accept @option{-c} and @option{-o}. The values of
6394 @code{CCASFLAGS} and @code{AM_CCASFLAGS} (or its per-target
6395 definition) is passed to the compilation. For preprocessed files,
6396 @code{DEFS}, @code{DEFAULT_INCLUDES}, @code{INCLUDES}, @code{CPPFLAGS}
6397 and @code{AM_CPPFLAGS} are also used.
6399 The autoconf macro @code{AM_PROG_AS} will define @code{CCAS} and
6400 @code{CCASFLAGS} for you (unless they are already set, it simply sets
6401 @code{CCAS} to the C compiler and @code{CCASFLAGS} to the C compiler
6402 flags), but you are free to define these variables by other means.
6404 Only the suffixes @file{.s}, @file{.S}, and @file{.sx} are recognized by
6405 @command{automake} as being files containing assembly code.
6408 @node Fortran 77 Support
6409 @comment node-name, next, previous, up
6410 @section Fortran 77 Support
6412 @cindex Fortran 77 support
6413 @cindex Support for Fortran 77
6415 Automake includes full support for Fortran 77.
6417 Any package including Fortran 77 code must define the output variable
6418 @code{F77} in @file{configure.ac}; the simplest way to do this is to use
6419 the @code{AC_PROG_F77} macro (@pxref{Particular Programs, , Particular
6420 Program Checks, autoconf, The Autoconf Manual}).
6422 A few additional variables are defined when a Fortran 77 source file is
6428 The name of the Fortran 77 compiler.
6431 Any flags to pass to the Fortran 77 compiler.
6434 The maintainer's variant of @code{FFLAGS}.
6437 Any flags to pass to the Ratfor compiler.
6440 The maintainer's variant of @code{RFLAGS}.
6443 The command used to actually compile a Fortran 77 source file. The file
6444 name is appended to form the complete command line.
6447 The command used to actually link a pure Fortran 77 program or shared
6452 Automake can handle preprocessing Fortran 77 and Ratfor source files in
6453 addition to compiling them@footnote{Much, if not most, of the
6454 information in the following sections pertaining to preprocessing
6455 Fortran 77 programs was taken almost verbatim from @ref{Catalogue of
6456 Rules, , Catalogue of Rules, make, The GNU Make Manual}.}. Automake
6457 also contains some support for creating programs and shared libraries
6458 that are a mixture of Fortran 77 and other languages (@pxref{Mixing
6459 Fortran 77 With C and C++}).
6461 These issues are covered in the following sections.
6464 * Preprocessing Fortran 77:: Preprocessing Fortran 77 sources
6465 * Compiling Fortran 77 Files:: Compiling Fortran 77 sources
6466 * Mixing Fortran 77 With C and C++:: Mixing Fortran 77 With C and C++
6470 @node Preprocessing Fortran 77
6471 @comment node-name, next, previous, up
6472 @subsection Preprocessing Fortran 77
6474 @cindex Preprocessing Fortran 77
6475 @cindex Fortran 77, Preprocessing
6476 @cindex Ratfor programs
6478 @file{N.f} is made automatically from @file{N.F} or @file{N.r}. This
6479 rule runs just the preprocessor to convert a preprocessable Fortran 77
6480 or Ratfor source file into a strict Fortran 77 source file. The precise
6481 command used is as follows:
6486 @code{$(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)@*
6487 $(AM_FFLAGS) $(FFLAGS)}
6490 @code{$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
6495 @node Compiling Fortran 77 Files
6496 @comment node-name, next, previous, up
6497 @subsection Compiling Fortran 77 Files
6499 @file{N.o} is made automatically from @file{N.f}, @file{N.F} or
6500 @file{N.r} by running the Fortran 77 compiler. The precise command used
6506 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS)}
6509 @code{$(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)@*
6510 $(AM_FFLAGS) $(FFLAGS)}
6513 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
6518 @node Mixing Fortran 77 With C and C++
6519 @comment node-name, next, previous, up
6520 @subsection Mixing Fortran 77 With C and C++
6522 @cindex Fortran 77, mixing with C and C++
6523 @cindex Mixing Fortran 77 with C and C++
6524 @cindex Linking Fortran 77 with C and C++
6526 @cindex Mixing Fortran 77 with C and/or C++
6528 Automake currently provides @emph{limited} support for creating programs
6529 and shared libraries that are a mixture of Fortran 77 and C and/or C++.
6530 However, there are many other issues related to mixing Fortran 77 with
6531 other languages that are @emph{not} (currently) handled by Automake, but
6532 that are handled by other packages@footnote{For example,
6533 @uref{http://www-zeus.desy.de/~burow/cfortran/, the cfortran package}
6534 addresses all of these inter-language issues, and runs under nearly all
6535 Fortran 77, C and C++ compilers on nearly all platforms. However,
6536 @command{cfortran} is not yet Free Software, but it will be in the next
6539 Automake can help in two ways:
6543 Automatic selection of the linker depending on which combinations of
6547 Automatic selection of the appropriate linker flags (e.g., @option{-L} and
6548 @option{-l}) to pass to the automatically selected linker in order to link
6549 in the appropriate Fortran 77 intrinsic and run-time libraries.
6551 @cindex @code{FLIBS}, defined
6553 These extra Fortran 77 linker flags are supplied in the output variable
6554 @code{FLIBS} by the @code{AC_F77_LIBRARY_LDFLAGS} Autoconf macro.
6555 @xref{Fortran Compiler, , Fortran Compiler Characteristics, autoconf,
6556 The Autoconf Manual}.
6559 If Automake detects that a program or shared library (as mentioned in
6560 some @code{_PROGRAMS} or @code{_LTLIBRARIES} primary) contains source
6561 code that is a mixture of Fortran 77 and C and/or C++, then it requires
6562 that the macro @code{AC_F77_LIBRARY_LDFLAGS} be called in
6563 @file{configure.ac}, and that either @code{$(FLIBS)}
6564 appear in the appropriate @code{_LDADD} (for programs) or @code{_LIBADD}
6565 (for shared libraries) variables. It is the responsibility of the
6566 person writing the @file{Makefile.am} to make sure that @samp{$(FLIBS)}
6567 appears in the appropriate @code{_LDADD} or
6568 @code{_LIBADD} variable.
6570 @cindex Mixed language example
6571 @cindex Example, mixed language
6573 For example, consider the following @file{Makefile.am}:
6577 foo_SOURCES = main.cc foo.f
6578 foo_LDADD = libfoo.la $(FLIBS)
6580 pkglib_LTLIBRARIES = libfoo.la
6581 libfoo_la_SOURCES = bar.f baz.c zardoz.cc
6582 libfoo_la_LIBADD = $(FLIBS)
6585 In this case, Automake will insist that @code{AC_F77_LIBRARY_LDFLAGS}
6586 is mentioned in @file{configure.ac}. Also, if @samp{$(FLIBS)} hadn't
6587 been mentioned in @code{foo_LDADD} and @code{libfoo_la_LIBADD}, then
6588 Automake would have issued a warning.
6591 * How the Linker is Chosen:: Automatic linker selection
6594 @node How the Linker is Chosen
6595 @comment node-name, next, previous, up
6596 @subsubsection How the Linker is Chosen
6598 @cindex Automatic linker selection
6599 @cindex Selecting the linker automatically
6601 When a program or library mixes several languages, Automake choose the
6602 linker according to the following priorities. (The names in
6603 parentheses are the variables containing the link command.)
6608 Native Java (@code{GCJLINK})
6611 Objective C++ (@code{OBJCXXLINK})
6614 C++ (@code{CXXLINK})
6617 Fortran 77 (@code{F77LINK})
6620 Fortran (@code{FCLINK})
6623 Objective C (@code{OBJCLINK})
6626 Unified Parallel C (@code{UPCLINK})
6632 For example, if Fortran 77, C and C++ source code is compiled
6633 into a program, then the C++ linker will be used. In this case, if the
6634 C or Fortran 77 linkers required any special libraries that weren't
6635 included by the C++ linker, then they must be manually added to an
6636 @code{_LDADD} or @code{_LIBADD} variable by the user writing the
6639 Automake only looks at the file names listed in @file{_SOURCES}
6640 variables to choose the linker, and defaults to the C linker.
6641 Sometimes this is inconvenient because you are linking against a
6642 library written in another language and would like to set the linker
6643 more appropriately. @xref{Libtool Convenience Libraries}, for a
6644 trick with @code{nodist_EXTRA_@dots{}_SOURCES}.
6646 A per-target @code{_LINK} variable will override the above selection.
6647 Per-target link flags will cause Automake to write a per-target
6648 @code{_LINK} variable according to the language chosen as above.
6651 @node Fortran 9x Support
6652 @comment node-name, next, previous, up
6653 @section Fortran 9x Support
6655 @cindex Fortran 9x support
6656 @cindex Support for Fortran 9x
6658 Automake includes support for Fortran 9x.
6660 Any package including Fortran 9x code must define the output variable
6661 @code{FC} in @file{configure.ac}; the simplest way to do this is to use
6662 the @code{AC_PROG_FC} macro (@pxref{Particular Programs, , Particular
6663 Program Checks, autoconf, The Autoconf Manual}).
6665 A few additional variables are defined when a Fortran 9x source file is
6671 The name of the Fortran 9x compiler.
6674 Any flags to pass to the Fortran 9x compiler.
6677 The maintainer's variant of @code{FCFLAGS}.
6680 The command used to actually compile a Fortran 9x source file. The file
6681 name is appended to form the complete command line.
6684 The command used to actually link a pure Fortran 9x program or shared
6690 * Compiling Fortran 9x Files:: Compiling Fortran 9x sources
6693 @node Compiling Fortran 9x Files
6694 @comment node-name, next, previous, up
6695 @subsection Compiling Fortran 9x Files
6697 @file{@var{file}.o} is made automatically from @file{@var{file}.f90},
6698 @file{@var{file}.f95}, @file{@var{file}.f03}, or @file{@var{file}.f08}
6699 by running the Fortran 9x compiler. The precise command used
6705 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f90) $<}
6708 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f95) $<}
6711 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f03) $<}
6714 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f08) $<}
6718 @node Java Support with gcj
6719 @comment node-name, next, previous, up
6720 @section Compiling Java sources using gcj
6722 @cindex Java support with gcj
6723 @cindex Support for Java with gcj
6724 @cindex Java to native code, compilation
6725 @cindex Compilation of Java to native code
6727 Automake includes support for natively compiled Java, using @command{gcj},
6728 the Java front end to the GNU Compiler Collection (rudimentary support
6729 for compiling Java to bytecode using the @command{javac} compiler is
6730 also present, @emph{albeit deprecated}; @pxref{Java}).
6732 Any package including Java code to be compiled must define the output
6733 variable @code{GCJ} in @file{configure.ac}; the variable @code{GCJFLAGS}
6734 must also be defined somehow (either in @file{configure.ac} or
6735 @file{Makefile.am}). The simplest way to do this is to use the
6736 @code{AM_PROG_GCJ} macro.
6740 By default, programs including Java source files are linked with
6743 As always, the contents of @code{AM_GCJFLAGS} are passed to every
6744 compilation invoking @command{gcj} (in its role as an ahead-of-time
6745 compiler, when invoking it to create @file{.class} files,
6746 @code{AM_JAVACFLAGS} is used instead). If it is necessary to pass
6747 options to @command{gcj} from @file{Makefile.am}, this variable, and not
6748 the user variable @code{GCJFLAGS}, should be used.
6752 @command{gcj} can be used to compile @file{.java}, @file{.class},
6753 @file{.zip}, or @file{.jar} files.
6755 When linking, @command{gcj} requires that the main class be specified
6756 using the @option{--main=} option. The easiest way to do this is to use
6757 the @code{_LDFLAGS} variable for the program.
6761 @comment node-name, next, previous, up
6762 @section Vala Support
6764 @cindex Vala Support
6765 @cindex Support for Vala
6767 Automake provides initial support for Vala
6768 (@uref{http://www.vala-project.org/}).
6769 This requires valac version 0.7.0 or later, and currently requires
6770 the user to use GNU @command{make}.
6773 foo_SOURCES = foo.vala bar.vala zardoc.c
6776 Any @file{.vala} file listed in a @code{_SOURCES} variable will be
6777 compiled into C code by the Vala compiler. The generated @file{.c} files are
6778 distributed. The end user does not need to have a Vala compiler installed.
6780 Automake ships with an Autoconf macro called @code{AM_PROG_VALAC}
6781 that will locate the Vala compiler and optionally check its version
6784 @defmac AM_PROG_VALAC (@ovar{minimum-version})
6785 Try to find a Vala compiler in @env{PATH}. If it is found, the variable
6786 @code{VALAC} is set. Optionally a minimum release number of the compiler
6790 AM_PROG_VALAC([0.7.0])
6794 There are a few variables that are used when compiling Vala sources:
6798 Path to the Vala compiler.
6801 Additional arguments for the Vala compiler.
6804 The maintainer's variant of @code{VALAFLAGS}.
6807 lib_LTLIBRARIES = libfoo.la
6808 libfoo_la_SOURCES = foo.vala
6812 Note that currently, you cannot use per-target @code{*_VALAFLAGS}
6813 (@pxref{Renamed Objects}) to produce different C files from one Vala
6817 @node Support for Other Languages
6818 @comment node-name, next, previous, up
6819 @section Support for Other Languages
6821 Automake currently only includes full support for C, C++ (@pxref{C++
6822 Support}), Objective C (@pxref{Objective C Support}),
6823 Objective C++ (@pxref{Objective C++ Support}),
6825 (@pxref{Fortran 77 Support}), Fortran 9x (@pxref{Fortran 9x Support}),
6826 and Java (@pxref{Java Support with gcj}). There is only rudimentary
6827 support for other languages, support for which will be improved based
6830 Some limited support for adding your own languages is available via the
6831 suffix rule handling (@pxref{Suffixes}).
6834 @section Automatic dependency tracking
6836 As a developer it is often painful to continually update the
6837 @file{Makefile.am} whenever the include-file dependencies change in a
6838 project. Automake supplies a way to automatically track dependency
6839 changes (@pxref{Dependency Tracking}).
6841 @cindex Dependency tracking
6842 @cindex Automatic dependency tracking
6844 Automake always uses complete dependencies for a compilation,
6845 including system headers. Automake's model is that dependency
6846 computation should be a side effect of the build. To this end,
6847 dependencies are computed by running all compilations through a
6848 special wrapper program called @command{depcomp}. @command{depcomp}
6849 understands how to coax many different C and C++ compilers into
6850 generating dependency information in the format it requires.
6851 @samp{automake -a} will install @command{depcomp} into your source
6852 tree for you. If @command{depcomp} can't figure out how to properly
6853 invoke your compiler, dependency tracking will simply be disabled for
6856 @cindex @command{depcomp}
6858 Experience with earlier versions of Automake (@pxref{Dependency Tracking
6859 Evolution, , Dependency Tracking Evolution, automake-history, Brief History
6860 of Automake}) taught us that it is not reliable to generate dependencies
6861 only on the maintainer's system, as configurations vary too much. So
6862 instead Automake implements dependency tracking at build time.
6864 Automatic dependency tracking can be suppressed by putting
6865 @option{no-dependencies} in the variable @code{AUTOMAKE_OPTIONS}, or
6866 passing @option{no-dependencies} as an argument to @code{AM_INIT_AUTOMAKE}
6867 (this should be the preferred way). Or, you can invoke @command{automake}
6868 with the @option{-i} option. Dependency tracking is enabled by default.
6870 @vindex AUTOMAKE_OPTIONS
6871 @opindex no-dependencies
6873 The person building your package also can choose to disable dependency
6874 tracking by configuring with @option{--disable-dependency-tracking}.
6876 @cindex Disabling dependency tracking
6877 @cindex Dependency tracking, disabling
6881 @section Support for executable extensions
6883 @cindex Executable extension
6884 @cindex Extension, executable
6887 On some platforms, such as Windows, executables are expected to have an
6888 extension such as @file{.exe}. On these platforms, some compilers (GCC
6889 among them) will automatically generate @file{foo.exe} when asked to
6890 generate @file{foo}.
6892 Automake provides mostly-transparent support for this. Unfortunately
6893 @emph{mostly} doesn't yet mean @emph{fully}. Until the English
6894 dictionary is revised, you will have to assist Automake if your package
6895 must support those platforms.
6897 One thing you must be aware of is that, internally, Automake rewrites
6898 something like this:
6901 bin_PROGRAMS = liver
6907 bin_PROGRAMS = liver$(EXEEXT)
6910 The targets Automake generates are likewise given the @samp{$(EXEEXT)}
6913 The variables @code{TESTS} and @code{XFAIL_TESTS} (@pxref{Simple Tests})
6914 are also rewritten if they contain filenames that have been declared as
6915 programs in the same @file{Makefile}. (This is mostly useful when some
6916 programs from @code{check_PROGRAMS} are listed in @code{TESTS}.)
6918 However, Automake cannot apply this rewriting to @command{configure}
6919 substitutions. This means that if you are conditionally building a
6920 program using such a substitution, then your @file{configure.ac} must
6921 take care to add @samp{$(EXEEXT)} when constructing the output variable.
6923 Sometimes maintainers like to write an explicit link rule for their
6924 program. Without executable extension support, this is easy---you
6925 simply write a rule whose target is the name of the program. However,
6926 when executable extension support is enabled, you must instead add the
6927 @samp{$(EXEEXT)} suffix.
6929 This might be a nuisance for maintainers who know their package will
6930 never run on a platform that has
6931 executable extensions. For those maintainers, the @option{no-exeext}
6932 option (@pxref{Options}) will disable this feature. This works in a
6933 fairly ugly way; if @option{no-exeext} is seen, then the presence of a
6934 rule for a target named @code{foo} in @file{Makefile.am} will override
6935 an @command{automake}-generated rule for @samp{foo$(EXEEXT)}. Without
6936 the @option{no-exeext} option, this use will give a diagnostic.
6940 @chapter Other Derived Objects
6942 Automake can handle derived objects that are not C programs. Sometimes
6943 the support for actually building such objects must be explicitly
6944 supplied, but Automake will still automatically handle installation and
6948 * Scripts:: Executable scripts
6949 * Headers:: Header files
6950 * Data:: Architecture-independent data files
6951 * Sources:: Derived sources
6956 @section Executable Scripts
6958 @cindex @code{_SCRIPTS} primary, defined
6959 @cindex @code{SCRIPTS} primary, defined
6960 @cindex Primary variable, @code{SCRIPTS}
6962 @cindex Installing scripts
6964 It is possible to define and install programs that are scripts. Such
6965 programs are listed using the @code{SCRIPTS} primary name. When the
6966 script is distributed in its final, installable form, the
6967 @file{Makefile} usually looks as follows:
6971 # Install my_script in $(bindir) and distribute it.
6972 dist_bin_SCRIPTS = my_script
6975 Scripts are not distributed by default; as we have just seen, those
6976 that should be distributed can be specified using a @code{dist_}
6977 prefix as with other primaries.
6979 @cindex @code{SCRIPTS}, installation directories
6981 @vindex sbin_SCRIPTS
6982 @vindex libexec_SCRIPTS
6983 @vindex pkgdata_SCRIPTS
6984 @vindex pkglibexec_SCRIPTS
6985 @vindex noinst_SCRIPTS
6986 @vindex check_SCRIPTS
6988 Scripts can be installed in @code{bindir}, @code{sbindir},
6989 @code{libexecdir}, @code{pkglibexecdir}, or @code{pkgdatadir}.
6991 Scripts that need not be installed can be listed in
6992 @code{noinst_SCRIPTS}, and among them, those which are needed only by
6993 @samp{make check} should go in @code{check_SCRIPTS}.
6995 When a script needs to be built, the @file{Makefile.am} should include
6996 the appropriate rules. For instance the @command{automake} program
6997 itself is a Perl script that is generated from @file{automake.in}.
6998 Here is how this is handled:
7001 bin_SCRIPTS = automake
7002 CLEANFILES = $(bin_SCRIPTS)
7003 EXTRA_DIST = automake.in
7005 do_subst = sed -e 's,[@@]datadir[@@],$(datadir),g' \
7006 -e 's,[@@]PERL[@@],$(PERL),g' \
7007 -e 's,[@@]PACKAGE[@@],$(PACKAGE),g' \
7008 -e 's,[@@]VERSION[@@],$(VERSION),g' \
7011 automake: automake.in Makefile
7012 $(do_subst) < $(srcdir)/automake.in > automake
7016 Such scripts for which a build rule has been supplied need to be
7017 deleted explicitly using @code{CLEANFILES} (@pxref{Clean}), and their
7018 sources have to be distributed, usually with @code{EXTRA_DIST}
7019 (@pxref{Basics of Distribution}).
7021 Another common way to build scripts is to process them from
7022 @file{configure} with @code{AC_CONFIG_FILES}. In this situation
7023 Automake knows which files should be cleaned and distributed, and what
7024 the rebuild rules should look like.
7026 For instance if @file{configure.ac} contains
7029 AC_CONFIG_FILES([src/my_script], [chmod +x src/my_script])
7033 to build @file{src/my_script} from @file{src/my_script.in}, then a
7034 @file{src/Makefile.am} to install this script in @code{$(bindir)} can
7038 bin_SCRIPTS = my_script
7039 CLEANFILES = $(bin_SCRIPTS)
7043 There is no need for @code{EXTRA_DIST} or any build rule: Automake
7044 infers them from @code{AC_CONFIG_FILES} (@pxref{Requirements}).
7045 @code{CLEANFILES} is still useful, because by default Automake will
7046 clean targets of @code{AC_CONFIG_FILES} in @code{distclean}, not
7049 Although this looks simpler, building scripts this way has one
7050 drawback: directory variables such as @code{$(datadir)} are not fully
7051 expanded and may refer to other directory variables.
7054 @section Header files
7056 @cindex @code{_HEADERS} primary, defined
7057 @cindex @code{HEADERS} primary, defined
7058 @cindex Primary variable, @code{HEADERS}
7060 @vindex noinst_HEADERS
7061 @cindex @code{HEADERS}, installation directories
7062 @cindex Installing headers
7063 @vindex include_HEADERS
7064 @vindex oldinclude_HEADERS
7065 @vindex pkginclude_HEADERS
7068 Header files that must be installed are specified by the
7069 @code{HEADERS} family of variables. Headers can be installed in
7070 @code{includedir}, @code{oldincludedir}, @code{pkgincludedir} or any
7071 other directory you may have defined (@pxref{Uniform}). For instance,
7074 include_HEADERS = foo.h bar/bar.h
7078 will install the two files as @file{$(includedir)/foo.h} and
7079 @file{$(includedir)/bar.h}.
7081 The @code{nobase_} prefix is also supported,
7084 nobase_include_HEADERS = foo.h bar/bar.h
7088 will install the two files as @file{$(includedir)/foo.h} and
7089 @file{$(includedir)/bar/bar.h} (@pxref{Alternative}).
7091 @vindex noinst_HEADERS
7092 Usually, only header files that accompany installed libraries need to
7093 be installed. Headers used by programs or convenience libraries are
7094 not installed. The @code{noinst_HEADERS} variable can be used for
7095 such headers. However when the header actually belongs to a single
7096 convenience library or program, we recommend listing it in the
7097 program's or library's @code{_SOURCES} variable (@pxref{Program
7098 Sources}) instead of in @code{noinst_HEADERS}. This is clearer for
7099 the @file{Makefile.am} reader. @code{noinst_HEADERS} would be the
7100 right variable to use in a directory containing only headers and no
7101 associated library or program.
7103 All header files must be listed somewhere; in a @code{_SOURCES}
7104 variable or in a @code{_HEADERS} variable. Missing ones will not
7105 appear in the distribution.
7107 For header files that are built and must not be distributed, use the
7108 @code{nodist_} prefix as in @code{nodist_include_HEADERS} or
7109 @code{nodist_prog_SOURCES}. If these generated headers are needed
7110 during the build, you must also ensure they exist before they are
7111 used (@pxref{Sources}).
7115 @section Architecture-independent data files
7117 @cindex @code{_DATA} primary, defined
7118 @cindex @code{DATA} primary, defined
7119 @cindex Primary variable, @code{DATA}
7122 Automake supports the installation of miscellaneous data files using the
7123 @code{DATA} family of variables.
7127 @vindex sysconf_DATA
7128 @vindex sharedstate_DATA
7129 @vindex localstate_DATA
7130 @vindex pkgdata_DATA
7132 Such data can be installed in the directories @code{datadir},
7133 @code{sysconfdir}, @code{sharedstatedir}, @code{localstatedir}, or
7136 By default, data files are @emph{not} included in a distribution. Of
7137 course, you can use the @code{dist_} prefix to change this on a
7140 Here is how Automake declares its auxiliary data files:
7143 dist_pkgdata_DATA = clean-kr.am clean.am @dots{}
7148 @section Built Sources
7150 Because Automake's automatic dependency tracking works as a side-effect
7151 of compilation (@pxref{Dependencies}) there is a bootstrap issue: a
7152 target should not be compiled before its dependencies are made, but
7153 these dependencies are unknown until the target is first compiled.
7155 Ordinarily this is not a problem, because dependencies are distributed
7156 sources: they preexist and do not need to be built. Suppose that
7157 @file{foo.c} includes @file{foo.h}. When it first compiles
7158 @file{foo.o}, @command{make} only knows that @file{foo.o} depends on
7159 @file{foo.c}. As a side-effect of this compilation @command{depcomp}
7160 records the @file{foo.h} dependency so that following invocations of
7161 @command{make} will honor it. In these conditions, it's clear there is
7162 no problem: either @file{foo.o} doesn't exist and has to be built
7163 (regardless of the dependencies), or accurate dependencies exist and
7164 they can be used to decide whether @file{foo.o} should be rebuilt.
7166 It's a different story if @file{foo.h} doesn't exist by the first
7167 @command{make} run. For instance, there might be a rule to build
7168 @file{foo.h}. This time @file{file.o}'s build will fail because the
7169 compiler can't find @file{foo.h}. @command{make} failed to trigger the
7170 rule to build @file{foo.h} first by lack of dependency information.
7172 @vindex BUILT_SOURCES
7173 @cindex @code{BUILT_SOURCES}, defined
7175 The @code{BUILT_SOURCES} variable is a workaround for this problem. A
7176 source file listed in @code{BUILT_SOURCES} is made on @samp{make all}
7177 or @samp{make check} (or even @samp{make install}) before other
7178 targets are processed. However, such a source file is not
7179 @emph{compiled} unless explicitly requested by mentioning it in some
7180 other @code{_SOURCES} variable.
7182 So, to conclude our introductory example, we could use
7183 @samp{BUILT_SOURCES = foo.h} to ensure @file{foo.h} gets built before
7184 any other target (including @file{foo.o}) during @samp{make all} or
7187 @code{BUILT_SOURCES} is actually a bit of a misnomer, as any file which
7188 must be created early in the build process can be listed in this
7189 variable. Moreover, all built sources do not necessarily have to be
7190 listed in @code{BUILT_SOURCES}. For instance, a generated @file{.c} file
7191 doesn't need to appear in @code{BUILT_SOURCES} (unless it is included by
7192 another source), because it's a known dependency of the associated
7195 It might be important to emphasize that @code{BUILT_SOURCES} is
7196 honored only by @samp{make all}, @samp{make check} and @samp{make
7197 install}. This means you cannot build a specific target (e.g.,
7198 @samp{make foo}) in a clean tree if it depends on a built source.
7199 However it will succeed if you have run @samp{make all} earlier,
7200 because accurate dependencies are already available.
7202 The next section illustrates and discusses the handling of built sources
7206 * Built Sources Example:: Several ways to handle built sources.
7209 @node Built Sources Example
7210 @subsection Built Sources Example
7212 Suppose that @file{foo.c} includes @file{bindir.h}, which is
7213 installation-dependent and not distributed: it needs to be built. Here
7214 @file{bindir.h} defines the preprocessor macro @code{bindir} to the
7215 value of the @command{make} variable @code{bindir} (inherited from
7218 We suggest several implementations below. It's not meant to be an
7219 exhaustive listing of all ways to handle built sources, but it will give
7220 you a few ideas if you encounter this issue.
7222 @subsubheading First Try
7224 This first implementation will illustrate the bootstrap issue mentioned
7225 in the previous section (@pxref{Sources}).
7227 Here is a tentative @file{Makefile.am}.
7233 nodist_foo_SOURCES = bindir.h
7234 CLEANFILES = bindir.h
7236 echo '#define bindir "$(bindir)"' >$@@
7239 This setup doesn't work, because Automake doesn't know that @file{foo.c}
7240 includes @file{bindir.h}. Remember, automatic dependency tracking works
7241 as a side-effect of compilation, so the dependencies of @file{foo.o} will
7242 be known only after @file{foo.o} has been compiled (@pxref{Dependencies}).
7243 The symptom is as follows.
7247 source='foo.c' object='foo.o' libtool=no \
7248 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
7249 depmode=gcc /bin/sh ./depcomp \
7250 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
7251 foo.c:2: bindir.h: No such file or directory
7252 make: *** [foo.o] Error 1
7255 In this example @file{bindir.h} is not distributed nor installed, and
7256 it is not even being built on-time. One may wonder if the
7257 @samp{nodist_foo_SOURCES = bindir.h} line has any use at all. This
7258 line simply states that @file{bindir.h} is a source of @code{foo}, so
7259 for instance, it should be inspected while generating tags
7260 (@pxref{Tags}). In other words, it does not help our present problem,
7261 and the build would fail identically without it.
7263 @subsubheading Using @code{BUILT_SOURCES}
7265 A solution is to require @file{bindir.h} to be built before anything
7266 else. This is what @code{BUILT_SOURCES} is meant for (@pxref{Sources}).
7271 nodist_foo_SOURCES = bindir.h
7272 BUILT_SOURCES = bindir.h
7273 CLEANFILES = bindir.h
7275 echo '#define bindir "$(bindir)"' >$@@
7278 See how @file{bindir.h} gets built first:
7282 echo '#define bindir "/usr/local/bin"' >bindir.h
7284 make[1]: Entering directory `/home/adl/tmp'
7285 source='foo.c' object='foo.o' libtool=no \
7286 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
7287 depmode=gcc /bin/sh ./depcomp \
7288 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
7289 gcc -g -O2 -o foo foo.o
7290 make[1]: Leaving directory `/home/adl/tmp'
7293 However, as said earlier, @code{BUILT_SOURCES} applies only to the
7294 @code{all}, @code{check}, and @code{install} targets. It still fails
7295 if you try to run @samp{make foo} explicitly:
7299 test -z "bindir.h" || rm -f bindir.h
7300 test -z "foo" || rm -f foo
7302 % : > .deps/foo.Po # Suppress previously recorded dependencies
7304 source='foo.c' object='foo.o' libtool=no \
7305 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
7306 depmode=gcc /bin/sh ./depcomp \
7307 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
7308 foo.c:2: bindir.h: No such file or directory
7309 make: *** [foo.o] Error 1
7312 @subsubheading Recording Dependencies manually
7314 Usually people are happy enough with @code{BUILT_SOURCES} because they
7315 never build targets such as @samp{make foo} before @samp{make all}, as
7316 in the previous example. However if this matters to you, you can
7317 avoid @code{BUILT_SOURCES} and record such dependencies explicitly in
7318 the @file{Makefile.am}.
7323 nodist_foo_SOURCES = bindir.h
7324 foo.$(OBJEXT): bindir.h
7325 CLEANFILES = bindir.h
7327 echo '#define bindir "$(bindir)"' >$@@
7330 You don't have to list @emph{all} the dependencies of @file{foo.o}
7331 explicitly, only those that might need to be built. If a dependency
7332 already exists, it will not hinder the first compilation and will be
7333 recorded by the normal dependency tracking code. (Note that after
7334 this first compilation the dependency tracking code will also have
7335 recorded the dependency between @file{foo.o} and
7336 @file{bindir.h}; so our explicit dependency is really useful to
7337 the first build only.)
7339 Adding explicit dependencies like this can be a bit dangerous if you are
7340 not careful enough. This is due to the way Automake tries not to
7341 overwrite your rules (it assumes you know better than it).
7342 @samp{foo.$(OBJEXT): bindir.h} supersedes any rule Automake may want to
7343 output to build @samp{foo.$(OBJEXT)}. It happens to work in this case
7344 because Automake doesn't have to output any @samp{foo.$(OBJEXT):}
7345 target: it relies on a suffix rule instead (i.e., @samp{.c.$(OBJEXT):}).
7346 Always check the generated @file{Makefile.in} if you do this.
7348 @subsubheading Build @file{bindir.h} from @file{configure}
7350 It's possible to define this preprocessor macro from @file{configure},
7351 either in @file{config.h} (@pxref{Defining Directories, , Defining
7352 Directories, autoconf, The Autoconf Manual}), or by processing a
7353 @file{bindir.h.in} file using @code{AC_CONFIG_FILES}
7354 (@pxref{Configuration Actions, ,Configuration Actions, autoconf, The
7357 At this point it should be clear that building @file{bindir.h} from
7358 @file{configure} works well for this example. @file{bindir.h} will exist
7359 before you build any target, hence will not cause any dependency issue.
7361 The Makefile can be shrunk as follows. We do not even have to mention
7369 However, it's not always possible to build sources from
7370 @file{configure}, especially when these sources are generated by a tool
7371 that needs to be built first.
7373 @subsubheading Build @file{bindir.c}, not @file{bindir.h}.
7375 Another attractive idea is to define @code{bindir} as a variable or
7376 function exported from @file{bindir.o}, and build @file{bindir.c}
7377 instead of @file{bindir.h}.
7380 noinst_PROGRAMS = foo
7381 foo_SOURCES = foo.c bindir.h
7382 nodist_foo_SOURCES = bindir.c
7383 CLEANFILES = bindir.c
7385 echo 'const char bindir[] = "$(bindir)";' >$@@
7388 @file{bindir.h} contains just the variable's declaration and doesn't
7389 need to be built, so it won't cause any trouble. @file{bindir.o} is
7390 always dependent on @file{bindir.c}, so @file{bindir.c} will get built
7393 @subsubheading Which is best?
7395 There is no panacea, of course. Each solution has its merits and
7398 You cannot use @code{BUILT_SOURCES} if the ability to run @samp{make
7399 foo} on a clean tree is important to you.
7401 You won't add explicit dependencies if you are leery of overriding
7402 an Automake rule by mistake.
7404 Building files from @file{./configure} is not always possible, neither
7405 is converting @file{.h} files into @file{.c} files.
7408 @node Other GNU Tools
7409 @chapter Other GNU Tools
7411 Since Automake is primarily intended to generate @file{Makefile.in}s for
7412 use in GNU programs, it tries hard to interoperate with other GNU tools.
7415 * Emacs Lisp:: Emacs Lisp
7418 * Java:: Java bytecode compilation (deprecated)
7426 @cindex @code{_LISP} primary, defined
7427 @cindex @code{LISP} primary, defined
7428 @cindex Primary variable, @code{LISP}
7434 Automake provides some support for Emacs Lisp. The @code{LISP} primary
7435 is used to hold a list of @file{.el} files. Possible prefixes for this
7436 primary are @code{lisp_} and @code{noinst_}. Note that if
7437 @code{lisp_LISP} is defined, then @file{configure.ac} must run
7438 @code{AM_PATH_LISPDIR} (@pxref{Macros}).
7440 @vindex dist_lisp_LISP
7441 @vindex dist_noinst_LISP
7442 Lisp sources are not distributed by default. You can prefix the
7443 @code{LISP} primary with @code{dist_}, as in @code{dist_lisp_LISP} or
7444 @code{dist_noinst_LISP}, to indicate that these files should be
7447 Automake will byte-compile all Emacs Lisp source files using the Emacs
7448 found by @code{AM_PATH_LISPDIR}, if any was found.
7450 Byte-compiled Emacs Lisp files are not portable among all versions of
7451 Emacs, so it makes sense to turn this off if you expect sites to have
7452 more than one version of Emacs installed. Furthermore, many packages
7453 don't actually benefit from byte-compilation. Still, we recommend
7454 that you byte-compile your Emacs Lisp sources. It is probably better
7455 for sites with strange setups to cope for themselves than to make the
7456 installation less nice for everybody else.
7458 There are two ways to avoid byte-compiling. Historically, we have
7459 recommended the following construct.
7462 lisp_LISP = file1.el file2.el
7467 @code{ELCFILES} is an internal Automake variable that normally lists
7468 all @file{.elc} files that must be byte-compiled. Automake defines
7469 @code{ELCFILES} automatically from @code{lisp_LISP}. Emptying this
7470 variable explicitly prevents byte-compilation.
7472 Since Automake 1.8, we now recommend using @code{lisp_DATA} instead:
7474 @c Keep in sync with primary-prefix-couples-documented-valid.sh
7476 lisp_DATA = file1.el file2.el
7479 Note that these two constructs are not equivalent. @code{_LISP} will
7480 not install a file if Emacs is not installed, while @code{_DATA} will
7481 always install its files.
7486 @cindex GNU Gettext support
7487 @cindex Gettext support
7488 @cindex Support for GNU Gettext
7490 If @code{AM_GNU_GETTEXT} is seen in @file{configure.ac}, then Automake
7491 turns on support for GNU gettext, a message catalog system for
7492 internationalization
7493 (@pxref{Top, , Introduction, gettext, GNU gettext utilities}).
7495 The @code{gettext} support in Automake requires the addition of one or
7496 two subdirectories to the package: @file{po} and possibly also @file{intl}.
7497 The latter is needed if @code{AM_GNU_GETTEXT} is not invoked with the
7498 @samp{external} argument, or if @code{AM_GNU_GETTEXT_INTL_SUBDIR} is used.
7499 Automake ensures that these directories exist and are mentioned in
7505 Automake provides support for GNU Libtool (@pxref{Top, , Introduction,
7506 libtool, The Libtool Manual}) with the @code{LTLIBRARIES} primary.
7507 @xref{A Shared Library}.
7511 @section Java bytecode compilation (deprecated)
7513 @cindex @code{_JAVA} primary, defined
7514 @cindex @code{JAVA} primary, defined
7515 @cindex Primary variable, @code{JAVA}
7516 @cindex Java to bytecode, compilation
7517 @cindex Compilation of Java to bytecode
7519 Automake provides some minimal support for Java bytecode compilation with
7520 the @code{JAVA} primary (in addition to the support for compiling Java to
7521 native machine code; @pxref{Java Support with gcj}). Note however that
7522 @emph{the interface and most features described here are deprecated}; the
7523 next automake release will strive to provide a better and cleaner
7524 interface, which however @emph{won't be backward-compatible}; the present
7525 interface will probably be removed altogether in future automake releases
7526 (1.13 or later), so don't use it in new code.
7528 Any @file{.java} files listed in a @code{_JAVA} variable will be
7529 compiled with @code{JAVAC} at build time. By default, @file{.java}
7530 files are not included in the distribution, you should use the
7531 @code{dist_} prefix to distribute them.
7533 Here is a typical setup for distributing @file{.java} files and
7534 installing the @file{.class} files resulting from their compilation.
7536 @c Keep in sync with primary-prefix-couples-documented-valid.sh
7538 javadir = $(datadir)/java
7539 dist_java_JAVA = a.java b.java @dots{}
7542 @cindex @code{JAVA} restrictions
7543 @cindex Restrictions for @code{JAVA}
7545 Currently Automake enforces the restriction that only one @code{_JAVA}
7546 primary can be used in a given @file{Makefile.am}. The reason for this
7547 restriction is that, in general, it isn't possible to know which
7548 @file{.class} files were generated from which @file{.java} files, so
7549 it would be impossible to know which files to install where. For
7550 instance, a @file{.java} file can define multiple classes; the resulting
7551 @file{.class} file names cannot be predicted without parsing the
7554 There are a few variables that are used when compiling Java sources:
7558 The name of the Java compiler. This defaults to @samp{javac}.
7561 The flags to pass to the compiler. This is considered to be a user
7562 variable (@pxref{User Variables}).
7565 More flags to pass to the Java compiler. This, and not
7566 @code{JAVACFLAGS}, should be used when it is necessary to put Java
7567 compiler flags into @file{Makefile.am}.
7570 The value of this variable is passed to the @option{-d} option to
7571 @code{javac}. It defaults to @samp{$(top_builddir)}.
7574 This variable is a shell expression that is used to set the
7575 @env{CLASSPATH} environment variable on the @code{javac} command line.
7576 (In the future we will probably handle class path setting differently.)
7583 @cindex @code{_PYTHON} primary, defined
7584 @cindex @code{PYTHON} primary, defined
7585 @cindex Primary variable, @code{PYTHON}
7588 Automake provides support for Python compilation with the
7589 @code{PYTHON} primary. A typical setup is to call
7590 @code{AM_PATH_PYTHON} in @file{configure.ac} and use a line like the
7591 following in @file{Makefile.am}:
7594 python_PYTHON = tree.py leave.py
7597 Any files listed in a @code{_PYTHON} variable will be byte-compiled
7598 with @command{py-compile} at install time. @command{py-compile}
7599 actually creates both standard (@file{.pyc}) and optimized
7600 (@file{.pyo}) byte-compiled versions of the source files. Note that
7601 because byte-compilation occurs at install time, any files listed in
7602 @code{noinst_PYTHON} will not be compiled. Python source files are
7603 included in the distribution by default, prepend @code{nodist_} (as in
7604 @code{nodist_python_PYTHON}) to omit them.
7606 Automake ships with an Autoconf macro called @code{AM_PATH_PYTHON}
7607 that will determine some Python-related directory variables (see
7608 below). If you have called @code{AM_PATH_PYTHON} from
7609 @file{configure.ac}, then you may use the variables
7610 @c Keep in sync with primary-prefix-couples-documented-valid.sh
7611 @code{python_PYTHON} or @code{pkgpython_PYTHON} to list Python source
7612 files in your @file{Makefile.am}, depending on where you want your files
7613 installed (see the definitions of @code{pythondir} and
7614 @code{pkgpythondir} below).
7616 @defmac AM_PATH_PYTHON (@ovar{version}, @ovar{action-if-found},
7617 @ovar{action-if-not-found})
7619 Search for a Python interpreter on the system. This macro takes three
7620 optional arguments. The first argument, if present, is the minimum
7621 version of Python required for this package: @code{AM_PATH_PYTHON}
7622 will skip any Python interpreter that is older than @var{version}.
7623 If an interpreter is found and satisfies @var{version}, then
7624 @var{action-if-found} is run. Otherwise, @var{action-if-not-found} is
7627 If @var{action-if-not-found} is not specified, as in the following
7628 example, the default is to abort @command{configure}.
7631 AM_PATH_PYTHON([2.2])
7635 This is fine when Python is an absolute requirement for the package.
7636 If Python >= 2.5 was only @emph{optional} to the package,
7637 @code{AM_PATH_PYTHON} could be called as follows.
7640 AM_PATH_PYTHON([2.5],, [:])
7643 If the @env{PYTHON} variable is set when @code{AM_PATH_PYTHON} is
7644 called, then that will be the only Python interpreter that is tried.
7646 @code{AM_PATH_PYTHON} creates the following output variables based on
7647 the Python installation found during configuration.
7652 The name of the Python executable, or @samp{:} if no suitable
7653 interpreter could be found.
7655 Assuming @var{action-if-not-found} is used (otherwise @file{./configure}
7656 will abort if Python is absent), the value of @code{PYTHON} can be used
7657 to setup a conditional in order to disable the relevant part of a build
7661 AM_PATH_PYTHON(,, [:])
7662 AM_CONDITIONAL([HAVE_PYTHON], [test "$PYTHON" != :])
7665 @item PYTHON_VERSION
7666 The Python version number, in the form @var{major}.@var{minor}
7667 (e.g., @samp{2.5}). This is currently the value of
7668 @samp{sys.version[:3]}.
7671 The string @samp{$@{prefix@}}. This term may be used in future work
7672 that needs the contents of Python's @samp{sys.prefix}, but general
7673 consensus is to always use the value from @command{configure}.
7675 @item PYTHON_EXEC_PREFIX
7676 The string @samp{$@{exec_prefix@}}. This term may be used in future work
7677 that needs the contents of Python's @samp{sys.exec_prefix}, but general
7678 consensus is to always use the value from @command{configure}.
7680 @item PYTHON_PLATFORM
7681 The canonical name used by Python to describe the operating system, as
7682 given by @samp{sys.platform}. This value is sometimes needed when
7683 building Python extensions.
7686 The directory name for the @file{site-packages} subdirectory of the
7687 standard Python install tree.
7690 This is the directory under @code{pythondir} that is named after the
7691 package. That is, it is @samp{$(pythondir)/$(PACKAGE)}. It is provided
7695 This is the directory where Python extension modules (shared libraries)
7696 should be installed. An extension module written in C could be declared
7697 as follows to Automake:
7699 @c Keep in sync with primary-prefix-couples-documented-valid.sh
7701 pyexec_LTLIBRARIES = quaternion.la
7702 quaternion_la_SOURCES = quaternion.c support.c support.h
7703 quaternion_la_LDFLAGS = -avoid-version -module
7707 This is a convenience variable that is defined as
7708 @samp{$(pyexecdir)/$(PACKAGE)}.
7711 All these directory variables have values that start with either
7712 @samp{$@{prefix@}} or @samp{$@{exec_prefix@}} unexpanded. This works
7713 fine in @file{Makefiles}, but it makes these variables hard to use in
7714 @file{configure}. This is mandated by the GNU coding standards, so
7715 that the user can run @samp{make prefix=/foo install}. The Autoconf
7716 manual has a section with more details on this topic
7717 (@pxref{Installation Directory Variables, , Installation Directory
7718 Variables, autoconf, The Autoconf Manual}). See also @ref{Hard-Coded
7723 @chapter Building documentation
7725 Currently Automake provides support for Texinfo and man pages.
7729 * Man Pages:: Man pages
7736 @cindex @code{_TEXINFOS} primary, defined
7737 @cindex @code{TEXINFOS} primary, defined
7738 @cindex Primary variable, @code{TEXINFOS}
7739 @cindex HTML output using Texinfo
7740 @cindex PDF output using Texinfo
7741 @cindex PS output using Texinfo
7742 @cindex DVI output using Texinfo
7744 @vindex info_TEXINFOS
7746 If the current directory contains Texinfo source, you must declare it
7747 with the @code{TEXINFOS} primary. Generally Texinfo files are converted
7748 into info, and thus the @code{info_TEXINFOS} variable is most commonly used
7749 here. Any Texinfo source file must end in the @file{.texi},
7750 @file{.txi}, or @file{.texinfo} extension. We recommend @file{.texi}
7753 Automake generates rules to build @file{.info}, @file{.dvi},
7754 @file{.ps}, @file{.pdf} and @file{.html} files from your Texinfo
7755 sources. Following the GNU Coding Standards, only the @file{.info}
7756 files are built by @samp{make all} and installed by @samp{make
7757 install} (unless you use @option{no-installinfo}, see below).
7758 Furthermore, @file{.info} files are automatically distributed so that
7759 Texinfo is not a prerequisite for installing your package.
7765 @trindex install-dvi
7766 @trindex install-html
7767 @trindex install-pdf
7769 Other documentation formats can be built on request by @samp{make
7770 dvi}, @samp{make ps}, @samp{make pdf} and @samp{make html}, and they
7771 can be installed with @samp{make install-dvi}, @samp{make install-ps},
7772 @samp{make install-pdf} and @samp{make install-html} explicitly.
7773 @samp{make uninstall} will remove everything: the Texinfo
7774 documentation installed by default as well as all the above optional
7777 All these targets can be extended using @samp{-local} rules
7778 (@pxref{Extending}).
7780 @cindex Texinfo flag, @code{VERSION}
7781 @cindex Texinfo flag, @code{UPDATED}
7782 @cindex Texinfo flag, @code{EDITION}
7783 @cindex Texinfo flag, @code{UPDATED-MONTH}
7785 @cindex @code{VERSION} Texinfo flag
7786 @cindex @code{UPDATED} Texinfo flag
7787 @cindex @code{EDITION} Texinfo flag
7788 @cindex @code{UPDATED-MONTH} Texinfo flag
7790 @cindex @file{mdate-sh}
7792 If the @file{.texi} file @code{@@include}s @file{version.texi}, then
7793 that file will be automatically generated. The file @file{version.texi}
7794 defines four Texinfo flag you can reference using
7795 @code{@@value@{EDITION@}}, @code{@@value@{VERSION@}},
7796 @code{@@value@{UPDATED@}}, and @code{@@value@{UPDATED-MONTH@}}.
7801 Both of these flags hold the version number of your program. They are
7802 kept separate for clarity.
7805 This holds the date the primary @file{.texi} file was last modified.
7808 This holds the name of the month in which the primary @file{.texi} file
7812 The @file{version.texi} support requires the @command{mdate-sh}
7813 script; this script is supplied with Automake and automatically
7814 included when @command{automake} is invoked with the
7815 @option{--add-missing} option.
7817 If you have multiple Texinfo files, and you want to use the
7818 @file{version.texi} feature, then you have to have a separate version
7819 file for each Texinfo file. Automake will treat any include in a
7820 Texinfo file that matches @file{vers*.texi} just as an automatically
7821 generated version file.
7823 Sometimes an info file actually depends on more than one @file{.texi}
7824 file. For instance, in GNU Hello, @file{hello.texi} includes the file
7825 @file{fdl.texi}. You can tell Automake about these dependencies using
7826 the @code{@var{texi}_TEXINFOS} variable. Here is how GNU Hello does it:
7831 info_TEXINFOS = hello.texi
7832 hello_TEXINFOS = fdl.texi
7835 @cindex @file{texinfo.tex}
7837 By default, Automake requires the file @file{texinfo.tex} to appear in
7838 the same directory as the @file{Makefile.am} file that lists the
7839 @file{.texi} files. If you used @code{AC_CONFIG_AUX_DIR} in
7840 @file{configure.ac} (@pxref{Input, , Finding `configure' Input,
7841 autoconf, The Autoconf Manual}), then @file{texinfo.tex} is looked for
7842 there. In both cases, @command{automake} then supplies @file{texinfo.tex} if
7843 @option{--add-missing} is given, and takes care of its distribution.
7844 However, if you set the @code{TEXINFO_TEX} variable (see below),
7845 it overrides the location of the file and turns off its installation
7846 into the source as well as its distribution.
7848 The option @option{no-texinfo.tex} can be used to eliminate the
7849 requirement for the file @file{texinfo.tex}. Use of the variable
7850 @code{TEXINFO_TEX} is preferable, however, because that allows the
7851 @code{dvi}, @code{ps}, and @code{pdf} targets to still work.
7853 @cindex Option, @code{no-installinfo}
7854 @cindex Target, @code{install-info}
7855 @cindex @code{install-info} target
7856 @cindex @code{no-installinfo} option
7858 @opindex no-installinfo
7859 @trindex install-info
7861 Automake generates an @code{install-info} rule; some people apparently
7862 use this. By default, info pages are installed by @samp{make
7863 install}, so running @code{make install-info} is pointless. This can
7864 be prevented via the @code{no-installinfo} option. In this case,
7865 @file{.info} files are not installed by default, and user must
7866 request this explicitly using @samp{make install-info}.
7868 @vindex AM_UPDATE_INFO_DIR
7869 By default, @code{make install-info} and @code{make install-info}
7870 will try to run the @command{install-info} program (if available)
7871 to update (or create) the @file{@code{$@{infodir@}}/dir} index.
7872 If this is undesired, it can be prevented by exporting the
7873 @code{AM_UPDATE_INFO_DIR} variable to "@code{no}".
7875 The following variables are used by the Texinfo build rules.
7879 The name of the program invoked to build @file{.info} files. This
7880 variable is defined by Automake. If the @command{makeinfo} program is
7881 found on the system then it will be used by default; otherwise
7882 @command{missing} will be used instead.
7885 The command invoked to build @file{.html} files. Automake
7886 defines this to @samp{$(MAKEINFO) --html}.
7889 User flags passed to each invocation of @samp{$(MAKEINFO)} and
7890 @samp{$(MAKEINFOHTML)}. This user variable (@pxref{User Variables}) is
7891 not expected to be defined in any @file{Makefile}; it can be used by
7892 users to pass extra flags to suit their needs.
7894 @item AM_MAKEINFOFLAGS
7895 @itemx AM_MAKEINFOHTMLFLAGS
7896 Maintainer flags passed to each @command{makeinfo} invocation. Unlike
7897 @code{MAKEINFOFLAGS}, these variables are meant to be defined by
7898 maintainers in @file{Makefile.am}. @samp{$(AM_MAKEINFOFLAGS)} is
7899 passed to @code{makeinfo} when building @file{.info} files; and
7900 @samp{$(AM_MAKEINFOHTMLFLAGS)} is used when building @file{.html}
7903 @c Keep in sync with txinfo21.sh
7904 For instance, the following setting can be used to obtain one single
7905 @file{.html} file per manual, without node separators.
7907 AM_MAKEINFOHTMLFLAGS = --no-headers --no-split
7910 @code{AM_MAKEINFOHTMLFLAGS} defaults to @samp{$(AM_MAKEINFOFLAGS)}.
7911 This means that defining @code{AM_MAKEINFOFLAGS} without defining
7912 @code{AM_MAKEINFOHTMLFLAGS} will impact builds of both @file{.info}
7913 and @file{.html} files.
7916 The name of the command that converts a @file{.texi} file into a
7917 @file{.dvi} file. This defaults to @samp{texi2dvi}, a script that ships
7918 with the Texinfo package.
7921 The name of the command that translates a @file{.texi} file into a
7922 @file{.pdf} file. This defaults to @samp{$(TEXI2DVI) --pdf --batch}.
7925 The name of the command that builds a @file{.ps} file out of a
7926 @file{.dvi} file. This defaults to @samp{dvips}.
7930 If your package has Texinfo files in many directories, you can use the
7931 variable @code{TEXINFO_TEX} to tell Automake where to find the canonical
7932 @file{texinfo.tex} for your package. The value of this variable should
7933 be the relative path from the current @file{Makefile.am} to
7937 TEXINFO_TEX = ../doc/texinfo.tex
7945 @cindex @code{_MANS} primary, defined
7946 @cindex @code{MANS} primary, defined
7947 @cindex Primary variable, @code{MANS}
7951 A package can also include man pages (but see the GNU standards on this
7952 matter, @ref{Man Pages, , , standards, The GNU Coding Standards}.) Man
7953 pages are declared using the @code{MANS} primary. Generally the
7954 @code{man_MANS} variable is used. Man pages are automatically installed in
7955 the correct subdirectory of @code{mandir}, based on the file extension.
7957 File extensions such as @file{.1c} are handled by looking for the valid
7958 part of the extension and using that to determine the correct
7959 subdirectory of @code{mandir}. Valid section names are the digits
7960 @samp{0} through @samp{9}, and the letters @samp{l} and @samp{n}.
7962 Sometimes developers prefer to name a man page something like
7963 @file{foo.man} in the source, and then rename it to have the correct
7964 suffix, for example @file{foo.1}, when installing the file. Automake
7965 also supports this mode. For a valid section named @var{section},
7966 there is a corresponding directory named @samp{man@var{section}dir},
7967 and a corresponding @code{_MANS} variable. Files listed in such a
7968 variable are installed in the indicated section. If the file already
7969 has a valid suffix, then it is installed as-is; otherwise the file
7970 suffix is changed to match the section.
7972 For instance, consider this example:
7974 man1_MANS = rename.man thesame.1 alsothesame.1c
7978 In this case, @file{rename.man} will be renamed to @file{rename.1} when
7979 installed, but the other files will keep their names.
7981 @cindex Target, @code{install-man}
7982 @cindex Option, @option{no-installman}
7983 @cindex @code{install-man} target
7984 @cindex @option{no-installman} option
7985 @opindex no-installman
7986 @trindex install-man
7988 By default, man pages are installed by @samp{make install}. However,
7989 since the GNU project does not require man pages, many maintainers do
7990 not expend effort to keep the man pages up to date. In these cases, the
7991 @option{no-installman} option will prevent the man pages from being
7992 installed by default. The user can still explicitly install them via
7993 @samp{make install-man}.
7995 For fast installation, with many files it is preferable to use
7996 @samp{man@var{section}_MANS} over @samp{man_MANS} as well as files that
7997 do not need to be renamed.
7999 Man pages are not currently considered to be source, because it is not
8000 uncommon for man pages to be automatically generated. Therefore they
8001 are not automatically included in the distribution. However, this can
8002 be changed by use of the @code{dist_} prefix. For instance here is
8003 how to distribute and install the two man pages of GNU @command{cpio}
8004 (which includes both Texinfo documentation and man pages):
8007 dist_man_MANS = cpio.1 mt.1
8010 The @code{nobase_} prefix is meaningless for man pages and is
8014 @cindex @code{notrans_} prefix
8015 @cindex Man page renaming, avoiding
8016 @cindex Avoiding man page renaming
8018 Executables and manpages may be renamed upon installation
8019 (@pxref{Renaming}). For manpages this can be avoided by use of the
8020 @code{notrans_} prefix. For instance, suppose an executable @samp{foo}
8021 allowing to access a library function @samp{foo} from the command line.
8022 The way to avoid renaming of the @file{foo.3} manpage is:
8026 notrans_man_MANS = foo.3
8029 @cindex @code{notrans_} and @code{dist_} or @code{nodist_}
8030 @cindex @code{dist_} and @code{notrans_}
8031 @cindex @code{nodist_} and @code{notrans_}
8033 @samp{notrans_} must be specified first when used in conjunction with
8034 either @samp{dist_} or @samp{nodist_} (@pxref{Fine-grained Distribution
8035 Control}). For instance:
8038 notrans_dist_man3_MANS = bar.3
8042 @chapter What Gets Installed
8044 @cindex Installation support
8045 @cindex @samp{make install} support
8047 Naturally, Automake handles the details of actually installing your
8048 program once it has been built. All files named by the various
8049 primaries are automatically installed in the appropriate places when the
8050 user runs @samp{make install}.
8053 * Basics of Installation:: What gets installed where
8054 * The Two Parts of Install:: Installing data and programs separately
8055 * Extending Installation:: Adding your own rules for installation
8056 * Staged Installs:: Installation in a temporary location
8057 * Install Rules for the User:: Useful additional rules
8060 @node Basics of Installation
8061 @section Basics of Installation
8063 A file named in a primary is installed by copying the built file into
8064 the appropriate directory. The base name of the file is used when
8068 bin_PROGRAMS = hello subdir/goodbye
8071 In this example, both @samp{hello} and @samp{goodbye} will be installed
8072 in @samp{$(bindir)}.
8074 Sometimes it is useful to avoid the basename step at install time. For
8075 instance, you might have a number of header files in subdirectories of
8076 the source tree that are laid out precisely how you want to install
8077 them. In this situation you can use the @code{nobase_} prefix to
8078 suppress the base name step. For example:
8081 nobase_include_HEADERS = stdio.h sys/types.h
8085 will install @file{stdio.h} in @samp{$(includedir)} and @file{types.h}
8086 in @samp{$(includedir)/sys}.
8088 For most file types, Automake will install multiple files at once, while
8089 avoiding command line length issues (@pxref{Length Limitations}). Since
8090 some @command{install} programs will not install the same file twice in
8091 one invocation, you may need to ensure that file lists are unique within
8092 one variable such as @samp{nobase_include_HEADERS} above.
8094 You should not rely on the order in which files listed in one variable
8095 are installed. Likewise, to cater for parallel make, you should not
8096 rely on any particular file installation order even among different
8097 file types (library dependencies are an exception here).
8100 @node The Two Parts of Install
8101 @section The Two Parts of Install
8103 Automake generates separate @code{install-data} and @code{install-exec}
8104 rules, in case the installer is installing on multiple machines that
8105 share directory structure---these targets allow the machine-independent
8106 parts to be installed only once. @code{install-exec} installs
8107 platform-dependent files, and @code{install-data} installs
8108 platform-independent files. The @code{install} target depends on both
8109 of these targets. While Automake tries to automatically segregate
8110 objects into the correct category, the @file{Makefile.am} author is, in
8111 the end, responsible for making sure this is done correctly.
8112 @trindex install-data
8113 @trindex install-exec
8115 @cindex Install, two parts of
8117 Variables using the standard directory prefixes @samp{data},
8118 @samp{info}, @samp{man}, @samp{include}, @samp{oldinclude},
8119 @samp{pkgdata}, or @samp{pkginclude} are installed by
8120 @code{install-data}.
8122 Variables using the standard directory prefixes @samp{bin},
8123 @samp{sbin}, @samp{libexec}, @samp{sysconf}, @samp{localstate},
8124 @samp{lib}, or @samp{pkglib} are installed by @code{install-exec}.
8126 For instance, @code{data_DATA} files are installed by @code{install-data},
8127 while @code{bin_PROGRAMS} files are installed by @code{install-exec}.
8129 Any variable using a user-defined directory prefix with
8130 @samp{exec} in the name (e.g.,
8131 @c Keep in sync with primary-prefix-couples-documented-valid.sh
8132 @code{myexecbin_PROGRAMS}) is installed by @code{install-exec}. All
8133 other user-defined prefixes are installed by @code{install-data}.
8135 @node Extending Installation
8136 @section Extending Installation
8138 It is possible to extend this mechanism by defining an
8139 @code{install-exec-local} or @code{install-data-local} rule. If these
8140 rules exist, they will be run at @samp{make install} time. These
8141 rules can do almost anything; care is required.
8142 @trindex install-exec-local
8143 @trindex install-data-local
8145 Automake also supports two install hooks, @code{install-exec-hook} and
8146 @code{install-data-hook}. These hooks are run after all other install
8147 rules of the appropriate type, exec or data, have completed. So, for
8148 instance, it is possible to perform post-installation modifications
8149 using an install hook. @xref{Extending}, for some examples.
8150 @cindex Install hook
8152 @node Staged Installs
8153 @section Staged Installs
8156 Automake generates support for the @code{DESTDIR} variable in all
8157 install rules. @code{DESTDIR} is used during the @samp{make install}
8158 step to relocate install objects into a staging area. Each object and
8159 path is prefixed with the value of @code{DESTDIR} before being copied
8160 into the install area. Here is an example of typical DESTDIR usage:
8163 mkdir /tmp/staging &&
8164 make DESTDIR=/tmp/staging install
8167 The @command{mkdir} command avoids a security problem if the attacker
8168 creates a symbolic link from @file{/tmp/staging} to a victim area;
8169 then @command{make} places install objects in a directory tree built under
8170 @file{/tmp/staging}. If @file{/gnu/bin/foo} and
8171 @file{/gnu/share/aclocal/foo.m4} are to be installed, the above command
8172 would install @file{/tmp/staging/gnu/bin/foo} and
8173 @file{/tmp/staging/gnu/share/aclocal/foo.m4}.
8175 This feature is commonly used to build install images and packages
8178 Support for @code{DESTDIR} is implemented by coding it directly into
8179 the install rules. If your @file{Makefile.am} uses a local install
8180 rule (e.g., @code{install-exec-local}) or an install hook, then you
8181 must write that code to respect @code{DESTDIR}.
8183 @xref{Makefile Conventions, , , standards, The GNU Coding Standards},
8184 for another usage example.
8186 @node Install Rules for the User
8187 @section Install Rules for the User
8189 Automake also generates rules for targets @code{uninstall},
8190 @code{installdirs}, and @code{install-strip}.
8192 @trindex installdirs
8193 @trindex install-strip
8195 Automake supports @code{uninstall-local} and @code{uninstall-hook}.
8196 There is no notion of separate uninstalls for ``exec'' and ``data'', as
8197 these features would not provide additional functionality.
8199 Note that @code{uninstall} is not meant as a replacement for a real
8204 @chapter What Gets Cleaned
8206 @cindex @samp{make clean} support
8208 The GNU Makefile Standards specify a number of different clean rules.
8209 @xref{Standard Targets, , Standard Targets for Users, standards,
8210 The GNU Coding Standards}.
8212 Generally the files that can be cleaned are determined automatically by
8213 Automake. Of course, Automake also recognizes some variables that can
8214 be defined to specify additional files to clean. These variables are
8215 @code{MOSTLYCLEANFILES}, @code{CLEANFILES}, @code{DISTCLEANFILES}, and
8216 @code{MAINTAINERCLEANFILES}.
8217 @vindex MOSTLYCLEANFILES
8219 @vindex DISTCLEANFILES
8220 @vindex MAINTAINERCLEANFILES
8222 @trindex mostlyclean-local
8223 @trindex clean-local
8224 @trindex distclean-local
8225 @trindex maintainer-clean-local
8226 When cleaning involves more than deleting some hard-coded list of
8227 files, it is also possible to supplement the cleaning rules with your
8228 own commands. Simply define a rule for any of the
8229 @code{mostlyclean-local}, @code{clean-local}, @code{distclean-local},
8230 or @code{maintainer-clean-local} targets (@pxref{Extending}). A common
8231 case is deleting a directory, for instance, a directory created by the
8239 Since @command{make} allows only one set of rules for a given target,
8240 a more extensible way of writing this is to use a separate target
8241 listed as a dependency:
8244 clean-local: clean-local-check
8245 .PHONY: clean-local-check
8250 As the GNU Standards aren't always explicit as to which files should
8251 be removed by which rule, we've adopted a heuristic that we believe
8252 was first formulated by Fran@,{c}ois Pinard:
8256 If @command{make} built it, and it is commonly something that one would
8257 want to rebuild (for instance, a @file{.o} file), then
8258 @code{mostlyclean} should delete it.
8261 Otherwise, if @command{make} built it, then @code{clean} should delete it.
8264 If @command{configure} built it, then @code{distclean} should delete it.
8267 If the maintainer built it (for instance, a @file{.info} file), then
8268 @code{maintainer-clean} should delete it. However
8269 @code{maintainer-clean} should not delete anything that needs to exist
8270 in order to run @samp{./configure && make}.
8273 We recommend that you follow this same set of heuristics in your
8278 @chapter What Goes in a Distribution
8281 * Basics of Distribution:: Files distributed by default
8282 * Fine-grained Distribution Control:: @code{dist_} and @code{nodist_} prefixes
8283 * The dist Hook:: A target for last-minute distribution changes
8284 * Checking the Distribution:: @samp{make distcheck} explained
8285 * The Types of Distributions:: A variety of formats and compression methods
8288 @node Basics of Distribution
8289 @section Basics of Distribution
8291 @cindex @samp{make dist}
8296 The @code{dist} rule in the generated @file{Makefile.in} can be used
8297 to generate a gzipped @code{tar} file and other flavors of archive for
8298 distribution. The file is named based on the @code{PACKAGE} and
8299 @code{VERSION} variables defined by @code{AM_INIT_AUTOMAKE}
8300 (@pxref{Macros}); more precisely the gzipped @code{tar} file is named
8301 @samp{@var{package}-@var{version}.tar.gz}.
8303 You can use the @command{make} variable @code{GZIP_ENV} to control how gzip
8304 is run. The default setting is @option{--best}.
8306 @cindex @code{m4_include}, distribution
8307 @cindex @code{include}, distribution
8310 For the most part, the files to distribute are automatically found by
8311 Automake: all source files are automatically included in a distribution,
8312 as are all @file{Makefile.am} and @file{Makefile.in} files. Automake also
8313 has a built-in list of commonly used files that are automatically
8314 included if they are found in the current directory (either physically,
8315 or as the target of a @file{Makefile.am} rule); this list is printed by
8316 @samp{automake --help}. Note that some files in this list are actually
8317 distributed only if other certain conditions hold (for example,
8318 @c Keep in sync with autodist-config-headers.sh
8319 the @file{config.h.top} and @file{config.h.bot} files are automatically
8320 distributed only if, e.g., @samp{AC_CONFIG_HEADERS([config.h])} is used
8321 in @file{configure.ac}). Also, files that are read by @command{configure}
8322 (i.e.@: the source files corresponding to the files specified in various
8323 Autoconf macros such as @code{AC_CONFIG_FILES} and siblings) are
8324 automatically distributed. Files included in a @file{Makefile.am} (using
8325 @code{include}) or in @file{configure.ac} (using @code{m4_include}), and
8326 helper scripts installed with @samp{automake --add-missing} are also
8330 Still, sometimes there are files that must be distributed, but which
8331 are not covered in the automatic rules. These files should be listed in
8332 the @code{EXTRA_DIST} variable. You can mention files from
8333 subdirectories in @code{EXTRA_DIST}.
8335 You can also mention a directory in @code{EXTRA_DIST}; in this case the
8336 entire directory will be recursively copied into the distribution.
8337 Please note that this will also copy @emph{everything} in the directory,
8338 including, e.g., Subversion's @file{.svn} private directories or CVS/RCS
8339 version control files. We recommend against using this feature.
8342 @vindex DIST_SUBDIRS
8343 If you define @code{SUBDIRS}, Automake will recursively include the
8344 subdirectories in the distribution. If @code{SUBDIRS} is defined
8345 conditionally (@pxref{Conditionals}), Automake will normally include
8346 all directories that could possibly appear in @code{SUBDIRS} in the
8347 distribution. If you need to specify the set of directories
8348 conditionally, you can set the variable @code{DIST_SUBDIRS} to the
8349 exact list of subdirectories to include in the distribution
8350 (@pxref{Conditional Subdirectories}).
8353 @node Fine-grained Distribution Control
8354 @section Fine-grained Distribution Control
8358 Sometimes you need tighter control over what does @emph{not} go into the
8359 distribution; for instance, you might have source files that are
8360 generated and that you do not want to distribute. In this case
8361 Automake gives fine-grained control using the @code{dist} and
8362 @code{nodist} prefixes. Any primary or @code{_SOURCES} variable can be
8363 prefixed with @code{dist_} to add the listed files to the distribution.
8364 Similarly, @code{nodist_} can be used to omit the files from the
8367 As an example, here is how you would cause some data to be distributed
8368 while leaving some source code out of the distribution:
8371 dist_data_DATA = distribute-this
8373 nodist_foo_SOURCES = do-not-distribute.c
8377 @section The dist Hook
8381 Occasionally it is useful to be able to change the distribution before
8382 it is packaged up. If the @code{dist-hook} rule exists, it is run
8383 after the distribution directory is filled, but before the actual
8384 distribution archives are created. One way to use this is for
8385 removing unnecessary files that get recursively included by specifying
8386 a directory in @code{EXTRA_DIST}:
8391 rm -rf `find $(distdir)/doc -type d -name .svn`
8394 @c The caveates described here should be documented in 'disthook.test'.
8396 Note that the @code{dist-hook} recipe shouldn't assume that the regular
8397 files in the distribution directory are writable; this might not be the
8398 case if one is packaging from a read-only source tree, or when a
8399 @code{make distcheck} is being done. For similar reasons, the recipe
8400 shouldn't assume that the subdirectories put into the distribution
8401 directory as effect of having them listed in @code{EXTRA_DIST} are
8402 writable. So, if the @code{dist-hook} recipe wants to modify the
8403 content of an existing file (or @code{EXTRA_DIST} subdirectory) in the
8404 distribution directory, it should explicitly to make it writable first:
8407 EXTRA_DIST = README doc
8409 chmod u+w $(distdir)/README $(distdir)/doc
8410 echo "Distribution date: `date`" >> README
8411 rm -f $(distdir)/doc/HACKING
8416 Two variables that come handy when writing @code{dist-hook} rules are
8417 @samp{$(distdir)} and @samp{$(top_distdir)}.
8419 @samp{$(distdir)} points to the directory where the @code{dist} rule
8420 will copy files from the current directory before creating the
8421 tarball. If you are at the top-level directory, then @samp{distdir =
8422 $(PACKAGE)-$(VERSION)}. When used from subdirectory named
8423 @file{foo/}, then @samp{distdir = ../$(PACKAGE)-$(VERSION)/foo}.
8424 @samp{$(distdir)} can be a relative or absolute path, do not assume
8427 @samp{$(top_distdir)} always points to the root directory of the
8428 distributed tree. At the top-level it's equal to @samp{$(distdir)}.
8429 In the @file{foo/} subdirectory
8430 @samp{top_distdir = ../$(PACKAGE)-$(VERSION)}.
8431 @samp{$(top_distdir)} too can be a relative or absolute path.
8433 Note that when packages are nested using @code{AC_CONFIG_SUBDIRS}
8434 (@pxref{Subpackages}), then @samp{$(distdir)} and
8435 @samp{$(top_distdir)} are relative to the package where @samp{make
8436 dist} was run, not to any sub-packages involved.
8438 @node Checking the Distribution
8439 @section Checking the Distribution
8441 @cindex @samp{make distcheck}
8443 Automake also generates a @code{distcheck} rule that can be of help
8444 to ensure that a given distribution will actually work. Simplifying
8445 a bit, we can say this rule first makes a distribution, and then,
8446 @emph{operating from it}, takes the following steps:
8449 tries to do a @code{VPATH} build (@pxref{VPATH Builds}), with the
8450 @code{srcdir} and all its content made @emph{read-only};
8452 runs the test suite (with @command{make check}) on this fresh build;
8454 installs the package in a temporary directory (with @command{make
8455 install}), and tries runs the test suite on the resulting installation
8456 (with @command{make installcheck});
8458 checks that the package can be correctly uninstalled (by @command{make
8459 uninstall}) and cleaned (by @code{make distclean});
8461 finally, makes another tarball to ensure the distribution is
8465 @vindex AM_DISTCHECK_CONFIGURE_FLAGS
8466 @vindex DISTCHECK_CONFIGURE_FLAGS
8467 @subheading DISTCHECK_CONFIGURE_FLAGS
8468 Building the package involves running @samp{./configure}. If you need
8469 to supply additional flags to @command{configure}, define them in the
8470 @code{AM_DISTCHECK_CONFIGURE_FLAGS} variable in your top-level
8471 @file{Makefile.am}. The user can still extend or override the flags
8472 provided there by defining the @code{DISTCHECK_CONFIGURE_FLAGS} variable,
8473 on the command line when invoking @command{make}.
8475 Still, developers are encouraged to strive to make their code buildable
8476 without requiring any special configure option; thus, in general, you
8477 shouldn't define @code{AM_DISTCHECK_CONFIGURE_FLAGS}. However, there
8478 might be few scenarios in which the use of this variable is justified.
8479 GNU @command{m4} offers an example. GNU @command{m4} configures by
8480 default with its experimental and seldom used "changeword" feature
8481 disabled; so in its case it is useful to have @command{make distcheck}
8482 run configure with the @option{--with-changeword} option, to ensure that
8483 the code for changeword support still compiles correctly.
8484 GNU @command{m4} also employs the @code{AM_DISTCHECK_CONFIGURE_FLAGS}
8485 variable to stress-test the use of @option{--program-prefix=g}, since at
8486 one point the @command{m4} build system had a bug where @command{make
8487 installcheck} was wrongly assuming it could blindly test "@command{m4}",
8488 rather than the just-installed "@command{gm4}".
8490 @trindex distcheck-hook
8491 @subheading distcheck-hook
8492 If the @code{distcheck-hook} rule is defined in your top-level
8493 @file{Makefile.am}, then it will be invoked by @code{distcheck} after
8494 the new distribution has been unpacked, but before the unpacked copy
8495 is configured and built. Your @code{distcheck-hook} can do almost
8496 anything, though as always caution is advised. Generally this hook is
8497 used to check for potential distribution errors not caught by the
8498 standard mechanism. Note that @code{distcheck-hook} as well as
8499 @code{AM_DISTCHECK_CONFIGURE_FLAGS} and @code{DISTCHECK_CONFIGURE_FLAGS}
8500 are not honored in a subpackage @file{Makefile.am}, but the flags from
8501 @code{AM_DISTCHECK_CONFIGURE_FLAGS} and @code{DISTCHECK_CONFIGURE_FLAGS}
8502 are passed down to the @command{configure} script of the subpackage.
8504 @cindex @samp{make distcleancheck}
8505 @trindex distcleancheck
8506 @vindex DISTCLEANFILES
8507 @vindex distcleancheck_listfiles
8509 @subheading distcleancheck
8510 Speaking of potential distribution errors, @code{distcheck} also
8511 ensures that the @code{distclean} rule actually removes all built
8512 files. This is done by running @samp{make distcleancheck} at the end of
8513 the @code{VPATH} build. By default, @code{distcleancheck} will run
8514 @code{distclean} and then make sure the build tree has been emptied by
8515 running @samp{$(distcleancheck_listfiles)}. Usually this check will
8516 find generated files that you forgot to add to the @code{DISTCLEANFILES}
8517 variable (@pxref{Clean}).
8519 The @code{distcleancheck} behavior should be OK for most packages,
8520 otherwise you have the possibility to override the definition of
8521 either the @code{distcleancheck} rule, or the
8522 @samp{$(distcleancheck_listfiles)} variable. For instance, to disable
8523 @code{distcleancheck} completely, add the following rule to your
8524 top-level @file{Makefile.am}:
8531 If you want @code{distcleancheck} to ignore built files that have not
8532 been cleaned because they are also part of the distribution, add the
8533 following definition instead:
8535 @c Keep in sync with distcleancheck.sh
8537 distcleancheck_listfiles = \
8538 find . -type f -exec sh -c 'test -f $(srcdir)/$$1 || echo $$1' \
8542 The above definition is not the default because it's usually an error if
8543 your Makefiles cause some distributed files to be rebuilt when the user
8544 build the package. (Think about the user missing the tool required to
8545 build the file; or if the required tool is built by your package,
8546 consider the cross-compilation case where it can't be run.) There is
8547 an entry in the FAQ about this (@pxref{Errors with distclean}), make
8548 sure you read it before playing with @code{distcleancheck_listfiles}.
8550 @cindex @samp{make distuninstallcheck}
8551 @trindex distuninstallcheck
8552 @vindex distuninstallcheck_listfiles
8554 @subheading distuninstallcheck
8555 @code{distcheck} also checks that the @code{uninstall} rule works
8556 properly, both for ordinary and @code{DESTDIR} builds. It does this
8557 by invoking @samp{make uninstall}, and then it checks the install tree
8558 to see if any files are left over. This check will make sure that you
8559 correctly coded your @code{uninstall}-related rules.
8561 By default, the checking is done by the @code{distuninstallcheck} rule,
8562 and the list of files in the install tree is generated by
8563 @samp{$(distuninstallcheck_listfiles)} (this is a variable whose value is
8564 a shell command to run that prints the list of files to stdout).
8566 Either of these can be overridden to modify the behavior of
8567 @code{distcheck}. For instance, to disable this check completely, you
8575 @node The Types of Distributions
8576 @section The Types of Distributions
8578 Automake generates rules to provide archives of the project for
8579 distributions in various formats. Their targets are:
8583 @item @code{dist-bzip2}
8584 Generate a bzip2 tar archive of the distribution. bzip2 archives are
8585 frequently smaller than gzipped archives.
8586 By default, this rule makes @samp{bzip2} use a compression option of @option{-9}.
8587 To make it use a different one, set the @env{BZIP2} environment variable.
8588 For example, @samp{make dist-bzip2 BZIP2=-7}.
8591 @item @code{dist-gzip}
8592 Generate a gzip tar archive of the distribution.
8595 @item @code{dist-lzip}
8596 Generate an @samp{lzip} tar archive of the distribution. @command{lzip}
8597 archives are frequently smaller than @command{bzip2}-compressed archives.
8600 @item @code{dist-shar}
8601 Generate a shar archive of the distribution.
8605 @item @code{dist-xz}
8606 Generate an @samp{xz} tar archive of the distribution. @command{xz}
8607 archives are frequently smaller than @command{bzip2}-compressed archives.
8608 By default, this rule makes @samp{xz} use a compression option of
8609 @option{-e}. To make it use a different one, set the @env{XZ_OPT}
8610 environment variable. For example, run this command to use the
8611 default compression ratio, but with a progress indicator:
8612 @samp{make dist-xz XZ_OPT=-7e}.
8615 @item @code{dist-zip}
8616 Generate a zip archive of the distribution.
8619 @item @code{dist-tarZ}
8620 Generate a compressed tar archive of
8625 The rule @code{dist} (and its historical synonym @code{dist-all}) will
8626 create archives in all the enabled formats, @ref{Options}. By
8627 default, only the @code{dist-gzip} target is hooked to @code{dist}.
8631 @chapter Support for test suites
8634 @cindex @code{make check}
8637 Automake can generate code to handle two kinds of test suites. One is
8638 based on integration with the @command{dejagnu} framework. The other
8639 (and most used) form is based on the use of generic test scripts, and
8640 its activation is triggered by the definition of the special @code{TESTS}
8641 variable. This second form allows for various degrees of sophistication
8642 and customization; in particular, it allows for concurrent execution
8643 of test scripts, use of established test protocols such as TAP, and
8644 definition of custom test drivers and test runners.
8647 In either case, the testsuite is invoked via @samp{make check}.
8650 * Generalities about Testing:: Concepts and terminology about testing
8651 * Simple Tests:: Listing test scripts in @code{TESTS}
8652 * Custom Test Drivers:: Writing and using custom test drivers
8653 * Using the TAP test protocol:: Integrating test scripts that use the TAP protocol
8654 * DejaGnu Tests:: Interfacing with the @command{dejagnu} testing framework
8655 * Install Tests:: Running tests on installed packages
8658 @node Generalities about Testing
8659 @section Generalities about Testing
8661 The purpose of testing is to determine whether a program or system behaves
8662 as expected (e.g., known inputs produce the expected outputs, error
8663 conditions are correctly handled or reported, and older bugs do not
8667 The minimal unit of testing is usually called @emph{test case}, or simply
8668 @emph{test}. How a test case is defined or delimited, and even what
8669 exactly @emph{constitutes} a test case, depends heavily on the testing
8670 paradigm and/or framework in use, so we won't attempt any more precise
8671 definition. The set of the test cases for a given program or system
8672 constitutes its @emph{testsuite}.
8674 @cindex test harness
8675 @cindex testsuite harness
8676 A @emph{test harness} (also @emph{testsuite harness}) is a program or
8677 software component that executes all (or part of) the defined test cases,
8678 analyzes their outcomes, and report or register these outcomes
8679 appropriately. Again, the details of how this is accomplished (and how
8680 the developer and user can influence it or interface with it) varies
8681 wildly, and we'll attempt no precise definition.
8684 @cindex test failure
8685 A test is said to @emph{pass} when it can determine that the condition or
8686 behaviour it means to verify holds, and is said to @emph{fail} when it can
8687 determine that such condition of behaviour does @emph{not} hold.
8690 Sometimes, tests can rely on non-portable tools or prerequisites, or
8691 simply make no sense on a given system (for example, a test checking a
8692 Windows-specific feature makes no sense on a GNU/Linux system). In this
8693 case, accordingly to the definition above, the tests can neither be
8694 considered passed nor failed; instead, they are @emph{skipped} -- i.e.,
8695 they are not run, or their result is anyway ignored for what concerns
8696 the count of failures an successes. Skips are usually explicitly
8697 reported though, so that the user will be aware that not all of the
8698 testsuite has really run.
8701 @cindex expected failure
8702 @cindex expected test failure
8704 @cindex unexpected pass
8705 @cindex unexpected test pass
8706 It's not uncommon, especially during early development stages, that some
8707 tests fail for known reasons, and that the developer doesn't want to
8708 tackle these failures immediately (this is especially true when the
8709 failing tests deal with corner cases). In this situation, the better
8710 policy is to declare that each of those failures is an @emph{expected
8711 failure} (or @emph{xfail}). In case a test that is expected to fail ends
8712 up passing instead, many testing environments will flag the result as a
8713 special kind of failure called @emph{unexpected pass} (or @emph{xpass}).
8716 @cindex Distinction between errors and failures in testsuites
8717 Many testing environments and frameworks distinguish between test failures
8718 and hard errors. As we've seen, a test failure happens when some invariant
8719 or expected behaviour of the software under test is not met. An @emph{hard
8720 error} happens when e.g., the set-up of a test case scenario fails, or when
8721 some other unexpected or highly undesirable condition is encountered (for
8722 example, the program under test experiences a segmentation fault).
8724 @emph{TODO}: Links to other test harnesses (esp. those sharing our
8728 @section Simple Tests
8731 * Scripts-based Testsuites:: Automake-specific concepts and terminology
8732 * Serial Test Harness:: Older (and obsolescent) serial test harness
8733 * Parallel Test Harness:: Generic concurrent test harness
8736 @node Scripts-based Testsuites
8737 @subsection Scripts-based Testsuites
8739 If the special variable @code{TESTS} is defined, its value is taken to be
8740 a list of programs or scripts to run in order to do the testing. Under
8741 the appropriate circumstances, it's possible for @code{TESTS} to list
8742 also data files to be passed to one or more test scripts defined by
8743 different means (the so-called ``log compilers'', @pxref{Parallel Test
8746 Test scripts can be executed serially or concurrently. Automake
8747 supports both these kinds of test execution, with the serial test harness
8748 being the default (for backward-compatibility reasons only, as its use
8749 is nowadays discouraged). The concurrent test harness relies on the
8750 concurrence capabilities (if any) offered by the underlying @command{make}
8751 implementation, and can thus only be as good as those are.
8753 By default, only the exit statuses of the test scripts are considered when
8754 determining the testsuite outcome. But Automake allows also the use of
8755 more complex test protocols, either standard (@pxref{Using the TAP test
8756 protocol}) or custom (@pxref{Custom Test Drivers}). Note that you can
8757 enable such protocols only when the parallel harness is used: they won't
8758 work with the serial test harness. In the rest of this section we are
8759 going to concentrate mostly on protocol-less tests, since we'll have later
8760 a whole section devoted to the use of test protocols (again, @pxref{Custom
8763 @cindex Exit status 77, special interpretation
8764 @cindex Exit status 99, special interpretation
8765 When no test protocol is in use, an exit status of 0 from a test script will
8766 denote a success, an exit status of 77 a skipped test, an exit status of 99
8767 an hard error, and any other exit status will denote a failure.
8769 @cindex Tests, expected failure
8770 @cindex Expected test failure
8772 @vindex DISABLE_HARD_ERRORS
8773 @cindex Disabling hard errors
8774 You may define the variable @code{XFAIL_TESTS} to a list of tests
8775 (usually a subset of @code{TESTS}) that are expected to fail; this will
8776 effectively reverse the result of those tests (with the provision that
8777 skips and hard errors remain untouched). You may also instruct the
8778 testsuite harness to treat hard errors like simple failures, by defining
8779 the @code{DISABLE_HARD_ERRORS} make variable to a nonempty value.
8781 Note however that, for tests based on more complex test protocols,
8782 the exact effects of @code{XFAIL_TESTS} and @code{DISABLE_HARD_ERRORS}
8783 might change, or they might even have no effect at all (for example,
8784 @c Keep this in sync with tap-no-disable-hard-errors.sh
8785 in tests using TAP, there is not way to disable hard errors, and the
8786 @code{DISABLE_HARD_ERRORS} variable has no effect on them).
8788 @anchor{Testsuite progress on console}
8789 @cindex Testsuite progress on console
8790 The result of each test case run by the scripts in @code{TESTS} will be
8791 printed on standard output, along with the test name. For test protocols
8792 that allow more test cases per test script (such as TAP), a number,
8793 identifier and/or brief description specific for the single test case is
8794 expected to be printed in addition to the name of the test script. The
8795 possible results (whose meanings should be clear from the previous
8796 @ref{Generalities about Testing}) are @code{PASS}, @code{FAIL},
8797 @code{SKIP}, @code{XFAIL}, @code{XPASS} and @code{ERROR}. Here is an
8798 example of output from an hypothetical testsuite that uses both plain
8800 @c Keep in sync with tap-doc.sh
8803 PASS: zardoz.tap 1 - Daemon started
8804 PASS: zardoz.tap 2 - Daemon responding
8805 SKIP: zardoz.tap 3 - Daemon uses /proc # SKIP /proc is not mounted
8806 PASS: zardoz.tap 4 - Daemon stopped
8809 XFAIL: mu.tap 2 # TODO frobnication not yet implemented
8813 A testsuite summary (expected to report at least the number of run,
8814 skipped and failed tests) will be printed at the end of the testsuite
8817 @anchor{Simple tests and color-tests}
8818 @vindex AM_COLOR_TESTS
8819 @cindex Colorized testsuite output
8820 If the Automake option @code{color-tests} is used (@pxref{Options})
8821 and standard output is connected to a capable terminal, then the test
8822 results and the summary are colored appropriately. The user can disable
8823 colored output by setting the @command{make} variable
8824 @samp{AM_COLOR_TESTS=no}, or force colored output even without a connecting
8825 terminal with @samp{AM_COLOR_TESTS=always}. It's also worth noting that
8826 some @command{make} implementations, when used in parallel mode, have
8827 slightly different semantics (@pxref{Parallel make,,, autoconf,
8828 The Autoconf Manual}), which can break the automatic detection of a
8829 connection to a capable terminal. If this is the case, you'll have to
8830 resort to the use of @samp{AM_COLOR_TESTS=always} in order to have the
8831 testsuite output colorized.
8833 Test programs that need data files should look for them in @code{srcdir}
8834 (which is both a make variable and an environment variable made available
8835 to the tests), so that they work when building in a separate directory
8836 (@pxref{Build Directories, , Build Directories , autoconf,
8837 The Autoconf Manual}), and in particular for the @code{distcheck} rule
8838 (@pxref{Checking the Distribution}).
8841 @vindex TESTS_ENVIRONMENT
8842 @vindex AM_TESTS_ENVIRONMENT
8843 The @code{AM_TESTS_ENVIRONMENT} and @code{TESTS_ENVIRONMENT} variables can
8844 be used to run initialization code and set environment variables for the
8845 test scripts. The former variable is developer-reserved, and can be
8846 defined in the @file{Makefile.am}, while the latter is reserved for the
8847 user, which can employ it to extend or override the settings in the
8848 former; for this to work portably, however, the contents of a non-empty
8849 @code{AM_TESTS_ENVIRONMENT} @emph{must} be terminated by a semicolon.
8851 @vindex AM_TESTS_FD_REDIRECT
8852 The @code{AM_TESTS_FD_REDIRECT} variable can be used to define file
8853 descriptor redirections for the test scripts. One might think that
8854 @code{AM_TESTS_ENVIRONMENT} could be used for this purpose, but experience
8855 has shown that doing so portably is practically impossible. The main
8856 hurdle is constituted by Korn shells, which usually set the close-on-exec
8857 flag on file descriptors opened with the @command{exec} builtin, thus
8858 rendering an idiom like @code{AM_TESTS_ENVIRONMENT = exec 9>&2;}
8859 ineffectual. This issue also affects some Bourne shells, such as the
8860 HP-UX's @command{/bin/sh},
8861 @c FIXME: should we offer a link to the relevant discussions on the
8862 @c bug-autoconf list?
8864 @c Keep in sync with tests-environment-backcompat.sh
8866 AM_TESTS_ENVIRONMENT = \
8867 ## Some environment initializations are kept in a separate shell
8868 ## file `tests-env.sh', which can make it easier to also run tests
8869 ## from the command line.
8870 . $(srcdir)/tests-env.sh; \
8871 ## On Solaris, prefer more POSIX-compliant versions of the standard
8872 ## tools by default.
8873 if test -d /usr/xpg4/bin; then \
8874 PATH=/usr/xpg4/bin:$$PATH; export PATH; \
8876 @c $$ restore font-lock
8877 ## With this, the test scripts will be able to print diagnostic
8878 ## messages to the original standard error stream, even if the test
8879 ## driver redirects the stderr of the test scripts to a log file
8880 ## before executing them.
8881 AM_TESTS_FD_REDIRECT = 9>&2
8885 Note however that @code{AM_TESTS_ENVIRONMENT} is, for historical and
8886 implementation reasons, @emph{not} supported by the serial harness
8887 (@pxref{Serial Test Harness}).
8889 Automake ensures that each file listed in @code{TESTS} is built before
8890 it is run; you can list both source and derived programs (or scripts)
8891 in @code{TESTS}; the generated rule will look both in @code{srcdir} and
8892 @file{.}. For instance, you might want to run a C program as a test.
8893 To do this you would list its name in @code{TESTS} and also in
8894 @code{check_PROGRAMS}, and then specify it as you would any other
8897 Programs listed in @code{check_PROGRAMS} (and @code{check_LIBRARIES},
8898 @code{check_LTLIBRARIES}...) are only built during @code{make check},
8899 not during @code{make all}. You should list there any program needed
8900 by your tests that does not need to be built by @code{make all}. Note
8901 that @code{check_PROGRAMS} are @emph{not} automatically added to
8902 @code{TESTS} because @code{check_PROGRAMS} usually lists programs used
8903 by the tests, not the tests themselves. Of course you can set
8904 @code{TESTS = $(check_PROGRAMS)} if all your programs are test cases.
8906 @node Serial Test Harness
8907 @subsection Serial Test Harness
8908 @cindex @option{serial-tests}, Using
8910 @emph{NOTE:} This harness, while still being the default one, is
8911 obsolescent, and kept mostly for backward-compatibility reasons. The user
8912 is advised to use the parallel test harness instead (@pxref{Parallel Test
8913 Harness}). Be warned that future Automake versions might switch to use
8914 that more modern and feature-rich harness by default.
8916 The serial test harness is enabled by the Automake option
8917 @option{serial-tests}. It operates by simply running the tests serially,
8918 one at the time, without any I/O redirection. It's up to the user to
8919 implement logging of tests' output, if that's requited or desired.
8920 @c TODO: give an example of how this can be done.
8922 For historical and implementation reasons, the @code{AM_TESTS_ENVIRONMENT}
8923 variable is @emph{not} supported by this harness (it will be silently
8924 ignored if defined); only @code{TESTS_ENVIRONMENT} is, and it is to be
8925 considered a developer-reserved variable. This is done so that, when
8926 using the serial harness, @code{TESTS_ENVIRONMENT} can be defined to an
8927 invocation of an interpreter through which the tests are to be run.
8928 For instance, the following setup may be used to run tests with Perl:
8931 TESTS_ENVIRONMENT = $(PERL) -Mstrict -w
8932 TESTS = foo.pl bar.pl baz.pl
8936 It's important to note that the use of @code{TESTS_ENVIRONMENT} endorsed
8937 here would be @emph{invalid} with the parallel harness. That harness
8938 provides a more elegant way to achieve the same effect, with the further
8939 benefit of freeing the @code{TESTS_ENVIRONMENT} variable for the user
8940 (@pxref{Parallel Test Harness}).
8942 Another, less serious limit of the serial harness is that it doesn't
8943 really distinguish between simple failures and hard errors; this is
8944 due to historical reasons only, and might be fixed in future Automake
8947 @node Parallel Test Harness
8948 @subsection Parallel Test Harness
8949 @cindex @option{parallel-tests}, Using
8951 The parallel (or concurrent) test harness is enabled by the Automake option
8952 @option{parallel-tests}. It features automatic collection of the test
8953 scripts output in @file{.log} files, concurrent execution of tests with
8954 @code{make -j}, specification of inter-test dependencies, lazy reruns of
8955 tests that have not completed in a prior run, and hard errors for exceptional
8958 This harness is still somewhat experimental and may undergo changes in
8959 order to satisfy additional portability requirements.
8961 @anchor{Basics of test metadata}
8962 @vindex TEST_SUITE_LOG
8964 @cindex @file{.log} files
8965 @cindex @file{.trs} files
8966 @cindex test metadata
8967 The parallel test harness operates by defining a set of @command{make}
8968 rules that run the test scripts listed in @code{TESTS}, and, for each
8969 such script, save its output in a corresponding @file{.log} file and
8970 its results (and other ``metadata'', @pxref{API for Custom Test Drivers})
8971 in a corresponding @file{.trs} (as in @b{T}est @b{R}e@b{S}ults) file.
8972 @c We choose the `.trs' extension also because, at the time of writing,
8973 @c it isn't already used for other significant purposes; see e.g.:
8974 @c - http://filext.com/file-extension/trs
8975 @c - http://www.file-extensions.org/search/?searchstring=trs
8976 The @file{.log} file will contain all the output emitted by the test on
8977 its standard output and its standard error. The @file{.trs} file will
8978 contain, among the other things, the results of the test cases run by
8981 The parallel test harness will also create a summary log file,
8982 @code{TEST_SUITE_LOG}, which defaults to @file{test-suite.log} and requires
8983 a @file{.log} suffix. This file depends upon all the @file{.log} and
8984 @file{.trs} files created for the test scripts listed in @code{TESTS}.
8987 As with the serial harness above, by default one status line is printed
8988 per completed test, and a short summary after the suite has completed.
8989 However, standard output and standard error of the test are redirected
8990 to a per-test log file, so that parallel execution does not produce
8991 intermingled output. The output from failed tests is collected in the
8992 @file{test-suite.log} file. If the variable @samp{VERBOSE} is set, this
8993 file is output after the summary.
8994 @c FIXME: we should be clearer about what we mean exactly here ...
8995 For best results, the tests should be verbose by default now.
8997 @vindex TEST_EXTENSIONS
8999 Each couple of @file{.log} and @file{.trs} files is created when the
9000 corresponding test has completed. The set of log files is listed in
9001 the read-only variable @code{TEST_LOGS}, and defaults to @code{TESTS},
9002 with the executable extension if any (@pxref{EXEEXT}), as well as any
9003 suffix listed in @code{TEST_EXTENSIONS} removed, and @file{.log} appended.
9004 Results are undefined if a test file name ends in several concatenated
9005 suffixes. @code{TEST_EXTENSIONS} defaults to @file{.test}; it can be
9006 overridden by the user, in which case any extension listed in it must be
9007 constituted by a dot, followed by a non-digit alphabetic character,
9008 followed by any number of alphabetic characters.
9009 @c Keep in sync with test-extensions.sh
9010 For example, @samp{.sh}, @samp{.T} and @samp{.t1} are valid extensions,
9011 while @samp{.x-y}, @samp{.6c} and @samp{.t.1} are not.
9013 @vindex _LOG_COMPILE
9014 @vindex _LOG_COMPILER
9017 @vindex LOG_COMPILER
9019 @vindex @var{ext}_LOG_COMPILE
9020 @vindex @var{ext}_LOG_COMPILER
9021 @vindex @var{ext}_LOG_FLAGS
9022 @vindex AM_@var{ext}_LOG_FLAGS
9023 @vindex AM_LOG_FLAGS
9024 For tests that match an extension @code{.@var{ext}} listed in
9025 @code{TEST_EXTENSIONS}, you can provide a custom ``test runner'' using
9026 the variable @code{@var{ext}_LOG_COMPILER} (note the upper-case
9027 extension) and pass options in @code{AM_@var{ext}_LOG_FLAGS} and allow
9028 the user to pass options in @code{@var{ext}_LOG_FLAGS}. It will cause
9029 all tests with this extension to be called with this runner. For all
9030 tests without a registered extension, the variables @code{LOG_COMPILER},
9031 @code{AM_LOG_FLAGS}, and @code{LOG_FLAGS} may be used. For example,
9033 @c Keep in sync with parallel-tests-log-compiler-example.sh
9035 TESTS = foo.pl bar.py baz
9036 TEST_EXTENSIONS = .pl .py
9037 PL_LOG_COMPILER = $(PERL)
9038 AM_PL_LOG_FLAGS = -w
9039 PY_LOG_COMPILER = $(PYTHON)
9040 AM_PY_LOG_FLAGS = -v
9041 LOG_COMPILER = ./wrapper-script
9046 will invoke @samp{$(PERL) -w foo.pl}, @samp{$(PYTHON) -v bar.py},
9047 and @samp{./wrapper-script -d baz} to produce @file{foo.log},
9048 @file{bar.log}, and @file{baz.log}, respectively. The @file{foo.trs},
9049 @file{bar.trs} and @file{baz.trs} files will be automatically produced
9052 It's important to note that, differently from what we've seen for the
9053 serial test harness (@pxref{Parallel Test Harness}), the
9054 @code{AM_TESTS_ENVIRONMENT} and @code{TESTS_ENVIRONMENT} variables
9055 @emph{cannot} be use to define a custom test runner; the
9056 @code{LOG_COMPILER} and @code{LOG_FLAGS} (or their extension-specific
9057 counterparts) should be used instead:
9061 AM_TESTS_ENVIRONMENT = PERL5LIB='$(srcdir)/lib' $(PERL) -Mstrict -w
9066 AM_TESTS_ENVIRONMENT = PERL5LIB='$(srcdir)/lib'; export PERL5LIB;
9067 LOG_COMPILER = $(PERL)
9068 AM_LOG_FLAGS = -Mstrict -w
9071 By default, the test suite harness will run all tests, but there are
9072 several ways to limit the set of tests that are run:
9076 You can set the @code{TESTS} variable. For example, you can use a
9077 command like this to run only a subset of the tests:
9080 env TESTS="foo.test bar.test" make -e check
9083 Note however that the command above will unconditionally overwrite the
9084 @file{test-suite.log} file, thus clobbering the recorded results
9085 of any previous testsuite run. This might be undesirable for packages
9086 whose testsuite takes long time to execute. Luckily, this problem can
9087 easily be avoided by overriding also @code{TEST_SUITE_LOG} at runtime;
9090 @c Keep in sync with parallel-tests-log-override-2.sh
9092 env TEST_SUITE_LOG=partial.log TESTS="..." make -e check
9095 will write the result of the partial testsuite runs to the
9096 @file{partial.log}, without touching @file{test-suite.log}.
9099 You can set the @code{TEST_LOGS} variable. By default, this variable is
9100 computed at @command{make} run time from the value of @code{TESTS} as
9101 described above. For example, you can use the following:
9104 set x subset*.log; shift
9105 env TEST_LOGS="foo.log $*" make -e check
9108 The comments made above about @code{TEST_SUITE_LOG} overriding applies
9112 @vindex RECHECK_LOGS
9113 @cindex lazy test execution
9114 By default, the test harness removes all old per-test @file{.log} and
9115 @file{.trs} files before it starts running tests to regenerate them. The
9116 variable @code{RECHECK_LOGS} contains the set of @file{.log} (and, by
9117 implication, @file{.trs}) files which are removed. @code{RECHECK_LOGS}
9118 defaults to @code{TEST_LOGS}, which means all tests need to be rechecked.
9119 By overriding this variable, you can choose which tests need to be
9120 reconsidered. For example, you can lazily rerun only those tests which
9121 are outdated, i.e., older than their prerequisite test files, by setting
9122 this variable to the empty value:
9125 env RECHECK_LOGS= make -e check
9130 You can ensure that all tests are rerun which have failed or passed
9131 unexpectedly, by running @code{make recheck} in the test directory.
9132 This convenience target will set @code{RECHECK_LOGS} appropriately
9133 before invoking the main test harness.
9137 In order to guarantee an ordering between tests even with @code{make
9138 -j@var{N}}, dependencies between the corresponding @file{.log} files
9139 may be specified through usual @command{make} dependencies. For example,
9140 the following snippet lets the test named @file{foo-execute.test} depend
9141 upon completion of the test @file{foo-compile.test}:
9144 TESTS = foo-compile.test foo-execute.test
9145 foo-execute.log: foo-compile.log
9149 Please note that this ordering ignores the @emph{results} of required
9150 tests, thus the test @file{foo-execute.test} is run even if the test
9151 @file{foo-compile.test} failed or was skipped beforehand. Further,
9152 please note that specifying such dependencies currently works only for
9153 tests that end in one of the suffixes listed in @code{TEST_EXTENSIONS}.
9155 Tests without such specified dependencies may be run concurrently with
9156 parallel @command{make -j@var{N}}, so be sure they are prepared for
9157 concurrent execution.
9160 @c Keep in sync with 'parallel-tests-extra-programs.test'.
9161 The combination of lazy test execution and correct dependencies between
9162 tests and their sources may be exploited for efficient unit testing
9163 during development. To further speed up the edit-compile-test cycle, it
9164 may even be useful to specify compiled programs in @code{EXTRA_PROGRAMS}
9165 instead of with @code{check_PROGRAMS}, as the former allows intertwined
9166 compilation and test execution (but note that @code{EXTRA_PROGRAMS} are
9167 not cleaned automatically, @pxref{Uniform}).
9169 The variables @code{TESTS} and @code{XFAIL_TESTS} may contain
9170 conditional parts as well as configure substitutions. In the latter
9171 case, however, certain restrictions apply: substituted test names
9172 must end with a nonempty test suffix like @file{.test}, so that one of
9173 the inference rules generated by @command{automake} can apply. For
9174 literal test names, @command{automake} can generate per-target rules
9175 to avoid this limitation.
9177 Please note that it is currently not possible to use @code{$(srcdir)/}
9178 or @code{$(top_srcdir)/} in the @code{TESTS} variable. This technical
9179 limitation is necessary to avoid generating test logs in the source tree
9180 and has the unfortunate consequence that it is not possible to specify
9181 distributed tests that are themselves generated by means of explicit
9182 rules, in a way that is portable to all @command{make} implementations
9183 (@pxref{Make Target Lookup,,, autoconf, The Autoconf Manual}, the
9184 semantics of FreeBSD and OpenBSD @command{make} conflict with this).
9185 In case of doubt you may want to require to use GNU @command{make},
9186 or work around the issue with inference rules to generate the tests.
9188 @node Custom Test Drivers
9189 @section Custom Test Drivers
9192 * Overview of Custom Test Drivers Support::
9193 * Declaring Custom Test Drivers::
9194 * API for Custom Test Drivers::
9197 @node Overview of Custom Test Drivers Support
9198 @subsection Overview of Custom Test Drivers Support
9200 Starting from Automake version 1.12, the parallel test harness allows
9201 the package authors to use third-party custom test drivers, in case the
9202 default ones are inadequate for their purposes, or do not support their
9203 testing protocol of choice.
9205 A custom test driver is expected to properly run the test programs passed
9206 to it (including the command-line arguments passed to those programs, if
9207 any), to analyze their execution and outcome, to create the @file{.log}
9208 and @file{.trs} files associated to these test runs, and to display the test
9209 results on the console. It is responsibility of the author of the test
9210 driver to ensure that it implements all the above steps meaningfully and
9211 correctly; Automake isn't and can't be of any help here. On the other
9212 hand, the Automake-provided code for testsuite summary generation offers
9213 support for test drivers allowing several test results per test script,
9214 if they take care to register such results properly (@pxref{Log files
9215 generation and test results recording}).
9217 The exact details of how test scripts' results are to be determined and
9218 analyzed is left to the individual drivers. Some drivers might only
9219 consider the test script exit status (this is done for example by the
9220 default test driver used by the parallel test harness, described
9221 in the previous section). Other drivers might implement more complex and
9222 advanced test protocols, which might require them to parse and interpreter
9223 the output emitted by the test script they're running (examples of such
9224 protocols are TAP and SubUnit).
9226 It's very important to note that, even when using custom test drivers,
9227 most of the infrastructure described in the previous section about the
9228 parallel harness remains in place; this includes:
9232 list of test scripts defined in @code{TESTS}, and overridable at
9233 runtime through the redefinition of @code{TESTS} or @code{TEST_LOGS};
9235 concurrency through the use of @command{make}'s option @option{-j};
9237 per-test @file{.log} and @file{.trs} files, and generation of a summary
9238 @file{.log} file from them;
9240 @code{recheck} target, @code{RECHECK_LOGS} variable, and lazy reruns
9243 inter-test dependencies;
9245 support for @code{check_*} variables (@code{check_PROGRAMS},
9246 @code{check_LIBRARIES}, ...);
9248 use of @code{VERBOSE} environment variable to get verbose output on
9251 definition and honoring of @code{TESTS_ENVIRONMENT},
9252 @code{AM_TESTS_ENVIRONMENT} and @code{AM_TESTS_FD_REDIRECT}
9255 definition of generic and extension-specific @code{LOG_COMPILER} and
9256 @code{LOG_FLAGS} variables.
9260 On the other hand, the exact semantics of how (and if)
9261 @option{color-tests}, @code{XFAIL_TESTS}, and hard errors are supported
9262 and handled is left to the individual test drivers.
9264 @c TODO: We should really add a working example in the doc/ directory,
9265 @c TODO: and reference if from here.
9267 @node Declaring Custom Test Drivers
9268 @subsection Declaring Custom Test Drivers
9271 @vindex _LOG_DRIVER_FLAGS
9273 @vindex LOG_DRIVER_FLAGS
9274 @vindex @var{ext}_LOG_DRIVER
9275 @vindex @var{ext}_LOG_DRIVER_FLAGS
9276 @vindex AM_@var{ext}_LOG_DRIVER_FLAGS
9277 @vindex AM_LOG_DRIVER_FLAGS
9278 Custom testsuite drivers are declared by defining the make variables
9279 @code{LOG_DRIVER} or @code{@var{ext}_LOG_DRIVER} (where @var{ext} must
9280 be declared in @code{TEST_EXTENSIONS}). They must be defined to
9281 programs or scripts that will be used to drive the execution, logging,
9282 and outcome report of the tests with corresponding extensions (or of
9283 those with no registered extension in the case of @code{LOG_DRIVER}).
9284 Clearly, multiple distinct test drivers can be declared in the same
9285 @file{Makefile.am}. Note moreover that the @code{LOG_DRIVER} variables
9286 are @emph{not} a substitute for the @code{LOG_COMPILER} variables: the
9287 two sets of variables can, and often do, usefully and legitimately
9290 @c TODO: We should really be able to point to a clarifying example here!
9292 The developer-reserved variable @code{AM_LOG_DRIVER_FLAGS} and the
9293 user-reserved variable @code{LOG_DRIVER_FLAGS} can be used to define
9294 flags that will be passed to each invocation of @code{LOG_DRIVER},
9295 with the user-defined flags obviously taking precedence over the
9296 developer-reserved ones. Similarly, for each extension @var{ext}
9297 declared in @code{TEST_EXTENSIONS}, flags listed in
9298 @code{AM_@var{ext}_LOG_DRIVER_FLAGS} and
9299 @code{@var{ext}_LOG_DRIVER_FLAGS} will be passed to
9300 invocations of @code{@var{ext}_LOG_DRIVER}.
9302 @node API for Custom Test Drivers
9303 @subsection API for Custom Test Drivers
9305 Note that @emph{the APIs described here are still highly experimental},
9306 and will very likely undergo tightenings and likely also extensive changes
9307 in the future, to accommodate for new features or to satisfy additional
9308 portability requirements.
9310 The main characteristic of these APIs is that they are designed to share
9311 as much infrastructure, semantics, and implementation details as possible
9312 with the parallel test harness and its default driver.
9315 * Command-line arguments for test drivers::
9316 * Log files generation and test results recording::
9317 * Testsuite progress output::
9320 @node Command-line arguments for test drivers
9321 @subsubsection Command-line arguments for test drivers
9323 A custom driver can rely on various command-line options and arguments
9324 being passed to it automatically by the Automake's @option{parallel-tests}
9325 harness. It is @emph{mandatory} that it understands all of them (even
9326 if the exact interpretation of the associated semantics can legitimately
9327 change between a test driver and another, and even be a no-op in some
9331 Here is the list of options:
9334 @item --test-name=@var{NAME}
9335 The name of the test, with VPATH prefix (if any) removed. This can have a
9336 suffix and a directory component (as in e.g., @file{sub/foo.test}), and is
9337 mostly meant to be used in console reports about testsuite advancements and
9338 results (@pxref{Testsuite progress output}).
9339 @item --log-file=@file{@var{PATH}.log}
9340 The @file{.log} file the test driver must create (@pxref{Basics of
9341 test metadata}). If it has a directory component (as in e.g.,
9342 @file{sub/foo.log}), the test harness will ensure that such directory
9343 exists @emph{before} the test driver is called.
9344 @item --trs-file=@file{@var{PATH}.trs}
9345 The @file{.trs} file the test driver must create (@pxref{Basics of
9346 test metadata}). If it has a directory component (as in e.g.,
9347 @file{sub/foo.trs}), the test harness will ensure that such directory
9348 exists @emph{before} the test driver is called.
9349 @item --color-tests=@{yes|no@}
9350 Whether the console output should be colorized or not (@pxref{Simple
9351 tests and color-tests}, to learn when this option gets activated and
9353 @item --expect-failure=@{yes|no@}
9354 Whether the tested program is expected to fail.
9355 @item --enable-hard-errors=@{yes|no@}
9356 Whether ``hard errors'' in the tested program should be treated differently
9357 from normal failures or not (the default should be @code{yes}). The exact
9358 meaning of ``hard error'' is highly dependent from the test protocols or
9361 Explicitly terminate the list of options.
9365 The first non-option argument passed to the test driver is the program to
9366 be run, and all the following ones are command-line options and arguments
9369 Note that the exact semantics attached to the @option{--color-tests},
9370 @option{--expect-failure} and @option{--enable-hard-errors} options are
9371 left up to the individual test drivers. Still, having a behaviour
9372 compatible or at least similar to that provided by the default
9373 @option{parallel-tests} driver is advised, as that would offer a better
9374 consistency and a more pleasant user experience.
9376 @node Log files generation and test results recording
9377 @subsubsection Log files generation and test results recording
9379 The test driver must correctly generate the files specified by the
9380 @option{--log-file} and @option{--trs-file} option (even when the tested
9381 program fails or crashes).
9383 The @file{.log} file should ideally contain all the output produced by the
9384 tested program, plus optionally other information that might facilitate
9385 debugging or analysis of bug reports. Apart from that, its format is
9388 The @file{.trs} file is used to register some metadata through the use
9389 of custom reStructuredText fields. This metadata is expected to be
9390 employed in various ways by the parallel test harness; for example, to
9391 count the test results when printing the testsuite summary, or to decide
9392 which tests to re-run upon @command{make reheck}. Unrecognized metadata
9393 in a @file{.trs} file is currently ignored by the harness, but this might
9394 change in the future. The list of currently recognized metadata follows.
9399 @cindex Register test result
9400 @cindex Register test case result
9401 @cindex Test result, registering
9402 @cindex Test case result, registering
9403 @cindex @code{:test-result:}
9404 @cindex reStructuredText field, @code{:test-result:}
9405 The test driver must use this field to register the results of @emph{each}
9406 test case run by a test script file. Several @code{:test-result:} fields
9407 can be present in the same @file{.trs} file; this is done in order to
9408 support test protocols that allow a single test script to run more test
9411 @c Keep this in sync with lib/am/check-am:$(TEST_SUITE_LOG).
9412 The only recognized test results are currently @code{PASS}, @code{XFAIL},
9413 @code{SKIP}, @code{FAIL}, @code{XPASS} and @code{ERROR}. These results,
9414 when declared with @code{:test-result:}, can be optionally followed by
9415 text holding the name and/or a brief description of the corresponding
9416 test; the @option{parallel-tests} harness will ignore such extra text when
9417 generating @file{test-suite.log} and preparing the testsuite summary.
9419 @c Keep in sync with 'test-metadata-recheck.test'.
9420 @item @code{:recheck:}
9422 @cindex reStructuredText field, @code{:recheck:}
9423 If this field is present and defined to @code{no}, then the corresponding
9424 test script will @emph{not} be run upon a @command{make recheck}. What
9425 happens when two or more @code{:recheck:} fields are present in the same
9426 @file{.trs} file is undefined behaviour.
9428 @c Keep in sync with 'test-metadata-global-log.test'.
9429 @item @code{:copy-in-global-log:}
9430 @cindex :copy-in-global-log:
9431 @cindex reStructuredText field, @code{:copy-in-global-log:}
9432 If this field is present and defined to @code{no}, then the content
9433 of the @file{.log} file will @emph{not} be copied into the global
9434 @file{test-suite.log}. We allow to forsake such copying because, while
9435 it can be useful in debugging and analysis of bug report, it can also be
9436 just a waste of space in normal situations, e.g., when a test script is
9437 successful. What happens when two or more @code{:copy-in-global-log:}
9438 fields are present in the same @file{.trs} file is undefined behaviour.
9440 @c Keep in sync with 'test-metadata-global-result.test'.
9441 @item @code{:test-global-result:}
9442 @cindex :test-global-result:
9443 @cindex reStructuredText field, @code{:test-global-result:}
9444 This is used to declare the "global result" of the script. Currently,
9445 the value of this field is needed only to be reported (more or less
9446 verbatim) in the generated global log file @code{$(TEST_SUITE_LOG)},
9447 so it's quite free-form. For example, a test script which run 10 test
9448 cases, 6 of which pass and 4 of which are skipped, could reasonably have
9449 a @code{PASS/SKIP} value for this field, while a test script which run
9450 19 successful tests and one failed test could have an @code{ALMOST
9451 PASSED} value. What happens when two or more @code{:test-global-result:}
9452 fields are present in the same @file{.trs} file is undefined behaviour.
9456 Let's see a small example. Assume a @file{.trs} file contains the
9460 :test-result: PASS server starts
9461 :global-log-copy: no
9462 :test-result: PASS HTTP/1.1 request
9463 :test-result: FAIL HTTP/1.0 request
9465 :test-result: SKIP HTTPS request (TLS library wasn't available)
9466 :test-result: PASS server stops
9470 Then the corresponding test script will be re-run by @command{make check},
9471 will contribute with @emph{five} test results to the testsuite summary
9472 (three of these tests being successful, one failed, and one skipped), and
9473 the content of the corresponding @file{.log} file will @emph{not} be
9474 copied in the global log file @file{test-suite.log}.
9476 @node Testsuite progress output
9477 @subsubsection Testsuite progress output
9479 A custom test driver also has the task of displaying, on the standard
9480 output, the test results as soon as they become available. Depending on
9481 the protocol in use, it can also display the reasons for failures and
9482 skips, and, more generally, any useful diagnostic output (but remember
9483 that each line on the screen is precious, so that cluttering the screen
9484 with overly verbose information is bad idea). The exact format of this
9485 progress output is left up to the test driver; in fact, a custom test
9486 driver might @emph{theoretically} even decide not to do any such report,
9487 leaving it all to the testsuite summary (that would be a very lousy idea,
9488 of course, and serves only to illustrate the flexibility that is
9491 Remember that consistency is good; so, if possible, try to be consistent
9492 with the output of the built-in Automake test drivers, providing a similar
9493 ``look & feel''. In particular, the testsuite progress output should be
9494 colorized when the @option{--color-tests} is passed to the driver. On the
9495 other end, if you are using a known and widespread test protocol with
9496 well-established implementations, being consistent with those
9497 implementations' output might be a good idea too.
9499 @c TODO: Give an example, maybe inspired to py.test-style output.
9500 @c TODO: That is a good idea because it shows a test driver that allows
9501 @c TODO: for different levels of verbosity in the progress output (could
9502 @c TODO: be implemented either using a driver cmdline flag, or an
9503 @c TODO: environment variable, or both).
9505 @node Using the TAP test protocol
9506 @section Using the TAP test protocol
9509 * Introduction to TAP::
9510 * Use TAP with the Automake test harness::
9511 * Incompatibilities with other TAP parsers and drivers::
9512 * Links and external resources on TAP::
9515 @node Introduction to TAP
9516 @subsection Introduction to TAP
9518 TAP, the Test Anything Protocol, is a simple text-based interface between
9519 testing modules or programs and a test harness. The tests (also called
9520 ``TAP producers'' in this context) write test results in a simple format
9521 on standard output; a test harness (also called ``TAP consumer'') will
9522 parse and interpret these results, and properly present them to the user,
9523 and/or register them for later analysis. The exact details of how this
9524 is accomplished can vary among different test harnesses. The Automake
9525 parallel harness will present the results on the console in the usual
9526 fashion (@pxref{Testsuite progress on console}), and will use the
9527 @file{.trs} files (@pxref{Basics of test metadata}) to store the test
9528 results and related metadata. Apart from that, it will try to remain
9529 as much compatible as possible with pre-existing and widespread utilities,
9530 such as the @uref{http://search.cpan.org/~andya/Test-Harness/bin/prove,
9531 @command{prove} utility}, at least for the simpler usages.
9533 TAP started its life as part of the test harness for Perl, but today
9534 it has been (mostly) standardized, and has various independent
9535 implementations in different languages; among them, C, C++, Perl,
9536 Python, PHP, and Java. For a semi-official specification of the
9537 TAP protocol, please refer to the documentation of
9538 @uref{http://search.cpan.org/~petdance/Test-Harness/lib/Test/Harness/TAP.pod,
9539 @samp{Test::Harness::TAP}}.
9541 The most relevant real-world usages of TAP are obviously in the testsuites
9542 of @command{perl} and of many perl modules. Still, also other important
9543 third-party packages, such as @uref{http://git-scm.com/, @command{git}},
9544 use TAP in their testsuite.
9546 @node Use TAP with the Automake test harness
9547 @subsection Use TAP with the Automake test harness
9549 Currently, the TAP driver that comes with Automake requires some by-hand
9550 steps on the developer's part (this situation should hopefully be improved
9551 in future Automake versions). You'll have to grab the @file{tap-driver.sh}
9552 script from the Automake distribution by hand, copy it in your source tree,
9553 add a call to @code{AC_PROG_AWK} in @file{configure.ac} to search for a
9554 proper awk program, and use the Automake support for third-party test
9555 drivers to instruct the harness to use the @file{tap-driver.sh} script
9556 and that awk program to run your TAP-producing tests. See the example
9557 below for clarification.
9559 Apart from the options common to all the Automake test drivers
9560 (@pxref{Command-line arguments for test drivers}), the @file{tap-driver.sh}
9561 supports the following options, whose names are chosen for enhanced
9562 compatibility with the @command{prove} utility.
9565 @c Keep in sync with 'tap-exit.test' and 'tap-signal.tap'.
9567 Causes the test driver to ignore the exit status of the test scripts;
9568 by default, the driver will report an error if the script exits with a
9569 non-zero status. This option has effect also on non-zero exit statuses
9570 due to termination by a signal.
9572 Instruct the test driver to display TAP diagnostic (i.e., lines beginning
9573 with the @samp{#} character) in the testsuite progress output too; by
9574 default, TAP diagnostic is only copied to the @file{.log} file.
9576 Revert the effects of @option{--comments}.
9578 Instruct the test driver to merge the test scripts' standard error into
9579 their standard output. This is necessary if you want to ensure that
9580 diagnostics from the test scripts are displayed in the correct order
9581 relative to test results; this can be of great help in debugging
9582 (especially if your test scripts are shell scripts run with shell
9583 tracing active). As a downside, this option might cause the test
9584 harness to get confused if anything that appears on standard error
9585 looks like a test result.
9587 Revert the effects of @option{--merge}.
9588 @item --diagnostic-string=@var{STRING}
9589 Change the string that introduces TAP diagnostic from the default value
9590 of ``@code{#}'' to @code{@var{STRING}}. This can be useful if your
9591 TAP-based test scripts produce verbose output on which they have limited
9592 control (because, say, the output comes from other tools invoked in the
9593 scripts), and it might contain text that gets spuriously interpreted as
9594 TAP diagnostic: such an issue can be solved by redefining the string that
9595 activates TAP diagnostic to a value you know won't appear by chance in
9596 the tests' output. Note however that this feature is non-standard, as
9597 the ``official'' TAP protocol does not allow for such a customization; so
9598 don't use it if you can avoid it.
9602 Here is an example of how the TAP driver can be set up and used.
9604 @c Keep in sync with tap-doc2.sh
9606 % @kbd{cat configure.ac}
9607 AC_INIT([GNU Try Tap], [1.0], [bug-automake@@gnu.org])
9608 AC_CONFIG_AUX_DIR([build-aux])
9609 AM_INIT_AUTOMAKE([foreign parallel-tests -Wall -Werror])
9610 AC_CONFIG_FILES([Makefile])
9611 AC_REQUIRE_AUX_FILE([tap-driver.sh])
9615 % @kbd{cat Makefile.am}
9616 TEST_LOG_DRIVER = env AM_TAP_AWK='$(AWK)' $(SHELL) \
9617 $(top_srcdir)/build-aux/tap-driver.sh
9618 TESTS = foo.test bar.test baz.test
9619 EXTRA_DIST = $(TESTS)
9621 % @kbd{cat foo.test}
9623 echo 1..4 # Number of tests to be executed.
9624 echo 'ok 1 - Swallows fly'
9625 echo 'not ok 2 - Caterpillars fly # TODO metamorphosis in progress'
9626 echo 'ok 3 - Pigs fly # SKIP not enough acid'
9627 echo '# I just love word plays ...'
9628 echo 'ok 4 - Flies fly too :-)'
9630 % @kbd{cat bar.test}
9633 echo 'not ok 1 - Bummer, this test has failed.'
9634 echo 'ok 2 - This passed though.'
9635 echo 'Bail out! Ennui kicking in, sorry...'
9636 echo 'ok 3 - This will not be seen.'
9638 % @kbd{cat baz.test}
9642 # Exit with error, even if all the tests have been successful.
9645 % @kbd{cp @var{PREFIX}/share/automake-@var{APIVERSION}/tap-driver.pl .}
9646 % @kbd{autoreconf -vi && ./configure && make check}
9648 PASS: foo.test 1 - Swallows fly
9649 XFAIL: foo.test 2 - Caterpillars fly # TODO metamorphosis in progress
9650 SKIP: foo.test 3 - Pigs fly # SKIP not enough acid
9651 PASS: foo.test 4 - Flies fly too :-)
9652 FAIL: bar.test 1 - Bummer, this test has failed.
9653 PASS: bar.test 2 - This passed though.
9654 ERROR: bar.test - Bail out! Ennui kicking in, sorry...
9656 ERROR: baz.test - exited with status 7
9658 Please report to bug-automake@@gnu.org
9660 % @kbd{echo exit status: $?}
9663 @c Keep the "skewed" indentation below, it produces pretty PDF output.
9664 % @kbd{env TEST_LOG_DRIVER_FLAGS='--comments --ignore-exit' \
9665 TESTS='foo.test baz.test' make -e check}
9667 PASS: foo.test 1 - Swallows fly
9668 XFAIL: foo.test 2 - Caterpillars fly # TODO metamorphosis in progress
9669 SKIP: foo.test 3 - Pigs fly # SKIP not enough acid
9670 # foo.test: I just love word plays...
9671 PASS: foo.test 4 - Flies fly too :-)
9674 % @kbd{echo exit status: $?}
9678 @node Incompatibilities with other TAP parsers and drivers
9679 @subsection Incompatibilities with other TAP parsers and drivers
9681 For implementation or historical reasons, the TAP driver and harness as
9682 implemented by Automake have some minors incompatibilities with the
9683 mainstream versions, which you should be aware of.
9687 A @code{Bail out!} directive doesn't stop the whole testsuite, but only
9688 the test script it occurs in. This doesn't follow TAP specifications,
9689 but on the other hand it maximizes compatibility (and code sharing) with
9690 the ``hard error'' concept of the default @option{parallel-tests} driver.
9692 The @code{version} and @code{pragma} directives are not supported.
9694 The @option{--diagnostic-string} option of our driver allows to modify
9695 the string that introduces TAP diagnostic from the default value
9696 of ``@code{#}''. The standard TAP protocol has currently no way to
9697 allow this, so if you use it your diagnostic will be lost to more
9698 compliant tools like @command{prove} and @code{Test::Harness}
9700 And there are probably some other small and yet undiscovered
9701 incompatibilities, especially in corner cases or with rare usages.
9704 @node Links and external resources on TAP
9705 @subsection Links and external resources on TAP
9708 Here are some links to more extensive official or third-party
9709 documentation and resources about the TAP protocol and related
9710 tools and libraries.
9713 @uref{http://search.cpan.org/~petdance/Test-Harness/lib/Test/Harness/TAP.pod,
9714 @samp{Test::Harness::TAP}},
9715 the (mostly) official documentation about the TAP format and protocol.
9717 @uref{http://search.cpan.org/~andya/Test-Harness/bin/prove,
9719 the most famous command-line TAP test driver, included in the distribution
9720 of @command{perl} and
9721 @uref{http://search.cpan.org/~andya/Test-Harness/lib/Test/Harness.pm,
9722 @samp{Test::Harness}}.
9724 The @uref{http://testanything.org/wiki/index.php/Main_Page,TAP wiki}.
9726 A ``gentle introduction'' to testing for perl coders:
9727 @uref{http://search.cpan.org/dist/Test-Simple/lib/Test/Tutorial.pod,
9728 @samp{Test::Tutorial}}.
9730 @uref{http://search.cpan.org/~mschwern/Test-Simple/lib/Test/Simple.pm,
9731 @samp{Test::Simple}}
9733 @uref{http://search.cpan.org/~mschwern/Test-Simple/lib/Test/More.pm,
9735 the standard perl testing libraries, which are based on TAP.
9737 @uref{http://www.eyrie.org/~eagle/software/c-tap-harness/,C TAP Harness},
9738 a C-based project implementing both a TAP producer and a TAP consumer.
9740 @uref{http://www.tap4j.org/,tap4j},
9741 a Java-based project implementing both a TAP producer and a TAP consumer.
9745 @section DejaGnu Tests
9747 If @uref{ftp://ftp.gnu.org/gnu/dejagnu/, @command{dejagnu}} appears in
9748 @code{AUTOMAKE_OPTIONS}, then a @command{dejagnu}-based test suite is
9749 assumed. The variable @code{DEJATOOL} is a list of names that are
9750 passed, one at a time, as the @option{--tool} argument to
9751 @command{runtest} invocations; it defaults to the name of the package.
9753 The variable @code{RUNTESTDEFAULTFLAGS} holds the @option{--tool} and
9754 @option{--srcdir} flags that are passed to dejagnu by default; this can be
9755 overridden if necessary.
9756 @vindex RUNTESTDEFAULTFLAGS
9758 The variables @code{EXPECT} and @code{RUNTEST} can
9759 also be overridden to provide project-specific values. For instance,
9760 you will need to do this if you are testing a compiler toolchain,
9761 because the default values do not take into account host and target
9768 The contents of the variable @code{RUNTESTFLAGS} are passed to the
9769 @code{runtest} invocation. This is considered a ``user variable''
9770 (@pxref{User Variables}). If you need to set @command{runtest} flags in
9771 @file{Makefile.am}, you can use @code{AM_RUNTESTFLAGS} instead.
9772 @vindex RUNTESTFLAGS
9773 @vindex AM_RUNTESTFLAGS
9775 @cindex @file{site.exp}
9776 Automake will generate rules to create a local @file{site.exp} file,
9777 defining various variables detected by @command{configure}. This file
9778 is automatically read by DejaGnu. It is OK for the user of a package
9779 to edit this file in order to tune the test suite. However this is
9780 not the place where the test suite author should define new variables:
9781 this should be done elsewhere in the real test suite code.
9782 Especially, @file{site.exp} should not be distributed.
9784 Still, if the package author has legitimate reasons to extend
9785 @file{site.exp} at @command{make} time, he can do so by defining
9786 the variable @code{EXTRA_DEJAGNU_SITE_CONFIG}; the files listed
9787 there will be considered @file{site.exp} prerequisites, and their
9788 content will be appended to it (in the same order in which they
9789 appear in @code{EXTRA_DEJAGNU_SITE_CONFIG}). Note that files are
9790 @emph{not} distributed by default.
9792 For more information regarding DejaGnu test suites, see @ref{Top, , ,
9793 dejagnu, The DejaGnu Manual}.
9796 @section Install Tests
9798 The @code{installcheck} target is available to the user as a way to
9799 run any tests after the package has been installed. You can add tests
9800 to this by writing an @code{installcheck-local} rule.
9804 @chapter Rebuilding Makefiles
9805 @cindex rebuild rules
9807 Automake generates rules to automatically rebuild @file{Makefile}s,
9808 @file{configure}, and other derived files like @file{Makefile.in}.
9810 @acindex AM_MAINTAINER_MODE
9811 If you are using @code{AM_MAINTAINER_MODE} in @file{configure.ac}, then
9812 these automatic rebuilding rules are only enabled in maintainer mode.
9814 @vindex ACLOCAL_AMFLAGS
9815 Sometimes you need to run @command{aclocal} with an argument like
9816 @option{-I} to tell it where to find @file{.m4} files. Since
9817 sometimes @command{make} will automatically run @command{aclocal}, you
9818 need a way to specify these arguments. You can do this by defining
9819 @code{ACLOCAL_AMFLAGS}; this holds arguments that are passed verbatim
9820 to @command{aclocal}. This variable is only useful in the top-level
9823 @vindex CONFIG_STATUS_DEPENDENCIES
9824 @vindex CONFIGURE_DEPENDENCIES
9825 @cindex @file{version.sh}, example
9826 @cindex @file{version.m4}, example
9828 Sometimes it is convenient to supplement the rebuild rules for
9829 @file{configure} or @file{config.status} with additional dependencies.
9830 The variables @code{CONFIGURE_DEPENDENCIES} and
9831 @code{CONFIG_STATUS_DEPENDENCIES} can be used to list these extra
9832 dependencies. These variables should be defined in all
9833 @file{Makefile}s of the tree (because these two rebuild rules are
9834 output in all them), so it is safer and easier to @code{AC_SUBST} them
9835 from @file{configure.ac}. For instance, the following statement will
9836 cause @file{configure} to be rerun each time @file{version.sh} is
9840 AC_SUBST([CONFIG_STATUS_DEPENDENCIES], ['$(top_srcdir)/version.sh'])
9844 Note the @samp{$(top_srcdir)/} in the file name. Since this variable
9845 is to be used in all @file{Makefile}s, its value must be sensible at
9846 any level in the build hierarchy.
9848 Beware not to mistake @code{CONFIGURE_DEPENDENCIES} for
9849 @code{CONFIG_STATUS_DEPENDENCIES}.
9851 @code{CONFIGURE_DEPENDENCIES} adds dependencies to the
9852 @file{configure} rule, whose effect is to run @command{autoconf}. This
9853 variable should be seldom used, because @command{automake} already tracks
9854 @code{m4_include}d files. However it can be useful when playing
9855 tricky games with @code{m4_esyscmd} or similar non-recommendable
9856 macros with side effects.
9858 @code{CONFIG_STATUS_DEPENDENCIES} adds dependencies to the
9859 @file{config.status} rule, whose effect is to run @file{configure}.
9860 This variable should therefore carry any non-standard source that may
9861 be read as a side effect of running @command{configure}, like @file{version.sh}
9862 in the example above.
9864 Speaking of @file{version.sh} scripts, we recommend against them
9865 today. They are mainly used when the version of a package is updated
9866 automatically by a script (e.g., in daily builds). Here is what some
9867 old-style @file{configure.ac}s may look like:
9871 . $srcdir/version.sh
9872 AM_INIT_AUTOMAKE([name], $VERSION_NUMBER)
9877 Here, @file{version.sh} is a shell fragment that sets
9878 @code{VERSION_NUMBER}. The problem with this example is that
9879 @command{automake} cannot track dependencies (listing @file{version.sh}
9880 in @command{CONFIG_STATUS_DEPENDENCIES}, and distributing this file is up
9881 to the user), and that it uses the obsolete form of @code{AC_INIT} and
9882 @code{AM_INIT_AUTOMAKE}. Upgrading to the new syntax is not
9883 straightforward, because shell variables are not allowed in
9884 @code{AC_INIT}'s arguments. We recommend that @file{version.sh} be
9885 replaced by an M4 file that is included by @file{configure.ac}:
9888 m4_include([version.m4])
9889 AC_INIT([name], VERSION_NUMBER)
9895 Here @file{version.m4} could contain something like
9896 @samp{m4_define([VERSION_NUMBER], [1.2])}. The advantage of this
9897 second form is that @command{automake} will take care of the
9898 dependencies when defining the rebuild rule, and will also distribute
9899 the file automatically. An inconvenience is that @command{autoconf}
9900 will now be rerun each time the version number is bumped, when only
9901 @file{configure} had to be rerun in the previous setup.
9905 @chapter Changing Automake's Behavior
9908 * Options generalities:: Semantics of Automake option
9909 * List of Automake options:: A comprehensive list of Automake options
9912 @node Options generalities
9913 @section Options generalities
9915 Various features of Automake can be controlled by options. Except where
9916 noted otherwise, options can be specified in one of several ways. Most
9917 options can be applied on a per-@file{Makefile} basis when listed in a
9918 special @file{Makefile} variable named @code{AUTOMAKE_OPTIONS}. Some
9919 of these options only make sense when specified in the toplevel
9920 @file{Makefile.am} file. Options are applied globally to all processed
9921 @file{Makefile} files when listed in the first argument of
9922 @code{AM_INIT_AUTOMAKE} in @file{configure.ac}, and some options which
9923 require changes to the @command{configure} script can only be specified
9924 there. These are annotated below.
9926 As a general rule, options specified in @code{AUTOMAKE_OPTIONS} take
9927 precedence over those specified in @code{AM_INIT_AUTOMAKE}, which in
9928 turn take precedence over those specified on the command line.
9930 Also, some care must be taken about the interactions among strictness
9931 level and warning categories. As a general rule, strictness-implied
9932 warnings are overridden by those specified by explicit options. For
9933 example, even if @samp{portability} warnings are disabled by default
9934 in @option{foreign} strictness, an usage like this will end up enabling
9938 AUTOMAKE_OPTIONS = -Wportability foreign
9941 However, a strictness level specified in a higher-priority context
9942 will override all the explicit warnings specified in a lower-priority
9943 context. For example, if @file{configure.ac} contains:
9946 AM_INIT_AUTOMAKE([-Wportability])
9950 and @file{Makefile.am} contains:
9953 AUTOMAKE_OPTIONS = foreign
9957 then @samp{portability} warnings will be @emph{disabled} in
9960 @node List of Automake options
9961 @section List of Automake options
9963 @vindex AUTOMAKE_OPTIONS
9966 @item @option{gnits}
9968 @itemx @option{foreign}
9969 @cindex Option, @option{gnits}
9970 @cindex Option, @option{gnu}
9971 @cindex Option, @option{foreign}
9976 Set the strictness as appropriate. The @option{gnits} option also
9977 implies options @option{readme-alpha} and @option{check-news}.
9979 @item @option{check-news}
9980 @cindex Option, @option{check-news}
9982 Cause @samp{make dist} to fail unless the current version number appears
9983 in the first few lines of the @file{NEWS} file.
9985 @item @option{color-tests}
9986 @cindex Option, @option{color-tests}
9987 @opindex color-tests
9988 Cause output of the serial and parallel test harnesses (see @ref{Simple
9989 Tests}) and of properly-written custom test drivers (@pxref{Custom Test
9990 Drivers}) to be colorized on capable terminals.
9992 @item @option{dejagnu}
9993 @cindex Option, @option{dejagnu}
9995 Cause @command{dejagnu}-specific rules to be generated. @xref{DejaGnu Tests}.
9997 @item @option{dist-bzip2}
9998 @cindex Option, @option{dist-bzip2}
10000 Hook @code{dist-bzip2} to @code{dist}.
10001 @trindex dist-bzip2
10003 @item @option{dist-lzip}
10004 @cindex Option, @option{dist-lzip}
10006 Hook @code{dist-lzip} to @code{dist}.
10009 @item @option{dist-shar}
10010 @cindex Option, @option{dist-shar}
10012 Hook @code{dist-shar} to @code{dist}.
10015 @item @option{dist-zip}
10016 @cindex Option, @option{dist-zip}
10018 Hook @code{dist-zip} to @code{dist}.
10021 @item @option{dist-tarZ}
10022 @cindex Option, @option{dist-tarZ}
10024 Hook @code{dist-tarZ} to @code{dist}.
10027 @item @option{filename-length-max=99}
10028 @cindex Option, @option{filename-length-max=99}
10029 @opindex filename-length-max=99
10030 Abort if file names longer than 99 characters are found during
10031 @samp{make dist}. Such long file names are generally considered not to
10032 be portable in tarballs. See the @option{tar-v7} and @option{tar-ustar}
10033 options below. This option should be used in the top-level
10034 @file{Makefile.am} or as an argument of @code{AM_INIT_AUTOMAKE} in
10035 @file{configure.ac}, it will be ignored otherwise. It will also be
10036 ignored in sub-packages of nested packages (@pxref{Subpackages}).
10038 @item @option{no-define}
10039 @cindex Option, @option{no-define}
10041 This option is meaningful only when passed as an argument to
10042 @code{AM_INIT_AUTOMAKE}. It will prevent the @code{PACKAGE} and
10043 @code{VERSION} variables from being @code{AC_DEFINE}d.
10045 @item @option{no-dependencies}
10046 @cindex Option, @option{no-dependencies}
10047 @opindex no-dependencies
10048 This is similar to using @option{--ignore-deps} on the command line,
10049 but is useful for those situations where you don't have the necessary
10050 bits to make automatic dependency tracking work
10051 (@pxref{Dependencies}). In this case the effect is to effectively
10052 disable automatic dependency tracking.
10054 @item @option{no-dist}
10055 @cindex Option, @option{no-dist}
10057 Don't emit any code related to @code{dist} target. This is useful
10058 when a package has its own method for making distributions.
10060 @item @option{no-dist-gzip}
10061 @cindex Option, @option{no-dist-gzip}
10062 @opindex no-dist-gzip
10063 Do not hook @code{dist-gzip} to @code{dist}.
10064 @trindex no-dist-gzip
10066 @item @option{no-exeext}
10067 @cindex Option, @option{no-exeext}
10069 If your @file{Makefile.am} defines a rule for target @code{foo}, it
10070 will override a rule for a target named @samp{foo$(EXEEXT)}. This is
10071 necessary when @code{EXEEXT} is found to be empty. However, by
10072 default @command{automake} will generate an error for this use. The
10073 @option{no-exeext} option will disable this error. This is intended for
10074 use only where it is known in advance that the package will not be
10075 ported to Windows, or any other operating system using extensions on
10078 @item @option{no-installinfo}
10079 @cindex Option, @option{no-installinfo}
10080 @opindex no-installinfo
10081 The generated @file{Makefile.in} will not cause info pages to be built
10082 or installed by default. However, @code{info} and @code{install-info}
10083 targets will still be available. This option is disallowed at
10084 @option{gnu} strictness and above.
10086 @trindex install-info
10088 @item @option{no-installman}
10089 @cindex Option, @option{no-installman}
10090 @opindex no-installman
10091 The generated @file{Makefile.in} will not cause man pages to be
10092 installed by default. However, an @code{install-man} target will still
10093 be available for optional installation. This option is disallowed at
10094 @option{gnu} strictness and above.
10095 @trindex install-man
10097 @item @option{nostdinc}
10098 @cindex Option, @option{nostdinc}
10100 This option can be used to disable the standard @option{-I} options that
10101 are ordinarily automatically provided by Automake.
10103 @item @option{no-texinfo.tex}
10104 @cindex Option, @option{no-texinfo.tex}
10105 @opindex no-texinfo.tex
10106 Don't require @file{texinfo.tex}, even if there are texinfo files in
10109 @item @option{parallel-tests}
10110 @cindex Option, @option{parallel-tests}
10111 @opindex parallel-tests
10112 Enable test suite harness for @code{TESTS} that can run tests in parallel
10113 (@pxref{Parallel Test Harness}, for more information).
10115 @item @option{serial-tests}
10116 @cindex Option, @option{serial-tests}
10117 @opindex serial-tests
10118 Enable the older serial test suite harness for @code{TESTS} (@pxref{Serial
10119 Test Harness}, for more information). This is still the default for the
10122 @item @option{readme-alpha}
10123 @cindex Option, @option{readme-alpha}
10124 @opindex readme-alpha
10125 If this release is an alpha release, and the file @file{README-alpha}
10126 exists, then it will be added to the distribution. If this option is
10127 given, version numbers are expected to follow one of two forms. The
10128 first form is @samp{@var{major}.@var{minor}.@var{alpha}}, where each
10129 element is a number; the final period and number should be left off for
10130 non-alpha releases. The second form is
10131 @samp{@var{major}.@var{minor}@var{alpha}}, where @var{alpha} is a
10132 letter; it should be omitted for non-alpha releases.
10134 @item @option{std-options}
10135 @cindex Options, @option{std-options}
10136 @cindex @samp{make installcheck}, testing @option{--help} and @option{--version}
10137 @cindex @option{--help} check
10138 @cindex @option{--version} check
10139 @opindex std-options
10141 Make the @code{installcheck} rule check that installed scripts and
10142 programs support the @option{--help} and @option{--version} options.
10143 This also provides a basic check that the program's
10144 run-time dependencies are satisfied after installation.
10146 @vindex AM_INSTALLCHECK_STD_OPTIONS_EXEMPT
10147 In a few situations, programs (or scripts) have to be exempted from this
10148 test. For instance, @command{false} (from GNU coreutils) is never
10149 successful, even for @option{--help} or @option{--version}. You can list
10150 such programs in the variable @code{AM_INSTALLCHECK_STD_OPTIONS_EXEMPT}.
10151 Programs (not scripts) listed in this variable should be suffixed by
10152 @samp{$(EXEEXT)} for the sake of Windows or OS/2. For instance, suppose we
10153 build @file{false} as a program but @file{true.sh} as a script, and that
10154 neither of them support @option{--help} or @option{--version}:
10157 AUTOMAKE_OPTIONS = std-options
10158 bin_PROGRAMS = false ...
10159 bin_SCRIPTS = true.sh ...
10160 AM_INSTALLCHECK_STD_OPTIONS_EXEMPT = false$(EXEEXT) true.sh
10163 @item @option{subdir-objects}
10164 @cindex Options, @option{subdir-objects}
10165 @opindex subdir-objects
10166 If this option is specified, then objects are placed into the
10167 subdirectory of the build directory corresponding to the subdirectory of
10168 the source file. For instance, if the source file is
10169 @file{subdir/file.cxx}, then the output file would be
10170 @file{subdir/file.o}.
10172 In order to use this option with C sources, you should add
10173 @code{AM_PROG_CC_C_O} to @file{configure.ac}.
10175 @anchor{tar-formats}
10176 @item @option{tar-v7}
10177 @itemx @option{tar-ustar}
10178 @itemx @option{tar-pax}
10179 @cindex Option, @option{tar-v7}
10180 @cindex Option, @option{tar-ustar}
10181 @cindex Option, @option{tar-pax}
10182 @cindex @command{tar} formats
10183 @cindex v7 @command{tar} format
10184 @cindex ustar format
10190 These three mutually exclusive options select the tar format to use
10191 when generating tarballs with @samp{make dist}. (The tar file created
10192 is then compressed according to the set of @option{no-dist-gzip},
10193 @option{dist-bzip2}, @option{dist-lzip}, @option{dist-xz} and
10194 @option{dist-tarZ} options in use.)
10196 These options must be passed as arguments to @code{AM_INIT_AUTOMAKE}
10197 (@pxref{Macros}) because they can require additional configure checks.
10198 Automake will complain if it sees such options in an
10199 @code{AUTOMAKE_OPTIONS} variable.
10201 @option{tar-v7} selects the old V7 tar format. This is the historical
10202 default. This antiquated format is understood by all tar
10203 implementations and supports file names with up to 99 characters. When
10204 given longer file names some tar implementations will diagnose the
10205 problem while other will generate broken tarballs or use non-portable
10206 extensions. Furthermore, the V7 format cannot store empty
10207 directories. When using this format, consider using the
10208 @option{filename-length-max=99} option to catch file names too long.
10210 @option{tar-ustar} selects the ustar format defined by POSIX
10211 1003.1-1988. This format is believed to be old enough to be portable.
10212 It fully supports empty directories. It can store file names with up
10213 to 256 characters, provided that the file name can be split at
10214 directory separator in two parts, first of them being at most 155
10215 bytes long. So, in most cases the maximum file name length will be
10216 shorter than 256 characters. However you may run against broken tar
10217 implementations that incorrectly handle file names longer than 99
10218 characters (please report them to @email{@value{PACKAGE_BUGREPORT}} so we
10219 can document this accurately).
10221 @option{tar-pax} selects the new pax interchange format defined by POSIX
10222 1003.1-2001. It does not limit the length of file names. However,
10223 this format is very young and should probably be restricted to
10224 packages that target only very modern platforms. There are moves to
10225 change the pax format in an upward-compatible way, so this option may
10226 refer to a more recent version in the future.
10228 @xref{Formats, , Controlling the Archive Format, tar, GNU Tar}, for
10229 further discussion about tar formats.
10231 @command{configure} knows several ways to construct these formats. It
10232 will not abort if it cannot find a tool up to the task (so that the
10233 package can still be built), but @samp{make dist} will fail.
10235 @item @var{version}
10236 @cindex Option, @var{version}
10237 A version number (e.g., @samp{0.30}) can be specified. If Automake is not
10238 newer than the version specified, creation of the @file{Makefile.in}
10239 will be suppressed.
10241 @item @option{-W@var{category}} or @option{--warnings=@var{category}}
10242 @cindex Option, warnings
10243 @cindex Option, @option{-W@var{category}}
10244 @cindex Option, @option{--warnings=@var{category}}
10245 These options behave exactly like their command-line counterpart
10246 (@pxref{automake Invocation}). This allows you to enable or disable some
10247 warning categories on a per-file basis. You can also setup some warnings
10248 for your entire project; for instance, try @samp{AM_INIT_AUTOMAKE([-Wall])}
10249 in your @file{configure.ac}.
10253 Unrecognized options are diagnosed by @command{automake}.
10255 If you want an option to apply to all the files in the tree, you can use
10256 the @code{AM_INIT_AUTOMAKE} macro in @file{configure.ac}.
10260 @node Miscellaneous
10261 @chapter Miscellaneous Rules
10263 There are a few rules and variables that didn't fit anywhere else.
10266 * Tags:: Interfacing to cscope, etags and mkid
10267 * Suffixes:: Handling new file extensions
10272 @section Interfacing to @command{etags}
10274 @cindex @file{TAGS} support
10276 Automake will generate rules to generate @file{TAGS} files for use with
10277 GNU Emacs under some circumstances.
10280 If any C, C++ or Fortran 77 source code or headers are present, then
10281 @code{tags} and @code{TAGS} rules will be generated for the directory.
10282 All files listed using the @code{_SOURCES}, @code{_HEADERS}, and
10283 @code{_LISP} primaries will be used to generate tags. Note that
10284 generated source files that are not distributed must be declared in
10285 variables like @code{nodist_noinst_HEADERS} or
10286 @code{nodist_@var{prog}_SOURCES} or they will be ignored.
10288 A @code{tags} rule will be output at the topmost directory of a
10289 multi-directory package. When run from this topmost directory,
10290 @samp{make tags} will generate a @file{TAGS} file that includes by
10291 reference all @file{TAGS} files from subdirectories.
10293 The @code{tags} rule will also be generated if the variable
10294 @code{ETAGS_ARGS} is defined. This variable is intended for use in
10295 directories that contain taggable source that @command{etags} does
10296 not understand. The user can use the @code{ETAGSFLAGS} to pass
10297 additional flags to @command{etags}; @code{AM_ETAGSFLAGS} is also
10298 available for use in @file{Makefile.am}.
10301 @vindex AM_ETAGSFLAGS
10303 Here is how Automake generates tags for its source, and for nodes in its
10307 ETAGS_ARGS = automake.in --lang=none \
10308 --regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi
10311 If you add file names to @code{ETAGS_ARGS}, you will probably also
10312 want to define @code{TAGS_DEPENDENCIES}. The contents of this variable
10313 are added directly to the dependencies for the @code{tags} rule.
10314 @vindex TAGS_DEPENDENCIES
10316 Automake also generates a @code{ctags} rule that can be used to
10317 build @command{vi}-style @file{tags} files. The variable @code{CTAGS}
10318 is the name of the program to invoke (by default @command{ctags});
10319 @code{CTAGSFLAGS} can be used by the user to pass additional flags,
10320 and @code{AM_CTAGSFLAGS} can be used by the @file{Makefile.am}.
10323 Automake will also generate an @code{ID} rule that will run
10324 @command{mkid} on the source. This is only supported on a
10325 directory-by-directory basis.
10327 Similarly, the @code{cscope} rule will create a list of all the source
10328 files in the tree and run @command{cscope} to build an inverted index
10329 database. The variable @code{CSCOPE} is the name of the program to invoke
10330 (by default @command{cscope}); @code{CSCOPEFLAGS} and
10331 @code{CSCOPE_ARGS} can be used by the user to pass additional flags and
10332 file names respectively, while @code{AM_CSCOPEFLAGS} can be used by the
10333 @file{Makefile.am}. Note that, currently, the Automake-provided
10334 @code{cscope} support, when used in a VPATH build, might not work well
10335 with non-GNU make implementations (especially with make implementations
10336 performing @ref{Automatic Rule Rewriting, , VPATH rewrites, autoconf,
10337 The Autoconf Manual}).
10339 Finally, Automake also emits rules to support the
10340 @uref{http://www.gnu.org/software/global/, GNU Global Tags program}.
10341 The @code{GTAGS} rule runs Global Tags and puts the
10342 result in the top build directory. The variable @code{GTAGS_ARGS}
10343 holds arguments that are passed to @command{gtags}.
10348 @section Handling new file extensions
10350 @cindex Adding new @code{SUFFIXES}
10351 @cindex @code{SUFFIXES}, adding
10354 It is sometimes useful to introduce a new implicit rule to handle a file
10355 type that Automake does not know about.
10357 For instance, suppose you had a compiler that could compile @file{.foo}
10358 files to @file{.o} files. You would simply define a suffix rule for
10366 Then you could directly use a @file{.foo} file in a @code{_SOURCES}
10367 variable and expect the correct results:
10370 bin_PROGRAMS = doit
10371 doit_SOURCES = doit.foo
10374 This was the simpler and more common case. In other cases, you will
10375 have to help Automake to figure out which extensions you are defining your
10376 suffix rule for. This usually happens when your extension does not
10377 start with a dot. Then, all you have to do is to put a list of new
10378 suffixes in the @code{SUFFIXES} variable @strong{before} you define your
10381 For instance, the following definition prevents Automake from misinterpreting
10382 the @samp{.idlC.cpp:} rule as an attempt to transform @file{.idlC} files into
10385 @c Keep in sync with suffix7.sh
10387 SUFFIXES = .idl C.cpp
10392 As you may have noted, the @code{SUFFIXES} variable behaves like the
10393 @code{.SUFFIXES} special target of @command{make}. You should not touch
10394 @code{.SUFFIXES} yourself, but use @code{SUFFIXES} instead and let
10395 Automake generate the suffix list for @code{.SUFFIXES}. Any given
10396 @code{SUFFIXES} go at the start of the generated suffixes list, followed
10397 by Automake generated suffixes not already in the list.
10403 @cindex Including @file{Makefile} fragment
10404 @cindex @file{Makefile} fragment, including
10406 Automake supports an @code{include} directive that can be used to
10407 include other @file{Makefile} fragments when @command{automake} is run.
10408 Note that these fragments are read and interpreted by @command{automake},
10409 not by @command{make}. As with conditionals, @command{make} has no idea that
10410 @code{include} is in use.
10412 There are two forms of @code{include}:
10415 @item include $(srcdir)/file
10416 Include a fragment that is found relative to the current source
10419 @item include $(top_srcdir)/file
10420 Include a fragment that is found relative to the top source directory.
10423 Note that if a fragment is included inside a conditional, then the
10424 condition applies to the entire contents of that fragment.
10426 Makefile fragments included this way are always distributed because
10427 they are needed to rebuild @file{Makefile.in}.
10430 @chapter Conditionals
10432 @cindex Conditionals
10434 Automake supports a simple type of conditionals.
10436 These conditionals are not the same as conditionals in
10437 GNU Make. Automake conditionals are checked at configure time by the
10438 @file{configure} script, and affect the translation from
10439 @file{Makefile.in} to @file{Makefile}. They are based on options passed
10440 to @file{configure} and on results that @file{configure} has discovered
10441 about the host system. GNU Make conditionals are checked at @command{make}
10442 time, and are based on variables passed to the make program or defined
10443 in the @file{Makefile}.
10445 Automake conditionals will work with any make program.
10448 * Usage of Conditionals:: Declaring conditional content
10449 * Limits of Conditionals:: Enclosing complete statements
10452 @node Usage of Conditionals
10453 @section Usage of Conditionals
10455 @acindex AM_CONDITIONAL
10456 Before using a conditional, you must define it by using
10457 @code{AM_CONDITIONAL} in the @file{configure.ac} file (@pxref{Macros}).
10459 @defmac AM_CONDITIONAL (@var{conditional}, @var{condition})
10460 The conditional name, @var{conditional}, should be a simple string
10461 starting with a letter and containing only letters, digits, and
10462 underscores. It must be different from @samp{TRUE} and @samp{FALSE}
10463 that are reserved by Automake.
10465 The shell @var{condition} (suitable for use in a shell @code{if}
10466 statement) is evaluated when @command{configure} is run. Note that you
10467 must arrange for @emph{every} @code{AM_CONDITIONAL} to be invoked every
10468 time @command{configure} is run. If @code{AM_CONDITIONAL} is run
10469 conditionally (e.g., in a shell @code{if} statement), then the result
10470 will confuse @command{automake}.
10473 @cindex @option{--enable-debug}, example
10474 @cindex Example conditional @option{--enable-debug}
10475 @cindex Conditional example, @option{--enable-debug}
10477 Conditionals typically depend upon options that the user provides to
10478 the @command{configure} script. Here is an example of how to write a
10479 conditional that is true if the user uses the @option{--enable-debug}
10483 AC_ARG_ENABLE([debug],
10484 [ --enable-debug Turn on debugging],
10485 [case "$@{enableval@}" in
10488 *) AC_MSG_ERROR([bad value $@{enableval@} for --enable-debug]) ;;
10489 esac],[debug=false])
10490 AM_CONDITIONAL([DEBUG], [test x$debug = xtrue])
10493 Here is an example of how to use that conditional in @file{Makefile.am}:
10505 noinst_PROGRAMS = $(DBG)
10508 This trivial example could also be handled using @code{EXTRA_PROGRAMS}
10509 (@pxref{Conditional Programs}).
10511 You may only test a single variable in an @code{if} statement, possibly
10512 negated using @samp{!}. The @code{else} statement may be omitted.
10513 Conditionals may be nested to any depth. You may specify an argument to
10514 @code{else} in which case it must be the negation of the condition used
10515 for the current @code{if}. Similarly you may specify the condition
10516 that is closed on the @code{endif} line:
10527 Unbalanced conditions are errors. The @code{if}, @code{else}, and
10528 @code{endif} statements should not be indented, i.e., start on column
10531 The @code{else} branch of the above two examples could be omitted,
10532 since assigning the empty string to an otherwise undefined variable
10533 makes no difference.
10535 @acindex AM_COND_IF
10536 In order to allow access to the condition registered by
10537 @code{AM_CONDITIONAL} inside @file{configure.ac}, and to allow
10538 conditional @code{AC_CONFIG_FILES}, @code{AM_COND_IF} may be used:
10540 @defmac AM_COND_IF (@var{conditional}, @ovar{if-true}, @ovar{if-false})
10541 If @var{conditional} is fulfilled, execute @var{if-true}, otherwise
10542 execute @var{if-false}. If either branch contains @code{AC_CONFIG_FILES},
10543 it will cause @command{automake} to output the rules for the respective
10544 files only for the given condition.
10547 @code{AM_COND_IF} macros may be nested when m4 quotation is used
10548 properly (@pxref{M4 Quotation, ,, autoconf, The Autoconf Manual}).
10550 @cindex Example conditional @code{AC_CONFIG_FILES}
10551 @cindex @code{AC_CONFIG_FILES}, conditional
10553 Here is an example of how to define a conditional config file:
10556 AM_CONDITIONAL([SHELL_WRAPPER], [test "x$with_wrapper" = xtrue])
10557 AM_COND_IF([SHELL_WRAPPER],
10558 [AC_CONFIG_FILES([wrapper:wrapper.in])])
10561 @node Limits of Conditionals
10562 @section Limits of Conditionals
10564 Conditionals should enclose complete statements like variables or
10565 rules definitions. Automake cannot deal with conditionals used inside
10566 a variable definition, for instance, and is not even able to diagnose
10567 this situation. The following example would not work:
10570 # This syntax is not understood by Automake
10579 However the intended definition of @code{AM_CPPFLAGS} can be achieved
10584 DEBUGFLAGS = -DDEBUG
10586 AM_CPPFLAGS = -DFEATURE_A $(DEBUGFLAGS) -DFEATURE_B
10593 AM_CPPFLAGS = -DFEATURE_A
10595 AM_CPPFLAGS += -DDEBUG
10597 AM_CPPFLAGS += -DFEATURE_B
10600 More details and examples of conditionals are described alongside
10601 various Automake features in this manual (@pxref{Conditional
10602 Subdirectories}, @pxref{Conditional Sources}, @pxref{Conditional
10603 Programs}, @pxref{Conditional Libtool Libraries}, @pxref{Conditional
10606 @node Silencing Make
10607 @chapter Silencing @command{make}
10609 @cindex Silent @command{make}
10610 @cindex Silencing @command{make}
10611 @cindex Silent rules
10612 @cindex Silent @command{make} rules
10615 * Make verbosity:: Make is verbose by default
10616 * Tricks For Silencing Make:: Standard and generic ways to silence make
10617 * Automake Silent Rules:: How Automake can help in silencing make
10620 @node Make verbosity
10621 @section Make is verbose by default
10623 Normally, when executing the set of rules associated with a target,
10624 @command{make} prints each rule before it is executed. This behaviour,
10625 while having been in place for a long time, and being even mandated by
10626 the POSIX standard, starkly violates the ``silence is golden'' UNIX
10627 principle@footnote{See also
10628 @uref{http://catb.org/~esr/writings/taoup/html/ch11s09.html}.}:
10631 When a program has nothing interesting or surprising to say, it should
10632 say nothing. Well-behaved Unix programs do their jobs unobtrusively,
10633 with a minimum of fuss and bother. Silence is golden.
10636 In fact, while such verbosity of @command{make} can theoretically be
10637 useful to track bugs and understand reasons of failures right away, it
10638 can also hide warning and error messages from @command{make}-invoked
10639 tools, drowning them in a flood of uninteresting and seldom useful
10640 messages, and thus allowing them to go easily undetected.
10642 This problem can be very annoying, especially for developers, who usually
10643 know quite well what's going on behind the scenes, and for whom the
10644 verbose output from @command{make} ends up being mostly noise that hampers
10645 the easy detection of potentially important warning messages.
10647 @node Tricks For Silencing Make
10648 @section Standard and generic ways to silence make
10650 Here we describe some common idioms/tricks to obtain a quieter make
10651 output, with their relative advantages and drawbacks. In the next
10652 section (@ref{Automake Silent Rules}) we'll see how Automake can help
10653 in this respect, providing more elaborate and flexible idioms.
10657 @item @command{make -s}
10659 This simply causes @command{make} not to print @emph{any} rule before
10662 The @option{-s} flag is mandated by POSIX, universally supported, and
10663 its purpose and function are easy to understand.
10665 But it also has its serious limitations too. First of all, it embodies
10666 an ``all or nothing'' strategy, i.e., either everything is silenced, or
10667 nothing is; this lack of granularity can sometimes be a fatal flaw.
10668 Moreover, when the @option{-s} flag is used, the @command{make} output
10669 might turn out to be too much terse; in case of errors, the user won't
10670 be able to easily see what rule or command have caused them, or even,
10671 in case of tools with poor error reporting, what the errors were!
10673 @item @command{make >/dev/null || make}
10675 Apparently, this perfectly obeys the ``silence is golden'' rule: warnings
10676 from stderr are passed through, output reporting is done only in case of
10677 error, and in that case it should provide a verbose-enough report to allow
10678 an easy determination of the error location and causes.
10680 However, calling @command{make} two times in a row might hide errors
10681 (especially intermittent ones), or subtly change the expected semantic
10682 of the @command{make} calls --- things these which can clearly make
10683 debugging and error assessment very difficult.
10685 @item @command{make --no-print-directory}
10687 This is GNU @command{make} specific. When called with the
10688 @option{--no-print-directory} option, GNU @command{make} will disable
10689 printing of the working directory by invoked sub-@command{make}s (the
10690 well-known ``@i{Entering/Leaving directory ...}'' messages). This helps
10691 to decrease the verbosity of the output, but experience has shown that
10692 it can also often render debugging considerably harder in projects using
10693 deeply-nested @command{make} recursion.
10695 As an aside, notice that the @option{--no-print-directory} option is
10696 automatically activated if the @option{-s} flag is used.
10698 @c TODO: Other tricks?
10699 @c TODO: Maybe speak about the @code{.SILENT} target?
10700 @c TODO: - Pros: More granularity on what to silence.
10701 @c TODO: - Cons: No easy way to temporarily override.
10705 @node Automake Silent Rules
10706 @section How Automake can help in silencing make
10708 The tricks and idioms for silencing @command{make} described in the
10709 previous section can be useful from time to time, but we've seen that
10710 they all have their serious drawbacks and limitations. That's why
10711 automake provides support for a more advanced and flexible way of
10712 obtaining quieter output from @command{make} (for most rules at least).
10714 @c TODO: Maybe describe in brief the precedent set by the build system
10715 @c of the Linux Kernel, from which Automake took inspiration ... Links?
10717 To give the gist of what Automake can do in this respect, here is a simple
10718 comparison between a typical @command{make} output (where silent rules
10719 are disabled) and one with silent rules enabled:
10722 % @kbd{cat Makefile.am}
10724 foo_SOURCES = main.c func.c
10726 int main (void) @{ return func (); @} /* func used undeclared */
10728 int func (void) @{ int i; return i; @} /* i used uninitialized */
10730 @i{The make output is by default very verbose. This causes warnings
10731 from the compiler to be somewhat hidden, and not immediate to spot.}
10732 % @kbd{make CFLAGS=-Wall}
10733 gcc -DPACKAGE_NAME=\"foo\" -DPACKAGE_TARNAME=\"foo\" ...
10734 -DPACKAGE_STRING=\"foo\ 1.0\" -DPACKAGE_BUGREPORT=\"\" ...
10735 -DPACKAGE=\"foo\" -DVERSION=\"1.0\" -I. -Wall -MT main.o
10736 -MD -MP -MF .deps/main.Tpo -c -o main.o main.c
10737 main.c: In function ‘main’:
10738 main.c:3:3: warning: implicit declaration of function ‘func’
10739 mv -f .deps/main.Tpo .deps/main.Po
10740 gcc -DPACKAGE_NAME=\"foo\" -DPACKAGE_TARNAME=\"foo\" ...
10741 -DPACKAGE_STRING=\"foo\ 1.0\" -DPACKAGE_BUGREPORT=\"\" ...
10742 -DPACKAGE=\"foo\" -DVERSION=\"1.0\" -I. -Wall -MT func.o
10743 -MD -MP -MF .deps/func.Tpo -c -o func.o func.c
10744 func.c: In function ‘func’:
10745 func.c:4:3: warning: ‘i’ used uninitialized in this function
10746 mv -f .deps/func.Tpo .deps/func.Po
10747 gcc -Wall -o foo main.o func.o
10749 @i{Clean up, so that we we can rebuild everything from scratch.}
10751 test -z "foo" || rm -f foo
10754 @i{Silent rules enabled: the output is minimal but informative. In
10755 particular, the warnings from the compiler stick out very clearly.}
10756 % @kbd{make V=0 CFLAGS=-Wall}
10758 main.c: In function ‘main’:
10759 main.c:3:3: warning: implicit declaration of function ‘func’
10761 func.c: In function ‘func’:
10762 func.c:4:3: warning: ‘i’ used uninitialized in this function
10766 @cindex silent rules and libtool
10767 Also, in projects using @command{libtool}, the use of silent rules can
10768 automatically enable the @command{libtool}'s @option{--silent} option:
10771 % @kbd{cat Makefile.am}
10772 lib_LTLIBRARIES = libx.la
10774 % @kbd{make # Both make and libtool are verbose by default.}
10776 libtool: compile: gcc -DPACKAGE_NAME=\"foo\" ... -DLT_OBJDIR=\".libs/\"
10777 -I. -g -O2 -MT libx.lo -MD -MP -MF .deps/libx.Tpo -c libx.c -fPIC
10778 -DPIC -o .libs/libx.o
10779 mv -f .deps/libx.Tpo .deps/libx.Plo
10780 /bin/sh ./libtool --tag=CC --mode=link gcc -g -O2 -o libx.la -rpath
10781 /usr/local/lib libx.lo
10782 libtool: link: gcc -shared .libs/libx.o -Wl,-soname -Wl,libx.so.0
10783 -o .libs/libx.so.0.0.0
10784 libtool: link: cd .libs && rm -f libx.so && ln -s libx.so.0.0.0 libx.so
10792 For Automake-generated @file{Makefile}s, the user may influence the
10793 verbosity at @command{configure} run time as well as at @command{make}
10798 @opindex --enable-silent-rules
10799 @opindex --disable-silent-rules
10800 Passing @option{--enable-silent-rules} to @command{configure} will cause
10801 build rules to be less verbose; the option @option{--disable-silent-rules}
10802 will cause normal verbose output.
10805 At @command{make} run time, the default chosen at @command{configure}
10806 time may be overridden: @code{make V=1} will produce verbose output,
10807 @code{make V=0} less verbose output.
10810 @cindex default verbosity for silent rules
10811 Note that silent rules are @emph{disabled} by default; the user must
10812 enable them explicitly at either @command{configure} run time or at
10813 @command{make} run time. We think that this is a good policy, since
10814 it provides the casual user with enough information to prepare a good
10815 bug report in case anything breaks.
10817 Still, notwithstanding the rationales above, a developer who really
10818 wants to make silent rules enabled by default in his own package can
10819 do so by calling @code{AM_SILENT_RULES([yes])} in @file{configure.ac}.
10821 @c Keep in sync with silent-configsite.sh
10822 Users who prefer to have silent rules enabled by default can edit their
10823 @file{config.site} file to make the variable @code{enable_silent_rules}
10824 default to @samp{yes}. This should still allow disabling silent rules
10825 at @command{configure} time and at @command{make} time.
10827 @c FIXME: there's really a need to specify this explicitly?
10828 For portability to different @command{make} implementations, package authors
10829 are advised to not set the variable @code{V} inside the @file{Makefile.am}
10830 file, to allow the user to override the value for subdirectories as well.
10832 To work at its best, the current implementation of this feature normally
10833 uses nested variable expansion @samp{$(@var{var1}$(V))}, a @file{Makefile}
10834 feature that is not required by POSIX 2008 but is widely supported in
10835 practice. On the rare @command{make} implementations that do not support
10836 nested variable expansion, whether rules are silent is always determined at
10837 configure time, and cannot be overridden at make time. Future versions of
10838 POSIX are likely to require nested variable expansion, so this minor
10839 limitation should go away with time.
10841 @vindex @code{AM_V_GEN}
10842 @vindex @code{AM_V_at}
10843 @vindex @code{AM_DEFAULT_VERBOSITY}
10844 @vindex @code{AM_V}
10845 @vindex @code{AM_DEFAULT_V}
10846 To extend the silent mode to your own rules, you have two choices:
10850 You can use the predefined variable @code{AM_V_GEN} as a prefix to
10851 commands that should output a status line in silent mode, and
10852 @code{AM_V_at} as a prefix to commands that should not output anything
10853 in silent mode. When output is to be verbose, both of these variables
10854 will expand to the empty string.
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 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 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 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 host 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 outputs 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 Actually, calls to such tools are all wrapped into a call to the
11570 @command{missing} script discussed later (@pxref{maintainer-mode}).
11571 @command{missing} will take care of fixing the timestamps when these
11572 tools are not installed, so that the build can continue.
11575 In distributed development, developers are likely to have different
11576 version of the maintainer tools installed. In this case rebuilds
11577 triggered by timestamp lossage will lead to spurious changes
11578 to generated files. There are several solutions to this:
11582 All developers should use the same versions, so that the rebuilt files
11583 are identical to files in CVS@. (This starts to be difficult when each
11584 project you work on uses different versions.)
11586 Or people use a script to fix the timestamp after a checkout (the GCC
11587 folks have such a script).
11589 Or @file{configure.ac} uses @code{AM_MAINTAINER_MODE}, which will
11590 disable all these rebuild rules by default. This is further discussed
11591 in @ref{maintainer-mode}.
11595 Although we focused on spurious rebuilds, the converse can also
11596 happen. CVS's timestamp handling can also let you think an
11597 out-of-date file is up-to-date.
11599 For instance, suppose a developer has modified @file{Makefile.am} and
11600 has rebuilt @file{Makefile.in}, and then decides to do a last-minute
11601 change to @file{Makefile.am} right before checking in both files
11602 (without rebuilding @file{Makefile.in} to account for the change).
11604 This last change to @file{Makefile.am} makes the copy of
11605 @file{Makefile.in} out-of-date. Since CVS processes files
11606 alphabetically, when another developer @samp{cvs update}s his or her
11607 tree, @file{Makefile.in} will happen to be newer than
11608 @file{Makefile.am}. This other developer will not see that
11609 @file{Makefile.in} is out-of-date.
11613 @subsubheading Generated Files out of CVS
11615 One way to get CVS and @command{make} working peacefully is to never
11616 store generated files in CVS, i.e., do not CVS-control files that
11617 are @file{Makefile} targets (also called @emph{derived} files).
11619 This way developers are not annoyed by changes to generated files. It
11620 does not matter if they all have different versions (assuming they are
11621 compatible, of course). And finally, timestamps are not lost, changes
11622 to sources files can't be missed as in the
11623 @file{Makefile.am}/@file{Makefile.in} example discussed earlier.
11625 The drawback is that the CVS repository is not an exact copy of what
11626 is distributed and that users now need to install various development
11627 tools (maybe even specific versions) before they can build a checkout.
11628 But, after all, CVS's job is versioning, not distribution.
11630 Allowing developers to use different versions of their tools can also
11631 hide bugs during distributed development. Indeed, developers will be
11632 using (hence testing) their own generated files, instead of the
11633 generated files that will be released actually. The developer who
11634 prepares the tarball might be using a version of the tool that
11635 produces bogus output (for instance a non-portable C file), something
11636 other developers could have noticed if they weren't using their own
11637 versions of this tool.
11639 @subheading Third-party Files
11640 @cindex CVS and third-party files
11641 @cindex third-party files and CVS
11643 Another class of files not discussed here (because they do not cause
11644 timestamp issues) are files that are shipped with a package, but
11645 maintained elsewhere. For instance, tools like @command{gettextize}
11646 and @command{autopoint} (from Gettext) or @command{libtoolize} (from
11647 Libtool), will install or update files in your package.
11649 These files, whether they are kept under CVS or not, raise similar
11650 concerns about version mismatch between developers' tools. The
11651 Gettext manual has a section about this, see @ref{CVS Issues, CVS
11652 Issues, Integrating with CVS, gettext, GNU gettext tools}.
11654 @node maintainer-mode
11655 @section @command{missing} and @code{AM_MAINTAINER_MODE}
11657 @subheading @command{missing}
11658 @cindex @command{missing}, purpose
11660 The @command{missing} script is a wrapper around several maintainer
11661 tools, designed to warn users if a maintainer tool is required but
11662 missing. Typical maintainer tools are @command{autoconf},
11663 @command{automake}, @command{bison}, etc. Because file generated by
11664 these tools are shipped with the other sources of a package, these
11665 tools shouldn't be required during a user build and they are not
11666 checked for in @file{configure}.
11668 However, if for some reason a rebuild rule is triggered and involves a
11669 missing tool, @command{missing} will notice it and warn the user.
11670 Besides the warning, when a tool is missing, @command{missing} will
11671 attempt to fix timestamps in a way that allows the build to continue.
11672 For instance, @command{missing} will touch @file{configure} if
11673 @command{autoconf} is not installed. When all distributed files are
11674 kept under version control, this feature of @command{missing} allows a
11675 user @emph{with no maintainer tools} to build a package off its version
11676 control repository, bypassing any timestamp inconsistency (implied by
11677 e.g.@: @samp{cvs update} or @samp{git clone}).
11679 If the required tool is installed, @command{missing} will run it and
11680 won't attempt to continue after failures. This is correct during
11681 development: developers love fixing failures. However, users with
11682 wrong versions of maintainer tools may get an error when the rebuild
11683 rule is spuriously triggered, halting the build. This failure to let
11684 the build continue is one of the arguments of the
11685 @code{AM_MAINTAINER_MODE} advocates.
11687 @subheading @code{AM_MAINTAINER_MODE}
11688 @cindex @code{AM_MAINTAINER_MODE}, purpose
11689 @acindex AM_MAINTAINER_MODE
11691 @code{AM_MAINTAINER_MODE} allows you to choose whether the so called
11692 "rebuild rules" should be enabled or disabled. With
11693 @code{AM_MAINTAINER_MODE([enable])}, they are enabled by default,
11694 otherwise they are disabled by default. In the latter case, if
11695 you have @code{AM_MAINTAINER_MODE} in @file{configure.ac}, and run
11696 @samp{./configure && make}, then @command{make} will *never* attempt to
11697 rebuild @file{configure}, @file{Makefile.in}s, Lex or Yacc outputs, etc.
11698 I.e., this disables build rules for files that are usually distributed
11699 and that users should normally not have to update.
11701 The user can override the default setting by passing either
11702 @samp{--enable-maintainer-mode} or @samp{--disable-maintainer-mode}
11703 to @command{configure}.
11705 People use @code{AM_MAINTAINER_MODE} either because they do not want their
11706 users (or themselves) annoyed by timestamps lossage (@pxref{CVS}), or
11707 because they simply can't stand the rebuild rules and prefer running
11708 maintainer tools explicitly.
11710 @code{AM_MAINTAINER_MODE} also allows you to disable some custom build
11711 rules conditionally. Some developers use this feature to disable
11712 rules that need exotic tools that users may not have available.
11714 Several years ago Fran@,{c}ois Pinard pointed out several arguments
11715 against this @code{AM_MAINTAINER_MODE} macro. Most of them relate to
11716 insecurity. By removing dependencies you get non-dependable builds:
11717 changes to sources files can have no effect on generated files and this
11718 can be very confusing when unnoticed. He adds that security shouldn't
11719 be reserved to maintainers (what @option{--enable-maintainer-mode}
11720 suggests), on the contrary. If one user has to modify a
11721 @file{Makefile.am}, then either @file{Makefile.in} should be updated
11722 or a warning should be output (this is what Automake uses
11723 @command{missing} for) but the last thing you want is that nothing
11724 happens and the user doesn't notice it (this is what happens when
11725 rebuild rules are disabled by @code{AM_MAINTAINER_MODE}).
11727 Jim Meyering, the inventor of the @code{AM_MAINTAINER_MODE} macro was
11728 swayed by Fran@,{c}ois's arguments, and got rid of
11729 @code{AM_MAINTAINER_MODE} in all of his packages.
11731 Still many people continue to use @code{AM_MAINTAINER_MODE}, because
11732 it helps them working on projects where all files are kept under version
11733 control, and because @command{missing} isn't enough if you have the
11734 wrong version of the tools.
11738 @section Why doesn't Automake support wildcards?
11741 Developers are lazy. They would often like to use wildcards in
11742 @file{Makefile.am}s, so that they would not need to remember to
11743 update @file{Makefile.am}s every time they add, delete, or rename
11746 There are several objections to this:
11749 When using CVS (or similar) developers need to remember they have to
11750 run @samp{cvs add} or @samp{cvs rm} anyway. Updating
11751 @file{Makefile.am} accordingly quickly becomes a reflex.
11753 Conversely, if your application doesn't compile
11754 because you forgot to add a file in @file{Makefile.am}, it will help
11755 you remember to @samp{cvs add} it.
11758 Using wildcards makes it easy to distribute files by mistake. For
11759 instance, some code a developer is experimenting with (a test case,
11760 say) that should not be part of the distribution.
11763 Using wildcards it's easy to omit some files by mistake. For
11764 instance, one developer creates a new file, uses it in many places,
11765 but forgets to commit it. Another developer then checks out the
11766 incomplete project and is able to run @samp{make dist} successfully,
11767 even though a file is missing. By listing files, @samp{make dist}
11768 @emph{will} complain.
11771 Wildcards are not portable to some non-GNU @command{make} implementations,
11772 e.g., NetBSD @command{make} will not expand globs such as @samp{*} in
11773 prerequisites of a target.
11776 Finally, it's really hard to @emph{forget} to add a file to
11777 @file{Makefile.am}: files that are not listed in @file{Makefile.am} are
11778 not compiled or installed, so you can't even test them.
11781 Still, these are philosophical objections, and as such you may disagree,
11782 or find enough value in wildcards to dismiss all of them. Before you
11783 start writing a patch against Automake to teach it about wildcards,
11784 let's see the main technical issue: portability.
11786 Although @samp{$(wildcard ...)} works with GNU @command{make}, it is
11787 not portable to other @command{make} implementations.
11789 The only way Automake could support @command{$(wildcard ...)} is by
11790 expending @command{$(wildcard ...)} when @command{automake} is run.
11791 The resulting @file{Makefile.in}s would be portable since they would
11792 list all files and not use @samp{$(wildcard ...)}. However that
11793 means developers would need to remember to run @command{automake} each
11794 time they add, delete, or rename files.
11796 Compared to editing @file{Makefile.am}, this is a very small gain. Sure,
11797 it's easier and faster to type @samp{automake; make} than to type
11798 @samp{emacs Makefile.am; make}. But nobody bothered enough to write a
11799 patch to add support for this syntax. Some people use scripts to
11800 generate file lists in @file{Makefile.am} or in separate
11801 @file{Makefile} fragments.
11803 Even if you don't care about portability, and are tempted to use
11804 @samp{$(wildcard ...)} anyway because you target only GNU Make, you
11805 should know there are many places where Automake needs to know exactly
11806 which files should be processed. As Automake doesn't know how to
11807 expand @samp{$(wildcard ...)}, you cannot use it in these places.
11808 @samp{$(wildcard ...)} is a black box comparable to @code{AC_SUBST}ed
11809 variables as far Automake is concerned.
11811 You can get warnings about @samp{$(wildcard ...}) constructs using the
11812 @option{-Wportability} flag.
11814 @node Limitations on File Names
11815 @section Limitations on File Names
11816 @cindex file names, limitations on
11818 Automake attempts to support all kinds of file names, even those that
11819 contain unusual characters or are unusually long. However, some
11820 limitations are imposed by the underlying operating system and tools.
11822 Most operating systems prohibit the use of the null byte in file
11823 names, and reserve @samp{/} as a directory separator. Also, they
11824 require that file names are properly encoded for the user's locale.
11825 Automake is subject to these limits.
11827 Portable packages should limit themselves to POSIX file
11828 names. These can contain ASCII letters and digits,
11829 @samp{_}, @samp{.}, and @samp{-}. File names consist of components
11830 separated by @samp{/}. File name components cannot begin with
11833 Portable POSIX file names cannot contain components that exceed a
11834 14-byte limit, but nowadays it's normally safe to assume the
11835 more-generous XOPEN limit of 255 bytes. POSIX
11836 limits file names to 255 bytes (XOPEN allows 1023 bytes),
11837 but you may want to limit a source tarball to file names of 99 bytes
11838 to avoid interoperability problems with old versions of @command{tar}.
11840 If you depart from these rules (e.g., by using non-ASCII
11841 characters in file names, or by using lengthy file names), your
11842 installers may have problems for reasons unrelated to Automake.
11843 However, if this does not concern you, you should know about the
11844 limitations imposed by Automake itself. These limitations are
11845 undesirable, but some of them seem to be inherent to underlying tools
11846 like Autoconf, Make, M4, and the shell. They fall into three
11847 categories: install directories, build directories, and file names.
11849 The following characters:
11852 @r{newline} " # $ ' `
11855 should not appear in the names of install directories. For example,
11856 the operand of @command{configure}'s @option{--prefix} option should
11857 not contain these characters.
11859 Build directories suffer the same limitations as install directories,
11860 and in addition should not contain the following characters:
11866 For example, the full name of the directory containing the source
11867 files should not contain these characters.
11869 Source and installation file names like @file{main.c} are limited even
11870 further: they should conform to the POSIX/XOPEN
11871 rules described above. In addition, if you plan to port to
11872 non-POSIX environments, you should avoid file names that
11873 differ only in case (e.g., @file{makefile} and @file{Makefile}).
11874 Nowadays it is no longer worth worrying about the 8.3 limits of
11877 @c FIXME This should probably be moved in the "Checking the Distribution"
11878 @c FIXME section...
11879 @node Errors with distclean
11880 @section Errors with distclean
11881 @cindex @code{distclean}, diagnostic
11882 @cindex @samp{make distclean}, diagnostic
11883 @cindex dependencies and distributed files
11886 This is a diagnostic you might encounter while running @samp{make
11889 As explained in @ref{Checking the Distribution}, @samp{make distcheck}
11890 attempts to build and check your package for errors like this one.
11892 @samp{make distcheck} will perform a @code{VPATH} build of your
11893 package (@pxref{VPATH Builds}), and then call @samp{make distclean}.
11894 Files left in the build directory after @samp{make distclean} has run
11895 are listed after this error.
11897 This diagnostic really covers two kinds of errors:
11901 files that are forgotten by distclean;
11903 distributed files that are erroneously rebuilt.
11906 The former left-over files are not distributed, so the fix is to mark
11907 them for cleaning (@pxref{Clean}), this is obvious and doesn't deserve
11910 The latter bug is not always easy to understand and fix, so let's
11911 proceed with an example. Suppose our package contains a program for
11912 which we want to build a man page using @command{help2man}. GNU
11913 @command{help2man} produces simple manual pages from the @option{--help}
11914 and @option{--version} output of other commands (@pxref{Top, , Overview,
11915 help2man, The Help2man Manual}). Because we don't want to force our
11916 users to install @command{help2man}, we decide to distribute the
11917 generated man page using the following setup.
11920 # This Makefile.am is bogus.
11922 foo_SOURCES = foo.c
11923 dist_man_MANS = foo.1
11925 foo.1: foo$(EXEEXT)
11926 help2man --output=foo.1 ./foo$(EXEEXT)
11929 This will effectively distribute the man page. However,
11930 @samp{make distcheck} will fail with:
11933 ERROR: files left in build directory after distclean:
11937 Why was @file{foo.1} rebuilt? Because although distributed,
11938 @file{foo.1} depends on a non-distributed built file:
11939 @file{foo$(EXEEXT)}. @file{foo$(EXEEXT)} is built by the user, so it
11940 will always appear to be newer than the distributed @file{foo.1}.
11942 @samp{make distcheck} caught an inconsistency in our package. Our
11943 intent was to distribute @file{foo.1} so users do not need to install
11944 @command{help2man}, however since this rule causes this file to be
11945 always rebuilt, users @emph{do} need @command{help2man}. Either we
11946 should ensure that @file{foo.1} is not rebuilt by users, or there is
11947 no point in distributing @file{foo.1}.
11949 More generally, the rule is that distributed files should never depend
11950 on non-distributed built files. If you distribute something
11951 generated, distribute its sources.
11953 One way to fix the above example, while still distributing
11954 @file{foo.1} is to not depend on @file{foo$(EXEEXT)}. For instance,
11955 assuming @command{foo --version} and @command{foo --help} do not
11956 change unless @file{foo.c} or @file{configure.ac} change, we could
11957 write the following @file{Makefile.am}:
11961 foo_SOURCES = foo.c
11962 dist_man_MANS = foo.1
11964 foo.1: foo.c $(top_srcdir)/configure.ac
11965 $(MAKE) $(AM_MAKEFLAGS) foo$(EXEEXT)
11966 help2man --output=foo.1 ./foo$(EXEEXT)
11969 This way, @file{foo.1} will not get rebuilt every time
11970 @file{foo$(EXEEXT)} changes. The @command{make} call makes sure
11971 @file{foo$(EXEEXT)} is up-to-date before @command{help2man}. Another
11972 way to ensure this would be to use separate directories for binaries
11973 and man pages, and set @code{SUBDIRS} so that binaries are built
11976 We could also decide not to distribute @file{foo.1}. In
11977 this case it's fine to have @file{foo.1} dependent upon
11978 @file{foo$(EXEEXT)}, since both will have to be rebuilt.
11979 However it would be impossible to build the package in a
11980 cross-compilation, because building @file{foo.1} involves
11981 an @emph{execution} of @file{foo$(EXEEXT)}.
11983 Another context where such errors are common is when distributed files
11984 are built by tools that are built by the package. The pattern is
11988 distributed-file: built-tools distributed-sources
11993 should be changed to
11996 distributed-file: distributed-sources
11997 $(MAKE) $(AM_MAKEFLAGS) built-tools
12002 or you could choose not to distribute @file{distributed-file}, if
12003 cross-compilation does not matter.
12005 The points made through these examples are worth a summary:
12010 Distributed files should never depend upon non-distributed built
12013 Distributed files should be distributed with all their dependencies.
12015 If a file is @emph{intended} to be rebuilt by users, then there is no point
12016 in distributing it.
12020 @vrindex distcleancheck_listfiles
12021 For desperate cases, it's always possible to disable this check by
12022 setting @code{distcleancheck_listfiles} as documented in @ref{Checking
12024 Make sure you do understand the reason why @samp{make distcheck}
12025 complains before you do this. @code{distcleancheck_listfiles} is a
12026 way to @emph{hide} errors, not to fix them. You can always do better.
12028 @node Flag Variables Ordering
12029 @section Flag Variables Ordering
12030 @cindex Ordering flag variables
12031 @cindex Flag variables, ordering
12034 What is the difference between @code{AM_CFLAGS}, @code{CFLAGS}, and
12035 @code{mumble_CFLAGS}?
12039 Why does @command{automake} output @code{CPPFLAGS} after
12040 @code{AM_CPPFLAGS} on compile lines? Shouldn't it be the converse?
12044 My @file{configure} adds some warning flags into @code{CXXFLAGS}. In
12045 one @file{Makefile.am} I would like to append a new flag, however if I
12046 put the flag into @code{AM_CXXFLAGS} it is prepended to the other
12047 flags, not appended.
12050 @subheading Compile Flag Variables
12051 @cindex Flag Variables, Ordering
12052 @cindex Compile Flag Variables
12053 @cindex @code{AM_CCASFLAGS} and @code{CCASFLAGS}
12054 @cindex @code{AM_CFLAGS} and @code{CFLAGS}
12055 @cindex @code{AM_CPPFLAGS} and @code{CPPFLAGS}
12056 @cindex @code{AM_CXXFLAGS} and @code{CXXFLAGS}
12057 @cindex @code{AM_FCFLAGS} and @code{FCFLAGS}
12058 @cindex @code{AM_FFLAGS} and @code{FFLAGS}
12059 @cindex @code{AM_GCJFLAGS} and @code{GCJFLAGS}
12060 @cindex @code{AM_LDFLAGS} and @code{LDFLAGS}
12061 @cindex @code{AM_LFLAGS} and @code{LFLAGS}
12062 @cindex @code{AM_LIBTOOLFLAGS} and @code{LIBTOOLFLAGS}
12063 @cindex @code{AM_OBJCFLAGS} and @code{OBJCFLAGS}
12064 @cindex @code{AM_OBJCXXFLAGS} and @code{OBJXXCFLAGS}
12065 @cindex @code{AM_RFLAGS} and @code{RFLAGS}
12066 @cindex @code{AM_UPCFLAGS} and @code{UPCFLAGS}
12067 @cindex @code{AM_YFLAGS} and @code{YFLAGS}
12068 @cindex @code{CCASFLAGS} and @code{AM_CCASFLAGS}
12069 @cindex @code{CFLAGS} and @code{AM_CFLAGS}
12070 @cindex @code{CPPFLAGS} and @code{AM_CPPFLAGS}
12071 @cindex @code{CXXFLAGS} and @code{AM_CXXFLAGS}
12072 @cindex @code{FCFLAGS} and @code{AM_FCFLAGS}
12073 @cindex @code{FFLAGS} and @code{AM_FFLAGS}
12074 @cindex @code{GCJFLAGS} and @code{AM_GCJFLAGS}
12075 @cindex @code{LDFLAGS} and @code{AM_LDFLAGS}
12076 @cindex @code{LFLAGS} and @code{AM_LFLAGS}
12077 @cindex @code{LIBTOOLFLAGS} and @code{AM_LIBTOOLFLAGS}
12078 @cindex @code{OBJCFLAGS} and @code{AM_OBJCFLAGS}
12079 @cindex @code{OBJCXXFLAGS} and @code{AM_OBJCXXFLAGS}
12080 @cindex @code{RFLAGS} and @code{AM_RFLAGS}
12081 @cindex @code{UPCFLAGS} and @code{AM_UPCFLAGS}
12082 @cindex @code{YFLAGS} and @code{AM_YFLAGS}
12084 This section attempts to answer all the above questions. We will
12085 mostly discuss @code{CPPFLAGS} in our examples, but actually the
12086 answer holds for all the compile flags used in Automake:
12087 @code{CCASFLAGS}, @code{CFLAGS}, @code{CPPFLAGS}, @code{CXXFLAGS},
12088 @code{FCFLAGS}, @code{FFLAGS}, @code{GCJFLAGS}, @code{LDFLAGS},
12089 @code{LFLAGS}, @code{LIBTOOLFLAGS}, @code{OBJCFLAGS}, @code{OBJCXXFLAGS},
12090 @code{RFLAGS}, @code{UPCFLAGS}, and @code{YFLAGS}.
12092 @code{CPPFLAGS}, @code{AM_CPPFLAGS}, and @code{mumble_CPPFLAGS} are
12093 three variables that can be used to pass flags to the C preprocessor
12094 (actually these variables are also used for other languages like C++
12095 or preprocessed Fortran). @code{CPPFLAGS} is the user variable
12096 (@pxref{User Variables}), @code{AM_CPPFLAGS} is the Automake variable,
12097 and @code{mumble_CPPFLAGS} is the variable specific to the
12098 @code{mumble} target (we call this a per-target variable,
12099 @pxref{Program and Library Variables}).
12101 Automake always uses two of these variables when compiling C sources
12102 files. When compiling an object file for the @code{mumble} target,
12103 the first variable will be @code{mumble_CPPFLAGS} if it is defined, or
12104 @code{AM_CPPFLAGS} otherwise. The second variable is always
12107 In the following example,
12110 bin_PROGRAMS = foo bar
12111 foo_SOURCES = xyz.c
12112 bar_SOURCES = main.c
12113 foo_CPPFLAGS = -DFOO
12114 AM_CPPFLAGS = -DBAZ
12118 @file{xyz.o} will be compiled with @samp{$(foo_CPPFLAGS) $(CPPFLAGS)},
12119 (because @file{xyz.o} is part of the @code{foo} target), while
12120 @file{main.o} will be compiled with @samp{$(AM_CPPFLAGS) $(CPPFLAGS)}
12121 (because there is no per-target variable for target @code{bar}).
12123 The difference between @code{mumble_CPPFLAGS} and @code{AM_CPPFLAGS}
12124 being clear enough, let's focus on @code{CPPFLAGS}. @code{CPPFLAGS}
12125 is a user variable, i.e., a variable that users are entitled to modify
12126 in order to compile the package. This variable, like many others,
12127 is documented at the end of the output of @samp{configure --help}.
12129 For instance, someone who needs to add @file{/home/my/usr/include} to
12130 the C compiler's search path would configure a package with
12133 ./configure CPPFLAGS='-I /home/my/usr/include'
12137 and this flag would be propagated to the compile rules of all
12140 It is also not uncommon to override a user variable at
12141 @command{make}-time. Many installers do this with @code{prefix}, but
12142 this can be useful with compiler flags too. For instance, if, while
12143 debugging a C++ project, you need to disable optimization in one
12144 specific object file, you can run something like
12148 make CXXFLAGS=-O0 file.o
12152 The reason @samp{$(CPPFLAGS)} appears after @samp{$(AM_CPPFLAGS)} or
12153 @samp{$(mumble_CPPFLAGS)} in the compile command is that users
12154 should always have the last say. It probably makes more sense if you
12155 think about it while looking at the @samp{CXXFLAGS=-O0} above, which
12156 should supersede any other switch from @code{AM_CXXFLAGS} or
12157 @code{mumble_CXXFLAGS} (and this of course replaces the previous value
12158 of @code{CXXFLAGS}).
12160 You should never redefine a user variable such as @code{CPPFLAGS} in
12161 @file{Makefile.am}. Use @samp{automake -Woverride} to diagnose such
12162 mistakes. Even something like
12165 CPPFLAGS = -DDATADIR=\"$(datadir)\" @@CPPFLAGS@@
12169 is erroneous. Although this preserves @file{configure}'s value of
12170 @code{CPPFLAGS}, the definition of @code{DATADIR} will disappear if a
12171 user attempts to override @code{CPPFLAGS} from the @command{make}
12175 AM_CPPFLAGS = -DDATADIR=\"$(datadir)\"
12179 is all that is needed here if no per-target flags are used.
12181 You should not add options to these user variables within
12182 @file{configure} either, for the same reason. Occasionally you need
12183 to modify these variables to perform a test, but you should reset
12184 their values afterwards. In contrast, it is OK to modify the
12185 @samp{AM_} variables within @file{configure} if you @code{AC_SUBST}
12186 them, but it is rather rare that you need to do this, unless you
12187 really want to change the default definitions of the @samp{AM_}
12188 variables in all @file{Makefile}s.
12190 What we recommend is that you define extra flags in separate
12191 variables. For instance, you may write an Autoconf macro that computes
12192 a set of warning options for the C compiler, and @code{AC_SUBST} them
12193 in @code{WARNINGCFLAGS}; you may also have an Autoconf macro that
12194 determines which compiler and which linker flags should be used to
12195 link with library @file{libfoo}, and @code{AC_SUBST} these in
12196 @code{LIBFOOCFLAGS} and @code{LIBFOOLDFLAGS}. Then, a
12197 @file{Makefile.am} could use these variables as follows:
12200 AM_CFLAGS = $(WARNINGCFLAGS)
12201 bin_PROGRAMS = prog1 prog2
12202 prog1_SOURCES = @dots{}
12203 prog2_SOURCES = @dots{}
12204 prog2_CFLAGS = $(LIBFOOCFLAGS) $(AM_CFLAGS)
12205 prog2_LDFLAGS = $(LIBFOOLDFLAGS)
12208 In this example both programs will be compiled with the flags
12209 substituted into @samp{$(WARNINGCFLAGS)}, and @code{prog2} will
12210 additionally be compiled with the flags required to link with
12213 Note that listing @code{AM_CFLAGS} in a per-target @code{CFLAGS}
12214 variable is a common idiom to ensure that @code{AM_CFLAGS} applies to
12215 every target in a @file{Makefile.in}.
12217 Using variables like this gives you full control over the ordering of
12218 the flags. For instance, if there is a flag in $(WARNINGCFLAGS) that
12219 you want to negate for a particular target, you can use something like
12220 @samp{prog1_CFLAGS = $(AM_CFLAGS) -no-flag}. If all these flags had
12221 been forcefully appended to @code{CFLAGS}, there would be no way to
12222 disable one flag. Yet another reason to leave user variables to
12225 Finally, we have avoided naming the variable of the example
12226 @code{LIBFOO_LDFLAGS} (with an underscore) because that would cause
12227 Automake to think that this is actually a per-target variable (like
12228 @code{mumble_LDFLAGS}) for some non-declared @code{LIBFOO} target.
12230 @subheading Other Variables
12232 There are other variables in Automake that follow similar principles
12233 to allow user options. For instance, Texinfo rules (@pxref{Texinfo})
12234 use @code{MAKEINFOFLAGS} and @code{AM_MAKEINFOFLAGS}. Similarly,
12235 DejaGnu tests (@pxref{DejaGnu Tests}) use @code{RUNTESTDEFAULTFLAGS} and
12236 @code{AM_RUNTESTDEFAULTFLAGS}. The tags and ctags rules
12237 (@pxref{Tags}) use @code{ETAGSFLAGS}, @code{AM_ETAGSFLAGS},
12238 @code{CTAGSFLAGS}, and @code{AM_CTAGSFLAGS}. Java rules
12239 (@pxref{Java}) use @code{JAVACFLAGS} and @code{AM_JAVACFLAGS}. None
12240 of these rules support per-target flags (yet).
12242 To some extent, even @code{AM_MAKEFLAGS} (@pxref{Subdirectories})
12243 obeys this naming scheme. The slight difference is that
12244 @code{MAKEFLAGS} is passed to sub-@command{make}s implicitly by
12245 @command{make} itself.
12247 However you should not think that all variables ending with
12248 @code{FLAGS} follow this convention. For instance,
12249 @code{DISTCHECK_CONFIGURE_FLAGS} (@pxref{Checking the Distribution}) and
12250 @code{ACLOCAL_AMFLAGS} (see @ref{Rebuilding} and @ref{Local Macros}),
12251 are two variables that are only useful to the maintainer and have no
12254 @code{ARFLAGS} (@pxref{A Library}) is usually defined by Automake and
12255 has neither @code{AM_} nor per-target cousin.
12257 Finally you should not think that the existence of a per-target
12258 variable implies the existence of an @code{AM_} variable or of a user
12259 variable. For instance, the @code{mumble_LDADD} per-target variable
12260 overrides the makefile-wide @code{LDADD} variable (which is not a user
12261 variable), and @code{mumble_LIBADD} exists only as a per-target
12262 variable. @xref{Program and Library Variables}.
12265 @node Renamed Objects
12266 @section Why are object files sometimes renamed?
12268 This happens when per-target compilation flags are used. Object
12269 files need to be renamed just in case they would clash with object
12270 files compiled from the same sources, but with different flags.
12271 Consider the following example.
12274 bin_PROGRAMS = true false
12275 true_SOURCES = generic.c
12276 true_CPPFLAGS = -DEXIT_CODE=0
12277 false_SOURCES = generic.c
12278 false_CPPFLAGS = -DEXIT_CODE=1
12282 Obviously the two programs are built from the same source, but it
12283 would be bad if they shared the same object, because @file{generic.o}
12284 cannot be built with both @samp{-DEXIT_CODE=0} @emph{and}
12285 @samp{-DEXIT_CODE=1}. Therefore @command{automake} outputs rules to
12286 build two different objects: @file{true-generic.o} and
12287 @file{false-generic.o}.
12289 @command{automake} doesn't actually look whether source files are
12290 shared to decide if it must rename objects. It will just rename all
12291 objects of a target as soon as it sees per-target compilation flags
12294 It's OK to share object files when per-target compilation flags are not
12295 used. For instance, @file{true} and @file{false} will both use
12296 @file{version.o} in the following example.
12299 AM_CPPFLAGS = -DVERSION=1.0
12300 bin_PROGRAMS = true false
12301 true_SOURCES = true.c version.c
12302 false_SOURCES = false.c version.c
12305 Note that the renaming of objects is also affected by the
12306 @code{_SHORTNAME} variable (@pxref{Program and Library Variables}).
12309 @node Per-Object Flags
12310 @section Per-Object Flags Emulation
12311 @cindex Per-object flags, emulated
12314 One of my source files needs to be compiled with different flags. How
12318 Automake supports per-program and per-library compilation flags (see
12319 @ref{Program and Library Variables} and @ref{Flag Variables
12320 Ordering}). With this you can define compilation flags that apply to
12321 all files compiled for a target. For instance, in
12325 foo_SOURCES = foo.c foo.h bar.c bar.h main.c
12326 foo_CFLAGS = -some -flags
12330 @file{foo-foo.o}, @file{foo-bar.o}, and @file{foo-main.o} will all be
12331 compiled with @samp{-some -flags}. (If you wonder about the names of
12332 these object files, see @ref{Renamed Objects}.) Note that
12333 @code{foo_CFLAGS} gives the flags to use when compiling all the C
12334 sources of the @emph{program} @code{foo}, it has nothing to do with
12335 @file{foo.c} or @file{foo-foo.o} specifically.
12337 What if @file{foo.c} needs to be compiled into @file{foo.o} using some
12338 specific flags, that none of the other files requires? Obviously
12339 per-program flags are not directly applicable here. Something like
12340 per-object flags are expected, i.e., flags that would be used only
12341 when creating @file{foo-foo.o}. Automake does not support that,
12342 however this is easy to simulate using a library that contains only
12343 that object, and compiling this library with per-library flags.
12347 foo_SOURCES = bar.c bar.h main.c
12348 foo_CFLAGS = -some -flags
12349 foo_LDADD = libfoo.a
12350 noinst_LIBRARIES = libfoo.a
12351 libfoo_a_SOURCES = foo.c foo.h
12352 libfoo_a_CFLAGS = -some -other -flags
12355 Here @file{foo-bar.o} and @file{foo-main.o} will all be
12356 compiled with @samp{-some -flags}, while @file{libfoo_a-foo.o} will
12357 be compiled using @samp{-some -other -flags}. Eventually, all
12358 three objects will be linked to form @file{foo}.
12360 This trick can also be achieved using Libtool convenience libraries,
12361 for instance @samp{noinst_LTLIBRARIES = libfoo.la} (@pxref{Libtool
12362 Convenience Libraries}).
12364 Another tempting idea to implement per-object flags is to override the
12365 compile rules @command{automake} would output for these files.
12366 Automake will not define a rule for a target you have defined, so you
12367 could think about defining the @samp{foo-foo.o: foo.c} rule yourself.
12368 We recommend against this, because this is error prone. For instance,
12369 if you add such a rule to the first example, it will break the day you
12370 decide to remove @code{foo_CFLAGS} (because @file{foo.c} will then be
12371 compiled as @file{foo.o} instead of @file{foo-foo.o}, @pxref{Renamed
12372 Objects}). Also in order to support dependency tracking, the two
12373 @file{.o}/@file{.obj} extensions, and all the other flags variables
12374 involved in a compilation, you will end up modifying a copy of the
12375 rule previously output by @command{automake} for this file. If a new
12376 release of Automake generates a different rule, your copy will need to
12377 be updated by hand.
12379 @node Multiple Outputs
12380 @section Handling Tools that Produce Many Outputs
12381 @cindex multiple outputs, rules with
12382 @cindex many outputs, rules with
12383 @cindex rules with multiple outputs
12385 This section describes a @command{make} idiom that can be used when a
12386 tool produces multiple output files. It is not specific to Automake
12387 and can be used in ordinary @file{Makefile}s.
12389 Suppose we have a program called @command{foo} that will read one file
12390 called @file{data.foo} and produce two files named @file{data.c} and
12391 @file{data.h}. We want to write a @file{Makefile} rule that captures
12392 this one-to-two dependency.
12394 The naive rule is incorrect:
12397 # This is incorrect.
12398 data.c data.h: data.foo
12403 What the above rule really says is that @file{data.c} and
12404 @file{data.h} each depend on @file{data.foo}, and can each be built by
12405 running @samp{foo data.foo}. In other words it is equivalent to:
12408 # We do not want this.
12416 which means that @command{foo} can be run twice. Usually it will not
12417 be run twice, because @command{make} implementations are smart enough
12418 to check for the existence of the second file after the first one has
12419 been built; they will therefore detect that it already exists.
12420 However there are a few situations where it can run twice anyway:
12424 The most worrying case is when running a parallel @command{make}. If
12425 @file{data.c} and @file{data.h} are built in parallel, two @samp{foo
12426 data.foo} commands will run concurrently. This is harmful.
12428 Another case is when the dependency (here @file{data.foo}) is
12429 (or depends upon) a phony target.
12432 A solution that works with parallel @command{make} but not with
12433 phony dependencies is the following:
12436 data.c data.h: data.foo
12442 The above rules are equivalent to
12447 data.h: data.foo data.c
12452 therefore a parallel @command{make} will have to serialize the builds
12453 of @file{data.c} and @file{data.h}, and will detect that the second is
12454 no longer needed once the first is over.
12456 Using this pattern is probably enough for most cases. However it does
12457 not scale easily to more output files (in this scheme all output files
12458 must be totally ordered by the dependency relation), so we will
12459 explore a more complicated solution.
12461 Another idea is to write the following:
12464 # There is still a problem with this one.
12471 The idea is that @samp{foo data.foo} is run only when @file{data.c}
12472 needs to be updated, but we further state that @file{data.h} depends
12473 upon @file{data.c}. That way, if @file{data.h} is required and
12474 @file{data.foo} is out of date, the dependency on @file{data.c} will
12477 This is almost perfect, but suppose we have built @file{data.h} and
12478 @file{data.c}, and then we erase @file{data.h}. Then, running
12479 @samp{make data.h} will not rebuild @file{data.h}. The above rules
12480 just state that @file{data.c} must be up-to-date with respect to
12481 @file{data.foo}, and this is already the case.
12483 What we need is a rule that forces a rebuild when @file{data.h} is
12484 missing. Here it is:
12490 ## Recover from the removal of $@@
12491 @@if test -f $@@; then :; else \
12493 $(MAKE) $(AM_MAKEFLAGS) data.c; \
12497 The above scheme can be extended to handle more outputs and more
12498 inputs. One of the outputs is selected to serve as a witness to the
12499 successful completion of the command, it depends upon all inputs, and
12500 all other outputs depend upon it. For instance, if @command{foo}
12501 should additionally read @file{data.bar} and also produce
12502 @file{data.w} and @file{data.x}, we would write:
12505 data.c: data.foo data.bar
12506 foo data.foo data.bar
12507 data.h data.w data.x: data.c
12508 ## Recover from the removal of $@@
12509 @@if test -f $@@; then :; else \
12511 $(MAKE) $(AM_MAKEFLAGS) data.c; \
12515 However there are now three minor problems in this setup. One is related
12516 to the timestamp ordering of @file{data.h}, @file{data.w},
12517 @file{data.x}, and @file{data.c}. Another one is a race condition
12518 if a parallel @command{make} attempts to run multiple instances of the
12519 recover block at once. Finally, the recursive rule breaks @samp{make -n}
12520 when run with GNU @command{make} (as well as some other @command{make}
12521 implementations), as it may remove @file{data.h} even when it should not
12522 (@pxref{MAKE Variable, , How the @code{MAKE} Variable Works, make,
12523 The GNU Make Manual}).
12525 Let us deal with the first problem. @command{foo} outputs four files,
12526 but we do not know in which order these files are created. Suppose
12527 that @file{data.h} is created before @file{data.c}. Then we have a
12528 weird situation. The next time @command{make} is run, @file{data.h}
12529 will appear older than @file{data.c}, the second rule will be
12530 triggered, a shell will be started to execute the @samp{if@dots{}fi}
12531 command, but actually it will just execute the @code{then} branch,
12532 that is: nothing. In other words, because the witness we selected is
12533 not the first file created by @command{foo}, @command{make} will start
12534 a shell to do nothing each time it is run.
12536 A simple riposte is to fix the timestamps when this happens.
12539 data.c: data.foo data.bar
12540 foo data.foo data.bar
12541 data.h data.w data.x: data.c
12542 @@if test -f $@@; then \
12545 ## Recover from the removal of $@@
12547 $(MAKE) $(AM_MAKEFLAGS) data.c; \
12551 Another solution is to use a different and dedicated file as witness,
12552 rather than using any of @command{foo}'s outputs.
12555 data.stamp: data.foo data.bar
12558 foo data.foo data.bar
12559 @@mv -f data.tmp $@@
12560 data.c data.h data.w data.x: data.stamp
12561 ## Recover from the removal of $@@
12562 @@if test -f $@@; then :; else \
12563 rm -f data.stamp; \
12564 $(MAKE) $(AM_MAKEFLAGS) data.stamp; \
12568 @file{data.tmp} is created before @command{foo} is run, so it has a
12569 timestamp older than output files output by @command{foo}. It is then
12570 renamed to @file{data.stamp} after @command{foo} has run, because we
12571 do not want to update @file{data.stamp} if @command{foo} fails.
12573 This solution still suffers from the second problem: the race
12574 condition in the recover rule. If, after a successful build, a user
12575 erases @file{data.c} and @file{data.h}, and runs @samp{make -j}, then
12576 @command{make} may start both recover rules in parallel. If the two
12577 instances of the rule execute @samp{$(MAKE) $(AM_MAKEFLAGS)
12578 data.stamp} concurrently the build is likely to fail (for instance, the
12579 two rules will create @file{data.tmp}, but only one can rename it).
12581 Admittedly, such a weird situation does not arise during ordinary
12582 builds. It occurs only when the build tree is mutilated. Here
12583 @file{data.c} and @file{data.h} have been explicitly removed without
12584 also removing @file{data.stamp} and the other output files.
12585 @code{make clean; make} will always recover from these situations even
12586 with parallel makes, so you may decide that the recover rule is solely
12587 to help non-parallel make users and leave things as-is. Fixing this
12588 requires some locking mechanism to ensure only one instance of the
12589 recover rule rebuilds @file{data.stamp}. One could imagine something
12590 along the following lines.
12593 data.c data.h data.w data.x: data.stamp
12594 ## Recover from the removal of $@@
12595 @@if test -f $@@; then :; else \
12596 trap 'rm -rf data.lock data.stamp' 1 2 13 15; \
12597 ## mkdir is a portable test-and-set
12598 if mkdir data.lock 2>/dev/null; then \
12599 ## This code is being executed by the first process.
12600 rm -f data.stamp; \
12601 $(MAKE) $(AM_MAKEFLAGS) data.stamp; \
12602 result=$$?; rm -rf data.lock; exit $$result; \
12604 ## This code is being executed by the follower processes.
12605 ## Wait until the first process is done.
12606 while test -d data.lock; do sleep 1; done; \
12607 ## Succeed if and only if the first process succeeded.
12608 test -f data.stamp; \
12613 Using a dedicated witness, like @file{data.stamp}, is very handy when
12614 the list of output files is not known beforehand. As an illustration,
12615 consider the following rules to compile many @file{*.el} files into
12616 @file{*.elc} files in a single command. It does not matter how
12617 @code{ELFILES} is defined (as long as it is not empty: empty targets
12618 are not accepted by POSIX).
12621 ELFILES = one.el two.el three.el @dots{}
12622 ELCFILES = $(ELFILES:=c)
12624 elc-stamp: $(ELFILES)
12627 $(elisp_comp) $(ELFILES)
12628 @@mv -f elc-temp $@@
12630 $(ELCFILES): elc-stamp
12631 @@if test -f $@@; then :; else \
12632 ## Recover from the removal of $@@
12633 trap 'rm -rf elc-lock elc-stamp' 1 2 13 15; \
12634 if mkdir elc-lock 2>/dev/null; then \
12635 ## This code is being executed by the first process.
12637 $(MAKE) $(AM_MAKEFLAGS) elc-stamp; \
12640 ## This code is being executed by the follower processes.
12641 ## Wait until the first process is done.
12642 while test -d elc-lock; do sleep 1; done; \
12643 ## Succeed if and only if the first process succeeded.
12644 test -f elc-stamp; exit $$?; \
12650 These solutions all still suffer from the third problem, namely that
12651 they break the promise that @samp{make -n} should not cause any actual
12652 changes to the tree. For those solutions that do not create lock files,
12653 it is possible to split the recover rules into two separate recipe
12654 commands, one of which does all work but the recursion, and the
12655 other invokes the recursive @samp{$(MAKE)}. The solutions involving
12656 locking could act upon the contents of the @samp{MAKEFLAGS} variable,
12657 but parsing that portably is not easy (@pxref{The Make Macro MAKEFLAGS,,,
12658 autoconf, The Autoconf Manual}). Here is an example:
12661 ELFILES = one.el two.el three.el @dots{}
12662 ELCFILES = $(ELFILES:=c)
12664 elc-stamp: $(ELFILES)
12667 $(elisp_comp) $(ELFILES)
12668 @@mv -f elc-temp $@@
12670 $(ELCFILES): elc-stamp
12671 ## Recover from the removal of $@@
12672 @@dry=; for f in x $$MAKEFLAGS; do \
12678 if test -f $@@; then :; else \
12679 $$dry trap 'rm -rf elc-lock elc-stamp' 1 2 13 15; \
12680 if $$dry mkdir elc-lock 2>/dev/null; then \
12681 ## This code is being executed by the first process.
12682 $$dry rm -f elc-stamp; \
12683 $(MAKE) $(AM_MAKEFLAGS) elc-stamp; \
12684 $$dry rmdir elc-lock; \
12686 ## This code is being executed by the follower processes.
12687 ## Wait until the first process is done.
12688 while test -d elc-lock && test -z "$$dry"; do \
12692 ## Succeed if and only if the first process succeeded.
12693 $$dry test -f elc-stamp; exit $$?; \
12698 For completeness it should be noted that GNU @command{make} is able to
12699 express rules with multiple output files using pattern rules
12700 (@pxref{Pattern Examples, , Pattern Rule Examples, make, The GNU Make
12701 Manual}). We do not discuss pattern rules here because they are not
12702 portable, but they can be convenient in packages that assume GNU
12706 @node Hard-Coded Install Paths
12707 @section Installing to Hard-Coded Locations
12710 My package needs to install some configuration file. I tried to use
12711 the following rule, but @samp{make distcheck} fails. Why?
12715 install-data-local:
12716 $(INSTALL_DATA) $(srcdir)/afile $(DESTDIR)/etc/afile
12721 My package needs to populate the installation directory of another
12722 package at install-time. I can easily compute that installation
12723 directory in @file{configure}, but if I install files therein,
12724 @samp{make distcheck} fails. How else should I do?
12727 These two setups share their symptoms: @samp{make distcheck} fails
12728 because they are installing files to hard-coded paths. In the later
12729 case the path is not really hard-coded in the package, but we can
12730 consider it to be hard-coded in the system (or in whichever tool that
12731 supplies the path). As long as the path does not use any of the
12732 standard directory variables (@samp{$(prefix)}, @samp{$(bindir)},
12733 @samp{$(datadir)}, etc.), the effect will be the same:
12734 user-installations are impossible.
12736 As a (non-root) user who wants to install a package, you usually have no
12737 right to install anything in @file{/usr} or @file{/usr/local}. So you
12738 do something like @samp{./configure --prefix ~/usr} to install a
12739 package in your own @file{~/usr} tree.
12741 If a package attempts to install something to some hard-coded path
12742 (e.g., @file{/etc/afile}), regardless of this @option{--prefix} setting,
12743 then the installation will fail. @samp{make distcheck} performs such
12744 a @option{--prefix} installation, hence it will fail too.
12746 Now, there are some easy solutions.
12748 The above @code{install-data-local} example for installing
12749 @file{/etc/afile} would be better replaced by
12752 sysconf_DATA = afile
12756 by default @code{sysconfdir} will be @samp{$(prefix)/etc}, because
12757 this is what the GNU Standards require. When such a package is
12758 installed on an FHS compliant system, the installer will have to set
12759 @samp{--sysconfdir=/etc}. As the maintainer of the package you
12760 should not be concerned by such site policies: use the appropriate
12761 standard directory variable to install your files so that the installer
12762 can easily redefine these variables to match their site conventions.
12764 Installing files that should be used by another package is slightly
12765 more involved. Let's take an example and assume you want to install
12766 a shared library that is a Python extension module. If you ask Python
12767 where to install the library, it will answer something like this:
12770 % @kbd{python -c 'from distutils import sysconfig;
12771 print sysconfig.get_python_lib(1,0)'}
12772 /usr/lib/python2.5/site-packages
12775 If you indeed use this absolute path to install your shared library,
12776 non-root users will not be able to install the package, hence
12779 Let's do better. The @samp{sysconfig.get_python_lib()} function
12780 actually accepts a third argument that will replace Python's
12781 installation prefix.
12784 % @kbd{python -c 'from distutils import sysconfig;
12785 print sysconfig.get_python_lib(1,0,"$@{exec_prefix@}")'}
12786 $@{exec_prefix@}/lib/python2.5/site-packages
12789 You can also use this new path. If you do
12792 root users can install your package with the same @option{--prefix}
12793 as Python (you get the behavior of the previous attempt)
12796 non-root users can install your package too, they will have the
12797 extension module in a place that is not searched by Python but they
12798 can work around this using environment variables (and if you installed
12799 scripts that use this shared library, it's easy to tell Python were to
12800 look in the beginning of your script, so the script works in both
12804 The @code{AM_PATH_PYTHON} macro uses similar commands to define
12805 @samp{$(pythondir)} and @samp{$(pyexecdir)} (@pxref{Python}).
12807 Of course not all tools are as advanced as Python regarding that
12808 substitution of @var{prefix}. So another strategy is to figure the
12809 part of the installation directory that must be preserved. For
12810 instance, here is how @code{AM_PATH_LISPDIR} (@pxref{Emacs Lisp})
12811 computes @samp{$(lispdir)}:
12814 $EMACS -batch -q -eval '(while load-path
12815 (princ (concat (car load-path) "\n"))
12816 (setq load-path (cdr load-path)))' >conftest.out
12819 -e '/.*\/lib\/x*emacs\/site-lisp$/@{
12820 s,.*/lib/\(x*emacs/site-lisp\)$,$@{libdir@}/\1,;p;q;
12822 -e '/.*\/share\/x*emacs\/site-lisp$/@{
12823 s,.*/share/\(x*emacs/site-lisp\),$@{datarootdir@}/\1,;p;q;
12828 I.e., it just picks the first directory that looks like
12829 @file{*/lib/*emacs/site-lisp} or @file{*/share/*emacs/site-lisp} in
12830 the search path of emacs, and then substitutes @samp{$@{libdir@}} or
12831 @samp{$@{datadir@}} appropriately.
12833 The emacs case looks complicated because it processes a list and
12834 expects two possible layouts, otherwise it's easy, and the benefits for
12835 non-root users are really worth the extra @command{sed} invocation.
12838 @node Debugging Make Rules
12839 @section Debugging Make Rules
12840 @cindex debugging rules
12841 @cindex rules, debugging
12843 The rules and dependency trees generated by @command{automake} can get
12844 rather complex, and leave the developer head-scratching when things
12845 don't work as expected. Besides the debug options provided by the
12846 @command{make} command (@pxref{Options Summary,,, make, The GNU Make
12847 Manual}), here's a couple of further hints for debugging makefiles
12848 generated by @command{automake} effectively:
12852 If less verbose output has been enabled in the package with the use
12853 of silent rules (@pxref{Automake Silent Rules}), you can use
12854 @code{make V=1} to see the commands being executed.
12856 @code{make -n} can help show what would be done without actually doing
12857 it. Note however, that this will @emph{still execute} commands prefixed
12858 with @samp{+}, and, when using GNU @command{make}, commands that contain
12859 the strings @samp{$(MAKE)} or @samp{$@{MAKE@}} (@pxref{Instead of
12860 Execution,,, make, The GNU Make Manual}).
12861 Typically, this is helpful to show what recursive rules would do, but it
12862 means that, in your own rules, you should not mix such recursion with
12863 actions that change any files.@footnote{Automake's @samp{dist} and
12864 @samp{distcheck} rules had a bug in this regard in that they created
12865 directories even with @option{-n}, but this has been fixed in Automake
12866 1.11.} Furthermore, note that GNU @command{make} will update
12867 prerequisites for the @file{Makefile} file itself even with @option{-n}
12868 (@pxref{Remaking Makefiles,,, make, The GNU Make Manual}).
12870 @code{make SHELL="/bin/bash -vx"} can help debug complex rules.
12871 @xref{The Make Macro SHELL,,, autoconf, The Autoconf Manual}, for some
12872 portability quirks associated with this construct.
12874 @code{echo 'print: ; @@echo "$(VAR)"' | make -f Makefile -f - print}
12875 can be handy to examine the expanded value of variables. You may need
12876 to use a target other than @samp{print} if that is already used or a
12877 file with that name exists.
12879 @url{http://bashdb.sourceforge.net/@/remake/} provides a modified
12880 GNU @command{make} command called @command{remake} that copes with
12881 complex GNU @command{make}-specific Makefiles and allows to trace
12882 execution, examine variables, and call rules interactively, much like
12887 @node Reporting Bugs
12888 @section Reporting Bugs
12890 Most nontrivial software has bugs. Automake is no exception. Although
12891 we cannot promise we can or will fix a bug, and we might not even agree
12892 that it is a bug, we want to hear about problems you encounter. Often we
12893 agree they are bugs and want to fix them.
12895 To make it possible for us to fix a bug, please report it. In order to
12896 do so effectively, it helps to know when and how to do it.
12898 Before reporting a bug, it is a good idea to see if it is already known.
12899 You can look at the @uref{http://debbugs.gnu.org/, GNU Bug Tracker}
12900 and the @uref{http://lists.gnu.org/@/archive/@/html/@/bug-automake/,
12901 bug-automake mailing list archives} for previous bug reports. We
12903 @uref{http://sourceware.org/@/cgi-bin/@/gnatsweb.pl?database=automake,
12904 Gnats database} for bug tracking, so some bugs might have been reported
12905 there already. Please do not use it for new bug reports, however.
12907 If the bug is not already known, it should be reported. It is very
12908 important to report bugs in a way that is useful and efficient. For
12909 this, please familiarize yourself with
12910 @uref{http://www.chiark.greenend.org.uk/@/~sgtatham/@/bugs.html, How to
12911 Report Bugs Effectively} and
12912 @uref{http://catb.org/@/~esr/@/faqs/@/smart-questions.html, How to Ask
12913 Questions the Smart Way}. This helps you and developers to save time
12914 which can then be spent on fixing more bugs and implementing more
12917 For a bug report, a feature request or other suggestions, please send
12918 email to @email{@value{PACKAGE_BUGREPORT}}. This will then open a new
12919 bug in the @uref{http://debbugs.gnu.org/@/automake, bug tracker}. Be
12920 sure to include the versions of Autoconf and Automake that you use.
12921 Ideally, post a minimal @file{Makefile.am} and @file{configure.ac} that
12922 reproduces the problem you encounter. If you have encountered test
12923 suite failures, please attach the @file{tests/test-suite.log} file.
12925 @c ========================================================== Appendices
12928 @node Copying This Manual
12929 @appendix Copying This Manual
12932 * GNU Free Documentation License:: License for copying this manual
12935 @node GNU Free Documentation License
12936 @appendixsec GNU Free Documentation License
12944 * Macro Index:: Index of Autoconf macros
12945 * Variable Index:: Index of Makefile variables
12946 * General Index:: General index
12950 @appendixsec Macro Index
12954 @node Variable Index
12955 @appendixsec Variable Index
12959 @node General Index
12960 @appendixsec General Index
12967 @c LocalWords: texinfo setfilename settitle setchapternewpage texi direntry
12968 @c LocalWords: dircategory in's aclocal ifinfo titlepage Tromey vskip pt sp
12969 @c LocalWords: filll defcodeindex ov cv op tr syncodeindex fn cp vr ifnottex
12970 @c LocalWords: dir Automake's ac Dist Gnits gnits dfn Autoconf's pxref
12971 @c LocalWords: cindex Autoconf autoconf perl samp cvs dist trindex SUBST foo
12972 @c LocalWords: xs emph FIXME ref vindex pkglibdir pkgincludedir pkgdatadir mt
12973 @c LocalWords: pkg libdir cpio bindir sbindir rmt pax sbin zar zardir acindex
12974 @c LocalWords: HTML htmldir html noinst TEXINFOS nodist nobase strudel CFLAGS
12975 @c LocalWords: libmumble CC YFLAGS itemx de fication config url comp
12976 @c LocalWords: depcomp elisp sh mdate mkinstalldirs mkdir py tex dvi ps pdf
12977 @c LocalWords: ylwrap zardoz INIT gettext acinclude mv FUNCS LIBOBJS LDADD fr
12978 @c LocalWords: uref featureful dnl src LINGUAS es ko nl pl sl sv PROG ISC doc
12979 @c LocalWords: POSIX STDC fcntl FUNC ALLOCA blksize struct stat intl po chmod
12980 @c LocalWords: ChangeLog SUBDIRS gettextize gpl testdata getopt INTLLIBS cpp
12981 @c LocalWords: localedir datadir DLOCALEDIR DEXIT CPPFLAGS autoreconf opindex
12982 @c LocalWords: AUX var symlink deps Wno Wnone package's aclocal's distclean
12983 @c LocalWords: ltmain xref LIBSOURCE LIBSOURCES LIBOBJ MEMCMP vs RANLIB CXX
12984 @c LocalWords: LDFLAGS LIBTOOL libtool XTRA LIBS gettext's acdir APIVERSION
12985 @c LocalWords: dirlist noindent usr TIOCGWINSZ sc
12986 @c LocalWords: GWINSZ termios SRCDIR tarball bzip LISPDIR lispdir XEmacs CCAS
12987 @c LocalWords: emacsen MicroEmacs CCASFLAGS UX GCJ gcj GCJFLAGS posix DMALLOC
12988 @c LocalWords: dmalloc ldmalloc REGEX regex DEPDIR DEP DEFUN aclocaldir fi
12989 @c LocalWords: mymacro myothermacro AMFLAGS autopoint autogen libtoolize yum
12990 @c LocalWords: autoheader README MAKEFLAGS subdir Inetutils sync COND endif
12991 @c LocalWords: Miller's installable includedir inc pkgdata EXEEXT libexec bsd
12992 @c LocalWords: pkglib libexecdir prog libcpio cpio's dlopen dlpreopen linux
12993 @c LocalWords: subsubsection OBJEXT esac lib LTLIBRARIES liblob LIBADD AR ar
12994 @c LocalWords: ARFLAGS cru ing maude libgettext lo LTLIBOBJS rpath SGI PRE yy
12995 @c LocalWords: libmaude CCLD CXXFLAGS FFLAGS LFLAGS OBJCFLAGS RFLAGS DEFS cc
12996 @c LocalWords: OBJCXXFLAGS
12997 @c LocalWords: SHORTNAME vtable srcdir nostdinc basename yxx cxx ll lxx gdb
12998 @c LocalWords: lexers yymaxdepth maxdepth yyparse yylex yyerror yylval lval
12999 @c LocalWords: yychar yydebug yypact yyr yydef def yychk chk yypgo pgo yyact
13000 @c LocalWords: yyexca exca yyerrflag errflag yynerrs nerrs yyps yypv pv yys
13001 @c LocalWords: yystate yytmp tmp yyv yyval val yylloc lloc yyreds yytoks toks
13002 @c LocalWords: yylhs yylen yydefred yydgoto yysindex yyrindex yygindex yyname
13003 @c LocalWords: yytable yycheck yyrule byacc CXXCOMPILE CXXLINK FLINK cfortran
13004 @c LocalWords: Catalogue preprocessable FLIBS libfoo baz JAVACFLAGS java exe
13005 @c LocalWords: SunOS fying basenames exeext uninstalled oldinclude kr FSF's
13006 @c LocalWords: pkginclude oldincludedir sysconf sharedstate localstate gcc rm
13007 @c LocalWords: sysconfdir sharedstatedir localstatedir preexist CLEANFILES gz
13008 @c LocalWords: depfile tmpdepfile depmode const interoperate
13009 @c LocalWords: JAVAC javac JAVAROOT builddir CLASSPATH ENV pyc pyo pkgpython
13010 @c LocalWords: pyexecdir pkgpyexecdir Python's pythondir pkgpythondir txi ois
13011 @c LocalWords: installinfo vers MAKEINFO makeinfo MAKEINFOFLAGS noinstall rf
13012 @c LocalWords: mandir thesame alsothesame installman myexecbin DESTDIR Pinard
13013 @c LocalWords: uninstall installdirs uninstalls MOSTLYCLEANFILES mostlyclean
13014 @c LocalWords: DISTCLEANFILES MAINTAINERCLEANFILES GZIP gzip shar exp
13015 @c LocalWords: distdir distcheck distcleancheck listfiles distuninstallcheck
13016 @c LocalWords: VPATH tarfile stdout XFAIL DejaGnu dejagnu DEJATOOL runtest ln
13017 @c LocalWords: RUNTESTDEFAULTFLAGS toolchain RUNTESTFLAGS asis readme DVIPS
13018 @c LocalWords: installcheck gzipped tarZ std utils etags mkid cd
13019 @c LocalWords: ARGS taggable ETAGSFLAGS lang ctags CTAGSFLAGS GTAGS gtags idl
13020 @c LocalWords: foocc doit idlC multilibs ABIs cmindex defmac ARG enableval FC
13021 @c LocalWords: MSG xtrue DBG pathchk CYGWIN afile proglink versioned CVS's TE
13022 @c LocalWords: wildcards Autoconfiscated subsubheading autotools Meyering API
13023 @c LocalWords: ois's wildcard Wportability cartouche vrindex printindex Duret
13024 @c LocalWords: DSOMEFLAG DVERSION automake Lutz insertcopying versioning FAQ
13025 @c LocalWords: LTLIBOBJ Libtool's libtool's libltdl dlopening itutions libbar
13026 @c LocalWords: WANTEDLIBS libhello sublibraries libtop libsub dlopened Ratfor
13027 @c LocalWords: mymodule timestamps timestamp underquoted MAKEINFOHTMLFLAGS te
13028 @c LocalWords: GNUmakefile Subpackages subpackage's subpackages aux
13029 @c LocalWords: detailmenu Timeline pwd reldir AUTOM autom PREREQ FOOBAR libc
13030 @c LocalWords: libhand subpackage moduleN libmain libmisc FCFLAGS FCCOMPILE
13031 @c LocalWords: FCLINK subst sed ELCFILES elc MAKEINFOHTML dvips esyscmd ustar
13032 @c LocalWords: tarballs Woverride vfi ELFILES djm AutoMake honkin FSF
13033 @c LocalWords: fileutils precanned MacKenzie's reimplement termutils Tromey's
13034 @c LocalWords: cois gnitsians LIBPROGRAMS progs LIBLIBRARIES Textutils Ulrich
13035 @c LocalWords: Matzigkeit Drepper's Gord Matzigkeit's jm Dalley Debian org
13036 @c LocalWords: Administrivia ILU CORBA Sourceware Molenda sourceware Elliston
13037 @c LocalWords: dep Oliva Akim Demaille Aiieeee Demaillator Akim's sourcequake
13038 @c LocalWords: grep backported screenshots libgcj KB unnumberedsubsubsec pre
13039 @c LocalWords: precomputing hacky makedepend inline clearmake LD PRELOAD Rel
13040 @c LocalWords: syscalls perlhist acl pm multitable headitem fdl appendixsec
13041 @c LocalWords: LTALLOCA MALLOC malloc memcmp strdup alloca libcompat xyz DFOO
13042 @c LocalWords: unprefixed buildable preprocessed DBAZ DDATADIR WARNINGCFLAGS
13043 @c LocalWords: LIBFOOCFLAGS LIBFOOLDFLAGS ftable testSubDir obj LIBTOOLFLAGS
13044 @c LocalWords: barexec Pinard's automatize initialize lzip xz cscope