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-2013 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 discouraged) 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}.
425 @cindex Constraints of Automake
426 @cindex Automake constraints
428 Automake does constrain a project in certain ways; for instance, it
429 assumes that the project uses Autoconf (@pxref{Top, , Introduction,
430 autoconf, The Autoconf Manual}), and enforces certain restrictions on
431 the @file{configure.ac} contents.
433 @cindex Automake requirements
434 @cindex Requirements, Automake
436 Automake requires @command{perl} in order to generate the
437 @file{Makefile.in}s. However, the distributions created by Automake are
438 fully GNU standards-compliant, and do not require @command{perl} in order
441 @cindex Bugs, reporting
442 @cindex Reporting bugs
443 @cindex E-mail, bug reports
445 For more information on bug reports, @xref{Reporting Bugs}.
447 @node Autotools Introduction
448 @chapter An Introduction to the Autotools
450 If you are new to Automake, maybe you know that it is part of a set of
451 tools called @emph{The Autotools}. Maybe you've already delved into a
452 package full of files named @file{configure}, @file{configure.ac},
453 @file{Makefile.in}, @file{Makefile.am}, @file{aclocal.m4}, @dots{},
454 some of them claiming to be @emph{generated by} Autoconf or Automake.
455 But the exact purpose of these files and their relations is probably
456 fuzzy. The goal of this chapter is to introduce you to this machinery,
457 to show you how it works and how powerful it is. If you've never
458 installed or seen such a package, do not worry: this chapter will walk
461 If you need some teaching material, more illustrations, or a less
462 @command{automake}-centered continuation, some slides for this
463 introduction are available in Alexandre Duret-Lutz's
464 @uref{http://www.lrde.epita.fr/@/~adl/@/autotools.html,
466 This chapter is the written version of the first part of his tutorial.
469 * GNU Build System:: Introducing the GNU Build System
470 * Use Cases:: Use Cases for the GNU Build System
471 * Why Autotools:: How Autotools Help
472 * Hello World:: A Small Hello World Package
475 @node GNU Build System
476 @section Introducing the GNU Build System
477 @cindex GNU Build System, introduction
479 It is a truth universally acknowledged, that as a developer in
480 possession of a new package, you must be in want of a build system.
482 In the Unix world, such a build system is traditionally achieved using
483 the command @command{make} (@pxref{Top, , Overview, make, The GNU Make
484 Manual}). You express the recipe to build your package in a
485 @file{Makefile}. This file is a set of rules to build the files in
486 the package. For instance the program @file{prog} may be built by
487 running the linker on the files @file{main.o}, @file{foo.o}, and
488 @file{bar.o}; the file @file{main.o} may be built by running the
489 compiler on @file{main.c}; etc. Each time @command{make} is run, it
490 reads @file{Makefile}, checks the existence and modification time of
491 the files mentioned, decides what files need to be built (or rebuilt),
492 and runs the associated commands.
494 When a package needs to be built on a different platform than the one
495 it was developed on, its @file{Makefile} usually needs to be adjusted.
496 For instance the compiler may have another name or require more
497 options. In 1991, David J. MacKenzie got tired of customizing
498 @file{Makefile} for the 20 platforms he had to deal with. Instead, he
499 handcrafted a little shell script called @file{configure} to
500 automatically adjust the @file{Makefile} (@pxref{Genesis, , Genesis,
501 autoconf, The Autoconf Manual}). Compiling his package was now
502 as simple as running @code{./configure && make}.
504 @cindex GNU Coding Standards
506 Today this process has been standardized in the GNU project. The GNU
507 Coding Standards (@pxref{Managing Releases, The Release Process, ,
508 standards, The GNU Coding Standards}) explains how each package of the
509 GNU project should have a @file{configure} script, and the minimal
510 interface it should have. The @file{Makefile} too should follow some
511 established conventions. The result? A unified build system that
512 makes all packages almost indistinguishable by the installer. In its
513 simplest scenario, all the installer has to do is to unpack the
514 package, run @code{./configure && make && make install}, and repeat
515 with the next package to install.
517 We call this build system the @dfn{GNU Build System}, since it was
518 grown out of the GNU project. However it is used by a vast number of
519 other packages: following any existing convention has its advantages.
521 @cindex Autotools, introduction
523 The Autotools are tools that will create a GNU Build System for your
524 package. Autoconf mostly focuses on @file{configure} and Automake on
525 @file{Makefile}s. It is entirely possible to create a GNU Build
526 System without the help of these tools. However it is rather
527 burdensome and error-prone. We will discuss this again after some
528 illustration of the GNU Build System in action.
531 @section Use Cases for the GNU Build System
532 @cindex GNU Build System, use cases
533 @cindex GNU Build System, features
534 @cindex Features of the GNU Build System
535 @cindex Use Cases for the GNU Build System
536 @cindex @file{amhello-1.0.tar.gz}, location
537 @cindex @file{amhello-1.0.tar.gz}, use cases
539 In this section we explore several use cases for the GNU Build System.
540 You can replay all of these examples on the @file{amhello-1.0.tar.gz}
541 package distributed with Automake. If Automake is installed on your
542 system, you should find a copy of this file in
543 @file{@var{prefix}/share/doc/automake/amhello-1.0.tar.gz}, where
544 @var{prefix} is the installation prefix specified during configuration
545 (@var{prefix} defaults to @file{/usr/local}, however if Automake was
546 installed by some GNU/Linux distribution it most likely has been set
547 to @file{/usr}). If you do not have a copy of Automake installed,
548 you can find a copy of this file inside the @file{doc/} directory of
549 the Automake package.
551 Some of the following use cases present features that are in fact
552 extensions to the GNU Build System. Read: they are not specified by
553 the GNU Coding Standards, but they are nonetheless part of the build
554 system created by the Autotools. To keep things simple, we do not
555 point out the difference. Our objective is to show you many of the
556 features that the build system created by the Autotools will offer to
560 * Basic Installation:: Common installation procedure
561 * Standard Targets:: A list of standard Makefile targets
562 * Standard Directory Variables:: A list of standard directory variables
563 * Standard Configuration Variables:: Using configuration variables
564 * config.site:: Using a config.site file
565 * VPATH Builds:: Parallel build trees
566 * Two-Part Install:: Installing data and programs separately
567 * Cross-Compilation:: Building for other architectures
568 * Renaming:: Renaming programs at install time
569 * DESTDIR:: Building binary packages with DESTDIR
570 * Preparing Distributions:: Rolling out tarballs
571 * Dependency Tracking:: Automatic dependency tracking
572 * Nested Packages:: The GNU Build Systems can be nested
575 @node Basic Installation
576 @subsection Basic Installation
577 @cindex Configuration, basics
578 @cindex Installation, basics
579 @cindex GNU Build System, basics
581 The most common installation procedure looks as follows.
584 ~ % @kbd{tar zxf amhello-1.0.tar.gz}
585 ~ % @kbd{cd amhello-1.0}
586 ~/amhello-1.0 % @kbd{./configure}
588 config.status: creating Makefile
589 config.status: creating src/Makefile
591 ~/amhello-1.0 % @kbd{make}
593 ~/amhello-1.0 % @kbd{make check}
595 ~/amhello-1.0 % @kbd{su}
597 /home/adl/amhello-1.0 # @kbd{make install}
599 /home/adl/amhello-1.0 # @kbd{exit}
600 ~/amhello-1.0 % @kbd{make installcheck}
606 The user first unpacks the package. Here, and in the following
607 examples, we will use the non-portable @code{tar zxf} command for
608 simplicity. On a system without GNU @command{tar} installed, this
609 command should read @code{gunzip -c amhello-1.0.tar.gz | tar xf -}.
611 The user then enters the newly created directory to run the
612 @file{configure} script. This script probes the system for various
613 features, and finally creates the @file{Makefile}s. In this toy
614 example there are only two @file{Makefile}s, but in real-world projects,
615 there may be many more, usually one @file{Makefile} per directory.
617 It is now possible to run @code{make}. This will construct all the
618 programs, libraries, and scripts that need to be constructed for the
619 package. In our example, this compiles the @file{hello} program.
620 All files are constructed in place, in the source tree; we will see
621 later how this can be changed.
623 @code{make check} causes the package's tests to be run. This step is
624 not mandatory, but it is often good to make sure the programs that
625 have been built behave as they should, before you decide to install
626 them. Our example does not contain any tests, so running @code{make
629 @cindex su, before @code{make install}
630 After everything has been built, and maybe tested, it is time to
631 install it on the system. That means copying the programs,
632 libraries, header files, scripts, and other data files from the
633 source directory to their final destination on the system. The
634 command @code{make install} will do that. However, by default
635 everything will be installed in subdirectories of @file{/usr/local}:
636 binaries will go into @file{/usr/local/bin}, libraries will end up in
637 @file{/usr/local/lib}, etc. This destination is usually not writable
638 by any user, so we assume that we have to become root before we can
639 run @code{make install}. In our example, running @code{make install}
640 will copy the program @file{hello} into @file{/usr/local/bin}
641 and @file{README} into @file{/usr/local/share/doc/amhello}.
643 A last and optional step is to run @code{make installcheck}. This
644 command may run tests on the installed files. @code{make check} tests
645 the files in the source tree, while @code{make installcheck} tests
646 their installed copies. The tests run by the latter can be different
647 from those run by the former. For instance, there are tests that
648 cannot be run in the source tree. Conversely, some packages are set
649 up so that @code{make installcheck} will run the very same tests as
650 @code{make check}, only on different files (non-installed
651 vs.@: installed). It can make a difference, for instance when the
652 source tree's layout is different from that of the installation.
653 Furthermore it may help to diagnose an incomplete installation.
655 Presently most packages do not have any @code{installcheck} tests
656 because the existence of @code{installcheck} is little known, and its
657 usefulness is neglected. Our little toy package is no better: @code{make
658 installcheck} does nothing.
660 @node Standard Targets
661 @subsection Standard @file{Makefile} Targets
663 So far we have come across four ways to run @command{make} in the GNU
664 Build System: @code{make}, @code{make check}, @code{make install}, and
665 @code{make installcheck}. The words @code{check}, @code{install}, and
666 @code{installcheck}, passed as arguments to @command{make}, are called
667 @dfn{targets}. @code{make} is a shorthand for @code{make all},
668 @code{all} being the default target in the GNU Build System.
670 Here is a list of the most useful targets that the GNU Coding Standards
676 Build programs, libraries, documentation, etc.@: (same as @code{make}).
679 Install what needs to be installed, copying the files from the
680 package's tree to system-wide directories.
681 @item make install-strip
682 @trindex install-strip
683 Same as @code{make install}, then strip debugging symbols. Some
684 users like to trade space for useful bug reports@enddots{}
687 The opposite of @code{make install}: erase the installed files.
688 (This needs to be run from the same build tree that was installed.)
691 Erase from the build tree the files built by @code{make all}.
694 Additionally erase anything @code{./configure} created.
697 Run the test suite, if any.
698 @item make installcheck
699 @trindex installcheck
700 Check the installed programs or libraries, if supported.
703 Recreate @file{@var{package}-@var{version}.tar.gz} from all the source
707 @node Standard Directory Variables
708 @subsection Standard Directory Variables
709 @cindex directory variables
711 The GNU Coding Standards also specify a hierarchy of variables to
712 denote installation directories. Some of these are:
714 @multitable {Directory variable} {@code{$@{datarootdir@}/doc/$@{PACKAGE@}}}
715 @headitem Directory variable @tab Default value
716 @item @code{prefix} @tab @code{/usr/local}
717 @item @w{@ @ @code{exec_prefix}} @tab @code{$@{prefix@}}
718 @item @w{@ @ @ @ @code{bindir}} @tab @code{$@{exec_prefix@}/bin}
719 @item @w{@ @ @ @ @code{libdir}} @tab @code{$@{exec_prefix@}/lib}
720 @item @w{@ @ @ @ @dots{}}
721 @item @w{@ @ @code{includedir}} @tab @code{$@{prefix@}/include}
722 @item @w{@ @ @code{datarootdir}} @tab @code{$@{prefix@}/share}
723 @item @w{@ @ @ @ @code{datadir}} @tab @code{$@{datarootdir@}}
724 @item @w{@ @ @ @ @code{mandir}} @tab @code{$@{datarootdir@}/man}
725 @item @w{@ @ @ @ @code{infodir}} @tab @code{$@{datarootdir@}/info}
726 @item @w{@ @ @ @ @code{docdir}} @tab @code{$@{datarootdir@}/doc/$@{PACKAGE@}}
727 @item @w{@ @ @dots{}}
730 @c We should provide a complete table somewhere, but not here. The
731 @c complete list of directory variables it too confusing as-is. It
732 @c requires some explanations that are too complicated for this
733 @c introduction. Besides listing directories like localstatedir
734 @c would make the explanations in ``Two-Part Install'' harder.
736 Each of these directories has a role which is often obvious from its
737 name. In a package, any installable file will be installed in one of
738 these directories. For instance in @code{amhello-1.0}, the program
739 @file{hello} is to be installed in @var{bindir}, the directory for
740 binaries. The default value for this directory is
741 @file{/usr/local/bin}, but the user can supply a different value when
742 calling @command{configure}. Also the file @file{README} will be
743 installed into @var{docdir}, which defaults to
744 @file{/usr/local/share/doc/amhello}.
748 As a user, if you wish to install a package on your own account, you
749 could proceed as follows:
752 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr}
754 ~/amhello-1.0 % @kbd{make}
756 ~/amhello-1.0 % @kbd{make install}
760 This would install @file{~/usr/bin/hello} and
761 @file{~/usr/share/doc/amhello/README}.
763 The list of all such directory options is shown by
764 @code{./configure --help}.
766 @node Standard Configuration Variables
767 @subsection Standard Configuration Variables
768 @cindex configuration variables, overriding
770 The GNU Coding Standards also define a set of standard configuration
771 variables used during the build. Here are some:
780 @item @code{CXXFLAGS}
784 @item @code{CPPFLAGS}
785 C/C++ preprocessor flags
789 @command{configure} usually does a good job at setting appropriate
790 values for these variables, but there are cases where you may want to
791 override them. For instance you may have several versions of a
792 compiler installed and would like to use another one, you may have
793 header files installed outside the default search path of the
794 compiler, or even libraries out of the way of the linker.
796 Here is how one would call @command{configure} to force it to use
797 @command{gcc-3} as C compiler, use header files from
798 @file{~/usr/include} when compiling, and libraries from
799 @file{~/usr/lib} when linking.
802 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr CC=gcc-3 \
803 CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib}
806 Again, a full list of these variables appears in the output of
807 @code{./configure --help}.
810 @subsection Overriding Default Configuration Setting with @file{config.site}
811 @cindex @file{config.site} example
813 When installing several packages using the same setup, it can be
814 convenient to create a file to capture common settings.
815 If a file named @file{@var{prefix}/share/config.site} exists,
816 @command{configure} will source it at the beginning of its execution.
818 Recall the command from the previous section:
821 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr CC=gcc-3 \
822 CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib}
825 Assuming we are installing many package in @file{~/usr}, and will
826 always want to use these definitions of @code{CC}, @code{CPPFLAGS}, and
827 @code{LDFLAGS}, we can automate this by creating the following
828 @file{~/usr/share/config.site} file:
831 test -z "$CC" && CC=gcc-3
832 test -z "$CPPFLAGS" && CPPFLAGS=-I$HOME/usr/include
833 test -z "$LDFLAGS" && LDFLAGS=-L$HOME/usr/lib
836 Now, any time a @file{configure} script is using the @file{~/usr}
837 prefix, it will execute the above @file{config.site} and define
838 these three variables.
841 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr}
842 configure: loading site script /home/adl/usr/share/config.site
846 @xref{Site Defaults, , Setting Site Defaults, autoconf, The Autoconf
847 Manual}, for more information about this feature.
851 @subsection Parallel Build Trees (a.k.a.@: VPATH Builds)
852 @cindex Parallel build trees
854 @cindex source tree and build tree
855 @cindex build tree and source tree
856 @cindex trees, source vs.@: build
858 The GNU Build System distinguishes two trees: the source tree, and
861 The source tree is rooted in the directory containing
862 @file{configure}. It contains all the sources files (those that are
863 distributed), and may be arranged using several subdirectories.
865 The build tree is rooted in the directory in which @file{configure}
866 was run, and is populated with all object files, programs, libraries,
867 and other derived files built from the sources (and hence not
868 distributed). The build tree usually has the same subdirectory layout
869 as the source tree; its subdirectories are created automatically by
872 If @file{configure} is executed in its own directory, the source and
873 build trees are combined: derived files are constructed in the same
874 directories as their sources. This was the case in our first
875 installation example (@pxref{Basic Installation}).
877 A common request from users is that they want to confine all derived
878 files to a single directory, to keep their source directories
879 uncluttered. Here is how we could run @file{configure} to build
880 everything in a subdirectory called @file{build/}.
883 ~ % @kbd{tar zxf ~/amhello-1.0.tar.gz}
884 ~ % @kbd{cd amhello-1.0}
885 ~/amhello-1.0 % @kbd{mkdir build && cd build}
886 ~/amhello-1.0/build % @kbd{../configure}
888 ~/amhello-1.0/build % @kbd{make}
892 These setups, where source and build trees are different, are often
893 called @dfn{parallel builds} or @dfn{VPATH builds}. The expression
894 @emph{parallel build} is misleading: the word @emph{parallel} is a
895 reference to the way the build tree shadows the source tree, it is not
896 about some concurrency in the way build commands are run. For this
897 reason we refer to such setups using the name @emph{VPATH builds} in
898 the following. @emph{VPATH} is the name of the @command{make} feature
899 used by the @file{Makefile}s to allow these builds (@pxref{General
900 Search, , @code{VPATH} Search Path for All Prerequisites, make, The
903 @cindex multiple configurations, example
904 @cindex debug build, example
905 @cindex optimized build, example
907 VPATH builds have other interesting uses. One is to build the same
908 sources with multiple configurations. For instance:
910 @c Keep in sync with amhello-cflags.sh
912 ~ % @kbd{tar zxf ~/amhello-1.0.tar.gz}
913 ~ % @kbd{cd amhello-1.0}
914 ~/amhello-1.0 % @kbd{mkdir debug optim && cd debug}
915 ~/amhello-1.0/debug % @kbd{../configure CFLAGS='-g -O0'}
917 ~/amhello-1.0/debug % @kbd{make}
919 ~/amhello-1.0/debug % cd ../optim
920 ~/amhello-1.0/optim % @kbd{../configure CFLAGS='-O3 -fomit-frame-pointer'}
922 ~/amhello-1.0/optim % @kbd{make}
926 With network file systems, a similar approach can be used to build the
927 same sources on different machines. For instance, suppose that the
928 sources are installed on a directory shared by two hosts: @code{HOST1}
929 and @code{HOST2}, which may be different platforms.
932 ~ % @kbd{cd /nfs/src}
933 /nfs/src % @kbd{tar zxf ~/amhello-1.0.tar.gz}
936 On the first host, you could create a local build directory:
938 [HOST1] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
939 [HOST1] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure}
941 [HOST1] /tmp/amh % @kbd{make && sudo make install}
946 (Here we assume that the installer has configured @command{sudo} so it
947 can execute @code{make install} with root privileges; it is more convenient
948 than using @command{su} like in @ref{Basic Installation}).
950 On the second host, you would do exactly the same, possibly at
953 [HOST2] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
954 [HOST2] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure}
956 [HOST2] /tmp/amh % @kbd{make && sudo make install}
960 @cindex read-only source tree
961 @cindex source tree, read-only
963 In this scenario, nothing forbids the @file{/nfs/src/amhello-1.0}
964 directory from being read-only. In fact VPATH builds are also a means
965 of building packages from a read-only medium such as a CD-ROM. (The
966 FSF used to sell CD-ROM with unpacked source code, before the GNU
967 project grew so big.)
969 @node Two-Part Install
970 @subsection Two-Part Installation
972 In our last example (@pxref{VPATH Builds}), a source tree was shared
973 by two hosts, but compilation and installation were done separately on
976 The GNU Build System also supports networked setups where part of the
977 installed files should be shared amongst multiple hosts. It does so
978 by distinguishing architecture-dependent files from
979 architecture-independent files, and providing two @file{Makefile}
980 targets to install each of these classes of files.
982 @trindex install-exec
983 @trindex install-data
985 These targets are @code{install-exec} for architecture-dependent files
986 and @code{install-data} for architecture-independent files.
987 The command we used up to now, @code{make install}, can be thought of
988 as a shorthand for @code{make install-exec install-data}.
990 From the GNU Build System point of view, the distinction between
991 architecture-dependent files and architecture-independent files is
992 based exclusively on the directory variable used to specify their
993 installation destination. In the list of directory variables we
994 provided earlier (@pxref{Standard Directory Variables}), all the
995 variables based on @var{exec-prefix} designate architecture-dependent
996 directories whose files will be installed by @code{make install-exec}.
997 The others designate architecture-independent directories and will
998 serve files installed by @code{make install-data}. @xref{The Two Parts
999 of Install}, for more details.
1001 Here is how we could revisit our two-host installation example,
1002 assuming that (1) we want to install the package directly in
1003 @file{/usr}, and (2) the directory @file{/usr/share} is shared by the
1006 On the first host we would run
1008 [HOST1] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
1009 [HOST1] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure --prefix /usr}
1011 [HOST1] /tmp/amh % @kbd{make && sudo make install}
1015 On the second host, however, we need only install the
1016 architecture-specific files.
1018 [HOST2] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
1019 [HOST2] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure --prefix /usr}
1021 [HOST2] /tmp/amh % @kbd{make && sudo make install-exec}
1025 In packages that have installation checks, it would make sense to run
1026 @code{make installcheck} (@pxref{Basic Installation}) to verify that
1027 the package works correctly despite the apparent partial installation.
1029 @node Cross-Compilation
1030 @subsection Cross-Compilation
1031 @cindex cross-compilation
1033 To @dfn{cross-compile} is to build on one platform a binary that will
1034 run on another platform. When speaking of cross-compilation, it is
1035 important to distinguish between the @dfn{build platform} on which
1036 the compilation is performed, and the @dfn{host platform} on which the
1037 resulting executable is expected to run. The following
1038 @command{configure} options are used to specify each of them:
1041 @item --build=@var{build}
1042 @opindex --build=@var{build}
1043 The system on which the package is built.
1044 @item --host=@var{host}
1045 @opindex --host=@var{host}
1046 The system where built programs and libraries will run.
1049 When the @option{--host} is used, @command{configure} will search for
1050 the cross-compiling suite for this platform. Cross-compilation tools
1051 commonly have their target architecture as prefix of their name. For
1052 instance my cross-compiler for MinGW32 has its binaries called
1053 @code{i586-mingw32msvc-gcc}, @code{i586-mingw32msvc-ld},
1054 @code{i586-mingw32msvc-as}, etc.
1056 @cindex MinGW cross-compilation example
1057 @cindex cross-compilation example
1059 Here is how we could build @code{amhello-1.0} for
1060 @code{i586-mingw32msvc} on a GNU/Linux PC.
1062 @c Keep in sync with amhello-cross-compile.sh
1064 ~/amhello-1.0 % @kbd{./configure --build i686-pc-linux-gnu --host i586-mingw32msvc}
1065 checking for a BSD-compatible install... /usr/bin/install -c
1066 checking whether build environment is sane... yes
1067 checking for gawk... gawk
1068 checking whether make sets $(MAKE)... yes
1069 checking for i586-mingw32msvc-strip... i586-mingw32msvc-strip
1070 checking for i586-mingw32msvc-gcc... i586-mingw32msvc-gcc
1071 checking for C compiler default output file name... a.exe
1072 checking whether the C compiler works... yes
1073 checking whether we are cross compiling... yes
1074 checking for suffix of executables... .exe
1075 checking for suffix of object files... o
1076 checking whether we are using the GNU C compiler... yes
1077 checking whether i586-mingw32msvc-gcc accepts -g... yes
1078 checking for i586-mingw32msvc-gcc option to accept ANSI C...
1080 ~/amhello-1.0 % @kbd{make}
1082 ~/amhello-1.0 % @kbd{cd src; file hello.exe}
1083 hello.exe: MS Windows PE 32-bit Intel 80386 console executable not relocatable
1086 The @option{--host} and @option{--build} options are usually all we
1087 need for cross-compiling. The only exception is if the package being
1088 built is itself a cross-compiler: we need a third option to specify
1089 its target architecture.
1092 @item --target=@var{target}
1093 @opindex --target=@var{target}
1094 When building compiler tools: the system for which the tools will
1098 For instance when installing GCC, the GNU Compiler Collection, we can
1099 use @option{--target=@/@var{target}} to specify that we want to build
1100 GCC as a cross-compiler for @var{target}. Mixing @option{--build} and
1101 @option{--target}, we can actually cross-compile a cross-compiler;
1102 such a three-way cross-compilation is known as a @dfn{Canadian cross}.
1104 @xref{Specifying Names, , Specifying the System Type, autoconf, The
1105 Autoconf Manual}, for more information about these @command{configure}
1109 @subsection Renaming Programs at Install Time
1110 @cindex Renaming programs
1111 @cindex Transforming program names
1112 @cindex Programs, renaming during installation
1114 The GNU Build System provides means to automatically rename
1115 executables and manpages before they are installed (@pxref{Man Pages}).
1116 This is especially convenient
1117 when installing a GNU package on a system that already has a
1118 proprietary implementation you do not want to overwrite. For instance,
1119 you may want to install GNU @command{tar} as @command{gtar} so you can
1120 distinguish it from your vendor's @command{tar}.
1122 This can be done using one of these three @command{configure} options.
1125 @item --program-prefix=@var{prefix}
1126 @opindex --program-prefix=@var{prefix}
1127 Prepend @var{prefix} to installed program names.
1128 @item --program-suffix=@var{suffix}
1129 @opindex --program-suffix=@var{suffix}
1130 Append @var{suffix} to installed program names.
1131 @item --program-transform-name=@var{program}
1132 @opindex --program-transform-name=@var{program}
1133 Run @code{sed @var{program}} on installed program names.
1136 The following commands would install @file{hello}
1137 as @file{/usr/local/bin/test-hello}, for instance.
1140 ~/amhello-1.0 % @kbd{./configure --program-prefix test-}
1142 ~/amhello-1.0 % @kbd{make}
1144 ~/amhello-1.0 % @kbd{sudo make install}
1149 @subsection Building Binary Packages Using DESTDIR
1152 The GNU Build System's @code{make install} and @code{make uninstall}
1153 interface does not exactly fit the needs of a system administrator
1154 who has to deploy and upgrade packages on lots of hosts. In other
1155 words, the GNU Build System does not replace a package manager.
1157 Such package managers usually need to know which files have been
1158 installed by a package, so a mere @code{make install} is
1161 @cindex Staged installation
1163 The @code{DESTDIR} variable can be used to perform a staged
1164 installation. The package should be configured as if it was going to
1165 be installed in its final location (e.g., @code{--prefix /usr}), but
1166 when running @code{make install}, the @code{DESTDIR} should be set to
1167 the absolute name of a directory into which the installation will be
1168 diverted. From this directory it is easy to review which files are
1169 being installed where, and finally copy them to their final location
1172 @cindex Binary package
1174 For instance here is how we could create a binary package containing a
1175 snapshot of all the files to be installed.
1177 @c Keep in sync with amhello-binpkg.sh
1179 ~/amhello-1.0 % @kbd{./configure --prefix /usr}
1181 ~/amhello-1.0 % @kbd{make}
1183 ~/amhello-1.0 % @kbd{make DESTDIR=$HOME/inst install}
1185 ~/amhello-1.0 % @kbd{cd ~/inst}
1186 ~/inst % @kbd{find . -type f -print > ../files.lst}
1187 ~/inst % @kbd{tar zcvf ~/amhello-1.0-i686.tar.gz `cat ../files.lst`}
1189 ./usr/share/doc/amhello/README
1192 After this example, @code{amhello-1.0-i686.tar.gz} is ready to be
1193 uncompressed in @file{/} on many hosts. (Using @code{`cat ../files.lst`}
1194 instead of @samp{.} as argument for @command{tar} avoids entries for
1195 each subdirectory in the archive: we would not like @command{tar} to
1196 restore the modification time of @file{/}, @file{/usr/}, etc.)
1198 Note that when building packages for several architectures, it might
1199 be convenient to use @code{make install-data} and @code{make
1200 install-exec} (@pxref{Two-Part Install}) to gather
1201 architecture-independent files in a single package.
1203 @xref{Install}, for more information.
1205 @c We should document PRE_INSTALL/POST_INSTALL/NORMAL_INSTALL and their
1206 @c UNINSTALL counterparts.
1208 @node Preparing Distributions
1209 @subsection Preparing Distributions
1210 @cindex Preparing distributions
1211 @cindex Packages, preparation
1212 @cindex Distributions, preparation
1214 We have already mentioned @code{make dist}. This target collects all
1215 your source files and the necessary parts of the build system to
1216 create a tarball named @file{@var{package}-@var{version}.tar.gz}.
1218 @cindex @code{distcheck} better than @code{dist}
1220 Another, more useful command is @code{make distcheck}. The
1221 @code{distcheck} target constructs
1222 @file{@var{package}-@var{version}.tar.gz} just as well as @code{dist},
1223 but it additionally ensures most of the use cases presented so far
1228 It attempts a full compilation of the package (@pxref{Basic
1229 Installation}), unpacking the newly constructed tarball, running
1230 @code{make}, @code{make check}, @code{make install}, as well as
1231 @code{make installcheck}, and even @code{make dist},
1233 it tests VPATH builds with read-only source tree (@pxref{VPATH Builds}),
1235 it makes sure @code{make clean}, @code{make distclean}, and @code{make
1236 uninstall} do not omit any file (@pxref{Standard Targets}),
1238 and it checks that @code{DESTDIR} installations work (@pxref{DESTDIR}).
1241 All of these actions are performed in a temporary subdirectory, so
1242 that no root privileges are required.
1244 Releasing a package that fails @code{make distcheck} means that one of
1245 the scenarios we presented will not work and some users will be
1246 disappointed. Therefore it is a good practice to release a package
1247 only after a successful @code{make distcheck}. This of course does
1248 not imply that the package will be flawless, but at least it will
1249 prevent some of the embarrassing errors you may find in packages
1250 released by people who have never heard about @code{distcheck} (like
1251 @code{DESTDIR} not working because of a typo, or a distributed file
1252 being erased by @code{make clean}, or even @code{VPATH} builds not
1255 @xref{Creating amhello}, to recreate @file{amhello-1.0.tar.gz} using
1256 @code{make distcheck}. @xref{Checking the Distribution}, for more
1257 information about @code{distcheck}.
1259 @node Dependency Tracking
1260 @subsection Automatic Dependency Tracking
1261 @cindex Dependency tracking
1263 Dependency tracking is performed as a side-effect of compilation.
1264 Each time the build system compiles a source file, it computes its
1265 list of dependencies (in C these are the header files included by the
1266 source being compiled). Later, any time @command{make} is run and a
1267 dependency appears to have changed, the dependent files will be
1270 Automake generates code for automatic dependency tracking by default,
1271 unless the developer chooses to override it; for more information,
1272 @pxref{Dependencies}.
1274 When @command{configure} is executed, you can see it probing each
1275 compiler for the dependency mechanism it supports (several mechanisms
1279 ~/amhello-1.0 % @kbd{./configure --prefix /usr}
1281 checking dependency style of gcc... gcc3
1285 Because dependencies are only computed as a side-effect of the
1286 compilation, no dependency information exists the first time a package
1287 is built. This is OK because all the files need to be built anyway:
1288 @code{make} does not have to decide which files need to be rebuilt.
1289 In fact, dependency tracking is completely useless for one-time builds
1290 and there is a @command{configure} option to disable this:
1293 @item --disable-dependency-tracking
1294 @opindex --disable-dependency-tracking
1295 Speed up one-time builds.
1298 Some compilers do not offer any practical way to derive the list of
1299 dependencies as a side-effect of the compilation, requiring a separate
1300 run (maybe of another tool) to compute these dependencies. The
1301 performance penalty implied by these methods is important enough to
1302 disable them by default. The option @option{--enable-dependency-tracking}
1303 must be passed to @command{configure} to activate them.
1306 @item --enable-dependency-tracking
1307 @opindex --enable-dependency-tracking
1308 Do not reject slow dependency extractors.
1311 @xref{Dependency Tracking Evolution, , Dependency Tracking Evolution,
1312 automake-history, Brief History of Automake}, for some discussion about
1313 the different dependency tracking schemes used by Automake over the years.
1315 @node Nested Packages
1316 @subsection Nested Packages
1317 @cindex Nested packages
1318 @cindex Packages, nested
1321 Although nesting packages isn't something we would recommend to
1322 someone who is discovering the Autotools, it is a nice feature worthy
1323 of mention in this small advertising tour.
1325 Autoconfiscated packages (that means packages whose build system have
1326 been created by Autoconf and friends) can be nested to arbitrary
1329 A typical setup is that package A will distribute one of the libraries
1330 it needs in a subdirectory. This library B is a complete package with
1331 its own GNU Build System. The @command{configure} script of A will
1332 run the @command{configure} script of B as part of its execution,
1333 building and installing A will also build and install B. Generating a
1334 distribution for A will also include B.
1336 It is possible to gather several packages like this. GCC is a heavy
1337 user of this feature. This gives installers a single package to
1338 configure, build and install, while it allows developers to work on
1339 subpackages independently.
1341 When configuring nested packages, the @command{configure} options
1342 given to the top-level @command{configure} are passed recursively to
1343 nested @command{configure}s. A package that does not understand an
1344 option will ignore it, assuming it is meaningful to some other
1347 @opindex --help=recursive
1349 The command @code{configure --help=recursive} can be used to display
1350 the options supported by all the included packages.
1352 @xref{Subpackages}, for an example setup.
1355 @section How Autotools Help
1356 @cindex Autotools, purpose
1358 There are several reasons why you may not want to implement the GNU
1359 Build System yourself (read: write a @file{configure} script and
1360 @file{Makefile}s yourself).
1364 As we have seen, the GNU Build System has a lot of
1365 features (@pxref{Use Cases}).
1366 Some users may expect features you have not implemented because
1367 you did not need them.
1369 Implementing these features portably is difficult and exhausting.
1370 Think of writing portable shell scripts, and portable
1371 @file{Makefile}s, for systems you may not have handy. @xref{Portable
1372 Shell, , Portable Shell Programming, autoconf, The Autoconf Manual}, to
1375 You will have to upgrade your setup to follow changes to the GNU
1379 The GNU Autotools take all this burden off your back and provide:
1383 Tools to create a portable, complete, and self-contained GNU Build
1384 System, from simple instructions.
1385 @emph{Self-contained} meaning the resulting build system does not
1386 require the GNU Autotools.
1388 A central place where fixes and improvements are made:
1389 a bug-fix for a portability issue will benefit every package.
1392 Yet there also exist reasons why you may want NOT to use the
1393 Autotools@enddots{} For instance you may be already using (or used to)
1394 another incompatible build system. Autotools will only be useful if
1395 you do accept the concepts of the GNU Build System. People who have their
1396 own idea of how a build system should work will feel frustrated by the
1400 @section A Small Hello World
1401 @cindex Example Hello World
1402 @cindex Hello World example
1403 @cindex @file{amhello-1.0.tar.gz}, creation
1405 In this section we recreate the @file{amhello-1.0} package from
1406 scratch. The first subsection shows how to call the Autotools to
1407 instantiate the GNU Build System, while the second explains the
1408 meaning of the @file{configure.ac} and @file{Makefile.am} files read
1411 @anchor{amhello Explained}
1413 * Creating amhello:: Create @file{amhello-1.0.tar.gz} from scratch
1414 * amhello's configure.ac Setup Explained::
1415 * amhello's Makefile.am Setup Explained::
1418 @node Creating amhello
1419 @subsection Creating @file{amhello-1.0.tar.gz}
1421 Here is how we can recreate @file{amhello-1.0.tar.gz} from scratch.
1422 The package is simple enough so that we will only need to write 5
1423 files. (You may copy them from the final @file{amhello-1.0.tar.gz}
1424 that is distributed with Automake if you do not want to write them.)
1426 Create the following files in an empty directory.
1431 @file{src/main.c} is the source file for the @file{hello} program. We
1432 store it in the @file{src/} subdirectory, because later, when the package
1433 evolves, it will ease the addition of a @file{man/} directory for man
1434 pages, a @file{data/} directory for data files, etc.
1436 ~/amhello % @kbd{cat src/main.c}
1443 puts ("Hello World!");
1444 puts ("This is " PACKAGE_STRING ".");
1450 @file{README} contains some very limited documentation for our little
1453 ~/amhello % @kbd{cat README}
1454 This is a demonstration package for GNU Automake.
1455 Type 'info Automake' to read the Automake manual.
1459 @file{Makefile.am} and @file{src/Makefile.am} contain Automake
1460 instructions for these two directories.
1463 ~/amhello % @kbd{cat src/Makefile.am}
1464 bin_PROGRAMS = hello
1465 hello_SOURCES = main.c
1466 ~/amhello % @kbd{cat Makefile.am}
1468 dist_doc_DATA = README
1472 Finally, @file{configure.ac} contains Autoconf instructions to
1473 create the @command{configure} script.
1476 ~/amhello % @kbd{cat configure.ac}
1477 AC_INIT([amhello], [1.0], [@value{PACKAGE_BUGREPORT}])
1478 AM_INIT_AUTOMAKE([-Wall -Werror foreign])
1480 AC_CONFIG_HEADERS([config.h])
1489 @cindex @command{autoreconf}, example
1491 Once you have these five files, it is time to run the Autotools to
1492 instantiate the build system. Do this using the @command{autoreconf}
1496 ~/amhello % @kbd{autoreconf --install}
1497 configure.ac: installing './install-sh'
1498 configure.ac: installing './missing'
1499 configure.ac: installing './compile'
1500 src/Makefile.am: installing './depcomp'
1503 At this point the build system is complete.
1505 In addition to the three scripts mentioned in its output, you can see
1506 that @command{autoreconf} created four other files: @file{configure},
1507 @file{config.h.in}, @file{Makefile.in}, and @file{src/Makefile.in}.
1508 The latter three files are templates that will be adapted to the
1509 system by @command{configure} under the names @file{config.h},
1510 @file{Makefile}, and @file{src/Makefile}. Let's do this:
1513 ~/amhello % @kbd{./configure}
1514 checking for a BSD-compatible install... /usr/bin/install -c
1515 checking whether build environment is sane... yes
1516 checking for gawk... no
1517 checking for mawk... mawk
1518 checking whether make sets $(MAKE)... yes
1519 checking for gcc... gcc
1520 checking for C compiler default output file name... a.out
1521 checking whether the C compiler works... yes
1522 checking whether we are cross compiling... no
1523 checking for suffix of executables...
1524 checking for suffix of object files... o
1525 checking whether we are using the GNU C compiler... yes
1526 checking whether gcc accepts -g... yes
1527 checking for gcc option to accept ISO C89... none needed
1528 checking for style of include used by make... GNU
1529 checking dependency style of gcc... gcc3
1530 configure: creating ./config.status
1531 config.status: creating Makefile
1532 config.status: creating src/Makefile
1533 config.status: creating config.h
1534 config.status: executing depfiles commands
1538 @cindex @code{distcheck} example
1540 You can see @file{Makefile}, @file{src/Makefile}, and @file{config.h}
1541 being created at the end after @command{configure} has probed the
1542 system. It is now possible to run all the targets we wish
1543 (@pxref{Standard Targets}). For instance:
1546 ~/amhello % @kbd{make}
1548 ~/amhello % @kbd{src/hello}
1550 This is amhello 1.0.
1551 ~/amhello % @kbd{make distcheck}
1553 =============================================
1554 amhello-1.0 archives ready for distribution:
1556 =============================================
1559 Note that running @command{autoreconf} is only needed initially when
1560 the GNU Build System does not exist. When you later change some
1561 instructions in a @file{Makefile.am} or @file{configure.ac}, the
1562 relevant part of the build system will be regenerated automatically
1563 when you execute @command{make}.
1565 @command{autoreconf} is a script that calls @command{autoconf},
1566 @command{automake}, and a bunch of other commands in the right order.
1567 If you are beginning with these tools, it is not important to figure
1568 out in which order all of these tools should be invoked and why. However,
1569 because Autoconf and Automake have separate manuals, the important
1570 point to understand is that @command{autoconf} is in charge of
1571 creating @file{configure} from @file{configure.ac}, while
1572 @command{automake} is in charge of creating @file{Makefile.in}s from
1573 @file{Makefile.am}s and @file{configure.ac}. This should at least
1574 direct you to the right manual when seeking answers.
1577 @node amhello's configure.ac Setup Explained
1578 @subsection @code{amhello}'s @file{configure.ac} Setup Explained
1580 @cindex @file{configure.ac}, Hello World
1582 Let us begin with the contents of @file{configure.ac}.
1585 AC_INIT([amhello], [1.0], [@value{PACKAGE_BUGREPORT}])
1586 AM_INIT_AUTOMAKE([-Wall -Werror foreign])
1588 AC_CONFIG_HEADERS([config.h])
1596 This file is read by both @command{autoconf} (to create
1597 @file{configure}) and @command{automake} (to create the various
1598 @file{Makefile.in}s). It contains a series of M4 macros that will be
1599 expanded as shell code to finally form the @file{configure} script.
1600 We will not elaborate on the syntax of this file, because the Autoconf
1601 manual has a whole section about it (@pxref{Writing Autoconf Input, ,
1602 Writing @file{configure.ac}, autoconf, The Autoconf Manual}).
1604 The macros prefixed with @code{AC_} are Autoconf macros, documented
1605 in the Autoconf manual (@pxref{Autoconf Macro Index, , Autoconf Macro
1606 Index, autoconf, The Autoconf Manual}). The macros that start with
1607 @code{AM_} are Automake macros, documented later in this manual
1608 (@pxref{Macro Index}).
1610 The first two lines of @file{configure.ac} initialize Autoconf and
1611 Automake. @code{AC_INIT} takes in as parameters the name of the package,
1612 its version number, and a contact address for bug-reports about the
1613 package (this address is output at the end of @code{./configure
1614 --help}, for instance). When adapting this setup to your own package,
1615 by all means please do not blindly copy Automake's address: use the
1616 mailing list of your package, or your own mail address.
1622 The argument to @code{AM_INIT_AUTOMAKE} is a list of options for
1623 @command{automake} (@pxref{Options}). @option{-Wall} and
1624 @option{-Werror} ask @command{automake} to turn on all warnings and
1625 report them as errors. We are speaking of @strong{Automake} warnings
1626 here, such as dubious instructions in @file{Makefile.am}. This has
1627 absolutely nothing to do with how the compiler will be called, even
1628 though it may support options with similar names. Using @option{-Wall
1629 -Werror} is a safe setting when starting to work on a package: you do
1630 not want to miss any issues. Later you may decide to relax things a
1631 bit. The @option{foreign} option tells Automake that this package
1632 will not follow the GNU Standards. GNU packages should always
1633 distribute additional files such as @file{ChangeLog}, @file{AUTHORS},
1634 etc. We do not want @command{automake} to complain about these
1635 missing files in our small example.
1637 The @code{AC_PROG_CC} line causes the @command{configure} script to
1638 search for a C compiler and define the variable @code{CC} with its
1639 name. The @file{src/Makefile.in} file generated by Automake uses the
1640 variable @code{CC} to build @file{hello}, so when @command{configure}
1641 creates @file{src/Makefile} from @file{src/Makefile.in}, it will define
1642 @code{CC} with the value it has found. If Automake is asked to create
1643 a @file{Makefile.in} that uses @code{CC} but @file{configure.ac} does
1644 not define it, it will suggest you add a call to @code{AC_PROG_CC}.
1646 The @code{AC_CONFIG_HEADERS([config.h])} invocation causes the
1647 @command{configure} script to create a @file{config.h} file gathering
1648 @samp{#define}s defined by other macros in @file{configure.ac}. In our
1649 case, the @code{AC_INIT} macro already defined a few of them. Here
1650 is an excerpt of @file{config.h} after @command{configure} has run:
1654 /* Define to the address where bug reports for this package should be sent. */
1655 #define PACKAGE_BUGREPORT "@value{PACKAGE_BUGREPORT}"
1657 /* Define to the full name and version of this package. */
1658 #define PACKAGE_STRING "amhello 1.0"
1662 As you probably noticed, @file{src/main.c} includes @file{config.h} so
1663 it can use @code{PACKAGE_STRING}. In a real-world project,
1664 @file{config.h} can grow really big, with one @samp{#define} per
1665 feature probed on the system.
1667 The @code{AC_CONFIG_FILES} macro declares the list of files that
1668 @command{configure} should create from their @file{*.in} templates.
1669 Automake also scans this list to find the @file{Makefile.am} files it must
1670 process. (This is important to remember: when adding a new directory
1671 to your project, you should add its @file{Makefile} to this list,
1672 otherwise Automake will never process the new @file{Makefile.am} you
1673 wrote in that directory.)
1675 Finally, the @code{AC_OUTPUT} line is a closing command that actually
1676 produces the part of the script in charge of creating the files
1677 registered with @code{AC_CONFIG_HEADERS} and @code{AC_CONFIG_FILES}.
1679 @cindex @command{autoscan}
1681 When starting a new project, we suggest you start with such a simple
1682 @file{configure.ac}, and gradually add the other tests it requires.
1683 The command @command{autoscan} can also suggest a few of the tests
1684 your package may need (@pxref{autoscan Invocation, , Using
1685 @command{autoscan} to Create @file{configure.ac}, autoconf, The
1689 @node amhello's Makefile.am Setup Explained
1690 @subsection @code{amhello}'s @file{Makefile.am} Setup Explained
1692 @cindex @file{Makefile.am}, Hello World
1694 We now turn to @file{src/Makefile.am}. This file contains
1695 Automake instructions to build and install @file{hello}.
1698 bin_PROGRAMS = hello
1699 hello_SOURCES = main.c
1702 A @file{Makefile.am} has the same syntax as an ordinary
1703 @file{Makefile}. When @command{automake} processes a
1704 @file{Makefile.am} it copies the entire file into the output
1705 @file{Makefile.in} (that will be later turned into @file{Makefile} by
1706 @command{configure}) but will react to certain variable definitions
1707 by generating some build rules and other variables.
1708 Often @file{Makefile.am}s contain only a list of variable definitions as
1709 above, but they can also contain other variable and rule definitions that
1710 @command{automake} will pass along without interpretation.
1712 Variables that end with @code{_PROGRAMS} are special variables
1713 that list programs that the resulting @file{Makefile} should build.
1714 In Automake speak, this @code{_PROGRAMS} suffix is called a
1715 @dfn{primary}; Automake recognizes other primaries such as
1716 @code{_SCRIPTS}, @code{_DATA}, @code{_LIBRARIES}, etc.@: corresponding
1717 to different types of files.
1719 The @samp{bin} part of the @code{bin_PROGRAMS} tells
1720 @command{automake} that the resulting programs should be installed in
1721 @var{bindir}. Recall that the GNU Build System uses a set of variables
1722 to denote destination directories and allow users to customize these
1723 locations (@pxref{Standard Directory Variables}). Any such directory
1724 variable can be put in front of a primary (omitting the @code{dir}
1725 suffix) to tell @command{automake} where to install the listed files.
1727 Programs need to be built from source files, so for each program
1728 @code{@var{prog}} listed in a @code{@w{_PROGRAMS}} variable,
1729 @command{automake} will look for another variable named
1730 @code{@var{prog}_SOURCES} listing its source files. There may be more
1731 than one source file: they will all be compiled and linked together.
1733 Automake also knows that source files need to be distributed when
1734 creating a tarball (unlike built programs). So a side-effect of this
1735 @code{hello_SOURCES} declaration is that @file{main.c} will be
1736 part of the tarball created by @code{make dist}.
1738 Finally here are some explanations regarding the top-level
1743 dist_doc_DATA = README
1746 @code{SUBDIRS} is a special variable listing all directories that
1747 @command{make} should recurse into before processing the current
1748 directory. So this line is responsible for @command{make} building
1749 @file{src/hello} even though we run it from the top-level. This line
1750 also causes @code{make install} to install @file{src/hello} before
1751 installing @file{README} (not that this order matters).
1753 The line @code{dist_doc_DATA = README} causes @file{README} to be
1754 distributed and installed in @var{docdir}. Files listed with the
1755 @code{_DATA} primary are not automatically part of the tarball built
1756 with @code{make dist}, so we add the @code{dist_} prefix so they get
1757 distributed. However, for @file{README} it would not have been
1758 necessary: @command{automake} automatically distributes any
1759 @file{README} file it encounters (the list of other files
1760 automatically distributed is presented by @code{automake --help}).
1761 The only important effect of this second line is therefore to install
1762 @file{README} during @code{make install}.
1764 One thing not covered in this example is accessing the installation
1765 directory values (@pxref{Standard Directory Variables}) from your
1766 program code, that is, converting them into defined macros. For this,
1767 @pxref{Defining Directories,,, autoconf, The Autoconf Manual}.
1771 @chapter General ideas
1773 The following sections cover a few basic ideas that will help you
1774 understand how Automake works.
1777 * General Operation:: General operation of Automake
1778 * Strictness:: Standards conformance checking
1779 * Uniform:: The Uniform Naming Scheme
1780 * Length Limitations:: Staying below the command line length limit
1781 * Canonicalization:: How derived variables are named
1782 * User Variables:: Variables reserved for the user
1783 * Auxiliary Programs:: Programs automake might require
1787 @node General Operation
1788 @section General Operation
1790 Automake works by reading a @file{Makefile.am} and generating a
1791 @file{Makefile.in}. Certain variables and rules defined in the
1792 @file{Makefile.am} instruct Automake to generate more specialized code;
1793 for instance, a @code{bin_PROGRAMS} variable definition will cause rules
1794 for compiling and linking programs to be generated.
1796 @cindex Non-standard targets
1797 @cindex @code{git-dist}, non-standard example
1800 The variable definitions and rules in the @file{Makefile.am} are
1801 copied mostly verbatim into the generated file, with all variable
1802 definitions preceding all rules. This allows you to add almost
1803 arbitrary code into the generated @file{Makefile.in}. For instance,
1804 the Automake distribution includes a non-standard rule for the
1805 @code{git-dist} target, which the Automake maintainer uses to make
1806 distributions from the source control system.
1808 @cindex GNU make extensions
1810 Note that most GNU make extensions are not recognized by Automake. Using
1811 such extensions in a @file{Makefile.am} will lead to errors or confusing
1814 @cindex Append operator
1816 A special exception is that the GNU make append operator, @samp{+=}, is
1817 supported. This operator appends its right hand argument to the variable
1818 specified on the left. Automake will translate the operator into
1819 an ordinary @samp{=} operator; @samp{+=} will thus work with any make program.
1821 Automake tries to keep comments grouped with any adjoining rules or
1822 variable definitions.
1824 @cindex Limitations of automake parser
1825 @cindex Automake parser, limitations of
1826 @cindex indentation in Makefile.am
1827 Generally, Automake is not particularly smart in the parsing of unusual
1828 Makefile constructs, so you're advised to avoid fancy constructs or
1829 ``creative'' use of whitespaces.
1830 @c Keep this in sync with doc-parsing-buglets-tabs.sh
1831 For example, @key{TAB} characters cannot be used between a target name
1832 and the following ``@code{:}'' character, and variable assignments
1833 shouldn't be indented with @key{TAB} characters.
1834 @c Keep this in sync with doc-parsing-buglets-colneq-subst.sh
1835 Also, using more complex macro in target names can cause trouble:
1838 % @kbd{cat Makefile.am}
1841 Makefile.am:1: bad characters in variable name '$(FOO'
1842 Makefile.am:1: ':='-style assignments are not portable
1845 @cindex Make targets, overriding
1846 @cindex Make rules, overriding
1847 @cindex Overriding make rules
1848 @cindex Overriding make targets
1850 A rule defined in @file{Makefile.am} generally overrides any such
1851 rule of a similar name that would be automatically generated by
1852 @command{automake}. Although this is a supported feature, it is generally
1853 best to avoid making use of it, as sometimes the generated rules are
1856 @cindex Variables, overriding
1857 @cindex Overriding make variables
1859 Similarly, a variable defined in @file{Makefile.am} or
1860 @code{AC_SUBST}ed from @file{configure.ac} will override any
1861 definition of the variable that @command{automake} would ordinarily
1862 create. This feature is more often useful than the ability to
1863 override a rule. Be warned that many of the variables generated by
1864 @command{automake} are considered to be for internal use only, and their
1865 names might change in future releases.
1867 @cindex Recursive operation of Automake
1868 @cindex Automake, recursive operation
1869 @cindex Example of recursive operation
1871 When examining a variable definition, Automake will recursively examine
1872 variables referenced in the definition. For example, if Automake is
1873 looking at the content of @code{foo_SOURCES} in this snippet
1875 @c Keep in sync with interp.sh
1878 foo_SOURCES = c.c $(xs)
1881 it would use the files @file{a.c}, @file{b.c}, and @file{c.c} as the
1882 contents of @code{foo_SOURCES}.
1884 @cindex @code{##} (special Automake comment)
1885 @cindex Special Automake comment
1886 @cindex Comment, special to Automake
1888 Automake also allows a form of comment that is @emph{not} copied into
1889 the output; all lines beginning with @samp{##} (leading spaces allowed)
1890 are completely ignored by Automake.
1892 It is customary to make the first line of @file{Makefile.am} read:
1894 @cindex Makefile.am, first line
1895 @cindex First line of Makefile.am
1898 ## Process this file with automake to produce Makefile.in
1901 @c FIXME discuss putting a copyright into Makefile.am here? I would but
1902 @c I don't know quite what to say.
1904 @c FIXME document customary ordering of Makefile.am here!
1910 @cindex Non-GNU packages
1912 While Automake is intended to be used by maintainers of GNU packages, it
1913 does make some effort to accommodate those who wish to use it, but do
1914 not want to use all the GNU conventions.
1916 @cindex Strictness, defined
1917 @cindex Strictness, @option{foreign}
1918 @cindex @option{foreign} strictness
1919 @cindex Strictness, @option{gnu}
1920 @cindex @option{gnu} strictness
1921 @cindex Strictness, @option{gnits}
1922 @cindex @option{gnits} strictness
1924 To this end, Automake supports three levels of @dfn{strictness}---the
1925 strictness indicating how stringently Automake should check standards
1928 The valid strictness levels are:
1932 Automake will check for only those things that are absolutely
1933 required for proper operations. For instance, whereas GNU standards
1934 dictate the existence of a @file{NEWS} file, it will not be required in
1935 this mode. This strictness will also turn off some warnings by default
1936 (among them, portability warnings).
1937 The name comes from the fact that Automake is intended to be
1938 used for GNU programs; these relaxed rules are not the standard mode of
1942 Automake will check---as much as possible---for compliance to the GNU
1943 standards for packages. This is the default.
1946 Automake will check for compliance to the as-yet-unwritten @dfn{Gnits
1947 standards}. These are based on the GNU standards, but are even more
1948 detailed. Unless you are a Gnits standards contributor, it is
1949 recommended that you avoid this option until such time as the Gnits
1950 standard is actually published (which may never happen).
1953 @xref{Gnits}, for more information on the precise implications of the
1958 @section The Uniform Naming Scheme
1960 @cindex Uniform naming scheme
1962 Automake variables generally follow a @dfn{uniform naming scheme} that
1963 makes it easy to decide how programs (and other derived objects) are
1964 built, and how they are installed. This scheme also supports
1965 @command{configure} time determination of what should be built.
1967 @cindex @code{_PROGRAMS} primary variable
1968 @cindex @code{PROGRAMS} primary variable
1969 @cindex Primary variable, @code{PROGRAMS}
1970 @cindex Primary variable, defined
1973 At @command{make} time, certain variables are used to determine which
1974 objects are to be built. The variable names are made of several pieces
1975 that are concatenated together.
1977 The piece that tells @command{automake} what is being built is commonly called
1978 the @dfn{primary}. For instance, the primary @code{PROGRAMS} holds a
1979 list of programs that are to be compiled and linked.
1982 @cindex @code{pkgdatadir}, defined
1983 @cindex @code{pkgincludedir}, defined
1984 @cindex @code{pkglibdir}, defined
1985 @cindex @code{pkglibexecdir}, defined
1988 @vindex pkgincludedir
1990 @vindex pkglibexecdir
1992 @cindex @code{PACKAGE}, directory
1993 A different set of names is used to decide where the built objects
1994 should be installed. These names are prefixes to the primary, and they
1995 indicate which standard directory should be used as the installation
1996 directory. The standard directory names are given in the GNU standards
1997 (@pxref{Directory Variables, , , standards, The GNU Coding Standards}).
1998 Automake extends this list with @code{pkgdatadir}, @code{pkgincludedir},
1999 @code{pkglibdir}, and @code{pkglibexecdir}; these are the same as the
2000 non-@samp{pkg} versions, but with @samp{$(PACKAGE)} appended. For instance,
2001 @code{pkglibdir} is defined as @samp{$(libdir)/$(PACKAGE)}.
2003 @cindex @code{EXTRA_}, prepending
2004 For each primary, there is one additional variable named by prepending
2005 @samp{EXTRA_} to the primary name. This variable is used to list
2006 objects that may or may not be built, depending on what
2007 @command{configure} decides. This variable is required because Automake
2008 must statically know the entire list of objects that may be built in
2009 order to generate a @file{Makefile.in} that will work in all cases.
2011 @cindex @code{EXTRA_PROGRAMS}, defined
2012 @cindex Example, @code{EXTRA_PROGRAMS}
2013 @cindex @command{cpio} example
2015 For instance, @command{cpio} decides at configure time which programs
2016 should be built. Some of the programs are installed in @code{bindir},
2017 and some are installed in @code{sbindir}:
2020 EXTRA_PROGRAMS = mt rmt
2021 bin_PROGRAMS = cpio pax
2022 sbin_PROGRAMS = $(MORE_PROGRAMS)
2025 Defining a primary without a prefix as a variable, e.g.,
2026 @samp{PROGRAMS}, is an error.
2028 Note that the common @samp{dir} suffix is left off when constructing the
2029 variable names; thus one writes @samp{bin_PROGRAMS} and not
2030 @samp{bindir_PROGRAMS}.
2032 Not every sort of object can be installed in every directory. Automake
2033 will flag those attempts it finds in error (but see below how to override
2034 the check if you really need to).
2035 Automake will also diagnose obvious misspellings in directory names.
2037 @cindex Extending list of installation directories
2038 @cindex Installation directories, extending list
2040 Sometimes the standard directories---even as augmented by
2041 Automake---are not enough. In particular it is sometimes useful, for
2042 clarity, to install objects in a subdirectory of some predefined
2043 directory. To this end, Automake allows you to extend the list of
2044 possible installation directories. A given prefix (e.g., @samp{zar})
2045 is valid if a variable of the same name with @samp{dir} appended is
2046 defined (e.g., @samp{zardir}).
2048 For instance, the following snippet will install @file{file.xml} into
2049 @samp{$(datadir)/xml}.
2051 @c Keep in sync with primary-prefix-couples-documented-valid.sh
2053 xmldir = $(datadir)/xml
2057 This feature can also be used to override the sanity checks Automake
2058 performs to diagnose suspicious directory/primary couples (in the
2059 unlikely case these checks are undesirable, and you really know what
2060 you're doing). For example, Automake would error out on this input:
2062 @c Should be tested in primary-prefix-invalid-couples.sh
2064 # Forbidden directory combinations, automake will error out on this.
2065 pkglib_PROGRAMS = foo
2066 doc_LIBRARIES = libquux.a
2070 but it will succeed with this:
2072 @c Keep in sync with primary-prefix-couples-documented-valid.sh
2074 # Work around forbidden directory combinations. Do not use this
2075 # without a very good reason!
2076 my_execbindir = $(pkglibdir)
2077 my_doclibdir = $(docdir)
2078 my_execbin_PROGRAMS = foo
2079 my_doclib_LIBRARIES = libquux.a
2082 The @samp{exec} substring of the @samp{my_execbindir} variable lets
2083 the files be installed at the right time (@pxref{The Two Parts of
2086 @cindex @samp{noinst_} primary prefix, definition
2089 The special prefix @samp{noinst_} indicates that the objects in question
2090 should be built but not installed at all. This is usually used for
2091 objects required to build the rest of your package, for instance static
2092 libraries (@pxref{A Library}), or helper scripts.
2094 @cindex @samp{check_} primary prefix, definition
2097 The special prefix @samp{check_} indicates that the objects in question
2098 should not be built until the @samp{make check} command is run. Those
2099 objects are not installed either.
2101 The current primary names are @samp{PROGRAMS}, @samp{LIBRARIES},
2102 @samp{LTLIBRARIES}, @samp{LISP}, @samp{PYTHON}, @samp{JAVA},
2103 @samp{SCRIPTS}, @samp{DATA}, @samp{HEADERS}, @samp{MANS}, and
2117 Some primaries also allow additional prefixes that control other
2118 aspects of @command{automake}'s behavior. The currently defined prefixes
2119 are @samp{dist_}, @samp{nodist_}, @samp{nobase_}, and @samp{notrans_}.
2120 These prefixes are explained later (@pxref{Program and Library Variables})
2121 (@pxref{Man Pages}).
2124 @node Length Limitations
2125 @section Staying below the command line length limit
2127 @cindex command line length limit
2130 Traditionally, most unix-like systems have a length limitation for the
2131 command line arguments and environment contents when creating new
2132 processes (see for example
2133 @uref{http://www.in-ulm.de/@/~mascheck/@/various/@/argmax/} for an
2134 overview on this issue),
2135 which of course also applies to commands spawned by @command{make}.
2136 POSIX requires this limit to be at least 4096 bytes, and most modern
2137 systems have quite high limits (or are unlimited).
2139 In order to create portable Makefiles that do not trip over these
2140 limits, it is necessary to keep the length of file lists bounded.
2141 Unfortunately, it is not possible to do so fully transparently within
2142 Automake, so your help may be needed. Typically, you can split long
2143 file lists manually and use different installation directory names for
2144 each list. For example,
2147 data_DATA = file1 @dots{} file@var{N} file@var{N+1} @dots{} file@var{2N}
2151 may also be written as
2153 @c Keep in sync with primary-prefix-couples-documented-valid.sh
2155 data_DATA = file1 @dots{} file@var{N}
2156 data2dir = $(datadir)
2157 data2_DATA = file@var{N+1} @dots{} file@var{2N}
2161 and will cause Automake to treat the two lists separately during
2162 @code{make install}. See @ref{The Two Parts of Install} for choosing
2163 directory names that will keep the ordering of the two parts of
2164 installation Note that @code{make dist} may still only work on a host
2165 with a higher length limit in this example.
2167 Automake itself employs a couple of strategies to avoid long command
2168 lines. For example, when @samp{$@{srcdir@}/} is prepended to file
2169 names, as can happen with above @code{$(data_DATA)} lists, it limits
2170 the amount of arguments passed to external commands.
2172 Unfortunately, some system's @command{make} commands may prepend
2173 @code{VPATH} prefixes like @samp{$@{srcdir@}/} to file names from the
2174 source tree automatically (@pxref{Automatic Rule Rewriting, , Automatic
2175 Rule Rewriting, autoconf, The Autoconf Manual}). In this case, the user
2176 may have to switch to use GNU Make, or refrain from using VPATH builds,
2177 in order to stay below the length limit.
2179 For libraries and programs built from many sources, convenience archives
2180 may be used as intermediates in order to limit the object list length
2181 (@pxref{Libtool Convenience Libraries}).
2184 @node Canonicalization
2185 @section How derived variables are named
2187 @cindex canonicalizing Automake variables
2189 Sometimes a Makefile variable name is derived from some text the
2190 maintainer supplies. For instance, a program name listed in
2191 @samp{_PROGRAMS} is rewritten into the name of a @samp{_SOURCES}
2192 variable. In cases like this, Automake canonicalizes the text, so that
2193 program names and the like do not have to follow Makefile variable naming
2194 rules. All characters in the name except for letters, numbers, the
2195 strudel (@@), and the underscore are turned into underscores when making
2196 variable references.
2198 For example, if your program is named @file{sniff-glue}, the derived
2199 variable name would be @samp{sniff_glue_SOURCES}, not
2200 @samp{sniff-glue_SOURCES}. Similarly the sources for a library named
2201 @file{libmumble++.a} should be listed in the
2202 @samp{libmumble___a_SOURCES} variable.
2204 The strudel is an addition, to make the use of Autoconf substitutions in
2205 variable names less obfuscating.
2208 @node User Variables
2209 @section Variables reserved for the user
2211 @cindex variables, reserved for the user
2212 @cindex user variables
2214 Some @file{Makefile} variables are reserved by the GNU Coding Standards
2215 for the use of the ``user''---the person building the package. For
2216 instance, @code{CFLAGS} is one such variable.
2218 Sometimes package developers are tempted to set user variables such as
2219 @code{CFLAGS} because it appears to make their job easier. However,
2220 the package itself should never set a user variable, particularly not
2221 to include switches that are required for proper compilation of the
2222 package. Since these variables are documented as being for the
2223 package builder, that person rightfully expects to be able to override
2224 any of these variables at build time.
2226 To get around this problem, Automake introduces an automake-specific
2227 shadow variable for each user flag variable. (Shadow variables are
2228 not introduced for variables like @code{CC}, where they would make no
2229 sense.) The shadow variable is named by prepending @samp{AM_} to the
2230 user variable's name. For instance, the shadow variable for
2231 @code{YFLAGS} is @code{AM_YFLAGS}. The package maintainer---that is,
2232 the author(s) of the @file{Makefile.am} and @file{configure.ac}
2233 files---may adjust these shadow variables however necessary.
2235 @xref{Flag Variables Ordering}, for more discussion about these
2236 variables and how they interact with per-target variables.
2238 @node Auxiliary Programs
2239 @section Programs automake might require
2241 @cindex Programs, auxiliary
2242 @cindex Auxiliary programs
2244 Automake sometimes requires helper programs so that the generated
2245 @file{Makefile} can do its work properly. There are a fairly large
2246 number of them, and we list them here.
2248 Although all of these files are distributed and installed with
2249 Automake, a couple of them are maintained separately. The Automake
2250 copies are updated before each release, but we mention the original
2251 source in case you need more recent versions.
2255 This is a wrapper primarily for the Microsoft lib archiver, to make
2259 This is a wrapper for compilers that do not accept options @option{-c}
2260 and @option{-o} at the same time. It is only used when absolutely
2261 required. Such compilers are rare, with the Microsoft C/C++ Compiler
2262 as the most notable exception. This wrapper also makes the following
2263 common options available for that compiler, while performing file name
2264 translation where needed: @option{-I}, @option{-L}, @option{-l},
2265 @option{-Wl,} and @option{-Xlinker}.
2269 These two programs compute the canonical triplets for the given build,
2270 host, or target architecture. These programs are updated regularly to
2271 support new architectures and fix probes broken by changes in new
2272 kernel versions. Each new release of Automake comes with up-to-date
2273 copies of these programs. If your copy of Automake is getting old,
2274 you are encouraged to fetch the latest versions of these files from
2275 @url{http://savannah.gnu.org/git/?group=config} before making a
2279 This program understands how to run a compiler so that it will
2280 generate not only the desired output but also dependency information
2281 that is then used by the automatic dependency tracking feature
2282 (@pxref{Dependencies}).
2285 This is a replacement for the @command{install} program that works on
2286 platforms where @command{install} is unavailable or unusable.
2289 This script is used to generate a @file{version.texi} file. It examines
2290 a file and prints some date information about it.
2293 This wraps a number of programs that are typically only required by
2294 maintainers. If the program in question doesn't exist, or seems to old,
2295 @command{missing} will print an informative warning before failing out,
2296 to provide the user with more context and information.
2299 This script used to be a wrapper around @samp{mkdir -p}, which is not
2300 portable. Now we prefer to use @samp{install-sh -d} when @command{configure}
2301 finds that @samp{mkdir -p} does not work, this makes one less script to
2304 For backward compatibility @file{mkinstalldirs} is still used and
2305 distributed when @command{automake} finds it in a package. But it is no
2306 longer installed automatically, and it should be safe to remove it.
2309 This is used to byte-compile Python scripts.
2312 This implements the default test driver offered by the parallel
2316 Not a program, this file is required for @samp{make dvi}, @samp{make
2317 ps} and @samp{make pdf} to work when Texinfo sources are in the
2318 package. The latest version can be downloaded from
2319 @url{http://www.gnu.org/software/texinfo/}.
2322 This program wraps @command{lex} and @command{yacc} to rename their
2323 output files. It also ensures that, for instance, multiple
2324 @command{yacc} instances can be invoked in a single directory in
2331 @chapter Some example packages
2333 This section contains two small examples.
2335 The first example (@pxref{Complete}) assumes you have an existing
2336 project already using Autoconf, with handcrafted @file{Makefile}s, and
2337 that you want to convert it to using Automake. If you are discovering
2338 both tools, it is probably better that you look at the Hello World
2339 example presented earlier (@pxref{Hello World}).
2341 The second example (@pxref{true}) shows how two programs can be built
2342 from the same file, using different compilation parameters. It
2343 contains some technical digressions that are probably best skipped on
2347 * Complete:: A simple example, start to finish
2348 * true:: Building true and false
2353 @section A simple example, start to finish
2355 @cindex Complete example
2357 Let's suppose you just finished writing @code{zardoz}, a program to make
2358 your head float from vortex to vortex. You've been using Autoconf to
2359 provide a portability framework, but your @file{Makefile.in}s have been
2360 ad-hoc. You want to make them bulletproof, so you turn to Automake.
2362 @cindex @code{AM_INIT_AUTOMAKE}, example use
2364 The first step is to update your @file{configure.ac} to include the
2365 commands that @command{automake} needs. The way to do this is to add an
2366 @code{AM_INIT_AUTOMAKE} call just after @code{AC_INIT}:
2369 AC_INIT([zardoz], [1.0])
2374 Since your program doesn't have any complicating factors (e.g., it
2375 doesn't use @code{gettext}, it doesn't want to build a shared library),
2376 you're done with this part. That was easy!
2378 @cindex @command{aclocal} program, introduction
2379 @cindex @file{aclocal.m4}, preexisting
2380 @cindex @file{acinclude.m4}, defined
2382 Now you must regenerate @file{configure}. But to do that, you'll need
2383 to tell @command{autoconf} how to find the new macro you've used. The
2384 easiest way to do this is to use the @command{aclocal} program to
2385 generate your @file{aclocal.m4} for you. But wait@dots{} maybe you
2386 already have an @file{aclocal.m4}, because you had to write some hairy
2387 macros for your program. The @command{aclocal} program lets you put
2388 your own macros into @file{acinclude.m4}, so simply rename and then
2392 mv aclocal.m4 acinclude.m4
2397 @cindex @command{zardoz} example
2399 Now it is time to write your @file{Makefile.am} for @code{zardoz}.
2400 Since @code{zardoz} is a user program, you want to install it where the
2401 rest of the user programs go: @code{bindir}. Additionally,
2402 @code{zardoz} has some Texinfo documentation. Your @file{configure.ac}
2403 script uses @code{AC_REPLACE_FUNCS}, so you need to link against
2404 @samp{$(LIBOBJS)}. So here's what you'd write:
2407 bin_PROGRAMS = zardoz
2408 zardoz_SOURCES = main.c head.c float.c vortex9.c gun.c
2409 zardoz_LDADD = $(LIBOBJS)
2411 info_TEXINFOS = zardoz.texi
2414 Now you can run @samp{automake --add-missing} to generate your
2415 @file{Makefile.in} and grab any auxiliary files you might need, and
2420 @section Building true and false
2422 @cindex Example, @command{false} and @command{true}
2423 @cindex @command{false} Example
2424 @cindex @command{true} Example
2426 Here is another, trickier example. It shows how to generate two
2427 programs (@code{true} and @code{false}) from the same source file
2428 (@file{true.c}). The difficult part is that each compilation of
2429 @file{true.c} requires different @code{cpp} flags.
2432 bin_PROGRAMS = true false
2434 false_LDADD = false.o
2437 $(COMPILE) -DEXIT_CODE=0 -c true.c
2440 $(COMPILE) -DEXIT_CODE=1 -o false.o -c true.c
2443 Note that there is no @code{true_SOURCES} definition. Automake will
2444 implicitly assume that there is a source file named @file{true.c}
2445 (@pxref{Default _SOURCES}), and
2446 define rules to compile @file{true.o} and link @file{true}. The
2447 @samp{true.o: true.c} rule supplied by the above @file{Makefile.am},
2448 will override the Automake generated rule to build @file{true.o}.
2450 @code{false_SOURCES} is defined to be empty---that way no implicit value
2451 is substituted. Because we have not listed the source of
2452 @file{false}, we have to tell Automake how to link the program. This is
2453 the purpose of the @code{false_LDADD} line. A @code{false_DEPENDENCIES}
2454 variable, holding the dependencies of the @file{false} target will be
2455 automatically generated by Automake from the content of
2458 The above rules won't work if your compiler doesn't accept both
2459 @option{-c} and @option{-o}. The simplest fix for this is to introduce a
2460 bogus dependency (to avoid problems with a parallel @command{make}):
2463 true.o: true.c false.o
2464 $(COMPILE) -DEXIT_CODE=0 -c true.c
2467 $(COMPILE) -DEXIT_CODE=1 -c true.c && mv true.o false.o
2470 As it turns out, there is also a much easier way to do this same task.
2471 Some of the above technique is useful enough that we've kept the
2472 example in the manual. However if you were to build @code{true} and
2473 @code{false} in real life, you would probably use per-program
2474 compilation flags, like so:
2476 @c Keep in sync with specflg7.sh and specflg8.sh
2478 bin_PROGRAMS = false true
2480 false_SOURCES = true.c
2481 false_CPPFLAGS = -DEXIT_CODE=1
2483 true_SOURCES = true.c
2484 true_CPPFLAGS = -DEXIT_CODE=0
2487 In this case Automake will cause @file{true.c} to be compiled twice,
2488 with different flags. In this instance, the names of the object files
2489 would be chosen by automake; they would be @file{false-true.o} and
2490 @file{true-true.o}. (The name of the object files rarely matters.)
2492 @node automake Invocation
2493 @chapter Creating a @file{Makefile.in}
2494 @c This node used to be named "Invoking automake". This @anchor
2495 @c allows old links to still work.
2496 @anchor{Invoking automake}
2498 @cindex Multiple @file{configure.ac} files
2499 @cindex Invoking @command{automake}
2500 @cindex @command{automake}, invoking
2501 @cindex Invocation of @command{automake}
2502 @cindex @command{automake}, invocation
2504 To create all the @file{Makefile.in}s for a package, run the
2505 @command{automake} program in the top level directory, with no
2506 arguments. @command{automake} will automatically find each
2507 appropriate @file{Makefile.am} (by scanning @file{configure.ac};
2508 @pxref{configure}) and generate the corresponding @file{Makefile.in}.
2509 Note that @command{automake} has a rather simplistic view of what
2510 constitutes a package; it assumes that a package has only one
2511 @file{configure.ac}, at the top. If your package has multiple
2512 @file{configure.ac}s, then you must run @command{automake} in each
2513 directory holding a @file{configure.ac}. (Alternatively, you may rely
2514 on Autoconf's @command{autoreconf}, which is able to recurse your
2515 package tree and run @command{automake} where appropriate.)
2517 You can optionally give @command{automake} an argument; @file{.am} is
2518 appended to the argument and the result is used as the name of the
2519 input file. This feature is generally only used to automatically
2520 rebuild an out-of-date @file{Makefile.in}. Note that
2521 @command{automake} must always be run from the topmost directory of a
2522 project, even if being used to regenerate the @file{Makefile.in} in
2523 some subdirectory. This is necessary because @command{automake} must
2524 scan @file{configure.ac}, and because @command{automake} uses the
2525 knowledge that a @file{Makefile.in} is in a subdirectory to change its
2526 behavior in some cases.
2529 Automake will run @command{autoconf} to scan @file{configure.ac} and
2530 its dependencies (i.e., @file{aclocal.m4} and any included file),
2531 therefore @command{autoconf} must be in your @env{PATH}. If there is
2532 an @env{AUTOCONF} variable in your environment it will be used
2533 instead of @command{autoconf}, this allows you to select a particular
2534 version of Autoconf. By the way, don't misunderstand this paragraph:
2535 @command{automake} runs @command{autoconf} to @strong{scan} your
2536 @file{configure.ac}, this won't build @file{configure} and you still
2537 have to run @command{autoconf} yourself for this purpose.
2539 @cindex @command{automake} options
2540 @cindex Options, @command{automake}
2541 @cindex Strictness, command line
2543 @command{automake} accepts the following options:
2545 @cindex Extra files distributed with Automake
2546 @cindex Files distributed with Automake
2547 @cindex @file{config.guess}
2551 @itemx --add-missing
2553 @opindex --add-missing
2554 Automake requires certain common files to exist in certain situations;
2555 for instance, @file{config.guess} is required if @file{configure.ac} invokes
2556 @code{AC_CANONICAL_HOST}. Automake is distributed with several of these
2557 files (@pxref{Auxiliary Programs}); this option will cause the missing
2558 ones to be automatically added to the package, whenever possible. In
2559 general if Automake tells you a file is missing, try using this option.
2560 By default Automake tries to make a symbolic link pointing to its own
2561 copy of the missing file; this can be changed with @option{--copy}.
2563 Many of the potentially-missing files are common scripts whose
2564 location may be specified via the @code{AC_CONFIG_AUX_DIR} macro.
2565 Therefore, @code{AC_CONFIG_AUX_DIR}'s setting affects whether a
2566 file is considered missing, and where the missing file is added
2569 In some strictness modes, additional files are installed, see @ref{Gnits}
2570 for more information.
2572 @item --libdir=@var{dir}
2574 Look for Automake data files in directory @var{dir} instead of in the
2575 installation directory. This is typically used for debugging.
2577 @item --print-libdir
2578 @opindex --print-libdir
2579 Print the path of the installation directory containing Automake-provided
2580 scripts and data files (like e.g., @file{texinfo.texi} and
2587 When used with @option{--add-missing}, causes installed files to be
2588 copied. The default is to make a symbolic link.
2592 @itemx --force-missing
2593 @opindex --force-missing
2594 When used with @option{--add-missing}, causes standard files to be reinstalled
2595 even if they already exist in the source tree. This involves removing
2596 the file from the source tree before creating the new symlink (or, with
2597 @option{--copy}, copying the new file).
2601 Set the global strictness to @option{foreign}. For more information, see
2606 Set the global strictness to @option{gnits}. For more information, see
2611 Set the global strictness to @option{gnu}. For more information, see
2612 @ref{Gnits}. This is the default strictness.
2616 Print a summary of the command line options and exit.
2619 @itemx --ignore-deps
2621 This disables the dependency tracking feature in generated
2622 @file{Makefile}s; see @ref{Dependencies}.
2624 @item --include-deps
2625 @opindex --include-deps
2626 This enables the dependency tracking feature. This feature is enabled
2627 by default. This option is provided for historical reasons only and
2628 probably should not be used.
2632 Ordinarily @command{automake} creates all @file{Makefile.in}s mentioned in
2633 @file{configure.ac}. This option causes it to only update those
2634 @file{Makefile.in}s that are out of date with respect to one of their
2638 @itemx --output-dir=@var{dir}
2640 @opindex --output-dir
2641 Put the generated @file{Makefile.in} in the directory @var{dir}.
2642 Ordinarily each @file{Makefile.in} is created in the directory of the
2643 corresponding @file{Makefile.am}. This option is deprecated and will be
2644 removed in a future release.
2650 Cause Automake to print information about which files are being read or
2655 Print the version number of Automake and exit.
2658 @itemx --warnings=@var{category}
2661 Output warnings falling in @var{category}. @var{category} can be
2665 warnings related to the GNU Coding Standards
2666 (@pxref{Top, , , standards, The GNU Coding Standards}).
2668 obsolete features or constructions
2670 user redefinitions of Automake rules or variables
2672 portability issues (e.g., use of @command{make} features that are
2673 known to be not portable)
2674 @item extra-portability
2675 extra portability issues related to obscure tools. One example of such
2676 a tool is the Microsoft @command{lib} archiver.
2678 weird syntax, unused variables, typos
2680 unsupported or incomplete features
2684 turn off all the warnings
2686 treat warnings as errors
2689 A category can be turned off by prefixing its name with @samp{no-}. For
2690 instance, @option{-Wno-syntax} will hide the warnings about unused
2693 The categories output by default are @samp{obsolete}, @samp{syntax} and
2694 @samp{unsupported}. Additionally, @samp{gnu} and @samp{portability}
2695 are enabled in @option{--gnu} and @option{--gnits} strictness.
2697 @c Checked by extra-portability.sh
2698 Turning off @samp{portability} will also turn off @samp{extra-portability},
2699 and similarly turning on @samp{extra-portability} will also turn on
2700 @samp{portability}. However, turning on @samp{portability} or turning
2701 off @samp{extra-portability} will not affect the other category.
2704 The environment variable @env{WARNINGS} can contain a comma separated
2705 list of categories to enable. It will be taken into account before the
2706 command-line switches, this way @option{-Wnone} will also ignore any
2707 warning category enabled by @env{WARNINGS}. This variable is also used
2708 by other tools like @command{autoconf}; unknown categories are ignored
2713 @vindex AUTOMAKE_JOBS
2714 If the environment variable @env{AUTOMAKE_JOBS} contains a positive
2715 number, it is taken as the maximum number of Perl threads to use in
2716 @command{automake} for generating multiple @file{Makefile.in} files
2717 concurrently. This is an experimental feature.
2721 @chapter Scanning @file{configure.ac}, using @command{aclocal}
2723 @cindex @file{configure.ac}, scanning
2724 @cindex Scanning @file{configure.ac}
2725 @cindex Using @command{aclocal}
2726 @cindex @command{aclocal}, using
2728 Automake scans the package's @file{configure.ac} to determine certain
2729 information about the package. Some @command{autoconf} macros are required
2730 and some variables must be defined in @file{configure.ac}. Automake
2731 will also use information from @file{configure.ac} to further tailor its
2734 Automake also supplies some Autoconf macros to make the maintenance
2735 easier. These macros can automatically be put into your
2736 @file{aclocal.m4} using the @command{aclocal} program.
2739 * Requirements:: Configuration requirements
2740 * Optional:: Other things Automake recognizes
2741 * aclocal Invocation:: Auto-generating aclocal.m4
2742 * Macros:: Autoconf macros supplied with Automake
2747 @section Configuration requirements
2749 @cindex Automake requirements
2750 @cindex Requirements of Automake
2752 @acindex AM_INIT_AUTOMAKE
2753 The one real requirement of Automake is that your @file{configure.ac}
2754 call @code{AM_INIT_AUTOMAKE}. This macro does several things that are
2755 required for proper Automake operation (@pxref{Macros}).
2757 Here are the other macros that Automake requires but which are not run
2758 by @code{AM_INIT_AUTOMAKE}:
2761 @item AC_CONFIG_FILES
2763 @acindex AC_CONFIG_FILES
2765 These two macros are usually invoked as follows near the end of
2766 @file{configure.ac}.
2780 Automake uses these to determine which files to create (@pxref{Output, ,
2781 Creating Output Files, autoconf, The Autoconf Manual}). A listed file
2782 is considered to be an Automake generated @file{Makefile} if there
2783 exists a file with the same name and the @file{.am} extension appended.
2784 Typically, @samp{AC_CONFIG_FILES([foo/Makefile])} will cause Automake to
2785 generate @file{foo/Makefile.in} if @file{foo/Makefile.am} exists.
2787 When using @code{AC_CONFIG_FILES} with multiple input files, as in
2790 AC_CONFIG_FILES([Makefile:top.in:Makefile.in:bot.in])
2794 @command{automake} will generate the first @file{.in} input file for
2795 which a @file{.am} file exists. If no such file exists the output
2796 file is not considered to be generated by Automake.
2798 Files created by @code{AC_CONFIG_FILES}, be they Automake
2799 @file{Makefile}s or not, are all removed by @samp{make distclean}.
2800 Their inputs are automatically distributed, unless they
2801 are the output of prior @code{AC_CONFIG_FILES} commands.
2802 Finally, rebuild rules are generated in the Automake @file{Makefile}
2803 existing in the subdirectory of the output file, if there is one, or
2804 in the top-level @file{Makefile} otherwise.
2806 The above machinery (cleaning, distributing, and rebuilding) works
2807 fine if the @code{AC_CONFIG_FILES} specifications contain only
2808 literals. If part of the specification uses shell variables,
2809 @command{automake} will not be able to fulfill this setup, and you will
2810 have to complete the missing bits by hand. For instance, on
2812 @c Keep in sync with output11.sh
2816 AC_CONFIG_FILES([output:$file],, [file=$file])
2820 @command{automake} will output rules to clean @file{output}, and
2821 rebuild it. However the rebuild rule will not depend on @file{input},
2822 and this file will not be distributed either. (You must add
2823 @samp{EXTRA_DIST = input} to your @file{Makefile.am} if @file{input} is a
2828 @c Keep in sync with output11.sh
2833 AC_CONFIG_FILES([$file:input],, [file=$file])
2834 AC_CONFIG_FILES([$file2],, [file2=$file2])
2838 will only cause @file{input} to be distributed. No file will be
2839 cleaned automatically (add @samp{DISTCLEANFILES = output out}
2840 yourself), and no rebuild rule will be output.
2842 Obviously @command{automake} cannot guess what value @samp{$file} is
2843 going to hold later when @file{configure} is run, and it cannot use
2844 the shell variable @samp{$file} in a @file{Makefile}. However, if you
2845 make reference to @samp{$file} as @samp{$@{file@}} (i.e., in a way
2846 that is compatible with @command{make}'s syntax) and furthermore use
2847 @code{AC_SUBST} to ensure that @samp{$@{file@}} is meaningful in a
2848 @file{Makefile}, then @command{automake} will be able to use
2849 @samp{$@{file@}} to generate all of these rules. For instance, here is
2850 how the Automake package itself generates versioned scripts for its
2854 AC_SUBST([APIVERSION], @dots{})
2857 [tests/aclocal-$@{APIVERSION@}:tests/aclocal.in],
2858 [chmod +x tests/aclocal-$@{APIVERSION@}],
2859 [APIVERSION=$APIVERSION])
2861 [tests/automake-$@{APIVERSION@}:tests/automake.in],
2862 [chmod +x tests/automake-$@{APIVERSION@}])
2866 Here cleaning, distributing, and rebuilding are done automatically,
2867 because @samp{$@{APIVERSION@}} is known at @command{make}-time.
2869 Note that you should not use shell variables to declare
2870 @file{Makefile} files for which @command{automake} must create
2871 @file{Makefile.in}. Even @code{AC_SUBST} does not help here, because
2872 @command{automake} needs to know the file name when it runs in order
2873 to check whether @file{Makefile.am} exists. (In the very hairy case
2874 that your setup requires such use of variables, you will have to tell
2875 Automake which @file{Makefile.in}s to generate on the command-line.)
2877 It is possible to let @command{automake} emit conditional rules for
2878 @code{AC_CONFIG_FILES} with the help of @code{AM_COND_IF}
2884 Use literals for @file{Makefile}s, and for other files whenever possible.
2886 Use @samp{$file} (or @samp{$@{file@}} without @samp{AC_SUBST([file])})
2887 for files that @command{automake} should ignore.
2889 Use @samp{$@{file@}} and @samp{AC_SUBST([file])} for files
2890 that @command{automake} should not ignore.
2897 @section Other things Automake recognizes
2899 @cindex Macros Automake recognizes
2900 @cindex Recognized macros by Automake
2902 Every time Automake is run it calls Autoconf to trace
2903 @file{configure.ac}. This way it can recognize the use of certain
2904 macros and tailor the generated @file{Makefile.in} appropriately.
2905 Currently recognized macros and their effects are:
2908 @item AC_CANONICAL_BUILD
2909 @itemx AC_CANONICAL_HOST
2910 @itemx AC_CANONICAL_TARGET
2911 @vindex build_triplet
2912 @vindex host_triplet
2913 @vindex target_triplet
2914 Automake will ensure that @file{config.guess} and @file{config.sub}
2915 exist. Also, the @file{Makefile} variables @code{build_triplet},
2916 @code{host_triplet} and @code{target_triplet} are introduced. See
2917 @ref{Canonicalizing, , Getting the Canonical System Type, autoconf,
2918 The Autoconf Manual}.
2920 @item AC_CONFIG_AUX_DIR
2921 Automake will look for various helper scripts, such as
2922 @file{install-sh}, in the directory named in this macro invocation.
2923 @c This list is accurate relative to version 1.11
2924 (The full list of scripts is:
2926 @file{config.guess},
2934 @file{mkinstalldirs},
2939 Not all scripts are always searched for; some scripts
2940 will only be sought if the generated @file{Makefile.in} requires them.
2942 If @code{AC_CONFIG_AUX_DIR} is not given, the scripts are looked for in
2943 their standard locations. For @file{mdate-sh},
2944 @file{texinfo.tex}, and @file{ylwrap}, the standard location is the
2945 source directory corresponding to the current @file{Makefile.am}. For
2946 the rest, the standard location is the first one of @file{.}, @file{..},
2947 or @file{../..} (relative to the top source directory) that provides any
2948 one of the helper scripts. @xref{Input, , Finding `configure' Input,
2949 autoconf, The Autoconf Manual}.
2951 Required files from @code{AC_CONFIG_AUX_DIR} are automatically
2952 distributed, even if there is no @file{Makefile.am} in this directory.
2954 @item AC_CONFIG_LIBOBJ_DIR
2955 Automake will require the sources file declared with
2956 @code{AC_LIBSOURCE} (see below) in the directory specified by this
2959 @item AC_CONFIG_HEADERS
2960 Automake will generate rules to rebuild these headers from the
2961 corresponding templates (usually, the template for a @file{foo.h}
2962 header being @file{foo.h.in}). Older versions of Automake
2963 required the use of @code{AM_CONFIG_HEADER}; this is no longer
2964 the case, and that macro has indeed been removed.
2966 As with @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the
2967 specification using shell variables will be ignored as far as
2968 cleaning, distributing, and rebuilding is concerned.
2970 @item AC_CONFIG_LINKS
2971 Automake will generate rules to remove @file{configure} generated
2972 links on @samp{make distclean} and to distribute named source files as
2973 part of @samp{make dist}.
2975 As for @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the
2976 specification using shell variables will be ignored as far as cleaning
2977 and distributing is concerned. (There are no rebuild rules for links.)
2981 @itemx AC_LIBSOURCES
2983 Automake will automatically distribute any file listed in
2984 @code{AC_LIBSOURCE} or @code{AC_LIBSOURCES}.
2986 Note that the @code{AC_LIBOBJ} macro calls @code{AC_LIBSOURCE}. So if
2987 an Autoconf macro is documented to call @samp{AC_LIBOBJ([file])}, then
2988 @file{file.c} will be distributed automatically by Automake. This
2989 encompasses many macros like @code{AC_FUNC_ALLOCA},
2990 @code{AC_FUNC_MEMCMP}, @code{AC_REPLACE_FUNCS}, and others.
2992 By the way, direct assignments to @code{LIBOBJS} are no longer
2993 supported. You should always use @code{AC_LIBOBJ} for this purpose.
2994 @xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs.@: @code{LIBOBJS},
2995 autoconf, The Autoconf Manual}.
2997 @item AC_PROG_RANLIB
2998 This is required if any libraries are built in the package.
2999 @xref{Particular Programs, , Particular Program Checks, autoconf, The
3003 This is required if any C++ source is included. @xref{Particular
3004 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
3007 This is required if any Objective C source is included. @xref{Particular
3008 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
3010 @item AC_PROG_OBJCXX
3011 This is required if any Objective C++ source is included. @xref{Particular
3012 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
3015 This is required if any Fortran 77 source is included. @xref{Particular
3016 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
3018 @item AC_F77_LIBRARY_LDFLAGS
3019 This is required for programs and shared libraries that are a mixture of
3020 languages that include Fortran 77 (@pxref{Mixing Fortran 77 With C and
3021 C++}). @xref{Macros, , Autoconf macros supplied with Automake}.
3024 Automake will add the flags computed by @code{AC_FC_SRCEXT} to compilation
3025 of files with the respective source extension (@pxref{Fortran Compiler, ,
3026 Fortran Compiler Characteristics, autoconf, The Autoconf Manual}).
3029 This is required if any Fortran 90/95 source is included. This macro is
3030 distributed with Autoconf version 2.58 and later. @xref{Particular
3031 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
3033 @item AC_PROG_LIBTOOL
3034 Automake will turn on processing for @command{libtool} (@pxref{Top, ,
3035 Introduction, libtool, The Libtool Manual}).
3039 If a Yacc source file is seen, then you must either use this macro or
3040 define the variable @code{YACC} in @file{configure.ac}. The former is
3041 preferred (@pxref{Particular Programs, , Particular Program Checks,
3042 autoconf, The Autoconf Manual}).
3045 If a Lex source file is seen, then this macro must be used.
3046 @xref{Particular Programs, , Particular Program Checks, autoconf, The
3049 @item AC_REQUIRE_AUX_FILE
3050 For each @code{AC_REQUIRE_AUX_FILE([@var{file}])},
3051 @command{automake} will ensure that @file{@var{file}} exists in the
3052 aux directory, and will complain otherwise. It
3053 will also automatically distribute the file. This macro should be
3054 used by third-party Autoconf macros that require some supporting
3055 files in the aux directory specified with @code{AC_CONFIG_AUX_DIR}
3056 above. @xref{Input, , Finding @command{configure} Input, autoconf,
3057 The Autoconf Manual}.
3060 The first argument is automatically defined as a variable in each
3061 generated @file{Makefile.in}, unless @code{AM_SUBST_NOTMAKE} is also
3062 used for this variable. @xref{Setting Output Variables, , Setting
3063 Output Variables, autoconf, The Autoconf Manual}.
3065 For every substituted variable @var{var}, @command{automake} will add
3066 a line @code{@var{var} = @var{value}} to each @file{Makefile.in} file.
3067 Many Autoconf macros invoke @code{AC_SUBST} to set output variables
3068 this way, e.g., @code{AC_PATH_XTRA} defines @code{X_CFLAGS} and
3069 @code{X_LIBS}. Thus, you can access these variables as
3070 @code{$(X_CFLAGS)} and @code{$(X_LIBS)} in any @file{Makefile.am}
3071 if @code{AC_PATH_XTRA} is called.
3073 @item AM_CONDITIONAL
3074 This introduces an Automake conditional (@pxref{Conditionals}).
3077 This macro allows @code{automake} to detect subsequent access within
3078 @file{configure.ac} to a conditional previously introduced with
3079 @code{AM_CONDITIONAL}, thus enabling conditional @code{AC_CONFIG_FILES}
3080 (@pxref{Usage of Conditionals}).
3082 @item AM_GNU_GETTEXT
3083 This macro is required for packages that use GNU gettext
3084 (@pxref{gettext}). It is distributed with gettext. If Automake sees
3085 this macro it ensures that the package meets some of gettext's
3088 @item AM_GNU_GETTEXT_INTL_SUBDIR
3089 This macro specifies that the @file{intl/} subdirectory is to be built,
3090 even if the @code{AM_GNU_GETTEXT} macro was invoked with a first argument
3093 @item AM_MAINTAINER_MODE(@ovar{default-mode})
3094 @opindex --enable-maintainer-mode
3095 @opindex --disable-maintainer-mode
3096 This macro adds an @option{--enable-maintainer-mode} option to
3097 @command{configure}. If this is used, @command{automake} will cause
3098 ``maintainer-only'' rules to be turned off by default in the
3099 generated @file{Makefile.in}s, unless @var{default-mode} is
3100 @samp{enable}. This macro defines the @code{MAINTAINER_MODE}
3101 conditional, which you can use in your own @file{Makefile.am}.
3102 @xref{maintainer-mode}.
3104 @item AM_SUBST_NOTMAKE(@var{var})
3105 Prevent Automake from defining a variable @var{var}, even if it is
3106 substituted by @command{config.status}. Normally, Automake defines a
3107 @command{make} variable for each @command{configure} substitution,
3108 i.e., for each @code{AC_SUBST([@var{var}])}. This macro prevents that
3109 definition from Automake. If @code{AC_SUBST} has not been called
3110 for this variable, then @code{AM_SUBST_NOTMAKE} has no effects.
3111 Preventing variable definitions may be useful for substitution of
3112 multi-line values, where @code{@var{var} = @@@var{value}@@} might yield
3116 Files included by @file{configure.ac} using this macro will be
3117 detected by Automake and automatically distributed. They will also
3118 appear as dependencies in @file{Makefile} rules.
3120 @code{m4_include} is seldom used by @file{configure.ac} authors, but
3121 can appear in @file{aclocal.m4} when @command{aclocal} detects that
3122 some required macros come from files local to your package (as opposed to
3123 macros installed in a system-wide directory, @pxref{aclocal Invocation}).
3127 @node aclocal Invocation
3128 @section Auto-generating aclocal.m4
3129 @c This node used to be named "Invoking automake". This @anchor
3130 @c allows old links to still work.
3131 @anchor{Invoking aclocal}
3133 @cindex Invocation of @command{aclocal}
3134 @cindex @command{aclocal}, Invocation
3135 @cindex Invoking @command{aclocal}
3136 @cindex @command{aclocal}, Invoking
3138 Automake includes a number of Autoconf macros that can be used in
3139 your package (@pxref{Macros}); some of them are actually required by
3140 Automake in certain situations. These macros must be defined in your
3141 @file{aclocal.m4}; otherwise they will not be seen by
3144 The @command{aclocal} program will automatically generate
3145 @file{aclocal.m4} files based on the contents of @file{configure.ac}.
3146 This provides a convenient way to get Automake-provided macros,
3147 without having to search around. The @command{aclocal} mechanism
3148 allows other packages to supply their own macros (@pxref{Extending
3149 aclocal}). You can also use it to maintain your own set of custom
3150 macros (@pxref{Local Macros}).
3152 At startup, @command{aclocal} scans all the @file{.m4} files it can
3153 find, looking for macro definitions (@pxref{Macro Search Path}). Then
3154 it scans @file{configure.ac}. Any mention of one of the macros found
3155 in the first step causes that macro, and any macros it in turn
3156 requires, to be put into @file{aclocal.m4}.
3158 @emph{Putting} the file that contains the macro definition into
3159 @file{aclocal.m4} is usually done by copying the entire text of this
3160 file, including unused macro definitions as well as both @samp{#} and
3161 @samp{dnl} comments. If you want to make a comment that will be
3162 completely ignored by @command{aclocal}, use @samp{##} as the comment
3165 When a file selected by @command{aclocal} is located in a subdirectory
3166 specified as a relative search path with @command{aclocal}'s @option{-I}
3167 argument, @command{aclocal} assumes the file belongs to the package
3168 and uses @code{m4_include} instead of copying it into
3169 @file{aclocal.m4}. This makes the package smaller, eases dependency
3170 tracking, and cause the file to be distributed automatically.
3171 (@xref{Local Macros}, for an example.) Any macro that is found in a
3172 system-wide directory, or via an absolute search path will be copied.
3173 So use @samp{-I `pwd`/reldir} instead of @samp{-I reldir} whenever
3174 some relative directory should be considered outside the package.
3176 The contents of @file{acinclude.m4}, if this file exists, are also
3177 automatically included in @file{aclocal.m4}. We recommend against
3178 using @file{acinclude.m4} in new packages (@pxref{Local Macros}).
3182 While computing @file{aclocal.m4}, @command{aclocal} runs
3183 @command{autom4te} (@pxref{Using autom4te, , Using @command{Autom4te},
3184 autoconf, The Autoconf Manual}) in order to trace the macros that are
3185 really used, and omit from @file{aclocal.m4} all macros that are
3186 mentioned but otherwise unexpanded (this can happen when a macro is
3187 called conditionally). @command{autom4te} is expected to be in the
3188 @env{PATH}, just as @command{autoconf}. Its location can be
3189 overridden using the @env{AUTOM4TE} environment variable.
3192 * aclocal Options:: Options supported by aclocal
3193 * Macro Search Path:: How aclocal finds .m4 files
3194 * Extending aclocal:: Writing your own aclocal macros
3195 * Local Macros:: Organizing local macros
3196 * Serials:: Serial lines in Autoconf macros
3197 * Future of aclocal:: aclocal's scheduled death
3200 @node aclocal Options
3201 @subsection aclocal Options
3203 @cindex @command{aclocal}, Options
3204 @cindex Options, @command{aclocal}
3206 @command{aclocal} accepts the following options:
3209 @item --automake-acdir=@var{dir}
3210 @opindex --automake-acdir
3211 Look for the automake-provided macro files in @var{dir} instead of
3212 in the installation directory. This is typically used for debugging.
3214 @item --system-acdir=@var{dir}
3215 @opindex --system-acdir
3216 Look for the system-wide third-party macro files (and the special
3217 @file{dirlist} file) in @var{dir} instead of in the installation
3218 directory. This is typically used for debugging.
3220 @item --diff[=@var{command}]
3222 Run @var{command} on M4 file that would be installed or overwritten
3223 by @option{--install}. The default @var{command} is @samp{diff -u}.
3224 This option implies @option{--install} and @option{--dry-run}.
3228 Do not actually overwrite (or create) @file{aclocal.m4} and M4
3229 files installed by @option{--install}.
3233 Print a summary of the command line options and exit.
3237 Add the directory @var{dir} to the list of directories searched for
3242 Install system-wide third-party macros into the first directory
3243 specified with @samp{-I @var{dir}} instead of copying them in the
3245 @c Keep in sync with aclocal-install-absdir.sh
3246 Note that this will happen also if @var{dir} is an absolute path.
3248 @cindex serial number and @option{--install}
3249 When this option is used, and only when this option is used,
3250 @command{aclocal} will also honor @samp{#serial @var{number}} lines
3251 that appear in macros: an M4 file is ignored if there exists another
3252 M4 file with the same basename and a greater serial number in the
3253 search path (@pxref{Serials}).
3257 Always overwrite the output file. The default is to overwrite the output
3258 file only when really needed, i.e., when its contents changes or if one
3259 of its dependencies is younger.
3261 This option forces the update of @file{aclocal.m4} (or the file
3262 specified with @file{--output} below) and only this file, it has
3263 absolutely no influence on files that may need to be installed by
3266 @item --output=@var{file}
3268 Cause the output to be put into @var{file} instead of @file{aclocal.m4}.
3270 @item --print-ac-dir
3271 @opindex --print-ac-dir
3272 Prints the name of the directory that @command{aclocal} will search to
3273 find third-party @file{.m4} files. When this option is given, normal
3274 processing is suppressed. This option was used @emph{in the past} by
3275 third-party packages to determine where to install @file{.m4} macro
3276 files, but @emph{this usage is today discouraged}, since it causes
3277 @samp{$(prefix)} not to be thoroughly honoured (which violates the
3278 GNU Coding Standards), and a similar semantics can be better obtained
3279 with the @env{ACLOCAL_PATH} environment variable; @pxref{Extending aclocal}.
3283 Print the names of the files it examines.
3287 Print the version number of Automake and exit.
3290 @item --warnings=@var{category}
3293 Output warnings falling in @var{category}. @var{category} can be
3297 dubious syntactic constructs, underquoted macros, unused macros, etc.
3301 all the warnings, this is the default
3303 turn off all the warnings
3305 treat warnings as errors
3308 All warnings are output by default.
3311 The environment variable @env{WARNINGS} is honored in the same
3312 way as it is for @command{automake} (@pxref{automake Invocation}).
3316 @node Macro Search Path
3317 @subsection Macro Search Path
3319 @cindex Macro search path
3320 @cindex @command{aclocal} search path
3322 By default, @command{aclocal} searches for @file{.m4} files in the following
3323 directories, in this order:
3326 @item @var{acdir-APIVERSION}
3327 This is where the @file{.m4} macros distributed with Automake itself
3328 are stored. @var{APIVERSION} depends on the Automake release used;
3329 for example, for Automake 1.11.x, @var{APIVERSION} = @code{1.11}.
3332 This directory is intended for third party @file{.m4} files, and is
3333 configured when @command{automake} itself is built. This is
3334 @file{@@datadir@@/aclocal/}, which typically
3335 expands to @file{$@{prefix@}/share/aclocal/}. To find the compiled-in
3336 value of @var{acdir}, use the @option{--print-ac-dir} option
3337 (@pxref{aclocal Options}).
3340 As an example, suppose that @command{automake-1.11.2} was configured with
3341 @option{--prefix=@-/usr/local}. Then, the search path would be:
3344 @item @file{/usr/local/share/aclocal-1.11.2/}
3345 @item @file{/usr/local/share/aclocal/}
3348 The paths for the @var{acdir} and @var{acdir-APIVERSION} directories can
3349 be changed respectively through aclocal options @option{--system-acdir}
3350 and @option{--automake-acdir} (@pxref{aclocal Options}). Note however
3351 that these options are only intended for use by the internal Automake
3352 test suite, or for debugging under highly unusual situations; they are
3353 not ordinarily needed by end-users.
3355 As explained in (@pxref{aclocal Options}), there are several options that
3356 can be used to change or extend this search path.
3358 @subsubheading Modifying the Macro Search Path: @samp{-I @var{dir}}
3360 Any extra directories specified using @option{-I} options
3361 (@pxref{aclocal Options}) are @emph{prepended} to this search list. Thus,
3362 @samp{aclocal -I /foo -I /bar} results in the following search path:
3367 @item @var{acdir}-@var{APIVERSION}
3371 @subsubheading Modifying the Macro Search Path: @file{dirlist}
3372 @cindex @file{dirlist}
3374 There is a third mechanism for customizing the search path. If a
3375 @file{dirlist} file exists in @var{acdir}, then that file is assumed to
3376 contain a list of directory patterns, one per line. @command{aclocal}
3377 expands these patterns to directory names, and adds them to the search
3378 list @emph{after} all other directories. @file{dirlist} entries may
3379 use shell wildcards such as @samp{*}, @samp{?}, or @code{[...]}.
3381 For example, suppose
3382 @file{@var{acdir}/dirlist} contains the following:
3391 and that @command{aclocal} was called with the @samp{-I /foo -I /bar} options.
3392 Then, the search path would be
3394 @c @code looks better than @file here
3398 @item @var{acdir}-@var{APIVERSION}
3405 and all directories with path names starting with @code{/test3}.
3407 If the @option{--system-acdir=@var{dir}} option is used, then
3408 @command{aclocal} will search for the @file{dirlist} file in
3409 @var{dir}; but remember the warnings above against the use of
3410 @option{--system-acdir}.
3412 @file{dirlist} is useful in the following situation: suppose that
3413 @command{automake} version @code{1.11.2} is installed with
3414 @samp{--prefix=/usr} by the system vendor. Thus, the default search
3417 @c @code looks better than @file here
3419 @item @code{/usr/share/aclocal-1.11/}
3420 @item @code{/usr/share/aclocal/}
3423 However, suppose further that many packages have been manually
3424 installed on the system, with $prefix=/usr/local, as is typical. In
3425 that case, many of these ``extra'' @file{.m4} files are in
3426 @file{/usr/local/share/aclocal}. The only way to force
3427 @file{/usr/bin/aclocal} to find these ``extra'' @file{.m4} files is to
3428 always call @samp{aclocal -I /usr/local/share/aclocal}. This is
3429 inconvenient. With @file{dirlist}, one may create a file
3430 @file{/usr/share/aclocal/dirlist} containing only the single line
3433 /usr/local/share/aclocal
3436 Now, the ``default'' search path on the affected system is
3438 @c @code looks better than @file here
3440 @item @code{/usr/share/aclocal-1.11/}
3441 @item @code{/usr/share/aclocal/}
3442 @item @code{/usr/local/share/aclocal/}
3445 without the need for @option{-I} options; @option{-I} options can be reserved
3446 for project-specific needs (@file{my-source-dir/m4/}), rather than
3447 using it to work around local system-dependent tool installation
3450 Similarly, @file{dirlist} can be handy if you have installed a local
3451 copy of Automake in your account and want @command{aclocal} to look for
3452 macros installed at other places on the system.
3454 @anchor{ACLOCAL_PATH}
3455 @subsubheading Modifying the Macro Search Path: @file{ACLOCAL_PATH}
3456 @cindex @env{ACLOCAL_PATH}
3458 The fourth and last mechanism to customize the macro search path is
3459 also the simplest. Any directory included in the colon-separated
3460 environment variable @env{ACLOCAL_PATH} is added to the search path
3461 @c Keep in sync with aclocal-path-precedence.sh
3462 and takes precedence over system directories (including those found via
3463 @file{dirlist}), with the exception of the versioned directory
3464 @var{acdir-APIVERSION} (@pxref{Macro Search Path}). However, directories
3465 passed via @option{-I} will take precedence over directories in
3468 @c Keep in sync with aclocal-path-installed.sh
3469 Also note that, if the @option{--install} option is used, any @file{.m4}
3470 file containing a required macro that is found in a directory listed in
3471 @env{ACLOCAL_PATH} will be installed locally.
3472 @c Keep in sync with aclocal-path-installed-serial.sh
3473 In this case, serial numbers in @file{.m4} are honoured too,
3476 Conversely to @file{dirlist}, @env{ACLOCAL_PATH} is useful if you are
3477 using a global copy of Automake and want @command{aclocal} to look for
3478 macros somewhere under your home directory.
3480 @subsubheading Planned future incompatibilities
3482 The order in which the directories in the macro search path are currently
3483 looked up is confusing and/or suboptimal in various aspects, and is
3484 probably going to be changed in the future Automake release. In
3485 particular, directories in @env{ACLOCAL_PATH} and @file{@var{acdir}}
3486 might end up taking precedence over @file{@var{acdir-APIVERSION}}, and
3487 directories in @file{@var{acdir}/dirlist} might end up taking precedence
3488 over @file{@var{acdir}}. @emph{This is a possible future incompatibility!}
3490 @node Extending aclocal
3491 @subsection Writing your own aclocal macros
3493 @cindex @command{aclocal}, extending
3494 @cindex Extending @command{aclocal}
3496 The @command{aclocal} program doesn't have any built-in knowledge of any
3497 macros, so it is easy to extend it with your own macros.
3499 This can be used by libraries that want to supply their own Autoconf
3500 macros for use by other programs. For instance, the @command{gettext}
3501 library supplies a macro @code{AM_GNU_GETTEXT} that should be used by
3502 any package using @command{gettext}. When the library is installed, it
3503 installs this macro so that @command{aclocal} will find it.
3505 A macro file's name should end in @file{.m4}. Such files should be
3506 installed in @file{$(datadir)/aclocal}. This is as simple as writing:
3508 @c Keep in sync with primary-prefix-couples-documented-valid.sh
3510 aclocaldir = $(datadir)/aclocal
3511 aclocal_DATA = mymacro.m4 myothermacro.m4
3515 Please do use @file{$(datadir)/aclocal}, and not something based on
3516 the result of @samp{aclocal --print-ac-dir} (@pxref{Hard-Coded Install
3517 Paths}, for arguments). It might also be helpful to suggest to
3518 the user to add the @file{$(datadir)/aclocal} directory to his
3519 @env{ACLOCAL_PATH} variable (@pxref{ACLOCAL_PATH}) so that
3520 @command{aclocal} will find the @file{.m4} files installed by your
3521 package automatically.
3523 A file of macros should be a series of properly quoted
3524 @code{AC_DEFUN}'s (@pxref{Macro Definitions, , , autoconf, The
3525 Autoconf Manual}). The @command{aclocal} programs also understands
3526 @code{AC_REQUIRE} (@pxref{Prerequisite Macros, , , autoconf, The
3527 Autoconf Manual}), so it is safe to put each macro in a separate file.
3528 Each file should have no side effects but macro definitions.
3529 Especially, any call to @code{AC_PREREQ} should be done inside the
3530 defined macro, not at the beginning of the file.
3532 @cindex underquoted @code{AC_DEFUN}
3536 Starting with Automake 1.8, @command{aclocal} will warn about all
3537 underquoted calls to @code{AC_DEFUN}. We realize this will annoy a
3538 lot of people, because @command{aclocal} was not so strict in the past
3539 and many third party macros are underquoted; and we have to apologize
3540 for this temporary inconvenience. The reason we have to be stricter
3541 is that a future implementation of @command{aclocal} (@pxref{Future of
3542 aclocal}) will have to temporarily include all of these third party
3543 @file{.m4} files, maybe several times, including even files that are
3544 not actually needed. Doing so should alleviate many problems of the
3545 current implementation, however it requires a stricter style from the
3546 macro authors. Hopefully it is easy to revise the existing macros.
3553 [AC_REQUIRE([AX_SOMETHING])dnl
3560 should be rewritten as
3563 AC_DEFUN([AX_FOOBAR],
3564 [AC_PREREQ([2.68])dnl
3565 AC_REQUIRE([AX_SOMETHING])dnl
3571 Wrapping the @code{AC_PREREQ} call inside the macro ensures that
3572 Autoconf 2.68 will not be required if @code{AX_FOOBAR} is not actually
3573 used. Most importantly, quoting the first argument of @code{AC_DEFUN}
3574 allows the macro to be redefined or included twice (otherwise this
3575 first argument would be expanded during the second definition). For
3576 consistency we like to quote even arguments such as @code{2.68} that
3579 If you have been directed here by the @command{aclocal} diagnostic but
3580 are not the maintainer of the implicated macro, you will want to
3581 contact the maintainer of that macro. Please make sure you have the
3582 latest version of the macro and that the problem hasn't already been
3583 reported before doing so: people tend to work faster when they aren't
3586 Another situation where @command{aclocal} is commonly used is to
3587 manage macros that are used locally by the package, @ref{Local
3591 @subsection Handling Local Macros
3593 Feature tests offered by Autoconf do not cover all needs. People
3594 often have to supplement existing tests with their own macros, or
3595 with third-party macros.
3597 There are two ways to organize custom macros in a package.
3599 The first possibility (the historical practice) is to list all your
3600 macros in @file{acinclude.m4}. This file will be included in
3601 @file{aclocal.m4} when you run @command{aclocal}, and its macro(s) will
3602 henceforth be visible to @command{autoconf}. However if it contains
3603 numerous macros, it will rapidly become difficult to maintain, and it
3604 will be almost impossible to share macros between packages.
3606 The second possibility, which we do recommend, is to write each macro
3607 in its own file and gather all these files in a directory. This
3608 directory is usually called @file{m4/}. Then it's enough to update
3609 @file{configure.ac} by adding a proper call to @code{AC_CONFIG_MACRO_DIRS}:
3612 AC_CONFIG_MACRO_DIRS([m4])
3615 @command{aclocal} will then take care of automatically adding @file{m4/}
3616 to its search path for m4 files.
3618 When @samp{aclocal} is run, it will build an @file{aclocal.m4}
3619 that @code{m4_include}s any file from @file{m4/} that defines a
3620 required macro. Macros not found locally will still be searched in
3621 system-wide directories, as explained in @ref{Macro Search Path}.
3623 Custom macros should be distributed for the same reason that
3624 @file{configure.ac} is: so that other people have all the sources of
3625 your package if they want to work on it. Actually, this distribution
3626 happens automatically because all @code{m4_include}d files are
3629 However there is no consensus on the distribution of third-party
3630 macros that your package may use. Many libraries install their own
3631 macro in the system-wide @command{aclocal} directory (@pxref{Extending
3632 aclocal}). For instance, Guile ships with a file called
3633 @file{guile.m4} that contains the macro @code{GUILE_FLAGS} that can
3634 be used to define setup compiler and linker flags appropriate for
3635 using Guile. Using @code{GUILE_FLAGS} in @file{configure.ac} will
3636 cause @command{aclocal} to copy @file{guile.m4} into
3637 @file{aclocal.m4}, but as @file{guile.m4} is not part of the project,
3638 it will not be distributed. Technically, that means a user who
3639 needs to rebuild @file{aclocal.m4} will have to install Guile first.
3640 This is probably OK, if Guile already is a requirement to build the
3641 package. However, if Guile is only an optional feature, or if your
3642 package might run on architectures where Guile cannot be installed,
3643 this requirement will hinder development. An easy solution is to copy
3644 such third-party macros in your local @file{m4/} directory so they get
3647 Since Automake 1.10, @command{aclocal} offers the option @code{--install}
3648 to copy these system-wide third-party macros in your local macro directory,
3649 helping to solve the above problem.
3651 With this setup, system-wide macros will be copied to @file{m4/}
3652 the first time you run @command{aclocal}. Then the locally installed
3653 macros will have precedence over the system-wide installed macros
3654 each time @command{aclocal} is run again.
3656 One reason why you should keep @option{--install} in the flags even
3657 after the first run is that when you later edit @file{configure.ac}
3658 and depend on a new macro, this macro will be installed in your
3659 @file{m4/} automatically. Another one is that serial numbers
3660 (@pxref{Serials}) can be used to update the macros in your source tree
3661 automatically when new system-wide versions are installed. A serial
3662 number should be a single line of the form
3669 where @var{nnn} contains only digits and dots. It should appear in
3670 the M4 file before any macro definition. It is a good practice to
3671 maintain a serial number for each macro you distribute, even if you do
3672 not use the @option{--install} option of @command{aclocal}: this allows
3673 other people to use it.
3677 @subsection Serial Numbers
3678 @cindex serial numbers in macros
3679 @cindex macro serial numbers
3680 @cindex @code{#serial} syntax
3681 @cindex @command{aclocal} and serial numbers
3683 Because third-party macros defined in @file{*.m4} files are naturally
3684 shared between multiple projects, some people like to version them.
3685 This makes it easier to tell which of two M4 files is newer. Since at
3686 least 1996, the tradition is to use a @samp{#serial} line for this.
3688 A serial number should be a single line of the form
3691 # serial @var{version}
3695 where @var{version} is a version number containing only digits and
3696 dots. Usually people use a single integer, and they increment it each
3697 time they change the macro (hence the name of ``serial''). Such a
3698 line should appear in the M4 file before any macro definition.
3700 The @samp{#} must be the first character on the line,
3701 and it is OK to have extra words after the version, as in
3704 #serial @var{version} @var{garbage}
3707 Normally these serial numbers are completely ignored by
3708 @command{aclocal} and @command{autoconf}, like any genuine comment.
3709 However when using @command{aclocal}'s @option{--install} feature, these
3710 serial numbers will modify the way @command{aclocal} selects the
3711 macros to install in the package: if two files with the same basename
3712 exist in your search path, and if at least one of them uses a
3713 @samp{#serial} line, @command{aclocal} will ignore the file that has
3714 the older @samp{#serial} line (or the file that has none).
3716 Note that a serial number applies to a whole M4 file, not to any macro
3717 it contains. A file can contains multiple macros, but only one
3720 Here is a use case that illustrates the use of @option{--install} and
3721 its interaction with serial numbers. Let's assume we maintain a
3722 package called MyPackage, the @file{configure.ac} of which requires a
3723 third-party macro @code{AX_THIRD_PARTY} defined in
3724 @file{/usr/share/aclocal/thirdparty.m4} as follows:
3728 AC_DEFUN([AX_THIRD_PARTY], [...])
3731 MyPackage uses an @file{m4/} directory to store local macros as
3732 explained in @ref{Local Macros}, and has
3735 AC_CONFIG_MACRO_DIRS([m4])
3739 in its @file{configure.ac}.
3741 Initially the @file{m4/} directory is empty. The first time we run
3742 @command{aclocal --install}, it will notice that
3746 @file{configure.ac} uses @code{AX_THIRD_PARTY}
3748 No local macros define @code{AX_THIRD_PARTY}
3750 @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3755 Because @file{/usr/share/aclocal/thirdparty.m4} is a system-wide macro
3756 and @command{aclocal} was given the @option{--install} option, it will
3757 copy this file in @file{m4/thirdparty.m4}, and output an
3758 @file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}.
3760 The next time @samp{aclocal --install} is run, something different
3761 happens. @command{aclocal} notices that
3765 @file{configure.ac} uses @code{AX_THIRD_PARTY}
3767 @file{m4/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3770 @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3775 Because both files have the same serial number, @command{aclocal} uses
3776 the first it found in its search path order (@pxref{Macro Search
3777 Path}). @command{aclocal} therefore ignores
3778 @file{/usr/share/aclocal/thirdparty.m4} and outputs an
3779 @file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}.
3781 Local directories specified with @option{-I} are always searched before
3782 system-wide directories, so a local file will always be preferred to
3783 the system-wide file in case of equal serial numbers.
3785 Now suppose the system-wide third-party macro is changed. This can
3786 happen if the package installing this macro is updated. Let's suppose
3787 the new macro has serial number 2. The next time @samp{aclocal --install}
3788 is run the situation is the following:
3792 @file{configure.ac} uses @code{AX_THIRD_PARTY}
3794 @file{m4/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3797 @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3802 When @command{aclocal} sees a greater serial number, it immediately
3803 forgets anything it knows from files that have the same basename and a
3804 smaller serial number. So after it has found
3805 @file{/usr/share/aclocal/thirdparty.m4} with serial 2,
3806 @command{aclocal} will proceed as if it had never seen
3807 @file{m4/thirdparty.m4}. This brings us back to a situation similar
3808 to that at the beginning of our example, where no local file defined
3809 the macro. @command{aclocal} will install the new version of the
3810 macro in @file{m4/thirdparty.m4}, in this case overriding the old
3811 version. MyPackage just had its macro updated as a side effect of
3812 running @command{aclocal}.
3814 If you are leery of letting @command{aclocal} update your local
3815 macro, you can run @samp{aclocal --diff} to review the changes
3816 @samp{aclocal --install} would perform on these macros.
3818 Finally, note that the @option{--force} option of @command{aclocal} has
3819 absolutely no effect on the files installed by @option{--install}. For
3820 instance, if you have modified your local macros, do not expect
3821 @option{--install --force} to replace the local macros by their
3822 system-wide versions. If you want to do so, simply erase the local
3823 macros you want to revert, and run @samp{aclocal --install}.
3826 @node Future of aclocal
3827 @subsection The Future of @command{aclocal}
3828 @cindex @command{aclocal}'s scheduled death
3830 @command{aclocal} is expected to disappear. This feature really
3831 should not be offered by Automake. Automake should focus on
3832 generating @file{Makefile}s; dealing with M4 macros really is
3833 Autoconf's job. The fact that some people install Automake just to use
3834 @command{aclocal}, but do not use @command{automake} otherwise is an
3835 indication of how that feature is misplaced.
3837 The new implementation will probably be done slightly differently.
3838 For instance, it could enforce the @file{m4/}-style layout discussed in
3841 We have no idea when and how this will happen. This has been
3842 discussed several times in the past, but someone still has to commit
3843 to that non-trivial task.
3845 From the user point of view, @command{aclocal}'s removal might turn
3846 out to be painful. There is a simple precaution that you may take to
3847 make that switch more seamless: never call @command{aclocal} yourself.
3848 Keep this guy under the exclusive control of @command{autoreconf} and
3849 Automake's rebuild rules. Hopefully you won't need to worry about
3850 things breaking, when @command{aclocal} disappears, because everything
3851 will have been taken care of. If otherwise you used to call
3852 @command{aclocal} directly yourself or from some script, you will
3853 quickly notice the change.
3855 Many packages come with a script called @file{bootstrap.sh} or
3856 @file{autogen.sh}, that will just call @command{aclocal},
3857 @command{libtoolize}, @command{gettextize} or @command{autopoint},
3858 @command{autoconf}, @command{autoheader}, and @command{automake} in
3859 the right order. Actually this is precisely what @command{autoreconf}
3860 can do for you. If your package has such a @file{bootstrap.sh} or
3861 @file{autogen.sh} script, consider using @command{autoreconf}. That
3862 should simplify its logic a lot (less things to maintain, yum!), it's
3863 even likely you will not need the script anymore, and more to the point
3864 you will not call @command{aclocal} directly anymore.
3866 For the time being, third-party packages should continue to install
3867 public macros into @file{/usr/share/aclocal/}. If @command{aclocal}
3868 is replaced by another tool it might make sense to rename the
3869 directory, but supporting @file{/usr/share/aclocal/} for backward
3870 compatibility should be really easy provided all macros are properly
3871 written (@pxref{Extending aclocal}).
3876 @section Autoconf macros supplied with Automake
3878 Automake ships with several Autoconf macros that you can use from your
3879 @file{configure.ac}. When you use one of them it will be included by
3880 @command{aclocal} in @file{aclocal.m4}.
3883 * Public Macros:: Macros that you can use.
3884 * Obsolete Macros:: Macros that will soon be removed.
3885 * Private Macros:: Macros that you should not use.
3888 @c consider generating the following subsections automatically from m4 files.
3891 @subsection Public Macros
3895 @item AM_INIT_AUTOMAKE([OPTIONS])
3896 @acindex AM_INIT_AUTOMAKE
3897 Runs many macros required for proper operation of the generated Makefiles.
3899 @vindex AUTOMAKE_OPTIONS
3900 Today, @code{AM_INIT_AUTOMAKE} is called with a single argument: a
3901 space-separated list of Automake options that should be applied to
3902 every @file{Makefile.am} in the tree. The effect is as if
3903 each option were listed in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
3906 This macro can also be called in another, @emph{deprecated} form:
3907 @code{AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])}. In this form,
3908 there are two required arguments: the package and the version number.
3909 This usage is mostly obsolete because the @var{package} and @var{version}
3910 can be obtained from Autoconf's @code{AC_INIT} macro. However,
3911 differently from what happens for @code{AC_INIT} invocations, this
3912 @code{AM_INIT_AUTOMAKE} invocation supports shell variables' expansions
3913 in the @code{PACKAGE} and @code{VERSION} arguments, and this can be
3914 still be useful in some selected situations. Our hope is that future
3915 Autoconf versions will improve their support for package versions
3916 defined dynamically at configure runtime; when (and if) this happens,
3917 support for the two-args @code{AM_INIT_AUTOMAKE} invocation will likely
3918 be removed from Automake.
3920 @anchor{Modernize AM_INIT_AUTOMAKE invocation}
3921 If your @file{configure.ac} has:
3924 AC_INIT([src/foo.c])
3925 AM_INIT_AUTOMAKE([mumble], [1.5])
3929 you should modernize it as follows:
3932 AC_INIT([mumble], [1.5])
3933 AC_CONFIG_SRCDIR([src/foo.c])
3937 Note that if you're upgrading your @file{configure.ac} from an earlier
3938 version of Automake, it is not always correct to simply move the
3939 package and version arguments from @code{AM_INIT_AUTOMAKE} directly to
3940 @code{AC_INIT}, as in the example above. The first argument to
3941 @code{AC_INIT} should be the name of your package (e.g., @samp{GNU
3942 Automake}), not the tarball name (e.g., @samp{automake}) that you used
3943 to pass to @code{AM_INIT_AUTOMAKE}. Autoconf tries to derive a
3944 tarball name from the package name, which should work for most but not
3945 all package names. (If it doesn't work for yours, you can use the
3946 four-argument form of @code{AC_INIT} to provide the tarball name
3949 @cindex @code{PACKAGE}, prevent definition
3950 @cindex @code{VERSION}, prevent definition
3952 By default this macro @code{AC_DEFINE}'s @code{PACKAGE} and
3953 @code{VERSION}. This can be avoided by passing the @option{no-define}
3954 option (@pxref{List of Automake options}):
3956 AM_INIT_AUTOMAKE([no-define ...])
3959 @item AM_PATH_LISPDIR
3960 @acindex AM_PATH_LISPDIR
3963 Searches for the program @command{emacs}, and, if found, sets the
3964 output variable @code{lispdir} to the full path to Emacs' site-lisp
3967 Note that this test assumes the @command{emacs} found to be a version
3968 that supports Emacs Lisp (such as GNU Emacs or XEmacs). Other
3969 emacsen can cause this test to hang (some, like old versions of
3970 MicroEmacs, start up in interactive mode, requiring @kbd{C-x C-c} to
3971 exit, which is hardly obvious for a non-emacs user). In most cases,
3972 however, you should be able to use @kbd{C-c} to kill the test. In
3973 order to avoid problems, you can set @env{EMACS} to ``no'' in the
3974 environment, or use the @option{--with-lispdir} option to
3975 @command{configure} to explicitly set the correct path (if you're sure
3976 you have an @command{emacs} that supports Emacs Lisp).
3978 @item AM_PROG_AR(@ovar{act-if-fail})
3981 You must use this macro when you use the archiver in your project, if
3982 you want support for unusual archivers such as Microsoft @command{lib}.
3983 The content of the optional argument is executed if the archiver
3984 interface is not recognized; the default action is to abort configure
3985 with an error message.
3991 Use this macro when you have assembly code in your project. This will
3992 choose the assembler for you (by default the C compiler) and set
3993 @code{CCAS}, and will also set @code{CCASFLAGS} if required.
3995 @item AM_PROG_CC_C_O
3996 @acindex AM_PROG_CC_C_O
3997 @acindex AC_PROG_CC_C_O
3998 This is an @emph{obsolete wrapper} around @code{AC_PROG_CC_C_O}.
3999 New code needs not use this macro. It might be deprecated and
4000 @emph{retired in future Automake versions}.
4003 @acindex AM_PROG_LEX
4004 @acindex AC_PROG_LEX
4005 @cindex HP-UX 10, @command{lex} problems
4006 @cindex @command{lex} problems with HP-UX 10
4007 Like @code{AC_PROG_LEX} (@pxref{Particular Programs, , Particular
4008 Program Checks, autoconf, The Autoconf Manual}), but uses the
4009 @command{missing} script on systems that do not have @command{lex}.
4010 HP-UX 10 is one such system.
4013 @acindex AM_PROG_GCJ
4016 This macro finds the @command{gcj} program or causes an error. It sets
4017 @code{GCJ} and @code{GCJFLAGS}. @command{gcj} is the Java front-end to the
4018 GNU Compiler Collection.
4020 @item AM_PROG_UPC([@var{compiler-search-list}])
4021 @acindex AM_PROG_UPC
4023 Find a compiler for Unified Parallel C and define the @code{UPC}
4024 variable. The default @var{compiler-search-list} is @samp{upcc upc}.
4025 This macro will abort @command{configure} if no Unified Parallel C
4028 @item AM_MISSING_PROG(@var{name}, @var{program})
4029 @acindex AM_MISSING_PROG
4031 Find a maintainer tool @var{program} and define the @var{name}
4032 environment variable with its location. If @var{program} is not
4033 detected, then @var{name} will instead invoke the @command{missing}
4034 script, in order to give useful advice to the user about the missing
4035 maintainer tool. @xref{maintainer-mode}, for more information on when
4036 the @command{missing} script is appropriate.
4038 @item AM_SILENT_RULES
4039 @acindex AM_SILENT_RULES
4040 Control the machinery for less verbose build output
4041 (@pxref{Automake Silent Rules}).
4043 @item AM_WITH_DMALLOC
4044 @acindex AM_WITH_DMALLOC
4045 @cindex @command{dmalloc}, support for
4046 @vindex WITH_DMALLOC
4047 @opindex --with-dmalloc
4048 Add support for the @uref{http://dmalloc.com/, Dmalloc package}. If
4049 the user runs @command{configure} with @option{--with-dmalloc}, then
4050 define @code{WITH_DMALLOC} and add @option{-ldmalloc} to @code{LIBS}.
4055 @node Obsolete Macros
4056 @subsection Obsolete Macros
4057 @cindex obsolete macros
4060 Although using some of the following macros was required in past
4061 releases, you should not use any of them in new code. @emph{All
4062 these macros will be removed in the next major Automake version};
4063 if you are still using them, running @command{autoupdate} should
4064 adjust your @file{configure.ac} automatically (@pxref{autoupdate
4065 Invocation, , Using @command{autoupdate} to Modernize
4066 @file{configure.ac}, autoconf, The Autoconf Manual}).
4071 @item AM_PROG_CC_C_O
4072 @acindex AM_PROG_CC_C_O
4073 @acindex AC_PROG_CC_C_O
4074 This is an @emph{obsolete wrapper} around @code{AC_PROG_CC_C_O}. New
4075 code needs not to use this macro. It will be deprecated, and then
4076 removed, in future Automake versions.
4078 @item AM_PROG_MKDIR_P
4079 @acindex AM_PROG_MKDIR_P
4080 @cindex @code{mkdir -p}, macro check
4084 From Automake 1.8 to 1.9.6 this macro used to define the output
4085 variable @code{mkdir_p} to one of @code{mkdir -p}, @code{install-sh
4086 -d}, or @code{mkinstalldirs}.
4088 Nowadays Autoconf provides a similar functionality with
4089 @code{AC_PROG_MKDIR_P} (@pxref{Particular Programs, , Particular
4090 Program Checks, autoconf, The Autoconf Manual}), however this defines
4091 the output variable @code{MKDIR_P} instead. In case you are still
4092 using the @code{AM_PROG_MKDIR_P} macro in your @file{configure.ac},
4093 or its provided variable @code{$(mkdir_p)} in your @file{Makefile.am},
4094 you are advised to switch ASAP to the more modern Autoconf-provided
4095 interface instead; both the macro and the variable @emph{will be
4096 removed} in the next major Automake release.
4101 @node Private Macros
4102 @subsection Private Macros
4104 The following macros are private macros you should not call directly.
4105 They are called by the other public macros when appropriate. Do not
4106 rely on them, as they might be changed in a future version. Consider
4107 them as implementation details; or better, do not consider them at all:
4111 @item _AM_DEPENDENCIES
4112 @itemx AM_SET_DEPDIR
4114 @itemx AM_OUTPUT_DEPENDENCY_COMMANDS
4115 These macros are used to implement Automake's automatic dependency
4116 tracking scheme. They are called automatically by Automake when
4117 required, and there should be no need to invoke them manually.
4119 @item AM_MAKE_INCLUDE
4120 This macro is used to discover how the user's @command{make} handles
4121 @code{include} statements. This macro is automatically invoked when
4122 needed; there should be no need to invoke it manually.
4124 @item AM_PROG_INSTALL_STRIP
4125 This is used to find a version of @code{install} that can be used to
4126 strip a program at installation time. This macro is automatically
4127 included when required.
4129 @item AM_SANITY_CHECK
4130 This checks to make sure that a file created in the build directory is
4131 newer than a file in the source directory. This can fail on systems
4132 where the clock is set incorrectly. This macro is automatically run
4133 from @code{AM_INIT_AUTOMAKE}.
4139 @chapter Directories
4141 For simple projects that distribute all files in the same directory
4142 it is enough to have a single @file{Makefile.am} that builds
4143 everything in place.
4145 In larger projects, it is common to organize files in different
4146 directories, in a tree. For example, there could be a directory
4147 for the program's source, one for the testsuite, and one for the
4148 documentation; or, for very large projects, there could be one
4149 directory per program, per library or per module.
4151 The traditional approach is to build these subdirectories recursively,
4152 employing @emph{make recursion}: each directory contains its
4153 own @file{Makefile}, and when @command{make} is run from the top-level
4154 directory, it enters each subdirectory in turn, and invokes there a
4155 new @command{make} instance to build the directory's contents.
4157 Because this approach is very widespread, Automake offers built-in
4158 support for it. However, it is worth nothing that the use of make
4159 recursion has its own serious issues and drawbacks, and that it's
4160 well possible to have packages with a multi directory layout that
4161 make little or no use of such recursion (examples of such packages
4162 are GNU Bison and GNU Automake itself); see also the @ref{Alternative}
4166 * Subdirectories:: Building subdirectories recursively
4167 * Conditional Subdirectories:: Conditionally not building directories
4168 * Alternative:: Subdirectories without recursion
4169 * Subpackages:: Nesting packages
4172 @node Subdirectories
4173 @section Recursing subdirectories
4175 @cindex @code{SUBDIRS}, explained
4177 In packages using make recursion, the top level @file{Makefile.am} must
4178 tell Automake which subdirectories are to be built. This is done via
4179 the @code{SUBDIRS} variable.
4182 The @code{SUBDIRS} variable holds a list of subdirectories in which
4183 building of various sorts can occur. The rules for many targets
4184 (e.g., @code{all}) in the generated @file{Makefile} will run commands
4185 both locally and in all specified subdirectories. Note that the
4186 directories listed in @code{SUBDIRS} are not required to contain
4187 @file{Makefile.am}s; only @file{Makefile}s (after configuration).
4188 This allows inclusion of libraries from packages that do not use
4189 Automake (such as @code{gettext}; see also @ref{Third-Party
4192 In packages that use subdirectories, the top-level @file{Makefile.am} is
4193 often very short. For instance, here is the @file{Makefile.am} from the
4194 GNU Hello distribution:
4197 EXTRA_DIST = BUGS ChangeLog.O README-alpha
4198 SUBDIRS = doc intl po src tests
4201 When Automake invokes @command{make} in a subdirectory, it uses the value
4202 of the @code{MAKE} variable. It passes the value of the variable
4203 @code{AM_MAKEFLAGS} to the @command{make} invocation; this can be set in
4204 @file{Makefile.am} if there are flags you must always pass to
4207 @vindex AM_MAKEFLAGS
4209 The directories mentioned in @code{SUBDIRS} are usually direct
4210 children of the current directory, each subdirectory containing its
4211 own @file{Makefile.am} with a @code{SUBDIRS} pointing to deeper
4212 subdirectories. Automake can be used to construct packages of
4213 arbitrary depth this way.
4215 By default, Automake generates @file{Makefiles} that work depth-first
4216 in postfix order: the subdirectories are built before the current
4217 directory. However, it is possible to change this ordering. You can
4218 do this by putting @samp{.} into @code{SUBDIRS}. For instance,
4219 putting @samp{.} first will cause a prefix ordering of
4225 SUBDIRS = lib src . test
4229 will cause @file{lib/} to be built before @file{src/}, then the
4230 current directory will be built, finally the @file{test/} directory
4231 will be built. It is customary to arrange test directories to be
4232 built after everything else since they are meant to test what has
4235 In addition to the built-in recursive targets defined by Automake
4236 (@code{all}, @code{check}, etc.), the developer can also define his
4237 own recursive targets. That is done by passing the names of such
4238 targets as arguments to the m4 macro @code{AM_EXTRA_RECURSIVE_TARGETS}
4239 in @file{configure.ac}. Automake generates rules to handle the
4240 recursion for such targets; and the developer can define real actions
4241 for them by defining corresponding @code{-local} targets.
4244 % @kbd{cat configure.ac}
4245 AC_INIT([pkg-name], [1.0]
4247 AM_EXTRA_RECURSIVE_TARGETS([foo])
4248 AC_CONFIG_FILES([Makefile sub/Makefile sub/src/Makefile])
4250 % @kbd{cat Makefile.am}
4253 @@echo This will be run by "make foo".
4254 % @kbd{cat sub/Makefile.am}
4256 % @kbd{cat sub/src/Makefile.am}
4258 @@echo This too will be run by a "make foo" issued either in
4259 @@echo the 'sub/src/' directory, the 'sub/' directory, or the
4260 @@echo top-level directory.
4263 @node Conditional Subdirectories
4264 @section Conditional Subdirectories
4265 @cindex Subdirectories, building conditionally
4266 @cindex Conditional subdirectories
4267 @cindex @code{SUBDIRS}, conditional
4268 @cindex Conditional @code{SUBDIRS}
4270 It is possible to define the @code{SUBDIRS} variable conditionally if,
4271 like in the case of GNU Inetutils, you want to only build a subset of
4274 To illustrate how this works, let's assume we have two directories
4275 @file{src/} and @file{opt/}. @file{src/} should always be built, but we
4276 want to decide in @command{configure} whether @file{opt/} will be built
4277 or not. (For this example we will assume that @file{opt/} should be
4278 built when the variable @samp{$want_opt} was set to @samp{yes}.)
4280 Running @command{make} should thus recurse into @file{src/} always, and
4281 then maybe in @file{opt/}.
4283 However @samp{make dist} should always recurse into both @file{src/}
4284 and @file{opt/}. Because @file{opt/} should be distributed even if it
4285 is not needed in the current configuration. This means
4286 @file{opt/Makefile} should be created @emph{unconditionally}.
4288 There are two ways to setup a project like this. You can use Automake
4289 conditionals (@pxref{Conditionals}) or use Autoconf @code{AC_SUBST}
4290 variables (@pxref{Setting Output Variables, , Setting Output
4291 Variables, autoconf, The Autoconf Manual}). Using Automake
4292 conditionals is the preferred solution. Before we illustrate these
4293 two possibilities, let's introduce @code{DIST_SUBDIRS}.
4296 * SUBDIRS vs DIST_SUBDIRS:: Two sets of directories
4297 * Subdirectories with AM_CONDITIONAL:: Specifying conditional subdirectories
4298 * Subdirectories with AC_SUBST:: Another way for conditional recursion
4299 * Unconfigured Subdirectories:: Not even creating a @samp{Makefile}
4302 @node SUBDIRS vs DIST_SUBDIRS
4303 @subsection @code{SUBDIRS} vs.@: @code{DIST_SUBDIRS}
4304 @cindex @code{DIST_SUBDIRS}, explained
4306 Automake considers two sets of directories, defined by the variables
4307 @code{SUBDIRS} and @code{DIST_SUBDIRS}.
4309 @code{SUBDIRS} contains the subdirectories of the current directory
4310 that must be built (@pxref{Subdirectories}). It must be defined
4311 manually; Automake will never guess a directory is to be built. As we
4312 will see in the next two sections, it is possible to define it
4313 conditionally so that some directory will be omitted from the build.
4315 @code{DIST_SUBDIRS} is used in rules that need to recurse in all
4316 directories, even those that have been conditionally left out of the
4317 build. Recall our example where we may not want to build subdirectory
4318 @file{opt/}, but yet we want to distribute it? This is where
4319 @code{DIST_SUBDIRS} comes into play: @samp{opt} may not appear in
4320 @code{SUBDIRS}, but it must appear in @code{DIST_SUBDIRS}.
4322 Precisely, @code{DIST_SUBDIRS} is used by @samp{make
4323 maintainer-clean}, @samp{make distclean} and @samp{make dist}. All
4324 other recursive rules use @code{SUBDIRS}.
4326 If @code{SUBDIRS} is defined conditionally using Automake
4327 conditionals, Automake will define @code{DIST_SUBDIRS} automatically
4328 from the possible values of @code{SUBDIRS} in all conditions.
4330 If @code{SUBDIRS} contains @code{AC_SUBST} variables,
4331 @code{DIST_SUBDIRS} will not be defined correctly because Automake
4332 does not know the possible values of these variables. In this case
4333 @code{DIST_SUBDIRS} needs to be defined manually.
4335 @node Subdirectories with AM_CONDITIONAL
4336 @subsection Subdirectories with @code{AM_CONDITIONAL}
4337 @cindex @code{SUBDIRS} and @code{AM_CONDITIONAL}
4338 @cindex @code{AM_CONDITIONAL} and @code{SUBDIRS}
4340 @c Keep in sync with subdir-am-cond.sh
4342 @file{configure} should output the @file{Makefile} for each directory
4343 and define a condition into which @file{opt/} should be built.
4347 AM_CONDITIONAL([COND_OPT], [test "$want_opt" = yes])
4348 AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
4352 Then @code{SUBDIRS} can be defined in the top-level @file{Makefile.am}
4359 SUBDIRS = src $(MAYBE_OPT)
4362 As you can see, running @command{make} will rightly recurse into
4363 @file{src/} and maybe @file{opt/}.
4365 @vindex DIST_SUBDIRS
4366 As you can't see, running @samp{make dist} will recurse into both
4367 @file{src/} and @file{opt/} directories because @samp{make dist}, unlike
4368 @samp{make all}, doesn't use the @code{SUBDIRS} variable. It uses the
4369 @code{DIST_SUBDIRS} variable.
4371 In this case Automake will define @samp{DIST_SUBDIRS = src opt}
4372 automatically because it knows that @code{MAYBE_OPT} can contain
4373 @samp{opt} in some condition.
4375 @node Subdirectories with AC_SUBST
4376 @subsection Subdirectories with @code{AC_SUBST}
4377 @cindex @code{SUBDIRS} and @code{AC_SUBST}
4378 @cindex @code{AC_SUBST} and @code{SUBDIRS}
4380 @c Keep in sync with subdir-ac-subst.sh
4382 Another possibility is to define @code{MAYBE_OPT} from
4383 @file{./configure} using @code{AC_SUBST}:
4387 if test "$want_opt" = yes; then
4392 AC_SUBST([MAYBE_OPT])
4393 AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
4397 In this case the top-level @file{Makefile.am} should look as follows.
4400 SUBDIRS = src $(MAYBE_OPT)
4401 DIST_SUBDIRS = src opt
4404 The drawback is that since Automake cannot guess what the possible
4405 values of @code{MAYBE_OPT} are, it is necessary to define
4406 @code{DIST_SUBDIRS}.
4408 @node Unconfigured Subdirectories
4409 @subsection Unconfigured Subdirectories
4410 @cindex Subdirectories, configured conditionally
4412 The semantics of @code{DIST_SUBDIRS} are often misunderstood by some
4413 users that try to @emph{configure and build} subdirectories
4414 conditionally. Here by configuring we mean creating the
4415 @file{Makefile} (it might also involve running a nested
4416 @command{configure} script: this is a costly operation that explains
4417 why people want to do it conditionally, but only the @file{Makefile}
4418 is relevant to the discussion).
4420 The above examples all assume that every @file{Makefile} is created,
4421 even in directories that are not going to be built. The simple reason
4422 is that we want @samp{make dist} to distribute even the directories
4423 that are not being built (e.g., platform-dependent code), hence
4424 @file{make dist} must recurse into the subdirectory, hence this
4425 directory must be configured and appear in @code{DIST_SUBDIRS}.
4427 Building packages that do not configure every subdirectory is a tricky
4428 business, and we do not recommend it to the novice as it is easy to
4429 produce an incomplete tarball by mistake. We will not discuss this
4430 topic in depth here, yet for the adventurous here are a few rules to
4435 @item @code{SUBDIRS} should always be a subset of @code{DIST_SUBDIRS}.
4437 It makes little sense to have a directory in @code{SUBDIRS} that
4438 is not in @code{DIST_SUBDIRS}. Think of the former as a way to tell
4439 which directories listed in the latter should be built.
4440 @item Any directory listed in @code{DIST_SUBDIRS} and @code{SUBDIRS}
4443 I.e., the @file{Makefile} must exists or the recursive @command{make}
4444 rules will not be able to process the directory.
4445 @item Any configured directory must be listed in @code{DIST_SUBDIRS}.
4447 So that the cleaning rules remove the generated @file{Makefile}s.
4448 It would be correct to see @code{DIST_SUBDIRS} as a variable that
4449 lists all the directories that have been configured.
4453 In order to prevent recursion in some unconfigured directory you
4454 must therefore ensure that this directory does not appear in
4455 @code{DIST_SUBDIRS} (and @code{SUBDIRS}). For instance, if you define
4456 @code{SUBDIRS} conditionally using @code{AC_SUBST} and do not define
4457 @code{DIST_SUBDIRS} explicitly, it will be default to
4458 @samp{$(SUBDIRS)}; another possibility is to force @code{DIST_SUBDIRS
4461 Of course, directories that are omitted from @code{DIST_SUBDIRS} will
4462 not be distributed unless you make other arrangements for this to
4463 happen (for instance, always running @samp{make dist} in a
4464 configuration where all directories are known to appear in
4465 @code{DIST_SUBDIRS}; or writing a @code{dist-hook} target to
4466 distribute these directories).
4468 @cindex Subdirectories, not distributed
4469 In few packages, unconfigured directories are not even expected to
4470 be distributed. Although these packages do not require the
4471 aforementioned extra arrangements, there is another pitfall. If the
4472 name of a directory appears in @code{SUBDIRS} or @code{DIST_SUBDIRS},
4473 @command{automake} will make sure the directory exists. Consequently
4474 @command{automake} cannot be run on such a distribution when one
4475 directory has been omitted. One way to avoid this check is to use the
4476 @code{AC_SUBST} method to declare conditional directories; since
4477 @command{automake} does not know the values of @code{AC_SUBST}
4478 variables it cannot ensure the corresponding directory exists.
4481 @section An Alternative Approach to Subdirectories
4483 If you've ever read Peter Miller's excellent paper,
4484 @uref{http://miller.emu.id.au/pmiller/books/rmch/,
4485 Recursive Make Considered Harmful}, the preceding sections on the use of
4486 make recursion will probably come as unwelcome advice. For those who
4487 haven't read the paper, Miller's main thesis is that recursive
4488 @command{make} invocations are both slow and error-prone.
4490 Automake provides sufficient cross-directory support @footnote{We
4491 believe. This work is new and there are probably warts.
4492 @xref{Introduction}, for information on reporting bugs.} to enable you
4493 to write a single @file{Makefile.am} for a complex multi-directory
4496 By default an installable file specified in a subdirectory will have its
4497 directory name stripped before installation. For instance, in this
4498 example, the header file will be installed as
4499 @file{$(includedir)/stdio.h}:
4502 include_HEADERS = inc/stdio.h
4506 @cindex @code{nobase_} prefix
4507 @cindex Path stripping, avoiding
4508 @cindex Avoiding path stripping
4510 However, the @samp{nobase_} prefix can be used to circumvent this path
4511 stripping. In this example, the header file will be installed as
4512 @file{$(includedir)/sys/types.h}:
4515 nobase_include_HEADERS = sys/types.h
4518 @cindex @code{nobase_} and @code{dist_} or @code{nodist_}
4519 @cindex @code{dist_} and @code{nobase_}
4520 @cindex @code{nodist_} and @code{nobase_}
4524 @samp{nobase_} should be specified first when used in conjunction with
4525 either @samp{dist_} or @samp{nodist_} (@pxref{Fine-grained Distribution
4526 Control}). For instance:
4529 nobase_dist_pkgdata_DATA = images/vortex.pgm sounds/whirl.ogg
4532 Finally, note that a variable using the @samp{nobase_} prefix can
4533 often be replaced by several variables, one for each destination
4534 directory (@pxref{Uniform}). For instance, the last example could be
4535 rewritten as follows:
4537 @c Keep in sync with primary-prefix-couples-documented-valid.sh
4539 imagesdir = $(pkgdatadir)/images
4540 soundsdir = $(pkgdatadir)/sounds
4541 dist_images_DATA = images/vortex.pgm
4542 dist_sounds_DATA = sounds/whirl.ogg
4546 This latter syntax makes it possible to change one destination
4547 directory without changing the layout of the source tree.
4549 Currently, @samp{nobase_*_LTLIBRARIES} are the only exception to this
4550 rule, in that there is no particular installation order guarantee for
4551 an otherwise equivalent set of variables without @samp{nobase_} prefix.
4554 @section Nesting Packages
4555 @cindex Nesting packages
4557 @acindex AC_CONFIG_SUBDIRS
4558 @acindex AC_CONFIG_AUX_DIR
4561 In the GNU Build System, packages can be nested to arbitrary depth.
4562 This means that a package can embed other packages with their own
4563 @file{configure}, @file{Makefile}s, etc.
4565 These other packages should just appear as subdirectories of their
4566 parent package. They must be listed in @code{SUBDIRS} like other
4567 ordinary directories. However the subpackage's @file{Makefile}s
4568 should be output by its own @file{configure} script, not by the
4569 parent's @file{configure}. This is achieved using the
4570 @code{AC_CONFIG_SUBDIRS} Autoconf macro (@pxref{Subdirectories,
4571 AC_CONFIG_SUBDIRS, Configuring Other Packages in Subdirectories,
4572 autoconf, The Autoconf Manual}).
4574 Here is an example package for an @code{arm} program that links with
4575 a @code{hand} library that is a nested package in subdirectory
4578 @code{arm}'s @file{configure.ac}:
4581 AC_INIT([arm], [1.0])
4582 AC_CONFIG_AUX_DIR([.])
4585 AC_CONFIG_FILES([Makefile])
4586 # Call hand's ./configure script recursively.
4587 AC_CONFIG_SUBDIRS([hand])
4591 @code{arm}'s @file{Makefile.am}:
4594 # Build the library in the hand subdirectory first.
4597 # Include hand's header when compiling this directory.
4598 AM_CPPFLAGS = -I$(srcdir)/hand
4602 # link with the hand library.
4603 arm_LDADD = hand/libhand.a
4606 Now here is @code{hand}'s @file{hand/configure.ac}:
4609 AC_INIT([hand], [1.2])
4610 AC_CONFIG_AUX_DIR([.])
4615 AC_CONFIG_FILES([Makefile])
4620 and its @file{hand/Makefile.am}:
4623 lib_LIBRARIES = libhand.a
4624 libhand_a_SOURCES = hand.c
4627 When @samp{make dist} is run from the top-level directory it will
4628 create an archive @file{arm-1.0.tar.gz} that contains the @code{arm}
4629 code as well as the @file{hand} subdirectory. This package can be
4630 built and installed like any ordinary package, with the usual
4631 @samp{./configure && make && make install} sequence (the @code{hand}
4632 subpackage will be built and installed by the process).
4634 When @samp{make dist} is run from the hand directory, it will create a
4635 self-contained @file{hand-1.2.tar.gz} archive. So although it appears
4636 to be embedded in another package, it can still be used separately.
4638 The purpose of the @samp{AC_CONFIG_AUX_DIR([.])} instruction is to
4639 force Automake and Autoconf to search for auxiliary scripts in the
4640 current directory. For instance, this means that there will be two
4641 copies of @file{install-sh}: one in the top-level of the @code{arm}
4642 package, and another one in the @file{hand/} subdirectory for the
4643 @code{hand} package.
4645 The historical default is to search for these auxiliary scripts in
4646 the parent directory and the grandparent directory. So if the
4647 @samp{AC_CONFIG_AUX_DIR([.])} line was removed from
4648 @file{hand/configure.ac}, that subpackage would share the auxiliary
4649 script of the @code{arm} package. This may looks like a gain in size
4650 (a few kilobytes), but it is actually a loss of modularity as the
4651 @code{hand} subpackage is no longer self-contained (@samp{make dist}
4652 in the subdirectory will not work anymore).
4654 Packages that do not use Automake need more work to be integrated this
4655 way. @xref{Third-Party Makefiles}.
4658 @chapter Building Programs and Libraries
4660 A large part of Automake's functionality is dedicated to making it easy
4661 to build programs and libraries.
4664 * A Program:: Building a program
4665 * A Library:: Building a library
4666 * A Shared Library:: Building a Libtool library
4667 * Program and Library Variables:: Variables controlling program and
4669 * Default _SOURCES:: Default source files
4670 * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
4671 * Program Variables:: Variables used when building a program
4672 * Yacc and Lex:: Yacc and Lex support
4673 * C++ Support:: Compiling C++ sources
4674 * Objective C Support:: Compiling Objective C sources
4675 * Objective C++ Support:: Compiling Objective C++ sources
4676 * Unified Parallel C Support:: Compiling Unified Parallel C sources
4677 * Assembly Support:: Compiling assembly sources
4678 * Fortran 77 Support:: Compiling Fortran 77 sources
4679 * Fortran 9x Support:: Compiling Fortran 9x sources
4680 * Java Support with gcj:: Compiling Java sources using gcj
4681 * Vala Support:: Compiling Vala sources
4682 * Support for Other Languages:: Compiling other languages
4683 * Dependencies:: Automatic dependency tracking
4684 * EXEEXT:: Support for executable extensions
4689 @section Building a program
4691 In order to build a program, you need to tell Automake which sources
4692 are part of it, and which libraries it should be linked with.
4694 This section also covers conditional compilation of sources or
4695 programs. Most of the comments about these also apply to libraries
4696 (@pxref{A Library}) and libtool libraries (@pxref{A Shared Library}).
4699 * Program Sources:: Defining program sources
4700 * Linking:: Linking with libraries or extra objects
4701 * Conditional Sources:: Handling conditional sources
4702 * Conditional Programs:: Building a program conditionally
4705 @node Program Sources
4706 @subsection Defining program sources
4708 @cindex @code{PROGRAMS}, @code{bindir}
4710 @vindex bin_PROGRAMS
4711 @vindex sbin_PROGRAMS
4712 @vindex libexec_PROGRAMS
4713 @vindex pkglibexec_PROGRAMS
4714 @vindex noinst_PROGRAMS
4715 @vindex check_PROGRAMS
4717 In a directory containing source that gets built into a program (as
4718 opposed to a library or a script), the @code{PROGRAMS} primary is used.
4719 Programs can be installed in @code{bindir}, @code{sbindir},
4720 @code{libexecdir}, @code{pkglibexecdir}, or not at all
4721 (@code{noinst_}). They can also be built only for @samp{make check}, in
4722 which case the prefix is @samp{check_}.
4727 bin_PROGRAMS = hello
4730 In this simple case, the resulting @file{Makefile.in} will contain code
4731 to generate a program named @code{hello}.
4733 Associated with each program are several assisting variables that are
4734 named after the program. These variables are all optional, and have
4735 reasonable defaults. Each variable, its use, and default is spelled out
4736 below; we use the ``hello'' example throughout.
4738 The variable @code{hello_SOURCES} is used to specify which source files
4739 get built into an executable:
4742 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
4745 This causes each mentioned @file{.c} file to be compiled into the
4746 corresponding @file{.o}. Then all are linked to produce @file{hello}.
4748 @cindex @code{_SOURCES} primary, defined
4749 @cindex @code{SOURCES} primary, defined
4750 @cindex Primary variable, @code{SOURCES}
4753 If @code{hello_SOURCES} is not specified, then it defaults to the single
4754 file @file{hello.c} (@pxref{Default _SOURCES}).
4758 Multiple programs can be built in a single directory. Multiple programs
4759 can share a single source file, which must be listed in each
4760 @code{_SOURCES} definition.
4762 @cindex Header files in @code{_SOURCES}
4763 @cindex @code{_SOURCES} and header files
4765 Header files listed in a @code{_SOURCES} definition will be included in
4766 the distribution but otherwise ignored. In case it isn't obvious, you
4767 should not include the header file generated by @file{configure} in a
4768 @code{_SOURCES} variable; this file should not be distributed. Lex
4769 (@file{.l}) and Yacc (@file{.y}) files can also be listed; see @ref{Yacc
4774 @subsection Linking the program
4776 If you need to link against libraries that are not found by
4777 @command{configure}, you can use @code{LDADD} to do so. This variable is
4778 used to specify additional objects or libraries to link with; it is
4779 inappropriate for specifying specific linker flags, you should use
4780 @code{AM_LDFLAGS} for this purpose.
4784 @cindex @code{prog_LDADD}, defined
4786 Sometimes, multiple programs are built in one directory but do not share
4787 the same link-time requirements. In this case, you can use the
4788 @code{@var{prog}_LDADD} variable (where @var{prog} is the name of the
4789 program as it appears in some @code{_PROGRAMS} variable, and usually
4790 written in lowercase) to override @code{LDADD}. If this variable exists
4791 for a given program, then that program is not linked using @code{LDADD}.
4794 For instance, in GNU cpio, @code{pax}, @code{cpio} and @code{mt} are
4795 linked against the library @file{libcpio.a}. However, @code{rmt} is
4796 built in the same directory, and has no such link requirement. Also,
4797 @code{mt} and @code{rmt} are only built on certain architectures. Here
4798 is what cpio's @file{src/Makefile.am} looks like (abridged):
4801 bin_PROGRAMS = cpio pax $(MT)
4802 libexec_PROGRAMS = $(RMT)
4803 EXTRA_PROGRAMS = mt rmt
4805 LDADD = ../lib/libcpio.a $(INTLLIBS)
4808 cpio_SOURCES = @dots{}
4809 pax_SOURCES = @dots{}
4810 mt_SOURCES = @dots{}
4811 rmt_SOURCES = @dots{}
4814 @cindex @code{_LDFLAGS}, defined
4815 @vindex maude_LDFLAGS
4816 @code{@var{prog}_LDADD} is inappropriate for passing program-specific
4817 linker flags (except for @option{-l}, @option{-L}, @option{-dlopen} and
4818 @option{-dlpreopen}). So, use the @code{@var{prog}_LDFLAGS} variable for
4821 @cindex @code{_DEPENDENCIES}, defined
4822 @vindex maude_DEPENDENCIES
4823 @vindex EXTRA_maude_DEPENDENCIES
4824 It is also occasionally useful to have a program depend on some other
4825 target that is not actually part of that program. This can be done
4826 using either the @code{@var{prog}_DEPENDENCIES} or the
4827 @code{EXTRA_@var{prog}_DEPENDENCIES} variable. Each program depends on
4828 the contents both variables, but no further interpretation is done.
4830 Since these dependencies are associated to the link rule used to
4831 create the programs they should normally list files used by the link
4832 command. That is @file{*.$(OBJEXT)}, @file{*.a}, or @file{*.la}
4833 files. In rare cases you may need to add other kinds of files such as
4834 linker scripts, but @emph{listing a source file in
4835 @code{_DEPENDENCIES} is wrong}. If some source file needs to be built
4836 before all the components of a program are built, consider using the
4837 @code{BUILT_SOURCES} variable instead (@pxref{Sources}).
4839 If @code{@var{prog}_DEPENDENCIES} is not supplied, it is computed by
4840 Automake. The automatically-assigned value is the contents of
4841 @code{@var{prog}_LDADD}, with most configure substitutions, @option{-l},
4842 @option{-L}, @option{-dlopen} and @option{-dlpreopen} options removed. The
4843 configure substitutions that are left in are only @samp{$(LIBOBJS)} and
4844 @samp{$(ALLOCA)}; these are left because it is known that they will not
4845 cause an invalid value for @code{@var{prog}_DEPENDENCIES} to be
4848 @ref{Conditional Sources} shows a situation where @code{_DEPENDENCIES}
4851 The @code{EXTRA_@var{prog}_DEPENDENCIES} may be useful for cases where
4852 you merely want to augment the @command{automake}-generated
4853 @code{@var{prog}_DEPENDENCIES} rather than replacing it.
4855 @cindex @code{LDADD} and @option{-l}
4856 @cindex @option{-l} and @code{LDADD}
4857 We recommend that you avoid using @option{-l} options in @code{LDADD}
4858 or @code{@var{prog}_LDADD} when referring to libraries built by your
4859 package. Instead, write the file name of the library explicitly as in
4860 the above @code{cpio} example. Use @option{-l} only to list
4861 third-party libraries. If you follow this rule, the default value of
4862 @code{@var{prog}_DEPENDENCIES} will list all your local libraries and
4863 omit the other ones.
4866 @node Conditional Sources
4867 @subsection Conditional compilation of sources
4869 You can't put a configure substitution (e.g., @samp{@@FOO@@} or
4870 @samp{$(FOO)} where @code{FOO} is defined via @code{AC_SUBST}) into a
4871 @code{_SOURCES} variable. The reason for this is a bit hard to
4872 explain, but suffice to say that it simply won't work. Automake will
4873 give an error if you try to do this.
4875 Fortunately there are two other ways to achieve the same result. One is
4876 to use configure substitutions in @code{_LDADD} variables, the other is
4877 to use an Automake conditional.
4879 @subsubheading Conditional Compilation using @code{_LDADD} Substitutions
4881 @cindex @code{EXTRA_prog_SOURCES}, defined
4883 Automake must know all the source files that could possibly go into a
4884 program, even if not all the files are built in every circumstance. Any
4885 files that are only conditionally built should be listed in the
4886 appropriate @code{EXTRA_} variable. For instance, if
4887 @file{hello-linux.c} or @file{hello-generic.c} were conditionally included
4888 in @code{hello}, the @file{Makefile.am} would contain:
4891 bin_PROGRAMS = hello
4892 hello_SOURCES = hello-common.c
4893 EXTRA_hello_SOURCES = hello-linux.c hello-generic.c
4894 hello_LDADD = $(HELLO_SYSTEM)
4895 hello_DEPENDENCIES = $(HELLO_SYSTEM)
4899 You can then setup the @samp{$(HELLO_SYSTEM)} substitution from
4900 @file{configure.ac}:
4905 *linux*) HELLO_SYSTEM='hello-linux.$(OBJEXT)' ;;
4906 *) HELLO_SYSTEM='hello-generic.$(OBJEXT)' ;;
4908 AC_SUBST([HELLO_SYSTEM])
4912 In this case, the variable @code{HELLO_SYSTEM} should be replaced by
4913 either @file{hello-linux.o} or @file{hello-generic.o}, and added to
4914 both @code{hello_DEPENDENCIES} and @code{hello_LDADD} in order to be
4915 built and linked in.
4917 @subsubheading Conditional Compilation using Automake Conditionals
4919 An often simpler way to compile source files conditionally is to use
4920 Automake conditionals. For instance, you could use this
4921 @file{Makefile.am} construct to build the same @file{hello} example:
4924 bin_PROGRAMS = hello
4926 hello_SOURCES = hello-linux.c hello-common.c
4928 hello_SOURCES = hello-generic.c hello-common.c
4932 In this case, @file{configure.ac} should setup the @code{LINUX}
4933 conditional using @code{AM_CONDITIONAL} (@pxref{Conditionals}).
4935 When using conditionals like this you don't need to use the
4936 @code{EXTRA_} variable, because Automake will examine the contents of
4937 each variable to construct the complete list of source files.
4939 If your program uses a lot of files, you will probably prefer a
4940 conditional @samp{+=}.
4943 bin_PROGRAMS = hello
4944 hello_SOURCES = hello-common.c
4946 hello_SOURCES += hello-linux.c
4948 hello_SOURCES += hello-generic.c
4952 @node Conditional Programs
4953 @subsection Conditional compilation of programs
4954 @cindex Conditional programs
4955 @cindex Programs, conditional
4957 Sometimes it is useful to determine the programs that are to be built
4958 at configure time. For instance, GNU @code{cpio} only builds
4959 @code{mt} and @code{rmt} under special circumstances. The means to
4960 achieve conditional compilation of programs are the same you can use
4961 to compile source files conditionally: substitutions or conditionals.
4963 @subsubheading Conditional Programs using @command{configure} Substitutions
4965 @vindex EXTRA_PROGRAMS
4966 @cindex @code{EXTRA_PROGRAMS}, defined
4967 In this case, you must notify Automake of all the programs that can
4968 possibly be built, but at the same time cause the generated
4969 @file{Makefile.in} to use the programs specified by @command{configure}.
4970 This is done by having @command{configure} substitute values into each
4971 @code{_PROGRAMS} definition, while listing all optionally built programs
4972 in @code{EXTRA_PROGRAMS}.
4975 bin_PROGRAMS = cpio pax $(MT)
4976 libexec_PROGRAMS = $(RMT)
4977 EXTRA_PROGRAMS = mt rmt
4980 As explained in @ref{EXEEXT}, Automake will rewrite
4981 @code{bin_PROGRAMS}, @code{libexec_PROGRAMS}, and
4982 @code{EXTRA_PROGRAMS}, appending @samp{$(EXEEXT)} to each binary.
4983 Obviously it cannot rewrite values obtained at run-time through
4984 @command{configure} substitutions, therefore you should take care of
4985 appending @samp{$(EXEEXT)} yourself, as in @samp{AC_SUBST([MT],
4986 ['mt$@{EXEEXT@}'])}.
4988 @subsubheading Conditional Programs using Automake Conditionals
4990 You can also use Automake conditionals (@pxref{Conditionals}) to
4991 select programs to be built. In this case you don't have to worry
4992 about @samp{$(EXEEXT)} or @code{EXTRA_PROGRAMS}.
4994 @c Keep in sync with exeext.sh
4996 bin_PROGRAMS = cpio pax
5001 libexec_PROGRAMS = rmt
5007 @section Building a library
5009 @cindex @code{_LIBRARIES} primary, defined
5010 @cindex @code{LIBRARIES} primary, defined
5011 @cindex Primary variable, @code{LIBRARIES}
5014 @vindex lib_LIBRARIES
5015 @vindex pkglib_LIBRARIES
5016 @vindex noinst_LIBRARIES
5018 Building a library is much like building a program. In this case, the
5019 name of the primary is @code{LIBRARIES}. Libraries can be installed in
5020 @code{libdir} or @code{pkglibdir}.
5022 @xref{A Shared Library}, for information on how to build shared
5023 libraries using libtool and the @code{LTLIBRARIES} primary.
5025 Each @code{_LIBRARIES} variable is a list of the libraries to be built.
5026 For instance, to create a library named @file{libcpio.a}, but not install
5027 it, you would write:
5030 noinst_LIBRARIES = libcpio.a
5031 libcpio_a_SOURCES = @dots{}
5034 The sources that go into a library are determined exactly as they are
5035 for programs, via the @code{_SOURCES} variables. Note that the library
5036 name is canonicalized (@pxref{Canonicalization}), so the @code{_SOURCES}
5037 variable corresponding to @file{libcpio.a} is @samp{libcpio_a_SOURCES},
5038 not @samp{libcpio.a_SOURCES}.
5040 @vindex maude_LIBADD
5041 Extra objects can be added to a library using the
5042 @code{@var{library}_LIBADD} variable. This should be used for objects
5043 determined by @command{configure}. Again from @code{cpio}:
5045 @c Keep in sync with pr401c.sh
5047 libcpio_a_LIBADD = $(LIBOBJS) $(ALLOCA)
5050 In addition, sources for extra objects that will not exist until
5051 configure-time must be added to the @code{BUILT_SOURCES} variable
5054 Building a static library is done by compiling all object files, then
5055 by invoking @samp{$(AR) $(ARFLAGS)} followed by the name of the
5056 library and the list of objects, and finally by calling
5057 @samp{$(RANLIB)} on that library. You should call
5058 @code{AC_PROG_RANLIB} from your @file{configure.ac} to define
5059 @code{RANLIB} (Automake will complain otherwise). You should also
5060 call @code{AM_PROG_AR} to define @code{AR}, in order to support unusual
5061 archivers such as Microsoft lib. @code{ARFLAGS} will default to
5062 @code{cru}; you can override this variable by setting it in your
5063 @file{Makefile.am} or by @code{AC_SUBST}ing it from your
5064 @file{configure.ac}. You can override the @code{AR} variable by
5065 defining a per-library @code{maude_AR} variable (@pxref{Program and
5066 Library Variables}).
5068 @cindex Empty libraries
5069 Be careful when selecting library components conditionally. Because
5070 building an empty library is not portable, you should ensure that any
5071 library always contains at least one object.
5073 To use a static library when building a program, add it to
5074 @code{LDADD} for this program. In the following example, the program
5075 @file{cpio} is statically linked with the library @file{libcpio.a}.
5078 noinst_LIBRARIES = libcpio.a
5079 libcpio_a_SOURCES = @dots{}
5082 cpio_SOURCES = cpio.c @dots{}
5083 cpio_LDADD = libcpio.a
5087 @node A Shared Library
5088 @section Building a Shared Library
5090 @cindex Shared libraries, support for
5092 Building shared libraries portably is a relatively complex matter.
5093 For this reason, GNU Libtool (@pxref{Top, , Introduction, libtool, The
5094 Libtool Manual}) was created to help build shared libraries in a
5095 platform-independent way.
5098 * Libtool Concept:: Introducing Libtool
5099 * Libtool Libraries:: Declaring Libtool Libraries
5100 * Conditional Libtool Libraries:: Building Libtool Libraries Conditionally
5101 * Conditional Libtool Sources:: Choosing Library Sources Conditionally
5102 * Libtool Convenience Libraries:: Building Convenience Libtool Libraries
5103 * Libtool Modules:: Building Libtool Modules
5104 * Libtool Flags:: Using _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS
5105 * LTLIBOBJS:: Using $(LTLIBOBJS) and $(LTALLOCA)
5106 * Libtool Issues:: Common Issues Related to Libtool's Use
5109 @node Libtool Concept
5110 @subsection The Libtool Concept
5112 @cindex @command{libtool}, introduction
5113 @cindex libtool library, definition
5114 @cindex suffix @file{.la}, defined
5115 @cindex @file{.la} suffix, defined
5117 Libtool abstracts shared and static libraries into a unified concept
5118 henceforth called @dfn{libtool libraries}. Libtool libraries are
5119 files using the @file{.la} suffix, and can designate a static library,
5120 a shared library, or maybe both. Their exact nature cannot be
5121 determined until @file{./configure} is run: not all platforms support
5122 all kinds of libraries, and users can explicitly select which
5123 libraries should be built. (However the package's maintainers can
5124 tune the default, @pxref{AC_PROG_LIBTOOL, , The @code{AC_PROG_LIBTOOL}
5125 macro, libtool, The Libtool Manual}.)
5127 @cindex suffix @file{.lo}, defined
5128 Because object files for shared and static libraries must be compiled
5129 differently, libtool is also used during compilation. Object files
5130 built by libtool are called @dfn{libtool objects}: these are files
5131 using the @file{.lo} suffix. Libtool libraries are built from these
5134 You should not assume anything about the structure of @file{.la} or
5135 @file{.lo} files and how libtool constructs them: this is libtool's
5136 concern, and the last thing one wants is to learn about libtool's
5137 guts. However the existence of these files matters, because they are
5138 used as targets and dependencies in @file{Makefile}s rules when
5139 building libtool libraries. There are situations where you may have
5140 to refer to these, for instance when expressing dependencies for
5141 building source files conditionally (@pxref{Conditional Libtool
5144 @cindex @file{libltdl}, introduction
5146 People considering writing a plug-in system, with dynamically loaded
5147 modules, should look into @file{libltdl}: libtool's dlopening library
5148 (@pxref{Using libltdl, , Using libltdl, libtool, The Libtool Manual}).
5149 This offers a portable dlopening facility to load libtool libraries
5150 dynamically, and can also achieve static linking where unavoidable.
5152 Before we discuss how to use libtool with Automake in details, it
5153 should be noted that the libtool manual also has a section about how
5154 to use Automake with libtool (@pxref{Using Automake, , Using Automake
5155 with Libtool, libtool, The Libtool Manual}).
5157 @node Libtool Libraries
5158 @subsection Building Libtool Libraries
5160 @cindex @code{_LTLIBRARIES} primary, defined
5161 @cindex @code{LTLIBRARIES} primary, defined
5162 @cindex Primary variable, @code{LTLIBRARIES}
5163 @cindex Example of shared libraries
5164 @vindex lib_LTLIBRARIES
5165 @vindex pkglib_LTLIBRARIES
5166 @vindex _LTLIBRARIES
5168 Automake uses libtool to build libraries declared with the
5169 @code{LTLIBRARIES} primary. Each @code{_LTLIBRARIES} variable is a
5170 list of libtool libraries to build. For instance, to create a libtool
5171 library named @file{libgettext.la}, and install it in @code{libdir},
5175 lib_LTLIBRARIES = libgettext.la
5176 libgettext_la_SOURCES = gettext.c gettext.h @dots{}
5179 Automake predefines the variable @code{pkglibdir}, so you can use
5180 @code{pkglib_LTLIBRARIES} to install libraries in
5181 @samp{$(libdir)/@@PACKAGE@@/}.
5183 If @file{gettext.h} is a public header file that needs to be installed
5184 in order for people to use the library, it should be declared using a
5185 @code{_HEADERS} variable, not in @code{libgettext_la_SOURCES}.
5186 Headers listed in the latter should be internal headers that are not
5187 part of the public interface.
5190 lib_LTLIBRARIES = libgettext.la
5191 libgettext_la_SOURCES = gettext.c @dots{}
5192 include_HEADERS = gettext.h @dots{}
5195 A package can build and install such a library along with other
5196 programs that use it. This dependency should be specified using
5197 @code{LDADD}. The following example builds a program named
5198 @file{hello} that is linked with @file{libgettext.la}.
5201 lib_LTLIBRARIES = libgettext.la
5202 libgettext_la_SOURCES = gettext.c @dots{}
5204 bin_PROGRAMS = hello
5205 hello_SOURCES = hello.c @dots{}
5206 hello_LDADD = libgettext.la
5210 Whether @file{hello} is statically or dynamically linked with
5211 @file{libgettext.la} is not yet known: this will depend on the
5212 configuration of libtool and the capabilities of the host.
5215 @node Conditional Libtool Libraries
5216 @subsection Building Libtool Libraries Conditionally
5217 @cindex libtool libraries, conditional
5218 @cindex conditional libtool libraries
5220 Like conditional programs (@pxref{Conditional Programs}), there are
5221 two main ways to build conditional libraries: using Automake
5222 conditionals or using Autoconf @code{AC_SUBST}itutions.
5224 The important implementation detail you have to be aware of is that
5225 the place where a library will be installed matters to libtool: it
5226 needs to be indicated @emph{at link-time} using the @option{-rpath}
5229 For libraries whose destination directory is known when Automake runs,
5230 Automake will automatically supply the appropriate @option{-rpath}
5231 option to libtool. This is the case for libraries listed explicitly in
5232 some installable @code{_LTLIBRARIES} variables such as
5233 @code{lib_LTLIBRARIES}.
5235 However, for libraries determined at configure time (and thus
5236 mentioned in @code{EXTRA_LTLIBRARIES}), Automake does not know the
5237 final installation directory. For such libraries you must add the
5238 @option{-rpath} option to the appropriate @code{_LDFLAGS} variable by
5241 The examples below illustrate the differences between these two methods.
5243 Here is an example where @code{WANTEDLIBS} is an @code{AC_SUBST}ed
5244 variable set at @file{./configure}-time to either @file{libfoo.la},
5245 @file{libbar.la}, both, or none. Although @samp{$(WANTEDLIBS)}
5246 appears in the @code{lib_LTLIBRARIES}, Automake cannot guess it
5247 relates to @file{libfoo.la} or @file{libbar.la} at the time it creates
5248 the link rule for these two libraries. Therefore the @option{-rpath}
5249 argument must be explicitly supplied.
5251 @c Keep in sync with ltcond.sh
5253 EXTRA_LTLIBRARIES = libfoo.la libbar.la
5254 lib_LTLIBRARIES = $(WANTEDLIBS)
5255 libfoo_la_SOURCES = foo.c @dots{}
5256 libfoo_la_LDFLAGS = -rpath '$(libdir)'
5257 libbar_la_SOURCES = bar.c @dots{}
5258 libbar_la_LDFLAGS = -rpath '$(libdir)'
5261 Here is how the same @file{Makefile.am} would look using Automake
5262 conditionals named @code{WANT_LIBFOO} and @code{WANT_LIBBAR}. Now
5263 Automake is able to compute the @option{-rpath} setting itself, because
5264 it's clear that both libraries will end up in @samp{$(libdir)} if they
5267 @c Keep in sync with ltcond.sh
5271 lib_LTLIBRARIES += libfoo.la
5274 lib_LTLIBRARIES += libbar.la
5276 libfoo_la_SOURCES = foo.c @dots{}
5277 libbar_la_SOURCES = bar.c @dots{}
5280 @node Conditional Libtool Sources
5281 @subsection Libtool Libraries with Conditional Sources
5283 Conditional compilation of sources in a library can be achieved in the
5284 same way as conditional compilation of sources in a program
5285 (@pxref{Conditional Sources}). The only difference is that
5286 @code{_LIBADD} should be used instead of @code{_LDADD} and that it
5287 should mention libtool objects (@file{.lo} files).
5289 So, to mimic the @file{hello} example from @ref{Conditional Sources},
5290 we could build a @file{libhello.la} library using either
5291 @file{hello-linux.c} or @file{hello-generic.c} with the following
5294 @c Keep in sync with ltcond2.sh
5296 lib_LTLIBRARIES = libhello.la
5297 libhello_la_SOURCES = hello-common.c
5298 EXTRA_libhello_la_SOURCES = hello-linux.c hello-generic.c
5299 libhello_la_LIBADD = $(HELLO_SYSTEM)
5300 libhello_la_DEPENDENCIES = $(HELLO_SYSTEM)
5304 And make sure @command{configure} defines @code{HELLO_SYSTEM} as
5305 either @file{hello-linux.lo} or @file{hello-@-generic.lo}.
5307 Or we could simply use an Automake conditional as follows.
5309 @c Keep in sync with ltcond2.sh
5311 lib_LTLIBRARIES = libhello.la
5312 libhello_la_SOURCES = hello-common.c
5314 libhello_la_SOURCES += hello-linux.c
5316 libhello_la_SOURCES += hello-generic.c
5320 @node Libtool Convenience Libraries
5321 @subsection Libtool Convenience Libraries
5322 @cindex convenience libraries, libtool
5323 @cindex libtool convenience libraries
5324 @vindex noinst_LTLIBRARIES
5325 @vindex check_LTLIBRARIES
5327 Sometimes you want to build libtool libraries that should not be
5328 installed. These are called @dfn{libtool convenience libraries} and
5329 are typically used to encapsulate many sublibraries, later gathered
5330 into one big installed library.
5332 Libtool convenience libraries are declared by directory-less variables
5333 such as @code{noinst_LTLIBRARIES}, @code{check_LTLIBRARIES}, or even
5334 @code{EXTRA_LTLIBRARIES}. Unlike installed libtool libraries they do
5335 not need an @option{-rpath} flag at link time (actually this is the only
5338 Convenience libraries listed in @code{noinst_LTLIBRARIES} are always
5339 built. Those listed in @code{check_LTLIBRARIES} are built only upon
5340 @samp{make check}. Finally, libraries listed in
5341 @code{EXTRA_LTLIBRARIES} are never built explicitly: Automake outputs
5342 rules to build them, but if the library does not appear as a Makefile
5343 dependency anywhere it won't be built (this is why
5344 @code{EXTRA_LTLIBRARIES} is used for conditional compilation).
5346 Here is a sample setup merging libtool convenience libraries from
5347 subdirectories into one main @file{libtop.la} library.
5349 @c Keep in sync with ltconv.sh
5351 # -- Top-level Makefile.am --
5352 SUBDIRS = sub1 sub2 @dots{}
5353 lib_LTLIBRARIES = libtop.la
5355 libtop_la_LIBADD = \
5360 # -- sub1/Makefile.am --
5361 noinst_LTLIBRARIES = libsub1.la
5362 libsub1_la_SOURCES = @dots{}
5364 # -- sub2/Makefile.am --
5365 # showing nested convenience libraries
5366 SUBDIRS = sub2.1 sub2.2 @dots{}
5367 noinst_LTLIBRARIES = libsub2.la
5368 libsub2_la_SOURCES =
5369 libsub2_la_LIBADD = \
5375 When using such setup, beware that @command{automake} will assume
5376 @file{libtop.la} is to be linked with the C linker. This is because
5377 @code{libtop_la_SOURCES} is empty, so @command{automake} picks C as
5378 default language. If @code{libtop_la_SOURCES} was not empty,
5379 @command{automake} would select the linker as explained in @ref{How
5380 the Linker is Chosen}.
5382 If one of the sublibraries contains non-C source, it is important that
5383 the appropriate linker be chosen. One way to achieve this is to
5384 pretend that there is such a non-C file among the sources of the
5385 library, thus forcing @command{automake} to select the appropriate
5386 linker. Here is the top-level @file{Makefile} of our example updated
5387 to force C++ linking.
5390 SUBDIRS = sub1 sub2 @dots{}
5391 lib_LTLIBRARIES = libtop.la
5393 # Dummy C++ source to cause C++ linking.
5394 nodist_EXTRA_libtop_la_SOURCES = dummy.cxx
5395 libtop_la_LIBADD = \
5401 @samp{EXTRA_*_SOURCES} variables are used to keep track of source
5402 files that might be compiled (this is mostly useful when doing
5403 conditional compilation using @code{AC_SUBST}, @pxref{Conditional
5404 Libtool Sources}), and the @code{nodist_} prefix means the listed
5405 sources are not to be distributed (@pxref{Program and Library
5406 Variables}). In effect the file @file{dummy.cxx} does not need to
5407 exist in the source tree. Of course if you have some real source file
5408 to list in @code{libtop_la_SOURCES} there is no point in cheating with
5409 @code{nodist_EXTRA_libtop_la_SOURCES}.
5412 @node Libtool Modules
5413 @subsection Libtool Modules
5414 @cindex modules, libtool
5415 @cindex libtool modules
5416 @cindex @option{-module}, libtool
5418 These are libtool libraries meant to be dlopened. They are
5419 indicated to libtool by passing @option{-module} at link-time.
5422 pkglib_LTLIBRARIES = mymodule.la
5423 mymodule_la_SOURCES = doit.c
5424 mymodule_la_LDFLAGS = -module
5427 Ordinarily, Automake requires that a library's name start with
5428 @code{lib}. However, when building a dynamically loadable module you
5429 might wish to use a "nonstandard" name. Automake will not complain
5430 about such nonstandard names if it knows the library being built is a
5431 libtool module, i.e., if @option{-module} explicitly appears in the
5432 library's @code{_LDFLAGS} variable (or in the common @code{AM_LDFLAGS}
5433 variable when no per-library @code{_LDFLAGS} variable is defined).
5435 As always, @code{AC_SUBST} variables are black boxes to Automake since
5436 their values are not yet known when @command{automake} is run.
5437 Therefore if @option{-module} is set via such a variable, Automake
5438 cannot notice it and will proceed as if the library was an ordinary
5439 libtool library, with strict naming.
5441 If @code{mymodule_la_SOURCES} is not specified, then it defaults to
5442 the single file @file{mymodule.c} (@pxref{Default _SOURCES}).
5445 @subsection @code{_LIBADD}, @code{_LDFLAGS}, and @code{_LIBTOOLFLAGS}
5446 @cindex @code{_LIBADD}, libtool
5447 @cindex @code{_LDFLAGS}, libtool
5448 @cindex @code{_LIBTOOLFLAGS}, libtool
5449 @vindex AM_LIBTOOLFLAGS
5450 @vindex LIBTOOLFLAGS
5451 @vindex maude_LIBTOOLFLAGS
5453 As shown in previous sections, the @samp{@var{library}_LIBADD}
5454 variable should be used to list extra libtool objects (@file{.lo}
5455 files) or libtool libraries (@file{.la}) to add to @var{library}.
5457 The @samp{@var{library}_LDFLAGS} variable is the place to list
5458 additional libtool linking flags, such as @option{-version-info},
5459 @option{-static}, and a lot more. @xref{Link mode, , Link mode,
5460 libtool, The Libtool Manual}.
5462 The @command{libtool} command has two kinds of options: mode-specific
5463 options and generic options. Mode-specific options such as the
5464 aforementioned linking flags should be lumped with the other flags
5465 passed to the tool invoked by @command{libtool} (hence the use of
5466 @samp{@var{library}_LDFLAGS} for libtool linking flags). Generic
5467 options include @option{--tag=@var{tag}} and @option{--silent}
5468 (@pxref{Invoking libtool, , Invoking @command{libtool}, libtool, The
5469 Libtool Manual} for more options) should appear before the mode
5470 selection on the command line; in @file{Makefile.am}s they should
5471 be listed in the @samp{@var{library}_LIBTOOLFLAGS} variable.
5473 If @samp{@var{library}_LIBTOOLFLAGS} is not defined, then the variable
5474 @code{AM_LIBTOOLFLAGS} is used instead.
5476 These flags are passed to libtool after the @option{--tag=@var{tag}}
5477 option computed by Automake (if any), so
5478 @samp{@var{library}_LIBTOOLFLAGS} (or @code{AM_LIBTOOLFLAGS}) is a
5479 good place to override or supplement the @option{--tag=@var{tag}}
5482 The libtool rules also use a @code{LIBTOOLFLAGS} variable that should
5483 not be set in @file{Makefile.am}: this is a user variable (@pxref{Flag
5484 Variables Ordering}. It allows users to run @samp{make
5485 LIBTOOLFLAGS=--silent}, for instance. Note that the verbosity of
5486 @command{libtool} can also be influenced by the Automake support
5487 for silent rules (@pxref{Automake Silent Rules}).
5489 @node LTLIBOBJS, Libtool Issues, Libtool Flags, A Shared Library
5490 @subsection @code{LTLIBOBJS} and @code{LTALLOCA}
5491 @cindex @code{LTLIBOBJS}, special handling
5492 @cindex @code{LIBOBJS}, and Libtool
5493 @cindex @code{LTALLOCA}, special handling
5494 @cindex @code{ALLOCA}, and Libtool
5501 Where an ordinary library might include @samp{$(LIBOBJS)} or
5502 @samp{$(ALLOCA)} (@pxref{LIBOBJS}), a libtool library must use
5503 @samp{$(LTLIBOBJS)} or @samp{$(LTALLOCA)}. This is required because
5504 the object files that libtool operates on do not necessarily end in
5507 Nowadays, the computation of @code{LTLIBOBJS} from @code{LIBOBJS} is
5508 performed automatically by Autoconf (@pxref{AC_LIBOBJ vs LIBOBJS, ,
5509 @code{AC_LIBOBJ} vs.@: @code{LIBOBJS}, autoconf, The Autoconf Manual}).
5511 @node Libtool Issues
5512 @subsection Common Issues Related to Libtool's Use
5515 * Error required file ltmain.sh not found:: The need to run libtoolize
5516 * Objects created both with libtool and without:: Avoid a specific build race
5519 @node Error required file ltmain.sh not found
5520 @subsubsection Error: @samp{required file `./ltmain.sh' not found}
5521 @cindex @file{ltmain.sh} not found
5522 @cindex @command{libtoolize}, no longer run by @command{automake}
5523 @cindex @command{libtoolize} and @command{autoreconf}
5524 @cindex @command{autoreconf} and @command{libtoolize}
5525 @cindex @file{bootstrap.sh} and @command{autoreconf}
5526 @cindex @file{autogen.sh} and @command{autoreconf}
5528 Libtool comes with a tool called @command{libtoolize} that will
5529 install libtool's supporting files into a package. Running this
5530 command will install @file{ltmain.sh}. You should execute it before
5531 @command{aclocal} and @command{automake}.
5533 People upgrading old packages to newer autotools are likely to face
5534 this issue because older Automake versions used to call
5535 @command{libtoolize}. Therefore old build scripts do not call
5536 @command{libtoolize}.
5538 Since Automake 1.6, it has been decided that running
5539 @command{libtoolize} was none of Automake's business. Instead, that
5540 functionality has been moved into the @command{autoreconf} command
5541 (@pxref{autoreconf Invocation, , Using @command{autoreconf}, autoconf,
5542 The Autoconf Manual}). If you do not want to remember what to run and
5543 when, just learn the @command{autoreconf} command. Hopefully,
5544 replacing existing @file{bootstrap.sh} or @file{autogen.sh} scripts by
5545 a call to @command{autoreconf} should also free you from any similar
5546 incompatible change in the future.
5548 @node Objects created both with libtool and without
5549 @subsubsection Objects @samp{created with both libtool and without}
5551 Sometimes, the same source file is used both to build a libtool
5552 library and to build another non-libtool target (be it a program or
5555 Let's consider the following @file{Makefile.am}.
5559 prog_SOURCES = prog.c foo.c @dots{}
5561 lib_LTLIBRARIES = libfoo.la
5562 libfoo_la_SOURCES = foo.c @dots{}
5566 (In this trivial case the issue could be avoided by linking
5567 @file{libfoo.la} with @file{prog} instead of listing @file{foo.c} in
5568 @code{prog_SOURCES}. But let's assume we really want to keep
5569 @file{prog} and @file{libfoo.la} separate.)
5571 Technically, it means that we should build @file{foo.$(OBJEXT)} for
5572 @file{prog}, and @file{foo.lo} for @file{libfoo.la}. The problem is
5573 that in the course of creating @file{foo.lo}, libtool may erase (or
5574 replace) @file{foo.$(OBJEXT)}, and this cannot be avoided.
5576 Therefore, when Automake detects this situation it will complain
5577 with a message such as
5579 object 'foo.$(OBJEXT)' created both with libtool and without
5582 A workaround for this issue is to ensure that these two objects get
5583 different basenames. As explained in @ref{Renamed Objects}, this
5584 happens automatically when per-targets flags are used.
5588 prog_SOURCES = prog.c foo.c @dots{}
5589 prog_CFLAGS = $(AM_CFLAGS)
5591 lib_LTLIBRARIES = libfoo.la
5592 libfoo_la_SOURCES = foo.c @dots{}
5596 Adding @samp{prog_CFLAGS = $(AM_CFLAGS)} is almost a no-op, because
5597 when the @code{prog_CFLAGS} is defined, it is used instead of
5598 @code{AM_CFLAGS}. However as a side effect it will cause
5599 @file{prog.c} and @file{foo.c} to be compiled as
5600 @file{prog-prog.$(OBJEXT)} and @file{prog-foo.$(OBJEXT)}, which solves
5603 @node Program and Library Variables
5604 @section Program and Library Variables
5606 Associated with each program is a collection of variables that can be
5607 used to modify how that program is built. There is a similar list of
5608 such variables for each library. The canonical name of the program (or
5609 library) is used as a base for naming these variables.
5611 In the list below, we use the name ``maude'' to refer to the program or
5612 library. In your @file{Makefile.am} you would replace this with the
5613 canonical name of your program. This list also refers to ``maude'' as a
5614 program, but in general the same rules apply for both static and dynamic
5615 libraries; the documentation below notes situations where programs and
5620 This variable, if it exists, lists all the source files that are
5621 compiled to build the program. These files are added to the
5622 distribution by default. When building the program, Automake will cause
5623 each source file to be compiled to a single @file{.o} file (or
5624 @file{.lo} when using libtool). Normally these object files are named
5625 after the source file, but other factors can change this. If a file in
5626 the @code{_SOURCES} variable has an unrecognized extension, Automake
5627 will do one of two things with it. If a suffix rule exists for turning
5628 files with the unrecognized extension into @file{.o} files, then
5629 @command{automake} will treat this file as it will any other source file
5630 (@pxref{Support for Other Languages}). Otherwise, the file will be
5631 ignored as though it were a header file.
5633 The prefixes @code{dist_} and @code{nodist_} can be used to control
5634 whether files listed in a @code{_SOURCES} variable are distributed.
5635 @code{dist_} is redundant, as sources are distributed by default, but it
5636 can be specified for clarity if desired.
5638 It is possible to have both @code{dist_} and @code{nodist_} variants of
5639 a given @code{_SOURCES} variable at once; this lets you easily
5640 distribute some files and not others, for instance:
5643 nodist_maude_SOURCES = nodist.c
5644 dist_maude_SOURCES = dist-me.c
5647 By default the output file (on Unix systems, the @file{.o} file) will
5648 be put into the current build directory. However, if the option
5649 @option{subdir-objects} is in effect in the current directory then the
5650 @file{.o} file will be put into the subdirectory named after the
5651 source file. For instance, with @option{subdir-objects} enabled,
5652 @file{sub/dir/file.c} will be compiled to @file{sub/dir/file.o}. Some
5653 people prefer this mode of operation. You can specify
5654 @option{subdir-objects} in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
5655 @cindex Subdirectory, objects in
5656 @cindex Objects in subdirectory
5659 @item EXTRA_maude_SOURCES
5660 Automake needs to know the list of files you intend to compile
5661 @emph{statically}. For one thing, this is the only way Automake has of
5662 knowing what sort of language support a given @file{Makefile.in}
5663 requires. @footnote{There are other, more obscure reasons for
5664 this limitation as well.} This means that, for example, you can't put a
5665 configure substitution like @samp{@@my_sources@@} into a @samp{_SOURCES}
5666 variable. If you intend to conditionally compile source files and use
5667 @file{configure} to substitute the appropriate object names into, e.g.,
5668 @code{_LDADD} (see below), then you should list the corresponding source
5669 files in the @code{EXTRA_} variable.
5671 This variable also supports @code{dist_} and @code{nodist_} prefixes.
5672 For instance, @code{nodist_EXTRA_maude_SOURCES} would list extra
5673 sources that may need to be built, but should not be distributed.
5676 A static library is created by default by invoking @samp{$(AR)
5677 $(ARFLAGS)} followed by the name of the library and then the objects
5678 being put into the library. You can override this by setting the
5679 @code{_AR} variable. This is usually used with C++; some C++
5680 compilers require a special invocation in order to instantiate all the
5681 templates that should go into a library. For instance, the SGI C++
5682 compiler likes this variable set like so:
5684 libmaude_a_AR = $(CXX) -ar -o
5688 Extra objects can be added to a @emph{library} using the @code{_LIBADD}
5689 variable. For instance, this should be used for objects determined by
5690 @command{configure} (@pxref{A Library}).
5692 In the case of libtool libraries, @code{maude_LIBADD} can also refer
5693 to other libtool libraries.
5696 Extra objects (@file{*.$(OBJEXT)}) and libraries (@file{*.a},
5697 @file{*.la}) can be added to a @emph{program} by listing them in the
5698 @code{_LDADD} variable. For instance, this should be used for objects
5699 determined by @command{configure} (@pxref{Linking}).
5701 @code{_LDADD} and @code{_LIBADD} are inappropriate for passing
5702 program-specific linker flags (except for @option{-l}, @option{-L},
5703 @option{-dlopen} and @option{-dlpreopen}). Use the @code{_LDFLAGS} variable
5706 For instance, if your @file{configure.ac} uses @code{AC_PATH_XTRA}, you
5707 could link your program against the X libraries like so:
5710 maude_LDADD = $(X_PRE_LIBS) $(X_LIBS) $(X_EXTRA_LIBS)
5713 We recommend that you use @option{-l} and @option{-L} only when
5714 referring to third-party libraries, and give the explicit file names
5715 of any library built by your package. Doing so will ensure that
5716 @code{maude_DEPENDENCIES} (see below) is correctly defined by default.
5719 This variable is used to pass extra flags to the link step of a program
5720 or a shared library. It overrides the @code{AM_LDFLAGS} variable.
5722 @item maude_LIBTOOLFLAGS
5723 This variable is used to pass extra options to @command{libtool}.
5724 It overrides the @code{AM_LIBTOOLFLAGS} variable.
5725 These options are output before @command{libtool}'s @option{--mode=@var{mode}}
5726 option, so they should not be mode-specific options (those belong to
5727 the compiler or linker flags). @xref{Libtool Flags}.
5729 @item maude_DEPENDENCIES
5730 @itemx EXTRA_maude_DEPENDENCIES
5731 It is also occasionally useful to have a target (program or library)
5732 depend on some other file that is not actually part of that target.
5733 This can be done using the @code{_DEPENDENCIES} variable. Each
5734 target depends on the contents of such a variable, but no further
5735 interpretation is done.
5737 Since these dependencies are associated to the link rule used to
5738 create the programs they should normally list files used by the link
5739 command. That is @file{*.$(OBJEXT)}, @file{*.a}, or @file{*.la} files
5740 for programs; @file{*.lo} and @file{*.la} files for Libtool libraries;
5741 and @file{*.$(OBJEXT)} files for static libraries. In rare cases you
5742 may need to add other kinds of files such as linker scripts, but
5743 @emph{listing a source file in @code{_DEPENDENCIES} is wrong}. If
5744 some source file needs to be built before all the components of a
5745 program are built, consider using the @code{BUILT_SOURCES} variable
5748 If @code{_DEPENDENCIES} is not supplied, it is computed by Automake.
5749 The automatically-assigned value is the contents of @code{_LDADD} or
5750 @code{_LIBADD}, with most configure substitutions, @option{-l}, @option{-L},
5751 @option{-dlopen} and @option{-dlpreopen} options removed. The configure
5752 substitutions that are left in are only @samp{$(LIBOBJS)} and
5753 @samp{$(ALLOCA)}; these are left because it is known that they will not
5754 cause an invalid value for @code{_DEPENDENCIES} to be generated.
5756 @code{_DEPENDENCIES} is more likely used to perform conditional
5757 compilation using an @code{AC_SUBST} variable that contains a list of
5758 objects. @xref{Conditional Sources}, and @ref{Conditional Libtool
5761 The @code{EXTRA_*_DEPENDENCIES} variable may be useful for cases where
5762 you merely want to augment the @command{automake}-generated
5763 @code{_DEPENDENCIES} variable rather than replacing it.
5766 You can override the linker on a per-program basis. By default the
5767 linker is chosen according to the languages used by the program. For
5768 instance, a program that includes C++ source code would use the C++
5769 compiler to link. The @code{_LINK} variable must hold the name of a
5770 command that can be passed all the @file{.o} file names and libraries
5771 to link against as arguments. Note that the name of the underlying
5772 program is @emph{not} passed to @code{_LINK}; typically one uses
5776 maude_LINK = $(CCLD) -magic -o $@@
5779 If a @code{_LINK} variable is not supplied, it may still be generated
5780 and used by Automake due to the use of per-target link flags such as
5781 @code{_CFLAGS}, @code{_LDFLAGS} or @code{_LIBTOOLFLAGS}, in cases where
5784 @item maude_CCASFLAGS
5786 @itemx maude_CPPFLAGS
5787 @itemx maude_CXXFLAGS
5789 @itemx maude_GCJFLAGS
5791 @itemx maude_OBJCFLAGS
5792 @itemx maude_OBJCXXFLAGS
5794 @itemx maude_UPCFLAGS
5796 @cindex per-target compilation flags, defined
5797 Automake allows you to set compilation flags on a per-program (or
5798 per-library) basis. A single source file can be included in several
5799 programs, and it will potentially be compiled with different flags for
5800 each program. This works for any language directly supported by
5801 Automake. These @dfn{per-target compilation flags} are
5810 @samp{_OBJCXXFLAGS},
5812 @samp{_UPCFLAGS}, and
5815 When using a per-target compilation flag, Automake will choose a
5816 different name for the intermediate object files. Ordinarily a file
5817 like @file{sample.c} will be compiled to produce @file{sample.o}.
5818 However, if the program's @code{_CFLAGS} variable is set, then the
5819 object file will be named, for instance, @file{maude-sample.o}. (See
5820 also @ref{Renamed Objects}).
5822 In compilations with per-target flags, the ordinary @samp{AM_} form of
5823 the flags variable is @emph{not} automatically included in the
5824 compilation (however, the user form of the variable @emph{is} included).
5825 So for instance, if you want the hypothetical @file{maude} compilations
5826 to also use the value of @code{AM_CFLAGS}, you would need to write:
5829 maude_CFLAGS = @dots{} your flags @dots{} $(AM_CFLAGS)
5832 @xref{Flag Variables Ordering}, for more discussion about the
5833 interaction between user variables, @samp{AM_} shadow variables, and
5834 per-target variables.
5836 @item maude_SHORTNAME
5837 On some platforms the allowable file names are very short. In order to
5838 support these systems and per-target compilation flags at the same
5839 time, Automake allows you to set a ``short name'' that will influence
5840 how intermediate object files are named. For instance, in the following
5844 bin_PROGRAMS = maude
5845 maude_CPPFLAGS = -DSOMEFLAG
5847 maude_SOURCES = sample.c @dots{}
5851 the object file would be named @file{m-sample.o} rather than
5852 @file{maude-sample.o}.
5854 This facility is rarely needed in practice,
5855 and we recommend avoiding it until you find it is required.
5858 @node Default _SOURCES
5859 @section Default @code{_SOURCES}
5863 @cindex @code{_SOURCES}, default
5864 @cindex default @code{_SOURCES}
5865 @vindex AM_DEFAULT_SOURCE_EXT
5867 @code{_SOURCES} variables are used to specify source files of programs
5868 (@pxref{A Program}), libraries (@pxref{A Library}), and Libtool
5869 libraries (@pxref{A Shared Library}).
5871 When no such variable is specified for a target, Automake will define
5872 one itself. The default is to compile a single C file whose base name
5873 is the name of the target itself, with any extension replaced by
5874 @code{AM_DEFAULT_SOURCE_EXT}, which defaults to @file{.c}.
5876 For example if you have the following somewhere in your
5877 @file{Makefile.am} with no corresponding @code{libfoo_a_SOURCES}:
5880 lib_LIBRARIES = libfoo.a sub/libc++.a
5884 @file{libfoo.a} will be built using a default source file named
5885 @file{libfoo.c}, and @file{sub/libc++.a} will be built from
5886 @file{sub/libc++.c}. (In older versions @file{sub/libc++.a}
5887 would be built from @file{sub_libc___a.c}, i.e., the default source
5888 was the canonized name of the target, with @file{.c} appended.
5889 We believe the new behavior is more sensible, but for backward
5890 compatibility @command{automake} will use the old name if a file or a rule
5891 with that name exists and @code{AM_DEFAULT_SOURCE_EXT} is not used.)
5893 @cindex @code{check_PROGRAMS} example
5894 @vindex check_PROGRAMS
5895 Default sources are mainly useful in test suites, when building many
5896 test programs each from a single source. For instance, in
5899 check_PROGRAMS = test1 test2 test3
5900 AM_DEFAULT_SOURCE_EXT = .cpp
5904 @file{test1}, @file{test2}, and @file{test3} will be built
5905 from @file{test1.cpp}, @file{test2.cpp}, and @file{test3.cpp}.
5906 Without the last line, they will be built from @file{test1.c},
5907 @file{test2.c}, and @file{test3.c}.
5909 @cindex Libtool modules, default source example
5910 @cindex default source, Libtool modules example
5911 Another case where this is convenient is building many Libtool modules
5912 (@file{module@var{n}.la}), each defined in its own file
5913 (@file{module@var{n}.c}).
5916 AM_LDFLAGS = -module
5917 lib_LTLIBRARIES = module1.la module2.la module3.la
5920 @cindex empty @code{_SOURCES}
5921 @cindex @code{_SOURCES}, empty
5922 Finally, there is one situation where this default source computation
5923 needs to be avoided: when a target should not be built from sources.
5924 We already saw such an example in @ref{true}; this happens when all
5925 the constituents of a target have already been compiled and just need
5926 to be combined using a @code{_LDADD} variable. Then it is necessary
5927 to define an empty @code{_SOURCES} variable, so that @command{automake}
5928 does not compute a default.
5931 bin_PROGRAMS = target
5933 target_LDADD = libmain.a libmisc.a
5937 @section Special handling for @code{LIBOBJS} and @code{ALLOCA}
5939 @cindex @code{LIBOBJS}, example
5940 @cindex @code{ALLOCA}, example
5941 @cindex @code{LIBOBJS}, special handling
5942 @cindex @code{ALLOCA}, special handling
5948 The @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} variables list object
5949 files that should be compiled into the project to provide an
5950 implementation for functions that are missing or broken on the host
5951 system. They are substituted by @file{configure}.
5955 These variables are defined by Autoconf macros such as
5956 @code{AC_LIBOBJ}, @code{AC_REPLACE_FUNCS} (@pxref{Generic Functions, ,
5957 Generic Function Checks, autoconf, The Autoconf Manual}), or
5958 @code{AC_FUNC_ALLOCA} (@pxref{Particular Functions, , Particular
5959 Function Checks, autoconf, The Autoconf Manual}). Many other Autoconf
5960 macros call @code{AC_LIBOBJ} or @code{AC_REPLACE_FUNCS} to
5961 populate @samp{$(LIBOBJS)}.
5963 @acindex AC_LIBSOURCE
5965 Using these variables is very similar to doing conditional compilation
5966 using @code{AC_SUBST} variables, as described in @ref{Conditional
5967 Sources}. That is, when building a program, @samp{$(LIBOBJS)} and
5968 @samp{$(ALLOCA)} should be added to the associated @samp{*_LDADD}
5969 variable, or to the @samp{*_LIBADD} variable when building a library.
5970 However there is no need to list the corresponding sources in
5971 @samp{EXTRA_*_SOURCES} nor to define @samp{*_DEPENDENCIES}. Automake
5972 automatically adds @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} to the
5973 dependencies, and it will discover the list of corresponding source
5974 files automatically (by tracing the invocations of the
5975 @code{AC_LIBSOURCE} Autoconf macros). If you have already defined
5976 @samp{*_DEPENDENCIES} explicitly for an unrelated reason, then you
5977 either need to add these variables manually, or use
5978 @samp{EXTRA_*_DEPENDENCIES} instead of @samp{*_DEPENDENCIES}.
5980 These variables are usually used to build a portability library that
5981 is linked with all the programs of the project. We now review a
5982 sample setup. First, @file{configure.ac} contains some checks that
5983 affect either @code{LIBOBJS} or @code{ALLOCA}.
5988 AC_CONFIG_LIBOBJ_DIR([lib])
5990 AC_FUNC_MALLOC dnl May add malloc.$(OBJEXT) to LIBOBJS
5991 AC_FUNC_MEMCMP dnl May add memcmp.$(OBJEXT) to LIBOBJS
5992 AC_REPLACE_FUNCS([strdup]) dnl May add strdup.$(OBJEXT) to LIBOBJS
5993 AC_FUNC_ALLOCA dnl May add alloca.$(OBJEXT) to ALLOCA
6002 @acindex AC_CONFIG_LIBOBJ_DIR
6004 The @code{AC_CONFIG_LIBOBJ_DIR} tells Autoconf that the source files
6005 of these object files are to be found in the @file{lib/} directory.
6006 Automake can also use this information, otherwise it expects the
6007 source files are to be in the directory where the @samp{$(LIBOBJS)}
6008 and @samp{$(ALLOCA)} variables are used.
6010 The @file{lib/} directory should therefore contain @file{malloc.c},
6011 @file{memcmp.c}, @file{strdup.c}, @file{alloca.c}. Here is its
6017 noinst_LIBRARIES = libcompat.a
6018 libcompat_a_SOURCES =
6019 libcompat_a_LIBADD = $(LIBOBJS) $(ALLOCA)
6022 The library can have any name, of course, and anyway it is not going
6023 to be installed: it just holds the replacement versions of the missing
6024 or broken functions so we can later link them in. Many projects
6025 also include extra functions, specific to the project, in that
6026 library: they are simply added on the @code{_SOURCES} line.
6028 @cindex Empty libraries and @samp{$(LIBOBJS)}
6029 @cindex @samp{$(LIBOBJS)} and empty libraries
6030 There is a small trap here, though: @samp{$(LIBOBJS)} and
6031 @samp{$(ALLOCA)} might be empty, and building an empty library is not
6032 portable. You should ensure that there is always something to put in
6033 @file{libcompat.a}. Most projects will also add some utility
6034 functions in that directory, and list them in
6035 @code{libcompat_a_SOURCES}, so in practice @file{libcompat.a} cannot
6038 Finally here is how this library could be used from the @file{src/}
6044 # Link all programs in this directory with libcompat.a
6045 LDADD = ../lib/libcompat.a
6047 bin_PROGRAMS = tool1 tool2 @dots{}
6048 tool1_SOURCES = @dots{}
6049 tool2_SOURCES = @dots{}
6052 When option @option{subdir-objects} is not used, as in the above
6053 example, the variables @samp{$(LIBOBJS)} or @samp{$(ALLOCA)} can only
6054 be used in the directory where their sources lie. E.g., here it would
6055 be wrong to use @samp{$(LIBOBJS)} or @samp{$(ALLOCA)} in
6056 @file{src/Makefile.am}. However if both @option{subdir-objects} and
6057 @code{AC_CONFIG_LIBOBJ_DIR} are used, it is OK to use these variables
6058 in other directories. For instance @file{src/Makefile.am} could be
6064 AUTOMAKE_OPTIONS = subdir-objects
6065 LDADD = $(LIBOBJS) $(ALLOCA)
6067 bin_PROGRAMS = tool1 tool2 @dots{}
6068 tool1_SOURCES = @dots{}
6069 tool2_SOURCES = @dots{}
6072 Because @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} contain object
6073 file names that end with @samp{.$(OBJEXT)}, they are not suitable for
6074 Libtool libraries (where the expected object extension is @file{.lo}):
6075 @code{LTLIBOBJS} and @code{LTALLOCA} should be used instead.
6077 @code{LTLIBOBJS} is defined automatically by Autoconf and should not
6078 be defined by hand (as in the past), however at the time of writing
6079 @code{LTALLOCA} still needs to be defined from @code{ALLOCA} manually.
6080 @xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs.@: @code{LIBOBJS},
6081 autoconf, The Autoconf Manual}.
6084 @node Program Variables
6085 @section Variables used when building a program
6087 Occasionally it is useful to know which @file{Makefile} variables
6088 Automake uses for compilations, and in which order (@pxref{Flag
6089 Variables Ordering}); for instance, you might need to do your own
6090 compilation in some special cases.
6092 Some variables are inherited from Autoconf; these are @code{CC},
6093 @code{CFLAGS}, @code{CPPFLAGS}, @code{DEFS}, @code{LDFLAGS}, and
6102 There are some additional variables that Automake defines on its own:
6106 The contents of this variable are passed to every compilation that invokes
6107 the C preprocessor; it is a list of arguments to the preprocessor. For
6108 instance, @option{-I} and @option{-D} options should be listed here.
6110 Automake already provides some @option{-I} options automatically, in a
6111 separate variable that is also passed to every compilation that invokes
6112 the C preprocessor. In particular it generates @samp{-I.},
6113 @samp{-I$(srcdir)}, and a @option{-I} pointing to the directory holding
6114 @file{config.h} (if you've used @code{AC_CONFIG_HEADERS}). You can
6115 disable the default @option{-I} options using the @option{nostdinc}
6118 When a file to be included is generated during the build and not part
6119 of a distribution tarball, its location is under @code{$(builddir)},
6120 not under @code{$(srcdir)}. This matters especially for packages that
6121 use header files placed in sub-directories and want to allow builds
6122 outside the source tree (@pxref{VPATH Builds}). In that case we
6123 recommend to use a pair of @option{-I} options, such as, e.g.,
6124 @samp{-Isome/subdir -I$(srcdir)/some/subdir} or
6125 @samp{-I$(top_builddir)/some/subdir -I$(top_srcdir)/some/subdir}.
6126 Note that the reference to the build tree should come before the
6127 reference to the source tree, so that accidentally leftover generated
6128 files in the source directory are ignored.
6130 @code{AM_CPPFLAGS} is ignored in preference to a per-executable (or
6131 per-library) @code{_CPPFLAGS} variable if it is defined.
6134 This does the same job as @code{AM_CPPFLAGS} (or any per-target
6135 @code{_CPPFLAGS} variable if it is used). It is an older name for the
6136 same functionality. This variable is deprecated; we suggest using
6137 @code{AM_CPPFLAGS} and per-target @code{_CPPFLAGS} instead.
6140 This is the variable the @file{Makefile.am} author can use to pass
6141 in additional C compiler flags. In some situations, this is
6142 not used, in preference to the per-executable (or per-library)
6146 This is the command used to actually compile a C source file. The
6147 file name is appended to form the complete command line.
6150 This is the variable the @file{Makefile.am} author can use to pass
6151 in additional linker flags. In some situations, this is not used, in
6152 preference to the per-executable (or per-library) @code{_LDFLAGS}.
6155 This is the command used to actually link a C program. It already
6156 includes @samp{-o $@@} and the usual variable references (for instance,
6157 @code{CFLAGS}); it takes as ``arguments'' the names of the object files
6158 and libraries to link in. This variable is not used when the linker is
6159 overridden with a per-target @code{_LINK} variable or per-target flags
6160 cause Automake to define such a @code{_LINK} variable.
6165 @section Yacc and Lex support
6167 Automake has somewhat idiosyncratic support for Yacc and Lex.
6169 Automake assumes that the @file{.c} file generated by @command{yacc}
6170 (or @command{lex}) should be named using the basename of the input
6171 file. That is, for a yacc source file @file{foo.y}, Automake will
6172 cause the intermediate file to be named @file{foo.c} (as opposed to
6173 @file{y.tab.c}, which is more traditional).
6175 The extension of a yacc source file is used to determine the extension
6176 of the resulting C or C++ source and header files. Note that header
6177 files are generated only when the @option{-d} Yacc option is used; see
6178 below for more information about this flag, and how to specify it.
6179 Files with the extension @file{.y} will thus be turned into @file{.c}
6180 sources and @file{.h} headers; likewise, @file{.yy} will become
6181 @file{.cc} and @file{.hh}, @file{.y++} will become @file{c++} and
6182 @file{h++}, @file{.yxx} will become @file{.cxx} and @file{.hxx},
6183 and @file{.ypp} will become @file{.cpp} and @file{.hpp}.
6185 Similarly, lex source files can be used to generate C or C++; the
6186 extensions @file{.l}, @file{.ll}, @file{.l++}, @file{.lxx}, and
6187 @file{.lpp} are recognized.
6189 You should never explicitly mention the intermediate (C or C++) file
6190 in any @code{SOURCES} variable; only list the source file.
6192 The intermediate files generated by @command{yacc} (or @command{lex})
6193 will be included in any distribution that is made. That way the user
6194 doesn't need to have @command{yacc} or @command{lex}.
6196 If a @command{yacc} source file is seen, then your @file{configure.ac} must
6197 define the variable @code{YACC}. This is most easily done by invoking
6198 the macro @code{AC_PROG_YACC} (@pxref{Particular Programs, , Particular
6199 Program Checks, autoconf, The Autoconf Manual}).
6203 When @code{yacc} is invoked, it is passed @code{AM_YFLAGS} and
6204 @code{YFLAGS}. The latter is a user variable and the former is
6205 intended for the @file{Makefile.am} author.
6207 @code{AM_YFLAGS} is usually used to pass the @option{-d} option to
6208 @command{yacc}. Automake knows what this means and will automatically
6209 adjust its rules to update and distribute the header file built by
6210 @samp{yacc -d}@footnote{Please note that @command{automake} recognizes
6211 @option{-d} in @code{AM_YFLAGS} only if it is not clustered with other
6212 options; for example, it won't be recognized if @code{AM_YFLAGS} is
6213 @option{-dt}, but it will be if @code{AM_YFLAGS} is @option{-d -t} or
6215 What Automake cannot guess, though, is where this
6216 header will be used: it is up to you to ensure the header gets built
6217 before it is first used. Typically this is necessary in order for
6218 dependency tracking to work when the header is included by another
6219 file. The common solution is listing the header file in
6220 @code{BUILT_SOURCES} (@pxref{Sources}) as follows.
6223 BUILT_SOURCES = parser.h
6226 foo_SOURCES = @dots{} parser.y @dots{}
6229 If a @command{lex} source file is seen, then your @file{configure.ac}
6230 must define the variable @code{LEX}. You can use @code{AC_PROG_LEX}
6231 to do this (@pxref{Particular Programs, , Particular Program Checks,
6232 autoconf, The Autoconf Manual}), but using @code{AM_PROG_LEX} macro
6233 (@pxref{Macros}) is recommended.
6237 When @command{lex} is invoked, it is passed @code{AM_LFLAGS} and
6238 @code{LFLAGS}. The latter is a user variable and the former is
6239 intended for the @file{Makefile.am} author.
6241 When @code{AM_MAINTAINER_MODE} (@pxref{maintainer-mode}) is used, the
6242 rebuild rule for distributed Yacc and Lex sources are only used when
6243 @code{maintainer-mode} is enabled, or when the files have been erased.
6245 @cindex @command{ylwrap}
6246 @cindex @command{yacc}, multiple parsers
6247 @cindex Multiple @command{yacc} parsers
6248 @cindex Multiple @command{lex} lexers
6249 @cindex @command{lex}, multiple lexers
6251 When @command{lex} or @command{yacc} sources are used, @code{automake -a}
6252 automatically installs an auxiliary program called @command{ylwrap} in
6253 your package (@pxref{Auxiliary Programs}).
6254 This program is used by the build rules to rename the output of these
6255 tools, and makes it possible to include multiple @command{yacc} (or
6256 @command{lex}) source files in a single directory. (This is necessary
6257 because yacc's output file name is fixed, and a parallel make could
6258 conceivably invoke more than one instance of @command{yacc}
6261 For @command{yacc}, simply managing locking is insufficient. The output of
6262 @command{yacc} always uses the same symbol names internally, so it isn't
6263 possible to link two @command{yacc} parsers into the same executable.
6265 We recommend using the following renaming hack used in @command{gdb}:
6267 #define yymaxdepth c_maxdepth
6268 #define yyparse c_parse
6270 #define yyerror c_error
6271 #define yylval c_lval
6272 #define yychar c_char
6273 #define yydebug c_debug
6274 #define yypact c_pact
6281 #define yyexca c_exca
6282 #define yyerrflag c_errflag
6283 #define yynerrs c_nerrs
6287 #define yy_yys c_yys
6288 #define yystate c_state
6291 #define yy_yyv c_yyv
6293 #define yylloc c_lloc
6294 #define yyreds c_reds
6295 #define yytoks c_toks
6296 #define yylhs c_yylhs
6297 #define yylen c_yylen
6298 #define yydefred c_yydefred
6299 #define yydgoto c_yydgoto
6300 #define yysindex c_yysindex
6301 #define yyrindex c_yyrindex
6302 #define yygindex c_yygindex
6303 #define yytable c_yytable
6304 #define yycheck c_yycheck
6305 #define yyname c_yyname
6306 #define yyrule c_yyrule
6309 For each define, replace the @samp{c_} prefix with whatever you like.
6310 These defines work for @command{bison}, @command{byacc}, and
6311 traditional @code{yacc}s. If you find a parser generator that uses a
6312 symbol not covered here, please report the new name so it can be added
6317 @section C++ Support
6320 @cindex Support for C++
6322 Automake includes full support for C++.
6324 Any package including C++ code must define the output variable
6325 @code{CXX} in @file{configure.ac}; the simplest way to do this is to use
6326 the @code{AC_PROG_CXX} macro (@pxref{Particular Programs, , Particular
6327 Program Checks, autoconf, The Autoconf Manual}).
6329 A few additional variables are defined when a C++ source file is seen:
6333 The name of the C++ compiler.
6336 Any flags to pass to the C++ compiler.
6339 The maintainer's variant of @code{CXXFLAGS}.
6342 The command used to actually compile a C++ source file. The file name
6343 is appended to form the complete command line.
6346 The command used to actually link a C++ program.
6350 @node Objective C Support
6351 @section Objective C Support
6353 @cindex Objective C support
6354 @cindex Support for Objective C
6356 Automake includes some support for Objective C.
6358 Any package including Objective C code must define the output variable
6359 @code{OBJC} in @file{configure.ac}; the simplest way to do this is to use
6360 the @code{AC_PROG_OBJC} macro (@pxref{Particular Programs, , Particular
6361 Program Checks, autoconf, The Autoconf Manual}).
6363 A few additional variables are defined when an Objective C source file
6368 The name of the Objective C compiler.
6371 Any flags to pass to the Objective C compiler.
6374 The maintainer's variant of @code{OBJCFLAGS}.
6377 The command used to actually compile an Objective C source file. The
6378 file name is appended to form the complete command line.
6381 The command used to actually link an Objective C program.
6385 @node Objective C++ Support
6386 @section Objective C++ Support
6388 @cindex Objective C++ support
6389 @cindex Support for Objective C++
6391 Automake includes some support for Objective C++.
6393 Any package including Objective C++ code must define the output variable
6394 @code{OBJCXX} in @file{configure.ac}; the simplest way to do this is to use
6395 the @code{AC_PROG_OBJCXX} macro (@pxref{Particular Programs, , Particular
6396 Program Checks, autoconf, The Autoconf Manual}).
6398 A few additional variables are defined when an Objective C++ source file
6403 The name of the Objective C++ compiler.
6406 Any flags to pass to the Objective C++ compiler.
6408 @item AM_OBJCXXFLAGS
6409 The maintainer's variant of @code{OBJCXXFLAGS}.
6412 The command used to actually compile an Objective C++ source file. The
6413 file name is appended to form the complete command line.
6416 The command used to actually link an Objective C++ program.
6420 @node Unified Parallel C Support
6421 @section Unified Parallel C Support
6423 @cindex Unified Parallel C support
6424 @cindex Support for Unified Parallel C
6426 Automake includes some support for Unified Parallel C.
6428 Any package including Unified Parallel C code must define the output
6429 variable @code{UPC} in @file{configure.ac}; the simplest way to do
6430 this is to use the @code{AM_PROG_UPC} macro (@pxref{Public Macros}).
6432 A few additional variables are defined when a Unified Parallel C
6433 source file is seen:
6437 The name of the Unified Parallel C compiler.
6440 Any flags to pass to the Unified Parallel C compiler.
6443 The maintainer's variant of @code{UPCFLAGS}.
6446 The command used to actually compile a Unified Parallel C source file.
6447 The file name is appended to form the complete command line.
6450 The command used to actually link a Unified Parallel C program.
6454 @node Assembly Support
6455 @section Assembly Support
6457 Automake includes some support for assembly code. There are two forms
6458 of assembler files: normal (@file{*.s}) and preprocessed by @code{CPP}
6459 (@file{*.S} or @file{*.sx}).
6464 @vindex AM_CCASFLAGS
6466 The variable @code{CCAS} holds the name of the compiler used to build
6467 assembly code. This compiler must work a bit like a C compiler; in
6468 particular it must accept @option{-c} and @option{-o}. The values of
6469 @code{CCASFLAGS} and @code{AM_CCASFLAGS} (or its per-target
6470 definition) is passed to the compilation. For preprocessed files,
6471 @code{DEFS}, @code{DEFAULT_INCLUDES}, @code{INCLUDES}, @code{CPPFLAGS}
6472 and @code{AM_CPPFLAGS} are also used.
6474 The autoconf macro @code{AM_PROG_AS} will define @code{CCAS} and
6475 @code{CCASFLAGS} for you (unless they are already set, it simply sets
6476 @code{CCAS} to the C compiler and @code{CCASFLAGS} to the C compiler
6477 flags), but you are free to define these variables by other means.
6479 Only the suffixes @file{.s}, @file{.S}, and @file{.sx} are recognized by
6480 @command{automake} as being files containing assembly code.
6483 @node Fortran 77 Support
6484 @comment node-name, next, previous, up
6485 @section Fortran 77 Support
6487 @cindex Fortran 77 support
6488 @cindex Support for Fortran 77
6490 Automake includes full support for Fortran 77.
6492 Any package including Fortran 77 code must define the output variable
6493 @code{F77} in @file{configure.ac}; the simplest way to do this is to use
6494 the @code{AC_PROG_F77} macro (@pxref{Particular Programs, , Particular
6495 Program Checks, autoconf, The Autoconf Manual}).
6497 A few additional variables are defined when a Fortran 77 source file is
6503 The name of the Fortran 77 compiler.
6506 Any flags to pass to the Fortran 77 compiler.
6509 The maintainer's variant of @code{FFLAGS}.
6512 Any flags to pass to the Ratfor compiler.
6515 The maintainer's variant of @code{RFLAGS}.
6518 The command used to actually compile a Fortran 77 source file. The file
6519 name is appended to form the complete command line.
6522 The command used to actually link a pure Fortran 77 program or shared
6527 Automake can handle preprocessing Fortran 77 and Ratfor source files in
6528 addition to compiling them@footnote{Much, if not most, of the
6529 information in the following sections pertaining to preprocessing
6530 Fortran 77 programs was taken almost verbatim from @ref{Catalogue of
6531 Rules, , Catalogue of Rules, make, The GNU Make Manual}.}. Automake
6532 also contains some support for creating programs and shared libraries
6533 that are a mixture of Fortran 77 and other languages (@pxref{Mixing
6534 Fortran 77 With C and C++}).
6536 These issues are covered in the following sections.
6539 * Preprocessing Fortran 77:: Preprocessing Fortran 77 sources
6540 * Compiling Fortran 77 Files:: Compiling Fortran 77 sources
6541 * Mixing Fortran 77 With C and C++:: Mixing Fortran 77 With C and C++
6545 @node Preprocessing Fortran 77
6546 @comment node-name, next, previous, up
6547 @subsection Preprocessing Fortran 77
6549 @cindex Preprocessing Fortran 77
6550 @cindex Fortran 77, Preprocessing
6551 @cindex Ratfor programs
6553 @file{N.f} is made automatically from @file{N.F} or @file{N.r}. This
6554 rule runs just the preprocessor to convert a preprocessable Fortran 77
6555 or Ratfor source file into a strict Fortran 77 source file. The precise
6556 command used is as follows:
6561 @code{$(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)@*
6562 $(AM_FFLAGS) $(FFLAGS)}
6565 @code{$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
6570 @node Compiling Fortran 77 Files
6571 @comment node-name, next, previous, up
6572 @subsection Compiling Fortran 77 Files
6574 @file{N.o} is made automatically from @file{N.f}, @file{N.F} or
6575 @file{N.r} by running the Fortran 77 compiler. The precise command used
6581 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS)}
6584 @code{$(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)@*
6585 $(AM_FFLAGS) $(FFLAGS)}
6588 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
6593 @node Mixing Fortran 77 With C and C++
6594 @comment node-name, next, previous, up
6595 @subsection Mixing Fortran 77 With C and C++
6597 @cindex Fortran 77, mixing with C and C++
6598 @cindex Mixing Fortran 77 with C and C++
6599 @cindex Linking Fortran 77 with C and C++
6601 @cindex Mixing Fortran 77 with C and/or C++
6603 Automake currently provides @emph{limited} support for creating programs
6604 and shared libraries that are a mixture of Fortran 77 and C and/or C++.
6605 However, there are many other issues related to mixing Fortran 77 with
6606 other languages that are @emph{not} (currently) handled by Automake, but
6607 that are handled by other packages@footnote{For example,
6608 @uref{http://www-zeus.desy.de/~burow/cfortran/, the cfortran package}
6609 addresses all of these inter-language issues, and runs under nearly all
6610 Fortran 77, C and C++ compilers on nearly all platforms. However,
6611 @command{cfortran} is not yet Free Software, but it will be in the next
6614 Automake can help in two ways:
6618 Automatic selection of the linker depending on which combinations of
6622 Automatic selection of the appropriate linker flags (e.g., @option{-L} and
6623 @option{-l}) to pass to the automatically selected linker in order to link
6624 in the appropriate Fortran 77 intrinsic and run-time libraries.
6626 @cindex @code{FLIBS}, defined
6628 These extra Fortran 77 linker flags are supplied in the output variable
6629 @code{FLIBS} by the @code{AC_F77_LIBRARY_LDFLAGS} Autoconf macro.
6630 @xref{Fortran Compiler, , Fortran Compiler Characteristics, autoconf,
6631 The Autoconf Manual}.
6634 If Automake detects that a program or shared library (as mentioned in
6635 some @code{_PROGRAMS} or @code{_LTLIBRARIES} primary) contains source
6636 code that is a mixture of Fortran 77 and C and/or C++, then it requires
6637 that the macro @code{AC_F77_LIBRARY_LDFLAGS} be called in
6638 @file{configure.ac}, and that either @code{$(FLIBS)}
6639 appear in the appropriate @code{_LDADD} (for programs) or @code{_LIBADD}
6640 (for shared libraries) variables. It is the responsibility of the
6641 person writing the @file{Makefile.am} to make sure that @samp{$(FLIBS)}
6642 appears in the appropriate @code{_LDADD} or
6643 @code{_LIBADD} variable.
6645 @cindex Mixed language example
6646 @cindex Example, mixed language
6648 For example, consider the following @file{Makefile.am}:
6652 foo_SOURCES = main.cc foo.f
6653 foo_LDADD = libfoo.la $(FLIBS)
6655 pkglib_LTLIBRARIES = libfoo.la
6656 libfoo_la_SOURCES = bar.f baz.c zardoz.cc
6657 libfoo_la_LIBADD = $(FLIBS)
6660 In this case, Automake will insist that @code{AC_F77_LIBRARY_LDFLAGS}
6661 is mentioned in @file{configure.ac}. Also, if @samp{$(FLIBS)} hadn't
6662 been mentioned in @code{foo_LDADD} and @code{libfoo_la_LIBADD}, then
6663 Automake would have issued a warning.
6666 * How the Linker is Chosen:: Automatic linker selection
6669 @node How the Linker is Chosen
6670 @comment node-name, next, previous, up
6671 @subsubsection How the Linker is Chosen
6673 @cindex Automatic linker selection
6674 @cindex Selecting the linker automatically
6676 When a program or library mixes several languages, Automake choose the
6677 linker according to the following priorities. (The names in
6678 parentheses are the variables containing the link command.)
6683 Native Java (@code{GCJLINK})
6686 Objective C++ (@code{OBJCXXLINK})
6689 C++ (@code{CXXLINK})
6692 Fortran 77 (@code{F77LINK})
6695 Fortran (@code{FCLINK})
6698 Objective C (@code{OBJCLINK})
6701 Unified Parallel C (@code{UPCLINK})
6707 For example, if Fortran 77, C and C++ source code is compiled
6708 into a program, then the C++ linker will be used. In this case, if the
6709 C or Fortran 77 linkers required any special libraries that weren't
6710 included by the C++ linker, then they must be manually added to an
6711 @code{_LDADD} or @code{_LIBADD} variable by the user writing the
6714 Automake only looks at the file names listed in @file{_SOURCES}
6715 variables to choose the linker, and defaults to the C linker.
6716 Sometimes this is inconvenient because you are linking against a
6717 library written in another language and would like to set the linker
6718 more appropriately. @xref{Libtool Convenience Libraries}, for a
6719 trick with @code{nodist_EXTRA_@dots{}_SOURCES}.
6721 A per-target @code{_LINK} variable will override the above selection.
6722 Per-target link flags will cause Automake to write a per-target
6723 @code{_LINK} variable according to the language chosen as above.
6726 @node Fortran 9x Support
6727 @comment node-name, next, previous, up
6728 @section Fortran 9x Support
6730 @cindex Fortran 9x support
6731 @cindex Support for Fortran 9x
6733 Automake includes support for Fortran 9x.
6735 Any package including Fortran 9x code must define the output variable
6736 @code{FC} in @file{configure.ac}; the simplest way to do this is to use
6737 the @code{AC_PROG_FC} macro (@pxref{Particular Programs, , Particular
6738 Program Checks, autoconf, The Autoconf Manual}).
6740 A few additional variables are defined when a Fortran 9x source file is
6746 The name of the Fortran 9x compiler.
6749 Any flags to pass to the Fortran 9x compiler.
6752 The maintainer's variant of @code{FCFLAGS}.
6755 The command used to actually compile a Fortran 9x source file. The file
6756 name is appended to form the complete command line.
6759 The command used to actually link a pure Fortran 9x program or shared
6765 * Compiling Fortran 9x Files:: Compiling Fortran 9x sources
6768 @node Compiling Fortran 9x Files
6769 @comment node-name, next, previous, up
6770 @subsection Compiling Fortran 9x Files
6772 @file{@var{file}.o} is made automatically from @file{@var{file}.f90},
6773 @file{@var{file}.f95}, @file{@var{file}.f03}, or @file{@var{file}.f08}
6774 by running the Fortran 9x compiler. The precise command used
6780 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f90) $<}
6783 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f95) $<}
6786 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f03) $<}
6789 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f08) $<}
6793 @node Java Support with gcj
6794 @comment node-name, next, previous, up
6795 @section Compiling Java sources using gcj
6797 @cindex Java support with gcj
6798 @cindex Support for Java with gcj
6799 @cindex Java to native code, compilation
6800 @cindex Compilation of Java to native code
6802 Automake includes support for natively compiled Java, using @command{gcj},
6803 the Java front end to the GNU Compiler Collection (rudimentary support
6804 for compiling Java to bytecode using the @command{javac} compiler is
6805 also present, @emph{albeit deprecated}; @pxref{Java}).
6807 Any package including Java code to be compiled must define the output
6808 variable @code{GCJ} in @file{configure.ac}; the variable @code{GCJFLAGS}
6809 must also be defined somehow (either in @file{configure.ac} or
6810 @file{Makefile.am}). The simplest way to do this is to use the
6811 @code{AM_PROG_GCJ} macro.
6815 By default, programs including Java source files are linked with
6818 As always, the contents of @code{AM_GCJFLAGS} are passed to every
6819 compilation invoking @command{gcj} (in its role as an ahead-of-time
6820 compiler, when invoking it to create @file{.class} files,
6821 @code{AM_JAVACFLAGS} is used instead). If it is necessary to pass
6822 options to @command{gcj} from @file{Makefile.am}, this variable, and not
6823 the user variable @code{GCJFLAGS}, should be used.
6827 @command{gcj} can be used to compile @file{.java}, @file{.class},
6828 @file{.zip}, or @file{.jar} files.
6830 When linking, @command{gcj} requires that the main class be specified
6831 using the @option{--main=} option. The easiest way to do this is to use
6832 the @code{_LDFLAGS} variable for the program.
6836 @comment node-name, next, previous, up
6837 @section Vala Support
6839 @cindex Vala Support
6840 @cindex Support for Vala
6842 Automake provides initial support for Vala
6843 (@uref{http://www.vala-project.org/}).
6844 This requires valac version 0.7.0 or later, and currently requires
6845 the user to use GNU @command{make}.
6848 foo_SOURCES = foo.vala bar.vala zardoc.c
6851 Any @file{.vala} file listed in a @code{_SOURCES} variable will be
6852 compiled into C code by the Vala compiler. The generated @file{.c} files
6853 are distributed. The end user does not need to have a Vala compiler installed.
6855 Automake ships with an Autoconf macro called @code{AM_PROG_VALAC}
6856 that will locate the Vala compiler and optionally check its version
6859 @defmac AM_PROG_VALAC (@ovar{minimum-version}, @ovar{action-if-found},
6860 @ovar{action-if-not-found})
6861 Search for a Vala compiler in @env{PATH}. If it is found, the variable
6862 @code{VALAC} is set to point to it (see below for more details). This
6863 macro takes three optional arguments. The first argument, if present,
6864 is the minimum version of the Vala compiler required to compile this
6865 package. If a compiler is found and satisfies @var{minimum-version},
6866 then @var{action-if-found} is run (this defaults to do nothing).
6867 Otherwise, @var{action-if-not-found} is run. If @var{action-if-not-found}
6868 is not specified, the default value is to print a warning in case no
6869 compiler is found, or if a too-old version of the compiler is found.
6872 There are a few variables that are used when compiling Vala sources:
6876 Absolute path to the Vala compiler, or simply @samp{valac} if no
6877 suitable compiler Vala could be found at configure runtime.
6880 Additional arguments for the Vala compiler.
6883 The maintainer's variant of @code{VALAFLAGS}.
6886 lib_LTLIBRARIES = libfoo.la
6887 libfoo_la_SOURCES = foo.vala
6891 Note that currently, you cannot use per-target @code{*_VALAFLAGS}
6892 (@pxref{Renamed Objects}) to produce different C files from one Vala
6896 @node Support for Other Languages
6897 @comment node-name, next, previous, up
6898 @section Support for Other Languages
6900 Automake currently only includes full support for C, C++ (@pxref{C++
6901 Support}), Objective C (@pxref{Objective C Support}),
6902 Objective C++ (@pxref{Objective C++ Support}),
6904 (@pxref{Fortran 77 Support}), Fortran 9x (@pxref{Fortran 9x Support}),
6905 and Java (@pxref{Java Support with gcj}). There is only rudimentary
6906 support for other languages, support for which will be improved based
6909 Some limited support for adding your own languages is available via the
6910 suffix rule handling (@pxref{Suffixes}).
6913 @section Automatic dependency tracking
6915 As a developer it is often painful to continually update the
6916 @file{Makefile.am} whenever the include-file dependencies change in a
6917 project. Automake supplies a way to automatically track dependency
6918 changes (@pxref{Dependency Tracking}).
6920 @cindex Dependency tracking
6921 @cindex Automatic dependency tracking
6923 Automake always uses complete dependencies for a compilation,
6924 including system headers. Automake's model is that dependency
6925 computation should be a side effect of the build. To this end,
6926 dependencies are computed by running all compilations through a
6927 special wrapper program called @command{depcomp}. @command{depcomp}
6928 understands how to coax many different C and C++ compilers into
6929 generating dependency information in the format it requires.
6930 @samp{automake -a} will install @command{depcomp} into your source
6931 tree for you. If @command{depcomp} can't figure out how to properly
6932 invoke your compiler, dependency tracking will simply be disabled for
6935 @cindex @command{depcomp}
6937 Experience with earlier versions of Automake (@pxref{Dependency Tracking
6938 Evolution, , Dependency Tracking Evolution, automake-history, Brief History
6939 of Automake}) taught us that it is not reliable to generate dependencies
6940 only on the maintainer's system, as configurations vary too much. So
6941 instead Automake implements dependency tracking at build time.
6943 Automatic dependency tracking can be suppressed by putting
6944 @option{no-dependencies} in the variable @code{AUTOMAKE_OPTIONS}, or
6945 passing @option{no-dependencies} as an argument to @code{AM_INIT_AUTOMAKE}
6946 (this should be the preferred way). Or, you can invoke @command{automake}
6947 with the @option{-i} option. Dependency tracking is enabled by default.
6949 @vindex AUTOMAKE_OPTIONS
6950 @opindex no-dependencies
6952 The person building your package also can choose to disable dependency
6953 tracking by configuring with @option{--disable-dependency-tracking}.
6955 @cindex Disabling dependency tracking
6956 @cindex Dependency tracking, disabling
6960 @section Support for executable extensions
6962 @cindex Executable extension
6963 @cindex Extension, executable
6966 On some platforms, such as Windows, executables are expected to have an
6967 extension such as @file{.exe}. On these platforms, some compilers (GCC
6968 among them) will automatically generate @file{foo.exe} when asked to
6969 generate @file{foo}.
6971 Automake provides mostly-transparent support for this. Unfortunately
6972 @emph{mostly} doesn't yet mean @emph{fully}. Until the English
6973 dictionary is revised, you will have to assist Automake if your package
6974 must support those platforms.
6976 One thing you must be aware of is that, internally, Automake rewrites
6977 something like this:
6980 bin_PROGRAMS = liver
6986 bin_PROGRAMS = liver$(EXEEXT)
6989 The targets Automake generates are likewise given the @samp{$(EXEEXT)}
6992 The variables @code{TESTS} and @code{XFAIL_TESTS} (@pxref{Simple Tests})
6993 are also rewritten if they contain filenames that have been declared as
6994 programs in the same @file{Makefile}. (This is mostly useful when some
6995 programs from @code{check_PROGRAMS} are listed in @code{TESTS}.)
6997 However, Automake cannot apply this rewriting to @command{configure}
6998 substitutions. This means that if you are conditionally building a
6999 program using such a substitution, then your @file{configure.ac} must
7000 take care to add @samp{$(EXEEXT)} when constructing the output variable.
7002 Sometimes maintainers like to write an explicit link rule for their
7003 program. Without executable extension support, this is easy---you
7004 simply write a rule whose target is the name of the program. However,
7005 when executable extension support is enabled, you must instead add the
7006 @samp{$(EXEEXT)} suffix.
7008 This might be a nuisance for maintainers who know their package will
7009 never run on a platform that has
7010 executable extensions. For those maintainers, the @option{no-exeext}
7011 option (@pxref{Options}) will disable this feature. This works in a
7012 fairly ugly way; if @option{no-exeext} is seen, then the presence of a
7013 rule for a target named @code{foo} in @file{Makefile.am} will override
7014 an @command{automake}-generated rule for @samp{foo$(EXEEXT)}. Without
7015 the @option{no-exeext} option, this use will give a diagnostic.
7019 @chapter Other Derived Objects
7021 Automake can handle derived objects that are not C programs. Sometimes
7022 the support for actually building such objects must be explicitly
7023 supplied, but Automake will still automatically handle installation and
7027 * Scripts:: Executable scripts
7028 * Headers:: Header files
7029 * Data:: Architecture-independent data files
7030 * Sources:: Derived sources
7035 @section Executable Scripts
7037 @cindex @code{_SCRIPTS} primary, defined
7038 @cindex @code{SCRIPTS} primary, defined
7039 @cindex Primary variable, @code{SCRIPTS}
7041 @cindex Installing scripts
7043 It is possible to define and install programs that are scripts. Such
7044 programs are listed using the @code{SCRIPTS} primary name. When the
7045 script is distributed in its final, installable form, the
7046 @file{Makefile} usually looks as follows:
7050 # Install my_script in $(bindir) and distribute it.
7051 dist_bin_SCRIPTS = my_script
7054 Scripts are not distributed by default; as we have just seen, those
7055 that should be distributed can be specified using a @code{dist_}
7056 prefix as with other primaries.
7058 @cindex @code{SCRIPTS}, installation directories
7060 @vindex sbin_SCRIPTS
7061 @vindex libexec_SCRIPTS
7062 @vindex pkgdata_SCRIPTS
7063 @vindex pkglibexec_SCRIPTS
7064 @vindex noinst_SCRIPTS
7065 @vindex check_SCRIPTS
7067 Scripts can be installed in @code{bindir}, @code{sbindir},
7068 @code{libexecdir}, @code{pkglibexecdir}, or @code{pkgdatadir}.
7070 Scripts that need not be installed can be listed in
7071 @code{noinst_SCRIPTS}, and among them, those which are needed only by
7072 @samp{make check} should go in @code{check_SCRIPTS}.
7074 When a script needs to be built, the @file{Makefile.am} should include
7075 the appropriate rules. For instance the @command{automake} program
7076 itself is a Perl script that is generated from @file{automake.in}.
7077 Here is how this is handled:
7080 bin_SCRIPTS = automake
7081 CLEANFILES = $(bin_SCRIPTS)
7082 EXTRA_DIST = automake.in
7084 do_subst = sed -e 's,[@@]datadir[@@],$(datadir),g' \
7085 -e 's,[@@]PERL[@@],$(PERL),g' \
7086 -e 's,[@@]PACKAGE[@@],$(PACKAGE),g' \
7087 -e 's,[@@]VERSION[@@],$(VERSION),g' \
7090 automake: automake.in Makefile
7091 $(do_subst) < $(srcdir)/automake.in > automake
7095 Such scripts for which a build rule has been supplied need to be
7096 deleted explicitly using @code{CLEANFILES} (@pxref{Clean}), and their
7097 sources have to be distributed, usually with @code{EXTRA_DIST}
7098 (@pxref{Basics of Distribution}).
7100 Another common way to build scripts is to process them from
7101 @file{configure} with @code{AC_CONFIG_FILES}. In this situation
7102 Automake knows which files should be cleaned and distributed, and what
7103 the rebuild rules should look like.
7105 For instance if @file{configure.ac} contains
7108 AC_CONFIG_FILES([src/my_script], [chmod +x src/my_script])
7112 to build @file{src/my_script} from @file{src/my_script.in}, then a
7113 @file{src/Makefile.am} to install this script in @code{$(bindir)} can
7117 bin_SCRIPTS = my_script
7118 CLEANFILES = $(bin_SCRIPTS)
7122 There is no need for @code{EXTRA_DIST} or any build rule: Automake
7123 infers them from @code{AC_CONFIG_FILES} (@pxref{Requirements}).
7124 @code{CLEANFILES} is still useful, because by default Automake will
7125 clean targets of @code{AC_CONFIG_FILES} in @code{distclean}, not
7128 Although this looks simpler, building scripts this way has one
7129 drawback: directory variables such as @code{$(datadir)} are not fully
7130 expanded and may refer to other directory variables.
7133 @section Header files
7135 @cindex @code{_HEADERS} primary, defined
7136 @cindex @code{HEADERS} primary, defined
7137 @cindex Primary variable, @code{HEADERS}
7139 @vindex noinst_HEADERS
7140 @cindex @code{HEADERS}, installation directories
7141 @cindex Installing headers
7142 @vindex include_HEADERS
7143 @vindex oldinclude_HEADERS
7144 @vindex pkginclude_HEADERS
7147 Header files that must be installed are specified by the
7148 @code{HEADERS} family of variables. Headers can be installed in
7149 @code{includedir}, @code{oldincludedir}, @code{pkgincludedir} or any
7150 other directory you may have defined (@pxref{Uniform}). For instance,
7153 include_HEADERS = foo.h bar/bar.h
7157 will install the two files as @file{$(includedir)/foo.h} and
7158 @file{$(includedir)/bar.h}.
7160 The @code{nobase_} prefix is also supported,
7163 nobase_include_HEADERS = foo.h bar/bar.h
7167 will install the two files as @file{$(includedir)/foo.h} and
7168 @file{$(includedir)/bar/bar.h} (@pxref{Alternative}).
7170 @vindex noinst_HEADERS
7171 Usually, only header files that accompany installed libraries need to
7172 be installed. Headers used by programs or convenience libraries are
7173 not installed. The @code{noinst_HEADERS} variable can be used for
7174 such headers. However when the header actually belongs to a single
7175 convenience library or program, we recommend listing it in the
7176 program's or library's @code{_SOURCES} variable (@pxref{Program
7177 Sources}) instead of in @code{noinst_HEADERS}. This is clearer for
7178 the @file{Makefile.am} reader. @code{noinst_HEADERS} would be the
7179 right variable to use in a directory containing only headers and no
7180 associated library or program.
7182 All header files must be listed somewhere; in a @code{_SOURCES}
7183 variable or in a @code{_HEADERS} variable. Missing ones will not
7184 appear in the distribution.
7186 For header files that are built and must not be distributed, use the
7187 @code{nodist_} prefix as in @code{nodist_include_HEADERS} or
7188 @code{nodist_prog_SOURCES}. If these generated headers are needed
7189 during the build, you must also ensure they exist before they are
7190 used (@pxref{Sources}).
7194 @section Architecture-independent data files
7196 @cindex @code{_DATA} primary, defined
7197 @cindex @code{DATA} primary, defined
7198 @cindex Primary variable, @code{DATA}
7201 Automake supports the installation of miscellaneous data files using the
7202 @code{DATA} family of variables.
7206 @vindex sysconf_DATA
7207 @vindex sharedstate_DATA
7208 @vindex localstate_DATA
7209 @vindex pkgdata_DATA
7211 Such data can be installed in the directories @code{datadir},
7212 @code{sysconfdir}, @code{sharedstatedir}, @code{localstatedir}, or
7215 By default, data files are @emph{not} included in a distribution. Of
7216 course, you can use the @code{dist_} prefix to change this on a
7219 Here is how Automake declares its auxiliary data files:
7222 dist_pkgdata_DATA = clean-kr.am clean.am @dots{}
7227 @section Built Sources
7229 Because Automake's automatic dependency tracking works as a side-effect
7230 of compilation (@pxref{Dependencies}) there is a bootstrap issue: a
7231 target should not be compiled before its dependencies are made, but
7232 these dependencies are unknown until the target is first compiled.
7234 Ordinarily this is not a problem, because dependencies are distributed
7235 sources: they preexist and do not need to be built. Suppose that
7236 @file{foo.c} includes @file{foo.h}. When it first compiles
7237 @file{foo.o}, @command{make} only knows that @file{foo.o} depends on
7238 @file{foo.c}. As a side-effect of this compilation @command{depcomp}
7239 records the @file{foo.h} dependency so that following invocations of
7240 @command{make} will honor it. In these conditions, it's clear there is
7241 no problem: either @file{foo.o} doesn't exist and has to be built
7242 (regardless of the dependencies), or accurate dependencies exist and
7243 they can be used to decide whether @file{foo.o} should be rebuilt.
7245 It's a different story if @file{foo.h} doesn't exist by the first
7246 @command{make} run. For instance, there might be a rule to build
7247 @file{foo.h}. This time @file{file.o}'s build will fail because the
7248 compiler can't find @file{foo.h}. @command{make} failed to trigger the
7249 rule to build @file{foo.h} first by lack of dependency information.
7251 @vindex BUILT_SOURCES
7252 @cindex @code{BUILT_SOURCES}, defined
7254 The @code{BUILT_SOURCES} variable is a workaround for this problem. A
7255 source file listed in @code{BUILT_SOURCES} is made on @samp{make all}
7256 or @samp{make check} (or even @samp{make install}) before other
7257 targets are processed. However, such a source file is not
7258 @emph{compiled} unless explicitly requested by mentioning it in some
7259 other @code{_SOURCES} variable.
7261 So, to conclude our introductory example, we could use
7262 @samp{BUILT_SOURCES = foo.h} to ensure @file{foo.h} gets built before
7263 any other target (including @file{foo.o}) during @samp{make all} or
7266 @code{BUILT_SOURCES} is actually a bit of a misnomer, as any file which
7267 must be created early in the build process can be listed in this
7268 variable. Moreover, all built sources do not necessarily have to be
7269 listed in @code{BUILT_SOURCES}. For instance, a generated @file{.c} file
7270 doesn't need to appear in @code{BUILT_SOURCES} (unless it is included by
7271 another source), because it's a known dependency of the associated
7274 It might be important to emphasize that @code{BUILT_SOURCES} is
7275 honored only by @samp{make all}, @samp{make check} and @samp{make
7276 install}. This means you cannot build a specific target (e.g.,
7277 @samp{make foo}) in a clean tree if it depends on a built source.
7278 However it will succeed if you have run @samp{make all} earlier,
7279 because accurate dependencies are already available.
7281 The next section illustrates and discusses the handling of built sources
7285 * Built Sources Example:: Several ways to handle built sources.
7288 @node Built Sources Example
7289 @subsection Built Sources Example
7291 Suppose that @file{foo.c} includes @file{bindir.h}, which is
7292 installation-dependent and not distributed: it needs to be built. Here
7293 @file{bindir.h} defines the preprocessor macro @code{bindir} to the
7294 value of the @command{make} variable @code{bindir} (inherited from
7297 We suggest several implementations below. It's not meant to be an
7298 exhaustive listing of all ways to handle built sources, but it will give
7299 you a few ideas if you encounter this issue.
7301 @subsubheading First Try
7303 This first implementation will illustrate the bootstrap issue mentioned
7304 in the previous section (@pxref{Sources}).
7306 Here is a tentative @file{Makefile.am}.
7312 nodist_foo_SOURCES = bindir.h
7313 CLEANFILES = bindir.h
7315 echo '#define bindir "$(bindir)"' >$@@
7318 This setup doesn't work, because Automake doesn't know that @file{foo.c}
7319 includes @file{bindir.h}. Remember, automatic dependency tracking works
7320 as a side-effect of compilation, so the dependencies of @file{foo.o} will
7321 be known only after @file{foo.o} has been compiled (@pxref{Dependencies}).
7322 The symptom is as follows.
7326 source='foo.c' object='foo.o' libtool=no \
7327 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
7328 depmode=gcc /bin/sh ./depcomp \
7329 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
7330 foo.c:2: bindir.h: No such file or directory
7331 make: *** [foo.o] Error 1
7334 In this example @file{bindir.h} is not distributed nor installed, and
7335 it is not even being built on-time. One may wonder if the
7336 @samp{nodist_foo_SOURCES = bindir.h} line has any use at all. This
7337 line simply states that @file{bindir.h} is a source of @code{foo}, so
7338 for instance, it should be inspected while generating tags
7339 (@pxref{Tags}). In other words, it does not help our present problem,
7340 and the build would fail identically without it.
7342 @subsubheading Using @code{BUILT_SOURCES}
7344 A solution is to require @file{bindir.h} to be built before anything
7345 else. This is what @code{BUILT_SOURCES} is meant for (@pxref{Sources}).
7350 nodist_foo_SOURCES = bindir.h
7351 BUILT_SOURCES = bindir.h
7352 CLEANFILES = bindir.h
7354 echo '#define bindir "$(bindir)"' >$@@
7357 See how @file{bindir.h} gets built first:
7361 echo '#define bindir "/usr/local/bin"' >bindir.h
7363 make[1]: Entering directory `/home/adl/tmp'
7364 source='foo.c' object='foo.o' libtool=no \
7365 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
7366 depmode=gcc /bin/sh ./depcomp \
7367 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
7368 gcc -g -O2 -o foo foo.o
7369 make[1]: Leaving directory `/home/adl/tmp'
7372 However, as said earlier, @code{BUILT_SOURCES} applies only to the
7373 @code{all}, @code{check}, and @code{install} targets. It still fails
7374 if you try to run @samp{make foo} explicitly:
7378 test -z "bindir.h" || rm -f bindir.h
7379 test -z "foo" || rm -f foo
7381 % : > .deps/foo.Po # Suppress previously recorded dependencies
7383 source='foo.c' object='foo.o' libtool=no \
7384 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
7385 depmode=gcc /bin/sh ./depcomp \
7386 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
7387 foo.c:2: bindir.h: No such file or directory
7388 make: *** [foo.o] Error 1
7391 @subsubheading Recording Dependencies manually
7393 Usually people are happy enough with @code{BUILT_SOURCES} because they
7394 never build targets such as @samp{make foo} before @samp{make all}, as
7395 in the previous example. However if this matters to you, you can
7396 avoid @code{BUILT_SOURCES} and record such dependencies explicitly in
7397 the @file{Makefile.am}.
7402 nodist_foo_SOURCES = bindir.h
7403 foo.$(OBJEXT): bindir.h
7404 CLEANFILES = bindir.h
7406 echo '#define bindir "$(bindir)"' >$@@
7409 You don't have to list @emph{all} the dependencies of @file{foo.o}
7410 explicitly, only those that might need to be built. If a dependency
7411 already exists, it will not hinder the first compilation and will be
7412 recorded by the normal dependency tracking code. (Note that after
7413 this first compilation the dependency tracking code will also have
7414 recorded the dependency between @file{foo.o} and
7415 @file{bindir.h}; so our explicit dependency is really useful to
7416 the first build only.)
7418 Adding explicit dependencies like this can be a bit dangerous if you are
7419 not careful enough. This is due to the way Automake tries not to
7420 overwrite your rules (it assumes you know better than it).
7421 @samp{foo.$(OBJEXT): bindir.h} supersedes any rule Automake may want to
7422 output to build @samp{foo.$(OBJEXT)}. It happens to work in this case
7423 because Automake doesn't have to output any @samp{foo.$(OBJEXT):}
7424 target: it relies on a suffix rule instead (i.e., @samp{.c.$(OBJEXT):}).
7425 Always check the generated @file{Makefile.in} if you do this.
7427 @subsubheading Build @file{bindir.h} from @file{configure}
7429 It's possible to define this preprocessor macro from @file{configure},
7430 either in @file{config.h} (@pxref{Defining Directories, , Defining
7431 Directories, autoconf, The Autoconf Manual}), or by processing a
7432 @file{bindir.h.in} file using @code{AC_CONFIG_FILES}
7433 (@pxref{Configuration Actions, ,Configuration Actions, autoconf, The
7436 At this point it should be clear that building @file{bindir.h} from
7437 @file{configure} works well for this example. @file{bindir.h} will exist
7438 before you build any target, hence will not cause any dependency issue.
7440 The Makefile can be shrunk as follows. We do not even have to mention
7448 However, it's not always possible to build sources from
7449 @file{configure}, especially when these sources are generated by a tool
7450 that needs to be built first.
7452 @subsubheading Build @file{bindir.c}, not @file{bindir.h}.
7454 Another attractive idea is to define @code{bindir} as a variable or
7455 function exported from @file{bindir.o}, and build @file{bindir.c}
7456 instead of @file{bindir.h}.
7459 noinst_PROGRAMS = foo
7460 foo_SOURCES = foo.c bindir.h
7461 nodist_foo_SOURCES = bindir.c
7462 CLEANFILES = bindir.c
7464 echo 'const char bindir[] = "$(bindir)";' >$@@
7467 @file{bindir.h} contains just the variable's declaration and doesn't
7468 need to be built, so it won't cause any trouble. @file{bindir.o} is
7469 always dependent on @file{bindir.c}, so @file{bindir.c} will get built
7472 @subsubheading Which is best?
7474 There is no panacea, of course. Each solution has its merits and
7477 You cannot use @code{BUILT_SOURCES} if the ability to run @samp{make
7478 foo} on a clean tree is important to you.
7480 You won't add explicit dependencies if you are leery of overriding
7481 an Automake rule by mistake.
7483 Building files from @file{./configure} is not always possible, neither
7484 is converting @file{.h} files into @file{.c} files.
7487 @node Other GNU Tools
7488 @chapter Other GNU Tools
7490 Since Automake is primarily intended to generate @file{Makefile.in}s for
7491 use in GNU programs, it tries hard to interoperate with other GNU tools.
7494 * Emacs Lisp:: Emacs Lisp
7497 * Java:: Java bytecode compilation (deprecated)
7505 @cindex @code{_LISP} primary, defined
7506 @cindex @code{LISP} primary, defined
7507 @cindex Primary variable, @code{LISP}
7513 Automake provides some support for Emacs Lisp. The @code{LISP} primary
7514 is used to hold a list of @file{.el} files. Possible prefixes for this
7515 primary are @code{lisp_} and @code{noinst_}. Note that if
7516 @code{lisp_LISP} is defined, then @file{configure.ac} must run
7517 @code{AM_PATH_LISPDIR} (@pxref{Macros}).
7519 @vindex dist_lisp_LISP
7520 @vindex dist_noinst_LISP
7521 Lisp sources are not distributed by default. You can prefix the
7522 @code{LISP} primary with @code{dist_}, as in @code{dist_lisp_LISP} or
7523 @code{dist_noinst_LISP}, to indicate that these files should be
7526 Automake will byte-compile all Emacs Lisp source files using the Emacs
7527 found by @code{AM_PATH_LISPDIR}, if any was found. When performing such
7528 byte-compilation, the flags specified in the (developer-reserved)
7529 @code{AM_ELCFLAGS} and (user-reserved) @code{ELCFLAGS} make variables
7530 will be passed to the Emacs invocation.
7532 Byte-compiled Emacs Lisp files are not portable among all versions of
7533 Emacs, so it makes sense to turn this off if you expect sites to have
7534 more than one version of Emacs installed. Furthermore, many packages
7535 don't actually benefit from byte-compilation. Still, we recommend
7536 that you byte-compile your Emacs Lisp sources. It is probably better
7537 for sites with strange setups to cope for themselves than to make the
7538 installation less nice for everybody else.
7540 There are two ways to avoid byte-compiling. Historically, we have
7541 recommended the following construct.
7544 lisp_LISP = file1.el file2.el
7549 @code{ELCFILES} is an internal Automake variable that normally lists
7550 all @file{.elc} files that must be byte-compiled. Automake defines
7551 @code{ELCFILES} automatically from @code{lisp_LISP}. Emptying this
7552 variable explicitly prevents byte-compilation.
7554 Since Automake 1.8, we now recommend using @code{lisp_DATA} instead:
7556 @c Keep in sync with primary-prefix-couples-documented-valid.sh
7558 lisp_DATA = file1.el file2.el
7561 Note that these two constructs are not equivalent. @code{_LISP} will
7562 not install a file if Emacs is not installed, while @code{_DATA} will
7563 always install its files.
7568 @cindex GNU Gettext support
7569 @cindex Gettext support
7570 @cindex Support for GNU Gettext
7572 If @code{AM_GNU_GETTEXT} is seen in @file{configure.ac}, then Automake
7573 turns on support for GNU gettext, a message catalog system for
7574 internationalization
7575 (@pxref{Top, , Introduction, gettext, GNU gettext utilities}).
7577 The @code{gettext} support in Automake requires the addition of one or
7578 two subdirectories to the package: @file{po} and possibly also @file{intl}.
7579 The latter is needed if @code{AM_GNU_GETTEXT} is not invoked with the
7580 @samp{external} argument, or if @code{AM_GNU_GETTEXT_INTL_SUBDIR} is used.
7581 Automake ensures that these directories exist and are mentioned in
7587 Automake provides support for GNU Libtool (@pxref{Top, , Introduction,
7588 libtool, The Libtool Manual}) with the @code{LTLIBRARIES} primary.
7589 @xref{A Shared Library}.
7593 @section Java bytecode compilation (deprecated)
7595 @cindex @code{_JAVA} primary, defined
7596 @cindex @code{JAVA} primary, defined
7597 @cindex Primary variable, @code{JAVA}
7598 @cindex Java to bytecode, compilation
7599 @cindex Compilation of Java to bytecode
7601 Automake provides some minimal support for Java bytecode compilation with
7602 the @code{JAVA} primary (in addition to the support for compiling Java to
7603 native machine code; @pxref{Java Support with gcj}). Note however that
7604 @emph{the interface and most features described here are deprecated}; the
7605 next automake release will strive to provide a better and cleaner
7606 interface, which however @emph{won't be backward-compatible}; the present
7607 interface will probably be removed altogether in future automake releases
7608 (1.13 or later), so don't use it in new code.
7610 Any @file{.java} files listed in a @code{_JAVA} variable will be
7611 compiled with @code{JAVAC} at build time. By default, @file{.java}
7612 files are not included in the distribution, you should use the
7613 @code{dist_} prefix to distribute them.
7615 Here is a typical setup for distributing @file{.java} files and
7616 installing the @file{.class} files resulting from their compilation.
7618 @c Keep in sync with primary-prefix-couples-documented-valid.sh
7620 javadir = $(datadir)/java
7621 dist_java_JAVA = a.java b.java @dots{}
7624 @cindex @code{JAVA} restrictions
7625 @cindex Restrictions for @code{JAVA}
7627 Currently Automake enforces the restriction that only one @code{_JAVA}
7628 primary can be used in a given @file{Makefile.am}. The reason for this
7629 restriction is that, in general, it isn't possible to know which
7630 @file{.class} files were generated from which @file{.java} files, so
7631 it would be impossible to know which files to install where. For
7632 instance, a @file{.java} file can define multiple classes; the resulting
7633 @file{.class} file names cannot be predicted without parsing the
7636 There are a few variables that are used when compiling Java sources:
7640 The name of the Java compiler. This defaults to @samp{javac}.
7643 The flags to pass to the compiler. This is considered to be a user
7644 variable (@pxref{User Variables}).
7647 More flags to pass to the Java compiler. This, and not
7648 @code{JAVACFLAGS}, should be used when it is necessary to put Java
7649 compiler flags into @file{Makefile.am}.
7652 The value of this variable is passed to the @option{-d} option to
7653 @code{javac}. It defaults to @samp{$(top_builddir)}.
7656 This variable is a shell expression that is used to set the
7657 @env{CLASSPATH} environment variable on the @code{javac} command line.
7658 (In the future we will probably handle class path setting differently.)
7665 @cindex @code{_PYTHON} primary, defined
7666 @cindex @code{PYTHON} primary, defined
7667 @cindex Primary variable, @code{PYTHON}
7670 Automake provides support for Python compilation with the
7671 @code{PYTHON} primary. A typical setup is to call
7672 @code{AM_PATH_PYTHON} in @file{configure.ac} and use a line like the
7673 following in @file{Makefile.am}:
7676 python_PYTHON = tree.py leave.py
7679 Any files listed in a @code{_PYTHON} variable will be byte-compiled
7680 with @command{py-compile} at install time. @command{py-compile}
7681 actually creates both standard (@file{.pyc}) and optimized
7682 (@file{.pyo}) byte-compiled versions of the source files. Note that
7683 because byte-compilation occurs at install time, any files listed in
7684 @code{noinst_PYTHON} will not be compiled. Python source files are
7685 included in the distribution by default, prepend @code{nodist_} (as in
7686 @code{nodist_python_PYTHON}) to omit them.
7688 Automake ships with an Autoconf macro called @code{AM_PATH_PYTHON}
7689 that will determine some Python-related directory variables (see
7690 below). If you have called @code{AM_PATH_PYTHON} from
7691 @file{configure.ac}, then you may use the variables
7692 @c Keep in sync with primary-prefix-couples-documented-valid.sh
7693 @code{python_PYTHON} or @code{pkgpython_PYTHON} to list Python source
7694 files in your @file{Makefile.am}, depending on where you want your files
7695 installed (see the definitions of @code{pythondir} and
7696 @code{pkgpythondir} below).
7698 @defmac AM_PATH_PYTHON (@ovar{version}, @ovar{action-if-found},
7699 @ovar{action-if-not-found})
7701 Search for a Python interpreter on the system. This macro takes three
7702 optional arguments. The first argument, if present, is the minimum
7703 version of Python required for this package: @code{AM_PATH_PYTHON}
7704 will skip any Python interpreter that is older than @var{version}.
7705 If an interpreter is found and satisfies @var{version}, then
7706 @var{action-if-found} is run. Otherwise, @var{action-if-not-found} is
7709 If @var{action-if-not-found} is not specified, as in the following
7710 example, the default is to abort @command{configure}.
7713 AM_PATH_PYTHON([2.2])
7717 This is fine when Python is an absolute requirement for the package.
7718 If Python >= 2.5 was only @emph{optional} to the package,
7719 @code{AM_PATH_PYTHON} could be called as follows.
7722 AM_PATH_PYTHON([2.5],, [:])
7725 If the @env{PYTHON} variable is set when @code{AM_PATH_PYTHON} is
7726 called, then that will be the only Python interpreter that is tried.
7728 @code{AM_PATH_PYTHON} creates the following output variables based on
7729 the Python installation found during configuration.
7734 The name of the Python executable, or @samp{:} if no suitable
7735 interpreter could be found.
7737 Assuming @var{action-if-not-found} is used (otherwise @file{./configure}
7738 will abort if Python is absent), the value of @code{PYTHON} can be used
7739 to setup a conditional in order to disable the relevant part of a build
7743 AM_PATH_PYTHON(,, [:])
7744 AM_CONDITIONAL([HAVE_PYTHON], [test "$PYTHON" != :])
7747 @item PYTHON_VERSION
7748 The Python version number, in the form @var{major}.@var{minor}
7749 (e.g., @samp{2.5}). This is currently the value of
7750 @samp{sys.version[:3]}.
7753 The string @samp{$@{prefix@}}. This term may be used in future work
7754 that needs the contents of Python's @samp{sys.prefix}, but general
7755 consensus is to always use the value from @command{configure}.
7757 @item PYTHON_EXEC_PREFIX
7758 The string @samp{$@{exec_prefix@}}. This term may be used in future work
7759 that needs the contents of Python's @samp{sys.exec_prefix}, but general
7760 consensus is to always use the value from @command{configure}.
7762 @item PYTHON_PLATFORM
7763 The canonical name used by Python to describe the operating system, as
7764 given by @samp{sys.platform}. This value is sometimes needed when
7765 building Python extensions.
7768 The directory name for the @file{site-packages} subdirectory of the
7769 standard Python install tree.
7772 This is the directory under @code{pythondir} that is named after the
7773 package. That is, it is @samp{$(pythondir)/$(PACKAGE)}. It is provided
7777 This is the directory where Python extension modules (shared libraries)
7778 should be installed. An extension module written in C could be declared
7779 as follows to Automake:
7781 @c Keep in sync with primary-prefix-couples-documented-valid.sh
7783 pyexec_LTLIBRARIES = quaternion.la
7784 quaternion_la_SOURCES = quaternion.c support.c support.h
7785 quaternion_la_LDFLAGS = -avoid-version -module
7789 This is a convenience variable that is defined as
7790 @samp{$(pyexecdir)/$(PACKAGE)}.
7793 All of these directory variables have values that start with either
7794 @samp{$@{prefix@}} or @samp{$@{exec_prefix@}} unexpanded. This works
7795 fine in @file{Makefiles}, but it makes these variables hard to use in
7796 @file{configure}. This is mandated by the GNU coding standards, so
7797 that the user can run @samp{make prefix=/foo install}. The Autoconf
7798 manual has a section with more details on this topic
7799 (@pxref{Installation Directory Variables, , Installation Directory
7800 Variables, autoconf, The Autoconf Manual}). See also @ref{Hard-Coded
7805 @chapter Building documentation
7807 Currently Automake provides support for Texinfo and man pages.
7811 * Man Pages:: Man pages
7818 @cindex @code{_TEXINFOS} primary, defined
7819 @cindex @code{TEXINFOS} primary, defined
7820 @cindex Primary variable, @code{TEXINFOS}
7821 @cindex HTML output using Texinfo
7822 @cindex PDF output using Texinfo
7823 @cindex PS output using Texinfo
7824 @cindex DVI output using Texinfo
7826 @vindex info_TEXINFOS
7828 If the current directory contains Texinfo source, you must declare it
7829 with the @code{TEXINFOS} primary. Generally Texinfo files are converted
7830 into info, and thus the @code{info_TEXINFOS} variable is most commonly used
7831 here. Any Texinfo source file should have the @file{.texi} extension.
7832 Automake also accepts @file{.txi} or @file{.texinfo} extensions, but their
7833 use is discouraged now, and will elicit runtime warnings.
7835 Automake generates rules to build @file{.info}, @file{.dvi},
7836 @file{.ps}, @file{.pdf} and @file{.html} files from your Texinfo
7837 sources. Following the GNU Coding Standards, only the @file{.info}
7838 files are built by @samp{make all} and installed by @samp{make
7839 install} (unless you use @option{no-installinfo}, see below).
7840 Furthermore, @file{.info} files are automatically distributed so that
7841 Texinfo is not a prerequisite for installing your package.
7843 It is worth noting that, contrary to what happens with the other formats,
7844 the generated @file{.info} files are by default placed in @code{srcdir}
7845 rather than in the @code{builddir}. This can be changed with the
7846 @option{info-in-builddir} option.
7852 @trindex install-dvi
7853 @trindex install-html
7854 @trindex install-pdf
7856 Other documentation formats can be built on request by @samp{make
7857 dvi}, @samp{make ps}, @samp{make pdf} and @samp{make html}, and they
7858 can be installed with @samp{make install-dvi}, @samp{make install-ps},
7859 @samp{make install-pdf} and @samp{make install-html} explicitly.
7860 @samp{make uninstall} will remove everything: the Texinfo
7861 documentation installed by default as well as all the above optional
7864 All of these targets can be extended using @samp{-local} rules
7865 (@pxref{Extending}).
7867 @cindex Texinfo flag, @code{VERSION}
7868 @cindex Texinfo flag, @code{UPDATED}
7869 @cindex Texinfo flag, @code{EDITION}
7870 @cindex Texinfo flag, @code{UPDATED-MONTH}
7872 @cindex @code{VERSION} Texinfo flag
7873 @cindex @code{UPDATED} Texinfo flag
7874 @cindex @code{EDITION} Texinfo flag
7875 @cindex @code{UPDATED-MONTH} Texinfo flag
7877 @cindex @file{mdate-sh}
7879 If the @file{.texi} file @code{@@include}s @file{version.texi}, then
7880 that file will be automatically generated. The file @file{version.texi}
7881 defines four Texinfo flag you can reference using
7882 @code{@@value@{EDITION@}}, @code{@@value@{VERSION@}},
7883 @code{@@value@{UPDATED@}}, and @code{@@value@{UPDATED-MONTH@}}.
7888 Both of these flags hold the version number of your program. They are
7889 kept separate for clarity.
7892 This holds the date the primary @file{.texi} file was last modified.
7895 This holds the name of the month in which the primary @file{.texi} file
7899 The @file{version.texi} support requires the @command{mdate-sh}
7900 script; this script is supplied with Automake and automatically
7901 included when @command{automake} is invoked with the
7902 @option{--add-missing} option.
7904 If you have multiple Texinfo files, and you want to use the
7905 @file{version.texi} feature, then you have to have a separate version
7906 file for each Texinfo file. Automake will treat any include in a
7907 Texinfo file that matches @file{vers*.texi} just as an automatically
7908 generated version file.
7910 Sometimes an info file actually depends on more than one @file{.texi}
7911 file. For instance, in GNU Hello, @file{hello.texi} includes the file
7912 @file{fdl.texi}. You can tell Automake about these dependencies using
7913 the @code{@var{texi}_TEXINFOS} variable. Here is how GNU Hello does it:
7918 info_TEXINFOS = hello.texi
7919 hello_TEXINFOS = fdl.texi
7922 @cindex @file{texinfo.tex}
7924 By default, Automake requires the file @file{texinfo.tex} to appear in
7925 the same directory as the @file{Makefile.am} file that lists the
7926 @file{.texi} files. If you used @code{AC_CONFIG_AUX_DIR} in
7927 @file{configure.ac} (@pxref{Input, , Finding `configure' Input,
7928 autoconf, The Autoconf Manual}), then @file{texinfo.tex} is looked for
7929 there. In both cases, @command{automake} then supplies @file{texinfo.tex} if
7930 @option{--add-missing} is given, and takes care of its distribution.
7931 However, if you set the @code{TEXINFO_TEX} variable (see below),
7932 it overrides the location of the file and turns off its installation
7933 into the source as well as its distribution.
7935 The option @option{no-texinfo.tex} can be used to eliminate the
7936 requirement for the file @file{texinfo.tex}. Use of the variable
7937 @code{TEXINFO_TEX} is preferable, however, because that allows the
7938 @code{dvi}, @code{ps}, and @code{pdf} targets to still work.
7940 @cindex Option, @code{no-installinfo}
7941 @cindex Target, @code{install-info}
7942 @cindex @code{install-info} target
7943 @cindex @code{no-installinfo} option
7945 @opindex no-installinfo
7946 @trindex install-info
7948 Automake generates an @code{install-info} rule; some people apparently
7949 use this. By default, info pages are installed by @samp{make
7950 install}, so running @code{make install-info} is pointless. This can
7951 be prevented via the @code{no-installinfo} option. In this case,
7952 @file{.info} files are not installed by default, and user must
7953 request this explicitly using @samp{make install-info}.
7955 @vindex AM_UPDATE_INFO_DIR
7956 By default, @code{make install-info} and @code{make uninstall-info}
7957 will try to run the @command{install-info} program (if available) to
7958 update (or create/remove) the @file{@code{$@{infodir@}}/dir} index.
7959 If this is undesired, it can be prevented by exporting the
7960 @code{AM_UPDATE_INFO_DIR} variable to "@code{no}".
7962 The following variables are used by the Texinfo build rules.
7966 The name of the program invoked to build @file{.info} files. This
7967 variable is defined by Automake. If the @command{makeinfo} program is
7968 found on the system then it will be used by default; otherwise
7969 @command{missing} will be used instead.
7972 The command invoked to build @file{.html} files. Automake
7973 defines this to @samp{$(MAKEINFO) --html}.
7976 User flags passed to each invocation of @samp{$(MAKEINFO)} and
7977 @samp{$(MAKEINFOHTML)}. This user variable (@pxref{User Variables}) is
7978 not expected to be defined in any @file{Makefile}; it can be used by
7979 users to pass extra flags to suit their needs.
7981 @item AM_MAKEINFOFLAGS
7982 @itemx AM_MAKEINFOHTMLFLAGS
7983 Maintainer flags passed to each @command{makeinfo} invocation. Unlike
7984 @code{MAKEINFOFLAGS}, these variables are meant to be defined by
7985 maintainers in @file{Makefile.am}. @samp{$(AM_MAKEINFOFLAGS)} is
7986 passed to @code{makeinfo} when building @file{.info} files; and
7987 @samp{$(AM_MAKEINFOHTMLFLAGS)} is used when building @file{.html}
7990 @c Keep in sync with txinfo-many-output-formats.sh
7991 For instance, the following setting can be used to obtain one single
7992 @file{.html} file per manual, without node separators.
7994 AM_MAKEINFOHTMLFLAGS = --no-headers --no-split
7997 @code{AM_MAKEINFOHTMLFLAGS} defaults to @samp{$(AM_MAKEINFOFLAGS)}.
7998 This means that defining @code{AM_MAKEINFOFLAGS} without defining
7999 @code{AM_MAKEINFOHTMLFLAGS} will impact builds of both @file{.info}
8000 and @file{.html} files.
8003 The name of the command that converts a @file{.texi} file into a
8004 @file{.dvi} file. This defaults to @samp{texi2dvi}, a script that ships
8005 with the Texinfo package.
8008 The name of the command that translates a @file{.texi} file into a
8009 @file{.pdf} file. This defaults to @samp{$(TEXI2DVI) --pdf --batch}.
8012 The name of the command that builds a @file{.ps} file out of a
8013 @file{.dvi} file. This defaults to @samp{dvips}.
8017 If your package has Texinfo files in many directories, you can use the
8018 variable @code{TEXINFO_TEX} to tell Automake where to find the canonical
8019 @file{texinfo.tex} for your package. The value of this variable should
8020 be the relative path from the current @file{Makefile.am} to
8024 TEXINFO_TEX = ../doc/texinfo.tex
8032 @cindex @code{_MANS} primary, defined
8033 @cindex @code{MANS} primary, defined
8034 @cindex Primary variable, @code{MANS}
8038 A package can also include man pages (but see the GNU standards on this
8039 matter, @ref{Man Pages, , , standards, The GNU Coding Standards}.) Man
8040 pages are declared using the @code{MANS} primary. Generally the
8041 @code{man_MANS} variable is used. Man pages are automatically installed in
8042 the correct subdirectory of @code{mandir}, based on the file extension.
8044 File extensions such as @file{.1c} are handled by looking for the valid
8045 part of the extension and using that to determine the correct
8046 subdirectory of @code{mandir}. Valid section names are the digits
8047 @samp{0} through @samp{9}, and the letters @samp{l} and @samp{n}.
8049 Sometimes developers prefer to name a man page something like
8050 @file{foo.man} in the source, and then rename it to have the correct
8051 suffix, for example @file{foo.1}, when installing the file. Automake
8052 also supports this mode. For a valid section named @var{section},
8053 there is a corresponding directory named @samp{man@var{section}dir},
8054 and a corresponding @code{_MANS} variable. Files listed in such a
8055 variable are installed in the indicated section. If the file already
8056 has a valid suffix, then it is installed as-is; otherwise the file
8057 suffix is changed to match the section.
8059 For instance, consider this example:
8061 man1_MANS = rename.man thesame.1 alsothesame.1c
8065 In this case, @file{rename.man} will be renamed to @file{rename.1} when
8066 installed, but the other files will keep their names.
8068 @cindex Target, @code{install-man}
8069 @cindex Option, @option{no-installman}
8070 @cindex @code{install-man} target
8071 @cindex @option{no-installman} option
8072 @opindex no-installman
8073 @trindex install-man
8075 By default, man pages are installed by @samp{make install}. However,
8076 since the GNU project does not require man pages, many maintainers do
8077 not expend effort to keep the man pages up to date. In these cases, the
8078 @option{no-installman} option will prevent the man pages from being
8079 installed by default. The user can still explicitly install them via
8080 @samp{make install-man}.
8082 For fast installation, with many files it is preferable to use
8083 @samp{man@var{section}_MANS} over @samp{man_MANS} as well as files that
8084 do not need to be renamed.
8086 Man pages are not currently considered to be source, because it is not
8087 uncommon for man pages to be automatically generated. Therefore they
8088 are not automatically included in the distribution. However, this can
8089 be changed by use of the @code{dist_} prefix. For instance here is
8090 how to distribute and install the two man pages of GNU @command{cpio}
8091 (which includes both Texinfo documentation and man pages):
8094 dist_man_MANS = cpio.1 mt.1
8097 The @code{nobase_} prefix is meaningless for man pages and is
8101 @cindex @code{notrans_} prefix
8102 @cindex Man page renaming, avoiding
8103 @cindex Avoiding man page renaming
8105 Executables and manpages may be renamed upon installation
8106 (@pxref{Renaming}). For manpages this can be avoided by use of the
8107 @code{notrans_} prefix. For instance, suppose an executable @samp{foo}
8108 allowing to access a library function @samp{foo} from the command line.
8109 The way to avoid renaming of the @file{foo.3} manpage is:
8113 notrans_man_MANS = foo.3
8116 @cindex @code{notrans_} and @code{dist_} or @code{nodist_}
8117 @cindex @code{dist_} and @code{notrans_}
8118 @cindex @code{nodist_} and @code{notrans_}
8120 @samp{notrans_} must be specified first when used in conjunction with
8121 either @samp{dist_} or @samp{nodist_} (@pxref{Fine-grained Distribution
8122 Control}). For instance:
8125 notrans_dist_man3_MANS = bar.3
8129 @chapter What Gets Installed
8131 @cindex Installation support
8132 @cindex @samp{make install} support
8134 Naturally, Automake handles the details of actually installing your
8135 program once it has been built. All files named by the various
8136 primaries are automatically installed in the appropriate places when the
8137 user runs @samp{make install}.
8140 * Basics of Installation:: What gets installed where
8141 * The Two Parts of Install:: Installing data and programs separately
8142 * Extending Installation:: Adding your own rules for installation
8143 * Staged Installs:: Installation in a temporary location
8144 * Install Rules for the User:: Useful additional rules
8147 @node Basics of Installation
8148 @section Basics of Installation
8150 A file named in a primary is installed by copying the built file into
8151 the appropriate directory. The base name of the file is used when
8155 bin_PROGRAMS = hello subdir/goodbye
8158 In this example, both @samp{hello} and @samp{goodbye} will be installed
8159 in @samp{$(bindir)}.
8161 Sometimes it is useful to avoid the basename step at install time. For
8162 instance, you might have a number of header files in subdirectories of
8163 the source tree that are laid out precisely how you want to install
8164 them. In this situation you can use the @code{nobase_} prefix to
8165 suppress the base name step. For example:
8168 nobase_include_HEADERS = stdio.h sys/types.h
8172 will install @file{stdio.h} in @samp{$(includedir)} and @file{types.h}
8173 in @samp{$(includedir)/sys}.
8175 For most file types, Automake will install multiple files at once, while
8176 avoiding command line length issues (@pxref{Length Limitations}). Since
8177 some @command{install} programs will not install the same file twice in
8178 one invocation, you may need to ensure that file lists are unique within
8179 one variable such as @samp{nobase_include_HEADERS} above.
8181 You should not rely on the order in which files listed in one variable
8182 are installed. Likewise, to cater for parallel make, you should not
8183 rely on any particular file installation order even among different
8184 file types (library dependencies are an exception here).
8187 @node The Two Parts of Install
8188 @section The Two Parts of Install
8190 Automake generates separate @code{install-data} and @code{install-exec}
8191 rules, in case the installer is installing on multiple machines that
8192 share directory structure---these targets allow the machine-independent
8193 parts to be installed only once. @code{install-exec} installs
8194 platform-dependent files, and @code{install-data} installs
8195 platform-independent files. The @code{install} target depends on both
8196 of these targets. While Automake tries to automatically segregate
8197 objects into the correct category, the @file{Makefile.am} author is, in
8198 the end, responsible for making sure this is done correctly.
8199 @trindex install-data
8200 @trindex install-exec
8202 @cindex Install, two parts of
8204 Variables using the standard directory prefixes @samp{data},
8205 @samp{info}, @samp{man}, @samp{include}, @samp{oldinclude},
8206 @samp{pkgdata}, or @samp{pkginclude} are installed by
8207 @code{install-data}.
8209 Variables using the standard directory prefixes @samp{bin},
8210 @samp{sbin}, @samp{libexec}, @samp{sysconf}, @samp{localstate},
8211 @samp{lib}, or @samp{pkglib} are installed by @code{install-exec}.
8213 For instance, @code{data_DATA} files are installed by @code{install-data},
8214 while @code{bin_PROGRAMS} files are installed by @code{install-exec}.
8216 Any variable using a user-defined directory prefix with
8217 @samp{exec} in the name (e.g.,
8218 @c Keep in sync with primary-prefix-couples-documented-valid.sh
8219 @code{myexecbin_PROGRAMS}) is installed by @code{install-exec}. All
8220 other user-defined prefixes are installed by @code{install-data}.
8222 @node Extending Installation
8223 @section Extending Installation
8225 It is possible to extend this mechanism by defining an
8226 @code{install-exec-local} or @code{install-data-local} rule. If these
8227 rules exist, they will be run at @samp{make install} time. These
8228 rules can do almost anything; care is required.
8229 @trindex install-exec-local
8230 @trindex install-data-local
8232 Automake also supports two install hooks, @code{install-exec-hook} and
8233 @code{install-data-hook}. These hooks are run after all other install
8234 rules of the appropriate type, exec or data, have completed. So, for
8235 instance, it is possible to perform post-installation modifications
8236 using an install hook. @xref{Extending}, for some examples.
8237 @cindex Install hook
8239 @node Staged Installs
8240 @section Staged Installs
8243 Automake generates support for the @code{DESTDIR} variable in all
8244 install rules. @code{DESTDIR} is used during the @samp{make install}
8245 step to relocate install objects into a staging area. Each object and
8246 path is prefixed with the value of @code{DESTDIR} before being copied
8247 into the install area. Here is an example of typical DESTDIR usage:
8250 mkdir /tmp/staging &&
8251 make DESTDIR=/tmp/staging install
8254 The @command{mkdir} command avoids a security problem if the attacker
8255 creates a symbolic link from @file{/tmp/staging} to a victim area;
8256 then @command{make} places install objects in a directory tree built under
8257 @file{/tmp/staging}. If @file{/gnu/bin/foo} and
8258 @file{/gnu/share/aclocal/foo.m4} are to be installed, the above command
8259 would install @file{/tmp/staging/gnu/bin/foo} and
8260 @file{/tmp/staging/gnu/share/aclocal/foo.m4}.
8262 This feature is commonly used to build install images and packages
8265 Support for @code{DESTDIR} is implemented by coding it directly into
8266 the install rules. If your @file{Makefile.am} uses a local install
8267 rule (e.g., @code{install-exec-local}) or an install hook, then you
8268 must write that code to respect @code{DESTDIR}.
8270 @xref{Makefile Conventions, , , standards, The GNU Coding Standards},
8271 for another usage example.
8273 @node Install Rules for the User
8274 @section Install Rules for the User
8276 Automake also generates rules for targets @code{uninstall},
8277 @code{installdirs}, and @code{install-strip}.
8279 @trindex installdirs
8280 @trindex install-strip
8282 Automake supports @code{uninstall-local} and @code{uninstall-hook}.
8283 There is no notion of separate uninstalls for ``exec'' and ``data'', as
8284 these features would not provide additional functionality.
8286 Note that @code{uninstall} is not meant as a replacement for a real
8291 @chapter What Gets Cleaned
8293 @cindex @samp{make clean} support
8295 The GNU Makefile Standards specify a number of different clean rules.
8296 @xref{Standard Targets, , Standard Targets for Users, standards,
8297 The GNU Coding Standards}.
8299 Generally the files that can be cleaned are determined automatically by
8300 Automake. Of course, Automake also recognizes some variables that can
8301 be defined to specify additional files to clean. These variables are
8302 @code{MOSTLYCLEANFILES}, @code{CLEANFILES}, @code{DISTCLEANFILES}, and
8303 @code{MAINTAINERCLEANFILES}.
8304 @vindex MOSTLYCLEANFILES
8306 @vindex DISTCLEANFILES
8307 @vindex MAINTAINERCLEANFILES
8309 @trindex mostlyclean-local
8310 @trindex clean-local
8311 @trindex distclean-local
8312 @trindex maintainer-clean-local
8313 When cleaning involves more than deleting some hard-coded list of
8314 files, it is also possible to supplement the cleaning rules with your
8315 own commands. Simply define a rule for any of the
8316 @code{mostlyclean-local}, @code{clean-local}, @code{distclean-local},
8317 or @code{maintainer-clean-local} targets (@pxref{Extending}). A common
8318 case is deleting a directory, for instance, a directory created by the
8326 Since @command{make} allows only one set of rules for a given target,
8327 a more extensible way of writing this is to use a separate target
8328 listed as a dependency:
8331 clean-local: clean-local-check
8332 .PHONY: clean-local-check
8337 As the GNU Standards aren't always explicit as to which files should
8338 be removed by which rule, we've adopted a heuristic that we believe
8339 was first formulated by Fran@,{c}ois Pinard:
8343 If @command{make} built it, and it is commonly something that one would
8344 want to rebuild (for instance, a @file{.o} file), then
8345 @code{mostlyclean} should delete it.
8348 Otherwise, if @command{make} built it, then @code{clean} should delete it.
8351 If @command{configure} built it, then @code{distclean} should delete it.
8354 If the maintainer built it (for instance, a @file{.info} file), then
8355 @code{maintainer-clean} should delete it. However
8356 @code{maintainer-clean} should not delete anything that needs to exist
8357 in order to run @samp{./configure && make}.
8360 We recommend that you follow this same set of heuristics in your
8365 @chapter What Goes in a Distribution
8368 * Basics of Distribution:: Files distributed by default
8369 * Fine-grained Distribution Control:: @code{dist_} and @code{nodist_} prefixes
8370 * The dist Hook:: A target for last-minute distribution changes
8371 * Checking the Distribution:: @samp{make distcheck} explained
8372 * The Types of Distributions:: A variety of formats and compression methods
8375 @node Basics of Distribution
8376 @section Basics of Distribution
8378 @cindex @samp{make dist}
8383 The @code{dist} rule in the generated @file{Makefile.in} can be used
8384 to generate a gzipped @code{tar} file and other flavors of archive for
8385 distribution. The file is named based on the @code{PACKAGE} and
8386 @code{VERSION} variables defined by @code{AM_INIT_AUTOMAKE}
8387 (@pxref{Macros}); more precisely the gzipped @code{tar} file is named
8388 @samp{@var{package}-@var{version}.tar.gz}.
8390 You can use the @command{make} variable @code{GZIP_ENV} to control how gzip
8391 is run. The default setting is @option{--best}.
8393 @cindex @code{m4_include}, distribution
8394 @cindex @code{include}, distribution
8397 For the most part, the files to distribute are automatically found by
8398 Automake: all source files are automatically included in a distribution,
8399 as are all @file{Makefile.am} and @file{Makefile.in} files. Automake also
8400 has a built-in list of commonly used files that are automatically
8401 included if they are found in the current directory (either physically,
8402 or as the target of a @file{Makefile.am} rule); this list is printed by
8403 @samp{automake --help}. Note that some files in this list are actually
8404 distributed only if other certain conditions hold (for example,
8405 @c Keep in sync with autodist-config-headers.sh
8406 the @file{config.h.top} and @file{config.h.bot} files are automatically
8407 distributed only if, e.g., @samp{AC_CONFIG_HEADERS([config.h])} is used
8408 in @file{configure.ac}). Also, files that are read by @command{configure}
8409 (i.e.@: the source files corresponding to the files specified in various
8410 Autoconf macros such as @code{AC_CONFIG_FILES} and siblings) are
8411 automatically distributed. Files included in a @file{Makefile.am} (using
8412 @code{include}) or in @file{configure.ac} (using @code{m4_include}), and
8413 helper scripts installed with @samp{automake --add-missing} are also
8417 Still, sometimes there are files that must be distributed, but which
8418 are not covered in the automatic rules. These files should be listed in
8419 the @code{EXTRA_DIST} variable. You can mention files from
8420 subdirectories in @code{EXTRA_DIST}.
8422 You can also mention a directory in @code{EXTRA_DIST}; in this case the
8423 entire directory will be recursively copied into the distribution.
8424 Please note that this will also copy @emph{everything} in the directory,
8425 including, e.g., Subversion's @file{.svn} private directories or CVS/RCS
8426 version control files; thus we recommend against using this feature
8427 as-is. However, you can use the @code{dist-hook} feature to
8428 ameliorate the problem; @pxref{The dist Hook}.
8431 @vindex DIST_SUBDIRS
8432 If you define @code{SUBDIRS}, Automake will recursively include the
8433 subdirectories in the distribution. If @code{SUBDIRS} is defined
8434 conditionally (@pxref{Conditionals}), Automake will normally include
8435 all directories that could possibly appear in @code{SUBDIRS} in the
8436 distribution. If you need to specify the set of directories
8437 conditionally, you can set the variable @code{DIST_SUBDIRS} to the
8438 exact list of subdirectories to include in the distribution
8439 (@pxref{Conditional Subdirectories}).
8442 @node Fine-grained Distribution Control
8443 @section Fine-grained Distribution Control
8447 Sometimes you need tighter control over what does @emph{not} go into the
8448 distribution; for instance, you might have source files that are
8449 generated and that you do not want to distribute. In this case
8450 Automake gives fine-grained control using the @code{dist} and
8451 @code{nodist} prefixes. Any primary or @code{_SOURCES} variable can be
8452 prefixed with @code{dist_} to add the listed files to the distribution.
8453 Similarly, @code{nodist_} can be used to omit the files from the
8456 As an example, here is how you would cause some data to be distributed
8457 while leaving some source code out of the distribution:
8460 dist_data_DATA = distribute-this
8462 nodist_foo_SOURCES = do-not-distribute.c
8466 @section The dist Hook
8470 Occasionally it is useful to be able to change the distribution before
8471 it is packaged up. If the @code{dist-hook} rule exists, it is run
8472 after the distribution directory is filled, but before the actual
8473 distribution archives are created. One way to use this is for
8474 removing unnecessary files that get recursively included by specifying
8475 a directory in @code{EXTRA_DIST}:
8480 rm -rf `find $(distdir)/doc -type d -name .svn`
8483 @c The caveates described here should be documented in 'disthook.sh'.
8485 Note that the @code{dist-hook} recipe shouldn't assume that the regular
8486 files in the distribution directory are writable; this might not be the
8487 case if one is packaging from a read-only source tree, or when a
8488 @code{make distcheck} is being done. For similar reasons, the recipe
8489 shouldn't assume that the subdirectories put into the distribution
8490 directory as effect of having them listed in @code{EXTRA_DIST} are
8491 writable. So, if the @code{dist-hook} recipe wants to modify the
8492 content of an existing file (or @code{EXTRA_DIST} subdirectory) in the
8493 distribution directory, it should explicitly to make it writable first:
8496 EXTRA_DIST = README doc
8498 chmod u+w $(distdir)/README $(distdir)/doc
8499 echo "Distribution date: `date`" >> README
8500 rm -f $(distdir)/doc/HACKING
8505 Two variables that come handy when writing @code{dist-hook} rules are
8506 @samp{$(distdir)} and @samp{$(top_distdir)}.
8508 @samp{$(distdir)} points to the directory where the @code{dist} rule
8509 will copy files from the current directory before creating the
8510 tarball. If you are at the top-level directory, then @samp{distdir =
8511 $(PACKAGE)-$(VERSION)}. When used from subdirectory named
8512 @file{foo/}, then @samp{distdir = ../$(PACKAGE)-$(VERSION)/foo}.
8513 @samp{$(distdir)} can be a relative or absolute path, do not assume
8516 @samp{$(top_distdir)} always points to the root directory of the
8517 distributed tree. At the top-level it's equal to @samp{$(distdir)}.
8518 In the @file{foo/} subdirectory
8519 @samp{top_distdir = ../$(PACKAGE)-$(VERSION)}.
8520 @samp{$(top_distdir)} too can be a relative or absolute path.
8522 Note that when packages are nested using @code{AC_CONFIG_SUBDIRS}
8523 (@pxref{Subpackages}), then @samp{$(distdir)} and
8524 @samp{$(top_distdir)} are relative to the package where @samp{make
8525 dist} was run, not to any sub-packages involved.
8527 @node Checking the Distribution
8528 @section Checking the Distribution
8530 @cindex @samp{make distcheck}
8532 Automake also generates a @code{distcheck} rule that can be of help
8533 to ensure that a given distribution will actually work. Simplifying
8534 a bit, we can say this rule first makes a distribution, and then,
8535 @emph{operating from it}, takes the following steps:
8538 tries to do a @code{VPATH} build (@pxref{VPATH Builds}), with the
8539 @code{srcdir} and all its content made @emph{read-only};
8541 runs the test suite (with @command{make check}) on this fresh build;
8543 installs the package in a temporary directory (with @command{make
8544 install}), and tries runs the test suite on the resulting installation
8545 (with @command{make installcheck});
8547 checks that the package can be correctly uninstalled (by @command{make
8548 uninstall}) and cleaned (by @code{make distclean});
8550 finally, makes another tarball to ensure the distribution is
8554 @vindex AM_DISTCHECK_CONFIGURE_FLAGS
8555 @vindex DISTCHECK_CONFIGURE_FLAGS
8556 @subheading DISTCHECK_CONFIGURE_FLAGS
8557 Building the package involves running @samp{./configure}. If you need
8558 to supply additional flags to @command{configure}, define them in the
8559 @code{AM_DISTCHECK_CONFIGURE_FLAGS} variable in your top-level
8560 @file{Makefile.am}. The user can still extend or override the flags
8561 provided there by defining the @code{DISTCHECK_CONFIGURE_FLAGS} variable,
8562 on the command line when invoking @command{make}.
8564 Still, developers are encouraged to strive to make their code buildable
8565 without requiring any special configure option; thus, in general, you
8566 shouldn't define @code{AM_DISTCHECK_CONFIGURE_FLAGS}. However, there
8567 might be few scenarios in which the use of this variable is justified.
8568 GNU @command{m4} offers an example. GNU @command{m4} configures by
8569 default with its experimental and seldom used "changeword" feature
8570 disabled; so in its case it is useful to have @command{make distcheck}
8571 run configure with the @option{--with-changeword} option, to ensure that
8572 the code for changeword support still compiles correctly.
8573 GNU @command{m4} also employs the @code{AM_DISTCHECK_CONFIGURE_FLAGS}
8574 variable to stress-test the use of @option{--program-prefix=g}, since at
8575 one point the @command{m4} build system had a bug where @command{make
8576 installcheck} was wrongly assuming it could blindly test "@command{m4}",
8577 rather than the just-installed "@command{gm4}".
8579 @trindex distcheck-hook
8580 @subheading distcheck-hook
8581 If the @code{distcheck-hook} rule is defined in your top-level
8582 @file{Makefile.am}, then it will be invoked by @code{distcheck} after
8583 the new distribution has been unpacked, but before the unpacked copy
8584 is configured and built. Your @code{distcheck-hook} can do almost
8585 anything, though as always caution is advised. Generally this hook is
8586 used to check for potential distribution errors not caught by the
8587 standard mechanism. Note that @code{distcheck-hook} as well as
8588 @code{AM_DISTCHECK_CONFIGURE_FLAGS} and @code{DISTCHECK_CONFIGURE_FLAGS}
8589 are not honored in a subpackage @file{Makefile.am}, but the flags from
8590 @code{AM_DISTCHECK_CONFIGURE_FLAGS} and @code{DISTCHECK_CONFIGURE_FLAGS}
8591 are passed down to the @command{configure} script of the subpackage.
8593 @cindex @samp{make distcleancheck}
8594 @trindex distcleancheck
8595 @vindex DISTCLEANFILES
8596 @vindex distcleancheck_listfiles
8598 @subheading distcleancheck
8599 Speaking of potential distribution errors, @code{distcheck} also
8600 ensures that the @code{distclean} rule actually removes all built
8601 files. This is done by running @samp{make distcleancheck} at the end of
8602 the @code{VPATH} build. By default, @code{distcleancheck} will run
8603 @code{distclean} and then make sure the build tree has been emptied by
8604 running @samp{$(distcleancheck_listfiles)}. Usually this check will
8605 find generated files that you forgot to add to the @code{DISTCLEANFILES}
8606 variable (@pxref{Clean}).
8608 The @code{distcleancheck} behavior should be OK for most packages,
8609 otherwise you have the possibility to override the definition of
8610 either the @code{distcleancheck} rule, or the
8611 @samp{$(distcleancheck_listfiles)} variable. For instance, to disable
8612 @code{distcleancheck} completely, add the following rule to your
8613 top-level @file{Makefile.am}:
8620 If you want @code{distcleancheck} to ignore built files that have not
8621 been cleaned because they are also part of the distribution, add the
8622 following definition instead:
8624 @c Keep in sync with distcleancheck.sh
8626 distcleancheck_listfiles = \
8627 find . -type f -exec sh -c 'test -f $(srcdir)/$$1 || echo $$1' \
8631 The above definition is not the default because it's usually an error if
8632 your Makefiles cause some distributed files to be rebuilt when the user
8633 build the package. (Think about the user missing the tool required to
8634 build the file; or if the required tool is built by your package,
8635 consider the cross-compilation case where it can't be run.) There is
8636 an entry in the FAQ about this (@pxref{Errors with distclean}), make
8637 sure you read it before playing with @code{distcleancheck_listfiles}.
8639 @cindex @samp{make distuninstallcheck}
8640 @trindex distuninstallcheck
8641 @vindex distuninstallcheck_listfiles
8643 @subheading distuninstallcheck
8644 @code{distcheck} also checks that the @code{uninstall} rule works
8645 properly, both for ordinary and @code{DESTDIR} builds. It does this
8646 by invoking @samp{make uninstall}, and then it checks the install tree
8647 to see if any files are left over. This check will make sure that you
8648 correctly coded your @code{uninstall}-related rules.
8650 By default, the checking is done by the @code{distuninstallcheck} rule,
8651 and the list of files in the install tree is generated by
8652 @samp{$(distuninstallcheck_listfiles)} (this is a variable whose value is
8653 a shell command to run that prints the list of files to stdout).
8655 Either of these can be overridden to modify the behavior of
8656 @code{distcheck}. For instance, to disable this check completely, you
8664 @node The Types of Distributions
8665 @section The Types of Distributions
8667 Automake generates rules to provide archives of the project for
8668 distributions in various formats. Their targets are:
8671 @item @code{dist-gzip}
8672 Generate a @samp{gzip} tar archive of the distribution. This is the
8673 only format enabled by default.
8677 @item @code{dist-bzip2}
8678 Generate a @samp{bzip2} tar archive of the distribution. bzip2 archives
8679 are frequently smaller than gzipped archives.
8680 By default, this rule makes @samp{bzip2} use a compression option of @option{-9}.
8681 To make it use a different one, set the @env{BZIP2} environment variable.
8682 For example, @samp{make dist-bzip2 BZIP2=-7}.
8685 @item @code{dist-lzip}
8686 Generate an @samp{lzip} tar archive of the distribution. @command{lzip}
8687 archives are frequently smaller than @command{bzip2}-compressed archives.
8691 @item @code{dist-xz}
8692 Generate an @samp{xz} tar archive of the distribution. @command{xz}
8693 archives are frequently smaller than @command{bzip2}-compressed archives.
8694 By default, this rule makes @samp{xz} use a compression option of
8695 @option{-e}. To make it use a different one, set the @env{XZ_OPT}
8696 environment variable. For example, run this command to use the
8697 default compression ratio, but with a progress indicator:
8698 @samp{make dist-xz XZ_OPT=-ve}.
8701 @item @code{dist-zip}
8702 Generate a @samp{zip} archive of the distribution.
8705 @item @code{dist-tarZ}
8706 Generate a tar archive of the distribution, compressed with the
8707 historical (obsolescent) program @command{compress}. Use of this
8708 option is discouraged.
8711 @item @code{dist-shar}
8712 Generate a @samp{shar} archive of the distribution. This format archive
8713 is obsolescent, and use of this option is discouraged.
8718 The rule @code{dist} (and its historical synonym @code{dist-all})
8719 will create archives in all the enabled formats (@pxref{List of
8720 Automake options} for how to change this list). By default, only
8721 the @code{dist-gzip} target is hooked to @code{dist}.
8725 @chapter Support for test suites
8728 @cindex @code{make check}
8731 Automake can generate code to handle two kinds of test suites. One is
8732 based on integration with the @command{dejagnu} framework. The other
8733 (and most used) form is based on the use of generic test scripts, and
8734 its activation is triggered by the definition of the special @code{TESTS}
8735 variable. This second form allows for various degrees of sophistication
8736 and customization; in particular, it allows for concurrent execution
8737 of test scripts, use of established test protocols such as TAP, and
8738 definition of custom test drivers and test runners.
8741 In either case, the testsuite is invoked via @samp{make check}.
8744 * Generalities about Testing:: Concepts and terminology about testing
8745 * Simple Tests:: Listing test scripts in @code{TESTS}
8746 * Custom Test Drivers:: Writing and using custom test drivers
8747 * Using the TAP test protocol:: Integrating test scripts that use the TAP protocol
8748 * DejaGnu Tests:: Interfacing with the @command{dejagnu} testing framework
8749 * Install Tests:: Running tests on installed packages
8752 @node Generalities about Testing
8753 @section Generalities about Testing
8755 The purpose of testing is to determine whether a program or system behaves
8756 as expected (e.g., known inputs produce the expected outputs, error
8757 conditions are correctly handled or reported, and older bugs do not
8761 The minimal unit of testing is usually called @emph{test case}, or simply
8762 @emph{test}. How a test case is defined or delimited, and even what
8763 exactly @emph{constitutes} a test case, depends heavily on the testing
8764 paradigm and/or framework in use, so we won't attempt any more precise
8765 definition. The set of the test cases for a given program or system
8766 constitutes its @emph{testsuite}.
8768 @cindex test harness
8769 @cindex testsuite harness
8770 A @emph{test harness} (also @emph{testsuite harness}) is a program or
8771 software component that executes all (or part of) the defined test cases,
8772 analyzes their outcomes, and report or register these outcomes
8773 appropriately. Again, the details of how this is accomplished (and how
8774 the developer and user can influence it or interface with it) varies
8775 wildly, and we'll attempt no precise definition.
8778 @cindex test failure
8779 A test is said to @emph{pass} when it can determine that the condition or
8780 behaviour it means to verify holds, and is said to @emph{fail} when it can
8781 determine that such condition of behaviour does @emph{not} hold.
8784 Sometimes, tests can rely on non-portable tools or prerequisites, or
8785 simply make no sense on a given system (for example, a test checking a
8786 Windows-specific feature makes no sense on a GNU/Linux system). In this
8787 case, accordingly to the definition above, the tests can neither be
8788 considered passed nor failed; instead, they are @emph{skipped} -- i.e.,
8789 they are not run, or their result is anyway ignored for what concerns
8790 the count of failures an successes. Skips are usually explicitly
8791 reported though, so that the user will be aware that not all of the
8792 testsuite has really run.
8795 @cindex expected failure
8796 @cindex expected test failure
8798 @cindex unexpected pass
8799 @cindex unexpected test pass
8800 It's not uncommon, especially during early development stages, that some
8801 tests fail for known reasons, and that the developer doesn't want to
8802 tackle these failures immediately (this is especially true when the
8803 failing tests deal with corner cases). In this situation, the better
8804 policy is to declare that each of those failures is an @emph{expected
8805 failure} (or @emph{xfail}). In case a test that is expected to fail ends
8806 up passing instead, many testing environments will flag the result as a
8807 special kind of failure called @emph{unexpected pass} (or @emph{xpass}).
8810 @cindex Distinction between errors and failures in testsuites
8811 Many testing environments and frameworks distinguish between test failures
8812 and hard errors. As we've seen, a test failure happens when some invariant
8813 or expected behaviour of the software under test is not met. An @emph{hard
8814 error} happens when e.g., the set-up of a test case scenario fails, or when
8815 some other unexpected or highly undesirable condition is encountered (for
8816 example, the program under test experiences a segmentation fault).
8818 @emph{TODO}: Links to other test harnesses (esp. those sharing our
8822 @section Simple Tests
8825 * Scripts-based Testsuites:: Automake-specific concepts and terminology
8826 * Serial Test Harness:: Older (and discouraged) serial test harness
8827 * Parallel Test Harness:: Generic concurrent test harness
8830 @node Scripts-based Testsuites
8831 @subsection Scripts-based Testsuites
8833 If the special variable @code{TESTS} is defined, its value is taken to be
8834 a list of programs or scripts to run in order to do the testing. Under
8835 the appropriate circumstances, it's possible for @code{TESTS} to list
8836 also data files to be passed to one or more test scripts defined by
8837 different means (the so-called ``log compilers'', @pxref{Parallel Test
8840 Test scripts can be executed serially or concurrently. Automake supports
8841 both these kinds of test execution, with the parallel test harness being
8842 the default. The concurrent test harness relies on the concurrence
8843 capabilities (if any) offered by the underlying @command{make}
8844 implementation, and can thus only be as good as those are.
8846 By default, only the exit statuses of the test scripts are considered when
8847 determining the testsuite outcome. But Automake allows also the use of
8848 more complex test protocols, either standard (@pxref{Using the TAP test
8849 protocol}) or custom (@pxref{Custom Test Drivers}). Note that you can't
8850 enable such protocols when the serial harness is used, though.
8851 In the rest of this section we are going to concentrate mostly on
8852 protocol-less tests, since we cover test protocols in a later section
8853 (again, @pxref{Custom Test Drivers}).
8855 @cindex Exit status 77, special interpretation
8856 @cindex Exit status 99, special interpretation
8857 When no test protocol is in use, an exit status of 0 from a test script will
8858 denote a success, an exit status of 77 a skipped test, an exit status of 99
8859 an hard error, and any other exit status will denote a failure.
8861 @cindex Tests, expected failure
8862 @cindex Expected test failure
8864 @vindex DISABLE_HARD_ERRORS
8865 @cindex Disabling hard errors
8866 You may define the variable @code{XFAIL_TESTS} to a list of tests
8867 (usually a subset of @code{TESTS}) that are expected to fail; this will
8868 effectively reverse the result of those tests (with the provision that
8869 skips and hard errors remain untouched). You may also instruct the
8870 testsuite harness to treat hard errors like simple failures, by defining
8871 the @code{DISABLE_HARD_ERRORS} make variable to a nonempty value.
8873 Note however that, for tests based on more complex test protocols,
8874 the exact effects of @code{XFAIL_TESTS} and @code{DISABLE_HARD_ERRORS}
8875 might change, or they might even have no effect at all (for example,
8876 @c Keep this in sync with tap-no-disable-hard-errors.sh
8877 in tests using TAP, there is not way to disable hard errors, and the
8878 @code{DISABLE_HARD_ERRORS} variable has no effect on them).
8880 @anchor{Testsuite progress on console}
8881 @cindex Testsuite progress on console
8882 The result of each test case run by the scripts in @code{TESTS} will be
8883 printed on standard output, along with the test name. For test protocols
8884 that allow more test cases per test script (such as TAP), a number,
8885 identifier and/or brief description specific for the single test case is
8886 expected to be printed in addition to the name of the test script. The
8887 possible results (whose meanings should be clear from the previous
8888 @ref{Generalities about Testing}) are @code{PASS}, @code{FAIL},
8889 @code{SKIP}, @code{XFAIL}, @code{XPASS} and @code{ERROR}. Here is an
8890 example of output from an hypothetical testsuite that uses both plain
8892 @c Keep in sync with tap-doc.sh
8895 PASS: zardoz.tap 1 - Daemon started
8896 PASS: zardoz.tap 2 - Daemon responding
8897 SKIP: zardoz.tap 3 - Daemon uses /proc # SKIP /proc is not mounted
8898 PASS: zardoz.tap 4 - Daemon stopped
8901 XFAIL: mu.tap 2 # TODO frobnication not yet implemented
8905 A testsuite summary (expected to report at least the number of run,
8906 skipped and failed tests) will be printed at the end of the testsuite
8909 @anchor{Simple tests and color-tests}
8910 @vindex AM_COLOR_TESTS
8911 @cindex Colorized testsuite output
8912 If the standard output is connected to a capable terminal, then the test
8913 results and the summary are colored appropriately. The developer and the
8914 user can disable colored output by setting the @command{make} variable
8915 @samp{AM_COLOR_TESTS=no}; the user can in addition force colored output
8916 even without a connecting terminal with @samp{AM_COLOR_TESTS=always}.
8917 It's also worth noting that some @command{make} implementations,
8918 when used in parallel mode, have slightly different semantics
8919 (@pxref{Parallel make,,, autoconf, The Autoconf Manual}), which can
8920 break the automatic detection of a connection to a capable terminal.
8921 If this is the case, the user will have to resort to the use of
8922 @samp{AM_COLOR_TESTS=always} in order to have the testsuite output
8925 Test programs that need data files should look for them in @code{srcdir}
8926 (which is both a make variable and an environment variable made available
8927 to the tests), so that they work when building in a separate directory
8928 (@pxref{Build Directories, , Build Directories , autoconf,
8929 The Autoconf Manual}), and in particular for the @code{distcheck} rule
8930 (@pxref{Checking the Distribution}).
8933 @vindex TESTS_ENVIRONMENT
8934 @vindex AM_TESTS_ENVIRONMENT
8935 The @code{AM_TESTS_ENVIRONMENT} and @code{TESTS_ENVIRONMENT} variables can
8936 be used to run initialization code and set environment variables for the
8937 test scripts. The former variable is developer-reserved, and can be
8938 defined in the @file{Makefile.am}, while the latter is reserved for the
8939 user, which can employ it to extend or override the settings in the
8940 former; for this to work portably, however, the contents of a non-empty
8941 @code{AM_TESTS_ENVIRONMENT} @emph{must} be terminated by a semicolon.
8943 @vindex AM_TESTS_FD_REDIRECT
8944 The @code{AM_TESTS_FD_REDIRECT} variable can be used to define file
8945 descriptor redirections for the test scripts. One might think that
8946 @code{AM_TESTS_ENVIRONMENT} could be used for this purpose, but experience
8947 has shown that doing so portably is practically impossible. The main
8948 hurdle is constituted by Korn shells, which usually set the close-on-exec
8949 flag on file descriptors opened with the @command{exec} builtin, thus
8950 rendering an idiom like @code{AM_TESTS_ENVIRONMENT = exec 9>&2;}
8951 ineffectual. This issue also affects some Bourne shells, such as the
8952 HP-UX's @command{/bin/sh},
8953 @c FIXME: should we offer a link to the relevant discussions on the
8954 @c bug-autoconf list?
8956 @c Keep in sync with tests-environment-backcompat.sh
8958 AM_TESTS_ENVIRONMENT = \
8959 ## Some environment initializations are kept in a separate shell
8960 ## file 'tests-env.sh', which can make it easier to also run tests
8961 ## from the command line.
8962 . $(srcdir)/tests-env.sh; \
8963 ## On Solaris, prefer more POSIX-compliant versions of the standard
8964 ## tools by default.
8965 if test -d /usr/xpg4/bin; then \
8966 PATH=/usr/xpg4/bin:$$PATH; export PATH; \
8968 @c $$ restore font-lock
8969 ## With this, the test scripts will be able to print diagnostic
8970 ## messages to the original standard error stream, even if the test
8971 ## driver redirects the stderr of the test scripts to a log file
8972 ## before executing them.
8973 AM_TESTS_FD_REDIRECT = 9>&2
8977 Note however that @code{AM_TESTS_ENVIRONMENT} is, for historical and
8978 implementation reasons, @emph{not} supported by the serial harness
8979 (@pxref{Serial Test Harness}).
8981 Automake ensures that each file listed in @code{TESTS} is built before
8982 it is run; you can list both source and derived programs (or scripts)
8983 in @code{TESTS}; the generated rule will look both in @code{srcdir} and
8984 @file{.}. For instance, you might want to run a C program as a test.
8985 To do this you would list its name in @code{TESTS} and also in
8986 @code{check_PROGRAMS}, and then specify it as you would any other
8989 Programs listed in @code{check_PROGRAMS} (and @code{check_LIBRARIES},
8990 @code{check_LTLIBRARIES}...) are only built during @code{make check},
8991 not during @code{make all}. You should list there any program needed
8992 by your tests that does not need to be built by @code{make all}. Note
8993 that @code{check_PROGRAMS} are @emph{not} automatically added to
8994 @code{TESTS} because @code{check_PROGRAMS} usually lists programs used
8995 by the tests, not the tests themselves. Of course you can set
8996 @code{TESTS = $(check_PROGRAMS)} if all your programs are test cases.
8998 @node Serial Test Harness
8999 @subsection Older (and discouraged) serial test harness
9000 @cindex @option{serial-tests}, Using
9002 First, note that today the use of this harness is strongly discouraged in
9003 favour of the parallel test harness (@pxref{Parallel Test Harness}).
9004 Still, there are @emph{few} situations when the advantages offered by
9005 the parallel harness are irrelevant, and when test concurrency can
9006 even cause tricky problems. In those cases, it might make sense to
9007 still use the serial harness, for simplicity and reliability (we still
9008 suggest trying to give the parallel harness a shot though).
9010 The serial test harness is enabled by the Automake option
9011 @option{serial-tests}. It operates by simply running the tests serially,
9012 one at the time, without any I/O redirection. It's up to the user to
9013 implement logging of tests' output, if that's requited or desired.
9014 @c TODO: give an example of how this can be done.
9016 For historical and implementation reasons, the @code{AM_TESTS_ENVIRONMENT}
9017 variable is @emph{not} supported by this harness (it will be silently
9018 ignored if defined); only @code{TESTS_ENVIRONMENT} is, and it is to be
9019 considered a developer-reserved variable. This is done so that, when
9020 using the serial harness, @code{TESTS_ENVIRONMENT} can be defined to an
9021 invocation of an interpreter through which the tests are to be run.
9022 For instance, the following setup may be used to run tests with Perl:
9025 TESTS_ENVIRONMENT = $(PERL) -Mstrict -w
9026 TESTS = foo.pl bar.pl baz.pl
9030 It's important to note that the use of @code{TESTS_ENVIRONMENT} endorsed
9031 here would be @emph{invalid} with the parallel harness. That harness
9032 provides a more elegant way to achieve the same effect, with the further
9033 benefit of freeing the @code{TESTS_ENVIRONMENT} variable for the user
9034 (@pxref{Parallel Test Harness}).
9036 Another, less serious limit of the serial harness is that it doesn't
9037 really distinguish between simple failures and hard errors; this is
9038 due to historical reasons only, and might be fixed in future Automake
9041 @node Parallel Test Harness
9042 @subsection Parallel Test Harness
9044 By default, Automake generated a parallel (concurrent) test harness. It
9045 features automatic collection of the test scripts output in @file{.log}
9046 files, concurrent execution of tests with @code{make -j}, specification
9047 of inter-test dependencies, lazy reruns of tests that have not completed
9048 in a prior run, and hard errors for exceptional failures.
9050 @anchor{Basics of test metadata}
9051 @vindex TEST_SUITE_LOG
9053 @cindex @file{.log} files
9054 @cindex @file{.trs} files
9055 @cindex test metadata
9056 The parallel test harness operates by defining a set of @command{make}
9057 rules that run the test scripts listed in @code{TESTS}, and, for each
9058 such script, save its output in a corresponding @file{.log} file and
9059 its results (and other ``metadata'', @pxref{API for Custom Test Drivers})
9060 in a corresponding @file{.trs} (as in @b{T}est @b{R}e@b{S}ults) file.
9061 @c We choose the '.trs' extension also because, at the time of writing,
9062 @c it isn't already used for other significant purposes; see e.g.:
9063 @c - http://filext.com/file-extension/trs
9064 @c - http://www.file-extensions.org/search/?searchstring=trs
9065 The @file{.log} file will contain all the output emitted by the test on
9066 its standard output and its standard error. The @file{.trs} file will
9067 contain, among the other things, the results of the test cases run by
9070 The parallel test harness will also create a summary log file,
9071 @code{TEST_SUITE_LOG}, which defaults to @file{test-suite.log} and requires
9072 a @file{.log} suffix. This file depends upon all the @file{.log} and
9073 @file{.trs} files created for the test scripts listed in @code{TESTS}.
9076 As with the serial harness above, by default one status line is printed
9077 per completed test, and a short summary after the suite has completed.
9078 However, standard output and standard error of the test are redirected
9079 to a per-test log file, so that parallel execution does not produce
9080 intermingled output. The output from failed tests is collected in the
9081 @file{test-suite.log} file. If the variable @samp{VERBOSE} is set, this
9082 file is output after the summary.
9083 @c FIXME: we should be clearer about what we mean exactly here ...
9084 For best results, the tests should be verbose by default now.
9086 @vindex TEST_EXTENSIONS
9088 Each couple of @file{.log} and @file{.trs} files is created when the
9089 corresponding test has completed. The set of log files is listed in
9090 the read-only variable @code{TEST_LOGS}, and defaults to @code{TESTS},
9091 with the executable extension if any (@pxref{EXEEXT}), as well as any
9092 suffix listed in @code{TEST_EXTENSIONS} removed, and @file{.log} appended.
9093 Results are undefined if a test file name ends in several concatenated
9094 suffixes. @code{TEST_EXTENSIONS} defaults to @file{.test}; it can be
9095 overridden by the user, in which case any extension listed in it must be
9096 constituted by a dot, followed by a non-digit alphabetic character,
9097 followed by any number of alphabetic characters.
9098 @c Keep in sync with test-extensions.sh
9099 For example, @samp{.sh}, @samp{.T} and @samp{.t1} are valid extensions,
9100 while @samp{.x-y}, @samp{.6c} and @samp{.t.1} are not.
9102 @vindex _LOG_COMPILE
9103 @vindex _LOG_COMPILER
9106 @vindex LOG_COMPILER
9108 @vindex @var{ext}_LOG_COMPILE
9109 @vindex @var{ext}_LOG_COMPILER
9110 @vindex @var{ext}_LOG_FLAGS
9111 @vindex AM_@var{ext}_LOG_FLAGS
9112 @vindex AM_LOG_FLAGS
9113 For tests that match an extension @code{.@var{ext}} listed in
9114 @code{TEST_EXTENSIONS}, you can provide a custom ``test runner'' using
9115 the variable @code{@var{ext}_LOG_COMPILER} (note the upper-case
9116 extension) and pass options in @code{AM_@var{ext}_LOG_FLAGS} and allow
9117 the user to pass options in @code{@var{ext}_LOG_FLAGS}. It will cause
9118 all tests with this extension to be called with this runner. For all
9119 tests without a registered extension, the variables @code{LOG_COMPILER},
9120 @code{AM_LOG_FLAGS}, and @code{LOG_FLAGS} may be used. For example,
9122 @c Keep in sync with parallel-tests-log-compiler-example.sh
9124 TESTS = foo.pl bar.py baz
9125 TEST_EXTENSIONS = .pl .py
9126 PL_LOG_COMPILER = $(PERL)
9127 AM_PL_LOG_FLAGS = -w
9128 PY_LOG_COMPILER = $(PYTHON)
9129 AM_PY_LOG_FLAGS = -v
9130 LOG_COMPILER = ./wrapper-script
9135 will invoke @samp{$(PERL) -w foo.pl}, @samp{$(PYTHON) -v bar.py},
9136 and @samp{./wrapper-script -d baz} to produce @file{foo.log},
9137 @file{bar.log}, and @file{baz.log}, respectively. The @file{foo.trs},
9138 @file{bar.trs} and @file{baz.trs} files will be automatically produced
9141 It's important to note that, differently from what we've seen for the
9142 serial test harness (@pxref{Parallel Test Harness}), the
9143 @code{AM_TESTS_ENVIRONMENT} and @code{TESTS_ENVIRONMENT} variables
9144 @emph{cannot} be use to define a custom test runner; the
9145 @code{LOG_COMPILER} and @code{LOG_FLAGS} (or their extension-specific
9146 counterparts) should be used instead:
9150 AM_TESTS_ENVIRONMENT = PERL5LIB='$(srcdir)/lib' $(PERL) -Mstrict -w
9155 AM_TESTS_ENVIRONMENT = PERL5LIB='$(srcdir)/lib'; export PERL5LIB;
9156 LOG_COMPILER = $(PERL)
9157 AM_LOG_FLAGS = -Mstrict -w
9160 By default, the test suite harness will run all tests, but there are
9161 several ways to limit the set of tests that are run:
9165 You can set the @code{TESTS} variable. For example, you can use a
9166 command like this to run only a subset of the tests:
9169 env TESTS="foo.test bar.test" make -e check
9172 Note however that the command above will unconditionally overwrite the
9173 @file{test-suite.log} file, thus clobbering the recorded results
9174 of any previous testsuite run. This might be undesirable for packages
9175 whose testsuite takes long time to execute. Luckily, this problem can
9176 easily be avoided by overriding also @code{TEST_SUITE_LOG} at runtime;
9179 @c Keep in sync with parallel-tests-log-override-2.sh
9181 env TEST_SUITE_LOG=partial.log TESTS="..." make -e check
9184 will write the result of the partial testsuite runs to the
9185 @file{partial.log}, without touching @file{test-suite.log}.
9188 You can set the @code{TEST_LOGS} variable. By default, this variable is
9189 computed at @command{make} run time from the value of @code{TESTS} as
9190 described above. For example, you can use the following:
9193 set x subset*.log; shift
9194 env TEST_LOGS="foo.log $*" make -e check
9197 The comments made above about @code{TEST_SUITE_LOG} overriding applies
9201 @vindex RECHECK_LOGS
9202 @cindex lazy test execution
9203 By default, the test harness removes all old per-test @file{.log} and
9204 @file{.trs} files before it starts running tests to regenerate them. The
9205 variable @code{RECHECK_LOGS} contains the set of @file{.log} (and, by
9206 implication, @file{.trs}) files which are removed. @code{RECHECK_LOGS}
9207 defaults to @code{TEST_LOGS}, which means all tests need to be rechecked.
9208 By overriding this variable, you can choose which tests need to be
9209 reconsidered. For example, you can lazily rerun only those tests which
9210 are outdated, i.e., older than their prerequisite test files, by setting
9211 this variable to the empty value:
9214 env RECHECK_LOGS= make -e check
9219 You can ensure that all tests are rerun which have failed or passed
9220 unexpectedly, by running @code{make recheck} in the test directory.
9221 This convenience target will set @code{RECHECK_LOGS} appropriately
9222 before invoking the main test harness.
9226 In order to guarantee an ordering between tests even with @code{make
9227 -j@var{N}}, dependencies between the corresponding @file{.log} files
9228 may be specified through usual @command{make} dependencies. For example,
9229 the following snippet lets the test named @file{foo-execute.test} depend
9230 upon completion of the test @file{foo-compile.test}:
9233 TESTS = foo-compile.test foo-execute.test
9234 foo-execute.log: foo-compile.log
9238 Please note that this ordering ignores the @emph{results} of required
9239 tests, thus the test @file{foo-execute.test} is run even if the test
9240 @file{foo-compile.test} failed or was skipped beforehand. Further,
9241 please note that specifying such dependencies currently works only for
9242 tests that end in one of the suffixes listed in @code{TEST_EXTENSIONS}.
9244 Tests without such specified dependencies may be run concurrently with
9245 parallel @command{make -j@var{N}}, so be sure they are prepared for
9246 concurrent execution.
9249 @c Keep in sync with 'parallel-tests-extra-programs.sh'.
9250 The combination of lazy test execution and correct dependencies between
9251 tests and their sources may be exploited for efficient unit testing
9252 during development. To further speed up the edit-compile-test cycle, it
9253 may even be useful to specify compiled programs in @code{EXTRA_PROGRAMS}
9254 instead of with @code{check_PROGRAMS}, as the former allows intertwined
9255 compilation and test execution (but note that @code{EXTRA_PROGRAMS} are
9256 not cleaned automatically, @pxref{Uniform}).
9258 The variables @code{TESTS} and @code{XFAIL_TESTS} may contain
9259 conditional parts as well as configure substitutions. In the latter
9260 case, however, certain restrictions apply: substituted test names
9261 must end with a nonempty test suffix like @file{.test}, so that one of
9262 the inference rules generated by @command{automake} can apply. For
9263 literal test names, @command{automake} can generate per-target rules
9264 to avoid this limitation.
9266 Please note that it is currently not possible to use @code{$(srcdir)/}
9267 or @code{$(top_srcdir)/} in the @code{TESTS} variable. This technical
9268 limitation is necessary to avoid generating test logs in the source tree
9269 and has the unfortunate consequence that it is not possible to specify
9270 distributed tests that are themselves generated by means of explicit
9271 rules, in a way that is portable to all @command{make} implementations
9272 (@pxref{Make Target Lookup,,, autoconf, The Autoconf Manual}, the
9273 semantics of FreeBSD and OpenBSD @command{make} conflict with this).
9274 In case of doubt you may want to require to use GNU @command{make},
9275 or work around the issue with inference rules to generate the tests.
9277 @node Custom Test Drivers
9278 @section Custom Test Drivers
9281 * Overview of Custom Test Drivers Support::
9282 * Declaring Custom Test Drivers::
9283 * API for Custom Test Drivers::
9286 @node Overview of Custom Test Drivers Support
9287 @subsection Overview of Custom Test Drivers Support
9289 Starting from Automake version 1.12, the parallel test harness allows
9290 the package authors to use third-party custom test drivers, in case the
9291 default ones are inadequate for their purposes, or do not support their
9292 testing protocol of choice.
9294 A custom test driver is expected to properly run the test programs passed
9295 to it (including the command-line arguments passed to those programs, if
9296 any), to analyze their execution and outcome, to create the @file{.log}
9297 and @file{.trs} files associated to these test runs, and to display the test
9298 results on the console. It is responsibility of the author of the test
9299 driver to ensure that it implements all the above steps meaningfully and
9300 correctly; Automake isn't and can't be of any help here. On the other
9301 hand, the Automake-provided code for testsuite summary generation offers
9302 support for test drivers allowing several test results per test script,
9303 if they take care to register such results properly (@pxref{Log files
9304 generation and test results recording}).
9306 The exact details of how test scripts' results are to be determined and
9307 analyzed is left to the individual drivers. Some drivers might only
9308 consider the test script exit status (this is done for example by the
9309 default test driver used by the parallel test harness, described
9310 in the previous section). Other drivers might implement more complex and
9311 advanced test protocols, which might require them to parse and interpreter
9312 the output emitted by the test script they're running (examples of such
9313 protocols are TAP and SubUnit).
9315 It's very important to note that, even when using custom test drivers,
9316 most of the infrastructure described in the previous section about the
9317 parallel harness remains in place; this includes:
9321 list of test scripts defined in @code{TESTS}, and overridable at
9322 runtime through the redefinition of @code{TESTS} or @code{TEST_LOGS};
9324 concurrency through the use of @command{make}'s option @option{-j};
9326 per-test @file{.log} and @file{.trs} files, and generation of a summary
9327 @file{.log} file from them;
9329 @code{recheck} target, @code{RECHECK_LOGS} variable, and lazy reruns
9332 inter-test dependencies;
9334 support for @code{check_*} variables (@code{check_PROGRAMS},
9335 @code{check_LIBRARIES}, ...);
9337 use of @code{VERBOSE} environment variable to get verbose output on
9340 definition and honoring of @code{TESTS_ENVIRONMENT},
9341 @code{AM_TESTS_ENVIRONMENT} and @code{AM_TESTS_FD_REDIRECT}
9344 definition of generic and extension-specific @code{LOG_COMPILER} and
9345 @code{LOG_FLAGS} variables.
9349 On the other hand, the exact semantics of how (and if) testsuite output
9350 colorization, @code{XFAIL_TESTS}, and hard errors are supported and
9351 handled is left to the individual test drivers.
9353 @c TODO: We should really add a working example in the doc/ directory,
9354 @c TODO: and reference if from here.
9356 @node Declaring Custom Test Drivers
9357 @subsection Declaring Custom Test Drivers
9360 @vindex _LOG_DRIVER_FLAGS
9362 @vindex LOG_DRIVER_FLAGS
9363 @vindex @var{ext}_LOG_DRIVER
9364 @vindex @var{ext}_LOG_DRIVER_FLAGS
9365 @vindex AM_@var{ext}_LOG_DRIVER_FLAGS
9366 @vindex AM_LOG_DRIVER_FLAGS
9367 Custom testsuite drivers are declared by defining the make variables
9368 @code{LOG_DRIVER} or @code{@var{ext}_LOG_DRIVER} (where @var{ext} must
9369 be declared in @code{TEST_EXTENSIONS}). They must be defined to
9370 programs or scripts that will be used to drive the execution, logging,
9371 and outcome report of the tests with corresponding extensions (or of
9372 those with no registered extension in the case of @code{LOG_DRIVER}).
9373 Clearly, multiple distinct test drivers can be declared in the same
9374 @file{Makefile.am}. Note moreover that the @code{LOG_DRIVER} variables
9375 are @emph{not} a substitute for the @code{LOG_COMPILER} variables: the
9376 two sets of variables can, and often do, usefully and legitimately
9379 @c TODO: We should really be able to point to a clarifying example here!
9381 The developer-reserved variable @code{AM_LOG_DRIVER_FLAGS} and the
9382 user-reserved variable @code{LOG_DRIVER_FLAGS} can be used to define
9383 flags that will be passed to each invocation of @code{LOG_DRIVER},
9384 with the user-defined flags obviously taking precedence over the
9385 developer-reserved ones. Similarly, for each extension @var{ext}
9386 declared in @code{TEST_EXTENSIONS}, flags listed in
9387 @code{AM_@var{ext}_LOG_DRIVER_FLAGS} and
9388 @code{@var{ext}_LOG_DRIVER_FLAGS} will be passed to
9389 invocations of @code{@var{ext}_LOG_DRIVER}.
9391 @node API for Custom Test Drivers
9392 @subsection API for Custom Test Drivers
9394 Note that @emph{the APIs described here are still highly experimental},
9395 and will very likely undergo tightenings and likely also extensive changes
9396 in the future, to accommodate for new features or to satisfy additional
9397 portability requirements.
9399 The main characteristic of these APIs is that they are designed to share
9400 as much infrastructure, semantics, and implementation details as possible
9401 with the parallel test harness and its default driver.
9404 * Command-line arguments for test drivers::
9405 * Log files generation and test results recording::
9406 * Testsuite progress output::
9409 @node Command-line arguments for test drivers
9410 @subsubsection Command-line arguments for test drivers
9412 A custom driver can rely on various command-line options and arguments
9413 being passed to it automatically by the Automake-generated test harness.
9414 It is @emph{mandatory} that it understands all of them (even if the exact
9415 interpretation of the associated semantics can legitimately change
9416 between a test driver and another, and even be a no-op in some drivers).
9419 Here is the list of options:
9422 @item --test-name=@var{NAME}
9423 The name of the test, with VPATH prefix (if any) removed. This can have a
9424 suffix and a directory component (as in e.g., @file{sub/foo.test}), and is
9425 mostly meant to be used in console reports about testsuite advancements and
9426 results (@pxref{Testsuite progress output}).
9427 @item --log-file=@file{@var{PATH}.log}
9428 The @file{.log} file the test driver must create (@pxref{Basics of
9429 test metadata}). If it has a directory component (as in e.g.,
9430 @file{sub/foo.log}), the test harness will ensure that such directory
9431 exists @emph{before} the test driver is called.
9432 @item --trs-file=@file{@var{PATH}.trs}
9433 The @file{.trs} file the test driver must create (@pxref{Basics of
9434 test metadata}). If it has a directory component (as in e.g.,
9435 @file{sub/foo.trs}), the test harness will ensure that such directory
9436 exists @emph{before} the test driver is called.
9437 @item --color-tests=@{yes|no@}
9438 Whether the console output should be colorized or not (@pxref{Simple
9439 tests and color-tests}, to learn when this option gets activated and
9441 @item --expect-failure=@{yes|no@}
9442 Whether the tested program is expected to fail.
9443 @item --enable-hard-errors=@{yes|no@}
9444 Whether ``hard errors'' in the tested program should be treated differently
9445 from normal failures or not (the default should be @code{yes}). The exact
9446 meaning of ``hard error'' is highly dependent from the test protocols or
9449 Explicitly terminate the list of options.
9453 The first non-option argument passed to the test driver is the program to
9454 be run, and all the following ones are command-line options and arguments
9457 Note that the exact semantics attached to the @option{--color-tests},
9458 @option{--expect-failure} and @option{--enable-hard-errors} options are
9459 left up to the individual test drivers. Still, having a behaviour
9460 compatible or at least similar to that provided by the default driver
9461 is advised, as that would offer a better consistency and a more pleasant
9464 @node Log files generation and test results recording
9465 @subsubsection Log files generation and test results recording
9467 The test driver must correctly generate the files specified by the
9468 @option{--log-file} and @option{--trs-file} option (even when the tested
9469 program fails or crashes).
9471 The @file{.log} file should ideally contain all the output produced by the
9472 tested program, plus optionally other information that might facilitate
9473 debugging or analysis of bug reports. Apart from that, its format is
9476 The @file{.trs} file is used to register some metadata through the use
9477 of custom reStructuredText fields. This metadata is expected to be
9478 employed in various ways by the parallel test harness; for example, to
9479 count the test results when printing the testsuite summary, or to decide
9480 which tests to re-run upon @command{make reheck}. Unrecognized metadata
9481 in a @file{.trs} file is currently ignored by the harness, but this might
9482 change in the future. The list of currently recognized metadata follows.
9487 @cindex Register test result
9488 @cindex Register test case result
9489 @cindex Test result, registering
9490 @cindex Test case result, registering
9491 @cindex @code{:test-result:}
9492 @cindex reStructuredText field, @code{:test-result:}
9493 The test driver must use this field to register the results of @emph{each}
9494 test case run by a test script file. Several @code{:test-result:} fields
9495 can be present in the same @file{.trs} file; this is done in order to
9496 support test protocols that allow a single test script to run more test
9499 @c Keep this in sync with lib/am/check-am:$(TEST_SUITE_LOG).
9500 The only recognized test results are currently @code{PASS}, @code{XFAIL},
9501 @code{SKIP}, @code{FAIL}, @code{XPASS} and @code{ERROR}. These results,
9502 when declared with @code{:test-result:}, can be optionally followed by
9503 text holding the name and/or a brief description of the corresponding
9504 test; the harness will ignore such extra text when generating
9505 @file{test-suite.log} and preparing the testsuite summary.
9507 @c Keep in sync with 'test-metadata-recheck.sh'.
9508 @item @code{:recheck:}
9510 @cindex reStructuredText field, @code{:recheck:}
9511 If this field is present and defined to @code{no}, then the corresponding
9512 test script will @emph{not} be run upon a @command{make recheck}. What
9513 happens when two or more @code{:recheck:} fields are present in the same
9514 @file{.trs} file is undefined behaviour.
9516 @c Keep in sync with 'test-metadata-global-log.sh'.
9517 @item @code{:copy-in-global-log:}
9518 @cindex :copy-in-global-log:
9519 @cindex reStructuredText field, @code{:copy-in-global-log:}
9520 If this field is present and defined to @code{no}, then the content
9521 of the @file{.log} file will @emph{not} be copied into the global
9522 @file{test-suite.log}. We allow to forsake such copying because, while
9523 it can be useful in debugging and analysis of bug report, it can also be
9524 just a waste of space in normal situations, e.g., when a test script is
9525 successful. What happens when two or more @code{:copy-in-global-log:}
9526 fields are present in the same @file{.trs} file is undefined behaviour.
9528 @c Keep in sync with 'test-metadata-global-result.sh'.
9529 @item @code{:test-global-result:}
9530 @cindex :test-global-result:
9531 @cindex reStructuredText field, @code{:test-global-result:}
9532 This is used to declare the "global result" of the script. Currently,
9533 the value of this field is needed only to be reported (more or less
9534 verbatim) in the generated global log file @code{$(TEST_SUITE_LOG)},
9535 so it's quite free-form. For example, a test script which run 10 test
9536 cases, 6 of which pass and 4 of which are skipped, could reasonably have
9537 a @code{PASS/SKIP} value for this field, while a test script which run
9538 19 successful tests and one failed test could have an @code{ALMOST
9539 PASSED} value. What happens when two or more @code{:test-global-result:}
9540 fields are present in the same @file{.trs} file is undefined behaviour.
9544 Let's see a small example. Assume a @file{.trs} file contains the
9548 :test-result: PASS server starts
9549 :global-log-copy: no
9550 :test-result: PASS HTTP/1.1 request
9551 :test-result: FAIL HTTP/1.0 request
9553 :test-result: SKIP HTTPS request (TLS library wasn't available)
9554 :test-result: PASS server stops
9558 Then the corresponding test script will be re-run by @command{make check},
9559 will contribute with @emph{five} test results to the testsuite summary
9560 (three of these tests being successful, one failed, and one skipped), and
9561 the content of the corresponding @file{.log} file will @emph{not} be
9562 copied in the global log file @file{test-suite.log}.
9564 @node Testsuite progress output
9565 @subsubsection Testsuite progress output
9567 A custom test driver also has the task of displaying, on the standard
9568 output, the test results as soon as they become available. Depending on
9569 the protocol in use, it can also display the reasons for failures and
9570 skips, and, more generally, any useful diagnostic output (but remember
9571 that each line on the screen is precious, so that cluttering the screen
9572 with overly verbose information is bad idea). The exact format of this
9573 progress output is left up to the test driver; in fact, a custom test
9574 driver might @emph{theoretically} even decide not to do any such report,
9575 leaving it all to the testsuite summary (that would be a very lousy idea,
9576 of course, and serves only to illustrate the flexibility that is
9579 Remember that consistency is good; so, if possible, try to be consistent
9580 with the output of the built-in Automake test drivers, providing a similar
9581 ``look & feel''. In particular, the testsuite progress output should be
9582 colorized when the @option{--color-tests} is passed to the driver. On the
9583 other end, if you are using a known and widespread test protocol with
9584 well-established implementations, being consistent with those
9585 implementations' output might be a good idea too.
9587 @c TODO: Give an example, maybe inspired to py.test-style output.
9588 @c TODO: That is a good idea because it shows a test driver that allows
9589 @c TODO: for different levels of verbosity in the progress output (could
9590 @c TODO: be implemented either using a driver cmdline flag, or an
9591 @c TODO: environment variable, or both).
9593 @node Using the TAP test protocol
9594 @section Using the TAP test protocol
9597 * Introduction to TAP::
9598 * Use TAP with the Automake test harness::
9599 * Incompatibilities with other TAP parsers and drivers::
9600 * Links and external resources on TAP::
9603 @node Introduction to TAP
9604 @subsection Introduction to TAP
9606 TAP, the Test Anything Protocol, is a simple text-based interface between
9607 testing modules or programs and a test harness. The tests (also called
9608 ``TAP producers'' in this context) write test results in a simple format
9609 on standard output; a test harness (also called ``TAP consumer'') will
9610 parse and interpret these results, and properly present them to the user,
9611 and/or register them for later analysis. The exact details of how this
9612 is accomplished can vary among different test harnesses. The Automake
9613 harness will present the results on the console in the usual
9614 fashion (@pxref{Testsuite progress on console}), and will use the
9615 @file{.trs} files (@pxref{Basics of test metadata}) to store the test
9616 results and related metadata. Apart from that, it will try to remain
9617 as much compatible as possible with pre-existing and widespread utilities,
9618 such as the @uref{http://search.cpan.org/~andya/Test-Harness/bin/prove,
9619 @command{prove} utility}, at least for the simpler usages.
9621 TAP started its life as part of the test harness for Perl, but today
9622 it has been (mostly) standardized, and has various independent
9623 implementations in different languages; among them, C, C++, Perl,
9624 Python, PHP, and Java. For a semi-official specification of the
9625 TAP protocol, please refer to the documentation of
9626 @uref{http://search.cpan.org/~petdance/Test-Harness/lib/Test/Harness/TAP.pod,
9627 @samp{Test::Harness::TAP}}.
9629 The most relevant real-world usages of TAP are obviously in the testsuites
9630 of @command{perl} and of many perl modules. Still, also other important
9631 third-party packages, such as @uref{http://git-scm.com/, @command{git}},
9632 use TAP in their testsuite.
9634 @node Use TAP with the Automake test harness
9635 @subsection Use TAP with the Automake test harness
9637 Currently, the TAP driver that comes with Automake requires some by-hand
9638 steps on the developer's part (this situation should hopefully be improved
9639 in future Automake versions). You'll have to grab the @file{tap-driver.sh}
9640 script from the Automake distribution by hand, copy it in your source tree,
9641 add a call to @code{AC_PROG_AWK} in @file{configure.ac} to search for a
9642 proper awk program, and use the Automake support for third-party test
9643 drivers to instruct the harness to use the @file{tap-driver.sh} script
9644 and that awk program to run your TAP-producing tests. See the example
9645 below for clarification.
9647 Apart from the options common to all the Automake test drivers
9648 (@pxref{Command-line arguments for test drivers}), the @file{tap-driver.sh}
9649 supports the following options, whose names are chosen for enhanced
9650 compatibility with the @command{prove} utility.
9653 @c Keep in sync with 'tap-exit.sh' and 'tap-signal.tap'.
9655 Causes the test driver to ignore the exit status of the test scripts;
9656 by default, the driver will report an error if the script exits with a
9657 non-zero status. This option has effect also on non-zero exit statuses
9658 due to termination by a signal.
9660 Instruct the test driver to display TAP diagnostic (i.e., lines beginning
9661 with the @samp{#} character) in the testsuite progress output too; by
9662 default, TAP diagnostic is only copied to the @file{.log} file.
9664 Revert the effects of @option{--comments}.
9666 Instruct the test driver to merge the test scripts' standard error into
9667 their standard output. This is necessary if you want to ensure that
9668 diagnostics from the test scripts are displayed in the correct order
9669 relative to test results; this can be of great help in debugging
9670 (especially if your test scripts are shell scripts run with shell
9671 tracing active). As a downside, this option might cause the test
9672 harness to get confused if anything that appears on standard error
9673 looks like a test result.
9675 Revert the effects of @option{--merge}.
9676 @item --diagnostic-string=@var{STRING}
9677 Change the string that introduces TAP diagnostic from the default value
9678 of ``@code{#}'' to @code{@var{STRING}}. This can be useful if your
9679 TAP-based test scripts produce verbose output on which they have limited
9680 control (because, say, the output comes from other tools invoked in the
9681 scripts), and it might contain text that gets spuriously interpreted as
9682 TAP diagnostic: such an issue can be solved by redefining the string that
9683 activates TAP diagnostic to a value you know won't appear by chance in
9684 the tests' output. Note however that this feature is non-standard, as
9685 the ``official'' TAP protocol does not allow for such a customization; so
9686 don't use it if you can avoid it.
9690 Here is an example of how the TAP driver can be set up and used.
9692 @c Keep in sync with tap-doc2.sh
9694 % @kbd{cat configure.ac}
9695 AC_INIT([GNU Try Tap], [1.0], [bug-automake@@gnu.org])
9696 AC_CONFIG_AUX_DIR([build-aux])
9697 AM_INIT_AUTOMAKE([foreign -Wall -Werror])
9698 AC_CONFIG_FILES([Makefile])
9699 AC_REQUIRE_AUX_FILE([tap-driver.sh])
9703 % @kbd{cat Makefile.am}
9704 TEST_LOG_DRIVER = env AM_TAP_AWK='$(AWK)' $(SHELL) \
9705 $(top_srcdir)/build-aux/tap-driver.sh
9706 TESTS = foo.test bar.test baz.test
9707 EXTRA_DIST = $(TESTS)
9709 % @kbd{cat foo.test}
9711 echo 1..4 # Number of tests to be executed.
9712 echo 'ok 1 - Swallows fly'
9713 echo 'not ok 2 - Caterpillars fly # TODO metamorphosis in progress'
9714 echo 'ok 3 - Pigs fly # SKIP not enough acid'
9715 echo '# I just love word plays ...'
9716 echo 'ok 4 - Flies fly too :-)'
9718 % @kbd{cat bar.test}
9721 echo 'not ok 1 - Bummer, this test has failed.'
9722 echo 'ok 2 - This passed though.'
9723 echo 'Bail out! Ennui kicking in, sorry...'
9724 echo 'ok 3 - This will not be seen.'
9726 % @kbd{cat baz.test}
9730 # Exit with error, even if all the tests have been successful.
9733 % @kbd{cp @var{PREFIX}/share/automake-@var{APIVERSION}/tap-driver.pl .}
9734 % @kbd{autoreconf -vi && ./configure && make check}
9736 PASS: foo.test 1 - Swallows fly
9737 XFAIL: foo.test 2 - Caterpillars fly # TODO metamorphosis in progress
9738 SKIP: foo.test 3 - Pigs fly # SKIP not enough acid
9739 PASS: foo.test 4 - Flies fly too :-)
9740 FAIL: bar.test 1 - Bummer, this test has failed.
9741 PASS: bar.test 2 - This passed though.
9742 ERROR: bar.test - Bail out! Ennui kicking in, sorry...
9744 ERROR: baz.test - exited with status 7
9746 Please report to bug-automake@@gnu.org
9748 % @kbd{echo exit status: $?}
9751 @c Keep the "skewed" indentation below, it produces pretty PDF output.
9752 % @kbd{env TEST_LOG_DRIVER_FLAGS='--comments --ignore-exit' \
9753 TESTS='foo.test baz.test' make -e check}
9755 PASS: foo.test 1 - Swallows fly
9756 XFAIL: foo.test 2 - Caterpillars fly # TODO metamorphosis in progress
9757 SKIP: foo.test 3 - Pigs fly # SKIP not enough acid
9758 # foo.test: I just love word plays...
9759 PASS: foo.test 4 - Flies fly too :-)
9762 % @kbd{echo exit status: $?}
9766 @node Incompatibilities with other TAP parsers and drivers
9767 @subsection Incompatibilities with other TAP parsers and drivers
9769 For implementation or historical reasons, the TAP driver and harness as
9770 implemented by Automake have some minors incompatibilities with the
9771 mainstream versions, which you should be aware of.
9775 A @code{Bail out!} directive doesn't stop the whole testsuite, but only
9776 the test script it occurs in. This doesn't follow TAP specifications,
9777 but on the other hand it maximizes compatibility (and code sharing) with
9778 the ``hard error'' concept of the default testsuite driver.
9780 The @code{version} and @code{pragma} directives are not supported.
9782 The @option{--diagnostic-string} option of our driver allows to modify
9783 the string that introduces TAP diagnostic from the default value
9784 of ``@code{#}''. The standard TAP protocol has currently no way to
9785 allow this, so if you use it your diagnostic will be lost to more
9786 compliant tools like @command{prove} and @code{Test::Harness}
9788 And there are probably some other small and yet undiscovered
9789 incompatibilities, especially in corner cases or with rare usages.
9792 @node Links and external resources on TAP
9793 @subsection Links and external resources on TAP
9796 Here are some links to more extensive official or third-party
9797 documentation and resources about the TAP protocol and related
9798 tools and libraries.
9801 @uref{http://search.cpan.org/~petdance/Test-Harness/lib/Test/Harness/TAP.pod,
9802 @samp{Test::Harness::TAP}},
9803 the (mostly) official documentation about the TAP format and protocol.
9805 @uref{http://search.cpan.org/~andya/Test-Harness/bin/prove,
9807 the most famous command-line TAP test driver, included in the distribution
9808 of @command{perl} and
9809 @uref{http://search.cpan.org/~andya/Test-Harness/lib/Test/Harness.pm,
9810 @samp{Test::Harness}}.
9812 The @uref{http://testanything.org/wiki/index.php/Main_Page,TAP wiki}.
9814 A ``gentle introduction'' to testing for perl coders:
9815 @uref{http://search.cpan.org/dist/Test-Simple/lib/Test/Tutorial.pod,
9816 @samp{Test::Tutorial}}.
9818 @uref{http://search.cpan.org/~mschwern/Test-Simple/lib/Test/Simple.pm,
9819 @samp{Test::Simple}}
9821 @uref{http://search.cpan.org/~mschwern/Test-Simple/lib/Test/More.pm,
9823 the standard perl testing libraries, which are based on TAP.
9825 @uref{http://www.eyrie.org/~eagle/software/c-tap-harness/,C TAP Harness},
9826 a C-based project implementing both a TAP producer and a TAP consumer.
9828 @uref{http://www.tap4j.org/,tap4j},
9829 a Java-based project implementing both a TAP producer and a TAP consumer.
9833 @section DejaGnu Tests
9835 If @uref{ftp://ftp.gnu.org/gnu/dejagnu/, @command{dejagnu}} appears in
9836 @code{AUTOMAKE_OPTIONS}, then a @command{dejagnu}-based test suite is
9837 assumed. The variable @code{DEJATOOL} is a list of names that are
9838 passed, one at a time, as the @option{--tool} argument to
9839 @command{runtest} invocations; it defaults to the name of the package.
9841 The variable @code{RUNTESTDEFAULTFLAGS} holds the @option{--tool} and
9842 @option{--srcdir} flags that are passed to dejagnu by default; this can be
9843 overridden if necessary.
9844 @vindex RUNTESTDEFAULTFLAGS
9846 The variables @code{EXPECT} and @code{RUNTEST} can
9847 also be overridden to provide project-specific values. For instance,
9848 you will need to do this if you are testing a compiler toolchain,
9849 because the default values do not take into account host and target
9856 The contents of the variable @code{RUNTESTFLAGS} are passed to the
9857 @code{runtest} invocation. This is considered a ``user variable''
9858 (@pxref{User Variables}). If you need to set @command{runtest} flags in
9859 @file{Makefile.am}, you can use @code{AM_RUNTESTFLAGS} instead.
9860 @vindex RUNTESTFLAGS
9861 @vindex AM_RUNTESTFLAGS
9863 @cindex @file{site.exp}
9864 Automake will generate rules to create a local @file{site.exp} file,
9865 defining various variables detected by @command{configure}. This file
9866 is automatically read by DejaGnu. It is OK for the user of a package
9867 to edit this file in order to tune the test suite. However this is
9868 not the place where the test suite author should define new variables:
9869 this should be done elsewhere in the real test suite code.
9870 Especially, @file{site.exp} should not be distributed.
9872 Still, if the package author has legitimate reasons to extend
9873 @file{site.exp} at @command{make} time, he can do so by defining
9874 the variable @code{EXTRA_DEJAGNU_SITE_CONFIG}; the files listed
9875 there will be considered @file{site.exp} prerequisites, and their
9876 content will be appended to it (in the same order in which they
9877 appear in @code{EXTRA_DEJAGNU_SITE_CONFIG}). Note that files are
9878 @emph{not} distributed by default.
9880 For more information regarding DejaGnu test suites, see @ref{Top, , ,
9881 dejagnu, The DejaGnu Manual}.
9884 @section Install Tests
9886 The @code{installcheck} target is available to the user as a way to
9887 run any tests after the package has been installed. You can add tests
9888 to this by writing an @code{installcheck-local} rule.
9892 @chapter Rebuilding Makefiles
9893 @cindex rebuild rules
9895 Automake generates rules to automatically rebuild @file{Makefile}s,
9896 @file{configure}, and other derived files like @file{Makefile.in}.
9898 @acindex AM_MAINTAINER_MODE
9899 If you are using @code{AM_MAINTAINER_MODE} in @file{configure.ac}, then
9900 these automatic rebuilding rules are only enabled in maintainer mode.
9902 @vindex CONFIG_STATUS_DEPENDENCIES
9903 @vindex CONFIGURE_DEPENDENCIES
9904 @cindex @file{version.sh}, example
9905 @cindex @file{version.m4}, example
9907 Sometimes it is convenient to supplement the rebuild rules for
9908 @file{configure} or @file{config.status} with additional dependencies.
9909 The variables @code{CONFIGURE_DEPENDENCIES} and
9910 @code{CONFIG_STATUS_DEPENDENCIES} can be used to list these extra
9911 dependencies. These variables should be defined in all
9912 @file{Makefile}s of the tree (because these two rebuild rules are
9913 output in all them), so it is safer and easier to @code{AC_SUBST} them
9914 from @file{configure.ac}. For instance, the following statement will
9915 cause @file{configure} to be rerun each time @file{version.sh} is
9918 @c Keep in sync with remake-config-status-dependencies.sh
9920 AC_SUBST([CONFIG_STATUS_DEPENDENCIES], ['$(top_srcdir)/version.sh'])
9924 Note the @samp{$(top_srcdir)/} in the file name. Since this variable
9925 is to be used in all @file{Makefile}s, its value must be sensible at
9926 any level in the build hierarchy.
9928 Beware not to mistake @code{CONFIGURE_DEPENDENCIES} for
9929 @code{CONFIG_STATUS_DEPENDENCIES}.
9931 @c Keep in sync with remake-configure-dependencies.sh
9932 @code{CONFIGURE_DEPENDENCIES} adds dependencies to the
9933 @file{configure} rule, whose effect is to run @command{autoconf}. This
9934 variable should be seldom used, because @command{automake} already tracks
9935 @code{m4_include}d files. However it can be useful when playing
9936 tricky games with @code{m4_esyscmd} or similar non-recommendable
9937 macros with side effects. Be also aware that interactions of this
9938 variable with the @ref{Autom4te Cache, , autom4te cache, autoconf,
9939 The Autoconf Manual} are quite problematic and can cause subtle
9940 breakage, so you might want to disable the cache if you want to use
9941 @code{CONFIGURE_DEPENDENCIES}.
9943 @code{CONFIG_STATUS_DEPENDENCIES} adds dependencies to the
9944 @file{config.status} rule, whose effect is to run @file{configure}.
9945 This variable should therefore carry any non-standard source that may
9946 be read as a side effect of running @command{configure}, like @file{version.sh}
9947 in the example above.
9949 Speaking of @file{version.sh} scripts, we recommend against them
9950 today. They are mainly used when the version of a package is updated
9951 automatically by a script (e.g., in daily builds). Here is what some
9952 old-style @file{configure.ac}s may look like:
9956 . $srcdir/version.sh
9957 AM_INIT_AUTOMAKE([name], $VERSION_NUMBER)
9962 Here, @file{version.sh} is a shell fragment that sets
9963 @code{VERSION_NUMBER}. The problem with this example is that
9964 @command{automake} cannot track dependencies (listing @file{version.sh}
9965 in @command{CONFIG_STATUS_DEPENDENCIES}, and distributing this file is up
9966 to the user), and that it uses the obsolete form of @code{AC_INIT} and
9967 @code{AM_INIT_AUTOMAKE}. Upgrading to the new syntax is not
9968 straightforward, because shell variables are not allowed in
9969 @code{AC_INIT}'s arguments. We recommend that @file{version.sh} be
9970 replaced by an M4 file that is included by @file{configure.ac}:
9973 m4_include([version.m4])
9974 AC_INIT([name], VERSION_NUMBER)
9980 Here @file{version.m4} could contain something like
9981 @samp{m4_define([VERSION_NUMBER], [1.2])}. The advantage of this
9982 second form is that @command{automake} will take care of the
9983 dependencies when defining the rebuild rule, and will also distribute
9984 the file automatically. An inconvenience is that @command{autoconf}
9985 will now be rerun each time the version number is bumped, when only
9986 @file{configure} had to be rerun in the previous setup.
9990 @chapter Changing Automake's Behavior
9993 * Options generalities:: Semantics of Automake option
9994 * List of Automake options:: A comprehensive list of Automake options
9997 @node Options generalities
9998 @section Options generalities
10000 Various features of Automake can be controlled by options. Except where
10001 noted otherwise, options can be specified in one of several ways. Most
10002 options can be applied on a per-@file{Makefile} basis when listed in a
10003 special @file{Makefile} variable named @code{AUTOMAKE_OPTIONS}. Some
10004 of these options only make sense when specified in the toplevel
10005 @file{Makefile.am} file. Options are applied globally to all processed
10006 @file{Makefile} files when listed in the first argument of
10007 @code{AM_INIT_AUTOMAKE} in @file{configure.ac}, and some options which
10008 require changes to the @command{configure} script can only be specified
10009 there. These are annotated below.
10011 As a general rule, options specified in @code{AUTOMAKE_OPTIONS} take
10012 precedence over those specified in @code{AM_INIT_AUTOMAKE}, which in
10013 turn take precedence over those specified on the command line.
10015 Also, some care must be taken about the interactions among strictness
10016 level and warning categories. As a general rule, strictness-implied
10017 warnings are overridden by those specified by explicit options. For
10018 example, even if @samp{portability} warnings are disabled by default
10019 in @option{foreign} strictness, an usage like this will end up enabling
10023 AUTOMAKE_OPTIONS = -Wportability foreign
10026 However, a strictness level specified in a higher-priority context
10027 will override all the explicit warnings specified in a lower-priority
10028 context. For example, if @file{configure.ac} contains:
10031 AM_INIT_AUTOMAKE([-Wportability])
10035 and @file{Makefile.am} contains:
10038 AUTOMAKE_OPTIONS = foreign
10042 then @samp{portability} warnings will be @emph{disabled} in
10043 @file{Makefile.am}.
10045 @node List of Automake options
10046 @section List of Automake options
10048 @vindex AUTOMAKE_OPTIONS
10051 @item @option{gnits}
10052 @itemx @option{gnu}
10053 @itemx @option{foreign}
10054 @cindex Option, @option{gnits}
10055 @cindex Option, @option{gnu}
10056 @cindex Option, @option{foreign}
10061 Set the strictness as appropriate. The @option{gnits} option also
10062 implies options @option{readme-alpha} and @option{check-news}.
10064 @item @option{check-news}
10065 @cindex Option, @option{check-news}
10066 @opindex check-news
10067 Cause @samp{make dist} to fail unless the current version number appears
10068 in the first few lines of the @file{NEWS} file.
10070 @item @option{dejagnu}
10071 @cindex Option, @option{dejagnu}
10073 Cause @command{dejagnu}-specific rules to be generated. @xref{DejaGnu Tests}.
10075 @item @option{dist-bzip2}
10076 @cindex Option, @option{dist-bzip2}
10077 @opindex dist-bzip2
10078 Hook @code{dist-bzip2} to @code{dist}.
10079 @trindex dist-bzip2
10081 @item @option{dist-lzip}
10082 @cindex Option, @option{dist-lzip}
10084 Hook @code{dist-lzip} to @code{dist}.
10087 @item @option{dist-xz}
10088 @cindex Option, @option{dist-xz}
10090 Hook @code{dist-xz} to @code{dist}.
10093 @item @option{dist-zip}
10094 @cindex Option, @option{dist-zip}
10096 Hook @code{dist-zip} to @code{dist}.
10099 @item @option{dist-shar}
10100 @cindex Option, @option{dist-shar}
10102 Hook @code{dist-shar} to @code{dist}. Use of this option
10103 is discouraged, as the @samp{shar} format is obsolescent and
10107 @item @option{dist-tarZ}
10108 @cindex Option, @option{dist-tarZ}
10110 Hook @code{dist-tarZ} to @code{dist}. Use of this option
10111 is discouraged, as the @samp{compress} program is obsolete.
10114 @item @option{filename-length-max=99}
10115 @cindex Option, @option{filename-length-max=99}
10116 @opindex filename-length-max=99
10117 Abort if file names longer than 99 characters are found during
10118 @samp{make dist}. Such long file names are generally considered not to
10119 be portable in tarballs. See the @option{tar-v7} and @option{tar-ustar}
10120 options below. This option should be used in the top-level
10121 @file{Makefile.am} or as an argument of @code{AM_INIT_AUTOMAKE} in
10122 @file{configure.ac}, it will be ignored otherwise. It will also be
10123 ignored in sub-packages of nested packages (@pxref{Subpackages}).
10125 @item @option{info-in-builddir}
10126 @cindex Option, @option{info-in-builddir}
10127 @opindex info-in-builddir
10128 Instruct Automake to place the generated @file{.info} files in the
10129 @code{builddir} rather than in the @code{srcdir}. Note that this
10130 might make VPATH builds with some non-GNU make implementations more
10133 @item @option{no-define}
10134 @cindex Option, @option{no-define}
10136 This option is meaningful only when passed as an argument to
10137 @code{AM_INIT_AUTOMAKE}. It will prevent the @code{PACKAGE} and
10138 @code{VERSION} variables from being @code{AC_DEFINE}d.
10140 @item @option{no-dependencies}
10141 @cindex Option, @option{no-dependencies}
10142 @opindex no-dependencies
10143 This is similar to using @option{--ignore-deps} on the command line,
10144 but is useful for those situations where you don't have the necessary
10145 bits to make automatic dependency tracking work
10146 (@pxref{Dependencies}). In this case the effect is to effectively
10147 disable automatic dependency tracking.
10149 @item @option{no-dist}
10150 @cindex Option, @option{no-dist}
10152 Don't emit any code related to @code{dist} target. This is useful
10153 when a package has its own method for making distributions.
10155 @item @option{no-dist-gzip}
10156 @cindex Option, @option{no-dist-gzip}
10157 @opindex no-dist-gzip
10158 Do not hook @code{dist-gzip} to @code{dist}.
10159 @trindex no-dist-gzip
10161 @item @option{no-exeext}
10162 @cindex Option, @option{no-exeext}
10164 If your @file{Makefile.am} defines a rule for target @code{foo}, it
10165 will override a rule for a target named @samp{foo$(EXEEXT)}. This is
10166 necessary when @code{EXEEXT} is found to be empty. However, by
10167 default @command{automake} will generate an error for this use. The
10168 @option{no-exeext} option will disable this error. This is intended for
10169 use only where it is known in advance that the package will not be
10170 ported to Windows, or any other operating system using extensions on
10173 @item @option{no-installinfo}
10174 @cindex Option, @option{no-installinfo}
10175 @opindex no-installinfo
10176 The generated @file{Makefile.in} will not cause info pages to be built
10177 or installed by default. However, @code{info} and @code{install-info}
10178 targets will still be available. This option is disallowed at
10179 @option{gnu} strictness and above.
10181 @trindex install-info
10183 @item @option{no-installman}
10184 @cindex Option, @option{no-installman}
10185 @opindex no-installman
10186 The generated @file{Makefile.in} will not cause man pages to be
10187 installed by default. However, an @code{install-man} target will still
10188 be available for optional installation. This option is disallowed at
10189 @option{gnu} strictness and above.
10190 @trindex install-man
10192 @item @option{nostdinc}
10193 @cindex Option, @option{nostdinc}
10195 This option can be used to disable the standard @option{-I} options that
10196 are ordinarily automatically provided by Automake.
10198 @item @option{no-texinfo.tex}
10199 @cindex Option, @option{no-texinfo.tex}
10200 @opindex no-texinfo.tex
10201 Don't require @file{texinfo.tex}, even if there are texinfo files in
10204 @item @option{serial-tests}
10205 @cindex Option, @option{serial-tests}
10206 @opindex serial-tests
10207 Enable the older serial test suite harness for @code{TESTS} (@pxref{Serial
10208 Test Harness}, for more information).
10210 @item @option{parallel-tests}
10211 @cindex Option, @option{parallel-tests}
10212 @opindex parallel-tests
10213 Enable test suite harness for @code{TESTS} that can run tests in parallel
10214 (@pxref{Parallel Test Harness}, for more information). This option is
10215 only kept for backward-compatibility, since the parallel test harness is
10218 @item @option{readme-alpha}
10219 @cindex Option, @option{readme-alpha}
10220 @opindex readme-alpha
10221 If this release is an alpha release, and the file @file{README-alpha}
10222 exists, then it will be added to the distribution. If this option is
10223 given, version numbers are expected to follow one of two forms. The
10224 first form is @samp{@var{major}.@var{minor}.@var{alpha}}, where each
10225 element is a number; the final period and number should be left off for
10226 non-alpha releases. The second form is
10227 @samp{@var{major}.@var{minor}@var{alpha}}, where @var{alpha} is a
10228 letter; it should be omitted for non-alpha releases.
10230 @item @option{std-options}
10231 @cindex Options, @option{std-options}
10232 @cindex @samp{make installcheck}, testing @option{--help} and @option{--version}
10233 @cindex @option{--help} check
10234 @cindex @option{--version} check
10235 @opindex std-options
10237 Make the @code{installcheck} rule check that installed scripts and
10238 programs support the @option{--help} and @option{--version} options.
10239 This also provides a basic check that the program's
10240 run-time dependencies are satisfied after installation.
10242 @vindex AM_INSTALLCHECK_STD_OPTIONS_EXEMPT
10243 In a few situations, programs (or scripts) have to be exempted from this
10244 test. For instance, @command{false} (from GNU coreutils) is never
10245 successful, even for @option{--help} or @option{--version}. You can list
10246 such programs in the variable @code{AM_INSTALLCHECK_STD_OPTIONS_EXEMPT}.
10247 Programs (not scripts) listed in this variable should be suffixed by
10248 @samp{$(EXEEXT)} for the sake of Windows or OS/2. For instance, suppose we
10249 build @file{false} as a program but @file{true.sh} as a script, and that
10250 neither of them support @option{--help} or @option{--version}:
10253 AUTOMAKE_OPTIONS = std-options
10254 bin_PROGRAMS = false ...
10255 bin_SCRIPTS = true.sh ...
10256 AM_INSTALLCHECK_STD_OPTIONS_EXEMPT = false$(EXEEXT) true.sh
10259 @item @option{subdir-objects}
10260 @cindex Options, @option{subdir-objects}
10261 @opindex subdir-objects
10262 If this option is specified, then objects are placed into the
10263 subdirectory of the build directory corresponding to the subdirectory of
10264 the source file. For instance, if the source file is
10265 @file{subdir/file.cxx}, then the output file would be
10266 @file{subdir/file.o}.
10268 @anchor{tar-formats}
10269 @item @option{tar-v7}
10270 @itemx @option{tar-ustar}
10271 @itemx @option{tar-pax}
10272 @cindex Option, @option{tar-v7}
10273 @cindex Option, @option{tar-ustar}
10274 @cindex Option, @option{tar-pax}
10275 @cindex @command{tar} formats
10276 @cindex v7 @command{tar} format
10277 @cindex ustar format
10283 These three mutually exclusive options select the tar format to use
10284 when generating tarballs with @samp{make dist}. (The tar file created
10285 is then compressed according to the set of @option{no-dist-gzip},
10286 @option{dist-bzip2}, @option{dist-lzip}, @option{dist-xz} and
10287 @option{dist-tarZ} options in use.)
10289 These options must be passed as arguments to @code{AM_INIT_AUTOMAKE}
10290 (@pxref{Macros}) because they can require additional configure checks.
10291 Automake will complain if it sees such options in an
10292 @code{AUTOMAKE_OPTIONS} variable.
10294 @option{tar-v7} selects the old V7 tar format. This is the historical
10295 default. This antiquated format is understood by all tar
10296 implementations and supports file names with up to 99 characters. When
10297 given longer file names some tar implementations will diagnose the
10298 problem while other will generate broken tarballs or use non-portable
10299 extensions. Furthermore, the V7 format cannot store empty
10300 directories. When using this format, consider using the
10301 @option{filename-length-max=99} option to catch file names too long.
10303 @option{tar-ustar} selects the ustar format defined by POSIX
10304 1003.1-1988. This format is believed to be old enough to be portable.
10305 It fully supports empty directories. It can store file names with up
10306 to 256 characters, provided that the file name can be split at
10307 directory separator in two parts, first of them being at most 155
10308 bytes long. So, in most cases the maximum file name length will be
10309 shorter than 256 characters. However you may run against broken tar
10310 implementations that incorrectly handle file names longer than 99
10311 characters (please report them to @email{@value{PACKAGE_BUGREPORT}} so we
10312 can document this accurately).
10314 @option{tar-pax} selects the new pax interchange format defined by POSIX
10315 1003.1-2001. It does not limit the length of file names. However,
10316 this format is very young and should probably be restricted to
10317 packages that target only very modern platforms. There are moves to
10318 change the pax format in an upward-compatible way, so this option may
10319 refer to a more recent version in the future.
10321 @xref{Formats, , Controlling the Archive Format, tar, GNU Tar}, for
10322 further discussion about tar formats.
10324 @command{configure} knows several ways to construct these formats. It
10325 will not abort if it cannot find a tool up to the task (so that the
10326 package can still be built), but @samp{make dist} will fail.
10328 @item @var{version}
10329 @cindex Option, @var{version}
10330 A version number (e.g., @samp{0.30}) can be specified. If Automake is not
10331 newer than the version specified, creation of the @file{Makefile.in}
10332 will be suppressed.
10334 @item @option{-W@var{category}} or @option{--warnings=@var{category}}
10335 @cindex Option, warnings
10336 @cindex Option, @option{-W@var{category}}
10337 @cindex Option, @option{--warnings=@var{category}}
10338 These options behave exactly like their command-line counterpart
10339 (@pxref{automake Invocation}). This allows you to enable or disable some
10340 warning categories on a per-file basis. You can also setup some warnings
10341 for your entire project; for instance, try @samp{AM_INIT_AUTOMAKE([-Wall])}
10342 in your @file{configure.ac}.
10346 Unrecognized options are diagnosed by @command{automake}.
10348 If you want an option to apply to all the files in the tree, you can use
10349 the @code{AM_INIT_AUTOMAKE} macro in @file{configure.ac}.
10353 @node Miscellaneous
10354 @chapter Miscellaneous Rules
10356 There are a few rules and variables that didn't fit anywhere else.
10359 * Tags:: Interfacing to cscope, etags and mkid
10360 * Suffixes:: Handling new file extensions
10365 @section Interfacing to @command{etags}
10367 @cindex @file{TAGS} support
10369 Automake will generate rules to generate @file{TAGS} files for use with
10370 GNU Emacs under some circumstances.
10373 If any C, C++ or Fortran 77 source code or headers are present, then
10374 @code{tags} and @code{TAGS} rules will be generated for the directory.
10375 All files listed using the @code{_SOURCES}, @code{_HEADERS}, and
10376 @code{_LISP} primaries will be used to generate tags. Note that
10377 generated source files that are not distributed must be declared in
10378 variables like @code{nodist_noinst_HEADERS} or
10379 @code{nodist_@var{prog}_SOURCES} or they will be ignored.
10381 A @code{tags} rule will be output at the topmost directory of a
10382 multi-directory package. When run from this topmost directory,
10383 @samp{make tags} will generate a @file{TAGS} file that includes by
10384 reference all @file{TAGS} files from subdirectories.
10386 The @code{tags} rule will also be generated if the variable
10387 @code{ETAGS_ARGS} is defined. This variable is intended for use in
10388 directories that contain taggable source that @command{etags} does
10389 not understand. The user can use the @code{ETAGSFLAGS} to pass
10390 additional flags to @command{etags}; @code{AM_ETAGSFLAGS} is also
10391 available for use in @file{Makefile.am}.
10394 @vindex AM_ETAGSFLAGS
10396 Here is how Automake generates tags for its source, and for nodes in its
10400 ETAGS_ARGS = automake.in --lang=none \
10401 --regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi
10404 If you add file names to @code{ETAGS_ARGS}, you will probably also
10405 want to define @code{TAGS_DEPENDENCIES}. The contents of this variable
10406 are added directly to the dependencies for the @code{tags} rule.
10407 @vindex TAGS_DEPENDENCIES
10409 Automake also generates a @code{ctags} rule that can be used to
10410 build @command{vi}-style @file{tags} files. The variable @code{CTAGS}
10411 is the name of the program to invoke (by default @command{ctags});
10412 @code{CTAGSFLAGS} can be used by the user to pass additional flags,
10413 and @code{AM_CTAGSFLAGS} can be used by the @file{Makefile.am}.
10416 Automake will also generate an @code{ID} rule that will run
10417 @command{mkid} on the source. This is only supported on a
10418 directory-by-directory basis.
10420 Similarly, the @code{cscope} rule will create a list of all the source
10421 files in the tree and run @command{cscope} to build an inverted index
10422 database. The variable @code{CSCOPE} is the name of the program to invoke
10423 (by default @command{cscope}); @code{CSCOPEFLAGS} and
10424 @code{CSCOPE_ARGS} can be used by the user to pass additional flags and
10425 file names respectively, while @code{AM_CSCOPEFLAGS} can be used by the
10426 @file{Makefile.am}. Note that, currently, the Automake-provided
10427 @code{cscope} support, when used in a VPATH build, might not work well
10428 with non-GNU make implementations (especially with make implementations
10429 performing @ref{Automatic Rule Rewriting, , VPATH rewrites, autoconf,
10430 The Autoconf Manual}).
10432 Finally, Automake also emits rules to support the
10433 @uref{http://www.gnu.org/software/global/, GNU Global Tags program}.
10434 The @code{GTAGS} rule runs Global Tags and puts the
10435 result in the top build directory. The variable @code{GTAGS_ARGS}
10436 holds arguments that are passed to @command{gtags}.
10441 @section Handling new file extensions
10443 @cindex Adding new @code{SUFFIXES}
10444 @cindex @code{SUFFIXES}, adding
10447 It is sometimes useful to introduce a new implicit rule to handle a file
10448 type that Automake does not know about.
10450 For instance, suppose you had a compiler that could compile @file{.foo}
10451 files to @file{.o} files. You would simply define a suffix rule for
10459 Then you could directly use a @file{.foo} file in a @code{_SOURCES}
10460 variable and expect the correct results:
10463 bin_PROGRAMS = doit
10464 doit_SOURCES = doit.foo
10467 This was the simpler and more common case. In other cases, you will
10468 have to help Automake to figure out which extensions you are defining your
10469 suffix rule for. This usually happens when your extension does not
10470 start with a dot. Then, all you have to do is to put a list of new
10471 suffixes in the @code{SUFFIXES} variable @strong{before} you define your
10474 For instance, the following definition prevents Automake from misinterpreting
10475 the @samp{.idlC.cpp:} rule as an attempt to transform @file{.idlC} files into
10478 @c Keep in sync with suffix7.sh
10480 SUFFIXES = .idl C.cpp
10485 As you may have noted, the @code{SUFFIXES} variable behaves like the
10486 @code{.SUFFIXES} special target of @command{make}. You should not touch
10487 @code{.SUFFIXES} yourself, but use @code{SUFFIXES} instead and let
10488 Automake generate the suffix list for @code{.SUFFIXES}. Any given
10489 @code{SUFFIXES} go at the start of the generated suffixes list, followed
10490 by Automake generated suffixes not already in the list.
10496 @cindex Including @file{Makefile} fragment
10497 @cindex @file{Makefile} fragment, including
10499 Automake supports an @code{include} directive that can be used to
10500 include other @file{Makefile} fragments when @command{automake} is run.
10501 Note that these fragments are read and interpreted by @command{automake},
10502 not by @command{make}. As with conditionals, @command{make} has no idea that
10503 @code{include} is in use.
10505 There are two forms of @code{include}:
10508 @item include $(srcdir)/file
10509 Include a fragment that is found relative to the current source
10512 @item include $(top_srcdir)/file
10513 Include a fragment that is found relative to the top source directory.
10516 Note that if a fragment is included inside a conditional, then the
10517 condition applies to the entire contents of that fragment.
10519 Makefile fragments included this way are always distributed because
10520 they are needed to rebuild @file{Makefile.in}.
10523 @chapter Conditionals
10525 @cindex Conditionals
10527 Automake supports a simple type of conditionals.
10529 These conditionals are not the same as conditionals in
10530 GNU Make. Automake conditionals are checked at configure time by the
10531 @file{configure} script, and affect the translation from
10532 @file{Makefile.in} to @file{Makefile}. They are based on options passed
10533 to @file{configure} and on results that @file{configure} has discovered
10534 about the host system. GNU Make conditionals are checked at @command{make}
10535 time, and are based on variables passed to the make program or defined
10536 in the @file{Makefile}.
10538 Automake conditionals will work with any make program.
10541 * Usage of Conditionals:: Declaring conditional content
10542 * Limits of Conditionals:: Enclosing complete statements
10545 @node Usage of Conditionals
10546 @section Usage of Conditionals
10548 @acindex AM_CONDITIONAL
10549 Before using a conditional, you must define it by using
10550 @code{AM_CONDITIONAL} in the @file{configure.ac} file (@pxref{Macros}).
10552 @defmac AM_CONDITIONAL (@var{conditional}, @var{condition})
10553 The conditional name, @var{conditional}, should be a simple string
10554 starting with a letter and containing only letters, digits, and
10555 underscores. It must be different from @samp{TRUE} and @samp{FALSE}
10556 that are reserved by Automake.
10558 The shell @var{condition} (suitable for use in a shell @code{if}
10559 statement) is evaluated when @command{configure} is run. Note that you
10560 must arrange for @emph{every} @code{AM_CONDITIONAL} to be invoked every
10561 time @command{configure} is run. If @code{AM_CONDITIONAL} is run
10562 conditionally (e.g., in a shell @code{if} statement), then the result
10563 will confuse @command{automake}.
10566 @cindex @option{--enable-debug}, example
10567 @cindex Example conditional @option{--enable-debug}
10568 @cindex Conditional example, @option{--enable-debug}
10570 Conditionals typically depend upon options that the user provides to
10571 the @command{configure} script. Here is an example of how to write a
10572 conditional that is true if the user uses the @option{--enable-debug}
10576 AC_ARG_ENABLE([debug],
10577 [ --enable-debug Turn on debugging],
10578 [case "$@{enableval@}" in
10581 *) AC_MSG_ERROR([bad value $@{enableval@} for --enable-debug]) ;;
10582 esac],[debug=false])
10583 AM_CONDITIONAL([DEBUG], [test x$debug = xtrue])
10586 Here is an example of how to use that conditional in @file{Makefile.am}:
10598 noinst_PROGRAMS = $(DBG)
10601 This trivial example could also be handled using @code{EXTRA_PROGRAMS}
10602 (@pxref{Conditional Programs}).
10604 You may only test a single variable in an @code{if} statement, possibly
10605 negated using @samp{!}. The @code{else} statement may be omitted.
10606 Conditionals may be nested to any depth. You may specify an argument to
10607 @code{else} in which case it must be the negation of the condition used
10608 for the current @code{if}. Similarly you may specify the condition
10609 that is closed on the @code{endif} line:
10620 Unbalanced conditions are errors. The @code{if}, @code{else}, and
10621 @code{endif} statements should not be indented, i.e., start on column
10624 The @code{else} branch of the above two examples could be omitted,
10625 since assigning the empty string to an otherwise undefined variable
10626 makes no difference.
10628 @acindex AM_COND_IF
10629 In order to allow access to the condition registered by
10630 @code{AM_CONDITIONAL} inside @file{configure.ac}, and to allow
10631 conditional @code{AC_CONFIG_FILES}, @code{AM_COND_IF} may be used:
10633 @defmac AM_COND_IF (@var{conditional}, @ovar{if-true}, @ovar{if-false})
10634 If @var{conditional} is fulfilled, execute @var{if-true}, otherwise
10635 execute @var{if-false}. If either branch contains @code{AC_CONFIG_FILES},
10636 it will cause @command{automake} to output the rules for the respective
10637 files only for the given condition.
10640 @code{AM_COND_IF} macros may be nested when m4 quotation is used
10641 properly (@pxref{M4 Quotation, ,, autoconf, The Autoconf Manual}).
10643 @cindex Example conditional @code{AC_CONFIG_FILES}
10644 @cindex @code{AC_CONFIG_FILES}, conditional
10646 Here is an example of how to define a conditional config file:
10649 AM_CONDITIONAL([SHELL_WRAPPER], [test "x$with_wrapper" = xtrue])
10650 AM_COND_IF([SHELL_WRAPPER],
10651 [AC_CONFIG_FILES([wrapper:wrapper.in])])
10654 @node Limits of Conditionals
10655 @section Limits of Conditionals
10657 Conditionals should enclose complete statements like variables or
10658 rules definitions. Automake cannot deal with conditionals used inside
10659 a variable definition, for instance, and is not even able to diagnose
10660 this situation. The following example would not work:
10663 # This syntax is not understood by Automake
10672 However the intended definition of @code{AM_CPPFLAGS} can be achieved
10677 DEBUGFLAGS = -DDEBUG
10679 AM_CPPFLAGS = -DFEATURE_A $(DEBUGFLAGS) -DFEATURE_B
10686 AM_CPPFLAGS = -DFEATURE_A
10688 AM_CPPFLAGS += -DDEBUG
10690 AM_CPPFLAGS += -DFEATURE_B
10693 More details and examples of conditionals are described alongside
10694 various Automake features in this manual (@pxref{Conditional
10695 Subdirectories}, @pxref{Conditional Sources}, @pxref{Conditional
10696 Programs}, @pxref{Conditional Libtool Libraries}, @pxref{Conditional
10699 @node Silencing Make
10700 @chapter Silencing @command{make}
10702 @cindex Silent @command{make}
10703 @cindex Silencing @command{make}
10704 @cindex Silent rules
10705 @cindex Silent @command{make} rules
10708 * Make verbosity:: Make is verbose by default
10709 * Tricks For Silencing Make:: Standard and generic ways to silence make
10710 * Automake Silent Rules:: How Automake can help in silencing make
10713 @node Make verbosity
10714 @section Make is verbose by default
10716 Normally, when executing the set of rules associated with a target,
10717 @command{make} prints each rule before it is executed. This behaviour,
10718 while having been in place for a long time, and being even mandated by
10719 the POSIX standard, starkly violates the ``silence is golden'' UNIX
10720 principle@footnote{See also
10721 @uref{http://catb.org/~esr/writings/taoup/html/ch11s09.html}.}:
10724 When a program has nothing interesting or surprising to say, it should
10725 say nothing. Well-behaved Unix programs do their jobs unobtrusively,
10726 with a minimum of fuss and bother. Silence is golden.
10729 In fact, while such verbosity of @command{make} can theoretically be
10730 useful to track bugs and understand reasons of failures right away, it
10731 can also hide warning and error messages from @command{make}-invoked
10732 tools, drowning them in a flood of uninteresting and seldom useful
10733 messages, and thus allowing them to go easily undetected.
10735 This problem can be very annoying, especially for developers, who usually
10736 know quite well what's going on behind the scenes, and for whom the
10737 verbose output from @command{make} ends up being mostly noise that hampers
10738 the easy detection of potentially important warning messages.
10740 @node Tricks For Silencing Make
10741 @section Standard and generic ways to silence make
10743 Here we describe some common idioms/tricks to obtain a quieter make
10744 output, with their relative advantages and drawbacks. In the next
10745 section (@ref{Automake Silent Rules}) we'll see how Automake can help
10746 in this respect, providing more elaborate and flexible idioms.
10750 @item @command{make -s}
10752 This simply causes @command{make} not to print @emph{any} rule before
10755 The @option{-s} flag is mandated by POSIX, universally supported, and
10756 its purpose and function are easy to understand.
10758 But it also has its serious limitations too. First of all, it embodies
10759 an ``all or nothing'' strategy, i.e., either everything is silenced, or
10760 nothing is; this lack of granularity can sometimes be a fatal flaw.
10761 Moreover, when the @option{-s} flag is used, the @command{make} output
10762 might turn out to be too much terse; in case of errors, the user won't
10763 be able to easily see what rule or command have caused them, or even,
10764 in case of tools with poor error reporting, what the errors were!
10766 @item @command{make >/dev/null || make}
10768 Apparently, this perfectly obeys the ``silence is golden'' rule: warnings
10769 from stderr are passed through, output reporting is done only in case of
10770 error, and in that case it should provide a verbose-enough report to allow
10771 an easy determination of the error location and causes.
10773 However, calling @command{make} two times in a row might hide errors
10774 (especially intermittent ones), or subtly change the expected semantic
10775 of the @command{make} calls --- things these which can clearly make
10776 debugging and error assessment very difficult.
10778 @item @command{make --no-print-directory}
10780 This is GNU @command{make} specific. When called with the
10781 @option{--no-print-directory} option, GNU @command{make} will disable
10782 printing of the working directory by invoked sub-@command{make}s (the
10783 well-known ``@i{Entering/Leaving directory ...}'' messages). This helps
10784 to decrease the verbosity of the output, but experience has shown that
10785 it can also often render debugging considerably harder in projects using
10786 deeply-nested @command{make} recursion.
10788 As an aside, notice that the @option{--no-print-directory} option is
10789 automatically activated if the @option{-s} flag is used.
10791 @c TODO: Other tricks?
10792 @c TODO: Maybe speak about the @code{.SILENT} target?
10793 @c TODO: - Pros: More granularity on what to silence.
10794 @c TODO: - Cons: No easy way to temporarily override.
10798 @node Automake Silent Rules
10799 @section How Automake can help in silencing make
10801 The tricks and idioms for silencing @command{make} described in the
10802 previous section can be useful from time to time, but we've seen that
10803 they all have their serious drawbacks and limitations. That's why
10804 automake provides support for a more advanced and flexible way of
10805 obtaining quieter output from @command{make} (for most rules at least).
10807 @c TODO: Maybe describe in brief the precedent set by the build system
10808 @c of the Linux Kernel, from which Automake took inspiration ... Links?
10810 To give the gist of what Automake can do in this respect, here is a simple
10811 comparison between a typical @command{make} output (where silent rules
10812 are disabled) and one with silent rules enabled:
10815 % @kbd{cat Makefile.am}
10817 foo_SOURCES = main.c func.c
10819 int main (void) @{ return func (); @} /* func used undeclared */
10821 int func (void) @{ int i; return i; @} /* i used uninitialized */
10823 @i{The make output is by default very verbose. This causes warnings
10824 from the compiler to be somewhat hidden, and not immediate to spot.}
10825 % @kbd{make CFLAGS=-Wall}
10826 gcc -DPACKAGE_NAME=\"foo\" -DPACKAGE_TARNAME=\"foo\" ...
10827 -DPACKAGE_STRING=\"foo\ 1.0\" -DPACKAGE_BUGREPORT=\"\" ...
10828 -DPACKAGE=\"foo\" -DVERSION=\"1.0\" -I. -Wall -MT main.o
10829 -MD -MP -MF .deps/main.Tpo -c -o main.o main.c
10830 main.c: In function ‘main’:
10831 main.c:3:3: warning: implicit declaration of function ‘func’
10832 mv -f .deps/main.Tpo .deps/main.Po
10833 gcc -DPACKAGE_NAME=\"foo\" -DPACKAGE_TARNAME=\"foo\" ...
10834 -DPACKAGE_STRING=\"foo\ 1.0\" -DPACKAGE_BUGREPORT=\"\" ...
10835 -DPACKAGE=\"foo\" -DVERSION=\"1.0\" -I. -Wall -MT func.o
10836 -MD -MP -MF .deps/func.Tpo -c -o func.o func.c
10837 func.c: In function ‘func’:
10838 func.c:4:3: warning: ‘i’ used uninitialized in this function
10839 mv -f .deps/func.Tpo .deps/func.Po
10840 gcc -Wall -o foo main.o func.o
10842 @i{Clean up, so that we we can rebuild everything from scratch.}
10844 test -z "foo" || rm -f foo
10847 @i{Silent rules enabled: the output is minimal but informative. In
10848 particular, the warnings from the compiler stick out very clearly.}
10849 % @kbd{make V=0 CFLAGS=-Wall}
10851 main.c: In function ‘main’:
10852 main.c:3:3: warning: implicit declaration of function ‘func’
10854 func.c: In function ‘func’:
10855 func.c:4:3: warning: ‘i’ used uninitialized in this function
10859 @cindex silent rules and libtool
10860 Also, in projects using @command{libtool}, the use of silent rules can
10861 automatically enable the @command{libtool}'s @option{--silent} option:
10864 % @kbd{cat Makefile.am}
10865 lib_LTLIBRARIES = libx.la
10867 % @kbd{make # Both make and libtool are verbose by default.}
10869 libtool: compile: gcc -DPACKAGE_NAME=\"foo\" ... -DLT_OBJDIR=\".libs/\"
10870 -I. -g -O2 -MT libx.lo -MD -MP -MF .deps/libx.Tpo -c libx.c -fPIC
10871 -DPIC -o .libs/libx.o
10872 mv -f .deps/libx.Tpo .deps/libx.Plo
10873 /bin/sh ./libtool --tag=CC --mode=link gcc -g -O2 -o libx.la -rpath
10874 /usr/local/lib libx.lo
10875 libtool: link: gcc -shared .libs/libx.o -Wl,-soname -Wl,libx.so.0
10876 -o .libs/libx.so.0.0.0
10877 libtool: link: cd .libs && rm -f libx.so && ln -s libx.so.0.0.0 libx.so
10885 For Automake-generated @file{Makefile}s, the user may influence the
10886 verbosity at @command{configure} run time as well as at @command{make}
10891 @opindex --enable-silent-rules
10892 @opindex --disable-silent-rules
10893 Passing @option{--enable-silent-rules} to @command{configure} will cause
10894 build rules to be less verbose; the option @option{--disable-silent-rules}
10895 will cause normal verbose output.
10898 At @command{make} run time, the default chosen at @command{configure}
10899 time may be overridden: @code{make V=1} will produce verbose output,
10900 @code{make V=0} less verbose output.
10903 @cindex default verbosity for silent rules
10904 Note that silent rules are @emph{disabled} by default; the user must
10905 enable them explicitly at either @command{configure} run time or at
10906 @command{make} run time. We think that this is a good policy, since
10907 it provides the casual user with enough information to prepare a good
10908 bug report in case anything breaks.
10910 Still, notwithstanding the rationales above, a developer who really
10911 wants to make silent rules enabled by default in his own package can
10912 do so by calling @code{AM_SILENT_RULES([yes])} in @file{configure.ac}.
10914 @c Keep in sync with silent-configsite.sh
10915 Users who prefer to have silent rules enabled by default can edit their
10916 @file{config.site} file to make the variable @code{enable_silent_rules}
10917 default to @samp{yes}. This should still allow disabling silent rules
10918 at @command{configure} time and at @command{make} time.
10920 @c FIXME: there's really a need to specify this explicitly?
10921 For portability to different @command{make} implementations, package authors
10922 are advised to not set the variable @code{V} inside the @file{Makefile.am}
10923 file, to allow the user to override the value for subdirectories as well.
10925 To work at its best, the current implementation of this feature normally
10926 uses nested variable expansion @samp{$(@var{var1}$(V))}, a @file{Makefile}
10927 feature that is not required by POSIX 2008 but is widely supported in
10928 practice. On the rare @command{make} implementations that do not support
10929 nested variable expansion, whether rules are silent is always determined at
10930 configure time, and cannot be overridden at make time. Future versions of
10931 POSIX are likely to require nested variable expansion, so this minor
10932 limitation should go away with time.
10934 @vindex @code{AM_V_GEN}
10935 @vindex @code{AM_V_at}
10936 @vindex @code{AM_DEFAULT_VERBOSITY}
10937 @vindex @code{AM_V}
10938 @vindex @code{AM_DEFAULT_V}
10939 To extend the silent mode to your own rules, you have few choices:
10944 You can use the predefined variable @code{AM_V_GEN} as a prefix to
10945 commands that should output a status line in silent mode, and
10946 @code{AM_V_at} as a prefix to commands that should not output anything
10947 in silent mode. When output is to be verbose, both of these variables
10948 will expand to the empty string.
10951 You can silence a recipe unconditionally with @code{@@}, and then use
10952 the predefined variable @code{AM_V_P} to know whether make is being run
10953 in silent or verbose mode, adjust the verbose information your recipe
10954 displays accordingly:
10959 ... [commands defining a shell variable '$headers'] ...; \
10960 if $(AM_V_P); then set -x; else echo " GEN [headers]"; fi; \
10961 rm -f $$headers && generate-header --flags $$headers
10965 You can add your own variables, so strings of your own choice are shown.
10966 The following snippet shows how you would define your own equivalent of
10970 pkg_verbose = $(pkg_verbose_@@AM_V@@)
10971 pkg_verbose_ = $(pkg_verbose_@@AM_DEFAULT_V@@)
10972 pkg_verbose_0 = @@echo PKG-GEN $@@;
10975 $(pkg_verbose)cp $(srcdir)/foo.in $@@
10980 As a final note, observe that, even when silent rules are enabled,
10981 the @option{--no-print-directory} option is still required with GNU
10982 @command{make} if the ``@i{Entering/Leaving directory ...}'' messages
10983 are to be disabled.
10986 @chapter The effect of @option{--gnu} and @option{--gnits}
10988 @cindex @option{--gnu}, required files
10989 @cindex @option{--gnu}, complete description
10991 The @option{--gnu} option (or @option{gnu} in the
10992 @code{AUTOMAKE_OPTIONS} variable) causes @command{automake} to check
10997 The files @file{INSTALL}, @file{NEWS}, @file{README}, @file{AUTHORS},
10998 and @file{ChangeLog}, plus one of @file{COPYING.LIB}, @file{COPYING.LESSER}
10999 or @file{COPYING}, are required at the topmost directory of the package.
11001 If the @option{--add-missing} option is given, @command{automake} will
11002 add a generic version of the @file{INSTALL} file as well as the
11003 @file{COPYING} file containing the text of the current version of the
11004 GNU General Public License existing at the time of this Automake release
11005 (version 3 as this is written, @uref{http://www.gnu.org/@/copyleft/@/gpl.html}).
11006 However, an existing @file{COPYING} file will never be overwritten by
11007 @command{automake}.
11010 The options @option{no-installman} and @option{no-installinfo} are
11014 Note that this option will be extended in the future to do even more
11015 checking; it is advisable to be familiar with the precise requirements
11016 of the GNU standards. Also, @option{--gnu} can require certain
11017 non-standard GNU programs to exist for use by various maintainer-only
11018 rules; for instance, in the future @command{pathchk} might be required for
11021 @cindex @option{--gnits}, complete description
11023 The @option{--gnits} option does everything that @option{--gnu} does, and
11024 checks the following as well:
11028 @samp{make installcheck} will check to make sure that the @option{--help}
11029 and @option{--version} really print a usage message and a version string,
11030 respectively. This is the @option{std-options} option (@pxref{Options}).
11033 @samp{make dist} will check to make sure the @file{NEWS} file has been
11034 updated to the current version.
11037 @code{VERSION} is checked to make sure its format complies with Gnits
11039 @c FIXME xref when standards are finished
11042 @cindex @file{README-alpha}
11043 If @code{VERSION} indicates that this is an alpha release, and the file
11044 @file{README-alpha} appears in the topmost directory of a package, then
11045 it is included in the distribution. This is done in @option{--gnits}
11046 mode, and no other, because this mode is the only one where version
11047 number formats are constrained, and hence the only mode where Automake
11048 can automatically determine whether @file{README-alpha} should be
11052 The file @file{THANKS} is required.
11057 @chapter When Automake Isn't Enough
11059 In some situations, where Automake is not up to one task, one has to
11060 resort to handwritten rules or even handwritten @file{Makefile}s.
11063 * Extending:: Adding new rules or overriding existing ones.
11064 * Third-Party Makefiles:: Integrating Non-Automake @file{Makefile}s.
11068 @section Extending Automake Rules
11070 With some minor exceptions (for example @code{_PROGRAMS} variables,
11071 @code{TESTS}, or @code{XFAIL_TESTS}) being rewritten to append
11072 @samp{$(EXEEXT)}), the contents of a @file{Makefile.am} is copied to
11073 @file{Makefile.in} verbatim.
11075 @cindex copying semantics
11077 These copying semantics mean that many problems can be worked around
11078 by simply adding some @command{make} variables and rules to
11079 @file{Makefile.am}. Automake will ignore these additions.
11081 @cindex conflicting definitions
11082 @cindex rules, conflicting
11083 @cindex variables, conflicting
11084 @cindex definitions, conflicts
11086 Since a @file{Makefile.in} is built from data gathered from three
11087 different places (@file{Makefile.am}, @file{configure.ac}, and
11088 @command{automake} itself), it is possible to have conflicting
11089 definitions of rules or variables. When building @file{Makefile.in}
11090 the following priorities are respected by @command{automake} to ensure
11091 the user always has the last word:
11095 User defined variables in @file{Makefile.am} have priority over
11096 variables @code{AC_SUBST}ed from @file{configure.ac}, and
11097 @code{AC_SUBST}ed variables have priority over
11098 @command{automake}-defined variables.
11100 As far as rules are concerned, a user-defined rule overrides any
11101 @command{automake}-defined rule for the same target.
11104 @cindex overriding rules
11105 @cindex overriding semantics
11106 @cindex rules, overriding
11108 These overriding semantics make it possible to fine tune some default
11109 settings of Automake, or replace some of its rules. Overriding
11110 Automake rules is often inadvisable, particularly in the topmost
11111 directory of a package with subdirectories. The @option{-Woverride}
11112 option (@pxref{automake Invocation}) comes in handy to catch overridden
11115 Note that Automake does not make any distinction between rules with
11116 commands and rules that only specify dependencies. So it is not
11117 possible to append new dependencies to an @command{automake}-defined
11118 target without redefining the entire rule.
11120 @cindex @option{-local} targets
11121 @cindex local targets
11123 However, various useful targets have a @samp{-local} version you can
11124 specify in your @file{Makefile.am}. Automake will supplement the
11125 standard target with these user-supplied targets.
11130 @trindex info-local
11138 @trindex html-local
11140 @trindex check-local
11142 @trindex install-data
11143 @trindex install-data-local
11144 @trindex install-dvi
11145 @trindex install-dvi-local
11146 @trindex install-exec
11147 @trindex install-exec-local
11148 @trindex install-html
11149 @trindex install-html-local
11150 @trindex install-info
11151 @trindex install-info-local
11152 @trindex install-pdf
11153 @trindex install-pdf-local
11154 @trindex install-ps
11155 @trindex install-ps-local
11157 @trindex uninstall-local
11158 @trindex mostlyclean
11159 @trindex mostlyclean-local
11161 @trindex clean-local
11163 @trindex distclean-local
11164 @trindex installdirs
11165 @trindex installdirs-local
11166 @trindex installcheck
11167 @trindex installcheck-local
11169 The targets that support a local version are @code{all}, @code{info},
11170 @code{dvi}, @code{ps}, @code{pdf}, @code{html}, @code{check},
11171 @code{install-data}, @code{install-dvi}, @code{install-exec},
11172 @code{install-html}, @code{install-info}, @code{install-pdf},
11173 @code{install-ps}, @code{uninstall}, @code{installdirs},
11174 @code{installcheck} and the various @code{clean} targets
11175 (@code{mostlyclean}, @code{clean}, @code{distclean}, and
11176 @code{maintainer-clean}).
11178 Note that there are no @code{uninstall-exec-local} or
11179 @code{uninstall-data-local} targets; just use @code{uninstall-local}.
11180 It doesn't make sense to uninstall just data or just executables.
11182 For instance, here is one way to erase a subdirectory during
11183 @samp{make clean} (@pxref{Clean}).
11190 You may be tempted to use @code{install-data-local} to install a file
11191 to some hard-coded location, but you should avoid this
11192 (@pxref{Hard-Coded Install Paths}).
11194 With the @code{-local} targets, there is no particular guarantee of
11195 execution order; typically, they are run early, but with parallel
11196 make, there is no way to be sure of that.
11198 @cindex @option{-hook} targets
11199 @cindex hook targets
11200 @trindex install-data-hook
11201 @trindex install-exec-hook
11202 @trindex uninstall-hook
11205 In contrast, some rules also have a way to run another rule, called a
11206 @dfn{hook}; hooks are always executed after the main rule's work is done.
11207 The hook is named after the principal target, with @samp{-hook} appended.
11208 The targets allowing hooks are @code{install-data},
11209 @code{install-exec}, @code{uninstall}, @code{dist}, and
11212 For instance, here is how to create a hard link to an installed program:
11216 ln $(DESTDIR)$(bindir)/program$(EXEEXT) \
11217 $(DESTDIR)$(bindir)/proglink$(EXEEXT)
11220 Although cheaper and more portable than symbolic links, hard links
11221 will not work everywhere (for instance, OS/2 does not have
11222 @command{ln}). Ideally you should fall back to @samp{cp -p} when
11223 @command{ln} does not work. An easy way, if symbolic links are
11224 acceptable to you, is to add @code{AC_PROG_LN_S} to
11225 @file{configure.ac} (@pxref{Particular Programs, , Particular Program
11226 Checks, autoconf, The Autoconf Manual}) and use @samp{$(LN_S)} in
11227 @file{Makefile.am}.
11229 @cindex versioned binaries, installing
11230 @cindex installing versioned binaries
11231 @cindex @code{LN_S} example
11232 For instance, here is how you could install a versioned copy of a
11233 program using @samp{$(LN_S)}:
11235 @c Keep in sync with insthook.sh
11238 cd $(DESTDIR)$(bindir) && \
11239 mv -f prog$(EXEEXT) prog-$(VERSION)$(EXEEXT) && \
11240 $(LN_S) prog-$(VERSION)$(EXEEXT) prog$(EXEEXT)
11243 Note that we rename the program so that a new version will erase the
11244 symbolic link, not the real binary. Also we @command{cd} into the
11245 destination directory in order to create relative links.
11247 When writing @code{install-exec-hook} or @code{install-data-hook},
11248 please bear in mind that the exec/data distinction is based on the
11249 installation directory, not on the primary used (@pxref{The Two Parts of
11251 @c Keep in sync with primary-prefix-couples-documented-valid.sh
11252 So a @code{foo_SCRIPTS} will be installed by
11253 @code{install-data}, and a @code{barexec_SCRIPTS} will be installed by
11254 @code{install-exec}. You should define your hooks consequently.
11256 @c FIXME should include discussion of variables you can use in these
11259 @node Third-Party Makefiles
11260 @section Third-Party @file{Makefile}s
11262 @cindex Third-party packages, interfacing with
11263 @cindex Interfacing with third-party packages
11265 In most projects all @file{Makefile}s are generated by Automake. In
11266 some cases, however, projects need to embed subdirectories with
11267 handwritten @file{Makefile}s. For instance, one subdirectory could be
11268 a third-party project with its own build system, not using Automake.
11270 It is possible to list arbitrary directories in @code{SUBDIRS} or
11271 @code{DIST_SUBDIRS} provided each of these directories has a
11272 @file{Makefile} that recognizes all the following recursive targets.
11274 @cindex recursive targets and third-party @file{Makefile}s
11275 When a user runs one of these targets, that target is run recursively
11276 in all subdirectories. This is why it is important that even
11277 third-party @file{Makefile}s support them.
11281 Compile the entire package. This is the default target in
11282 Automake-generated @file{Makefile}s, but it does not need to be the
11283 default in third-party @file{Makefile}s.
11288 @vindex top_distdir
11289 Copy files to distribute into @samp{$(distdir)}, before a tarball is
11290 constructed. Of course this target is not required if the
11291 @option{no-dist} option (@pxref{Options}) is used.
11293 The variables @samp{$(top_distdir)} and @samp{$(distdir)}
11294 (@pxref{The dist Hook}) will be passed from the outer package to the subpackage
11295 when the @code{distdir} target is invoked. These two variables have
11296 been adjusted for the directory that is being recursed into, so they
11300 @itemx install-data
11301 @itemx install-exec
11303 Install or uninstall files (@pxref{Install}).
11306 @itemx install-html
11307 @itemx install-info
11310 Install only some specific documentation format (@pxref{Texinfo}).
11313 Create install directories, but do not install any files.
11316 @itemx installcheck
11317 Check the package (@pxref{Tests}).
11322 @itemx maintainer-clean
11323 Cleaning rules (@pxref{Clean}).
11330 Build the documentation in various formats (@pxref{Texinfo}).
11334 Build @file{TAGS} and @file{CTAGS} (@pxref{Tags}).
11337 If you have ever used Gettext in a project, this is a good example of
11338 how third-party @file{Makefile}s can be used with Automake. The
11339 @file{Makefile}s @command{gettextize} puts in the @file{po/} and
11340 @file{intl/} directories are handwritten @file{Makefile}s that
11341 implement all of these targets. That way they can be added to
11342 @code{SUBDIRS} in Automake packages.
11344 Directories that are only listed in @code{DIST_SUBDIRS} but not in
11345 @code{SUBDIRS} need only the @code{distclean},
11346 @code{maintainer-clean}, and @code{distdir} rules (@pxref{Conditional
11349 Usually, many of these rules are irrelevant to the third-party
11350 subproject, but they are required for the whole package to work. It's
11351 OK to have a rule that does nothing, so if you are integrating a
11352 third-party project with no documentation or tag support, you could
11353 simply augment its @file{Makefile} as follows:
11356 EMPTY_AUTOMAKE_TARGETS = dvi pdf ps info html tags ctags
11357 .PHONY: $(EMPTY_AUTOMAKE_TARGETS)
11358 $(EMPTY_AUTOMAKE_TARGETS):
11361 Another aspect of integrating third-party build systems is whether
11362 they support VPATH builds (@pxref{VPATH Builds}). Obviously if the
11363 subpackage does not support VPATH builds the whole package will not
11364 support VPATH builds. This in turns means that @samp{make distcheck}
11365 will not work, because it relies on VPATH builds. Some people can
11366 live without this (actually, many Automake users have never heard of
11367 @samp{make distcheck}). Other people may prefer to revamp the
11368 existing @file{Makefile}s to support VPATH@. Doing so does not
11369 necessarily require Automake, only Autoconf is needed (@pxref{Build
11370 Directories, , Build Directories, autoconf, The Autoconf Manual}).
11371 The necessary substitutions: @samp{@@srcdir@@}, @samp{@@top_srcdir@@},
11372 and @samp{@@top_builddir@@} are defined by @file{configure} when it
11373 processes a @file{Makefile} (@pxref{Preset Output Variables, , Preset
11374 Output Variables, autoconf, The Autoconf Manual}), they are not
11375 computed by the Makefile like the aforementioned @samp{$(distdir)} and
11376 @samp{$(top_distdir)} variables.
11378 It is sometimes inconvenient to modify a third-party @file{Makefile}
11379 to introduce the above required targets. For instance, one may want to
11380 keep the third-party sources untouched to ease upgrades to new
11383 @cindex @file{GNUmakefile} including @file{Makefile}
11384 Here are two other ideas. If GNU make is assumed, one possibility is
11385 to add to that subdirectory a @file{GNUmakefile} that defines the
11386 required targets and includes the third-party @file{Makefile}. For
11387 this to work in VPATH builds, @file{GNUmakefile} must lie in the build
11388 directory; the easiest way to do this is to write a
11389 @file{GNUmakefile.in} instead, and have it processed with
11390 @code{AC_CONFIG_FILES} from the outer package. For example if we
11391 assume @file{Makefile} defines all targets except the documentation
11392 targets, and that the @code{check} target is actually called
11393 @code{test}, we could write @file{GNUmakefile} (or
11394 @file{GNUmakefile.in}) like this:
11397 # First, include the real Makefile
11399 # Then, define the other targets needed by Automake Makefiles.
11400 .PHONY: dvi pdf ps info html check
11401 dvi pdf ps info html:
11405 @cindex Proxy @file{Makefile} for third-party packages
11406 A similar idea that does not use @code{include} is to write a proxy
11407 @file{Makefile} that dispatches rules to the real @file{Makefile},
11408 either with @samp{$(MAKE) -f Makefile.real $(AM_MAKEFLAGS) target} (if
11409 it's OK to rename the original @file{Makefile}) or with @samp{cd
11410 subdir && $(MAKE) $(AM_MAKEFLAGS) target} (if it's OK to store the
11411 subdirectory project one directory deeper). The good news is that
11412 this proxy @file{Makefile} can be generated with Automake. All we
11413 need are @option{-local} targets (@pxref{Extending}) that perform the
11414 dispatch. Of course the other Automake features are available, so you
11415 could decide to let Automake perform distribution or installation.
11416 Here is a possible @file{Makefile.am}:
11420 cd subdir && $(MAKE) $(AM_MAKEFLAGS) all
11422 cd subdir && $(MAKE) $(AM_MAKEFLAGS) test
11424 cd subdir && $(MAKE) $(AM_MAKEFLAGS) clean
11426 # Assuming the package knows how to install itself
11427 install-data-local:
11428 cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-data
11429 install-exec-local:
11430 cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-exec
11432 cd subdir && $(MAKE) $(AM_MAKEFLAGS) uninstall
11434 # Distribute files from here.
11435 EXTRA_DIST = subdir/Makefile subdir/program.c ...
11438 Pushing this idea to the extreme, it is also possible to ignore the
11439 subproject build system and build everything from this proxy
11440 @file{Makefile.am}. This might sound very sensible if you need VPATH
11441 builds but the subproject does not support them.
11444 @chapter Distributing @file{Makefile.in}s
11446 Automake places no restrictions on the distribution of the resulting
11447 @file{Makefile.in}s. We still encourage software authors to
11448 distribute their work under terms like those of the GPL, but doing so
11449 is not required to use Automake.
11451 Some of the files that can be automatically installed via the
11452 @option{--add-missing} switch do fall under the GPL@. However, these also
11453 have a special exception allowing you to distribute them with your
11454 package, regardless of the licensing you choose.
11457 @node API Versioning
11458 @chapter Automake API Versioning
11460 New Automake releases usually include bug fixes and new features.
11461 Unfortunately they may also introduce new bugs and incompatibilities.
11462 This makes four reasons why a package may require a particular Automake
11465 Things get worse when maintaining a large tree of packages, each one
11466 requiring a different version of Automake. In the past, this meant that
11467 any developer (and sometimes users) had to install several versions of
11468 Automake in different places, and switch @samp{$PATH} appropriately for
11471 Starting with version 1.6, Automake installs versioned binaries. This
11472 means you can install several versions of Automake in the same
11473 @samp{$prefix}, and can select an arbitrary Automake version by running
11474 @command{automake-1.6} or @command{automake-1.7} without juggling with
11475 @samp{$PATH}. Furthermore, @file{Makefile}'s generated by Automake 1.6
11476 will use @command{automake-1.6} explicitly in their rebuild rules.
11478 The number @samp{1.6} in @command{automake-1.6} is Automake's API version,
11479 not Automake's version. If a bug fix release is made, for instance
11480 Automake 1.6.1, the API version will remain 1.6. This means that a
11481 package that works with Automake 1.6 should also work with 1.6.1; after
11482 all, this is what people expect from bug fix releases.
11484 If your package relies on a feature or a bug fix introduced in
11485 a release, you can pass this version as an option to Automake to ensure
11486 older releases will not be used. For instance, use this in your
11487 @file{configure.ac}:
11490 AM_INIT_AUTOMAKE([1.6.1]) dnl Require Automake 1.6.1 or better.
11494 or, in a particular @file{Makefile.am}:
11497 AUTOMAKE_OPTIONS = 1.6.1 # Require Automake 1.6.1 or better.
11501 Automake will print an error message if its version is
11502 older than the requested version.
11505 @heading What is in the API
11507 Automake's programming interface is not easy to define. Basically it
11508 should include at least all @strong{documented} variables and targets
11509 that a @file{Makefile.am} author can use, any behavior associated with
11510 them (e.g., the places where @samp{-hook}'s are run), the command line
11511 interface of @command{automake} and @command{aclocal}, @dots{}
11513 @heading What is not in the API
11515 Every undocumented variable, target, or command line option, is not part
11516 of the API@. You should avoid using them, as they could change from one
11517 version to the other (even in bug fix releases, if this helps to fix a
11520 If it turns out you need to use such an undocumented feature, contact
11521 @email{automake@@gnu.org} and try to get it documented and exercised by
11525 @chapter Upgrading a Package to a Newer Automake Version
11527 Automake maintains three kind of files in a package.
11530 @item @file{aclocal.m4}
11531 @item @file{Makefile.in}s
11532 @item auxiliary tools like @file{install-sh} or @file{py-compile}
11535 @file{aclocal.m4} is generated by @command{aclocal} and contains some
11536 Automake-supplied M4 macros. Auxiliary tools are installed by
11537 @samp{automake --add-missing} when needed. @file{Makefile.in}s are
11538 built from @file{Makefile.am} by @command{automake}, and rely on the
11539 definitions of the M4 macros put in @file{aclocal.m4} as well as the
11540 behavior of the auxiliary tools installed.
11542 Because all of these files are closely related, it is important to
11543 regenerate all of them when upgrading to a newer Automake release.
11544 The usual way to do that is
11547 aclocal # with any option needed (such a -I m4)
11549 automake --add-missing --force-missing
11553 or more conveniently:
11559 The use of @option{--force-missing} ensures that auxiliary tools will be
11560 overridden by new versions (@pxref{automake Invocation}).
11562 It is important to regenerate all of these files each time Automake is
11563 upgraded, even between bug fixes releases. For instance, it is not
11564 unusual for a bug fix to involve changes to both the rules generated
11565 in @file{Makefile.in} and the supporting M4 macros copied to
11568 Presently @command{automake} is able to diagnose situations where
11569 @file{aclocal.m4} has been generated with another version of
11570 @command{aclocal}. However it never checks whether auxiliary scripts
11571 are up-to-date. In other words, @command{automake} will tell you when
11572 @command{aclocal} needs to be rerun, but it will never diagnose a
11573 missing @option{--force-missing}.
11575 Before upgrading to a new major release, it is a good idea to read the
11576 file @file{NEWS}. This file lists all changes between releases: new
11577 features, obsolete constructs, known incompatibilities, and
11581 @chapter Frequently Asked Questions about Automake
11583 This chapter covers some questions that often come up on the mailing
11587 * CVS:: CVS and generated files
11588 * maintainer-mode:: missing and AM_MAINTAINER_MODE
11589 * Wildcards:: Why doesn't Automake support wildcards?
11590 * Limitations on File Names:: Limitations on source and installed file names
11591 * Errors with distclean:: Files left in build directory after distclean
11592 * Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS
11593 * Renamed Objects:: Why are object files sometimes renamed?
11594 * Per-Object Flags:: How to simulate per-object flags?
11595 * Multiple Outputs:: Writing rules for tools with many output files
11596 * Hard-Coded Install Paths:: Installing to hard-coded locations
11597 * Debugging Make Rules:: Strategies when things don't work as expected
11598 * Reporting Bugs:: Feedback on bugs and feature requests
11602 @section CVS and generated files
11604 @subheading Background: distributed generated Files
11605 @cindex generated files, distributed
11606 @cindex rebuild rules
11608 Packages made with Autoconf and Automake ship with some generated
11609 files like @file{configure} or @file{Makefile.in}. These files were
11610 generated on the developer's machine and are distributed so that
11611 end-users do not have to install the maintainer tools required to
11612 rebuild them. Other generated files like Lex scanners, Yacc parsers,
11613 or Info documentation, are usually distributed on similar grounds.
11615 Automake output rules in @file{Makefile}s to rebuild these files. For
11616 instance, @command{make} will run @command{autoconf} to rebuild
11617 @file{configure} whenever @file{configure.ac} is changed. This makes
11618 development safer by ensuring a @file{configure} is never out-of-date
11619 with respect to @file{configure.ac}.
11621 As generated files shipped in packages are up-to-date, and because
11622 @command{tar} preserves times-tamps, these rebuild rules are not
11623 triggered when a user unpacks and builds a package.
11625 @subheading Background: CVS and Timestamps
11626 @cindex timestamps and CVS
11627 @cindex CVS and timestamps
11629 Unless you use CVS keywords (in which case files must be updated at
11630 commit time), CVS preserves timestamp during @samp{cvs commit} and
11631 @samp{cvs import -d} operations.
11633 When you check out a file using @samp{cvs checkout} its timestamp is
11634 set to that of the revision that is being checked out.
11636 However, during @command{cvs update}, files will have the date of the
11637 update, not the original timestamp of this revision. This is meant to
11638 make sure that @command{make} notices sources files have been updated.
11640 This timestamp shift is troublesome when both sources and generated
11641 files are kept under CVS@. Because CVS processes files in lexical
11642 order, @file{configure.ac} will appear newer than @file{configure}
11643 after a @command{cvs update} that updates both files, even if
11644 @file{configure} was newer than @file{configure.ac} when it was
11645 checked in. Calling @command{make} will then trigger a spurious rebuild
11646 of @file{configure}.
11648 @subheading Living with CVS in Autoconfiscated Projects
11649 @cindex CVS and generated files
11650 @cindex generated files and CVS
11652 There are basically two clans amongst maintainers: those who keep all
11653 distributed files under CVS, including generated files, and those who
11654 keep generated files @emph{out} of CVS.
11656 @subsubheading All Files in CVS
11660 The CVS repository contains all distributed files so you know exactly
11661 what is distributed, and you can checkout any prior version entirely.
11664 Maintainers can see how generated files evolve (for instance, you can
11665 see what happens to your @file{Makefile.in}s when you upgrade Automake
11666 and make sure they look OK).
11669 Users do not need the autotools to build a checkout of the project, it
11670 works just like a released tarball.
11673 If users use @command{cvs update} to update their copy, instead of
11674 @command{cvs checkout} to fetch a fresh one, timestamps will be
11675 inaccurate. Some rebuild rules will be triggered and attempt to
11676 run developer tools such as @command{autoconf} or @command{automake}.
11678 Calls to such tools are all wrapped into a call to the @command{missing}
11679 script discussed later (@pxref{maintainer-mode}), so that the user will
11680 see more descriptive warnings about missing or out-of-date tools, and
11681 possible suggestions about how to obtain them, rather than just some
11682 ``command not found'' error, or (worse) some obscure message from some
11683 older version of the required tool they happen to have installed.
11685 Maintainers interested in keeping their package buildable from a CVS
11686 checkout even for those users that lack maintainer-specific tools might
11687 want to provide an helper script (or to enhance their existing bootstrap
11688 script) to fix the timestamps after a
11689 @command{cvs update} or a @command{git checkout}, to prevent spurious
11690 rebuilds. In case of a project committing the Autotools-generated
11691 files, as well as the generated @file{.info} files, such script might
11692 look something like this:
11696 # fix-timestamp.sh: prevents useless rebuilds after "cvs update"
11698 # aclocal-generated aclocal.m4 depends on locally-installed
11699 # '.m4' macro files, as well as on 'configure.ac'
11702 # autoconf-generated configure depends on aclocal.m4 and on
11704 configure config.h.in
11705 # so does autoheader-generated config.h.in
11706 configure config.h.in
11707 # and all the automake-generated Makefile.in files
11708 touch `find . -name Makefile.in -print`
11709 # finally, the makeinfo-generated '.info' files depend on the
11710 # corresponding '.texi' files
11715 In distributed development, developers are likely to have different
11716 version of the maintainer tools installed. In this case rebuilds
11717 triggered by timestamp lossage will lead to spurious changes
11718 to generated files. There are several solutions to this:
11722 All developers should use the same versions, so that the rebuilt files
11723 are identical to files in CVS@. (This starts to be difficult when each
11724 project you work on uses different versions.)
11726 Or people use a script to fix the timestamp after a checkout (the GCC
11727 folks have such a script).
11729 Or @file{configure.ac} uses @code{AM_MAINTAINER_MODE}, which will
11730 disable all of these rebuild rules by default. This is further discussed
11731 in @ref{maintainer-mode}.
11735 Although we focused on spurious rebuilds, the converse can also
11736 happen. CVS's timestamp handling can also let you think an
11737 out-of-date file is up-to-date.
11739 For instance, suppose a developer has modified @file{Makefile.am} and
11740 has rebuilt @file{Makefile.in}, and then decides to do a last-minute
11741 change to @file{Makefile.am} right before checking in both files
11742 (without rebuilding @file{Makefile.in} to account for the change).
11744 This last change to @file{Makefile.am} makes the copy of
11745 @file{Makefile.in} out-of-date. Since CVS processes files
11746 alphabetically, when another developer @samp{cvs update}s his or her
11747 tree, @file{Makefile.in} will happen to be newer than
11748 @file{Makefile.am}. This other developer will not see that
11749 @file{Makefile.in} is out-of-date.
11753 @subsubheading Generated Files out of CVS
11755 One way to get CVS and @command{make} working peacefully is to never
11756 store generated files in CVS, i.e., do not CVS-control files that
11757 are @file{Makefile} targets (also called @emph{derived} files).
11759 This way developers are not annoyed by changes to generated files. It
11760 does not matter if they all have different versions (assuming they are
11761 compatible, of course). And finally, timestamps are not lost, changes
11762 to sources files can't be missed as in the
11763 @file{Makefile.am}/@file{Makefile.in} example discussed earlier.
11765 The drawback is that the CVS repository is not an exact copy of what
11766 is distributed and that users now need to install various development
11767 tools (maybe even specific versions) before they can build a checkout.
11768 But, after all, CVS's job is versioning, not distribution.
11770 Allowing developers to use different versions of their tools can also
11771 hide bugs during distributed development. Indeed, developers will be
11772 using (hence testing) their own generated files, instead of the
11773 generated files that will be released actually. The developer who
11774 prepares the tarball might be using a version of the tool that
11775 produces bogus output (for instance a non-portable C file), something
11776 other developers could have noticed if they weren't using their own
11777 versions of this tool.
11779 @subheading Third-party Files
11780 @cindex CVS and third-party files
11781 @cindex third-party files and CVS
11783 Another class of files not discussed here (because they do not cause
11784 timestamp issues) are files that are shipped with a package, but
11785 maintained elsewhere. For instance, tools like @command{gettextize}
11786 and @command{autopoint} (from Gettext) or @command{libtoolize} (from
11787 Libtool), will install or update files in your package.
11789 These files, whether they are kept under CVS or not, raise similar
11790 concerns about version mismatch between developers' tools. The
11791 Gettext manual has a section about this, see @ref{CVS Issues, CVS
11792 Issues, Integrating with CVS, gettext, GNU gettext tools}.
11794 @node maintainer-mode
11795 @section @command{missing} and @code{AM_MAINTAINER_MODE}
11797 @subheading @command{missing}
11798 @cindex @command{missing}, purpose
11800 The @command{missing} script is a wrapper around several maintainer
11801 tools, designed to warn users if a maintainer tool is required but
11802 missing. Typical maintainer tools are @command{autoconf},
11803 @command{automake}, @command{bison}, etc. Because file generated by
11804 these tools are shipped with the other sources of a package, these
11805 tools shouldn't be required during a user build and they are not
11806 checked for in @file{configure}.
11808 However, if for some reason a rebuild rule is triggered and involves a
11809 missing tool, @command{missing} will notice it and warn the user, even
11810 suggesting how to obtain such a tool (at least in case it is a well-known
11811 one, like @command{makeinfo} or @command{bison}). This is more helpful
11812 and user-friendly than just having the rebuild rules spewing out a terse
11813 error message like @samp{sh: @var{tool}: command not found}. Similarly,
11814 @command{missing} will warn the user if it detects that a maintainer
11815 tool it attempted to use seems too old (be warned that diagnosing this
11816 correctly is typically more difficult that detecting missing tools, and
11817 requires cooperation from the tool itself, so it won't always work).
11819 If the required tool is installed, @command{missing} will run it and
11820 won't attempt to continue after failures. This is correct during
11821 development: developers love fixing failures. However, users with
11822 missing or too old maintainer tools may get an error when the rebuild
11823 rule is spuriously triggered, halting the build. This failure to let
11824 the build continue is one of the arguments of the
11825 @code{AM_MAINTAINER_MODE} advocates.
11827 @subheading @code{AM_MAINTAINER_MODE}
11828 @cindex @code{AM_MAINTAINER_MODE}, purpose
11829 @acindex AM_MAINTAINER_MODE
11831 @code{AM_MAINTAINER_MODE} allows you to choose whether the so called
11832 "rebuild rules" should be enabled or disabled. With
11833 @code{AM_MAINTAINER_MODE([enable])}, they are enabled by default,
11834 otherwise they are disabled by default. In the latter case, if
11835 you have @code{AM_MAINTAINER_MODE} in @file{configure.ac}, and run
11836 @samp{./configure && make}, then @command{make} will *never* attempt to
11837 rebuild @file{configure}, @file{Makefile.in}s, Lex or Yacc outputs, etc.
11838 I.e., this disables build rules for files that are usually distributed
11839 and that users should normally not have to update.
11841 The user can override the default setting by passing either
11842 @samp{--enable-maintainer-mode} or @samp{--disable-maintainer-mode}
11843 to @command{configure}.
11845 People use @code{AM_MAINTAINER_MODE} either because they do not want their
11846 users (or themselves) annoyed by timestamps lossage (@pxref{CVS}), or
11847 because they simply can't stand the rebuild rules and prefer running
11848 maintainer tools explicitly.
11850 @code{AM_MAINTAINER_MODE} also allows you to disable some custom build
11851 rules conditionally. Some developers use this feature to disable
11852 rules that need exotic tools that users may not have available.
11854 Several years ago Fran@,{c}ois Pinard pointed out several arguments
11855 against this @code{AM_MAINTAINER_MODE} macro. Most of them relate to
11856 insecurity. By removing dependencies you get non-dependable builds:
11857 changes to sources files can have no effect on generated files and this
11858 can be very confusing when unnoticed. He adds that security shouldn't
11859 be reserved to maintainers (what @option{--enable-maintainer-mode}
11860 suggests), on the contrary. If one user has to modify a
11861 @file{Makefile.am}, then either @file{Makefile.in} should be updated
11862 or a warning should be output (this is what Automake uses
11863 @command{missing} for) but the last thing you want is that nothing
11864 happens and the user doesn't notice it (this is what happens when
11865 rebuild rules are disabled by @code{AM_MAINTAINER_MODE}).
11867 Jim Meyering, the inventor of the @code{AM_MAINTAINER_MODE} macro was
11868 swayed by Fran@,{c}ois's arguments, and got rid of
11869 @code{AM_MAINTAINER_MODE} in all of his packages.
11871 Still many people continue to use @code{AM_MAINTAINER_MODE}, because
11872 it helps them working on projects where all files are kept under version
11873 control, and because @command{missing} isn't enough if you have the
11874 wrong version of the tools.
11878 @section Why doesn't Automake support wildcards?
11881 Developers are lazy. They would often like to use wildcards in
11882 @file{Makefile.am}s, so that they would not need to remember to
11883 update @file{Makefile.am}s every time they add, delete, or rename
11886 There are several objections to this:
11889 When using CVS (or similar) developers need to remember they have to
11890 run @samp{cvs add} or @samp{cvs rm} anyway. Updating
11891 @file{Makefile.am} accordingly quickly becomes a reflex.
11893 Conversely, if your application doesn't compile
11894 because you forgot to add a file in @file{Makefile.am}, it will help
11895 you remember to @samp{cvs add} it.
11898 Using wildcards makes it easy to distribute files by mistake. For
11899 instance, some code a developer is experimenting with (a test case,
11900 say) that should not be part of the distribution.
11903 Using wildcards it's easy to omit some files by mistake. For
11904 instance, one developer creates a new file, uses it in many places,
11905 but forgets to commit it. Another developer then checks out the
11906 incomplete project and is able to run @samp{make dist} successfully,
11907 even though a file is missing. By listing files, @samp{make dist}
11908 @emph{will} complain.
11911 Wildcards are not portable to some non-GNU @command{make} implementations,
11912 e.g., NetBSD @command{make} will not expand globs such as @samp{*} in
11913 prerequisites of a target.
11916 Finally, it's really hard to @emph{forget} to add a file to
11917 @file{Makefile.am}: files that are not listed in @file{Makefile.am} are
11918 not compiled or installed, so you can't even test them.
11921 Still, these are philosophical objections, and as such you may disagree,
11922 or find enough value in wildcards to dismiss all of them. Before you
11923 start writing a patch against Automake to teach it about wildcards,
11924 let's see the main technical issue: portability.
11926 Although @samp{$(wildcard ...)} works with GNU @command{make}, it is
11927 not portable to other @command{make} implementations.
11929 The only way Automake could support @command{$(wildcard ...)} is by
11930 expanding @command{$(wildcard ...)} when @command{automake} is run.
11931 The resulting @file{Makefile.in}s would be portable since they would
11932 list all files and not use @samp{$(wildcard ...)}. However that
11933 means developers would need to remember to run @command{automake} each
11934 time they add, delete, or rename files.
11936 Compared to editing @file{Makefile.am}, this is a very small gain. Sure,
11937 it's easier and faster to type @samp{automake; make} than to type
11938 @samp{emacs Makefile.am; make}. But nobody bothered enough to write a
11939 patch to add support for this syntax. Some people use scripts to
11940 generate file lists in @file{Makefile.am} or in separate
11941 @file{Makefile} fragments.
11943 Even if you don't care about portability, and are tempted to use
11944 @samp{$(wildcard ...)} anyway because you target only GNU Make, you
11945 should know there are many places where Automake needs to know exactly
11946 which files should be processed. As Automake doesn't know how to
11947 expand @samp{$(wildcard ...)}, you cannot use it in these places.
11948 @samp{$(wildcard ...)} is a black box comparable to @code{AC_SUBST}ed
11949 variables as far Automake is concerned.
11951 You can get warnings about @samp{$(wildcard ...}) constructs using the
11952 @option{-Wportability} flag.
11954 @node Limitations on File Names
11955 @section Limitations on File Names
11956 @cindex file names, limitations on
11958 Automake attempts to support all kinds of file names, even those that
11959 contain unusual characters or are unusually long. However, some
11960 limitations are imposed by the underlying operating system and tools.
11962 Most operating systems prohibit the use of the null byte in file
11963 names, and reserve @samp{/} as a directory separator. Also, they
11964 require that file names are properly encoded for the user's locale.
11965 Automake is subject to these limits.
11967 Portable packages should limit themselves to POSIX file
11968 names. These can contain ASCII letters and digits,
11969 @samp{_}, @samp{.}, and @samp{-}. File names consist of components
11970 separated by @samp{/}. File name components cannot begin with
11973 Portable POSIX file names cannot contain components that exceed a
11974 14-byte limit, but nowadays it's normally safe to assume the
11975 more-generous XOPEN limit of 255 bytes. POSIX
11976 limits file names to 255 bytes (XOPEN allows 1023 bytes),
11977 but you may want to limit a source tarball to file names of 99 bytes
11978 to avoid interoperability problems with old versions of @command{tar}.
11980 If you depart from these rules (e.g., by using non-ASCII
11981 characters in file names, or by using lengthy file names), your
11982 installers may have problems for reasons unrelated to Automake.
11983 However, if this does not concern you, you should know about the
11984 limitations imposed by Automake itself. These limitations are
11985 undesirable, but some of them seem to be inherent to underlying tools
11986 like Autoconf, Make, M4, and the shell. They fall into three
11987 categories: install directories, build directories, and file names.
11989 The following characters:
11992 @r{newline} " # $ ' `
11995 should not appear in the names of install directories. For example,
11996 the operand of @command{configure}'s @option{--prefix} option should
11997 not contain these characters.
11999 Build directories suffer the same limitations as install directories,
12000 and in addition should not contain the following characters:
12006 For example, the full name of the directory containing the source
12007 files should not contain these characters.
12009 Source and installation file names like @file{main.c} are limited even
12010 further: they should conform to the POSIX/XOPEN
12011 rules described above. In addition, if you plan to port to
12012 non-POSIX environments, you should avoid file names that
12013 differ only in case (e.g., @file{makefile} and @file{Makefile}).
12014 Nowadays it is no longer worth worrying about the 8.3 limits of
12017 @c FIXME This should probably be moved in the "Checking the Distribution"
12018 @c FIXME section...
12019 @node Errors with distclean
12020 @section Errors with distclean
12021 @cindex @code{distclean}, diagnostic
12022 @cindex @samp{make distclean}, diagnostic
12023 @cindex dependencies and distributed files
12026 This is a diagnostic you might encounter while running @samp{make
12029 As explained in @ref{Checking the Distribution}, @samp{make distcheck}
12030 attempts to build and check your package for errors like this one.
12032 @samp{make distcheck} will perform a @code{VPATH} build of your
12033 package (@pxref{VPATH Builds}), and then call @samp{make distclean}.
12034 Files left in the build directory after @samp{make distclean} has run
12035 are listed after this error.
12037 This diagnostic really covers two kinds of errors:
12041 files that are forgotten by distclean;
12043 distributed files that are erroneously rebuilt.
12046 The former left-over files are not distributed, so the fix is to mark
12047 them for cleaning (@pxref{Clean}), this is obvious and doesn't deserve
12050 The latter bug is not always easy to understand and fix, so let's
12051 proceed with an example. Suppose our package contains a program for
12052 which we want to build a man page using @command{help2man}. GNU
12053 @command{help2man} produces simple manual pages from the @option{--help}
12054 and @option{--version} output of other commands (@pxref{Top, , Overview,
12055 help2man, The Help2man Manual}). Because we don't want to force our
12056 users to install @command{help2man}, we decide to distribute the
12057 generated man page using the following setup.
12060 # This Makefile.am is bogus.
12062 foo_SOURCES = foo.c
12063 dist_man_MANS = foo.1
12065 foo.1: foo$(EXEEXT)
12066 help2man --output=foo.1 ./foo$(EXEEXT)
12069 This will effectively distribute the man page. However,
12070 @samp{make distcheck} will fail with:
12073 ERROR: files left in build directory after distclean:
12077 Why was @file{foo.1} rebuilt? Because although distributed,
12078 @file{foo.1} depends on a non-distributed built file:
12079 @file{foo$(EXEEXT)}. @file{foo$(EXEEXT)} is built by the user, so it
12080 will always appear to be newer than the distributed @file{foo.1}.
12082 @samp{make distcheck} caught an inconsistency in our package. Our
12083 intent was to distribute @file{foo.1} so users do not need to install
12084 @command{help2man}, however since this rule causes this file to be
12085 always rebuilt, users @emph{do} need @command{help2man}. Either we
12086 should ensure that @file{foo.1} is not rebuilt by users, or there is
12087 no point in distributing @file{foo.1}.
12089 More generally, the rule is that distributed files should never depend
12090 on non-distributed built files. If you distribute something
12091 generated, distribute its sources.
12093 One way to fix the above example, while still distributing
12094 @file{foo.1} is to not depend on @file{foo$(EXEEXT)}. For instance,
12095 assuming @command{foo --version} and @command{foo --help} do not
12096 change unless @file{foo.c} or @file{configure.ac} change, we could
12097 write the following @file{Makefile.am}:
12101 foo_SOURCES = foo.c
12102 dist_man_MANS = foo.1
12104 foo.1: foo.c $(top_srcdir)/configure.ac
12105 $(MAKE) $(AM_MAKEFLAGS) foo$(EXEEXT)
12106 help2man --output=foo.1 ./foo$(EXEEXT)
12109 This way, @file{foo.1} will not get rebuilt every time
12110 @file{foo$(EXEEXT)} changes. The @command{make} call makes sure
12111 @file{foo$(EXEEXT)} is up-to-date before @command{help2man}. Another
12112 way to ensure this would be to use separate directories for binaries
12113 and man pages, and set @code{SUBDIRS} so that binaries are built
12116 We could also decide not to distribute @file{foo.1}. In
12117 this case it's fine to have @file{foo.1} dependent upon
12118 @file{foo$(EXEEXT)}, since both will have to be rebuilt.
12119 However it would be impossible to build the package in a
12120 cross-compilation, because building @file{foo.1} involves
12121 an @emph{execution} of @file{foo$(EXEEXT)}.
12123 Another context where such errors are common is when distributed files
12124 are built by tools that are built by the package. The pattern is
12128 distributed-file: built-tools distributed-sources
12133 should be changed to
12136 distributed-file: distributed-sources
12137 $(MAKE) $(AM_MAKEFLAGS) built-tools
12142 or you could choose not to distribute @file{distributed-file}, if
12143 cross-compilation does not matter.
12145 The points made through these examples are worth a summary:
12150 Distributed files should never depend upon non-distributed built
12153 Distributed files should be distributed with all their dependencies.
12155 If a file is @emph{intended} to be rebuilt by users, then there is no point
12156 in distributing it.
12160 @vrindex distcleancheck_listfiles
12161 For desperate cases, it's always possible to disable this check by
12162 setting @code{distcleancheck_listfiles} as documented in @ref{Checking
12164 Make sure you do understand the reason why @samp{make distcheck}
12165 complains before you do this. @code{distcleancheck_listfiles} is a
12166 way to @emph{hide} errors, not to fix them. You can always do better.
12168 @node Flag Variables Ordering
12169 @section Flag Variables Ordering
12170 @cindex Ordering flag variables
12171 @cindex Flag variables, ordering
12174 What is the difference between @code{AM_CFLAGS}, @code{CFLAGS}, and
12175 @code{mumble_CFLAGS}?
12179 Why does @command{automake} output @code{CPPFLAGS} after
12180 @code{AM_CPPFLAGS} on compile lines? Shouldn't it be the converse?
12184 My @file{configure} adds some warning flags into @code{CXXFLAGS}. In
12185 one @file{Makefile.am} I would like to append a new flag, however if I
12186 put the flag into @code{AM_CXXFLAGS} it is prepended to the other
12187 flags, not appended.
12190 @subheading Compile Flag Variables
12191 @cindex Flag Variables, Ordering
12192 @cindex Compile Flag Variables
12193 @cindex @code{AM_CCASFLAGS} and @code{CCASFLAGS}
12194 @cindex @code{AM_CFLAGS} and @code{CFLAGS}
12195 @cindex @code{AM_CPPFLAGS} and @code{CPPFLAGS}
12196 @cindex @code{AM_CXXFLAGS} and @code{CXXFLAGS}
12197 @cindex @code{AM_FCFLAGS} and @code{FCFLAGS}
12198 @cindex @code{AM_FFLAGS} and @code{FFLAGS}
12199 @cindex @code{AM_GCJFLAGS} and @code{GCJFLAGS}
12200 @cindex @code{AM_LDFLAGS} and @code{LDFLAGS}
12201 @cindex @code{AM_LFLAGS} and @code{LFLAGS}
12202 @cindex @code{AM_LIBTOOLFLAGS} and @code{LIBTOOLFLAGS}
12203 @cindex @code{AM_OBJCFLAGS} and @code{OBJCFLAGS}
12204 @cindex @code{AM_OBJCXXFLAGS} and @code{OBJXXCFLAGS}
12205 @cindex @code{AM_RFLAGS} and @code{RFLAGS}
12206 @cindex @code{AM_UPCFLAGS} and @code{UPCFLAGS}
12207 @cindex @code{AM_YFLAGS} and @code{YFLAGS}
12208 @cindex @code{CCASFLAGS} and @code{AM_CCASFLAGS}
12209 @cindex @code{CFLAGS} and @code{AM_CFLAGS}
12210 @cindex @code{CPPFLAGS} and @code{AM_CPPFLAGS}
12211 @cindex @code{CXXFLAGS} and @code{AM_CXXFLAGS}
12212 @cindex @code{FCFLAGS} and @code{AM_FCFLAGS}
12213 @cindex @code{FFLAGS} and @code{AM_FFLAGS}
12214 @cindex @code{GCJFLAGS} and @code{AM_GCJFLAGS}
12215 @cindex @code{LDFLAGS} and @code{AM_LDFLAGS}
12216 @cindex @code{LFLAGS} and @code{AM_LFLAGS}
12217 @cindex @code{LIBTOOLFLAGS} and @code{AM_LIBTOOLFLAGS}
12218 @cindex @code{OBJCFLAGS} and @code{AM_OBJCFLAGS}
12219 @cindex @code{OBJCXXFLAGS} and @code{AM_OBJCXXFLAGS}
12220 @cindex @code{RFLAGS} and @code{AM_RFLAGS}
12221 @cindex @code{UPCFLAGS} and @code{AM_UPCFLAGS}
12222 @cindex @code{YFLAGS} and @code{AM_YFLAGS}
12224 This section attempts to answer all the above questions. We will
12225 mostly discuss @code{CPPFLAGS} in our examples, but actually the
12226 answer holds for all the compile flags used in Automake:
12227 @code{CCASFLAGS}, @code{CFLAGS}, @code{CPPFLAGS}, @code{CXXFLAGS},
12228 @code{FCFLAGS}, @code{FFLAGS}, @code{GCJFLAGS}, @code{LDFLAGS},
12229 @code{LFLAGS}, @code{LIBTOOLFLAGS}, @code{OBJCFLAGS}, @code{OBJCXXFLAGS},
12230 @code{RFLAGS}, @code{UPCFLAGS}, and @code{YFLAGS}.
12232 @code{CPPFLAGS}, @code{AM_CPPFLAGS}, and @code{mumble_CPPFLAGS} are
12233 three variables that can be used to pass flags to the C preprocessor
12234 (actually these variables are also used for other languages like C++
12235 or preprocessed Fortran). @code{CPPFLAGS} is the user variable
12236 (@pxref{User Variables}), @code{AM_CPPFLAGS} is the Automake variable,
12237 and @code{mumble_CPPFLAGS} is the variable specific to the
12238 @code{mumble} target (we call this a per-target variable,
12239 @pxref{Program and Library Variables}).
12241 Automake always uses two of these variables when compiling C sources
12242 files. When compiling an object file for the @code{mumble} target,
12243 the first variable will be @code{mumble_CPPFLAGS} if it is defined, or
12244 @code{AM_CPPFLAGS} otherwise. The second variable is always
12247 In the following example,
12250 bin_PROGRAMS = foo bar
12251 foo_SOURCES = xyz.c
12252 bar_SOURCES = main.c
12253 foo_CPPFLAGS = -DFOO
12254 AM_CPPFLAGS = -DBAZ
12258 @file{xyz.o} will be compiled with @samp{$(foo_CPPFLAGS) $(CPPFLAGS)},
12259 (because @file{xyz.o} is part of the @code{foo} target), while
12260 @file{main.o} will be compiled with @samp{$(AM_CPPFLAGS) $(CPPFLAGS)}
12261 (because there is no per-target variable for target @code{bar}).
12263 The difference between @code{mumble_CPPFLAGS} and @code{AM_CPPFLAGS}
12264 being clear enough, let's focus on @code{CPPFLAGS}. @code{CPPFLAGS}
12265 is a user variable, i.e., a variable that users are entitled to modify
12266 in order to compile the package. This variable, like many others,
12267 is documented at the end of the output of @samp{configure --help}.
12269 For instance, someone who needs to add @file{/home/my/usr/include} to
12270 the C compiler's search path would configure a package with
12273 ./configure CPPFLAGS='-I /home/my/usr/include'
12277 and this flag would be propagated to the compile rules of all
12280 It is also not uncommon to override a user variable at
12281 @command{make}-time. Many installers do this with @code{prefix}, but
12282 this can be useful with compiler flags too. For instance, if, while
12283 debugging a C++ project, you need to disable optimization in one
12284 specific object file, you can run something like
12288 make CXXFLAGS=-O0 file.o
12292 The reason @samp{$(CPPFLAGS)} appears after @samp{$(AM_CPPFLAGS)} or
12293 @samp{$(mumble_CPPFLAGS)} in the compile command is that users
12294 should always have the last say. It probably makes more sense if you
12295 think about it while looking at the @samp{CXXFLAGS=-O0} above, which
12296 should supersede any other switch from @code{AM_CXXFLAGS} or
12297 @code{mumble_CXXFLAGS} (and this of course replaces the previous value
12298 of @code{CXXFLAGS}).
12300 You should never redefine a user variable such as @code{CPPFLAGS} in
12301 @file{Makefile.am}. Use @samp{automake -Woverride} to diagnose such
12302 mistakes. Even something like
12305 CPPFLAGS = -DDATADIR=\"$(datadir)\" @@CPPFLAGS@@
12309 is erroneous. Although this preserves @file{configure}'s value of
12310 @code{CPPFLAGS}, the definition of @code{DATADIR} will disappear if a
12311 user attempts to override @code{CPPFLAGS} from the @command{make}
12315 AM_CPPFLAGS = -DDATADIR=\"$(datadir)\"
12319 is all that is needed here if no per-target flags are used.
12321 You should not add options to these user variables within
12322 @file{configure} either, for the same reason. Occasionally you need
12323 to modify these variables to perform a test, but you should reset
12324 their values afterwards. In contrast, it is OK to modify the
12325 @samp{AM_} variables within @file{configure} if you @code{AC_SUBST}
12326 them, but it is rather rare that you need to do this, unless you
12327 really want to change the default definitions of the @samp{AM_}
12328 variables in all @file{Makefile}s.
12330 What we recommend is that you define extra flags in separate
12331 variables. For instance, you may write an Autoconf macro that computes
12332 a set of warning options for the C compiler, and @code{AC_SUBST} them
12333 in @code{WARNINGCFLAGS}; you may also have an Autoconf macro that
12334 determines which compiler and which linker flags should be used to
12335 link with library @file{libfoo}, and @code{AC_SUBST} these in
12336 @code{LIBFOOCFLAGS} and @code{LIBFOOLDFLAGS}. Then, a
12337 @file{Makefile.am} could use these variables as follows:
12340 AM_CFLAGS = $(WARNINGCFLAGS)
12341 bin_PROGRAMS = prog1 prog2
12342 prog1_SOURCES = @dots{}
12343 prog2_SOURCES = @dots{}
12344 prog2_CFLAGS = $(LIBFOOCFLAGS) $(AM_CFLAGS)
12345 prog2_LDFLAGS = $(LIBFOOLDFLAGS)
12348 In this example both programs will be compiled with the flags
12349 substituted into @samp{$(WARNINGCFLAGS)}, and @code{prog2} will
12350 additionally be compiled with the flags required to link with
12353 Note that listing @code{AM_CFLAGS} in a per-target @code{CFLAGS}
12354 variable is a common idiom to ensure that @code{AM_CFLAGS} applies to
12355 every target in a @file{Makefile.in}.
12357 Using variables like this gives you full control over the ordering of
12358 the flags. For instance, if there is a flag in $(WARNINGCFLAGS) that
12359 you want to negate for a particular target, you can use something like
12360 @samp{prog1_CFLAGS = $(AM_CFLAGS) -no-flag}. If all of these flags had
12361 been forcefully appended to @code{CFLAGS}, there would be no way to
12362 disable one flag. Yet another reason to leave user variables to
12365 Finally, we have avoided naming the variable of the example
12366 @code{LIBFOO_LDFLAGS} (with an underscore) because that would cause
12367 Automake to think that this is actually a per-target variable (like
12368 @code{mumble_LDFLAGS}) for some non-declared @code{LIBFOO} target.
12370 @subheading Other Variables
12372 There are other variables in Automake that follow similar principles
12373 to allow user options. For instance, Texinfo rules (@pxref{Texinfo})
12374 use @code{MAKEINFOFLAGS} and @code{AM_MAKEINFOFLAGS}. Similarly,
12375 DejaGnu tests (@pxref{DejaGnu Tests}) use @code{RUNTESTDEFAULTFLAGS} and
12376 @code{AM_RUNTESTDEFAULTFLAGS}. The tags and ctags rules
12377 (@pxref{Tags}) use @code{ETAGSFLAGS}, @code{AM_ETAGSFLAGS},
12378 @code{CTAGSFLAGS}, and @code{AM_CTAGSFLAGS}. Java rules
12379 (@pxref{Java}) use @code{JAVACFLAGS} and @code{AM_JAVACFLAGS}. None
12380 of these rules support per-target flags (yet).
12382 To some extent, even @code{AM_MAKEFLAGS} (@pxref{Subdirectories})
12383 obeys this naming scheme. The slight difference is that
12384 @code{MAKEFLAGS} is passed to sub-@command{make}s implicitly by
12385 @command{make} itself.
12387 @code{ARFLAGS} (@pxref{A Library}) is usually defined by Automake and
12388 has neither @code{AM_} nor per-target cousin.
12390 Finally you should not think that the existence of a per-target
12391 variable implies the existence of an @code{AM_} variable or of a user
12392 variable. For instance, the @code{mumble_LDADD} per-target variable
12393 overrides the makefile-wide @code{LDADD} variable (which is not a user
12394 variable), and @code{mumble_LIBADD} exists only as a per-target
12395 variable. @xref{Program and Library Variables}.
12398 @node Renamed Objects
12399 @section Why are object files sometimes renamed?
12401 This happens when per-target compilation flags are used. Object
12402 files need to be renamed just in case they would clash with object
12403 files compiled from the same sources, but with different flags.
12404 Consider the following example.
12407 bin_PROGRAMS = true false
12408 true_SOURCES = generic.c
12409 true_CPPFLAGS = -DEXIT_CODE=0
12410 false_SOURCES = generic.c
12411 false_CPPFLAGS = -DEXIT_CODE=1
12415 Obviously the two programs are built from the same source, but it
12416 would be bad if they shared the same object, because @file{generic.o}
12417 cannot be built with both @samp{-DEXIT_CODE=0} @emph{and}
12418 @samp{-DEXIT_CODE=1}. Therefore @command{automake} outputs rules to
12419 build two different objects: @file{true-generic.o} and
12420 @file{false-generic.o}.
12422 @command{automake} doesn't actually look whether source files are
12423 shared to decide if it must rename objects. It will just rename all
12424 objects of a target as soon as it sees per-target compilation flags
12427 It's OK to share object files when per-target compilation flags are not
12428 used. For instance, @file{true} and @file{false} will both use
12429 @file{version.o} in the following example.
12432 AM_CPPFLAGS = -DVERSION=1.0
12433 bin_PROGRAMS = true false
12434 true_SOURCES = true.c version.c
12435 false_SOURCES = false.c version.c
12438 Note that the renaming of objects is also affected by the
12439 @code{_SHORTNAME} variable (@pxref{Program and Library Variables}).
12442 @node Per-Object Flags
12443 @section Per-Object Flags Emulation
12444 @cindex Per-object flags, emulated
12447 One of my source files needs to be compiled with different flags. How
12451 Automake supports per-program and per-library compilation flags (see
12452 @ref{Program and Library Variables} and @ref{Flag Variables
12453 Ordering}). With this you can define compilation flags that apply to
12454 all files compiled for a target. For instance, in
12458 foo_SOURCES = foo.c foo.h bar.c bar.h main.c
12459 foo_CFLAGS = -some -flags
12463 @file{foo-foo.o}, @file{foo-bar.o}, and @file{foo-main.o} will all be
12464 compiled with @samp{-some -flags}. (If you wonder about the names of
12465 these object files, see @ref{Renamed Objects}.) Note that
12466 @code{foo_CFLAGS} gives the flags to use when compiling all the C
12467 sources of the @emph{program} @code{foo}, it has nothing to do with
12468 @file{foo.c} or @file{foo-foo.o} specifically.
12470 What if @file{foo.c} needs to be compiled into @file{foo.o} using some
12471 specific flags, that none of the other files requires? Obviously
12472 per-program flags are not directly applicable here. Something like
12473 per-object flags are expected, i.e., flags that would be used only
12474 when creating @file{foo-foo.o}. Automake does not support that,
12475 however this is easy to simulate using a library that contains only
12476 that object, and compiling this library with per-library flags.
12480 foo_SOURCES = bar.c bar.h main.c
12481 foo_CFLAGS = -some -flags
12482 foo_LDADD = libfoo.a
12483 noinst_LIBRARIES = libfoo.a
12484 libfoo_a_SOURCES = foo.c foo.h
12485 libfoo_a_CFLAGS = -some -other -flags
12488 Here @file{foo-bar.o} and @file{foo-main.o} will all be
12489 compiled with @samp{-some -flags}, while @file{libfoo_a-foo.o} will
12490 be compiled using @samp{-some -other -flags}. Eventually, all
12491 three objects will be linked to form @file{foo}.
12493 This trick can also be achieved using Libtool convenience libraries,
12494 for instance @samp{noinst_LTLIBRARIES = libfoo.la} (@pxref{Libtool
12495 Convenience Libraries}).
12497 Another tempting idea to implement per-object flags is to override the
12498 compile rules @command{automake} would output for these files.
12499 Automake will not define a rule for a target you have defined, so you
12500 could think about defining the @samp{foo-foo.o: foo.c} rule yourself.
12501 We recommend against this, because this is error prone. For instance,
12502 if you add such a rule to the first example, it will break the day you
12503 decide to remove @code{foo_CFLAGS} (because @file{foo.c} will then be
12504 compiled as @file{foo.o} instead of @file{foo-foo.o}, @pxref{Renamed
12505 Objects}). Also in order to support dependency tracking, the two
12506 @file{.o}/@file{.obj} extensions, and all the other flags variables
12507 involved in a compilation, you will end up modifying a copy of the
12508 rule previously output by @command{automake} for this file. If a new
12509 release of Automake generates a different rule, your copy will need to
12510 be updated by hand.
12512 @node Multiple Outputs
12513 @section Handling Tools that Produce Many Outputs
12514 @cindex multiple outputs, rules with
12515 @cindex many outputs, rules with
12516 @cindex rules with multiple outputs
12518 This section describes a @command{make} idiom that can be used when a
12519 tool produces multiple output files. It is not specific to Automake
12520 and can be used in ordinary @file{Makefile}s.
12522 Suppose we have a program called @command{foo} that will read one file
12523 called @file{data.foo} and produce two files named @file{data.c} and
12524 @file{data.h}. We want to write a @file{Makefile} rule that captures
12525 this one-to-two dependency.
12527 The naive rule is incorrect:
12530 # This is incorrect.
12531 data.c data.h: data.foo
12536 What the above rule really says is that @file{data.c} and
12537 @file{data.h} each depend on @file{data.foo}, and can each be built by
12538 running @samp{foo data.foo}. In other words it is equivalent to:
12541 # We do not want this.
12549 which means that @command{foo} can be run twice. Usually it will not
12550 be run twice, because @command{make} implementations are smart enough
12551 to check for the existence of the second file after the first one has
12552 been built; they will therefore detect that it already exists.
12553 However there are a few situations where it can run twice anyway:
12557 The most worrying case is when running a parallel @command{make}. If
12558 @file{data.c} and @file{data.h} are built in parallel, two @samp{foo
12559 data.foo} commands will run concurrently. This is harmful.
12561 Another case is when the dependency (here @file{data.foo}) is
12562 (or depends upon) a phony target.
12565 A solution that works with parallel @command{make} but not with
12566 phony dependencies is the following:
12569 data.c data.h: data.foo
12575 The above rules are equivalent to
12580 data.h: data.foo data.c
12585 therefore a parallel @command{make} will have to serialize the builds
12586 of @file{data.c} and @file{data.h}, and will detect that the second is
12587 no longer needed once the first is over.
12589 Using this pattern is probably enough for most cases. However it does
12590 not scale easily to more output files (in this scheme all output files
12591 must be totally ordered by the dependency relation), so we will
12592 explore a more complicated solution.
12594 Another idea is to write the following:
12597 # There is still a problem with this one.
12604 The idea is that @samp{foo data.foo} is run only when @file{data.c}
12605 needs to be updated, but we further state that @file{data.h} depends
12606 upon @file{data.c}. That way, if @file{data.h} is required and
12607 @file{data.foo} is out of date, the dependency on @file{data.c} will
12610 This is almost perfect, but suppose we have built @file{data.h} and
12611 @file{data.c}, and then we erase @file{data.h}. Then, running
12612 @samp{make data.h} will not rebuild @file{data.h}. The above rules
12613 just state that @file{data.c} must be up-to-date with respect to
12614 @file{data.foo}, and this is already the case.
12616 What we need is a rule that forces a rebuild when @file{data.h} is
12617 missing. Here it is:
12623 ## Recover from the removal of $@@
12624 @@if test -f $@@; then :; else \
12626 $(MAKE) $(AM_MAKEFLAGS) data.c; \
12630 The above scheme can be extended to handle more outputs and more
12631 inputs. One of the outputs is selected to serve as a witness to the
12632 successful completion of the command, it depends upon all inputs, and
12633 all other outputs depend upon it. For instance, if @command{foo}
12634 should additionally read @file{data.bar} and also produce
12635 @file{data.w} and @file{data.x}, we would write:
12638 data.c: data.foo data.bar
12639 foo data.foo data.bar
12640 data.h data.w data.x: data.c
12641 ## Recover from the removal of $@@
12642 @@if test -f $@@; then :; else \
12644 $(MAKE) $(AM_MAKEFLAGS) data.c; \
12648 However there are now three minor problems in this setup. One is related
12649 to the timestamp ordering of @file{data.h}, @file{data.w},
12650 @file{data.x}, and @file{data.c}. Another one is a race condition
12651 if a parallel @command{make} attempts to run multiple instances of the
12652 recover block at once. Finally, the recursive rule breaks @samp{make -n}
12653 when run with GNU @command{make} (as well as some other @command{make}
12654 implementations), as it may remove @file{data.h} even when it should not
12655 (@pxref{MAKE Variable, , How the @code{MAKE} Variable Works, make,
12656 The GNU Make Manual}).
12658 Let us deal with the first problem. @command{foo} outputs four files,
12659 but we do not know in which order these files are created. Suppose
12660 that @file{data.h} is created before @file{data.c}. Then we have a
12661 weird situation. The next time @command{make} is run, @file{data.h}
12662 will appear older than @file{data.c}, the second rule will be
12663 triggered, a shell will be started to execute the @samp{if@dots{}fi}
12664 command, but actually it will just execute the @code{then} branch,
12665 that is: nothing. In other words, because the witness we selected is
12666 not the first file created by @command{foo}, @command{make} will start
12667 a shell to do nothing each time it is run.
12669 A simple riposte is to fix the timestamps when this happens.
12672 data.c: data.foo data.bar
12673 foo data.foo data.bar
12674 data.h data.w data.x: data.c
12675 @@if test -f $@@; then \
12678 ## Recover from the removal of $@@
12680 $(MAKE) $(AM_MAKEFLAGS) data.c; \
12684 Another solution is to use a different and dedicated file as witness,
12685 rather than using any of @command{foo}'s outputs.
12688 data.stamp: data.foo data.bar
12691 foo data.foo data.bar
12692 @@mv -f data.tmp $@@
12693 data.c data.h data.w data.x: data.stamp
12694 ## Recover from the removal of $@@
12695 @@if test -f $@@; then :; else \
12696 rm -f data.stamp; \
12697 $(MAKE) $(AM_MAKEFLAGS) data.stamp; \
12701 @file{data.tmp} is created before @command{foo} is run, so it has a
12702 timestamp older than output files output by @command{foo}. It is then
12703 renamed to @file{data.stamp} after @command{foo} has run, because we
12704 do not want to update @file{data.stamp} if @command{foo} fails.
12706 This solution still suffers from the second problem: the race
12707 condition in the recover rule. If, after a successful build, a user
12708 erases @file{data.c} and @file{data.h}, and runs @samp{make -j}, then
12709 @command{make} may start both recover rules in parallel. If the two
12710 instances of the rule execute @samp{$(MAKE) $(AM_MAKEFLAGS)
12711 data.stamp} concurrently the build is likely to fail (for instance, the
12712 two rules will create @file{data.tmp}, but only one can rename it).
12714 Admittedly, such a weird situation does not arise during ordinary
12715 builds. It occurs only when the build tree is mutilated. Here
12716 @file{data.c} and @file{data.h} have been explicitly removed without
12717 also removing @file{data.stamp} and the other output files.
12718 @code{make clean; make} will always recover from these situations even
12719 with parallel makes, so you may decide that the recover rule is solely
12720 to help non-parallel make users and leave things as-is. Fixing this
12721 requires some locking mechanism to ensure only one instance of the
12722 recover rule rebuilds @file{data.stamp}. One could imagine something
12723 along the following lines.
12726 data.c data.h data.w data.x: data.stamp
12727 ## Recover from the removal of $@@
12728 @@if test -f $@@; then :; else \
12729 trap 'rm -rf data.lock data.stamp' 1 2 13 15; \
12730 ## mkdir is a portable test-and-set
12731 if mkdir data.lock 2>/dev/null; then \
12732 ## This code is being executed by the first process.
12733 rm -f data.stamp; \
12734 $(MAKE) $(AM_MAKEFLAGS) data.stamp; \
12735 result=$$?; rm -rf data.lock; exit $$result; \
12737 ## This code is being executed by the follower processes.
12738 ## Wait until the first process is done.
12739 while test -d data.lock; do sleep 1; done; \
12740 ## Succeed if and only if the first process succeeded.
12741 test -f data.stamp; \
12746 Using a dedicated witness, like @file{data.stamp}, is very handy when
12747 the list of output files is not known beforehand. As an illustration,
12748 consider the following rules to compile many @file{*.el} files into
12749 @file{*.elc} files in a single command. It does not matter how
12750 @code{ELFILES} is defined (as long as it is not empty: empty targets
12751 are not accepted by POSIX).
12754 ELFILES = one.el two.el three.el @dots{}
12755 ELCFILES = $(ELFILES:=c)
12757 elc-stamp: $(ELFILES)
12760 $(elisp_comp) $(ELFILES)
12761 @@mv -f elc-temp $@@
12763 $(ELCFILES): elc-stamp
12764 @@if test -f $@@; then :; else \
12765 ## Recover from the removal of $@@
12766 trap 'rm -rf elc-lock elc-stamp' 1 2 13 15; \
12767 if mkdir elc-lock 2>/dev/null; then \
12768 ## This code is being executed by the first process.
12770 $(MAKE) $(AM_MAKEFLAGS) elc-stamp; \
12773 ## This code is being executed by the follower processes.
12774 ## Wait until the first process is done.
12775 while test -d elc-lock; do sleep 1; done; \
12776 ## Succeed if and only if the first process succeeded.
12777 test -f elc-stamp; exit $$?; \
12783 These solutions all still suffer from the third problem, namely that
12784 they break the promise that @samp{make -n} should not cause any actual
12785 changes to the tree. For those solutions that do not create lock files,
12786 it is possible to split the recover rules into two separate recipe
12787 commands, one of which does all work but the recursion, and the
12788 other invokes the recursive @samp{$(MAKE)}. The solutions involving
12789 locking could act upon the contents of the @samp{MAKEFLAGS} variable,
12790 but parsing that portably is not easy (@pxref{The Make Macro MAKEFLAGS,,,
12791 autoconf, The Autoconf Manual}). Here is an example:
12794 ELFILES = one.el two.el three.el @dots{}
12795 ELCFILES = $(ELFILES:=c)
12797 elc-stamp: $(ELFILES)
12800 $(elisp_comp) $(ELFILES)
12801 @@mv -f elc-temp $@@
12803 $(ELCFILES): elc-stamp
12804 ## Recover from the removal of $@@
12805 @@dry=; for f in x $$MAKEFLAGS; do \
12811 if test -f $@@; then :; else \
12812 $$dry trap 'rm -rf elc-lock elc-stamp' 1 2 13 15; \
12813 if $$dry mkdir elc-lock 2>/dev/null; then \
12814 ## This code is being executed by the first process.
12815 $$dry rm -f elc-stamp; \
12816 $(MAKE) $(AM_MAKEFLAGS) elc-stamp; \
12817 $$dry rmdir elc-lock; \
12819 ## This code is being executed by the follower processes.
12820 ## Wait until the first process is done.
12821 while test -d elc-lock && test -z "$$dry"; do \
12825 ## Succeed if and only if the first process succeeded.
12826 $$dry test -f elc-stamp; exit $$?; \
12831 For completeness it should be noted that GNU @command{make} is able to
12832 express rules with multiple output files using pattern rules
12833 (@pxref{Pattern Examples, , Pattern Rule Examples, make, The GNU Make
12834 Manual}). We do not discuss pattern rules here because they are not
12835 portable, but they can be convenient in packages that assume GNU
12839 @node Hard-Coded Install Paths
12840 @section Installing to Hard-Coded Locations
12843 My package needs to install some configuration file. I tried to use
12844 the following rule, but @samp{make distcheck} fails. Why?
12848 install-data-local:
12849 $(INSTALL_DATA) $(srcdir)/afile $(DESTDIR)/etc/afile
12854 My package needs to populate the installation directory of another
12855 package at install-time. I can easily compute that installation
12856 directory in @file{configure}, but if I install files therein,
12857 @samp{make distcheck} fails. How else should I do?
12860 These two setups share their symptoms: @samp{make distcheck} fails
12861 because they are installing files to hard-coded paths. In the later
12862 case the path is not really hard-coded in the package, but we can
12863 consider it to be hard-coded in the system (or in whichever tool that
12864 supplies the path). As long as the path does not use any of the
12865 standard directory variables (@samp{$(prefix)}, @samp{$(bindir)},
12866 @samp{$(datadir)}, etc.), the effect will be the same:
12867 user-installations are impossible.
12869 As a (non-root) user who wants to install a package, you usually have no
12870 right to install anything in @file{/usr} or @file{/usr/local}. So you
12871 do something like @samp{./configure --prefix ~/usr} to install a
12872 package in your own @file{~/usr} tree.
12874 If a package attempts to install something to some hard-coded path
12875 (e.g., @file{/etc/afile}), regardless of this @option{--prefix} setting,
12876 then the installation will fail. @samp{make distcheck} performs such
12877 a @option{--prefix} installation, hence it will fail too.
12879 Now, there are some easy solutions.
12881 The above @code{install-data-local} example for installing
12882 @file{/etc/afile} would be better replaced by
12885 sysconf_DATA = afile
12889 by default @code{sysconfdir} will be @samp{$(prefix)/etc}, because
12890 this is what the GNU Standards require. When such a package is
12891 installed on an FHS compliant system, the installer will have to set
12892 @samp{--sysconfdir=/etc}. As the maintainer of the package you
12893 should not be concerned by such site policies: use the appropriate
12894 standard directory variable to install your files so that the installer
12895 can easily redefine these variables to match their site conventions.
12897 Installing files that should be used by another package is slightly
12898 more involved. Let's take an example and assume you want to install
12899 a shared library that is a Python extension module. If you ask Python
12900 where to install the library, it will answer something like this:
12903 % @kbd{python -c 'from distutils import sysconfig;
12904 print sysconfig.get_python_lib(1,0)'}
12905 /usr/lib/python2.5/site-packages
12908 If you indeed use this absolute path to install your shared library,
12909 non-root users will not be able to install the package, hence
12912 Let's do better. The @samp{sysconfig.get_python_lib()} function
12913 actually accepts a third argument that will replace Python's
12914 installation prefix.
12917 % @kbd{python -c 'from distutils import sysconfig;
12918 print sysconfig.get_python_lib(1,0,"$@{exec_prefix@}")'}
12919 $@{exec_prefix@}/lib/python2.5/site-packages
12922 You can also use this new path. If you do
12925 root users can install your package with the same @option{--prefix}
12926 as Python (you get the behavior of the previous attempt)
12929 non-root users can install your package too, they will have the
12930 extension module in a place that is not searched by Python but they
12931 can work around this using environment variables (and if you installed
12932 scripts that use this shared library, it's easy to tell Python were to
12933 look in the beginning of your script, so the script works in both
12937 The @code{AM_PATH_PYTHON} macro uses similar commands to define
12938 @samp{$(pythondir)} and @samp{$(pyexecdir)} (@pxref{Python}).
12940 Of course not all tools are as advanced as Python regarding that
12941 substitution of @var{prefix}. So another strategy is to figure the
12942 part of the installation directory that must be preserved. For
12943 instance, here is how @code{AM_PATH_LISPDIR} (@pxref{Emacs Lisp})
12944 computes @samp{$(lispdir)}:
12947 $EMACS -batch -q -eval '(while load-path
12948 (princ (concat (car load-path) "\n"))
12949 (setq load-path (cdr load-path)))' >conftest.out
12952 -e '/.*\/lib\/x*emacs\/site-lisp$/@{
12953 s,.*/lib/\(x*emacs/site-lisp\)$,$@{libdir@}/\1,;p;q;
12955 -e '/.*\/share\/x*emacs\/site-lisp$/@{
12956 s,.*/share/\(x*emacs/site-lisp\),$@{datarootdir@}/\1,;p;q;
12961 I.e., it just picks the first directory that looks like
12962 @file{*/lib/*emacs/site-lisp} or @file{*/share/*emacs/site-lisp} in
12963 the search path of emacs, and then substitutes @samp{$@{libdir@}} or
12964 @samp{$@{datadir@}} appropriately.
12966 The emacs case looks complicated because it processes a list and
12967 expects two possible layouts, otherwise it's easy, and the benefits for
12968 non-root users are really worth the extra @command{sed} invocation.
12971 @node Debugging Make Rules
12972 @section Debugging Make Rules
12973 @cindex debugging rules
12974 @cindex rules, debugging
12976 The rules and dependency trees generated by @command{automake} can get
12977 rather complex, and leave the developer head-scratching when things
12978 don't work as expected. Besides the debug options provided by the
12979 @command{make} command (@pxref{Options Summary,,, make, The GNU Make
12980 Manual}), here's a couple of further hints for debugging makefiles
12981 generated by @command{automake} effectively:
12985 If less verbose output has been enabled in the package with the use
12986 of silent rules (@pxref{Automake Silent Rules}), you can use
12987 @code{make V=1} to see the commands being executed.
12989 @code{make -n} can help show what would be done without actually doing
12990 it. Note however, that this will @emph{still execute} commands prefixed
12991 with @samp{+}, and, when using GNU @command{make}, commands that contain
12992 the strings @samp{$(MAKE)} or @samp{$@{MAKE@}} (@pxref{Instead of
12993 Execution,,, make, The GNU Make Manual}).
12994 Typically, this is helpful to show what recursive rules would do, but it
12995 means that, in your own rules, you should not mix such recursion with
12996 actions that change any files.@footnote{Automake's @samp{dist} and
12997 @samp{distcheck} rules had a bug in this regard in that they created
12998 directories even with @option{-n}, but this has been fixed in Automake
12999 1.11.} Furthermore, note that GNU @command{make} will update
13000 prerequisites for the @file{Makefile} file itself even with @option{-n}
13001 (@pxref{Remaking Makefiles,,, make, The GNU Make Manual}).
13003 @code{make SHELL="/bin/bash -vx"} can help debug complex rules.
13004 @xref{The Make Macro SHELL,,, autoconf, The Autoconf Manual}, for some
13005 portability quirks associated with this construct.
13007 @code{echo 'print: ; @@echo "$(VAR)"' | make -f Makefile -f - print}
13008 can be handy to examine the expanded value of variables. You may need
13009 to use a target other than @samp{print} if that is already used or a
13010 file with that name exists.
13012 @url{http://bashdb.sourceforge.net/@/remake/} provides a modified
13013 GNU @command{make} command called @command{remake} that copes with
13014 complex GNU @command{make}-specific Makefiles and allows to trace
13015 execution, examine variables, and call rules interactively, much like
13020 @node Reporting Bugs
13021 @section Reporting Bugs
13023 Most nontrivial software has bugs. Automake is no exception. Although
13024 we cannot promise we can or will fix a bug, and we might not even agree
13025 that it is a bug, we want to hear about problems you encounter. Often we
13026 agree they are bugs and want to fix them.
13028 To make it possible for us to fix a bug, please report it. In order to
13029 do so effectively, it helps to know when and how to do it.
13031 Before reporting a bug, it is a good idea to see if it is already known.
13032 You can look at the @uref{http://debbugs.gnu.org/, GNU Bug Tracker}
13033 and the @uref{http://lists.gnu.org/@/archive/@/html/@/bug-automake/,
13034 bug-automake mailing list archives} for previous bug reports. We
13036 @uref{http://sourceware.org/@/cgi-bin/@/gnatsweb.pl?database=automake,
13037 Gnats database} for bug tracking, so some bugs might have been reported
13038 there already. Please do not use it for new bug reports, however.
13040 If the bug is not already known, it should be reported. It is very
13041 important to report bugs in a way that is useful and efficient. For
13042 this, please familiarize yourself with
13043 @uref{http://www.chiark.greenend.org.uk/@/~sgtatham/@/bugs.html, How to
13044 Report Bugs Effectively} and
13045 @uref{http://catb.org/@/~esr/@/faqs/@/smart-questions.html, How to Ask
13046 Questions the Smart Way}. This helps you and developers to save time
13047 which can then be spent on fixing more bugs and implementing more
13050 For a bug report, a feature request or other suggestions, please send
13051 email to @email{@value{PACKAGE_BUGREPORT}}. This will then open a new
13052 bug in the @uref{http://debbugs.gnu.org/@/automake, bug tracker}. Be
13053 sure to include the versions of Autoconf and Automake that you use.
13054 Ideally, post a minimal @file{Makefile.am} and @file{configure.ac} that
13055 reproduces the problem you encounter. If you have encountered test
13056 suite failures, please attach the @file{test-suite.log} file.
13058 @c ========================================================== Appendices
13061 @node Copying This Manual
13062 @appendix Copying This Manual
13065 * GNU Free Documentation License:: License for copying this manual
13068 @node GNU Free Documentation License
13069 @appendixsec GNU Free Documentation License
13077 * Macro Index:: Index of Autoconf macros
13078 * Variable Index:: Index of Makefile variables
13079 * General Index:: General index
13083 @appendixsec Macro Index
13087 @node Variable Index
13088 @appendixsec Variable Index
13092 @node General Index
13093 @appendixsec General Index
13100 @c LocalWords: texinfo setfilename settitle setchapternewpage texi direntry
13101 @c LocalWords: dircategory in's aclocal ifinfo titlepage Tromey vskip pt sp
13102 @c LocalWords: filll defcodeindex ov cv op tr syncodeindex fn cp vr ifnottex
13103 @c LocalWords: dir Automake's ac Dist Gnits gnits dfn Autoconf's pxref
13104 @c LocalWords: cindex Autoconf autoconf perl samp cvs dist trindex SUBST foo
13105 @c LocalWords: xs emph FIXME ref vindex pkglibdir pkgincludedir pkgdatadir mt
13106 @c LocalWords: pkg libdir cpio bindir sbindir rmt pax sbin zar zardir acindex
13107 @c LocalWords: HTML htmldir html noinst TEXINFOS nodist nobase strudel CFLAGS
13108 @c LocalWords: libmumble CC YFLAGS itemx de fication config url comp
13109 @c LocalWords: depcomp elisp sh mdate mkinstalldirs mkdir py tex dvi ps pdf
13110 @c LocalWords: ylwrap zardoz INIT gettext acinclude mv FUNCS LIBOBJS LDADD fr
13111 @c LocalWords: uref featureful dnl src LINGUAS es ko nl pl sl sv PROG ISC doc
13112 @c LocalWords: POSIX STDC fcntl FUNC ALLOCA blksize struct stat intl po chmod
13113 @c LocalWords: ChangeLog SUBDIRS gettextize gpl testdata getopt INTLLIBS cpp
13114 @c LocalWords: localedir datadir DLOCALEDIR DEXIT CPPFLAGS autoreconf opindex
13115 @c LocalWords: AUX var symlink deps Wno Wnone package's aclocal's distclean
13116 @c LocalWords: ltmain xref LIBSOURCE LIBSOURCES LIBOBJ MEMCMP vs RANLIB CXX
13117 @c LocalWords: LDFLAGS LIBTOOL libtool XTRA LIBS gettext's acdir APIVERSION
13118 @c LocalWords: dirlist noindent usr TIOCGWINSZ sc
13119 @c LocalWords: GWINSZ termios SRCDIR tarball bzip LISPDIR lispdir XEmacs CCAS
13120 @c LocalWords: emacsen MicroEmacs CCASFLAGS UX GCJ gcj GCJFLAGS posix DMALLOC
13121 @c LocalWords: dmalloc ldmalloc REGEX regex DEPDIR DEP DEFUN aclocaldir fi
13122 @c LocalWords: mymacro myothermacro AMFLAGS autopoint autogen libtoolize yum
13123 @c LocalWords: autoheader README MAKEFLAGS subdir Inetutils sync COND endif
13124 @c LocalWords: Miller's installable includedir inc pkgdata EXEEXT libexec bsd
13125 @c LocalWords: pkglib libexecdir prog libcpio cpio's dlopen dlpreopen linux
13126 @c LocalWords: subsubsection OBJEXT esac lib LTLIBRARIES liblob LIBADD AR ar
13127 @c LocalWords: ARFLAGS cru ing maude libgettext lo LTLIBOBJS rpath SGI PRE yy
13128 @c LocalWords: libmaude CCLD CXXFLAGS FFLAGS LFLAGS OBJCFLAGS RFLAGS DEFS cc
13129 @c LocalWords: OBJCXXFLAGS
13130 @c LocalWords: SHORTNAME vtable srcdir nostdinc basename yxx cxx ll lxx gdb
13131 @c LocalWords: lexers yymaxdepth maxdepth yyparse yylex yyerror yylval lval
13132 @c LocalWords: yychar yydebug yypact yyr yydef def yychk chk yypgo pgo yyact
13133 @c LocalWords: yyexca exca yyerrflag errflag yynerrs nerrs yyps yypv pv yys
13134 @c LocalWords: yystate yytmp tmp yyv yyval val yylloc lloc yyreds yytoks toks
13135 @c LocalWords: yylhs yylen yydefred yydgoto yysindex yyrindex yygindex yyname
13136 @c LocalWords: yytable yycheck yyrule byacc CXXCOMPILE CXXLINK FLINK cfortran
13137 @c LocalWords: Catalogue preprocessable FLIBS libfoo baz JAVACFLAGS java exe
13138 @c LocalWords: SunOS fying basenames exeext uninstalled oldinclude kr FSF's
13139 @c LocalWords: pkginclude oldincludedir sysconf sharedstate localstate gcc rm
13140 @c LocalWords: sysconfdir sharedstatedir localstatedir preexist CLEANFILES gz
13141 @c LocalWords: depfile tmpdepfile depmode const interoperate
13142 @c LocalWords: JAVAC javac JAVAROOT builddir CLASSPATH ENV pyc pyo pkgpython
13143 @c LocalWords: pyexecdir pkgpyexecdir Python's pythondir pkgpythondir txi ois
13144 @c LocalWords: installinfo vers MAKEINFO makeinfo MAKEINFOFLAGS noinstall rf
13145 @c LocalWords: mandir thesame alsothesame installman myexecbin DESTDIR Pinard
13146 @c LocalWords: uninstall installdirs uninstalls MOSTLYCLEANFILES mostlyclean
13147 @c LocalWords: DISTCLEANFILES MAINTAINERCLEANFILES GZIP gzip shar exp
13148 @c LocalWords: distdir distcheck distcleancheck listfiles distuninstallcheck
13149 @c LocalWords: VPATH tarfile stdout XFAIL DejaGnu dejagnu DEJATOOL runtest ln
13150 @c LocalWords: RUNTESTDEFAULTFLAGS toolchain RUNTESTFLAGS asis readme DVIPS
13151 @c LocalWords: installcheck gzipped tarZ std utils etags mkid cd
13152 @c LocalWords: ARGS taggable ETAGSFLAGS lang ctags CTAGSFLAGS GTAGS gtags idl
13153 @c LocalWords: foocc doit idlC multilibs ABIs cmindex defmac ARG enableval FC
13154 @c LocalWords: MSG xtrue DBG pathchk CYGWIN afile proglink versioned CVS's TE
13155 @c LocalWords: wildcards Autoconfiscated subsubheading autotools Meyering API
13156 @c LocalWords: ois's wildcard Wportability cartouche vrindex printindex Duret
13157 @c LocalWords: DSOMEFLAG DVERSION automake Lutz insertcopying versioning FAQ
13158 @c LocalWords: LTLIBOBJ Libtool's libtool's libltdl dlopening itutions libbar
13159 @c LocalWords: WANTEDLIBS libhello sublibraries libtop libsub dlopened Ratfor
13160 @c LocalWords: mymodule timestamps timestamp underquoted MAKEINFOHTMLFLAGS te
13161 @c LocalWords: GNUmakefile Subpackages subpackage's subpackages aux
13162 @c LocalWords: detailmenu Timeline pwd reldir AUTOM autom PREREQ FOOBAR libc
13163 @c LocalWords: libhand subpackage moduleN libmain libmisc FCFLAGS FCCOMPILE
13164 @c LocalWords: FCLINK subst sed ELCFILES elc MAKEINFOHTML dvips esyscmd ustar
13165 @c LocalWords: tarballs Woverride vfi ELFILES djm AutoMake honkin FSF
13166 @c LocalWords: fileutils precanned MacKenzie's reimplement termutils Tromey's
13167 @c LocalWords: cois gnitsians LIBPROGRAMS progs LIBLIBRARIES Textutils Ulrich
13168 @c LocalWords: Matzigkeit Drepper's Gord Matzigkeit's jm Dalley Debian org
13169 @c LocalWords: Administrivia ILU CORBA Sourceware Molenda sourceware Elliston
13170 @c LocalWords: dep Oliva Akim Demaille Aiieeee Demaillator Akim's sourcequake
13171 @c LocalWords: grep backported screenshots libgcj KB unnumberedsubsubsec pre
13172 @c LocalWords: precomputing hacky makedepend inline clearmake LD PRELOAD Rel
13173 @c LocalWords: syscalls perlhist acl pm multitable headitem fdl appendixsec
13174 @c LocalWords: LTALLOCA MALLOC malloc memcmp strdup alloca libcompat xyz DFOO
13175 @c LocalWords: unprefixed buildable preprocessed DBAZ DDATADIR WARNINGCFLAGS
13176 @c LocalWords: LIBFOOCFLAGS LIBFOOLDFLAGS ftable testSubDir obj LIBTOOLFLAGS
13177 @c LocalWords: barexec Pinard's automatize initialize lzip xz cscope