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
56 @author Ralf Wildenhues
57 @author Stefano Lattarini
59 @vskip 0pt plus 1filll
65 @c We use the following macros to define indices:
66 @c @cindex concepts, and anything that does not fit elsewhere
67 @c @vindex Makefile variables
69 @c @acindex Autoconf/Automake/Libtool/M4/... macros
70 @c @opindex tool options
72 @c Define an index of configure macros.
74 @c Define an index of options.
76 @c Define an index of targets.
78 @c Define an index of commands.
81 @c Put the macros in the function index.
84 @c Put everything else into one index (arbitrarily chosen to be the
92 @comment node-name, next, previous, up
98 * Introduction:: Automake's purpose
99 * Autotools Introduction:: An Introduction to the Autotools
100 * Generalities:: General ideas
101 * Examples:: Some example packages
102 * automake Invocation:: Creating a Makefile.in
103 * configure:: Scanning configure.ac, using aclocal
104 * Directories:: Declaring subdirectories
105 * Programs:: Building programs and libraries
106 * Other Objects:: Other derived objects
107 * Other GNU Tools:: Other GNU Tools
108 * Documentation:: Building documentation
109 * Install:: What gets installed
110 * Clean:: What gets cleaned
111 * Dist:: What goes in a distribution
112 * Tests:: Support for test suites
113 * Rebuilding:: Automatic rebuilding of Makefile
114 * Options:: Changing Automake's behavior
115 * Miscellaneous:: Miscellaneous rules
116 * Include:: Including extra files in an Automake template
117 * Conditionals:: Conditionals
118 * Silencing Make:: Obtain less verbose output from @command{make}
119 * Gnits:: The effect of @option{--gnu} and @option{--gnits}
120 * Not Enough:: When Automake is not Enough
121 * Distributing:: Distributing the Makefile.in
122 * API Versioning:: About compatibility between Automake versions
123 * Upgrading:: Upgrading to a Newer Automake Version
124 * FAQ:: Frequently Asked Questions
125 * Copying This Manual:: How to make copies of this manual
126 * Indices:: Indices of variables, macros, and concepts
129 --- The Detailed Node Listing ---
131 An Introduction to the Autotools
133 * GNU Build System:: Introducing the GNU Build System
134 * Use Cases:: Use Cases for the GNU Build System
135 * Why Autotools:: How Autotools Help
136 * Hello World:: A Small Hello World Package
138 Use Cases for the GNU Build System
140 * Basic Installation:: Common installation procedure
141 * Standard Targets:: A list of standard Makefile targets
142 * Standard Directory Variables:: A list of standard directory variables
143 * Standard Configuration Variables:: Using configuration variables
144 * config.site:: Using a config.site file
145 * VPATH Builds:: Parallel build trees
146 * Two-Part Install:: Installing data and programs separately
147 * Cross-Compilation:: Building for other architectures
148 * Renaming:: Renaming programs at install time
149 * DESTDIR:: Building binary packages with DESTDIR
150 * Preparing Distributions:: Rolling out tarballs
151 * Dependency Tracking:: Automatic dependency tracking
152 * Nested Packages:: The GNU Build Systems can be nested
156 * Creating amhello:: Create @file{amhello-1.0.tar.gz} from scratch
157 * amhello's configure.ac Setup Explained::
158 * amhello's Makefile.am Setup Explained::
162 * General Operation:: General operation of Automake
163 * Strictness:: Standards conformance checking
164 * Uniform:: The Uniform Naming Scheme
165 * Length Limitations:: Staying below the command line length limit
166 * Canonicalization:: How derived variables are named
167 * User Variables:: Variables reserved for the user
168 * Auxiliary Programs:: Programs automake might require
170 Some example packages
172 * Complete:: A simple example, start to finish
173 * true:: Building true and false
175 Scanning @file{configure.ac}, using @command{aclocal}
177 * Requirements:: Configuration requirements
178 * Optional:: Other things Automake recognizes
179 * aclocal Invocation:: Auto-generating aclocal.m4
180 * Macros:: Autoconf macros supplied with Automake
182 Auto-generating aclocal.m4
184 * aclocal Options:: Options supported by aclocal
185 * Macro Search Path:: How aclocal finds .m4 files
186 * Extending aclocal:: Writing your own aclocal macros
187 * Local Macros:: Organizing local macros
188 * Serials:: Serial lines in Autoconf macros
189 * Future of aclocal:: aclocal's scheduled death
191 Autoconf macros supplied with Automake
193 * Public Macros:: Macros that you can use.
194 * Private Macros:: Macros that you should not use.
198 * Subdirectories:: Building subdirectories recursively
199 * Conditional Subdirectories:: Conditionally not building directories
200 * Alternative:: Subdirectories without recursion
201 * Subpackages:: Nesting packages
203 Conditional Subdirectories
205 * SUBDIRS vs DIST_SUBDIRS:: Two sets of directories
206 * Subdirectories with AM_CONDITIONAL:: Specifying conditional subdirectories
207 * Subdirectories with AC_SUBST:: Another way for conditional recursion
208 * Unconfigured Subdirectories:: Not even creating a @samp{Makefile}
210 Building Programs and Libraries
212 * A Program:: Building a program
213 * A Library:: Building a library
214 * A Shared Library:: Building a Libtool library
215 * Program and Library Variables:: Variables controlling program and
217 * Default _SOURCES:: Default source files
218 * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
219 * Program Variables:: Variables used when building a program
220 * Yacc and Lex:: Yacc and Lex support
221 * C++ Support:: Compiling C++ sources
222 * Objective C Support:: Compiling Objective C sources
223 * Objective C++ Support:: Compiling Objective C++ sources
224 * Unified Parallel C Support:: Compiling Unified Parallel C sources
225 * Assembly Support:: Compiling assembly sources
226 * Fortran 77 Support:: Compiling Fortran 77 sources
227 * Fortran 9x Support:: Compiling Fortran 9x sources
228 * Java Support with gcj:: Compiling Java sources using gcj
229 * Vala Support:: Compiling Vala sources
230 * Support for Other Languages:: Compiling other languages
231 * Dependencies:: Automatic dependency tracking
232 * EXEEXT:: Support for executable extensions
236 * Program Sources:: Defining program sources
237 * Linking:: Linking with libraries or extra objects
238 * Conditional Sources:: Handling conditional sources
239 * Conditional Programs:: Building a program conditionally
241 Building a Shared Library
243 * Libtool Concept:: Introducing Libtool
244 * Libtool Libraries:: Declaring Libtool Libraries
245 * Conditional Libtool Libraries:: Building Libtool Libraries Conditionally
246 * Conditional Libtool Sources:: Choosing Library Sources Conditionally
247 * Libtool Convenience Libraries:: Building Convenience Libtool Libraries
248 * Libtool Modules:: Building Libtool Modules
249 * Libtool Flags:: Using _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS
250 * LTLIBOBJS:: Using $(LTLIBOBJS) and $(LTALLOCA)
251 * Libtool Issues:: Common Issues Related to Libtool's Use
253 Common Issues Related to Libtool's Use
255 * Error required file ltmain.sh not found:: The need to run libtoolize
256 * Objects created both with libtool and without:: Avoid a specific build race
260 * Preprocessing Fortran 77:: Preprocessing Fortran 77 sources
261 * Compiling Fortran 77 Files:: Compiling Fortran 77 sources
262 * Mixing Fortran 77 With C and C++:: Mixing Fortran 77 With C and C++
264 Mixing Fortran 77 With C and C++
266 * How the Linker is Chosen:: Automatic linker selection
270 * Compiling Fortran 9x Files:: Compiling Fortran 9x sources
272 Other Derived Objects
274 * Scripts:: Executable scripts
275 * Headers:: Header files
276 * Data:: Architecture-independent data files
277 * Sources:: Derived sources
281 * Built Sources Example:: Several ways to handle built sources.
285 * Emacs Lisp:: Emacs Lisp
288 * Java:: Java bytecode compilation (deprecated)
291 Building documentation
294 * Man Pages:: Man pages
298 * Basics of Installation:: What gets installed where
299 * The Two Parts of Install:: Installing data and programs separately
300 * Extending Installation:: Adding your own rules for installation
301 * Staged Installs:: Installation in a temporary location
302 * Install Rules for the User:: Useful additional rules
304 What Goes in a Distribution
306 * Basics of Distribution:: Files distributed by default
307 * Fine-grained Distribution Control:: @code{dist_} and @code{nodist_} prefixes
308 * The dist Hook:: A target for last-minute distribution changes
309 * Checking the Distribution:: @samp{make distcheck} explained
310 * The Types of Distributions:: A variety of formats and compression methods
312 Support for test suites
314 * Generalities about Testing:: Generic concepts and terminology about testing
315 * Simple Tests:: Listing test scripts in @code{TESTS}
316 * Custom Test Drivers:: Writing and using custom test drivers
317 * Using the TAP test protocol:: Integrating test scripts that use the TAP protocol
318 * DejaGnu Tests:: Interfacing with the @command{dejagnu} testing framework
319 * Install Tests:: Running tests on installed packages
323 * Scripts-based Testsuites:: Automake-specific concepts and terminology
324 * Serial Test Harness:: Older (and discouraged) serial test harness
325 * Parallel Test Harness:: Generic concurrent test harness
327 Using the TAP test protocol
329 * Introduction to TAP::
330 * Use TAP with the Automake test harness::
331 * Incompatibilities with other TAP parsers and drivers::
332 * Links and external resources on TAP::
336 * Overview of Custom Test Drivers Support::
337 * Declaring Custom Test Drivers::
338 * API for Custom Test Drivers::
340 API for Custom Test Drivers
342 * Command-line arguments for test drivers::
343 * Log files generation and test results recording::
344 * Testsuite progress output::
346 Changing Automake's Behavior
348 * Options generalities:: Semantics of Automake option
349 * List of Automake options:: A comprehensive list of Automake options
353 * Tags:: Interfacing to cscope, etags and mkid
354 * Suffixes:: Handling new file extensions
358 * Usage of Conditionals:: Declaring conditional content
359 * Limits of Conditionals:: Enclosing complete statements
363 * Make verbosity:: Make is verbose by default
364 * Tricks For Silencing Make:: Standard and generic ways to silence make
365 * Automake Silent Rules:: How Automake can help in silencing make
367 When Automake Isn't Enough
369 * Extending:: Adding new rules or overriding existing ones.
370 * Third-Party Makefiles:: Integrating Non-Automake @file{Makefile}s.
372 Frequently Asked Questions about Automake
374 * CVS:: CVS and generated files
375 * maintainer-mode:: missing and AM_MAINTAINER_MODE
376 * Wildcards:: Why doesn't Automake support wildcards?
377 * Limitations on File Names:: Limitations on source and installed file names
378 * Errors with distclean:: Files left in build directory after distclean
379 * Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS
380 * Renamed Objects:: Why are object files sometimes renamed?
381 * Per-Object Flags:: How to simulate per-object flags?
382 * Multiple Outputs:: Writing rules for tools with many output files
383 * Hard-Coded Install Paths:: Installing to hard-coded locations
384 * Debugging Make Rules:: Strategies when things don't work as expected
385 * Reporting Bugs:: Feedback on bugs and feature requests
389 * GNU Free Documentation License:: License for copying this manual
393 * Macro Index:: Index of Autoconf macros
394 * Variable Index:: Index of Makefile variables
395 * General Index:: General index
404 @chapter Introduction
406 Automake is a tool for automatically generating @file{Makefile.in}s
407 from files called @file{Makefile.am}. Each @file{Makefile.am} is
408 basically a series of @command{make} variable
409 definitions@footnote{These variables are also called @dfn{make macros}
410 in Make terminology, however in this manual we reserve the term
411 @dfn{macro} for Autoconf's macros.}, with rules being thrown in
412 occasionally. The generated @file{Makefile.in}s are compliant with
413 the GNU Makefile standards.
415 @cindex GNU Makefile standards
417 The GNU Makefile Standards Document
418 (@pxref{Makefile Conventions, , , standards, The GNU Coding Standards})
419 is long, complicated, and subject to change. The goal of Automake is to
420 remove the burden of Makefile maintenance from the back of the
421 individual GNU maintainer (and put it on the back of the Automake
424 The typical Automake input file is simply a series of variable definitions.
425 Each such file is processed to create a @file{Makefile.in}.
427 @cindex Constraints of Automake
428 @cindex Automake constraints
430 Automake does constrain a project in certain ways; for instance, it
431 assumes that the project uses Autoconf (@pxref{Top, , Introduction,
432 autoconf, The Autoconf Manual}), and enforces certain restrictions on
433 the @file{configure.ac} contents.
435 @cindex Automake requirements
436 @cindex Requirements, Automake
438 Automake requires @command{perl} in order to generate the
439 @file{Makefile.in}s. However, the distributions created by Automake are
440 fully GNU standards-compliant, and do not require @command{perl} in order
443 @cindex Bugs, reporting
444 @cindex Reporting bugs
445 @cindex E-mail, bug reports
447 For more information on bug reports, @xref{Reporting Bugs}.
449 @node Autotools Introduction
450 @chapter An Introduction to the Autotools
452 If you are new to Automake, maybe you know that it is part of a set of
453 tools called @emph{The Autotools}. Maybe you've already delved into a
454 package full of files named @file{configure}, @file{configure.ac},
455 @file{Makefile.in}, @file{Makefile.am}, @file{aclocal.m4}, @dots{},
456 some of them claiming to be @emph{generated by} Autoconf or Automake.
457 But the exact purpose of these files and their relations is probably
458 fuzzy. The goal of this chapter is to introduce you to this machinery,
459 to show you how it works and how powerful it is. If you've never
460 installed or seen such a package, do not worry: this chapter will walk
463 If you need some teaching material, more illustrations, or a less
464 @command{automake}-centered continuation, some slides for this
465 introduction are available in Alexandre Duret-Lutz's
466 @uref{http://www.lrde.epita.fr/@/~adl/@/autotools.html,
468 This chapter is the written version of the first part of his tutorial.
471 * GNU Build System:: Introducing the GNU Build System
472 * Use Cases:: Use Cases for the GNU Build System
473 * Why Autotools:: How Autotools Help
474 * Hello World:: A Small Hello World Package
477 @node GNU Build System
478 @section Introducing the GNU Build System
479 @cindex GNU Build System, introduction
481 It is a truth universally acknowledged, that as a developer in
482 possession of a new package, you must be in want of a build system.
484 In the Unix world, such a build system is traditionally achieved using
485 the command @command{make} (@pxref{Top, , Overview, make, The GNU Make
486 Manual}). You express the recipe to build your package in a
487 @file{Makefile}. This file is a set of rules to build the files in
488 the package. For instance the program @file{prog} may be built by
489 running the linker on the files @file{main.o}, @file{foo.o}, and
490 @file{bar.o}; the file @file{main.o} may be built by running the
491 compiler on @file{main.c}; etc. Each time @command{make} is run, it
492 reads @file{Makefile}, checks the existence and modification time of
493 the files mentioned, decides what files need to be built (or rebuilt),
494 and runs the associated commands.
496 When a package needs to be built on a different platform than the one
497 it was developed on, its @file{Makefile} usually needs to be adjusted.
498 For instance the compiler may have another name or require more
499 options. In 1991, David J. MacKenzie got tired of customizing
500 @file{Makefile} for the 20 platforms he had to deal with. Instead, he
501 handcrafted a little shell script called @file{configure} to
502 automatically adjust the @file{Makefile} (@pxref{Genesis, , Genesis,
503 autoconf, The Autoconf Manual}). Compiling his package was now
504 as simple as running @code{./configure && make}.
506 @cindex GNU Coding Standards
508 Today this process has been standardized in the GNU project. The GNU
509 Coding Standards (@pxref{Managing Releases, The Release Process, ,
510 standards, The GNU Coding Standards}) explains how each package of the
511 GNU project should have a @file{configure} script, and the minimal
512 interface it should have. The @file{Makefile} too should follow some
513 established conventions. The result? A unified build system that
514 makes all packages almost indistinguishable by the installer. In its
515 simplest scenario, all the installer has to do is to unpack the
516 package, run @code{./configure && make && make install}, and repeat
517 with the next package to install.
519 We call this build system the @dfn{GNU Build System}, since it was
520 grown out of the GNU project. However it is used by a vast number of
521 other packages: following any existing convention has its advantages.
523 @cindex Autotools, introduction
525 The Autotools are tools that will create a GNU Build System for your
526 package. Autoconf mostly focuses on @file{configure} and Automake on
527 @file{Makefile}s. It is entirely possible to create a GNU Build
528 System without the help of these tools. However it is rather
529 burdensome and error-prone. We will discuss this again after some
530 illustration of the GNU Build System in action.
533 @section Use Cases for the GNU Build System
534 @cindex GNU Build System, use cases
535 @cindex GNU Build System, features
536 @cindex Features of the GNU Build System
537 @cindex Use Cases for the GNU Build System
538 @cindex @file{amhello-1.0.tar.gz}, location
539 @cindex @file{amhello-1.0.tar.gz}, use cases
541 In this section we explore several use cases for the GNU Build System.
542 You can replay all of these examples on the @file{amhello-1.0.tar.gz}
543 package distributed with Automake. If Automake is installed on your
544 system, you should find a copy of this file in
545 @file{@var{prefix}/share/doc/automake/amhello-1.0.tar.gz}, where
546 @var{prefix} is the installation prefix specified during configuration
547 (@var{prefix} defaults to @file{/usr/local}, however if Automake was
548 installed by some GNU/Linux distribution it most likely has been set
549 to @file{/usr}). If you do not have a copy of Automake installed,
550 you can find a copy of this file inside the @file{doc/} directory of
551 the Automake package.
553 Some of the following use cases present features that are in fact
554 extensions to the GNU Build System. Read: they are not specified by
555 the GNU Coding Standards, but they are nonetheless part of the build
556 system created by the Autotools. To keep things simple, we do not
557 point out the difference. Our objective is to show you many of the
558 features that the build system created by the Autotools will offer to
562 * Basic Installation:: Common installation procedure
563 * Standard Targets:: A list of standard Makefile targets
564 * Standard Directory Variables:: A list of standard directory variables
565 * Standard Configuration Variables:: Using configuration variables
566 * config.site:: Using a config.site file
567 * VPATH Builds:: Parallel build trees
568 * Two-Part Install:: Installing data and programs separately
569 * Cross-Compilation:: Building for other architectures
570 * Renaming:: Renaming programs at install time
571 * DESTDIR:: Building binary packages with DESTDIR
572 * Preparing Distributions:: Rolling out tarballs
573 * Dependency Tracking:: Automatic dependency tracking
574 * Nested Packages:: The GNU Build Systems can be nested
577 @node Basic Installation
578 @subsection Basic Installation
579 @cindex Configuration, basics
580 @cindex Installation, basics
581 @cindex GNU Build System, basics
583 The most common installation procedure looks as follows.
586 ~ % @kbd{tar zxf amhello-1.0.tar.gz}
587 ~ % @kbd{cd amhello-1.0}
588 ~/amhello-1.0 % @kbd{./configure}
590 config.status: creating Makefile
591 config.status: creating src/Makefile
593 ~/amhello-1.0 % @kbd{make}
595 ~/amhello-1.0 % @kbd{make check}
597 ~/amhello-1.0 % @kbd{su}
599 /home/adl/amhello-1.0 # @kbd{make install}
601 /home/adl/amhello-1.0 # @kbd{exit}
602 ~/amhello-1.0 % @kbd{make installcheck}
608 The user first unpacks the package. Here, and in the following
609 examples, we will use the non-portable @code{tar zxf} command for
610 simplicity. On a system without GNU @command{tar} installed, this
611 command should read @code{gunzip -c amhello-1.0.tar.gz | tar xf -}.
613 The user then enters the newly created directory to run the
614 @file{configure} script. This script probes the system for various
615 features, and finally creates the @file{Makefile}s. In this toy
616 example there are only two @file{Makefile}s, but in real-world projects,
617 there may be many more, usually one @file{Makefile} per directory.
619 It is now possible to run @code{make}. This will construct all the
620 programs, libraries, and scripts that need to be constructed for the
621 package. In our example, this compiles the @file{hello} program.
622 All files are constructed in place, in the source tree; we will see
623 later how this can be changed.
625 @code{make check} causes the package's tests to be run. This step is
626 not mandatory, but it is often good to make sure the programs that
627 have been built behave as they should, before you decide to install
628 them. Our example does not contain any tests, so running @code{make
631 @cindex su, before @code{make install}
632 After everything has been built, and maybe tested, it is time to
633 install it on the system. That means copying the programs,
634 libraries, header files, scripts, and other data files from the
635 source directory to their final destination on the system. The
636 command @code{make install} will do that. However, by default
637 everything will be installed in subdirectories of @file{/usr/local}:
638 binaries will go into @file{/usr/local/bin}, libraries will end up in
639 @file{/usr/local/lib}, etc. This destination is usually not writable
640 by any user, so we assume that we have to become root before we can
641 run @code{make install}. In our example, running @code{make install}
642 will copy the program @file{hello} into @file{/usr/local/bin}
643 and @file{README} into @file{/usr/local/share/doc/amhello}.
645 A last and optional step is to run @code{make installcheck}. This
646 command may run tests on the installed files. @code{make check} tests
647 the files in the source tree, while @code{make installcheck} tests
648 their installed copies. The tests run by the latter can be different
649 from those run by the former. For instance, there are tests that
650 cannot be run in the source tree. Conversely, some packages are set
651 up so that @code{make installcheck} will run the very same tests as
652 @code{make check}, only on different files (non-installed
653 vs.@: installed). It can make a difference, for instance when the
654 source tree's layout is different from that of the installation.
655 Furthermore it may help to diagnose an incomplete installation.
657 Presently most packages do not have any @code{installcheck} tests
658 because the existence of @code{installcheck} is little known, and its
659 usefulness is neglected. Our little toy package is no better: @code{make
660 installcheck} does nothing.
662 @node Standard Targets
663 @subsection Standard @file{Makefile} Targets
665 So far we have come across four ways to run @command{make} in the GNU
666 Build System: @code{make}, @code{make check}, @code{make install}, and
667 @code{make installcheck}. The words @code{check}, @code{install}, and
668 @code{installcheck}, passed as arguments to @command{make}, are called
669 @dfn{targets}. @code{make} is a shorthand for @code{make all},
670 @code{all} being the default target in the GNU Build System.
672 Here is a list of the most useful targets that the GNU Coding Standards
678 Build programs, libraries, documentation, etc.@: (same as @code{make}).
681 Install what needs to be installed, copying the files from the
682 package's tree to system-wide directories.
683 @item make install-strip
684 @trindex install-strip
685 Same as @code{make install}, then strip debugging symbols. Some
686 users like to trade space for useful bug reports@enddots{}
689 The opposite of @code{make install}: erase the installed files.
690 (This needs to be run from the same build tree that was installed.)
693 Erase from the build tree the files built by @code{make all}.
696 Additionally erase anything @code{./configure} created.
699 Run the test suite, if any.
700 @item make installcheck
701 @trindex installcheck
702 Check the installed programs or libraries, if supported.
705 Recreate @file{@var{package}-@var{version}.tar.gz} from all the source
709 @node Standard Directory Variables
710 @subsection Standard Directory Variables
711 @cindex directory variables
713 The GNU Coding Standards also specify a hierarchy of variables to
714 denote installation directories. Some of these are:
716 @multitable {Directory variable} {@code{$@{datarootdir@}/doc/$@{PACKAGE@}}}
717 @headitem Directory variable @tab Default value
718 @item @code{prefix} @tab @code{/usr/local}
719 @item @w{@ @ @code{exec_prefix}} @tab @code{$@{prefix@}}
720 @item @w{@ @ @ @ @code{bindir}} @tab @code{$@{exec_prefix@}/bin}
721 @item @w{@ @ @ @ @code{libdir}} @tab @code{$@{exec_prefix@}/lib}
722 @item @w{@ @ @ @ @dots{}}
723 @item @w{@ @ @code{includedir}} @tab @code{$@{prefix@}/include}
724 @item @w{@ @ @code{datarootdir}} @tab @code{$@{prefix@}/share}
725 @item @w{@ @ @ @ @code{datadir}} @tab @code{$@{datarootdir@}}
726 @item @w{@ @ @ @ @code{mandir}} @tab @code{$@{datarootdir@}/man}
727 @item @w{@ @ @ @ @code{infodir}} @tab @code{$@{datarootdir@}/info}
728 @item @w{@ @ @ @ @code{docdir}} @tab @code{$@{datarootdir@}/doc/$@{PACKAGE@}}
729 @item @w{@ @ @dots{}}
732 @c We should provide a complete table somewhere, but not here. The
733 @c complete list of directory variables it too confusing as-is. It
734 @c requires some explanations that are too complicated for this
735 @c introduction. Besides listing directories like localstatedir
736 @c would make the explanations in ``Two-Part Install'' harder.
738 Each of these directories has a role which is often obvious from its
739 name. In a package, any installable file will be installed in one of
740 these directories. For instance in @code{amhello-1.0}, the program
741 @file{hello} is to be installed in @var{bindir}, the directory for
742 binaries. The default value for this directory is
743 @file{/usr/local/bin}, but the user can supply a different value when
744 calling @command{configure}. Also the file @file{README} will be
745 installed into @var{docdir}, which defaults to
746 @file{/usr/local/share/doc/amhello}.
750 As a user, if you wish to install a package on your own account, you
751 could proceed as follows:
754 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr}
756 ~/amhello-1.0 % @kbd{make}
758 ~/amhello-1.0 % @kbd{make install}
762 This would install @file{~/usr/bin/hello} and
763 @file{~/usr/share/doc/amhello/README}.
765 The list of all such directory options is shown by
766 @code{./configure --help}.
768 @node Standard Configuration Variables
769 @subsection Standard Configuration Variables
770 @cindex configuration variables, overriding
772 The GNU Coding Standards also define a set of standard configuration
773 variables used during the build. Here are some:
782 @item @code{CXXFLAGS}
786 @item @code{CPPFLAGS}
787 C/C++ preprocessor flags
791 @command{configure} usually does a good job at setting appropriate
792 values for these variables, but there are cases where you may want to
793 override them. For instance you may have several versions of a
794 compiler installed and would like to use another one, you may have
795 header files installed outside the default search path of the
796 compiler, or even libraries out of the way of the linker.
798 Here is how one would call @command{configure} to force it to use
799 @command{gcc-3} as C compiler, use header files from
800 @file{~/usr/include} when compiling, and libraries from
801 @file{~/usr/lib} when linking.
804 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr CC=gcc-3 \
805 CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib}
808 Again, a full list of these variables appears in the output of
809 @code{./configure --help}.
812 @subsection Overriding Default Configuration Setting with @file{config.site}
813 @cindex @file{config.site} example
815 When installing several packages using the same setup, it can be
816 convenient to create a file to capture common settings.
817 If a file named @file{@var{prefix}/share/config.site} exists,
818 @command{configure} will source it at the beginning of its execution.
820 Recall the command from the previous section:
823 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr CC=gcc-3 \
824 CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib}
827 Assuming we are installing many package in @file{~/usr}, and will
828 always want to use these definitions of @code{CC}, @code{CPPFLAGS}, and
829 @code{LDFLAGS}, we can automate this by creating the following
830 @file{~/usr/share/config.site} file:
833 test -z "$CC" && CC=gcc-3
834 test -z "$CPPFLAGS" && CPPFLAGS=-I$HOME/usr/include
835 test -z "$LDFLAGS" && LDFLAGS=-L$HOME/usr/lib
838 Now, any time a @file{configure} script is using the @file{~/usr}
839 prefix, it will execute the above @file{config.site} and define
840 these three variables.
843 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr}
844 configure: loading site script /home/adl/usr/share/config.site
848 @xref{Site Defaults, , Setting Site Defaults, autoconf, The Autoconf
849 Manual}, for more information about this feature.
853 @subsection Parallel Build Trees (a.k.a.@: VPATH Builds)
854 @cindex Parallel build trees
856 @cindex source tree and build tree
857 @cindex build tree and source tree
858 @cindex trees, source vs.@: build
860 The GNU Build System distinguishes two trees: the source tree, and
863 The source tree is rooted in the directory containing
864 @file{configure}. It contains all the sources files (those that are
865 distributed), and may be arranged using several subdirectories.
867 The build tree is rooted in the directory in which @file{configure}
868 was run, and is populated with all object files, programs, libraries,
869 and other derived files built from the sources (and hence not
870 distributed). The build tree usually has the same subdirectory layout
871 as the source tree; its subdirectories are created automatically by
874 If @file{configure} is executed in its own directory, the source and
875 build trees are combined: derived files are constructed in the same
876 directories as their sources. This was the case in our first
877 installation example (@pxref{Basic Installation}).
879 A common request from users is that they want to confine all derived
880 files to a single directory, to keep their source directories
881 uncluttered. Here is how we could run @file{configure} to build
882 everything in a subdirectory called @file{build/}.
885 ~ % @kbd{tar zxf ~/amhello-1.0.tar.gz}
886 ~ % @kbd{cd amhello-1.0}
887 ~/amhello-1.0 % @kbd{mkdir build && cd build}
888 ~/amhello-1.0/build % @kbd{../configure}
890 ~/amhello-1.0/build % @kbd{make}
894 These setups, where source and build trees are different, are often
895 called @dfn{parallel builds} or @dfn{VPATH builds}. The expression
896 @emph{parallel build} is misleading: the word @emph{parallel} is a
897 reference to the way the build tree shadows the source tree, it is not
898 about some concurrency in the way build commands are run. For this
899 reason we refer to such setups using the name @emph{VPATH builds} in
900 the following. @emph{VPATH} is the name of the @command{make} feature
901 used by the @file{Makefile}s to allow these builds (@pxref{General
902 Search, , @code{VPATH} Search Path for All Prerequisites, make, The
905 @cindex multiple configurations, example
906 @cindex debug build, example
907 @cindex optimized build, example
909 VPATH builds have other interesting uses. One is to build the same
910 sources with multiple configurations. For instance:
912 @c Keep in sync with amhello-cflags.sh
914 ~ % @kbd{tar zxf ~/amhello-1.0.tar.gz}
915 ~ % @kbd{cd amhello-1.0}
916 ~/amhello-1.0 % @kbd{mkdir debug optim && cd debug}
917 ~/amhello-1.0/debug % @kbd{../configure CFLAGS='-g -O0'}
919 ~/amhello-1.0/debug % @kbd{make}
921 ~/amhello-1.0/debug % cd ../optim
922 ~/amhello-1.0/optim % @kbd{../configure CFLAGS='-O3 -fomit-frame-pointer'}
924 ~/amhello-1.0/optim % @kbd{make}
928 With network file systems, a similar approach can be used to build the
929 same sources on different machines. For instance, suppose that the
930 sources are installed on a directory shared by two hosts: @code{HOST1}
931 and @code{HOST2}, which may be different platforms.
934 ~ % @kbd{cd /nfs/src}
935 /nfs/src % @kbd{tar zxf ~/amhello-1.0.tar.gz}
938 On the first host, you could create a local build directory:
940 [HOST1] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
941 [HOST1] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure}
943 [HOST1] /tmp/amh % @kbd{make && sudo make install}
948 (Here we assume that the installer has configured @command{sudo} so it
949 can execute @code{make install} with root privileges; it is more convenient
950 than using @command{su} like in @ref{Basic Installation}).
952 On the second host, you would do exactly the same, possibly at
955 [HOST2] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
956 [HOST2] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure}
958 [HOST2] /tmp/amh % @kbd{make && sudo make install}
962 @cindex read-only source tree
963 @cindex source tree, read-only
965 In this scenario, nothing forbids the @file{/nfs/src/amhello-1.0}
966 directory from being read-only. In fact VPATH builds are also a means
967 of building packages from a read-only medium such as a CD-ROM. (The
968 FSF used to sell CD-ROM with unpacked source code, before the GNU
969 project grew so big.)
971 @node Two-Part Install
972 @subsection Two-Part Installation
974 In our last example (@pxref{VPATH Builds}), a source tree was shared
975 by two hosts, but compilation and installation were done separately on
978 The GNU Build System also supports networked setups where part of the
979 installed files should be shared amongst multiple hosts. It does so
980 by distinguishing architecture-dependent files from
981 architecture-independent files, and providing two @file{Makefile}
982 targets to install each of these classes of files.
984 @trindex install-exec
985 @trindex install-data
987 These targets are @code{install-exec} for architecture-dependent files
988 and @code{install-data} for architecture-independent files.
989 The command we used up to now, @code{make install}, can be thought of
990 as a shorthand for @code{make install-exec install-data}.
992 From the GNU Build System point of view, the distinction between
993 architecture-dependent files and architecture-independent files is
994 based exclusively on the directory variable used to specify their
995 installation destination. In the list of directory variables we
996 provided earlier (@pxref{Standard Directory Variables}), all the
997 variables based on @var{exec-prefix} designate architecture-dependent
998 directories whose files will be installed by @code{make install-exec}.
999 The others designate architecture-independent directories and will
1000 serve files installed by @code{make install-data}. @xref{The Two Parts
1001 of Install}, for more details.
1003 Here is how we could revisit our two-host installation example,
1004 assuming that (1) we want to install the package directly in
1005 @file{/usr}, and (2) the directory @file{/usr/share} is shared by the
1008 On the first host we would run
1010 [HOST1] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
1011 [HOST1] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure --prefix /usr}
1013 [HOST1] /tmp/amh % @kbd{make && sudo make install}
1017 On the second host, however, we need only install the
1018 architecture-specific files.
1020 [HOST2] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
1021 [HOST2] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure --prefix /usr}
1023 [HOST2] /tmp/amh % @kbd{make && sudo make install-exec}
1027 In packages that have installation checks, it would make sense to run
1028 @code{make installcheck} (@pxref{Basic Installation}) to verify that
1029 the package works correctly despite the apparent partial installation.
1031 @node Cross-Compilation
1032 @subsection Cross-Compilation
1033 @cindex cross-compilation
1035 To @dfn{cross-compile} is to build on one platform a binary that will
1036 run on another platform. When speaking of cross-compilation, it is
1037 important to distinguish between the @dfn{build platform} on which
1038 the compilation is performed, and the @dfn{host platform} on which the
1039 resulting executable is expected to run. The following
1040 @command{configure} options are used to specify each of them:
1043 @item --build=@var{build}
1044 @opindex --build=@var{build}
1045 The system on which the package is built.
1046 @item --host=@var{host}
1047 @opindex --host=@var{host}
1048 The system where built programs and libraries will run.
1051 When the @option{--host} is used, @command{configure} will search for
1052 the cross-compiling suite for this platform. Cross-compilation tools
1053 commonly have their target architecture as prefix of their name. For
1054 instance my cross-compiler for MinGW32 has its binaries called
1055 @code{i586-mingw32msvc-gcc}, @code{i586-mingw32msvc-ld},
1056 @code{i586-mingw32msvc-as}, etc.
1058 @cindex MinGW cross-compilation example
1059 @cindex cross-compilation example
1061 Here is how we could build @code{amhello-1.0} for
1062 @code{i586-mingw32msvc} on a GNU/Linux PC.
1064 @c Keep in sync with amhello-cross-compile.sh
1066 ~/amhello-1.0 % @kbd{./configure --build i686-pc-linux-gnu --host i586-mingw32msvc}
1067 checking for a BSD-compatible install... /usr/bin/install -c
1068 checking whether build environment is sane... yes
1069 checking for gawk... gawk
1070 checking whether make sets $(MAKE)... yes
1071 checking for i586-mingw32msvc-strip... i586-mingw32msvc-strip
1072 checking for i586-mingw32msvc-gcc... i586-mingw32msvc-gcc
1073 checking for C compiler default output file name... a.exe
1074 checking whether the C compiler works... yes
1075 checking whether we are cross compiling... yes
1076 checking for suffix of executables... .exe
1077 checking for suffix of object files... o
1078 checking whether we are using the GNU C compiler... yes
1079 checking whether i586-mingw32msvc-gcc accepts -g... yes
1080 checking for i586-mingw32msvc-gcc option to accept ANSI C...
1082 ~/amhello-1.0 % @kbd{make}
1084 ~/amhello-1.0 % @kbd{cd src; file hello.exe}
1085 hello.exe: MS Windows PE 32-bit Intel 80386 console executable not relocatable
1088 The @option{--host} and @option{--build} options are usually all we
1089 need for cross-compiling. The only exception is if the package being
1090 built is itself a cross-compiler: we need a third option to specify
1091 its target architecture.
1094 @item --target=@var{target}
1095 @opindex --target=@var{target}
1096 When building compiler tools: the system for which the tools will
1100 For instance when installing GCC, the GNU Compiler Collection, we can
1101 use @option{--target=@/@var{target}} to specify that we want to build
1102 GCC as a cross-compiler for @var{target}. Mixing @option{--build} and
1103 @option{--target}, we can actually cross-compile a cross-compiler;
1104 such a three-way cross-compilation is known as a @dfn{Canadian cross}.
1106 @xref{Specifying Names, , Specifying the System Type, autoconf, The
1107 Autoconf Manual}, for more information about these @command{configure}
1111 @subsection Renaming Programs at Install Time
1112 @cindex Renaming programs
1113 @cindex Transforming program names
1114 @cindex Programs, renaming during installation
1116 The GNU Build System provides means to automatically rename
1117 executables and manpages before they are installed (@pxref{Man Pages}).
1118 This is especially convenient
1119 when installing a GNU package on a system that already has a
1120 proprietary implementation you do not want to overwrite. For instance,
1121 you may want to install GNU @command{tar} as @command{gtar} so you can
1122 distinguish it from your vendor's @command{tar}.
1124 This can be done using one of these three @command{configure} options.
1127 @item --program-prefix=@var{prefix}
1128 @opindex --program-prefix=@var{prefix}
1129 Prepend @var{prefix} to installed program names.
1130 @item --program-suffix=@var{suffix}
1131 @opindex --program-suffix=@var{suffix}
1132 Append @var{suffix} to installed program names.
1133 @item --program-transform-name=@var{program}
1134 @opindex --program-transform-name=@var{program}
1135 Run @code{sed @var{program}} on installed program names.
1138 The following commands would install @file{hello}
1139 as @file{/usr/local/bin/test-hello}, for instance.
1142 ~/amhello-1.0 % @kbd{./configure --program-prefix test-}
1144 ~/amhello-1.0 % @kbd{make}
1146 ~/amhello-1.0 % @kbd{sudo make install}
1151 @subsection Building Binary Packages Using DESTDIR
1154 The GNU Build System's @code{make install} and @code{make uninstall}
1155 interface does not exactly fit the needs of a system administrator
1156 who has to deploy and upgrade packages on lots of hosts. In other
1157 words, the GNU Build System does not replace a package manager.
1159 Such package managers usually need to know which files have been
1160 installed by a package, so a mere @code{make install} is
1163 @cindex Staged installation
1165 The @code{DESTDIR} variable can be used to perform a staged
1166 installation. The package should be configured as if it was going to
1167 be installed in its final location (e.g., @code{--prefix /usr}), but
1168 when running @code{make install}, the @code{DESTDIR} should be set to
1169 the absolute name of a directory into which the installation will be
1170 diverted. From this directory it is easy to review which files are
1171 being installed where, and finally copy them to their final location
1174 @cindex Binary package
1176 For instance here is how we could create a binary package containing a
1177 snapshot of all the files to be installed.
1179 @c Keep in sync with amhello-binpkg.sh
1181 ~/amhello-1.0 % @kbd{./configure --prefix /usr}
1183 ~/amhello-1.0 % @kbd{make}
1185 ~/amhello-1.0 % @kbd{make DESTDIR=$HOME/inst install}
1187 ~/amhello-1.0 % @kbd{cd ~/inst}
1188 ~/inst % @kbd{find . -type f -print > ../files.lst}
1189 ~/inst % @kbd{tar zcvf ~/amhello-1.0-i686.tar.gz `cat ../files.lst`}
1191 ./usr/share/doc/amhello/README
1194 After this example, @code{amhello-1.0-i686.tar.gz} is ready to be
1195 uncompressed in @file{/} on many hosts. (Using @code{`cat ../files.lst`}
1196 instead of @samp{.} as argument for @command{tar} avoids entries for
1197 each subdirectory in the archive: we would not like @command{tar} to
1198 restore the modification time of @file{/}, @file{/usr/}, etc.)
1200 Note that when building packages for several architectures, it might
1201 be convenient to use @code{make install-data} and @code{make
1202 install-exec} (@pxref{Two-Part Install}) to gather
1203 architecture-independent files in a single package.
1205 @xref{Install}, for more information.
1207 @c We should document PRE_INSTALL/POST_INSTALL/NORMAL_INSTALL and their
1208 @c UNINSTALL counterparts.
1210 @node Preparing Distributions
1211 @subsection Preparing Distributions
1212 @cindex Preparing distributions
1213 @cindex Packages, preparation
1214 @cindex Distributions, preparation
1216 We have already mentioned @code{make dist}. This target collects all
1217 your source files and the necessary parts of the build system to
1218 create a tarball named @file{@var{package}-@var{version}.tar.gz}.
1220 @cindex @code{distcheck} better than @code{dist}
1222 Another, more useful command is @code{make distcheck}. The
1223 @code{distcheck} target constructs
1224 @file{@var{package}-@var{version}.tar.gz} just as well as @code{dist},
1225 but it additionally ensures most of the use cases presented so far
1230 It attempts a full compilation of the package (@pxref{Basic
1231 Installation}), unpacking the newly constructed tarball, running
1232 @code{make}, @code{make check}, @code{make install}, as well as
1233 @code{make installcheck}, and even @code{make dist},
1235 it tests VPATH builds with read-only source tree (@pxref{VPATH Builds}),
1237 it makes sure @code{make clean}, @code{make distclean}, and @code{make
1238 uninstall} do not omit any file (@pxref{Standard Targets}),
1240 and it checks that @code{DESTDIR} installations work (@pxref{DESTDIR}).
1243 All of these actions are performed in a temporary subdirectory, so
1244 that no root privileges are required.
1246 Releasing a package that fails @code{make distcheck} means that one of
1247 the scenarios we presented will not work and some users will be
1248 disappointed. Therefore it is a good practice to release a package
1249 only after a successful @code{make distcheck}. This of course does
1250 not imply that the package will be flawless, but at least it will
1251 prevent some of the embarrassing errors you may find in packages
1252 released by people who have never heard about @code{distcheck} (like
1253 @code{DESTDIR} not working because of a typo, or a distributed file
1254 being erased by @code{make clean}, or even @code{VPATH} builds not
1257 @xref{Creating amhello}, to recreate @file{amhello-1.0.tar.gz} using
1258 @code{make distcheck}. @xref{Checking the Distribution}, for more
1259 information about @code{distcheck}.
1261 @node Dependency Tracking
1262 @subsection Automatic Dependency Tracking
1263 @cindex Dependency tracking
1265 Dependency tracking is performed as a side-effect of compilation.
1266 Each time the build system compiles a source file, it computes its
1267 list of dependencies (in C these are the header files included by the
1268 source being compiled). Later, any time @command{make} is run and a
1269 dependency appears to have changed, the dependent files will be
1272 Automake generates code for automatic dependency tracking by default,
1273 unless the developer chooses to override it; for more information,
1274 @pxref{Dependencies}.
1276 When @command{configure} is executed, you can see it probing each
1277 compiler for the dependency mechanism it supports (several mechanisms
1281 ~/amhello-1.0 % @kbd{./configure --prefix /usr}
1283 checking dependency style of gcc... gcc3
1287 Because dependencies are only computed as a side-effect of the
1288 compilation, no dependency information exists the first time a package
1289 is built. This is OK because all the files need to be built anyway:
1290 @code{make} does not have to decide which files need to be rebuilt.
1291 In fact, dependency tracking is completely useless for one-time builds
1292 and there is a @command{configure} option to disable this:
1295 @item --disable-dependency-tracking
1296 @opindex --disable-dependency-tracking
1297 Speed up one-time builds.
1300 Some compilers do not offer any practical way to derive the list of
1301 dependencies as a side-effect of the compilation, requiring a separate
1302 run (maybe of another tool) to compute these dependencies. The
1303 performance penalty implied by these methods is important enough to
1304 disable them by default. The option @option{--enable-dependency-tracking}
1305 must be passed to @command{configure} to activate them.
1308 @item --enable-dependency-tracking
1309 @opindex --enable-dependency-tracking
1310 Do not reject slow dependency extractors.
1313 @xref{Dependency Tracking Evolution, , Dependency Tracking Evolution,
1314 automake-history, Brief History of Automake}, for some discussion about
1315 the different dependency tracking schemes used by Automake over the years.
1317 @node Nested Packages
1318 @subsection Nested Packages
1319 @cindex Nested packages
1320 @cindex Packages, nested
1323 Although nesting packages isn't something we would recommend to
1324 someone who is discovering the Autotools, it is a nice feature worthy
1325 of mention in this small advertising tour.
1327 Autoconfiscated packages (that means packages whose build system have
1328 been created by Autoconf and friends) can be nested to arbitrary
1331 A typical setup is that package A will distribute one of the libraries
1332 it needs in a subdirectory. This library B is a complete package with
1333 its own GNU Build System. The @command{configure} script of A will
1334 run the @command{configure} script of B as part of its execution,
1335 building and installing A will also build and install B. Generating a
1336 distribution for A will also include B.
1338 It is possible to gather several packages like this. GCC is a heavy
1339 user of this feature. This gives installers a single package to
1340 configure, build and install, while it allows developers to work on
1341 subpackages independently.
1343 When configuring nested packages, the @command{configure} options
1344 given to the top-level @command{configure} are passed recursively to
1345 nested @command{configure}s. A package that does not understand an
1346 option will ignore it, assuming it is meaningful to some other
1349 @opindex --help=recursive
1351 The command @code{configure --help=recursive} can be used to display
1352 the options supported by all the included packages.
1354 @xref{Subpackages}, for an example setup.
1357 @section How Autotools Help
1358 @cindex Autotools, purpose
1360 There are several reasons why you may not want to implement the GNU
1361 Build System yourself (read: write a @file{configure} script and
1362 @file{Makefile}s yourself).
1366 As we have seen, the GNU Build System has a lot of
1367 features (@pxref{Use Cases}).
1368 Some users may expect features you have not implemented because
1369 you did not need them.
1371 Implementing these features portably is difficult and exhausting.
1372 Think of writing portable shell scripts, and portable
1373 @file{Makefile}s, for systems you may not have handy. @xref{Portable
1374 Shell, , Portable Shell Programming, autoconf, The Autoconf Manual}, to
1377 You will have to upgrade your setup to follow changes to the GNU
1381 The GNU Autotools take all this burden off your back and provide:
1385 Tools to create a portable, complete, and self-contained GNU Build
1386 System, from simple instructions.
1387 @emph{Self-contained} meaning the resulting build system does not
1388 require the GNU Autotools.
1390 A central place where fixes and improvements are made:
1391 a bug-fix for a portability issue will benefit every package.
1394 Yet there also exist reasons why you may want NOT to use the
1395 Autotools@enddots{} For instance you may be already using (or used to)
1396 another incompatible build system. Autotools will only be useful if
1397 you do accept the concepts of the GNU Build System. People who have their
1398 own idea of how a build system should work will feel frustrated by the
1402 @section A Small Hello World
1403 @cindex Example Hello World
1404 @cindex Hello World example
1405 @cindex @file{amhello-1.0.tar.gz}, creation
1407 In this section we recreate the @file{amhello-1.0} package from
1408 scratch. The first subsection shows how to call the Autotools to
1409 instantiate the GNU Build System, while the second explains the
1410 meaning of the @file{configure.ac} and @file{Makefile.am} files read
1413 @anchor{amhello Explained}
1415 * Creating amhello:: Create @file{amhello-1.0.tar.gz} from scratch
1416 * amhello's configure.ac Setup Explained::
1417 * amhello's Makefile.am Setup Explained::
1420 @node Creating amhello
1421 @subsection Creating @file{amhello-1.0.tar.gz}
1423 Here is how we can recreate @file{amhello-1.0.tar.gz} from scratch.
1424 The package is simple enough so that we will only need to write 5
1425 files. (You may copy them from the final @file{amhello-1.0.tar.gz}
1426 that is distributed with Automake if you do not want to write them.)
1428 Create the following files in an empty directory.
1433 @file{src/main.c} is the source file for the @file{hello} program. We
1434 store it in the @file{src/} subdirectory, because later, when the package
1435 evolves, it will ease the addition of a @file{man/} directory for man
1436 pages, a @file{data/} directory for data files, etc.
1438 ~/amhello % @kbd{cat src/main.c}
1445 puts ("Hello World!");
1446 puts ("This is " PACKAGE_STRING ".");
1452 @file{README} contains some very limited documentation for our little
1455 ~/amhello % @kbd{cat README}
1456 This is a demonstration package for GNU Automake.
1457 Type 'info Automake' to read the Automake manual.
1461 @file{Makefile.am} and @file{src/Makefile.am} contain Automake
1462 instructions for these two directories.
1465 ~/amhello % @kbd{cat src/Makefile.am}
1466 bin_PROGRAMS = hello
1467 hello_SOURCES = main.c
1468 ~/amhello % @kbd{cat Makefile.am}
1470 dist_doc_DATA = README
1474 Finally, @file{configure.ac} contains Autoconf instructions to
1475 create the @command{configure} script.
1478 ~/amhello % @kbd{cat configure.ac}
1479 AC_INIT([amhello], [1.0], [@value{PACKAGE_BUGREPORT}])
1480 AM_INIT_AUTOMAKE([-Wall -Werror foreign])
1482 AC_CONFIG_HEADERS([config.h])
1491 @cindex @command{autoreconf}, example
1493 Once you have these five files, it is time to run the Autotools to
1494 instantiate the build system. Do this using the @command{autoreconf}
1498 ~/amhello % @kbd{autoreconf --install}
1499 configure.ac: installing './install-sh'
1500 configure.ac: installing './missing'
1501 configure.ac: installing './compile'
1502 src/Makefile.am: installing './depcomp'
1505 At this point the build system is complete.
1507 In addition to the three scripts mentioned in its output, you can see
1508 that @command{autoreconf} created four other files: @file{configure},
1509 @file{config.h.in}, @file{Makefile.in}, and @file{src/Makefile.in}.
1510 The latter three files are templates that will be adapted to the
1511 system by @command{configure} under the names @file{config.h},
1512 @file{Makefile}, and @file{src/Makefile}. Let's do this:
1515 ~/amhello % @kbd{./configure}
1516 checking for a BSD-compatible install... /usr/bin/install -c
1517 checking whether build environment is sane... yes
1518 checking for gawk... no
1519 checking for mawk... mawk
1520 checking whether make sets $(MAKE)... yes
1521 checking for gcc... gcc
1522 checking for C compiler default output file name... a.out
1523 checking whether the C compiler works... yes
1524 checking whether we are cross compiling... no
1525 checking for suffix of executables...
1526 checking for suffix of object files... o
1527 checking whether we are using the GNU C compiler... yes
1528 checking whether gcc accepts -g... yes
1529 checking for gcc option to accept ISO C89... none needed
1530 checking for style of include used by make... GNU
1531 checking dependency style of gcc... gcc3
1532 configure: creating ./config.status
1533 config.status: creating Makefile
1534 config.status: creating src/Makefile
1535 config.status: creating config.h
1536 config.status: executing depfiles commands
1540 @cindex @code{distcheck} example
1542 You can see @file{Makefile}, @file{src/Makefile}, and @file{config.h}
1543 being created at the end after @command{configure} has probed the
1544 system. It is now possible to run all the targets we wish
1545 (@pxref{Standard Targets}). For instance:
1548 ~/amhello % @kbd{make}
1550 ~/amhello % @kbd{src/hello}
1552 This is amhello 1.0.
1553 ~/amhello % @kbd{make distcheck}
1555 =============================================
1556 amhello-1.0 archives ready for distribution:
1558 =============================================
1561 Note that running @command{autoreconf} is only needed initially when
1562 the GNU Build System does not exist. When you later change some
1563 instructions in a @file{Makefile.am} or @file{configure.ac}, the
1564 relevant part of the build system will be regenerated automatically
1565 when you execute @command{make}.
1567 @command{autoreconf} is a script that calls @command{autoconf},
1568 @command{automake}, and a bunch of other commands in the right order.
1569 If you are beginning with these tools, it is not important to figure
1570 out in which order all of these tools should be invoked and why. However,
1571 because Autoconf and Automake have separate manuals, the important
1572 point to understand is that @command{autoconf} is in charge of
1573 creating @file{configure} from @file{configure.ac}, while
1574 @command{automake} is in charge of creating @file{Makefile.in}s from
1575 @file{Makefile.am}s and @file{configure.ac}. This should at least
1576 direct you to the right manual when seeking answers.
1579 @node amhello's configure.ac Setup Explained
1580 @subsection @code{amhello}'s @file{configure.ac} Setup Explained
1582 @cindex @file{configure.ac}, Hello World
1584 Let us begin with the contents of @file{configure.ac}.
1587 AC_INIT([amhello], [1.0], [@value{PACKAGE_BUGREPORT}])
1588 AM_INIT_AUTOMAKE([-Wall -Werror foreign])
1590 AC_CONFIG_HEADERS([config.h])
1598 This file is read by both @command{autoconf} (to create
1599 @file{configure}) and @command{automake} (to create the various
1600 @file{Makefile.in}s). It contains a series of M4 macros that will be
1601 expanded as shell code to finally form the @file{configure} script.
1602 We will not elaborate on the syntax of this file, because the Autoconf
1603 manual has a whole section about it (@pxref{Writing Autoconf Input, ,
1604 Writing @file{configure.ac}, autoconf, The Autoconf Manual}).
1606 The macros prefixed with @code{AC_} are Autoconf macros, documented
1607 in the Autoconf manual (@pxref{Autoconf Macro Index, , Autoconf Macro
1608 Index, autoconf, The Autoconf Manual}). The macros that start with
1609 @code{AM_} are Automake macros, documented later in this manual
1610 (@pxref{Macro Index}).
1612 The first two lines of @file{configure.ac} initialize Autoconf and
1613 Automake. @code{AC_INIT} takes in as parameters the name of the package,
1614 its version number, and a contact address for bug-reports about the
1615 package (this address is output at the end of @code{./configure
1616 --help}, for instance). When adapting this setup to your own package,
1617 by all means please do not blindly copy Automake's address: use the
1618 mailing list of your package, or your own mail address.
1624 The argument to @code{AM_INIT_AUTOMAKE} is a list of options for
1625 @command{automake} (@pxref{Options}). @option{-Wall} and
1626 @option{-Werror} ask @command{automake} to turn on all warnings and
1627 report them as errors. We are speaking of @strong{Automake} warnings
1628 here, such as dubious instructions in @file{Makefile.am}. This has
1629 absolutely nothing to do with how the compiler will be called, even
1630 though it may support options with similar names. Using @option{-Wall
1631 -Werror} is a safe setting when starting to work on a package: you do
1632 not want to miss any issues. Later you may decide to relax things a
1633 bit. The @option{foreign} option tells Automake that this package
1634 will not follow the GNU Standards. GNU packages should always
1635 distribute additional files such as @file{ChangeLog}, @file{AUTHORS},
1636 etc. We do not want @command{automake} to complain about these
1637 missing files in our small example.
1639 The @code{AC_PROG_CC} line causes the @command{configure} script to
1640 search for a C compiler and define the variable @code{CC} with its
1641 name. The @file{src/Makefile.in} file generated by Automake uses the
1642 variable @code{CC} to build @file{hello}, so when @command{configure}
1643 creates @file{src/Makefile} from @file{src/Makefile.in}, it will define
1644 @code{CC} with the value it has found. If Automake is asked to create
1645 a @file{Makefile.in} that uses @code{CC} but @file{configure.ac} does
1646 not define it, it will suggest you add a call to @code{AC_PROG_CC}.
1648 The @code{AC_CONFIG_HEADERS([config.h])} invocation causes the
1649 @command{configure} script to create a @file{config.h} file gathering
1650 @samp{#define}s defined by other macros in @file{configure.ac}. In our
1651 case, the @code{AC_INIT} macro already defined a few of them. Here
1652 is an excerpt of @file{config.h} after @command{configure} has run:
1656 /* Define to the address where bug reports for this package should be sent. */
1657 #define PACKAGE_BUGREPORT "@value{PACKAGE_BUGREPORT}"
1659 /* Define to the full name and version of this package. */
1660 #define PACKAGE_STRING "amhello 1.0"
1664 As you probably noticed, @file{src/main.c} includes @file{config.h} so
1665 it can use @code{PACKAGE_STRING}. In a real-world project,
1666 @file{config.h} can grow really big, with one @samp{#define} per
1667 feature probed on the system.
1669 The @code{AC_CONFIG_FILES} macro declares the list of files that
1670 @command{configure} should create from their @file{*.in} templates.
1671 Automake also scans this list to find the @file{Makefile.am} files it must
1672 process. (This is important to remember: when adding a new directory
1673 to your project, you should add its @file{Makefile} to this list,
1674 otherwise Automake will never process the new @file{Makefile.am} you
1675 wrote in that directory.)
1677 Finally, the @code{AC_OUTPUT} line is a closing command that actually
1678 produces the part of the script in charge of creating the files
1679 registered with @code{AC_CONFIG_HEADERS} and @code{AC_CONFIG_FILES}.
1681 @cindex @command{autoscan}
1683 When starting a new project, we suggest you start with such a simple
1684 @file{configure.ac}, and gradually add the other tests it requires.
1685 The command @command{autoscan} can also suggest a few of the tests
1686 your package may need (@pxref{autoscan Invocation, , Using
1687 @command{autoscan} to Create @file{configure.ac}, autoconf, The
1691 @node amhello's Makefile.am Setup Explained
1692 @subsection @code{amhello}'s @file{Makefile.am} Setup Explained
1694 @cindex @file{Makefile.am}, Hello World
1696 We now turn to @file{src/Makefile.am}. This file contains
1697 Automake instructions to build and install @file{hello}.
1700 bin_PROGRAMS = hello
1701 hello_SOURCES = main.c
1704 A @file{Makefile.am} has the same syntax as an ordinary
1705 @file{Makefile}. When @command{automake} processes a
1706 @file{Makefile.am} it copies the entire file into the output
1707 @file{Makefile.in} (that will be later turned into @file{Makefile} by
1708 @command{configure}) but will react to certain variable definitions
1709 by generating some build rules and other variables.
1710 Often @file{Makefile.am}s contain only a list of variable definitions as
1711 above, but they can also contain other variable and rule definitions that
1712 @command{automake} will pass along without interpretation.
1714 Variables that end with @code{_PROGRAMS} are special variables
1715 that list programs that the resulting @file{Makefile} should build.
1716 In Automake speak, this @code{_PROGRAMS} suffix is called a
1717 @dfn{primary}; Automake recognizes other primaries such as
1718 @code{_SCRIPTS}, @code{_DATA}, @code{_LIBRARIES}, etc.@: corresponding
1719 to different types of files.
1721 The @samp{bin} part of the @code{bin_PROGRAMS} tells
1722 @command{automake} that the resulting programs should be installed in
1723 @var{bindir}. Recall that the GNU Build System uses a set of variables
1724 to denote destination directories and allow users to customize these
1725 locations (@pxref{Standard Directory Variables}). Any such directory
1726 variable can be put in front of a primary (omitting the @code{dir}
1727 suffix) to tell @command{automake} where to install the listed files.
1729 Programs need to be built from source files, so for each program
1730 @code{@var{prog}} listed in a @code{@w{_PROGRAMS}} variable,
1731 @command{automake} will look for another variable named
1732 @code{@var{prog}_SOURCES} listing its source files. There may be more
1733 than one source file: they will all be compiled and linked together.
1735 Automake also knows that source files need to be distributed when
1736 creating a tarball (unlike built programs). So a side-effect of this
1737 @code{hello_SOURCES} declaration is that @file{main.c} will be
1738 part of the tarball created by @code{make dist}.
1740 Finally here are some explanations regarding the top-level
1745 dist_doc_DATA = README
1748 @code{SUBDIRS} is a special variable listing all directories that
1749 @command{make} should recurse into before processing the current
1750 directory. So this line is responsible for @command{make} building
1751 @file{src/hello} even though we run it from the top-level. This line
1752 also causes @code{make install} to install @file{src/hello} before
1753 installing @file{README} (not that this order matters).
1755 The line @code{dist_doc_DATA = README} causes @file{README} to be
1756 distributed and installed in @var{docdir}. Files listed with the
1757 @code{_DATA} primary are not automatically part of the tarball built
1758 with @code{make dist}, so we add the @code{dist_} prefix so they get
1759 distributed. However, for @file{README} it would not have been
1760 necessary: @command{automake} automatically distributes any
1761 @file{README} file it encounters (the list of other files
1762 automatically distributed is presented by @code{automake --help}).
1763 The only important effect of this second line is therefore to install
1764 @file{README} during @code{make install}.
1766 One thing not covered in this example is accessing the installation
1767 directory values (@pxref{Standard Directory Variables}) from your
1768 program code, that is, converting them into defined macros. For this,
1769 @pxref{Defining Directories,,, autoconf, The Autoconf Manual}.
1773 @chapter General ideas
1775 The following sections cover a few basic ideas that will help you
1776 understand how Automake works.
1779 * General Operation:: General operation of Automake
1780 * Strictness:: Standards conformance checking
1781 * Uniform:: The Uniform Naming Scheme
1782 * Length Limitations:: Staying below the command line length limit
1783 * Canonicalization:: How derived variables are named
1784 * User Variables:: Variables reserved for the user
1785 * Auxiliary Programs:: Programs automake might require
1789 @node General Operation
1790 @section General Operation
1792 Automake works by reading a @file{Makefile.am} and generating a
1793 @file{Makefile.in}. Certain variables and rules defined in the
1794 @file{Makefile.am} instruct Automake to generate more specialized code;
1795 for instance, a @code{bin_PROGRAMS} variable definition will cause rules
1796 for compiling and linking programs to be generated.
1798 @cindex Non-standard targets
1799 @cindex @code{git-dist}, non-standard example
1802 The variable definitions and rules in the @file{Makefile.am} are
1803 copied mostly verbatim into the generated file, with all variable
1804 definitions preceding all rules. This allows you to add almost
1805 arbitrary code into the generated @file{Makefile.in}. For instance,
1806 the Automake distribution includes a non-standard rule for the
1807 @code{git-dist} target, which the Automake maintainer uses to make
1808 distributions from the source control system.
1810 @cindex GNU make extensions
1812 Note that most GNU make extensions are not recognized by Automake. Using
1813 such extensions in a @file{Makefile.am} will lead to errors or confusing
1816 @cindex Append operator
1818 A special exception is that the GNU make append operator, @samp{+=}, is
1819 supported. This operator appends its right hand argument to the variable
1820 specified on the left. Automake will translate the operator into
1821 an ordinary @samp{=} operator; @samp{+=} will thus work with any make program.
1823 Automake tries to keep comments grouped with any adjoining rules or
1824 variable definitions.
1826 @cindex Limitations of automake parser
1827 @cindex Automake parser, limitations of
1828 @cindex indentation in Makefile.am
1829 Generally, Automake is not particularly smart in the parsing of unusual
1830 Makefile constructs, so you're advised to avoid fancy constructs or
1831 ``creative'' use of whitespaces.
1832 @c Keep this in sync with doc-parsing-buglets-tabs.sh
1833 For example, @key{TAB} characters cannot be used between a target name
1834 and the following ``@code{:}'' character, and variable assignments
1835 shouldn't be indented with @key{TAB} characters.
1836 @c Keep this in sync with doc-parsing-buglets-colneq-subst.sh
1837 Also, using more complex macro in target names can cause trouble:
1840 % @kbd{cat Makefile.am}
1843 Makefile.am:1: bad characters in variable name '$(FOO'
1844 Makefile.am:1: ':='-style assignments are not portable
1847 @cindex Make targets, overriding
1848 @cindex Make rules, overriding
1849 @cindex Overriding make rules
1850 @cindex Overriding make targets
1852 A rule defined in @file{Makefile.am} generally overrides any such
1853 rule of a similar name that would be automatically generated by
1854 @command{automake}. Although this is a supported feature, it is generally
1855 best to avoid making use of it, as sometimes the generated rules are
1858 @cindex Variables, overriding
1859 @cindex Overriding make variables
1861 Similarly, a variable defined in @file{Makefile.am} or
1862 @code{AC_SUBST}ed from @file{configure.ac} will override any
1863 definition of the variable that @command{automake} would ordinarily
1864 create. This feature is more often useful than the ability to
1865 override a rule. Be warned that many of the variables generated by
1866 @command{automake} are considered to be for internal use only, and their
1867 names might change in future releases.
1869 @cindex Recursive operation of Automake
1870 @cindex Automake, recursive operation
1871 @cindex Example of recursive operation
1873 When examining a variable definition, Automake will recursively examine
1874 variables referenced in the definition. For example, if Automake is
1875 looking at the content of @code{foo_SOURCES} in this snippet
1877 @c Keep in sync with interp.sh
1880 foo_SOURCES = c.c $(xs)
1883 it would use the files @file{a.c}, @file{b.c}, and @file{c.c} as the
1884 contents of @code{foo_SOURCES}.
1886 @cindex @code{##} (special Automake comment)
1887 @cindex Special Automake comment
1888 @cindex Comment, special to Automake
1890 Automake also allows a form of comment that is @emph{not} copied into
1891 the output; all lines beginning with @samp{##} (leading spaces allowed)
1892 are completely ignored by Automake.
1894 It is customary to make the first line of @file{Makefile.am} read:
1896 @cindex Makefile.am, first line
1897 @cindex First line of Makefile.am
1900 ## Process this file with automake to produce Makefile.in
1903 @c FIXME discuss putting a copyright into Makefile.am here? I would but
1904 @c I don't know quite what to say.
1906 @c FIXME document customary ordering of Makefile.am here!
1912 @cindex Non-GNU packages
1914 While Automake is intended to be used by maintainers of GNU packages, it
1915 does make some effort to accommodate those who wish to use it, but do
1916 not want to use all the GNU conventions.
1918 @cindex Strictness, defined
1919 @cindex Strictness, @option{foreign}
1920 @cindex @option{foreign} strictness
1921 @cindex Strictness, @option{gnu}
1922 @cindex @option{gnu} strictness
1923 @cindex Strictness, @option{gnits}
1924 @cindex @option{gnits} strictness
1926 To this end, Automake supports three levels of @dfn{strictness}---the
1927 strictness indicating how stringently Automake should check standards
1930 The valid strictness levels are:
1934 Automake will check for only those things that are absolutely
1935 required for proper operations. For instance, whereas GNU standards
1936 dictate the existence of a @file{NEWS} file, it will not be required in
1937 this mode. This strictness will also turn off some warnings by default
1938 (among them, portability warnings).
1939 The name comes from the fact that Automake is intended to be
1940 used for GNU programs; these relaxed rules are not the standard mode of
1944 Automake will check---as much as possible---for compliance to the GNU
1945 standards for packages. This is the default.
1948 Automake will check for compliance to the as-yet-unwritten @dfn{Gnits
1949 standards}. These are based on the GNU standards, but are even more
1950 detailed. Unless you are a Gnits standards contributor, it is
1951 recommended that you avoid this option until such time as the Gnits
1952 standard is actually published (which may never happen).
1955 @xref{Gnits}, for more information on the precise implications of the
1960 @section The Uniform Naming Scheme
1962 @cindex Uniform naming scheme
1964 Automake variables generally follow a @dfn{uniform naming scheme} that
1965 makes it easy to decide how programs (and other derived objects) are
1966 built, and how they are installed. This scheme also supports
1967 @command{configure} time determination of what should be built.
1969 @cindex @code{_PROGRAMS} primary variable
1970 @cindex @code{PROGRAMS} primary variable
1971 @cindex Primary variable, @code{PROGRAMS}
1972 @cindex Primary variable, defined
1975 At @command{make} time, certain variables are used to determine which
1976 objects are to be built. The variable names are made of several pieces
1977 that are concatenated together.
1979 The piece that tells @command{automake} what is being built is commonly called
1980 the @dfn{primary}. For instance, the primary @code{PROGRAMS} holds a
1981 list of programs that are to be compiled and linked.
1984 @cindex @code{pkgdatadir}, defined
1985 @cindex @code{pkgincludedir}, defined
1986 @cindex @code{pkglibdir}, defined
1987 @cindex @code{pkglibexecdir}, defined
1990 @vindex pkgincludedir
1992 @vindex pkglibexecdir
1994 @cindex @code{PACKAGE}, directory
1995 A different set of names is used to decide where the built objects
1996 should be installed. These names are prefixes to the primary, and they
1997 indicate which standard directory should be used as the installation
1998 directory. The standard directory names are given in the GNU standards
1999 (@pxref{Directory Variables, , , standards, The GNU Coding Standards}).
2000 Automake extends this list with @code{pkgdatadir}, @code{pkgincludedir},
2001 @code{pkglibdir}, and @code{pkglibexecdir}; these are the same as the
2002 non-@samp{pkg} versions, but with @samp{$(PACKAGE)} appended. For instance,
2003 @code{pkglibdir} is defined as @samp{$(libdir)/$(PACKAGE)}.
2005 @cindex @code{EXTRA_}, prepending
2006 For each primary, there is one additional variable named by prepending
2007 @samp{EXTRA_} to the primary name. This variable is used to list
2008 objects that may or may not be built, depending on what
2009 @command{configure} decides. This variable is required because Automake
2010 must statically know the entire list of objects that may be built in
2011 order to generate a @file{Makefile.in} that will work in all cases.
2013 @cindex @code{EXTRA_PROGRAMS}, defined
2014 @cindex Example, @code{EXTRA_PROGRAMS}
2015 @cindex @command{cpio} example
2017 For instance, @command{cpio} decides at configure time which programs
2018 should be built. Some of the programs are installed in @code{bindir},
2019 and some are installed in @code{sbindir}:
2022 EXTRA_PROGRAMS = mt rmt
2023 bin_PROGRAMS = cpio pax
2024 sbin_PROGRAMS = $(MORE_PROGRAMS)
2027 Defining a primary without a prefix as a variable, e.g.,
2028 @samp{PROGRAMS}, is an error.
2030 Note that the common @samp{dir} suffix is left off when constructing the
2031 variable names; thus one writes @samp{bin_PROGRAMS} and not
2032 @samp{bindir_PROGRAMS}.
2034 Not every sort of object can be installed in every directory. Automake
2035 will flag those attempts it finds in error (but see below how to override
2036 the check if you really need to).
2037 Automake will also diagnose obvious misspellings in directory names.
2039 @cindex Extending list of installation directories
2040 @cindex Installation directories, extending list
2042 Sometimes the standard directories---even as augmented by
2043 Automake---are not enough. In particular it is sometimes useful, for
2044 clarity, to install objects in a subdirectory of some predefined
2045 directory. To this end, Automake allows you to extend the list of
2046 possible installation directories. A given prefix (e.g., @samp{zar})
2047 is valid if a variable of the same name with @samp{dir} appended is
2048 defined (e.g., @samp{zardir}).
2050 For instance, the following snippet will install @file{file.xml} into
2051 @samp{$(datadir)/xml}.
2053 @c Keep in sync with primary-prefix-couples-documented-valid.sh
2055 xmldir = $(datadir)/xml
2059 This feature can also be used to override the sanity checks Automake
2060 performs to diagnose suspicious directory/primary couples (in the
2061 unlikely case these checks are undesirable, and you really know what
2062 you're doing). For example, Automake would error out on this input:
2064 @c Should be tested in primary-prefix-invalid-couples.sh
2066 # Forbidden directory combinations, automake will error out on this.
2067 pkglib_PROGRAMS = foo
2068 doc_LIBRARIES = libquux.a
2072 but it will succeed with this:
2074 @c Keep in sync with primary-prefix-couples-documented-valid.sh
2076 # Work around forbidden directory combinations. Do not use this
2077 # without a very good reason!
2078 my_execbindir = $(pkglibdir)
2079 my_doclibdir = $(docdir)
2080 my_execbin_PROGRAMS = foo
2081 my_doclib_LIBRARIES = libquux.a
2084 The @samp{exec} substring of the @samp{my_execbindir} variable lets
2085 the files be installed at the right time (@pxref{The Two Parts of
2088 @cindex @samp{noinst_} primary prefix, definition
2091 The special prefix @samp{noinst_} indicates that the objects in question
2092 should be built but not installed at all. This is usually used for
2093 objects required to build the rest of your package, for instance static
2094 libraries (@pxref{A Library}), or helper scripts.
2096 @cindex @samp{check_} primary prefix, definition
2099 The special prefix @samp{check_} indicates that the objects in question
2100 should not be built until the @samp{make check} command is run. Those
2101 objects are not installed either.
2103 The current primary names are @samp{PROGRAMS}, @samp{LIBRARIES},
2104 @samp{LTLIBRARIES}, @samp{LISP}, @samp{PYTHON}, @samp{JAVA},
2105 @samp{SCRIPTS}, @samp{DATA}, @samp{HEADERS}, @samp{MANS}, and
2119 Some primaries also allow additional prefixes that control other
2120 aspects of @command{automake}'s behavior. The currently defined prefixes
2121 are @samp{dist_}, @samp{nodist_}, @samp{nobase_}, and @samp{notrans_}.
2122 These prefixes are explained later (@pxref{Program and Library Variables})
2123 (@pxref{Man Pages}).
2126 @node Length Limitations
2127 @section Staying below the command line length limit
2129 @cindex command line length limit
2132 Traditionally, most unix-like systems have a length limitation for the
2133 command line arguments and environment contents when creating new
2134 processes (see for example
2135 @uref{http://www.in-ulm.de/@/~mascheck/@/various/@/argmax/} for an
2136 overview on this issue),
2137 which of course also applies to commands spawned by @command{make}.
2138 POSIX requires this limit to be at least 4096 bytes, and most modern
2139 systems have quite high limits (or are unlimited).
2141 In order to create portable Makefiles that do not trip over these
2142 limits, it is necessary to keep the length of file lists bounded.
2143 Unfortunately, it is not possible to do so fully transparently within
2144 Automake, so your help may be needed. Typically, you can split long
2145 file lists manually and use different installation directory names for
2146 each list. For example,
2149 data_DATA = file1 @dots{} file@var{N} file@var{N+1} @dots{} file@var{2N}
2153 may also be written as
2155 @c Keep in sync with primary-prefix-couples-documented-valid.sh
2157 data_DATA = file1 @dots{} file@var{N}
2158 data2dir = $(datadir)
2159 data2_DATA = file@var{N+1} @dots{} file@var{2N}
2163 and will cause Automake to treat the two lists separately during
2164 @code{make install}. See @ref{The Two Parts of Install} for choosing
2165 directory names that will keep the ordering of the two parts of
2166 installation Note that @code{make dist} may still only work on a host
2167 with a higher length limit in this example.
2169 Automake itself employs a couple of strategies to avoid long command
2170 lines. For example, when @samp{$@{srcdir@}/} is prepended to file
2171 names, as can happen with above @code{$(data_DATA)} lists, it limits
2172 the amount of arguments passed to external commands.
2174 Unfortunately, some system's @command{make} commands may prepend
2175 @code{VPATH} prefixes like @samp{$@{srcdir@}/} to file names from the
2176 source tree automatically (@pxref{Automatic Rule Rewriting, , Automatic
2177 Rule Rewriting, autoconf, The Autoconf Manual}). In this case, the user
2178 may have to switch to use GNU Make, or refrain from using VPATH builds,
2179 in order to stay below the length limit.
2181 For libraries and programs built from many sources, convenience archives
2182 may be used as intermediates in order to limit the object list length
2183 (@pxref{Libtool Convenience Libraries}).
2186 @node Canonicalization
2187 @section How derived variables are named
2189 @cindex canonicalizing Automake variables
2191 Sometimes a Makefile variable name is derived from some text the
2192 maintainer supplies. For instance, a program name listed in
2193 @samp{_PROGRAMS} is rewritten into the name of a @samp{_SOURCES}
2194 variable. In cases like this, Automake canonicalizes the text, so that
2195 program names and the like do not have to follow Makefile variable naming
2196 rules. All characters in the name except for letters, numbers, the
2197 strudel (@@), and the underscore are turned into underscores when making
2198 variable references.
2200 For example, if your program is named @file{sniff-glue}, the derived
2201 variable name would be @samp{sniff_glue_SOURCES}, not
2202 @samp{sniff-glue_SOURCES}. Similarly the sources for a library named
2203 @file{libmumble++.a} should be listed in the
2204 @samp{libmumble___a_SOURCES} variable.
2206 The strudel is an addition, to make the use of Autoconf substitutions in
2207 variable names less obfuscating.
2210 @node User Variables
2211 @section Variables reserved for the user
2213 @cindex variables, reserved for the user
2214 @cindex user variables
2216 Some @file{Makefile} variables are reserved by the GNU Coding Standards
2217 for the use of the ``user''---the person building the package. For
2218 instance, @code{CFLAGS} is one such variable.
2220 Sometimes package developers are tempted to set user variables such as
2221 @code{CFLAGS} because it appears to make their job easier. However,
2222 the package itself should never set a user variable, particularly not
2223 to include switches that are required for proper compilation of the
2224 package. Since these variables are documented as being for the
2225 package builder, that person rightfully expects to be able to override
2226 any of these variables at build time.
2228 To get around this problem, Automake introduces an automake-specific
2229 shadow variable for each user flag variable. (Shadow variables are
2230 not introduced for variables like @code{CC}, where they would make no
2231 sense.) The shadow variable is named by prepending @samp{AM_} to the
2232 user variable's name. For instance, the shadow variable for
2233 @code{YFLAGS} is @code{AM_YFLAGS}. The package maintainer---that is,
2234 the author(s) of the @file{Makefile.am} and @file{configure.ac}
2235 files---may adjust these shadow variables however necessary.
2237 @xref{Flag Variables Ordering}, for more discussion about these
2238 variables and how they interact with per-target variables.
2240 @node Auxiliary Programs
2241 @section Programs automake might require
2243 @cindex Programs, auxiliary
2244 @cindex Auxiliary programs
2246 Automake sometimes requires helper programs so that the generated
2247 @file{Makefile} can do its work properly. There are a fairly large
2248 number of them, and we list them here.
2250 Although all of these files are distributed and installed with
2251 Automake, a couple of them are maintained separately. The Automake
2252 copies are updated before each release, but we mention the original
2253 source in case you need more recent versions.
2257 This is a wrapper primarily for the Microsoft lib archiver, to make
2261 This is a wrapper for compilers that do not accept options @option{-c}
2262 and @option{-o} at the same time. It is only used when absolutely
2263 required. Such compilers are rare, with the Microsoft C/C++ Compiler
2264 as the most notable exception. This wrapper also makes the following
2265 common options available for that compiler, while performing file name
2266 translation where needed: @option{-I}, @option{-L}, @option{-l},
2267 @option{-Wl,} and @option{-Xlinker}.
2271 These two programs compute the canonical triplets for the given build,
2272 host, or target architecture. These programs are updated regularly to
2273 support new architectures and fix probes broken by changes in new
2274 kernel versions. Each new release of Automake comes with up-to-date
2275 copies of these programs. If your copy of Automake is getting old,
2276 you are encouraged to fetch the latest versions of these files from
2277 @url{http://savannah.gnu.org/git/?group=config} before making a
2281 This program understands how to run a compiler so that it will
2282 generate not only the desired output but also dependency information
2283 that is then used by the automatic dependency tracking feature
2284 (@pxref{Dependencies}).
2287 This is a replacement for the @command{install} program that works on
2288 platforms where @command{install} is unavailable or unusable.
2291 This script is used to generate a @file{version.texi} file. It examines
2292 a file and prints some date information about it.
2295 This wraps a number of programs that are typically only required by
2296 maintainers. If the program in question doesn't exist, or seems to old,
2297 @command{missing} will print an informative warning before failing out,
2298 to provide the user with more context and information.
2301 This script used to be a wrapper around @samp{mkdir -p}, which is not
2302 portable. Now we prefer to use @samp{install-sh -d} when @command{configure}
2303 finds that @samp{mkdir -p} does not work, this makes one less script to
2306 For backward compatibility @file{mkinstalldirs} is still used and
2307 distributed when @command{automake} finds it in a package. But it is no
2308 longer installed automatically, and it should be safe to remove it.
2311 This is used to byte-compile Python scripts.
2314 This implements the default test driver offered by the parallel
2318 Not a program, this file is required for @samp{make dvi}, @samp{make
2319 ps} and @samp{make pdf} to work when Texinfo sources are in the
2320 package. The latest version can be downloaded from
2321 @url{http://www.gnu.org/software/texinfo/}.
2324 This program wraps @command{lex} and @command{yacc} to rename their
2325 output files. It also ensures that, for instance, multiple
2326 @command{yacc} instances can be invoked in a single directory in
2333 @chapter Some example packages
2335 This section contains two small examples.
2337 The first example (@pxref{Complete}) assumes you have an existing
2338 project already using Autoconf, with handcrafted @file{Makefile}s, and
2339 that you want to convert it to using Automake. If you are discovering
2340 both tools, it is probably better that you look at the Hello World
2341 example presented earlier (@pxref{Hello World}).
2343 The second example (@pxref{true}) shows how two programs can be built
2344 from the same file, using different compilation parameters. It
2345 contains some technical digressions that are probably best skipped on
2349 * Complete:: A simple example, start to finish
2350 * true:: Building true and false
2355 @section A simple example, start to finish
2357 @cindex Complete example
2359 Let's suppose you just finished writing @code{zardoz}, a program to make
2360 your head float from vortex to vortex. You've been using Autoconf to
2361 provide a portability framework, but your @file{Makefile.in}s have been
2362 ad-hoc. You want to make them bulletproof, so you turn to Automake.
2364 @cindex @code{AM_INIT_AUTOMAKE}, example use
2366 The first step is to update your @file{configure.ac} to include the
2367 commands that @command{automake} needs. The way to do this is to add an
2368 @code{AM_INIT_AUTOMAKE} call just after @code{AC_INIT}:
2371 AC_INIT([zardoz], [1.0])
2376 Since your program doesn't have any complicating factors (e.g., it
2377 doesn't use @code{gettext}, it doesn't want to build a shared library),
2378 you're done with this part. That was easy!
2380 @cindex @command{aclocal} program, introduction
2381 @cindex @file{aclocal.m4}, preexisting
2382 @cindex @file{acinclude.m4}, defined
2384 Now you must regenerate @file{configure}. But to do that, you'll need
2385 to tell @command{autoconf} how to find the new macro you've used. The
2386 easiest way to do this is to use the @command{aclocal} program to
2387 generate your @file{aclocal.m4} for you. But wait@dots{} maybe you
2388 already have an @file{aclocal.m4}, because you had to write some hairy
2389 macros for your program. The @command{aclocal} program lets you put
2390 your own macros into @file{acinclude.m4}, so simply rename and then
2394 mv aclocal.m4 acinclude.m4
2399 @cindex @command{zardoz} example
2401 Now it is time to write your @file{Makefile.am} for @code{zardoz}.
2402 Since @code{zardoz} is a user program, you want to install it where the
2403 rest of the user programs go: @code{bindir}. Additionally,
2404 @code{zardoz} has some Texinfo documentation. Your @file{configure.ac}
2405 script uses @code{AC_REPLACE_FUNCS}, so you need to link against
2406 @samp{$(LIBOBJS)}. So here's what you'd write:
2409 bin_PROGRAMS = zardoz
2410 zardoz_SOURCES = main.c head.c float.c vortex9.c gun.c
2411 zardoz_LDADD = $(LIBOBJS)
2413 info_TEXINFOS = zardoz.texi
2416 Now you can run @samp{automake --add-missing} to generate your
2417 @file{Makefile.in} and grab any auxiliary files you might need, and
2422 @section Building true and false
2424 @cindex Example, @command{false} and @command{true}
2425 @cindex @command{false} Example
2426 @cindex @command{true} Example
2428 Here is another, trickier example. It shows how to generate two
2429 programs (@code{true} and @code{false}) from the same source file
2430 (@file{true.c}). The difficult part is that each compilation of
2431 @file{true.c} requires different @code{cpp} flags.
2434 bin_PROGRAMS = true false
2436 false_LDADD = false.o
2439 $(COMPILE) -DEXIT_CODE=0 -c true.c
2442 $(COMPILE) -DEXIT_CODE=1 -o false.o -c true.c
2445 Note that there is no @code{true_SOURCES} definition. Automake will
2446 implicitly assume that there is a source file named @file{true.c}
2447 (@pxref{Default _SOURCES}), and
2448 define rules to compile @file{true.o} and link @file{true}. The
2449 @samp{true.o: true.c} rule supplied by the above @file{Makefile.am},
2450 will override the Automake generated rule to build @file{true.o}.
2452 @code{false_SOURCES} is defined to be empty---that way no implicit value
2453 is substituted. Because we have not listed the source of
2454 @file{false}, we have to tell Automake how to link the program. This is
2455 the purpose of the @code{false_LDADD} line. A @code{false_DEPENDENCIES}
2456 variable, holding the dependencies of the @file{false} target will be
2457 automatically generated by Automake from the content of
2460 The above rules won't work if your compiler doesn't accept both
2461 @option{-c} and @option{-o}. The simplest fix for this is to introduce a
2462 bogus dependency (to avoid problems with a parallel @command{make}):
2465 true.o: true.c false.o
2466 $(COMPILE) -DEXIT_CODE=0 -c true.c
2469 $(COMPILE) -DEXIT_CODE=1 -c true.c && mv true.o false.o
2472 As it turns out, there is also a much easier way to do this same task.
2473 Some of the above technique is useful enough that we've kept the
2474 example in the manual. However if you were to build @code{true} and
2475 @code{false} in real life, you would probably use per-program
2476 compilation flags, like so:
2478 @c Keep in sync with specflg7.sh and specflg8.sh
2480 bin_PROGRAMS = false true
2482 false_SOURCES = true.c
2483 false_CPPFLAGS = -DEXIT_CODE=1
2485 true_SOURCES = true.c
2486 true_CPPFLAGS = -DEXIT_CODE=0
2489 In this case Automake will cause @file{true.c} to be compiled twice,
2490 with different flags. In this instance, the names of the object files
2491 would be chosen by automake; they would be @file{false-true.o} and
2492 @file{true-true.o}. (The name of the object files rarely matters.)
2494 @node automake Invocation
2495 @chapter Creating a @file{Makefile.in}
2496 @c This node used to be named "Invoking automake". This @anchor
2497 @c allows old links to still work.
2498 @anchor{Invoking automake}
2500 @cindex Multiple @file{configure.ac} files
2501 @cindex Invoking @command{automake}
2502 @cindex @command{automake}, invoking
2503 @cindex Invocation of @command{automake}
2504 @cindex @command{automake}, invocation
2506 To create all the @file{Makefile.in}s for a package, run the
2507 @command{automake} program in the top level directory, with no
2508 arguments. @command{automake} will automatically find each
2509 appropriate @file{Makefile.am} (by scanning @file{configure.ac};
2510 @pxref{configure}) and generate the corresponding @file{Makefile.in}.
2511 Note that @command{automake} has a rather simplistic view of what
2512 constitutes a package; it assumes that a package has only one
2513 @file{configure.ac}, at the top. If your package has multiple
2514 @file{configure.ac}s, then you must run @command{automake} in each
2515 directory holding a @file{configure.ac}. (Alternatively, you may rely
2516 on Autoconf's @command{autoreconf}, which is able to recurse your
2517 package tree and run @command{automake} where appropriate.)
2519 You can optionally give @command{automake} an argument; @file{.am} is
2520 appended to the argument and the result is used as the name of the
2521 input file. This feature is generally only used to automatically
2522 rebuild an out-of-date @file{Makefile.in}. Note that
2523 @command{automake} must always be run from the topmost directory of a
2524 project, even if being used to regenerate the @file{Makefile.in} in
2525 some subdirectory. This is necessary because @command{automake} must
2526 scan @file{configure.ac}, and because @command{automake} uses the
2527 knowledge that a @file{Makefile.in} is in a subdirectory to change its
2528 behavior in some cases.
2531 Automake will run @command{autoconf} to scan @file{configure.ac} and
2532 its dependencies (i.e., @file{aclocal.m4} and any included file),
2533 therefore @command{autoconf} must be in your @env{PATH}. If there is
2534 an @env{AUTOCONF} variable in your environment it will be used
2535 instead of @command{autoconf}, this allows you to select a particular
2536 version of Autoconf. By the way, don't misunderstand this paragraph:
2537 @command{automake} runs @command{autoconf} to @strong{scan} your
2538 @file{configure.ac}, this won't build @file{configure} and you still
2539 have to run @command{autoconf} yourself for this purpose.
2541 @cindex @command{automake} options
2542 @cindex Options, @command{automake}
2543 @cindex Strictness, command line
2545 @command{automake} accepts the following options:
2547 @cindex Extra files distributed with Automake
2548 @cindex Files distributed with Automake
2549 @cindex @file{config.guess}
2553 @itemx --add-missing
2555 @opindex --add-missing
2556 Automake requires certain common files to exist in certain situations;
2557 for instance, @file{config.guess} is required if @file{configure.ac} invokes
2558 @code{AC_CANONICAL_HOST}. Automake is distributed with several of these
2559 files (@pxref{Auxiliary Programs}); this option will cause the missing
2560 ones to be automatically added to the package, whenever possible. In
2561 general if Automake tells you a file is missing, try using this option.
2562 By default Automake tries to make a symbolic link pointing to its own
2563 copy of the missing file; this can be changed with @option{--copy}.
2565 Many of the potentially-missing files are common scripts whose
2566 location may be specified via the @code{AC_CONFIG_AUX_DIR} macro.
2567 Therefore, @code{AC_CONFIG_AUX_DIR}'s setting affects whether a
2568 file is considered missing, and where the missing file is added
2571 In some strictness modes, additional files are installed, see @ref{Gnits}
2572 for more information.
2574 @item --libdir=@var{dir}
2576 Look for Automake data files in directory @var{dir} instead of in the
2577 installation directory. This is typically used for debugging.
2579 @item --print-libdir
2580 @opindex --print-libdir
2581 Print the path of the installation directory containing Automake-provided
2582 scripts and data files (like e.g., @file{texinfo.texi} and
2589 When used with @option{--add-missing}, causes installed files to be
2590 copied. The default is to make a symbolic link.
2594 @itemx --force-missing
2595 @opindex --force-missing
2596 When used with @option{--add-missing}, causes standard files to be reinstalled
2597 even if they already exist in the source tree. This involves removing
2598 the file from the source tree before creating the new symlink (or, with
2599 @option{--copy}, copying the new file).
2603 Set the global strictness to @option{foreign}. For more information, see
2608 Set the global strictness to @option{gnits}. For more information, see
2613 Set the global strictness to @option{gnu}. For more information, see
2614 @ref{Gnits}. This is the default strictness.
2618 Print a summary of the command line options and exit.
2621 @itemx --ignore-deps
2623 This disables the dependency tracking feature in generated
2624 @file{Makefile}s; see @ref{Dependencies}.
2626 @item --include-deps
2627 @opindex --include-deps
2628 This enables the dependency tracking feature. This feature is enabled
2629 by default. This option is provided for historical reasons only and
2630 probably should not be used.
2634 Ordinarily @command{automake} creates all @file{Makefile.in}s mentioned in
2635 @file{configure.ac}. This option causes it to only update those
2636 @file{Makefile.in}s that are out of date with respect to one of their
2640 @itemx --output-dir=@var{dir}
2642 @opindex --output-dir
2643 Put the generated @file{Makefile.in} in the directory @var{dir}.
2644 Ordinarily each @file{Makefile.in} is created in the directory of the
2645 corresponding @file{Makefile.am}. This option is deprecated and will be
2646 removed in a future release.
2652 Cause Automake to print information about which files are being read or
2657 Print the version number of Automake and exit.
2660 @itemx --warnings=@var{category}
2663 Output warnings falling in @var{category}. @var{category} can be
2667 warnings related to the GNU Coding Standards
2668 (@pxref{Top, , , standards, The GNU Coding Standards}).
2670 obsolete features or constructions
2672 user redefinitions of Automake rules or variables
2674 portability issues (e.g., use of @command{make} features that are
2675 known to be not portable)
2676 @item extra-portability
2677 extra portability issues related to obscure tools. One example of such
2678 a tool is the Microsoft @command{lib} archiver.
2680 weird syntax, unused variables, typos
2682 unsupported or incomplete features
2686 turn off all the warnings
2688 treat warnings as errors
2691 A category can be turned off by prefixing its name with @samp{no-}. For
2692 instance, @option{-Wno-syntax} will hide the warnings about unused
2695 The categories output by default are @samp{obsolete}, @samp{syntax} and
2696 @samp{unsupported}. Additionally, @samp{gnu} and @samp{portability}
2697 are enabled in @option{--gnu} and @option{--gnits} strictness.
2699 @c Checked by extra-portability.sh
2700 Turning off @samp{portability} will also turn off @samp{extra-portability},
2701 and similarly turning on @samp{extra-portability} will also turn on
2702 @samp{portability}. However, turning on @samp{portability} or turning
2703 off @samp{extra-portability} will not affect the other category.
2706 The environment variable @env{WARNINGS} can contain a comma separated
2707 list of categories to enable. It will be taken into account before the
2708 command-line switches, this way @option{-Wnone} will also ignore any
2709 warning category enabled by @env{WARNINGS}. This variable is also used
2710 by other tools like @command{autoconf}; unknown categories are ignored
2715 @vindex AUTOMAKE_JOBS
2716 If the environment variable @env{AUTOMAKE_JOBS} contains a positive
2717 number, it is taken as the maximum number of Perl threads to use in
2718 @command{automake} for generating multiple @file{Makefile.in} files
2719 concurrently. This is an experimental feature.
2723 @chapter Scanning @file{configure.ac}, using @command{aclocal}
2725 @cindex @file{configure.ac}, scanning
2726 @cindex Scanning @file{configure.ac}
2727 @cindex Using @command{aclocal}
2728 @cindex @command{aclocal}, using
2730 Automake scans the package's @file{configure.ac} to determine certain
2731 information about the package. Some @command{autoconf} macros are required
2732 and some variables must be defined in @file{configure.ac}. Automake
2733 will also use information from @file{configure.ac} to further tailor its
2736 Automake also supplies some Autoconf macros to make the maintenance
2737 easier. These macros can automatically be put into your
2738 @file{aclocal.m4} using the @command{aclocal} program.
2741 * Requirements:: Configuration requirements
2742 * Optional:: Other things Automake recognizes
2743 * aclocal Invocation:: Auto-generating aclocal.m4
2744 * Macros:: Autoconf macros supplied with Automake
2749 @section Configuration requirements
2751 @cindex Automake requirements
2752 @cindex Requirements of Automake
2754 @acindex AM_INIT_AUTOMAKE
2755 The one real requirement of Automake is that your @file{configure.ac}
2756 call @code{AM_INIT_AUTOMAKE}. This macro does several things that are
2757 required for proper Automake operation (@pxref{Macros}).
2759 Here are the other macros that Automake requires but which are not run
2760 by @code{AM_INIT_AUTOMAKE}:
2763 @item AC_CONFIG_FILES
2765 @acindex AC_CONFIG_FILES
2767 These two macros are usually invoked as follows near the end of
2768 @file{configure.ac}.
2782 Automake uses these to determine which files to create (@pxref{Output, ,
2783 Creating Output Files, autoconf, The Autoconf Manual}). A listed file
2784 is considered to be an Automake generated @file{Makefile} if there
2785 exists a file with the same name and the @file{.am} extension appended.
2786 Typically, @samp{AC_CONFIG_FILES([foo/Makefile])} will cause Automake to
2787 generate @file{foo/Makefile.in} if @file{foo/Makefile.am} exists.
2789 When using @code{AC_CONFIG_FILES} with multiple input files, as in
2792 AC_CONFIG_FILES([Makefile:top.in:Makefile.in:bot.in])
2796 @command{automake} will generate the first @file{.in} input file for
2797 which a @file{.am} file exists. If no such file exists the output
2798 file is not considered to be generated by Automake.
2800 Files created by @code{AC_CONFIG_FILES}, be they Automake
2801 @file{Makefile}s or not, are all removed by @samp{make distclean}.
2802 Their inputs are automatically distributed, unless they
2803 are the output of prior @code{AC_CONFIG_FILES} commands.
2804 Finally, rebuild rules are generated in the Automake @file{Makefile}
2805 existing in the subdirectory of the output file, if there is one, or
2806 in the top-level @file{Makefile} otherwise.
2808 The above machinery (cleaning, distributing, and rebuilding) works
2809 fine if the @code{AC_CONFIG_FILES} specifications contain only
2810 literals. If part of the specification uses shell variables,
2811 @command{automake} will not be able to fulfill this setup, and you will
2812 have to complete the missing bits by hand. For instance, on
2814 @c Keep in sync with output11.sh
2818 AC_CONFIG_FILES([output:$file],, [file=$file])
2822 @command{automake} will output rules to clean @file{output}, and
2823 rebuild it. However the rebuild rule will not depend on @file{input},
2824 and this file will not be distributed either. (You must add
2825 @samp{EXTRA_DIST = input} to your @file{Makefile.am} if @file{input} is a
2830 @c Keep in sync with output11.sh
2835 AC_CONFIG_FILES([$file:input],, [file=$file])
2836 AC_CONFIG_FILES([$file2],, [file2=$file2])
2840 will only cause @file{input} to be distributed. No file will be
2841 cleaned automatically (add @samp{DISTCLEANFILES = output out}
2842 yourself), and no rebuild rule will be output.
2844 Obviously @command{automake} cannot guess what value @samp{$file} is
2845 going to hold later when @file{configure} is run, and it cannot use
2846 the shell variable @samp{$file} in a @file{Makefile}. However, if you
2847 make reference to @samp{$file} as @samp{$@{file@}} (i.e., in a way
2848 that is compatible with @command{make}'s syntax) and furthermore use
2849 @code{AC_SUBST} to ensure that @samp{$@{file@}} is meaningful in a
2850 @file{Makefile}, then @command{automake} will be able to use
2851 @samp{$@{file@}} to generate all of these rules. For instance, here is
2852 how the Automake package itself generates versioned scripts for its
2856 AC_SUBST([APIVERSION], @dots{})
2859 [tests/aclocal-$@{APIVERSION@}:tests/aclocal.in],
2860 [chmod +x tests/aclocal-$@{APIVERSION@}],
2861 [APIVERSION=$APIVERSION])
2863 [tests/automake-$@{APIVERSION@}:tests/automake.in],
2864 [chmod +x tests/automake-$@{APIVERSION@}])
2868 Here cleaning, distributing, and rebuilding are done automatically,
2869 because @samp{$@{APIVERSION@}} is known at @command{make}-time.
2871 Note that you should not use shell variables to declare
2872 @file{Makefile} files for which @command{automake} must create
2873 @file{Makefile.in}. Even @code{AC_SUBST} does not help here, because
2874 @command{automake} needs to know the file name when it runs in order
2875 to check whether @file{Makefile.am} exists. (In the very hairy case
2876 that your setup requires such use of variables, you will have to tell
2877 Automake which @file{Makefile.in}s to generate on the command-line.)
2879 It is possible to let @command{automake} emit conditional rules for
2880 @code{AC_CONFIG_FILES} with the help of @code{AM_COND_IF}
2886 Use literals for @file{Makefile}s, and for other files whenever possible.
2888 Use @samp{$file} (or @samp{$@{file@}} without @samp{AC_SUBST([file])})
2889 for files that @command{automake} should ignore.
2891 Use @samp{$@{file@}} and @samp{AC_SUBST([file])} for files
2892 that @command{automake} should not ignore.
2899 @section Other things Automake recognizes
2901 @cindex Macros Automake recognizes
2902 @cindex Recognized macros by Automake
2904 Every time Automake is run it calls Autoconf to trace
2905 @file{configure.ac}. This way it can recognize the use of certain
2906 macros and tailor the generated @file{Makefile.in} appropriately.
2907 Currently recognized macros and their effects are:
2910 @item AC_CANONICAL_BUILD
2911 @itemx AC_CANONICAL_HOST
2912 @itemx AC_CANONICAL_TARGET
2913 @vindex build_triplet
2914 @vindex host_triplet
2915 @vindex target_triplet
2916 Automake will ensure that @file{config.guess} and @file{config.sub}
2917 exist. Also, the @file{Makefile} variables @code{build_triplet},
2918 @code{host_triplet} and @code{target_triplet} are introduced. See
2919 @ref{Canonicalizing, , Getting the Canonical System Type, autoconf,
2920 The Autoconf Manual}.
2922 @item AC_CONFIG_AUX_DIR
2923 Automake will look for various helper scripts, such as
2924 @file{install-sh}, in the directory named in this macro invocation.
2925 @c This list is accurate relative to version 1.11
2926 (The full list of scripts is:
2928 @file{config.guess},
2936 @file{mkinstalldirs},
2941 Not all scripts are always searched for; some scripts
2942 will only be sought if the generated @file{Makefile.in} requires them.
2944 If @code{AC_CONFIG_AUX_DIR} is not given, the scripts are looked for in
2945 their standard locations. For @file{mdate-sh},
2946 @file{texinfo.tex}, and @file{ylwrap}, the standard location is the
2947 source directory corresponding to the current @file{Makefile.am}. For
2948 the rest, the standard location is the first one of @file{.}, @file{..},
2949 or @file{../..} (relative to the top source directory) that provides any
2950 one of the helper scripts. @xref{Input, , Finding `configure' Input,
2951 autoconf, The Autoconf Manual}.
2953 Required files from @code{AC_CONFIG_AUX_DIR} are automatically
2954 distributed, even if there is no @file{Makefile.am} in this directory.
2956 @item AC_CONFIG_LIBOBJ_DIR
2957 Automake will require the sources file declared with
2958 @code{AC_LIBSOURCE} (see below) in the directory specified by this
2961 @item AC_CONFIG_HEADERS
2962 Automake will generate rules to rebuild these headers from the
2963 corresponding templates (usually, the template for a @file{foo.h}
2964 header being @file{foo.h.in}). Older versions of Automake
2965 required the use of @code{AM_CONFIG_HEADER}; this is no longer
2966 the case, and that macro has indeed been removed.
2968 As with @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the
2969 specification using shell variables will be ignored as far as
2970 cleaning, distributing, and rebuilding is concerned.
2972 @item AC_CONFIG_LINKS
2973 Automake will generate rules to remove @file{configure} generated
2974 links on @samp{make distclean} and to distribute named source files as
2975 part of @samp{make dist}.
2977 As for @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the
2978 specification using shell variables will be ignored as far as cleaning
2979 and distributing is concerned. (There are no rebuild rules for links.)
2983 @itemx AC_LIBSOURCES
2985 Automake will automatically distribute any file listed in
2986 @code{AC_LIBSOURCE} or @code{AC_LIBSOURCES}.
2988 Note that the @code{AC_LIBOBJ} macro calls @code{AC_LIBSOURCE}. So if
2989 an Autoconf macro is documented to call @samp{AC_LIBOBJ([file])}, then
2990 @file{file.c} will be distributed automatically by Automake. This
2991 encompasses many macros like @code{AC_FUNC_ALLOCA},
2992 @code{AC_FUNC_MEMCMP}, @code{AC_REPLACE_FUNCS}, and others.
2994 By the way, direct assignments to @code{LIBOBJS} are no longer
2995 supported. You should always use @code{AC_LIBOBJ} for this purpose.
2996 @xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs.@: @code{LIBOBJS},
2997 autoconf, The Autoconf Manual}.
2999 @item AC_PROG_RANLIB
3000 This is required if any libraries are built in the package.
3001 @xref{Particular Programs, , Particular Program Checks, autoconf, The
3005 This is required if any C++ source is included. @xref{Particular
3006 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
3009 This is required if any Objective C source is included. @xref{Particular
3010 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
3012 @item AC_PROG_OBJCXX
3013 This is required if any Objective C++ source is included. @xref{Particular
3014 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
3017 This is required if any Fortran 77 source is included. @xref{Particular
3018 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
3020 @item AC_F77_LIBRARY_LDFLAGS
3021 This is required for programs and shared libraries that are a mixture of
3022 languages that include Fortran 77 (@pxref{Mixing Fortran 77 With C and
3023 C++}). @xref{Macros, , Autoconf macros supplied with Automake}.
3026 Automake will add the flags computed by @code{AC_FC_SRCEXT} to compilation
3027 of files with the respective source extension (@pxref{Fortran Compiler, ,
3028 Fortran Compiler Characteristics, autoconf, The Autoconf Manual}).
3031 This is required if any Fortran 90/95 source is included. This macro is
3032 distributed with Autoconf version 2.58 and later. @xref{Particular
3033 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
3035 @item AC_PROG_LIBTOOL
3036 Automake will turn on processing for @command{libtool} (@pxref{Top, ,
3037 Introduction, libtool, The Libtool Manual}).
3041 If a Yacc source file is seen, then you must either use this macro or
3042 define the variable @code{YACC} in @file{configure.ac}. The former is
3043 preferred (@pxref{Particular Programs, , Particular Program Checks,
3044 autoconf, The Autoconf Manual}).
3047 If a Lex source file is seen, then this macro must be used.
3048 @xref{Particular Programs, , Particular Program Checks, autoconf, The
3051 @item AC_REQUIRE_AUX_FILE
3052 For each @code{AC_REQUIRE_AUX_FILE([@var{file}])},
3053 @command{automake} will ensure that @file{@var{file}} exists in the
3054 aux directory, and will complain otherwise. It
3055 will also automatically distribute the file. This macro should be
3056 used by third-party Autoconf macros that require some supporting
3057 files in the aux directory specified with @code{AC_CONFIG_AUX_DIR}
3058 above. @xref{Input, , Finding @command{configure} Input, autoconf,
3059 The Autoconf Manual}.
3062 The first argument is automatically defined as a variable in each
3063 generated @file{Makefile.in}, unless @code{AM_SUBST_NOTMAKE} is also
3064 used for this variable. @xref{Setting Output Variables, , Setting
3065 Output Variables, autoconf, The Autoconf Manual}.
3067 For every substituted variable @var{var}, @command{automake} will add
3068 a line @code{@var{var} = @var{value}} to each @file{Makefile.in} file.
3069 Many Autoconf macros invoke @code{AC_SUBST} to set output variables
3070 this way, e.g., @code{AC_PATH_XTRA} defines @code{X_CFLAGS} and
3071 @code{X_LIBS}. Thus, you can access these variables as
3072 @code{$(X_CFLAGS)} and @code{$(X_LIBS)} in any @file{Makefile.am}
3073 if @code{AC_PATH_XTRA} is called.
3075 @item AM_CONDITIONAL
3076 This introduces an Automake conditional (@pxref{Conditionals}).
3079 This macro allows @code{automake} to detect subsequent access within
3080 @file{configure.ac} to a conditional previously introduced with
3081 @code{AM_CONDITIONAL}, thus enabling conditional @code{AC_CONFIG_FILES}
3082 (@pxref{Usage of Conditionals}).
3084 @item AM_GNU_GETTEXT
3085 This macro is required for packages that use GNU gettext
3086 (@pxref{gettext}). It is distributed with gettext. If Automake sees
3087 this macro it ensures that the package meets some of gettext's
3090 @item AM_GNU_GETTEXT_INTL_SUBDIR
3091 This macro specifies that the @file{intl/} subdirectory is to be built,
3092 even if the @code{AM_GNU_GETTEXT} macro was invoked with a first argument
3095 @item AM_MAINTAINER_MODE(@ovar{default-mode})
3096 @opindex --enable-maintainer-mode
3097 @opindex --disable-maintainer-mode
3098 This macro adds an @option{--enable-maintainer-mode} option to
3099 @command{configure}. If this is used, @command{automake} will cause
3100 ``maintainer-only'' rules to be turned off by default in the
3101 generated @file{Makefile.in}s, unless @var{default-mode} is
3102 @samp{enable}. This macro defines the @code{MAINTAINER_MODE}
3103 conditional, which you can use in your own @file{Makefile.am}.
3104 @xref{maintainer-mode}.
3106 @item AM_SUBST_NOTMAKE(@var{var})
3107 Prevent Automake from defining a variable @var{var}, even if it is
3108 substituted by @command{config.status}. Normally, Automake defines a
3109 @command{make} variable for each @command{configure} substitution,
3110 i.e., for each @code{AC_SUBST([@var{var}])}. This macro prevents that
3111 definition from Automake. If @code{AC_SUBST} has not been called
3112 for this variable, then @code{AM_SUBST_NOTMAKE} has no effects.
3113 Preventing variable definitions may be useful for substitution of
3114 multi-line values, where @code{@var{var} = @@@var{value}@@} might yield
3118 Files included by @file{configure.ac} using this macro will be
3119 detected by Automake and automatically distributed. They will also
3120 appear as dependencies in @file{Makefile} rules.
3122 @code{m4_include} is seldom used by @file{configure.ac} authors, but
3123 can appear in @file{aclocal.m4} when @command{aclocal} detects that
3124 some required macros come from files local to your package (as opposed to
3125 macros installed in a system-wide directory, @pxref{aclocal Invocation}).
3129 @node aclocal Invocation
3130 @section Auto-generating aclocal.m4
3131 @c This node used to be named "Invoking automake". This @anchor
3132 @c allows old links to still work.
3133 @anchor{Invoking aclocal}
3135 @cindex Invocation of @command{aclocal}
3136 @cindex @command{aclocal}, Invocation
3137 @cindex Invoking @command{aclocal}
3138 @cindex @command{aclocal}, Invoking
3140 Automake includes a number of Autoconf macros that can be used in
3141 your package (@pxref{Macros}); some of them are actually required by
3142 Automake in certain situations. These macros must be defined in your
3143 @file{aclocal.m4}; otherwise they will not be seen by
3146 The @command{aclocal} program will automatically generate
3147 @file{aclocal.m4} files based on the contents of @file{configure.ac}.
3148 This provides a convenient way to get Automake-provided macros,
3149 without having to search around. The @command{aclocal} mechanism
3150 allows other packages to supply their own macros (@pxref{Extending
3151 aclocal}). You can also use it to maintain your own set of custom
3152 macros (@pxref{Local Macros}).
3154 At startup, @command{aclocal} scans all the @file{.m4} files it can
3155 find, looking for macro definitions (@pxref{Macro Search Path}). Then
3156 it scans @file{configure.ac}. Any mention of one of the macros found
3157 in the first step causes that macro, and any macros it in turn
3158 requires, to be put into @file{aclocal.m4}.
3160 @emph{Putting} the file that contains the macro definition into
3161 @file{aclocal.m4} is usually done by copying the entire text of this
3162 file, including unused macro definitions as well as both @samp{#} and
3163 @samp{dnl} comments. If you want to make a comment that will be
3164 completely ignored by @command{aclocal}, use @samp{##} as the comment
3167 When a file selected by @command{aclocal} is located in a subdirectory
3168 specified as a relative search path with @command{aclocal}'s @option{-I}
3169 argument, @command{aclocal} assumes the file belongs to the package
3170 and uses @code{m4_include} instead of copying it into
3171 @file{aclocal.m4}. This makes the package smaller, eases dependency
3172 tracking, and cause the file to be distributed automatically.
3173 (@xref{Local Macros}, for an example.) Any macro that is found in a
3174 system-wide directory, or via an absolute search path will be copied.
3175 So use @samp{-I `pwd`/reldir} instead of @samp{-I reldir} whenever
3176 some relative directory should be considered outside the package.
3178 The contents of @file{acinclude.m4}, if this file exists, are also
3179 automatically included in @file{aclocal.m4}. We recommend against
3180 using @file{acinclude.m4} in new packages (@pxref{Local Macros}).
3184 While computing @file{aclocal.m4}, @command{aclocal} runs
3185 @command{autom4te} (@pxref{Using autom4te, , Using @command{Autom4te},
3186 autoconf, The Autoconf Manual}) in order to trace the macros that are
3187 really used, and omit from @file{aclocal.m4} all macros that are
3188 mentioned but otherwise unexpanded (this can happen when a macro is
3189 called conditionally). @command{autom4te} is expected to be in the
3190 @env{PATH}, just as @command{autoconf}. Its location can be
3191 overridden using the @env{AUTOM4TE} environment variable.
3194 * aclocal Options:: Options supported by aclocal
3195 * Macro Search Path:: How aclocal finds .m4 files
3196 * Extending aclocal:: Writing your own aclocal macros
3197 * Local Macros:: Organizing local macros
3198 * Serials:: Serial lines in Autoconf macros
3199 * Future of aclocal:: aclocal's scheduled death
3202 @node aclocal Options
3203 @subsection aclocal Options
3205 @cindex @command{aclocal}, Options
3206 @cindex Options, @command{aclocal}
3208 @command{aclocal} accepts the following options:
3211 @item --automake-acdir=@var{dir}
3212 @opindex --automake-acdir
3213 Look for the automake-provided macro files in @var{dir} instead of
3214 in the installation directory. This is typically used for debugging.
3216 @item --system-acdir=@var{dir}
3217 @opindex --system-acdir
3218 Look for the system-wide third-party macro files (and the special
3219 @file{dirlist} file) in @var{dir} instead of in the installation
3220 directory. This is typically used for debugging.
3222 @item --diff[=@var{command}]
3224 Run @var{command} on M4 file that would be installed or overwritten
3225 by @option{--install}. The default @var{command} is @samp{diff -u}.
3226 This option implies @option{--install} and @option{--dry-run}.
3230 Do not actually overwrite (or create) @file{aclocal.m4} and M4
3231 files installed by @option{--install}.
3235 Print a summary of the command line options and exit.
3239 Add the directory @var{dir} to the list of directories searched for
3244 Install system-wide third-party macros into the first directory
3245 specified with @samp{-I @var{dir}} instead of copying them in the
3247 @c Keep in sync with aclocal-install-absdir.sh
3248 Note that this will happen also if @var{dir} is an absolute path.
3250 @cindex serial number and @option{--install}
3251 When this option is used, and only when this option is used,
3252 @command{aclocal} will also honor @samp{#serial @var{number}} lines
3253 that appear in macros: an M4 file is ignored if there exists another
3254 M4 file with the same basename and a greater serial number in the
3255 search path (@pxref{Serials}).
3259 Always overwrite the output file. The default is to overwrite the output
3260 file only when really needed, i.e., when its contents changes or if one
3261 of its dependencies is younger.
3263 This option forces the update of @file{aclocal.m4} (or the file
3264 specified with @file{--output} below) and only this file, it has
3265 absolutely no influence on files that may need to be installed by
3268 @item --output=@var{file}
3270 Cause the output to be put into @var{file} instead of @file{aclocal.m4}.
3272 @item --print-ac-dir
3273 @opindex --print-ac-dir
3274 Prints the name of the directory that @command{aclocal} will search to
3275 find third-party @file{.m4} files. When this option is given, normal
3276 processing is suppressed. This option was used @emph{in the past} by
3277 third-party packages to determine where to install @file{.m4} macro
3278 files, but @emph{this usage is today discouraged}, since it causes
3279 @samp{$(prefix)} not to be thoroughly honoured (which violates the
3280 GNU Coding Standards), and a similar semantics can be better obtained
3281 with the @env{ACLOCAL_PATH} environment variable; @pxref{Extending aclocal}.
3285 Print the names of the files it examines.
3289 Print the version number of Automake and exit.
3292 @item --warnings=@var{category}
3295 Output warnings falling in @var{category}. @var{category} can be
3299 dubious syntactic constructs, underquoted macros, unused macros, etc.
3303 all the warnings, this is the default
3305 turn off all the warnings
3307 treat warnings as errors
3310 All warnings are output by default.
3313 The environment variable @env{WARNINGS} is honored in the same
3314 way as it is for @command{automake} (@pxref{automake Invocation}).
3318 @node Macro Search Path
3319 @subsection Macro Search Path
3321 @cindex Macro search path
3322 @cindex @command{aclocal} search path
3324 By default, @command{aclocal} searches for @file{.m4} files in the following
3325 directories, in this order:
3328 @item @var{acdir-APIVERSION}
3329 This is where the @file{.m4} macros distributed with Automake itself
3330 are stored. @var{APIVERSION} depends on the Automake release used;
3331 for example, for Automake 1.11.x, @var{APIVERSION} = @code{1.11}.
3334 This directory is intended for third party @file{.m4} files, and is
3335 configured when @command{automake} itself is built. This is
3336 @file{@@datadir@@/aclocal/}, which typically
3337 expands to @file{$@{prefix@}/share/aclocal/}. To find the compiled-in
3338 value of @var{acdir}, use the @option{--print-ac-dir} option
3339 (@pxref{aclocal Options}).
3342 As an example, suppose that @command{automake-1.11.2} was configured with
3343 @option{--prefix=@-/usr/local}. Then, the search path would be:
3346 @item @file{/usr/local/share/aclocal-1.11.2/}
3347 @item @file{/usr/local/share/aclocal/}
3350 The paths for the @var{acdir} and @var{acdir-APIVERSION} directories can
3351 be changed respectively through aclocal options @option{--system-acdir}
3352 and @option{--automake-acdir} (@pxref{aclocal Options}). Note however
3353 that these options are only intended for use by the internal Automake
3354 test suite, or for debugging under highly unusual situations; they are
3355 not ordinarily needed by end-users.
3357 As explained in (@pxref{aclocal Options}), there are several options that
3358 can be used to change or extend this search path.
3360 @subsubheading Modifying the Macro Search Path: @samp{-I @var{dir}}
3362 Any extra directories specified using @option{-I} options
3363 (@pxref{aclocal Options}) are @emph{prepended} to this search list. Thus,
3364 @samp{aclocal -I /foo -I /bar} results in the following search path:
3369 @item @var{acdir}-@var{APIVERSION}
3373 @subsubheading Modifying the Macro Search Path: @file{dirlist}
3374 @cindex @file{dirlist}
3376 There is a third mechanism for customizing the search path. If a
3377 @file{dirlist} file exists in @var{acdir}, then that file is assumed to
3378 contain a list of directory patterns, one per line. @command{aclocal}
3379 expands these patterns to directory names, and adds them to the search
3380 list @emph{after} all other directories. @file{dirlist} entries may
3381 use shell wildcards such as @samp{*}, @samp{?}, or @code{[...]}.
3383 For example, suppose
3384 @file{@var{acdir}/dirlist} contains the following:
3393 and that @command{aclocal} was called with the @samp{-I /foo -I /bar} options.
3394 Then, the search path would be
3396 @c @code looks better than @file here
3400 @item @var{acdir}-@var{APIVERSION}
3407 and all directories with path names starting with @code{/test3}.
3409 If the @option{--system-acdir=@var{dir}} option is used, then
3410 @command{aclocal} will search for the @file{dirlist} file in
3411 @var{dir}; but remember the warnings above against the use of
3412 @option{--system-acdir}.
3414 @file{dirlist} is useful in the following situation: suppose that
3415 @command{automake} version @code{1.11.2} is installed with
3416 @samp{--prefix=/usr} by the system vendor. Thus, the default search
3419 @c @code looks better than @file here
3421 @item @code{/usr/share/aclocal-1.11/}
3422 @item @code{/usr/share/aclocal/}
3425 However, suppose further that many packages have been manually
3426 installed on the system, with $prefix=/usr/local, as is typical. In
3427 that case, many of these ``extra'' @file{.m4} files are in
3428 @file{/usr/local/share/aclocal}. The only way to force
3429 @file{/usr/bin/aclocal} to find these ``extra'' @file{.m4} files is to
3430 always call @samp{aclocal -I /usr/local/share/aclocal}. This is
3431 inconvenient. With @file{dirlist}, one may create a file
3432 @file{/usr/share/aclocal/dirlist} containing only the single line
3435 /usr/local/share/aclocal
3438 Now, the ``default'' search path on the affected system is
3440 @c @code looks better than @file here
3442 @item @code{/usr/share/aclocal-1.11/}
3443 @item @code{/usr/share/aclocal/}
3444 @item @code{/usr/local/share/aclocal/}
3447 without the need for @option{-I} options; @option{-I} options can be reserved
3448 for project-specific needs (@file{my-source-dir/m4/}), rather than
3449 using it to work around local system-dependent tool installation
3452 Similarly, @file{dirlist} can be handy if you have installed a local
3453 copy of Automake in your account and want @command{aclocal} to look for
3454 macros installed at other places on the system.
3456 @anchor{ACLOCAL_PATH}
3457 @subsubheading Modifying the Macro Search Path: @file{ACLOCAL_PATH}
3458 @cindex @env{ACLOCAL_PATH}
3460 The fourth and last mechanism to customize the macro search path is
3461 also the simplest. Any directory included in the colon-separated
3462 environment variable @env{ACLOCAL_PATH} is added to the search path
3463 @c Keep in sync with aclocal-path-precedence.sh
3464 and takes precedence over system directories (including those found via
3465 @file{dirlist}), with the exception of the versioned directory
3466 @var{acdir-APIVERSION} (@pxref{Macro Search Path}). However, directories
3467 passed via @option{-I} will take precedence over directories in
3470 @c Keep in sync with aclocal-path-installed.sh
3471 Also note that, if the @option{--install} option is used, any @file{.m4}
3472 file containing a required macro that is found in a directory listed in
3473 @env{ACLOCAL_PATH} will be installed locally.
3474 @c Keep in sync with aclocal-path-installed-serial.sh
3475 In this case, serial numbers in @file{.m4} are honoured too,
3478 Conversely to @file{dirlist}, @env{ACLOCAL_PATH} is useful if you are
3479 using a global copy of Automake and want @command{aclocal} to look for
3480 macros somewhere under your home directory.
3482 @subsubheading Planned future incompatibilities
3484 The order in which the directories in the macro search path are currently
3485 looked up is confusing and/or suboptimal in various aspects, and is
3486 probably going to be changed in the future Automake release. In
3487 particular, directories in @env{ACLOCAL_PATH} and @file{@var{acdir}}
3488 might end up taking precedence over @file{@var{acdir-APIVERSION}}, and
3489 directories in @file{@var{acdir}/dirlist} might end up taking precedence
3490 over @file{@var{acdir}}. @emph{This is a possible future incompatibility!}
3492 @node Extending aclocal
3493 @subsection Writing your own aclocal macros
3495 @cindex @command{aclocal}, extending
3496 @cindex Extending @command{aclocal}
3498 The @command{aclocal} program doesn't have any built-in knowledge of any
3499 macros, so it is easy to extend it with your own macros.
3501 This can be used by libraries that want to supply their own Autoconf
3502 macros for use by other programs. For instance, the @command{gettext}
3503 library supplies a macro @code{AM_GNU_GETTEXT} that should be used by
3504 any package using @command{gettext}. When the library is installed, it
3505 installs this macro so that @command{aclocal} will find it.
3507 A macro file's name should end in @file{.m4}. Such files should be
3508 installed in @file{$(datadir)/aclocal}. This is as simple as writing:
3510 @c Keep in sync with primary-prefix-couples-documented-valid.sh
3512 aclocaldir = $(datadir)/aclocal
3513 aclocal_DATA = mymacro.m4 myothermacro.m4
3517 Please do use @file{$(datadir)/aclocal}, and not something based on
3518 the result of @samp{aclocal --print-ac-dir} (@pxref{Hard-Coded Install
3519 Paths}, for arguments). It might also be helpful to suggest to
3520 the user to add the @file{$(datadir)/aclocal} directory to his
3521 @env{ACLOCAL_PATH} variable (@pxref{ACLOCAL_PATH}) so that
3522 @command{aclocal} will find the @file{.m4} files installed by your
3523 package automatically.
3525 A file of macros should be a series of properly quoted
3526 @code{AC_DEFUN}'s (@pxref{Macro Definitions, , , autoconf, The
3527 Autoconf Manual}). The @command{aclocal} programs also understands
3528 @code{AC_REQUIRE} (@pxref{Prerequisite Macros, , , autoconf, The
3529 Autoconf Manual}), so it is safe to put each macro in a separate file.
3530 Each file should have no side effects but macro definitions.
3531 Especially, any call to @code{AC_PREREQ} should be done inside the
3532 defined macro, not at the beginning of the file.
3534 @cindex underquoted @code{AC_DEFUN}
3538 Starting with Automake 1.8, @command{aclocal} will warn about all
3539 underquoted calls to @code{AC_DEFUN}. We realize this will annoy a
3540 lot of people, because @command{aclocal} was not so strict in the past
3541 and many third party macros are underquoted; and we have to apologize
3542 for this temporary inconvenience. The reason we have to be stricter
3543 is that a future implementation of @command{aclocal} (@pxref{Future of
3544 aclocal}) will have to temporarily include all of these third party
3545 @file{.m4} files, maybe several times, including even files that are
3546 not actually needed. Doing so should alleviate many problems of the
3547 current implementation, however it requires a stricter style from the
3548 macro authors. Hopefully it is easy to revise the existing macros.
3555 [AC_REQUIRE([AX_SOMETHING])dnl
3562 should be rewritten as
3565 AC_DEFUN([AX_FOOBAR],
3566 [AC_PREREQ([2.68])dnl
3567 AC_REQUIRE([AX_SOMETHING])dnl
3573 Wrapping the @code{AC_PREREQ} call inside the macro ensures that
3574 Autoconf 2.68 will not be required if @code{AX_FOOBAR} is not actually
3575 used. Most importantly, quoting the first argument of @code{AC_DEFUN}
3576 allows the macro to be redefined or included twice (otherwise this
3577 first argument would be expanded during the second definition). For
3578 consistency we like to quote even arguments such as @code{2.68} that
3581 If you have been directed here by the @command{aclocal} diagnostic but
3582 are not the maintainer of the implicated macro, you will want to
3583 contact the maintainer of that macro. Please make sure you have the
3584 latest version of the macro and that the problem hasn't already been
3585 reported before doing so: people tend to work faster when they aren't
3588 Another situation where @command{aclocal} is commonly used is to
3589 manage macros that are used locally by the package, @ref{Local
3593 @subsection Handling Local Macros
3595 Feature tests offered by Autoconf do not cover all needs. People
3596 often have to supplement existing tests with their own macros, or
3597 with third-party macros.
3599 There are two ways to organize custom macros in a package.
3601 The first possibility (the historical practice) is to list all your
3602 macros in @file{acinclude.m4}. This file will be included in
3603 @file{aclocal.m4} when you run @command{aclocal}, and its macro(s) will
3604 henceforth be visible to @command{autoconf}. However if it contains
3605 numerous macros, it will rapidly become difficult to maintain, and it
3606 will be almost impossible to share macros between packages.
3608 The second possibility, which we do recommend, is to write each macro
3609 in its own file and gather all these files in a directory. This
3610 directory is usually called @file{m4/}. Then it's enough to update
3611 @file{configure.ac} by adding a proper call to @code{AC_CONFIG_MACRO_DIRS}:
3614 AC_CONFIG_MACRO_DIRS([m4])
3617 @command{aclocal} will then take care of automatically adding @file{m4/}
3618 to its search path for m4 files.
3620 When @samp{aclocal} is run, it will build an @file{aclocal.m4}
3621 that @code{m4_include}s any file from @file{m4/} that defines a
3622 required macro. Macros not found locally will still be searched in
3623 system-wide directories, as explained in @ref{Macro Search Path}.
3625 Custom macros should be distributed for the same reason that
3626 @file{configure.ac} is: so that other people have all the sources of
3627 your package if they want to work on it. Actually, this distribution
3628 happens automatically because all @code{m4_include}d files are
3631 However there is no consensus on the distribution of third-party
3632 macros that your package may use. Many libraries install their own
3633 macro in the system-wide @command{aclocal} directory (@pxref{Extending
3634 aclocal}). For instance, Guile ships with a file called
3635 @file{guile.m4} that contains the macro @code{GUILE_FLAGS} that can
3636 be used to define setup compiler and linker flags appropriate for
3637 using Guile. Using @code{GUILE_FLAGS} in @file{configure.ac} will
3638 cause @command{aclocal} to copy @file{guile.m4} into
3639 @file{aclocal.m4}, but as @file{guile.m4} is not part of the project,
3640 it will not be distributed. Technically, that means a user who
3641 needs to rebuild @file{aclocal.m4} will have to install Guile first.
3642 This is probably OK, if Guile already is a requirement to build the
3643 package. However, if Guile is only an optional feature, or if your
3644 package might run on architectures where Guile cannot be installed,
3645 this requirement will hinder development. An easy solution is to copy
3646 such third-party macros in your local @file{m4/} directory so they get
3649 Since Automake 1.10, @command{aclocal} offers the option @code{--install}
3650 to copy these system-wide third-party macros in your local macro directory,
3651 helping to solve the above problem.
3653 With this setup, system-wide macros will be copied to @file{m4/}
3654 the first time you run @command{aclocal}. Then the locally installed
3655 macros will have precedence over the system-wide installed macros
3656 each time @command{aclocal} is run again.
3658 One reason why you should keep @option{--install} in the flags even
3659 after the first run is that when you later edit @file{configure.ac}
3660 and depend on a new macro, this macro will be installed in your
3661 @file{m4/} automatically. Another one is that serial numbers
3662 (@pxref{Serials}) can be used to update the macros in your source tree
3663 automatically when new system-wide versions are installed. A serial
3664 number should be a single line of the form
3671 where @var{nnn} contains only digits and dots. It should appear in
3672 the M4 file before any macro definition. It is a good practice to
3673 maintain a serial number for each macro you distribute, even if you do
3674 not use the @option{--install} option of @command{aclocal}: this allows
3675 other people to use it.
3679 @subsection Serial Numbers
3680 @cindex serial numbers in macros
3681 @cindex macro serial numbers
3682 @cindex @code{#serial} syntax
3683 @cindex @command{aclocal} and serial numbers
3685 Because third-party macros defined in @file{*.m4} files are naturally
3686 shared between multiple projects, some people like to version them.
3687 This makes it easier to tell which of two M4 files is newer. Since at
3688 least 1996, the tradition is to use a @samp{#serial} line for this.
3690 A serial number should be a single line of the form
3693 # serial @var{version}
3697 where @var{version} is a version number containing only digits and
3698 dots. Usually people use a single integer, and they increment it each
3699 time they change the macro (hence the name of ``serial''). Such a
3700 line should appear in the M4 file before any macro definition.
3702 The @samp{#} must be the first character on the line,
3703 and it is OK to have extra words after the version, as in
3706 #serial @var{version} @var{garbage}
3709 Normally these serial numbers are completely ignored by
3710 @command{aclocal} and @command{autoconf}, like any genuine comment.
3711 However when using @command{aclocal}'s @option{--install} feature, these
3712 serial numbers will modify the way @command{aclocal} selects the
3713 macros to install in the package: if two files with the same basename
3714 exist in your search path, and if at least one of them uses a
3715 @samp{#serial} line, @command{aclocal} will ignore the file that has
3716 the older @samp{#serial} line (or the file that has none).
3718 Note that a serial number applies to a whole M4 file, not to any macro
3719 it contains. A file can contains multiple macros, but only one
3722 Here is a use case that illustrates the use of @option{--install} and
3723 its interaction with serial numbers. Let's assume we maintain a
3724 package called MyPackage, the @file{configure.ac} of which requires a
3725 third-party macro @code{AX_THIRD_PARTY} defined in
3726 @file{/usr/share/aclocal/thirdparty.m4} as follows:
3730 AC_DEFUN([AX_THIRD_PARTY], [...])
3733 MyPackage uses an @file{m4/} directory to store local macros as
3734 explained in @ref{Local Macros}, and has
3737 AC_CONFIG_MACRO_DIRS([m4])
3741 in its @file{configure.ac}.
3743 Initially the @file{m4/} directory is empty. The first time we run
3744 @command{aclocal --install}, it will notice that
3748 @file{configure.ac} uses @code{AX_THIRD_PARTY}
3750 No local macros define @code{AX_THIRD_PARTY}
3752 @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3757 Because @file{/usr/share/aclocal/thirdparty.m4} is a system-wide macro
3758 and @command{aclocal} was given the @option{--install} option, it will
3759 copy this file in @file{m4/thirdparty.m4}, and output an
3760 @file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}.
3762 The next time @samp{aclocal --install} is run, something different
3763 happens. @command{aclocal} notices that
3767 @file{configure.ac} uses @code{AX_THIRD_PARTY}
3769 @file{m4/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3772 @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3777 Because both files have the same serial number, @command{aclocal} uses
3778 the first it found in its search path order (@pxref{Macro Search
3779 Path}). @command{aclocal} therefore ignores
3780 @file{/usr/share/aclocal/thirdparty.m4} and outputs an
3781 @file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}.
3783 Local directories specified with @option{-I} are always searched before
3784 system-wide directories, so a local file will always be preferred to
3785 the system-wide file in case of equal serial numbers.
3787 Now suppose the system-wide third-party macro is changed. This can
3788 happen if the package installing this macro is updated. Let's suppose
3789 the new macro has serial number 2. The next time @samp{aclocal --install}
3790 is run the situation is the following:
3794 @file{configure.ac} uses @code{AX_THIRD_PARTY}
3796 @file{m4/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3799 @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3804 When @command{aclocal} sees a greater serial number, it immediately
3805 forgets anything it knows from files that have the same basename and a
3806 smaller serial number. So after it has found
3807 @file{/usr/share/aclocal/thirdparty.m4} with serial 2,
3808 @command{aclocal} will proceed as if it had never seen
3809 @file{m4/thirdparty.m4}. This brings us back to a situation similar
3810 to that at the beginning of our example, where no local file defined
3811 the macro. @command{aclocal} will install the new version of the
3812 macro in @file{m4/thirdparty.m4}, in this case overriding the old
3813 version. MyPackage just had its macro updated as a side effect of
3814 running @command{aclocal}.
3816 If you are leery of letting @command{aclocal} update your local
3817 macro, you can run @samp{aclocal --diff} to review the changes
3818 @samp{aclocal --install} would perform on these macros.
3820 Finally, note that the @option{--force} option of @command{aclocal} has
3821 absolutely no effect on the files installed by @option{--install}. For
3822 instance, if you have modified your local macros, do not expect
3823 @option{--install --force} to replace the local macros by their
3824 system-wide versions. If you want to do so, simply erase the local
3825 macros you want to revert, and run @samp{aclocal --install}.
3828 @node Future of aclocal
3829 @subsection The Future of @command{aclocal}
3830 @cindex @command{aclocal}'s scheduled death
3832 @command{aclocal} is expected to disappear. This feature really
3833 should not be offered by Automake. Automake should focus on
3834 generating @file{Makefile}s; dealing with M4 macros really is
3835 Autoconf's job. The fact that some people install Automake just to use
3836 @command{aclocal}, but do not use @command{automake} otherwise is an
3837 indication of how that feature is misplaced.
3839 The new implementation will probably be done slightly differently.
3840 For instance, it could enforce the @file{m4/}-style layout discussed in
3843 We have no idea when and how this will happen. This has been
3844 discussed several times in the past, but someone still has to commit
3845 to that non-trivial task.
3847 From the user point of view, @command{aclocal}'s removal might turn
3848 out to be painful. There is a simple precaution that you may take to
3849 make that switch more seamless: never call @command{aclocal} yourself.
3850 Keep this guy under the exclusive control of @command{autoreconf} and
3851 Automake's rebuild rules. Hopefully you won't need to worry about
3852 things breaking, when @command{aclocal} disappears, because everything
3853 will have been taken care of. If otherwise you used to call
3854 @command{aclocal} directly yourself or from some script, you will
3855 quickly notice the change.
3857 Many packages come with a script called @file{bootstrap.sh} or
3858 @file{autogen.sh}, that will just call @command{aclocal},
3859 @command{libtoolize}, @command{gettextize} or @command{autopoint},
3860 @command{autoconf}, @command{autoheader}, and @command{automake} in
3861 the right order. Actually this is precisely what @command{autoreconf}
3862 can do for you. If your package has such a @file{bootstrap.sh} or
3863 @file{autogen.sh} script, consider using @command{autoreconf}. That
3864 should simplify its logic a lot (less things to maintain, yum!), it's
3865 even likely you will not need the script anymore, and more to the point
3866 you will not call @command{aclocal} directly anymore.
3868 For the time being, third-party packages should continue to install
3869 public macros into @file{/usr/share/aclocal/}. If @command{aclocal}
3870 is replaced by another tool it might make sense to rename the
3871 directory, but supporting @file{/usr/share/aclocal/} for backward
3872 compatibility should be really easy provided all macros are properly
3873 written (@pxref{Extending aclocal}).
3878 @section Autoconf macros supplied with Automake
3880 Automake ships with several Autoconf macros that you can use from your
3881 @file{configure.ac}. When you use one of them it will be included by
3882 @command{aclocal} in @file{aclocal.m4}.
3885 * Public Macros:: Macros that you can use.
3886 * Obsolete Macros:: Macros that will soon be removed.
3887 * Private Macros:: Macros that you should not use.
3890 @c consider generating the following subsections automatically from m4 files.
3893 @subsection Public Macros
3897 @item AM_INIT_AUTOMAKE([OPTIONS])
3898 @acindex AM_INIT_AUTOMAKE
3899 Runs many macros required for proper operation of the generated Makefiles.
3901 @vindex AUTOMAKE_OPTIONS
3902 Today, @code{AM_INIT_AUTOMAKE} is called with a single argument: a
3903 space-separated list of Automake options that should be applied to
3904 every @file{Makefile.am} in the tree. The effect is as if
3905 each option were listed in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
3908 This macro can also be called in another, @emph{deprecated} form:
3909 @code{AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])}. In this form,
3910 there are two required arguments: the package and the version number.
3911 This usage is mostly obsolete because the @var{package} and @var{version}
3912 can be obtained from Autoconf's @code{AC_INIT} macro. However,
3913 differently from what happens for @code{AC_INIT} invocations, this
3914 @code{AM_INIT_AUTOMAKE} invocation supports shell variables' expansions
3915 in the @code{PACKAGE} and @code{VERSION} arguments, and this can be
3916 still be useful in some selected situations. Our hope is that future
3917 Autoconf versions will improve their support for package versions
3918 defined dynamically at configure runtime; when (and if) this happens,
3919 support for the two-args @code{AM_INIT_AUTOMAKE} invocation will likely
3920 be removed from Automake.
3922 @anchor{Modernize AM_INIT_AUTOMAKE invocation}
3923 If your @file{configure.ac} has:
3926 AC_INIT([src/foo.c])
3927 AM_INIT_AUTOMAKE([mumble], [1.5])
3931 you should modernize it as follows:
3934 AC_INIT([mumble], [1.5])
3935 AC_CONFIG_SRCDIR([src/foo.c])
3939 Note that if you're upgrading your @file{configure.ac} from an earlier
3940 version of Automake, it is not always correct to simply move the
3941 package and version arguments from @code{AM_INIT_AUTOMAKE} directly to
3942 @code{AC_INIT}, as in the example above. The first argument to
3943 @code{AC_INIT} should be the name of your package (e.g., @samp{GNU
3944 Automake}), not the tarball name (e.g., @samp{automake}) that you used
3945 to pass to @code{AM_INIT_AUTOMAKE}. Autoconf tries to derive a
3946 tarball name from the package name, which should work for most but not
3947 all package names. (If it doesn't work for yours, you can use the
3948 four-argument form of @code{AC_INIT} to provide the tarball name
3951 @cindex @code{PACKAGE}, prevent definition
3952 @cindex @code{VERSION}, prevent definition
3954 By default this macro @code{AC_DEFINE}'s @code{PACKAGE} and
3955 @code{VERSION}. This can be avoided by passing the @option{no-define}
3956 option (@pxref{List of Automake options}):
3958 AM_INIT_AUTOMAKE([no-define ...])
3961 @item AM_PATH_LISPDIR
3962 @acindex AM_PATH_LISPDIR
3965 Searches for the program @command{emacs}, and, if found, sets the
3966 output variable @code{lispdir} to the full path to Emacs' site-lisp
3969 Note that this test assumes the @command{emacs} found to be a version
3970 that supports Emacs Lisp (such as GNU Emacs or XEmacs). Other
3971 emacsen can cause this test to hang (some, like old versions of
3972 MicroEmacs, start up in interactive mode, requiring @kbd{C-x C-c} to
3973 exit, which is hardly obvious for a non-emacs user). In most cases,
3974 however, you should be able to use @kbd{C-c} to kill the test. In
3975 order to avoid problems, you can set @env{EMACS} to ``no'' in the
3976 environment, or use the @option{--with-lispdir} option to
3977 @command{configure} to explicitly set the correct path (if you're sure
3978 you have an @command{emacs} that supports Emacs Lisp).
3980 @item AM_PROG_AR(@ovar{act-if-fail})
3983 You must use this macro when you use the archiver in your project, if
3984 you want support for unusual archivers such as Microsoft @command{lib}.
3985 The content of the optional argument is executed if the archiver
3986 interface is not recognized; the default action is to abort configure
3987 with an error message.
3993 Use this macro when you have assembly code in your project. This will
3994 choose the assembler for you (by default the C compiler) and set
3995 @code{CCAS}, and will also set @code{CCASFLAGS} if required.
3997 @item AM_PROG_CC_C_O
3998 @acindex AM_PROG_CC_C_O
3999 This is an obsolescent macro that checks that the C compiler supports
4000 the @option{-c} and @option{-o} options together. Note that, since
4001 Automake 1.14, the @code{AC_PROG_CC} is rewritten to implement such
4002 checks itself, and thus the explicit use of @code{AM_PROG_CC_C_O}
4003 should no longer be required.
4006 @acindex AM_PROG_LEX
4007 @acindex AC_PROG_LEX
4008 @cindex HP-UX 10, @command{lex} problems
4009 @cindex @command{lex} problems with HP-UX 10
4010 Like @code{AC_PROG_LEX} (@pxref{Particular Programs, , Particular
4011 Program Checks, autoconf, The Autoconf Manual}), but uses the
4012 @command{missing} script on systems that do not have @command{lex}.
4013 HP-UX 10 is one such system.
4016 @acindex AM_PROG_GCJ
4019 This macro finds the @command{gcj} program or causes an error. It sets
4020 @code{GCJ} and @code{GCJFLAGS}. @command{gcj} is the Java front-end to the
4021 GNU Compiler Collection.
4023 @item AM_PROG_UPC([@var{compiler-search-list}])
4024 @acindex AM_PROG_UPC
4026 Find a compiler for Unified Parallel C and define the @code{UPC}
4027 variable. The default @var{compiler-search-list} is @samp{upcc upc}.
4028 This macro will abort @command{configure} if no Unified Parallel C
4031 @item AM_MISSING_PROG(@var{name}, @var{program})
4032 @acindex AM_MISSING_PROG
4034 Find a maintainer tool @var{program} and define the @var{name}
4035 environment variable with its location. If @var{program} is not
4036 detected, then @var{name} will instead invoke the @command{missing}
4037 script, in order to give useful advice to the user about the missing
4038 maintainer tool. @xref{maintainer-mode}, for more information on when
4039 the @command{missing} script is appropriate.
4041 @item AM_SILENT_RULES
4042 @acindex AM_SILENT_RULES
4043 Control the machinery for less verbose build output
4044 (@pxref{Automake Silent Rules}).
4046 @item AM_WITH_DMALLOC
4047 @acindex AM_WITH_DMALLOC
4048 @cindex @command{dmalloc}, support for
4049 @vindex WITH_DMALLOC
4050 @opindex --with-dmalloc
4051 Add support for the @uref{http://dmalloc.com/, Dmalloc package}. If
4052 the user runs @command{configure} with @option{--with-dmalloc}, then
4053 define @code{WITH_DMALLOC} and add @option{-ldmalloc} to @code{LIBS}.
4058 @node Obsolete Macros
4059 @subsection Obsolete Macros
4060 @cindex obsolete macros
4063 Although using some of the following macros was required in past
4064 releases, you should not use any of them in new code. @emph{All
4065 these macros will be removed in the next major Automake version};
4066 if you are still using them, running @command{autoupdate} should
4067 adjust your @file{configure.ac} automatically (@pxref{autoupdate
4068 Invocation, , Using @command{autoupdate} to Modernize
4069 @file{configure.ac}, autoconf, The Autoconf Manual}).
4074 @item AM_PROG_MKDIR_P
4075 @acindex AM_PROG_MKDIR_P
4076 @cindex @code{mkdir -p}, macro check
4080 From Automake 1.8 to 1.9.6 this macro used to define the output
4081 variable @code{mkdir_p} to one of @code{mkdir -p}, @code{install-sh
4082 -d}, or @code{mkinstalldirs}.
4084 Nowadays Autoconf provides a similar functionality with
4085 @code{AC_PROG_MKDIR_P} (@pxref{Particular Programs, , Particular
4086 Program Checks, autoconf, The Autoconf Manual}), however this defines
4087 the output variable @code{MKDIR_P} instead. In case you are still
4088 using the @code{AM_PROG_MKDIR_P} macro in your @file{configure.ac},
4089 or its provided variable @code{$(mkdir_p)} in your @file{Makefile.am},
4090 you are advised to switch ASAP to the more modern Autoconf-provided
4091 interface instead; both the macro and the variable might be removed
4092 in a future major Automake release.
4097 @node Private Macros
4098 @subsection Private Macros
4100 The following macros are private macros you should not call directly.
4101 They are called by the other public macros when appropriate. Do not
4102 rely on them, as they might be changed in a future version. Consider
4103 them as implementation details; or better, do not consider them at all:
4107 @item _AM_DEPENDENCIES
4108 @itemx AM_SET_DEPDIR
4110 @itemx AM_OUTPUT_DEPENDENCY_COMMANDS
4111 These macros are used to implement Automake's automatic dependency
4112 tracking scheme. They are called automatically by Automake when
4113 required, and there should be no need to invoke them manually.
4115 @item AM_MAKE_INCLUDE
4116 This macro is used to discover how the user's @command{make} handles
4117 @code{include} statements. This macro is automatically invoked when
4118 needed; there should be no need to invoke it manually.
4120 @item AM_PROG_INSTALL_STRIP
4121 This is used to find a version of @code{install} that can be used to
4122 strip a program at installation time. This macro is automatically
4123 included when required.
4125 @item AM_SANITY_CHECK
4126 This checks to make sure that a file created in the build directory is
4127 newer than a file in the source directory. This can fail on systems
4128 where the clock is set incorrectly. This macro is automatically run
4129 from @code{AM_INIT_AUTOMAKE}.
4135 @chapter Directories
4137 For simple projects that distribute all files in the same directory
4138 it is enough to have a single @file{Makefile.am} that builds
4139 everything in place.
4141 In larger projects, it is common to organize files in different
4142 directories, in a tree. For example, there could be a directory
4143 for the program's source, one for the testsuite, and one for the
4144 documentation; or, for very large projects, there could be one
4145 directory per program, per library or per module.
4147 The traditional approach is to build these subdirectories recursively,
4148 employing @emph{make recursion}: each directory contains its
4149 own @file{Makefile}, and when @command{make} is run from the top-level
4150 directory, it enters each subdirectory in turn, and invokes there a
4151 new @command{make} instance to build the directory's contents.
4153 Because this approach is very widespread, Automake offers built-in
4154 support for it. However, it is worth nothing that the use of make
4155 recursion has its own serious issues and drawbacks, and that it's
4156 well possible to have packages with a multi directory layout that
4157 make little or no use of such recursion (examples of such packages
4158 are GNU Bison and GNU Automake itself); see also the @ref{Alternative}
4162 * Subdirectories:: Building subdirectories recursively
4163 * Conditional Subdirectories:: Conditionally not building directories
4164 * Alternative:: Subdirectories without recursion
4165 * Subpackages:: Nesting packages
4168 @node Subdirectories
4169 @section Recursing subdirectories
4171 @cindex @code{SUBDIRS}, explained
4173 In packages using make recursion, the top level @file{Makefile.am} must
4174 tell Automake which subdirectories are to be built. This is done via
4175 the @code{SUBDIRS} variable.
4178 The @code{SUBDIRS} variable holds a list of subdirectories in which
4179 building of various sorts can occur. The rules for many targets
4180 (e.g., @code{all}) in the generated @file{Makefile} will run commands
4181 both locally and in all specified subdirectories. Note that the
4182 directories listed in @code{SUBDIRS} are not required to contain
4183 @file{Makefile.am}s; only @file{Makefile}s (after configuration).
4184 This allows inclusion of libraries from packages that do not use
4185 Automake (such as @code{gettext}; see also @ref{Third-Party
4188 In packages that use subdirectories, the top-level @file{Makefile.am} is
4189 often very short. For instance, here is the @file{Makefile.am} from the
4190 GNU Hello distribution:
4193 EXTRA_DIST = BUGS ChangeLog.O README-alpha
4194 SUBDIRS = doc intl po src tests
4197 When Automake invokes @command{make} in a subdirectory, it uses the value
4198 of the @code{MAKE} variable. It passes the value of the variable
4199 @code{AM_MAKEFLAGS} to the @command{make} invocation; this can be set in
4200 @file{Makefile.am} if there are flags you must always pass to
4203 @vindex AM_MAKEFLAGS
4205 The directories mentioned in @code{SUBDIRS} are usually direct
4206 children of the current directory, each subdirectory containing its
4207 own @file{Makefile.am} with a @code{SUBDIRS} pointing to deeper
4208 subdirectories. Automake can be used to construct packages of
4209 arbitrary depth this way.
4211 By default, Automake generates @file{Makefiles} that work depth-first
4212 in postfix order: the subdirectories are built before the current
4213 directory. However, it is possible to change this ordering. You can
4214 do this by putting @samp{.} into @code{SUBDIRS}. For instance,
4215 putting @samp{.} first will cause a prefix ordering of
4221 SUBDIRS = lib src . test
4225 will cause @file{lib/} to be built before @file{src/}, then the
4226 current directory will be built, finally the @file{test/} directory
4227 will be built. It is customary to arrange test directories to be
4228 built after everything else since they are meant to test what has
4231 In addition to the built-in recursive targets defined by Automake
4232 (@code{all}, @code{check}, etc.), the developer can also define his
4233 own recursive targets. That is done by passing the names of such
4234 targets as arguments to the m4 macro @code{AM_EXTRA_RECURSIVE_TARGETS}
4235 in @file{configure.ac}. Automake generates rules to handle the
4236 recursion for such targets; and the developer can define real actions
4237 for them by defining corresponding @code{-local} targets.
4240 % @kbd{cat configure.ac}
4241 AC_INIT([pkg-name], [1.0]
4243 AM_EXTRA_RECURSIVE_TARGETS([foo])
4244 AC_CONFIG_FILES([Makefile sub/Makefile sub/src/Makefile])
4246 % @kbd{cat Makefile.am}
4249 @@echo This will be run by "make foo".
4250 % @kbd{cat sub/Makefile.am}
4252 % @kbd{cat sub/src/Makefile.am}
4254 @@echo This too will be run by a "make foo" issued either in
4255 @@echo the 'sub/src/' directory, the 'sub/' directory, or the
4256 @@echo top-level directory.
4259 @node Conditional Subdirectories
4260 @section Conditional Subdirectories
4261 @cindex Subdirectories, building conditionally
4262 @cindex Conditional subdirectories
4263 @cindex @code{SUBDIRS}, conditional
4264 @cindex Conditional @code{SUBDIRS}
4266 It is possible to define the @code{SUBDIRS} variable conditionally if,
4267 like in the case of GNU Inetutils, you want to only build a subset of
4270 To illustrate how this works, let's assume we have two directories
4271 @file{src/} and @file{opt/}. @file{src/} should always be built, but we
4272 want to decide in @command{configure} whether @file{opt/} will be built
4273 or not. (For this example we will assume that @file{opt/} should be
4274 built when the variable @samp{$want_opt} was set to @samp{yes}.)
4276 Running @command{make} should thus recurse into @file{src/} always, and
4277 then maybe in @file{opt/}.
4279 However @samp{make dist} should always recurse into both @file{src/}
4280 and @file{opt/}. Because @file{opt/} should be distributed even if it
4281 is not needed in the current configuration. This means
4282 @file{opt/Makefile} should be created @emph{unconditionally}.
4284 There are two ways to setup a project like this. You can use Automake
4285 conditionals (@pxref{Conditionals}) or use Autoconf @code{AC_SUBST}
4286 variables (@pxref{Setting Output Variables, , Setting Output
4287 Variables, autoconf, The Autoconf Manual}). Using Automake
4288 conditionals is the preferred solution. Before we illustrate these
4289 two possibilities, let's introduce @code{DIST_SUBDIRS}.
4292 * SUBDIRS vs DIST_SUBDIRS:: Two sets of directories
4293 * Subdirectories with AM_CONDITIONAL:: Specifying conditional subdirectories
4294 * Subdirectories with AC_SUBST:: Another way for conditional recursion
4295 * Unconfigured Subdirectories:: Not even creating a @samp{Makefile}
4298 @node SUBDIRS vs DIST_SUBDIRS
4299 @subsection @code{SUBDIRS} vs.@: @code{DIST_SUBDIRS}
4300 @cindex @code{DIST_SUBDIRS}, explained
4302 Automake considers two sets of directories, defined by the variables
4303 @code{SUBDIRS} and @code{DIST_SUBDIRS}.
4305 @code{SUBDIRS} contains the subdirectories of the current directory
4306 that must be built (@pxref{Subdirectories}). It must be defined
4307 manually; Automake will never guess a directory is to be built. As we
4308 will see in the next two sections, it is possible to define it
4309 conditionally so that some directory will be omitted from the build.
4311 @code{DIST_SUBDIRS} is used in rules that need to recurse in all
4312 directories, even those that have been conditionally left out of the
4313 build. Recall our example where we may not want to build subdirectory
4314 @file{opt/}, but yet we want to distribute it? This is where
4315 @code{DIST_SUBDIRS} comes into play: @samp{opt} may not appear in
4316 @code{SUBDIRS}, but it must appear in @code{DIST_SUBDIRS}.
4318 Precisely, @code{DIST_SUBDIRS} is used by @samp{make
4319 maintainer-clean}, @samp{make distclean} and @samp{make dist}. All
4320 other recursive rules use @code{SUBDIRS}.
4322 If @code{SUBDIRS} is defined conditionally using Automake
4323 conditionals, Automake will define @code{DIST_SUBDIRS} automatically
4324 from the possible values of @code{SUBDIRS} in all conditions.
4326 If @code{SUBDIRS} contains @code{AC_SUBST} variables,
4327 @code{DIST_SUBDIRS} will not be defined correctly because Automake
4328 does not know the possible values of these variables. In this case
4329 @code{DIST_SUBDIRS} needs to be defined manually.
4331 @node Subdirectories with AM_CONDITIONAL
4332 @subsection Subdirectories with @code{AM_CONDITIONAL}
4333 @cindex @code{SUBDIRS} and @code{AM_CONDITIONAL}
4334 @cindex @code{AM_CONDITIONAL} and @code{SUBDIRS}
4336 @c Keep in sync with subdir-am-cond.sh
4338 @file{configure} should output the @file{Makefile} for each directory
4339 and define a condition into which @file{opt/} should be built.
4343 AM_CONDITIONAL([COND_OPT], [test "$want_opt" = yes])
4344 AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
4348 Then @code{SUBDIRS} can be defined in the top-level @file{Makefile.am}
4355 SUBDIRS = src $(MAYBE_OPT)
4358 As you can see, running @command{make} will rightly recurse into
4359 @file{src/} and maybe @file{opt/}.
4361 @vindex DIST_SUBDIRS
4362 As you can't see, running @samp{make dist} will recurse into both
4363 @file{src/} and @file{opt/} directories because @samp{make dist}, unlike
4364 @samp{make all}, doesn't use the @code{SUBDIRS} variable. It uses the
4365 @code{DIST_SUBDIRS} variable.
4367 In this case Automake will define @samp{DIST_SUBDIRS = src opt}
4368 automatically because it knows that @code{MAYBE_OPT} can contain
4369 @samp{opt} in some condition.
4371 @node Subdirectories with AC_SUBST
4372 @subsection Subdirectories with @code{AC_SUBST}
4373 @cindex @code{SUBDIRS} and @code{AC_SUBST}
4374 @cindex @code{AC_SUBST} and @code{SUBDIRS}
4376 @c Keep in sync with subdir-ac-subst.sh
4378 Another possibility is to define @code{MAYBE_OPT} from
4379 @file{./configure} using @code{AC_SUBST}:
4383 if test "$want_opt" = yes; then
4388 AC_SUBST([MAYBE_OPT])
4389 AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
4393 In this case the top-level @file{Makefile.am} should look as follows.
4396 SUBDIRS = src $(MAYBE_OPT)
4397 DIST_SUBDIRS = src opt
4400 The drawback is that since Automake cannot guess what the possible
4401 values of @code{MAYBE_OPT} are, it is necessary to define
4402 @code{DIST_SUBDIRS}.
4404 @node Unconfigured Subdirectories
4405 @subsection Unconfigured Subdirectories
4406 @cindex Subdirectories, configured conditionally
4408 The semantics of @code{DIST_SUBDIRS} are often misunderstood by some
4409 users that try to @emph{configure and build} subdirectories
4410 conditionally. Here by configuring we mean creating the
4411 @file{Makefile} (it might also involve running a nested
4412 @command{configure} script: this is a costly operation that explains
4413 why people want to do it conditionally, but only the @file{Makefile}
4414 is relevant to the discussion).
4416 The above examples all assume that every @file{Makefile} is created,
4417 even in directories that are not going to be built. The simple reason
4418 is that we want @samp{make dist} to distribute even the directories
4419 that are not being built (e.g., platform-dependent code), hence
4420 @file{make dist} must recurse into the subdirectory, hence this
4421 directory must be configured and appear in @code{DIST_SUBDIRS}.
4423 Building packages that do not configure every subdirectory is a tricky
4424 business, and we do not recommend it to the novice as it is easy to
4425 produce an incomplete tarball by mistake. We will not discuss this
4426 topic in depth here, yet for the adventurous here are a few rules to
4431 @item @code{SUBDIRS} should always be a subset of @code{DIST_SUBDIRS}.
4433 It makes little sense to have a directory in @code{SUBDIRS} that
4434 is not in @code{DIST_SUBDIRS}. Think of the former as a way to tell
4435 which directories listed in the latter should be built.
4436 @item Any directory listed in @code{DIST_SUBDIRS} and @code{SUBDIRS}
4439 I.e., the @file{Makefile} must exists or the recursive @command{make}
4440 rules will not be able to process the directory.
4441 @item Any configured directory must be listed in @code{DIST_SUBDIRS}.
4443 So that the cleaning rules remove the generated @file{Makefile}s.
4444 It would be correct to see @code{DIST_SUBDIRS} as a variable that
4445 lists all the directories that have been configured.
4449 In order to prevent recursion in some unconfigured directory you
4450 must therefore ensure that this directory does not appear in
4451 @code{DIST_SUBDIRS} (and @code{SUBDIRS}). For instance, if you define
4452 @code{SUBDIRS} conditionally using @code{AC_SUBST} and do not define
4453 @code{DIST_SUBDIRS} explicitly, it will be default to
4454 @samp{$(SUBDIRS)}; another possibility is to force @code{DIST_SUBDIRS
4457 Of course, directories that are omitted from @code{DIST_SUBDIRS} will
4458 not be distributed unless you make other arrangements for this to
4459 happen (for instance, always running @samp{make dist} in a
4460 configuration where all directories are known to appear in
4461 @code{DIST_SUBDIRS}; or writing a @code{dist-hook} target to
4462 distribute these directories).
4464 @cindex Subdirectories, not distributed
4465 In few packages, unconfigured directories are not even expected to
4466 be distributed. Although these packages do not require the
4467 aforementioned extra arrangements, there is another pitfall. If the
4468 name of a directory appears in @code{SUBDIRS} or @code{DIST_SUBDIRS},
4469 @command{automake} will make sure the directory exists. Consequently
4470 @command{automake} cannot be run on such a distribution when one
4471 directory has been omitted. One way to avoid this check is to use the
4472 @code{AC_SUBST} method to declare conditional directories; since
4473 @command{automake} does not know the values of @code{AC_SUBST}
4474 variables it cannot ensure the corresponding directory exists.
4477 @section An Alternative Approach to Subdirectories
4479 If you've ever read Peter Miller's excellent paper,
4480 @uref{http://miller.emu.id.au/pmiller/books/rmch/,
4481 Recursive Make Considered Harmful}, the preceding sections on the use of
4482 make recursion will probably come as unwelcome advice. For those who
4483 haven't read the paper, Miller's main thesis is that recursive
4484 @command{make} invocations are both slow and error-prone.
4486 Automake provides sufficient cross-directory support @footnote{We
4487 believe. This work is new and there are probably warts.
4488 @xref{Introduction}, for information on reporting bugs.} to enable you
4489 to write a single @file{Makefile.am} for a complex multi-directory
4492 By default an installable file specified in a subdirectory will have its
4493 directory name stripped before installation. For instance, in this
4494 example, the header file will be installed as
4495 @file{$(includedir)/stdio.h}:
4498 include_HEADERS = inc/stdio.h
4502 @cindex @code{nobase_} prefix
4503 @cindex Path stripping, avoiding
4504 @cindex Avoiding path stripping
4506 However, the @samp{nobase_} prefix can be used to circumvent this path
4507 stripping. In this example, the header file will be installed as
4508 @file{$(includedir)/sys/types.h}:
4511 nobase_include_HEADERS = sys/types.h
4514 @cindex @code{nobase_} and @code{dist_} or @code{nodist_}
4515 @cindex @code{dist_} and @code{nobase_}
4516 @cindex @code{nodist_} and @code{nobase_}
4520 @samp{nobase_} should be specified first when used in conjunction with
4521 either @samp{dist_} or @samp{nodist_} (@pxref{Fine-grained Distribution
4522 Control}). For instance:
4525 nobase_dist_pkgdata_DATA = images/vortex.pgm sounds/whirl.ogg
4528 Finally, note that a variable using the @samp{nobase_} prefix can
4529 often be replaced by several variables, one for each destination
4530 directory (@pxref{Uniform}). For instance, the last example could be
4531 rewritten as follows:
4533 @c Keep in sync with primary-prefix-couples-documented-valid.sh
4535 imagesdir = $(pkgdatadir)/images
4536 soundsdir = $(pkgdatadir)/sounds
4537 dist_images_DATA = images/vortex.pgm
4538 dist_sounds_DATA = sounds/whirl.ogg
4542 This latter syntax makes it possible to change one destination
4543 directory without changing the layout of the source tree.
4545 Currently, @samp{nobase_*_LTLIBRARIES} are the only exception to this
4546 rule, in that there is no particular installation order guarantee for
4547 an otherwise equivalent set of variables without @samp{nobase_} prefix.
4550 @section Nesting Packages
4551 @cindex Nesting packages
4553 @acindex AC_CONFIG_SUBDIRS
4554 @acindex AC_CONFIG_AUX_DIR
4557 In the GNU Build System, packages can be nested to arbitrary depth.
4558 This means that a package can embed other packages with their own
4559 @file{configure}, @file{Makefile}s, etc.
4561 These other packages should just appear as subdirectories of their
4562 parent package. They must be listed in @code{SUBDIRS} like other
4563 ordinary directories. However the subpackage's @file{Makefile}s
4564 should be output by its own @file{configure} script, not by the
4565 parent's @file{configure}. This is achieved using the
4566 @code{AC_CONFIG_SUBDIRS} Autoconf macro (@pxref{Subdirectories,
4567 AC_CONFIG_SUBDIRS, Configuring Other Packages in Subdirectories,
4568 autoconf, The Autoconf Manual}).
4570 Here is an example package for an @code{arm} program that links with
4571 a @code{hand} library that is a nested package in subdirectory
4574 @code{arm}'s @file{configure.ac}:
4577 AC_INIT([arm], [1.0])
4578 AC_CONFIG_AUX_DIR([.])
4581 AC_CONFIG_FILES([Makefile])
4582 # Call hand's ./configure script recursively.
4583 AC_CONFIG_SUBDIRS([hand])
4587 @code{arm}'s @file{Makefile.am}:
4590 # Build the library in the hand subdirectory first.
4593 # Include hand's header when compiling this directory.
4594 AM_CPPFLAGS = -I$(srcdir)/hand
4598 # link with the hand library.
4599 arm_LDADD = hand/libhand.a
4602 Now here is @code{hand}'s @file{hand/configure.ac}:
4605 AC_INIT([hand], [1.2])
4606 AC_CONFIG_AUX_DIR([.])
4611 AC_CONFIG_FILES([Makefile])
4616 and its @file{hand/Makefile.am}:
4619 lib_LIBRARIES = libhand.a
4620 libhand_a_SOURCES = hand.c
4623 When @samp{make dist} is run from the top-level directory it will
4624 create an archive @file{arm-1.0.tar.gz} that contains the @code{arm}
4625 code as well as the @file{hand} subdirectory. This package can be
4626 built and installed like any ordinary package, with the usual
4627 @samp{./configure && make && make install} sequence (the @code{hand}
4628 subpackage will be built and installed by the process).
4630 When @samp{make dist} is run from the hand directory, it will create a
4631 self-contained @file{hand-1.2.tar.gz} archive. So although it appears
4632 to be embedded in another package, it can still be used separately.
4634 The purpose of the @samp{AC_CONFIG_AUX_DIR([.])} instruction is to
4635 force Automake and Autoconf to search for auxiliary scripts in the
4636 current directory. For instance, this means that there will be two
4637 copies of @file{install-sh}: one in the top-level of the @code{arm}
4638 package, and another one in the @file{hand/} subdirectory for the
4639 @code{hand} package.
4641 The historical default is to search for these auxiliary scripts in
4642 the parent directory and the grandparent directory. So if the
4643 @samp{AC_CONFIG_AUX_DIR([.])} line was removed from
4644 @file{hand/configure.ac}, that subpackage would share the auxiliary
4645 script of the @code{arm} package. This may looks like a gain in size
4646 (a few kilobytes), but it is actually a loss of modularity as the
4647 @code{hand} subpackage is no longer self-contained (@samp{make dist}
4648 in the subdirectory will not work anymore).
4650 Packages that do not use Automake need more work to be integrated this
4651 way. @xref{Third-Party Makefiles}.
4654 @chapter Building Programs and Libraries
4656 A large part of Automake's functionality is dedicated to making it easy
4657 to build programs and libraries.
4660 * A Program:: Building a program
4661 * A Library:: Building a library
4662 * A Shared Library:: Building a Libtool library
4663 * Program and Library Variables:: Variables controlling program and
4665 * Default _SOURCES:: Default source files
4666 * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
4667 * Program Variables:: Variables used when building a program
4668 * Yacc and Lex:: Yacc and Lex support
4669 * C++ Support:: Compiling C++ sources
4670 * Objective C Support:: Compiling Objective C sources
4671 * Objective C++ Support:: Compiling Objective C++ sources
4672 * Unified Parallel C Support:: Compiling Unified Parallel C sources
4673 * Assembly Support:: Compiling assembly sources
4674 * Fortran 77 Support:: Compiling Fortran 77 sources
4675 * Fortran 9x Support:: Compiling Fortran 9x sources
4676 * Java Support with gcj:: Compiling Java sources using gcj
4677 * Vala Support:: Compiling Vala sources
4678 * Support for Other Languages:: Compiling other languages
4679 * Dependencies:: Automatic dependency tracking
4680 * EXEEXT:: Support for executable extensions
4685 @section Building a program
4687 In order to build a program, you need to tell Automake which sources
4688 are part of it, and which libraries it should be linked with.
4690 This section also covers conditional compilation of sources or
4691 programs. Most of the comments about these also apply to libraries
4692 (@pxref{A Library}) and libtool libraries (@pxref{A Shared Library}).
4695 * Program Sources:: Defining program sources
4696 * Linking:: Linking with libraries or extra objects
4697 * Conditional Sources:: Handling conditional sources
4698 * Conditional Programs:: Building a program conditionally
4701 @node Program Sources
4702 @subsection Defining program sources
4704 @cindex @code{PROGRAMS}, @code{bindir}
4706 @vindex bin_PROGRAMS
4707 @vindex sbin_PROGRAMS
4708 @vindex libexec_PROGRAMS
4709 @vindex pkglibexec_PROGRAMS
4710 @vindex noinst_PROGRAMS
4711 @vindex check_PROGRAMS
4713 In a directory containing source that gets built into a program (as
4714 opposed to a library or a script), the @code{PROGRAMS} primary is used.
4715 Programs can be installed in @code{bindir}, @code{sbindir},
4716 @code{libexecdir}, @code{pkglibexecdir}, or not at all
4717 (@code{noinst_}). They can also be built only for @samp{make check}, in
4718 which case the prefix is @samp{check_}.
4723 bin_PROGRAMS = hello
4726 In this simple case, the resulting @file{Makefile.in} will contain code
4727 to generate a program named @code{hello}.
4729 Associated with each program are several assisting variables that are
4730 named after the program. These variables are all optional, and have
4731 reasonable defaults. Each variable, its use, and default is spelled out
4732 below; we use the ``hello'' example throughout.
4734 The variable @code{hello_SOURCES} is used to specify which source files
4735 get built into an executable:
4738 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
4741 This causes each mentioned @file{.c} file to be compiled into the
4742 corresponding @file{.o}. Then all are linked to produce @file{hello}.
4744 @cindex @code{_SOURCES} primary, defined
4745 @cindex @code{SOURCES} primary, defined
4746 @cindex Primary variable, @code{SOURCES}
4749 If @code{hello_SOURCES} is not specified, then it defaults to the single
4750 file @file{hello.c} (@pxref{Default _SOURCES}).
4754 Multiple programs can be built in a single directory. Multiple programs
4755 can share a single source file, which must be listed in each
4756 @code{_SOURCES} definition.
4758 @cindex Header files in @code{_SOURCES}
4759 @cindex @code{_SOURCES} and header files
4761 Header files listed in a @code{_SOURCES} definition will be included in
4762 the distribution but otherwise ignored. In case it isn't obvious, you
4763 should not include the header file generated by @file{configure} in a
4764 @code{_SOURCES} variable; this file should not be distributed. Lex
4765 (@file{.l}) and Yacc (@file{.y}) files can also be listed; see @ref{Yacc
4770 @subsection Linking the program
4772 If you need to link against libraries that are not found by
4773 @command{configure}, you can use @code{LDADD} to do so. This variable is
4774 used to specify additional objects or libraries to link with; it is
4775 inappropriate for specifying specific linker flags, you should use
4776 @code{AM_LDFLAGS} for this purpose.
4780 @cindex @code{prog_LDADD}, defined
4782 Sometimes, multiple programs are built in one directory but do not share
4783 the same link-time requirements. In this case, you can use the
4784 @code{@var{prog}_LDADD} variable (where @var{prog} is the name of the
4785 program as it appears in some @code{_PROGRAMS} variable, and usually
4786 written in lowercase) to override @code{LDADD}. If this variable exists
4787 for a given program, then that program is not linked using @code{LDADD}.
4790 For instance, in GNU cpio, @code{pax}, @code{cpio} and @code{mt} are
4791 linked against the library @file{libcpio.a}. However, @code{rmt} is
4792 built in the same directory, and has no such link requirement. Also,
4793 @code{mt} and @code{rmt} are only built on certain architectures. Here
4794 is what cpio's @file{src/Makefile.am} looks like (abridged):
4797 bin_PROGRAMS = cpio pax $(MT)
4798 libexec_PROGRAMS = $(RMT)
4799 EXTRA_PROGRAMS = mt rmt
4801 LDADD = ../lib/libcpio.a $(INTLLIBS)
4804 cpio_SOURCES = @dots{}
4805 pax_SOURCES = @dots{}
4806 mt_SOURCES = @dots{}
4807 rmt_SOURCES = @dots{}
4810 @cindex @code{_LDFLAGS}, defined
4811 @vindex maude_LDFLAGS
4812 @code{@var{prog}_LDADD} is inappropriate for passing program-specific
4813 linker flags (except for @option{-l}, @option{-L}, @option{-dlopen} and
4814 @option{-dlpreopen}). So, use the @code{@var{prog}_LDFLAGS} variable for
4817 @cindex @code{_DEPENDENCIES}, defined
4818 @vindex maude_DEPENDENCIES
4819 @vindex EXTRA_maude_DEPENDENCIES
4820 It is also occasionally useful to have a program depend on some other
4821 target that is not actually part of that program. This can be done
4822 using either the @code{@var{prog}_DEPENDENCIES} or the
4823 @code{EXTRA_@var{prog}_DEPENDENCIES} variable. Each program depends on
4824 the contents both variables, but no further interpretation is done.
4826 Since these dependencies are associated to the link rule used to
4827 create the programs they should normally list files used by the link
4828 command. That is @file{*.$(OBJEXT)}, @file{*.a}, or @file{*.la}
4829 files. In rare cases you may need to add other kinds of files such as
4830 linker scripts, but @emph{listing a source file in
4831 @code{_DEPENDENCIES} is wrong}. If some source file needs to be built
4832 before all the components of a program are built, consider using the
4833 @code{BUILT_SOURCES} variable instead (@pxref{Sources}).
4835 If @code{@var{prog}_DEPENDENCIES} is not supplied, it is computed by
4836 Automake. The automatically-assigned value is the contents of
4837 @code{@var{prog}_LDADD}, with most configure substitutions, @option{-l},
4838 @option{-L}, @option{-dlopen} and @option{-dlpreopen} options removed. The
4839 configure substitutions that are left in are only @samp{$(LIBOBJS)} and
4840 @samp{$(ALLOCA)}; these are left because it is known that they will not
4841 cause an invalid value for @code{@var{prog}_DEPENDENCIES} to be
4844 @ref{Conditional Sources} shows a situation where @code{_DEPENDENCIES}
4847 The @code{EXTRA_@var{prog}_DEPENDENCIES} may be useful for cases where
4848 you merely want to augment the @command{automake}-generated
4849 @code{@var{prog}_DEPENDENCIES} rather than replacing it.
4851 @cindex @code{LDADD} and @option{-l}
4852 @cindex @option{-l} and @code{LDADD}
4853 We recommend that you avoid using @option{-l} options in @code{LDADD}
4854 or @code{@var{prog}_LDADD} when referring to libraries built by your
4855 package. Instead, write the file name of the library explicitly as in
4856 the above @code{cpio} example. Use @option{-l} only to list
4857 third-party libraries. If you follow this rule, the default value of
4858 @code{@var{prog}_DEPENDENCIES} will list all your local libraries and
4859 omit the other ones.
4862 @node Conditional Sources
4863 @subsection Conditional compilation of sources
4865 You can't put a configure substitution (e.g., @samp{@@FOO@@} or
4866 @samp{$(FOO)} where @code{FOO} is defined via @code{AC_SUBST}) into a
4867 @code{_SOURCES} variable. The reason for this is a bit hard to
4868 explain, but suffice to say that it simply won't work. Automake will
4869 give an error if you try to do this.
4871 Fortunately there are two other ways to achieve the same result. One is
4872 to use configure substitutions in @code{_LDADD} variables, the other is
4873 to use an Automake conditional.
4875 @subsubheading Conditional Compilation using @code{_LDADD} Substitutions
4877 @cindex @code{EXTRA_prog_SOURCES}, defined
4879 Automake must know all the source files that could possibly go into a
4880 program, even if not all the files are built in every circumstance. Any
4881 files that are only conditionally built should be listed in the
4882 appropriate @code{EXTRA_} variable. For instance, if
4883 @file{hello-linux.c} or @file{hello-generic.c} were conditionally included
4884 in @code{hello}, the @file{Makefile.am} would contain:
4887 bin_PROGRAMS = hello
4888 hello_SOURCES = hello-common.c
4889 EXTRA_hello_SOURCES = hello-linux.c hello-generic.c
4890 hello_LDADD = $(HELLO_SYSTEM)
4891 hello_DEPENDENCIES = $(HELLO_SYSTEM)
4895 You can then setup the @samp{$(HELLO_SYSTEM)} substitution from
4896 @file{configure.ac}:
4901 *linux*) HELLO_SYSTEM='hello-linux.$(OBJEXT)' ;;
4902 *) HELLO_SYSTEM='hello-generic.$(OBJEXT)' ;;
4904 AC_SUBST([HELLO_SYSTEM])
4908 In this case, the variable @code{HELLO_SYSTEM} should be replaced by
4909 either @file{hello-linux.o} or @file{hello-generic.o}, and added to
4910 both @code{hello_DEPENDENCIES} and @code{hello_LDADD} in order to be
4911 built and linked in.
4913 @subsubheading Conditional Compilation using Automake Conditionals
4915 An often simpler way to compile source files conditionally is to use
4916 Automake conditionals. For instance, you could use this
4917 @file{Makefile.am} construct to build the same @file{hello} example:
4920 bin_PROGRAMS = hello
4922 hello_SOURCES = hello-linux.c hello-common.c
4924 hello_SOURCES = hello-generic.c hello-common.c
4928 In this case, @file{configure.ac} should setup the @code{LINUX}
4929 conditional using @code{AM_CONDITIONAL} (@pxref{Conditionals}).
4931 When using conditionals like this you don't need to use the
4932 @code{EXTRA_} variable, because Automake will examine the contents of
4933 each variable to construct the complete list of source files.
4935 If your program uses a lot of files, you will probably prefer a
4936 conditional @samp{+=}.
4939 bin_PROGRAMS = hello
4940 hello_SOURCES = hello-common.c
4942 hello_SOURCES += hello-linux.c
4944 hello_SOURCES += hello-generic.c
4948 @node Conditional Programs
4949 @subsection Conditional compilation of programs
4950 @cindex Conditional programs
4951 @cindex Programs, conditional
4953 Sometimes it is useful to determine the programs that are to be built
4954 at configure time. For instance, GNU @code{cpio} only builds
4955 @code{mt} and @code{rmt} under special circumstances. The means to
4956 achieve conditional compilation of programs are the same you can use
4957 to compile source files conditionally: substitutions or conditionals.
4959 @subsubheading Conditional Programs using @command{configure} Substitutions
4961 @vindex EXTRA_PROGRAMS
4962 @cindex @code{EXTRA_PROGRAMS}, defined
4963 In this case, you must notify Automake of all the programs that can
4964 possibly be built, but at the same time cause the generated
4965 @file{Makefile.in} to use the programs specified by @command{configure}.
4966 This is done by having @command{configure} substitute values into each
4967 @code{_PROGRAMS} definition, while listing all optionally built programs
4968 in @code{EXTRA_PROGRAMS}.
4971 bin_PROGRAMS = cpio pax $(MT)
4972 libexec_PROGRAMS = $(RMT)
4973 EXTRA_PROGRAMS = mt rmt
4976 As explained in @ref{EXEEXT}, Automake will rewrite
4977 @code{bin_PROGRAMS}, @code{libexec_PROGRAMS}, and
4978 @code{EXTRA_PROGRAMS}, appending @samp{$(EXEEXT)} to each binary.
4979 Obviously it cannot rewrite values obtained at run-time through
4980 @command{configure} substitutions, therefore you should take care of
4981 appending @samp{$(EXEEXT)} yourself, as in @samp{AC_SUBST([MT],
4982 ['mt$@{EXEEXT@}'])}.
4984 @subsubheading Conditional Programs using Automake Conditionals
4986 You can also use Automake conditionals (@pxref{Conditionals}) to
4987 select programs to be built. In this case you don't have to worry
4988 about @samp{$(EXEEXT)} or @code{EXTRA_PROGRAMS}.
4990 @c Keep in sync with exeext.sh
4992 bin_PROGRAMS = cpio pax
4997 libexec_PROGRAMS = rmt
5003 @section Building a library
5005 @cindex @code{_LIBRARIES} primary, defined
5006 @cindex @code{LIBRARIES} primary, defined
5007 @cindex Primary variable, @code{LIBRARIES}
5010 @vindex lib_LIBRARIES
5011 @vindex pkglib_LIBRARIES
5012 @vindex noinst_LIBRARIES
5014 Building a library is much like building a program. In this case, the
5015 name of the primary is @code{LIBRARIES}. Libraries can be installed in
5016 @code{libdir} or @code{pkglibdir}.
5018 @xref{A Shared Library}, for information on how to build shared
5019 libraries using libtool and the @code{LTLIBRARIES} primary.
5021 Each @code{_LIBRARIES} variable is a list of the libraries to be built.
5022 For instance, to create a library named @file{libcpio.a}, but not install
5023 it, you would write:
5026 noinst_LIBRARIES = libcpio.a
5027 libcpio_a_SOURCES = @dots{}
5030 The sources that go into a library are determined exactly as they are
5031 for programs, via the @code{_SOURCES} variables. Note that the library
5032 name is canonicalized (@pxref{Canonicalization}), so the @code{_SOURCES}
5033 variable corresponding to @file{libcpio.a} is @samp{libcpio_a_SOURCES},
5034 not @samp{libcpio.a_SOURCES}.
5036 @vindex maude_LIBADD
5037 Extra objects can be added to a library using the
5038 @code{@var{library}_LIBADD} variable. This should be used for objects
5039 determined by @command{configure}. Again from @code{cpio}:
5041 @c Keep in sync with pr401c.sh
5043 libcpio_a_LIBADD = $(LIBOBJS) $(ALLOCA)
5046 In addition, sources for extra objects that will not exist until
5047 configure-time must be added to the @code{BUILT_SOURCES} variable
5050 Building a static library is done by compiling all object files, then
5051 by invoking @samp{$(AR) $(ARFLAGS)} followed by the name of the
5052 library and the list of objects, and finally by calling
5053 @samp{$(RANLIB)} on that library. You should call
5054 @code{AC_PROG_RANLIB} from your @file{configure.ac} to define
5055 @code{RANLIB} (Automake will complain otherwise). You should also
5056 call @code{AM_PROG_AR} to define @code{AR}, in order to support unusual
5057 archivers such as Microsoft lib. @code{ARFLAGS} will default to
5058 @code{cru}; you can override this variable by setting it in your
5059 @file{Makefile.am} or by @code{AC_SUBST}ing it from your
5060 @file{configure.ac}. You can override the @code{AR} variable by
5061 defining a per-library @code{maude_AR} variable (@pxref{Program and
5062 Library Variables}).
5064 @cindex Empty libraries
5065 Be careful when selecting library components conditionally. Because
5066 building an empty library is not portable, you should ensure that any
5067 library always contains at least one object.
5069 To use a static library when building a program, add it to
5070 @code{LDADD} for this program. In the following example, the program
5071 @file{cpio} is statically linked with the library @file{libcpio.a}.
5074 noinst_LIBRARIES = libcpio.a
5075 libcpio_a_SOURCES = @dots{}
5078 cpio_SOURCES = cpio.c @dots{}
5079 cpio_LDADD = libcpio.a
5083 @node A Shared Library
5084 @section Building a Shared Library
5086 @cindex Shared libraries, support for
5088 Building shared libraries portably is a relatively complex matter.
5089 For this reason, GNU Libtool (@pxref{Top, , Introduction, libtool, The
5090 Libtool Manual}) was created to help build shared libraries in a
5091 platform-independent way.
5094 * Libtool Concept:: Introducing Libtool
5095 * Libtool Libraries:: Declaring Libtool Libraries
5096 * Conditional Libtool Libraries:: Building Libtool Libraries Conditionally
5097 * Conditional Libtool Sources:: Choosing Library Sources Conditionally
5098 * Libtool Convenience Libraries:: Building Convenience Libtool Libraries
5099 * Libtool Modules:: Building Libtool Modules
5100 * Libtool Flags:: Using _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS
5101 * LTLIBOBJS:: Using $(LTLIBOBJS) and $(LTALLOCA)
5102 * Libtool Issues:: Common Issues Related to Libtool's Use
5105 @node Libtool Concept
5106 @subsection The Libtool Concept
5108 @cindex @command{libtool}, introduction
5109 @cindex libtool library, definition
5110 @cindex suffix @file{.la}, defined
5111 @cindex @file{.la} suffix, defined
5113 Libtool abstracts shared and static libraries into a unified concept
5114 henceforth called @dfn{libtool libraries}. Libtool libraries are
5115 files using the @file{.la} suffix, and can designate a static library,
5116 a shared library, or maybe both. Their exact nature cannot be
5117 determined until @file{./configure} is run: not all platforms support
5118 all kinds of libraries, and users can explicitly select which
5119 libraries should be built. (However the package's maintainers can
5120 tune the default, @pxref{AC_PROG_LIBTOOL, , The @code{AC_PROG_LIBTOOL}
5121 macro, libtool, The Libtool Manual}.)
5123 @cindex suffix @file{.lo}, defined
5124 Because object files for shared and static libraries must be compiled
5125 differently, libtool is also used during compilation. Object files
5126 built by libtool are called @dfn{libtool objects}: these are files
5127 using the @file{.lo} suffix. Libtool libraries are built from these
5130 You should not assume anything about the structure of @file{.la} or
5131 @file{.lo} files and how libtool constructs them: this is libtool's
5132 concern, and the last thing one wants is to learn about libtool's
5133 guts. However the existence of these files matters, because they are
5134 used as targets and dependencies in @file{Makefile}s rules when
5135 building libtool libraries. There are situations where you may have
5136 to refer to these, for instance when expressing dependencies for
5137 building source files conditionally (@pxref{Conditional Libtool
5140 @cindex @file{libltdl}, introduction
5142 People considering writing a plug-in system, with dynamically loaded
5143 modules, should look into @file{libltdl}: libtool's dlopening library
5144 (@pxref{Using libltdl, , Using libltdl, libtool, The Libtool Manual}).
5145 This offers a portable dlopening facility to load libtool libraries
5146 dynamically, and can also achieve static linking where unavoidable.
5148 Before we discuss how to use libtool with Automake in details, it
5149 should be noted that the libtool manual also has a section about how
5150 to use Automake with libtool (@pxref{Using Automake, , Using Automake
5151 with Libtool, libtool, The Libtool Manual}).
5153 @node Libtool Libraries
5154 @subsection Building Libtool Libraries
5156 @cindex @code{_LTLIBRARIES} primary, defined
5157 @cindex @code{LTLIBRARIES} primary, defined
5158 @cindex Primary variable, @code{LTLIBRARIES}
5159 @cindex Example of shared libraries
5160 @vindex lib_LTLIBRARIES
5161 @vindex pkglib_LTLIBRARIES
5162 @vindex _LTLIBRARIES
5164 Automake uses libtool to build libraries declared with the
5165 @code{LTLIBRARIES} primary. Each @code{_LTLIBRARIES} variable is a
5166 list of libtool libraries to build. For instance, to create a libtool
5167 library named @file{libgettext.la}, and install it in @code{libdir},
5171 lib_LTLIBRARIES = libgettext.la
5172 libgettext_la_SOURCES = gettext.c gettext.h @dots{}
5175 Automake predefines the variable @code{pkglibdir}, so you can use
5176 @code{pkglib_LTLIBRARIES} to install libraries in
5177 @samp{$(libdir)/@@PACKAGE@@/}.
5179 If @file{gettext.h} is a public header file that needs to be installed
5180 in order for people to use the library, it should be declared using a
5181 @code{_HEADERS} variable, not in @code{libgettext_la_SOURCES}.
5182 Headers listed in the latter should be internal headers that are not
5183 part of the public interface.
5186 lib_LTLIBRARIES = libgettext.la
5187 libgettext_la_SOURCES = gettext.c @dots{}
5188 include_HEADERS = gettext.h @dots{}
5191 A package can build and install such a library along with other
5192 programs that use it. This dependency should be specified using
5193 @code{LDADD}. The following example builds a program named
5194 @file{hello} that is linked with @file{libgettext.la}.
5197 lib_LTLIBRARIES = libgettext.la
5198 libgettext_la_SOURCES = gettext.c @dots{}
5200 bin_PROGRAMS = hello
5201 hello_SOURCES = hello.c @dots{}
5202 hello_LDADD = libgettext.la
5206 Whether @file{hello} is statically or dynamically linked with
5207 @file{libgettext.la} is not yet known: this will depend on the
5208 configuration of libtool and the capabilities of the host.
5211 @node Conditional Libtool Libraries
5212 @subsection Building Libtool Libraries Conditionally
5213 @cindex libtool libraries, conditional
5214 @cindex conditional libtool libraries
5216 Like conditional programs (@pxref{Conditional Programs}), there are
5217 two main ways to build conditional libraries: using Automake
5218 conditionals or using Autoconf @code{AC_SUBST}itutions.
5220 The important implementation detail you have to be aware of is that
5221 the place where a library will be installed matters to libtool: it
5222 needs to be indicated @emph{at link-time} using the @option{-rpath}
5225 For libraries whose destination directory is known when Automake runs,
5226 Automake will automatically supply the appropriate @option{-rpath}
5227 option to libtool. This is the case for libraries listed explicitly in
5228 some installable @code{_LTLIBRARIES} variables such as
5229 @code{lib_LTLIBRARIES}.
5231 However, for libraries determined at configure time (and thus
5232 mentioned in @code{EXTRA_LTLIBRARIES}), Automake does not know the
5233 final installation directory. For such libraries you must add the
5234 @option{-rpath} option to the appropriate @code{_LDFLAGS} variable by
5237 The examples below illustrate the differences between these two methods.
5239 Here is an example where @code{WANTEDLIBS} is an @code{AC_SUBST}ed
5240 variable set at @file{./configure}-time to either @file{libfoo.la},
5241 @file{libbar.la}, both, or none. Although @samp{$(WANTEDLIBS)}
5242 appears in the @code{lib_LTLIBRARIES}, Automake cannot guess it
5243 relates to @file{libfoo.la} or @file{libbar.la} at the time it creates
5244 the link rule for these two libraries. Therefore the @option{-rpath}
5245 argument must be explicitly supplied.
5247 @c Keep in sync with ltcond.sh
5249 EXTRA_LTLIBRARIES = libfoo.la libbar.la
5250 lib_LTLIBRARIES = $(WANTEDLIBS)
5251 libfoo_la_SOURCES = foo.c @dots{}
5252 libfoo_la_LDFLAGS = -rpath '$(libdir)'
5253 libbar_la_SOURCES = bar.c @dots{}
5254 libbar_la_LDFLAGS = -rpath '$(libdir)'
5257 Here is how the same @file{Makefile.am} would look using Automake
5258 conditionals named @code{WANT_LIBFOO} and @code{WANT_LIBBAR}. Now
5259 Automake is able to compute the @option{-rpath} setting itself, because
5260 it's clear that both libraries will end up in @samp{$(libdir)} if they
5263 @c Keep in sync with ltcond.sh
5267 lib_LTLIBRARIES += libfoo.la
5270 lib_LTLIBRARIES += libbar.la
5272 libfoo_la_SOURCES = foo.c @dots{}
5273 libbar_la_SOURCES = bar.c @dots{}
5276 @node Conditional Libtool Sources
5277 @subsection Libtool Libraries with Conditional Sources
5279 Conditional compilation of sources in a library can be achieved in the
5280 same way as conditional compilation of sources in a program
5281 (@pxref{Conditional Sources}). The only difference is that
5282 @code{_LIBADD} should be used instead of @code{_LDADD} and that it
5283 should mention libtool objects (@file{.lo} files).
5285 So, to mimic the @file{hello} example from @ref{Conditional Sources},
5286 we could build a @file{libhello.la} library using either
5287 @file{hello-linux.c} or @file{hello-generic.c} with the following
5290 @c Keep in sync with ltcond2.sh
5292 lib_LTLIBRARIES = libhello.la
5293 libhello_la_SOURCES = hello-common.c
5294 EXTRA_libhello_la_SOURCES = hello-linux.c hello-generic.c
5295 libhello_la_LIBADD = $(HELLO_SYSTEM)
5296 libhello_la_DEPENDENCIES = $(HELLO_SYSTEM)
5300 And make sure @command{configure} defines @code{HELLO_SYSTEM} as
5301 either @file{hello-linux.lo} or @file{hello-@-generic.lo}.
5303 Or we could simply use an Automake conditional as follows.
5305 @c Keep in sync with ltcond2.sh
5307 lib_LTLIBRARIES = libhello.la
5308 libhello_la_SOURCES = hello-common.c
5310 libhello_la_SOURCES += hello-linux.c
5312 libhello_la_SOURCES += hello-generic.c
5316 @node Libtool Convenience Libraries
5317 @subsection Libtool Convenience Libraries
5318 @cindex convenience libraries, libtool
5319 @cindex libtool convenience libraries
5320 @vindex noinst_LTLIBRARIES
5321 @vindex check_LTLIBRARIES
5323 Sometimes you want to build libtool libraries that should not be
5324 installed. These are called @dfn{libtool convenience libraries} and
5325 are typically used to encapsulate many sublibraries, later gathered
5326 into one big installed library.
5328 Libtool convenience libraries are declared by directory-less variables
5329 such as @code{noinst_LTLIBRARIES}, @code{check_LTLIBRARIES}, or even
5330 @code{EXTRA_LTLIBRARIES}. Unlike installed libtool libraries they do
5331 not need an @option{-rpath} flag at link time (actually this is the only
5334 Convenience libraries listed in @code{noinst_LTLIBRARIES} are always
5335 built. Those listed in @code{check_LTLIBRARIES} are built only upon
5336 @samp{make check}. Finally, libraries listed in
5337 @code{EXTRA_LTLIBRARIES} are never built explicitly: Automake outputs
5338 rules to build them, but if the library does not appear as a Makefile
5339 dependency anywhere it won't be built (this is why
5340 @code{EXTRA_LTLIBRARIES} is used for conditional compilation).
5342 Here is a sample setup merging libtool convenience libraries from
5343 subdirectories into one main @file{libtop.la} library.
5345 @c Keep in sync with ltconv.sh
5347 # -- Top-level Makefile.am --
5348 SUBDIRS = sub1 sub2 @dots{}
5349 lib_LTLIBRARIES = libtop.la
5351 libtop_la_LIBADD = \
5356 # -- sub1/Makefile.am --
5357 noinst_LTLIBRARIES = libsub1.la
5358 libsub1_la_SOURCES = @dots{}
5360 # -- sub2/Makefile.am --
5361 # showing nested convenience libraries
5362 SUBDIRS = sub2.1 sub2.2 @dots{}
5363 noinst_LTLIBRARIES = libsub2.la
5364 libsub2_la_SOURCES =
5365 libsub2_la_LIBADD = \
5371 When using such setup, beware that @command{automake} will assume
5372 @file{libtop.la} is to be linked with the C linker. This is because
5373 @code{libtop_la_SOURCES} is empty, so @command{automake} picks C as
5374 default language. If @code{libtop_la_SOURCES} was not empty,
5375 @command{automake} would select the linker as explained in @ref{How
5376 the Linker is Chosen}.
5378 If one of the sublibraries contains non-C source, it is important that
5379 the appropriate linker be chosen. One way to achieve this is to
5380 pretend that there is such a non-C file among the sources of the
5381 library, thus forcing @command{automake} to select the appropriate
5382 linker. Here is the top-level @file{Makefile} of our example updated
5383 to force C++ linking.
5386 SUBDIRS = sub1 sub2 @dots{}
5387 lib_LTLIBRARIES = libtop.la
5389 # Dummy C++ source to cause C++ linking.
5390 nodist_EXTRA_libtop_la_SOURCES = dummy.cxx
5391 libtop_la_LIBADD = \
5397 @samp{EXTRA_*_SOURCES} variables are used to keep track of source
5398 files that might be compiled (this is mostly useful when doing
5399 conditional compilation using @code{AC_SUBST}, @pxref{Conditional
5400 Libtool Sources}), and the @code{nodist_} prefix means the listed
5401 sources are not to be distributed (@pxref{Program and Library
5402 Variables}). In effect the file @file{dummy.cxx} does not need to
5403 exist in the source tree. Of course if you have some real source file
5404 to list in @code{libtop_la_SOURCES} there is no point in cheating with
5405 @code{nodist_EXTRA_libtop_la_SOURCES}.
5408 @node Libtool Modules
5409 @subsection Libtool Modules
5410 @cindex modules, libtool
5411 @cindex libtool modules
5412 @cindex @option{-module}, libtool
5414 These are libtool libraries meant to be dlopened. They are
5415 indicated to libtool by passing @option{-module} at link-time.
5418 pkglib_LTLIBRARIES = mymodule.la
5419 mymodule_la_SOURCES = doit.c
5420 mymodule_la_LDFLAGS = -module
5423 Ordinarily, Automake requires that a library's name start with
5424 @code{lib}. However, when building a dynamically loadable module you
5425 might wish to use a "nonstandard" name. Automake will not complain
5426 about such nonstandard names if it knows the library being built is a
5427 libtool module, i.e., if @option{-module} explicitly appears in the
5428 library's @code{_LDFLAGS} variable (or in the common @code{AM_LDFLAGS}
5429 variable when no per-library @code{_LDFLAGS} variable is defined).
5431 As always, @code{AC_SUBST} variables are black boxes to Automake since
5432 their values are not yet known when @command{automake} is run.
5433 Therefore if @option{-module} is set via such a variable, Automake
5434 cannot notice it and will proceed as if the library was an ordinary
5435 libtool library, with strict naming.
5437 If @code{mymodule_la_SOURCES} is not specified, then it defaults to
5438 the single file @file{mymodule.c} (@pxref{Default _SOURCES}).
5441 @subsection @code{_LIBADD}, @code{_LDFLAGS}, and @code{_LIBTOOLFLAGS}
5442 @cindex @code{_LIBADD}, libtool
5443 @cindex @code{_LDFLAGS}, libtool
5444 @cindex @code{_LIBTOOLFLAGS}, libtool
5445 @vindex AM_LIBTOOLFLAGS
5446 @vindex LIBTOOLFLAGS
5447 @vindex maude_LIBTOOLFLAGS
5449 As shown in previous sections, the @samp{@var{library}_LIBADD}
5450 variable should be used to list extra libtool objects (@file{.lo}
5451 files) or libtool libraries (@file{.la}) to add to @var{library}.
5453 The @samp{@var{library}_LDFLAGS} variable is the place to list
5454 additional libtool linking flags, such as @option{-version-info},
5455 @option{-static}, and a lot more. @xref{Link mode, , Link mode,
5456 libtool, The Libtool Manual}.
5458 The @command{libtool} command has two kinds of options: mode-specific
5459 options and generic options. Mode-specific options such as the
5460 aforementioned linking flags should be lumped with the other flags
5461 passed to the tool invoked by @command{libtool} (hence the use of
5462 @samp{@var{library}_LDFLAGS} for libtool linking flags). Generic
5463 options include @option{--tag=@var{tag}} and @option{--silent}
5464 (@pxref{Invoking libtool, , Invoking @command{libtool}, libtool, The
5465 Libtool Manual} for more options) should appear before the mode
5466 selection on the command line; in @file{Makefile.am}s they should
5467 be listed in the @samp{@var{library}_LIBTOOLFLAGS} variable.
5469 If @samp{@var{library}_LIBTOOLFLAGS} is not defined, then the variable
5470 @code{AM_LIBTOOLFLAGS} is used instead.
5472 These flags are passed to libtool after the @option{--tag=@var{tag}}
5473 option computed by Automake (if any), so
5474 @samp{@var{library}_LIBTOOLFLAGS} (or @code{AM_LIBTOOLFLAGS}) is a
5475 good place to override or supplement the @option{--tag=@var{tag}}
5478 The libtool rules also use a @code{LIBTOOLFLAGS} variable that should
5479 not be set in @file{Makefile.am}: this is a user variable (@pxref{Flag
5480 Variables Ordering}. It allows users to run @samp{make
5481 LIBTOOLFLAGS=--silent}, for instance. Note that the verbosity of
5482 @command{libtool} can also be influenced by the Automake support
5483 for silent rules (@pxref{Automake Silent Rules}).
5485 @node LTLIBOBJS, Libtool Issues, Libtool Flags, A Shared Library
5486 @subsection @code{LTLIBOBJS} and @code{LTALLOCA}
5487 @cindex @code{LTLIBOBJS}, special handling
5488 @cindex @code{LIBOBJS}, and Libtool
5489 @cindex @code{LTALLOCA}, special handling
5490 @cindex @code{ALLOCA}, and Libtool
5497 Where an ordinary library might include @samp{$(LIBOBJS)} or
5498 @samp{$(ALLOCA)} (@pxref{LIBOBJS}), a libtool library must use
5499 @samp{$(LTLIBOBJS)} or @samp{$(LTALLOCA)}. This is required because
5500 the object files that libtool operates on do not necessarily end in
5503 Nowadays, the computation of @code{LTLIBOBJS} from @code{LIBOBJS} is
5504 performed automatically by Autoconf (@pxref{AC_LIBOBJ vs LIBOBJS, ,
5505 @code{AC_LIBOBJ} vs.@: @code{LIBOBJS}, autoconf, The Autoconf Manual}).
5507 @node Libtool Issues
5508 @subsection Common Issues Related to Libtool's Use
5511 * Error required file ltmain.sh not found:: The need to run libtoolize
5512 * Objects created both with libtool and without:: Avoid a specific build race
5515 @node Error required file ltmain.sh not found
5516 @subsubsection Error: @samp{required file `./ltmain.sh' not found}
5517 @cindex @file{ltmain.sh} not found
5518 @cindex @command{libtoolize}, no longer run by @command{automake}
5519 @cindex @command{libtoolize} and @command{autoreconf}
5520 @cindex @command{autoreconf} and @command{libtoolize}
5521 @cindex @file{bootstrap.sh} and @command{autoreconf}
5522 @cindex @file{autogen.sh} and @command{autoreconf}
5524 Libtool comes with a tool called @command{libtoolize} that will
5525 install libtool's supporting files into a package. Running this
5526 command will install @file{ltmain.sh}. You should execute it before
5527 @command{aclocal} and @command{automake}.
5529 People upgrading old packages to newer autotools are likely to face
5530 this issue because older Automake versions used to call
5531 @command{libtoolize}. Therefore old build scripts do not call
5532 @command{libtoolize}.
5534 Since Automake 1.6, it has been decided that running
5535 @command{libtoolize} was none of Automake's business. Instead, that
5536 functionality has been moved into the @command{autoreconf} command
5537 (@pxref{autoreconf Invocation, , Using @command{autoreconf}, autoconf,
5538 The Autoconf Manual}). If you do not want to remember what to run and
5539 when, just learn the @command{autoreconf} command. Hopefully,
5540 replacing existing @file{bootstrap.sh} or @file{autogen.sh} scripts by
5541 a call to @command{autoreconf} should also free you from any similar
5542 incompatible change in the future.
5544 @node Objects created both with libtool and without
5545 @subsubsection Objects @samp{created with both libtool and without}
5547 Sometimes, the same source file is used both to build a libtool
5548 library and to build another non-libtool target (be it a program or
5551 Let's consider the following @file{Makefile.am}.
5555 prog_SOURCES = prog.c foo.c @dots{}
5557 lib_LTLIBRARIES = libfoo.la
5558 libfoo_la_SOURCES = foo.c @dots{}
5562 (In this trivial case the issue could be avoided by linking
5563 @file{libfoo.la} with @file{prog} instead of listing @file{foo.c} in
5564 @code{prog_SOURCES}. But let's assume we really want to keep
5565 @file{prog} and @file{libfoo.la} separate.)
5567 Technically, it means that we should build @file{foo.$(OBJEXT)} for
5568 @file{prog}, and @file{foo.lo} for @file{libfoo.la}. The problem is
5569 that in the course of creating @file{foo.lo}, libtool may erase (or
5570 replace) @file{foo.$(OBJEXT)}, and this cannot be avoided.
5572 Therefore, when Automake detects this situation it will complain
5573 with a message such as
5575 object 'foo.$(OBJEXT)' created both with libtool and without
5578 A workaround for this issue is to ensure that these two objects get
5579 different basenames. As explained in @ref{Renamed Objects}, this
5580 happens automatically when per-targets flags are used.
5584 prog_SOURCES = prog.c foo.c @dots{}
5585 prog_CFLAGS = $(AM_CFLAGS)
5587 lib_LTLIBRARIES = libfoo.la
5588 libfoo_la_SOURCES = foo.c @dots{}
5592 Adding @samp{prog_CFLAGS = $(AM_CFLAGS)} is almost a no-op, because
5593 when the @code{prog_CFLAGS} is defined, it is used instead of
5594 @code{AM_CFLAGS}. However as a side effect it will cause
5595 @file{prog.c} and @file{foo.c} to be compiled as
5596 @file{prog-prog.$(OBJEXT)} and @file{prog-foo.$(OBJEXT)}, which solves
5599 @node Program and Library Variables
5600 @section Program and Library Variables
5602 Associated with each program is a collection of variables that can be
5603 used to modify how that program is built. There is a similar list of
5604 such variables for each library. The canonical name of the program (or
5605 library) is used as a base for naming these variables.
5607 In the list below, we use the name ``maude'' to refer to the program or
5608 library. In your @file{Makefile.am} you would replace this with the
5609 canonical name of your program. This list also refers to ``maude'' as a
5610 program, but in general the same rules apply for both static and dynamic
5611 libraries; the documentation below notes situations where programs and
5616 This variable, if it exists, lists all the source files that are
5617 compiled to build the program. These files are added to the
5618 distribution by default. When building the program, Automake will cause
5619 each source file to be compiled to a single @file{.o} file (or
5620 @file{.lo} when using libtool). Normally these object files are named
5621 after the source file, but other factors can change this. If a file in
5622 the @code{_SOURCES} variable has an unrecognized extension, Automake
5623 will do one of two things with it. If a suffix rule exists for turning
5624 files with the unrecognized extension into @file{.o} files, then
5625 @command{automake} will treat this file as it will any other source file
5626 (@pxref{Support for Other Languages}). Otherwise, the file will be
5627 ignored as though it were a header file.
5629 The prefixes @code{dist_} and @code{nodist_} can be used to control
5630 whether files listed in a @code{_SOURCES} variable are distributed.
5631 @code{dist_} is redundant, as sources are distributed by default, but it
5632 can be specified for clarity if desired.
5634 It is possible to have both @code{dist_} and @code{nodist_} variants of
5635 a given @code{_SOURCES} variable at once; this lets you easily
5636 distribute some files and not others, for instance:
5639 nodist_maude_SOURCES = nodist.c
5640 dist_maude_SOURCES = dist-me.c
5643 By default the output file (on Unix systems, the @file{.o} file) will
5644 be put into the current build directory. However, if the option
5645 @option{subdir-objects} is in effect in the current directory then the
5646 @file{.o} file will be put into the subdirectory named after the
5647 source file. For instance, with @option{subdir-objects} enabled,
5648 @file{sub/dir/file.c} will be compiled to @file{sub/dir/file.o}. Some
5649 people prefer this mode of operation. You can specify
5650 @option{subdir-objects} in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
5651 @cindex Subdirectory, objects in
5652 @cindex Objects in subdirectory
5655 @item EXTRA_maude_SOURCES
5656 Automake needs to know the list of files you intend to compile
5657 @emph{statically}. For one thing, this is the only way Automake has of
5658 knowing what sort of language support a given @file{Makefile.in}
5659 requires. @footnote{There are other, more obscure reasons for
5660 this limitation as well.} This means that, for example, you can't put a
5661 configure substitution like @samp{@@my_sources@@} into a @samp{_SOURCES}
5662 variable. If you intend to conditionally compile source files and use
5663 @file{configure} to substitute the appropriate object names into, e.g.,
5664 @code{_LDADD} (see below), then you should list the corresponding source
5665 files in the @code{EXTRA_} variable.
5667 This variable also supports @code{dist_} and @code{nodist_} prefixes.
5668 For instance, @code{nodist_EXTRA_maude_SOURCES} would list extra
5669 sources that may need to be built, but should not be distributed.
5672 A static library is created by default by invoking @samp{$(AR)
5673 $(ARFLAGS)} followed by the name of the library and then the objects
5674 being put into the library. You can override this by setting the
5675 @code{_AR} variable. This is usually used with C++; some C++
5676 compilers require a special invocation in order to instantiate all the
5677 templates that should go into a library. For instance, the SGI C++
5678 compiler likes this variable set like so:
5680 libmaude_a_AR = $(CXX) -ar -o
5684 Extra objects can be added to a @emph{library} using the @code{_LIBADD}
5685 variable. For instance, this should be used for objects determined by
5686 @command{configure} (@pxref{A Library}).
5688 In the case of libtool libraries, @code{maude_LIBADD} can also refer
5689 to other libtool libraries.
5692 Extra objects (@file{*.$(OBJEXT)}) and libraries (@file{*.a},
5693 @file{*.la}) can be added to a @emph{program} by listing them in the
5694 @code{_LDADD} variable. For instance, this should be used for objects
5695 determined by @command{configure} (@pxref{Linking}).
5697 @code{_LDADD} and @code{_LIBADD} are inappropriate for passing
5698 program-specific linker flags (except for @option{-l}, @option{-L},
5699 @option{-dlopen} and @option{-dlpreopen}). Use the @code{_LDFLAGS} variable
5702 For instance, if your @file{configure.ac} uses @code{AC_PATH_XTRA}, you
5703 could link your program against the X libraries like so:
5706 maude_LDADD = $(X_PRE_LIBS) $(X_LIBS) $(X_EXTRA_LIBS)
5709 We recommend that you use @option{-l} and @option{-L} only when
5710 referring to third-party libraries, and give the explicit file names
5711 of any library built by your package. Doing so will ensure that
5712 @code{maude_DEPENDENCIES} (see below) is correctly defined by default.
5715 This variable is used to pass extra flags to the link step of a program
5716 or a shared library. It overrides the @code{AM_LDFLAGS} variable.
5718 @item maude_LIBTOOLFLAGS
5719 This variable is used to pass extra options to @command{libtool}.
5720 It overrides the @code{AM_LIBTOOLFLAGS} variable.
5721 These options are output before @command{libtool}'s @option{--mode=@var{mode}}
5722 option, so they should not be mode-specific options (those belong to
5723 the compiler or linker flags). @xref{Libtool Flags}.
5725 @item maude_DEPENDENCIES
5726 @itemx EXTRA_maude_DEPENDENCIES
5727 It is also occasionally useful to have a target (program or library)
5728 depend on some other file that is not actually part of that target.
5729 This can be done using the @code{_DEPENDENCIES} variable. Each
5730 target depends on the contents of such a variable, but no further
5731 interpretation is done.
5733 Since these dependencies are associated to the link rule used to
5734 create the programs they should normally list files used by the link
5735 command. That is @file{*.$(OBJEXT)}, @file{*.a}, or @file{*.la} files
5736 for programs; @file{*.lo} and @file{*.la} files for Libtool libraries;
5737 and @file{*.$(OBJEXT)} files for static libraries. In rare cases you
5738 may need to add other kinds of files such as linker scripts, but
5739 @emph{listing a source file in @code{_DEPENDENCIES} is wrong}. If
5740 some source file needs to be built before all the components of a
5741 program are built, consider using the @code{BUILT_SOURCES} variable
5744 If @code{_DEPENDENCIES} is not supplied, it is computed by Automake.
5745 The automatically-assigned value is the contents of @code{_LDADD} or
5746 @code{_LIBADD}, with most configure substitutions, @option{-l}, @option{-L},
5747 @option{-dlopen} and @option{-dlpreopen} options removed. The configure
5748 substitutions that are left in are only @samp{$(LIBOBJS)} and
5749 @samp{$(ALLOCA)}; these are left because it is known that they will not
5750 cause an invalid value for @code{_DEPENDENCIES} to be generated.
5752 @code{_DEPENDENCIES} is more likely used to perform conditional
5753 compilation using an @code{AC_SUBST} variable that contains a list of
5754 objects. @xref{Conditional Sources}, and @ref{Conditional Libtool
5757 The @code{EXTRA_*_DEPENDENCIES} variable may be useful for cases where
5758 you merely want to augment the @command{automake}-generated
5759 @code{_DEPENDENCIES} variable rather than replacing it.
5762 You can override the linker on a per-program basis. By default the
5763 linker is chosen according to the languages used by the program. For
5764 instance, a program that includes C++ source code would use the C++
5765 compiler to link. The @code{_LINK} variable must hold the name of a
5766 command that can be passed all the @file{.o} file names and libraries
5767 to link against as arguments. Note that the name of the underlying
5768 program is @emph{not} passed to @code{_LINK}; typically one uses
5772 maude_LINK = $(CCLD) -magic -o $@@
5775 If a @code{_LINK} variable is not supplied, it may still be generated
5776 and used by Automake due to the use of per-target link flags such as
5777 @code{_CFLAGS}, @code{_LDFLAGS} or @code{_LIBTOOLFLAGS}, in cases where
5780 @item maude_CCASFLAGS
5782 @itemx maude_CPPFLAGS
5783 @itemx maude_CXXFLAGS
5785 @itemx maude_GCJFLAGS
5787 @itemx maude_OBJCFLAGS
5788 @itemx maude_OBJCXXFLAGS
5790 @itemx maude_UPCFLAGS
5792 @cindex per-target compilation flags, defined
5793 Automake allows you to set compilation flags on a per-program (or
5794 per-library) basis. A single source file can be included in several
5795 programs, and it will potentially be compiled with different flags for
5796 each program. This works for any language directly supported by
5797 Automake. These @dfn{per-target compilation flags} are
5806 @samp{_OBJCXXFLAGS},
5808 @samp{_UPCFLAGS}, and
5811 When using a per-target compilation flag, Automake will choose a
5812 different name for the intermediate object files. Ordinarily a file
5813 like @file{sample.c} will be compiled to produce @file{sample.o}.
5814 However, if the program's @code{_CFLAGS} variable is set, then the
5815 object file will be named, for instance, @file{maude-sample.o}. (See
5816 also @ref{Renamed Objects}).
5818 In compilations with per-target flags, the ordinary @samp{AM_} form of
5819 the flags variable is @emph{not} automatically included in the
5820 compilation (however, the user form of the variable @emph{is} included).
5821 So for instance, if you want the hypothetical @file{maude} compilations
5822 to also use the value of @code{AM_CFLAGS}, you would need to write:
5825 maude_CFLAGS = @dots{} your flags @dots{} $(AM_CFLAGS)
5828 @xref{Flag Variables Ordering}, for more discussion about the
5829 interaction between user variables, @samp{AM_} shadow variables, and
5830 per-target variables.
5832 @item maude_SHORTNAME
5833 On some platforms the allowable file names are very short. In order to
5834 support these systems and per-target compilation flags at the same
5835 time, Automake allows you to set a ``short name'' that will influence
5836 how intermediate object files are named. For instance, in the following
5840 bin_PROGRAMS = maude
5841 maude_CPPFLAGS = -DSOMEFLAG
5843 maude_SOURCES = sample.c @dots{}
5847 the object file would be named @file{m-sample.o} rather than
5848 @file{maude-sample.o}.
5850 This facility is rarely needed in practice,
5851 and we recommend avoiding it until you find it is required.
5854 @node Default _SOURCES
5855 @section Default @code{_SOURCES}
5859 @cindex @code{_SOURCES}, default
5860 @cindex default @code{_SOURCES}
5861 @vindex AM_DEFAULT_SOURCE_EXT
5863 @code{_SOURCES} variables are used to specify source files of programs
5864 (@pxref{A Program}), libraries (@pxref{A Library}), and Libtool
5865 libraries (@pxref{A Shared Library}).
5867 When no such variable is specified for a target, Automake will define
5868 one itself. The default is to compile a single C file whose base name
5869 is the name of the target itself, with any extension replaced by
5870 @code{AM_DEFAULT_SOURCE_EXT}, which defaults to @file{.c}.
5872 For example if you have the following somewhere in your
5873 @file{Makefile.am} with no corresponding @code{libfoo_a_SOURCES}:
5876 lib_LIBRARIES = libfoo.a sub/libc++.a
5880 @file{libfoo.a} will be built using a default source file named
5881 @file{libfoo.c}, and @file{sub/libc++.a} will be built from
5882 @file{sub/libc++.c}. (In older versions @file{sub/libc++.a}
5883 would be built from @file{sub_libc___a.c}, i.e., the default source
5884 was the canonized name of the target, with @file{.c} appended.
5885 We believe the new behavior is more sensible, but for backward
5886 compatibility @command{automake} will use the old name if a file or a rule
5887 with that name exists and @code{AM_DEFAULT_SOURCE_EXT} is not used.)
5889 @cindex @code{check_PROGRAMS} example
5890 @vindex check_PROGRAMS
5891 Default sources are mainly useful in test suites, when building many
5892 test programs each from a single source. For instance, in
5895 check_PROGRAMS = test1 test2 test3
5896 AM_DEFAULT_SOURCE_EXT = .cpp
5900 @file{test1}, @file{test2}, and @file{test3} will be built
5901 from @file{test1.cpp}, @file{test2.cpp}, and @file{test3.cpp}.
5902 Without the last line, they will be built from @file{test1.c},
5903 @file{test2.c}, and @file{test3.c}.
5905 @cindex Libtool modules, default source example
5906 @cindex default source, Libtool modules example
5907 Another case where this is convenient is building many Libtool modules
5908 (@file{module@var{n}.la}), each defined in its own file
5909 (@file{module@var{n}.c}).
5912 AM_LDFLAGS = -module
5913 lib_LTLIBRARIES = module1.la module2.la module3.la
5916 @cindex empty @code{_SOURCES}
5917 @cindex @code{_SOURCES}, empty
5918 Finally, there is one situation where this default source computation
5919 needs to be avoided: when a target should not be built from sources.
5920 We already saw such an example in @ref{true}; this happens when all
5921 the constituents of a target have already been compiled and just need
5922 to be combined using a @code{_LDADD} variable. Then it is necessary
5923 to define an empty @code{_SOURCES} variable, so that @command{automake}
5924 does not compute a default.
5927 bin_PROGRAMS = target
5929 target_LDADD = libmain.a libmisc.a
5933 @section Special handling for @code{LIBOBJS} and @code{ALLOCA}
5935 @cindex @code{LIBOBJS}, example
5936 @cindex @code{ALLOCA}, example
5937 @cindex @code{LIBOBJS}, special handling
5938 @cindex @code{ALLOCA}, special handling
5944 The @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} variables list object
5945 files that should be compiled into the project to provide an
5946 implementation for functions that are missing or broken on the host
5947 system. They are substituted by @file{configure}.
5951 These variables are defined by Autoconf macros such as
5952 @code{AC_LIBOBJ}, @code{AC_REPLACE_FUNCS} (@pxref{Generic Functions, ,
5953 Generic Function Checks, autoconf, The Autoconf Manual}), or
5954 @code{AC_FUNC_ALLOCA} (@pxref{Particular Functions, , Particular
5955 Function Checks, autoconf, The Autoconf Manual}). Many other Autoconf
5956 macros call @code{AC_LIBOBJ} or @code{AC_REPLACE_FUNCS} to
5957 populate @samp{$(LIBOBJS)}.
5959 @acindex AC_LIBSOURCE
5961 Using these variables is very similar to doing conditional compilation
5962 using @code{AC_SUBST} variables, as described in @ref{Conditional
5963 Sources}. That is, when building a program, @samp{$(LIBOBJS)} and
5964 @samp{$(ALLOCA)} should be added to the associated @samp{*_LDADD}
5965 variable, or to the @samp{*_LIBADD} variable when building a library.
5966 However there is no need to list the corresponding sources in
5967 @samp{EXTRA_*_SOURCES} nor to define @samp{*_DEPENDENCIES}. Automake
5968 automatically adds @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} to the
5969 dependencies, and it will discover the list of corresponding source
5970 files automatically (by tracing the invocations of the
5971 @code{AC_LIBSOURCE} Autoconf macros). If you have already defined
5972 @samp{*_DEPENDENCIES} explicitly for an unrelated reason, then you
5973 either need to add these variables manually, or use
5974 @samp{EXTRA_*_DEPENDENCIES} instead of @samp{*_DEPENDENCIES}.
5976 These variables are usually used to build a portability library that
5977 is linked with all the programs of the project. We now review a
5978 sample setup. First, @file{configure.ac} contains some checks that
5979 affect either @code{LIBOBJS} or @code{ALLOCA}.
5984 AC_CONFIG_LIBOBJ_DIR([lib])
5986 AC_FUNC_MALLOC dnl May add malloc.$(OBJEXT) to LIBOBJS
5987 AC_FUNC_MEMCMP dnl May add memcmp.$(OBJEXT) to LIBOBJS
5988 AC_REPLACE_FUNCS([strdup]) dnl May add strdup.$(OBJEXT) to LIBOBJS
5989 AC_FUNC_ALLOCA dnl May add alloca.$(OBJEXT) to ALLOCA
5998 @acindex AC_CONFIG_LIBOBJ_DIR
6000 The @code{AC_CONFIG_LIBOBJ_DIR} tells Autoconf that the source files
6001 of these object files are to be found in the @file{lib/} directory.
6002 Automake can also use this information, otherwise it expects the
6003 source files are to be in the directory where the @samp{$(LIBOBJS)}
6004 and @samp{$(ALLOCA)} variables are used.
6006 The @file{lib/} directory should therefore contain @file{malloc.c},
6007 @file{memcmp.c}, @file{strdup.c}, @file{alloca.c}. Here is its
6013 noinst_LIBRARIES = libcompat.a
6014 libcompat_a_SOURCES =
6015 libcompat_a_LIBADD = $(LIBOBJS) $(ALLOCA)
6018 The library can have any name, of course, and anyway it is not going
6019 to be installed: it just holds the replacement versions of the missing
6020 or broken functions so we can later link them in. Many projects
6021 also include extra functions, specific to the project, in that
6022 library: they are simply added on the @code{_SOURCES} line.
6024 @cindex Empty libraries and @samp{$(LIBOBJS)}
6025 @cindex @samp{$(LIBOBJS)} and empty libraries
6026 There is a small trap here, though: @samp{$(LIBOBJS)} and
6027 @samp{$(ALLOCA)} might be empty, and building an empty library is not
6028 portable. You should ensure that there is always something to put in
6029 @file{libcompat.a}. Most projects will also add some utility
6030 functions in that directory, and list them in
6031 @code{libcompat_a_SOURCES}, so in practice @file{libcompat.a} cannot
6034 Finally here is how this library could be used from the @file{src/}
6040 # Link all programs in this directory with libcompat.a
6041 LDADD = ../lib/libcompat.a
6043 bin_PROGRAMS = tool1 tool2 @dots{}
6044 tool1_SOURCES = @dots{}
6045 tool2_SOURCES = @dots{}
6048 When option @option{subdir-objects} is not used, as in the above
6049 example, the variables @samp{$(LIBOBJS)} or @samp{$(ALLOCA)} can only
6050 be used in the directory where their sources lie. E.g., here it would
6051 be wrong to use @samp{$(LIBOBJS)} or @samp{$(ALLOCA)} in
6052 @file{src/Makefile.am}. However if both @option{subdir-objects} and
6053 @code{AC_CONFIG_LIBOBJ_DIR} are used, it is OK to use these variables
6054 in other directories. For instance @file{src/Makefile.am} could be
6060 AUTOMAKE_OPTIONS = subdir-objects
6061 LDADD = $(LIBOBJS) $(ALLOCA)
6063 bin_PROGRAMS = tool1 tool2 @dots{}
6064 tool1_SOURCES = @dots{}
6065 tool2_SOURCES = @dots{}
6068 Because @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} contain object
6069 file names that end with @samp{.$(OBJEXT)}, they are not suitable for
6070 Libtool libraries (where the expected object extension is @file{.lo}):
6071 @code{LTLIBOBJS} and @code{LTALLOCA} should be used instead.
6073 @code{LTLIBOBJS} is defined automatically by Autoconf and should not
6074 be defined by hand (as in the past), however at the time of writing
6075 @code{LTALLOCA} still needs to be defined from @code{ALLOCA} manually.
6076 @xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs.@: @code{LIBOBJS},
6077 autoconf, The Autoconf Manual}.
6080 @node Program Variables
6081 @section Variables used when building a program
6083 Occasionally it is useful to know which @file{Makefile} variables
6084 Automake uses for compilations, and in which order (@pxref{Flag
6085 Variables Ordering}); for instance, you might need to do your own
6086 compilation in some special cases.
6088 Some variables are inherited from Autoconf; these are @code{CC},
6089 @code{CFLAGS}, @code{CPPFLAGS}, @code{DEFS}, @code{LDFLAGS}, and
6098 There are some additional variables that Automake defines on its own:
6102 The contents of this variable are passed to every compilation that invokes
6103 the C preprocessor; it is a list of arguments to the preprocessor. For
6104 instance, @option{-I} and @option{-D} options should be listed here.
6106 Automake already provides some @option{-I} options automatically, in a
6107 separate variable that is also passed to every compilation that invokes
6108 the C preprocessor. In particular it generates @samp{-I.},
6109 @samp{-I$(srcdir)}, and a @option{-I} pointing to the directory holding
6110 @file{config.h} (if you've used @code{AC_CONFIG_HEADERS}). You can
6111 disable the default @option{-I} options using the @option{nostdinc}
6114 When a file to be included is generated during the build and not part
6115 of a distribution tarball, its location is under @code{$(builddir)},
6116 not under @code{$(srcdir)}. This matters especially for packages that
6117 use header files placed in sub-directories and want to allow builds
6118 outside the source tree (@pxref{VPATH Builds}). In that case we
6119 recommend to use a pair of @option{-I} options, such as, e.g.,
6120 @samp{-Isome/subdir -I$(srcdir)/some/subdir} or
6121 @samp{-I$(top_builddir)/some/subdir -I$(top_srcdir)/some/subdir}.
6122 Note that the reference to the build tree should come before the
6123 reference to the source tree, so that accidentally leftover generated
6124 files in the source directory are ignored.
6126 @code{AM_CPPFLAGS} is ignored in preference to a per-executable (or
6127 per-library) @code{_CPPFLAGS} variable if it is defined.
6130 This does the same job as @code{AM_CPPFLAGS} (or any per-target
6131 @code{_CPPFLAGS} variable if it is used). It is an older name for the
6132 same functionality. This variable is deprecated; we suggest using
6133 @code{AM_CPPFLAGS} and per-target @code{_CPPFLAGS} instead.
6136 This is the variable the @file{Makefile.am} author can use to pass
6137 in additional C compiler flags. In some situations, this is
6138 not used, in preference to the per-executable (or per-library)
6142 This is the command used to actually compile a C source file. The
6143 file name is appended to form the complete command line.
6146 This is the variable the @file{Makefile.am} author can use to pass
6147 in additional linker flags. In some situations, this is not used, in
6148 preference to the per-executable (or per-library) @code{_LDFLAGS}.
6151 This is the command used to actually link a C program. It already
6152 includes @samp{-o $@@} and the usual variable references (for instance,
6153 @code{CFLAGS}); it takes as ``arguments'' the names of the object files
6154 and libraries to link in. This variable is not used when the linker is
6155 overridden with a per-target @code{_LINK} variable or per-target flags
6156 cause Automake to define such a @code{_LINK} variable.
6161 @section Yacc and Lex support
6163 Automake has somewhat idiosyncratic support for Yacc and Lex.
6165 Automake assumes that the @file{.c} file generated by @command{yacc}
6166 (or @command{lex}) should be named using the basename of the input
6167 file. That is, for a yacc source file @file{foo.y}, Automake will
6168 cause the intermediate file to be named @file{foo.c} (as opposed to
6169 @file{y.tab.c}, which is more traditional).
6171 The extension of a yacc source file is used to determine the extension
6172 of the resulting C or C++ source and header files. Note that header
6173 files are generated only when the @option{-d} Yacc option is used; see
6174 below for more information about this flag, and how to specify it.
6175 Files with the extension @file{.y} will thus be turned into @file{.c}
6176 sources and @file{.h} headers; likewise, @file{.yy} will become
6177 @file{.cc} and @file{.hh}, @file{.y++} will become @file{c++} and
6178 @file{h++}, @file{.yxx} will become @file{.cxx} and @file{.hxx},
6179 and @file{.ypp} will become @file{.cpp} and @file{.hpp}.
6181 Similarly, lex source files can be used to generate C or C++; the
6182 extensions @file{.l}, @file{.ll}, @file{.l++}, @file{.lxx}, and
6183 @file{.lpp} are recognized.
6185 You should never explicitly mention the intermediate (C or C++) file
6186 in any @code{SOURCES} variable; only list the source file.
6188 The intermediate files generated by @command{yacc} (or @command{lex})
6189 will be included in any distribution that is made. That way the user
6190 doesn't need to have @command{yacc} or @command{lex}.
6192 If a @command{yacc} source file is seen, then your @file{configure.ac} must
6193 define the variable @code{YACC}. This is most easily done by invoking
6194 the macro @code{AC_PROG_YACC} (@pxref{Particular Programs, , Particular
6195 Program Checks, autoconf, The Autoconf Manual}).
6199 When @code{yacc} is invoked, it is passed @code{AM_YFLAGS} and
6200 @code{YFLAGS}. The latter is a user variable and the former is
6201 intended for the @file{Makefile.am} author.
6203 @code{AM_YFLAGS} is usually used to pass the @option{-d} option to
6204 @command{yacc}. Automake knows what this means and will automatically
6205 adjust its rules to update and distribute the header file built by
6206 @samp{yacc -d}@footnote{Please note that @command{automake} recognizes
6207 @option{-d} in @code{AM_YFLAGS} only if it is not clustered with other
6208 options; for example, it won't be recognized if @code{AM_YFLAGS} is
6209 @option{-dt}, but it will be if @code{AM_YFLAGS} is @option{-d -t} or
6211 What Automake cannot guess, though, is where this
6212 header will be used: it is up to you to ensure the header gets built
6213 before it is first used. Typically this is necessary in order for
6214 dependency tracking to work when the header is included by another
6215 file. The common solution is listing the header file in
6216 @code{BUILT_SOURCES} (@pxref{Sources}) as follows.
6219 BUILT_SOURCES = parser.h
6222 foo_SOURCES = @dots{} parser.y @dots{}
6225 If a @command{lex} source file is seen, then your @file{configure.ac}
6226 must define the variable @code{LEX}. You can use @code{AC_PROG_LEX}
6227 to do this (@pxref{Particular Programs, , Particular Program Checks,
6228 autoconf, The Autoconf Manual}), but using @code{AM_PROG_LEX} macro
6229 (@pxref{Macros}) is recommended.
6233 When @command{lex} is invoked, it is passed @code{AM_LFLAGS} and
6234 @code{LFLAGS}. The latter is a user variable and the former is
6235 intended for the @file{Makefile.am} author.
6237 When @code{AM_MAINTAINER_MODE} (@pxref{maintainer-mode}) is used, the
6238 rebuild rule for distributed Yacc and Lex sources are only used when
6239 @code{maintainer-mode} is enabled, or when the files have been erased.
6241 @cindex @command{ylwrap}
6242 @cindex @command{yacc}, multiple parsers
6243 @cindex Multiple @command{yacc} parsers
6244 @cindex Multiple @command{lex} lexers
6245 @cindex @command{lex}, multiple lexers
6247 When @command{lex} or @command{yacc} sources are used, @code{automake -a}
6248 automatically installs an auxiliary program called @command{ylwrap} in
6249 your package (@pxref{Auxiliary Programs}).
6250 This program is used by the build rules to rename the output of these
6251 tools, and makes it possible to include multiple @command{yacc} (or
6252 @command{lex}) source files in a single directory. (This is necessary
6253 because yacc's output file name is fixed, and a parallel make could
6254 conceivably invoke more than one instance of @command{yacc}
6257 For @command{yacc}, simply managing locking is insufficient. The output of
6258 @command{yacc} always uses the same symbol names internally, so it isn't
6259 possible to link two @command{yacc} parsers into the same executable.
6261 We recommend using the following renaming hack used in @command{gdb}:
6263 #define yymaxdepth c_maxdepth
6264 #define yyparse c_parse
6266 #define yyerror c_error
6267 #define yylval c_lval
6268 #define yychar c_char
6269 #define yydebug c_debug
6270 #define yypact c_pact
6277 #define yyexca c_exca
6278 #define yyerrflag c_errflag
6279 #define yynerrs c_nerrs
6283 #define yy_yys c_yys
6284 #define yystate c_state
6287 #define yy_yyv c_yyv
6289 #define yylloc c_lloc
6290 #define yyreds c_reds
6291 #define yytoks c_toks
6292 #define yylhs c_yylhs
6293 #define yylen c_yylen
6294 #define yydefred c_yydefred
6295 #define yydgoto c_yydgoto
6296 #define yysindex c_yysindex
6297 #define yyrindex c_yyrindex
6298 #define yygindex c_yygindex
6299 #define yytable c_yytable
6300 #define yycheck c_yycheck
6301 #define yyname c_yyname
6302 #define yyrule c_yyrule
6305 For each define, replace the @samp{c_} prefix with whatever you like.
6306 These defines work for @command{bison}, @command{byacc}, and
6307 traditional @code{yacc}s. If you find a parser generator that uses a
6308 symbol not covered here, please report the new name so it can be added
6313 @section C++ Support
6316 @cindex Support for C++
6318 Automake includes full support for C++.
6320 Any package including C++ code must define the output variable
6321 @code{CXX} in @file{configure.ac}; the simplest way to do this is to use
6322 the @code{AC_PROG_CXX} macro (@pxref{Particular Programs, , Particular
6323 Program Checks, autoconf, The Autoconf Manual}).
6325 A few additional variables are defined when a C++ source file is seen:
6329 The name of the C++ compiler.
6332 Any flags to pass to the C++ compiler.
6335 The maintainer's variant of @code{CXXFLAGS}.
6338 The command used to actually compile a C++ source file. The file name
6339 is appended to form the complete command line.
6342 The command used to actually link a C++ program.
6346 @node Objective C Support
6347 @section Objective C Support
6349 @cindex Objective C support
6350 @cindex Support for Objective C
6352 Automake includes some support for Objective C.
6354 Any package including Objective C code must define the output variable
6355 @code{OBJC} in @file{configure.ac}; the simplest way to do this is to use
6356 the @code{AC_PROG_OBJC} macro (@pxref{Particular Programs, , Particular
6357 Program Checks, autoconf, The Autoconf Manual}).
6359 A few additional variables are defined when an Objective C source file
6364 The name of the Objective C compiler.
6367 Any flags to pass to the Objective C compiler.
6370 The maintainer's variant of @code{OBJCFLAGS}.
6373 The command used to actually compile an Objective C source file. The
6374 file name is appended to form the complete command line.
6377 The command used to actually link an Objective C program.
6381 @node Objective C++ Support
6382 @section Objective C++ Support
6384 @cindex Objective C++ support
6385 @cindex Support for Objective C++
6387 Automake includes some support for Objective C++.
6389 Any package including Objective C++ code must define the output variable
6390 @code{OBJCXX} in @file{configure.ac}; the simplest way to do this is to use
6391 the @code{AC_PROG_OBJCXX} macro (@pxref{Particular Programs, , Particular
6392 Program Checks, autoconf, The Autoconf Manual}).
6394 A few additional variables are defined when an Objective C++ source file
6399 The name of the Objective C++ compiler.
6402 Any flags to pass to the Objective C++ compiler.
6404 @item AM_OBJCXXFLAGS
6405 The maintainer's variant of @code{OBJCXXFLAGS}.
6408 The command used to actually compile an Objective C++ source file. The
6409 file name is appended to form the complete command line.
6412 The command used to actually link an Objective C++ program.
6416 @node Unified Parallel C Support
6417 @section Unified Parallel C Support
6419 @cindex Unified Parallel C support
6420 @cindex Support for Unified Parallel C
6422 Automake includes some support for Unified Parallel C.
6424 Any package including Unified Parallel C code must define the output
6425 variable @code{UPC} in @file{configure.ac}; the simplest way to do
6426 this is to use the @code{AM_PROG_UPC} macro (@pxref{Public Macros}).
6428 A few additional variables are defined when a Unified Parallel C
6429 source file is seen:
6433 The name of the Unified Parallel C compiler.
6436 Any flags to pass to the Unified Parallel C compiler.
6439 The maintainer's variant of @code{UPCFLAGS}.
6442 The command used to actually compile a Unified Parallel C source file.
6443 The file name is appended to form the complete command line.
6446 The command used to actually link a Unified Parallel C program.
6450 @node Assembly Support
6451 @section Assembly Support
6453 Automake includes some support for assembly code. There are two forms
6454 of assembler files: normal (@file{*.s}) and preprocessed by @code{CPP}
6455 (@file{*.S} or @file{*.sx}).
6460 @vindex AM_CCASFLAGS
6462 The variable @code{CCAS} holds the name of the compiler used to build
6463 assembly code. This compiler must work a bit like a C compiler; in
6464 particular it must accept @option{-c} and @option{-o}. The values of
6465 @code{CCASFLAGS} and @code{AM_CCASFLAGS} (or its per-target
6466 definition) is passed to the compilation. For preprocessed files,
6467 @code{DEFS}, @code{DEFAULT_INCLUDES}, @code{INCLUDES}, @code{CPPFLAGS}
6468 and @code{AM_CPPFLAGS} are also used.
6470 The autoconf macro @code{AM_PROG_AS} will define @code{CCAS} and
6471 @code{CCASFLAGS} for you (unless they are already set, it simply sets
6472 @code{CCAS} to the C compiler and @code{CCASFLAGS} to the C compiler
6473 flags), but you are free to define these variables by other means.
6475 Only the suffixes @file{.s}, @file{.S}, and @file{.sx} are recognized by
6476 @command{automake} as being files containing assembly code.
6479 @node Fortran 77 Support
6480 @comment node-name, next, previous, up
6481 @section Fortran 77 Support
6483 @cindex Fortran 77 support
6484 @cindex Support for Fortran 77
6486 Automake includes full support for Fortran 77.
6488 Any package including Fortran 77 code must define the output variable
6489 @code{F77} in @file{configure.ac}; the simplest way to do this is to use
6490 the @code{AC_PROG_F77} macro (@pxref{Particular Programs, , Particular
6491 Program Checks, autoconf, The Autoconf Manual}).
6493 A few additional variables are defined when a Fortran 77 source file is
6499 The name of the Fortran 77 compiler.
6502 Any flags to pass to the Fortran 77 compiler.
6505 The maintainer's variant of @code{FFLAGS}.
6508 Any flags to pass to the Ratfor compiler.
6511 The maintainer's variant of @code{RFLAGS}.
6514 The command used to actually compile a Fortran 77 source file. The file
6515 name is appended to form the complete command line.
6518 The command used to actually link a pure Fortran 77 program or shared
6523 Automake can handle preprocessing Fortran 77 and Ratfor source files in
6524 addition to compiling them@footnote{Much, if not most, of the
6525 information in the following sections pertaining to preprocessing
6526 Fortran 77 programs was taken almost verbatim from @ref{Catalogue of
6527 Rules, , Catalogue of Rules, make, The GNU Make Manual}.}. Automake
6528 also contains some support for creating programs and shared libraries
6529 that are a mixture of Fortran 77 and other languages (@pxref{Mixing
6530 Fortran 77 With C and C++}).
6532 These issues are covered in the following sections.
6535 * Preprocessing Fortran 77:: Preprocessing Fortran 77 sources
6536 * Compiling Fortran 77 Files:: Compiling Fortran 77 sources
6537 * Mixing Fortran 77 With C and C++:: Mixing Fortran 77 With C and C++
6541 @node Preprocessing Fortran 77
6542 @comment node-name, next, previous, up
6543 @subsection Preprocessing Fortran 77
6545 @cindex Preprocessing Fortran 77
6546 @cindex Fortran 77, Preprocessing
6547 @cindex Ratfor programs
6549 @file{N.f} is made automatically from @file{N.F} or @file{N.r}. This
6550 rule runs just the preprocessor to convert a preprocessable Fortran 77
6551 or Ratfor source file into a strict Fortran 77 source file. The precise
6552 command used is as follows:
6557 @code{$(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)@*
6558 $(AM_FFLAGS) $(FFLAGS)}
6561 @code{$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
6566 @node Compiling Fortran 77 Files
6567 @comment node-name, next, previous, up
6568 @subsection Compiling Fortran 77 Files
6570 @file{N.o} is made automatically from @file{N.f}, @file{N.F} or
6571 @file{N.r} by running the Fortran 77 compiler. The precise command used
6577 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS)}
6580 @code{$(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)@*
6581 $(AM_FFLAGS) $(FFLAGS)}
6584 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
6589 @node Mixing Fortran 77 With C and C++
6590 @comment node-name, next, previous, up
6591 @subsection Mixing Fortran 77 With C and C++
6593 @cindex Fortran 77, mixing with C and C++
6594 @cindex Mixing Fortran 77 with C and C++
6595 @cindex Linking Fortran 77 with C and C++
6597 @cindex Mixing Fortran 77 with C and/or C++
6599 Automake currently provides @emph{limited} support for creating programs
6600 and shared libraries that are a mixture of Fortran 77 and C and/or C++.
6601 However, there are many other issues related to mixing Fortran 77 with
6602 other languages that are @emph{not} (currently) handled by Automake, but
6603 that are handled by other packages@footnote{For example,
6604 @uref{http://www-zeus.desy.de/~burow/cfortran/, the cfortran package}
6605 addresses all of these inter-language issues, and runs under nearly all
6606 Fortran 77, C and C++ compilers on nearly all platforms. However,
6607 @command{cfortran} is not yet Free Software, but it will be in the next
6610 Automake can help in two ways:
6614 Automatic selection of the linker depending on which combinations of
6618 Automatic selection of the appropriate linker flags (e.g., @option{-L} and
6619 @option{-l}) to pass to the automatically selected linker in order to link
6620 in the appropriate Fortran 77 intrinsic and run-time libraries.
6622 @cindex @code{FLIBS}, defined
6624 These extra Fortran 77 linker flags are supplied in the output variable
6625 @code{FLIBS} by the @code{AC_F77_LIBRARY_LDFLAGS} Autoconf macro.
6626 @xref{Fortran Compiler, , Fortran Compiler Characteristics, autoconf,
6627 The Autoconf Manual}.
6630 If Automake detects that a program or shared library (as mentioned in
6631 some @code{_PROGRAMS} or @code{_LTLIBRARIES} primary) contains source
6632 code that is a mixture of Fortran 77 and C and/or C++, then it requires
6633 that the macro @code{AC_F77_LIBRARY_LDFLAGS} be called in
6634 @file{configure.ac}, and that either @code{$(FLIBS)}
6635 appear in the appropriate @code{_LDADD} (for programs) or @code{_LIBADD}
6636 (for shared libraries) variables. It is the responsibility of the
6637 person writing the @file{Makefile.am} to make sure that @samp{$(FLIBS)}
6638 appears in the appropriate @code{_LDADD} or
6639 @code{_LIBADD} variable.
6641 @cindex Mixed language example
6642 @cindex Example, mixed language
6644 For example, consider the following @file{Makefile.am}:
6648 foo_SOURCES = main.cc foo.f
6649 foo_LDADD = libfoo.la $(FLIBS)
6651 pkglib_LTLIBRARIES = libfoo.la
6652 libfoo_la_SOURCES = bar.f baz.c zardoz.cc
6653 libfoo_la_LIBADD = $(FLIBS)
6656 In this case, Automake will insist that @code{AC_F77_LIBRARY_LDFLAGS}
6657 is mentioned in @file{configure.ac}. Also, if @samp{$(FLIBS)} hadn't
6658 been mentioned in @code{foo_LDADD} and @code{libfoo_la_LIBADD}, then
6659 Automake would have issued a warning.
6662 * How the Linker is Chosen:: Automatic linker selection
6665 @node How the Linker is Chosen
6666 @comment node-name, next, previous, up
6667 @subsubsection How the Linker is Chosen
6669 @cindex Automatic linker selection
6670 @cindex Selecting the linker automatically
6672 When a program or library mixes several languages, Automake choose the
6673 linker according to the following priorities. (The names in
6674 parentheses are the variables containing the link command.)
6679 Native Java (@code{GCJLINK})
6682 Objective C++ (@code{OBJCXXLINK})
6685 C++ (@code{CXXLINK})
6688 Fortran 77 (@code{F77LINK})
6691 Fortran (@code{FCLINK})
6694 Objective C (@code{OBJCLINK})
6697 Unified Parallel C (@code{UPCLINK})
6703 For example, if Fortran 77, C and C++ source code is compiled
6704 into a program, then the C++ linker will be used. In this case, if the
6705 C or Fortran 77 linkers required any special libraries that weren't
6706 included by the C++ linker, then they must be manually added to an
6707 @code{_LDADD} or @code{_LIBADD} variable by the user writing the
6710 Automake only looks at the file names listed in @file{_SOURCES}
6711 variables to choose the linker, and defaults to the C linker.
6712 Sometimes this is inconvenient because you are linking against a
6713 library written in another language and would like to set the linker
6714 more appropriately. @xref{Libtool Convenience Libraries}, for a
6715 trick with @code{nodist_EXTRA_@dots{}_SOURCES}.
6717 A per-target @code{_LINK} variable will override the above selection.
6718 Per-target link flags will cause Automake to write a per-target
6719 @code{_LINK} variable according to the language chosen as above.
6722 @node Fortran 9x Support
6723 @comment node-name, next, previous, up
6724 @section Fortran 9x Support
6726 @cindex Fortran 9x support
6727 @cindex Support for Fortran 9x
6729 Automake includes support for Fortran 9x.
6731 Any package including Fortran 9x code must define the output variable
6732 @code{FC} in @file{configure.ac}; the simplest way to do this is to use
6733 the @code{AC_PROG_FC} macro (@pxref{Particular Programs, , Particular
6734 Program Checks, autoconf, The Autoconf Manual}).
6736 A few additional variables are defined when a Fortran 9x source file is
6742 The name of the Fortran 9x compiler.
6745 Any flags to pass to the Fortran 9x compiler.
6748 The maintainer's variant of @code{FCFLAGS}.
6751 The command used to actually compile a Fortran 9x source file. The file
6752 name is appended to form the complete command line.
6755 The command used to actually link a pure Fortran 9x program or shared
6761 * Compiling Fortran 9x Files:: Compiling Fortran 9x sources
6764 @node Compiling Fortran 9x Files
6765 @comment node-name, next, previous, up
6766 @subsection Compiling Fortran 9x Files
6768 @file{@var{file}.o} is made automatically from @file{@var{file}.f90},
6769 @file{@var{file}.f95}, @file{@var{file}.f03}, or @file{@var{file}.f08}
6770 by running the Fortran 9x compiler. The precise command used
6776 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f90) $<}
6779 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f95) $<}
6782 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f03) $<}
6785 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f08) $<}
6789 @node Java Support with gcj
6790 @comment node-name, next, previous, up
6791 @section Compiling Java sources using gcj
6793 @cindex Java support with gcj
6794 @cindex Support for Java with gcj
6795 @cindex Java to native code, compilation
6796 @cindex Compilation of Java to native code
6798 Automake includes support for natively compiled Java, using @command{gcj},
6799 the Java front end to the GNU Compiler Collection (rudimentary support
6800 for compiling Java to bytecode using the @command{javac} compiler is
6801 also present, @emph{albeit deprecated}; @pxref{Java}).
6803 Any package including Java code to be compiled must define the output
6804 variable @code{GCJ} in @file{configure.ac}; the variable @code{GCJFLAGS}
6805 must also be defined somehow (either in @file{configure.ac} or
6806 @file{Makefile.am}). The simplest way to do this is to use the
6807 @code{AM_PROG_GCJ} macro.
6811 By default, programs including Java source files are linked with
6814 As always, the contents of @code{AM_GCJFLAGS} are passed to every
6815 compilation invoking @command{gcj} (in its role as an ahead-of-time
6816 compiler, when invoking it to create @file{.class} files,
6817 @code{AM_JAVACFLAGS} is used instead). If it is necessary to pass
6818 options to @command{gcj} from @file{Makefile.am}, this variable, and not
6819 the user variable @code{GCJFLAGS}, should be used.
6823 @command{gcj} can be used to compile @file{.java}, @file{.class},
6824 @file{.zip}, or @file{.jar} files.
6826 When linking, @command{gcj} requires that the main class be specified
6827 using the @option{--main=} option. The easiest way to do this is to use
6828 the @code{_LDFLAGS} variable for the program.
6832 @comment node-name, next, previous, up
6833 @section Vala Support
6835 @cindex Vala Support
6836 @cindex Support for Vala
6838 Automake provides initial support for Vala
6839 (@uref{http://www.vala-project.org/}).
6840 This requires valac version 0.7.0 or later, and currently requires
6841 the user to use GNU @command{make}.
6844 foo_SOURCES = foo.vala bar.vala zardoc.c
6847 Any @file{.vala} file listed in a @code{_SOURCES} variable will be
6848 compiled into C code by the Vala compiler. The generated @file{.c} files
6849 are distributed. The end user does not need to have a Vala compiler installed.
6851 Automake ships with an Autoconf macro called @code{AM_PROG_VALAC}
6852 that will locate the Vala compiler and optionally check its version
6855 @defmac AM_PROG_VALAC (@ovar{minimum-version}, @ovar{action-if-found},
6856 @ovar{action-if-not-found})
6857 Search for a Vala compiler in @env{PATH}. If it is found, the variable
6858 @code{VALAC} is set to point to it (see below for more details). This
6859 macro takes three optional arguments. The first argument, if present,
6860 is the minimum version of the Vala compiler required to compile this
6861 package. If a compiler is found and satisfies @var{minimum-version},
6862 then @var{action-if-found} is run (this defaults to do nothing).
6863 Otherwise, @var{action-if-not-found} is run. If @var{action-if-not-found}
6864 is not specified, the default value is to print a warning in case no
6865 compiler is found, or if a too-old version of the compiler is found.
6868 There are a few variables that are used when compiling Vala sources:
6872 Absolute path to the Vala compiler, or simply @samp{valac} if no
6873 suitable compiler Vala could be found at configure runtime.
6876 Additional arguments for the Vala compiler.
6879 The maintainer's variant of @code{VALAFLAGS}.
6882 lib_LTLIBRARIES = libfoo.la
6883 libfoo_la_SOURCES = foo.vala
6887 Note that currently, you cannot use per-target @code{*_VALAFLAGS}
6888 (@pxref{Renamed Objects}) to produce different C files from one Vala
6892 @node Support for Other Languages
6893 @comment node-name, next, previous, up
6894 @section Support for Other Languages
6896 Automake currently only includes full support for C, C++ (@pxref{C++
6897 Support}), Objective C (@pxref{Objective C Support}),
6898 Objective C++ (@pxref{Objective C++ Support}),
6900 (@pxref{Fortran 77 Support}), Fortran 9x (@pxref{Fortran 9x Support}),
6901 and Java (@pxref{Java Support with gcj}). There is only rudimentary
6902 support for other languages, support for which will be improved based
6905 Some limited support for adding your own languages is available via the
6906 suffix rule handling (@pxref{Suffixes}).
6909 @section Automatic dependency tracking
6911 As a developer it is often painful to continually update the
6912 @file{Makefile.am} whenever the include-file dependencies change in a
6913 project. Automake supplies a way to automatically track dependency
6914 changes (@pxref{Dependency Tracking}).
6916 @cindex Dependency tracking
6917 @cindex Automatic dependency tracking
6919 Automake always uses complete dependencies for a compilation,
6920 including system headers. Automake's model is that dependency
6921 computation should be a side effect of the build. To this end,
6922 dependencies are computed by running all compilations through a
6923 special wrapper program called @command{depcomp}. @command{depcomp}
6924 understands how to coax many different C and C++ compilers into
6925 generating dependency information in the format it requires.
6926 @samp{automake -a} will install @command{depcomp} into your source
6927 tree for you. If @command{depcomp} can't figure out how to properly
6928 invoke your compiler, dependency tracking will simply be disabled for
6931 @cindex @command{depcomp}
6933 Experience with earlier versions of Automake (@pxref{Dependency Tracking
6934 Evolution, , Dependency Tracking Evolution, automake-history, Brief History
6935 of Automake}) taught us that it is not reliable to generate dependencies
6936 only on the maintainer's system, as configurations vary too much. So
6937 instead Automake implements dependency tracking at build time.
6939 Automatic dependency tracking can be suppressed by putting
6940 @option{no-dependencies} in the variable @code{AUTOMAKE_OPTIONS}, or
6941 passing @option{no-dependencies} as an argument to @code{AM_INIT_AUTOMAKE}
6942 (this should be the preferred way). Or, you can invoke @command{automake}
6943 with the @option{-i} option. Dependency tracking is enabled by default.
6945 @vindex AUTOMAKE_OPTIONS
6946 @opindex no-dependencies
6948 The person building your package also can choose to disable dependency
6949 tracking by configuring with @option{--disable-dependency-tracking}.
6951 @cindex Disabling dependency tracking
6952 @cindex Dependency tracking, disabling
6956 @section Support for executable extensions
6958 @cindex Executable extension
6959 @cindex Extension, executable
6962 On some platforms, such as Windows, executables are expected to have an
6963 extension such as @file{.exe}. On these platforms, some compilers (GCC
6964 among them) will automatically generate @file{foo.exe} when asked to
6965 generate @file{foo}.
6967 Automake provides mostly-transparent support for this. Unfortunately
6968 @emph{mostly} doesn't yet mean @emph{fully}. Until the English
6969 dictionary is revised, you will have to assist Automake if your package
6970 must support those platforms.
6972 One thing you must be aware of is that, internally, Automake rewrites
6973 something like this:
6976 bin_PROGRAMS = liver
6982 bin_PROGRAMS = liver$(EXEEXT)
6985 The targets Automake generates are likewise given the @samp{$(EXEEXT)}
6988 The variables @code{TESTS} and @code{XFAIL_TESTS} (@pxref{Simple Tests})
6989 are also rewritten if they contain filenames that have been declared as
6990 programs in the same @file{Makefile}. (This is mostly useful when some
6991 programs from @code{check_PROGRAMS} are listed in @code{TESTS}.)
6993 However, Automake cannot apply this rewriting to @command{configure}
6994 substitutions. This means that if you are conditionally building a
6995 program using such a substitution, then your @file{configure.ac} must
6996 take care to add @samp{$(EXEEXT)} when constructing the output variable.
6998 Sometimes maintainers like to write an explicit link rule for their
6999 program. Without executable extension support, this is easy---you
7000 simply write a rule whose target is the name of the program. However,
7001 when executable extension support is enabled, you must instead add the
7002 @samp{$(EXEEXT)} suffix.
7004 This might be a nuisance for maintainers who know their package will
7005 never run on a platform that has
7006 executable extensions. For those maintainers, the @option{no-exeext}
7007 option (@pxref{Options}) will disable this feature. This works in a
7008 fairly ugly way; if @option{no-exeext} is seen, then the presence of a
7009 rule for a target named @code{foo} in @file{Makefile.am} will override
7010 an @command{automake}-generated rule for @samp{foo$(EXEEXT)}. Without
7011 the @option{no-exeext} option, this use will give a diagnostic.
7015 @chapter Other Derived Objects
7017 Automake can handle derived objects that are not C programs. Sometimes
7018 the support for actually building such objects must be explicitly
7019 supplied, but Automake will still automatically handle installation and
7023 * Scripts:: Executable scripts
7024 * Headers:: Header files
7025 * Data:: Architecture-independent data files
7026 * Sources:: Derived sources
7031 @section Executable Scripts
7033 @cindex @code{_SCRIPTS} primary, defined
7034 @cindex @code{SCRIPTS} primary, defined
7035 @cindex Primary variable, @code{SCRIPTS}
7037 @cindex Installing scripts
7039 It is possible to define and install programs that are scripts. Such
7040 programs are listed using the @code{SCRIPTS} primary name. When the
7041 script is distributed in its final, installable form, the
7042 @file{Makefile} usually looks as follows:
7046 # Install my_script in $(bindir) and distribute it.
7047 dist_bin_SCRIPTS = my_script
7050 Scripts are not distributed by default; as we have just seen, those
7051 that should be distributed can be specified using a @code{dist_}
7052 prefix as with other primaries.
7054 @cindex @code{SCRIPTS}, installation directories
7056 @vindex sbin_SCRIPTS
7057 @vindex libexec_SCRIPTS
7058 @vindex pkgdata_SCRIPTS
7059 @vindex pkglibexec_SCRIPTS
7060 @vindex noinst_SCRIPTS
7061 @vindex check_SCRIPTS
7063 Scripts can be installed in @code{bindir}, @code{sbindir},
7064 @code{libexecdir}, @code{pkglibexecdir}, or @code{pkgdatadir}.
7066 Scripts that need not be installed can be listed in
7067 @code{noinst_SCRIPTS}, and among them, those which are needed only by
7068 @samp{make check} should go in @code{check_SCRIPTS}.
7070 When a script needs to be built, the @file{Makefile.am} should include
7071 the appropriate rules. For instance the @command{automake} program
7072 itself is a Perl script that is generated from @file{automake.in}.
7073 Here is how this is handled:
7076 bin_SCRIPTS = automake
7077 CLEANFILES = $(bin_SCRIPTS)
7078 EXTRA_DIST = automake.in
7080 do_subst = sed -e 's,[@@]datadir[@@],$(datadir),g' \
7081 -e 's,[@@]PERL[@@],$(PERL),g' \
7082 -e 's,[@@]PACKAGE[@@],$(PACKAGE),g' \
7083 -e 's,[@@]VERSION[@@],$(VERSION),g' \
7086 automake: automake.in Makefile
7087 $(do_subst) < $(srcdir)/automake.in > automake
7091 Such scripts for which a build rule has been supplied need to be
7092 deleted explicitly using @code{CLEANFILES} (@pxref{Clean}), and their
7093 sources have to be distributed, usually with @code{EXTRA_DIST}
7094 (@pxref{Basics of Distribution}).
7096 Another common way to build scripts is to process them from
7097 @file{configure} with @code{AC_CONFIG_FILES}. In this situation
7098 Automake knows which files should be cleaned and distributed, and what
7099 the rebuild rules should look like.
7101 For instance if @file{configure.ac} contains
7104 AC_CONFIG_FILES([src/my_script], [chmod +x src/my_script])
7108 to build @file{src/my_script} from @file{src/my_script.in}, then a
7109 @file{src/Makefile.am} to install this script in @code{$(bindir)} can
7113 bin_SCRIPTS = my_script
7114 CLEANFILES = $(bin_SCRIPTS)
7118 There is no need for @code{EXTRA_DIST} or any build rule: Automake
7119 infers them from @code{AC_CONFIG_FILES} (@pxref{Requirements}).
7120 @code{CLEANFILES} is still useful, because by default Automake will
7121 clean targets of @code{AC_CONFIG_FILES} in @code{distclean}, not
7124 Although this looks simpler, building scripts this way has one
7125 drawback: directory variables such as @code{$(datadir)} are not fully
7126 expanded and may refer to other directory variables.
7129 @section Header files
7131 @cindex @code{_HEADERS} primary, defined
7132 @cindex @code{HEADERS} primary, defined
7133 @cindex Primary variable, @code{HEADERS}
7135 @vindex noinst_HEADERS
7136 @cindex @code{HEADERS}, installation directories
7137 @cindex Installing headers
7138 @vindex include_HEADERS
7139 @vindex oldinclude_HEADERS
7140 @vindex pkginclude_HEADERS
7143 Header files that must be installed are specified by the
7144 @code{HEADERS} family of variables. Headers can be installed in
7145 @code{includedir}, @code{oldincludedir}, @code{pkgincludedir} or any
7146 other directory you may have defined (@pxref{Uniform}). For instance,
7149 include_HEADERS = foo.h bar/bar.h
7153 will install the two files as @file{$(includedir)/foo.h} and
7154 @file{$(includedir)/bar.h}.
7156 The @code{nobase_} prefix is also supported,
7159 nobase_include_HEADERS = foo.h bar/bar.h
7163 will install the two files as @file{$(includedir)/foo.h} and
7164 @file{$(includedir)/bar/bar.h} (@pxref{Alternative}).
7166 @vindex noinst_HEADERS
7167 Usually, only header files that accompany installed libraries need to
7168 be installed. Headers used by programs or convenience libraries are
7169 not installed. The @code{noinst_HEADERS} variable can be used for
7170 such headers. However when the header actually belongs to a single
7171 convenience library or program, we recommend listing it in the
7172 program's or library's @code{_SOURCES} variable (@pxref{Program
7173 Sources}) instead of in @code{noinst_HEADERS}. This is clearer for
7174 the @file{Makefile.am} reader. @code{noinst_HEADERS} would be the
7175 right variable to use in a directory containing only headers and no
7176 associated library or program.
7178 All header files must be listed somewhere; in a @code{_SOURCES}
7179 variable or in a @code{_HEADERS} variable. Missing ones will not
7180 appear in the distribution.
7182 For header files that are built and must not be distributed, use the
7183 @code{nodist_} prefix as in @code{nodist_include_HEADERS} or
7184 @code{nodist_prog_SOURCES}. If these generated headers are needed
7185 during the build, you must also ensure they exist before they are
7186 used (@pxref{Sources}).
7190 @section Architecture-independent data files
7192 @cindex @code{_DATA} primary, defined
7193 @cindex @code{DATA} primary, defined
7194 @cindex Primary variable, @code{DATA}
7197 Automake supports the installation of miscellaneous data files using the
7198 @code{DATA} family of variables.
7202 @vindex sysconf_DATA
7203 @vindex sharedstate_DATA
7204 @vindex localstate_DATA
7205 @vindex pkgdata_DATA
7207 Such data can be installed in the directories @code{datadir},
7208 @code{sysconfdir}, @code{sharedstatedir}, @code{localstatedir}, or
7211 By default, data files are @emph{not} included in a distribution. Of
7212 course, you can use the @code{dist_} prefix to change this on a
7215 Here is how Automake declares its auxiliary data files:
7218 dist_pkgdata_DATA = clean-kr.am clean.am @dots{}
7223 @section Built Sources
7225 Because Automake's automatic dependency tracking works as a side-effect
7226 of compilation (@pxref{Dependencies}) there is a bootstrap issue: a
7227 target should not be compiled before its dependencies are made, but
7228 these dependencies are unknown until the target is first compiled.
7230 Ordinarily this is not a problem, because dependencies are distributed
7231 sources: they preexist and do not need to be built. Suppose that
7232 @file{foo.c} includes @file{foo.h}. When it first compiles
7233 @file{foo.o}, @command{make} only knows that @file{foo.o} depends on
7234 @file{foo.c}. As a side-effect of this compilation @command{depcomp}
7235 records the @file{foo.h} dependency so that following invocations of
7236 @command{make} will honor it. In these conditions, it's clear there is
7237 no problem: either @file{foo.o} doesn't exist and has to be built
7238 (regardless of the dependencies), or accurate dependencies exist and
7239 they can be used to decide whether @file{foo.o} should be rebuilt.
7241 It's a different story if @file{foo.h} doesn't exist by the first
7242 @command{make} run. For instance, there might be a rule to build
7243 @file{foo.h}. This time @file{file.o}'s build will fail because the
7244 compiler can't find @file{foo.h}. @command{make} failed to trigger the
7245 rule to build @file{foo.h} first by lack of dependency information.
7247 @vindex BUILT_SOURCES
7248 @cindex @code{BUILT_SOURCES}, defined
7250 The @code{BUILT_SOURCES} variable is a workaround for this problem. A
7251 source file listed in @code{BUILT_SOURCES} is made on @samp{make all}
7252 or @samp{make check} (or even @samp{make install}) before other
7253 targets are processed. However, such a source file is not
7254 @emph{compiled} unless explicitly requested by mentioning it in some
7255 other @code{_SOURCES} variable.
7257 So, to conclude our introductory example, we could use
7258 @samp{BUILT_SOURCES = foo.h} to ensure @file{foo.h} gets built before
7259 any other target (including @file{foo.o}) during @samp{make all} or
7262 @code{BUILT_SOURCES} is actually a bit of a misnomer, as any file which
7263 must be created early in the build process can be listed in this
7264 variable. Moreover, all built sources do not necessarily have to be
7265 listed in @code{BUILT_SOURCES}. For instance, a generated @file{.c} file
7266 doesn't need to appear in @code{BUILT_SOURCES} (unless it is included by
7267 another source), because it's a known dependency of the associated
7270 It might be important to emphasize that @code{BUILT_SOURCES} is
7271 honored only by @samp{make all}, @samp{make check} and @samp{make
7272 install}. This means you cannot build a specific target (e.g.,
7273 @samp{make foo}) in a clean tree if it depends on a built source.
7274 However it will succeed if you have run @samp{make all} earlier,
7275 because accurate dependencies are already available.
7277 The next section illustrates and discusses the handling of built sources
7281 * Built Sources Example:: Several ways to handle built sources.
7284 @node Built Sources Example
7285 @subsection Built Sources Example
7287 Suppose that @file{foo.c} includes @file{bindir.h}, which is
7288 installation-dependent and not distributed: it needs to be built. Here
7289 @file{bindir.h} defines the preprocessor macro @code{bindir} to the
7290 value of the @command{make} variable @code{bindir} (inherited from
7293 We suggest several implementations below. It's not meant to be an
7294 exhaustive listing of all ways to handle built sources, but it will give
7295 you a few ideas if you encounter this issue.
7297 @subsubheading First Try
7299 This first implementation will illustrate the bootstrap issue mentioned
7300 in the previous section (@pxref{Sources}).
7302 Here is a tentative @file{Makefile.am}.
7308 nodist_foo_SOURCES = bindir.h
7309 CLEANFILES = bindir.h
7311 echo '#define bindir "$(bindir)"' >$@@
7314 This setup doesn't work, because Automake doesn't know that @file{foo.c}
7315 includes @file{bindir.h}. Remember, automatic dependency tracking works
7316 as a side-effect of compilation, so the dependencies of @file{foo.o} will
7317 be known only after @file{foo.o} has been compiled (@pxref{Dependencies}).
7318 The symptom is as follows.
7322 source='foo.c' object='foo.o' libtool=no \
7323 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
7324 depmode=gcc /bin/sh ./depcomp \
7325 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
7326 foo.c:2: bindir.h: No such file or directory
7327 make: *** [foo.o] Error 1
7330 In this example @file{bindir.h} is not distributed nor installed, and
7331 it is not even being built on-time. One may wonder if the
7332 @samp{nodist_foo_SOURCES = bindir.h} line has any use at all. This
7333 line simply states that @file{bindir.h} is a source of @code{foo}, so
7334 for instance, it should be inspected while generating tags
7335 (@pxref{Tags}). In other words, it does not help our present problem,
7336 and the build would fail identically without it.
7338 @subsubheading Using @code{BUILT_SOURCES}
7340 A solution is to require @file{bindir.h} to be built before anything
7341 else. This is what @code{BUILT_SOURCES} is meant for (@pxref{Sources}).
7346 nodist_foo_SOURCES = bindir.h
7347 BUILT_SOURCES = bindir.h
7348 CLEANFILES = bindir.h
7350 echo '#define bindir "$(bindir)"' >$@@
7353 See how @file{bindir.h} gets built first:
7357 echo '#define bindir "/usr/local/bin"' >bindir.h
7359 make[1]: Entering directory `/home/adl/tmp'
7360 source='foo.c' object='foo.o' libtool=no \
7361 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
7362 depmode=gcc /bin/sh ./depcomp \
7363 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
7364 gcc -g -O2 -o foo foo.o
7365 make[1]: Leaving directory `/home/adl/tmp'
7368 However, as said earlier, @code{BUILT_SOURCES} applies only to the
7369 @code{all}, @code{check}, and @code{install} targets. It still fails
7370 if you try to run @samp{make foo} explicitly:
7374 test -z "bindir.h" || rm -f bindir.h
7375 test -z "foo" || rm -f foo
7377 % : > .deps/foo.Po # Suppress previously recorded dependencies
7379 source='foo.c' object='foo.o' libtool=no \
7380 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
7381 depmode=gcc /bin/sh ./depcomp \
7382 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
7383 foo.c:2: bindir.h: No such file or directory
7384 make: *** [foo.o] Error 1
7387 @subsubheading Recording Dependencies manually
7389 Usually people are happy enough with @code{BUILT_SOURCES} because they
7390 never build targets such as @samp{make foo} before @samp{make all}, as
7391 in the previous example. However if this matters to you, you can
7392 avoid @code{BUILT_SOURCES} and record such dependencies explicitly in
7393 the @file{Makefile.am}.
7398 nodist_foo_SOURCES = bindir.h
7399 foo.$(OBJEXT): bindir.h
7400 CLEANFILES = bindir.h
7402 echo '#define bindir "$(bindir)"' >$@@
7405 You don't have to list @emph{all} the dependencies of @file{foo.o}
7406 explicitly, only those that might need to be built. If a dependency
7407 already exists, it will not hinder the first compilation and will be
7408 recorded by the normal dependency tracking code. (Note that after
7409 this first compilation the dependency tracking code will also have
7410 recorded the dependency between @file{foo.o} and
7411 @file{bindir.h}; so our explicit dependency is really useful to
7412 the first build only.)
7414 Adding explicit dependencies like this can be a bit dangerous if you are
7415 not careful enough. This is due to the way Automake tries not to
7416 overwrite your rules (it assumes you know better than it).
7417 @samp{foo.$(OBJEXT): bindir.h} supersedes any rule Automake may want to
7418 output to build @samp{foo.$(OBJEXT)}. It happens to work in this case
7419 because Automake doesn't have to output any @samp{foo.$(OBJEXT):}
7420 target: it relies on a suffix rule instead (i.e., @samp{.c.$(OBJEXT):}).
7421 Always check the generated @file{Makefile.in} if you do this.
7423 @subsubheading Build @file{bindir.h} from @file{configure}
7425 It's possible to define this preprocessor macro from @file{configure},
7426 either in @file{config.h} (@pxref{Defining Directories, , Defining
7427 Directories, autoconf, The Autoconf Manual}), or by processing a
7428 @file{bindir.h.in} file using @code{AC_CONFIG_FILES}
7429 (@pxref{Configuration Actions, ,Configuration Actions, autoconf, The
7432 At this point it should be clear that building @file{bindir.h} from
7433 @file{configure} works well for this example. @file{bindir.h} will exist
7434 before you build any target, hence will not cause any dependency issue.
7436 The Makefile can be shrunk as follows. We do not even have to mention
7444 However, it's not always possible to build sources from
7445 @file{configure}, especially when these sources are generated by a tool
7446 that needs to be built first.
7448 @subsubheading Build @file{bindir.c}, not @file{bindir.h}.
7450 Another attractive idea is to define @code{bindir} as a variable or
7451 function exported from @file{bindir.o}, and build @file{bindir.c}
7452 instead of @file{bindir.h}.
7455 noinst_PROGRAMS = foo
7456 foo_SOURCES = foo.c bindir.h
7457 nodist_foo_SOURCES = bindir.c
7458 CLEANFILES = bindir.c
7460 echo 'const char bindir[] = "$(bindir)";' >$@@
7463 @file{bindir.h} contains just the variable's declaration and doesn't
7464 need to be built, so it won't cause any trouble. @file{bindir.o} is
7465 always dependent on @file{bindir.c}, so @file{bindir.c} will get built
7468 @subsubheading Which is best?
7470 There is no panacea, of course. Each solution has its merits and
7473 You cannot use @code{BUILT_SOURCES} if the ability to run @samp{make
7474 foo} on a clean tree is important to you.
7476 You won't add explicit dependencies if you are leery of overriding
7477 an Automake rule by mistake.
7479 Building files from @file{./configure} is not always possible, neither
7480 is converting @file{.h} files into @file{.c} files.
7483 @node Other GNU Tools
7484 @chapter Other GNU Tools
7486 Since Automake is primarily intended to generate @file{Makefile.in}s for
7487 use in GNU programs, it tries hard to interoperate with other GNU tools.
7490 * Emacs Lisp:: Emacs Lisp
7493 * Java:: Java bytecode compilation (deprecated)
7501 @cindex @code{_LISP} primary, defined
7502 @cindex @code{LISP} primary, defined
7503 @cindex Primary variable, @code{LISP}
7509 Automake provides some support for Emacs Lisp. The @code{LISP} primary
7510 is used to hold a list of @file{.el} files. Possible prefixes for this
7511 primary are @code{lisp_} and @code{noinst_}. Note that if
7512 @code{lisp_LISP} is defined, then @file{configure.ac} must run
7513 @code{AM_PATH_LISPDIR} (@pxref{Macros}).
7515 @vindex dist_lisp_LISP
7516 @vindex dist_noinst_LISP
7517 Lisp sources are not distributed by default. You can prefix the
7518 @code{LISP} primary with @code{dist_}, as in @code{dist_lisp_LISP} or
7519 @code{dist_noinst_LISP}, to indicate that these files should be
7522 Automake will byte-compile all Emacs Lisp source files using the Emacs
7523 found by @code{AM_PATH_LISPDIR}, if any was found. When performing such
7524 byte-compilation, the flags specified in the (developer-reserved)
7525 @code{AM_ELCFLAGS} and (user-reserved) @code{ELCFLAGS} make variables
7526 will be passed to the Emacs invocation.
7528 Byte-compiled Emacs Lisp files are not portable among all versions of
7529 Emacs, so it makes sense to turn this off if you expect sites to have
7530 more than one version of Emacs installed. Furthermore, many packages
7531 don't actually benefit from byte-compilation. Still, we recommend
7532 that you byte-compile your Emacs Lisp sources. It is probably better
7533 for sites with strange setups to cope for themselves than to make the
7534 installation less nice for everybody else.
7536 There are two ways to avoid byte-compiling. Historically, we have
7537 recommended the following construct.
7540 lisp_LISP = file1.el file2.el
7545 @code{ELCFILES} is an internal Automake variable that normally lists
7546 all @file{.elc} files that must be byte-compiled. Automake defines
7547 @code{ELCFILES} automatically from @code{lisp_LISP}. Emptying this
7548 variable explicitly prevents byte-compilation.
7550 Since Automake 1.8, we now recommend using @code{lisp_DATA} instead:
7552 @c Keep in sync with primary-prefix-couples-documented-valid.sh
7554 lisp_DATA = file1.el file2.el
7557 Note that these two constructs are not equivalent. @code{_LISP} will
7558 not install a file if Emacs is not installed, while @code{_DATA} will
7559 always install its files.
7564 @cindex GNU Gettext support
7565 @cindex Gettext support
7566 @cindex Support for GNU Gettext
7568 If @code{AM_GNU_GETTEXT} is seen in @file{configure.ac}, then Automake
7569 turns on support for GNU gettext, a message catalog system for
7570 internationalization
7571 (@pxref{Top, , Introduction, gettext, GNU gettext utilities}).
7573 The @code{gettext} support in Automake requires the addition of one or
7574 two subdirectories to the package: @file{po} and possibly also @file{intl}.
7575 The latter is needed if @code{AM_GNU_GETTEXT} is not invoked with the
7576 @samp{external} argument, or if @code{AM_GNU_GETTEXT_INTL_SUBDIR} is used.
7577 Automake ensures that these directories exist and are mentioned in
7583 Automake provides support for GNU Libtool (@pxref{Top, , Introduction,
7584 libtool, The Libtool Manual}) with the @code{LTLIBRARIES} primary.
7585 @xref{A Shared Library}.
7589 @section Java bytecode compilation (deprecated)
7591 @cindex @code{_JAVA} primary, defined
7592 @cindex @code{JAVA} primary, defined
7593 @cindex Primary variable, @code{JAVA}
7594 @cindex Java to bytecode, compilation
7595 @cindex Compilation of Java to bytecode
7597 Automake provides some minimal support for Java bytecode compilation with
7598 the @code{JAVA} primary (in addition to the support for compiling Java to
7599 native machine code; @pxref{Java Support with gcj}). Note however that
7600 @emph{the interface and most features described here are deprecated}.
7601 Future Automake releases will strive to provide a better and cleaner
7602 interface, which however @emph{won't be backward-compatible}; the present
7603 interface will probably be removed altogether some time after the
7604 introduction of the new interface (if that ever materializes).
7606 Any @file{.java} files listed in a @code{_JAVA} variable will be
7607 compiled with @code{JAVAC} at build time. By default, @file{.java}
7608 files are not included in the distribution, you should use the
7609 @code{dist_} prefix to distribute them.
7611 Here is a typical setup for distributing @file{.java} files and
7612 installing the @file{.class} files resulting from their compilation.
7614 @c Keep in sync with primary-prefix-couples-documented-valid.sh
7616 javadir = $(datadir)/java
7617 dist_java_JAVA = a.java b.java @dots{}
7620 @cindex @code{JAVA} restrictions
7621 @cindex Restrictions for @code{JAVA}
7623 Currently Automake enforces the restriction that only one @code{_JAVA}
7624 primary can be used in a given @file{Makefile.am}. The reason for this
7625 restriction is that, in general, it isn't possible to know which
7626 @file{.class} files were generated from which @file{.java} files, so
7627 it would be impossible to know which files to install where. For
7628 instance, a @file{.java} file can define multiple classes; the resulting
7629 @file{.class} file names cannot be predicted without parsing the
7632 There are a few variables that are used when compiling Java sources:
7636 The name of the Java compiler. This defaults to @samp{javac}.
7639 The flags to pass to the compiler. This is considered to be a user
7640 variable (@pxref{User Variables}).
7643 More flags to pass to the Java compiler. This, and not
7644 @code{JAVACFLAGS}, should be used when it is necessary to put Java
7645 compiler flags into @file{Makefile.am}.
7648 The value of this variable is passed to the @option{-d} option to
7649 @code{javac}. It defaults to @samp{$(top_builddir)}.
7652 This variable is a shell expression that is used to set the
7653 @env{CLASSPATH} environment variable on the @code{javac} command line.
7654 (In the future we will probably handle class path setting differently.)
7661 @cindex @code{_PYTHON} primary, defined
7662 @cindex @code{PYTHON} primary, defined
7663 @cindex Primary variable, @code{PYTHON}
7666 Automake provides support for Python compilation with the
7667 @code{PYTHON} primary. A typical setup is to call
7668 @code{AM_PATH_PYTHON} in @file{configure.ac} and use a line like the
7669 following in @file{Makefile.am}:
7672 python_PYTHON = tree.py leave.py
7675 Any files listed in a @code{_PYTHON} variable will be byte-compiled
7676 with @command{py-compile} at install time. @command{py-compile}
7677 actually creates both standard (@file{.pyc}) and optimized
7678 (@file{.pyo}) byte-compiled versions of the source files. Note that
7679 because byte-compilation occurs at install time, any files listed in
7680 @code{noinst_PYTHON} will not be compiled. Python source files are
7681 included in the distribution by default, prepend @code{nodist_} (as in
7682 @code{nodist_python_PYTHON}) to omit them.
7684 Automake ships with an Autoconf macro called @code{AM_PATH_PYTHON}
7685 that will determine some Python-related directory variables (see
7686 below). If you have called @code{AM_PATH_PYTHON} from
7687 @file{configure.ac}, then you may use the variables
7688 @c Keep in sync with primary-prefix-couples-documented-valid.sh
7689 @code{python_PYTHON} or @code{pkgpython_PYTHON} to list Python source
7690 files in your @file{Makefile.am}, depending on where you want your files
7691 installed (see the definitions of @code{pythondir} and
7692 @code{pkgpythondir} below).
7694 @defmac AM_PATH_PYTHON (@ovar{version}, @ovar{action-if-found},
7695 @ovar{action-if-not-found})
7697 Search for a Python interpreter on the system. This macro takes three
7698 optional arguments. The first argument, if present, is the minimum
7699 version of Python required for this package: @code{AM_PATH_PYTHON}
7700 will skip any Python interpreter that is older than @var{version}.
7701 If an interpreter is found and satisfies @var{version}, then
7702 @var{action-if-found} is run. Otherwise, @var{action-if-not-found} is
7705 If @var{action-if-not-found} is not specified, as in the following
7706 example, the default is to abort @command{configure}.
7709 AM_PATH_PYTHON([2.2])
7713 This is fine when Python is an absolute requirement for the package.
7714 If Python >= 2.5 was only @emph{optional} to the package,
7715 @code{AM_PATH_PYTHON} could be called as follows.
7718 AM_PATH_PYTHON([2.5],, [:])
7721 If the @env{PYTHON} variable is set when @code{AM_PATH_PYTHON} is
7722 called, then that will be the only Python interpreter that is tried.
7724 @code{AM_PATH_PYTHON} creates the following output variables based on
7725 the Python installation found during configuration.
7730 The name of the Python executable, or @samp{:} if no suitable
7731 interpreter could be found.
7733 Assuming @var{action-if-not-found} is used (otherwise @file{./configure}
7734 will abort if Python is absent), the value of @code{PYTHON} can be used
7735 to setup a conditional in order to disable the relevant part of a build
7739 AM_PATH_PYTHON(,, [:])
7740 AM_CONDITIONAL([HAVE_PYTHON], [test "$PYTHON" != :])
7743 @item PYTHON_VERSION
7744 The Python version number, in the form @var{major}.@var{minor}
7745 (e.g., @samp{2.5}). This is currently the value of
7746 @samp{sys.version[:3]}.
7749 The string @samp{$@{prefix@}}. This term may be used in future work
7750 that needs the contents of Python's @samp{sys.prefix}, but general
7751 consensus is to always use the value from @command{configure}.
7753 @item PYTHON_EXEC_PREFIX
7754 The string @samp{$@{exec_prefix@}}. This term may be used in future work
7755 that needs the contents of Python's @samp{sys.exec_prefix}, but general
7756 consensus is to always use the value from @command{configure}.
7758 @item PYTHON_PLATFORM
7759 The canonical name used by Python to describe the operating system, as
7760 given by @samp{sys.platform}. This value is sometimes needed when
7761 building Python extensions.
7764 The directory name for the @file{site-packages} subdirectory of the
7765 standard Python install tree.
7768 This is the directory under @code{pythondir} that is named after the
7769 package. That is, it is @samp{$(pythondir)/$(PACKAGE)}. It is provided
7773 This is the directory where Python extension modules (shared libraries)
7774 should be installed. An extension module written in C could be declared
7775 as follows to Automake:
7777 @c Keep in sync with primary-prefix-couples-documented-valid.sh
7779 pyexec_LTLIBRARIES = quaternion.la
7780 quaternion_la_SOURCES = quaternion.c support.c support.h
7781 quaternion_la_LDFLAGS = -avoid-version -module
7785 This is a convenience variable that is defined as
7786 @samp{$(pyexecdir)/$(PACKAGE)}.
7789 All of these directory variables have values that start with either
7790 @samp{$@{prefix@}} or @samp{$@{exec_prefix@}} unexpanded. This works
7791 fine in @file{Makefiles}, but it makes these variables hard to use in
7792 @file{configure}. This is mandated by the GNU coding standards, so
7793 that the user can run @samp{make prefix=/foo install}. The Autoconf
7794 manual has a section with more details on this topic
7795 (@pxref{Installation Directory Variables, , Installation Directory
7796 Variables, autoconf, The Autoconf Manual}). See also @ref{Hard-Coded
7801 @chapter Building documentation
7803 Currently Automake provides support for Texinfo and man pages.
7807 * Man Pages:: Man pages
7814 @cindex @code{_TEXINFOS} primary, defined
7815 @cindex @code{TEXINFOS} primary, defined
7816 @cindex Primary variable, @code{TEXINFOS}
7817 @cindex HTML output using Texinfo
7818 @cindex PDF output using Texinfo
7819 @cindex PS output using Texinfo
7820 @cindex DVI output using Texinfo
7822 @vindex info_TEXINFOS
7824 If the current directory contains Texinfo source, you must declare it
7825 with the @code{TEXINFOS} primary. Generally Texinfo files are converted
7826 into info, and thus the @code{info_TEXINFOS} variable is most commonly used
7827 here. Any Texinfo source file should have the @file{.texi} extension.
7828 Automake also accepts @file{.txi} or @file{.texinfo} extensions, but their
7829 use is discouraged now, and will elicit runtime warnings.
7831 Automake generates rules to build @file{.info}, @file{.dvi},
7832 @file{.ps}, @file{.pdf} and @file{.html} files from your Texinfo
7833 sources. Following the GNU Coding Standards, only the @file{.info}
7834 files are built by @samp{make all} and installed by @samp{make
7835 install} (unless you use @option{no-installinfo}, see below).
7836 Furthermore, @file{.info} files are automatically distributed so that
7837 Texinfo is not a prerequisite for installing your package.
7839 It is worth noting that, contrary to what happens with the other formats,
7840 the generated @file{.info} files are by default placed in @code{srcdir}
7841 rather than in the @code{builddir}. This can be changed with the
7842 @option{info-in-builddir} option.
7848 @trindex install-dvi
7849 @trindex install-html
7850 @trindex install-pdf
7852 Other documentation formats can be built on request by @samp{make
7853 dvi}, @samp{make ps}, @samp{make pdf} and @samp{make html}, and they
7854 can be installed with @samp{make install-dvi}, @samp{make install-ps},
7855 @samp{make install-pdf} and @samp{make install-html} explicitly.
7856 @samp{make uninstall} will remove everything: the Texinfo
7857 documentation installed by default as well as all the above optional
7860 All of these targets can be extended using @samp{-local} rules
7861 (@pxref{Extending}).
7863 @cindex Texinfo flag, @code{VERSION}
7864 @cindex Texinfo flag, @code{UPDATED}
7865 @cindex Texinfo flag, @code{EDITION}
7866 @cindex Texinfo flag, @code{UPDATED-MONTH}
7868 @cindex @code{VERSION} Texinfo flag
7869 @cindex @code{UPDATED} Texinfo flag
7870 @cindex @code{EDITION} Texinfo flag
7871 @cindex @code{UPDATED-MONTH} Texinfo flag
7873 @cindex @file{mdate-sh}
7875 If the @file{.texi} file @code{@@include}s @file{version.texi}, then
7876 that file will be automatically generated. The file @file{version.texi}
7877 defines four Texinfo flag you can reference using
7878 @code{@@value@{EDITION@}}, @code{@@value@{VERSION@}},
7879 @code{@@value@{UPDATED@}}, and @code{@@value@{UPDATED-MONTH@}}.
7884 Both of these flags hold the version number of your program. They are
7885 kept separate for clarity.
7888 This holds the date the primary @file{.texi} file was last modified.
7891 This holds the name of the month in which the primary @file{.texi} file
7895 The @file{version.texi} support requires the @command{mdate-sh}
7896 script; this script is supplied with Automake and automatically
7897 included when @command{automake} is invoked with the
7898 @option{--add-missing} option.
7900 If you have multiple Texinfo files, and you want to use the
7901 @file{version.texi} feature, then you have to have a separate version
7902 file for each Texinfo file. Automake will treat any include in a
7903 Texinfo file that matches @file{vers*.texi} just as an automatically
7904 generated version file.
7906 Sometimes an info file actually depends on more than one @file{.texi}
7907 file. For instance, in GNU Hello, @file{hello.texi} includes the file
7908 @file{fdl.texi}. You can tell Automake about these dependencies using
7909 the @code{@var{texi}_TEXINFOS} variable. Here is how GNU Hello does it:
7914 info_TEXINFOS = hello.texi
7915 hello_TEXINFOS = fdl.texi
7918 @cindex @file{texinfo.tex}
7920 By default, Automake requires the file @file{texinfo.tex} to appear in
7921 the same directory as the @file{Makefile.am} file that lists the
7922 @file{.texi} files. If you used @code{AC_CONFIG_AUX_DIR} in
7923 @file{configure.ac} (@pxref{Input, , Finding `configure' Input,
7924 autoconf, The Autoconf Manual}), then @file{texinfo.tex} is looked for
7925 there. In both cases, @command{automake} then supplies @file{texinfo.tex} if
7926 @option{--add-missing} is given, and takes care of its distribution.
7927 However, if you set the @code{TEXINFO_TEX} variable (see below),
7928 it overrides the location of the file and turns off its installation
7929 into the source as well as its distribution.
7931 The option @option{no-texinfo.tex} can be used to eliminate the
7932 requirement for the file @file{texinfo.tex}. Use of the variable
7933 @code{TEXINFO_TEX} is preferable, however, because that allows the
7934 @code{dvi}, @code{ps}, and @code{pdf} targets to still work.
7936 @cindex Option, @code{no-installinfo}
7937 @cindex Target, @code{install-info}
7938 @cindex @code{install-info} target
7939 @cindex @code{no-installinfo} option
7941 @opindex no-installinfo
7942 @trindex install-info
7944 Automake generates an @code{install-info} rule; some people apparently
7945 use this. By default, info pages are installed by @samp{make
7946 install}, so running @code{make install-info} is pointless. This can
7947 be prevented via the @code{no-installinfo} option. In this case,
7948 @file{.info} files are not installed by default, and user must
7949 request this explicitly using @samp{make install-info}.
7951 @vindex AM_UPDATE_INFO_DIR
7952 By default, @code{make install-info} and @code{make uninstall-info}
7953 will try to run the @command{install-info} program (if available) to
7954 update (or create/remove) the @file{@code{$@{infodir@}}/dir} index.
7955 If this is undesired, it can be prevented by exporting the
7956 @code{AM_UPDATE_INFO_DIR} variable to "@code{no}".
7958 The following variables are used by the Texinfo build rules.
7962 The name of the program invoked to build @file{.info} files. This
7963 variable is defined by Automake. If the @command{makeinfo} program is
7964 found on the system then it will be used by default; otherwise
7965 @command{missing} will be used instead.
7968 The command invoked to build @file{.html} files. Automake
7969 defines this to @samp{$(MAKEINFO) --html}.
7972 User flags passed to each invocation of @samp{$(MAKEINFO)} and
7973 @samp{$(MAKEINFOHTML)}. This user variable (@pxref{User Variables}) is
7974 not expected to be defined in any @file{Makefile}; it can be used by
7975 users to pass extra flags to suit their needs.
7977 @item AM_MAKEINFOFLAGS
7978 @itemx AM_MAKEINFOHTMLFLAGS
7979 Maintainer flags passed to each @command{makeinfo} invocation. Unlike
7980 @code{MAKEINFOFLAGS}, these variables are meant to be defined by
7981 maintainers in @file{Makefile.am}. @samp{$(AM_MAKEINFOFLAGS)} is
7982 passed to @code{makeinfo} when building @file{.info} files; and
7983 @samp{$(AM_MAKEINFOHTMLFLAGS)} is used when building @file{.html}
7986 @c Keep in sync with txinfo-many-output-formats.sh
7987 For instance, the following setting can be used to obtain one single
7988 @file{.html} file per manual, without node separators.
7990 AM_MAKEINFOHTMLFLAGS = --no-headers --no-split
7993 @code{AM_MAKEINFOHTMLFLAGS} defaults to @samp{$(AM_MAKEINFOFLAGS)}.
7994 This means that defining @code{AM_MAKEINFOFLAGS} without defining
7995 @code{AM_MAKEINFOHTMLFLAGS} will impact builds of both @file{.info}
7996 and @file{.html} files.
7999 The name of the command that converts a @file{.texi} file into a
8000 @file{.dvi} file. This defaults to @samp{texi2dvi}, a script that ships
8001 with the Texinfo package.
8004 The name of the command that translates a @file{.texi} file into a
8005 @file{.pdf} file. This defaults to @samp{$(TEXI2DVI) --pdf --batch}.
8008 The name of the command that builds a @file{.ps} file out of a
8009 @file{.dvi} file. This defaults to @samp{dvips}.
8013 If your package has Texinfo files in many directories, you can use the
8014 variable @code{TEXINFO_TEX} to tell Automake where to find the canonical
8015 @file{texinfo.tex} for your package. The value of this variable should
8016 be the relative path from the current @file{Makefile.am} to
8020 TEXINFO_TEX = ../doc/texinfo.tex
8028 @cindex @code{_MANS} primary, defined
8029 @cindex @code{MANS} primary, defined
8030 @cindex Primary variable, @code{MANS}
8034 A package can also include man pages (but see the GNU standards on this
8035 matter, @ref{Man Pages, , , standards, The GNU Coding Standards}.) Man
8036 pages are declared using the @code{MANS} primary. Generally the
8037 @code{man_MANS} variable is used. Man pages are automatically installed in
8038 the correct subdirectory of @code{mandir}, based on the file extension.
8040 File extensions such as @file{.1c} are handled by looking for the valid
8041 part of the extension and using that to determine the correct
8042 subdirectory of @code{mandir}. Valid section names are the digits
8043 @samp{0} through @samp{9}, and the letters @samp{l} and @samp{n}.
8045 Sometimes developers prefer to name a man page something like
8046 @file{foo.man} in the source, and then rename it to have the correct
8047 suffix, for example @file{foo.1}, when installing the file. Automake
8048 also supports this mode. For a valid section named @var{section},
8049 there is a corresponding directory named @samp{man@var{section}dir},
8050 and a corresponding @code{_MANS} variable. Files listed in such a
8051 variable are installed in the indicated section. If the file already
8052 has a valid suffix, then it is installed as-is; otherwise the file
8053 suffix is changed to match the section.
8055 For instance, consider this example:
8057 man1_MANS = rename.man thesame.1 alsothesame.1c
8061 In this case, @file{rename.man} will be renamed to @file{rename.1} when
8062 installed, but the other files will keep their names.
8064 @cindex Target, @code{install-man}
8065 @cindex Option, @option{no-installman}
8066 @cindex @code{install-man} target
8067 @cindex @option{no-installman} option
8068 @opindex no-installman
8069 @trindex install-man
8071 By default, man pages are installed by @samp{make install}. However,
8072 since the GNU project does not require man pages, many maintainers do
8073 not expend effort to keep the man pages up to date. In these cases, the
8074 @option{no-installman} option will prevent the man pages from being
8075 installed by default. The user can still explicitly install them via
8076 @samp{make install-man}.
8078 For fast installation, with many files it is preferable to use
8079 @samp{man@var{section}_MANS} over @samp{man_MANS} as well as files that
8080 do not need to be renamed.
8082 Man pages are not currently considered to be source, because it is not
8083 uncommon for man pages to be automatically generated. Therefore they
8084 are not automatically included in the distribution. However, this can
8085 be changed by use of the @code{dist_} prefix. For instance here is
8086 how to distribute and install the two man pages of GNU @command{cpio}
8087 (which includes both Texinfo documentation and man pages):
8090 dist_man_MANS = cpio.1 mt.1
8093 The @code{nobase_} prefix is meaningless for man pages and is
8097 @cindex @code{notrans_} prefix
8098 @cindex Man page renaming, avoiding
8099 @cindex Avoiding man page renaming
8101 Executables and manpages may be renamed upon installation
8102 (@pxref{Renaming}). For manpages this can be avoided by use of the
8103 @code{notrans_} prefix. For instance, suppose an executable @samp{foo}
8104 allowing to access a library function @samp{foo} from the command line.
8105 The way to avoid renaming of the @file{foo.3} manpage is:
8109 notrans_man_MANS = foo.3
8112 @cindex @code{notrans_} and @code{dist_} or @code{nodist_}
8113 @cindex @code{dist_} and @code{notrans_}
8114 @cindex @code{nodist_} and @code{notrans_}
8116 @samp{notrans_} must be specified first when used in conjunction with
8117 either @samp{dist_} or @samp{nodist_} (@pxref{Fine-grained Distribution
8118 Control}). For instance:
8121 notrans_dist_man3_MANS = bar.3
8125 @chapter What Gets Installed
8127 @cindex Installation support
8128 @cindex @samp{make install} support
8130 Naturally, Automake handles the details of actually installing your
8131 program once it has been built. All files named by the various
8132 primaries are automatically installed in the appropriate places when the
8133 user runs @samp{make install}.
8136 * Basics of Installation:: What gets installed where
8137 * The Two Parts of Install:: Installing data and programs separately
8138 * Extending Installation:: Adding your own rules for installation
8139 * Staged Installs:: Installation in a temporary location
8140 * Install Rules for the User:: Useful additional rules
8143 @node Basics of Installation
8144 @section Basics of Installation
8146 A file named in a primary is installed by copying the built file into
8147 the appropriate directory. The base name of the file is used when
8151 bin_PROGRAMS = hello subdir/goodbye
8154 In this example, both @samp{hello} and @samp{goodbye} will be installed
8155 in @samp{$(bindir)}.
8157 Sometimes it is useful to avoid the basename step at install time. For
8158 instance, you might have a number of header files in subdirectories of
8159 the source tree that are laid out precisely how you want to install
8160 them. In this situation you can use the @code{nobase_} prefix to
8161 suppress the base name step. For example:
8164 nobase_include_HEADERS = stdio.h sys/types.h
8168 will install @file{stdio.h} in @samp{$(includedir)} and @file{types.h}
8169 in @samp{$(includedir)/sys}.
8171 For most file types, Automake will install multiple files at once, while
8172 avoiding command line length issues (@pxref{Length Limitations}). Since
8173 some @command{install} programs will not install the same file twice in
8174 one invocation, you may need to ensure that file lists are unique within
8175 one variable such as @samp{nobase_include_HEADERS} above.
8177 You should not rely on the order in which files listed in one variable
8178 are installed. Likewise, to cater for parallel make, you should not
8179 rely on any particular file installation order even among different
8180 file types (library dependencies are an exception here).
8183 @node The Two Parts of Install
8184 @section The Two Parts of Install
8186 Automake generates separate @code{install-data} and @code{install-exec}
8187 rules, in case the installer is installing on multiple machines that
8188 share directory structure---these targets allow the machine-independent
8189 parts to be installed only once. @code{install-exec} installs
8190 platform-dependent files, and @code{install-data} installs
8191 platform-independent files. The @code{install} target depends on both
8192 of these targets. While Automake tries to automatically segregate
8193 objects into the correct category, the @file{Makefile.am} author is, in
8194 the end, responsible for making sure this is done correctly.
8195 @trindex install-data
8196 @trindex install-exec
8198 @cindex Install, two parts of
8200 Variables using the standard directory prefixes @samp{data},
8201 @samp{info}, @samp{man}, @samp{include}, @samp{oldinclude},
8202 @samp{pkgdata}, or @samp{pkginclude} are installed by
8203 @code{install-data}.
8205 Variables using the standard directory prefixes @samp{bin},
8206 @samp{sbin}, @samp{libexec}, @samp{sysconf}, @samp{localstate},
8207 @samp{lib}, or @samp{pkglib} are installed by @code{install-exec}.
8209 For instance, @code{data_DATA} files are installed by @code{install-data},
8210 while @code{bin_PROGRAMS} files are installed by @code{install-exec}.
8212 Any variable using a user-defined directory prefix with
8213 @samp{exec} in the name (e.g.,
8214 @c Keep in sync with primary-prefix-couples-documented-valid.sh
8215 @code{myexecbin_PROGRAMS}) is installed by @code{install-exec}. All
8216 other user-defined prefixes are installed by @code{install-data}.
8218 @node Extending Installation
8219 @section Extending Installation
8221 It is possible to extend this mechanism by defining an
8222 @code{install-exec-local} or @code{install-data-local} rule. If these
8223 rules exist, they will be run at @samp{make install} time. These
8224 rules can do almost anything; care is required.
8225 @trindex install-exec-local
8226 @trindex install-data-local
8228 Automake also supports two install hooks, @code{install-exec-hook} and
8229 @code{install-data-hook}. These hooks are run after all other install
8230 rules of the appropriate type, exec or data, have completed. So, for
8231 instance, it is possible to perform post-installation modifications
8232 using an install hook. @xref{Extending}, for some examples.
8233 @cindex Install hook
8235 @node Staged Installs
8236 @section Staged Installs
8239 Automake generates support for the @code{DESTDIR} variable in all
8240 install rules. @code{DESTDIR} is used during the @samp{make install}
8241 step to relocate install objects into a staging area. Each object and
8242 path is prefixed with the value of @code{DESTDIR} before being copied
8243 into the install area. Here is an example of typical DESTDIR usage:
8246 mkdir /tmp/staging &&
8247 make DESTDIR=/tmp/staging install
8250 The @command{mkdir} command avoids a security problem if the attacker
8251 creates a symbolic link from @file{/tmp/staging} to a victim area;
8252 then @command{make} places install objects in a directory tree built under
8253 @file{/tmp/staging}. If @file{/gnu/bin/foo} and
8254 @file{/gnu/share/aclocal/foo.m4} are to be installed, the above command
8255 would install @file{/tmp/staging/gnu/bin/foo} and
8256 @file{/tmp/staging/gnu/share/aclocal/foo.m4}.
8258 This feature is commonly used to build install images and packages
8261 Support for @code{DESTDIR} is implemented by coding it directly into
8262 the install rules. If your @file{Makefile.am} uses a local install
8263 rule (e.g., @code{install-exec-local}) or an install hook, then you
8264 must write that code to respect @code{DESTDIR}.
8266 @xref{Makefile Conventions, , , standards, The GNU Coding Standards},
8267 for another usage example.
8269 @node Install Rules for the User
8270 @section Install Rules for the User
8272 Automake also generates rules for targets @code{uninstall},
8273 @code{installdirs}, and @code{install-strip}.
8275 @trindex installdirs
8276 @trindex install-strip
8278 Automake supports @code{uninstall-local} and @code{uninstall-hook}.
8279 There is no notion of separate uninstalls for ``exec'' and ``data'', as
8280 these features would not provide additional functionality.
8282 Note that @code{uninstall} is not meant as a replacement for a real
8287 @chapter What Gets Cleaned
8289 @cindex @samp{make clean} support
8291 The GNU Makefile Standards specify a number of different clean rules.
8292 @xref{Standard Targets, , Standard Targets for Users, standards,
8293 The GNU Coding Standards}.
8295 Generally the files that can be cleaned are determined automatically by
8296 Automake. Of course, Automake also recognizes some variables that can
8297 be defined to specify additional files to clean. These variables are
8298 @code{MOSTLYCLEANFILES}, @code{CLEANFILES}, @code{DISTCLEANFILES}, and
8299 @code{MAINTAINERCLEANFILES}.
8300 @vindex MOSTLYCLEANFILES
8302 @vindex DISTCLEANFILES
8303 @vindex MAINTAINERCLEANFILES
8305 @trindex mostlyclean-local
8306 @trindex clean-local
8307 @trindex distclean-local
8308 @trindex maintainer-clean-local
8309 When cleaning involves more than deleting some hard-coded list of
8310 files, it is also possible to supplement the cleaning rules with your
8311 own commands. Simply define a rule for any of the
8312 @code{mostlyclean-local}, @code{clean-local}, @code{distclean-local},
8313 or @code{maintainer-clean-local} targets (@pxref{Extending}). A common
8314 case is deleting a directory, for instance, a directory created by the
8322 Since @command{make} allows only one set of rules for a given target,
8323 a more extensible way of writing this is to use a separate target
8324 listed as a dependency:
8327 clean-local: clean-local-check
8328 .PHONY: clean-local-check
8333 As the GNU Standards aren't always explicit as to which files should
8334 be removed by which rule, we've adopted a heuristic that we believe
8335 was first formulated by Fran@,{c}ois Pinard:
8339 If @command{make} built it, and it is commonly something that one would
8340 want to rebuild (for instance, a @file{.o} file), then
8341 @code{mostlyclean} should delete it.
8344 Otherwise, if @command{make} built it, then @code{clean} should delete it.
8347 If @command{configure} built it, then @code{distclean} should delete it.
8350 If the maintainer built it (for instance, a @file{.info} file), then
8351 @code{maintainer-clean} should delete it. However
8352 @code{maintainer-clean} should not delete anything that needs to exist
8353 in order to run @samp{./configure && make}.
8356 We recommend that you follow this same set of heuristics in your
8361 @chapter What Goes in a Distribution
8364 * Basics of Distribution:: Files distributed by default
8365 * Fine-grained Distribution Control:: @code{dist_} and @code{nodist_} prefixes
8366 * The dist Hook:: A target for last-minute distribution changes
8367 * Checking the Distribution:: @samp{make distcheck} explained
8368 * The Types of Distributions:: A variety of formats and compression methods
8371 @node Basics of Distribution
8372 @section Basics of Distribution
8374 @cindex @samp{make dist}
8379 The @code{dist} rule in the generated @file{Makefile.in} can be used
8380 to generate a gzipped @code{tar} file and other flavors of archive for
8381 distribution. The file is named based on the @code{PACKAGE} and
8382 @code{VERSION} variables defined by @code{AM_INIT_AUTOMAKE}
8383 (@pxref{Macros}); more precisely the gzipped @code{tar} file is named
8384 @samp{@var{package}-@var{version}.tar.gz}.
8386 You can use the @command{make} variable @code{GZIP_ENV} to control how gzip
8387 is run. The default setting is @option{--best}.
8389 @cindex @code{m4_include}, distribution
8390 @cindex @code{include}, distribution
8393 For the most part, the files to distribute are automatically found by
8394 Automake: all source files are automatically included in a distribution,
8395 as are all @file{Makefile.am} and @file{Makefile.in} files. Automake also
8396 has a built-in list of commonly used files that are automatically
8397 included if they are found in the current directory (either physically,
8398 or as the target of a @file{Makefile.am} rule); this list is printed by
8399 @samp{automake --help}. Note that some files in this list are actually
8400 distributed only if other certain conditions hold (for example,
8401 @c Keep in sync with autodist-config-headers.sh
8402 the @file{config.h.top} and @file{config.h.bot} files are automatically
8403 distributed only if, e.g., @samp{AC_CONFIG_HEADERS([config.h])} is used
8404 in @file{configure.ac}). Also, files that are read by @command{configure}
8405 (i.e.@: the source files corresponding to the files specified in various
8406 Autoconf macros such as @code{AC_CONFIG_FILES} and siblings) are
8407 automatically distributed. Files included in a @file{Makefile.am} (using
8408 @code{include}) or in @file{configure.ac} (using @code{m4_include}), and
8409 helper scripts installed with @samp{automake --add-missing} are also
8413 Still, sometimes there are files that must be distributed, but which
8414 are not covered in the automatic rules. These files should be listed in
8415 the @code{EXTRA_DIST} variable. You can mention files from
8416 subdirectories in @code{EXTRA_DIST}.
8418 You can also mention a directory in @code{EXTRA_DIST}; in this case the
8419 entire directory will be recursively copied into the distribution.
8420 Please note that this will also copy @emph{everything} in the directory,
8421 including, e.g., Subversion's @file{.svn} private directories or CVS/RCS
8422 version control files; thus we recommend against using this feature
8423 as-is. However, you can use the @code{dist-hook} feature to
8424 ameliorate the problem; @pxref{The dist Hook}.
8427 @vindex DIST_SUBDIRS
8428 If you define @code{SUBDIRS}, Automake will recursively include the
8429 subdirectories in the distribution. If @code{SUBDIRS} is defined
8430 conditionally (@pxref{Conditionals}), Automake will normally include
8431 all directories that could possibly appear in @code{SUBDIRS} in the
8432 distribution. If you need to specify the set of directories
8433 conditionally, you can set the variable @code{DIST_SUBDIRS} to the
8434 exact list of subdirectories to include in the distribution
8435 (@pxref{Conditional Subdirectories}).
8438 @node Fine-grained Distribution Control
8439 @section Fine-grained Distribution Control
8443 Sometimes you need tighter control over what does @emph{not} go into the
8444 distribution; for instance, you might have source files that are
8445 generated and that you do not want to distribute. In this case
8446 Automake gives fine-grained control using the @code{dist} and
8447 @code{nodist} prefixes. Any primary or @code{_SOURCES} variable can be
8448 prefixed with @code{dist_} to add the listed files to the distribution.
8449 Similarly, @code{nodist_} can be used to omit the files from the
8452 As an example, here is how you would cause some data to be distributed
8453 while leaving some source code out of the distribution:
8456 dist_data_DATA = distribute-this
8458 nodist_foo_SOURCES = do-not-distribute.c
8462 @section The dist Hook
8466 Occasionally it is useful to be able to change the distribution before
8467 it is packaged up. If the @code{dist-hook} rule exists, it is run
8468 after the distribution directory is filled, but before the actual
8469 distribution archives are created. One way to use this is for
8470 removing unnecessary files that get recursively included by specifying
8471 a directory in @code{EXTRA_DIST}:
8476 rm -rf `find $(distdir)/doc -type d -name .svn`
8479 @c The caveates described here should be documented in 'disthook.sh'.
8481 Note that the @code{dist-hook} recipe shouldn't assume that the regular
8482 files in the distribution directory are writable; this might not be the
8483 case if one is packaging from a read-only source tree, or when a
8484 @code{make distcheck} is being done. For similar reasons, the recipe
8485 shouldn't assume that the subdirectories put into the distribution
8486 directory as effect of having them listed in @code{EXTRA_DIST} are
8487 writable. So, if the @code{dist-hook} recipe wants to modify the
8488 content of an existing file (or @code{EXTRA_DIST} subdirectory) in the
8489 distribution directory, it should explicitly to make it writable first:
8492 EXTRA_DIST = README doc
8494 chmod u+w $(distdir)/README $(distdir)/doc
8495 echo "Distribution date: `date`" >> README
8496 rm -f $(distdir)/doc/HACKING
8501 Two variables that come handy when writing @code{dist-hook} rules are
8502 @samp{$(distdir)} and @samp{$(top_distdir)}.
8504 @samp{$(distdir)} points to the directory where the @code{dist} rule
8505 will copy files from the current directory before creating the
8506 tarball. If you are at the top-level directory, then @samp{distdir =
8507 $(PACKAGE)-$(VERSION)}. When used from subdirectory named
8508 @file{foo/}, then @samp{distdir = ../$(PACKAGE)-$(VERSION)/foo}.
8509 @samp{$(distdir)} can be a relative or absolute path, do not assume
8512 @samp{$(top_distdir)} always points to the root directory of the
8513 distributed tree. At the top-level it's equal to @samp{$(distdir)}.
8514 In the @file{foo/} subdirectory
8515 @samp{top_distdir = ../$(PACKAGE)-$(VERSION)}.
8516 @samp{$(top_distdir)} too can be a relative or absolute path.
8518 Note that when packages are nested using @code{AC_CONFIG_SUBDIRS}
8519 (@pxref{Subpackages}), then @samp{$(distdir)} and
8520 @samp{$(top_distdir)} are relative to the package where @samp{make
8521 dist} was run, not to any sub-packages involved.
8523 @node Checking the Distribution
8524 @section Checking the Distribution
8526 @cindex @samp{make distcheck}
8528 Automake also generates a @code{distcheck} rule that can be of help
8529 to ensure that a given distribution will actually work. Simplifying
8530 a bit, we can say this rule first makes a distribution, and then,
8531 @emph{operating from it}, takes the following steps:
8534 tries to do a @code{VPATH} build (@pxref{VPATH Builds}), with the
8535 @code{srcdir} and all its content made @emph{read-only};
8537 runs the test suite (with @command{make check}) on this fresh build;
8539 installs the package in a temporary directory (with @command{make
8540 install}), and tries runs the test suite on the resulting installation
8541 (with @command{make installcheck});
8543 checks that the package can be correctly uninstalled (by @command{make
8544 uninstall}) and cleaned (by @code{make distclean});
8546 finally, makes another tarball to ensure the distribution is
8550 @vindex AM_DISTCHECK_CONFIGURE_FLAGS
8551 @vindex DISTCHECK_CONFIGURE_FLAGS
8552 @subheading DISTCHECK_CONFIGURE_FLAGS
8553 Building the package involves running @samp{./configure}. If you need
8554 to supply additional flags to @command{configure}, define them in the
8555 @code{AM_DISTCHECK_CONFIGURE_FLAGS} variable in your top-level
8556 @file{Makefile.am}. The user can still extend or override the flags
8557 provided there by defining the @code{DISTCHECK_CONFIGURE_FLAGS} variable,
8558 on the command line when invoking @command{make}.
8560 Still, developers are encouraged to strive to make their code buildable
8561 without requiring any special configure option; thus, in general, you
8562 shouldn't define @code{AM_DISTCHECK_CONFIGURE_FLAGS}. However, there
8563 might be few scenarios in which the use of this variable is justified.
8564 GNU @command{m4} offers an example. GNU @command{m4} configures by
8565 default with its experimental and seldom used "changeword" feature
8566 disabled; so in its case it is useful to have @command{make distcheck}
8567 run configure with the @option{--with-changeword} option, to ensure that
8568 the code for changeword support still compiles correctly.
8569 GNU @command{m4} also employs the @code{AM_DISTCHECK_CONFIGURE_FLAGS}
8570 variable to stress-test the use of @option{--program-prefix=g}, since at
8571 one point the @command{m4} build system had a bug where @command{make
8572 installcheck} was wrongly assuming it could blindly test "@command{m4}",
8573 rather than the just-installed "@command{gm4}".
8575 @trindex distcheck-hook
8576 @subheading distcheck-hook
8577 If the @code{distcheck-hook} rule is defined in your top-level
8578 @file{Makefile.am}, then it will be invoked by @code{distcheck} after
8579 the new distribution has been unpacked, but before the unpacked copy
8580 is configured and built. Your @code{distcheck-hook} can do almost
8581 anything, though as always caution is advised. Generally this hook is
8582 used to check for potential distribution errors not caught by the
8583 standard mechanism. Note that @code{distcheck-hook} as well as
8584 @code{AM_DISTCHECK_CONFIGURE_FLAGS} and @code{DISTCHECK_CONFIGURE_FLAGS}
8585 are not honored in a subpackage @file{Makefile.am}, but the flags from
8586 @code{AM_DISTCHECK_CONFIGURE_FLAGS} and @code{DISTCHECK_CONFIGURE_FLAGS}
8587 are passed down to the @command{configure} script of the subpackage.
8589 @cindex @samp{make distcleancheck}
8590 @trindex distcleancheck
8591 @vindex DISTCLEANFILES
8592 @vindex distcleancheck_listfiles
8594 @subheading distcleancheck
8595 Speaking of potential distribution errors, @code{distcheck} also
8596 ensures that the @code{distclean} rule actually removes all built
8597 files. This is done by running @samp{make distcleancheck} at the end of
8598 the @code{VPATH} build. By default, @code{distcleancheck} will run
8599 @code{distclean} and then make sure the build tree has been emptied by
8600 running @samp{$(distcleancheck_listfiles)}. Usually this check will
8601 find generated files that you forgot to add to the @code{DISTCLEANFILES}
8602 variable (@pxref{Clean}).
8604 The @code{distcleancheck} behavior should be OK for most packages,
8605 otherwise you have the possibility to override the definition of
8606 either the @code{distcleancheck} rule, or the
8607 @samp{$(distcleancheck_listfiles)} variable. For instance, to disable
8608 @code{distcleancheck} completely, add the following rule to your
8609 top-level @file{Makefile.am}:
8616 If you want @code{distcleancheck} to ignore built files that have not
8617 been cleaned because they are also part of the distribution, add the
8618 following definition instead:
8620 @c Keep in sync with distcleancheck.sh
8622 distcleancheck_listfiles = \
8623 find . -type f -exec sh -c 'test -f $(srcdir)/$$1 || echo $$1' \
8627 The above definition is not the default because it's usually an error if
8628 your Makefiles cause some distributed files to be rebuilt when the user
8629 build the package. (Think about the user missing the tool required to
8630 build the file; or if the required tool is built by your package,
8631 consider the cross-compilation case where it can't be run.) There is
8632 an entry in the FAQ about this (@pxref{Errors with distclean}), make
8633 sure you read it before playing with @code{distcleancheck_listfiles}.
8635 @cindex @samp{make distuninstallcheck}
8636 @trindex distuninstallcheck
8637 @vindex distuninstallcheck_listfiles
8639 @subheading distuninstallcheck
8640 @code{distcheck} also checks that the @code{uninstall} rule works
8641 properly, both for ordinary and @code{DESTDIR} builds. It does this
8642 by invoking @samp{make uninstall}, and then it checks the install tree
8643 to see if any files are left over. This check will make sure that you
8644 correctly coded your @code{uninstall}-related rules.
8646 By default, the checking is done by the @code{distuninstallcheck} rule,
8647 and the list of files in the install tree is generated by
8648 @samp{$(distuninstallcheck_listfiles)} (this is a variable whose value is
8649 a shell command to run that prints the list of files to stdout).
8651 Either of these can be overridden to modify the behavior of
8652 @code{distcheck}. For instance, to disable this check completely, you
8660 @node The Types of Distributions
8661 @section The Types of Distributions
8663 Automake generates rules to provide archives of the project for
8664 distributions in various formats. Their targets are:
8667 @item @code{dist-gzip}
8668 Generate a @samp{gzip} tar archive of the distribution. This is the
8669 only format enabled by default.
8673 @item @code{dist-bzip2}
8674 Generate a @samp{bzip2} tar archive of the distribution. bzip2 archives
8675 are frequently smaller than gzipped archives.
8676 By default, this rule makes @samp{bzip2} use a compression option of @option{-9}.
8677 To make it use a different one, set the @env{BZIP2} environment variable.
8678 For example, @samp{make dist-bzip2 BZIP2=-7}.
8681 @item @code{dist-lzip}
8682 Generate an @samp{lzip} tar archive of the distribution. @command{lzip}
8683 archives are frequently smaller than @command{bzip2}-compressed archives.
8687 @item @code{dist-xz}
8688 Generate an @samp{xz} tar archive of the distribution. @command{xz}
8689 archives are frequently smaller than @command{bzip2}-compressed archives.
8690 By default, this rule makes @samp{xz} use a compression option of
8691 @option{-e}. To make it use a different one, set the @env{XZ_OPT}
8692 environment variable. For example, run this command to use the
8693 default compression ratio, but with a progress indicator:
8694 @samp{make dist-xz XZ_OPT=-ve}.
8697 @item @code{dist-zip}
8698 Generate a @samp{zip} archive of the distribution.
8701 @item @code{dist-tarZ}
8702 Generate a tar archive of the distribution, compressed with the
8703 historical (and obsolescent) program @command{compress}. This
8704 option is deprecated, and it and the corresponding functionality
8705 will be removed altogether in Automake 2.0.
8708 @item @code{dist-shar}
8709 Generate a @samp{shar} archive of the distribution. This format
8710 archive is obsolescent, and use of this option is deprecated.
8711 It and the corresponding functionality will be removed altogether
8717 The rule @code{dist} (and its historical synonym @code{dist-all})
8718 will create archives in all the enabled formats (@pxref{List of
8719 Automake options} for how to change this list). By default, only
8720 the @code{dist-gzip} target is hooked to @code{dist}.
8724 @chapter Support for test suites
8727 @cindex @code{make check}
8730 Automake can generate code to handle two kinds of test suites. One is
8731 based on integration with the @command{dejagnu} framework. The other
8732 (and most used) form is based on the use of generic test scripts, and
8733 its activation is triggered by the definition of the special @code{TESTS}
8734 variable. This second form allows for various degrees of sophistication
8735 and customization; in particular, it allows for concurrent execution
8736 of test scripts, use of established test protocols such as TAP, and
8737 definition of custom test drivers and test runners.
8740 In either case, the testsuite is invoked via @samp{make check}.
8743 * Generalities about Testing:: Concepts and terminology about testing
8744 * Simple Tests:: Listing test scripts in @code{TESTS}
8745 * Custom Test Drivers:: Writing and using custom test drivers
8746 * Using the TAP test protocol:: Integrating test scripts that use the TAP protocol
8747 * DejaGnu Tests:: Interfacing with the @command{dejagnu} testing framework
8748 * Install Tests:: Running tests on installed packages
8751 @node Generalities about Testing
8752 @section Generalities about Testing
8754 The purpose of testing is to determine whether a program or system behaves
8755 as expected (e.g., known inputs produce the expected outputs, error
8756 conditions are correctly handled or reported, and older bugs do not
8760 The minimal unit of testing is usually called @emph{test case}, or simply
8761 @emph{test}. How a test case is defined or delimited, and even what
8762 exactly @emph{constitutes} a test case, depends heavily on the testing
8763 paradigm and/or framework in use, so we won't attempt any more precise
8764 definition. The set of the test cases for a given program or system
8765 constitutes its @emph{testsuite}.
8767 @cindex test harness
8768 @cindex testsuite harness
8769 A @emph{test harness} (also @emph{testsuite harness}) is a program or
8770 software component that executes all (or part of) the defined test cases,
8771 analyzes their outcomes, and report or register these outcomes
8772 appropriately. Again, the details of how this is accomplished (and how
8773 the developer and user can influence it or interface with it) varies
8774 wildly, and we'll attempt no precise definition.
8777 @cindex test failure
8778 A test is said to @emph{pass} when it can determine that the condition or
8779 behaviour it means to verify holds, and is said to @emph{fail} when it can
8780 determine that such condition of behaviour does @emph{not} hold.
8783 Sometimes, tests can rely on non-portable tools or prerequisites, or
8784 simply make no sense on a given system (for example, a test checking a
8785 Windows-specific feature makes no sense on a GNU/Linux system). In this
8786 case, accordingly to the definition above, the tests can neither be
8787 considered passed nor failed; instead, they are @emph{skipped} -- i.e.,
8788 they are not run, or their result is anyway ignored for what concerns
8789 the count of failures an successes. Skips are usually explicitly
8790 reported though, so that the user will be aware that not all of the
8791 testsuite has really run.
8794 @cindex expected failure
8795 @cindex expected test failure
8797 @cindex unexpected pass
8798 @cindex unexpected test pass
8799 It's not uncommon, especially during early development stages, that some
8800 tests fail for known reasons, and that the developer doesn't want to
8801 tackle these failures immediately (this is especially true when the
8802 failing tests deal with corner cases). In this situation, the better
8803 policy is to declare that each of those failures is an @emph{expected
8804 failure} (or @emph{xfail}). In case a test that is expected to fail ends
8805 up passing instead, many testing environments will flag the result as a
8806 special kind of failure called @emph{unexpected pass} (or @emph{xpass}).
8809 @cindex Distinction between errors and failures in testsuites
8810 Many testing environments and frameworks distinguish between test failures
8811 and hard errors. As we've seen, a test failure happens when some invariant
8812 or expected behaviour of the software under test is not met. An @emph{hard
8813 error} happens when e.g., the set-up of a test case scenario fails, or when
8814 some other unexpected or highly undesirable condition is encountered (for
8815 example, the program under test experiences a segmentation fault).
8817 @emph{TODO}: Links to other test harnesses (esp. those sharing our
8821 @section Simple Tests
8824 * Scripts-based Testsuites:: Automake-specific concepts and terminology
8825 * Serial Test Harness:: Older (and discouraged) serial test harness
8826 * Parallel Test Harness:: Generic concurrent test harness
8829 @node Scripts-based Testsuites
8830 @subsection Scripts-based Testsuites
8832 If the special variable @code{TESTS} is defined, its value is taken to be
8833 a list of programs or scripts to run in order to do the testing. Under
8834 the appropriate circumstances, it's possible for @code{TESTS} to list
8835 also data files to be passed to one or more test scripts defined by
8836 different means (the so-called ``log compilers'', @pxref{Parallel Test
8839 Test scripts can be executed serially or concurrently. Automake supports
8840 both these kinds of test execution, with the parallel test harness being
8841 the default. The concurrent test harness relies on the concurrence
8842 capabilities (if any) offered by the underlying @command{make}
8843 implementation, and can thus only be as good as those are.
8845 By default, only the exit statuses of the test scripts are considered when
8846 determining the testsuite outcome. But Automake allows also the use of
8847 more complex test protocols, either standard (@pxref{Using the TAP test
8848 protocol}) or custom (@pxref{Custom Test Drivers}). Note that you can't
8849 enable such protocols when the serial harness is used, though.
8850 In the rest of this section we are going to concentrate mostly on
8851 protocol-less tests, since we cover test protocols in a later section
8852 (again, @pxref{Custom Test Drivers}).
8854 @cindex Exit status 77, special interpretation
8855 @cindex Exit status 99, special interpretation
8856 When no test protocol is in use, an exit status of 0 from a test script will
8857 denote a success, an exit status of 77 a skipped test, an exit status of 99
8858 an hard error, and any other exit status will denote a failure.
8860 @cindex Tests, expected failure
8861 @cindex Expected test failure
8863 @vindex DISABLE_HARD_ERRORS
8864 @cindex Disabling hard errors
8865 You may define the variable @code{XFAIL_TESTS} to a list of tests
8866 (usually a subset of @code{TESTS}) that are expected to fail; this will
8867 effectively reverse the result of those tests (with the provision that
8868 skips and hard errors remain untouched). You may also instruct the
8869 testsuite harness to treat hard errors like simple failures, by defining
8870 the @code{DISABLE_HARD_ERRORS} make variable to a nonempty value.
8872 Note however that, for tests based on more complex test protocols,
8873 the exact effects of @code{XFAIL_TESTS} and @code{DISABLE_HARD_ERRORS}
8874 might change, or they might even have no effect at all (for example,
8875 @c Keep this in sync with tap-no-disable-hard-errors.sh
8876 in tests using TAP, there is not way to disable hard errors, and the
8877 @code{DISABLE_HARD_ERRORS} variable has no effect on them).
8879 @anchor{Testsuite progress on console}
8880 @cindex Testsuite progress on console
8881 The result of each test case run by the scripts in @code{TESTS} will be
8882 printed on standard output, along with the test name. For test protocols
8883 that allow more test cases per test script (such as TAP), a number,
8884 identifier and/or brief description specific for the single test case is
8885 expected to be printed in addition to the name of the test script. The
8886 possible results (whose meanings should be clear from the previous
8887 @ref{Generalities about Testing}) are @code{PASS}, @code{FAIL},
8888 @code{SKIP}, @code{XFAIL}, @code{XPASS} and @code{ERROR}. Here is an
8889 example of output from an hypothetical testsuite that uses both plain
8891 @c Keep in sync with tap-doc.sh
8894 PASS: zardoz.tap 1 - Daemon started
8895 PASS: zardoz.tap 2 - Daemon responding
8896 SKIP: zardoz.tap 3 - Daemon uses /proc # SKIP /proc is not mounted
8897 PASS: zardoz.tap 4 - Daemon stopped
8900 XFAIL: mu.tap 2 # TODO frobnication not yet implemented
8904 A testsuite summary (expected to report at least the number of run,
8905 skipped and failed tests) will be printed at the end of the testsuite
8908 @anchor{Simple tests and color-tests}
8909 @vindex AM_COLOR_TESTS
8910 @cindex Colorized testsuite output
8911 If the standard output is connected to a capable terminal, then the test
8912 results and the summary are colored appropriately. The developer and the
8913 user can disable colored output by setting the @command{make} variable
8914 @samp{AM_COLOR_TESTS=no}; the user can in addition force colored output
8915 even without a connecting terminal with @samp{AM_COLOR_TESTS=always}.
8916 It's also worth noting that some @command{make} implementations,
8917 when used in parallel mode, have slightly different semantics
8918 (@pxref{Parallel make,,, autoconf, The Autoconf Manual}), which can
8919 break the automatic detection of a connection to a capable terminal.
8920 If this is the case, the user will have to resort to the use of
8921 @samp{AM_COLOR_TESTS=always} in order to have the testsuite output
8924 Test programs that need data files should look for them in @code{srcdir}
8925 (which is both a make variable and an environment variable made available
8926 to the tests), so that they work when building in a separate directory
8927 (@pxref{Build Directories, , Build Directories , autoconf,
8928 The Autoconf Manual}), and in particular for the @code{distcheck} rule
8929 (@pxref{Checking the Distribution}).
8932 @vindex TESTS_ENVIRONMENT
8933 @vindex AM_TESTS_ENVIRONMENT
8934 The @code{AM_TESTS_ENVIRONMENT} and @code{TESTS_ENVIRONMENT} variables can
8935 be used to run initialization code and set environment variables for the
8936 test scripts. The former variable is developer-reserved, and can be
8937 defined in the @file{Makefile.am}, while the latter is reserved for the
8938 user, which can employ it to extend or override the settings in the
8939 former; for this to work portably, however, the contents of a non-empty
8940 @code{AM_TESTS_ENVIRONMENT} @emph{must} be terminated by a semicolon.
8942 @vindex AM_TESTS_FD_REDIRECT
8943 The @code{AM_TESTS_FD_REDIRECT} variable can be used to define file
8944 descriptor redirections for the test scripts. One might think that
8945 @code{AM_TESTS_ENVIRONMENT} could be used for this purpose, but experience
8946 has shown that doing so portably is practically impossible. The main
8947 hurdle is constituted by Korn shells, which usually set the close-on-exec
8948 flag on file descriptors opened with the @command{exec} builtin, thus
8949 rendering an idiom like @code{AM_TESTS_ENVIRONMENT = exec 9>&2;}
8950 ineffectual. This issue also affects some Bourne shells, such as the
8951 HP-UX's @command{/bin/sh},
8952 @c FIXME: should we offer a link to the relevant discussions on the
8953 @c bug-autoconf list?
8955 @c Keep in sync with tests-environment-backcompat.sh
8957 AM_TESTS_ENVIRONMENT = \
8958 ## Some environment initializations are kept in a separate shell
8959 ## file 'tests-env.sh', which can make it easier to also run tests
8960 ## from the command line.
8961 . $(srcdir)/tests-env.sh; \
8962 ## On Solaris, prefer more POSIX-compliant versions of the standard
8963 ## tools by default.
8964 if test -d /usr/xpg4/bin; then \
8965 PATH=/usr/xpg4/bin:$$PATH; export PATH; \
8967 @c $$ restore font-lock
8968 ## With this, the test scripts will be able to print diagnostic
8969 ## messages to the original standard error stream, even if the test
8970 ## driver redirects the stderr of the test scripts to a log file
8971 ## before executing them.
8972 AM_TESTS_FD_REDIRECT = 9>&2
8976 Note however that @code{AM_TESTS_ENVIRONMENT} is, for historical and
8977 implementation reasons, @emph{not} supported by the serial harness
8978 (@pxref{Serial Test Harness}).
8980 Automake ensures that each file listed in @code{TESTS} is built before
8981 it is run; you can list both source and derived programs (or scripts)
8982 in @code{TESTS}; the generated rule will look both in @code{srcdir} and
8983 @file{.}. For instance, you might want to run a C program as a test.
8984 To do this you would list its name in @code{TESTS} and also in
8985 @code{check_PROGRAMS}, and then specify it as you would any other
8988 Programs listed in @code{check_PROGRAMS} (and @code{check_LIBRARIES},
8989 @code{check_LTLIBRARIES}...) are only built during @code{make check},
8990 not during @code{make all}. You should list there any program needed
8991 by your tests that does not need to be built by @code{make all}. Note
8992 that @code{check_PROGRAMS} are @emph{not} automatically added to
8993 @code{TESTS} because @code{check_PROGRAMS} usually lists programs used
8994 by the tests, not the tests themselves. Of course you can set
8995 @code{TESTS = $(check_PROGRAMS)} if all your programs are test cases.
8997 @node Serial Test Harness
8998 @subsection Older (and discouraged) serial test harness
8999 @cindex @option{serial-tests}, Using
9001 First, note that today the use of this harness is strongly discouraged in
9002 favour of the parallel test harness (@pxref{Parallel Test Harness}).
9003 Still, there are @emph{few} situations when the advantages offered by
9004 the parallel harness are irrelevant, and when test concurrency can
9005 even cause tricky problems. In those cases, it might make sense to
9006 still use the serial harness, for simplicity and reliability (we still
9007 suggest trying to give the parallel harness a shot though).
9009 The serial test harness is enabled by the Automake option
9010 @option{serial-tests}. It operates by simply running the tests serially,
9011 one at the time, without any I/O redirection. It's up to the user to
9012 implement logging of tests' output, if that's requited or desired.
9013 @c TODO: give an example of how this can be done.
9015 For historical and implementation reasons, the @code{AM_TESTS_ENVIRONMENT}
9016 variable is @emph{not} supported by this harness (it will be silently
9017 ignored if defined); only @code{TESTS_ENVIRONMENT} is, and it is to be
9018 considered a developer-reserved variable. This is done so that, when
9019 using the serial harness, @code{TESTS_ENVIRONMENT} can be defined to an
9020 invocation of an interpreter through which the tests are to be run.
9021 For instance, the following setup may be used to run tests with Perl:
9024 TESTS_ENVIRONMENT = $(PERL) -Mstrict -w
9025 TESTS = foo.pl bar.pl baz.pl
9029 It's important to note that the use of @code{TESTS_ENVIRONMENT} endorsed
9030 here would be @emph{invalid} with the parallel harness. That harness
9031 provides a more elegant way to achieve the same effect, with the further
9032 benefit of freeing the @code{TESTS_ENVIRONMENT} variable for the user
9033 (@pxref{Parallel Test Harness}).
9035 Another, less serious limit of the serial harness is that it doesn't
9036 really distinguish between simple failures and hard errors; this is
9037 due to historical reasons only, and might be fixed in future Automake
9040 @node Parallel Test Harness
9041 @subsection Parallel Test Harness
9043 By default, Automake generated a parallel (concurrent) test harness. It
9044 features automatic collection of the test scripts output in @file{.log}
9045 files, concurrent execution of tests with @code{make -j}, specification
9046 of inter-test dependencies, lazy reruns of tests that have not completed
9047 in a prior run, and hard errors for exceptional failures.
9049 @anchor{Basics of test metadata}
9050 @vindex TEST_SUITE_LOG
9052 @cindex @file{.log} files
9053 @cindex @file{.trs} files
9054 @cindex test metadata
9055 The parallel test harness operates by defining a set of @command{make}
9056 rules that run the test scripts listed in @code{TESTS}, and, for each
9057 such script, save its output in a corresponding @file{.log} file and
9058 its results (and other ``metadata'', @pxref{API for Custom Test Drivers})
9059 in a corresponding @file{.trs} (as in @b{T}est @b{R}e@b{S}ults) file.
9060 @c We choose the '.trs' extension also because, at the time of writing,
9061 @c it isn't already used for other significant purposes; see e.g.:
9062 @c - http://filext.com/file-extension/trs
9063 @c - http://www.file-extensions.org/search/?searchstring=trs
9064 The @file{.log} file will contain all the output emitted by the test on
9065 its standard output and its standard error. The @file{.trs} file will
9066 contain, among the other things, the results of the test cases run by
9069 The parallel test harness will also create a summary log file,
9070 @code{TEST_SUITE_LOG}, which defaults to @file{test-suite.log} and requires
9071 a @file{.log} suffix. This file depends upon all the @file{.log} and
9072 @file{.trs} files created for the test scripts listed in @code{TESTS}.
9075 As with the serial harness above, by default one status line is printed
9076 per completed test, and a short summary after the suite has completed.
9077 However, standard output and standard error of the test are redirected
9078 to a per-test log file, so that parallel execution does not produce
9079 intermingled output. The output from failed tests is collected in the
9080 @file{test-suite.log} file. If the variable @samp{VERBOSE} is set, this
9081 file is output after the summary.
9082 @c FIXME: we should be clearer about what we mean exactly here ...
9083 For best results, the tests should be verbose by default now.
9085 @vindex TEST_EXTENSIONS
9087 Each couple of @file{.log} and @file{.trs} files is created when the
9088 corresponding test has completed. The set of log files is listed in
9089 the read-only variable @code{TEST_LOGS}, and defaults to @code{TESTS},
9090 with the executable extension if any (@pxref{EXEEXT}), as well as any
9091 suffix listed in @code{TEST_EXTENSIONS} removed, and @file{.log} appended.
9092 Results are undefined if a test file name ends in several concatenated
9093 suffixes. @code{TEST_EXTENSIONS} defaults to @file{.test}; it can be
9094 overridden by the user, in which case any extension listed in it must be
9095 constituted by a dot, followed by a non-digit alphabetic character,
9096 followed by any number of alphabetic characters.
9097 @c Keep in sync with test-extensions.sh
9098 For example, @samp{.sh}, @samp{.T} and @samp{.t1} are valid extensions,
9099 while @samp{.x-y}, @samp{.6c} and @samp{.t.1} are not.
9101 @cindex Configure substitutions in @code{TESTS}
9102 It is important to note that, due to current limitations (unlikely to be
9103 lifted), configure substitutions in the definition of @code{TESTS} can
9104 only work if they will expand to a list of tests that have a suffix listed
9105 in @code{TEST_EXTENSIONS}.
9107 @vindex _LOG_COMPILE
9108 @vindex _LOG_COMPILER
9111 @vindex LOG_COMPILER
9113 @vindex @var{ext}_LOG_COMPILE
9114 @vindex @var{ext}_LOG_COMPILER
9115 @vindex @var{ext}_LOG_FLAGS
9116 @vindex AM_@var{ext}_LOG_FLAGS
9117 @vindex AM_LOG_FLAGS
9118 For tests that match an extension @code{.@var{ext}} listed in
9119 @code{TEST_EXTENSIONS}, you can provide a custom ``test runner'' using
9120 the variable @code{@var{ext}_LOG_COMPILER} (note the upper-case
9121 extension) and pass options in @code{AM_@var{ext}_LOG_FLAGS} and allow
9122 the user to pass options in @code{@var{ext}_LOG_FLAGS}. It will cause
9123 all tests with this extension to be called with this runner. For all
9124 tests without a registered extension, the variables @code{LOG_COMPILER},
9125 @code{AM_LOG_FLAGS}, and @code{LOG_FLAGS} may be used. For example,
9127 @c Keep in sync with parallel-tests-log-compiler-example.sh
9129 TESTS = foo.pl bar.py baz
9130 TEST_EXTENSIONS = .pl .py
9131 PL_LOG_COMPILER = $(PERL)
9132 AM_PL_LOG_FLAGS = -w
9133 PY_LOG_COMPILER = $(PYTHON)
9134 AM_PY_LOG_FLAGS = -v
9135 LOG_COMPILER = ./wrapper-script
9140 will invoke @samp{$(PERL) -w foo.pl}, @samp{$(PYTHON) -v bar.py},
9141 and @samp{./wrapper-script -d baz} to produce @file{foo.log},
9142 @file{bar.log}, and @file{baz.log}, respectively. The @file{foo.trs},
9143 @file{bar.trs} and @file{baz.trs} files will be automatically produced
9146 It's important to note that, differently from what we've seen for the
9147 serial test harness (@pxref{Parallel Test Harness}), the
9148 @code{AM_TESTS_ENVIRONMENT} and @code{TESTS_ENVIRONMENT} variables
9149 @emph{cannot} be use to define a custom test runner; the
9150 @code{LOG_COMPILER} and @code{LOG_FLAGS} (or their extension-specific
9151 counterparts) should be used instead:
9155 AM_TESTS_ENVIRONMENT = PERL5LIB='$(srcdir)/lib' $(PERL) -Mstrict -w
9160 AM_TESTS_ENVIRONMENT = PERL5LIB='$(srcdir)/lib'; export PERL5LIB;
9161 LOG_COMPILER = $(PERL)
9162 AM_LOG_FLAGS = -Mstrict -w
9165 By default, the test suite harness will run all tests, but there are
9166 several ways to limit the set of tests that are run:
9170 You can set the @code{TESTS} variable. For example, you can use a
9171 command like this to run only a subset of the tests:
9174 env TESTS="foo.test bar.test" make -e check
9177 Note however that the command above will unconditionally overwrite the
9178 @file{test-suite.log} file, thus clobbering the recorded results
9179 of any previous testsuite run. This might be undesirable for packages
9180 whose testsuite takes long time to execute. Luckily, this problem can
9181 easily be avoided by overriding also @code{TEST_SUITE_LOG} at runtime;
9184 @c Keep in sync with parallel-tests-log-override-2.sh
9186 env TEST_SUITE_LOG=partial.log TESTS="..." make -e check
9189 will write the result of the partial testsuite runs to the
9190 @file{partial.log}, without touching @file{test-suite.log}.
9193 You can set the @code{TEST_LOGS} variable. By default, this variable is
9194 computed at @command{make} run time from the value of @code{TESTS} as
9195 described above. For example, you can use the following:
9198 set x subset*.log; shift
9199 env TEST_LOGS="foo.log $*" make -e check
9202 The comments made above about @code{TEST_SUITE_LOG} overriding applies
9206 @vindex RECHECK_LOGS
9207 @cindex lazy test execution
9208 By default, the test harness removes all old per-test @file{.log} and
9209 @file{.trs} files before it starts running tests to regenerate them. The
9210 variable @code{RECHECK_LOGS} contains the set of @file{.log} (and, by
9211 implication, @file{.trs}) files which are removed. @code{RECHECK_LOGS}
9212 defaults to @code{TEST_LOGS}, which means all tests need to be rechecked.
9213 By overriding this variable, you can choose which tests need to be
9214 reconsidered. For example, you can lazily rerun only those tests which
9215 are outdated, i.e., older than their prerequisite test files, by setting
9216 this variable to the empty value:
9219 env RECHECK_LOGS= make -e check
9224 You can ensure that all tests are rerun which have failed or passed
9225 unexpectedly, by running @code{make recheck} in the test directory.
9226 This convenience target will set @code{RECHECK_LOGS} appropriately
9227 before invoking the main test harness.
9231 In order to guarantee an ordering between tests even with @code{make
9232 -j@var{N}}, dependencies between the corresponding @file{.log} files
9233 may be specified through usual @command{make} dependencies. For example,
9234 the following snippet lets the test named @file{foo-execute.test} depend
9235 upon completion of the test @file{foo-compile.test}:
9238 TESTS = foo-compile.test foo-execute.test
9239 foo-execute.log: foo-compile.log
9243 Please note that this ordering ignores the @emph{results} of required
9244 tests, thus the test @file{foo-execute.test} is run even if the test
9245 @file{foo-compile.test} failed or was skipped beforehand. Further,
9246 please note that specifying such dependencies currently works only for
9247 tests that end in one of the suffixes listed in @code{TEST_EXTENSIONS}.
9249 Tests without such specified dependencies may be run concurrently with
9250 parallel @command{make -j@var{N}}, so be sure they are prepared for
9251 concurrent execution.
9254 @c Keep in sync with 'parallel-tests-extra-programs.sh'.
9255 The combination of lazy test execution and correct dependencies between
9256 tests and their sources may be exploited for efficient unit testing
9257 during development. To further speed up the edit-compile-test cycle, it
9258 may even be useful to specify compiled programs in @code{EXTRA_PROGRAMS}
9259 instead of with @code{check_PROGRAMS}, as the former allows intertwined
9260 compilation and test execution (but note that @code{EXTRA_PROGRAMS} are
9261 not cleaned automatically, @pxref{Uniform}).
9263 The variables @code{TESTS} and @code{XFAIL_TESTS} may contain
9264 conditional parts as well as configure substitutions. In the latter
9265 case, however, certain restrictions apply: substituted test names
9266 must end with a nonempty test suffix like @file{.test}, so that one of
9267 the inference rules generated by @command{automake} can apply. For
9268 literal test names, @command{automake} can generate per-target rules
9269 to avoid this limitation.
9271 Please note that it is currently not possible to use @code{$(srcdir)/}
9272 or @code{$(top_srcdir)/} in the @code{TESTS} variable. This technical
9273 limitation is necessary to avoid generating test logs in the source tree
9274 and has the unfortunate consequence that it is not possible to specify
9275 distributed tests that are themselves generated by means of explicit
9276 rules, in a way that is portable to all @command{make} implementations
9277 (@pxref{Make Target Lookup,,, autoconf, The Autoconf Manual}, the
9278 semantics of FreeBSD and OpenBSD @command{make} conflict with this).
9279 In case of doubt you may want to require to use GNU @command{make},
9280 or work around the issue with inference rules to generate the tests.
9282 @node Custom Test Drivers
9283 @section Custom Test Drivers
9286 * Overview of Custom Test Drivers Support::
9287 * Declaring Custom Test Drivers::
9288 * API for Custom Test Drivers::
9291 @node Overview of Custom Test Drivers Support
9292 @subsection Overview of Custom Test Drivers Support
9294 Starting from Automake version 1.12, the parallel test harness allows
9295 the package authors to use third-party custom test drivers, in case the
9296 default ones are inadequate for their purposes, or do not support their
9297 testing protocol of choice.
9299 A custom test driver is expected to properly run the test programs passed
9300 to it (including the command-line arguments passed to those programs, if
9301 any), to analyze their execution and outcome, to create the @file{.log}
9302 and @file{.trs} files associated to these test runs, and to display the test
9303 results on the console. It is responsibility of the author of the test
9304 driver to ensure that it implements all the above steps meaningfully and
9305 correctly; Automake isn't and can't be of any help here. On the other
9306 hand, the Automake-provided code for testsuite summary generation offers
9307 support for test drivers allowing several test results per test script,
9308 if they take care to register such results properly (@pxref{Log files
9309 generation and test results recording}).
9311 The exact details of how test scripts' results are to be determined and
9312 analyzed is left to the individual drivers. Some drivers might only
9313 consider the test script exit status (this is done for example by the
9314 default test driver used by the parallel test harness, described
9315 in the previous section). Other drivers might implement more complex and
9316 advanced test protocols, which might require them to parse and interpreter
9317 the output emitted by the test script they're running (examples of such
9318 protocols are TAP and SubUnit).
9320 It's very important to note that, even when using custom test drivers,
9321 most of the infrastructure described in the previous section about the
9322 parallel harness remains in place; this includes:
9326 list of test scripts defined in @code{TESTS}, and overridable at
9327 runtime through the redefinition of @code{TESTS} or @code{TEST_LOGS};
9329 concurrency through the use of @command{make}'s option @option{-j};
9331 per-test @file{.log} and @file{.trs} files, and generation of a summary
9332 @file{.log} file from them;
9334 @code{recheck} target, @code{RECHECK_LOGS} variable, and lazy reruns
9337 inter-test dependencies;
9339 support for @code{check_*} variables (@code{check_PROGRAMS},
9340 @code{check_LIBRARIES}, ...);
9342 use of @code{VERBOSE} environment variable to get verbose output on
9345 definition and honoring of @code{TESTS_ENVIRONMENT},
9346 @code{AM_TESTS_ENVIRONMENT} and @code{AM_TESTS_FD_REDIRECT}
9349 definition of generic and extension-specific @code{LOG_COMPILER} and
9350 @code{LOG_FLAGS} variables.
9354 On the other hand, the exact semantics of how (and if) testsuite output
9355 colorization, @code{XFAIL_TESTS}, and hard errors are supported and
9356 handled is left to the individual test drivers.
9358 @c TODO: We should really add a working example in the doc/ directory,
9359 @c TODO: and reference if from here.
9361 @node Declaring Custom Test Drivers
9362 @subsection Declaring Custom Test Drivers
9365 @vindex _LOG_DRIVER_FLAGS
9367 @vindex LOG_DRIVER_FLAGS
9368 @vindex @var{ext}_LOG_DRIVER
9369 @vindex @var{ext}_LOG_DRIVER_FLAGS
9370 @vindex AM_@var{ext}_LOG_DRIVER_FLAGS
9371 @vindex AM_LOG_DRIVER_FLAGS
9372 Custom testsuite drivers are declared by defining the make variables
9373 @code{LOG_DRIVER} or @code{@var{ext}_LOG_DRIVER} (where @var{ext} must
9374 be declared in @code{TEST_EXTENSIONS}). They must be defined to
9375 programs or scripts that will be used to drive the execution, logging,
9376 and outcome report of the tests with corresponding extensions (or of
9377 those with no registered extension in the case of @code{LOG_DRIVER}).
9378 Clearly, multiple distinct test drivers can be declared in the same
9379 @file{Makefile.am}. Note moreover that the @code{LOG_DRIVER} variables
9380 are @emph{not} a substitute for the @code{LOG_COMPILER} variables: the
9381 two sets of variables can, and often do, usefully and legitimately
9384 @c TODO: We should really be able to point to a clarifying example here!
9386 The developer-reserved variable @code{AM_LOG_DRIVER_FLAGS} and the
9387 user-reserved variable @code{LOG_DRIVER_FLAGS} can be used to define
9388 flags that will be passed to each invocation of @code{LOG_DRIVER},
9389 with the user-defined flags obviously taking precedence over the
9390 developer-reserved ones. Similarly, for each extension @var{ext}
9391 declared in @code{TEST_EXTENSIONS}, flags listed in
9392 @code{AM_@var{ext}_LOG_DRIVER_FLAGS} and
9393 @code{@var{ext}_LOG_DRIVER_FLAGS} will be passed to
9394 invocations of @code{@var{ext}_LOG_DRIVER}.
9396 @node API for Custom Test Drivers
9397 @subsection API for Custom Test Drivers
9399 Note that @emph{the APIs described here are still highly experimental},
9400 and will very likely undergo tightenings and likely also extensive changes
9401 in the future, to accommodate for new features or to satisfy additional
9402 portability requirements.
9404 The main characteristic of these APIs is that they are designed to share
9405 as much infrastructure, semantics, and implementation details as possible
9406 with the parallel test harness and its default driver.
9409 * Command-line arguments for test drivers::
9410 * Log files generation and test results recording::
9411 * Testsuite progress output::
9414 @node Command-line arguments for test drivers
9415 @subsubsection Command-line arguments for test drivers
9417 A custom driver can rely on various command-line options and arguments
9418 being passed to it automatically by the Automake-generated test harness.
9419 It is @emph{mandatory} that it understands all of them (even if the exact
9420 interpretation of the associated semantics can legitimately change
9421 between a test driver and another, and even be a no-op in some drivers).
9424 Here is the list of options:
9427 @item --test-name=@var{NAME}
9428 The name of the test, with VPATH prefix (if any) removed. This can have a
9429 suffix and a directory component (as in e.g., @file{sub/foo.test}), and is
9430 mostly meant to be used in console reports about testsuite advancements and
9431 results (@pxref{Testsuite progress output}).
9432 @item --log-file=@file{@var{PATH}.log}
9433 The @file{.log} 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.log}), the test harness will ensure that such directory
9436 exists @emph{before} the test driver is called.
9437 @item --trs-file=@file{@var{PATH}.trs}
9438 The @file{.trs} file the test driver must create (@pxref{Basics of
9439 test metadata}). If it has a directory component (as in e.g.,
9440 @file{sub/foo.trs}), the test harness will ensure that such directory
9441 exists @emph{before} the test driver is called.
9442 @item --color-tests=@{yes|no@}
9443 Whether the console output should be colorized or not (@pxref{Simple
9444 tests and color-tests}, to learn when this option gets activated and
9446 @item --expect-failure=@{yes|no@}
9447 Whether the tested program is expected to fail.
9448 @item --enable-hard-errors=@{yes|no@}
9449 Whether ``hard errors'' in the tested program should be treated differently
9450 from normal failures or not (the default should be @code{yes}). The exact
9451 meaning of ``hard error'' is highly dependent from the test protocols or
9454 Explicitly terminate the list of options.
9458 The first non-option argument passed to the test driver is the program to
9459 be run, and all the following ones are command-line options and arguments
9462 Note that the exact semantics attached to the @option{--color-tests},
9463 @option{--expect-failure} and @option{--enable-hard-errors} options are
9464 left up to the individual test drivers. Still, having a behaviour
9465 compatible or at least similar to that provided by the default driver
9466 is advised, as that would offer a better consistency and a more pleasant
9469 @node Log files generation and test results recording
9470 @subsubsection Log files generation and test results recording
9472 The test driver must correctly generate the files specified by the
9473 @option{--log-file} and @option{--trs-file} option (even when the tested
9474 program fails or crashes).
9476 The @file{.log} file should ideally contain all the output produced by the
9477 tested program, plus optionally other information that might facilitate
9478 debugging or analysis of bug reports. Apart from that, its format is
9481 The @file{.trs} file is used to register some metadata through the use
9482 of custom reStructuredText fields. This metadata is expected to be
9483 employed in various ways by the parallel test harness; for example, to
9484 count the test results when printing the testsuite summary, or to decide
9485 which tests to re-run upon @command{make reheck}. Unrecognized metadata
9486 in a @file{.trs} file is currently ignored by the harness, but this might
9487 change in the future. The list of currently recognized metadata follows.
9492 @cindex Register test result
9493 @cindex Register test case result
9494 @cindex Test result, registering
9495 @cindex Test case result, registering
9496 @cindex @code{:test-result:}
9497 @cindex reStructuredText field, @code{:test-result:}
9498 The test driver must use this field to register the results of @emph{each}
9499 test case run by a test script file. Several @code{:test-result:} fields
9500 can be present in the same @file{.trs} file; this is done in order to
9501 support test protocols that allow a single test script to run more test
9504 @c Keep this in sync with lib/am/check-am:$(TEST_SUITE_LOG).
9505 The only recognized test results are currently @code{PASS}, @code{XFAIL},
9506 @code{SKIP}, @code{FAIL}, @code{XPASS} and @code{ERROR}. These results,
9507 when declared with @code{:test-result:}, can be optionally followed by
9508 text holding the name and/or a brief description of the corresponding
9509 test; the harness will ignore such extra text when generating
9510 @file{test-suite.log} and preparing the testsuite summary.
9512 @c Keep in sync with 'test-metadata-recheck.sh'.
9513 @item @code{:recheck:}
9515 @cindex reStructuredText field, @code{:recheck:}
9516 If this field is present and defined to @code{no}, then the corresponding
9517 test script will @emph{not} be run upon a @command{make recheck}. What
9518 happens when two or more @code{:recheck:} fields are present in the same
9519 @file{.trs} file is undefined behaviour.
9521 @c Keep in sync with 'test-metadata-global-log.sh'.
9522 @item @code{:copy-in-global-log:}
9523 @cindex :copy-in-global-log:
9524 @cindex reStructuredText field, @code{:copy-in-global-log:}
9525 If this field is present and defined to @code{no}, then the content
9526 of the @file{.log} file will @emph{not} be copied into the global
9527 @file{test-suite.log}. We allow to forsake such copying because, while
9528 it can be useful in debugging and analysis of bug report, it can also be
9529 just a waste of space in normal situations, e.g., when a test script is
9530 successful. What happens when two or more @code{:copy-in-global-log:}
9531 fields are present in the same @file{.trs} file is undefined behaviour.
9533 @c Keep in sync with 'test-metadata-global-result.sh'.
9534 @item @code{:test-global-result:}
9535 @cindex :test-global-result:
9536 @cindex reStructuredText field, @code{:test-global-result:}
9537 This is used to declare the "global result" of the script. Currently,
9538 the value of this field is needed only to be reported (more or less
9539 verbatim) in the generated global log file @code{$(TEST_SUITE_LOG)},
9540 so it's quite free-form. For example, a test script which run 10 test
9541 cases, 6 of which pass and 4 of which are skipped, could reasonably have
9542 a @code{PASS/SKIP} value for this field, while a test script which run
9543 19 successful tests and one failed test could have an @code{ALMOST
9544 PASSED} value. What happens when two or more @code{:test-global-result:}
9545 fields are present in the same @file{.trs} file is undefined behaviour.
9549 Let's see a small example. Assume a @file{.trs} file contains the
9553 :test-result: PASS server starts
9554 :global-log-copy: no
9555 :test-result: PASS HTTP/1.1 request
9556 :test-result: FAIL HTTP/1.0 request
9558 :test-result: SKIP HTTPS request (TLS library wasn't available)
9559 :test-result: PASS server stops
9563 Then the corresponding test script will be re-run by @command{make check},
9564 will contribute with @emph{five} test results to the testsuite summary
9565 (three of these tests being successful, one failed, and one skipped), and
9566 the content of the corresponding @file{.log} file will @emph{not} be
9567 copied in the global log file @file{test-suite.log}.
9569 @node Testsuite progress output
9570 @subsubsection Testsuite progress output
9572 A custom test driver also has the task of displaying, on the standard
9573 output, the test results as soon as they become available. Depending on
9574 the protocol in use, it can also display the reasons for failures and
9575 skips, and, more generally, any useful diagnostic output (but remember
9576 that each line on the screen is precious, so that cluttering the screen
9577 with overly verbose information is bad idea). The exact format of this
9578 progress output is left up to the test driver; in fact, a custom test
9579 driver might @emph{theoretically} even decide not to do any such report,
9580 leaving it all to the testsuite summary (that would be a very lousy idea,
9581 of course, and serves only to illustrate the flexibility that is
9584 Remember that consistency is good; so, if possible, try to be consistent
9585 with the output of the built-in Automake test drivers, providing a similar
9586 ``look & feel''. In particular, the testsuite progress output should be
9587 colorized when the @option{--color-tests} is passed to the driver. On the
9588 other end, if you are using a known and widespread test protocol with
9589 well-established implementations, being consistent with those
9590 implementations' output might be a good idea too.
9592 @c TODO: Give an example, maybe inspired to py.test-style output.
9593 @c TODO: That is a good idea because it shows a test driver that allows
9594 @c TODO: for different levels of verbosity in the progress output (could
9595 @c TODO: be implemented either using a driver cmdline flag, or an
9596 @c TODO: environment variable, or both).
9598 @node Using the TAP test protocol
9599 @section Using the TAP test protocol
9602 * Introduction to TAP::
9603 * Use TAP with the Automake test harness::
9604 * Incompatibilities with other TAP parsers and drivers::
9605 * Links and external resources on TAP::
9608 @node Introduction to TAP
9609 @subsection Introduction to TAP
9611 TAP, the Test Anything Protocol, is a simple text-based interface between
9612 testing modules or programs and a test harness. The tests (also called
9613 ``TAP producers'' in this context) write test results in a simple format
9614 on standard output; a test harness (also called ``TAP consumer'') will
9615 parse and interpret these results, and properly present them to the user,
9616 and/or register them for later analysis. The exact details of how this
9617 is accomplished can vary among different test harnesses. The Automake
9618 harness will present the results on the console in the usual
9619 fashion (@pxref{Testsuite progress on console}), and will use the
9620 @file{.trs} files (@pxref{Basics of test metadata}) to store the test
9621 results and related metadata. Apart from that, it will try to remain
9622 as much compatible as possible with pre-existing and widespread utilities,
9623 such as the @uref{http://search.cpan.org/~andya/Test-Harness/bin/prove,
9624 @command{prove} utility}, at least for the simpler usages.
9626 TAP started its life as part of the test harness for Perl, but today
9627 it has been (mostly) standardized, and has various independent
9628 implementations in different languages; among them, C, C++, Perl,
9629 Python, PHP, and Java. For a semi-official specification of the
9630 TAP protocol, please refer to the documentation of
9631 @uref{http://search.cpan.org/~petdance/Test-Harness/lib/Test/Harness/TAP.pod,
9632 @samp{Test::Harness::TAP}}.
9634 The most relevant real-world usages of TAP are obviously in the testsuites
9635 of @command{perl} and of many perl modules. Still, also other important
9636 third-party packages, such as @uref{http://git-scm.com/, @command{git}},
9637 use TAP in their testsuite.
9639 @node Use TAP with the Automake test harness
9640 @subsection Use TAP with the Automake test harness
9642 Currently, the TAP driver that comes with Automake requires some by-hand
9643 steps on the developer's part (this situation should hopefully be improved
9644 in future Automake versions). You'll have to grab the @file{tap-driver.sh}
9645 script from the Automake distribution by hand, copy it in your source tree,
9646 add a call to @code{AC_PROG_AWK} in @file{configure.ac} to search for a
9647 proper awk program, and use the Automake support for third-party test
9648 drivers to instruct the harness to use the @file{tap-driver.sh} script
9649 and that awk program to run your TAP-producing tests. See the example
9650 below for clarification.
9652 Apart from the options common to all the Automake test drivers
9653 (@pxref{Command-line arguments for test drivers}), the @file{tap-driver.sh}
9654 supports the following options, whose names are chosen for enhanced
9655 compatibility with the @command{prove} utility.
9658 @c Keep in sync with 'tap-exit.sh' and 'tap-signal.tap'.
9660 Causes the test driver to ignore the exit status of the test scripts;
9661 by default, the driver will report an error if the script exits with a
9662 non-zero status. This option has effect also on non-zero exit statuses
9663 due to termination by a signal.
9665 Instruct the test driver to display TAP diagnostic (i.e., lines beginning
9666 with the @samp{#} character) in the testsuite progress output too; by
9667 default, TAP diagnostic is only copied to the @file{.log} file.
9669 Revert the effects of @option{--comments}.
9671 Instruct the test driver to merge the test scripts' standard error into
9672 their standard output. This is necessary if you want to ensure that
9673 diagnostics from the test scripts are displayed in the correct order
9674 relative to test results; this can be of great help in debugging
9675 (especially if your test scripts are shell scripts run with shell
9676 tracing active). As a downside, this option might cause the test
9677 harness to get confused if anything that appears on standard error
9678 looks like a test result.
9680 Revert the effects of @option{--merge}.
9681 @item --diagnostic-string=@var{STRING}
9682 Change the string that introduces TAP diagnostic from the default value
9683 of ``@code{#}'' to @code{@var{STRING}}. This can be useful if your
9684 TAP-based test scripts produce verbose output on which they have limited
9685 control (because, say, the output comes from other tools invoked in the
9686 scripts), and it might contain text that gets spuriously interpreted as
9687 TAP diagnostic: such an issue can be solved by redefining the string that
9688 activates TAP diagnostic to a value you know won't appear by chance in
9689 the tests' output. Note however that this feature is non-standard, as
9690 the ``official'' TAP protocol does not allow for such a customization; so
9691 don't use it if you can avoid it.
9695 Here is an example of how the TAP driver can be set up and used.
9697 @c Keep in sync with tap-doc2.sh
9699 % @kbd{cat configure.ac}
9700 AC_INIT([GNU Try Tap], [1.0], [bug-automake@@gnu.org])
9701 AC_CONFIG_AUX_DIR([build-aux])
9702 AM_INIT_AUTOMAKE([foreign -Wall -Werror])
9703 AC_CONFIG_FILES([Makefile])
9704 AC_REQUIRE_AUX_FILE([tap-driver.sh])
9708 % @kbd{cat Makefile.am}
9709 TEST_LOG_DRIVER = env AM_TAP_AWK='$(AWK)' $(SHELL) \
9710 $(top_srcdir)/build-aux/tap-driver.sh
9711 TESTS = foo.test bar.test baz.test
9712 EXTRA_DIST = $(TESTS)
9714 % @kbd{cat foo.test}
9716 echo 1..4 # Number of tests to be executed.
9717 echo 'ok 1 - Swallows fly'
9718 echo 'not ok 2 - Caterpillars fly # TODO metamorphosis in progress'
9719 echo 'ok 3 - Pigs fly # SKIP not enough acid'
9720 echo '# I just love word plays ...'
9721 echo 'ok 4 - Flies fly too :-)'
9723 % @kbd{cat bar.test}
9726 echo 'not ok 1 - Bummer, this test has failed.'
9727 echo 'ok 2 - This passed though.'
9728 echo 'Bail out! Ennui kicking in, sorry...'
9729 echo 'ok 3 - This will not be seen.'
9731 % @kbd{cat baz.test}
9735 # Exit with error, even if all the tests have been successful.
9738 % @kbd{cp @var{PREFIX}/share/automake-@var{APIVERSION}/tap-driver.pl .}
9739 % @kbd{autoreconf -vi && ./configure && make check}
9741 PASS: foo.test 1 - Swallows fly
9742 XFAIL: foo.test 2 - Caterpillars fly # TODO metamorphosis in progress
9743 SKIP: foo.test 3 - Pigs fly # SKIP not enough acid
9744 PASS: foo.test 4 - Flies fly too :-)
9745 FAIL: bar.test 1 - Bummer, this test has failed.
9746 PASS: bar.test 2 - This passed though.
9747 ERROR: bar.test - Bail out! Ennui kicking in, sorry...
9749 ERROR: baz.test - exited with status 7
9751 Please report to bug-automake@@gnu.org
9753 % @kbd{echo exit status: $?}
9756 @c Keep the "skewed" indentation below, it produces pretty PDF output.
9757 % @kbd{env TEST_LOG_DRIVER_FLAGS='--comments --ignore-exit' \
9758 TESTS='foo.test baz.test' make -e check}
9760 PASS: foo.test 1 - Swallows fly
9761 XFAIL: foo.test 2 - Caterpillars fly # TODO metamorphosis in progress
9762 SKIP: foo.test 3 - Pigs fly # SKIP not enough acid
9763 # foo.test: I just love word plays...
9764 PASS: foo.test 4 - Flies fly too :-)
9767 % @kbd{echo exit status: $?}
9771 @node Incompatibilities with other TAP parsers and drivers
9772 @subsection Incompatibilities with other TAP parsers and drivers
9774 For implementation or historical reasons, the TAP driver and harness as
9775 implemented by Automake have some minors incompatibilities with the
9776 mainstream versions, which you should be aware of.
9780 A @code{Bail out!} directive doesn't stop the whole testsuite, but only
9781 the test script it occurs in. This doesn't follow TAP specifications,
9782 but on the other hand it maximizes compatibility (and code sharing) with
9783 the ``hard error'' concept of the default testsuite driver.
9785 The @code{version} and @code{pragma} directives are not supported.
9787 The @option{--diagnostic-string} option of our driver allows to modify
9788 the string that introduces TAP diagnostic from the default value
9789 of ``@code{#}''. The standard TAP protocol has currently no way to
9790 allow this, so if you use it your diagnostic will be lost to more
9791 compliant tools like @command{prove} and @code{Test::Harness}
9793 And there are probably some other small and yet undiscovered
9794 incompatibilities, especially in corner cases or with rare usages.
9797 @node Links and external resources on TAP
9798 @subsection Links and external resources on TAP
9801 Here are some links to more extensive official or third-party
9802 documentation and resources about the TAP protocol and related
9803 tools and libraries.
9806 @uref{http://search.cpan.org/~petdance/Test-Harness/lib/Test/Harness/TAP.pod,
9807 @samp{Test::Harness::TAP}},
9808 the (mostly) official documentation about the TAP format and protocol.
9810 @uref{http://search.cpan.org/~andya/Test-Harness/bin/prove,
9812 the most famous command-line TAP test driver, included in the distribution
9813 of @command{perl} and
9814 @uref{http://search.cpan.org/~andya/Test-Harness/lib/Test/Harness.pm,
9815 @samp{Test::Harness}}.
9817 The @uref{http://testanything.org/wiki/index.php/Main_Page,TAP wiki}.
9819 A ``gentle introduction'' to testing for perl coders:
9820 @uref{http://search.cpan.org/dist/Test-Simple/lib/Test/Tutorial.pod,
9821 @samp{Test::Tutorial}}.
9823 @uref{http://search.cpan.org/~mschwern/Test-Simple/lib/Test/Simple.pm,
9824 @samp{Test::Simple}}
9826 @uref{http://search.cpan.org/~mschwern/Test-Simple/lib/Test/More.pm,
9828 the standard perl testing libraries, which are based on TAP.
9830 @uref{http://www.eyrie.org/~eagle/software/c-tap-harness/,C TAP Harness},
9831 a C-based project implementing both a TAP producer and a TAP consumer.
9833 @uref{http://www.tap4j.org/,tap4j},
9834 a Java-based project implementing both a TAP producer and a TAP consumer.
9838 @section DejaGnu Tests
9840 If @uref{ftp://ftp.gnu.org/gnu/dejagnu/, @command{dejagnu}} appears in
9841 @code{AUTOMAKE_OPTIONS}, then a @command{dejagnu}-based test suite is
9842 assumed. The variable @code{DEJATOOL} is a list of names that are
9843 passed, one at a time, as the @option{--tool} argument to
9844 @command{runtest} invocations; it defaults to the name of the package.
9846 The variable @code{RUNTESTDEFAULTFLAGS} holds the @option{--tool} and
9847 @option{--srcdir} flags that are passed to dejagnu by default; this can be
9848 overridden if necessary.
9849 @vindex RUNTESTDEFAULTFLAGS
9851 The variables @code{EXPECT} and @code{RUNTEST} can
9852 also be overridden to provide project-specific values. For instance,
9853 you will need to do this if you are testing a compiler toolchain,
9854 because the default values do not take into account host and target
9861 The contents of the variable @code{RUNTESTFLAGS} are passed to the
9862 @code{runtest} invocation. This is considered a ``user variable''
9863 (@pxref{User Variables}). If you need to set @command{runtest} flags in
9864 @file{Makefile.am}, you can use @code{AM_RUNTESTFLAGS} instead.
9865 @vindex RUNTESTFLAGS
9866 @vindex AM_RUNTESTFLAGS
9868 @cindex @file{site.exp}
9869 Automake will generate rules to create a local @file{site.exp} file,
9870 defining various variables detected by @command{configure}. This file
9871 is automatically read by DejaGnu. It is OK for the user of a package
9872 to edit this file in order to tune the test suite. However this is
9873 not the place where the test suite author should define new variables:
9874 this should be done elsewhere in the real test suite code.
9875 Especially, @file{site.exp} should not be distributed.
9877 Still, if the package author has legitimate reasons to extend
9878 @file{site.exp} at @command{make} time, he can do so by defining
9879 the variable @code{EXTRA_DEJAGNU_SITE_CONFIG}; the files listed
9880 there will be considered @file{site.exp} prerequisites, and their
9881 content will be appended to it (in the same order in which they
9882 appear in @code{EXTRA_DEJAGNU_SITE_CONFIG}). Note that files are
9883 @emph{not} distributed by default.
9885 For more information regarding DejaGnu test suites, see @ref{Top, , ,
9886 dejagnu, The DejaGnu Manual}.
9889 @section Install Tests
9891 The @code{installcheck} target is available to the user as a way to
9892 run any tests after the package has been installed. You can add tests
9893 to this by writing an @code{installcheck-local} rule.
9897 @chapter Rebuilding Makefiles
9898 @cindex rebuild rules
9900 Automake generates rules to automatically rebuild @file{Makefile}s,
9901 @file{configure}, and other derived files like @file{Makefile.in}.
9903 @acindex AM_MAINTAINER_MODE
9904 If you are using @code{AM_MAINTAINER_MODE} in @file{configure.ac}, then
9905 these automatic rebuilding rules are only enabled in maintainer mode.
9907 @vindex CONFIG_STATUS_DEPENDENCIES
9908 @vindex CONFIGURE_DEPENDENCIES
9909 @cindex @file{version.sh}, example
9910 @cindex @file{version.m4}, example
9912 Sometimes it is convenient to supplement the rebuild rules for
9913 @file{configure} or @file{config.status} with additional dependencies.
9914 The variables @code{CONFIGURE_DEPENDENCIES} and
9915 @code{CONFIG_STATUS_DEPENDENCIES} can be used to list these extra
9916 dependencies. These variables should be defined in all
9917 @file{Makefile}s of the tree (because these two rebuild rules are
9918 output in all them), so it is safer and easier to @code{AC_SUBST} them
9919 from @file{configure.ac}. For instance, the following statement will
9920 cause @file{configure} to be rerun each time @file{version.sh} is
9923 @c Keep in sync with remake-config-status-dependencies.sh
9925 AC_SUBST([CONFIG_STATUS_DEPENDENCIES], ['$(top_srcdir)/version.sh'])
9929 Note the @samp{$(top_srcdir)/} in the file name. Since this variable
9930 is to be used in all @file{Makefile}s, its value must be sensible at
9931 any level in the build hierarchy.
9933 Beware not to mistake @code{CONFIGURE_DEPENDENCIES} for
9934 @code{CONFIG_STATUS_DEPENDENCIES}.
9936 @c Keep in sync with remake-configure-dependencies.sh
9937 @code{CONFIGURE_DEPENDENCIES} adds dependencies to the
9938 @file{configure} rule, whose effect is to run @command{autoconf}. This
9939 variable should be seldom used, because @command{automake} already tracks
9940 @code{m4_include}d files. However it can be useful when playing
9941 tricky games with @code{m4_esyscmd} or similar non-recommendable
9942 macros with side effects. Be also aware that interactions of this
9943 variable with the @ref{Autom4te Cache, , autom4te cache, autoconf,
9944 The Autoconf Manual} are quite problematic and can cause subtle
9945 breakage, so you might want to disable the cache if you want to use
9946 @code{CONFIGURE_DEPENDENCIES}.
9948 @code{CONFIG_STATUS_DEPENDENCIES} adds dependencies to the
9949 @file{config.status} rule, whose effect is to run @file{configure}.
9950 This variable should therefore carry any non-standard source that may
9951 be read as a side effect of running @command{configure}, like @file{version.sh}
9952 in the example above.
9954 Speaking of @file{version.sh} scripts, we recommend against them
9955 today. They are mainly used when the version of a package is updated
9956 automatically by a script (e.g., in daily builds). Here is what some
9957 old-style @file{configure.ac}s may look like:
9961 . $srcdir/version.sh
9962 AM_INIT_AUTOMAKE([name], $VERSION_NUMBER)
9967 Here, @file{version.sh} is a shell fragment that sets
9968 @code{VERSION_NUMBER}. The problem with this example is that
9969 @command{automake} cannot track dependencies (listing @file{version.sh}
9970 in @command{CONFIG_STATUS_DEPENDENCIES}, and distributing this file is up
9971 to the user), and that it uses the obsolete form of @code{AC_INIT} and
9972 @code{AM_INIT_AUTOMAKE}. Upgrading to the new syntax is not
9973 straightforward, because shell variables are not allowed in
9974 @code{AC_INIT}'s arguments. We recommend that @file{version.sh} be
9975 replaced by an M4 file that is included by @file{configure.ac}:
9978 m4_include([version.m4])
9979 AC_INIT([name], VERSION_NUMBER)
9985 Here @file{version.m4} could contain something like
9986 @samp{m4_define([VERSION_NUMBER], [1.2])}. The advantage of this
9987 second form is that @command{automake} will take care of the
9988 dependencies when defining the rebuild rule, and will also distribute
9989 the file automatically. An inconvenience is that @command{autoconf}
9990 will now be rerun each time the version number is bumped, when only
9991 @file{configure} had to be rerun in the previous setup.
9995 @chapter Changing Automake's Behavior
9998 * Options generalities:: Semantics of Automake option
9999 * List of Automake options:: A comprehensive list of Automake options
10002 @node Options generalities
10003 @section Options generalities
10005 Various features of Automake can be controlled by options. Except where
10006 noted otherwise, options can be specified in one of several ways. Most
10007 options can be applied on a per-@file{Makefile} basis when listed in a
10008 special @file{Makefile} variable named @code{AUTOMAKE_OPTIONS}. Some
10009 of these options only make sense when specified in the toplevel
10010 @file{Makefile.am} file. Options are applied globally to all processed
10011 @file{Makefile} files when listed in the first argument of
10012 @code{AM_INIT_AUTOMAKE} in @file{configure.ac}, and some options which
10013 require changes to the @command{configure} script can only be specified
10014 there. These are annotated below.
10016 As a general rule, options specified in @code{AUTOMAKE_OPTIONS} take
10017 precedence over those specified in @code{AM_INIT_AUTOMAKE}, which in
10018 turn take precedence over those specified on the command line.
10020 Also, some care must be taken about the interactions among strictness
10021 level and warning categories. As a general rule, strictness-implied
10022 warnings are overridden by those specified by explicit options. For
10023 example, even if @samp{portability} warnings are disabled by default
10024 in @option{foreign} strictness, an usage like this will end up enabling
10028 AUTOMAKE_OPTIONS = -Wportability foreign
10031 However, a strictness level specified in a higher-priority context
10032 will override all the explicit warnings specified in a lower-priority
10033 context. For example, if @file{configure.ac} contains:
10036 AM_INIT_AUTOMAKE([-Wportability])
10040 and @file{Makefile.am} contains:
10043 AUTOMAKE_OPTIONS = foreign
10047 then @samp{portability} warnings will be @emph{disabled} in
10048 @file{Makefile.am}.
10050 @node List of Automake options
10051 @section List of Automake options
10053 @vindex AUTOMAKE_OPTIONS
10056 @item @option{gnits}
10057 @itemx @option{gnu}
10058 @itemx @option{foreign}
10059 @cindex Option, @option{gnits}
10060 @cindex Option, @option{gnu}
10061 @cindex Option, @option{foreign}
10066 Set the strictness as appropriate. The @option{gnits} option also
10067 implies options @option{readme-alpha} and @option{check-news}.
10069 @item @option{check-news}
10070 @cindex Option, @option{check-news}
10071 @opindex check-news
10072 Cause @samp{make dist} to fail unless the current version number appears
10073 in the first few lines of the @file{NEWS} file.
10075 @item @option{dejagnu}
10076 @cindex Option, @option{dejagnu}
10078 Cause @command{dejagnu}-specific rules to be generated. @xref{DejaGnu Tests}.
10080 @item @option{dist-bzip2}
10081 @cindex Option, @option{dist-bzip2}
10082 @opindex dist-bzip2
10083 Hook @code{dist-bzip2} to @code{dist}.
10084 @trindex dist-bzip2
10086 @item @option{dist-lzip}
10087 @cindex Option, @option{dist-lzip}
10089 Hook @code{dist-lzip} to @code{dist}.
10092 @item @option{dist-xz}
10093 @cindex Option, @option{dist-xz}
10095 Hook @code{dist-xz} to @code{dist}.
10098 @item @option{dist-zip}
10099 @cindex Option, @option{dist-zip}
10101 Hook @code{dist-zip} to @code{dist}.
10104 @item @option{dist-shar}
10105 @cindex Option, @option{dist-shar}
10107 Hook @code{dist-shar} to @code{dist}. Use of this option
10108 is deprecated, as the @samp{shar} format is obsolescent and
10109 problematic. Support for it will be removed altogether in
10113 @item @option{dist-tarZ}
10114 @cindex Option, @option{dist-tarZ}
10116 Hook @code{dist-tarZ} to @code{dist}. Use of this option
10117 is deprecated, as the @samp{compress} program is obsolete.
10118 Support for it will be removed altogether in Automake 2.0.
10121 @item @option{filename-length-max=99}
10122 @cindex Option, @option{filename-length-max=99}
10123 @opindex filename-length-max=99
10124 Abort if file names longer than 99 characters are found during
10125 @samp{make dist}. Such long file names are generally considered not to
10126 be portable in tarballs. See the @option{tar-v7} and @option{tar-ustar}
10127 options below. This option should be used in the top-level
10128 @file{Makefile.am} or as an argument of @code{AM_INIT_AUTOMAKE} in
10129 @file{configure.ac}, it will be ignored otherwise. It will also be
10130 ignored in sub-packages of nested packages (@pxref{Subpackages}).
10132 @item @option{info-in-builddir}
10133 @cindex Option, @option{info-in-builddir}
10134 @opindex info-in-builddir
10135 Instruct Automake to place the generated @file{.info} files in the
10136 @code{builddir} rather than in the @code{srcdir}. Note that this
10137 might make VPATH builds with some non-GNU make implementations more
10140 @item @option{no-define}
10141 @cindex Option, @option{no-define}
10143 This option is meaningful only when passed as an argument to
10144 @code{AM_INIT_AUTOMAKE}. It will prevent the @code{PACKAGE} and
10145 @code{VERSION} variables from being @code{AC_DEFINE}d.
10147 @item @option{no-dependencies}
10148 @cindex Option, @option{no-dependencies}
10149 @opindex no-dependencies
10150 This is similar to using @option{--ignore-deps} on the command line,
10151 but is useful for those situations where you don't have the necessary
10152 bits to make automatic dependency tracking work
10153 (@pxref{Dependencies}). In this case the effect is to effectively
10154 disable automatic dependency tracking.
10156 @item @option{no-dist}
10157 @cindex Option, @option{no-dist}
10159 Don't emit any code related to @code{dist} target. This is useful
10160 when a package has its own method for making distributions.
10162 @item @option{no-dist-gzip}
10163 @cindex Option, @option{no-dist-gzip}
10164 @opindex no-dist-gzip
10165 Do not hook @code{dist-gzip} to @code{dist}.
10166 @trindex no-dist-gzip
10168 @item @option{no-exeext}
10169 @cindex Option, @option{no-exeext}
10171 If your @file{Makefile.am} defines a rule for target @code{foo}, it
10172 will override a rule for a target named @samp{foo$(EXEEXT)}. This is
10173 necessary when @code{EXEEXT} is found to be empty. However, by
10174 default @command{automake} will generate an error for this use. The
10175 @option{no-exeext} option will disable this error. This is intended for
10176 use only where it is known in advance that the package will not be
10177 ported to Windows, or any other operating system using extensions on
10180 @item @option{no-installinfo}
10181 @cindex Option, @option{no-installinfo}
10182 @opindex no-installinfo
10183 The generated @file{Makefile.in} will not cause info pages to be built
10184 or installed by default. However, @code{info} and @code{install-info}
10185 targets will still be available. This option is disallowed at
10186 @option{gnu} strictness and above.
10188 @trindex install-info
10190 @item @option{no-installman}
10191 @cindex Option, @option{no-installman}
10192 @opindex no-installman
10193 The generated @file{Makefile.in} will not cause man pages to be
10194 installed by default. However, an @code{install-man} target will still
10195 be available for optional installation. This option is disallowed at
10196 @option{gnu} strictness and above.
10197 @trindex install-man
10199 @item @option{nostdinc}
10200 @cindex Option, @option{nostdinc}
10202 This option can be used to disable the standard @option{-I} options that
10203 are ordinarily automatically provided by Automake.
10205 @item @option{no-texinfo.tex}
10206 @cindex Option, @option{no-texinfo.tex}
10207 @opindex no-texinfo.tex
10208 Don't require @file{texinfo.tex}, even if there are texinfo files in
10211 @item @option{serial-tests}
10212 @cindex Option, @option{serial-tests}
10213 @opindex serial-tests
10214 Enable the older serial test suite harness for @code{TESTS} (@pxref{Serial
10215 Test Harness}, for more information).
10217 @item @option{parallel-tests}
10218 @cindex Option, @option{parallel-tests}
10219 @opindex parallel-tests
10220 Enable test suite harness for @code{TESTS} that can run tests in parallel
10221 (@pxref{Parallel Test Harness}, for more information). This option is
10222 only kept for backward-compatibility, since the parallel test harness is
10225 @item @option{readme-alpha}
10226 @cindex Option, @option{readme-alpha}
10227 @opindex readme-alpha
10228 If this release is an alpha release, and the file @file{README-alpha}
10229 exists, then it will be added to the distribution. If this option is
10230 given, version numbers are expected to follow one of two forms. The
10231 first form is @samp{@var{major}.@var{minor}.@var{alpha}}, where each
10232 element is a number; the final period and number should be left off for
10233 non-alpha releases. The second form is
10234 @samp{@var{major}.@var{minor}@var{alpha}}, where @var{alpha} is a
10235 letter; it should be omitted for non-alpha releases.
10237 @item @option{std-options}
10238 @cindex Options, @option{std-options}
10239 @cindex @samp{make installcheck}, testing @option{--help} and @option{--version}
10240 @cindex @option{--help} check
10241 @cindex @option{--version} check
10242 @opindex std-options
10244 Make the @code{installcheck} rule check that installed scripts and
10245 programs support the @option{--help} and @option{--version} options.
10246 This also provides a basic check that the program's
10247 run-time dependencies are satisfied after installation.
10249 @vindex AM_INSTALLCHECK_STD_OPTIONS_EXEMPT
10250 In a few situations, programs (or scripts) have to be exempted from this
10251 test. For instance, @command{false} (from GNU coreutils) is never
10252 successful, even for @option{--help} or @option{--version}. You can list
10253 such programs in the variable @code{AM_INSTALLCHECK_STD_OPTIONS_EXEMPT}.
10254 Programs (not scripts) listed in this variable should be suffixed by
10255 @samp{$(EXEEXT)} for the sake of Windows or OS/2. For instance, suppose we
10256 build @file{false} as a program but @file{true.sh} as a script, and that
10257 neither of them support @option{--help} or @option{--version}:
10260 AUTOMAKE_OPTIONS = std-options
10261 bin_PROGRAMS = false ...
10262 bin_SCRIPTS = true.sh ...
10263 AM_INSTALLCHECK_STD_OPTIONS_EXEMPT = false$(EXEEXT) true.sh
10266 @item @option{subdir-objects}
10267 @cindex Options, @option{subdir-objects}
10268 @opindex subdir-objects
10269 If this option is specified, then objects are placed into the
10270 subdirectory of the build directory corresponding to the subdirectory of
10271 the source file. For instance, if the source file is
10272 @file{subdir/file.cxx}, then the output file would be
10273 @file{subdir/file.o}.
10275 @anchor{tar-formats}
10276 @item @option{tar-v7}
10277 @itemx @option{tar-ustar}
10278 @itemx @option{tar-pax}
10279 @cindex Option, @option{tar-v7}
10280 @cindex Option, @option{tar-ustar}
10281 @cindex Option, @option{tar-pax}
10282 @cindex @command{tar} formats
10283 @cindex v7 @command{tar} format
10284 @cindex ustar format
10290 These three mutually exclusive options select the tar format to use
10291 when generating tarballs with @samp{make dist}. (The tar file created
10292 is then compressed according to the set of @option{no-dist-gzip},
10293 @option{dist-bzip2}, @option{dist-lzip}, @option{dist-xz} and
10294 @option{dist-tarZ} options in use.)
10296 These options must be passed as arguments to @code{AM_INIT_AUTOMAKE}
10297 (@pxref{Macros}) because they can require additional configure checks.
10298 Automake will complain if it sees such options in an
10299 @code{AUTOMAKE_OPTIONS} variable.
10301 @option{tar-v7} selects the old V7 tar format. This is the historical
10302 default. This antiquated format is understood by all tar
10303 implementations and supports file names with up to 99 characters. When
10304 given longer file names some tar implementations will diagnose the
10305 problem while other will generate broken tarballs or use non-portable
10306 extensions. Furthermore, the V7 format cannot store empty
10307 directories. When using this format, consider using the
10308 @option{filename-length-max=99} option to catch file names too long.
10310 @option{tar-ustar} selects the ustar format defined by POSIX
10311 1003.1-1988. This format is believed to be old enough to be portable.
10312 It fully supports empty directories. It can store file names with up
10313 to 256 characters, provided that the file name can be split at
10314 directory separator in two parts, first of them being at most 155
10315 bytes long. So, in most cases the maximum file name length will be
10316 shorter than 256 characters. However you may run against broken tar
10317 implementations that incorrectly handle file names longer than 99
10318 characters (please report them to @email{@value{PACKAGE_BUGREPORT}} so we
10319 can document this accurately).
10321 @option{tar-pax} selects the new pax interchange format defined by POSIX
10322 1003.1-2001. It does not limit the length of file names. However,
10323 this format is very young and should probably be restricted to
10324 packages that target only very modern platforms. There are moves to
10325 change the pax format in an upward-compatible way, so this option may
10326 refer to a more recent version in the future.
10328 @xref{Formats, , Controlling the Archive Format, tar, GNU Tar}, for
10329 further discussion about tar formats.
10331 @command{configure} knows several ways to construct these formats. It
10332 will not abort if it cannot find a tool up to the task (so that the
10333 package can still be built), but @samp{make dist} will fail.
10335 @item @var{version}
10336 @cindex Option, @var{version}
10337 A version number (e.g., @samp{0.30}) can be specified. If Automake is not
10338 newer than the version specified, creation of the @file{Makefile.in}
10339 will be suppressed.
10341 @item @option{-W@var{category}} or @option{--warnings=@var{category}}
10342 @cindex Option, warnings
10343 @cindex Option, @option{-W@var{category}}
10344 @cindex Option, @option{--warnings=@var{category}}
10345 These options behave exactly like their command-line counterpart
10346 (@pxref{automake Invocation}). This allows you to enable or disable some
10347 warning categories on a per-file basis. You can also setup some warnings
10348 for your entire project; for instance, try @samp{AM_INIT_AUTOMAKE([-Wall])}
10349 in your @file{configure.ac}.
10353 Unrecognized options are diagnosed by @command{automake}.
10355 If you want an option to apply to all the files in the tree, you can use
10356 the @code{AM_INIT_AUTOMAKE} macro in @file{configure.ac}.
10360 @node Miscellaneous
10361 @chapter Miscellaneous Rules
10363 There are a few rules and variables that didn't fit anywhere else.
10366 * Tags:: Interfacing to cscope, etags and mkid
10367 * Suffixes:: Handling new file extensions
10372 @section Interfacing to @command{etags}
10374 @cindex @file{TAGS} support
10376 Automake will generate rules to generate @file{TAGS} files for use with
10377 GNU Emacs under some circumstances.
10380 If any C, C++ or Fortran 77 source code or headers are present, then
10381 @code{tags} and @code{TAGS} rules will be generated for the directory.
10382 All files listed using the @code{_SOURCES}, @code{_HEADERS}, and
10383 @code{_LISP} primaries will be used to generate tags. Note that
10384 generated source files that are not distributed must be declared in
10385 variables like @code{nodist_noinst_HEADERS} or
10386 @code{nodist_@var{prog}_SOURCES} or they will be ignored.
10388 A @code{tags} rule will be output at the topmost directory of a
10389 multi-directory package. When run from this topmost directory,
10390 @samp{make tags} will generate a @file{TAGS} file that includes by
10391 reference all @file{TAGS} files from subdirectories.
10393 The @code{tags} rule will also be generated if the variable
10394 @code{ETAGS_ARGS} is defined. This variable is intended for use in
10395 directories that contain taggable source that @command{etags} does
10396 not understand. The user can use the @code{ETAGSFLAGS} to pass
10397 additional flags to @command{etags}; @code{AM_ETAGSFLAGS} is also
10398 available for use in @file{Makefile.am}.
10401 @vindex AM_ETAGSFLAGS
10403 Here is how Automake generates tags for its source, and for nodes in its
10407 ETAGS_ARGS = automake.in --lang=none \
10408 --regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi
10411 If you add file names to @code{ETAGS_ARGS}, you will probably also
10412 want to define @code{TAGS_DEPENDENCIES}. The contents of this variable
10413 are added directly to the dependencies for the @code{tags} rule.
10414 @vindex TAGS_DEPENDENCIES
10416 Automake also generates a @code{ctags} rule that can be used to
10417 build @command{vi}-style @file{tags} files. The variable @code{CTAGS}
10418 is the name of the program to invoke (by default @command{ctags});
10419 @code{CTAGSFLAGS} can be used by the user to pass additional flags,
10420 and @code{AM_CTAGSFLAGS} can be used by the @file{Makefile.am}.
10423 Automake will also generate an @code{ID} rule that will run
10424 @command{mkid} on the source. This is only supported on a
10425 directory-by-directory basis.
10427 Similarly, the @code{cscope} rule will create a list of all the source
10428 files in the tree and run @command{cscope} to build an inverted index
10429 database. The variable @code{CSCOPE} is the name of the program to invoke
10430 (by default @command{cscope}); @code{CSCOPEFLAGS} and
10431 @code{CSCOPE_ARGS} can be used by the user to pass additional flags and
10432 file names respectively, while @code{AM_CSCOPEFLAGS} can be used by the
10433 @file{Makefile.am}. Note that, currently, the Automake-provided
10434 @code{cscope} support, when used in a VPATH build, might not work well
10435 with non-GNU make implementations (especially with make implementations
10436 performing @ref{Automatic Rule Rewriting, , VPATH rewrites, autoconf,
10437 The Autoconf Manual}).
10439 Finally, Automake also emits rules to support the
10440 @uref{http://www.gnu.org/software/global/, GNU Global Tags program}.
10441 The @code{GTAGS} rule runs Global Tags and puts the
10442 result in the top build directory. The variable @code{GTAGS_ARGS}
10443 holds arguments that are passed to @command{gtags}.
10448 @section Handling new file extensions
10450 @cindex Adding new @code{SUFFIXES}
10451 @cindex @code{SUFFIXES}, adding
10454 It is sometimes useful to introduce a new implicit rule to handle a file
10455 type that Automake does not know about.
10457 For instance, suppose you had a compiler that could compile @file{.foo}
10458 files to @file{.o} files. You would simply define a suffix rule for
10466 Then you could directly use a @file{.foo} file in a @code{_SOURCES}
10467 variable and expect the correct results:
10470 bin_PROGRAMS = doit
10471 doit_SOURCES = doit.foo
10474 This was the simpler and more common case. In other cases, you will
10475 have to help Automake to figure out which extensions you are defining your
10476 suffix rule for. This usually happens when your extension does not
10477 start with a dot. Then, all you have to do is to put a list of new
10478 suffixes in the @code{SUFFIXES} variable @strong{before} you define your
10481 For instance, the following definition prevents Automake from misinterpreting
10482 the @samp{.idlC.cpp:} rule as an attempt to transform @file{.idlC} files into
10485 @c Keep in sync with suffix7.sh
10487 SUFFIXES = .idl C.cpp
10492 As you may have noted, the @code{SUFFIXES} variable behaves like the
10493 @code{.SUFFIXES} special target of @command{make}. You should not touch
10494 @code{.SUFFIXES} yourself, but use @code{SUFFIXES} instead and let
10495 Automake generate the suffix list for @code{.SUFFIXES}. Any given
10496 @code{SUFFIXES} go at the start of the generated suffixes list, followed
10497 by Automake generated suffixes not already in the list.
10503 @cindex Including @file{Makefile} fragment
10504 @cindex @file{Makefile} fragment, including
10506 Automake supports an @code{include} directive that can be used to
10507 include other @file{Makefile} fragments when @command{automake} is run.
10508 Note that these fragments are read and interpreted by @command{automake},
10509 not by @command{make}. As with conditionals, @command{make} has no idea that
10510 @code{include} is in use.
10512 There are two forms of @code{include}:
10515 @item include $(srcdir)/file
10516 Include a fragment that is found relative to the current source
10519 @item include $(top_srcdir)/file
10520 Include a fragment that is found relative to the top source directory.
10523 Note that if a fragment is included inside a conditional, then the
10524 condition applies to the entire contents of that fragment.
10526 Makefile fragments included this way are always distributed because
10527 they are needed to rebuild @file{Makefile.in}.
10529 Inside a fragment, the construct @code{%reldir%} is replaced with the
10530 directory of the fragment relative to the base @file{Makefile.am}.
10531 Similarly, @code{%canon_reldir%} is replaced with the canonicalized
10532 (@pxref{Canonicalization}) form of @code{%reldir%}. As a convenience,
10533 @code{%D%} is a synonym for @code{%reldir%}, and @code{%C%}
10534 is a synonym for @code{%canon_reldir%}.
10536 A special feature is that if the fragment is in the same directory as
10537 the base @file{Makefile.am} (i.e., @code{%reldir%} is @code{.}), then
10538 @code{%reldir%} and @code{%canon_reldir%} will expand to the empty
10539 string as well as eat, if present, a following slash or underscore
10542 Thus, a makefile fragment might look like this:
10545 bin_PROGRAMS += %reldir%/mumble
10546 %canon_reldir%_mumble_SOURCES = %reldir%/one.c
10550 @chapter Conditionals
10552 @cindex Conditionals
10554 Automake supports a simple type of conditionals.
10556 These conditionals are not the same as conditionals in
10557 GNU Make. Automake conditionals are checked at configure time by the
10558 @file{configure} script, and affect the translation from
10559 @file{Makefile.in} to @file{Makefile}. They are based on options passed
10560 to @file{configure} and on results that @file{configure} has discovered
10561 about the host system. GNU Make conditionals are checked at @command{make}
10562 time, and are based on variables passed to the make program or defined
10563 in the @file{Makefile}.
10565 Automake conditionals will work with any make program.
10568 * Usage of Conditionals:: Declaring conditional content
10569 * Limits of Conditionals:: Enclosing complete statements
10572 @node Usage of Conditionals
10573 @section Usage of Conditionals
10575 @acindex AM_CONDITIONAL
10576 Before using a conditional, you must define it by using
10577 @code{AM_CONDITIONAL} in the @file{configure.ac} file (@pxref{Macros}).
10579 @defmac AM_CONDITIONAL (@var{conditional}, @var{condition})
10580 The conditional name, @var{conditional}, should be a simple string
10581 starting with a letter and containing only letters, digits, and
10582 underscores. It must be different from @samp{TRUE} and @samp{FALSE}
10583 that are reserved by Automake.
10585 The shell @var{condition} (suitable for use in a shell @code{if}
10586 statement) is evaluated when @command{configure} is run. Note that you
10587 must arrange for @emph{every} @code{AM_CONDITIONAL} to be invoked every
10588 time @command{configure} is run. If @code{AM_CONDITIONAL} is run
10589 conditionally (e.g., in a shell @code{if} statement), then the result
10590 will confuse @command{automake}.
10593 @cindex @option{--enable-debug}, example
10594 @cindex Example conditional @option{--enable-debug}
10595 @cindex Conditional example, @option{--enable-debug}
10597 Conditionals typically depend upon options that the user provides to
10598 the @command{configure} script. Here is an example of how to write a
10599 conditional that is true if the user uses the @option{--enable-debug}
10603 AC_ARG_ENABLE([debug],
10604 [ --enable-debug Turn on debugging],
10605 [case "$@{enableval@}" in
10608 *) AC_MSG_ERROR([bad value $@{enableval@} for --enable-debug]) ;;
10609 esac],[debug=false])
10610 AM_CONDITIONAL([DEBUG], [test x$debug = xtrue])
10613 Here is an example of how to use that conditional in @file{Makefile.am}:
10625 noinst_PROGRAMS = $(DBG)
10628 This trivial example could also be handled using @code{EXTRA_PROGRAMS}
10629 (@pxref{Conditional Programs}).
10631 You may only test a single variable in an @code{if} statement, possibly
10632 negated using @samp{!}. The @code{else} statement may be omitted.
10633 Conditionals may be nested to any depth. You may specify an argument to
10634 @code{else} in which case it must be the negation of the condition used
10635 for the current @code{if}. Similarly you may specify the condition
10636 that is closed on the @code{endif} line:
10647 Unbalanced conditions are errors. The @code{if}, @code{else}, and
10648 @code{endif} statements should not be indented, i.e., start on column
10651 The @code{else} branch of the above two examples could be omitted,
10652 since assigning the empty string to an otherwise undefined variable
10653 makes no difference.
10655 @acindex AM_COND_IF
10656 In order to allow access to the condition registered by
10657 @code{AM_CONDITIONAL} inside @file{configure.ac}, and to allow
10658 conditional @code{AC_CONFIG_FILES}, @code{AM_COND_IF} may be used:
10660 @defmac AM_COND_IF (@var{conditional}, @ovar{if-true}, @ovar{if-false})
10661 If @var{conditional} is fulfilled, execute @var{if-true}, otherwise
10662 execute @var{if-false}. If either branch contains @code{AC_CONFIG_FILES},
10663 it will cause @command{automake} to output the rules for the respective
10664 files only for the given condition.
10667 @code{AM_COND_IF} macros may be nested when m4 quotation is used
10668 properly (@pxref{M4 Quotation, ,, autoconf, The Autoconf Manual}).
10670 @cindex Example conditional @code{AC_CONFIG_FILES}
10671 @cindex @code{AC_CONFIG_FILES}, conditional
10673 Here is an example of how to define a conditional config file:
10676 AM_CONDITIONAL([SHELL_WRAPPER], [test "x$with_wrapper" = xtrue])
10677 AM_COND_IF([SHELL_WRAPPER],
10678 [AC_CONFIG_FILES([wrapper:wrapper.in])])
10681 @node Limits of Conditionals
10682 @section Limits of Conditionals
10684 Conditionals should enclose complete statements like variables or
10685 rules definitions. Automake cannot deal with conditionals used inside
10686 a variable definition, for instance, and is not even able to diagnose
10687 this situation. The following example would not work:
10690 # This syntax is not understood by Automake
10699 However the intended definition of @code{AM_CPPFLAGS} can be achieved
10704 DEBUGFLAGS = -DDEBUG
10706 AM_CPPFLAGS = -DFEATURE_A $(DEBUGFLAGS) -DFEATURE_B
10713 AM_CPPFLAGS = -DFEATURE_A
10715 AM_CPPFLAGS += -DDEBUG
10717 AM_CPPFLAGS += -DFEATURE_B
10720 More details and examples of conditionals are described alongside
10721 various Automake features in this manual (@pxref{Conditional
10722 Subdirectories}, @pxref{Conditional Sources}, @pxref{Conditional
10723 Programs}, @pxref{Conditional Libtool Libraries}, @pxref{Conditional
10726 @node Silencing Make
10727 @chapter Silencing @command{make}
10729 @cindex Silent @command{make}
10730 @cindex Silencing @command{make}
10731 @cindex Silent rules
10732 @cindex Silent @command{make} rules
10735 * Make verbosity:: Make is verbose by default
10736 * Tricks For Silencing Make:: Standard and generic ways to silence make
10737 * Automake Silent Rules:: How Automake can help in silencing make
10740 @node Make verbosity
10741 @section Make is verbose by default
10743 Normally, when executing the set of rules associated with a target,
10744 @command{make} prints each rule before it is executed. This behaviour,
10745 while having been in place for a long time, and being even mandated by
10746 the POSIX standard, starkly violates the ``silence is golden'' UNIX
10747 principle@footnote{See also
10748 @uref{http://catb.org/~esr/writings/taoup/html/ch11s09.html}.}:
10751 When a program has nothing interesting or surprising to say, it should
10752 say nothing. Well-behaved Unix programs do their jobs unobtrusively,
10753 with a minimum of fuss and bother. Silence is golden.
10756 In fact, while such verbosity of @command{make} can theoretically be
10757 useful to track bugs and understand reasons of failures right away, it
10758 can also hide warning and error messages from @command{make}-invoked
10759 tools, drowning them in a flood of uninteresting and seldom useful
10760 messages, and thus allowing them to go easily undetected.
10762 This problem can be very annoying, especially for developers, who usually
10763 know quite well what's going on behind the scenes, and for whom the
10764 verbose output from @command{make} ends up being mostly noise that hampers
10765 the easy detection of potentially important warning messages.
10767 @node Tricks For Silencing Make
10768 @section Standard and generic ways to silence make
10770 Here we describe some common idioms/tricks to obtain a quieter make
10771 output, with their relative advantages and drawbacks. In the next
10772 section (@ref{Automake Silent Rules}) we'll see how Automake can help
10773 in this respect, providing more elaborate and flexible idioms.
10777 @item @command{make -s}
10779 This simply causes @command{make} not to print @emph{any} rule before
10782 The @option{-s} flag is mandated by POSIX, universally supported, and
10783 its purpose and function are easy to understand.
10785 But it also has its serious limitations too. First of all, it embodies
10786 an ``all or nothing'' strategy, i.e., either everything is silenced, or
10787 nothing is; this lack of granularity can sometimes be a fatal flaw.
10788 Moreover, when the @option{-s} flag is used, the @command{make} output
10789 might turn out to be too much terse; in case of errors, the user won't
10790 be able to easily see what rule or command have caused them, or even,
10791 in case of tools with poor error reporting, what the errors were!
10793 @item @command{make >/dev/null || make}
10795 Apparently, this perfectly obeys the ``silence is golden'' rule: warnings
10796 from stderr are passed through, output reporting is done only in case of
10797 error, and in that case it should provide a verbose-enough report to allow
10798 an easy determination of the error location and causes.
10800 However, calling @command{make} two times in a row might hide errors
10801 (especially intermittent ones), or subtly change the expected semantic
10802 of the @command{make} calls --- things these which can clearly make
10803 debugging and error assessment very difficult.
10805 @item @command{make --no-print-directory}
10807 This is GNU @command{make} specific. When called with the
10808 @option{--no-print-directory} option, GNU @command{make} will disable
10809 printing of the working directory by invoked sub-@command{make}s (the
10810 well-known ``@i{Entering/Leaving directory ...}'' messages). This helps
10811 to decrease the verbosity of the output, but experience has shown that
10812 it can also often render debugging considerably harder in projects using
10813 deeply-nested @command{make} recursion.
10815 As an aside, notice that the @option{--no-print-directory} option is
10816 automatically activated if the @option{-s} flag is used.
10818 @c TODO: Other tricks?
10819 @c TODO: Maybe speak about the @code{.SILENT} target?
10820 @c TODO: - Pros: More granularity on what to silence.
10821 @c TODO: - Cons: No easy way to temporarily override.
10825 @node Automake Silent Rules
10826 @section How Automake can help in silencing make
10828 The tricks and idioms for silencing @command{make} described in the
10829 previous section can be useful from time to time, but we've seen that
10830 they all have their serious drawbacks and limitations. That's why
10831 automake provides support for a more advanced and flexible way of
10832 obtaining quieter output from @command{make} (for most rules at least).
10834 @c TODO: Maybe describe in brief the precedent set by the build system
10835 @c of the Linux Kernel, from which Automake took inspiration ... Links?
10837 To give the gist of what Automake can do in this respect, here is a simple
10838 comparison between a typical @command{make} output (where silent rules
10839 are disabled) and one with silent rules enabled:
10842 % @kbd{cat Makefile.am}
10844 foo_SOURCES = main.c func.c
10846 int main (void) @{ return func (); @} /* func used undeclared */
10848 int func (void) @{ int i; return i; @} /* i used uninitialized */
10850 @i{The make output is by default very verbose. This causes warnings
10851 from the compiler to be somewhat hidden, and not immediate to spot.}
10852 % @kbd{make CFLAGS=-Wall}
10853 gcc -DPACKAGE_NAME=\"foo\" -DPACKAGE_TARNAME=\"foo\" ...
10854 -DPACKAGE_STRING=\"foo\ 1.0\" -DPACKAGE_BUGREPORT=\"\" ...
10855 -DPACKAGE=\"foo\" -DVERSION=\"1.0\" -I. -Wall -MT main.o
10856 -MD -MP -MF .deps/main.Tpo -c -o main.o main.c
10857 main.c: In function ‘main’:
10858 main.c:3:3: warning: implicit declaration of function ‘func’
10859 mv -f .deps/main.Tpo .deps/main.Po
10860 gcc -DPACKAGE_NAME=\"foo\" -DPACKAGE_TARNAME=\"foo\" ...
10861 -DPACKAGE_STRING=\"foo\ 1.0\" -DPACKAGE_BUGREPORT=\"\" ...
10862 -DPACKAGE=\"foo\" -DVERSION=\"1.0\" -I. -Wall -MT func.o
10863 -MD -MP -MF .deps/func.Tpo -c -o func.o func.c
10864 func.c: In function ‘func’:
10865 func.c:4:3: warning: ‘i’ used uninitialized in this function
10866 mv -f .deps/func.Tpo .deps/func.Po
10867 gcc -Wall -o foo main.o func.o
10869 @i{Clean up, so that we we can rebuild everything from scratch.}
10871 test -z "foo" || rm -f foo
10874 @i{Silent rules enabled: the output is minimal but informative. In
10875 particular, the warnings from the compiler stick out very clearly.}
10876 % @kbd{make V=0 CFLAGS=-Wall}
10878 main.c: In function ‘main’:
10879 main.c:3:3: warning: implicit declaration of function ‘func’
10881 func.c: In function ‘func’:
10882 func.c:4:3: warning: ‘i’ used uninitialized in this function
10886 @cindex silent rules and libtool
10887 Also, in projects using @command{libtool}, the use of silent rules can
10888 automatically enable the @command{libtool}'s @option{--silent} option:
10891 % @kbd{cat Makefile.am}
10892 lib_LTLIBRARIES = libx.la
10894 % @kbd{make # Both make and libtool are verbose by default.}
10896 libtool: compile: gcc -DPACKAGE_NAME=\"foo\" ... -DLT_OBJDIR=\".libs/\"
10897 -I. -g -O2 -MT libx.lo -MD -MP -MF .deps/libx.Tpo -c libx.c -fPIC
10898 -DPIC -o .libs/libx.o
10899 mv -f .deps/libx.Tpo .deps/libx.Plo
10900 /bin/sh ./libtool --tag=CC --mode=link gcc -g -O2 -o libx.la -rpath
10901 /usr/local/lib libx.lo
10902 libtool: link: gcc -shared .libs/libx.o -Wl,-soname -Wl,libx.so.0
10903 -o .libs/libx.so.0.0.0
10904 libtool: link: cd .libs && rm -f libx.so && ln -s libx.so.0.0.0 libx.so
10912 For Automake-generated @file{Makefile}s, the user may influence the
10913 verbosity at @command{configure} run time as well as at @command{make}
10918 @opindex --enable-silent-rules
10919 @opindex --disable-silent-rules
10920 Passing @option{--enable-silent-rules} to @command{configure} will cause
10921 build rules to be less verbose; the option @option{--disable-silent-rules}
10922 will cause normal verbose output.
10925 At @command{make} run time, the default chosen at @command{configure}
10926 time may be overridden: @code{make V=1} will produce verbose output,
10927 @code{make V=0} less verbose output.
10930 @cindex default verbosity for silent rules
10931 Note that silent rules are @emph{disabled} by default; the user must
10932 enable them explicitly at either @command{configure} run time or at
10933 @command{make} run time. We think that this is a good policy, since
10934 it provides the casual user with enough information to prepare a good
10935 bug report in case anything breaks.
10937 Still, notwithstanding the rationales above, a developer who really
10938 wants to make silent rules enabled by default in his own package can
10939 do so by calling @code{AM_SILENT_RULES([yes])} in @file{configure.ac}.
10941 @c Keep in sync with silent-configsite.sh
10942 Users who prefer to have silent rules enabled by default can edit their
10943 @file{config.site} file to make the variable @code{enable_silent_rules}
10944 default to @samp{yes}. This should still allow disabling silent rules
10945 at @command{configure} time and at @command{make} time.
10947 @c FIXME: there's really a need to specify this explicitly?
10948 For portability to different @command{make} implementations, package authors
10949 are advised to not set the variable @code{V} inside the @file{Makefile.am}
10950 file, to allow the user to override the value for subdirectories as well.
10952 To work at its best, the current implementation of this feature normally
10953 uses nested variable expansion @samp{$(@var{var1}$(V))}, a @file{Makefile}
10954 feature that is not required by POSIX 2008 but is widely supported in
10955 practice. On the rare @command{make} implementations that do not support
10956 nested variable expansion, whether rules are silent is always determined at
10957 configure time, and cannot be overridden at make time. Future versions of
10958 POSIX are likely to require nested variable expansion, so this minor
10959 limitation should go away with time.
10961 @vindex @code{AM_V_GEN}
10962 @vindex @code{AM_V_at}
10963 @vindex @code{AM_DEFAULT_VERBOSITY}
10964 @vindex @code{AM_V}
10965 @vindex @code{AM_DEFAULT_V}
10966 To extend the silent mode to your own rules, you have few choices:
10971 You can use the predefined variable @code{AM_V_GEN} as a prefix to
10972 commands that should output a status line in silent mode, and
10973 @code{AM_V_at} as a prefix to commands that should not output anything
10974 in silent mode. When output is to be verbose, both of these variables
10975 will expand to the empty string.
10978 You can silence a recipe unconditionally with @code{@@}, and then use
10979 the predefined variable @code{AM_V_P} to know whether make is being run
10980 in silent or verbose mode, adjust the verbose information your recipe
10981 displays accordingly:
10986 ... [commands defining a shell variable '$headers'] ...; \
10987 if $(AM_V_P); then set -x; else echo " GEN [headers]"; fi; \
10988 rm -f $$headers && generate-header --flags $$headers
10992 You can add your own variables, so strings of your own choice are shown.
10993 The following snippet shows how you would define your own equivalent of
10997 pkg_verbose = $(pkg_verbose_@@AM_V@@)
10998 pkg_verbose_ = $(pkg_verbose_@@AM_DEFAULT_V@@)
10999 pkg_verbose_0 = @@echo PKG-GEN $@@;
11002 $(pkg_verbose)cp $(srcdir)/foo.in $@@
11007 As a final note, observe that, even when silent rules are enabled,
11008 the @option{--no-print-directory} option is still required with GNU
11009 @command{make} if the ``@i{Entering/Leaving directory ...}'' messages
11010 are to be disabled.
11013 @chapter The effect of @option{--gnu} and @option{--gnits}
11015 @cindex @option{--gnu}, required files
11016 @cindex @option{--gnu}, complete description
11018 The @option{--gnu} option (or @option{gnu} in the
11019 @code{AUTOMAKE_OPTIONS} variable) causes @command{automake} to check
11024 The files @file{INSTALL}, @file{NEWS}, @file{README}, @file{AUTHORS},
11025 and @file{ChangeLog}, plus one of @file{COPYING.LIB}, @file{COPYING.LESSER}
11026 or @file{COPYING}, are required at the topmost directory of the package.
11028 If the @option{--add-missing} option is given, @command{automake} will
11029 add a generic version of the @file{INSTALL} file as well as the
11030 @file{COPYING} file containing the text of the current version of the
11031 GNU General Public License existing at the time of this Automake release
11032 (version 3 as this is written, @uref{http://www.gnu.org/@/copyleft/@/gpl.html}).
11033 However, an existing @file{COPYING} file will never be overwritten by
11034 @command{automake}.
11037 The options @option{no-installman} and @option{no-installinfo} are
11041 Note that this option will be extended in the future to do even more
11042 checking; it is advisable to be familiar with the precise requirements
11043 of the GNU standards. Also, @option{--gnu} can require certain
11044 non-standard GNU programs to exist for use by various maintainer-only
11045 rules; for instance, in the future @command{pathchk} might be required for
11048 @cindex @option{--gnits}, complete description
11050 The @option{--gnits} option does everything that @option{--gnu} does, and
11051 checks the following as well:
11055 @samp{make installcheck} will check to make sure that the @option{--help}
11056 and @option{--version} really print a usage message and a version string,
11057 respectively. This is the @option{std-options} option (@pxref{Options}).
11060 @samp{make dist} will check to make sure the @file{NEWS} file has been
11061 updated to the current version.
11064 @code{VERSION} is checked to make sure its format complies with Gnits
11066 @c FIXME xref when standards are finished
11069 @cindex @file{README-alpha}
11070 If @code{VERSION} indicates that this is an alpha release, and the file
11071 @file{README-alpha} appears in the topmost directory of a package, then
11072 it is included in the distribution. This is done in @option{--gnits}
11073 mode, and no other, because this mode is the only one where version
11074 number formats are constrained, and hence the only mode where Automake
11075 can automatically determine whether @file{README-alpha} should be
11079 The file @file{THANKS} is required.
11084 @chapter When Automake Isn't Enough
11086 In some situations, where Automake is not up to one task, one has to
11087 resort to handwritten rules or even handwritten @file{Makefile}s.
11090 * Extending:: Adding new rules or overriding existing ones.
11091 * Third-Party Makefiles:: Integrating Non-Automake @file{Makefile}s.
11095 @section Extending Automake Rules
11097 With some minor exceptions (for example @code{_PROGRAMS} variables,
11098 @code{TESTS}, or @code{XFAIL_TESTS}) being rewritten to append
11099 @samp{$(EXEEXT)}), the contents of a @file{Makefile.am} is copied to
11100 @file{Makefile.in} verbatim.
11102 @cindex copying semantics
11104 These copying semantics mean that many problems can be worked around
11105 by simply adding some @command{make} variables and rules to
11106 @file{Makefile.am}. Automake will ignore these additions.
11108 @cindex conflicting definitions
11109 @cindex rules, conflicting
11110 @cindex variables, conflicting
11111 @cindex definitions, conflicts
11113 Since a @file{Makefile.in} is built from data gathered from three
11114 different places (@file{Makefile.am}, @file{configure.ac}, and
11115 @command{automake} itself), it is possible to have conflicting
11116 definitions of rules or variables. When building @file{Makefile.in}
11117 the following priorities are respected by @command{automake} to ensure
11118 the user always has the last word:
11122 User defined variables in @file{Makefile.am} have priority over
11123 variables @code{AC_SUBST}ed from @file{configure.ac}, and
11124 @code{AC_SUBST}ed variables have priority over
11125 @command{automake}-defined variables.
11127 As far as rules are concerned, a user-defined rule overrides any
11128 @command{automake}-defined rule for the same target.
11131 @cindex overriding rules
11132 @cindex overriding semantics
11133 @cindex rules, overriding
11135 These overriding semantics make it possible to fine tune some default
11136 settings of Automake, or replace some of its rules. Overriding
11137 Automake rules is often inadvisable, particularly in the topmost
11138 directory of a package with subdirectories. The @option{-Woverride}
11139 option (@pxref{automake Invocation}) comes in handy to catch overridden
11142 Note that Automake does not make any distinction between rules with
11143 commands and rules that only specify dependencies. So it is not
11144 possible to append new dependencies to an @command{automake}-defined
11145 target without redefining the entire rule.
11147 @cindex @option{-local} targets
11148 @cindex local targets
11150 However, various useful targets have a @samp{-local} version you can
11151 specify in your @file{Makefile.am}. Automake will supplement the
11152 standard target with these user-supplied targets.
11157 @trindex info-local
11165 @trindex html-local
11167 @trindex check-local
11169 @trindex install-data
11170 @trindex install-data-local
11171 @trindex install-dvi
11172 @trindex install-dvi-local
11173 @trindex install-exec
11174 @trindex install-exec-local
11175 @trindex install-html
11176 @trindex install-html-local
11177 @trindex install-info
11178 @trindex install-info-local
11179 @trindex install-pdf
11180 @trindex install-pdf-local
11181 @trindex install-ps
11182 @trindex install-ps-local
11184 @trindex uninstall-local
11185 @trindex mostlyclean
11186 @trindex mostlyclean-local
11188 @trindex clean-local
11190 @trindex distclean-local
11191 @trindex installdirs
11192 @trindex installdirs-local
11193 @trindex installcheck
11194 @trindex installcheck-local
11196 The targets that support a local version are @code{all}, @code{info},
11197 @code{dvi}, @code{ps}, @code{pdf}, @code{html}, @code{check},
11198 @code{install-data}, @code{install-dvi}, @code{install-exec},
11199 @code{install-html}, @code{install-info}, @code{install-pdf},
11200 @code{install-ps}, @code{uninstall}, @code{installdirs},
11201 @code{installcheck} and the various @code{clean} targets
11202 (@code{mostlyclean}, @code{clean}, @code{distclean}, and
11203 @code{maintainer-clean}).
11205 Note that there are no @code{uninstall-exec-local} or
11206 @code{uninstall-data-local} targets; just use @code{uninstall-local}.
11207 It doesn't make sense to uninstall just data or just executables.
11209 For instance, here is one way to erase a subdirectory during
11210 @samp{make clean} (@pxref{Clean}).
11217 You may be tempted to use @code{install-data-local} to install a file
11218 to some hard-coded location, but you should avoid this
11219 (@pxref{Hard-Coded Install Paths}).
11221 With the @code{-local} targets, there is no particular guarantee of
11222 execution order; typically, they are run early, but with parallel
11223 make, there is no way to be sure of that.
11225 @cindex @option{-hook} targets
11226 @cindex hook targets
11227 @trindex install-data-hook
11228 @trindex install-exec-hook
11229 @trindex uninstall-hook
11232 In contrast, some rules also have a way to run another rule, called a
11233 @dfn{hook}; hooks are always executed after the main rule's work is done.
11234 The hook is named after the principal target, with @samp{-hook} appended.
11235 The targets allowing hooks are @code{install-data},
11236 @code{install-exec}, @code{uninstall}, @code{dist}, and
11239 For instance, here is how to create a hard link to an installed program:
11243 ln $(DESTDIR)$(bindir)/program$(EXEEXT) \
11244 $(DESTDIR)$(bindir)/proglink$(EXEEXT)
11247 Although cheaper and more portable than symbolic links, hard links
11248 will not work everywhere (for instance, OS/2 does not have
11249 @command{ln}). Ideally you should fall back to @samp{cp -p} when
11250 @command{ln} does not work. An easy way, if symbolic links are
11251 acceptable to you, is to add @code{AC_PROG_LN_S} to
11252 @file{configure.ac} (@pxref{Particular Programs, , Particular Program
11253 Checks, autoconf, The Autoconf Manual}) and use @samp{$(LN_S)} in
11254 @file{Makefile.am}.
11256 @cindex versioned binaries, installing
11257 @cindex installing versioned binaries
11258 @cindex @code{LN_S} example
11259 For instance, here is how you could install a versioned copy of a
11260 program using @samp{$(LN_S)}:
11262 @c Keep in sync with insthook.sh
11265 cd $(DESTDIR)$(bindir) && \
11266 mv -f prog$(EXEEXT) prog-$(VERSION)$(EXEEXT) && \
11267 $(LN_S) prog-$(VERSION)$(EXEEXT) prog$(EXEEXT)
11270 Note that we rename the program so that a new version will erase the
11271 symbolic link, not the real binary. Also we @command{cd} into the
11272 destination directory in order to create relative links.
11274 When writing @code{install-exec-hook} or @code{install-data-hook},
11275 please bear in mind that the exec/data distinction is based on the
11276 installation directory, not on the primary used (@pxref{The Two Parts of
11278 @c Keep in sync with primary-prefix-couples-documented-valid.sh
11279 So a @code{foo_SCRIPTS} will be installed by
11280 @code{install-data}, and a @code{barexec_SCRIPTS} will be installed by
11281 @code{install-exec}. You should define your hooks consequently.
11283 @c FIXME should include discussion of variables you can use in these
11286 @node Third-Party Makefiles
11287 @section Third-Party @file{Makefile}s
11289 @cindex Third-party packages, interfacing with
11290 @cindex Interfacing with third-party packages
11292 In most projects all @file{Makefile}s are generated by Automake. In
11293 some cases, however, projects need to embed subdirectories with
11294 handwritten @file{Makefile}s. For instance, one subdirectory could be
11295 a third-party project with its own build system, not using Automake.
11297 It is possible to list arbitrary directories in @code{SUBDIRS} or
11298 @code{DIST_SUBDIRS} provided each of these directories has a
11299 @file{Makefile} that recognizes all the following recursive targets.
11301 @cindex recursive targets and third-party @file{Makefile}s
11302 When a user runs one of these targets, that target is run recursively
11303 in all subdirectories. This is why it is important that even
11304 third-party @file{Makefile}s support them.
11308 Compile the entire package. This is the default target in
11309 Automake-generated @file{Makefile}s, but it does not need to be the
11310 default in third-party @file{Makefile}s.
11315 @vindex top_distdir
11316 Copy files to distribute into @samp{$(distdir)}, before a tarball is
11317 constructed. Of course this target is not required if the
11318 @option{no-dist} option (@pxref{Options}) is used.
11320 The variables @samp{$(top_distdir)} and @samp{$(distdir)}
11321 (@pxref{The dist Hook}) will be passed from the outer package to the subpackage
11322 when the @code{distdir} target is invoked. These two variables have
11323 been adjusted for the directory that is being recursed into, so they
11327 @itemx install-data
11328 @itemx install-exec
11330 Install or uninstall files (@pxref{Install}).
11333 @itemx install-html
11334 @itemx install-info
11337 Install only some specific documentation format (@pxref{Texinfo}).
11340 Create install directories, but do not install any files.
11343 @itemx installcheck
11344 Check the package (@pxref{Tests}).
11349 @itemx maintainer-clean
11350 Cleaning rules (@pxref{Clean}).
11357 Build the documentation in various formats (@pxref{Texinfo}).
11361 Build @file{TAGS} and @file{CTAGS} (@pxref{Tags}).
11364 If you have ever used Gettext in a project, this is a good example of
11365 how third-party @file{Makefile}s can be used with Automake. The
11366 @file{Makefile}s @command{gettextize} puts in the @file{po/} and
11367 @file{intl/} directories are handwritten @file{Makefile}s that
11368 implement all of these targets. That way they can be added to
11369 @code{SUBDIRS} in Automake packages.
11371 Directories that are only listed in @code{DIST_SUBDIRS} but not in
11372 @code{SUBDIRS} need only the @code{distclean},
11373 @code{maintainer-clean}, and @code{distdir} rules (@pxref{Conditional
11376 Usually, many of these rules are irrelevant to the third-party
11377 subproject, but they are required for the whole package to work. It's
11378 OK to have a rule that does nothing, so if you are integrating a
11379 third-party project with no documentation or tag support, you could
11380 simply augment its @file{Makefile} as follows:
11383 EMPTY_AUTOMAKE_TARGETS = dvi pdf ps info html tags ctags
11384 .PHONY: $(EMPTY_AUTOMAKE_TARGETS)
11385 $(EMPTY_AUTOMAKE_TARGETS):
11388 Another aspect of integrating third-party build systems is whether
11389 they support VPATH builds (@pxref{VPATH Builds}). Obviously if the
11390 subpackage does not support VPATH builds the whole package will not
11391 support VPATH builds. This in turns means that @samp{make distcheck}
11392 will not work, because it relies on VPATH builds. Some people can
11393 live without this (actually, many Automake users have never heard of
11394 @samp{make distcheck}). Other people may prefer to revamp the
11395 existing @file{Makefile}s to support VPATH@. Doing so does not
11396 necessarily require Automake, only Autoconf is needed (@pxref{Build
11397 Directories, , Build Directories, autoconf, The Autoconf Manual}).
11398 The necessary substitutions: @samp{@@srcdir@@}, @samp{@@top_srcdir@@},
11399 and @samp{@@top_builddir@@} are defined by @file{configure} when it
11400 processes a @file{Makefile} (@pxref{Preset Output Variables, , Preset
11401 Output Variables, autoconf, The Autoconf Manual}), they are not
11402 computed by the Makefile like the aforementioned @samp{$(distdir)} and
11403 @samp{$(top_distdir)} variables.
11405 It is sometimes inconvenient to modify a third-party @file{Makefile}
11406 to introduce the above required targets. For instance, one may want to
11407 keep the third-party sources untouched to ease upgrades to new
11410 @cindex @file{GNUmakefile} including @file{Makefile}
11411 Here are two other ideas. If GNU make is assumed, one possibility is
11412 to add to that subdirectory a @file{GNUmakefile} that defines the
11413 required targets and includes the third-party @file{Makefile}. For
11414 this to work in VPATH builds, @file{GNUmakefile} must lie in the build
11415 directory; the easiest way to do this is to write a
11416 @file{GNUmakefile.in} instead, and have it processed with
11417 @code{AC_CONFIG_FILES} from the outer package. For example if we
11418 assume @file{Makefile} defines all targets except the documentation
11419 targets, and that the @code{check} target is actually called
11420 @code{test}, we could write @file{GNUmakefile} (or
11421 @file{GNUmakefile.in}) like this:
11424 # First, include the real Makefile
11426 # Then, define the other targets needed by Automake Makefiles.
11427 .PHONY: dvi pdf ps info html check
11428 dvi pdf ps info html:
11432 @cindex Proxy @file{Makefile} for third-party packages
11433 A similar idea that does not use @code{include} is to write a proxy
11434 @file{Makefile} that dispatches rules to the real @file{Makefile},
11435 either with @samp{$(MAKE) -f Makefile.real $(AM_MAKEFLAGS) target} (if
11436 it's OK to rename the original @file{Makefile}) or with @samp{cd
11437 subdir && $(MAKE) $(AM_MAKEFLAGS) target} (if it's OK to store the
11438 subdirectory project one directory deeper). The good news is that
11439 this proxy @file{Makefile} can be generated with Automake. All we
11440 need are @option{-local} targets (@pxref{Extending}) that perform the
11441 dispatch. Of course the other Automake features are available, so you
11442 could decide to let Automake perform distribution or installation.
11443 Here is a possible @file{Makefile.am}:
11447 cd subdir && $(MAKE) $(AM_MAKEFLAGS) all
11449 cd subdir && $(MAKE) $(AM_MAKEFLAGS) test
11451 cd subdir && $(MAKE) $(AM_MAKEFLAGS) clean
11453 # Assuming the package knows how to install itself
11454 install-data-local:
11455 cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-data
11456 install-exec-local:
11457 cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-exec
11459 cd subdir && $(MAKE) $(AM_MAKEFLAGS) uninstall
11461 # Distribute files from here.
11462 EXTRA_DIST = subdir/Makefile subdir/program.c ...
11465 Pushing this idea to the extreme, it is also possible to ignore the
11466 subproject build system and build everything from this proxy
11467 @file{Makefile.am}. This might sound very sensible if you need VPATH
11468 builds but the subproject does not support them.
11471 @chapter Distributing @file{Makefile.in}s
11473 Automake places no restrictions on the distribution of the resulting
11474 @file{Makefile.in}s. We still encourage software authors to
11475 distribute their work under terms like those of the GPL, but doing so
11476 is not required to use Automake.
11478 Some of the files that can be automatically installed via the
11479 @option{--add-missing} switch do fall under the GPL@. However, these also
11480 have a special exception allowing you to distribute them with your
11481 package, regardless of the licensing you choose.
11484 @node API Versioning
11485 @chapter Automake API Versioning
11487 New Automake releases usually include bug fixes and new features.
11488 Unfortunately they may also introduce new bugs and incompatibilities.
11489 This makes four reasons why a package may require a particular Automake
11492 Things get worse when maintaining a large tree of packages, each one
11493 requiring a different version of Automake. In the past, this meant that
11494 any developer (and sometimes users) had to install several versions of
11495 Automake in different places, and switch @samp{$PATH} appropriately for
11498 Starting with version 1.6, Automake installs versioned binaries. This
11499 means you can install several versions of Automake in the same
11500 @samp{$prefix}, and can select an arbitrary Automake version by running
11501 @command{automake-1.6} or @command{automake-1.7} without juggling with
11502 @samp{$PATH}. Furthermore, @file{Makefile}'s generated by Automake 1.6
11503 will use @command{automake-1.6} explicitly in their rebuild rules.
11505 The number @samp{1.6} in @command{automake-1.6} is Automake's API version,
11506 not Automake's version. If a bug fix release is made, for instance
11507 Automake 1.6.1, the API version will remain 1.6. This means that a
11508 package that works with Automake 1.6 should also work with 1.6.1; after
11509 all, this is what people expect from bug fix releases.
11511 If your package relies on a feature or a bug fix introduced in
11512 a release, you can pass this version as an option to Automake to ensure
11513 older releases will not be used. For instance, use this in your
11514 @file{configure.ac}:
11517 AM_INIT_AUTOMAKE([1.6.1]) dnl Require Automake 1.6.1 or better.
11521 or, in a particular @file{Makefile.am}:
11524 AUTOMAKE_OPTIONS = 1.6.1 # Require Automake 1.6.1 or better.
11528 Automake will print an error message if its version is
11529 older than the requested version.
11532 @heading What is in the API
11534 Automake's programming interface is not easy to define. Basically it
11535 should include at least all @strong{documented} variables and targets
11536 that a @file{Makefile.am} author can use, any behavior associated with
11537 them (e.g., the places where @samp{-hook}'s are run), the command line
11538 interface of @command{automake} and @command{aclocal}, @dots{}
11540 @heading What is not in the API
11542 Every undocumented variable, target, or command line option, is not part
11543 of the API@. You should avoid using them, as they could change from one
11544 version to the other (even in bug fix releases, if this helps to fix a
11547 If it turns out you need to use such an undocumented feature, contact
11548 @email{automake@@gnu.org} and try to get it documented and exercised by
11552 @chapter Upgrading a Package to a Newer Automake Version
11554 Automake maintains three kind of files in a package.
11557 @item @file{aclocal.m4}
11558 @item @file{Makefile.in}s
11559 @item auxiliary tools like @file{install-sh} or @file{py-compile}
11562 @file{aclocal.m4} is generated by @command{aclocal} and contains some
11563 Automake-supplied M4 macros. Auxiliary tools are installed by
11564 @samp{automake --add-missing} when needed. @file{Makefile.in}s are
11565 built from @file{Makefile.am} by @command{automake}, and rely on the
11566 definitions of the M4 macros put in @file{aclocal.m4} as well as the
11567 behavior of the auxiliary tools installed.
11569 Because all of these files are closely related, it is important to
11570 regenerate all of them when upgrading to a newer Automake release.
11571 The usual way to do that is
11574 aclocal # with any option needed (such a -I m4)
11576 automake --add-missing --force-missing
11580 or more conveniently:
11586 The use of @option{--force-missing} ensures that auxiliary tools will be
11587 overridden by new versions (@pxref{automake Invocation}).
11589 It is important to regenerate all of these files each time Automake is
11590 upgraded, even between bug fixes releases. For instance, it is not
11591 unusual for a bug fix to involve changes to both the rules generated
11592 in @file{Makefile.in} and the supporting M4 macros copied to
11595 Presently @command{automake} is able to diagnose situations where
11596 @file{aclocal.m4} has been generated with another version of
11597 @command{aclocal}. However it never checks whether auxiliary scripts
11598 are up-to-date. In other words, @command{automake} will tell you when
11599 @command{aclocal} needs to be rerun, but it will never diagnose a
11600 missing @option{--force-missing}.
11602 Before upgrading to a new major release, it is a good idea to read the
11603 file @file{NEWS}. This file lists all changes between releases: new
11604 features, obsolete constructs, known incompatibilities, and
11608 @chapter Frequently Asked Questions about Automake
11610 This chapter covers some questions that often come up on the mailing
11614 * CVS:: CVS and generated files
11615 * maintainer-mode:: missing and AM_MAINTAINER_MODE
11616 * Wildcards:: Why doesn't Automake support wildcards?
11617 * Limitations on File Names:: Limitations on source and installed file names
11618 * Errors with distclean:: Files left in build directory after distclean
11619 * Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS
11620 * Renamed Objects:: Why are object files sometimes renamed?
11621 * Per-Object Flags:: How to simulate per-object flags?
11622 * Multiple Outputs:: Writing rules for tools with many output files
11623 * Hard-Coded Install Paths:: Installing to hard-coded locations
11624 * Debugging Make Rules:: Strategies when things don't work as expected
11625 * Reporting Bugs:: Feedback on bugs and feature requests
11629 @section CVS and generated files
11631 @subheading Background: distributed generated Files
11632 @cindex generated files, distributed
11633 @cindex rebuild rules
11635 Packages made with Autoconf and Automake ship with some generated
11636 files like @file{configure} or @file{Makefile.in}. These files were
11637 generated on the developer's machine and are distributed so that
11638 end-users do not have to install the maintainer tools required to
11639 rebuild them. Other generated files like Lex scanners, Yacc parsers,
11640 or Info documentation, are usually distributed on similar grounds.
11642 Automake output rules in @file{Makefile}s to rebuild these files. For
11643 instance, @command{make} will run @command{autoconf} to rebuild
11644 @file{configure} whenever @file{configure.ac} is changed. This makes
11645 development safer by ensuring a @file{configure} is never out-of-date
11646 with respect to @file{configure.ac}.
11648 As generated files shipped in packages are up-to-date, and because
11649 @command{tar} preserves times-tamps, these rebuild rules are not
11650 triggered when a user unpacks and builds a package.
11652 @subheading Background: CVS and Timestamps
11653 @cindex timestamps and CVS
11654 @cindex CVS and timestamps
11656 Unless you use CVS keywords (in which case files must be updated at
11657 commit time), CVS preserves timestamp during @samp{cvs commit} and
11658 @samp{cvs import -d} operations.
11660 When you check out a file using @samp{cvs checkout} its timestamp is
11661 set to that of the revision that is being checked out.
11663 However, during @command{cvs update}, files will have the date of the
11664 update, not the original timestamp of this revision. This is meant to
11665 make sure that @command{make} notices sources files have been updated.
11667 This timestamp shift is troublesome when both sources and generated
11668 files are kept under CVS@. Because CVS processes files in lexical
11669 order, @file{configure.ac} will appear newer than @file{configure}
11670 after a @command{cvs update} that updates both files, even if
11671 @file{configure} was newer than @file{configure.ac} when it was
11672 checked in. Calling @command{make} will then trigger a spurious rebuild
11673 of @file{configure}.
11675 @subheading Living with CVS in Autoconfiscated Projects
11676 @cindex CVS and generated files
11677 @cindex generated files and CVS
11679 There are basically two clans amongst maintainers: those who keep all
11680 distributed files under CVS, including generated files, and those who
11681 keep generated files @emph{out} of CVS.
11683 @subsubheading All Files in CVS
11687 The CVS repository contains all distributed files so you know exactly
11688 what is distributed, and you can checkout any prior version entirely.
11691 Maintainers can see how generated files evolve (for instance, you can
11692 see what happens to your @file{Makefile.in}s when you upgrade Automake
11693 and make sure they look OK).
11696 Users do not need the autotools to build a checkout of the project, it
11697 works just like a released tarball.
11700 If users use @command{cvs update} to update their copy, instead of
11701 @command{cvs checkout} to fetch a fresh one, timestamps will be
11702 inaccurate. Some rebuild rules will be triggered and attempt to
11703 run developer tools such as @command{autoconf} or @command{automake}.
11705 Calls to such tools are all wrapped into a call to the @command{missing}
11706 script discussed later (@pxref{maintainer-mode}), so that the user will
11707 see more descriptive warnings about missing or out-of-date tools, and
11708 possible suggestions about how to obtain them, rather than just some
11709 ``command not found'' error, or (worse) some obscure message from some
11710 older version of the required tool they happen to have installed.
11712 Maintainers interested in keeping their package buildable from a CVS
11713 checkout even for those users that lack maintainer-specific tools might
11714 want to provide an helper script (or to enhance their existing bootstrap
11715 script) to fix the timestamps after a
11716 @command{cvs update} or a @command{git checkout}, to prevent spurious
11717 rebuilds. In case of a project committing the Autotools-generated
11718 files, as well as the generated @file{.info} files, such script might
11719 look something like this:
11723 # fix-timestamp.sh: prevents useless rebuilds after "cvs update"
11725 # aclocal-generated aclocal.m4 depends on locally-installed
11726 # '.m4' macro files, as well as on 'configure.ac'
11729 # autoconf-generated configure depends on aclocal.m4 and on
11731 configure config.h.in
11732 # so does autoheader-generated config.h.in
11733 configure config.h.in
11734 # and all the automake-generated Makefile.in files
11735 touch `find . -name Makefile.in -print`
11736 # finally, the makeinfo-generated '.info' files depend on the
11737 # corresponding '.texi' files
11742 In distributed development, developers are likely to have different
11743 version of the maintainer tools installed. In this case rebuilds
11744 triggered by timestamp lossage will lead to spurious changes
11745 to generated files. There are several solutions to this:
11749 All developers should use the same versions, so that the rebuilt files
11750 are identical to files in CVS@. (This starts to be difficult when each
11751 project you work on uses different versions.)
11753 Or people use a script to fix the timestamp after a checkout (the GCC
11754 folks have such a script).
11756 Or @file{configure.ac} uses @code{AM_MAINTAINER_MODE}, which will
11757 disable all of these rebuild rules by default. This is further discussed
11758 in @ref{maintainer-mode}.
11762 Although we focused on spurious rebuilds, the converse can also
11763 happen. CVS's timestamp handling can also let you think an
11764 out-of-date file is up-to-date.
11766 For instance, suppose a developer has modified @file{Makefile.am} and
11767 has rebuilt @file{Makefile.in}, and then decides to do a last-minute
11768 change to @file{Makefile.am} right before checking in both files
11769 (without rebuilding @file{Makefile.in} to account for the change).
11771 This last change to @file{Makefile.am} makes the copy of
11772 @file{Makefile.in} out-of-date. Since CVS processes files
11773 alphabetically, when another developer @samp{cvs update}s his or her
11774 tree, @file{Makefile.in} will happen to be newer than
11775 @file{Makefile.am}. This other developer will not see that
11776 @file{Makefile.in} is out-of-date.
11780 @subsubheading Generated Files out of CVS
11782 One way to get CVS and @command{make} working peacefully is to never
11783 store generated files in CVS, i.e., do not CVS-control files that
11784 are @file{Makefile} targets (also called @emph{derived} files).
11786 This way developers are not annoyed by changes to generated files. It
11787 does not matter if they all have different versions (assuming they are
11788 compatible, of course). And finally, timestamps are not lost, changes
11789 to sources files can't be missed as in the
11790 @file{Makefile.am}/@file{Makefile.in} example discussed earlier.
11792 The drawback is that the CVS repository is not an exact copy of what
11793 is distributed and that users now need to install various development
11794 tools (maybe even specific versions) before they can build a checkout.
11795 But, after all, CVS's job is versioning, not distribution.
11797 Allowing developers to use different versions of their tools can also
11798 hide bugs during distributed development. Indeed, developers will be
11799 using (hence testing) their own generated files, instead of the
11800 generated files that will be released actually. The developer who
11801 prepares the tarball might be using a version of the tool that
11802 produces bogus output (for instance a non-portable C file), something
11803 other developers could have noticed if they weren't using their own
11804 versions of this tool.
11806 @subheading Third-party Files
11807 @cindex CVS and third-party files
11808 @cindex third-party files and CVS
11810 Another class of files not discussed here (because they do not cause
11811 timestamp issues) are files that are shipped with a package, but
11812 maintained elsewhere. For instance, tools like @command{gettextize}
11813 and @command{autopoint} (from Gettext) or @command{libtoolize} (from
11814 Libtool), will install or update files in your package.
11816 These files, whether they are kept under CVS or not, raise similar
11817 concerns about version mismatch between developers' tools. The
11818 Gettext manual has a section about this, see @ref{CVS Issues, CVS
11819 Issues, Integrating with CVS, gettext, GNU gettext tools}.
11821 @node maintainer-mode
11822 @section @command{missing} and @code{AM_MAINTAINER_MODE}
11824 @subheading @command{missing}
11825 @cindex @command{missing}, purpose
11827 The @command{missing} script is a wrapper around several maintainer
11828 tools, designed to warn users if a maintainer tool is required but
11829 missing. Typical maintainer tools are @command{autoconf},
11830 @command{automake}, @command{bison}, etc. Because file generated by
11831 these tools are shipped with the other sources of a package, these
11832 tools shouldn't be required during a user build and they are not
11833 checked for in @file{configure}.
11835 However, if for some reason a rebuild rule is triggered and involves a
11836 missing tool, @command{missing} will notice it and warn the user, even
11837 suggesting how to obtain such a tool (at least in case it is a well-known
11838 one, like @command{makeinfo} or @command{bison}). This is more helpful
11839 and user-friendly than just having the rebuild rules spewing out a terse
11840 error message like @samp{sh: @var{tool}: command not found}. Similarly,
11841 @command{missing} will warn the user if it detects that a maintainer
11842 tool it attempted to use seems too old (be warned that diagnosing this
11843 correctly is typically more difficult that detecting missing tools, and
11844 requires cooperation from the tool itself, so it won't always work).
11846 If the required tool is installed, @command{missing} will run it and
11847 won't attempt to continue after failures. This is correct during
11848 development: developers love fixing failures. However, users with
11849 missing or too old maintainer tools may get an error when the rebuild
11850 rule is spuriously triggered, halting the build. This failure to let
11851 the build continue is one of the arguments of the
11852 @code{AM_MAINTAINER_MODE} advocates.
11854 @subheading @code{AM_MAINTAINER_MODE}
11855 @cindex @code{AM_MAINTAINER_MODE}, purpose
11856 @acindex AM_MAINTAINER_MODE
11858 @code{AM_MAINTAINER_MODE} allows you to choose whether the so called
11859 "rebuild rules" should be enabled or disabled. With
11860 @code{AM_MAINTAINER_MODE([enable])}, they are enabled by default,
11861 otherwise they are disabled by default. In the latter case, if
11862 you have @code{AM_MAINTAINER_MODE} in @file{configure.ac}, and run
11863 @samp{./configure && make}, then @command{make} will *never* attempt to
11864 rebuild @file{configure}, @file{Makefile.in}s, Lex or Yacc outputs, etc.
11865 I.e., this disables build rules for files that are usually distributed
11866 and that users should normally not have to update.
11868 The user can override the default setting by passing either
11869 @samp{--enable-maintainer-mode} or @samp{--disable-maintainer-mode}
11870 to @command{configure}.
11872 People use @code{AM_MAINTAINER_MODE} either because they do not want their
11873 users (or themselves) annoyed by timestamps lossage (@pxref{CVS}), or
11874 because they simply can't stand the rebuild rules and prefer running
11875 maintainer tools explicitly.
11877 @code{AM_MAINTAINER_MODE} also allows you to disable some custom build
11878 rules conditionally. Some developers use this feature to disable
11879 rules that need exotic tools that users may not have available.
11881 Several years ago Fran@,{c}ois Pinard pointed out several arguments
11882 against this @code{AM_MAINTAINER_MODE} macro. Most of them relate to
11883 insecurity. By removing dependencies you get non-dependable builds:
11884 changes to sources files can have no effect on generated files and this
11885 can be very confusing when unnoticed. He adds that security shouldn't
11886 be reserved to maintainers (what @option{--enable-maintainer-mode}
11887 suggests), on the contrary. If one user has to modify a
11888 @file{Makefile.am}, then either @file{Makefile.in} should be updated
11889 or a warning should be output (this is what Automake uses
11890 @command{missing} for) but the last thing you want is that nothing
11891 happens and the user doesn't notice it (this is what happens when
11892 rebuild rules are disabled by @code{AM_MAINTAINER_MODE}).
11894 Jim Meyering, the inventor of the @code{AM_MAINTAINER_MODE} macro was
11895 swayed by Fran@,{c}ois's arguments, and got rid of
11896 @code{AM_MAINTAINER_MODE} in all of his packages.
11898 Still many people continue to use @code{AM_MAINTAINER_MODE}, because
11899 it helps them working on projects where all files are kept under version
11900 control, and because @command{missing} isn't enough if you have the
11901 wrong version of the tools.
11905 @section Why doesn't Automake support wildcards?
11908 Developers are lazy. They would often like to use wildcards in
11909 @file{Makefile.am}s, so that they would not need to remember to
11910 update @file{Makefile.am}s every time they add, delete, or rename
11913 There are several objections to this:
11916 When using CVS (or similar) developers need to remember they have to
11917 run @samp{cvs add} or @samp{cvs rm} anyway. Updating
11918 @file{Makefile.am} accordingly quickly becomes a reflex.
11920 Conversely, if your application doesn't compile
11921 because you forgot to add a file in @file{Makefile.am}, it will help
11922 you remember to @samp{cvs add} it.
11925 Using wildcards makes it easy to distribute files by mistake. For
11926 instance, some code a developer is experimenting with (a test case,
11927 say) that should not be part of the distribution.
11930 Using wildcards it's easy to omit some files by mistake. For
11931 instance, one developer creates a new file, uses it in many places,
11932 but forgets to commit it. Another developer then checks out the
11933 incomplete project and is able to run @samp{make dist} successfully,
11934 even though a file is missing. By listing files, @samp{make dist}
11935 @emph{will} complain.
11938 Wildcards are not portable to some non-GNU @command{make} implementations,
11939 e.g., NetBSD @command{make} will not expand globs such as @samp{*} in
11940 prerequisites of a target.
11943 Finally, it's really hard to @emph{forget} to add a file to
11944 @file{Makefile.am}: files that are not listed in @file{Makefile.am} are
11945 not compiled or installed, so you can't even test them.
11948 Still, these are philosophical objections, and as such you may disagree,
11949 or find enough value in wildcards to dismiss all of them. Before you
11950 start writing a patch against Automake to teach it about wildcards,
11951 let's see the main technical issue: portability.
11953 Although @samp{$(wildcard ...)} works with GNU @command{make}, it is
11954 not portable to other @command{make} implementations.
11956 The only way Automake could support @command{$(wildcard ...)} is by
11957 expanding @command{$(wildcard ...)} when @command{automake} is run.
11958 The resulting @file{Makefile.in}s would be portable since they would
11959 list all files and not use @samp{$(wildcard ...)}. However that
11960 means developers would need to remember to run @command{automake} each
11961 time they add, delete, or rename files.
11963 Compared to editing @file{Makefile.am}, this is a very small gain. Sure,
11964 it's easier and faster to type @samp{automake; make} than to type
11965 @samp{emacs Makefile.am; make}. But nobody bothered enough to write a
11966 patch to add support for this syntax. Some people use scripts to
11967 generate file lists in @file{Makefile.am} or in separate
11968 @file{Makefile} fragments.
11970 Even if you don't care about portability, and are tempted to use
11971 @samp{$(wildcard ...)} anyway because you target only GNU Make, you
11972 should know there are many places where Automake needs to know exactly
11973 which files should be processed. As Automake doesn't know how to
11974 expand @samp{$(wildcard ...)}, you cannot use it in these places.
11975 @samp{$(wildcard ...)} is a black box comparable to @code{AC_SUBST}ed
11976 variables as far Automake is concerned.
11978 You can get warnings about @samp{$(wildcard ...}) constructs using the
11979 @option{-Wportability} flag.
11981 @node Limitations on File Names
11982 @section Limitations on File Names
11983 @cindex file names, limitations on
11985 Automake attempts to support all kinds of file names, even those that
11986 contain unusual characters or are unusually long. However, some
11987 limitations are imposed by the underlying operating system and tools.
11989 Most operating systems prohibit the use of the null byte in file
11990 names, and reserve @samp{/} as a directory separator. Also, they
11991 require that file names are properly encoded for the user's locale.
11992 Automake is subject to these limits.
11994 Portable packages should limit themselves to POSIX file
11995 names. These can contain ASCII letters and digits,
11996 @samp{_}, @samp{.}, and @samp{-}. File names consist of components
11997 separated by @samp{/}. File name components cannot begin with
12000 Portable POSIX file names cannot contain components that exceed a
12001 14-byte limit, but nowadays it's normally safe to assume the
12002 more-generous XOPEN limit of 255 bytes. POSIX
12003 limits file names to 255 bytes (XOPEN allows 1023 bytes),
12004 but you may want to limit a source tarball to file names of 99 bytes
12005 to avoid interoperability problems with old versions of @command{tar}.
12007 If you depart from these rules (e.g., by using non-ASCII
12008 characters in file names, or by using lengthy file names), your
12009 installers may have problems for reasons unrelated to Automake.
12010 However, if this does not concern you, you should know about the
12011 limitations imposed by Automake itself. These limitations are
12012 undesirable, but some of them seem to be inherent to underlying tools
12013 like Autoconf, Make, M4, and the shell. They fall into three
12014 categories: install directories, build directories, and file names.
12016 The following characters:
12019 @r{newline} " # $ ' `
12022 should not appear in the names of install directories. For example,
12023 the operand of @command{configure}'s @option{--prefix} option should
12024 not contain these characters.
12026 Build directories suffer the same limitations as install directories,
12027 and in addition should not contain the following characters:
12033 For example, the full name of the directory containing the source
12034 files should not contain these characters.
12036 Source and installation file names like @file{main.c} are limited even
12037 further: they should conform to the POSIX/XOPEN
12038 rules described above. In addition, if you plan to port to
12039 non-POSIX environments, you should avoid file names that
12040 differ only in case (e.g., @file{makefile} and @file{Makefile}).
12041 Nowadays it is no longer worth worrying about the 8.3 limits of
12044 @c FIXME This should probably be moved in the "Checking the Distribution"
12045 @c FIXME section...
12046 @node Errors with distclean
12047 @section Errors with distclean
12048 @cindex @code{distclean}, diagnostic
12049 @cindex @samp{make distclean}, diagnostic
12050 @cindex dependencies and distributed files
12053 This is a diagnostic you might encounter while running @samp{make
12056 As explained in @ref{Checking the Distribution}, @samp{make distcheck}
12057 attempts to build and check your package for errors like this one.
12059 @samp{make distcheck} will perform a @code{VPATH} build of your
12060 package (@pxref{VPATH Builds}), and then call @samp{make distclean}.
12061 Files left in the build directory after @samp{make distclean} has run
12062 are listed after this error.
12064 This diagnostic really covers two kinds of errors:
12068 files that are forgotten by distclean;
12070 distributed files that are erroneously rebuilt.
12073 The former left-over files are not distributed, so the fix is to mark
12074 them for cleaning (@pxref{Clean}), this is obvious and doesn't deserve
12077 The latter bug is not always easy to understand and fix, so let's
12078 proceed with an example. Suppose our package contains a program for
12079 which we want to build a man page using @command{help2man}. GNU
12080 @command{help2man} produces simple manual pages from the @option{--help}
12081 and @option{--version} output of other commands (@pxref{Top, , Overview,
12082 help2man, The Help2man Manual}). Because we don't want to force our
12083 users to install @command{help2man}, we decide to distribute the
12084 generated man page using the following setup.
12087 # This Makefile.am is bogus.
12089 foo_SOURCES = foo.c
12090 dist_man_MANS = foo.1
12092 foo.1: foo$(EXEEXT)
12093 help2man --output=foo.1 ./foo$(EXEEXT)
12096 This will effectively distribute the man page. However,
12097 @samp{make distcheck} will fail with:
12100 ERROR: files left in build directory after distclean:
12104 Why was @file{foo.1} rebuilt? Because although distributed,
12105 @file{foo.1} depends on a non-distributed built file:
12106 @file{foo$(EXEEXT)}. @file{foo$(EXEEXT)} is built by the user, so it
12107 will always appear to be newer than the distributed @file{foo.1}.
12109 @samp{make distcheck} caught an inconsistency in our package. Our
12110 intent was to distribute @file{foo.1} so users do not need to install
12111 @command{help2man}, however since this rule causes this file to be
12112 always rebuilt, users @emph{do} need @command{help2man}. Either we
12113 should ensure that @file{foo.1} is not rebuilt by users, or there is
12114 no point in distributing @file{foo.1}.
12116 More generally, the rule is that distributed files should never depend
12117 on non-distributed built files. If you distribute something
12118 generated, distribute its sources.
12120 One way to fix the above example, while still distributing
12121 @file{foo.1} is to not depend on @file{foo$(EXEEXT)}. For instance,
12122 assuming @command{foo --version} and @command{foo --help} do not
12123 change unless @file{foo.c} or @file{configure.ac} change, we could
12124 write the following @file{Makefile.am}:
12128 foo_SOURCES = foo.c
12129 dist_man_MANS = foo.1
12131 foo.1: foo.c $(top_srcdir)/configure.ac
12132 $(MAKE) $(AM_MAKEFLAGS) foo$(EXEEXT)
12133 help2man --output=foo.1 ./foo$(EXEEXT)
12136 This way, @file{foo.1} will not get rebuilt every time
12137 @file{foo$(EXEEXT)} changes. The @command{make} call makes sure
12138 @file{foo$(EXEEXT)} is up-to-date before @command{help2man}. Another
12139 way to ensure this would be to use separate directories for binaries
12140 and man pages, and set @code{SUBDIRS} so that binaries are built
12143 We could also decide not to distribute @file{foo.1}. In
12144 this case it's fine to have @file{foo.1} dependent upon
12145 @file{foo$(EXEEXT)}, since both will have to be rebuilt.
12146 However it would be impossible to build the package in a
12147 cross-compilation, because building @file{foo.1} involves
12148 an @emph{execution} of @file{foo$(EXEEXT)}.
12150 Another context where such errors are common is when distributed files
12151 are built by tools that are built by the package. The pattern is
12155 distributed-file: built-tools distributed-sources
12160 should be changed to
12163 distributed-file: distributed-sources
12164 $(MAKE) $(AM_MAKEFLAGS) built-tools
12169 or you could choose not to distribute @file{distributed-file}, if
12170 cross-compilation does not matter.
12172 The points made through these examples are worth a summary:
12177 Distributed files should never depend upon non-distributed built
12180 Distributed files should be distributed with all their dependencies.
12182 If a file is @emph{intended} to be rebuilt by users, then there is no point
12183 in distributing it.
12187 @vrindex distcleancheck_listfiles
12188 For desperate cases, it's always possible to disable this check by
12189 setting @code{distcleancheck_listfiles} as documented in @ref{Checking
12191 Make sure you do understand the reason why @samp{make distcheck}
12192 complains before you do this. @code{distcleancheck_listfiles} is a
12193 way to @emph{hide} errors, not to fix them. You can always do better.
12195 @node Flag Variables Ordering
12196 @section Flag Variables Ordering
12197 @cindex Ordering flag variables
12198 @cindex Flag variables, ordering
12201 What is the difference between @code{AM_CFLAGS}, @code{CFLAGS}, and
12202 @code{mumble_CFLAGS}?
12206 Why does @command{automake} output @code{CPPFLAGS} after
12207 @code{AM_CPPFLAGS} on compile lines? Shouldn't it be the converse?
12211 My @file{configure} adds some warning flags into @code{CXXFLAGS}. In
12212 one @file{Makefile.am} I would like to append a new flag, however if I
12213 put the flag into @code{AM_CXXFLAGS} it is prepended to the other
12214 flags, not appended.
12217 @subheading Compile Flag Variables
12218 @cindex Flag Variables, Ordering
12219 @cindex Compile Flag Variables
12220 @cindex @code{AM_CCASFLAGS} and @code{CCASFLAGS}
12221 @cindex @code{AM_CFLAGS} and @code{CFLAGS}
12222 @cindex @code{AM_CPPFLAGS} and @code{CPPFLAGS}
12223 @cindex @code{AM_CXXFLAGS} and @code{CXXFLAGS}
12224 @cindex @code{AM_FCFLAGS} and @code{FCFLAGS}
12225 @cindex @code{AM_FFLAGS} and @code{FFLAGS}
12226 @cindex @code{AM_GCJFLAGS} and @code{GCJFLAGS}
12227 @cindex @code{AM_LDFLAGS} and @code{LDFLAGS}
12228 @cindex @code{AM_LFLAGS} and @code{LFLAGS}
12229 @cindex @code{AM_LIBTOOLFLAGS} and @code{LIBTOOLFLAGS}
12230 @cindex @code{AM_OBJCFLAGS} and @code{OBJCFLAGS}
12231 @cindex @code{AM_OBJCXXFLAGS} and @code{OBJXXCFLAGS}
12232 @cindex @code{AM_RFLAGS} and @code{RFLAGS}
12233 @cindex @code{AM_UPCFLAGS} and @code{UPCFLAGS}
12234 @cindex @code{AM_YFLAGS} and @code{YFLAGS}
12235 @cindex @code{CCASFLAGS} and @code{AM_CCASFLAGS}
12236 @cindex @code{CFLAGS} and @code{AM_CFLAGS}
12237 @cindex @code{CPPFLAGS} and @code{AM_CPPFLAGS}
12238 @cindex @code{CXXFLAGS} and @code{AM_CXXFLAGS}
12239 @cindex @code{FCFLAGS} and @code{AM_FCFLAGS}
12240 @cindex @code{FFLAGS} and @code{AM_FFLAGS}
12241 @cindex @code{GCJFLAGS} and @code{AM_GCJFLAGS}
12242 @cindex @code{LDFLAGS} and @code{AM_LDFLAGS}
12243 @cindex @code{LFLAGS} and @code{AM_LFLAGS}
12244 @cindex @code{LIBTOOLFLAGS} and @code{AM_LIBTOOLFLAGS}
12245 @cindex @code{OBJCFLAGS} and @code{AM_OBJCFLAGS}
12246 @cindex @code{OBJCXXFLAGS} and @code{AM_OBJCXXFLAGS}
12247 @cindex @code{RFLAGS} and @code{AM_RFLAGS}
12248 @cindex @code{UPCFLAGS} and @code{AM_UPCFLAGS}
12249 @cindex @code{YFLAGS} and @code{AM_YFLAGS}
12251 This section attempts to answer all the above questions. We will
12252 mostly discuss @code{CPPFLAGS} in our examples, but actually the
12253 answer holds for all the compile flags used in Automake:
12254 @code{CCASFLAGS}, @code{CFLAGS}, @code{CPPFLAGS}, @code{CXXFLAGS},
12255 @code{FCFLAGS}, @code{FFLAGS}, @code{GCJFLAGS}, @code{LDFLAGS},
12256 @code{LFLAGS}, @code{LIBTOOLFLAGS}, @code{OBJCFLAGS}, @code{OBJCXXFLAGS},
12257 @code{RFLAGS}, @code{UPCFLAGS}, and @code{YFLAGS}.
12259 @code{CPPFLAGS}, @code{AM_CPPFLAGS}, and @code{mumble_CPPFLAGS} are
12260 three variables that can be used to pass flags to the C preprocessor
12261 (actually these variables are also used for other languages like C++
12262 or preprocessed Fortran). @code{CPPFLAGS} is the user variable
12263 (@pxref{User Variables}), @code{AM_CPPFLAGS} is the Automake variable,
12264 and @code{mumble_CPPFLAGS} is the variable specific to the
12265 @code{mumble} target (we call this a per-target variable,
12266 @pxref{Program and Library Variables}).
12268 Automake always uses two of these variables when compiling C sources
12269 files. When compiling an object file for the @code{mumble} target,
12270 the first variable will be @code{mumble_CPPFLAGS} if it is defined, or
12271 @code{AM_CPPFLAGS} otherwise. The second variable is always
12274 In the following example,
12277 bin_PROGRAMS = foo bar
12278 foo_SOURCES = xyz.c
12279 bar_SOURCES = main.c
12280 foo_CPPFLAGS = -DFOO
12281 AM_CPPFLAGS = -DBAZ
12285 @file{xyz.o} will be compiled with @samp{$(foo_CPPFLAGS) $(CPPFLAGS)},
12286 (because @file{xyz.o} is part of the @code{foo} target), while
12287 @file{main.o} will be compiled with @samp{$(AM_CPPFLAGS) $(CPPFLAGS)}
12288 (because there is no per-target variable for target @code{bar}).
12290 The difference between @code{mumble_CPPFLAGS} and @code{AM_CPPFLAGS}
12291 being clear enough, let's focus on @code{CPPFLAGS}. @code{CPPFLAGS}
12292 is a user variable, i.e., a variable that users are entitled to modify
12293 in order to compile the package. This variable, like many others,
12294 is documented at the end of the output of @samp{configure --help}.
12296 For instance, someone who needs to add @file{/home/my/usr/include} to
12297 the C compiler's search path would configure a package with
12300 ./configure CPPFLAGS='-I /home/my/usr/include'
12304 and this flag would be propagated to the compile rules of all
12307 It is also not uncommon to override a user variable at
12308 @command{make}-time. Many installers do this with @code{prefix}, but
12309 this can be useful with compiler flags too. For instance, if, while
12310 debugging a C++ project, you need to disable optimization in one
12311 specific object file, you can run something like
12315 make CXXFLAGS=-O0 file.o
12319 The reason @samp{$(CPPFLAGS)} appears after @samp{$(AM_CPPFLAGS)} or
12320 @samp{$(mumble_CPPFLAGS)} in the compile command is that users
12321 should always have the last say. It probably makes more sense if you
12322 think about it while looking at the @samp{CXXFLAGS=-O0} above, which
12323 should supersede any other switch from @code{AM_CXXFLAGS} or
12324 @code{mumble_CXXFLAGS} (and this of course replaces the previous value
12325 of @code{CXXFLAGS}).
12327 You should never redefine a user variable such as @code{CPPFLAGS} in
12328 @file{Makefile.am}. Use @samp{automake -Woverride} to diagnose such
12329 mistakes. Even something like
12332 CPPFLAGS = -DDATADIR=\"$(datadir)\" @@CPPFLAGS@@
12336 is erroneous. Although this preserves @file{configure}'s value of
12337 @code{CPPFLAGS}, the definition of @code{DATADIR} will disappear if a
12338 user attempts to override @code{CPPFLAGS} from the @command{make}
12342 AM_CPPFLAGS = -DDATADIR=\"$(datadir)\"
12346 is all that is needed here if no per-target flags are used.
12348 You should not add options to these user variables within
12349 @file{configure} either, for the same reason. Occasionally you need
12350 to modify these variables to perform a test, but you should reset
12351 their values afterwards. In contrast, it is OK to modify the
12352 @samp{AM_} variables within @file{configure} if you @code{AC_SUBST}
12353 them, but it is rather rare that you need to do this, unless you
12354 really want to change the default definitions of the @samp{AM_}
12355 variables in all @file{Makefile}s.
12357 What we recommend is that you define extra flags in separate
12358 variables. For instance, you may write an Autoconf macro that computes
12359 a set of warning options for the C compiler, and @code{AC_SUBST} them
12360 in @code{WARNINGCFLAGS}; you may also have an Autoconf macro that
12361 determines which compiler and which linker flags should be used to
12362 link with library @file{libfoo}, and @code{AC_SUBST} these in
12363 @code{LIBFOOCFLAGS} and @code{LIBFOOLDFLAGS}. Then, a
12364 @file{Makefile.am} could use these variables as follows:
12367 AM_CFLAGS = $(WARNINGCFLAGS)
12368 bin_PROGRAMS = prog1 prog2
12369 prog1_SOURCES = @dots{}
12370 prog2_SOURCES = @dots{}
12371 prog2_CFLAGS = $(LIBFOOCFLAGS) $(AM_CFLAGS)
12372 prog2_LDFLAGS = $(LIBFOOLDFLAGS)
12375 In this example both programs will be compiled with the flags
12376 substituted into @samp{$(WARNINGCFLAGS)}, and @code{prog2} will
12377 additionally be compiled with the flags required to link with
12380 Note that listing @code{AM_CFLAGS} in a per-target @code{CFLAGS}
12381 variable is a common idiom to ensure that @code{AM_CFLAGS} applies to
12382 every target in a @file{Makefile.in}.
12384 Using variables like this gives you full control over the ordering of
12385 the flags. For instance, if there is a flag in $(WARNINGCFLAGS) that
12386 you want to negate for a particular target, you can use something like
12387 @samp{prog1_CFLAGS = $(AM_CFLAGS) -no-flag}. If all of these flags had
12388 been forcefully appended to @code{CFLAGS}, there would be no way to
12389 disable one flag. Yet another reason to leave user variables to
12392 Finally, we have avoided naming the variable of the example
12393 @code{LIBFOO_LDFLAGS} (with an underscore) because that would cause
12394 Automake to think that this is actually a per-target variable (like
12395 @code{mumble_LDFLAGS}) for some non-declared @code{LIBFOO} target.
12397 @subheading Other Variables
12399 There are other variables in Automake that follow similar principles
12400 to allow user options. For instance, Texinfo rules (@pxref{Texinfo})
12401 use @code{MAKEINFOFLAGS} and @code{AM_MAKEINFOFLAGS}. Similarly,
12402 DejaGnu tests (@pxref{DejaGnu Tests}) use @code{RUNTESTDEFAULTFLAGS} and
12403 @code{AM_RUNTESTDEFAULTFLAGS}. The tags and ctags rules
12404 (@pxref{Tags}) use @code{ETAGSFLAGS}, @code{AM_ETAGSFLAGS},
12405 @code{CTAGSFLAGS}, and @code{AM_CTAGSFLAGS}. Java rules
12406 (@pxref{Java}) use @code{JAVACFLAGS} and @code{AM_JAVACFLAGS}. None
12407 of these rules support per-target flags (yet).
12409 To some extent, even @code{AM_MAKEFLAGS} (@pxref{Subdirectories})
12410 obeys this naming scheme. The slight difference is that
12411 @code{MAKEFLAGS} is passed to sub-@command{make}s implicitly by
12412 @command{make} itself.
12414 @code{ARFLAGS} (@pxref{A Library}) is usually defined by Automake and
12415 has neither @code{AM_} nor per-target cousin.
12417 Finally you should not think that the existence of a per-target
12418 variable implies the existence of an @code{AM_} variable or of a user
12419 variable. For instance, the @code{mumble_LDADD} per-target variable
12420 overrides the makefile-wide @code{LDADD} variable (which is not a user
12421 variable), and @code{mumble_LIBADD} exists only as a per-target
12422 variable. @xref{Program and Library Variables}.
12425 @node Renamed Objects
12426 @section Why are object files sometimes renamed?
12428 This happens when per-target compilation flags are used. Object
12429 files need to be renamed just in case they would clash with object
12430 files compiled from the same sources, but with different flags.
12431 Consider the following example.
12434 bin_PROGRAMS = true false
12435 true_SOURCES = generic.c
12436 true_CPPFLAGS = -DEXIT_CODE=0
12437 false_SOURCES = generic.c
12438 false_CPPFLAGS = -DEXIT_CODE=1
12442 Obviously the two programs are built from the same source, but it
12443 would be bad if they shared the same object, because @file{generic.o}
12444 cannot be built with both @samp{-DEXIT_CODE=0} @emph{and}
12445 @samp{-DEXIT_CODE=1}. Therefore @command{automake} outputs rules to
12446 build two different objects: @file{true-generic.o} and
12447 @file{false-generic.o}.
12449 @command{automake} doesn't actually look whether source files are
12450 shared to decide if it must rename objects. It will just rename all
12451 objects of a target as soon as it sees per-target compilation flags
12454 It's OK to share object files when per-target compilation flags are not
12455 used. For instance, @file{true} and @file{false} will both use
12456 @file{version.o} in the following example.
12459 AM_CPPFLAGS = -DVERSION=1.0
12460 bin_PROGRAMS = true false
12461 true_SOURCES = true.c version.c
12462 false_SOURCES = false.c version.c
12465 Note that the renaming of objects is also affected by the
12466 @code{_SHORTNAME} variable (@pxref{Program and Library Variables}).
12469 @node Per-Object Flags
12470 @section Per-Object Flags Emulation
12471 @cindex Per-object flags, emulated
12474 One of my source files needs to be compiled with different flags. How
12478 Automake supports per-program and per-library compilation flags (see
12479 @ref{Program and Library Variables} and @ref{Flag Variables
12480 Ordering}). With this you can define compilation flags that apply to
12481 all files compiled for a target. For instance, in
12485 foo_SOURCES = foo.c foo.h bar.c bar.h main.c
12486 foo_CFLAGS = -some -flags
12490 @file{foo-foo.o}, @file{foo-bar.o}, and @file{foo-main.o} will all be
12491 compiled with @samp{-some -flags}. (If you wonder about the names of
12492 these object files, see @ref{Renamed Objects}.) Note that
12493 @code{foo_CFLAGS} gives the flags to use when compiling all the C
12494 sources of the @emph{program} @code{foo}, it has nothing to do with
12495 @file{foo.c} or @file{foo-foo.o} specifically.
12497 What if @file{foo.c} needs to be compiled into @file{foo.o} using some
12498 specific flags, that none of the other files requires? Obviously
12499 per-program flags are not directly applicable here. Something like
12500 per-object flags are expected, i.e., flags that would be used only
12501 when creating @file{foo-foo.o}. Automake does not support that,
12502 however this is easy to simulate using a library that contains only
12503 that object, and compiling this library with per-library flags.
12507 foo_SOURCES = bar.c bar.h main.c
12508 foo_CFLAGS = -some -flags
12509 foo_LDADD = libfoo.a
12510 noinst_LIBRARIES = libfoo.a
12511 libfoo_a_SOURCES = foo.c foo.h
12512 libfoo_a_CFLAGS = -some -other -flags
12515 Here @file{foo-bar.o} and @file{foo-main.o} will all be
12516 compiled with @samp{-some -flags}, while @file{libfoo_a-foo.o} will
12517 be compiled using @samp{-some -other -flags}. Eventually, all
12518 three objects will be linked to form @file{foo}.
12520 This trick can also be achieved using Libtool convenience libraries,
12521 for instance @samp{noinst_LTLIBRARIES = libfoo.la} (@pxref{Libtool
12522 Convenience Libraries}).
12524 Another tempting idea to implement per-object flags is to override the
12525 compile rules @command{automake} would output for these files.
12526 Automake will not define a rule for a target you have defined, so you
12527 could think about defining the @samp{foo-foo.o: foo.c} rule yourself.
12528 We recommend against this, because this is error prone. For instance,
12529 if you add such a rule to the first example, it will break the day you
12530 decide to remove @code{foo_CFLAGS} (because @file{foo.c} will then be
12531 compiled as @file{foo.o} instead of @file{foo-foo.o}, @pxref{Renamed
12532 Objects}). Also in order to support dependency tracking, the two
12533 @file{.o}/@file{.obj} extensions, and all the other flags variables
12534 involved in a compilation, you will end up modifying a copy of the
12535 rule previously output by @command{automake} for this file. If a new
12536 release of Automake generates a different rule, your copy will need to
12537 be updated by hand.
12539 @node Multiple Outputs
12540 @section Handling Tools that Produce Many Outputs
12541 @cindex multiple outputs, rules with
12542 @cindex many outputs, rules with
12543 @cindex rules with multiple outputs
12545 This section describes a @command{make} idiom that can be used when a
12546 tool produces multiple output files. It is not specific to Automake
12547 and can be used in ordinary @file{Makefile}s.
12549 Suppose we have a program called @command{foo} that will read one file
12550 called @file{data.foo} and produce two files named @file{data.c} and
12551 @file{data.h}. We want to write a @file{Makefile} rule that captures
12552 this one-to-two dependency.
12554 The naive rule is incorrect:
12557 # This is incorrect.
12558 data.c data.h: data.foo
12563 What the above rule really says is that @file{data.c} and
12564 @file{data.h} each depend on @file{data.foo}, and can each be built by
12565 running @samp{foo data.foo}. In other words it is equivalent to:
12568 # We do not want this.
12576 which means that @command{foo} can be run twice. Usually it will not
12577 be run twice, because @command{make} implementations are smart enough
12578 to check for the existence of the second file after the first one has
12579 been built; they will therefore detect that it already exists.
12580 However there are a few situations where it can run twice anyway:
12584 The most worrying case is when running a parallel @command{make}. If
12585 @file{data.c} and @file{data.h} are built in parallel, two @samp{foo
12586 data.foo} commands will run concurrently. This is harmful.
12588 Another case is when the dependency (here @file{data.foo}) is
12589 (or depends upon) a phony target.
12592 A solution that works with parallel @command{make} but not with
12593 phony dependencies is the following:
12596 data.c data.h: data.foo
12602 The above rules are equivalent to
12607 data.h: data.foo data.c
12612 therefore a parallel @command{make} will have to serialize the builds
12613 of @file{data.c} and @file{data.h}, and will detect that the second is
12614 no longer needed once the first is over.
12616 Using this pattern is probably enough for most cases. However it does
12617 not scale easily to more output files (in this scheme all output files
12618 must be totally ordered by the dependency relation), so we will
12619 explore a more complicated solution.
12621 Another idea is to write the following:
12624 # There is still a problem with this one.
12631 The idea is that @samp{foo data.foo} is run only when @file{data.c}
12632 needs to be updated, but we further state that @file{data.h} depends
12633 upon @file{data.c}. That way, if @file{data.h} is required and
12634 @file{data.foo} is out of date, the dependency on @file{data.c} will
12637 This is almost perfect, but suppose we have built @file{data.h} and
12638 @file{data.c}, and then we erase @file{data.h}. Then, running
12639 @samp{make data.h} will not rebuild @file{data.h}. The above rules
12640 just state that @file{data.c} must be up-to-date with respect to
12641 @file{data.foo}, and this is already the case.
12643 What we need is a rule that forces a rebuild when @file{data.h} is
12644 missing. Here it is:
12650 ## Recover from the removal of $@@
12651 @@if test -f $@@; then :; else \
12653 $(MAKE) $(AM_MAKEFLAGS) data.c; \
12657 The above scheme can be extended to handle more outputs and more
12658 inputs. One of the outputs is selected to serve as a witness to the
12659 successful completion of the command, it depends upon all inputs, and
12660 all other outputs depend upon it. For instance, if @command{foo}
12661 should additionally read @file{data.bar} and also produce
12662 @file{data.w} and @file{data.x}, we would write:
12665 data.c: data.foo data.bar
12666 foo data.foo data.bar
12667 data.h data.w data.x: data.c
12668 ## Recover from the removal of $@@
12669 @@if test -f $@@; then :; else \
12671 $(MAKE) $(AM_MAKEFLAGS) data.c; \
12675 However there are now three minor problems in this setup. One is related
12676 to the timestamp ordering of @file{data.h}, @file{data.w},
12677 @file{data.x}, and @file{data.c}. Another one is a race condition
12678 if a parallel @command{make} attempts to run multiple instances of the
12679 recover block at once. Finally, the recursive rule breaks @samp{make -n}
12680 when run with GNU @command{make} (as well as some other @command{make}
12681 implementations), as it may remove @file{data.h} even when it should not
12682 (@pxref{MAKE Variable, , How the @code{MAKE} Variable Works, make,
12683 The GNU Make Manual}).
12685 Let us deal with the first problem. @command{foo} outputs four files,
12686 but we do not know in which order these files are created. Suppose
12687 that @file{data.h} is created before @file{data.c}. Then we have a
12688 weird situation. The next time @command{make} is run, @file{data.h}
12689 will appear older than @file{data.c}, the second rule will be
12690 triggered, a shell will be started to execute the @samp{if@dots{}fi}
12691 command, but actually it will just execute the @code{then} branch,
12692 that is: nothing. In other words, because the witness we selected is
12693 not the first file created by @command{foo}, @command{make} will start
12694 a shell to do nothing each time it is run.
12696 A simple riposte is to fix the timestamps when this happens.
12699 data.c: data.foo data.bar
12700 foo data.foo data.bar
12701 data.h data.w data.x: data.c
12702 @@if test -f $@@; then \
12705 ## Recover from the removal of $@@
12707 $(MAKE) $(AM_MAKEFLAGS) data.c; \
12711 Another solution is to use a different and dedicated file as witness,
12712 rather than using any of @command{foo}'s outputs.
12715 data.stamp: data.foo data.bar
12718 foo data.foo data.bar
12719 @@mv -f data.tmp $@@
12720 data.c data.h data.w data.x: data.stamp
12721 ## Recover from the removal of $@@
12722 @@if test -f $@@; then :; else \
12723 rm -f data.stamp; \
12724 $(MAKE) $(AM_MAKEFLAGS) data.stamp; \
12728 @file{data.tmp} is created before @command{foo} is run, so it has a
12729 timestamp older than output files output by @command{foo}. It is then
12730 renamed to @file{data.stamp} after @command{foo} has run, because we
12731 do not want to update @file{data.stamp} if @command{foo} fails.
12733 This solution still suffers from the second problem: the race
12734 condition in the recover rule. If, after a successful build, a user
12735 erases @file{data.c} and @file{data.h}, and runs @samp{make -j}, then
12736 @command{make} may start both recover rules in parallel. If the two
12737 instances of the rule execute @samp{$(MAKE) $(AM_MAKEFLAGS)
12738 data.stamp} concurrently the build is likely to fail (for instance, the
12739 two rules will create @file{data.tmp}, but only one can rename it).
12741 Admittedly, such a weird situation does not arise during ordinary
12742 builds. It occurs only when the build tree is mutilated. Here
12743 @file{data.c} and @file{data.h} have been explicitly removed without
12744 also removing @file{data.stamp} and the other output files.
12745 @code{make clean; make} will always recover from these situations even
12746 with parallel makes, so you may decide that the recover rule is solely
12747 to help non-parallel make users and leave things as-is. Fixing this
12748 requires some locking mechanism to ensure only one instance of the
12749 recover rule rebuilds @file{data.stamp}. One could imagine something
12750 along the following lines.
12753 data.c data.h data.w data.x: data.stamp
12754 ## Recover from the removal of $@@
12755 @@if test -f $@@; then :; else \
12756 trap 'rm -rf data.lock data.stamp' 1 2 13 15; \
12757 ## mkdir is a portable test-and-set
12758 if mkdir data.lock 2>/dev/null; then \
12759 ## This code is being executed by the first process.
12760 rm -f data.stamp; \
12761 $(MAKE) $(AM_MAKEFLAGS) data.stamp; \
12762 result=$$?; rm -rf data.lock; exit $$result; \
12764 ## This code is being executed by the follower processes.
12765 ## Wait until the first process is done.
12766 while test -d data.lock; do sleep 1; done; \
12767 ## Succeed if and only if the first process succeeded.
12768 test -f data.stamp; \
12773 Using a dedicated witness, like @file{data.stamp}, is very handy when
12774 the list of output files is not known beforehand. As an illustration,
12775 consider the following rules to compile many @file{*.el} files into
12776 @file{*.elc} files in a single command. It does not matter how
12777 @code{ELFILES} is defined (as long as it is not empty: empty targets
12778 are not accepted by POSIX).
12781 ELFILES = one.el two.el three.el @dots{}
12782 ELCFILES = $(ELFILES:=c)
12784 elc-stamp: $(ELFILES)
12787 $(elisp_comp) $(ELFILES)
12788 @@mv -f elc-temp $@@
12790 $(ELCFILES): elc-stamp
12791 @@if test -f $@@; then :; else \
12792 ## Recover from the removal of $@@
12793 trap 'rm -rf elc-lock elc-stamp' 1 2 13 15; \
12794 if mkdir elc-lock 2>/dev/null; then \
12795 ## This code is being executed by the first process.
12797 $(MAKE) $(AM_MAKEFLAGS) elc-stamp; \
12800 ## This code is being executed by the follower processes.
12801 ## Wait until the first process is done.
12802 while test -d elc-lock; do sleep 1; done; \
12803 ## Succeed if and only if the first process succeeded.
12804 test -f elc-stamp; exit $$?; \
12810 These solutions all still suffer from the third problem, namely that
12811 they break the promise that @samp{make -n} should not cause any actual
12812 changes to the tree. For those solutions that do not create lock files,
12813 it is possible to split the recover rules into two separate recipe
12814 commands, one of which does all work but the recursion, and the
12815 other invokes the recursive @samp{$(MAKE)}. The solutions involving
12816 locking could act upon the contents of the @samp{MAKEFLAGS} variable,
12817 but parsing that portably is not easy (@pxref{The Make Macro MAKEFLAGS,,,
12818 autoconf, The Autoconf Manual}). Here is an example:
12821 ELFILES = one.el two.el three.el @dots{}
12822 ELCFILES = $(ELFILES:=c)
12824 elc-stamp: $(ELFILES)
12827 $(elisp_comp) $(ELFILES)
12828 @@mv -f elc-temp $@@
12830 $(ELCFILES): elc-stamp
12831 ## Recover from the removal of $@@
12832 @@dry=; for f in x $$MAKEFLAGS; do \
12838 if test -f $@@; then :; else \
12839 $$dry trap 'rm -rf elc-lock elc-stamp' 1 2 13 15; \
12840 if $$dry mkdir elc-lock 2>/dev/null; then \
12841 ## This code is being executed by the first process.
12842 $$dry rm -f elc-stamp; \
12843 $(MAKE) $(AM_MAKEFLAGS) elc-stamp; \
12844 $$dry rmdir elc-lock; \
12846 ## This code is being executed by the follower processes.
12847 ## Wait until the first process is done.
12848 while test -d elc-lock && test -z "$$dry"; do \
12852 ## Succeed if and only if the first process succeeded.
12853 $$dry test -f elc-stamp; exit $$?; \
12858 For completeness it should be noted that GNU @command{make} is able to
12859 express rules with multiple output files using pattern rules
12860 (@pxref{Pattern Examples, , Pattern Rule Examples, make, The GNU Make
12861 Manual}). We do not discuss pattern rules here because they are not
12862 portable, but they can be convenient in packages that assume GNU
12866 @node Hard-Coded Install Paths
12867 @section Installing to Hard-Coded Locations
12870 My package needs to install some configuration file. I tried to use
12871 the following rule, but @samp{make distcheck} fails. Why?
12875 install-data-local:
12876 $(INSTALL_DATA) $(srcdir)/afile $(DESTDIR)/etc/afile
12881 My package needs to populate the installation directory of another
12882 package at install-time. I can easily compute that installation
12883 directory in @file{configure}, but if I install files therein,
12884 @samp{make distcheck} fails. How else should I do?
12887 These two setups share their symptoms: @samp{make distcheck} fails
12888 because they are installing files to hard-coded paths. In the later
12889 case the path is not really hard-coded in the package, but we can
12890 consider it to be hard-coded in the system (or in whichever tool that
12891 supplies the path). As long as the path does not use any of the
12892 standard directory variables (@samp{$(prefix)}, @samp{$(bindir)},
12893 @samp{$(datadir)}, etc.), the effect will be the same:
12894 user-installations are impossible.
12896 As a (non-root) user who wants to install a package, you usually have no
12897 right to install anything in @file{/usr} or @file{/usr/local}. So you
12898 do something like @samp{./configure --prefix ~/usr} to install a
12899 package in your own @file{~/usr} tree.
12901 If a package attempts to install something to some hard-coded path
12902 (e.g., @file{/etc/afile}), regardless of this @option{--prefix} setting,
12903 then the installation will fail. @samp{make distcheck} performs such
12904 a @option{--prefix} installation, hence it will fail too.
12906 Now, there are some easy solutions.
12908 The above @code{install-data-local} example for installing
12909 @file{/etc/afile} would be better replaced by
12912 sysconf_DATA = afile
12916 by default @code{sysconfdir} will be @samp{$(prefix)/etc}, because
12917 this is what the GNU Standards require. When such a package is
12918 installed on an FHS compliant system, the installer will have to set
12919 @samp{--sysconfdir=/etc}. As the maintainer of the package you
12920 should not be concerned by such site policies: use the appropriate
12921 standard directory variable to install your files so that the installer
12922 can easily redefine these variables to match their site conventions.
12924 Installing files that should be used by another package is slightly
12925 more involved. Let's take an example and assume you want to install
12926 a shared library that is a Python extension module. If you ask Python
12927 where to install the library, it will answer something like this:
12930 % @kbd{python -c 'from distutils import sysconfig;
12931 print sysconfig.get_python_lib(1,0)'}
12932 /usr/lib/python2.5/site-packages
12935 If you indeed use this absolute path to install your shared library,
12936 non-root users will not be able to install the package, hence
12939 Let's do better. The @samp{sysconfig.get_python_lib()} function
12940 actually accepts a third argument that will replace Python's
12941 installation prefix.
12944 % @kbd{python -c 'from distutils import sysconfig;
12945 print sysconfig.get_python_lib(1,0,"$@{exec_prefix@}")'}
12946 $@{exec_prefix@}/lib/python2.5/site-packages
12949 You can also use this new path. If you do
12952 root users can install your package with the same @option{--prefix}
12953 as Python (you get the behavior of the previous attempt)
12956 non-root users can install your package too, they will have the
12957 extension module in a place that is not searched by Python but they
12958 can work around this using environment variables (and if you installed
12959 scripts that use this shared library, it's easy to tell Python were to
12960 look in the beginning of your script, so the script works in both
12964 The @code{AM_PATH_PYTHON} macro uses similar commands to define
12965 @samp{$(pythondir)} and @samp{$(pyexecdir)} (@pxref{Python}).
12967 Of course not all tools are as advanced as Python regarding that
12968 substitution of @var{prefix}. So another strategy is to figure the
12969 part of the installation directory that must be preserved. For
12970 instance, here is how @code{AM_PATH_LISPDIR} (@pxref{Emacs Lisp})
12971 computes @samp{$(lispdir)}:
12974 $EMACS -batch -q -eval '(while load-path
12975 (princ (concat (car load-path) "\n"))
12976 (setq load-path (cdr load-path)))' >conftest.out
12979 -e '/.*\/lib\/x*emacs\/site-lisp$/@{
12980 s,.*/lib/\(x*emacs/site-lisp\)$,$@{libdir@}/\1,;p;q;
12982 -e '/.*\/share\/x*emacs\/site-lisp$/@{
12983 s,.*/share/\(x*emacs/site-lisp\),$@{datarootdir@}/\1,;p;q;
12988 I.e., it just picks the first directory that looks like
12989 @file{*/lib/*emacs/site-lisp} or @file{*/share/*emacs/site-lisp} in
12990 the search path of emacs, and then substitutes @samp{$@{libdir@}} or
12991 @samp{$@{datadir@}} appropriately.
12993 The emacs case looks complicated because it processes a list and
12994 expects two possible layouts, otherwise it's easy, and the benefits for
12995 non-root users are really worth the extra @command{sed} invocation.
12998 @node Debugging Make Rules
12999 @section Debugging Make Rules
13000 @cindex debugging rules
13001 @cindex rules, debugging
13003 The rules and dependency trees generated by @command{automake} can get
13004 rather complex, and leave the developer head-scratching when things
13005 don't work as expected. Besides the debug options provided by the
13006 @command{make} command (@pxref{Options Summary,,, make, The GNU Make
13007 Manual}), here's a couple of further hints for debugging makefiles
13008 generated by @command{automake} effectively:
13012 If less verbose output has been enabled in the package with the use
13013 of silent rules (@pxref{Automake Silent Rules}), you can use
13014 @code{make V=1} to see the commands being executed.
13016 @code{make -n} can help show what would be done without actually doing
13017 it. Note however, that this will @emph{still execute} commands prefixed
13018 with @samp{+}, and, when using GNU @command{make}, commands that contain
13019 the strings @samp{$(MAKE)} or @samp{$@{MAKE@}} (@pxref{Instead of
13020 Execution,,, make, The GNU Make Manual}).
13021 Typically, this is helpful to show what recursive rules would do, but it
13022 means that, in your own rules, you should not mix such recursion with
13023 actions that change any files.@footnote{Automake's @samp{dist} and
13024 @samp{distcheck} rules had a bug in this regard in that they created
13025 directories even with @option{-n}, but this has been fixed in Automake
13026 1.11.} Furthermore, note that GNU @command{make} will update
13027 prerequisites for the @file{Makefile} file itself even with @option{-n}
13028 (@pxref{Remaking Makefiles,,, make, The GNU Make Manual}).
13030 @code{make SHELL="/bin/bash -vx"} can help debug complex rules.
13031 @xref{The Make Macro SHELL,,, autoconf, The Autoconf Manual}, for some
13032 portability quirks associated with this construct.
13034 @code{echo 'print: ; @@echo "$(VAR)"' | make -f Makefile -f - print}
13035 can be handy to examine the expanded value of variables. You may need
13036 to use a target other than @samp{print} if that is already used or a
13037 file with that name exists.
13039 @url{http://bashdb.sourceforge.net/@/remake/} provides a modified
13040 GNU @command{make} command called @command{remake} that copes with
13041 complex GNU @command{make}-specific Makefiles and allows to trace
13042 execution, examine variables, and call rules interactively, much like
13047 @node Reporting Bugs
13048 @section Reporting Bugs
13050 Most nontrivial software has bugs. Automake is no exception. Although
13051 we cannot promise we can or will fix a bug, and we might not even agree
13052 that it is a bug, we want to hear about problems you encounter. Often we
13053 agree they are bugs and want to fix them.
13055 To make it possible for us to fix a bug, please report it. In order to
13056 do so effectively, it helps to know when and how to do it.
13058 Before reporting a bug, it is a good idea to see if it is already known.
13059 You can look at the @uref{http://debbugs.gnu.org/, GNU Bug Tracker}
13060 and the @uref{http://lists.gnu.org/@/archive/@/html/@/bug-automake/,
13061 bug-automake mailing list archives} for previous bug reports. We
13063 @uref{http://sourceware.org/@/cgi-bin/@/gnatsweb.pl?database=automake,
13064 Gnats database} for bug tracking, so some bugs might have been reported
13065 there already. Please do not use it for new bug reports, however.
13067 If the bug is not already known, it should be reported. It is very
13068 important to report bugs in a way that is useful and efficient. For
13069 this, please familiarize yourself with
13070 @uref{http://www.chiark.greenend.org.uk/@/~sgtatham/@/bugs.html, How to
13071 Report Bugs Effectively} and
13072 @uref{http://catb.org/@/~esr/@/faqs/@/smart-questions.html, How to Ask
13073 Questions the Smart Way}. This helps you and developers to save time
13074 which can then be spent on fixing more bugs and implementing more
13077 For a bug report, a feature request or other suggestions, please send
13078 email to @email{@value{PACKAGE_BUGREPORT}}. This will then open a new
13079 bug in the @uref{http://debbugs.gnu.org/@/automake, bug tracker}. Be
13080 sure to include the versions of Autoconf and Automake that you use.
13081 Ideally, post a minimal @file{Makefile.am} and @file{configure.ac} that
13082 reproduces the problem you encounter. If you have encountered test
13083 suite failures, please attach the @file{test-suite.log} file.
13085 @c ========================================================== Appendices
13088 @node Copying This Manual
13089 @appendix Copying This Manual
13092 * GNU Free Documentation License:: License for copying this manual
13095 @node GNU Free Documentation License
13096 @appendixsec GNU Free Documentation License
13104 * Macro Index:: Index of Autoconf macros
13105 * Variable Index:: Index of Makefile variables
13106 * General Index:: General index
13110 @appendixsec Macro Index
13114 @node Variable Index
13115 @appendixsec Variable Index
13119 @node General Index
13120 @appendixsec General Index
13127 @c LocalWords: texinfo setfilename settitle setchapternewpage texi direntry
13128 @c LocalWords: dircategory in's aclocal ifinfo titlepage Tromey vskip pt sp
13129 @c LocalWords: filll defcodeindex ov cv op tr syncodeindex fn cp vr ifnottex
13130 @c LocalWords: dir Automake's ac Dist Gnits gnits dfn Autoconf's pxref
13131 @c LocalWords: cindex Autoconf autoconf perl samp cvs dist trindex SUBST foo
13132 @c LocalWords: xs emph FIXME ref vindex pkglibdir pkgincludedir pkgdatadir mt
13133 @c LocalWords: pkg libdir cpio bindir sbindir rmt pax sbin zar zardir acindex
13134 @c LocalWords: HTML htmldir html noinst TEXINFOS nodist nobase strudel CFLAGS
13135 @c LocalWords: libmumble CC YFLAGS itemx de fication config url comp
13136 @c LocalWords: depcomp elisp sh mdate mkinstalldirs mkdir py tex dvi ps pdf
13137 @c LocalWords: ylwrap zardoz INIT gettext acinclude mv FUNCS LIBOBJS LDADD fr
13138 @c LocalWords: uref featureful dnl src LINGUAS es ko nl pl sl sv PROG ISC doc
13139 @c LocalWords: POSIX STDC fcntl FUNC ALLOCA blksize struct stat intl po chmod
13140 @c LocalWords: ChangeLog SUBDIRS gettextize gpl testdata getopt INTLLIBS cpp
13141 @c LocalWords: localedir datadir DLOCALEDIR DEXIT CPPFLAGS autoreconf opindex
13142 @c LocalWords: AUX var symlink deps Wno Wnone package's aclocal's distclean
13143 @c LocalWords: ltmain xref LIBSOURCE LIBSOURCES LIBOBJ MEMCMP vs RANLIB CXX
13144 @c LocalWords: LDFLAGS LIBTOOL libtool XTRA LIBS gettext's acdir APIVERSION
13145 @c LocalWords: dirlist noindent usr TIOCGWINSZ sc
13146 @c LocalWords: GWINSZ termios SRCDIR tarball bzip LISPDIR lispdir XEmacs CCAS
13147 @c LocalWords: emacsen MicroEmacs CCASFLAGS UX GCJ gcj GCJFLAGS posix DMALLOC
13148 @c LocalWords: dmalloc ldmalloc REGEX regex DEPDIR DEP DEFUN aclocaldir fi
13149 @c LocalWords: mymacro myothermacro AMFLAGS autopoint autogen libtoolize yum
13150 @c LocalWords: autoheader README MAKEFLAGS subdir Inetutils sync COND endif
13151 @c LocalWords: Miller's installable includedir inc pkgdata EXEEXT libexec bsd
13152 @c LocalWords: pkglib libexecdir prog libcpio cpio's dlopen dlpreopen linux
13153 @c LocalWords: subsubsection OBJEXT esac lib LTLIBRARIES liblob LIBADD AR ar
13154 @c LocalWords: ARFLAGS cru ing maude libgettext lo LTLIBOBJS rpath SGI PRE yy
13155 @c LocalWords: libmaude CCLD CXXFLAGS FFLAGS LFLAGS OBJCFLAGS RFLAGS DEFS cc
13156 @c LocalWords: OBJCXXFLAGS
13157 @c LocalWords: SHORTNAME vtable srcdir nostdinc basename yxx cxx ll lxx gdb
13158 @c LocalWords: lexers yymaxdepth maxdepth yyparse yylex yyerror yylval lval
13159 @c LocalWords: yychar yydebug yypact yyr yydef def yychk chk yypgo pgo yyact
13160 @c LocalWords: yyexca exca yyerrflag errflag yynerrs nerrs yyps yypv pv yys
13161 @c LocalWords: yystate yytmp tmp yyv yyval val yylloc lloc yyreds yytoks toks
13162 @c LocalWords: yylhs yylen yydefred yydgoto yysindex yyrindex yygindex yyname
13163 @c LocalWords: yytable yycheck yyrule byacc CXXCOMPILE CXXLINK FLINK cfortran
13164 @c LocalWords: Catalogue preprocessable FLIBS libfoo baz JAVACFLAGS java exe
13165 @c LocalWords: SunOS fying basenames exeext uninstalled oldinclude kr FSF's
13166 @c LocalWords: pkginclude oldincludedir sysconf sharedstate localstate gcc rm
13167 @c LocalWords: sysconfdir sharedstatedir localstatedir preexist CLEANFILES gz
13168 @c LocalWords: depfile tmpdepfile depmode const interoperate
13169 @c LocalWords: JAVAC javac JAVAROOT builddir CLASSPATH ENV pyc pyo pkgpython
13170 @c LocalWords: pyexecdir pkgpyexecdir Python's pythondir pkgpythondir txi ois
13171 @c LocalWords: installinfo vers MAKEINFO makeinfo MAKEINFOFLAGS noinstall rf
13172 @c LocalWords: mandir thesame alsothesame installman myexecbin DESTDIR Pinard
13173 @c LocalWords: uninstall installdirs uninstalls MOSTLYCLEANFILES mostlyclean
13174 @c LocalWords: DISTCLEANFILES MAINTAINERCLEANFILES GZIP gzip shar exp
13175 @c LocalWords: distdir distcheck distcleancheck listfiles distuninstallcheck
13176 @c LocalWords: VPATH tarfile stdout XFAIL DejaGnu dejagnu DEJATOOL runtest ln
13177 @c LocalWords: RUNTESTDEFAULTFLAGS toolchain RUNTESTFLAGS asis readme DVIPS
13178 @c LocalWords: installcheck gzipped tarZ std utils etags mkid cd
13179 @c LocalWords: ARGS taggable ETAGSFLAGS lang ctags CTAGSFLAGS GTAGS gtags idl
13180 @c LocalWords: foocc doit idlC multilibs ABIs cmindex defmac ARG enableval FC
13181 @c LocalWords: MSG xtrue DBG pathchk CYGWIN afile proglink versioned CVS's TE
13182 @c LocalWords: wildcards Autoconfiscated subsubheading autotools Meyering API
13183 @c LocalWords: ois's wildcard Wportability cartouche vrindex printindex Duret
13184 @c LocalWords: DSOMEFLAG DVERSION automake Lutz insertcopying versioning FAQ
13185 @c LocalWords: LTLIBOBJ Libtool's libtool's libltdl dlopening itutions libbar
13186 @c LocalWords: WANTEDLIBS libhello sublibraries libtop libsub dlopened Ratfor
13187 @c LocalWords: mymodule timestamps timestamp underquoted MAKEINFOHTMLFLAGS te
13188 @c LocalWords: GNUmakefile Subpackages subpackage's subpackages aux
13189 @c LocalWords: detailmenu Timeline pwd reldir AUTOM autom PREREQ FOOBAR libc
13190 @c LocalWords: libhand subpackage moduleN libmain libmisc FCFLAGS FCCOMPILE
13191 @c LocalWords: FCLINK subst sed ELCFILES elc MAKEINFOHTML dvips esyscmd ustar
13192 @c LocalWords: tarballs Woverride vfi ELFILES djm AutoMake honkin FSF
13193 @c LocalWords: fileutils precanned MacKenzie's reimplement termutils Tromey's
13194 @c LocalWords: cois gnitsians LIBPROGRAMS progs LIBLIBRARIES Textutils Ulrich
13195 @c LocalWords: Matzigkeit Drepper's Gord Matzigkeit's jm Dalley Debian org
13196 @c LocalWords: Administrivia ILU CORBA Sourceware Molenda sourceware Elliston
13197 @c LocalWords: dep Oliva Akim Demaille Aiieeee Demaillator Akim's sourcequake
13198 @c LocalWords: grep backported screenshots libgcj KB unnumberedsubsubsec pre
13199 @c LocalWords: precomputing hacky makedepend inline clearmake LD PRELOAD Rel
13200 @c LocalWords: syscalls perlhist acl pm multitable headitem fdl appendixsec
13201 @c LocalWords: LTALLOCA MALLOC malloc memcmp strdup alloca libcompat xyz DFOO
13202 @c LocalWords: unprefixed buildable preprocessed DBAZ DDATADIR WARNINGCFLAGS
13203 @c LocalWords: LIBFOOCFLAGS LIBFOOLDFLAGS ftable testSubDir obj LIBTOOLFLAGS
13204 @c LocalWords: barexec Pinard's automatize initialize lzip xz cscope