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, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
27 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012 Free Software
31 Permission is granted to copy, distribute and/or modify this document
32 under the terms of the GNU Free Documentation License,
33 Version 1.3 or any later version published by the Free Software
34 Foundation; with no Invariant Sections, with no Front-Cover texts,
35 and with no Back-Cover Texts. A copy of the license is included in the
36 section entitled ``GNU Free Documentation License.''
41 @dircategory Software development
43 * Automake: (automake). Making GNU standards-compliant Makefiles.
46 @dircategory Individual utilities
48 * aclocal-invocation: (automake)aclocal Invocation. Generating aclocal.m4.
49 * automake-invocation: (automake)automake Invocation. Generating Makefile.in.
54 @subtitle For version @value{VERSION}, @value{UPDATED}
55 @author David MacKenzie
57 @author Alexandre Duret-Lutz
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 * Cygnus:: The effect of @option{--cygnus}
121 * Not Enough:: When Automake is not Enough
122 * Distributing:: Distributing the Makefile.in
123 * API Versioning:: About compatibility between Automake versions
124 * Upgrading:: Upgrading to a Newer Automake Version
125 * FAQ:: Frequently Asked Questions
126 * History:: Notes about the history of Automake
127 * Copying This Manual:: How to make copies of this manual
128 * Indices:: Indices of variables, macros, and concepts
131 --- The Detailed Node Listing ---
133 An Introduction to the Autotools
135 * GNU Build System:: Introducing the GNU Build System
136 * Use Cases:: Use Cases for the GNU Build System
137 * Why Autotools:: How Autotools Help
138 * Hello World:: A Small Hello World Package
140 Use Cases for the GNU Build System
142 * Basic Installation:: Common installation procedure
143 * Standard Targets:: A list of standard Makefile targets
144 * Standard Directory Variables:: A list of standard directory variables
145 * Standard Configuration Variables:: Using configuration variables
146 * config.site:: Using a config.site file
147 * VPATH Builds:: Parallel build trees
148 * Two-Part Install:: Installing data and programs separately
149 * Cross-Compilation:: Building for other architectures
150 * Renaming:: Renaming programs at install time
151 * DESTDIR:: Building binary packages with DESTDIR
152 * Preparing Distributions:: Rolling out tarballs
153 * Dependency Tracking:: Automatic dependency tracking
154 * Nested Packages:: The GNU Build Systems can be nested
158 * Creating amhello:: Create @file{amhello-1.0.tar.gz} from scratch
159 * amhello's configure.ac Setup Explained::
160 * amhello's Makefile.am Setup Explained::
164 * General Operation:: General operation of Automake
165 * Strictness:: Standards conformance checking
166 * Uniform:: The Uniform Naming Scheme
167 * Length Limitations:: Staying below the command line length limit
168 * Canonicalization:: How derived variables are named
169 * User Variables:: Variables reserved for the user
170 * Auxiliary Programs:: Programs automake might require
172 Some example packages
174 * Complete:: A simple example, start to finish
175 * true:: Building true and false
177 Scanning @file{configure.ac}, using @command{aclocal}
179 * Requirements:: Configuration requirements
180 * Optional:: Other things Automake recognizes
181 * aclocal Invocation:: Auto-generating aclocal.m4
182 * Macros:: Autoconf macros supplied with Automake
184 Auto-generating aclocal.m4
186 * aclocal Options:: Options supported by aclocal
187 * Macro Search Path:: How aclocal finds .m4 files
188 * Extending aclocal:: Writing your own aclocal macros
189 * Local Macros:: Organizing local macros
190 * Serials:: Serial lines in Autoconf macros
191 * Future of aclocal:: aclocal's scheduled death
193 Autoconf macros supplied with Automake
195 * Public Macros:: Macros that you can use.
196 * Obsolete Macros:: Macros that you should stop using.
197 * Private Macros:: Macros that you should not use.
201 * Subdirectories:: Building subdirectories recursively
202 * Conditional Subdirectories:: Conditionally not building directories
203 * Alternative:: Subdirectories without recursion
204 * Subpackages:: Nesting packages
206 Conditional Subdirectories
208 * SUBDIRS vs DIST_SUBDIRS:: Two sets of directories
209 * Subdirectories with AM_CONDITIONAL:: Specifying conditional subdirectories
210 * Subdirectories with AC_SUBST:: Another way for conditional recursion
211 * Unconfigured Subdirectories:: Not even creating a @samp{Makefile}
213 Building Programs and Libraries
215 * A Program:: Building a program
216 * A Library:: Building a library
217 * A Shared Library:: Building a Libtool library
218 * Program and Library Variables:: Variables controlling program and
220 * Default _SOURCES:: Default source files
221 * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
222 * Program Variables:: Variables used when building a program
223 * Yacc and Lex:: Yacc and Lex support
224 * C++ Support:: Compiling C++ sources
225 * Objective C Support:: Compiling Objective C sources
226 * Unified Parallel C Support:: Compiling Unified Parallel C sources
227 * Assembly Support:: Compiling assembly sources
228 * Fortran 77 Support:: Compiling Fortran 77 sources
229 * Fortran 9x Support:: Compiling Fortran 9x sources
230 * Java Support with gcj:: Compiling Java sources using gcj
231 * Vala Support:: Compiling Vala sources
232 * Support for Other Languages:: Compiling other languages
233 * Dependencies:: Automatic dependency tracking
234 * EXEEXT:: Support for executable extensions
238 * Program Sources:: Defining program sources
239 * Linking:: Linking with libraries or extra objects
240 * Conditional Sources:: Handling conditional sources
241 * Conditional Programs:: Building a program conditionally
243 Building a Shared Library
245 * Libtool Concept:: Introducing Libtool
246 * Libtool Libraries:: Declaring Libtool Libraries
247 * Conditional Libtool Libraries:: Building Libtool Libraries Conditionally
248 * Conditional Libtool Sources:: Choosing Library Sources Conditionally
249 * Libtool Convenience Libraries:: Building Convenience Libtool Libraries
250 * Libtool Modules:: Building Libtool Modules
251 * Libtool Flags:: Using _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS
252 * LTLIBOBJS:: Using $(LTLIBOBJS) and $(LTALLOCA)
253 * Libtool Issues:: Common Issues Related to Libtool's Use
255 Common Issues Related to Libtool's Use
257 * Error required file ltmain.sh not found:: The need to run libtoolize
258 * Objects created both with libtool and without:: Avoid a specific build race
262 * Preprocessing Fortran 77:: Preprocessing Fortran 77 sources
263 * Compiling Fortran 77 Files:: Compiling Fortran 77 sources
264 * Mixing Fortran 77 With C and C++:: Mixing Fortran 77 With C and C++
266 Mixing Fortran 77 With C and C++
268 * How the Linker is Chosen:: Automatic linker selection
272 * Compiling Fortran 9x Files:: Compiling Fortran 9x sources
274 Other Derived Objects
276 * Scripts:: Executable scripts
277 * Headers:: Header files
278 * Data:: Architecture-independent data files
279 * Sources:: Derived sources
283 * Built Sources Example:: Several ways to handle built sources.
287 * Emacs Lisp:: Emacs Lisp
290 * Java:: Java bytecode compilation (deprecated)
293 Building documentation
296 * Man Pages:: Man pages
300 * Basics of Installation:: What gets installed where
301 * The Two Parts of Install:: Installing data and programs separately
302 * Extending Installation:: Adding your own rules for installation
303 * Staged Installs:: Installation in a temporary location
304 * Install Rules for the User:: Useful additional rules
306 What Goes in a Distribution
308 * Basics of Distribution:: Files distributed by default
309 * Fine-grained Distribution Control:: @code{dist_} and @code{nodist_} prefixes
310 * The dist Hook:: A target for last-minute distribution changes
311 * Checking the Distribution:: @samp{make distcheck} explained
312 * The Types of Distributions:: A variety of formats and compression methods
314 Support for test suites
316 * Generalities about Testing:: Generic concepts and terminology about testing
317 * Simple Tests:: Listing test scripts in @code{TESTS}
318 * Custom Test Drivers:: Writing and using custom test drivers
319 * Using the TAP test protocol:: Integrating test scripts that use the TAP protocol
320 * DejaGnu Tests:: Interfacing with the @command{dejagnu} testing framework
321 * Install Tests:: Running tests on installed packages
325 * Scripts-based Testsuites:: Automake-specific concepts and terminology
326 * Serial Test Harness:: Older (and obsolescent) serial test harness
327 * Parallel Test Harness:: Generic concurrent test harness
329 Using the TAP test protocol
331 * Introduction to TAP::
332 * Use TAP with the Automake test harness::
333 * Incompatibilities with other TAP parsers and drivers::
334 * Links and external resources on TAP::
338 * Overview of Custom Test Drivers Support::
339 * Declaring Custom Test Drivers::
340 * API for Custom Test Drivers::
342 API for Custom Test Drivers
344 * Command-line arguments for test drivers::
345 * Log files generation and test results recording::
346 * Testsuite progress output::
348 Changing Automake's Behavior
350 * Options generalities:: Semantics of Automake option
351 * List of Automake options:: A comprehensive list of Automake options
355 * Tags:: Interfacing to cscope, etags and mkid
356 * Suffixes:: Handling new file extensions
357 * Multilibs:: Support for multilibs.
361 * Usage of Conditionals:: Declaring conditional content
362 * Limits of Conditionals:: Enclosing complete statements
366 * Make verbosity:: Make is verbose by default
367 * Tricks For Silencing Make:: Standard and generic ways to silence make
368 * Automake silent-rules Option:: How Automake can help in silencing make
370 When Automake Isn't Enough
372 * Extending:: Adding new rules or overriding existing ones.
373 * Third-Party Makefiles:: Integrating Non-Automake @file{Makefile}s.
375 Frequently Asked Questions about Automake
377 * CVS:: CVS and generated files
378 * maintainer-mode:: missing and AM_MAINTAINER_MODE
379 * Wildcards:: Why doesn't Automake support wildcards?
380 * Limitations on File Names:: Limitations on source and installed file names
381 * distcleancheck:: Files left in build directory after distclean
382 * Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS
383 * Renamed Objects:: Why are object files sometimes renamed?
384 * Per-Object Flags:: How to simulate per-object flags?
385 * Multiple Outputs:: Writing rules for tools with many output files
386 * Hard-Coded Install Paths:: Installing to hard-coded locations
387 * Debugging Make Rules:: Strategies when things don't work as expected
388 * Reporting Bugs:: Feedback on bugs and feature requests
392 * Timeline:: The Automake story.
393 * Dependency Tracking Evolution:: Evolution of Automatic Dependency Tracking
394 * Releases:: Statistics about Automake Releases
396 Dependency Tracking in Automake
398 * First Take on Dependencies:: Precomputed dependency tracking
399 * Dependencies As Side Effects:: Update at developer compile time
400 * Dependencies for the User:: Update at user compile time
401 * Techniques for Dependencies:: Alternative approaches
402 * Recommendations for Tool Writers:: What tool writers can do to help
403 * Future Directions for Dependencies:: Languages Automake does not know
407 * GNU Free Documentation License:: License for copying this manual
411 * Macro Index:: Index of Autoconf macros
412 * Variable Index:: Index of Makefile variables
413 * General Index:: General index
422 @chapter Introduction
424 Automake is a tool for automatically generating @file{Makefile.in}s
425 from files called @file{Makefile.am}. Each @file{Makefile.am} is
426 basically a series of @command{make} variable
427 definitions@footnote{These variables are also called @dfn{make macros}
428 in Make terminology, however in this manual we reserve the term
429 @dfn{macro} for Autoconf's macros.}, with rules being thrown in
430 occasionally. The generated @file{Makefile.in}s are compliant with
431 the GNU Makefile standards.
433 @cindex GNU Makefile standards
435 The GNU Makefile Standards Document
436 (@pxref{Makefile Conventions, , , standards, The GNU Coding Standards})
437 is long, complicated, and subject to change. The goal of Automake is to
438 remove the burden of Makefile maintenance from the back of the
439 individual GNU maintainer (and put it on the back of the Automake
442 The typical Automake input file is simply a series of variable definitions.
443 Each such file is processed to create a @file{Makefile.in}. There
444 should generally be one @file{Makefile.am} per directory of a project.
446 @cindex Constraints of Automake
447 @cindex Automake constraints
449 Automake does constrain a project in certain ways; for instance, it
450 assumes that the project uses Autoconf (@pxref{Top, , Introduction,
451 autoconf, The Autoconf Manual}), and enforces certain restrictions on
452 the @file{configure.ac} contents@footnote{Older Autoconf versions used
453 @file{configure.in}. Autoconf 2.50 and greater promotes
454 @file{configure.ac} over @file{configure.in}. The rest of this
455 documentation will refer to @file{configure.ac}, but Automake also
456 supports @file{configure.in} for backward compatibility.}.
458 @cindex Automake requirements
459 @cindex Requirements, Automake
461 Automake requires @command{perl} in order to generate the
462 @file{Makefile.in}s. However, the distributions created by Automake are
463 fully GNU standards-compliant, and do not require @command{perl} in order
466 @cindex Bugs, reporting
467 @cindex Reporting bugs
468 @cindex E-mail, bug reports
470 For more information on bug reports, @xref{Reporting Bugs}.
472 @node Autotools Introduction
473 @chapter An Introduction to the Autotools
475 If you are new to Automake, maybe you know that it is part of a set of
476 tools called @emph{The Autotools}. Maybe you've already delved into a
477 package full of files named @file{configure}, @file{configure.ac},
478 @file{Makefile.in}, @file{Makefile.am}, @file{aclocal.m4}, @dots{},
479 some of them claiming to be @emph{generated by} Autoconf or Automake.
480 But the exact purpose of these files and their relations is probably
481 fuzzy. The goal of this chapter is to introduce you to this machinery,
482 to show you how it works and how powerful it is. If you've never
483 installed or seen such a package, do not worry: this chapter will walk
486 If you need some teaching material, more illustrations, or a less
487 @command{automake}-centered continuation, some slides for this
488 introduction are available in Alexandre Duret-Lutz's
489 @uref{http://www.lrde.epita.fr/@/~adl/@/autotools.html,
491 This chapter is the written version of the first part of his tutorial.
494 * GNU Build System:: Introducing the GNU Build System
495 * Use Cases:: Use Cases for the GNU Build System
496 * Why Autotools:: How Autotools Help
497 * Hello World:: A Small Hello World Package
500 @node GNU Build System
501 @section Introducing the GNU Build System
502 @cindex GNU Build System, introduction
504 It is a truth universally acknowledged, that as a developer in
505 possession of a new package, you must be in want of a build system.
507 In the Unix world, such a build system is traditionally achieved using
508 the command @command{make} (@pxref{Top, , Overview, make, The GNU Make
509 Manual}). You express the recipe to build your package in a
510 @file{Makefile}. This file is a set of rules to build the files in
511 the package. For instance the program @file{prog} may be built by
512 running the linker on the files @file{main.o}, @file{foo.o}, and
513 @file{bar.o}; the file @file{main.o} may be built by running the
514 compiler on @file{main.c}; etc. Each time @command{make} is run, it
515 reads @file{Makefile}, checks the existence and modification time of
516 the files mentioned, decides what files need to be built (or rebuilt),
517 and runs the associated commands.
519 When a package needs to be built on a different platform than the one
520 it was developed on, its @file{Makefile} usually needs to be adjusted.
521 For instance the compiler may have another name or require more
522 options. In 1991, David J. MacKenzie got tired of customizing
523 @file{Makefile} for the 20 platforms he had to deal with. Instead, he
524 handcrafted a little shell script called @file{configure} to
525 automatically adjust the @file{Makefile} (@pxref{Genesis, , Genesis,
526 autoconf, The Autoconf Manual}). Compiling his package was now
527 as simple as running @code{./configure && make}.
529 @cindex GNU Coding Standards
531 Today this process has been standardized in the GNU project. The GNU
532 Coding Standards (@pxref{Managing Releases, The Release Process, ,
533 standards, The GNU Coding Standards}) explains how each package of the
534 GNU project should have a @file{configure} script, and the minimal
535 interface it should have. The @file{Makefile} too should follow some
536 established conventions. The result? A unified build system that
537 makes all packages almost indistinguishable by the installer. In its
538 simplest scenario, all the installer has to do is to unpack the
539 package, run @code{./configure && make && make install}, and repeat
540 with the next package to install.
542 We call this build system the @dfn{GNU Build System}, since it was
543 grown out of the GNU project. However it is used by a vast number of
544 other packages: following any existing convention has its advantages.
546 @cindex Autotools, introduction
548 The Autotools are tools that will create a GNU Build System for your
549 package. Autoconf mostly focuses on @file{configure} and Automake on
550 @file{Makefile}s. It is entirely possible to create a GNU Build
551 System without the help of these tools. However it is rather
552 burdensome and error-prone. We will discuss this again after some
553 illustration of the GNU Build System in action.
556 @section Use Cases for the GNU Build System
557 @cindex GNU Build System, use cases
558 @cindex GNU Build System, features
559 @cindex Features of the GNU Build System
560 @cindex Use Cases for the GNU Build System
561 @cindex @file{amhello-1.0.tar.gz}, location
562 @cindex @file{amhello-1.0.tar.gz}, use cases
564 In this section we explore several use cases for the GNU Build System.
565 You can replay all these examples on the @file{amhello-1.0.tar.gz}
566 package distributed with Automake. If Automake is installed on your
567 system, you should find a copy of this file in
568 @file{@var{prefix}/share/doc/automake/amhello-1.0.tar.gz}, where
569 @var{prefix} is the installation prefix specified during configuration
570 (@var{prefix} defaults to @file{/usr/local}, however if Automake was
571 installed by some GNU/Linux distribution it most likely has been set
572 to @file{/usr}). If you do not have a copy of Automake installed,
573 you can find a copy of this file inside the @file{doc/} directory of
574 the Automake package.
576 Some of the following use cases present features that are in fact
577 extensions to the GNU Build System. Read: they are not specified by
578 the GNU Coding Standards, but they are nonetheless part of the build
579 system created by the Autotools. To keep things simple, we do not
580 point out the difference. Our objective is to show you many of the
581 features that the build system created by the Autotools will offer to
585 * Basic Installation:: Common installation procedure
586 * Standard Targets:: A list of standard Makefile targets
587 * Standard Directory Variables:: A list of standard directory variables
588 * Standard Configuration Variables:: Using configuration variables
589 * config.site:: Using a config.site file
590 * VPATH Builds:: Parallel build trees
591 * Two-Part Install:: Installing data and programs separately
592 * Cross-Compilation:: Building for other architectures
593 * Renaming:: Renaming programs at install time
594 * DESTDIR:: Building binary packages with DESTDIR
595 * Preparing Distributions:: Rolling out tarballs
596 * Dependency Tracking:: Automatic dependency tracking
597 * Nested Packages:: The GNU Build Systems can be nested
600 @node Basic Installation
601 @subsection Basic Installation
602 @cindex Configuration, basics
603 @cindex Installation, basics
604 @cindex GNU Build System, basics
606 The most common installation procedure looks as follows.
609 ~ % @kbd{tar zxf amhello-1.0.tar.gz}
610 ~ % @kbd{cd amhello-1.0}
611 ~/amhello-1.0 % @kbd{./configure}
613 config.status: creating Makefile
614 config.status: creating src/Makefile
616 ~/amhello-1.0 % @kbd{make}
618 ~/amhello-1.0 % @kbd{make check}
620 ~/amhello-1.0 % @kbd{su}
622 /home/adl/amhello-1.0 # @kbd{make install}
624 /home/adl/amhello-1.0 # @kbd{exit}
625 ~/amhello-1.0 % @kbd{make installcheck}
631 The user first unpacks the package. Here, and in the following
632 examples, we will use the non-portable @code{tar zxf} command for
633 simplicity. On a system without GNU @command{tar} installed, this
634 command should read @code{gunzip -c amhello-1.0.tar.gz | tar xf -}.
636 The user then enters the newly created directory to run the
637 @file{configure} script. This script probes the system for various
638 features, and finally creates the @file{Makefile}s. In this toy
639 example there are only two @file{Makefile}s, but in real-world projects,
640 there may be many more, usually one @file{Makefile} per directory.
642 It is now possible to run @code{make}. This will construct all the
643 programs, libraries, and scripts that need to be constructed for the
644 package. In our example, this compiles the @file{hello} program.
645 All files are constructed in place, in the source tree; we will see
646 later how this can be changed.
648 @code{make check} causes the package's tests to be run. This step is
649 not mandatory, but it is often good to make sure the programs that
650 have been built behave as they should, before you decide to install
651 them. Our example does not contain any tests, so running @code{make
654 @cindex su, before @code{make install}
655 After everything has been built, and maybe tested, it is time to
656 install it on the system. That means copying the programs,
657 libraries, header files, scripts, and other data files from the
658 source directory to their final destination on the system. The
659 command @code{make install} will do that. However, by default
660 everything will be installed in subdirectories of @file{/usr/local}:
661 binaries will go into @file{/usr/local/bin}, libraries will end up in
662 @file{/usr/local/lib}, etc. This destination is usually not writable
663 by any user, so we assume that we have to become root before we can
664 run @code{make install}. In our example, running @code{make install}
665 will copy the program @file{hello} into @file{/usr/local/bin}
666 and @file{README} into @file{/usr/local/share/doc/amhello}.
668 A last and optional step is to run @code{make installcheck}. This
669 command may run tests on the installed files. @code{make check} tests
670 the files in the source tree, while @code{make installcheck} tests
671 their installed copies. The tests run by the latter can be different
672 from those run by the former. For instance, there are tests that
673 cannot be run in the source tree. Conversely, some packages are set
674 up so that @code{make installcheck} will run the very same tests as
675 @code{make check}, only on different files (non-installed
676 vs.@: installed). It can make a difference, for instance when the
677 source tree's layout is different from that of the installation.
678 Furthermore it may help to diagnose an incomplete installation.
680 Presently most packages do not have any @code{installcheck} tests
681 because the existence of @code{installcheck} is little known, and its
682 usefulness is neglected. Our little toy package is no better: @code{make
683 installcheck} does nothing.
685 @node Standard Targets
686 @subsection Standard @file{Makefile} Targets
688 So far we have come across four ways to run @command{make} in the GNU
689 Build System: @code{make}, @code{make check}, @code{make install}, and
690 @code{make installcheck}. The words @code{check}, @code{install}, and
691 @code{installcheck}, passed as arguments to @command{make}, are called
692 @dfn{targets}. @code{make} is a shorthand for @code{make all},
693 @code{all} being the default target in the GNU Build System.
695 Here is a list of the most useful targets that the GNU Coding Standards
701 Build programs, libraries, documentation, etc.@: (same as @code{make}).
704 Install what needs to be installed, copying the files from the
705 package's tree to system-wide directories.
706 @item make install-strip
707 @trindex install-strip
708 Same as @code{make install}, then strip debugging symbols. Some
709 users like to trade space for useful bug reports@enddots{}
712 The opposite of @code{make install}: erase the installed files.
713 (This needs to be run from the same build tree that was installed.)
716 Erase from the build tree the files built by @code{make all}.
719 Additionally erase anything @code{./configure} created.
722 Run the test suite, if any.
723 @item make installcheck
724 @trindex installcheck
725 Check the installed programs or libraries, if supported.
728 Recreate @file{@var{package}-@var{version}.tar.gz} from all the source
732 @node Standard Directory Variables
733 @subsection Standard Directory Variables
734 @cindex directory variables
736 The GNU Coding Standards also specify a hierarchy of variables to
737 denote installation directories. Some of these are:
739 @multitable {Directory variable} {@code{$@{datarootdir@}/doc/$@{PACKAGE@}}}
740 @headitem Directory variable @tab Default value
741 @item @code{prefix} @tab @code{/usr/local}
742 @item @w{@ @ @code{exec_prefix}} @tab @code{$@{prefix@}}
743 @item @w{@ @ @ @ @code{bindir}} @tab @code{$@{exec_prefix@}/bin}
744 @item @w{@ @ @ @ @code{libdir}} @tab @code{$@{exec_prefix@}/lib}
745 @item @w{@ @ @ @ @dots{}}
746 @item @w{@ @ @code{includedir}} @tab @code{$@{prefix@}/include}
747 @item @w{@ @ @code{datarootdir}} @tab @code{$@{prefix@}/share}
748 @item @w{@ @ @ @ @code{datadir}} @tab @code{$@{datarootdir@}}
749 @item @w{@ @ @ @ @code{mandir}} @tab @code{$@{datarootdir@}/man}
750 @item @w{@ @ @ @ @code{infodir}} @tab @code{$@{datarootdir@}/info}
751 @item @w{@ @ @ @ @code{docdir}} @tab @code{$@{datarootdir@}/doc/$@{PACKAGE@}}
752 @item @w{@ @ @dots{}}
755 @c We should provide a complete table somewhere, but not here. The
756 @c complete list of directory variables it too confusing as-is. It
757 @c requires some explanations that are too complicated for this
758 @c introduction. Besides listing directories like localstatedir
759 @c would make the explanations in ``Two-Part Install'' harder.
761 Each of these directories has a role which is often obvious from its
762 name. In a package, any installable file will be installed in one of
763 these directories. For instance in @code{amhello-1.0}, the program
764 @file{hello} is to be installed in @var{bindir}, the directory for
765 binaries. The default value for this directory is
766 @file{/usr/local/bin}, but the user can supply a different value when
767 calling @command{configure}. Also the file @file{README} will be
768 installed into @var{docdir}, which defaults to
769 @file{/usr/local/share/doc/amhello}.
773 As a user, if you wish to install a package on your own account, you
774 could proceed as follows:
777 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr}
779 ~/amhello-1.0 % @kbd{make}
781 ~/amhello-1.0 % @kbd{make install}
785 This would install @file{~/usr/bin/hello} and
786 @file{~/usr/share/doc/amhello/README}.
788 The list of all such directory options is shown by
789 @code{./configure --help}.
791 @node Standard Configuration Variables
792 @subsection Standard Configuration Variables
793 @cindex configuration variables, overriding
795 The GNU Coding Standards also define a set of standard configuration
796 variables used during the build. Here are some:
805 @item @code{CXXFLAGS}
809 @item @code{CPPFLAGS}
810 C/C++ preprocessor flags
814 @command{configure} usually does a good job at setting appropriate
815 values for these variables, but there are cases where you may want to
816 override them. For instance you may have several versions of a
817 compiler installed and would like to use another one, you may have
818 header files installed outside the default search path of the
819 compiler, or even libraries out of the way of the linker.
821 Here is how one would call @command{configure} to force it to use
822 @command{gcc-3} as C compiler, use header files from
823 @file{~/usr/include} when compiling, and libraries from
824 @file{~/usr/lib} when linking.
827 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr CC=gcc-3 \
828 CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib}
831 Again, a full list of these variables appears in the output of
832 @code{./configure --help}.
835 @subsection Overriding Default Configuration Setting with @file{config.site}
836 @cindex @file{config.site} example
838 When installing several packages using the same setup, it can be
839 convenient to create a file to capture common settings.
840 If a file named @file{@var{prefix}/share/config.site} exists,
841 @command{configure} will source it at the beginning of its execution.
843 Recall the command from the previous section:
846 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr CC=gcc-3 \
847 CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib}
850 Assuming we are installing many package in @file{~/usr}, and will
851 always want to use these definitions of @code{CC}, @code{CPPFLAGS}, and
852 @code{LDFLAGS}, we can automate this by creating the following
853 @file{~/usr/share/config.site} file:
856 test -z "$CC" && CC=gcc-3
857 test -z "$CPPFLAGS" && CPPFLAGS=-I$HOME/usr/include
858 test -z "$LDFLAGS" && LDFLAGS=-L$HOME/usr/lib
861 Now, any time a @file{configure} script is using the @file{~/usr}
862 prefix, it will execute the above @file{config.site} and define
863 these three variables.
866 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr}
867 configure: loading site script /home/adl/usr/share/config.site
871 @xref{Site Defaults, , Setting Site Defaults, autoconf, The Autoconf
872 Manual}, for more information about this feature.
876 @subsection Parallel Build Trees (a.k.a.@: VPATH Builds)
877 @cindex Parallel build trees
879 @cindex source tree and build tree
880 @cindex build tree and source tree
881 @cindex trees, source vs.@: build
883 The GNU Build System distinguishes two trees: the source tree, and
886 The source tree is rooted in the directory containing
887 @file{configure}. It contains all the sources files (those that are
888 distributed), and may be arranged using several subdirectories.
890 The build tree is rooted in the directory in which @file{configure}
891 was run, and is populated with all object files, programs, libraries,
892 and other derived files built from the sources (and hence not
893 distributed). The build tree usually has the same subdirectory layout
894 as the source tree; its subdirectories are created automatically by
897 If @file{configure} is executed in its own directory, the source and
898 build trees are combined: derived files are constructed in the same
899 directories as their sources. This was the case in our first
900 installation example (@pxref{Basic Installation}).
902 A common request from users is that they want to confine all derived
903 files to a single directory, to keep their source directories
904 uncluttered. Here is how we could run @file{configure} to build
905 everything in a subdirectory called @file{build/}.
908 ~ % @kbd{tar zxf ~/amhello-1.0.tar.gz}
909 ~ % @kbd{cd amhello-1.0}
910 ~/amhello-1.0 % @kbd{mkdir build && cd build}
911 ~/amhello-1.0/build % @kbd{../configure}
913 ~/amhello-1.0/build % @kbd{make}
917 These setups, where source and build trees are different, are often
918 called @dfn{parallel builds} or @dfn{VPATH builds}. The expression
919 @emph{parallel build} is misleading: the word @emph{parallel} is a
920 reference to the way the build tree shadows the source tree, it is not
921 about some concurrency in the way build commands are run. For this
922 reason we refer to such setups using the name @emph{VPATH builds} in
923 the following. @emph{VPATH} is the name of the @command{make} feature
924 used by the @file{Makefile}s to allow these builds (@pxref{General
925 Search, , @code{VPATH} Search Path for All Prerequisites, make, The
928 @cindex multiple configurations, example
929 @cindex debug build, example
930 @cindex optimized build, example
932 VPATH builds have other interesting uses. One is to build the same
933 sources with multiple configurations. For instance:
935 @c Keep in sync with amhello-cflags.test.
937 ~ % @kbd{tar zxf ~/amhello-1.0.tar.gz}
938 ~ % @kbd{cd amhello-1.0}
939 ~/amhello-1.0 % @kbd{mkdir debug optim && cd debug}
940 ~/amhello-1.0/debug % @kbd{../configure CFLAGS='-g -O0'}
942 ~/amhello-1.0/debug % @kbd{make}
944 ~/amhello-1.0/debug % cd ../optim
945 ~/amhello-1.0/optim % @kbd{../configure CFLAGS='-O3 -fomit-frame-pointer'}
947 ~/amhello-1.0/optim % @kbd{make}
951 With network file systems, a similar approach can be used to build the
952 same sources on different machines. For instance, suppose that the
953 sources are installed on a directory shared by two hosts: @code{HOST1}
954 and @code{HOST2}, which may be different platforms.
957 ~ % @kbd{cd /nfs/src}
958 /nfs/src % @kbd{tar zxf ~/amhello-1.0.tar.gz}
961 On the first host, you could create a local build directory:
963 [HOST1] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
964 [HOST1] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure}
966 [HOST1] /tmp/amh % @kbd{make && sudo make install}
971 (Here we assume that the installer has configured @command{sudo} so it
972 can execute @code{make install} with root privileges; it is more convenient
973 than using @command{su} like in @ref{Basic Installation}).
975 On the second host, you would do exactly the same, possibly at
978 [HOST2] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
979 [HOST2] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure}
981 [HOST2] /tmp/amh % @kbd{make && sudo make install}
985 @cindex read-only source tree
986 @cindex source tree, read-only
988 In this scenario, nothing forbids the @file{/nfs/src/amhello-1.0}
989 directory from being read-only. In fact VPATH builds are also a means
990 of building packages from a read-only medium such as a CD-ROM. (The
991 FSF used to sell CD-ROM with unpacked source code, before the GNU
992 project grew so big.)
994 @node Two-Part Install
995 @subsection Two-Part Installation
997 In our last example (@pxref{VPATH Builds}), a source tree was shared
998 by two hosts, but compilation and installation were done separately on
1001 The GNU Build System also supports networked setups where part of the
1002 installed files should be shared amongst multiple hosts. It does so
1003 by distinguishing architecture-dependent files from
1004 architecture-independent files, and providing two @file{Makefile}
1005 targets to install each of these classes of files.
1007 @trindex install-exec
1008 @trindex install-data
1010 These targets are @code{install-exec} for architecture-dependent files
1011 and @code{install-data} for architecture-independent files.
1012 The command we used up to now, @code{make install}, can be thought of
1013 as a shorthand for @code{make install-exec install-data}.
1015 From the GNU Build System point of view, the distinction between
1016 architecture-dependent files and architecture-independent files is
1017 based exclusively on the directory variable used to specify their
1018 installation destination. In the list of directory variables we
1019 provided earlier (@pxref{Standard Directory Variables}), all the
1020 variables based on @var{exec-prefix} designate architecture-dependent
1021 directories whose files will be installed by @code{make install-exec}.
1022 The others designate architecture-independent directories and will
1023 serve files installed by @code{make install-data}. @xref{The Two Parts
1024 of Install}, for more details.
1026 Here is how we could revisit our two-host installation example,
1027 assuming that (1) we want to install the package directly in
1028 @file{/usr}, and (2) the directory @file{/usr/share} is shared by the
1031 On the first host we would run
1033 [HOST1] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
1034 [HOST1] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure --prefix /usr}
1036 [HOST1] /tmp/amh % @kbd{make && sudo make install}
1040 On the second host, however, we need only install the
1041 architecture-specific files.
1043 [HOST2] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
1044 [HOST2] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure --prefix /usr}
1046 [HOST2] /tmp/amh % @kbd{make && sudo make install-exec}
1050 In packages that have installation checks, it would make sense to run
1051 @code{make installcheck} (@pxref{Basic Installation}) to verify that
1052 the package works correctly despite the apparent partial installation.
1054 @node Cross-Compilation
1055 @subsection Cross-Compilation
1056 @cindex cross-compilation
1058 To @dfn{cross-compile} is to build on one platform a binary that will
1059 run on another platform. When speaking of cross-compilation, it is
1060 important to distinguish between the @dfn{build platform} on which
1061 the compilation is performed, and the @dfn{host platform} on which the
1062 resulting executable is expected to run. The following
1063 @command{configure} options are used to specify each of them:
1066 @item --build=@var{build}
1067 @opindex --build=@var{build}
1068 The system on which the package is built.
1069 @item --host=@var{host}
1070 @opindex --host=@var{host}
1071 The system where built programs and libraries will run.
1074 When the @option{--host} is used, @command{configure} will search for
1075 the cross-compiling suite for this platform. Cross-compilation tools
1076 commonly have their target architecture as prefix of their name. For
1077 instance my cross-compiler for MinGW32 has its binaries called
1078 @code{i586-mingw32msvc-gcc}, @code{i586-mingw32msvc-ld},
1079 @code{i586-mingw32msvc-as}, etc.
1081 @cindex MinGW cross-compilation example
1082 @cindex cross-compilation example
1084 Here is how we could build @code{amhello-1.0} for
1085 @code{i586-mingw32msvc} on a GNU/Linux PC.
1087 @c Keep in sync with amhello-cross-compile.test.
1089 ~/amhello-1.0 % @kbd{./configure --build i686-pc-linux-gnu --host i586-mingw32msvc}
1090 checking for a BSD-compatible install... /usr/bin/install -c
1091 checking whether build environment is sane... yes
1092 checking for gawk... gawk
1093 checking whether make sets $(MAKE)... yes
1094 checking for i586-mingw32msvc-strip... i586-mingw32msvc-strip
1095 checking for i586-mingw32msvc-gcc... i586-mingw32msvc-gcc
1096 checking for C compiler default output file name... a.exe
1097 checking whether the C compiler works... yes
1098 checking whether we are cross compiling... yes
1099 checking for suffix of executables... .exe
1100 checking for suffix of object files... o
1101 checking whether we are using the GNU C compiler... yes
1102 checking whether i586-mingw32msvc-gcc accepts -g... yes
1103 checking for i586-mingw32msvc-gcc option to accept ANSI C...
1105 ~/amhello-1.0 % @kbd{make}
1107 ~/amhello-1.0 % @kbd{cd src; file hello.exe}
1108 hello.exe: MS Windows PE 32-bit Intel 80386 console executable not relocatable
1111 The @option{--host} and @option{--build} options are usually all we
1112 need for cross-compiling. The only exception is if the package being
1113 built is itself a cross-compiler: we need a third option to specify
1114 its target architecture.
1117 @item --target=@var{target}
1118 @opindex --target=@var{target}
1119 When building compiler tools: the system for which the tools will
1123 For instance when installing GCC, the GNU Compiler Collection, we can
1124 use @option{--target=@/@var{target}} to specify that we want to build
1125 GCC as a cross-compiler for @var{target}. Mixing @option{--build} and
1126 @option{--target}, we can actually cross-compile a cross-compiler;
1127 such a three-way cross-compilation is known as a @dfn{Canadian cross}.
1129 @xref{Specifying Names, , Specifying the System Type, autoconf, The
1130 Autoconf Manual}, for more information about these @command{configure}
1134 @subsection Renaming Programs at Install Time
1135 @cindex Renaming programs
1136 @cindex Transforming program names
1137 @cindex Programs, renaming during installation
1139 The GNU Build System provides means to automatically rename
1140 executables and manpages before they are installed (@pxref{Man Pages}).
1141 This is especially convenient
1142 when installing a GNU package on a system that already has a
1143 proprietary implementation you do not want to overwrite. For instance,
1144 you may want to install GNU @command{tar} as @command{gtar} so you can
1145 distinguish it from your vendor's @command{tar}.
1147 This can be done using one of these three @command{configure} options.
1150 @item --program-prefix=@var{prefix}
1151 @opindex --program-prefix=@var{prefix}
1152 Prepend @var{prefix} to installed program names.
1153 @item --program-suffix=@var{suffix}
1154 @opindex --program-suffix=@var{suffix}
1155 Append @var{suffix} to installed program names.
1156 @item --program-transform-name=@var{program}
1157 @opindex --program-transform-name=@var{program}
1158 Run @code{sed @var{program}} on installed program names.
1161 The following commands would install @file{hello}
1162 as @file{/usr/local/bin/test-hello}, for instance.
1165 ~/amhello-1.0 % @kbd{./configure --program-prefix test-}
1167 ~/amhello-1.0 % @kbd{make}
1169 ~/amhello-1.0 % @kbd{sudo make install}
1174 @subsection Building Binary Packages Using DESTDIR
1177 The GNU Build System's @code{make install} and @code{make uninstall}
1178 interface does not exactly fit the needs of a system administrator
1179 who has to deploy and upgrade packages on lots of hosts. In other
1180 words, the GNU Build System does not replace a package manager.
1182 Such package managers usually need to know which files have been
1183 installed by a package, so a mere @code{make install} is
1186 @cindex Staged installation
1188 The @code{DESTDIR} variable can be used to perform a staged
1189 installation. The package should be configured as if it was going to
1190 be installed in its final location (e.g., @code{--prefix /usr}), but
1191 when running @code{make install}, the @code{DESTDIR} should be set to
1192 the absolute name of a directory into which the installation will be
1193 diverted. From this directory it is easy to review which files are
1194 being installed where, and finally copy them to their final location
1197 @cindex Binary package
1199 For instance here is how we could create a binary package containing a
1200 snapshot of all the files to be installed.
1202 @c Keep in sync with amhello-binpkg.test.
1204 ~/amhello-1.0 % @kbd{./configure --prefix /usr}
1206 ~/amhello-1.0 % @kbd{make}
1208 ~/amhello-1.0 % @kbd{make DESTDIR=$HOME/inst install}
1210 ~/amhello-1.0 % @kbd{cd ~/inst}
1211 ~/inst % @kbd{find . -type f -print > ../files.lst}
1212 ~/inst % @kbd{tar zcvf ~/amhello-1.0-i686.tar.gz `cat ../files.lst`}
1214 ./usr/share/doc/amhello/README
1217 After this example, @code{amhello-1.0-i686.tar.gz} is ready to be
1218 uncompressed in @file{/} on many hosts. (Using @code{`cat ../files.lst`}
1219 instead of @samp{.} as argument for @command{tar} avoids entries for
1220 each subdirectory in the archive: we would not like @command{tar} to
1221 restore the modification time of @file{/}, @file{/usr/}, etc.)
1223 Note that when building packages for several architectures, it might
1224 be convenient to use @code{make install-data} and @code{make
1225 install-exec} (@pxref{Two-Part Install}) to gather
1226 architecture-independent files in a single package.
1228 @xref{Install}, for more information.
1230 @c We should document PRE_INSTALL/POST_INSTALL/NORMAL_INSTALL and their
1231 @c UNINSTALL counterparts.
1233 @node Preparing Distributions
1234 @subsection Preparing Distributions
1235 @cindex Preparing distributions
1236 @cindex Packages, preparation
1237 @cindex Distributions, preparation
1239 We have already mentioned @code{make dist}. This target collects all
1240 your source files and the necessary parts of the build system to
1241 create a tarball named @file{@var{package}-@var{version}.tar.gz}.
1243 @cindex @code{distcheck} better than @code{dist}
1245 Another, more useful command is @code{make distcheck}. The
1246 @code{distcheck} target constructs
1247 @file{@var{package}-@var{version}.tar.gz} just as well as @code{dist},
1248 but it additionally ensures most of the use cases presented so far
1253 It attempts a full compilation of the package (@pxref{Basic
1254 Installation}), unpacking the newly constructed tarball, running
1255 @code{make}, @code{make check}, @code{make install}, as well as
1256 @code{make installcheck}, and even @code{make dist},
1258 it tests VPATH builds with read-only source tree (@pxref{VPATH Builds}),
1260 it makes sure @code{make clean}, @code{make distclean}, and @code{make
1261 uninstall} do not omit any file (@pxref{Standard Targets}),
1263 and it checks that @code{DESTDIR} installations work (@pxref{DESTDIR}).
1266 All of these actions are performed in a temporary subdirectory, so
1267 that no root privileges are required.
1269 Releasing a package that fails @code{make distcheck} means that one of
1270 the scenarios we presented will not work and some users will be
1271 disappointed. Therefore it is a good practice to release a package
1272 only after a successful @code{make distcheck}. This of course does
1273 not imply that the package will be flawless, but at least it will
1274 prevent some of the embarrassing errors you may find in packages
1275 released by people who have never heard about @code{distcheck} (like
1276 @code{DESTDIR} not working because of a typo, or a distributed file
1277 being erased by @code{make clean}, or even @code{VPATH} builds not
1280 @xref{Creating amhello}, to recreate @file{amhello-1.0.tar.gz} using
1281 @code{make distcheck}. @xref{Checking the Distribution}, for more
1282 information about @code{distcheck}.
1284 @node Dependency Tracking
1285 @subsection Automatic Dependency Tracking
1286 @cindex Dependency tracking
1288 Dependency tracking is performed as a side-effect of compilation.
1289 Each time the build system compiles a source file, it computes its
1290 list of dependencies (in C these are the header files included by the
1291 source being compiled). Later, any time @command{make} is run and a
1292 dependency appears to have changed, the dependent files will be
1295 Automake generates code for automatic dependency tracking by default,
1296 unless the developer chooses to override it; for more information,
1297 @pxref{Dependencies}.
1299 When @command{configure} is executed, you can see it probing each
1300 compiler for the dependency mechanism it supports (several mechanisms
1304 ~/amhello-1.0 % @kbd{./configure --prefix /usr}
1306 checking dependency style of gcc... gcc3
1310 Because dependencies are only computed as a side-effect of the
1311 compilation, no dependency information exists the first time a package
1312 is built. This is OK because all the files need to be built anyway:
1313 @code{make} does not have to decide which files need to be rebuilt.
1314 In fact, dependency tracking is completely useless for one-time builds
1315 and there is a @command{configure} option to disable this:
1318 @item --disable-dependency-tracking
1319 @opindex --disable-dependency-tracking
1320 Speed up one-time builds.
1323 Some compilers do not offer any practical way to derive the list of
1324 dependencies as a side-effect of the compilation, requiring a separate
1325 run (maybe of another tool) to compute these dependencies. The
1326 performance penalty implied by these methods is important enough to
1327 disable them by default. The option @option{--enable-dependency-tracking}
1328 must be passed to @command{configure} to activate them.
1331 @item --enable-dependency-tracking
1332 @opindex --enable-dependency-tracking
1333 Do not reject slow dependency extractors.
1336 @xref{Dependency Tracking Evolution}, for some discussion about the
1337 different dependency tracking schemes used by Automake over the years.
1339 @node Nested Packages
1340 @subsection Nested Packages
1341 @cindex Nested packages
1342 @cindex Packages, nested
1345 Although nesting packages isn't something we would recommend to
1346 someone who is discovering the Autotools, it is a nice feature worthy
1347 of mention in this small advertising tour.
1349 Autoconfiscated packages (that means packages whose build system have
1350 been created by Autoconf and friends) can be nested to arbitrary
1353 A typical setup is that package A will distribute one of the libraries
1354 it needs in a subdirectory. This library B is a complete package with
1355 its own GNU Build System. The @command{configure} script of A will
1356 run the @command{configure} script of B as part of its execution,
1357 building and installing A will also build and install B. Generating a
1358 distribution for A will also include B.
1360 It is possible to gather several packages like this. GCC is a heavy
1361 user of this feature. This gives installers a single package to
1362 configure, build and install, while it allows developers to work on
1363 subpackages independently.
1365 When configuring nested packages, the @command{configure} options
1366 given to the top-level @command{configure} are passed recursively to
1367 nested @command{configure}s. A package that does not understand an
1368 option will ignore it, assuming it is meaningful to some other
1371 @opindex --help=recursive
1373 The command @code{configure --help=recursive} can be used to display
1374 the options supported by all the included packages.
1376 @xref{Subpackages}, for an example setup.
1379 @section How Autotools Help
1380 @cindex Autotools, purpose
1382 There are several reasons why you may not want to implement the GNU
1383 Build System yourself (read: write a @file{configure} script and
1384 @file{Makefile}s yourself).
1388 As we have seen, the GNU Build System has a lot of
1389 features (@pxref{Use Cases}).
1390 Some users may expect features you have not implemented because
1391 you did not need them.
1393 Implementing these features portably is difficult and exhausting.
1394 Think of writing portable shell scripts, and portable
1395 @file{Makefile}s, for systems you may not have handy. @xref{Portable
1396 Shell, , Portable Shell Programming, autoconf, The Autoconf Manual}, to
1399 You will have to upgrade your setup to follow changes to the GNU
1403 The GNU Autotools take all this burden off your back and provide:
1407 Tools to create a portable, complete, and self-contained GNU Build
1408 System, from simple instructions.
1409 @emph{Self-contained} meaning the resulting build system does not
1410 require the GNU Autotools.
1412 A central place where fixes and improvements are made:
1413 a bug-fix for a portability issue will benefit every package.
1416 Yet there also exist reasons why you may want NOT to use the
1417 Autotools@enddots{} For instance you may be already using (or used to)
1418 another incompatible build system. Autotools will only be useful if
1419 you do accept the concepts of the GNU Build System. People who have their
1420 own idea of how a build system should work will feel frustrated by the
1424 @section A Small Hello World
1425 @cindex Example Hello World
1426 @cindex Hello World example
1427 @cindex @file{amhello-1.0.tar.gz}, creation
1429 In this section we recreate the @file{amhello-1.0} package from
1430 scratch. The first subsection shows how to call the Autotools to
1431 instantiate the GNU Build System, while the second explains the
1432 meaning of the @file{configure.ac} and @file{Makefile.am} files read
1435 @anchor{amhello Explained}
1437 * Creating amhello:: Create @file{amhello-1.0.tar.gz} from scratch
1438 * amhello's configure.ac Setup Explained::
1439 * amhello's Makefile.am Setup Explained::
1442 @node Creating amhello
1443 @subsection Creating @file{amhello-1.0.tar.gz}
1445 Here is how we can recreate @file{amhello-1.0.tar.gz} from scratch.
1446 The package is simple enough so that we will only need to write 5
1447 files. (You may copy them from the final @file{amhello-1.0.tar.gz}
1448 that is distributed with Automake if you do not want to write them.)
1450 Create the following files in an empty directory.
1455 @file{src/main.c} is the source file for the @file{hello} program. We
1456 store it in the @file{src/} subdirectory, because later, when the package
1457 evolves, it will ease the addition of a @file{man/} directory for man
1458 pages, a @file{data/} directory for data files, etc.
1460 ~/amhello % @kbd{cat src/main.c}
1467 puts ("Hello World!");
1468 puts ("This is " PACKAGE_STRING ".");
1474 @file{README} contains some very limited documentation for our little
1477 ~/amhello % @kbd{cat README}
1478 This is a demonstration package for GNU Automake.
1479 Type `info Automake' to read the Automake manual.
1483 @file{Makefile.am} and @file{src/Makefile.am} contain Automake
1484 instructions for these two directories.
1487 ~/amhello % @kbd{cat src/Makefile.am}
1488 bin_PROGRAMS = hello
1489 hello_SOURCES = main.c
1490 ~/amhello % @kbd{cat Makefile.am}
1492 dist_doc_DATA = README
1496 Finally, @file{configure.ac} contains Autoconf instructions to
1497 create the @command{configure} script.
1500 ~/amhello % @kbd{cat configure.ac}
1501 AC_INIT([amhello], [1.0], [@value{PACKAGE_BUGREPORT}])
1502 AM_INIT_AUTOMAKE([-Wall -Werror foreign])
1504 AC_CONFIG_HEADERS([config.h])
1513 @cindex @command{autoreconf}, example
1515 Once you have these five files, it is time to run the Autotools to
1516 instantiate the build system. Do this using the @command{autoreconf}
1520 ~/amhello % @kbd{autoreconf --install}
1521 configure.ac: installing `./install-sh'
1522 configure.ac: installing `./missing'
1523 src/Makefile.am: installing `./depcomp'
1526 At this point the build system is complete.
1528 In addition to the three scripts mentioned in its output, you can see
1529 that @command{autoreconf} created four other files: @file{configure},
1530 @file{config.h.in}, @file{Makefile.in}, and @file{src/Makefile.in}.
1531 The latter three files are templates that will be adapted to the
1532 system by @command{configure} under the names @file{config.h},
1533 @file{Makefile}, and @file{src/Makefile}. Let's do this:
1536 ~/amhello % @kbd{./configure}
1537 checking for a BSD-compatible install... /usr/bin/install -c
1538 checking whether build environment is sane... yes
1539 checking for gawk... no
1540 checking for mawk... mawk
1541 checking whether make sets $(MAKE)... yes
1542 checking for gcc... gcc
1543 checking for C compiler default output file name... a.out
1544 checking whether the C compiler works... yes
1545 checking whether we are cross compiling... no
1546 checking for suffix of executables...
1547 checking for suffix of object files... o
1548 checking whether we are using the GNU C compiler... yes
1549 checking whether gcc accepts -g... yes
1550 checking for gcc option to accept ISO C89... none needed
1551 checking for style of include used by make... GNU
1552 checking dependency style of gcc... gcc3
1553 configure: creating ./config.status
1554 config.status: creating Makefile
1555 config.status: creating src/Makefile
1556 config.status: creating config.h
1557 config.status: executing depfiles commands
1561 @cindex @code{distcheck} example
1563 You can see @file{Makefile}, @file{src/Makefile}, and @file{config.h}
1564 being created at the end after @command{configure} has probed the
1565 system. It is now possible to run all the targets we wish
1566 (@pxref{Standard Targets}). For instance:
1569 ~/amhello % @kbd{make}
1571 ~/amhello % @kbd{src/hello}
1573 This is amhello 1.0.
1574 ~/amhello % @kbd{make distcheck}
1576 =============================================
1577 amhello-1.0 archives ready for distribution:
1579 =============================================
1582 Note that running @command{autoreconf} is only needed initially when
1583 the GNU Build System does not exist. When you later change some
1584 instructions in a @file{Makefile.am} or @file{configure.ac}, the
1585 relevant part of the build system will be regenerated automatically
1586 when you execute @command{make}.
1588 @command{autoreconf} is a script that calls @command{autoconf},
1589 @command{automake}, and a bunch of other commands in the right order.
1590 If you are beginning with these tools, it is not important to figure
1591 out in which order all these tools should be invoked and why. However,
1592 because Autoconf and Automake have separate manuals, the important
1593 point to understand is that @command{autoconf} is in charge of
1594 creating @file{configure} from @file{configure.ac}, while
1595 @command{automake} is in charge of creating @file{Makefile.in}s from
1596 @file{Makefile.am}s and @file{configure.ac}. This should at least
1597 direct you to the right manual when seeking answers.
1600 @node amhello's configure.ac Setup Explained
1601 @subsection @code{amhello}'s @file{configure.ac} Setup Explained
1603 @cindex @file{configure.ac}, Hello World
1605 Let us begin with the contents of @file{configure.ac}.
1608 AC_INIT([amhello], [1.0], [@value{PACKAGE_BUGREPORT}])
1609 AM_INIT_AUTOMAKE([-Wall -Werror foreign])
1611 AC_CONFIG_HEADERS([config.h])
1619 This file is read by both @command{autoconf} (to create
1620 @file{configure}) and @command{automake} (to create the various
1621 @file{Makefile.in}s). It contains a series of M4 macros that will be
1622 expanded as shell code to finally form the @file{configure} script.
1623 We will not elaborate on the syntax of this file, because the Autoconf
1624 manual has a whole section about it (@pxref{Writing Autoconf Input, ,
1625 Writing @file{configure.ac}, autoconf, The Autoconf Manual}).
1627 The macros prefixed with @code{AC_} are Autoconf macros, documented
1628 in the Autoconf manual (@pxref{Autoconf Macro Index, , Autoconf Macro
1629 Index, autoconf, The Autoconf Manual}). The macros that start with
1630 @code{AM_} are Automake macros, documented later in this manual
1631 (@pxref{Macro Index}).
1633 The first two lines of @file{configure.ac} initialize Autoconf and
1634 Automake. @code{AC_INIT} takes in as parameters the name of the package,
1635 its version number, and a contact address for bug-reports about the
1636 package (this address is output at the end of @code{./configure
1637 --help}, for instance). When adapting this setup to your own package,
1638 by all means please do not blindly copy Automake's address: use the
1639 mailing list of your package, or your own mail address.
1645 The argument to @code{AM_INIT_AUTOMAKE} is a list of options for
1646 @command{automake} (@pxref{Options}). @option{-Wall} and
1647 @option{-Werror} ask @command{automake} to turn on all warnings and
1648 report them as errors. We are speaking of @strong{Automake} warnings
1649 here, such as dubious instructions in @file{Makefile.am}. This has
1650 absolutely nothing to do with how the compiler will be called, even
1651 though it may support options with similar names. Using @option{-Wall
1652 -Werror} is a safe setting when starting to work on a package: you do
1653 not want to miss any issues. Later you may decide to relax things a
1654 bit. The @option{foreign} option tells Automake that this package
1655 will not follow the GNU Standards. GNU packages should always
1656 distribute additional files such as @file{ChangeLog}, @file{AUTHORS},
1657 etc. We do not want @command{automake} to complain about these
1658 missing files in our small example.
1660 The @code{AC_PROG_CC} line causes the @command{configure} script to
1661 search for a C compiler and define the variable @code{CC} with its
1662 name. The @file{src/Makefile.in} file generated by Automake uses the
1663 variable @code{CC} to build @file{hello}, so when @command{configure}
1664 creates @file{src/Makefile} from @file{src/Makefile.in}, it will define
1665 @code{CC} with the value it has found. If Automake is asked to create
1666 a @file{Makefile.in} that uses @code{CC} but @file{configure.ac} does
1667 not define it, it will suggest you add a call to @code{AC_PROG_CC}.
1669 The @code{AC_CONFIG_HEADERS([config.h])} invocation causes the
1670 @command{configure} script to create a @file{config.h} file gathering
1671 @samp{#define}s defined by other macros in @file{configure.ac}. In our
1672 case, the @code{AC_INIT} macro already defined a few of them. Here
1673 is an excerpt of @file{config.h} after @command{configure} has run:
1677 /* Define to the address where bug reports for this package should be sent. */
1678 #define PACKAGE_BUGREPORT "@value{PACKAGE_BUGREPORT}"
1680 /* Define to the full name and version of this package. */
1681 #define PACKAGE_STRING "amhello 1.0"
1685 As you probably noticed, @file{src/main.c} includes @file{config.h} so
1686 it can use @code{PACKAGE_STRING}. In a real-world project,
1687 @file{config.h} can grow really big, with one @samp{#define} per
1688 feature probed on the system.
1690 The @code{AC_CONFIG_FILES} macro declares the list of files that
1691 @command{configure} should create from their @file{*.in} templates.
1692 Automake also scans this list to find the @file{Makefile.am} files it must
1693 process. (This is important to remember: when adding a new directory
1694 to your project, you should add its @file{Makefile} to this list,
1695 otherwise Automake will never process the new @file{Makefile.am} you
1696 wrote in that directory.)
1698 Finally, the @code{AC_OUTPUT} line is a closing command that actually
1699 produces the part of the script in charge of creating the files
1700 registered with @code{AC_CONFIG_HEADERS} and @code{AC_CONFIG_FILES}.
1702 @cindex @command{autoscan}
1704 When starting a new project, we suggest you start with such a simple
1705 @file{configure.ac}, and gradually add the other tests it requires.
1706 The command @command{autoscan} can also suggest a few of the tests
1707 your package may need (@pxref{autoscan Invocation, , Using
1708 @command{autoscan} to Create @file{configure.ac}, autoconf, The
1712 @node amhello's Makefile.am Setup Explained
1713 @subsection @code{amhello}'s @file{Makefile.am} Setup Explained
1715 @cindex @file{Makefile.am}, Hello World
1717 We now turn to @file{src/Makefile.am}. This file contains
1718 Automake instructions to build and install @file{hello}.
1721 bin_PROGRAMS = hello
1722 hello_SOURCES = main.c
1725 A @file{Makefile.am} has the same syntax as an ordinary
1726 @file{Makefile}. When @command{automake} processes a
1727 @file{Makefile.am} it copies the entire file into the output
1728 @file{Makefile.in} (that will be later turned into @file{Makefile} by
1729 @command{configure}) but will react to certain variable definitions
1730 by generating some build rules and other variables.
1731 Often @file{Makefile.am}s contain only a list of variable definitions as
1732 above, but they can also contain other variable and rule definitions that
1733 @command{automake} will pass along without interpretation.
1735 Variables that end with @code{_PROGRAMS} are special variables
1736 that list programs that the resulting @file{Makefile} should build.
1737 In Automake speak, this @code{_PROGRAMS} suffix is called a
1738 @dfn{primary}; Automake recognizes other primaries such as
1739 @code{_SCRIPTS}, @code{_DATA}, @code{_LIBRARIES}, etc.@: corresponding
1740 to different types of files.
1742 The @samp{bin} part of the @code{bin_PROGRAMS} tells
1743 @command{automake} that the resulting programs should be installed in
1744 @var{bindir}. Recall that the GNU Build System uses a set of variables
1745 to denote destination directories and allow users to customize these
1746 locations (@pxref{Standard Directory Variables}). Any such directory
1747 variable can be put in front of a primary (omitting the @code{dir}
1748 suffix) to tell @command{automake} where to install the listed files.
1750 Programs need to be built from source files, so for each program
1751 @code{@var{prog}} listed in a @code{@w{_PROGRAMS}} variable,
1752 @command{automake} will look for another variable named
1753 @code{@var{prog}_SOURCES} listing its source files. There may be more
1754 than one source file: they will all be compiled and linked together.
1756 Automake also knows that source files need to be distributed when
1757 creating a tarball (unlike built programs). So a side-effect of this
1758 @code{hello_SOURCES} declaration is that @file{main.c} will be
1759 part of the tarball created by @code{make dist}.
1761 Finally here are some explanations regarding the top-level
1766 dist_doc_DATA = README
1769 @code{SUBDIRS} is a special variable listing all directories that
1770 @command{make} should recurse into before processing the current
1771 directory. So this line is responsible for @command{make} building
1772 @file{src/hello} even though we run it from the top-level. This line
1773 also causes @code{make install} to install @file{src/hello} before
1774 installing @file{README} (not that this order matters).
1776 The line @code{dist_doc_DATA = README} causes @file{README} to be
1777 distributed and installed in @var{docdir}. Files listed with the
1778 @code{_DATA} primary are not automatically part of the tarball built
1779 with @code{make dist}, so we add the @code{dist_} prefix so they get
1780 distributed. However, for @file{README} it would not have been
1781 necessary: @command{automake} automatically distributes any
1782 @file{README} file it encounters (the list of other files
1783 automatically distributed is presented by @code{automake --help}).
1784 The only important effect of this second line is therefore to install
1785 @file{README} during @code{make install}.
1787 One thing not covered in this example is accessing the installation
1788 directory values (@pxref{Standard Directory Variables}) from your
1789 program code, that is, converting them into defined macros. For this,
1790 @pxref{Defining Directories,,, autoconf, The Autoconf Manual}.
1794 @chapter General ideas
1796 The following sections cover a few basic ideas that will help you
1797 understand how Automake works.
1800 * General Operation:: General operation of Automake
1801 * Strictness:: Standards conformance checking
1802 * Uniform:: The Uniform Naming Scheme
1803 * Length Limitations:: Staying below the command line length limit
1804 * Canonicalization:: How derived variables are named
1805 * User Variables:: Variables reserved for the user
1806 * Auxiliary Programs:: Programs automake might require
1810 @node General Operation
1811 @section General Operation
1813 Automake works by reading a @file{Makefile.am} and generating a
1814 @file{Makefile.in}. Certain variables and rules defined in the
1815 @file{Makefile.am} instruct Automake to generate more specialized code;
1816 for instance, a @code{bin_PROGRAMS} variable definition will cause rules
1817 for compiling and linking programs to be generated.
1819 @cindex Non-standard targets
1820 @cindex @code{git-dist}, non-standard example
1823 The variable definitions and rules in the @file{Makefile.am} are
1824 copied mostly verbatim into the generated file, with all variable
1825 definitions preceding all rules. This allows you to add almost
1826 arbitrary code into the generated @file{Makefile.in}. For instance,
1827 the Automake distribution includes a non-standard rule for the
1828 @code{git-dist} target, which the Automake maintainer uses to make
1829 distributions from the source control system.
1831 @cindex GNU make extensions
1833 Note that most GNU make extensions are not recognized by Automake. Using
1834 such extensions in a @file{Makefile.am} will lead to errors or confusing
1837 @cindex Append operator
1839 A special exception is that the GNU make append operator, @samp{+=}, is
1840 supported. This operator appends its right hand argument to the variable
1841 specified on the left. Automake will translate the operator into
1842 an ordinary @samp{=} operator; @samp{+=} will thus work with any make program.
1844 Automake tries to keep comments grouped with any adjoining rules or
1845 variable definitions.
1847 @cindex Limitations of automake parser
1848 @cindex Automake parser, limitations of
1849 @cindex indentation in Makefile.am
1850 Generally, Automake is not particularly smart in the parsing of unusual
1851 Makefile constructs, so you're advised to avoid fancy constructs or
1852 ``creative'' use of whitespaces.
1853 @c Keep this in sync with doc-parsing-buglets-tabs.test.
1854 For example, @key{TAB} characters cannot be used between a target name
1855 and the following ``@code{:}'' character, and variable assignments
1856 shouldn't be indented with @key{TAB} characters.
1857 @c Keep this in sync with doc-parsing-buglets-colneq-subst.test.
1858 Also, using more complex macro in target names can cause trouble:
1861 % @kbd{cat Makefile.am}
1864 Makefile.am:1: bad characters in variable name `$(FOO'
1865 Makefile.am:1: `:='-style assignments are not portable
1868 @cindex Make targets, overriding
1869 @cindex Make rules, overriding
1870 @cindex Overriding make rules
1871 @cindex Overriding make targets
1873 A rule defined in @file{Makefile.am} generally overrides any such
1874 rule of a similar name that would be automatically generated by
1875 @command{automake}. Although this is a supported feature, it is generally
1876 best to avoid making use of it, as sometimes the generated rules are
1879 @cindex Variables, overriding
1880 @cindex Overriding make variables
1882 Similarly, a variable defined in @file{Makefile.am} or
1883 @code{AC_SUBST}ed from @file{configure.ac} will override any
1884 definition of the variable that @command{automake} would ordinarily
1885 create. This feature is more often useful than the ability to
1886 override a rule. Be warned that many of the variables generated by
1887 @command{automake} are considered to be for internal use only, and their
1888 names might change in future releases.
1890 @cindex Recursive operation of Automake
1891 @cindex Automake, recursive operation
1892 @cindex Example of recursive operation
1894 When examining a variable definition, Automake will recursively examine
1895 variables referenced in the definition. For example, if Automake is
1896 looking at the content of @code{foo_SOURCES} in this snippet
1898 @c Keep in sync with interp.test.
1901 foo_SOURCES = c.c $(xs)
1904 it would use the files @file{a.c}, @file{b.c}, and @file{c.c} as the
1905 contents of @code{foo_SOURCES}.
1907 @cindex @code{##} (special Automake comment)
1908 @cindex Special Automake comment
1909 @cindex Comment, special to Automake
1911 Automake also allows a form of comment that is @emph{not} copied into
1912 the output; all lines beginning with @samp{##} (leading spaces allowed)
1913 are completely ignored by Automake.
1915 It is customary to make the first line of @file{Makefile.am} read:
1917 @cindex Makefile.am, first line
1918 @cindex First line of Makefile.am
1921 ## Process this file with automake to produce Makefile.in
1924 @c FIXME discuss putting a copyright into Makefile.am here? I would but
1925 @c I don't know quite what to say.
1927 @c FIXME document customary ordering of Makefile.am here!
1933 @cindex Non-GNU packages
1935 While Automake is intended to be used by maintainers of GNU packages, it
1936 does make some effort to accommodate those who wish to use it, but do
1937 not want to use all the GNU conventions.
1939 @cindex Strictness, defined
1940 @cindex Strictness, @option{foreign}
1941 @cindex @option{foreign} strictness
1942 @cindex Strictness, @option{gnu}
1943 @cindex @option{gnu} strictness
1944 @cindex Strictness, @option{gnits}
1945 @cindex @option{gnits} strictness
1947 To this end, Automake supports three levels of @dfn{strictness}---the
1948 strictness indicating how stringently Automake should check standards
1951 The valid strictness levels are:
1955 Automake will check for only those things that are absolutely
1956 required for proper operations. For instance, whereas GNU standards
1957 dictate the existence of a @file{NEWS} file, it will not be required in
1958 this mode. This strictness will also turn off some warnings by default
1959 (among them, portability warnings).
1960 The name comes from the fact that Automake is intended to be
1961 used for GNU programs; these relaxed rules are not the standard mode of
1965 Automake will check---as much as possible---for compliance to the GNU
1966 standards for packages. This is the default.
1969 Automake will check for compliance to the as-yet-unwritten @dfn{Gnits
1970 standards}. These are based on the GNU standards, but are even more
1971 detailed. Unless you are a Gnits standards contributor, it is
1972 recommended that you avoid this option until such time as the Gnits
1973 standard is actually published (which may never happen).
1976 @xref{Gnits}, for more information on the precise implications of the
1979 Automake also has a special ``cygnus'' mode that is similar to
1980 strictness but handled differently. This mode is useful for packages
1981 that are put into a ``Cygnus'' style tree (e.g., the GCC tree).
1982 @xref{Cygnus}, for more information on this mode.
1986 @section The Uniform Naming Scheme
1988 @cindex Uniform naming scheme
1990 Automake variables generally follow a @dfn{uniform naming scheme} that
1991 makes it easy to decide how programs (and other derived objects) are
1992 built, and how they are installed. This scheme also supports
1993 @command{configure} time determination of what should be built.
1995 @cindex @code{_PROGRAMS} primary variable
1996 @cindex @code{PROGRAMS} primary variable
1997 @cindex Primary variable, @code{PROGRAMS}
1998 @cindex Primary variable, defined
2001 At @command{make} time, certain variables are used to determine which
2002 objects are to be built. The variable names are made of several pieces
2003 that are concatenated together.
2005 The piece that tells @command{automake} what is being built is commonly called
2006 the @dfn{primary}. For instance, the primary @code{PROGRAMS} holds a
2007 list of programs that are to be compiled and linked.
2010 @cindex @code{pkgdatadir}, defined
2011 @cindex @code{pkgincludedir}, defined
2012 @cindex @code{pkglibdir}, defined
2013 @cindex @code{pkglibexecdir}, defined
2016 @vindex pkgincludedir
2018 @vindex pkglibexecdir
2020 @cindex @code{PACKAGE}, directory
2021 A different set of names is used to decide where the built objects
2022 should be installed. These names are prefixes to the primary, and they
2023 indicate which standard directory should be used as the installation
2024 directory. The standard directory names are given in the GNU standards
2025 (@pxref{Directory Variables, , , standards, The GNU Coding Standards}).
2026 Automake extends this list with @code{pkgdatadir}, @code{pkgincludedir},
2027 @code{pkglibdir}, and @code{pkglibexecdir}; these are the same as the
2028 non-@samp{pkg} versions, but with @samp{$(PACKAGE)} appended. For instance,
2029 @code{pkglibdir} is defined as @samp{$(libdir)/$(PACKAGE)}.
2031 @cindex @code{EXTRA_}, prepending
2032 For each primary, there is one additional variable named by prepending
2033 @samp{EXTRA_} to the primary name. This variable is used to list
2034 objects that may or may not be built, depending on what
2035 @command{configure} decides. This variable is required because Automake
2036 must statically know the entire list of objects that may be built in
2037 order to generate a @file{Makefile.in} that will work in all cases.
2039 @cindex @code{EXTRA_PROGRAMS}, defined
2040 @cindex Example, @code{EXTRA_PROGRAMS}
2041 @cindex @command{cpio} example
2043 For instance, @command{cpio} decides at configure time which programs
2044 should be built. Some of the programs are installed in @code{bindir},
2045 and some are installed in @code{sbindir}:
2048 EXTRA_PROGRAMS = mt rmt
2049 bin_PROGRAMS = cpio pax
2050 sbin_PROGRAMS = $(MORE_PROGRAMS)
2053 Defining a primary without a prefix as a variable, e.g.,
2054 @samp{PROGRAMS}, is an error.
2056 Note that the common @samp{dir} suffix is left off when constructing the
2057 variable names; thus one writes @samp{bin_PROGRAMS} and not
2058 @samp{bindir_PROGRAMS}.
2060 Not every sort of object can be installed in every directory. Automake
2061 will flag those attempts it finds in error (but see below how to override
2062 the check if you really need to).
2063 Automake will also diagnose obvious misspellings in directory names.
2065 @cindex Extending list of installation directories
2066 @cindex Installation directories, extending list
2068 Sometimes the standard directories---even as augmented by
2069 Automake---are not enough. In particular it is sometimes useful, for
2070 clarity, to install objects in a subdirectory of some predefined
2071 directory. To this end, Automake allows you to extend the list of
2072 possible installation directories. A given prefix (e.g., @samp{zar})
2073 is valid if a variable of the same name with @samp{dir} appended is
2074 defined (e.g., @samp{zardir}).
2076 For instance, the following snippet will install @file{file.xml} into
2077 @samp{$(datadir)/xml}.
2079 @c Keep in sync with primary-prefix-couples-documented-valid.test.
2081 xmldir = $(datadir)/xml
2085 This feature can also be used to override the sanity checks Automake
2086 performs to diagnose suspicious directory/primary couples (in the
2087 unlikely case these checks are undesirable, and you really know what
2088 you're doing). For example, Automake would error out on this input:
2090 @c Should be tested in primary-prefix-invalid-couples.test.
2092 # Forbidden directory combinations, automake will error out on this.
2093 pkglib_PROGRAMS = foo
2094 doc_LIBRARIES = libquux.a
2098 but it will succeed with this:
2100 @c Keep in sync with primary-prefix-couples-documented-valid.test.
2102 # Work around forbidden directory combinations. Do not use this
2103 # without a very good reason!
2104 my_execbindir = $(pkglibdir)
2105 my_doclibdir = $(docdir)
2106 my_execbin_PROGRAMS = foo
2107 my_doclib_LIBRARIES = libquux.a
2110 The @samp{exec} substring of the @samp{my_execbindir} variable lets
2111 the files be installed at the right time (@pxref{The Two Parts of
2114 @cindex @samp{noinst_} primary prefix, definition
2117 The special prefix @samp{noinst_} indicates that the objects in question
2118 should be built but not installed at all. This is usually used for
2119 objects required to build the rest of your package, for instance static
2120 libraries (@pxref{A Library}), or helper scripts.
2122 @cindex @samp{check_} primary prefix, definition
2125 The special prefix @samp{check_} indicates that the objects in question
2126 should not be built until the @samp{make check} command is run. Those
2127 objects are not installed either.
2129 The current primary names are @samp{PROGRAMS}, @samp{LIBRARIES},
2130 @samp{LTLIBRARIES}, @samp{LISP}, @samp{PYTHON}, @samp{JAVA},
2131 @samp{SCRIPTS}, @samp{DATA}, @samp{HEADERS}, @samp{MANS}, and
2145 Some primaries also allow additional prefixes that control other
2146 aspects of @command{automake}'s behavior. The currently defined prefixes
2147 are @samp{dist_}, @samp{nodist_}, @samp{nobase_}, and @samp{notrans_}.
2148 These prefixes are explained later (@pxref{Program and Library Variables})
2149 (@pxref{Man Pages}).
2152 @node Length Limitations
2153 @section Staying below the command line length limit
2155 @cindex command line length limit
2158 Traditionally, most unix-like systems have a length limitation for the
2159 command line arguments and environment contents when creating new
2160 processes (see for example
2161 @uref{http://www.in-ulm.de/@/~mascheck/@/various/@/argmax/} for an
2162 overview on this issue),
2163 which of course also applies to commands spawned by @command{make}.
2164 POSIX requires this limit to be at least 4096 bytes, and most modern
2165 systems have quite high limits (or are unlimited).
2167 In order to create portable Makefiles that do not trip over these
2168 limits, it is necessary to keep the length of file lists bounded.
2169 Unfortunately, it is not possible to do so fully transparently within
2170 Automake, so your help may be needed. Typically, you can split long
2171 file lists manually and use different installation directory names for
2172 each list. For example,
2175 data_DATA = file1 @dots{} file@var{N} file@var{N+1} @dots{} file@var{2N}
2179 may also be written as
2181 @c Keep in sync with primary-prefix-couples-documented-valid.test.
2183 data_DATA = file1 @dots{} file@var{N}
2184 data2dir = $(datadir)
2185 data2_DATA = file@var{N+1} @dots{} file@var{2N}
2189 and will cause Automake to treat the two lists separately during
2190 @code{make install}. See @ref{The Two Parts of Install} for choosing
2191 directory names that will keep the ordering of the two parts of
2192 installation Note that @code{make dist} may still only work on a host
2193 with a higher length limit in this example.
2195 Automake itself employs a couple of strategies to avoid long command
2196 lines. For example, when @samp{$@{srcdir@}/} is prepended to file
2197 names, as can happen with above @code{$(data_DATA)} lists, it limits
2198 the amount of arguments passed to external commands.
2200 Unfortunately, some system's @command{make} commands may prepend
2201 @code{VPATH} prefixes like @samp{$@{srcdir@}/} to file names from the
2202 source tree automatically (@pxref{Automatic Rule Rewriting, , Automatic
2203 Rule Rewriting, autoconf, The Autoconf Manual}). In this case, the user
2204 may have to switch to use GNU Make, or refrain from using VPATH builds,
2205 in order to stay below the length limit.
2207 For libraries and programs built from many sources, convenience archives
2208 may be used as intermediates in order to limit the object list length
2209 (@pxref{Libtool Convenience Libraries}).
2212 @node Canonicalization
2213 @section How derived variables are named
2215 @cindex canonicalizing Automake variables
2217 Sometimes a Makefile variable name is derived from some text the
2218 maintainer supplies. For instance, a program name listed in
2219 @samp{_PROGRAMS} is rewritten into the name of a @samp{_SOURCES}
2220 variable. In cases like this, Automake canonicalizes the text, so that
2221 program names and the like do not have to follow Makefile variable naming
2222 rules. All characters in the name except for letters, numbers, the
2223 strudel (@@), and the underscore are turned into underscores when making
2224 variable references.
2226 For example, if your program is named @file{sniff-glue}, the derived
2227 variable name would be @samp{sniff_glue_SOURCES}, not
2228 @samp{sniff-glue_SOURCES}. Similarly the sources for a library named
2229 @file{libmumble++.a} should be listed in the
2230 @samp{libmumble___a_SOURCES} variable.
2232 The strudel is an addition, to make the use of Autoconf substitutions in
2233 variable names less obfuscating.
2236 @node User Variables
2237 @section Variables reserved for the user
2239 @cindex variables, reserved for the user
2240 @cindex user variables
2242 Some @file{Makefile} variables are reserved by the GNU Coding Standards
2243 for the use of the ``user''---the person building the package. For
2244 instance, @code{CFLAGS} is one such variable.
2246 Sometimes package developers are tempted to set user variables such as
2247 @code{CFLAGS} because it appears to make their job easier. However,
2248 the package itself should never set a user variable, particularly not
2249 to include switches that are required for proper compilation of the
2250 package. Since these variables are documented as being for the
2251 package builder, that person rightfully expects to be able to override
2252 any of these variables at build time.
2254 To get around this problem, Automake introduces an automake-specific
2255 shadow variable for each user flag variable. (Shadow variables are
2256 not introduced for variables like @code{CC}, where they would make no
2257 sense.) The shadow variable is named by prepending @samp{AM_} to the
2258 user variable's name. For instance, the shadow variable for
2259 @code{YFLAGS} is @code{AM_YFLAGS}. The package maintainer---that is,
2260 the author(s) of the @file{Makefile.am} and @file{configure.ac}
2261 files---may adjust these shadow variables however necessary.
2263 @xref{Flag Variables Ordering}, for more discussion about these
2264 variables and how they interact with per-target variables.
2266 @node Auxiliary Programs
2267 @section Programs automake might require
2269 @cindex Programs, auxiliary
2270 @cindex Auxiliary programs
2272 Automake sometimes requires helper programs so that the generated
2273 @file{Makefile} can do its work properly. There are a fairly large
2274 number of them, and we list them here.
2276 Although all of these files are distributed and installed with
2277 Automake, a couple of them are maintained separately. The Automake
2278 copies are updated before each release, but we mention the original
2279 source in case you need more recent versions.
2283 This is a wrapper primarily for the Microsoft lib archiver, to make
2287 This is a wrapper for compilers that do not accept options @option{-c}
2288 and @option{-o} at the same time. It is only used when absolutely
2289 required. Such compilers are rare, with the Microsoft C/C++ Compiler
2290 as the most notable exception. This wrapper also makes the following
2291 common options available for that compiler, while performing file name
2292 translation where needed: @option{-I}, @option{-L}, @option{-l},
2293 @option{-Wl,} and @option{-Xlinker}.
2297 These two programs compute the canonical triplets for the given build,
2298 host, or target architecture. These programs are updated regularly to
2299 support new architectures and fix probes broken by changes in new
2300 kernel versions. Each new release of Automake comes with up-to-date
2301 copies of these programs. If your copy of Automake is getting old,
2302 you are encouraged to fetch the latest versions of these files from
2303 @url{http://savannah.gnu.org/git/?group=config} before making a
2307 This file is not a program, it is a @file{configure} fragment used for
2308 multilib support (@pxref{Multilibs}). This file is maintained in the
2309 GCC tree at @url{http://gcc.gnu.org/svn.html}.
2312 This program understands how to run a compiler so that it will
2313 generate not only the desired output but also dependency information
2314 that is then used by the automatic dependency tracking feature
2315 (@pxref{Dependencies}).
2318 This program is used to byte-compile Emacs Lisp code.
2321 This is a replacement for the @command{install} program that works on
2322 platforms where @command{install} is unavailable or unusable.
2325 This script is used to generate a @file{version.texi} file. It examines
2326 a file and prints some date information about it.
2329 This wraps a number of programs that are typically only required by
2330 maintainers. If the program in question doesn't exist,
2331 @command{missing} prints an informative warning and attempts to fix
2332 things so that the build can continue.
2335 This script used to be a wrapper around @samp{mkdir -p}, which is not
2336 portable. Now we prefer to use @samp{install-sh -d} when @command{configure}
2337 finds that @samp{mkdir -p} does not work, this makes one less script to
2340 For backward compatibility @file{mkinstalldirs} is still used and
2341 distributed when @command{automake} finds it in a package. But it is no
2342 longer installed automatically, and it should be safe to remove it.
2345 This is used to byte-compile Python scripts.
2348 This program duplicates a tree of directories, using symbolic links
2349 instead of copying files. Such an operation is performed when building
2350 multilibs (@pxref{Multilibs}). This file is maintained in the GCC
2351 tree at @url{http://gcc.gnu.org/svn.html}.
2354 This implements the default test driver offered by the parallel
2358 Not a program, this file is required for @samp{make dvi}, @samp{make
2359 ps} and @samp{make pdf} to work when Texinfo sources are in the
2360 package. The latest version can be downloaded from
2361 @url{http://www.gnu.org/software/texinfo/}.
2364 This program wraps @command{lex} and @command{yacc} to rename their
2365 output files. It also ensures that, for instance, multiple
2366 @command{yacc} instances can be invoked in a single directory in
2373 @chapter Some example packages
2375 This section contains two small examples.
2377 The first example (@pxref{Complete}) assumes you have an existing
2378 project already using Autoconf, with handcrafted @file{Makefile}s, and
2379 that you want to convert it to using Automake. If you are discovering
2380 both tools, it is probably better that you look at the Hello World
2381 example presented earlier (@pxref{Hello World}).
2383 The second example (@pxref{true}) shows how two programs can be built
2384 from the same file, using different compilation parameters. It
2385 contains some technical digressions that are probably best skipped on
2389 * Complete:: A simple example, start to finish
2390 * true:: Building true and false
2395 @section A simple example, start to finish
2397 @cindex Complete example
2399 Let's suppose you just finished writing @code{zardoz}, a program to make
2400 your head float from vortex to vortex. You've been using Autoconf to
2401 provide a portability framework, but your @file{Makefile.in}s have been
2402 ad-hoc. You want to make them bulletproof, so you turn to Automake.
2404 @cindex @code{AM_INIT_AUTOMAKE}, example use
2406 The first step is to update your @file{configure.ac} to include the
2407 commands that @command{automake} needs. The way to do this is to add an
2408 @code{AM_INIT_AUTOMAKE} call just after @code{AC_INIT}:
2411 AC_INIT([zardoz], [1.0])
2416 Since your program doesn't have any complicating factors (e.g., it
2417 doesn't use @code{gettext}, it doesn't want to build a shared library),
2418 you're done with this part. That was easy!
2420 @cindex @command{aclocal} program, introduction
2421 @cindex @file{aclocal.m4}, preexisting
2422 @cindex @file{acinclude.m4}, defined
2424 Now you must regenerate @file{configure}. But to do that, you'll need
2425 to tell @command{autoconf} how to find the new macro you've used. The
2426 easiest way to do this is to use the @command{aclocal} program to
2427 generate your @file{aclocal.m4} for you. But wait@dots{} maybe you
2428 already have an @file{aclocal.m4}, because you had to write some hairy
2429 macros for your program. The @command{aclocal} program lets you put
2430 your own macros into @file{acinclude.m4}, so simply rename and then
2434 mv aclocal.m4 acinclude.m4
2439 @cindex @command{zardoz} example
2441 Now it is time to write your @file{Makefile.am} for @code{zardoz}.
2442 Since @code{zardoz} is a user program, you want to install it where the
2443 rest of the user programs go: @code{bindir}. Additionally,
2444 @code{zardoz} has some Texinfo documentation. Your @file{configure.ac}
2445 script uses @code{AC_REPLACE_FUNCS}, so you need to link against
2446 @samp{$(LIBOBJS)}. So here's what you'd write:
2449 bin_PROGRAMS = zardoz
2450 zardoz_SOURCES = main.c head.c float.c vortex9.c gun.c
2451 zardoz_LDADD = $(LIBOBJS)
2453 info_TEXINFOS = zardoz.texi
2456 Now you can run @samp{automake --add-missing} to generate your
2457 @file{Makefile.in} and grab any auxiliary files you might need, and
2462 @section Building true and false
2464 @cindex Example, @command{false} and @command{true}
2465 @cindex @command{false} Example
2466 @cindex @command{true} Example
2468 Here is another, trickier example. It shows how to generate two
2469 programs (@code{true} and @code{false}) from the same source file
2470 (@file{true.c}). The difficult part is that each compilation of
2471 @file{true.c} requires different @code{cpp} flags.
2474 bin_PROGRAMS = true false
2476 false_LDADD = false.o
2479 $(COMPILE) -DEXIT_CODE=0 -c true.c
2482 $(COMPILE) -DEXIT_CODE=1 -o false.o -c true.c
2485 Note that there is no @code{true_SOURCES} definition. Automake will
2486 implicitly assume that there is a source file named @file{true.c}
2487 (@pxref{Default _SOURCES}), and
2488 define rules to compile @file{true.o} and link @file{true}. The
2489 @samp{true.o: true.c} rule supplied by the above @file{Makefile.am},
2490 will override the Automake generated rule to build @file{true.o}.
2492 @code{false_SOURCES} is defined to be empty---that way no implicit value
2493 is substituted. Because we have not listed the source of
2494 @file{false}, we have to tell Automake how to link the program. This is
2495 the purpose of the @code{false_LDADD} line. A @code{false_DEPENDENCIES}
2496 variable, holding the dependencies of the @file{false} target will be
2497 automatically generated by Automake from the content of
2500 The above rules won't work if your compiler doesn't accept both
2501 @option{-c} and @option{-o}. The simplest fix for this is to introduce a
2502 bogus dependency (to avoid problems with a parallel @command{make}):
2505 true.o: true.c false.o
2506 $(COMPILE) -DEXIT_CODE=0 -c true.c
2509 $(COMPILE) -DEXIT_CODE=1 -c true.c && mv true.o false.o
2512 As it turns out, there is also a much easier way to do this same task.
2513 Some of the above technique is useful enough that we've kept the
2514 example in the manual. However if you were to build @code{true} and
2515 @code{false} in real life, you would probably use per-program
2516 compilation flags, like so:
2518 @c Keep in sync with specflg7.test and specflg8.test.
2520 bin_PROGRAMS = false true
2522 false_SOURCES = true.c
2523 false_CPPFLAGS = -DEXIT_CODE=1
2525 true_SOURCES = true.c
2526 true_CPPFLAGS = -DEXIT_CODE=0
2529 In this case Automake will cause @file{true.c} to be compiled twice,
2530 with different flags. In this instance, the names of the object files
2531 would be chosen by automake; they would be @file{false-true.o} and
2532 @file{true-true.o}. (The name of the object files rarely matters.)
2534 @node automake Invocation
2535 @chapter Creating a @file{Makefile.in}
2536 @c This node used to be named "Invoking automake". This @anchor
2537 @c allows old links to still work.
2538 @anchor{Invoking automake}
2540 @cindex Multiple @file{configure.ac} files
2541 @cindex Invoking @command{automake}
2542 @cindex @command{automake}, invoking
2543 @cindex Invocation of @command{automake}
2544 @cindex @command{automake}, invocation
2546 To create all the @file{Makefile.in}s for a package, run the
2547 @command{automake} program in the top level directory, with no
2548 arguments. @command{automake} will automatically find each
2549 appropriate @file{Makefile.am} (by scanning @file{configure.ac};
2550 @pxref{configure}) and generate the corresponding @file{Makefile.in}.
2551 Note that @command{automake} has a rather simplistic view of what
2552 constitutes a package; it assumes that a package has only one
2553 @file{configure.ac}, at the top. If your package has multiple
2554 @file{configure.ac}s, then you must run @command{automake} in each
2555 directory holding a @file{configure.ac}. (Alternatively, you may rely
2556 on Autoconf's @command{autoreconf}, which is able to recurse your
2557 package tree and run @command{automake} where appropriate.)
2559 You can optionally give @command{automake} an argument; @file{.am} is
2560 appended to the argument and the result is used as the name of the
2561 input file. This feature is generally only used to automatically
2562 rebuild an out-of-date @file{Makefile.in}. Note that
2563 @command{automake} must always be run from the topmost directory of a
2564 project, even if being used to regenerate the @file{Makefile.in} in
2565 some subdirectory. This is necessary because @command{automake} must
2566 scan @file{configure.ac}, and because @command{automake} uses the
2567 knowledge that a @file{Makefile.in} is in a subdirectory to change its
2568 behavior in some cases.
2571 Automake will run @command{autoconf} to scan @file{configure.ac} and
2572 its dependencies (i.e., @file{aclocal.m4} and any included file),
2573 therefore @command{autoconf} must be in your @env{PATH}. If there is
2574 an @env{AUTOCONF} variable in your environment it will be used
2575 instead of @command{autoconf}, this allows you to select a particular
2576 version of Autoconf. By the way, don't misunderstand this paragraph:
2577 @command{automake} runs @command{autoconf} to @strong{scan} your
2578 @file{configure.ac}, this won't build @file{configure} and you still
2579 have to run @command{autoconf} yourself for this purpose.
2581 @cindex @command{automake} options
2582 @cindex Options, @command{automake}
2583 @cindex Strictness, command line
2585 @command{automake} accepts the following options:
2587 @cindex Extra files distributed with Automake
2588 @cindex Files distributed with Automake
2589 @cindex @file{config.guess}
2593 @itemx --add-missing
2595 @opindex --add-missing
2596 Automake requires certain common files to exist in certain situations;
2597 for instance, @file{config.guess} is required if @file{configure.ac} invokes
2598 @code{AC_CANONICAL_HOST}. Automake is distributed with several of these
2599 files (@pxref{Auxiliary Programs}); this option will cause the missing
2600 ones to be automatically added to the package, whenever possible. In
2601 general if Automake tells you a file is missing, try using this option.
2602 By default Automake tries to make a symbolic link pointing to its own
2603 copy of the missing file; this can be changed with @option{--copy}.
2605 Many of the potentially-missing files are common scripts whose
2606 location may be specified via the @code{AC_CONFIG_AUX_DIR} macro.
2607 Therefore, @code{AC_CONFIG_AUX_DIR}'s setting affects whether a
2608 file is considered missing, and where the missing file is added
2611 In some strictness modes, additional files are installed, see @ref{Gnits}
2612 for more information.
2614 @item --libdir=@var{dir}
2616 Look for Automake data files in directory @var{dir} instead of in the
2617 installation directory. This is typically used for debugging.
2623 When used with @option{--add-missing}, causes installed files to be
2624 copied. The default is to make a symbolic link.
2628 Causes the generated @file{Makefile.in}s to follow Cygnus rules, instead
2629 of GNU or Gnits rules. For more information, see @ref{Cygnus}.
2633 @itemx --force-missing
2634 @opindex --force-missing
2635 When used with @option{--add-missing}, causes standard files to be reinstalled
2636 even if they already exist in the source tree. This involves removing
2637 the file from the source tree before creating the new symlink (or, with
2638 @option{--copy}, copying the new file).
2642 Set the global strictness to @option{foreign}. For more information, see
2647 Set the global strictness to @option{gnits}. For more information, see
2652 Set the global strictness to @option{gnu}. For more information, see
2653 @ref{Gnits}. This is the default strictness.
2657 Print a summary of the command line options and exit.
2660 @itemx --ignore-deps
2662 This disables the dependency tracking feature in generated
2663 @file{Makefile}s; see @ref{Dependencies}.
2665 @item --include-deps
2666 @opindex --include-deps
2667 This enables the dependency tracking feature. This feature is enabled
2668 by default. This option is provided for historical reasons only and
2669 probably should not be used.
2673 Ordinarily @command{automake} creates all @file{Makefile.in}s mentioned in
2674 @file{configure.ac}. This option causes it to only update those
2675 @file{Makefile.in}s that are out of date with respect to one of their
2679 @itemx --output-dir=@var{dir}
2681 @opindex --output-dir
2682 Put the generated @file{Makefile.in} in the directory @var{dir}.
2683 Ordinarily each @file{Makefile.in} is created in the directory of the
2684 corresponding @file{Makefile.am}. This option is deprecated and will be
2685 removed in a future release.
2691 Cause Automake to print information about which files are being read or
2696 Print the version number of Automake and exit.
2699 @itemx --warnings=@var{category}
2702 Output warnings falling in @var{category}. @var{category} can be
2706 warnings related to the GNU Coding Standards
2707 (@pxref{Top, , , standards, The GNU Coding Standards}).
2709 obsolete features or constructions
2711 user redefinitions of Automake rules or variables
2713 portability issues (e.g., use of @command{make} features that are
2714 known to be not portable)
2715 @item extra-portability
2716 extra portability issues related to obscure tools. One example of such
2717 a tool is the Microsoft @command{lib} archiver.
2719 weird syntax, unused variables, typos
2721 unsupported or incomplete features
2725 turn off all the warnings
2727 treat warnings as errors
2730 A category can be turned off by prefixing its name with @samp{no-}. For
2731 instance, @option{-Wno-syntax} will hide the warnings about unused
2734 The categories output by default are @samp{syntax} and
2735 @samp{unsupported}. Additionally, @samp{gnu} and @samp{portability}
2736 are enabled in @option{--gnu} and @option{--gnits} strictness.
2737 On the other hand, the @option{silent-rules} options (@pxref{Options})
2738 turns off portability warnings about recursive variable expansions.
2740 @c Checked by extra-portability.test
2741 Turning off @samp{portability} will also turn off @samp{extra-portability},
2742 and similarly turning on @samp{extra-portability} will also turn on
2743 @samp{portability}. However, turning on @samp{portability} or turning
2744 off @samp{extra-portability} will not affect the other category.
2747 The environment variable @env{WARNINGS} can contain a comma separated
2748 list of categories to enable. It will be taken into account before the
2749 command-line switches, this way @option{-Wnone} will also ignore any
2750 warning category enabled by @env{WARNINGS}. This variable is also used
2751 by other tools like @command{autoconf}; unknown categories are ignored
2756 @vindex AUTOMAKE_JOBS
2757 If the environment variable @env{AUTOMAKE_JOBS} contains a positive
2758 number, it is taken as the maximum number of Perl threads to use in
2759 @command{automake} for generating multiple @file{Makefile.in} files
2760 concurrently. This is an experimental feature.
2764 @chapter Scanning @file{configure.ac}, using @command{aclocal}
2766 @cindex @file{configure.ac}, scanning
2767 @cindex Scanning @file{configure.ac}
2768 @cindex Using @command{aclocal}
2769 @cindex @command{aclocal}, using
2771 Automake scans the package's @file{configure.ac} to determine certain
2772 information about the package. Some @command{autoconf} macros are required
2773 and some variables must be defined in @file{configure.ac}. Automake
2774 will also use information from @file{configure.ac} to further tailor its
2777 Automake also supplies some Autoconf macros to make the maintenance
2778 easier. These macros can automatically be put into your
2779 @file{aclocal.m4} using the @command{aclocal} program.
2782 * Requirements:: Configuration requirements
2783 * Optional:: Other things Automake recognizes
2784 * aclocal Invocation:: Auto-generating aclocal.m4
2785 * Macros:: Autoconf macros supplied with Automake
2790 @section Configuration requirements
2792 @cindex Automake requirements
2793 @cindex Requirements of Automake
2795 @acindex AM_INIT_AUTOMAKE
2796 The one real requirement of Automake is that your @file{configure.ac}
2797 call @code{AM_INIT_AUTOMAKE}. This macro does several things that are
2798 required for proper Automake operation (@pxref{Macros}).
2800 Here are the other macros that Automake requires but which are not run
2801 by @code{AM_INIT_AUTOMAKE}:
2804 @item AC_CONFIG_FILES
2806 @acindex AC_CONFIG_FILES
2808 These two macros are usually invoked as follows near the end of
2809 @file{configure.ac}.
2823 Automake uses these to determine which files to create (@pxref{Output, ,
2824 Creating Output Files, autoconf, The Autoconf Manual}). A listed file
2825 is considered to be an Automake generated @file{Makefile} if there
2826 exists a file with the same name and the @file{.am} extension appended.
2827 Typically, @samp{AC_CONFIG_FILES([foo/Makefile])} will cause Automake to
2828 generate @file{foo/Makefile.in} if @file{foo/Makefile.am} exists.
2830 When using @code{AC_CONFIG_FILES} with multiple input files, as in
2833 AC_CONFIG_FILES([Makefile:top.in:Makefile.in:bot.in])
2837 @command{automake} will generate the first @file{.in} input file for
2838 which a @file{.am} file exists. If no such file exists the output
2839 file is not considered to be generated by Automake.
2841 Files created by @code{AC_CONFIG_FILES}, be they Automake
2842 @file{Makefile}s or not, are all removed by @samp{make distclean}.
2843 Their inputs are automatically distributed, unless they
2844 are the output of prior @code{AC_CONFIG_FILES} commands.
2845 Finally, rebuild rules are generated in the Automake @file{Makefile}
2846 existing in the subdirectory of the output file, if there is one, or
2847 in the top-level @file{Makefile} otherwise.
2849 The above machinery (cleaning, distributing, and rebuilding) works
2850 fine if the @code{AC_CONFIG_FILES} specifications contain only
2851 literals. If part of the specification uses shell variables,
2852 @command{automake} will not be able to fulfill this setup, and you will
2853 have to complete the missing bits by hand. For instance, on
2855 @c Keep in sync with output11.test.
2859 AC_CONFIG_FILES([output:$file],, [file=$file])
2863 @command{automake} will output rules to clean @file{output}, and
2864 rebuild it. However the rebuild rule will not depend on @file{input},
2865 and this file will not be distributed either. (You must add
2866 @samp{EXTRA_DIST = input} to your @file{Makefile.am} if @file{input} is a
2871 @c Keep in sync with output11.test.
2876 AC_CONFIG_FILES([$file:input],, [file=$file])
2877 AC_CONFIG_FILES([$file2],, [file2=$file2])
2881 will only cause @file{input} to be distributed. No file will be
2882 cleaned automatically (add @samp{DISTCLEANFILES = output out}
2883 yourself), and no rebuild rule will be output.
2885 Obviously @command{automake} cannot guess what value @samp{$file} is
2886 going to hold later when @file{configure} is run, and it cannot use
2887 the shell variable @samp{$file} in a @file{Makefile}. However, if you
2888 make reference to @samp{$file} as @samp{$@{file@}} (i.e., in a way
2889 that is compatible with @command{make}'s syntax) and furthermore use
2890 @code{AC_SUBST} to ensure that @samp{$@{file@}} is meaningful in a
2891 @file{Makefile}, then @command{automake} will be able to use
2892 @samp{$@{file@}} to generate all these rules. For instance, here is
2893 how the Automake package itself generates versioned scripts for its
2897 AC_SUBST([APIVERSION], @dots{})
2900 [tests/aclocal-$@{APIVERSION@}:tests/aclocal.in],
2901 [chmod +x tests/aclocal-$@{APIVERSION@}],
2902 [APIVERSION=$APIVERSION])
2904 [tests/automake-$@{APIVERSION@}:tests/automake.in],
2905 [chmod +x tests/automake-$@{APIVERSION@}])
2909 Here cleaning, distributing, and rebuilding are done automatically,
2910 because @samp{$@{APIVERSION@}} is known at @command{make}-time.
2912 Note that you should not use shell variables to declare
2913 @file{Makefile} files for which @command{automake} must create
2914 @file{Makefile.in}. Even @code{AC_SUBST} does not help here, because
2915 @command{automake} needs to know the file name when it runs in order
2916 to check whether @file{Makefile.am} exists. (In the very hairy case
2917 that your setup requires such use of variables, you will have to tell
2918 Automake which @file{Makefile.in}s to generate on the command-line.)
2920 It is possible to let @command{automake} emit conditional rules for
2921 @code{AC_CONFIG_FILES} with the help of @code{AM_COND_IF}
2927 Use literals for @file{Makefile}s, and for other files whenever possible.
2929 Use @samp{$file} (or @samp{$@{file@}} without @samp{AC_SUBST([file])})
2930 for files that @command{automake} should ignore.
2932 Use @samp{$@{file@}} and @samp{AC_SUBST([file])} for files
2933 that @command{automake} should not ignore.
2940 @section Other things Automake recognizes
2942 @cindex Macros Automake recognizes
2943 @cindex Recognized macros by Automake
2945 Every time Automake is run it calls Autoconf to trace
2946 @file{configure.ac}. This way it can recognize the use of certain
2947 macros and tailor the generated @file{Makefile.in} appropriately.
2948 Currently recognized macros and their effects are:
2951 @item AC_CANONICAL_BUILD
2952 @itemx AC_CANONICAL_HOST
2953 @itemx AC_CANONICAL_TARGET
2954 @vindex build_triplet
2955 @vindex host_triplet
2956 @vindex target_triplet
2957 Automake will ensure that @file{config.guess} and @file{config.sub}
2958 exist. Also, the @file{Makefile} variables @code{build_triplet},
2959 @code{host_triplet} and @code{target_triplet} are introduced. See
2960 @ref{Canonicalizing, , Getting the Canonical System Type, autoconf,
2961 The Autoconf Manual}.
2963 @item AC_CONFIG_AUX_DIR
2964 Automake will look for various helper scripts, such as
2965 @file{install-sh}, in the directory named in this macro invocation.
2966 @c This list is accurate relative to version 1.11
2967 (The full list of scripts is:
2969 @file{config.guess},
2978 @file{mkinstalldirs},
2983 Not all scripts are always searched for; some scripts
2984 will only be sought if the generated @file{Makefile.in} requires them.
2986 If @code{AC_CONFIG_AUX_DIR} is not given, the scripts are looked for in
2987 their standard locations. For @file{mdate-sh},
2988 @file{texinfo.tex}, and @file{ylwrap}, the standard location is the
2989 source directory corresponding to the current @file{Makefile.am}. For
2990 the rest, the standard location is the first one of @file{.}, @file{..},
2991 or @file{../..} (relative to the top source directory) that provides any
2992 one of the helper scripts. @xref{Input, , Finding `configure' Input,
2993 autoconf, The Autoconf Manual}.
2995 Required files from @code{AC_CONFIG_AUX_DIR} are automatically
2996 distributed, even if there is no @file{Makefile.am} in this directory.
2998 @item AC_CONFIG_LIBOBJ_DIR
2999 Automake will require the sources file declared with
3000 @code{AC_LIBSOURCE} (see below) in the directory specified by this
3003 @item AC_CONFIG_HEADERS
3004 Automake will generate rules to rebuild these headers. Older versions
3005 of Automake required the use of @code{AM_CONFIG_HEADER}
3006 (@pxref{Macros}); this is no longer the case.
3008 As with @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the
3009 specification using shell variables will be ignored as far as
3010 cleaning, distributing, and rebuilding is concerned.
3012 @item AC_CONFIG_LINKS
3013 Automake will generate rules to remove @file{configure} generated
3014 links on @samp{make distclean} and to distribute named source files as
3015 part of @samp{make dist}.
3017 As for @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the
3018 specification using shell variables will be ignored as far as cleaning
3019 and distributing is concerned. (There are no rebuild rules for links.)
3023 @itemx AC_LIBSOURCES
3025 Automake will automatically distribute any file listed in
3026 @code{AC_LIBSOURCE} or @code{AC_LIBSOURCES}.
3028 Note that the @code{AC_LIBOBJ} macro calls @code{AC_LIBSOURCE}. So if
3029 an Autoconf macro is documented to call @samp{AC_LIBOBJ([file])}, then
3030 @file{file.c} will be distributed automatically by Automake. This
3031 encompasses many macros like @code{AC_FUNC_ALLOCA},
3032 @code{AC_FUNC_MEMCMP}, @code{AC_REPLACE_FUNCS}, and others.
3034 By the way, direct assignments to @code{LIBOBJS} are no longer
3035 supported. You should always use @code{AC_LIBOBJ} for this purpose.
3036 @xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs.@: @code{LIBOBJS},
3037 autoconf, The Autoconf Manual}.
3039 @item AC_PROG_RANLIB
3040 This is required if any libraries are built in the package.
3041 @xref{Particular Programs, , Particular Program Checks, autoconf, The
3045 This is required if any C++ source is included. @xref{Particular
3046 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
3049 This is required if any Objective C source is included. @xref{Particular
3050 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
3053 This is required if any Fortran 77 source is included. This macro is
3054 distributed with Autoconf version 2.13 and later. @xref{Particular
3055 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
3057 @item AC_F77_LIBRARY_LDFLAGS
3058 This is required for programs and shared libraries that are a mixture of
3059 languages that include Fortran 77 (@pxref{Mixing Fortran 77 With C and
3060 C++}). @xref{Macros, , Autoconf macros supplied with Automake}.
3063 Automake will add the flags computed by @code{AC_FC_SRCEXT} to compilation
3064 of files with the respective source extension (@pxref{Fortran Compiler, ,
3065 Fortran Compiler Characteristics, autoconf, The Autoconf Manual}).
3068 This is required if any Fortran 90/95 source is included. This macro is
3069 distributed with Autoconf version 2.58 and later. @xref{Particular
3070 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
3072 @item AC_PROG_LIBTOOL
3073 Automake will turn on processing for @command{libtool} (@pxref{Top, ,
3074 Introduction, libtool, The Libtool Manual}).
3078 If a Yacc source file is seen, then you must either use this macro or
3079 define the variable @code{YACC} in @file{configure.ac}. The former is
3080 preferred (@pxref{Particular Programs, , Particular Program Checks,
3081 autoconf, The Autoconf Manual}).
3084 If a Lex source file is seen, then this macro must be used.
3085 @xref{Particular Programs, , Particular Program Checks, autoconf, The
3088 @item AC_REQUIRE_AUX_FILE
3089 For each @code{AC_REQUIRE_AUX_FILE([@var{file}])},
3090 @command{automake} will ensure that @file{@var{file}} exists in the
3091 aux directory, and will complain otherwise. It
3092 will also automatically distribute the file. This macro should be
3093 used by third-party Autoconf macros that require some supporting
3094 files in the aux directory specified with @code{AC_CONFIG_AUX_DIR}
3095 above. @xref{Input, , Finding @command{configure} Input, autoconf,
3096 The Autoconf Manual}.
3099 The first argument is automatically defined as a variable in each
3100 generated @file{Makefile.in}, unless @code{AM_SUBST_NOTMAKE} is also
3101 used for this variable. @xref{Setting Output Variables, , Setting
3102 Output Variables, autoconf, The Autoconf Manual}.
3104 For every substituted variable @var{var}, @command{automake} will add
3105 a line @code{@var{var} = @var{value}} to each @file{Makefile.in} file.
3106 Many Autoconf macros invoke @code{AC_SUBST} to set output variables
3107 this way, e.g., @code{AC_PATH_XTRA} defines @code{X_CFLAGS} and
3108 @code{X_LIBS}. Thus, you can access these variables as
3109 @code{$(X_CFLAGS)} and @code{$(X_LIBS)} in any @file{Makefile.am}
3110 if @code{AC_PATH_XTRA} is called.
3112 @item AM_CONDITIONAL
3113 This introduces an Automake conditional (@pxref{Conditionals}).
3116 This macro allows @code{automake} to detect subsequent access within
3117 @file{configure.ac} to a conditional previously introduced with
3118 @code{AM_CONDITIONAL}, thus enabling conditional @code{AC_CONFIG_FILES}
3119 (@pxref{Usage of Conditionals}).
3121 @item AM_GNU_GETTEXT
3122 This macro is required for packages that use GNU gettext
3123 (@pxref{gettext}). It is distributed with gettext. If Automake sees
3124 this macro it ensures that the package meets some of gettext's
3127 @item AM_GNU_GETTEXT_INTL_SUBDIR
3128 This macro specifies that the @file{intl/} subdirectory is to be built,
3129 even if the @code{AM_GNU_GETTEXT} macro was invoked with a first argument
3132 @item AM_MAINTAINER_MODE(@ovar{default-mode})
3133 @opindex --enable-maintainer-mode
3134 @opindex --disable-maintainer-mode
3135 This macro adds an @option{--enable-maintainer-mode} option to
3136 @command{configure}. If this is used, @command{automake} will cause
3137 ``maintainer-only'' rules to be turned off by default in the
3138 generated @file{Makefile.in}s, unless @var{default-mode} is
3139 @samp{enable}. This macro defines the @code{MAINTAINER_MODE}
3140 conditional, which you can use in your own @file{Makefile.am}.
3141 @xref{maintainer-mode}.
3143 @item AM_SUBST_NOTMAKE(@var{var})
3144 Prevent Automake from defining a variable @var{var}, even if it is
3145 substituted by @command{config.status}. Normally, Automake defines a
3146 @command{make} variable for each @command{configure} substitution,
3147 i.e., for each @code{AC_SUBST([@var{var}])}. This macro prevents that
3148 definition from Automake. If @code{AC_SUBST} has not been called
3149 for this variable, then @code{AM_SUBST_NOTMAKE} has no effects.
3150 Preventing variable definitions may be useful for substitution of
3151 multi-line values, where @code{@var{var} = @@@var{value}@@} might yield
3155 Files included by @file{configure.ac} using this macro will be
3156 detected by Automake and automatically distributed. They will also
3157 appear as dependencies in @file{Makefile} rules.
3159 @code{m4_include} is seldom used by @file{configure.ac} authors, but
3160 can appear in @file{aclocal.m4} when @command{aclocal} detects that
3161 some required macros come from files local to your package (as opposed to
3162 macros installed in a system-wide directory, @pxref{aclocal Invocation}).
3166 @node aclocal Invocation
3167 @section Auto-generating aclocal.m4
3168 @c This node used to be named "Invoking automake". This @anchor
3169 @c allows old links to still work.
3170 @anchor{Invoking aclocal}
3172 @cindex Invocation of @command{aclocal}
3173 @cindex @command{aclocal}, Invocation
3174 @cindex Invoking @command{aclocal}
3175 @cindex @command{aclocal}, Invoking
3177 Automake includes a number of Autoconf macros that can be used in
3178 your package (@pxref{Macros}); some of them are actually required by
3179 Automake in certain situations. These macros must be defined in your
3180 @file{aclocal.m4}; otherwise they will not be seen by
3183 The @command{aclocal} program will automatically generate
3184 @file{aclocal.m4} files based on the contents of @file{configure.ac}.
3185 This provides a convenient way to get Automake-provided macros,
3186 without having to search around. The @command{aclocal} mechanism
3187 allows other packages to supply their own macros (@pxref{Extending
3188 aclocal}). You can also use it to maintain your own set of custom
3189 macros (@pxref{Local Macros}).
3191 At startup, @command{aclocal} scans all the @file{.m4} files it can
3192 find, looking for macro definitions (@pxref{Macro Search Path}). Then
3193 it scans @file{configure.ac}. Any mention of one of the macros found
3194 in the first step causes that macro, and any macros it in turn
3195 requires, to be put into @file{aclocal.m4}.
3197 @emph{Putting} the file that contains the macro definition into
3198 @file{aclocal.m4} is usually done by copying the entire text of this
3199 file, including unused macro definitions as well as both @samp{#} and
3200 @samp{dnl} comments. If you want to make a comment that will be
3201 completely ignored by @command{aclocal}, use @samp{##} as the comment
3204 When a file selected by @command{aclocal} is located in a subdirectory
3205 specified as a relative search path with @command{aclocal}'s @option{-I}
3206 argument, @command{aclocal} assumes the file belongs to the package
3207 and uses @code{m4_include} instead of copying it into
3208 @file{aclocal.m4}. This makes the package smaller, eases dependency
3209 tracking, and cause the file to be distributed automatically.
3210 (@xref{Local Macros}, for an example.) Any macro that is found in a
3211 system-wide directory, or via an absolute search path will be copied.
3212 So use @samp{-I `pwd`/reldir} instead of @samp{-I reldir} whenever
3213 some relative directory should be considered outside the package.
3215 The contents of @file{acinclude.m4}, if this file exists, are also
3216 automatically included in @file{aclocal.m4}. We recommend against
3217 using @file{acinclude.m4} in new packages (@pxref{Local Macros}).
3221 While computing @file{aclocal.m4}, @command{aclocal} runs
3222 @command{autom4te} (@pxref{Using autom4te, , Using @command{Autom4te},
3223 autoconf, The Autoconf Manual}) in order to trace the macros that are
3224 really used, and omit from @file{aclocal.m4} all macros that are
3225 mentioned but otherwise unexpanded (this can happen when a macro is
3226 called conditionally). @command{autom4te} is expected to be in the
3227 @env{PATH}, just as @command{autoconf}. Its location can be
3228 overridden using the @env{AUTOM4TE} environment variable.
3231 * aclocal Options:: Options supported by aclocal
3232 * Macro Search Path:: How aclocal finds .m4 files
3233 * Extending aclocal:: Writing your own aclocal macros
3234 * Local Macros:: Organizing local macros
3235 * Serials:: Serial lines in Autoconf macros
3236 * Future of aclocal:: aclocal's scheduled death
3239 @node aclocal Options
3240 @subsection aclocal Options
3242 @cindex @command{aclocal}, Options
3243 @cindex Options, @command{aclocal}
3245 @command{aclocal} accepts the following options:
3248 @item --automake-acdir=@var{dir}
3249 @opindex --automake-acdir
3250 Look for the automake-provided macro files in @var{dir} instead of
3251 in the installation directory. This is typically used for debugging.
3253 @item --system-acdir=@var{dir}
3254 @opindex --system-acdir
3255 Look for the system-wide third-party macro files (and the special
3256 @file{dirlist} file) in @var{dir} instead of in the installation
3257 directory. This is typically used for debugging.
3259 @item --diff[=@var{command}]
3261 Run @var{command} on M4 file that would be installed or overwritten
3262 by @option{--install}. The default @var{command} is @samp{diff -u}.
3263 This option implies @option{--install} and @option{--dry-run}.
3267 Do not actually overwrite (or create) @file{aclocal.m4} and M4
3268 files installed by @option{--install}.
3272 Print a summary of the command line options and exit.
3276 Add the directory @var{dir} to the list of directories searched for
3281 Install system-wide third-party macros into the first directory
3282 specified with @samp{-I @var{dir}} instead of copying them in the
3284 @c The following semantics is checked by `aclocal-install-absdir.test'.
3285 Note that this will happen also if @var{dir} is an absolute path.
3287 @cindex serial number and @option{--install}
3288 When this option is used, and only when this option is used,
3289 @command{aclocal} will also honor @samp{#serial @var{number}} lines
3290 that appear in macros: an M4 file is ignored if there exists another
3291 M4 file with the same basename and a greater serial number in the
3292 search path (@pxref{Serials}).
3296 Always overwrite the output file. The default is to overwrite the output
3297 file only when really needed, i.e., when its contents changes or if one
3298 of its dependencies is younger.
3300 This option forces the update of @file{aclocal.m4} (or the file
3301 specified with @file{--output} below) and only this file, it has
3302 absolutely no influence on files that may need to be installed by
3305 @item --output=@var{file}
3307 Cause the output to be put into @var{file} instead of @file{aclocal.m4}.
3309 @item --print-ac-dir
3310 @opindex --print-ac-dir
3311 Prints the name of the directory that @command{aclocal} will search to
3312 find third-party @file{.m4} files. When this option is given, normal
3313 processing is suppressed. This option was used @emph{in the past} by
3314 third-party packages to determine where to install @file{.m4} macro
3315 files, but @emph{this usage is today discouraged}, since it causes
3316 @samp{$(prefix)} not to be thoroughly honoured (which violates the
3317 GNU Coding Standards), and a similar semantics can be better obtained
3318 with the @env{ACLOCAL_PATH} environment variable; @pxref{Extending aclocal}.
3322 Print the names of the files it examines.
3326 Print the version number of Automake and exit.
3329 @item --warnings=@var{category}
3332 Output warnings falling in @var{category}. @var{category} can be
3336 dubious syntactic constructs, underquoted macros, unused macros, etc.
3340 all the warnings, this is the default
3342 turn off all the warnings
3344 treat warnings as errors
3347 All warnings are output by default.
3350 The environment variable @env{WARNINGS} is honored in the same
3351 way as it is for @command{automake} (@pxref{automake Invocation}).
3355 @node Macro Search Path
3356 @subsection Macro Search Path
3358 @cindex Macro search path
3359 @cindex @command{aclocal} search path
3361 By default, @command{aclocal} searches for @file{.m4} files in the following
3362 directories, in this order:
3365 @item @var{acdir-APIVERSION}
3366 This is where the @file{.m4} macros distributed with Automake itself
3367 are stored. @var{APIVERSION} depends on the Automake release used;
3368 for example, for Automake 1.11.x, @var{APIVERSION} = @code{1.11}.
3371 This directory is intended for third party @file{.m4} files, and is
3372 configured when @command{automake} itself is built. This is
3373 @file{@@datadir@@/aclocal/}, which typically
3374 expands to @file{$@{prefix@}/share/aclocal/}. To find the compiled-in
3375 value of @var{acdir}, use the @option{--print-ac-dir} option
3376 (@pxref{aclocal Options}).
3379 As an example, suppose that @command{automake-1.11.2} was configured with
3380 @option{--prefix=@-/usr/local}. Then, the search path would be:
3383 @item @file{/usr/local/share/aclocal-1.11.2/}
3384 @item @file{/usr/local/share/aclocal/}
3387 The paths for the @var{acdir} and @var{acdir-APIVERSION} directories can
3388 be changed respectively through aclocal options @option{--system-acdir}
3389 and @option{--automake-acdir} (@pxref{aclocal Options}). Note however
3390 that these options are only intended for use by the internal Automake
3391 test suite, or for debugging under highly unusual situations; they are
3392 not ordinarily needed by end-users.
3394 As explained in (@pxref{aclocal Options}), there are several options that
3395 can be used to change or extend this search path.
3397 @subsubheading Modifying the Macro Search Path: @samp{-I @var{dir}}
3399 Any extra directories specified using @option{-I} options
3400 (@pxref{aclocal Options}) are @emph{prepended} to this search list. Thus,
3401 @samp{aclocal -I /foo -I /bar} results in the following search path:
3406 @item @var{acdir}-@var{APIVERSION}
3410 @subsubheading Modifying the Macro Search Path: @file{dirlist}
3411 @cindex @file{dirlist}
3413 There is a third mechanism for customizing the search path. If a
3414 @file{dirlist} file exists in @var{acdir}, then that file is assumed to
3415 contain a list of directory patterns, one per line. @command{aclocal}
3416 expands these patterns to directory names, and adds them to the search
3417 list @emph{after} all other directories. @file{dirlist} entries may
3418 use shell wildcards such as @samp{*}, @samp{?}, or @code{[...]}.
3420 For example, suppose
3421 @file{@var{acdir}/dirlist} contains the following:
3430 and that @command{aclocal} was called with the @samp{-I /foo -I /bar} options.
3431 Then, the search path would be
3433 @c @code looks better than @file here
3437 @item @var{acdir}-@var{APIVERSION}
3444 and all directories with path names starting with @code{/test3}.
3446 If the @option{--system-acdir=@var{dir}} option is used, then
3447 @command{aclocal} will search for the @file{dirlist} file in
3448 @var{dir}; but remember the warnings above against the use of
3449 @option{--system-acdir}.
3451 @file{dirlist} is useful in the following situation: suppose that
3452 @command{automake} version @code{1.11.2} is installed with
3453 @samp{--prefix=/usr} by the system vendor. Thus, the default search
3456 @c @code looks better than @file here
3458 @item @code{/usr/share/aclocal-1.11/}
3459 @item @code{/usr/share/aclocal/}
3462 However, suppose further that many packages have been manually
3463 installed on the system, with $prefix=/usr/local, as is typical. In
3464 that case, many of these ``extra'' @file{.m4} files are in
3465 @file{/usr/local/share/aclocal}. The only way to force
3466 @file{/usr/bin/aclocal} to find these ``extra'' @file{.m4} files is to
3467 always call @samp{aclocal -I /usr/local/share/aclocal}. This is
3468 inconvenient. With @file{dirlist}, one may create a file
3469 @file{/usr/share/aclocal/dirlist} containing only the single line
3472 /usr/local/share/aclocal
3475 Now, the ``default'' search path on the affected system is
3477 @c @code looks better than @file here
3479 @item @code{/usr/share/aclocal-1.11/}
3480 @item @code{/usr/share/aclocal/}
3481 @item @code{/usr/local/share/aclocal/}
3484 without the need for @option{-I} options; @option{-I} options can be reserved
3485 for project-specific needs (@file{my-source-dir/m4/}), rather than
3486 using it to work around local system-dependent tool installation
3489 Similarly, @file{dirlist} can be handy if you have installed a local
3490 copy of Automake in your account and want @command{aclocal} to look for
3491 macros installed at other places on the system.
3493 @anchor{ACLOCAL_PATH}
3494 @subsubheading Modifying the Macro Search Path: @file{ACLOCAL_PATH}
3495 @cindex @env{ACLOCAL_PATH}
3497 The fourth and last mechanism to customize the macro search path is
3498 also the simplest. Any directory included in the colon-separated
3499 environment variable @env{ACLOCAL_PATH} is added to the search path
3500 @c Keep in sync with aclocal-path-precedence.test.
3501 and takes precedence over system directories (including those found via
3502 @file{dirlist}), with the exception of the versioned directory
3503 @var{acdir-APIVERSION} (@pxref{Macro Search Path}). However, directories
3504 passed via @option{-I} will take precedence over directories in
3507 @c Keep in sync with aclocal-path-installed.test.
3508 Also note that, if the @option{--install} option is used, any @file{.m4}
3509 file containing a required macro that is found in a directory listed in
3510 @env{ACLOCAL_PATH} will be installed locally.
3511 @c Keep in sync with aclocal-path-installed-serial.test.
3512 In this case, serial numbers in @file{.m4} are honoured too,
3515 Conversely to @file{dirlist}, @env{ACLOCAL_PATH} is useful if you are
3516 using a global copy of Automake and want @command{aclocal} to look for
3517 macros somewhere under your home directory.
3519 @subsubheading Planned future incompatibilities
3521 The order in which the directories in the macro search path are currently
3522 looked up is confusing and/or suboptimal in various aspects, and is
3523 probably going to be changed in the future Automake release. In
3524 particular, directories in @env{ACLOCAL_PATH} and @file{@var{acdir}}
3525 might end up taking precedence over @file{@var{acdir-APIVERSION}}, and
3526 directories in @file{@var{acdir}/dirlist} might end up taking precedence
3527 over @file{@var{acdir}}. @emph{This is a possible future incompatibility!}
3529 @node Extending aclocal
3530 @subsection Writing your own aclocal macros
3532 @cindex @command{aclocal}, extending
3533 @cindex Extending @command{aclocal}
3535 The @command{aclocal} program doesn't have any built-in knowledge of any
3536 macros, so it is easy to extend it with your own macros.
3538 This can be used by libraries that want to supply their own Autoconf
3539 macros for use by other programs. For instance, the @command{gettext}
3540 library supplies a macro @code{AM_GNU_GETTEXT} that should be used by
3541 any package using @command{gettext}. When the library is installed, it
3542 installs this macro so that @command{aclocal} will find it.
3544 A macro file's name should end in @file{.m4}. Such files should be
3545 installed in @file{$(datadir)/aclocal}. This is as simple as writing:
3547 @c Keep in sync with primary-prefix-couples-documented-valid.test.
3549 aclocaldir = $(datadir)/aclocal
3550 aclocal_DATA = mymacro.m4 myothermacro.m4
3554 Please do use @file{$(datadir)/aclocal}, and not something based on
3555 the result of @samp{aclocal --print-ac-dir} (@pxref{Hard-Coded Install
3556 Paths}, for arguments). It might also be helpful to suggest to
3557 the user to add the @file{$(datadir)/aclocal} directory to his
3558 @env{ACLOCAL_PATH} variable (@pxref{ACLOCAL_PATH}) so that
3559 @command{aclocal} will find the @file{.m4} files installed by your
3560 package automatically.
3562 A file of macros should be a series of properly quoted
3563 @code{AC_DEFUN}'s (@pxref{Macro Definitions, , , autoconf, The
3564 Autoconf Manual}). The @command{aclocal} programs also understands
3565 @code{AC_REQUIRE} (@pxref{Prerequisite Macros, , , autoconf, The
3566 Autoconf Manual}), so it is safe to put each macro in a separate file.
3567 Each file should have no side effects but macro definitions.
3568 Especially, any call to @code{AC_PREREQ} should be done inside the
3569 defined macro, not at the beginning of the file.
3571 @cindex underquoted @code{AC_DEFUN}
3575 Starting with Automake 1.8, @command{aclocal} will warn about all
3576 underquoted calls to @code{AC_DEFUN}. We realize this will annoy a
3577 lot of people, because @command{aclocal} was not so strict in the past
3578 and many third party macros are underquoted; and we have to apologize
3579 for this temporary inconvenience. The reason we have to be stricter
3580 is that a future implementation of @command{aclocal} (@pxref{Future of
3581 aclocal}) will have to temporarily include all these third party
3582 @file{.m4} files, maybe several times, including even files that are
3583 not actually needed. Doing so should alleviate many problems of the
3584 current implementation, however it requires a stricter style from the
3585 macro authors. Hopefully it is easy to revise the existing macros.
3592 [AC_REQUIRE([AX_SOMETHING])dnl
3599 should be rewritten as
3602 AC_DEFUN([AX_FOOBAR],
3603 [AC_PREREQ([2.57])dnl
3604 AC_REQUIRE([AX_SOMETHING])dnl
3610 Wrapping the @code{AC_PREREQ} call inside the macro ensures that
3611 Autoconf 2.57 will not be required if @code{AX_FOOBAR} is not actually
3612 used. Most importantly, quoting the first argument of @code{AC_DEFUN}
3613 allows the macro to be redefined or included twice (otherwise this
3614 first argument would be expanded during the second definition). For
3615 consistency we like to quote even arguments such as @code{2.57} that
3618 If you have been directed here by the @command{aclocal} diagnostic but
3619 are not the maintainer of the implicated macro, you will want to
3620 contact the maintainer of that macro. Please make sure you have the
3621 latest version of the macro and that the problem hasn't already been
3622 reported before doing so: people tend to work faster when they aren't
3625 Another situation where @command{aclocal} is commonly used is to
3626 manage macros that are used locally by the package, @ref{Local
3630 @subsection Handling Local Macros
3632 Feature tests offered by Autoconf do not cover all needs. People
3633 often have to supplement existing tests with their own macros, or
3634 with third-party macros.
3636 There are two ways to organize custom macros in a package.
3638 The first possibility (the historical practice) is to list all your
3639 macros in @file{acinclude.m4}. This file will be included in
3640 @file{aclocal.m4} when you run @command{aclocal}, and its macro(s) will
3641 henceforth be visible to @command{autoconf}. However if it contains
3642 numerous macros, it will rapidly become difficult to maintain, and it
3643 will be almost impossible to share macros between packages.
3645 @vindex ACLOCAL_AMFLAGS
3646 The second possibility, which we do recommend, is to write each macro
3647 in its own file and gather all these files in a directory. This
3648 directory is usually called @file{m4/}. To build @file{aclocal.m4},
3649 one should therefore instruct @command{aclocal} to scan @file{m4/}.
3650 From the command line, this is done with @samp{aclocal -I m4}. The
3651 top-level @file{Makefile.am} should also be updated to define
3654 ACLOCAL_AMFLAGS = -I m4
3657 @code{ACLOCAL_AMFLAGS} contains options to pass to @command{aclocal}
3658 when @file{aclocal.m4} is to be rebuilt by @command{make}. This line is
3659 also used by @command{autoreconf} (@pxref{autoreconf Invocation, ,
3660 Using @command{autoreconf} to Update @file{configure} Scripts,
3661 autoconf, The Autoconf Manual}) to run @command{aclocal} with suitable
3662 options, or by @command{autopoint} (@pxref{autopoint Invocation, ,
3663 Invoking the @command{autopoint} Program, gettext, GNU gettext tools})
3664 and @command{gettextize} (@pxref{gettextize Invocation, , Invoking the
3665 @command{gettextize} Program, gettext, GNU gettext tools}) to locate
3666 the place where Gettext's macros should be installed. So even if you
3667 do not really care about the rebuild rules, you should define
3668 @code{ACLOCAL_AMFLAGS}.
3670 When @samp{aclocal -I m4} is run, it will build an @file{aclocal.m4}
3671 that @code{m4_include}s any file from @file{m4/} that defines a
3672 required macro. Macros not found locally will still be searched in
3673 system-wide directories, as explained in @ref{Macro Search Path}.
3675 Custom macros should be distributed for the same reason that
3676 @file{configure.ac} is: so that other people have all the sources of
3677 your package if they want to work on it. Actually, this distribution
3678 happens automatically because all @code{m4_include}d files are
3681 However there is no consensus on the distribution of third-party
3682 macros that your package may use. Many libraries install their own
3683 macro in the system-wide @command{aclocal} directory (@pxref{Extending
3684 aclocal}). For instance, Guile ships with a file called
3685 @file{guile.m4} that contains the macro @code{GUILE_FLAGS} that can
3686 be used to define setup compiler and linker flags appropriate for
3687 using Guile. Using @code{GUILE_FLAGS} in @file{configure.ac} will
3688 cause @command{aclocal} to copy @file{guile.m4} into
3689 @file{aclocal.m4}, but as @file{guile.m4} is not part of the project,
3690 it will not be distributed. Technically, that means a user who
3691 needs to rebuild @file{aclocal.m4} will have to install Guile first.
3692 This is probably OK, if Guile already is a requirement to build the
3693 package. However, if Guile is only an optional feature, or if your
3694 package might run on architectures where Guile cannot be installed,
3695 this requirement will hinder development. An easy solution is to copy
3696 such third-party macros in your local @file{m4/} directory so they get
3699 Since Automake 1.10, @command{aclocal} offers an option to copy these
3700 system-wide third-party macros in your local macro directory, solving
3701 the above problem. Simply use:
3704 ACLOCAL_AMFLAGS = -I m4 --install
3708 With this setup, system-wide macros will be copied to @file{m4/}
3709 the first time you run @command{autoreconf}. Then the locally
3710 installed macros will have precedence over the system-wide installed
3711 macros each time @command{aclocal} is run again.
3713 One reason why you should keep @option{--install} in the flags even
3714 after the first run is that when you later edit @file{configure.ac}
3715 and depend on a new macro, this macro will be installed in your
3716 @file{m4/} automatically. Another one is that serial numbers
3717 (@pxref{Serials}) can be used to update the macros in your source tree
3718 automatically when new system-wide versions are installed. A serial
3719 number should be a single line of the form
3726 where @var{nnn} contains only digits and dots. It should appear in
3727 the M4 file before any macro definition. It is a good practice to
3728 maintain a serial number for each macro you distribute, even if you do
3729 not use the @option{--install} option of @command{aclocal}: this allows
3730 other people to use it.
3734 @subsection Serial Numbers
3735 @cindex serial numbers in macros
3736 @cindex macro serial numbers
3737 @cindex @code{#serial} syntax
3738 @cindex @command{aclocal} and serial numbers
3740 Because third-party macros defined in @file{*.m4} files are naturally
3741 shared between multiple projects, some people like to version them.
3742 This makes it easier to tell which of two M4 files is newer. Since at
3743 least 1996, the tradition is to use a @samp{#serial} line for this.
3745 A serial number should be a single line of the form
3748 # serial @var{version}
3752 where @var{version} is a version number containing only digits and
3753 dots. Usually people use a single integer, and they increment it each
3754 time they change the macro (hence the name of ``serial''). Such a
3755 line should appear in the M4 file before any macro definition.
3757 The @samp{#} must be the first character on the line,
3758 and it is OK to have extra words after the version, as in
3761 #serial @var{version} @var{garbage}
3764 Normally these serial numbers are completely ignored by
3765 @command{aclocal} and @command{autoconf}, like any genuine comment.
3766 However when using @command{aclocal}'s @option{--install} feature, these
3767 serial numbers will modify the way @command{aclocal} selects the
3768 macros to install in the package: if two files with the same basename
3769 exist in your search path, and if at least one of them uses a
3770 @samp{#serial} line, @command{aclocal} will ignore the file that has
3771 the older @samp{#serial} line (or the file that has none).
3773 Note that a serial number applies to a whole M4 file, not to any macro
3774 it contains. A file can contains multiple macros, but only one
3777 Here is a use case that illustrates the use of @option{--install} and
3778 its interaction with serial numbers. Let's assume we maintain a
3779 package called MyPackage, the @file{configure.ac} of which requires a
3780 third-party macro @code{AX_THIRD_PARTY} defined in
3781 @file{/usr/share/aclocal/thirdparty.m4} as follows:
3785 AC_DEFUN([AX_THIRD_PARTY], [...])
3788 MyPackage uses an @file{m4/} directory to store local macros as
3789 explained in @ref{Local Macros}, and has
3792 ACLOCAL_AMFLAGS = -I m4 --install
3796 in its top-level @file{Makefile.am}.
3798 Initially the @file{m4/} directory is empty. The first time we run
3799 @command{autoreconf}, it will fetch the options to pass to
3800 @command{aclocal} in @file{Makefile.am}, and run @samp{aclocal -I m4
3801 --install}. @command{aclocal} will notice that
3805 @file{configure.ac} uses @code{AX_THIRD_PARTY}
3807 No local macros define @code{AX_THIRD_PARTY}
3809 @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3814 Because @file{/usr/share/aclocal/thirdparty.m4} is a system-wide macro
3815 and @command{aclocal} was given the @option{--install} option, it will
3816 copy this file in @file{m4/thirdparty.m4}, and output an
3817 @file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}.
3819 The next time @samp{aclocal -I m4 --install} is run (either via
3820 @command{autoreconf}, by hand, or from the @file{Makefile} rebuild
3821 rules) something different happens. @command{aclocal} notices that
3825 @file{configure.ac} uses @code{AX_THIRD_PARTY}
3827 @file{m4/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3830 @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3835 Because both files have the same serial number, @command{aclocal} uses
3836 the first it found in its search path order (@pxref{Macro Search
3837 Path}). @command{aclocal} therefore ignores
3838 @file{/usr/share/aclocal/thirdparty.m4} and outputs an
3839 @file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}.
3841 Local directories specified with @option{-I} are always searched before
3842 system-wide directories, so a local file will always be preferred to
3843 the system-wide file in case of equal serial numbers.
3845 Now suppose the system-wide third-party macro is changed. This can
3846 happen if the package installing this macro is updated. Let's suppose
3847 the new macro has serial number 2. The next time @samp{aclocal -I m4
3848 --install} is run the situation is the following:
3852 @file{configure.ac} uses @code{AX_THIRD_PARTY}
3854 @file{m4/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3857 @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3862 When @command{aclocal} sees a greater serial number, it immediately
3863 forgets anything it knows from files that have the same basename and a
3864 smaller serial number. So after it has found
3865 @file{/usr/share/aclocal/thirdparty.m4} with serial 2,
3866 @command{aclocal} will proceed as if it had never seen
3867 @file{m4/thirdparty.m4}. This brings us back to a situation similar
3868 to that at the beginning of our example, where no local file defined
3869 the macro. @command{aclocal} will install the new version of the
3870 macro in @file{m4/thirdparty.m4}, in this case overriding the old
3871 version. MyPackage just had its macro updated as a side effect of
3872 running @command{aclocal}.
3874 If you are leery of letting @command{aclocal} update your local macro,
3875 you can run @samp{aclocal -I m4 --diff} to review the changes
3876 @samp{aclocal -I m4 --install} would perform on these macros.
3878 Finally, note that the @option{--force} option of @command{aclocal} has
3879 absolutely no effect on the files installed by @option{--install}. For
3880 instance, if you have modified your local macros, do not expect
3881 @option{--install --force} to replace the local macros by their
3882 system-wide versions. If you want to do so, simply erase the local
3883 macros you want to revert, and run @samp{aclocal -I m4 --install}.
3886 @node Future of aclocal
3887 @subsection The Future of @command{aclocal}
3888 @cindex @command{aclocal}'s scheduled death
3890 @command{aclocal} is expected to disappear. This feature really
3891 should not be offered by Automake. Automake should focus on
3892 generating @file{Makefile}s; dealing with M4 macros really is
3893 Autoconf's job. The fact that some people install Automake just to use
3894 @command{aclocal}, but do not use @command{automake} otherwise is an
3895 indication of how that feature is misplaced.
3897 The new implementation will probably be done slightly differently.
3898 For instance, it could enforce the @file{m4/}-style layout discussed in
3901 We have no idea when and how this will happen. This has been
3902 discussed several times in the past, but someone still has to commit
3903 to that non-trivial task.
3905 From the user point of view, @command{aclocal}'s removal might turn
3906 out to be painful. There is a simple precaution that you may take to
3907 make that switch more seamless: never call @command{aclocal} yourself.
3908 Keep this guy under the exclusive control of @command{autoreconf} and
3909 Automake's rebuild rules. Hopefully you won't need to worry about
3910 things breaking, when @command{aclocal} disappears, because everything
3911 will have been taken care of. If otherwise you used to call
3912 @command{aclocal} directly yourself or from some script, you will
3913 quickly notice the change.
3915 Many packages come with a script called @file{bootstrap.sh} or
3916 @file{autogen.sh}, that will just call @command{aclocal},
3917 @command{libtoolize}, @command{gettextize} or @command{autopoint},
3918 @command{autoconf}, @command{autoheader}, and @command{automake} in
3919 the right order. Actually this is precisely what @command{autoreconf}
3920 can do for you. If your package has such a @file{bootstrap.sh} or
3921 @file{autogen.sh} script, consider using @command{autoreconf}. That
3922 should simplify its logic a lot (less things to maintain, yum!), it's
3923 even likely you will not need the script anymore, and more to the point
3924 you will not call @command{aclocal} directly anymore.
3926 For the time being, third-party packages should continue to install
3927 public macros into @file{/usr/share/aclocal/}. If @command{aclocal}
3928 is replaced by another tool it might make sense to rename the
3929 directory, but supporting @file{/usr/share/aclocal/} for backward
3930 compatibility should be really easy provided all macros are properly
3931 written (@pxref{Extending aclocal}).
3936 @section Autoconf macros supplied with Automake
3938 Automake ships with several Autoconf macros that you can use from your
3939 @file{configure.ac}. When you use one of them it will be included by
3940 @command{aclocal} in @file{aclocal.m4}.
3943 * Public Macros:: Macros that you can use.
3944 * Obsolete Macros:: Macros that you should stop using.
3945 * Private Macros:: Macros that you should not use.
3948 @c consider generating the following subsections automatically from m4 files.
3951 @subsection Public Macros
3955 @item AM_ENABLE_MULTILIB
3956 @acindex AM_ENABLE_MULTILIB
3957 This is used when a ``multilib'' library is being built. The first
3958 optional argument is the name of the @file{Makefile} being generated; it
3959 defaults to @samp{Makefile}. The second optional argument is used to find
3960 the top source directory; it defaults to the empty string (generally
3961 this should not be used unless you are familiar with the internals).
3964 @item AM_INIT_AUTOMAKE([OPTIONS])
3965 @itemx AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])
3966 @acindex AM_INIT_AUTOMAKE
3967 Runs many macros required for proper operation of the generated Makefiles.
3969 @vindex AUTOMAKE_OPTIONS
3970 This macro has two forms, the first of which is preferred.
3971 In this form, @code{AM_INIT_AUTOMAKE} is called with a
3972 single argument: a space-separated list of Automake options that should
3973 be applied to every @file{Makefile.am} in the tree. The effect is as if
3974 each option were listed in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
3977 The second, deprecated, form of @code{AM_INIT_AUTOMAKE} has two required
3978 arguments: the package and the version number. This form is
3979 obsolete because the @var{package} and @var{version} can be obtained
3980 from Autoconf's @code{AC_INIT} macro (which itself has an old and a new
3983 If your @file{configure.ac} has:
3986 AC_INIT([src/foo.c])
3987 AM_INIT_AUTOMAKE([mumble], [1.5])
3991 you can modernize it as follows:
3994 AC_INIT([mumble], [1.5])
3995 AC_CONFIG_SRCDIR([src/foo.c])
3999 Note that if you're upgrading your @file{configure.ac} from an earlier
4000 version of Automake, it is not always correct to simply move the
4001 package and version arguments from @code{AM_INIT_AUTOMAKE} directly to
4002 @code{AC_INIT}, as in the example above. The first argument to
4003 @code{AC_INIT} should be the name of your package (e.g., @samp{GNU
4004 Automake}), not the tarball name (e.g., @samp{automake}) that you used
4005 to pass to @code{AM_INIT_AUTOMAKE}. Autoconf tries to derive a
4006 tarball name from the package name, which should work for most but not
4007 all package names. (If it doesn't work for yours, you can use the
4008 four-argument form of @code{AC_INIT} to provide the tarball name
4011 @cindex @code{PACKAGE}, prevent definition
4012 @cindex @code{VERSION}, prevent definition
4014 By default this macro @code{AC_DEFINE}'s @code{PACKAGE} and
4015 @code{VERSION}. This can be avoided by passing the @option{no-define}
4018 AM_INIT_AUTOMAKE([gnits 1.5 no-define dist-bzip2])
4020 or by passing a third non-empty argument to the obsolete form.
4022 @item AM_PATH_LISPDIR
4023 @acindex AM_PATH_LISPDIR
4026 Searches for the program @command{emacs}, and, if found, sets the
4027 output variable @code{lispdir} to the full path to Emacs' site-lisp
4030 Note that this test assumes the @command{emacs} found to be a version
4031 that supports Emacs Lisp (such as GNU Emacs or XEmacs). Other
4032 emacsen can cause this test to hang (some, like old versions of
4033 MicroEmacs, start up in interactive mode, requiring @kbd{C-x C-c} to
4034 exit, which is hardly obvious for a non-emacs user). In most cases,
4035 however, you should be able to use @kbd{C-c} to kill the test. In
4036 order to avoid problems, you can set @env{EMACS} to ``no'' in the
4037 environment, or use the @option{--with-lispdir} option to
4038 @command{configure} to explicitly set the correct path (if you're sure
4039 you have an @command{emacs} that supports Emacs Lisp).
4041 @item AM_PROG_AR(@ovar{act-if-fail})
4044 You must use this macro when you use the archiver in your project, if
4045 you want support for unusual archivers such as Microsoft @command{lib}.
4046 The content of the optional argument is executed if the archiver
4047 interface is not recognized; the default action is to abort configure
4048 with an error message.
4054 Use this macro when you have assembly code in your project. This will
4055 choose the assembler for you (by default the C compiler) and set
4056 @code{CCAS}, and will also set @code{CCASFLAGS} if required.
4058 @item AM_PROG_CC_C_O
4059 @acindex AM_PROG_CC_C_O
4060 @acindex AC_PROG_CC_C_O
4061 This is like @code{AC_PROG_CC_C_O}, but it generates its results in
4062 the manner required by Automake. You must use this instead of
4063 @code{AC_PROG_CC_C_O} when you need this functionality, that is, when
4064 using per-target flags or subdir-objects with C sources.
4067 @acindex AM_PROG_LEX
4068 @acindex AC_PROG_LEX
4069 @cindex HP-UX 10, @command{lex} problems
4070 @cindex @command{lex} problems with HP-UX 10
4071 Like @code{AC_PROG_LEX} (@pxref{Particular Programs, , Particular
4072 Program Checks, autoconf, The Autoconf Manual}), but uses the
4073 @command{missing} script on systems that do not have @command{lex}.
4074 HP-UX 10 is one such system.
4077 @acindex AM_PROG_GCJ
4080 This macro finds the @command{gcj} program or causes an error. It sets
4081 @code{GCJ} and @code{GCJFLAGS}. @command{gcj} is the Java front-end to the
4082 GNU Compiler Collection.
4084 @item AM_PROG_UPC([@var{compiler-search-list}])
4085 @acindex AM_PROG_UPC
4087 Find a compiler for Unified Parallel C and define the @code{UPC}
4088 variable. The default @var{compiler-search-list} is @samp{upcc upc}.
4089 This macro will abort @command{configure} if no Unified Parallel C
4092 @item AM_SILENT_RULES
4093 @acindex AM_SILENT_RULES
4094 Enable the machinery for less verbose build output (@pxref{Options}).
4096 @item AM_WITH_DMALLOC
4097 @acindex AM_WITH_DMALLOC
4098 @cindex @command{dmalloc}, support for
4099 @vindex WITH_DMALLOC
4100 @opindex --with-dmalloc
4101 Add support for the @uref{http://dmalloc.com/, Dmalloc package}. If
4102 the user runs @command{configure} with @option{--with-dmalloc}, then
4103 define @code{WITH_DMALLOC} and add @option{-ldmalloc} to @code{LIBS}.
4108 @node Obsolete Macros
4109 @subsection Obsolete Macros
4110 @cindex obsolete macros
4113 Although using some of the following macros was required in past
4114 releases, you should not use any of them in new code. Running
4115 @command{autoupdate} should adjust your @file{configure.ac}
4116 automatically (@pxref{autoupdate Invocation, , Using
4117 @command{autoupdate} to Modernize @file{configure.ac}, autoconf, The
4122 @item AM_CONFIG_HEADER
4123 @acindex AM_CONFIG_HEADER
4124 Automake will generate rules to automatically regenerate the config
4125 header. This obsolete macro is a synonym of @code{AC_CONFIG_HEADERS}
4126 today (@pxref{Optional}).
4128 @item AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
4129 @acindex AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
4130 If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
4131 define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be
4132 found in @file{<termios.h>}. This macro is obsolete, you should
4133 use Autoconf's @code{AC_HEADER_TIOCGWINSZ} instead.
4135 @item AM_PROG_MKDIR_P
4136 @acindex AM_PROG_MKDIR_P
4137 @cindex @code{mkdir -p}, macro check
4141 From Automake 1.8 to 1.9.6 this macro used to define the output
4142 variable @code{mkdir_p} to one of @code{mkdir -p}, @code{install-sh
4143 -d}, or @code{mkinstalldirs}.
4145 Nowadays Autoconf provides a similar functionality with
4146 @code{AC_PROG_MKDIR_P} (@pxref{Particular Programs, , Particular
4147 Program Checks, autoconf, The Autoconf Manual}), however this defines
4148 the output variable @code{MKDIR_P} instead. Therefore
4149 @code{AM_PROG_MKDIR_P} has been rewritten as a thin wrapper around
4150 @code{AC_PROG_MKDIR_P} to define @code{mkdir_p} to the same value as
4151 @code{MKDIR_P} for backward compatibility.
4153 If you are using Automake, there is normally no reason to call this
4154 macro, because @code{AM_INIT_AUTOMAKE} already does so. However, make
4155 sure that the custom rules in your @file{Makefile}s use
4156 @code{$(MKDIR_P)} and not @code{$(mkdir_p)}. Even if both variables
4157 still work, the latter should be considered obsolete.
4159 If you are not using Automake, please call @code{AC_PROG_MKDIR_P}
4160 instead of @code{AM_PROG_MKDIR_P}.
4162 @item AM_SYS_POSIX_TERMIOS
4163 @acindex AM_SYS_POSIX_TERMIOS
4164 @cindex POSIX termios headers
4165 @cindex termios POSIX headers
4166 Check to see if POSIX termios headers and functions are available on the
4167 system. If so, set the shell variable @code{am_cv_sys_posix_termios} to
4168 @samp{yes}. If not, set the variable to @samp{no}. This macro is obsolete,
4169 you should use Autoconf's @code{AC_SYS_POSIX_TERMIOS} instead.
4174 @node Private Macros
4175 @subsection Private Macros
4177 The following macros are private macros you should not call directly.
4178 They are called by the other public macros when appropriate. Do not
4179 rely on them, as they might be changed in a future version. Consider
4180 them as implementation details; or better, do not consider them at all:
4184 @item _AM_DEPENDENCIES
4185 @itemx AM_SET_DEPDIR
4187 @itemx AM_OUTPUT_DEPENDENCY_COMMANDS
4188 These macros are used to implement Automake's automatic dependency
4189 tracking scheme. They are called automatically by Automake when
4190 required, and there should be no need to invoke them manually.
4192 @item AM_MAKE_INCLUDE
4193 This macro is used to discover how the user's @command{make} handles
4194 @code{include} statements. This macro is automatically invoked when
4195 needed; there should be no need to invoke it manually.
4197 @item AM_PROG_INSTALL_STRIP
4198 This is used to find a version of @code{install} that can be used to
4199 strip a program at installation time. This macro is automatically
4200 included when required.
4202 @item AM_SANITY_CHECK
4203 This checks to make sure that a file created in the build directory is
4204 newer than a file in the source directory. This can fail on systems
4205 where the clock is set incorrectly. This macro is automatically run
4206 from @code{AM_INIT_AUTOMAKE}.
4212 @chapter Directories
4214 For simple projects that distribute all files in the same directory
4215 it is enough to have a single @file{Makefile.am} that builds
4216 everything in place.
4218 In larger projects it is common to organize files in different
4219 directories, in a tree. For instance one directory per program, per
4220 library or per module. The traditional approach is to build these
4221 subdirectories recursively: each directory contains its @file{Makefile}
4222 (generated from @file{Makefile.am}), and when @command{make} is run
4223 from the top level directory it enters each subdirectory in turn to
4227 * Subdirectories:: Building subdirectories recursively
4228 * Conditional Subdirectories:: Conditionally not building directories
4229 * Alternative:: Subdirectories without recursion
4230 * Subpackages:: Nesting packages
4233 @node Subdirectories
4234 @section Recursing subdirectories
4236 @cindex @code{SUBDIRS}, explained
4238 In packages with subdirectories, the top level @file{Makefile.am} must
4239 tell Automake which subdirectories are to be built. This is done via
4240 the @code{SUBDIRS} variable.
4243 The @code{SUBDIRS} variable holds a list of subdirectories in which
4244 building of various sorts can occur. The rules for many targets
4245 (e.g., @code{all}) in the generated @file{Makefile} will run commands
4246 both locally and in all specified subdirectories. Note that the
4247 directories listed in @code{SUBDIRS} are not required to contain
4248 @file{Makefile.am}s; only @file{Makefile}s (after configuration).
4249 This allows inclusion of libraries from packages that do not use
4250 Automake (such as @code{gettext}; see also @ref{Third-Party
4253 In packages that use subdirectories, the top-level @file{Makefile.am} is
4254 often very short. For instance, here is the @file{Makefile.am} from the
4255 GNU Hello distribution:
4258 EXTRA_DIST = BUGS ChangeLog.O README-alpha
4259 SUBDIRS = doc intl po src tests
4262 When Automake invokes @command{make} in a subdirectory, it uses the value
4263 of the @code{MAKE} variable. It passes the value of the variable
4264 @code{AM_MAKEFLAGS} to the @command{make} invocation; this can be set in
4265 @file{Makefile.am} if there are flags you must always pass to
4268 @vindex AM_MAKEFLAGS
4270 The directories mentioned in @code{SUBDIRS} are usually direct
4271 children of the current directory, each subdirectory containing its
4272 own @file{Makefile.am} with a @code{SUBDIRS} pointing to deeper
4273 subdirectories. Automake can be used to construct packages of
4274 arbitrary depth this way.
4276 By default, Automake generates @file{Makefiles} that work depth-first
4277 in postfix order: the subdirectories are built before the current
4278 directory. However, it is possible to change this ordering. You can
4279 do this by putting @samp{.} into @code{SUBDIRS}. For instance,
4280 putting @samp{.} first will cause a prefix ordering of
4286 SUBDIRS = lib src . test
4290 will cause @file{lib/} to be built before @file{src/}, then the
4291 current directory will be built, finally the @file{test/} directory
4292 will be built. It is customary to arrange test directories to be
4293 built after everything else since they are meant to test what has
4296 All @code{clean} rules are run in reverse order of build rules.
4298 @node Conditional Subdirectories
4299 @section Conditional Subdirectories
4300 @cindex Subdirectories, building conditionally
4301 @cindex Conditional subdirectories
4302 @cindex @code{SUBDIRS}, conditional
4303 @cindex Conditional @code{SUBDIRS}
4305 It is possible to define the @code{SUBDIRS} variable conditionally if,
4306 like in the case of GNU Inetutils, you want to only build a subset of
4309 To illustrate how this works, let's assume we have two directories
4310 @file{src/} and @file{opt/}. @file{src/} should always be built, but we
4311 want to decide in @command{configure} whether @file{opt/} will be built
4312 or not. (For this example we will assume that @file{opt/} should be
4313 built when the variable @samp{$want_opt} was set to @samp{yes}.)
4315 Running @command{make} should thus recurse into @file{src/} always, and
4316 then maybe in @file{opt/}.
4318 However @samp{make dist} should always recurse into both @file{src/}
4319 and @file{opt/}. Because @file{opt/} should be distributed even if it
4320 is not needed in the current configuration. This means
4321 @file{opt/Makefile} should be created @emph{unconditionally}.
4323 There are two ways to setup a project like this. You can use Automake
4324 conditionals (@pxref{Conditionals}) or use Autoconf @code{AC_SUBST}
4325 variables (@pxref{Setting Output Variables, , Setting Output
4326 Variables, autoconf, The Autoconf Manual}). Using Automake
4327 conditionals is the preferred solution. Before we illustrate these
4328 two possibilities, let's introduce @code{DIST_SUBDIRS}.
4331 * SUBDIRS vs DIST_SUBDIRS:: Two sets of directories
4332 * Subdirectories with AM_CONDITIONAL:: Specifying conditional subdirectories
4333 * Subdirectories with AC_SUBST:: Another way for conditional recursion
4334 * Unconfigured Subdirectories:: Not even creating a @samp{Makefile}
4337 @node SUBDIRS vs DIST_SUBDIRS
4338 @subsection @code{SUBDIRS} vs.@: @code{DIST_SUBDIRS}
4339 @cindex @code{DIST_SUBDIRS}, explained
4341 Automake considers two sets of directories, defined by the variables
4342 @code{SUBDIRS} and @code{DIST_SUBDIRS}.
4344 @code{SUBDIRS} contains the subdirectories of the current directory
4345 that must be built (@pxref{Subdirectories}). It must be defined
4346 manually; Automake will never guess a directory is to be built. As we
4347 will see in the next two sections, it is possible to define it
4348 conditionally so that some directory will be omitted from the build.
4350 @code{DIST_SUBDIRS} is used in rules that need to recurse in all
4351 directories, even those that have been conditionally left out of the
4352 build. Recall our example where we may not want to build subdirectory
4353 @file{opt/}, but yet we want to distribute it? This is where
4354 @code{DIST_SUBDIRS} comes into play: @samp{opt} may not appear in
4355 @code{SUBDIRS}, but it must appear in @code{DIST_SUBDIRS}.
4357 Precisely, @code{DIST_SUBDIRS} is used by @samp{make
4358 maintainer-clean}, @samp{make distclean} and @samp{make dist}. All
4359 other recursive rules use @code{SUBDIRS}.
4361 If @code{SUBDIRS} is defined conditionally using Automake
4362 conditionals, Automake will define @code{DIST_SUBDIRS} automatically
4363 from the possible values of @code{SUBDIRS} in all conditions.
4365 If @code{SUBDIRS} contains @code{AC_SUBST} variables,
4366 @code{DIST_SUBDIRS} will not be defined correctly because Automake
4367 does not know the possible values of these variables. In this case
4368 @code{DIST_SUBDIRS} needs to be defined manually.
4370 @node Subdirectories with AM_CONDITIONAL
4371 @subsection Subdirectories with @code{AM_CONDITIONAL}
4372 @cindex @code{SUBDIRS} and @code{AM_CONDITIONAL}
4373 @cindex @code{AM_CONDITIONAL} and @code{SUBDIRS}
4375 @c Keep in sync with subcond2.test.
4377 @file{configure} should output the @file{Makefile} for each directory
4378 and define a condition into which @file{opt/} should be built.
4382 AM_CONDITIONAL([COND_OPT], [test "$want_opt" = yes])
4383 AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
4387 Then @code{SUBDIRS} can be defined in the top-level @file{Makefile.am}
4394 SUBDIRS = src $(MAYBE_OPT)
4397 As you can see, running @command{make} will rightly recurse into
4398 @file{src/} and maybe @file{opt/}.
4400 @vindex DIST_SUBDIRS
4401 As you can't see, running @samp{make dist} will recurse into both
4402 @file{src/} and @file{opt/} directories because @samp{make dist}, unlike
4403 @samp{make all}, doesn't use the @code{SUBDIRS} variable. It uses the
4404 @code{DIST_SUBDIRS} variable.
4406 In this case Automake will define @samp{DIST_SUBDIRS = src opt}
4407 automatically because it knows that @code{MAYBE_OPT} can contain
4408 @samp{opt} in some condition.
4410 @node Subdirectories with AC_SUBST
4411 @subsection Subdirectories with @code{AC_SUBST}
4412 @cindex @code{SUBDIRS} and @code{AC_SUBST}
4413 @cindex @code{AC_SUBST} and @code{SUBDIRS}
4415 @c Keep in sync with subcond3.test.
4417 Another possibility is to define @code{MAYBE_OPT} from
4418 @file{./configure} using @code{AC_SUBST}:
4422 if test "$want_opt" = yes; then
4427 AC_SUBST([MAYBE_OPT])
4428 AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
4432 In this case the top-level @file{Makefile.am} should look as follows.
4435 SUBDIRS = src $(MAYBE_OPT)
4436 DIST_SUBDIRS = src opt
4439 The drawback is that since Automake cannot guess what the possible
4440 values of @code{MAYBE_OPT} are, it is necessary to define
4441 @code{DIST_SUBDIRS}.
4443 @node Unconfigured Subdirectories
4444 @subsection Unconfigured Subdirectories
4445 @cindex Subdirectories, configured conditionally
4447 The semantics of @code{DIST_SUBDIRS} are often misunderstood by some
4448 users that try to @emph{configure and build} subdirectories
4449 conditionally. Here by configuring we mean creating the
4450 @file{Makefile} (it might also involve running a nested
4451 @command{configure} script: this is a costly operation that explains
4452 why people want to do it conditionally, but only the @file{Makefile}
4453 is relevant to the discussion).
4455 The above examples all assume that every @file{Makefile} is created,
4456 even in directories that are not going to be built. The simple reason
4457 is that we want @samp{make dist} to distribute even the directories
4458 that are not being built (e.g., platform-dependent code), hence
4459 @file{make dist} must recurse into the subdirectory, hence this
4460 directory must be configured and appear in @code{DIST_SUBDIRS}.
4462 Building packages that do not configure every subdirectory is a tricky
4463 business, and we do not recommend it to the novice as it is easy to
4464 produce an incomplete tarball by mistake. We will not discuss this
4465 topic in depth here, yet for the adventurous here are a few rules to
4470 @item @code{SUBDIRS} should always be a subset of @code{DIST_SUBDIRS}.
4472 It makes little sense to have a directory in @code{SUBDIRS} that
4473 is not in @code{DIST_SUBDIRS}. Think of the former as a way to tell
4474 which directories listed in the latter should be built.
4475 @item Any directory listed in @code{DIST_SUBDIRS} and @code{SUBDIRS}
4478 I.e., the @file{Makefile} must exists or the recursive @command{make}
4479 rules will not be able to process the directory.
4480 @item Any configured directory must be listed in @code{DIST_SUBDIRS}.
4482 So that the cleaning rules remove the generated @file{Makefile}s.
4483 It would be correct to see @code{DIST_SUBDIRS} as a variable that
4484 lists all the directories that have been configured.
4488 In order to prevent recursion in some unconfigured directory you
4489 must therefore ensure that this directory does not appear in
4490 @code{DIST_SUBDIRS} (and @code{SUBDIRS}). For instance, if you define
4491 @code{SUBDIRS} conditionally using @code{AC_SUBST} and do not define
4492 @code{DIST_SUBDIRS} explicitly, it will be default to
4493 @samp{$(SUBDIRS)}; another possibility is to force @code{DIST_SUBDIRS
4496 Of course, directories that are omitted from @code{DIST_SUBDIRS} will
4497 not be distributed unless you make other arrangements for this to
4498 happen (for instance, always running @samp{make dist} in a
4499 configuration where all directories are known to appear in
4500 @code{DIST_SUBDIRS}; or writing a @code{dist-hook} target to
4501 distribute these directories).
4503 @cindex Subdirectories, not distributed
4504 In few packages, unconfigured directories are not even expected to
4505 be distributed. Although these packages do not require the
4506 aforementioned extra arrangements, there is another pitfall. If the
4507 name of a directory appears in @code{SUBDIRS} or @code{DIST_SUBDIRS},
4508 @command{automake} will make sure the directory exists. Consequently
4509 @command{automake} cannot be run on such a distribution when one
4510 directory has been omitted. One way to avoid this check is to use the
4511 @code{AC_SUBST} method to declare conditional directories; since
4512 @command{automake} does not know the values of @code{AC_SUBST}
4513 variables it cannot ensure the corresponding directory exists.
4516 @section An Alternative Approach to Subdirectories
4518 If you've ever read Peter Miller's excellent paper,
4519 @uref{http://miller.emu.id.au/pmiller/books/rmch/,
4520 Recursive Make Considered Harmful}, the preceding sections on the use of
4521 subdirectories will probably come as unwelcome advice. For those who
4522 haven't read the paper, Miller's main thesis is that recursive
4523 @command{make} invocations are both slow and error-prone.
4525 Automake provides sufficient cross-directory support @footnote{We
4526 believe. This work is new and there are probably warts.
4527 @xref{Introduction}, for information on reporting bugs.} to enable you
4528 to write a single @file{Makefile.am} for a complex multi-directory
4532 By default an installable file specified in a subdirectory will have its
4533 directory name stripped before installation. For instance, in this
4534 example, the header file will be installed as
4535 @file{$(includedir)/stdio.h}:
4538 include_HEADERS = inc/stdio.h
4542 @cindex @code{nobase_} prefix
4543 @cindex Path stripping, avoiding
4544 @cindex Avoiding path stripping
4546 However, the @samp{nobase_} prefix can be used to circumvent this path
4547 stripping. In this example, the header file will be installed as
4548 @file{$(includedir)/sys/types.h}:
4551 nobase_include_HEADERS = sys/types.h
4554 @cindex @code{nobase_} and @code{dist_} or @code{nodist_}
4555 @cindex @code{dist_} and @code{nobase_}
4556 @cindex @code{nodist_} and @code{nobase_}
4560 @samp{nobase_} should be specified first when used in conjunction with
4561 either @samp{dist_} or @samp{nodist_} (@pxref{Fine-grained Distribution
4562 Control}). For instance:
4565 nobase_dist_pkgdata_DATA = images/vortex.pgm sounds/whirl.ogg
4568 Finally, note that a variable using the @samp{nobase_} prefix can
4569 often be replaced by several variables, one for each destination
4570 directory (@pxref{Uniform}). For instance, the last example could be
4571 rewritten as follows:
4573 @c Keep in sync with primary-prefix-couples-documented-valid.test.
4575 imagesdir = $(pkgdatadir)/images
4576 soundsdir = $(pkgdatadir)/sounds
4577 dist_images_DATA = images/vortex.pgm
4578 dist_sounds_DATA = sounds/whirl.ogg
4582 This latter syntax makes it possible to change one destination
4583 directory without changing the layout of the source tree.
4585 Currently, @samp{nobase_*_LTLIBRARIES} are the only exception to this
4586 rule, in that there is no particular installation order guarantee for
4587 an otherwise equivalent set of variables without @samp{nobase_} prefix.
4590 @section Nesting Packages
4591 @cindex Nesting packages
4593 @acindex AC_CONFIG_SUBDIRS
4594 @acindex AC_CONFIG_AUX_DIR
4597 In the GNU Build System, packages can be nested to arbitrary depth.
4598 This means that a package can embed other packages with their own
4599 @file{configure}, @file{Makefile}s, etc.
4601 These other packages should just appear as subdirectories of their
4602 parent package. They must be listed in @code{SUBDIRS} like other
4603 ordinary directories. However the subpackage's @file{Makefile}s
4604 should be output by its own @file{configure} script, not by the
4605 parent's @file{configure}. This is achieved using the
4606 @code{AC_CONFIG_SUBDIRS} Autoconf macro (@pxref{Subdirectories,
4607 AC_CONFIG_SUBDIRS, Configuring Other Packages in Subdirectories,
4608 autoconf, The Autoconf Manual}).
4610 Here is an example package for an @code{arm} program that links with
4611 a @code{hand} library that is a nested package in subdirectory
4614 @code{arm}'s @file{configure.ac}:
4617 AC_INIT([arm], [1.0])
4618 AC_CONFIG_AUX_DIR([.])
4621 AC_CONFIG_FILES([Makefile])
4622 # Call hand's ./configure script recursively.
4623 AC_CONFIG_SUBDIRS([hand])
4627 @code{arm}'s @file{Makefile.am}:
4630 # Build the library in the hand subdirectory first.
4633 # Include hand's header when compiling this directory.
4634 AM_CPPFLAGS = -I$(srcdir)/hand
4638 # link with the hand library.
4639 arm_LDADD = hand/libhand.a
4642 Now here is @code{hand}'s @file{hand/configure.ac}:
4645 AC_INIT([hand], [1.2])
4646 AC_CONFIG_AUX_DIR([.])
4651 AC_CONFIG_FILES([Makefile])
4656 and its @file{hand/Makefile.am}:
4659 lib_LIBRARIES = libhand.a
4660 libhand_a_SOURCES = hand.c
4663 When @samp{make dist} is run from the top-level directory it will
4664 create an archive @file{arm-1.0.tar.gz} that contains the @code{arm}
4665 code as well as the @file{hand} subdirectory. This package can be
4666 built and installed like any ordinary package, with the usual
4667 @samp{./configure && make && make install} sequence (the @code{hand}
4668 subpackage will be built and installed by the process).
4670 When @samp{make dist} is run from the hand directory, it will create a
4671 self-contained @file{hand-1.2.tar.gz} archive. So although it appears
4672 to be embedded in another package, it can still be used separately.
4674 The purpose of the @samp{AC_CONFIG_AUX_DIR([.])} instruction is to
4675 force Automake and Autoconf to search for auxiliary scripts in the
4676 current directory. For instance, this means that there will be two
4677 copies of @file{install-sh}: one in the top-level of the @code{arm}
4678 package, and another one in the @file{hand/} subdirectory for the
4679 @code{hand} package.
4681 The historical default is to search for these auxiliary scripts in
4682 the parent directory and the grandparent directory. So if the
4683 @samp{AC_CONFIG_AUX_DIR([.])} line was removed from
4684 @file{hand/configure.ac}, that subpackage would share the auxiliary
4685 script of the @code{arm} package. This may looks like a gain in size
4686 (a few kilobytes), but it is actually a loss of modularity as the
4687 @code{hand} subpackage is no longer self-contained (@samp{make dist}
4688 in the subdirectory will not work anymore).
4690 Packages that do not use Automake need more work to be integrated this
4691 way. @xref{Third-Party Makefiles}.
4694 @chapter Building Programs and Libraries
4696 A large part of Automake's functionality is dedicated to making it easy
4697 to build programs and libraries.
4700 * A Program:: Building a program
4701 * A Library:: Building a library
4702 * A Shared Library:: Building a Libtool library
4703 * Program and Library Variables:: Variables controlling program and
4705 * Default _SOURCES:: Default source files
4706 * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
4707 * Program Variables:: Variables used when building a program
4708 * Yacc and Lex:: Yacc and Lex support
4709 * C++ Support:: Compiling C++ sources
4710 * Objective C Support:: Compiling Objective C sources
4711 * Unified Parallel C Support:: Compiling Unified Parallel C sources
4712 * Assembly Support:: Compiling assembly sources
4713 * Fortran 77 Support:: Compiling Fortran 77 sources
4714 * Fortran 9x Support:: Compiling Fortran 9x sources
4715 * Java Support with gcj:: Compiling Java sources using gcj
4716 * Vala Support:: Compiling Vala sources
4717 * Support for Other Languages:: Compiling other languages
4718 * Dependencies:: Automatic dependency tracking
4719 * EXEEXT:: Support for executable extensions
4724 @section Building a program
4726 In order to build a program, you need to tell Automake which sources
4727 are part of it, and which libraries it should be linked with.
4729 This section also covers conditional compilation of sources or
4730 programs. Most of the comments about these also apply to libraries
4731 (@pxref{A Library}) and libtool libraries (@pxref{A Shared Library}).
4734 * Program Sources:: Defining program sources
4735 * Linking:: Linking with libraries or extra objects
4736 * Conditional Sources:: Handling conditional sources
4737 * Conditional Programs:: Building a program conditionally
4740 @node Program Sources
4741 @subsection Defining program sources
4743 @cindex @code{PROGRAMS}, @code{bindir}
4745 @vindex bin_PROGRAMS
4746 @vindex sbin_PROGRAMS
4747 @vindex libexec_PROGRAMS
4748 @vindex pkglibexec_PROGRAMS
4749 @vindex noinst_PROGRAMS
4750 @vindex check_PROGRAMS
4752 In a directory containing source that gets built into a program (as
4753 opposed to a library or a script), the @code{PROGRAMS} primary is used.
4754 Programs can be installed in @code{bindir}, @code{sbindir},
4755 @code{libexecdir}, @code{pkglibexecdir}, or not at all
4756 (@code{noinst_}). They can also be built only for @samp{make check}, in
4757 which case the prefix is @samp{check_}.
4762 bin_PROGRAMS = hello
4765 In this simple case, the resulting @file{Makefile.in} will contain code
4766 to generate a program named @code{hello}.
4768 Associated with each program are several assisting variables that are
4769 named after the program. These variables are all optional, and have
4770 reasonable defaults. Each variable, its use, and default is spelled out
4771 below; we use the ``hello'' example throughout.
4773 The variable @code{hello_SOURCES} is used to specify which source files
4774 get built into an executable:
4777 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
4780 This causes each mentioned @file{.c} file to be compiled into the
4781 corresponding @file{.o}. Then all are linked to produce @file{hello}.
4783 @cindex @code{_SOURCES} primary, defined
4784 @cindex @code{SOURCES} primary, defined
4785 @cindex Primary variable, @code{SOURCES}
4788 If @code{hello_SOURCES} is not specified, then it defaults to the single
4789 file @file{hello.c} (@pxref{Default _SOURCES}).
4793 Multiple programs can be built in a single directory. Multiple programs
4794 can share a single source file, which must be listed in each
4795 @code{_SOURCES} definition.
4797 @cindex Header files in @code{_SOURCES}
4798 @cindex @code{_SOURCES} and header files
4800 Header files listed in a @code{_SOURCES} definition will be included in
4801 the distribution but otherwise ignored. In case it isn't obvious, you
4802 should not include the header file generated by @file{configure} in a
4803 @code{_SOURCES} variable; this file should not be distributed. Lex
4804 (@file{.l}) and Yacc (@file{.y}) files can also be listed; see @ref{Yacc
4809 @subsection Linking the program
4811 If you need to link against libraries that are not found by
4812 @command{configure}, you can use @code{LDADD} to do so. This variable is
4813 used to specify additional objects or libraries to link with; it is
4814 inappropriate for specifying specific linker flags, you should use
4815 @code{AM_LDFLAGS} for this purpose.
4819 @cindex @code{prog_LDADD}, defined
4821 Sometimes, multiple programs are built in one directory but do not share
4822 the same link-time requirements. In this case, you can use the
4823 @code{@var{prog}_LDADD} variable (where @var{prog} is the name of the
4824 program as it appears in some @code{_PROGRAMS} variable, and usually
4825 written in lowercase) to override @code{LDADD}. If this variable exists
4826 for a given program, then that program is not linked using @code{LDADD}.
4829 For instance, in GNU cpio, @code{pax}, @code{cpio} and @code{mt} are
4830 linked against the library @file{libcpio.a}. However, @code{rmt} is
4831 built in the same directory, and has no such link requirement. Also,
4832 @code{mt} and @code{rmt} are only built on certain architectures. Here
4833 is what cpio's @file{src/Makefile.am} looks like (abridged):
4836 bin_PROGRAMS = cpio pax $(MT)
4837 libexec_PROGRAMS = $(RMT)
4838 EXTRA_PROGRAMS = mt rmt
4840 LDADD = ../lib/libcpio.a $(INTLLIBS)
4843 cpio_SOURCES = @dots{}
4844 pax_SOURCES = @dots{}
4845 mt_SOURCES = @dots{}
4846 rmt_SOURCES = @dots{}
4849 @cindex @code{_LDFLAGS}, defined
4850 @vindex maude_LDFLAGS
4851 @code{@var{prog}_LDADD} is inappropriate for passing program-specific
4852 linker flags (except for @option{-l}, @option{-L}, @option{-dlopen} and
4853 @option{-dlpreopen}). So, use the @code{@var{prog}_LDFLAGS} variable for
4856 @cindex @code{_DEPENDENCIES}, defined
4857 @vindex maude_DEPENDENCIES
4858 @vindex EXTRA_maude_DEPENDENCIES
4859 It is also occasionally useful to have a program depend on some other
4860 target that is not actually part of that program. This can be done
4861 using either the @code{@var{prog}_DEPENDENCIES} or the
4862 @code{EXTRA_@var{prog}_DEPENDENCIES} variable. Each program depends on
4863 the contents both variables, but no further interpretation is done.
4865 Since these dependencies are associated to the link rule used to
4866 create the programs they should normally list files used by the link
4867 command. That is @file{*.$(OBJEXT)}, @file{*.a}, or @file{*.la}
4868 files. In rare cases you may need to add other kinds of files such as
4869 linker scripts, but @emph{listing a source file in
4870 @code{_DEPENDENCIES} is wrong}. If some source file needs to be built
4871 before all the components of a program are built, consider using the
4872 @code{BUILT_SOURCES} variable instead (@pxref{Sources}).
4874 If @code{@var{prog}_DEPENDENCIES} is not supplied, it is computed by
4875 Automake. The automatically-assigned value is the contents of
4876 @code{@var{prog}_LDADD}, with most configure substitutions, @option{-l},
4877 @option{-L}, @option{-dlopen} and @option{-dlpreopen} options removed. The
4878 configure substitutions that are left in are only @samp{$(LIBOBJS)} and
4879 @samp{$(ALLOCA)}; these are left because it is known that they will not
4880 cause an invalid value for @code{@var{prog}_DEPENDENCIES} to be
4883 @ref{Conditional Sources} shows a situation where @code{_DEPENDENCIES}
4886 The @code{EXTRA_@var{prog}_DEPENDENCIES} may be useful for cases where
4887 you merely want to augment the @command{automake}-generated
4888 @code{@var{prog}_DEPENDENCIES} rather than replacing it.
4890 @cindex @code{LDADD} and @option{-l}
4891 @cindex @option{-l} and @code{LDADD}
4892 We recommend that you avoid using @option{-l} options in @code{LDADD}
4893 or @code{@var{prog}_LDADD} when referring to libraries built by your
4894 package. Instead, write the file name of the library explicitly as in
4895 the above @code{cpio} example. Use @option{-l} only to list
4896 third-party libraries. If you follow this rule, the default value of
4897 @code{@var{prog}_DEPENDENCIES} will list all your local libraries and
4898 omit the other ones.
4901 @node Conditional Sources
4902 @subsection Conditional compilation of sources
4904 You can't put a configure substitution (e.g., @samp{@@FOO@@} or
4905 @samp{$(FOO)} where @code{FOO} is defined via @code{AC_SUBST}) into a
4906 @code{_SOURCES} variable. The reason for this is a bit hard to
4907 explain, but suffice to say that it simply won't work. Automake will
4908 give an error if you try to do this.
4910 Fortunately there are two other ways to achieve the same result. One is
4911 to use configure substitutions in @code{_LDADD} variables, the other is
4912 to use an Automake conditional.
4914 @subsubheading Conditional Compilation using @code{_LDADD} Substitutions
4916 @cindex @code{EXTRA_prog_SOURCES}, defined
4918 Automake must know all the source files that could possibly go into a
4919 program, even if not all the files are built in every circumstance. Any
4920 files that are only conditionally built should be listed in the
4921 appropriate @code{EXTRA_} variable. For instance, if
4922 @file{hello-linux.c} or @file{hello-generic.c} were conditionally included
4923 in @code{hello}, the @file{Makefile.am} would contain:
4926 bin_PROGRAMS = hello
4927 hello_SOURCES = hello-common.c
4928 EXTRA_hello_SOURCES = hello-linux.c hello-generic.c
4929 hello_LDADD = $(HELLO_SYSTEM)
4930 hello_DEPENDENCIES = $(HELLO_SYSTEM)
4934 You can then setup the @samp{$(HELLO_SYSTEM)} substitution from
4935 @file{configure.ac}:
4940 *linux*) HELLO_SYSTEM='hello-linux.$(OBJEXT)' ;;
4941 *) HELLO_SYSTEM='hello-generic.$(OBJEXT)' ;;
4943 AC_SUBST([HELLO_SYSTEM])
4947 In this case, the variable @code{HELLO_SYSTEM} should be replaced by
4948 either @file{hello-linux.o} or @file{hello-generic.o}, and added to
4949 both @code{hello_DEPENDENCIES} and @code{hello_LDADD} in order to be
4950 built and linked in.
4952 @subsubheading Conditional Compilation using Automake Conditionals
4954 An often simpler way to compile source files conditionally is to use
4955 Automake conditionals. For instance, you could use this
4956 @file{Makefile.am} construct to build the same @file{hello} example:
4959 bin_PROGRAMS = hello
4961 hello_SOURCES = hello-linux.c hello-common.c
4963 hello_SOURCES = hello-generic.c hello-common.c
4967 In this case, @file{configure.ac} should setup the @code{LINUX}
4968 conditional using @code{AM_CONDITIONAL} (@pxref{Conditionals}).
4970 When using conditionals like this you don't need to use the
4971 @code{EXTRA_} variable, because Automake will examine the contents of
4972 each variable to construct the complete list of source files.
4974 If your program uses a lot of files, you will probably prefer a
4975 conditional @samp{+=}.
4978 bin_PROGRAMS = hello
4979 hello_SOURCES = hello-common.c
4981 hello_SOURCES += hello-linux.c
4983 hello_SOURCES += hello-generic.c
4987 @node Conditional Programs
4988 @subsection Conditional compilation of programs
4989 @cindex Conditional programs
4990 @cindex Programs, conditional
4992 Sometimes it is useful to determine the programs that are to be built
4993 at configure time. For instance, GNU @code{cpio} only builds
4994 @code{mt} and @code{rmt} under special circumstances. The means to
4995 achieve conditional compilation of programs are the same you can use
4996 to compile source files conditionally: substitutions or conditionals.
4998 @subsubheading Conditional Programs using @command{configure} Substitutions
5000 @vindex EXTRA_PROGRAMS
5001 @cindex @code{EXTRA_PROGRAMS}, defined
5002 In this case, you must notify Automake of all the programs that can
5003 possibly be built, but at the same time cause the generated
5004 @file{Makefile.in} to use the programs specified by @command{configure}.
5005 This is done by having @command{configure} substitute values into each
5006 @code{_PROGRAMS} definition, while listing all optionally built programs
5007 in @code{EXTRA_PROGRAMS}.
5010 bin_PROGRAMS = cpio pax $(MT)
5011 libexec_PROGRAMS = $(RMT)
5012 EXTRA_PROGRAMS = mt rmt
5015 As explained in @ref{EXEEXT}, Automake will rewrite
5016 @code{bin_PROGRAMS}, @code{libexec_PROGRAMS}, and
5017 @code{EXTRA_PROGRAMS}, appending @samp{$(EXEEXT)} to each binary.
5018 Obviously it cannot rewrite values obtained at run-time through
5019 @command{configure} substitutions, therefore you should take care of
5020 appending @samp{$(EXEEXT)} yourself, as in @samp{AC_SUBST([MT],
5021 ['mt$@{EXEEXT@}'])}.
5023 @subsubheading Conditional Programs using Automake Conditionals
5025 You can also use Automake conditionals (@pxref{Conditionals}) to
5026 select programs to be built. In this case you don't have to worry
5027 about @samp{$(EXEEXT)} or @code{EXTRA_PROGRAMS}.
5029 @c Keep in sync with exeext.test.
5031 bin_PROGRAMS = cpio pax
5036 libexec_PROGRAMS = rmt
5042 @section Building a library
5044 @cindex @code{_LIBRARIES} primary, defined
5045 @cindex @code{LIBRARIES} primary, defined
5046 @cindex Primary variable, @code{LIBRARIES}
5049 @vindex lib_LIBRARIES
5050 @vindex pkglib_LIBRARIES
5051 @vindex noinst_LIBRARIES
5053 Building a library is much like building a program. In this case, the
5054 name of the primary is @code{LIBRARIES}. Libraries can be installed in
5055 @code{libdir} or @code{pkglibdir}.
5057 @xref{A Shared Library}, for information on how to build shared
5058 libraries using libtool and the @code{LTLIBRARIES} primary.
5060 Each @code{_LIBRARIES} variable is a list of the libraries to be built.
5061 For instance, to create a library named @file{libcpio.a}, but not install
5062 it, you would write:
5065 noinst_LIBRARIES = libcpio.a
5066 libcpio_a_SOURCES = @dots{}
5069 The sources that go into a library are determined exactly as they are
5070 for programs, via the @code{_SOURCES} variables. Note that the library
5071 name is canonicalized (@pxref{Canonicalization}), so the @code{_SOURCES}
5072 variable corresponding to @file{libcpio.a} is @samp{libcpio_a_SOURCES},
5073 not @samp{libcpio.a_SOURCES}.
5075 @vindex maude_LIBADD
5076 Extra objects can be added to a library using the
5077 @code{@var{library}_LIBADD} variable. This should be used for objects
5078 determined by @command{configure}. Again from @code{cpio}:
5080 @c Keep in sync with pr401c.test.
5082 libcpio_a_LIBADD = $(LIBOBJS) $(ALLOCA)
5085 In addition, sources for extra objects that will not exist until
5086 configure-time must be added to the @code{BUILT_SOURCES} variable
5089 Building a static library is done by compiling all object files, then
5090 by invoking @samp{$(AR) $(ARFLAGS)} followed by the name of the
5091 library and the list of objects, and finally by calling
5092 @samp{$(RANLIB)} on that library. You should call
5093 @code{AC_PROG_RANLIB} from your @file{configure.ac} to define
5094 @code{RANLIB} (Automake will complain otherwise). You should also
5095 call @code{AM_PROG_AR} to define @code{AR}, in order to support unusual
5096 archivers such as Microsoft lib. @code{ARFLAGS} will default to
5097 @code{cru}; you can override this variable by setting it in your
5098 @file{Makefile.am} or by @code{AC_SUBST}ing it from your
5099 @file{configure.ac}. You can override the @code{AR} variable by
5100 defining a per-library @code{maude_AR} variable (@pxref{Program and
5101 Library Variables}).
5103 @cindex Empty libraries
5104 Be careful when selecting library components conditionally. Because
5105 building an empty library is not portable, you should ensure that any
5106 library always contains at least one object.
5108 To use a static library when building a program, add it to
5109 @code{LDADD} for this program. In the following example, the program
5110 @file{cpio} is statically linked with the library @file{libcpio.a}.
5113 noinst_LIBRARIES = libcpio.a
5114 libcpio_a_SOURCES = @dots{}
5117 cpio_SOURCES = cpio.c @dots{}
5118 cpio_LDADD = libcpio.a
5122 @node A Shared Library
5123 @section Building a Shared Library
5125 @cindex Shared libraries, support for
5127 Building shared libraries portably is a relatively complex matter.
5128 For this reason, GNU Libtool (@pxref{Top, , Introduction, libtool, The
5129 Libtool Manual}) was created to help build shared libraries in a
5130 platform-independent way.
5133 * Libtool Concept:: Introducing Libtool
5134 * Libtool Libraries:: Declaring Libtool Libraries
5135 * Conditional Libtool Libraries:: Building Libtool Libraries Conditionally
5136 * Conditional Libtool Sources:: Choosing Library Sources Conditionally
5137 * Libtool Convenience Libraries:: Building Convenience Libtool Libraries
5138 * Libtool Modules:: Building Libtool Modules
5139 * Libtool Flags:: Using _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS
5140 * LTLIBOBJS:: Using $(LTLIBOBJS) and $(LTALLOCA)
5141 * Libtool Issues:: Common Issues Related to Libtool's Use
5144 @node Libtool Concept
5145 @subsection The Libtool Concept
5147 @cindex @command{libtool}, introduction
5148 @cindex libtool library, definition
5149 @cindex suffix @file{.la}, defined
5150 @cindex @file{.la} suffix, defined
5152 Libtool abstracts shared and static libraries into a unified concept
5153 henceforth called @dfn{libtool libraries}. Libtool libraries are
5154 files using the @file{.la} suffix, and can designate a static library,
5155 a shared library, or maybe both. Their exact nature cannot be
5156 determined until @file{./configure} is run: not all platforms support
5157 all kinds of libraries, and users can explicitly select which
5158 libraries should be built. (However the package's maintainers can
5159 tune the default, @pxref{AC_PROG_LIBTOOL, , The @code{AC_PROG_LIBTOOL}
5160 macro, libtool, The Libtool Manual}.)
5162 @cindex suffix @file{.lo}, defined
5163 Because object files for shared and static libraries must be compiled
5164 differently, libtool is also used during compilation. Object files
5165 built by libtool are called @dfn{libtool objects}: these are files
5166 using the @file{.lo} suffix. Libtool libraries are built from these
5169 You should not assume anything about the structure of @file{.la} or
5170 @file{.lo} files and how libtool constructs them: this is libtool's
5171 concern, and the last thing one wants is to learn about libtool's
5172 guts. However the existence of these files matters, because they are
5173 used as targets and dependencies in @file{Makefile}s rules when
5174 building libtool libraries. There are situations where you may have
5175 to refer to these, for instance when expressing dependencies for
5176 building source files conditionally (@pxref{Conditional Libtool
5179 @cindex @file{libltdl}, introduction
5181 People considering writing a plug-in system, with dynamically loaded
5182 modules, should look into @file{libltdl}: libtool's dlopening library
5183 (@pxref{Using libltdl, , Using libltdl, libtool, The Libtool Manual}).
5184 This offers a portable dlopening facility to load libtool libraries
5185 dynamically, and can also achieve static linking where unavoidable.
5187 Before we discuss how to use libtool with Automake in details, it
5188 should be noted that the libtool manual also has a section about how
5189 to use Automake with libtool (@pxref{Using Automake, , Using Automake
5190 with Libtool, libtool, The Libtool Manual}).
5192 @node Libtool Libraries
5193 @subsection Building Libtool Libraries
5195 @cindex @code{_LTLIBRARIES} primary, defined
5196 @cindex @code{LTLIBRARIES} primary, defined
5197 @cindex Primary variable, @code{LTLIBRARIES}
5198 @cindex Example of shared libraries
5199 @vindex lib_LTLIBRARIES
5200 @vindex pkglib_LTLIBRARIES
5201 @vindex _LTLIBRARIES
5203 Automake uses libtool to build libraries declared with the
5204 @code{LTLIBRARIES} primary. Each @code{_LTLIBRARIES} variable is a
5205 list of libtool libraries to build. For instance, to create a libtool
5206 library named @file{libgettext.la}, and install it in @code{libdir},
5210 lib_LTLIBRARIES = libgettext.la
5211 libgettext_la_SOURCES = gettext.c gettext.h @dots{}
5214 Automake predefines the variable @code{pkglibdir}, so you can use
5215 @code{pkglib_LTLIBRARIES} to install libraries in
5216 @samp{$(libdir)/@@PACKAGE@@/}.
5218 If @file{gettext.h} is a public header file that needs to be installed
5219 in order for people to use the library, it should be declared using a
5220 @code{_HEADERS} variable, not in @code{libgettext_la_SOURCES}.
5221 Headers listed in the latter should be internal headers that are not
5222 part of the public interface.
5225 lib_LTLIBRARIES = libgettext.la
5226 libgettext_la_SOURCES = gettext.c @dots{}
5227 include_HEADERS = gettext.h @dots{}
5230 A package can build and install such a library along with other
5231 programs that use it. This dependency should be specified using
5232 @code{LDADD}. The following example builds a program named
5233 @file{hello} that is linked with @file{libgettext.la}.
5236 lib_LTLIBRARIES = libgettext.la
5237 libgettext_la_SOURCES = gettext.c @dots{}
5239 bin_PROGRAMS = hello
5240 hello_SOURCES = hello.c @dots{}
5241 hello_LDADD = libgettext.la
5245 Whether @file{hello} is statically or dynamically linked with
5246 @file{libgettext.la} is not yet known: this will depend on the
5247 configuration of libtool and the capabilities of the host.
5250 @node Conditional Libtool Libraries
5251 @subsection Building Libtool Libraries Conditionally
5252 @cindex libtool libraries, conditional
5253 @cindex conditional libtool libraries
5255 Like conditional programs (@pxref{Conditional Programs}), there are
5256 two main ways to build conditional libraries: using Automake
5257 conditionals or using Autoconf @code{AC_SUBST}itutions.
5259 The important implementation detail you have to be aware of is that
5260 the place where a library will be installed matters to libtool: it
5261 needs to be indicated @emph{at link-time} using the @option{-rpath}
5264 For libraries whose destination directory is known when Automake runs,
5265 Automake will automatically supply the appropriate @option{-rpath}
5266 option to libtool. This is the case for libraries listed explicitly in
5267 some installable @code{_LTLIBRARIES} variables such as
5268 @code{lib_LTLIBRARIES}.
5270 However, for libraries determined at configure time (and thus
5271 mentioned in @code{EXTRA_LTLIBRARIES}), Automake does not know the
5272 final installation directory. For such libraries you must add the
5273 @option{-rpath} option to the appropriate @code{_LDFLAGS} variable by
5276 The examples below illustrate the differences between these two methods.
5278 Here is an example where @code{WANTEDLIBS} is an @code{AC_SUBST}ed
5279 variable set at @file{./configure}-time to either @file{libfoo.la},
5280 @file{libbar.la}, both, or none. Although @samp{$(WANTEDLIBS)}
5281 appears in the @code{lib_LTLIBRARIES}, Automake cannot guess it
5282 relates to @file{libfoo.la} or @file{libbar.la} at the time it creates
5283 the link rule for these two libraries. Therefore the @option{-rpath}
5284 argument must be explicitly supplied.
5286 @c Keep in sync with ltcond.test.
5288 EXTRA_LTLIBRARIES = libfoo.la libbar.la
5289 lib_LTLIBRARIES = $(WANTEDLIBS)
5290 libfoo_la_SOURCES = foo.c @dots{}
5291 libfoo_la_LDFLAGS = -rpath '$(libdir)'
5292 libbar_la_SOURCES = bar.c @dots{}
5293 libbar_la_LDFLAGS = -rpath '$(libdir)'
5296 Here is how the same @file{Makefile.am} would look using Automake
5297 conditionals named @code{WANT_LIBFOO} and @code{WANT_LIBBAR}. Now
5298 Automake is able to compute the @option{-rpath} setting itself, because
5299 it's clear that both libraries will end up in @samp{$(libdir)} if they
5302 @c Keep in sync with ltcond.test.
5306 lib_LTLIBRARIES += libfoo.la
5309 lib_LTLIBRARIES += libbar.la
5311 libfoo_la_SOURCES = foo.c @dots{}
5312 libbar_la_SOURCES = bar.c @dots{}
5315 @node Conditional Libtool Sources
5316 @subsection Libtool Libraries with Conditional Sources
5318 Conditional compilation of sources in a library can be achieved in the
5319 same way as conditional compilation of sources in a program
5320 (@pxref{Conditional Sources}). The only difference is that
5321 @code{_LIBADD} should be used instead of @code{_LDADD} and that it
5322 should mention libtool objects (@file{.lo} files).
5324 So, to mimic the @file{hello} example from @ref{Conditional Sources},
5325 we could build a @file{libhello.la} library using either
5326 @file{hello-linux.c} or @file{hello-generic.c} with the following
5329 @c Keep in sync with ltcond2.test.
5331 lib_LTLIBRARIES = libhello.la
5332 libhello_la_SOURCES = hello-common.c
5333 EXTRA_libhello_la_SOURCES = hello-linux.c hello-generic.c
5334 libhello_la_LIBADD = $(HELLO_SYSTEM)
5335 libhello_la_DEPENDENCIES = $(HELLO_SYSTEM)
5339 And make sure @command{configure} defines @code{HELLO_SYSTEM} as
5340 either @file{hello-linux.lo} or @file{hello-@-generic.lo}.
5342 Or we could simply use an Automake conditional as follows.
5344 @c Keep in sync with ltcond2.test.
5346 lib_LTLIBRARIES = libhello.la
5347 libhello_la_SOURCES = hello-common.c
5349 libhello_la_SOURCES += hello-linux.c
5351 libhello_la_SOURCES += hello-generic.c
5355 @node Libtool Convenience Libraries
5356 @subsection Libtool Convenience Libraries
5357 @cindex convenience libraries, libtool
5358 @cindex libtool convenience libraries
5359 @vindex noinst_LTLIBRARIES
5360 @vindex check_LTLIBRARIES
5362 Sometimes you want to build libtool libraries that should not be
5363 installed. These are called @dfn{libtool convenience libraries} and
5364 are typically used to encapsulate many sublibraries, later gathered
5365 into one big installed library.
5367 Libtool convenience libraries are declared by directory-less variables
5368 such as @code{noinst_LTLIBRARIES}, @code{check_LTLIBRARIES}, or even
5369 @code{EXTRA_LTLIBRARIES}. Unlike installed libtool libraries they do
5370 not need an @option{-rpath} flag at link time (actually this is the only
5373 Convenience libraries listed in @code{noinst_LTLIBRARIES} are always
5374 built. Those listed in @code{check_LTLIBRARIES} are built only upon
5375 @samp{make check}. Finally, libraries listed in
5376 @code{EXTRA_LTLIBRARIES} are never built explicitly: Automake outputs
5377 rules to build them, but if the library does not appear as a Makefile
5378 dependency anywhere it won't be built (this is why
5379 @code{EXTRA_LTLIBRARIES} is used for conditional compilation).
5381 Here is a sample setup merging libtool convenience libraries from
5382 subdirectories into one main @file{libtop.la} library.
5384 @c Keep in sync with ltconv.test.
5386 # -- Top-level Makefile.am --
5387 SUBDIRS = sub1 sub2 @dots{}
5388 lib_LTLIBRARIES = libtop.la
5390 libtop_la_LIBADD = \
5395 # -- sub1/Makefile.am --
5396 noinst_LTLIBRARIES = libsub1.la
5397 libsub1_la_SOURCES = @dots{}
5399 # -- sub2/Makefile.am --
5400 # showing nested convenience libraries
5401 SUBDIRS = sub2.1 sub2.2 @dots{}
5402 noinst_LTLIBRARIES = libsub2.la
5403 libsub2_la_SOURCES =
5404 libsub2_la_LIBADD = \
5410 When using such setup, beware that @command{automake} will assume
5411 @file{libtop.la} is to be linked with the C linker. This is because
5412 @code{libtop_la_SOURCES} is empty, so @command{automake} picks C as
5413 default language. If @code{libtop_la_SOURCES} was not empty,
5414 @command{automake} would select the linker as explained in @ref{How
5415 the Linker is Chosen}.
5417 If one of the sublibraries contains non-C source, it is important that
5418 the appropriate linker be chosen. One way to achieve this is to
5419 pretend that there is such a non-C file among the sources of the
5420 library, thus forcing @command{automake} to select the appropriate
5421 linker. Here is the top-level @file{Makefile} of our example updated
5422 to force C++ linking.
5425 SUBDIRS = sub1 sub2 @dots{}
5426 lib_LTLIBRARIES = libtop.la
5428 # Dummy C++ source to cause C++ linking.
5429 nodist_EXTRA_libtop_la_SOURCES = dummy.cxx
5430 libtop_la_LIBADD = \
5436 @samp{EXTRA_*_SOURCES} variables are used to keep track of source
5437 files that might be compiled (this is mostly useful when doing
5438 conditional compilation using @code{AC_SUBST}, @pxref{Conditional
5439 Libtool Sources}), and the @code{nodist_} prefix means the listed
5440 sources are not to be distributed (@pxref{Program and Library
5441 Variables}). In effect the file @file{dummy.cxx} does not need to
5442 exist in the source tree. Of course if you have some real source file
5443 to list in @code{libtop_la_SOURCES} there is no point in cheating with
5444 @code{nodist_EXTRA_libtop_la_SOURCES}.
5447 @node Libtool Modules
5448 @subsection Libtool Modules
5449 @cindex modules, libtool
5450 @cindex libtool modules
5451 @cindex @option{-module}, libtool
5453 These are libtool libraries meant to be dlopened. They are
5454 indicated to libtool by passing @option{-module} at link-time.
5457 pkglib_LTLIBRARIES = mymodule.la
5458 mymodule_la_SOURCES = doit.c
5459 mymodule_la_LDFLAGS = -module
5462 Ordinarily, Automake requires that a library's name start with
5463 @code{lib}. However, when building a dynamically loadable module you
5464 might wish to use a "nonstandard" name. Automake will not complain
5465 about such nonstandard names if it knows the library being built is a
5466 libtool module, i.e., if @option{-module} explicitly appears in the
5467 library's @code{_LDFLAGS} variable (or in the common @code{AM_LDFLAGS}
5468 variable when no per-library @code{_LDFLAGS} variable is defined).
5470 As always, @code{AC_SUBST} variables are black boxes to Automake since
5471 their values are not yet known when @command{automake} is run.
5472 Therefore if @option{-module} is set via such a variable, Automake
5473 cannot notice it and will proceed as if the library was an ordinary
5474 libtool library, with strict naming.
5476 If @code{mymodule_la_SOURCES} is not specified, then it defaults to
5477 the single file @file{mymodule.c} (@pxref{Default _SOURCES}).
5480 @subsection @code{_LIBADD}, @code{_LDFLAGS}, and @code{_LIBTOOLFLAGS}
5481 @cindex @code{_LIBADD}, libtool
5482 @cindex @code{_LDFLAGS}, libtool
5483 @cindex @code{_LIBTOOLFLAGS}, libtool
5484 @vindex AM_LIBTOOLFLAGS
5485 @vindex LIBTOOLFLAGS
5486 @vindex maude_LIBTOOLFLAGS
5488 As shown in previous sections, the @samp{@var{library}_LIBADD}
5489 variable should be used to list extra libtool objects (@file{.lo}
5490 files) or libtool libraries (@file{.la}) to add to @var{library}.
5492 The @samp{@var{library}_LDFLAGS} variable is the place to list
5493 additional libtool linking flags, such as @option{-version-info},
5494 @option{-static}, and a lot more. @xref{Link mode, , Link mode,
5495 libtool, The Libtool Manual}.
5497 The @command{libtool} command has two kinds of options: mode-specific
5498 options and generic options. Mode-specific options such as the
5499 aforementioned linking flags should be lumped with the other flags
5500 passed to the tool invoked by @command{libtool} (hence the use of
5501 @samp{@var{library}_LDFLAGS} for libtool linking flags). Generic
5502 options include @option{--tag=@var{tag}} and @option{--silent}
5503 (@pxref{Invoking libtool, , Invoking @command{libtool}, libtool, The
5504 Libtool Manual} for more options) should appear before the mode
5505 selection on the command line; in @file{Makefile.am}s they should
5506 be listed in the @samp{@var{library}_LIBTOOLFLAGS} variable.
5508 If @samp{@var{library}_LIBTOOLFLAGS} is not defined, then the variable
5509 @code{AM_LIBTOOLFLAGS} is used instead.
5511 These flags are passed to libtool after the @option{--tag=@var{tag}}
5512 option computed by Automake (if any), so
5513 @samp{@var{library}_LIBTOOLFLAGS} (or @code{AM_LIBTOOLFLAGS}) is a
5514 good place to override or supplement the @option{--tag=@var{tag}}
5517 The libtool rules also use a @code{LIBTOOLFLAGS} variable that should
5518 not be set in @file{Makefile.am}: this is a user variable (@pxref{Flag
5519 Variables Ordering}. It allows users to run @samp{make
5520 LIBTOOLFLAGS=--silent}, for instance. Note that the verbosity of
5521 @command{libtool} can also be influenced with the Automake
5522 @option{silent-rules} option (@pxref{Options}).
5525 @node LTLIBOBJS, Libtool Issues, Libtool Flags, A Shared Library
5526 @subsection @code{LTLIBOBJS} and @code{LTALLOCA}
5527 @cindex @code{LTLIBOBJS}, special handling
5528 @cindex @code{LIBOBJS}, and Libtool
5529 @cindex @code{LTALLOCA}, special handling
5530 @cindex @code{ALLOCA}, and Libtool
5537 Where an ordinary library might include @samp{$(LIBOBJS)} or
5538 @samp{$(ALLOCA)} (@pxref{LIBOBJS}), a libtool library must use
5539 @samp{$(LTLIBOBJS)} or @samp{$(LTALLOCA)}. This is required because
5540 the object files that libtool operates on do not necessarily end in
5543 Nowadays, the computation of @code{LTLIBOBJS} from @code{LIBOBJS} is
5544 performed automatically by Autoconf (@pxref{AC_LIBOBJ vs LIBOBJS, ,
5545 @code{AC_LIBOBJ} vs.@: @code{LIBOBJS}, autoconf, The Autoconf Manual}).
5547 @node Libtool Issues
5548 @subsection Common Issues Related to Libtool's Use
5551 * Error required file ltmain.sh not found:: The need to run libtoolize
5552 * Objects created both with libtool and without:: Avoid a specific build race
5555 @node Error required file ltmain.sh not found
5556 @subsubsection Error: @samp{required file `./ltmain.sh' not found}
5557 @cindex @file{ltmain.sh} not found
5558 @cindex @command{libtoolize}, no longer run by @command{automake}
5559 @cindex @command{libtoolize} and @command{autoreconf}
5560 @cindex @command{autoreconf} and @command{libtoolize}
5561 @cindex @file{bootstrap.sh} and @command{autoreconf}
5562 @cindex @file{autogen.sh} and @command{autoreconf}
5564 Libtool comes with a tool called @command{libtoolize} that will
5565 install libtool's supporting files into a package. Running this
5566 command will install @file{ltmain.sh}. You should execute it before
5567 @command{aclocal} and @command{automake}.
5569 People upgrading old packages to newer autotools are likely to face
5570 this issue because older Automake versions used to call
5571 @command{libtoolize}. Therefore old build scripts do not call
5572 @command{libtoolize}.
5574 Since Automake 1.6, it has been decided that running
5575 @command{libtoolize} was none of Automake's business. Instead, that
5576 functionality has been moved into the @command{autoreconf} command
5577 (@pxref{autoreconf Invocation, , Using @command{autoreconf}, autoconf,
5578 The Autoconf Manual}). If you do not want to remember what to run and
5579 when, just learn the @command{autoreconf} command. Hopefully,
5580 replacing existing @file{bootstrap.sh} or @file{autogen.sh} scripts by
5581 a call to @command{autoreconf} should also free you from any similar
5582 incompatible change in the future.
5584 @node Objects created both with libtool and without
5585 @subsubsection Objects @samp{created with both libtool and without}
5587 Sometimes, the same source file is used both to build a libtool
5588 library and to build another non-libtool target (be it a program or
5591 Let's consider the following @file{Makefile.am}.
5595 prog_SOURCES = prog.c foo.c @dots{}
5597 lib_LTLIBRARIES = libfoo.la
5598 libfoo_la_SOURCES = foo.c @dots{}
5602 (In this trivial case the issue could be avoided by linking
5603 @file{libfoo.la} with @file{prog} instead of listing @file{foo.c} in
5604 @code{prog_SOURCES}. But let's assume we really want to keep
5605 @file{prog} and @file{libfoo.la} separate.)
5607 Technically, it means that we should build @file{foo.$(OBJEXT)} for
5608 @file{prog}, and @file{foo.lo} for @file{libfoo.la}. The problem is
5609 that in the course of creating @file{foo.lo}, libtool may erase (or
5610 replace) @file{foo.$(OBJEXT)}, and this cannot be avoided.
5612 Therefore, when Automake detects this situation it will complain
5613 with a message such as
5615 object `foo.$(OBJEXT)' created both with libtool and without
5618 A workaround for this issue is to ensure that these two objects get
5619 different basenames. As explained in @ref{Renamed Objects}, this
5620 happens automatically when per-targets flags are used.
5624 prog_SOURCES = prog.c foo.c @dots{}
5625 prog_CFLAGS = $(AM_CFLAGS)
5627 lib_LTLIBRARIES = libfoo.la
5628 libfoo_la_SOURCES = foo.c @dots{}
5632 Adding @samp{prog_CFLAGS = $(AM_CFLAGS)} is almost a no-op, because
5633 when the @code{prog_CFLAGS} is defined, it is used instead of
5634 @code{AM_CFLAGS}. However as a side effect it will cause
5635 @file{prog.c} and @file{foo.c} to be compiled as
5636 @file{prog-prog.$(OBJEXT)} and @file{prog-foo.$(OBJEXT)}, which solves
5639 @node Program and Library Variables
5640 @section Program and Library Variables
5642 Associated with each program is a collection of variables that can be
5643 used to modify how that program is built. There is a similar list of
5644 such variables for each library. The canonical name of the program (or
5645 library) is used as a base for naming these variables.
5647 In the list below, we use the name ``maude'' to refer to the program or
5648 library. In your @file{Makefile.am} you would replace this with the
5649 canonical name of your program. This list also refers to ``maude'' as a
5650 program, but in general the same rules apply for both static and dynamic
5651 libraries; the documentation below notes situations where programs and
5656 This variable, if it exists, lists all the source files that are
5657 compiled to build the program. These files are added to the
5658 distribution by default. When building the program, Automake will cause
5659 each source file to be compiled to a single @file{.o} file (or
5660 @file{.lo} when using libtool). Normally these object files are named
5661 after the source file, but other factors can change this. If a file in
5662 the @code{_SOURCES} variable has an unrecognized extension, Automake
5663 will do one of two things with it. If a suffix rule exists for turning
5664 files with the unrecognized extension into @file{.o} files, then
5665 @command{automake} will treat this file as it will any other source file
5666 (@pxref{Support for Other Languages}). Otherwise, the file will be
5667 ignored as though it were a header file.
5669 The prefixes @code{dist_} and @code{nodist_} can be used to control
5670 whether files listed in a @code{_SOURCES} variable are distributed.
5671 @code{dist_} is redundant, as sources are distributed by default, but it
5672 can be specified for clarity if desired.
5674 It is possible to have both @code{dist_} and @code{nodist_} variants of
5675 a given @code{_SOURCES} variable at once; this lets you easily
5676 distribute some files and not others, for instance:
5679 nodist_maude_SOURCES = nodist.c
5680 dist_maude_SOURCES = dist-me.c
5683 By default the output file (on Unix systems, the @file{.o} file) will
5684 be put into the current build directory. However, if the option
5685 @option{subdir-objects} is in effect in the current directory then the
5686 @file{.o} file will be put into the subdirectory named after the
5687 source file. For instance, with @option{subdir-objects} enabled,
5688 @file{sub/dir/file.c} will be compiled to @file{sub/dir/file.o}. Some
5689 people prefer this mode of operation. You can specify
5690 @option{subdir-objects} in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
5691 @cindex Subdirectory, objects in
5692 @cindex Objects in subdirectory
5695 @item EXTRA_maude_SOURCES
5696 Automake needs to know the list of files you intend to compile
5697 @emph{statically}. For one thing, this is the only way Automake has of
5698 knowing what sort of language support a given @file{Makefile.in}
5699 requires. @footnote{There are other, more obscure reasons for
5700 this limitation as well.} This means that, for example, you can't put a
5701 configure substitution like @samp{@@my_sources@@} into a @samp{_SOURCES}
5702 variable. If you intend to conditionally compile source files and use
5703 @file{configure} to substitute the appropriate object names into, e.g.,
5704 @code{_LDADD} (see below), then you should list the corresponding source
5705 files in the @code{EXTRA_} variable.
5707 This variable also supports @code{dist_} and @code{nodist_} prefixes.
5708 For instance, @code{nodist_EXTRA_maude_SOURCES} would list extra
5709 sources that may need to be built, but should not be distributed.
5712 A static library is created by default by invoking @samp{$(AR)
5713 $(ARFLAGS)} followed by the name of the library and then the objects
5714 being put into the library. You can override this by setting the
5715 @code{_AR} variable. This is usually used with C++; some C++
5716 compilers require a special invocation in order to instantiate all the
5717 templates that should go into a library. For instance, the SGI C++
5718 compiler likes this variable set like so:
5720 libmaude_a_AR = $(CXX) -ar -o
5724 Extra objects can be added to a @emph{library} using the @code{_LIBADD}
5725 variable. For instance, this should be used for objects determined by
5726 @command{configure} (@pxref{A Library}).
5728 In the case of libtool libraries, @code{maude_LIBADD} can also refer
5729 to other libtool libraries.
5732 Extra objects (@file{*.$(OBJEXT)}) and libraries (@file{*.a},
5733 @file{*.la}) can be added to a @emph{program} by listing them in the
5734 @code{_LDADD} variable. For instance, this should be used for objects
5735 determined by @command{configure} (@pxref{Linking}).
5737 @code{_LDADD} and @code{_LIBADD} are inappropriate for passing
5738 program-specific linker flags (except for @option{-l}, @option{-L},
5739 @option{-dlopen} and @option{-dlpreopen}). Use the @code{_LDFLAGS} variable
5742 For instance, if your @file{configure.ac} uses @code{AC_PATH_XTRA}, you
5743 could link your program against the X libraries like so:
5746 maude_LDADD = $(X_PRE_LIBS) $(X_LIBS) $(X_EXTRA_LIBS)
5749 We recommend that you use @option{-l} and @option{-L} only when
5750 referring to third-party libraries, and give the explicit file names
5751 of any library built by your package. Doing so will ensure that
5752 @code{maude_DEPENDENCIES} (see below) is correctly defined by default.
5755 This variable is used to pass extra flags to the link step of a program
5756 or a shared library. It overrides the @code{AM_LDFLAGS} variable.
5758 @item maude_LIBTOOLFLAGS
5759 This variable is used to pass extra options to @command{libtool}.
5760 It overrides the @code{AM_LIBTOOLFLAGS} variable.
5761 These options are output before @command{libtool}'s @option{--mode=@var{mode}}
5762 option, so they should not be mode-specific options (those belong to
5763 the compiler or linker flags). @xref{Libtool Flags}.
5765 @item maude_DEPENDENCIES
5766 @itemx EXTRA_maude_DEPENDENCIES
5767 It is also occasionally useful to have a target (program or library)
5768 depend on some other file that is not actually part of that target.
5769 This can be done using the @code{_DEPENDENCIES} variable. Each
5770 target depends on the contents of such a variable, but no further
5771 interpretation is done.
5773 Since these dependencies are associated to the link rule used to
5774 create the programs they should normally list files used by the link
5775 command. That is @file{*.$(OBJEXT)}, @file{*.a}, or @file{*.la} files
5776 for programs; @file{*.lo} and @file{*.la} files for Libtool libraries;
5777 and @file{*.$(OBJEXT)} files for static libraries. In rare cases you
5778 may need to add other kinds of files such as linker scripts, but
5779 @emph{listing a source file in @code{_DEPENDENCIES} is wrong}. If
5780 some source file needs to be built before all the components of a
5781 program are built, consider using the @code{BUILT_SOURCES} variable
5784 If @code{_DEPENDENCIES} is not supplied, it is computed by Automake.
5785 The automatically-assigned value is the contents of @code{_LDADD} or
5786 @code{_LIBADD}, with most configure substitutions, @option{-l}, @option{-L},
5787 @option{-dlopen} and @option{-dlpreopen} options removed. The configure
5788 substitutions that are left in are only @samp{$(LIBOBJS)} and
5789 @samp{$(ALLOCA)}; these are left because it is known that they will not
5790 cause an invalid value for @code{_DEPENDENCIES} to be generated.
5792 @code{_DEPENDENCIES} is more likely used to perform conditional
5793 compilation using an @code{AC_SUBST} variable that contains a list of
5794 objects. @xref{Conditional Sources}, and @ref{Conditional Libtool
5797 The @code{EXTRA_*_DEPENDENCIES} variable may be useful for cases where
5798 you merely want to augment the @command{automake}-generated
5799 @code{_DEPENDENCIES} variable rather than replacing it.
5802 You can override the linker on a per-program basis. By default the
5803 linker is chosen according to the languages used by the program. For
5804 instance, a program that includes C++ source code would use the C++
5805 compiler to link. The @code{_LINK} variable must hold the name of a
5806 command that can be passed all the @file{.o} file names and libraries
5807 to link against as arguments. Note that the name of the underlying
5808 program is @emph{not} passed to @code{_LINK}; typically one uses
5812 maude_LINK = $(CCLD) -magic -o $@@
5815 If a @code{_LINK} variable is not supplied, it may still be generated
5816 and used by Automake due to the use of per-target link flags such as
5817 @code{_CFLAGS}, @code{_LDFLAGS} or @code{_LIBTOOLFLAGS}, in cases where
5820 @item maude_CCASFLAGS
5822 @itemx maude_CPPFLAGS
5823 @itemx maude_CXXFLAGS
5825 @itemx maude_GCJFLAGS
5827 @itemx maude_OBJCFLAGS
5829 @itemx maude_UPCFLAGS
5831 @cindex per-target compilation flags, defined
5832 Automake allows you to set compilation flags on a per-program (or
5833 per-library) basis. A single source file can be included in several
5834 programs, and it will potentially be compiled with different flags for
5835 each program. This works for any language directly supported by
5836 Automake. These @dfn{per-target compilation flags} are
5846 @samp{_UPCFLAGS}, and
5849 When using a per-target compilation flag, Automake will choose a
5850 different name for the intermediate object files. Ordinarily a file
5851 like @file{sample.c} will be compiled to produce @file{sample.o}.
5852 However, if the program's @code{_CFLAGS} variable is set, then the
5853 object file will be named, for instance, @file{maude-sample.o}. (See
5854 also @ref{Renamed Objects}.) The use of per-target compilation flags
5855 with C sources requires that the macro @code{AM_PROG_CC_C_O} be called
5856 from @file{configure.ac}.
5858 In compilations with per-target flags, the ordinary @samp{AM_} form of
5859 the flags variable is @emph{not} automatically included in the
5860 compilation (however, the user form of the variable @emph{is} included).
5861 So for instance, if you want the hypothetical @file{maude} compilations
5862 to also use the value of @code{AM_CFLAGS}, you would need to write:
5865 maude_CFLAGS = @dots{} your flags @dots{} $(AM_CFLAGS)
5868 @xref{Flag Variables Ordering}, for more discussion about the
5869 interaction between user variables, @samp{AM_} shadow variables, and
5870 per-target variables.
5872 @item maude_SHORTNAME
5873 On some platforms the allowable file names are very short. In order to
5874 support these systems and per-target compilation flags at the same
5875 time, Automake allows you to set a ``short name'' that will influence
5876 how intermediate object files are named. For instance, in the following
5880 bin_PROGRAMS = maude
5881 maude_CPPFLAGS = -DSOMEFLAG
5883 maude_SOURCES = sample.c @dots{}
5887 the object file would be named @file{m-sample.o} rather than
5888 @file{maude-sample.o}.
5890 This facility is rarely needed in practice,
5891 and we recommend avoiding it until you find it is required.
5894 @node Default _SOURCES
5895 @section Default @code{_SOURCES}
5899 @cindex @code{_SOURCES}, default
5900 @cindex default @code{_SOURCES}
5901 @vindex AM_DEFAULT_SOURCE_EXT
5903 @code{_SOURCES} variables are used to specify source files of programs
5904 (@pxref{A Program}), libraries (@pxref{A Library}), and Libtool
5905 libraries (@pxref{A Shared Library}).
5907 When no such variable is specified for a target, Automake will define
5908 one itself. The default is to compile a single C file whose base name
5909 is the name of the target itself, with any extension replaced by
5910 @code{AM_DEFAULT_SOURCE_EXT}, which defaults to @file{.c}.
5912 For example if you have the following somewhere in your
5913 @file{Makefile.am} with no corresponding @code{libfoo_a_SOURCES}:
5916 lib_LIBRARIES = libfoo.a sub/libc++.a
5920 @file{libfoo.a} will be built using a default source file named
5921 @file{libfoo.c}, and @file{sub/libc++.a} will be built from
5922 @file{sub/libc++.c}. (In older versions @file{sub/libc++.a}
5923 would be built from @file{sub_libc___a.c}, i.e., the default source
5924 was the canonized name of the target, with @file{.c} appended.
5925 We believe the new behavior is more sensible, but for backward
5926 compatibility @command{automake} will use the old name if a file or a rule
5927 with that name exists and @code{AM_DEFAULT_SOURCE_EXT} is not used.)
5929 @cindex @code{check_PROGRAMS} example
5930 @vindex check_PROGRAMS
5931 Default sources are mainly useful in test suites, when building many
5932 test programs each from a single source. For instance, in
5935 check_PROGRAMS = test1 test2 test3
5936 AM_DEFAULT_SOURCE_EXT = .cpp
5940 @file{test1}, @file{test2}, and @file{test3} will be built
5941 from @file{test1.cpp}, @file{test2.cpp}, and @file{test3.cpp}.
5942 Without the last line, they will be built from @file{test1.c},
5943 @file{test2.c}, and @file{test3.c}.
5945 @cindex Libtool modules, default source example
5946 @cindex default source, Libtool modules example
5947 Another case where this is convenient is building many Libtool modules
5948 (@file{module@var{n}.la}), each defined in its own file
5949 (@file{module@var{n}.c}).
5952 AM_LDFLAGS = -module
5953 lib_LTLIBRARIES = module1.la module2.la module3.la
5956 @cindex empty @code{_SOURCES}
5957 @cindex @code{_SOURCES}, empty
5958 Finally, there is one situation where this default source computation
5959 needs to be avoided: when a target should not be built from sources.
5960 We already saw such an example in @ref{true}; this happens when all
5961 the constituents of a target have already been compiled and just need
5962 to be combined using a @code{_LDADD} variable. Then it is necessary
5963 to define an empty @code{_SOURCES} variable, so that @command{automake}
5964 does not compute a default.
5967 bin_PROGRAMS = target
5969 target_LDADD = libmain.a libmisc.a
5973 @section Special handling for @code{LIBOBJS} and @code{ALLOCA}
5975 @cindex @code{LIBOBJS}, example
5976 @cindex @code{ALLOCA}, example
5977 @cindex @code{LIBOBJS}, special handling
5978 @cindex @code{ALLOCA}, special handling
5984 The @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} variables list object
5985 files that should be compiled into the project to provide an
5986 implementation for functions that are missing or broken on the host
5987 system. They are substituted by @file{configure}.
5991 These variables are defined by Autoconf macros such as
5992 @code{AC_LIBOBJ}, @code{AC_REPLACE_FUNCS} (@pxref{Generic Functions, ,
5993 Generic Function Checks, autoconf, The Autoconf Manual}), or
5994 @code{AC_FUNC_ALLOCA} (@pxref{Particular Functions, , Particular
5995 Function Checks, autoconf, The Autoconf Manual}). Many other Autoconf
5996 macros call @code{AC_LIBOBJ} or @code{AC_REPLACE_FUNCS} to
5997 populate @samp{$(LIBOBJS)}.
5999 @acindex AC_LIBSOURCE
6001 Using these variables is very similar to doing conditional compilation
6002 using @code{AC_SUBST} variables, as described in @ref{Conditional
6003 Sources}. That is, when building a program, @samp{$(LIBOBJS)} and
6004 @samp{$(ALLOCA)} should be added to the associated @samp{*_LDADD}
6005 variable, or to the @samp{*_LIBADD} variable when building a library.
6006 However there is no need to list the corresponding sources in
6007 @samp{EXTRA_*_SOURCES} nor to define @samp{*_DEPENDENCIES}. Automake
6008 automatically adds @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} to the
6009 dependencies, and it will discover the list of corresponding source
6010 files automatically (by tracing the invocations of the
6011 @code{AC_LIBSOURCE} Autoconf macros). If you have already defined
6012 @samp{*_DEPENDENCIES} explicitly for an unrelated reason, then you
6013 either need to add these variables manually, or use
6014 @samp{EXTRA_*_DEPENDENCIES} instead of @samp{*_DEPENDENCIES}.
6016 These variables are usually used to build a portability library that
6017 is linked with all the programs of the project. We now review a
6018 sample setup. First, @file{configure.ac} contains some checks that
6019 affect either @code{LIBOBJS} or @code{ALLOCA}.
6024 AC_CONFIG_LIBOBJ_DIR([lib])
6026 AC_FUNC_MALLOC dnl May add malloc.$(OBJEXT) to LIBOBJS
6027 AC_FUNC_MEMCMP dnl May add memcmp.$(OBJEXT) to LIBOBJS
6028 AC_REPLACE_FUNCS([strdup]) dnl May add strdup.$(OBJEXT) to LIBOBJS
6029 AC_FUNC_ALLOCA dnl May add alloca.$(OBJEXT) to ALLOCA
6038 @acindex AC_CONFIG_LIBOBJ_DIR
6040 The @code{AC_CONFIG_LIBOBJ_DIR} tells Autoconf that the source files
6041 of these object files are to be found in the @file{lib/} directory.
6042 Automake can also use this information, otherwise it expects the
6043 source files are to be in the directory where the @samp{$(LIBOBJS)}
6044 and @samp{$(ALLOCA)} variables are used.
6046 The @file{lib/} directory should therefore contain @file{malloc.c},
6047 @file{memcmp.c}, @file{strdup.c}, @file{alloca.c}. Here is its
6053 noinst_LIBRARIES = libcompat.a
6054 libcompat_a_SOURCES =
6055 libcompat_a_LIBADD = $(LIBOBJS) $(ALLOCA)
6058 The library can have any name, of course, and anyway it is not going
6059 to be installed: it just holds the replacement versions of the missing
6060 or broken functions so we can later link them in. Many projects
6061 also include extra functions, specific to the project, in that
6062 library: they are simply added on the @code{_SOURCES} line.
6064 @cindex Empty libraries and @samp{$(LIBOBJS)}
6065 @cindex @samp{$(LIBOBJS)} and empty libraries
6066 There is a small trap here, though: @samp{$(LIBOBJS)} and
6067 @samp{$(ALLOCA)} might be empty, and building an empty library is not
6068 portable. You should ensure that there is always something to put in
6069 @file{libcompat.a}. Most projects will also add some utility
6070 functions in that directory, and list them in
6071 @code{libcompat_a_SOURCES}, so in practice @file{libcompat.a} cannot
6074 Finally here is how this library could be used from the @file{src/}
6080 # Link all programs in this directory with libcompat.a
6081 LDADD = ../lib/libcompat.a
6083 bin_PROGRAMS = tool1 tool2 @dots{}
6084 tool1_SOURCES = @dots{}
6085 tool2_SOURCES = @dots{}
6088 When option @option{subdir-objects} is not used, as in the above
6089 example, the variables @samp{$(LIBOBJS)} or @samp{$(ALLOCA)} can only
6090 be used in the directory where their sources lie. E.g., here it would
6091 be wrong to use @samp{$(LIBOBJS)} or @samp{$(ALLOCA)} in
6092 @file{src/Makefile.am}. However if both @option{subdir-objects} and
6093 @code{AC_CONFIG_LIBOBJ_DIR} are used, it is OK to use these variables
6094 in other directories. For instance @file{src/Makefile.am} could be
6100 AUTOMAKE_OPTIONS = subdir-objects
6101 LDADD = $(LIBOBJS) $(ALLOCA)
6103 bin_PROGRAMS = tool1 tool2 @dots{}
6104 tool1_SOURCES = @dots{}
6105 tool2_SOURCES = @dots{}
6108 Because @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} contain object
6109 file names that end with @samp{.$(OBJEXT)}, they are not suitable for
6110 Libtool libraries (where the expected object extension is @file{.lo}):
6111 @code{LTLIBOBJS} and @code{LTALLOCA} should be used instead.
6113 @code{LTLIBOBJS} is defined automatically by Autoconf and should not
6114 be defined by hand (as in the past), however at the time of writing
6115 @code{LTALLOCA} still needs to be defined from @code{ALLOCA} manually.
6116 @xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs.@: @code{LIBOBJS},
6117 autoconf, The Autoconf Manual}.
6120 @node Program Variables
6121 @section Variables used when building a program
6123 Occasionally it is useful to know which @file{Makefile} variables
6124 Automake uses for compilations, and in which order (@pxref{Flag
6125 Variables Ordering}); for instance, you might need to do your own
6126 compilation in some special cases.
6128 Some variables are inherited from Autoconf; these are @code{CC},
6129 @code{CFLAGS}, @code{CPPFLAGS}, @code{DEFS}, @code{LDFLAGS}, and
6138 There are some additional variables that Automake defines on its own:
6142 The contents of this variable are passed to every compilation that invokes
6143 the C preprocessor; it is a list of arguments to the preprocessor. For
6144 instance, @option{-I} and @option{-D} options should be listed here.
6146 Automake already provides some @option{-I} options automatically, in a
6147 separate variable that is also passed to every compilation that invokes
6148 the C preprocessor. In particular it generates @samp{-I.},
6149 @samp{-I$(srcdir)}, and a @option{-I} pointing to the directory holding
6150 @file{config.h} (if you've used @code{AC_CONFIG_HEADERS} or
6151 @code{AM_CONFIG_HEADER}). You can disable the default @option{-I}
6152 options using the @option{nostdinc} option.
6154 When a file to be included is generated during the build and not part
6155 of a distribution tarball, its location is under @code{$(builddir)},
6156 not under @code{$(srcdir)}. This matters especially for packages that
6157 use header files placed in sub-directories and want to allow builds
6158 outside the source tree (@pxref{VPATH Builds}). In that case we
6159 recommend to use a pair of @option{-I} options, such as, e.g.,
6160 @samp{-Isome/subdir -I$(srcdir)/some/subdir} or
6161 @samp{-I$(top_builddir)/some/subdir -I$(top_srcdir)/some/subdir}.
6162 Note that the reference to the build tree should come before the
6163 reference to the source tree, so that accidentally leftover generated
6164 files in the source directory are ignored.
6166 @code{AM_CPPFLAGS} is ignored in preference to a per-executable (or
6167 per-library) @code{_CPPFLAGS} variable if it is defined.
6170 This does the same job as @code{AM_CPPFLAGS} (or any per-target
6171 @code{_CPPFLAGS} variable if it is used). It is an older name for the
6172 same functionality. This variable is deprecated; we suggest using
6173 @code{AM_CPPFLAGS} and per-target @code{_CPPFLAGS} instead.
6176 This is the variable the @file{Makefile.am} author can use to pass
6177 in additional C compiler flags. It is more fully documented elsewhere.
6178 In some situations, this is not used, in preference to the
6179 per-executable (or per-library) @code{_CFLAGS}.
6182 This is the command used to actually compile a C source file. The
6183 file name is appended to form the complete command line.
6186 This is the variable the @file{Makefile.am} author can use to pass
6187 in additional linker flags. In some situations, this is not used, in
6188 preference to the per-executable (or per-library) @code{_LDFLAGS}.
6191 This is the command used to actually link a C program. It already
6192 includes @samp{-o $@@} and the usual variable references (for instance,
6193 @code{CFLAGS}); it takes as ``arguments'' the names of the object files
6194 and libraries to link in. This variable is not used when the linker is
6195 overridden with a per-target @code{_LINK} variable or per-target flags
6196 cause Automake to define such a @code{_LINK} variable.
6201 @section Yacc and Lex support
6203 Automake has somewhat idiosyncratic support for Yacc and Lex.
6205 Automake assumes that the @file{.c} file generated by @command{yacc}
6206 (or @command{lex}) should be named using the basename of the input
6207 file. That is, for a yacc source file @file{foo.y}, Automake will
6208 cause the intermediate file to be named @file{foo.c} (as opposed to
6209 @file{y.tab.c}, which is more traditional).
6211 The extension of a yacc source file is used to determine the extension
6212 of the resulting C or C++ file. Files with the extension @file{.y}
6213 will be turned into @file{.c} files; likewise, @file{.yy} will become
6214 @file{.cc}; @file{.y++}, @file{c++}; @file{.yxx}, @file{.cxx}; and
6215 @file{.ypp}, @file{.cpp}.
6217 Likewise, lex source files can be used to generate C or C++; the
6218 extensions @file{.l}, @file{.ll}, @file{.l++}, @file{.lxx}, and
6219 @file{.lpp} are recognized.
6221 You should never explicitly mention the intermediate (C or C++) file
6222 in any @code{SOURCES} variable; only list the source file.
6224 The intermediate files generated by @command{yacc} (or @command{lex})
6225 will be included in any distribution that is made. That way the user
6226 doesn't need to have @command{yacc} or @command{lex}.
6228 If a @command{yacc} source file is seen, then your @file{configure.ac} must
6229 define the variable @code{YACC}. This is most easily done by invoking
6230 the macro @code{AC_PROG_YACC} (@pxref{Particular Programs, , Particular
6231 Program Checks, autoconf, The Autoconf Manual}).
6235 When @code{yacc} is invoked, it is passed @code{AM_YFLAGS} and
6236 @code{YFLAGS}. The latter is a user variable and the former is
6237 intended for the @file{Makefile.am} author.
6239 @code{AM_YFLAGS} is usually used to pass the @option{-d} option to
6240 @command{yacc}. Automake knows what this means and will automatically
6241 adjust its rules to update and distribute the header file built by
6242 @samp{yacc -d}@footnote{Please note that @command{automake} recognizes
6243 @option{-d} in @code{AM_YFLAGS} only if it is not clustered with other
6244 options; for example, it won't be recognized if @code{AM_YFLAGS} is
6245 @option{-dt}, but it will be if @code{AM_YFLAGS} is @option{-d -t} or
6247 What Automake cannot guess, though, is where this
6248 header will be used: it is up to you to ensure the header gets built
6249 before it is first used. Typically this is necessary in order for
6250 dependency tracking to work when the header is included by another
6251 file. The common solution is listing the header file in
6252 @code{BUILT_SOURCES} (@pxref{Sources}) as follows.
6255 BUILT_SOURCES = parser.h
6258 foo_SOURCES = @dots{} parser.y @dots{}
6261 If a @command{lex} source file is seen, then your @file{configure.ac}
6262 must define the variable @code{LEX}. You can use @code{AC_PROG_LEX}
6263 to do this (@pxref{Particular Programs, , Particular Program Checks,
6264 autoconf, The Autoconf Manual}), but using @code{AM_PROG_LEX} macro
6265 (@pxref{Macros}) is recommended.
6269 When @command{lex} is invoked, it is passed @code{AM_LFLAGS} and
6270 @code{LFLAGS}. The latter is a user variable and the former is
6271 intended for the @file{Makefile.am} author.
6273 When @code{AM_MAINTAINER_MODE} (@pxref{maintainer-mode}) is used, the
6274 rebuild rule for distributed Yacc and Lex sources are only used when
6275 @code{maintainer-mode} is enabled, or when the files have been erased.
6277 @cindex @command{ylwrap}
6278 @cindex @command{yacc}, multiple parsers
6279 @cindex Multiple @command{yacc} parsers
6280 @cindex Multiple @command{lex} lexers
6281 @cindex @command{lex}, multiple lexers
6283 When @command{lex} or @command{yacc} sources are used, @code{automake
6284 -i} automatically installs an auxiliary program called
6285 @command{ylwrap} in your package (@pxref{Auxiliary Programs}). This
6286 program is used by the build rules to rename the output of these
6287 tools, and makes it possible to include multiple @command{yacc} (or
6288 @command{lex}) source files in a single directory. (This is necessary
6289 because yacc's output file name is fixed, and a parallel make could
6290 conceivably invoke more than one instance of @command{yacc}
6293 For @command{yacc}, simply managing locking is insufficient. The output of
6294 @command{yacc} always uses the same symbol names internally, so it isn't
6295 possible to link two @command{yacc} parsers into the same executable.
6297 We recommend using the following renaming hack used in @command{gdb}:
6299 #define yymaxdepth c_maxdepth
6300 #define yyparse c_parse
6302 #define yyerror c_error
6303 #define yylval c_lval
6304 #define yychar c_char
6305 #define yydebug c_debug
6306 #define yypact c_pact
6313 #define yyexca c_exca
6314 #define yyerrflag c_errflag
6315 #define yynerrs c_nerrs
6319 #define yy_yys c_yys
6320 #define yystate c_state
6323 #define yy_yyv c_yyv
6325 #define yylloc c_lloc
6326 #define yyreds c_reds
6327 #define yytoks c_toks
6328 #define yylhs c_yylhs
6329 #define yylen c_yylen
6330 #define yydefred c_yydefred
6331 #define yydgoto c_yydgoto
6332 #define yysindex c_yysindex
6333 #define yyrindex c_yyrindex
6334 #define yygindex c_yygindex
6335 #define yytable c_yytable
6336 #define yycheck c_yycheck
6337 #define yyname c_yyname
6338 #define yyrule c_yyrule
6341 For each define, replace the @samp{c_} prefix with whatever you like.
6342 These defines work for @command{bison}, @command{byacc}, and
6343 traditional @code{yacc}s. If you find a parser generator that uses a
6344 symbol not covered here, please report the new name so it can be added
6349 @section C++ Support
6352 @cindex Support for C++
6354 Automake includes full support for C++.
6356 Any package including C++ code must define the output variable
6357 @code{CXX} in @file{configure.ac}; the simplest way to do this is to use
6358 the @code{AC_PROG_CXX} macro (@pxref{Particular Programs, , Particular
6359 Program Checks, autoconf, The Autoconf Manual}).
6361 A few additional variables are defined when a C++ source file is seen:
6365 The name of the C++ compiler.
6368 Any flags to pass to the C++ compiler.
6371 The maintainer's variant of @code{CXXFLAGS}.
6374 The command used to actually compile a C++ source file. The file name
6375 is appended to form the complete command line.
6378 The command used to actually link a C++ program.
6382 @node Objective C Support
6383 @section Objective C Support
6385 @cindex Objective C support
6386 @cindex Support for Objective C
6388 Automake includes some support for Objective C.
6390 Any package including Objective C code must define the output variable
6391 @code{OBJC} in @file{configure.ac}; the simplest way to do this is to use
6392 the @code{AC_PROG_OBJC} macro (@pxref{Particular Programs, , Particular
6393 Program Checks, autoconf, The Autoconf Manual}).
6395 A few additional variables are defined when an Objective C source file
6400 The name of the Objective C compiler.
6403 Any flags to pass to the Objective C compiler.
6406 The maintainer's variant of @code{OBJCFLAGS}.
6409 The command used to actually compile an Objective C source file. The
6410 file name is appended to form the complete command line.
6413 The command used to actually link an Objective C program.
6417 @node Unified Parallel C Support
6418 @section Unified Parallel C Support
6420 @cindex Unified Parallel C support
6421 @cindex Support for Unified Parallel C
6423 Automake includes some support for Unified Parallel C.
6425 Any package including Unified Parallel C code must define the output
6426 variable @code{UPC} in @file{configure.ac}; the simplest way to do
6427 this is to use the @code{AM_PROG_UPC} macro (@pxref{Public Macros}).
6429 A few additional variables are defined when a Unified Parallel C
6430 source file is seen:
6434 The name of the Unified Parallel C compiler.
6437 Any flags to pass to the Unified Parallel C compiler.
6440 The maintainer's variant of @code{UPCFLAGS}.
6443 The command used to actually compile a Unified Parallel C source file.
6444 The file name is appended to form the complete command line.
6447 The command used to actually link a Unified Parallel C program.
6451 @node Assembly Support
6452 @section Assembly Support
6454 Automake includes some support for assembly code. There are two forms
6455 of assembler files: normal (@file{*.s}) and preprocessed by @code{CPP}
6456 (@file{*.S} or @file{*.sx}).
6461 @vindex AM_CCASFLAGS
6463 The variable @code{CCAS} holds the name of the compiler used to build
6464 assembly code. This compiler must work a bit like a C compiler; in
6465 particular it must accept @option{-c} and @option{-o}. The values of
6466 @code{CCASFLAGS} and @code{AM_CCASFLAGS} (or its per-target
6467 definition) is passed to the compilation. For preprocessed files,
6468 @code{DEFS}, @code{DEFAULT_INCLUDES}, @code{INCLUDES}, @code{CPPFLAGS}
6469 and @code{AM_CPPFLAGS} are also used.
6471 The autoconf macro @code{AM_PROG_AS} will define @code{CCAS} and
6472 @code{CCASFLAGS} for you (unless they are already set, it simply sets
6473 @code{CCAS} to the C compiler and @code{CCASFLAGS} to the C compiler
6474 flags), but you are free to define these variables by other means.
6476 Only the suffixes @file{.s}, @file{.S}, and @file{.sx} are recognized by
6477 @command{automake} as being files containing assembly code.
6480 @node Fortran 77 Support
6481 @comment node-name, next, previous, up
6482 @section Fortran 77 Support
6484 @cindex Fortran 77 support
6485 @cindex Support for Fortran 77
6487 Automake includes full support for Fortran 77.
6489 Any package including Fortran 77 code must define the output variable
6490 @code{F77} in @file{configure.ac}; the simplest way to do this is to use
6491 the @code{AC_PROG_F77} macro (@pxref{Particular Programs, , Particular
6492 Program Checks, autoconf, The Autoconf Manual}).
6494 A few additional variables are defined when a Fortran 77 source file is
6500 The name of the Fortran 77 compiler.
6503 Any flags to pass to the Fortran 77 compiler.
6506 The maintainer's variant of @code{FFLAGS}.
6509 Any flags to pass to the Ratfor compiler.
6512 The maintainer's variant of @code{RFLAGS}.
6515 The command used to actually compile a Fortran 77 source file. The file
6516 name is appended to form the complete command line.
6519 The command used to actually link a pure Fortran 77 program or shared
6524 Automake can handle preprocessing Fortran 77 and Ratfor source files in
6525 addition to compiling them@footnote{Much, if not most, of the
6526 information in the following sections pertaining to preprocessing
6527 Fortran 77 programs was taken almost verbatim from @ref{Catalogue of
6528 Rules, , Catalogue of Rules, make, The GNU Make Manual}.}. Automake
6529 also contains some support for creating programs and shared libraries
6530 that are a mixture of Fortran 77 and other languages (@pxref{Mixing
6531 Fortran 77 With C and C++}).
6533 These issues are covered in the following sections.
6536 * Preprocessing Fortran 77:: Preprocessing Fortran 77 sources
6537 * Compiling Fortran 77 Files:: Compiling Fortran 77 sources
6538 * Mixing Fortran 77 With C and C++:: Mixing Fortran 77 With C and C++
6542 @node Preprocessing Fortran 77
6543 @comment node-name, next, previous, up
6544 @subsection Preprocessing Fortran 77
6546 @cindex Preprocessing Fortran 77
6547 @cindex Fortran 77, Preprocessing
6548 @cindex Ratfor programs
6550 @file{N.f} is made automatically from @file{N.F} or @file{N.r}. This
6551 rule runs just the preprocessor to convert a preprocessable Fortran 77
6552 or Ratfor source file into a strict Fortran 77 source file. The precise
6553 command used is as follows:
6558 @code{$(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)@*
6559 $(AM_FFLAGS) $(FFLAGS)}
6562 @code{$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
6567 @node Compiling Fortran 77 Files
6568 @comment node-name, next, previous, up
6569 @subsection Compiling Fortran 77 Files
6571 @file{N.o} is made automatically from @file{N.f}, @file{N.F} or
6572 @file{N.r} by running the Fortran 77 compiler. The precise command used
6578 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS)}
6581 @code{$(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)@*
6582 $(AM_FFLAGS) $(FFLAGS)}
6585 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
6590 @node Mixing Fortran 77 With C and C++
6591 @comment node-name, next, previous, up
6592 @subsection Mixing Fortran 77 With C and C++
6594 @cindex Fortran 77, mixing with C and C++
6595 @cindex Mixing Fortran 77 with C and C++
6596 @cindex Linking Fortran 77 with C and C++
6598 @cindex Mixing Fortran 77 with C and/or C++
6600 Automake currently provides @emph{limited} support for creating programs
6601 and shared libraries that are a mixture of Fortran 77 and C and/or C++.
6602 However, there are many other issues related to mixing Fortran 77 with
6603 other languages that are @emph{not} (currently) handled by Automake, but
6604 that are handled by other packages@footnote{For example,
6605 @uref{http://www-zeus.desy.de/~burow/cfortran/, the cfortran package}
6606 addresses all of these inter-language issues, and runs under nearly all
6607 Fortran 77, C and C++ compilers on nearly all platforms. However,
6608 @command{cfortran} is not yet Free Software, but it will be in the next
6611 Automake can help in two ways:
6615 Automatic selection of the linker depending on which combinations of
6619 Automatic selection of the appropriate linker flags (e.g., @option{-L} and
6620 @option{-l}) to pass to the automatically selected linker in order to link
6621 in the appropriate Fortran 77 intrinsic and run-time libraries.
6623 @cindex @code{FLIBS}, defined
6625 These extra Fortran 77 linker flags are supplied in the output variable
6626 @code{FLIBS} by the @code{AC_F77_LIBRARY_LDFLAGS} Autoconf macro
6627 supplied with newer versions of Autoconf (Autoconf version 2.13 and
6628 later). @xref{Fortran Compiler, , Fortran Compiler Characteristics,
6629 autoconf, The Autoconf Manual}.
6632 If Automake detects that a program or shared library (as mentioned in
6633 some @code{_PROGRAMS} or @code{_LTLIBRARIES} primary) contains source
6634 code that is a mixture of Fortran 77 and C and/or C++, then it requires
6635 that the macro @code{AC_F77_LIBRARY_LDFLAGS} be called in
6636 @file{configure.ac}, and that either @code{$(FLIBS)}
6637 appear in the appropriate @code{_LDADD} (for programs) or @code{_LIBADD}
6638 (for shared libraries) variables. It is the responsibility of the
6639 person writing the @file{Makefile.am} to make sure that @samp{$(FLIBS)}
6640 appears in the appropriate @code{_LDADD} or
6641 @code{_LIBADD} variable.
6643 @cindex Mixed language example
6644 @cindex Example, mixed language
6646 For example, consider the following @file{Makefile.am}:
6650 foo_SOURCES = main.cc foo.f
6651 foo_LDADD = libfoo.la $(FLIBS)
6653 pkglib_LTLIBRARIES = libfoo.la
6654 libfoo_la_SOURCES = bar.f baz.c zardoz.cc
6655 libfoo_la_LIBADD = $(FLIBS)
6658 In this case, Automake will insist that @code{AC_F77_LIBRARY_LDFLAGS}
6659 is mentioned in @file{configure.ac}. Also, if @samp{$(FLIBS)} hadn't
6660 been mentioned in @code{foo_LDADD} and @code{libfoo_la_LIBADD}, then
6661 Automake would have issued a warning.
6664 * How the Linker is Chosen:: Automatic linker selection
6667 @node How the Linker is Chosen
6668 @comment node-name, next, previous, up
6669 @subsubsection How the Linker is Chosen
6671 @cindex Automatic linker selection
6672 @cindex Selecting the linker automatically
6674 When a program or library mixes several languages, Automake choose the
6675 linker according to the following priorities. (The names in
6676 parentheses are the variables containing the link command.)
6681 Native Java (@code{GCJLINK})
6684 C++ (@code{CXXLINK})
6687 Fortran 77 (@code{F77LINK})
6690 Fortran (@code{FCLINK})
6693 Objective C (@code{OBJCLINK})
6696 Unified Parallel C (@code{UPCLINK})
6702 For example, if Fortran 77, C and C++ source code is compiled
6703 into a program, then the C++ linker will be used. In this case, if the
6704 C or Fortran 77 linkers required any special libraries that weren't
6705 included by the C++ linker, then they must be manually added to an
6706 @code{_LDADD} or @code{_LIBADD} variable by the user writing the
6709 Automake only looks at the file names listed in @file{_SOURCES}
6710 variables to choose the linker, and defaults to the C linker.
6711 Sometimes this is inconvenient because you are linking against a
6712 library written in another language and would like to set the linker
6713 more appropriately. @xref{Libtool Convenience Libraries}, for a
6714 trick with @code{nodist_EXTRA_@dots{}_SOURCES}.
6716 A per-target @code{_LINK} variable will override the above selection.
6717 Per-target link flags will cause Automake to write a per-target
6718 @code{_LINK} variable according to the language chosen as above.
6721 @node Fortran 9x Support
6722 @comment node-name, next, previous, up
6723 @section Fortran 9x Support
6725 @cindex Fortran 9x support
6726 @cindex Support for Fortran 9x
6728 Automake includes support for Fortran 9x.
6730 Any package including Fortran 9x code must define the output variable
6731 @code{FC} in @file{configure.ac}; the simplest way to do this is to use
6732 the @code{AC_PROG_FC} macro (@pxref{Particular Programs, , Particular
6733 Program Checks, autoconf, The Autoconf Manual}).
6735 A few additional variables are defined when a Fortran 9x source file is
6741 The name of the Fortran 9x compiler.
6744 Any flags to pass to the Fortran 9x compiler.
6747 The maintainer's variant of @code{FCFLAGS}.
6750 The command used to actually compile a Fortran 9x source file. The file
6751 name is appended to form the complete command line.
6754 The command used to actually link a pure Fortran 9x program or shared
6760 * Compiling Fortran 9x Files:: Compiling Fortran 9x sources
6763 @node Compiling Fortran 9x Files
6764 @comment node-name, next, previous, up
6765 @subsection Compiling Fortran 9x Files
6767 @file{@var{file}.o} is made automatically from @file{@var{file}.f90},
6768 @file{@var{file}.f95}, @file{@var{file}.f03}, or @file{@var{file}.f08}
6769 by running the Fortran 9x compiler. The precise command used
6775 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f90) $<}
6778 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f95) $<}
6781 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f03) $<}
6784 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f08) $<}
6788 @node Java Support with gcj
6789 @comment node-name, next, previous, up
6790 @section Compiling Java sources using gcj
6792 @cindex Java support with gcj
6793 @cindex Support for Java with gcj
6794 @cindex Java to native code, compilation
6795 @cindex Compilation of Java to native code
6797 Automake includes support for natively compiled Java, using @command{gcj},
6798 the Java front end to the GNU Compiler Collection (rudimentary support
6799 for compiling Java to bytecode using the @command{javac} compiler is
6800 also present, @emph{albeit deprecated}; @pxref{Java}).
6802 Any package including Java code to be compiled must define the output
6803 variable @code{GCJ} in @file{configure.ac}; the variable @code{GCJFLAGS}
6804 must also be defined somehow (either in @file{configure.ac} or
6805 @file{Makefile.am}). The simplest way to do this is to use the
6806 @code{AM_PROG_GCJ} macro.
6810 By default, programs including Java source files are linked with
6813 As always, the contents of @code{AM_GCJFLAGS} are passed to every
6814 compilation invoking @command{gcj} (in its role as an ahead-of-time
6815 compiler, when invoking it to create @file{.class} files,
6816 @code{AM_JAVACFLAGS} is used instead). If it is necessary to pass
6817 options to @command{gcj} from @file{Makefile.am}, this variable, and not
6818 the user variable @code{GCJFLAGS}, should be used.
6822 @command{gcj} can be used to compile @file{.java}, @file{.class},
6823 @file{.zip}, or @file{.jar} files.
6825 When linking, @command{gcj} requires that the main class be specified
6826 using the @option{--main=} option. The easiest way to do this is to use
6827 the @code{_LDFLAGS} variable for the program.
6831 @comment node-name, next, previous, up
6832 @section Vala Support
6834 @cindex Vala Support
6835 @cindex Support for Vala
6837 Automake provides initial support for Vala
6838 (@uref{http://www.vala-project.org/}).
6839 This requires valac version 0.7.0 or later, and currently requires
6840 the user to use GNU @command{make}.
6843 foo_SOURCES = foo.vala bar.vala zardoc.c
6846 Any @file{.vala} file listed in a @code{_SOURCES} variable will be
6847 compiled into C code by the Vala compiler. The generated @file{.c} files are
6848 distributed. The end user does not need to have a Vala compiler installed.
6850 Automake ships with an Autoconf macro called @code{AM_PROG_VALAC}
6851 that will locate the Vala compiler and optionally check its version
6854 @defmac AM_PROG_VALAC (@ovar{minimum-version})
6855 Try to find a Vala compiler in @env{PATH}. If it is found, the variable
6856 @code{VALAC} is set. Optionally a minimum release number of the compiler
6860 AM_PROG_VALAC([0.7.0])
6864 There are a few variables that are used when compiling Vala sources:
6868 Path to the Vala compiler.
6871 Additional arguments for the Vala compiler.
6874 The maintainer's variant of @code{VALAFLAGS}.
6877 lib_LTLIBRARIES = libfoo.la
6878 libfoo_la_SOURCES = foo.vala
6882 Note that currently, you cannot use per-target @code{*_VALAFLAGS}
6883 (@pxref{Renamed Objects}) to produce different C files from one Vala
6887 @node Support for Other Languages
6888 @comment node-name, next, previous, up
6889 @section Support for Other Languages
6891 Automake currently only includes full support for C, C++ (@pxref{C++
6892 Support}), Objective C (@pxref{Objective C Support}), Fortran 77
6893 (@pxref{Fortran 77 Support}), Fortran 9x (@pxref{Fortran 9x Support}),
6894 and Java (@pxref{Java Support with gcj}). There is only rudimentary
6895 support for other languages, support for which will be improved based
6898 Some limited support for adding your own languages is available via the
6899 suffix rule handling (@pxref{Suffixes}).
6902 @section Automatic dependency tracking
6904 As a developer it is often painful to continually update the
6905 @file{Makefile.am} whenever the include-file dependencies change in a
6906 project. Automake supplies a way to automatically track dependency
6907 changes (@pxref{Dependency Tracking}).
6909 @cindex Dependency tracking
6910 @cindex Automatic dependency tracking
6912 Automake always uses complete dependencies for a compilation,
6913 including system headers. Automake's model is that dependency
6914 computation should be a side effect of the build. To this end,
6915 dependencies are computed by running all compilations through a
6916 special wrapper program called @command{depcomp}. @command{depcomp}
6917 understands how to coax many different C and C++ compilers into
6918 generating dependency information in the format it requires.
6919 @samp{automake -a} will install @command{depcomp} into your source
6920 tree for you. If @command{depcomp} can't figure out how to properly
6921 invoke your compiler, dependency tracking will simply be disabled for
6924 @cindex @command{depcomp}
6926 Experience with earlier versions of Automake (@pxref{Dependency
6927 Tracking Evolution}) taught us that it is not reliable to generate
6928 dependencies only on the maintainer's system, as configurations vary
6929 too much. So instead Automake implements dependency tracking at build
6932 Automatic dependency tracking can be suppressed by putting
6933 @option{no-dependencies} in the variable @code{AUTOMAKE_OPTIONS}, or
6934 passing @option{no-dependencies} as an argument to @code{AM_INIT_AUTOMAKE}
6935 (this should be the preferred way). Or, you can invoke @command{automake}
6936 with the @option{-i} option. Dependency tracking is enabled by default.
6938 @vindex AUTOMAKE_OPTIONS
6939 @opindex no-dependencies
6941 The person building your package also can choose to disable dependency
6942 tracking by configuring with @option{--disable-dependency-tracking}.
6944 @cindex Disabling dependency tracking
6945 @cindex Dependency tracking, disabling
6949 @section Support for executable extensions
6951 @cindex Executable extension
6952 @cindex Extension, executable
6955 On some platforms, such as Windows, executables are expected to have an
6956 extension such as @file{.exe}. On these platforms, some compilers (GCC
6957 among them) will automatically generate @file{foo.exe} when asked to
6958 generate @file{foo}.
6960 Automake provides mostly-transparent support for this. Unfortunately
6961 @emph{mostly} doesn't yet mean @emph{fully}. Until the English
6962 dictionary is revised, you will have to assist Automake if your package
6963 must support those platforms.
6965 One thing you must be aware of is that, internally, Automake rewrites
6966 something like this:
6969 bin_PROGRAMS = liver
6975 bin_PROGRAMS = liver$(EXEEXT)
6978 The targets Automake generates are likewise given the @samp{$(EXEEXT)}
6981 The variables @code{TESTS} and @code{XFAIL_TESTS} (@pxref{Simple Tests})
6982 are also rewritten if they contain filenames that have been declared as
6983 programs in the same @file{Makefile}. (This is mostly useful when some
6984 programs from @code{check_PROGRAMS} are listed in @code{TESTS}.)
6986 However, Automake cannot apply this rewriting to @command{configure}
6987 substitutions. This means that if you are conditionally building a
6988 program using such a substitution, then your @file{configure.ac} must
6989 take care to add @samp{$(EXEEXT)} when constructing the output variable.
6991 With Autoconf 2.13 and earlier, you must explicitly use @code{AC_EXEEXT}
6992 to get this support. With Autoconf 2.50, @code{AC_EXEEXT} is run
6993 automatically if you configure a compiler (say, through
6996 Sometimes maintainers like to write an explicit link rule for their
6997 program. Without executable extension support, this is easy---you
6998 simply write a rule whose target is the name of the program. However,
6999 when executable extension support is enabled, you must instead add the
7000 @samp{$(EXEEXT)} suffix.
7002 Unfortunately, due to the change in Autoconf 2.50, this means you must
7003 always add this extension. However, this is a problem for maintainers
7004 who know their package will never run on a platform that has
7005 executable extensions. For those maintainers, the @option{no-exeext}
7006 option (@pxref{Options}) will disable this feature. This works in a
7007 fairly ugly way; if @option{no-exeext} is seen, then the presence of a
7008 rule for a target named @code{foo} in @file{Makefile.am} will override
7009 an @command{automake}-generated rule for @samp{foo$(EXEEXT)}. Without
7010 the @option{no-exeext} option, this use will give a diagnostic.
7014 @chapter Other Derived Objects
7016 Automake can handle derived objects that are not C programs. Sometimes
7017 the support for actually building such objects must be explicitly
7018 supplied, but Automake will still automatically handle installation and
7022 * Scripts:: Executable scripts
7023 * Headers:: Header files
7024 * Data:: Architecture-independent data files
7025 * Sources:: Derived sources
7030 @section Executable Scripts
7032 @cindex @code{_SCRIPTS} primary, defined
7033 @cindex @code{SCRIPTS} primary, defined
7034 @cindex Primary variable, @code{SCRIPTS}
7036 @cindex Installing scripts
7038 It is possible to define and install programs that are scripts. Such
7039 programs are listed using the @code{SCRIPTS} primary name. When the
7040 script is distributed in its final, installable form, the
7041 @file{Makefile} usually looks as follows:
7045 # Install my_script in $(bindir) and distribute it.
7046 dist_bin_SCRIPTS = my_script
7049 Scripts are not distributed by default; as we have just seen, those
7050 that should be distributed can be specified using a @code{dist_}
7051 prefix as with other primaries.
7053 @cindex @code{SCRIPTS}, installation directories
7055 @vindex sbin_SCRIPTS
7056 @vindex libexec_SCRIPTS
7057 @vindex pkgdata_SCRIPTS
7058 @vindex pkglibexec_SCRIPTS
7059 @vindex noinst_SCRIPTS
7060 @vindex check_SCRIPTS
7062 Scripts can be installed in @code{bindir}, @code{sbindir},
7063 @code{libexecdir}, @code{pkglibexecdir}, or @code{pkgdatadir}.
7065 Scripts that need not be installed can be listed in
7066 @code{noinst_SCRIPTS}, and among them, those which are needed only by
7067 @samp{make check} should go in @code{check_SCRIPTS}.
7069 When a script needs to be built, the @file{Makefile.am} should include
7070 the appropriate rules. For instance the @command{automake} program
7071 itself is a Perl script that is generated from @file{automake.in}.
7072 Here is how this is handled:
7075 bin_SCRIPTS = automake
7076 CLEANFILES = $(bin_SCRIPTS)
7077 EXTRA_DIST = automake.in
7079 do_subst = sed -e 's,[@@]datadir[@@],$(datadir),g' \
7080 -e 's,[@@]PERL[@@],$(PERL),g' \
7081 -e 's,[@@]PACKAGE[@@],$(PACKAGE),g' \
7082 -e 's,[@@]VERSION[@@],$(VERSION),g' \
7085 automake: automake.in Makefile
7086 $(do_subst) < $(srcdir)/automake.in > automake
7090 Such scripts for which a build rule has been supplied need to be
7091 deleted explicitly using @code{CLEANFILES} (@pxref{Clean}), and their
7092 sources have to be distributed, usually with @code{EXTRA_DIST}
7093 (@pxref{Basics of Distribution}).
7095 Another common way to build scripts is to process them from
7096 @file{configure} with @code{AC_CONFIG_FILES}. In this situation
7097 Automake knows which files should be cleaned and distributed, and what
7098 the rebuild rules should look like.
7100 For instance if @file{configure.ac} contains
7103 AC_CONFIG_FILES([src/my_script], [chmod +x src/my_script])
7107 to build @file{src/my_script} from @file{src/my_script.in}, then a
7108 @file{src/Makefile.am} to install this script in @code{$(bindir)} can
7112 bin_SCRIPTS = my_script
7113 CLEANFILES = $(bin_SCRIPTS)
7117 There is no need for @code{EXTRA_DIST} or any build rule: Automake
7118 infers them from @code{AC_CONFIG_FILES} (@pxref{Requirements}).
7119 @code{CLEANFILES} is still useful, because by default Automake will
7120 clean targets of @code{AC_CONFIG_FILES} in @code{distclean}, not
7123 Although this looks simpler, building scripts this way has one
7124 drawback: directory variables such as @code{$(datadir)} are not fully
7125 expanded and may refer to other directory variables.
7128 @section Header files
7130 @cindex @code{_HEADERS} primary, defined
7131 @cindex @code{HEADERS} primary, defined
7132 @cindex Primary variable, @code{HEADERS}
7134 @vindex noinst_HEADERS
7135 @cindex @code{HEADERS}, installation directories
7136 @cindex Installing headers
7137 @vindex include_HEADERS
7138 @vindex oldinclude_HEADERS
7139 @vindex pkginclude_HEADERS
7142 Header files that must be installed are specified by the
7143 @code{HEADERS} family of variables. Headers can be installed in
7144 @code{includedir}, @code{oldincludedir}, @code{pkgincludedir} or any
7145 other directory you may have defined (@pxref{Uniform}). For instance,
7148 include_HEADERS = foo.h bar/bar.h
7152 will install the two files as @file{$(includedir)/foo.h} and
7153 @file{$(includedir)/bar.h}.
7155 The @code{nobase_} prefix is also supported,
7158 nobase_include_HEADERS = foo.h bar/bar.h
7162 will install the two files as @file{$(includedir)/foo.h} and
7163 @file{$(includedir)/bar/bar.h} (@pxref{Alternative}).
7165 @vindex noinst_HEADERS
7166 Usually, only header files that accompany installed libraries need to
7167 be installed. Headers used by programs or convenience libraries are
7168 not installed. The @code{noinst_HEADERS} variable can be used for
7169 such headers. However when the header actually belongs to a single
7170 convenience library or program, we recommend listing it in the
7171 program's or library's @code{_SOURCES} variable (@pxref{Program
7172 Sources}) instead of in @code{noinst_HEADERS}. This is clearer for
7173 the @file{Makefile.am} reader. @code{noinst_HEADERS} would be the
7174 right variable to use in a directory containing only headers and no
7175 associated library or program.
7177 All header files must be listed somewhere; in a @code{_SOURCES}
7178 variable or in a @code{_HEADERS} variable. Missing ones will not
7179 appear in the distribution.
7181 For header files that are built and must not be distributed, use the
7182 @code{nodist_} prefix as in @code{nodist_include_HEADERS} or
7183 @code{nodist_prog_SOURCES}. If these generated headers are needed
7184 during the build, you must also ensure they exist before they are
7185 used (@pxref{Sources}).
7189 @section Architecture-independent data files
7191 @cindex @code{_DATA} primary, defined
7192 @cindex @code{DATA} primary, defined
7193 @cindex Primary variable, @code{DATA}
7196 Automake supports the installation of miscellaneous data files using the
7197 @code{DATA} family of variables.
7201 @vindex sysconf_DATA
7202 @vindex sharedstate_DATA
7203 @vindex localstate_DATA
7204 @vindex pkgdata_DATA
7206 Such data can be installed in the directories @code{datadir},
7207 @code{sysconfdir}, @code{sharedstatedir}, @code{localstatedir}, or
7210 By default, data files are @emph{not} included in a distribution. Of
7211 course, you can use the @code{dist_} prefix to change this on a
7214 Here is how Automake declares its auxiliary data files:
7217 dist_pkgdata_DATA = clean-kr.am clean.am @dots{}
7222 @section Built Sources
7224 Because Automake's automatic dependency tracking works as a side-effect
7225 of compilation (@pxref{Dependencies}) there is a bootstrap issue: a
7226 target should not be compiled before its dependencies are made, but
7227 these dependencies are unknown until the target is first compiled.
7229 Ordinarily this is not a problem, because dependencies are distributed
7230 sources: they preexist and do not need to be built. Suppose that
7231 @file{foo.c} includes @file{foo.h}. When it first compiles
7232 @file{foo.o}, @command{make} only knows that @file{foo.o} depends on
7233 @file{foo.c}. As a side-effect of this compilation @command{depcomp}
7234 records the @file{foo.h} dependency so that following invocations of
7235 @command{make} will honor it. In these conditions, it's clear there is
7236 no problem: either @file{foo.o} doesn't exist and has to be built
7237 (regardless of the dependencies), or accurate dependencies exist and
7238 they can be used to decide whether @file{foo.o} should be rebuilt.
7240 It's a different story if @file{foo.h} doesn't exist by the first
7241 @command{make} run. For instance, there might be a rule to build
7242 @file{foo.h}. This time @file{file.o}'s build will fail because the
7243 compiler can't find @file{foo.h}. @command{make} failed to trigger the
7244 rule to build @file{foo.h} first by lack of dependency information.
7246 @vindex BUILT_SOURCES
7247 @cindex @code{BUILT_SOURCES}, defined
7249 The @code{BUILT_SOURCES} variable is a workaround for this problem. A
7250 source file listed in @code{BUILT_SOURCES} is made on @samp{make all}
7251 or @samp{make check} (or even @samp{make install}) before other
7252 targets are processed. However, such a source file is not
7253 @emph{compiled} unless explicitly requested by mentioning it in some
7254 other @code{_SOURCES} variable.
7256 So, to conclude our introductory example, we could use
7257 @samp{BUILT_SOURCES = foo.h} to ensure @file{foo.h} gets built before
7258 any other target (including @file{foo.o}) during @samp{make all} or
7261 @code{BUILT_SOURCES} is actually a bit of a misnomer, as any file which
7262 must be created early in the build process can be listed in this
7263 variable. Moreover, all built sources do not necessarily have to be
7264 listed in @code{BUILT_SOURCES}. For instance, a generated @file{.c} file
7265 doesn't need to appear in @code{BUILT_SOURCES} (unless it is included by
7266 another source), because it's a known dependency of the associated
7269 It might be important to emphasize that @code{BUILT_SOURCES} is
7270 honored only by @samp{make all}, @samp{make check} and @samp{make
7271 install}. This means you cannot build a specific target (e.g.,
7272 @samp{make foo}) in a clean tree if it depends on a built source.
7273 However it will succeed if you have run @samp{make all} earlier,
7274 because accurate dependencies are already available.
7276 The next section illustrates and discusses the handling of built sources
7280 * Built Sources Example:: Several ways to handle built sources.
7283 @node Built Sources Example
7284 @subsection Built Sources Example
7286 Suppose that @file{foo.c} includes @file{bindir.h}, which is
7287 installation-dependent and not distributed: it needs to be built. Here
7288 @file{bindir.h} defines the preprocessor macro @code{bindir} to the
7289 value of the @command{make} variable @code{bindir} (inherited from
7292 We suggest several implementations below. It's not meant to be an
7293 exhaustive listing of all ways to handle built sources, but it will give
7294 you a few ideas if you encounter this issue.
7296 @subsubheading First Try
7298 This first implementation will illustrate the bootstrap issue mentioned
7299 in the previous section (@pxref{Sources}).
7301 Here is a tentative @file{Makefile.am}.
7307 nodist_foo_SOURCES = bindir.h
7308 CLEANFILES = bindir.h
7310 echo '#define bindir "$(bindir)"' >$@@
7313 This setup doesn't work, because Automake doesn't know that @file{foo.c}
7314 includes @file{bindir.h}. Remember, automatic dependency tracking works
7315 as a side-effect of compilation, so the dependencies of @file{foo.o} will
7316 be known only after @file{foo.o} has been compiled (@pxref{Dependencies}).
7317 The symptom is as follows.
7321 source='foo.c' object='foo.o' libtool=no \
7322 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
7323 depmode=gcc /bin/sh ./depcomp \
7324 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
7325 foo.c:2: bindir.h: No such file or directory
7326 make: *** [foo.o] Error 1
7329 In this example @file{bindir.h} is not distributed nor installed, and
7330 it is not even being built on-time. One may wonder if the
7331 @samp{nodist_foo_SOURCES = bindir.h} line has any use at all. This
7332 line simply states that @file{bindir.h} is a source of @code{foo}, so
7333 for instance, it should be inspected while generating tags
7334 (@pxref{Tags}). In other words, it does not help our present problem,
7335 and the build would fail identically without it.
7337 @subsubheading Using @code{BUILT_SOURCES}
7339 A solution is to require @file{bindir.h} to be built before anything
7340 else. This is what @code{BUILT_SOURCES} is meant for (@pxref{Sources}).
7345 nodist_foo_SOURCES = bindir.h
7346 BUILT_SOURCES = bindir.h
7347 CLEANFILES = bindir.h
7349 echo '#define bindir "$(bindir)"' >$@@
7352 See how @file{bindir.h} gets built first:
7356 echo '#define bindir "/usr/local/bin"' >bindir.h
7358 make[1]: Entering directory `/home/adl/tmp'
7359 source='foo.c' object='foo.o' libtool=no \
7360 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
7361 depmode=gcc /bin/sh ./depcomp \
7362 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
7363 gcc -g -O2 -o foo foo.o
7364 make[1]: Leaving directory `/home/adl/tmp'
7367 However, as said earlier, @code{BUILT_SOURCES} applies only to the
7368 @code{all}, @code{check}, and @code{install} targets. It still fails
7369 if you try to run @samp{make foo} explicitly:
7373 test -z "bindir.h" || rm -f bindir.h
7374 test -z "foo" || rm -f foo
7376 % : > .deps/foo.Po # Suppress previously recorded dependencies
7378 source='foo.c' object='foo.o' libtool=no \
7379 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
7380 depmode=gcc /bin/sh ./depcomp \
7381 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
7382 foo.c:2: bindir.h: No such file or directory
7383 make: *** [foo.o] Error 1
7386 @subsubheading Recording Dependencies manually
7388 Usually people are happy enough with @code{BUILT_SOURCES} because they
7389 never build targets such as @samp{make foo} before @samp{make all}, as
7390 in the previous example. However if this matters to you, you can
7391 avoid @code{BUILT_SOURCES} and record such dependencies explicitly in
7392 the @file{Makefile.am}.
7397 nodist_foo_SOURCES = bindir.h
7398 foo.$(OBJEXT): bindir.h
7399 CLEANFILES = bindir.h
7401 echo '#define bindir "$(bindir)"' >$@@
7404 You don't have to list @emph{all} the dependencies of @file{foo.o}
7405 explicitly, only those that might need to be built. If a dependency
7406 already exists, it will not hinder the first compilation and will be
7407 recorded by the normal dependency tracking code. (Note that after
7408 this first compilation the dependency tracking code will also have
7409 recorded the dependency between @file{foo.o} and
7410 @file{bindir.h}; so our explicit dependency is really useful to
7411 the first build only.)
7413 Adding explicit dependencies like this can be a bit dangerous if you are
7414 not careful enough. This is due to the way Automake tries not to
7415 overwrite your rules (it assumes you know better than it).
7416 @samp{foo.$(OBJEXT): bindir.h} supersedes any rule Automake may want to
7417 output to build @samp{foo.$(OBJEXT)}. It happens to work in this case
7418 because Automake doesn't have to output any @samp{foo.$(OBJEXT):}
7419 target: it relies on a suffix rule instead (i.e., @samp{.c.$(OBJEXT):}).
7420 Always check the generated @file{Makefile.in} if you do this.
7422 @subsubheading Build @file{bindir.h} from @file{configure}
7424 It's possible to define this preprocessor macro from @file{configure},
7425 either in @file{config.h} (@pxref{Defining Directories, , Defining
7426 Directories, autoconf, The Autoconf Manual}), or by processing a
7427 @file{bindir.h.in} file using @code{AC_CONFIG_FILES}
7428 (@pxref{Configuration Actions, ,Configuration Actions, autoconf, The
7431 At this point it should be clear that building @file{bindir.h} from
7432 @file{configure} works well for this example. @file{bindir.h} will exist
7433 before you build any target, hence will not cause any dependency issue.
7435 The Makefile can be shrunk as follows. We do not even have to mention
7443 However, it's not always possible to build sources from
7444 @file{configure}, especially when these sources are generated by a tool
7445 that needs to be built first.
7447 @subsubheading Build @file{bindir.c}, not @file{bindir.h}.
7449 Another attractive idea is to define @code{bindir} as a variable or
7450 function exported from @file{bindir.o}, and build @file{bindir.c}
7451 instead of @file{bindir.h}.
7454 noinst_PROGRAMS = foo
7455 foo_SOURCES = foo.c bindir.h
7456 nodist_foo_SOURCES = bindir.c
7457 CLEANFILES = bindir.c
7459 echo 'const char bindir[] = "$(bindir)";' >$@@
7462 @file{bindir.h} contains just the variable's declaration and doesn't
7463 need to be built, so it won't cause any trouble. @file{bindir.o} is
7464 always dependent on @file{bindir.c}, so @file{bindir.c} will get built
7467 @subsubheading Which is best?
7469 There is no panacea, of course. Each solution has its merits and
7472 You cannot use @code{BUILT_SOURCES} if the ability to run @samp{make
7473 foo} on a clean tree is important to you.
7475 You won't add explicit dependencies if you are leery of overriding
7476 an Automake rule by mistake.
7478 Building files from @file{./configure} is not always possible, neither
7479 is converting @file{.h} files into @file{.c} files.
7482 @node Other GNU Tools
7483 @chapter Other GNU Tools
7485 Since Automake is primarily intended to generate @file{Makefile.in}s for
7486 use in GNU programs, it tries hard to interoperate with other GNU tools.
7489 * Emacs Lisp:: Emacs Lisp
7492 * Java:: Java bytecode compilation (deprecated)
7500 @cindex @code{_LISP} primary, defined
7501 @cindex @code{LISP} primary, defined
7502 @cindex Primary variable, @code{LISP}
7508 Automake provides some support for Emacs Lisp. The @code{LISP} primary
7509 is used to hold a list of @file{.el} files. Possible prefixes for this
7510 primary are @code{lisp_} and @code{noinst_}. Note that if
7511 @code{lisp_LISP} is defined, then @file{configure.ac} must run
7512 @code{AM_PATH_LISPDIR} (@pxref{Macros}).
7514 @vindex dist_lisp_LISP
7515 @vindex dist_noinst_LISP
7516 Lisp sources are not distributed by default. You can prefix the
7517 @code{LISP} primary with @code{dist_}, as in @code{dist_lisp_LISP} or
7518 @code{dist_noinst_LISP}, to indicate that these files should be
7521 Automake will byte-compile all Emacs Lisp source files using the Emacs
7522 found by @code{AM_PATH_LISPDIR}, if any was found.
7524 Byte-compiled Emacs Lisp files are not portable among all versions of
7525 Emacs, so it makes sense to turn this off if you expect sites to have
7526 more than one version of Emacs installed. Furthermore, many packages
7527 don't actually benefit from byte-compilation. Still, we recommend
7528 that you byte-compile your Emacs Lisp sources. It is probably better
7529 for sites with strange setups to cope for themselves than to make the
7530 installation less nice for everybody else.
7532 There are two ways to avoid byte-compiling. Historically, we have
7533 recommended the following construct.
7536 lisp_LISP = file1.el file2.el
7541 @code{ELCFILES} is an internal Automake variable that normally lists
7542 all @file{.elc} files that must be byte-compiled. Automake defines
7543 @code{ELCFILES} automatically from @code{lisp_LISP}. Emptying this
7544 variable explicitly prevents byte-compilation.
7546 Since Automake 1.8, we now recommend using @code{lisp_DATA} instead:
7548 @c Keep in sync with primary-prefix-couples-documented-valid.test.
7550 lisp_DATA = file1.el file2.el
7553 Note that these two constructs are not equivalent. @code{_LISP} will
7554 not install a file if Emacs is not installed, while @code{_DATA} will
7555 always install its files.
7560 @cindex GNU Gettext support
7561 @cindex Gettext support
7562 @cindex Support for GNU Gettext
7564 If @code{AM_GNU_GETTEXT} is seen in @file{configure.ac}, then Automake
7565 turns on support for GNU gettext, a message catalog system for
7566 internationalization
7567 (@pxref{Top, , Introduction, gettext, GNU gettext utilities}).
7569 The @code{gettext} support in Automake requires the addition of one or
7570 two subdirectories to the package: @file{po} and possibly also @file{intl}.
7571 The latter is needed if @code{AM_GNU_GETTEXT} is not invoked with the
7572 @samp{external} argument, or if @code{AM_GNU_GETTEXT_INTL_SUBDIR} is used.
7573 Automake ensures that these directories exist and are mentioned in
7579 Automake provides support for GNU Libtool (@pxref{Top, , Introduction,
7580 libtool, The Libtool Manual}) with the @code{LTLIBRARIES} primary.
7581 @xref{A Shared Library}.
7585 @section Java bytecode compilation (deprecated)
7587 @cindex @code{_JAVA} primary, defined
7588 @cindex @code{JAVA} primary, defined
7589 @cindex Primary variable, @code{JAVA}
7590 @cindex Java to bytecode, compilation
7591 @cindex Compilation of Java to bytecode
7593 Automake provides some minimal support for Java bytecode compilation with
7594 the @code{JAVA} primary (in addition to the support for compiling Java to
7595 native machine code; @pxref{Java Support with gcj}). Note however that
7596 @emph{the interface and most features described here are deprecated}; the
7597 next automake release will strive to provide a better and cleaner
7598 interface, which however @emph{won't be backward-compatible}; the present
7599 interface will probably be removed altogether in future automake releases
7600 (1.13 or later), so don't use it in new code.
7602 Any @file{.java} files listed in a @code{_JAVA} variable will be
7603 compiled with @code{JAVAC} at build time. By default, @file{.java}
7604 files are not included in the distribution, you should use the
7605 @code{dist_} prefix to distribute them.
7607 Here is a typical setup for distributing @file{.java} files and
7608 installing the @file{.class} files resulting from their compilation.
7610 @c Keep in sync with primary-prefix-couples-documented-valid.test.
7612 javadir = $(datadir)/java
7613 dist_java_JAVA = a.java b.java @dots{}
7616 @cindex @code{JAVA} restrictions
7617 @cindex Restrictions for @code{JAVA}
7619 Currently Automake enforces the restriction that only one @code{_JAVA}
7620 primary can be used in a given @file{Makefile.am}. The reason for this
7621 restriction is that, in general, it isn't possible to know which
7622 @file{.class} files were generated from which @file{.java} files, so
7623 it would be impossible to know which files to install where. For
7624 instance, a @file{.java} file can define multiple classes; the resulting
7625 @file{.class} file names cannot be predicted without parsing the
7628 There are a few variables that are used when compiling Java sources:
7632 The name of the Java compiler. This defaults to @samp{javac}.
7635 The flags to pass to the compiler. This is considered to be a user
7636 variable (@pxref{User Variables}).
7639 More flags to pass to the Java compiler. This, and not
7640 @code{JAVACFLAGS}, should be used when it is necessary to put Java
7641 compiler flags into @file{Makefile.am}.
7644 The value of this variable is passed to the @option{-d} option to
7645 @code{javac}. It defaults to @samp{$(top_builddir)}.
7648 This variable is a shell expression that is used to set the
7649 @env{CLASSPATH} environment variable on the @code{javac} command line.
7650 (In the future we will probably handle class path setting differently.)
7657 @cindex @code{_PYTHON} primary, defined
7658 @cindex @code{PYTHON} primary, defined
7659 @cindex Primary variable, @code{PYTHON}
7662 Automake provides support for Python compilation with the
7663 @code{PYTHON} primary. A typical setup is to call
7664 @code{AM_PATH_PYTHON} in @file{configure.ac} and use a line like the
7665 following in @file{Makefile.am}:
7668 python_PYTHON = tree.py leave.py
7671 Any files listed in a @code{_PYTHON} variable will be byte-compiled
7672 with @command{py-compile} at install time. @command{py-compile}
7673 actually creates both standard (@file{.pyc}) and optimized
7674 (@file{.pyo}) byte-compiled versions of the source files. Note that
7675 because byte-compilation occurs at install time, any files listed in
7676 @code{noinst_PYTHON} will not be compiled. Python source files are
7677 included in the distribution by default, prepend @code{nodist_} (as in
7678 @code{nodist_python_PYTHON}) to omit them.
7680 Automake ships with an Autoconf macro called @code{AM_PATH_PYTHON}
7681 that will determine some Python-related directory variables (see
7682 below). If you have called @code{AM_PATH_PYTHON} from
7683 @file{configure.ac}, then you may use the variables
7684 @c Keep in sync with primary-prefix-couples-documented-valid.test.
7685 @code{python_PYTHON} or @code{pkgpython_PYTHON} to list Python source
7686 files in your @file{Makefile.am}, depending on where you want your files
7687 installed (see the definitions of @code{pythondir} and
7688 @code{pkgpythondir} below).
7690 @defmac AM_PATH_PYTHON (@ovar{version}, @ovar{action-if-found},
7691 @ovar{action-if-not-found})
7693 Search for a Python interpreter on the system. This macro takes three
7694 optional arguments. The first argument, if present, is the minimum
7695 version of Python required for this package: @code{AM_PATH_PYTHON}
7696 will skip any Python interpreter that is older than @var{version}.
7697 If an interpreter is found and satisfies @var{version}, then
7698 @var{action-if-found} is run. Otherwise, @var{action-if-not-found} is
7701 If @var{action-if-not-found} is not specified, as in the following
7702 example, the default is to abort @command{configure}.
7705 AM_PATH_PYTHON([2.2])
7709 This is fine when Python is an absolute requirement for the package.
7710 If Python >= 2.5 was only @emph{optional} to the package,
7711 @code{AM_PATH_PYTHON} could be called as follows.
7714 AM_PATH_PYTHON([2.5],, [:])
7717 If the @env{PYTHON} variable is set when @code{AM_PATH_PYTHON} is
7718 called, then that will be the only Python interpreter that is tried.
7720 @code{AM_PATH_PYTHON} creates the following output variables based on
7721 the Python installation found during configuration.
7726 The name of the Python executable, or @samp{:} if no suitable
7727 interpreter could be found.
7729 Assuming @var{action-if-not-found} is used (otherwise @file{./configure}
7730 will abort if Python is absent), the value of @code{PYTHON} can be used
7731 to setup a conditional in order to disable the relevant part of a build
7735 AM_PATH_PYTHON(,, [:])
7736 AM_CONDITIONAL([HAVE_PYTHON], [test "$PYTHON" != :])
7739 @item PYTHON_VERSION
7740 The Python version number, in the form @var{major}.@var{minor}
7741 (e.g., @samp{2.5}). This is currently the value of
7742 @samp{sys.version[:3]}.
7745 The string @samp{$@{prefix@}}. This term may be used in future work
7746 that needs the contents of Python's @samp{sys.prefix}, but general
7747 consensus is to always use the value from @command{configure}.
7749 @item PYTHON_EXEC_PREFIX
7750 The string @samp{$@{exec_prefix@}}. This term may be used in future work
7751 that needs the contents of Python's @samp{sys.exec_prefix}, but general
7752 consensus is to always use the value from @command{configure}.
7754 @item PYTHON_PLATFORM
7755 The canonical name used by Python to describe the operating system, as
7756 given by @samp{sys.platform}. This value is sometimes needed when
7757 building Python extensions.
7760 The directory name for the @file{site-packages} subdirectory of the
7761 standard Python install tree.
7764 This is the directory under @code{pythondir} that is named after the
7765 package. That is, it is @samp{$(pythondir)/$(PACKAGE)}. It is provided
7769 This is the directory where Python extension modules (shared libraries)
7770 should be installed. An extension module written in C could be declared
7771 as follows to Automake:
7773 @c Keep in sync with primary-prefix-couples-documented-valid.test.
7775 pyexec_LTLIBRARIES = quaternion.la
7776 quaternion_la_SOURCES = quaternion.c support.c support.h
7777 quaternion_la_LDFLAGS = -avoid-version -module
7781 This is a convenience variable that is defined as
7782 @samp{$(pyexecdir)/$(PACKAGE)}.
7785 All these directory variables have values that start with either
7786 @samp{$@{prefix@}} or @samp{$@{exec_prefix@}} unexpanded. This works
7787 fine in @file{Makefiles}, but it makes these variables hard to use in
7788 @file{configure}. This is mandated by the GNU coding standards, so
7789 that the user can run @samp{make prefix=/foo install}. The Autoconf
7790 manual has a section with more details on this topic
7791 (@pxref{Installation Directory Variables, , Installation Directory
7792 Variables, autoconf, The Autoconf Manual}). See also @ref{Hard-Coded
7797 @chapter Building documentation
7799 Currently Automake provides support for Texinfo and man pages.
7803 * Man Pages:: Man pages
7810 @cindex @code{_TEXINFOS} primary, defined
7811 @cindex @code{TEXINFOS} primary, defined
7812 @cindex Primary variable, @code{TEXINFOS}
7813 @cindex HTML output using Texinfo
7814 @cindex PDF output using Texinfo
7815 @cindex PS output using Texinfo
7816 @cindex DVI output using Texinfo
7818 @vindex info_TEXINFOS
7820 If the current directory contains Texinfo source, you must declare it
7821 with the @code{TEXINFOS} primary. Generally Texinfo files are converted
7822 into info, and thus the @code{info_TEXINFOS} variable is most commonly used
7823 here. Any Texinfo source file must end in the @file{.texi},
7824 @file{.txi}, or @file{.texinfo} extension. We recommend @file{.texi}
7827 Automake generates rules to build @file{.info}, @file{.dvi},
7828 @file{.ps}, @file{.pdf} and @file{.html} files from your Texinfo
7829 sources. Following the GNU Coding Standards, only the @file{.info}
7830 files are built by @samp{make all} and installed by @samp{make
7831 install} (unless you use @option{no-installinfo}, see below).
7832 Furthermore, @file{.info} files are automatically distributed so that
7833 Texinfo is not a prerequisite for installing your package.
7839 @trindex install-dvi
7840 @trindex install-html
7841 @trindex install-pdf
7843 Other documentation formats can be built on request by @samp{make
7844 dvi}, @samp{make ps}, @samp{make pdf} and @samp{make html}, and they
7845 can be installed with @samp{make install-dvi}, @samp{make install-ps},
7846 @samp{make install-pdf} and @samp{make install-html} explicitly.
7847 @samp{make uninstall} will remove everything: the Texinfo
7848 documentation installed by default as well as all the above optional
7851 All these targets can be extended using @samp{-local} rules
7852 (@pxref{Extending}).
7854 @cindex Texinfo flag, @code{VERSION}
7855 @cindex Texinfo flag, @code{UPDATED}
7856 @cindex Texinfo flag, @code{EDITION}
7857 @cindex Texinfo flag, @code{UPDATED-MONTH}
7859 @cindex @code{VERSION} Texinfo flag
7860 @cindex @code{UPDATED} Texinfo flag
7861 @cindex @code{EDITION} Texinfo flag
7862 @cindex @code{UPDATED-MONTH} Texinfo flag
7864 @cindex @file{mdate-sh}
7866 If the @file{.texi} file @code{@@include}s @file{version.texi}, then
7867 that file will be automatically generated. The file @file{version.texi}
7868 defines four Texinfo flag you can reference using
7869 @code{@@value@{EDITION@}}, @code{@@value@{VERSION@}},
7870 @code{@@value@{UPDATED@}}, and @code{@@value@{UPDATED-MONTH@}}.
7875 Both of these flags hold the version number of your program. They are
7876 kept separate for clarity.
7879 This holds the date the primary @file{.texi} file was last modified.
7882 This holds the name of the month in which the primary @file{.texi} file
7886 The @file{version.texi} support requires the @command{mdate-sh}
7887 script; this script is supplied with Automake and automatically
7888 included when @command{automake} is invoked with the
7889 @option{--add-missing} option.
7891 If you have multiple Texinfo files, and you want to use the
7892 @file{version.texi} feature, then you have to have a separate version
7893 file for each Texinfo file. Automake will treat any include in a
7894 Texinfo file that matches @file{vers*.texi} just as an automatically
7895 generated version file.
7897 Sometimes an info file actually depends on more than one @file{.texi}
7898 file. For instance, in GNU Hello, @file{hello.texi} includes the file
7899 @file{fdl.texi}. You can tell Automake about these dependencies using
7900 the @code{@var{texi}_TEXINFOS} variable. Here is how GNU Hello does it:
7905 info_TEXINFOS = hello.texi
7906 hello_TEXINFOS = fdl.texi
7909 @cindex @file{texinfo.tex}
7911 By default, Automake requires the file @file{texinfo.tex} to appear in
7912 the same directory as the @file{Makefile.am} file that lists the
7913 @file{.texi} files. If you used @code{AC_CONFIG_AUX_DIR} in
7914 @file{configure.ac} (@pxref{Input, , Finding `configure' Input,
7915 autoconf, The Autoconf Manual}), then @file{texinfo.tex} is looked for
7916 there. In both cases, @command{automake} then supplies @file{texinfo.tex} if
7917 @option{--add-missing} is given, and takes care of its distribution.
7918 However, if you set the @code{TEXINFO_TEX} variable (see below),
7919 it overrides the location of the file and turns off its installation
7920 into the source as well as its distribution.
7922 The option @option{no-texinfo.tex} can be used to eliminate the
7923 requirement for the file @file{texinfo.tex}. Use of the variable
7924 @code{TEXINFO_TEX} is preferable, however, because that allows the
7925 @code{dvi}, @code{ps}, and @code{pdf} targets to still work.
7927 @cindex Option, @code{no-installinfo}
7928 @cindex Target, @code{install-info}
7929 @cindex @code{install-info} target
7930 @cindex @code{no-installinfo} option
7932 @opindex no-installinfo
7933 @trindex install-info
7935 Automake generates an @code{install-info} rule; some people apparently
7936 use this. By default, info pages are installed by @samp{make
7937 install}, so running @code{make install-info} is pointless. This can
7938 be prevented via the @code{no-installinfo} option. In this case,
7939 @file{.info} files are not installed by default, and user must
7940 request this explicitly using @samp{make install-info}.
7942 @vindex AM_UPDATE_INFO_DIR
7943 By default, @code{make install-info} will try to run the
7944 @command{install-info} program (if available) to update (or create)
7945 the @file{@code{$@{infodir@}}/dir} index. If this is undesired, it
7946 can be prevented by exporting the @code{AM_UPDATE_INFO_DIR} variable
7949 The following variables are used by the Texinfo build rules.
7953 The name of the program invoked to build @file{.info} files. This
7954 variable is defined by Automake. If the @command{makeinfo} program is
7955 found on the system then it will be used by default; otherwise
7956 @command{missing} will be used instead.
7959 The command invoked to build @file{.html} files. Automake
7960 defines this to @samp{$(MAKEINFO) --html}.
7963 User flags passed to each invocation of @samp{$(MAKEINFO)} and
7964 @samp{$(MAKEINFOHTML)}. This user variable (@pxref{User Variables}) is
7965 not expected to be defined in any @file{Makefile}; it can be used by
7966 users to pass extra flags to suit their needs.
7968 @item AM_MAKEINFOFLAGS
7969 @itemx AM_MAKEINFOHTMLFLAGS
7970 Maintainer flags passed to each @command{makeinfo} invocation. Unlike
7971 @code{MAKEINFOFLAGS}, these variables are meant to be defined by
7972 maintainers in @file{Makefile.am}. @samp{$(AM_MAKEINFOFLAGS)} is
7973 passed to @code{makeinfo} when building @file{.info} files; and
7974 @samp{$(AM_MAKEINFOHTMLFLAGS)} is used when building @file{.html}
7977 @c Keep in sync with txinfo21.test.
7978 For instance, the following setting can be used to obtain one single
7979 @file{.html} file per manual, without node separators.
7981 AM_MAKEINFOHTMLFLAGS = --no-headers --no-split
7984 @code{AM_MAKEINFOHTMLFLAGS} defaults to @samp{$(AM_MAKEINFOFLAGS)}.
7985 This means that defining @code{AM_MAKEINFOFLAGS} without defining
7986 @code{AM_MAKEINFOHTMLFLAGS} will impact builds of both @file{.info}
7987 and @file{.html} files.
7990 The name of the command that converts a @file{.texi} file into a
7991 @file{.dvi} file. This defaults to @samp{texi2dvi}, a script that ships
7992 with the Texinfo package.
7995 The name of the command that translates a @file{.texi} file into a
7996 @file{.pdf} file. This defaults to @samp{$(TEXI2DVI) --pdf --batch}.
7999 The name of the command that builds a @file{.ps} file out of a
8000 @file{.dvi} file. This defaults to @samp{dvips}.
8004 If your package has Texinfo files in many directories, you can use the
8005 variable @code{TEXINFO_TEX} to tell Automake where to find the canonical
8006 @file{texinfo.tex} for your package. The value of this variable should
8007 be the relative path from the current @file{Makefile.am} to
8011 TEXINFO_TEX = ../doc/texinfo.tex
8019 @cindex @code{_MANS} primary, defined
8020 @cindex @code{MANS} primary, defined
8021 @cindex Primary variable, @code{MANS}
8025 A package can also include man pages (but see the GNU standards on this
8026 matter, @ref{Man Pages, , , standards, The GNU Coding Standards}.) Man
8027 pages are declared using the @code{MANS} primary. Generally the
8028 @code{man_MANS} variable is used. Man pages are automatically installed in
8029 the correct subdirectory of @code{mandir}, based on the file extension.
8031 File extensions such as @file{.1c} are handled by looking for the valid
8032 part of the extension and using that to determine the correct
8033 subdirectory of @code{mandir}. Valid section names are the digits
8034 @samp{0} through @samp{9}, and the letters @samp{l} and @samp{n}.
8036 Sometimes developers prefer to name a man page something like
8037 @file{foo.man} in the source, and then rename it to have the correct
8038 suffix, for example @file{foo.1}, when installing the file. Automake
8039 also supports this mode. For a valid section named @var{section},
8040 there is a corresponding directory named @samp{man@var{section}dir},
8041 and a corresponding @code{_MANS} variable. Files listed in such a
8042 variable are installed in the indicated section. If the file already
8043 has a valid suffix, then it is installed as-is; otherwise the file
8044 suffix is changed to match the section.
8046 For instance, consider this example:
8048 man1_MANS = rename.man thesame.1 alsothesame.1c
8052 In this case, @file{rename.man} will be renamed to @file{rename.1} when
8053 installed, but the other files will keep their names.
8055 @cindex Target, @code{install-man}
8056 @cindex Option, @option{no-installman}
8057 @cindex @code{install-man} target
8058 @cindex @option{no-installman} option
8059 @opindex no-installman
8060 @trindex install-man
8062 By default, man pages are installed by @samp{make install}. However,
8063 since the GNU project does not require man pages, many maintainers do
8064 not expend effort to keep the man pages up to date. In these cases, the
8065 @option{no-installman} option will prevent the man pages from being
8066 installed by default. The user can still explicitly install them via
8067 @samp{make install-man}.
8069 For fast installation, with many files it is preferable to use
8070 @samp{man@var{section}_MANS} over @samp{man_MANS} as well as files that
8071 do not need to be renamed.
8073 Man pages are not currently considered to be source, because it is not
8074 uncommon for man pages to be automatically generated. Therefore they
8075 are not automatically included in the distribution. However, this can
8076 be changed by use of the @code{dist_} prefix. For instance here is
8077 how to distribute and install the two man pages of GNU @command{cpio}
8078 (which includes both Texinfo documentation and man pages):
8081 dist_man_MANS = cpio.1 mt.1
8084 The @code{nobase_} prefix is meaningless for man pages and is
8088 @cindex @code{notrans_} prefix
8089 @cindex Man page renaming, avoiding
8090 @cindex Avoiding man page renaming
8092 Executables and manpages may be renamed upon installation
8093 (@pxref{Renaming}). For manpages this can be avoided by use of the
8094 @code{notrans_} prefix. For instance, suppose an executable @samp{foo}
8095 allowing to access a library function @samp{foo} from the command line.
8096 The way to avoid renaming of the @file{foo.3} manpage is:
8100 notrans_man_MANS = foo.3
8103 @cindex @code{notrans_} and @code{dist_} or @code{nodist_}
8104 @cindex @code{dist_} and @code{notrans_}
8105 @cindex @code{nodist_} and @code{notrans_}
8107 @samp{notrans_} must be specified first when used in conjunction with
8108 either @samp{dist_} or @samp{nodist_} (@pxref{Fine-grained Distribution
8109 Control}). For instance:
8112 notrans_dist_man3_MANS = bar.3
8116 @chapter What Gets Installed
8118 @cindex Installation support
8119 @cindex @samp{make install} support
8121 Naturally, Automake handles the details of actually installing your
8122 program once it has been built. All files named by the various
8123 primaries are automatically installed in the appropriate places when the
8124 user runs @samp{make install}.
8127 * Basics of Installation:: What gets installed where
8128 * The Two Parts of Install:: Installing data and programs separately
8129 * Extending Installation:: Adding your own rules for installation
8130 * Staged Installs:: Installation in a temporary location
8131 * Install Rules for the User:: Useful additional rules
8134 @node Basics of Installation
8135 @section Basics of Installation
8137 A file named in a primary is installed by copying the built file into
8138 the appropriate directory. The base name of the file is used when
8142 bin_PROGRAMS = hello subdir/goodbye
8145 In this example, both @samp{hello} and @samp{goodbye} will be installed
8146 in @samp{$(bindir)}.
8148 Sometimes it is useful to avoid the basename step at install time. For
8149 instance, you might have a number of header files in subdirectories of
8150 the source tree that are laid out precisely how you want to install
8151 them. In this situation you can use the @code{nobase_} prefix to
8152 suppress the base name step. For example:
8155 nobase_include_HEADERS = stdio.h sys/types.h
8159 will install @file{stdio.h} in @samp{$(includedir)} and @file{types.h}
8160 in @samp{$(includedir)/sys}.
8162 For most file types, Automake will install multiple files at once, while
8163 avoiding command line length issues (@pxref{Length Limitations}). Since
8164 some @command{install} programs will not install the same file twice in
8165 one invocation, you may need to ensure that file lists are unique within
8166 one variable such as @samp{nobase_include_HEADERS} above.
8168 You should not rely on the order in which files listed in one variable
8169 are installed. Likewise, to cater for parallel make, you should not
8170 rely on any particular file installation order even among different
8171 file types (library dependencies are an exception here).
8174 @node The Two Parts of Install
8175 @section The Two Parts of Install
8177 Automake generates separate @code{install-data} and @code{install-exec}
8178 rules, in case the installer is installing on multiple machines that
8179 share directory structure---these targets allow the machine-independent
8180 parts to be installed only once. @code{install-exec} installs
8181 platform-dependent files, and @code{install-data} installs
8182 platform-independent files. The @code{install} target depends on both
8183 of these targets. While Automake tries to automatically segregate
8184 objects into the correct category, the @file{Makefile.am} author is, in
8185 the end, responsible for making sure this is done correctly.
8186 @trindex install-data
8187 @trindex install-exec
8189 @cindex Install, two parts of
8191 Variables using the standard directory prefixes @samp{data},
8192 @samp{info}, @samp{man}, @samp{include}, @samp{oldinclude},
8193 @samp{pkgdata}, or @samp{pkginclude} are installed by
8194 @code{install-data}.
8196 Variables using the standard directory prefixes @samp{bin},
8197 @samp{sbin}, @samp{libexec}, @samp{sysconf}, @samp{localstate},
8198 @samp{lib}, or @samp{pkglib} are installed by @code{install-exec}.
8200 For instance, @code{data_DATA} files are installed by @code{install-data},
8201 while @code{bin_PROGRAMS} files are installed by @code{install-exec}.
8203 Any variable using a user-defined directory prefix with
8204 @samp{exec} in the name (e.g.,
8205 @c Keep in sync with primary-prefix-couples-documented-valid.test.
8206 @code{myexecbin_PROGRAMS}) is installed by @code{install-exec}. All
8207 other user-defined prefixes are installed by @code{install-data}.
8209 @node Extending Installation
8210 @section Extending Installation
8212 It is possible to extend this mechanism by defining an
8213 @code{install-exec-local} or @code{install-data-local} rule. If these
8214 rules exist, they will be run at @samp{make install} time. These
8215 rules can do almost anything; care is required.
8216 @trindex install-exec-local
8217 @trindex install-data-local
8219 Automake also supports two install hooks, @code{install-exec-hook} and
8220 @code{install-data-hook}. These hooks are run after all other install
8221 rules of the appropriate type, exec or data, have completed. So, for
8222 instance, it is possible to perform post-installation modifications
8223 using an install hook. @xref{Extending}, for some examples.
8224 @cindex Install hook
8226 @node Staged Installs
8227 @section Staged Installs
8230 Automake generates support for the @code{DESTDIR} variable in all
8231 install rules. @code{DESTDIR} is used during the @samp{make install}
8232 step to relocate install objects into a staging area. Each object and
8233 path is prefixed with the value of @code{DESTDIR} before being copied
8234 into the install area. Here is an example of typical DESTDIR usage:
8237 mkdir /tmp/staging &&
8238 make DESTDIR=/tmp/staging install
8241 The @command{mkdir} command avoids a security problem if the attacker
8242 creates a symbolic link from @file{/tmp/staging} to a victim area;
8243 then @command{make} places install objects in a directory tree built under
8244 @file{/tmp/staging}. If @file{/gnu/bin/foo} and
8245 @file{/gnu/share/aclocal/foo.m4} are to be installed, the above command
8246 would install @file{/tmp/staging/gnu/bin/foo} and
8247 @file{/tmp/staging/gnu/share/aclocal/foo.m4}.
8249 This feature is commonly used to build install images and packages
8252 Support for @code{DESTDIR} is implemented by coding it directly into
8253 the install rules. If your @file{Makefile.am} uses a local install
8254 rule (e.g., @code{install-exec-local}) or an install hook, then you
8255 must write that code to respect @code{DESTDIR}.
8257 @xref{Makefile Conventions, , , standards, The GNU Coding Standards},
8258 for another usage example.
8260 @node Install Rules for the User
8261 @section Install Rules for the User
8263 Automake also generates rules for targets @code{uninstall},
8264 @code{installdirs}, and @code{install-strip}.
8266 @trindex installdirs
8267 @trindex install-strip
8269 Automake supports @code{uninstall-local} and @code{uninstall-hook}.
8270 There is no notion of separate uninstalls for ``exec'' and ``data'', as
8271 these features would not provide additional functionality.
8273 Note that @code{uninstall} is not meant as a replacement for a real
8278 @chapter What Gets Cleaned
8280 @cindex @samp{make clean} support
8282 The GNU Makefile Standards specify a number of different clean rules.
8283 @xref{Standard Targets, , Standard Targets for Users, standards,
8284 The GNU Coding Standards}.
8286 Generally the files that can be cleaned are determined automatically by
8287 Automake. Of course, Automake also recognizes some variables that can
8288 be defined to specify additional files to clean. These variables are
8289 @code{MOSTLYCLEANFILES}, @code{CLEANFILES}, @code{DISTCLEANFILES}, and
8290 @code{MAINTAINERCLEANFILES}.
8291 @vindex MOSTLYCLEANFILES
8293 @vindex DISTCLEANFILES
8294 @vindex MAINTAINERCLEANFILES
8296 @trindex mostlyclean-local
8297 @trindex clean-local
8298 @trindex distclean-local
8299 @trindex maintainer-clean-local
8300 When cleaning involves more than deleting some hard-coded list of
8301 files, it is also possible to supplement the cleaning rules with your
8302 own commands. Simply define a rule for any of the
8303 @code{mostlyclean-local}, @code{clean-local}, @code{distclean-local},
8304 or @code{maintainer-clean-local} targets (@pxref{Extending}). A common
8305 case is deleting a directory, for instance, a directory created by the
8313 Since @command{make} allows only one set of rules for a given target,
8314 a more extensible way of writing this is to use a separate target
8315 listed as a dependency:
8318 clean-local: clean-local-check
8319 .PHONY: clean-local-check
8324 As the GNU Standards aren't always explicit as to which files should
8325 be removed by which rule, we've adopted a heuristic that we believe
8326 was first formulated by Fran@,{c}ois Pinard:
8330 If @command{make} built it, and it is commonly something that one would
8331 want to rebuild (for instance, a @file{.o} file), then
8332 @code{mostlyclean} should delete it.
8335 Otherwise, if @command{make} built it, then @code{clean} should delete it.
8338 If @command{configure} built it, then @code{distclean} should delete it.
8341 If the maintainer built it (for instance, a @file{.info} file), then
8342 @code{maintainer-clean} should delete it. However
8343 @code{maintainer-clean} should not delete anything that needs to exist
8344 in order to run @samp{./configure && make}.
8347 We recommend that you follow this same set of heuristics in your
8352 @chapter What Goes in a Distribution
8355 * Basics of Distribution:: Files distributed by default
8356 * Fine-grained Distribution Control:: @code{dist_} and @code{nodist_} prefixes
8357 * The dist Hook:: A target for last-minute distribution changes
8358 * Checking the Distribution:: @samp{make distcheck} explained
8359 * The Types of Distributions:: A variety of formats and compression methods
8362 @node Basics of Distribution
8363 @section Basics of Distribution
8365 @cindex @samp{make dist}
8370 The @code{dist} rule in the generated @file{Makefile.in} can be used
8371 to generate a gzipped @code{tar} file and other flavors of archive for
8372 distribution. The file is named based on the @code{PACKAGE} and
8373 @code{VERSION} variables defined by @code{AM_INIT_AUTOMAKE}
8374 (@pxref{Macros}); more precisely the gzipped @code{tar} file is named
8375 @samp{@var{package}-@var{version}.tar.gz}.
8377 You can use the @command{make} variable @code{GZIP_ENV} to control how gzip
8378 is run. The default setting is @option{--best}.
8380 @cindex @code{m4_include}, distribution
8381 @cindex @code{include}, distribution
8384 For the most part, the files to distribute are automatically found by
8385 Automake: all source files are automatically included in a distribution,
8386 as are all @file{Makefile.am} and @file{Makefile.in} files. Automake also
8387 has a built-in list of commonly used files that are automatically
8388 included if they are found in the current directory (either physically,
8389 or as the target of a @file{Makefile.am} rule); this list is printed by
8390 @samp{automake --help}. Note that some files in this list are actually
8391 distributed only if other certain conditions hold (for example,
8392 @c Keep in sync with autodist-config-headers.test.
8393 the @file{config.h.top} and @file{config.h.bot} files are automatically
8394 distributed only if, e.g., @samp{AC_CONFIG_HEADERS([config.h])} is used
8395 in @file{configure.ac}). Also, files that are read by @command{configure}
8396 (i.e.@: the source files corresponding to the files specified in various
8397 Autoconf macros such as @code{AC_CONFIG_FILES} and siblings) are
8398 automatically distributed. Files included in a @file{Makefile.am} (using
8399 @code{include}) or in @file{configure.ac} (using @code{m4_include}), and
8400 helper scripts installed with @samp{automake --add-missing} are also
8404 Still, sometimes there are files that must be distributed, but which
8405 are not covered in the automatic rules. These files should be listed in
8406 the @code{EXTRA_DIST} variable. You can mention files from
8407 subdirectories in @code{EXTRA_DIST}.
8409 You can also mention a directory in @code{EXTRA_DIST}; in this case the
8410 entire directory will be recursively copied into the distribution.
8411 Please note that this will also copy @emph{everything} in the directory,
8412 including, e.g., Subversion's @file{.svn} private directories or CVS/RCS
8413 version control files. We recommend against using this feature.
8416 @vindex DIST_SUBDIRS
8417 If you define @code{SUBDIRS}, Automake will recursively include the
8418 subdirectories in the distribution. If @code{SUBDIRS} is defined
8419 conditionally (@pxref{Conditionals}), Automake will normally include
8420 all directories that could possibly appear in @code{SUBDIRS} in the
8421 distribution. If you need to specify the set of directories
8422 conditionally, you can set the variable @code{DIST_SUBDIRS} to the
8423 exact list of subdirectories to include in the distribution
8424 (@pxref{Conditional Subdirectories}).
8427 @node Fine-grained Distribution Control
8428 @section Fine-grained Distribution Control
8432 Sometimes you need tighter control over what does @emph{not} go into the
8433 distribution; for instance, you might have source files that are
8434 generated and that you do not want to distribute. In this case
8435 Automake gives fine-grained control using the @code{dist} and
8436 @code{nodist} prefixes. Any primary or @code{_SOURCES} variable can be
8437 prefixed with @code{dist_} to add the listed files to the distribution.
8438 Similarly, @code{nodist_} can be used to omit the files from the
8441 As an example, here is how you would cause some data to be distributed
8442 while leaving some source code out of the distribution:
8445 dist_data_DATA = distribute-this
8447 nodist_foo_SOURCES = do-not-distribute.c
8451 @section The dist Hook
8455 Occasionally it is useful to be able to change the distribution before
8456 it is packaged up. If the @code{dist-hook} rule exists, it is run
8457 after the distribution directory is filled, but before the actual tar
8458 (or shar) file is created. One way to use this is for distributing
8459 files in subdirectories for which a new @file{Makefile.am} is overkill:
8463 mkdir $(distdir)/random
8464 cp -p $(srcdir)/random/a1 $(srcdir)/random/a2 $(distdir)/random
8467 Another way to use this is for removing unnecessary files that get
8468 recursively included by specifying a directory in EXTRA_DIST:
8474 rm -rf `find $(distdir)/doc -type d -name .svn`
8479 Two variables that come handy when writing @code{dist-hook} rules are
8480 @samp{$(distdir)} and @samp{$(top_distdir)}.
8482 @samp{$(distdir)} points to the directory where the @code{dist} rule
8483 will copy files from the current directory before creating the
8484 tarball. If you are at the top-level directory, then @samp{distdir =
8485 $(PACKAGE)-$(VERSION)}. When used from subdirectory named
8486 @file{foo/}, then @samp{distdir = ../$(PACKAGE)-$(VERSION)/foo}.
8487 @samp{$(distdir)} can be a relative or absolute path, do not assume
8490 @samp{$(top_distdir)} always points to the root directory of the
8491 distributed tree. At the top-level it's equal to @samp{$(distdir)}.
8492 In the @file{foo/} subdirectory
8493 @samp{top_distdir = ../$(PACKAGE)-$(VERSION)}.
8494 @samp{$(top_distdir)} too can be a relative or absolute path.
8496 Note that when packages are nested using @code{AC_CONFIG_SUBDIRS}
8497 (@pxref{Subpackages}), then @samp{$(distdir)} and
8498 @samp{$(top_distdir)} are relative to the package where @samp{make
8499 dist} was run, not to any sub-packages involved.
8501 @node Checking the Distribution
8502 @section Checking the Distribution
8504 @cindex @samp{make distcheck}
8505 @cindex @samp{make distcleancheck}
8506 @vindex distcleancheck_listfiles
8507 @cindex @samp{make distuninstallcheck}
8508 @vindex distuninstallcheck_listfiles
8511 Automake also generates a @code{distcheck} rule that can be of help to
8512 ensure that a given distribution will actually work. @code{distcheck}
8513 makes a distribution, then tries to do a @code{VPATH} build
8514 (@pxref{VPATH Builds}), run the test suite, and finally make another
8515 tarball to ensure the distribution is self-contained.
8517 @vindex AM_DISTCHECK_CONFIGURE_FLAGS
8518 @vindex DISTCHECK_CONFIGURE_FLAGS
8519 Building the package involves running @samp{./configure}. If you need
8520 to supply additional flags to @command{configure}, define them in the
8521 @code{AM_DISTCHECK_CONFIGURE_FLAGS} variable in your top-level
8522 @file{Makefile.am}. The user can still extend or override the flags
8523 provided there by defining the @code{DISTCHECK_CONFIGURE_FLAGS} variable,
8524 on the command line when invoking @command{make}.
8526 Still, developers are encouraged to strive to make their code buildable
8527 without requiring any special configure option; thus, in general, you
8528 shouldn't define @code{AM_DISTCHECK_CONFIGURE_FLAGS}. However, there
8529 might be few scenarios in which the use of this variable is justified.
8530 GNU @command{m4} offers an example. GNU @command{m4} configures by
8531 default with its experimental and seldom used "changeword" feature
8532 disabled; so in its case it is useful to have @command{make distcheck}
8533 run configure with the @option{--with-changeword} option, to ensure that
8534 the code for changeword support still compiles correctly.
8535 GNU @command{m4} also employs the @code{AM_DISTCHECK_CONFIGURE_FLAGS}
8536 variable to stress-test the use of @option{--program-prefix=g}, since at
8537 one point the @command{m4} build system had a bug where @command{make
8538 installcheck} was wrongly assuming it could blindly test "@command{m4}",
8539 rather than the just-installed "@command{gm4}".
8541 @trindex distcheck-hook
8542 If the @code{distcheck-hook} rule is defined in your top-level
8543 @file{Makefile.am}, then it will be invoked by @code{distcheck} after
8544 the new distribution has been unpacked, but before the unpacked copy
8545 is configured and built. Your @code{distcheck-hook} can do almost
8546 anything, though as always caution is advised. Generally this hook is
8547 used to check for potential distribution errors not caught by the
8548 standard mechanism. Note that @code{distcheck-hook} as well as
8549 @code{AM_DISTCHECK_CONFIGURE_FLAGS} and @code{DISTCHECK_CONFIGURE_FLAGS}
8550 are not honored in a subpackage @file{Makefile.am}, but the flags from
8551 @code{AM_DISTCHECK_CONFIGURE_FLAGS} and @code{DISTCHECK_CONFIGURE_FLAGS}
8552 are passed down to the @command{configure} script of the subpackage.
8554 @trindex distcleancheck
8555 @vindex DISTCLEANFILES
8556 @vindex distcleancheck_listfiles
8557 Speaking of potential distribution errors, @code{distcheck} also
8558 ensures that the @code{distclean} rule actually removes all built
8559 files. This is done by running @samp{make distcleancheck} at the end of
8560 the @code{VPATH} build. By default, @code{distcleancheck} will run
8561 @code{distclean} and then make sure the build tree has been emptied by
8562 running @samp{$(distcleancheck_listfiles)}. Usually this check will
8563 find generated files that you forgot to add to the @code{DISTCLEANFILES}
8564 variable (@pxref{Clean}).
8566 The @code{distcleancheck} behavior should be OK for most packages,
8567 otherwise you have the possibility to override the definition of
8568 either the @code{distcleancheck} rule, or the
8569 @samp{$(distcleancheck_listfiles)} variable. For instance, to disable
8570 @code{distcleancheck} completely, add the following rule to your
8571 top-level @file{Makefile.am}:
8578 If you want @code{distcleancheck} to ignore built files that have not
8579 been cleaned because they are also part of the distribution, add the
8580 following definition instead:
8582 @c Keep in sync with distcleancheck.test.
8584 distcleancheck_listfiles = \
8585 find . -type f -exec sh -c 'test -f $(srcdir)/$$1 || echo $$1' \
8589 The above definition is not the default because it's usually an error if
8590 your Makefiles cause some distributed files to be rebuilt when the user
8591 build the package. (Think about the user missing the tool required to
8592 build the file; or if the required tool is built by your package,
8593 consider the cross-compilation case where it can't be run.) There is
8594 an entry in the FAQ about this (@pxref{distcleancheck}), make sure you
8595 read it before playing with @code{distcleancheck_listfiles}.
8597 @code{distcheck} also checks that the @code{uninstall} rule works
8598 properly, both for ordinary and @code{DESTDIR} builds. It does this
8599 by invoking @samp{make uninstall}, and then it checks the install tree
8600 to see if any files are left over. This check will make sure that you
8601 correctly coded your @code{uninstall}-related rules.
8603 By default, the checking is done by the @code{distuninstallcheck} rule,
8604 and the list of files in the install tree is generated by
8605 @samp{$(distuninstallcheck_listfiles)} (this is a variable whose value is
8606 a shell command to run that prints the list of files to stdout).
8608 Either of these can be overridden to modify the behavior of
8609 @code{distcheck}. For instance, to disable this check completely, you
8617 @node The Types of Distributions
8618 @section The Types of Distributions
8620 Automake generates rules to provide archives of the project for
8621 distributions in various formats. Their targets are:
8625 @item @code{dist-bzip2}
8626 Generate a bzip2 tar archive of the distribution. bzip2 archives are
8627 frequently smaller than gzipped archives.
8628 By default, this rule makes @samp{bzip2} use a compression option of @option{-9}.
8629 To make it use a different one, set the @env{BZIP2} environment variable.
8630 For example, @samp{make dist-bzip2 BZIP2=-7}.
8633 @item @code{dist-gzip}
8634 Generate a gzip tar archive of the distribution.
8637 @item @code{dist-lzip}
8638 Generate an @samp{lzip} tar archive of the distribution. @command{lzip}
8639 archives are frequently smaller than @command{bzip2}-compressed archives.
8642 @item @code{dist-lzma}
8643 Generate an @samp{lzma} tar archive of the distribution.
8644 The @samp{lzma} format is obsolete, you should use the @samp{xz} format
8645 instead. @emph{Support for @samp{lzma}-compressed archives will be
8646 removed in the next major Automake release.}
8649 @item @code{dist-shar}
8650 Generate a shar archive of the distribution.
8654 @item @code{dist-xz}
8655 Generate an @samp{xz} tar archive of the distribution. @command{xz}
8656 archives are frequently smaller than @command{bzip2}-compressed archives.
8657 The @samp{xz} format displaces the obsolete @samp{lzma} format.
8658 By default, this rule makes @samp{xz} use a compression option of
8659 @option{-e}. To make it use a different one, set the @env{XZ_OPT}
8660 environment variable. For example, run this command to use the
8661 default compression ratio, but with a progress indicator:
8662 @samp{make dist-xz XZ_OPT=-7e}.
8665 @item @code{dist-zip}
8666 Generate a zip archive of the distribution.
8669 @item @code{dist-tarZ}
8670 Generate a compressed tar archive of
8675 The rule @code{dist} (and its historical synonym @code{dist-all}) will
8676 create archives in all the enabled formats, @ref{Options}. By
8677 default, only the @code{dist-gzip} target is hooked to @code{dist}.
8681 @chapter Support for test suites
8684 @cindex @code{make check}
8687 Automake can generate code to handle two kinds of test suites. One is
8688 based on integration with the @command{dejagnu} framework. The other
8689 (and most used) form is based on the use of generic test scripts, and
8690 its activation is triggered by the definition of the special @code{TESTS}
8691 variable. This second form allows for various degrees of sophistication
8692 and customization; in particular, it allows for concurrent execution
8693 of test scripts, use of established test protocols such as TAP, and
8694 definition of custom test drivers and test runners.
8697 In either case, the testsuite is invoked via @samp{make check}.
8700 * Generalities about Testing:: Concepts and terminology about testing
8701 * Simple Tests:: Listing test scripts in @code{TESTS}
8702 * Custom Test Drivers:: Writing and using custom test drivers
8703 * Using the TAP test protocol:: Integrating test scripts that use the TAP protocol
8704 * DejaGnu Tests:: Interfacing with the @command{dejagnu} testing framework
8705 * Install Tests:: Running tests on installed packages
8708 @node Generalities about Testing
8709 @section Generalities about Testing
8711 The purpose of testing is to determine whether a program or system behaves
8712 as expected (e.g., known inputs produce the expected outputs, error
8713 conditions are correctly handled or reported, and older bugs do not
8717 The minimal unit of testing is usually called @emph{test case}, or simply
8718 @emph{test}. How a test case is defined or delimited, and even what
8719 exactly @emph{constitutes} a test case, depends heavily on the testing
8720 paradigm and/or framework in use, so we won't attempt any more precise
8721 definition. The set of the test cases for a given program or system
8722 constitutes its @emph{testsuite}.
8724 @cindex test harness
8725 @cindex testsuite harness
8726 A @emph{test harness} (also @emph{testsuite harness}) is a program or
8727 software component that executes all (or part of) the defined test cases,
8728 analyzes their outcomes, and report or register these outcomes
8729 appropriately. Again, the details of how this is accomplished (and how
8730 the developer and user can influence it or interface with it) varies
8731 wildly, and we'll attempt no precise definition.
8734 @cindex test failure
8735 A test is said to @emph{pass} when it can determine that the condition or
8736 behaviour it means to verify holds, and is said to @emph{fail} when it can
8737 determine that such condition of behaviour does @emph{not} hold.
8740 Sometimes, tests can rely on non-portable tools or prerequisites, or
8741 simply make no sense on a given system (for example, a test checking a
8742 Windows-specific feature makes no sense on a GNU/Linux system). In this
8743 case, accordingly to the definition above, the tests can neither be
8744 considered passed nor failed; instead, they are @emph{skipped} -- i.e.,
8745 they are not run, or their result is anyway ignored for what concerns
8746 the count of failures an successes. Skips are usually explicitly
8747 reported though, so that the user will be aware that not all of the
8748 testsuite has really run.
8751 @cindex expected failure
8752 @cindex expected test failure
8754 @cindex unexpected pass
8755 @cindex unexpected test pass
8756 It's not uncommon, especially during early development stages, that some
8757 tests fail for known reasons, and that the developer doesn't want to
8758 tackle these failures immediately (this is especially true when the
8759 failing tests deal with corner cases). In this situation, the better
8760 policy is to declare that each of those failures is an @emph{expected
8761 failure} (or @emph{xfail}). In case a test that is expected to fail ends
8762 up passing instead, many testing environments will flag the result as a
8763 special kind of failure called @emph{unexpected pass} (or @emph{xpass}).
8766 @cindex Distinction between errors and failures in testsuites
8767 Many testing environments and frameworks distinguish between test failures
8768 and hard errors. As we've seen, a test failure happens when some invariant
8769 or expected behaviour of the software under test is not met. An @emph{hard
8770 error} happens when e.g., the set-up of a test case scenario fails, or when
8771 some other unexpected or highly undesirable condition is encountered (for
8772 example, the program under test experiences a segmentation fault).
8774 @emph{TODO}: Links to other test harnesses (esp. those sharing our
8778 @section Simple Tests
8781 * Scripts-based Testsuites:: Automake-specific concepts and terminology
8782 * Serial Test Harness:: Older (and obsolescent) serial test harness
8783 * Parallel Test Harness:: Generic concurrent test harness
8786 @node Scripts-based Testsuites
8787 @subsection Scripts-based Testsuites
8789 If the special variable @code{TESTS} is defined, its value is taken to be
8790 a list of programs or scripts to run in order to do the testing. Under
8791 the appropriate circumstances, it's possible for @code{TESTS} to list
8792 also data files to be passed to one or more test scripts defined by
8793 different means (the so-called ``log compilers'', @pxref{Parallel Test
8796 Test scripts can be executed serially or concurrently. Automake
8797 supports both these kinds of test execution, with the serial test harness
8798 being the default (for backward-compatibility reasons only, as its use
8799 is nowadays discouraged). The concurrent test harness relies on the
8800 concurrence capabilities (if any) offered by the underlying @command{make}
8801 implementation, and can thus only be as good as those are.
8803 By default, only the exit statuses of the test scripts are considered when
8804 determining the testsuite outcome. But Automake allows also the use of
8805 more complex test protocols, either standard (@pxref{Using the TAP test
8806 protocol}) or custom (@pxref{Custom Test Drivers}). Note that you can
8807 enable such protocols only when the parallel harness is used: they won't
8808 work with the serial test harness. In the rest of this section we are
8809 going to concentrate mostly on protocol-less tests, since we'll have later
8810 a whole section devoted to the use of test protocols (again, @pxref{Custom
8813 @cindex Exit status 77, special interpretation
8814 @cindex Exit status 99, special interpretation
8815 When no test protocol is in use, an exit status of 0 from a test script will
8816 denote a success, an exit status of 77 a skipped test, an exit status of 99
8817 an hard error, and any other exit status will denote a failure.
8819 @cindex Tests, expected failure
8820 @cindex Expected test failure
8822 @vindex DISABLE_HARD_ERRORS
8823 @cindex Disabling hard errors
8824 You may define the variable @code{XFAIL_TESTS} to a list of tests
8825 (usually a subset of @code{TESTS}) that are expected to fail; this will
8826 effectively reverse the result of those tests (with the provision that
8827 skips and hard errors remain untouched). You may also instruct the
8828 testsuite harness to treat hard errors like simple failures, by defining
8829 the @code{DISABLE_HARD_ERRORS} make variable to a nonempty value.
8831 Note however that, for tests based on more complex test protocols,
8832 the exact effects of @code{XFAIL_TESTS} and @code{DISABLE_HARD_ERRORS}
8833 might change, or they might even have no effect at all (for example,
8834 @c Keep this in sync with tap-no-disable-hard-errors.test.
8835 in tests using TAP, there is not way to disable hard errors, and the
8836 @code{DISABLE_HARD_ERRORS} variable has no effect on them).
8838 @anchor{Testsuite progress on console}
8839 @cindex Testsuite progress on console
8840 The result of each test case run by the scripts in @code{TESTS} will be
8841 printed on standard output, along with the test name. For test protocols
8842 that allow more test cases per test script (such as TAP), a number,
8843 identifier and/or brief description specific for the single test case is
8844 expected to be printed in addition to the name of the test script. The
8845 possible results (whose meanings should be clear from the previous
8846 @ref{Generalities about Testing}) are @code{PASS}, @code{FAIL},
8847 @code{SKIP}, @code{XFAIL}, @code{XPASS} and @code{ERROR}. Here is an
8848 example of output from an hypothetical testsuite that uses both plain
8850 @c Keep in sync with tap-doc.test.
8853 PASS: zardoz.tap 1 - Daemon started
8854 PASS: zardoz.tap 2 - Daemon responding
8855 SKIP: zardoz.tap 3 - Daemon uses /proc # SKIP /proc is not mounted
8856 PASS: zardoz.tap 4 - Daemon stopped
8859 XFAIL: mu.tap 2 # TODO frobnication not yet implemented
8863 A testsuite summary (expected to report at least the number of run,
8864 skipped and failed tests) will be printed at the end of the testsuite
8867 @anchor{Simple tests and color-tests}
8868 @vindex AM_COLOR_TESTS
8869 @cindex Colorized testsuite output
8870 If the Automake option @code{color-tests} is used (@pxref{Options})
8871 and standard output is connected to a capable terminal, then the test
8872 results and the summary are colored appropriately. The user can disable
8873 colored output by setting the @command{make} variable
8874 @samp{AM_COLOR_TESTS=no}, or force colored output even without a connecting
8875 terminal with @samp{AM_COLOR_TESTS=always}. It's also worth noting that
8876 some @command{make} implementations, when used in parallel mode, have
8877 slightly different semantics (@pxref{Parallel make,,, autoconf,
8878 The Autoconf Manual}), which can break the automatic detection of a
8879 connection to a capable terminal. If this is the case, you'll have to
8880 resort to the use of @samp{AM_COLOR_TESTS=always} in order to have the
8881 testsuite output colorized.
8883 Test programs that need data files should look for them in @code{srcdir}
8884 (which is both a make variable and an environment variable made available
8885 to the tests), so that they work when building in a separate directory
8886 (@pxref{Build Directories, , Build Directories , autoconf,
8887 The Autoconf Manual}), and in particular for the @code{distcheck} rule
8888 (@pxref{Checking the Distribution}).
8891 @vindex TESTS_ENVIRONMENT
8892 @vindex AM_TESTS_ENVIRONMENT
8893 The @code{AM_TESTS_ENVIRONMENT} and @code{TESTS_ENVIRONMENT} variables can
8894 be used to run initialization code and set environment variables for the
8895 test scripts. The former variable is developer-reserved, and can be
8896 defined in the @file{Makefile.am}, while the latter is reserved for the
8897 user, which can employ it to extend or override the settings in the
8898 former; for this to work portably, however, the contents of a non-empty
8899 @code{AM_TESTS_ENVIRONMENT} @emph{must} be terminated by a semicolon.
8901 @vindex AM_TESTS_FD_REDIRECT
8902 The @code{AM_TESTS_FD_REDIRECT} variable can be used to define file
8903 descriptor redirections for the test scripts. One might think that
8904 @code{AM_TESTS_ENVIRONMENT} could be used for this purpose, but experience
8905 has shown that doing so portably is practically impossible. The main
8906 hurdle is constituted by Korn shells, which usually set the close-on-exec
8907 flag on file descriptors opened with the @command{exec} builtin, thus
8908 rendering an idiom like @code{AM_TESTS_ENVIRONMENT = exec 9>&2;}
8909 ineffectual. This issue also affects some Bourne shells, such as the
8910 HP-UX's @command{/bin/sh},
8911 @c FIXME: should we offer a link to the relevant discussions on the
8912 @c bug-autoconf list?
8914 @c Keep in sync with tests-environment-backcompat.test.
8916 AM_TESTS_ENVIRONMENT = \
8917 ## Some environment initializations are kept in a separate shell
8918 ## file `tests-env.sh', which can make it easier to also run tests
8919 ## from the command line.
8920 . $(srcdir)/tests-env.sh; \
8921 ## On Solaris, prefer more POSIX-compliant versions of the standard
8922 ## tools by default.
8923 if test -d /usr/xpg4/bin; then \
8924 PATH=/usr/xpg4/bin:$$PATH; export PATH; \
8926 @c $$ restore font-lock
8927 ## With this, the test scripts will be able to print diagnostic
8928 ## messages to the original standard error stream, even if the test
8929 ## driver redirects the stderr of the test scripts to a log file
8930 ## before executing them.
8931 AM_TESTS_FD_REDIRECT = 9>&2
8935 Note however that @code{AM_TESTS_ENVIRONMENT} is, for historical and
8936 implementation reasons, @emph{not} supported by the serial harness
8937 (@pxref{Serial Test Harness}).
8939 Automake ensures that each file listed in @code{TESTS} is built before
8940 it is run; you can list both source and derived programs (or scripts)
8941 in @code{TESTS}; the generated rule will look both in @code{srcdir} and
8942 @file{.}. For instance, you might want to run a C program as a test.
8943 To do this you would list its name in @code{TESTS} and also in
8944 @code{check_PROGRAMS}, and then specify it as you would any other
8947 Programs listed in @code{check_PROGRAMS} (and @code{check_LIBRARIES},
8948 @code{check_LTLIBRARIES}...) are only built during @code{make check},
8949 not during @code{make all}. You should list there any program needed
8950 by your tests that does not need to be built by @code{make all}. Note
8951 that @code{check_PROGRAMS} are @emph{not} automatically added to
8952 @code{TESTS} because @code{check_PROGRAMS} usually lists programs used
8953 by the tests, not the tests themselves. Of course you can set
8954 @code{TESTS = $(check_PROGRAMS)} if all your programs are test cases.
8956 @node Serial Test Harness
8957 @subsection Serial Test Harness
8959 @emph{NOTE:} This harness, while still being the default one, is
8960 obsolescent, and kept mostly for backward-compatibility reasons.
8961 The user is advised to use the parallel test harness instead
8962 (@pxref{Parallel Test Harness}).
8964 The serial harness operates by simply running the tests serially, one at
8965 the time, without any I/O redirection. It's up to the user to implement
8966 logging of tests' output, if that's requited or desired.
8967 @c TODO: give an example of how this can be done.
8969 For historical and implementation reasons, the @code{AM_TESTS_ENVIRONMENT}
8970 variable is @emph{not} supported by this harness (it will be silently
8971 ignored if defined); only @code{TESTS_ENVIRONMENT} is, and it is to be
8972 considered a developer-reserved variable. This is done so that, when
8973 using the serial harness, @code{TESTS_ENVIRONMENT} can be defined to an
8974 invocation of an interpreter through which the tests are to be run.
8975 For instance, the following setup may be used to run tests with Perl:
8978 TESTS_ENVIRONMENT = $(PERL) -Mstrict -w
8979 TESTS = foo.pl bar.pl baz.pl
8983 It's important to note that the use of @code{TESTS_ENVIRONMENT} endorsed
8984 here would be @emph{invalid} with the parallel harness. That harness
8985 provides a more elegant way to achieve the same effect, with the further
8986 benefit of freeing the @code{TESTS_ENVIRONMENT} variable for the user
8987 (@pxref{Parallel Test Harness}).
8989 Another, less serious limit of the serial harness is that it doesn't
8990 really distinguish between simple failures and hard errors; this is
8991 due to historical reasons only, and might be fixed in future Automake
8994 @node Parallel Test Harness
8995 @subsection Parallel Test Harness
8996 @cindex @option{parallel-tests}, Using
8998 The parallel (or concurrent) test harness is enabled by the Automake option
8999 @option{parallel-tests}. It features automatic collection of the test
9000 scripts output in @file{.log} files, concurrent execution of tests with
9001 @code{make -j}, specification of inter-test dependencies, lazy reruns of
9002 tests that have not completed in a prior run, and hard errors for exceptional
9005 This harness is still somewhat experimental and may undergo changes in
9006 order to satisfy additional portability requirements.
9008 @anchor{Basics of test metadata}
9009 @vindex TEST_SUITE_LOG
9011 @cindex @file{.log} files
9012 @cindex @file{.trs} files
9013 @cindex test metadata
9014 The parallel test harness operates by defining a set of @command{make}
9015 rules that run the test scripts listed in @code{TESTS}, and, for each
9016 such script, save its output in a corresponding @file{.log} file and
9017 its results (and other ``metadata'', @pxref{API for Custom Test Drivers})
9018 in a corresponding @file{.trs} (as in @b{T}est @b{R}e@b{S}ults) file.
9019 @c We choose the `.trs' extension also because, at the time of writing,
9020 @c it isn't already used for other significant purposes; see e.g.:
9021 @c - http://filext.com/file-extension/trs
9022 @c - http://www.file-extensions.org/search/?searchstring=trs
9023 The @file{.log} file will contain all the output emitted by the test on
9024 its standard output and its standard error. The @file{.trs} file will
9025 contain, among the other things, the results of the test cases run by
9028 The parallel test harness will also create a summary log file,
9029 @code{TEST_SUITE_LOG}, which defaults to @file{test-suite.log} and requires
9030 a @file{.log} suffix. This file depends upon all the @file{.log} and
9031 @file{.trs} files created for the test scripts listed in @code{TESTS}.
9034 As with the serial harness above, by default one status line is printed
9035 per completed test, and a short summary after the suite has completed.
9036 However, standard output and standard error of the test are redirected
9037 to a per-test log file, so that parallel execution does not produce
9038 intermingled output. The output from failed tests is collected in the
9039 @file{test-suite.log} file. If the variable @samp{VERBOSE} is set, this
9040 file is output after the summary.
9041 @c FIXME: we should be clearer about what we mean exactly here ...
9042 For best results, the tests should be verbose by default now.
9044 @vindex TEST_EXTENSIONS
9046 Each couple of @file{.log} and @file{.trs} files is created when the
9047 corresponding test has completed. The set of log files is listed in
9048 the read-only variable @code{TEST_LOGS}, and defaults to @code{TESTS},
9049 with the executable extension if any (@pxref{EXEEXT}), as well as any
9050 suffix listed in @code{TEST_EXTENSIONS} removed, and @file{.log} appended.
9051 Results are undefined if a test file name ends in several concatenated
9052 suffixes. @code{TEST_EXTENSIONS} defaults to @file{.test}; it can be
9053 overridden by the user, in which case any extension listed in it must be
9054 constituted by a dot, followed by a non-digit alphabetic character,
9055 followed by any number of alphabetic characters.
9056 @c Keep in sync with test-extensions.test.
9057 For example, @samp{.sh}, @samp{.T} and @samp{.t1} are valid extensions,
9058 while @samp{.x-y}, @samp{.6c} and @samp{.t.1} are not.
9060 @vindex _LOG_COMPILE
9061 @vindex _LOG_COMPILER
9064 @vindex LOG_COMPILER
9066 @vindex @var{ext}_LOG_COMPILE
9067 @vindex @var{ext}_LOG_COMPILER
9068 @vindex @var{ext}_LOG_FLAGS
9069 @vindex AM_@var{ext}_LOG_FLAGS
9070 @vindex AM_LOG_FLAGS
9071 For tests that match an extension @code{.@var{ext}} listed in
9072 @code{TEST_EXTENSIONS}, you can provide a custom ``test runner'' using
9073 the variable @code{@var{ext}_LOG_COMPILER} (note the upper-case
9074 extension) and pass options in @code{AM_@var{ext}_LOG_FLAGS} and allow
9075 the user to pass options in @code{@var{ext}_LOG_FLAGS}. It will cause
9076 all tests with this extension to be called with this runner. For all
9077 tests without a registered extension, the variables @code{LOG_COMPILER},
9078 @code{AM_LOG_FLAGS}, and @code{LOG_FLAGS} may be used. For example,
9080 @c Keep in sync with parallel-tests-log-compiler-example.test.
9082 TESTS = foo.pl bar.py baz
9083 TEST_EXTENSIONS = .pl .py
9084 PL_LOG_COMPILER = $(PERL)
9085 AM_PL_LOG_FLAGS = -w
9086 PY_LOG_COMPILER = $(PYTHON)
9087 AM_PY_LOG_FLAGS = -v
9088 LOG_COMPILER = ./wrapper-script
9093 will invoke @samp{$(PERL) -w foo.pl}, @samp{$(PYTHON) -v bar.py},
9094 and @samp{./wrapper-script -d baz} to produce @file{foo.log},
9095 @file{bar.log}, and @file{baz.log}, respectively. The @file{foo.trs},
9096 @file{bar.trs} and @file{baz.trs} files will be automatically produced
9099 It's important to note that, differently from what we've seen for the
9100 serial test harness (@pxref{Parallel Test Harness}), the
9101 @code{AM_TESTS_ENVIRONMENT} and @code{TESTS_ENVIRONMENT} variables
9102 @emph{cannot} be use to define a custom test runner; the
9103 @code{LOG_COMPILER} and @code{LOG_FLAGS} (or their extension-specific
9104 counterparts) should be used instead:
9108 AM_TESTS_ENVIRONMENT = PERL5LIB='$(srcdir)/lib' $(PERL) -Mstrict -w
9113 AM_TESTS_ENVIRONMENT = PERL5LIB='$(srcdir)/lib'; export PERL5LIB;
9114 LOG_COMPILER = $(PERL)
9115 AM_LOG_FLAGS = -Mstrict -w
9118 By default, the test suite harness will run all tests, but there are
9119 several ways to limit the set of tests that are run:
9123 You can set the @code{TESTS} variable. For example, you can use a
9124 command like this to run only a subset of the tests:
9127 env TESTS="foo.test bar.test" make -e check
9130 Note however that the command above will unconditionally overwrite the
9131 @file{test-suite.log} file, thus clobbering the recorded results
9132 of any previous testsuite run. This might be undesirable for packages
9133 whose testsuite takes long time to execute. Luckily, this problem can
9134 easily be avoided by overriding also @code{TEST_SUITE_LOG} at runtime;
9137 @c Keep in sync with parallel-tests-log-override-2.test.
9139 env TEST_SUITE_LOG=partial.log TESTS="..." make -e check
9142 will write the result of the partial testsuite runs to the
9143 @file{partial.log}, without touching @file{test-suite.log}.
9146 You can set the @code{TEST_LOGS} variable. By default, this variable is
9147 computed at @command{make} run time from the value of @code{TESTS} as
9148 described above. For example, you can use the following:
9151 set x subset*.log; shift
9152 env TEST_LOGS="foo.log $*" make -e check
9155 The comments made above about @code{TEST_SUITE_LOG} overriding applies
9159 @vindex RECHECK_LOGS
9160 @cindex lazy test execution
9161 By default, the test harness removes all old per-test @file{.log} and
9162 @file{.trs} files before it starts running tests to regenerate them. The
9163 variable @code{RECHECK_LOGS} contains the set of @file{.log} (and, by
9164 implication, @file{.trs}) files which are removed. @code{RECHECK_LOGS}
9165 defaults to @code{TEST_LOGS}, which means all tests need to be rechecked.
9166 By overriding this variable, you can choose which tests need to be
9167 reconsidered. For example, you can lazily rerun only those tests which
9168 are outdated, i.e., older than their prerequisite test files, by setting
9169 this variable to the empty value:
9172 env RECHECK_LOGS= make -e check
9177 You can ensure that all tests are rerun which have failed or passed
9178 unexpectedly, by running @code{make recheck} in the test directory.
9179 This convenience target will set @code{RECHECK_LOGS} appropriately
9180 before invoking the main test harness.
9184 In order to guarantee an ordering between tests even with @code{make
9185 -j@var{N}}, dependencies between the corresponding @file{.log} files
9186 may be specified through usual @command{make} dependencies. For example,
9187 the following snippet lets the test named @file{foo-execute.test} depend
9188 upon completion of the test @file{foo-compile.test}:
9191 TESTS = foo-compile.test foo-execute.test
9192 foo-execute.log: foo-compile.log
9196 Please note that this ordering ignores the @emph{results} of required
9197 tests, thus the test @file{foo-execute.test} is run even if the test
9198 @file{foo-compile.test} failed or was skipped beforehand. Further,
9199 please note that specifying such dependencies currently works only for
9200 tests that end in one of the suffixes listed in @code{TEST_EXTENSIONS}.
9202 Tests without such specified dependencies may be run concurrently with
9203 parallel @command{make -j@var{N}}, so be sure they are prepared for
9204 concurrent execution.
9207 @c Keep in sync with 'parallel-tests-extra-programs.test'.
9208 The combination of lazy test execution and correct dependencies between
9209 tests and their sources may be exploited for efficient unit testing
9210 during development. To further speed up the edit-compile-test cycle, it
9211 may even be useful to specify compiled programs in @code{EXTRA_PROGRAMS}
9212 instead of with @code{check_PROGRAMS}, as the former allows intertwined
9213 compilation and test execution (but note that @code{EXTRA_PROGRAMS} are
9214 not cleaned automatically, @pxref{Uniform}).
9216 The variables @code{TESTS} and @code{XFAIL_TESTS} may contain
9217 conditional parts as well as configure substitutions. In the latter
9218 case, however, certain restrictions apply: substituted test names
9219 must end with a nonempty test suffix like @file{.test}, so that one of
9220 the inference rules generated by @command{automake} can apply. For
9221 literal test names, @command{automake} can generate per-target rules
9222 to avoid this limitation.
9224 Please note that it is currently not possible to use @code{$(srcdir)/}
9225 or @code{$(top_srcdir)/} in the @code{TESTS} variable. This technical
9226 limitation is necessary to avoid generating test logs in the source tree
9227 and has the unfortunate consequence that it is not possible to specify
9228 distributed tests that are themselves generated by means of explicit
9229 rules, in a way that is portable to all @command{make} implementations
9230 (@pxref{Make Target Lookup,,, autoconf, The Autoconf Manual}, the
9231 semantics of FreeBSD and OpenBSD @command{make} conflict with this).
9232 In case of doubt you may want to require to use GNU @command{make},
9233 or work around the issue with inference rules to generate the tests.
9235 @node Custom Test Drivers
9236 @section Custom Test Drivers
9239 * Overview of Custom Test Drivers Support::
9240 * Declaring Custom Test Drivers::
9241 * API for Custom Test Drivers::
9244 @node Overview of Custom Test Drivers Support
9245 @subsection Overview of Custom Test Drivers Support
9247 Starting from Automake version 1.12, the parallel test harness allows
9248 the package authors to use third-party custom test drivers, in case the
9249 default ones are inadequate for their purposes, or do not support their
9250 testing protocol of choice.
9252 A custom test driver is expected to properly run the test programs passed
9253 to it (including the command-line arguments passed to those programs, if
9254 any), to analyze their execution and outcome, to create the @file{.log}
9255 and @file{.trs} files associated to these test runs, and to display the test
9256 results on the console. It is responsibility of the author of the test
9257 driver to ensure that it implements all the above steps meaningfully and
9258 correctly; Automake isn't and can't be of any help here. On the other
9259 hand, the Automake-provided code for testsuite summary generation offers
9260 support for test drivers allowing several test results per test script,
9261 if they take care to register such results properly (@pxref{Log files
9262 generation and test results recording}).
9264 The exact details of how test scripts' results are to be determined and
9265 analyzed is left to the individual drivers. Some drivers might only
9266 consider the test script exit status (this is done for example by the
9267 default test driver used by the parallel test harness, described
9268 in the previous section). Other drivers might implement more complex and
9269 advanced test protocols, which might require them to parse and interpreter
9270 the output emitted by the test script they're running (examples of such
9271 protocols are TAP and SubUnit).
9273 It's very important to note that, even when using custom test drivers,
9274 most of the infrastructure described in the previous section about the
9275 parallel harness remains in place; this includes:
9279 list of test scripts defined in @code{TESTS}, and overridable at
9280 runtime through the redefinition of @code{TESTS} or @code{TEST_LOGS};
9282 concurrency through the use of @command{make}'s option @option{-j};
9284 per-test @file{.log} and @file{.trs} files, and generation of a summary
9285 @file{.log} file from them;
9287 @code{recheck} target, @code{RECHECK_LOGS} variable, and lazy reruns
9290 inter-test dependencies;
9292 support for @code{check_*} variables (@code{check_PROGRAMS},
9293 @code{check_LIBRARIES}, ...);
9295 use of @code{VERBOSE} environment variable to get verbose output on
9298 definition and honoring of @code{TESTS_ENVIRONMENT},
9299 @code{AM_TESTS_ENVIRONMENT} and @code{AM_TESTS_FD_REDIRECT}
9302 definition of generic and extension-specific @code{LOG_COMPILER} and
9303 @code{LOG_FLAGS} variables.
9307 On the other hand, the exact semantics of how (and if)
9308 @option{color-tests}, @code{XFAIL_TESTS}, and hard errors are supported
9309 and handled is left to the individual test drivers.
9311 @c TODO: We should really add a working example in the doc/ directory,
9312 @c TODO: and reference if from here.
9314 @node Declaring Custom Test Drivers
9315 @subsection Declaring Custom Test Drivers
9318 @vindex _LOG_DRIVER_FLAGS
9320 @vindex LOG_DRIVER_FLAGS
9321 @vindex @var{ext}_LOG_DRIVER
9322 @vindex @var{ext}_LOG_DRIVER_FLAGS
9323 @vindex AM_@var{ext}_LOG_DRIVER_FLAGS
9324 @vindex AM_LOG_DRIVER_FLAGS
9325 Custom testsuite drivers are declared by defining the make variables
9326 @code{LOG_DRIVER} or @code{@var{ext}_LOG_DRIVER} (where @var{ext} must
9327 be declared in @code{TEST_EXTENSIONS}). They must be defined to
9328 programs or scripts that will be used to drive the execution, logging,
9329 and outcome report of the tests with corresponding extensions (or of
9330 those with no registered extension in the case of @code{LOG_DRIVER}).
9331 Clearly, multiple distinct test drivers can be declared in the same
9332 @file{Makefile.am}. Note moreover that the @code{LOG_DRIVER} variables
9333 are @emph{not} a substitute for the @code{LOG_COMPILER} variables: the
9334 two sets of variables can, and often do, usefully and legitimately
9337 @c TODO: We should really be able to point to a clarifying example here!
9339 The developer-reserved variable @code{AM_LOG_DRIVER_FLAGS} and the
9340 user-reserved variable @code{LOG_DRIVER_FLAGS} can be used to define
9341 flags that will be passed to each invocation of @code{LOG_DRIVER},
9342 with the user-defined flags obviously taking precedence over the
9343 developer-reserved ones. Similarly, for each extension @var{ext}
9344 declared in @code{TEST_EXTENSIONS}, flags listed in
9345 @code{AM_@var{ext}_LOG_DRIVER_FLAGS} and
9346 @code{@var{ext}_LOG_DRIVER_FLAGS} will be passed to
9347 invocations of @code{@var{ext}_LOG_DRIVER}.
9349 @node API for Custom Test Drivers
9350 @subsection API for Custom Test Drivers
9352 Note that @emph{the APIs described here are still highly experimental},
9353 and will very likely undergo tightenings and likely also extensive changes
9354 in the future, to accommodate for new features or to satisfy additional
9355 portability requirements.
9357 The main characteristic of these APIs is that they are designed to share
9358 as much infrastructure, semantics, and implementation details as possible
9359 with the parallel test harness and its default driver.
9362 * Command-line arguments for test drivers::
9363 * Log files generation and test results recording::
9364 * Testsuite progress output::
9367 @node Command-line arguments for test drivers
9368 @subsubsection Command-line arguments for test drivers
9370 A custom driver can rely on various command-line options and arguments
9371 being passed to it automatically by the Automake's @option{parallel-tests}
9372 harness. It is @emph{mandatory} that it understands all of them (even
9373 if the exact interpretation of the associated semantics can legitimately
9374 change between a test driver and another, and even be a no-op in some
9378 Here is the list of options:
9381 @item --test-name=@var{NAME}
9382 The name of the test, with VPATH prefix (if any) removed. This can have a
9383 suffix and a directory component (as in e.g., @file{sub/foo.test}), and is
9384 mostly meant to be used in console reports about testsuite advancements and
9385 results (@pxref{Testsuite progress output}).
9386 @item --log-file=@file{@var{PATH}.log}
9387 The @file{.log} file the test driver must create (@pxref{Basics of
9388 test metadata}). If it has a directory component (as in e.g.,
9389 @file{sub/foo.log}), the test harness will ensure that such directory
9390 exists @emph{before} the test driver is called.
9391 @item --trs-file=@file{@var{PATH}.trs}
9392 The @file{.trs} file the test driver must create (@pxref{Basics of
9393 test metadata}). If it has a directory component (as in e.g.,
9394 @file{sub/foo.trs}), the test harness will ensure that such directory
9395 exists @emph{before} the test driver is called.
9396 @item --color-tests=@{yes|no@}
9397 Whether the console output should be colorized or not (@pxref{Simple
9398 tests and color-tests}, to learn when this option gets activated and
9400 @item --expect-failure=@{yes|no@}
9401 Whether the tested program is expected to fail.
9402 @item --enable-hard-errors=@{yes|no@}
9403 Whether ``hard errors'' in the tested program should be treated differently
9404 from normal failures or not (the default should be @code{yes}). The exact
9405 meaning of ``hard error'' is highly dependent from the test protocols or
9408 Explicitly terminate the list of options.
9412 The first non-option argument passed to the test driver is the program to
9413 be run, and all the following ones are command-line options and arguments
9416 Note that the exact semantics attached to the @option{--color-tests},
9417 @option{--expect-failure} and @option{--enable-hard-errors} options are
9418 left up to the individual test drivers. Still, having a behaviour
9419 compatible or at least similar to that provided by the default
9420 @option{parallel-tests} driver is advised, as that would offer a better
9421 consistency and a more pleasant user experience.
9423 @node Log files generation and test results recording
9424 @subsubsection Log files generation and test results recording
9426 The test driver must correctly generate the files specified by the
9427 @option{--log-file} and @option{--trs-file} option (even when the tested
9428 program fails or crashes).
9430 The @file{.log} file should ideally contain all the output produced by the
9431 tested program, plus optionally other information that might facilitate
9432 debugging or analysis of bug reports. Apart from that, its format is
9435 The @file{.trs} file is used to register some metadata through the use
9436 of custom reStructuredText fields. This metadata is expected to be
9437 employed in various ways by the parallel test harness; for example, to
9438 count the test results when printing the testsuite summary, or to decide
9439 which tests to re-run upon @command{make reheck}. Unrecognized metadata
9440 in a @file{.trs} file is currently ignored by the harness, but this might
9441 change in the future. The list of currently recognized metadata follows.
9446 @cindex Register test result
9447 @cindex Register test case result
9448 @cindex Test result, registering
9449 @cindex Test case result, registering
9450 @cindex @code{:test-result:}
9451 @cindex reStructuredText field, @code{:test-result:}
9452 The test driver must use this field to register the results of @emph{each}
9453 test case run by a test script file. Several @code{:test-result:} fields
9454 can be present in the same @file{.trs} file; this is done in order to
9455 support test protocols that allow a single test script to run more test
9458 @c Keep this in sync with lib/am/check-am:$(TEST_SUITE_LOG).
9459 The only recognized test results are currently @code{PASS}, @code{XFAIL},
9460 @code{SKIP}, @code{FAIL}, @code{XPASS} and @code{ERROR}. These results,
9461 when declared with @code{:test-result:}, can be optionally followed by
9462 text holding the name and/or a brief description of the corresponding
9463 test; the @option{parallel-tests} harness will ignore such extra text when
9464 generating @file{test-suite.log} and preparing the testsuite summary.
9466 @c Keep in sync with 'test-metadata-recheck.test'.
9467 @item @code{:recheck:}
9469 @cindex reStructuredText field, @code{:recheck:}
9470 If this field is present and defined to @code{no}, then the corresponding
9471 test script will @emph{not} be run upon a @command{make recheck}. What
9472 happens when two or more @code{:recheck:} fields are present in the same
9473 @file{.trs} file is undefined behaviour.
9475 @c Keep in sync with 'test-metadata-global-log.test'.
9476 @item @code{:copy-in-global-log:}
9477 @cindex :copy-in-global-log:
9478 @cindex reStructuredText field, @code{:copy-in-global-log:}
9479 If this field is present and defined to @code{no}, then the content
9480 of the @file{.log} file will @emph{not} be copied into the global
9481 @file{test-suite.log}. We allow to forsake such copying because, while
9482 it can be useful in debugging and analysis of bug report, it can also be
9483 just a waste of space in normal situations, e.g., when a test script is
9484 successful. What happens when two or more @code{:copy-in-global-log:}
9485 fields are present in the same @file{.trs} file is undefined behaviour.
9487 @c Keep in sync with 'test-metadata-global-result.test'.
9488 @item @code{:test-global-result:}
9489 @cindex :test-global-result:
9490 @cindex reStructuredText field, @code{:test-global-result:}
9491 This is used to declare the "global result" of the script. Currently,
9492 the value of this field is needed only to be reported (more or less
9493 verbatim) in the generated global log file @code{$(TEST_SUITE_LOG)},
9494 so it's quite free-form. For example, a test script which run 10 test
9495 cases, 6 of which pass and 4 of which are skipped, could reasonably have
9496 a @code{PASS/SKIP} value for this field, while a test script which run
9497 19 successful tests and one failed test could have an @code{ALMOST
9498 PASSED} value. What happens when two or more @code{:test-global-result:}
9499 fields are present in the same @file{.trs} file is undefined behaviour.
9503 Let's see a small example. Assume a @file{.trs} file contains the
9507 :test-result: PASS server starts
9508 :global-log-copy: no
9509 :test-result: PASS HTTP/1.1 request
9510 :test-result: FAIL HTTP/1.0 request
9512 :test-result: SKIP HTTPS request (TLS library wasn't available)
9513 :test-result: PASS server stops
9517 Then the corresponding test script will be re-run by @command{make check},
9518 will contribute with @emph{five} test results to the testsuite summary
9519 (three of these tests being successful, one failed, and one skipped), and
9520 the content of the corresponding @file{.log} file will @emph{not} be
9521 copied in the global log file @file{test-suite.log}.
9523 @node Testsuite progress output
9524 @subsubsection Testsuite progress output
9526 A custom test driver also has the task of displaying, on the standard
9527 output, the test results as soon as they become available. Depending on
9528 the protocol in use, it can also display the reasons for failures and
9529 skips, and, more generally, any useful diagnostic output (but remember
9530 that each line on the screen is precious, so that cluttering the screen
9531 with overly verbose information is bad idea). The exact format of this
9532 progress output is left up to the test driver; in fact, a custom test
9533 driver might @emph{theoretically} even decide not to do any such report,
9534 leaving it all to the testsuite summary (that would be a very lousy idea,
9535 of course, and serves only to illustrate the flexibility that is
9538 Remember that consistency is good; so, if possible, try to be consistent
9539 with the output of the built-in Automake test drivers, providing a similar
9540 ``look & feel''. In particular, the testsuite progress output should be
9541 colorized when the @option{--color-tests} is passed to the driver. On the
9542 other end, if you are using a known and widespread test protocol with
9543 well-established implementations, being consistent with those
9544 implementations' output might be a good idea too.
9546 @c TODO: Give an example, maybe inspired to py.test-style output.
9547 @c TODO: That is a good idea because it shows a test driver that allows
9548 @c TODO: for different levels of verbosity in the progress output (could
9549 @c TODO: be implemented either using a driver cmdline flag, or an
9550 @c TODO: environment variable, or both).
9552 @node Using the TAP test protocol
9553 @section Using the TAP test protocol
9556 * Introduction to TAP::
9557 * Use TAP with the Automake test harness::
9558 * Incompatibilities with other TAP parsers and drivers::
9559 * Links and external resources on TAP::
9562 @node Introduction to TAP
9563 @subsection Introduction to TAP
9565 TAP, the Test Anything Protocol, is a simple text-based interface between
9566 testing modules or programs and a test harness. The tests (also called
9567 ``TAP producers'' in this context) write test results in a simple format
9568 on standard output; a test harness (also called ``TAP consumer'') will
9569 parse and interpret these results, and properly present them to the user,
9570 and/or register them for later analysis. The exact details of how this
9571 is accomplished can vary among different test harnesses. The Automake
9572 parallel harness will present the results on the console in the usual
9573 fashion (@pxref{Testsuite progress on console}), and will use the
9574 @file{.trs} files (@pxref{Basics of test metadata}) to store the test
9575 results and related metadata. Apart from that, it will try to remain
9576 as much compatible as possible with pre-existing and widespread utilities,
9577 such as the @uref{http://search.cpan.org/~andya/Test-Harness/bin/prove,
9578 @command{prove} utility}, at least for the simpler usages.
9580 TAP started its life as part of the test harness for Perl, but today
9581 it has been (mostly) standardized, and has various independent
9582 implementations in different languages; among them, C, C++, Perl,
9583 Python, PHP, and Java. For a semi-official specification of the
9584 TAP protocol, please refer to the documentation of
9585 @uref{http://search.cpan.org/~petdance/Test-Harness/lib/Test/Harness/TAP.pod,
9586 @samp{Test::Harness::TAP}}.
9588 The most relevant real-world usages of TAP are obviously in the testsuites
9589 of @command{perl} and of many perl modules. Still, also other important
9590 third-party packages, such as @uref{http://git-scm.com/, @command{git}},
9591 use TAP in their testsuite.
9593 @node Use TAP with the Automake test harness
9594 @subsection Use TAP with the Automake test harness
9596 Currently, the TAP driver that comes with Automake requires a perl
9597 interpreter to work, and requires various by-hand steps on the
9598 developer's part (this should be fixed in future Automake versions).
9599 You'll have grab the @file{tap-driver.pl} script from the Automake
9600 distribution by hand, copy it in your source tree, add code to
9601 @file{configure.ac} to search a perl interpreter and to define the
9602 @code{$(PERL)} variable accordingly, and use the Automake support
9603 for third-party test drivers to instruct the harness to use the
9604 @file{tap-driver.pl} to run your TAP-producing tests. See the example
9605 below for clarification.
9607 Apart from the options common to all the Automake test drivers
9608 (@pxref{Command-line arguments for test drivers}), the @file{tap-driver.pl}
9609 supports the following options, whose names are chosen for enhanced
9610 compatibility with the @command{prove} utility.
9613 @c Keep in sync with 'tap-exit.test' and 'tap-signal.test'.
9615 Causes the test driver to ignore the exit status of the test scripts;
9616 by default, the driver will report an error if the script exit with a
9617 non-zero status. This option has effect also
9619 Instruct the test driver to display TAP diagnostic (i.e., lines beginning
9620 with the @samp{#} character) in the testsuite progress output too; by
9621 default, TAP diagnostic is only copied in the @file{.log} file.
9623 Revert the effects of @option{--comments}.
9625 Instruct the test driver to merge the test scripts' standard error into
9626 their standard output. This is necessary if you want to ensure that
9627 diagnostics from the test scripts are displayed in the correct order
9628 relative to test results; this can be of great help in debugging
9629 (especially if your test scripts are shell scripts run with shell
9630 tracing active). As a downside, this option might cause the test
9631 harness to get confused if anything that appears on standard error
9632 looks like a test result.
9634 Revert the effects of @option{--merge}.
9635 @item --diagnostic-string=@var{STRING}
9636 Change the string that introduces TAP diagnostic from the default value
9637 of ``@code{#}'' to @code{@var{STRING}}. This can be useful if your
9638 TAP-based test scripts produce verbose output on which they have limited
9639 control (because, say, the output comes by other tools invoked in the
9640 scripts), and it might contain text that gets spuriously interpreted as
9641 TAP diagnostic: such an issue can be solved by redefining the string that
9642 activates TAP diagnostic to a value you know won't appear by chance in
9643 the tests' output. Note however that this feature is non-standard, as
9644 the ``official'' TAP protocol does not allow for such a customization; so
9645 don't use it if you can avoid it.
9649 Here is an example of how the TAP driver can be set up and used.
9651 @c Keep in sync with tap-doc2.test.
9653 % @kbd{cat configure.ac}
9654 AC_INIT([GNU Try Tap], [1.0], [bug-automake@@gnu.org])
9655 AC_CONFIG_AUX_DIR([build-aux])
9656 AM_INIT_AUTOMAKE([foreign parallel-tests -Wall -Werror])
9657 AC_CONFIG_FILES([Makefile])
9658 AC_REQUIRE_AUX_FILE([tap-driver.pl])
9659 AC_PATH_PROG([PERL], [perl])
9660 test -n "$PERL" || AC_MSG_ERROR([perl not found])
9661 $PERL -MTAP::Parser -e 1 || AC_MSG_ERROR([TAP::Parser not found])
9664 % @kbd{cat Makefile.am}
9665 TEST_LOG_DRIVER = $(PERL) $(srcdir)/build-aux/tap-driver.pl
9666 TESTS = foo.test bar.test baz.test
9667 EXTRA_DIST = $(TESTS)
9669 % @kbd{cat foo.test}
9671 echo 1..4 # Number of tests to be executed.
9672 echo 'ok 1 - Swallows fly'
9673 echo 'not ok 2 - Caterpillars fly # TODO metamorphosis in progress'
9674 echo 'ok 3 - Pigs fly # SKIP not enough acid'
9675 echo '# I just love word plays ...'
9676 echo 'ok 4 - Flies fly too :-)'
9678 % @kbd{cat bar.test}
9681 echo 'not ok 1 - Bummer, this test has failed.'
9682 echo 'ok 2 - This passed though.'
9683 echo 'Bail out! Ennui kicking in, sorry...'
9684 echo 'ok 3 - This will not be seen.'
9686 % @kbd{cat baz.test}
9690 # Exit with error, even if all the test case has been successful.
9693 % @kbd{cp @var{PREFIX}/share/automake-@var{APIVERSION}/tap-driver.pl .}
9694 % @kbd{autoreconf -vi && ./configure && make check}
9696 PASS: foo.test 1 - Swallows fly
9697 XFAIL: foo.test 2 - Caterpillars fly # TODO metamorphosis in progress
9698 SKIP: foo.test 3 - Pigs fly # SKIP not enough acid
9699 PASS: foo.test 4 - Flies fly too :-)
9700 FAIL: bar.test 1 - Bummer, this test has failed.
9701 PASS: bar.test 2 - This passed though.
9702 ERROR: bar.test - Bail out! Ennui kicking in, sorry...
9704 ERROR: baz.test - exited with status 7
9706 Please report to bug-automake@@gnu.org
9708 % @kbd{echo exit status: $?}
9711 @c Keep the "skewed" indentation below, it produces pretty PDF output.
9712 % @kbd{env TEST_LOG_DRIVER_FLAGS='--comments --ignore-exit' \
9713 TESTS='foo.test baz.test' make -e check}
9715 PASS: foo.test 1 - Swallows fly
9716 XFAIL: foo.test 2 - Caterpillars fly # TODO metamorphosis in progress
9717 SKIP: foo.test 3 - Pigs fly # SKIP not enough acid
9718 # foo.test: I just love word plays...
9719 PASS: foo.test 4 - Flies fly too :-)
9722 % @kbd{echo exit status: $?}
9726 @node Incompatibilities with other TAP parsers and drivers
9727 @subsection Incompatibilities with other TAP parsers and drivers
9729 For implementation or historical reasons, the TAP driver and harness as
9730 implemented by Automake have some minors incompatibilities with the
9731 mainstream versions, which you should be aware of.
9735 A @code{Bail out!} directive doesn't stop the whole testsuite, but only
9736 the test script it occurs into. This doesn't follows TAP specifications,
9737 but on the other hand it maximizes compatibility (and code sharing) with
9738 the ``hard error'' concept of the default @option{parallel-tests} driver.
9740 The @code{version} and @code{pragma} directives are not supported.
9742 The @option{--diagnostic-string} option of out driver allows to modify
9743 the string that introduces TAP diagnostic from the default value
9744 of ``@code{#}''. The standard TAP protocol has currently no way to
9745 allow this, so if you use it your diagnostic will be lost to more
9746 compliant tools like @command{prove} and @code{Test::Harness}
9748 And there are probably some other small and yet undiscovered
9749 incompatibilities, especially in corner cases or with rare usages.
9752 @node Links and external resources on TAP
9753 @subsection Links and external resources on TAP
9756 Here are some links to more extensive official or third-party
9757 documentation and resources about the TAP protocol and related
9758 tools and libraries.
9761 @uref{http://search.cpan.org/~petdance/Test-Harness/lib/Test/Harness/TAP.pod,
9762 @samp{Test::Harness::TAP}},
9763 the (mostly) official documentation about the TAP format and protocol.
9765 @uref{http://search.cpan.org/~andya/Test-Harness/bin/prove,
9767 the most famous command-line TAP test driver, included in the distribution
9768 of @command{perl} and
9769 @uref{http://search.cpan.org/~andya/Test-Harness/lib/Test/Harness.pm,
9770 @samp{Test::Harness}}.
9772 The @uref{http://testanything.org/wiki/index.php/Main_Page,TAP wiki}.
9774 A ``gentle introduction'' to testing for perl coders:
9775 @uref{http://search.cpan.org/dist/Test-Simple/lib/Test/Tutorial.pod,
9776 @samp{Test::Tutorial}}.
9778 @uref{http://search.cpan.org/~mschwern/Test-Simple/lib/Test/Simple.pm,
9779 @samp{Test::Simple}}
9781 @uref{http://search.cpan.org/~mschwern/Test-Simple/lib/Test/More.pm,
9783 the standard perl testing libraries, which are based on TAP.
9785 @uref{http://www.eyrie.org/~eagle/software/c-tap-harness/,C TAP Harness},
9786 a C-based project implementing both a TAP producer and a TAP consumer.
9788 @uref{http://www.tap4j.org/,tap4j},
9789 a Java-based project implementing both a TAP producer and a TAP consumer.
9793 @section DejaGnu Tests
9795 If @uref{ftp://ftp.gnu.org/gnu/dejagnu/, @command{dejagnu}} appears in
9796 @code{AUTOMAKE_OPTIONS}, then a @command{dejagnu}-based test suite is
9797 assumed. The variable @code{DEJATOOL} is a list of names that are
9798 passed, one at a time, as the @option{--tool} argument to
9799 @command{runtest} invocations; it defaults to the name of the package.
9801 The variable @code{RUNTESTDEFAULTFLAGS} holds the @option{--tool} and
9802 @option{--srcdir} flags that are passed to dejagnu by default; this can be
9803 overridden if necessary.
9804 @vindex RUNTESTDEFAULTFLAGS
9806 The variables @code{EXPECT} and @code{RUNTEST} can
9807 also be overridden to provide project-specific values. For instance,
9808 you will need to do this if you are testing a compiler toolchain,
9809 because the default values do not take into account host and target
9816 The contents of the variable @code{RUNTESTFLAGS} are passed to the
9817 @code{runtest} invocation. This is considered a ``user variable''
9818 (@pxref{User Variables}). If you need to set @command{runtest} flags in
9819 @file{Makefile.am}, you can use @code{AM_RUNTESTFLAGS} instead.
9820 @vindex RUNTESTFLAGS
9821 @vindex AM_RUNTESTFLAGS
9823 @cindex @file{site.exp}
9824 Automake will generate rules to create a local @file{site.exp} file,
9825 defining various variables detected by @command{configure}. This file
9826 is automatically read by DejaGnu. It is OK for the user of a package
9827 to edit this file in order to tune the test suite. However this is
9828 not the place where the test suite author should define new variables:
9829 this should be done elsewhere in the real test suite code.
9830 Especially, @file{site.exp} should not be distributed.
9832 Still, if the package author has legitimate reasons to extend
9833 @file{site.exp} at @command{make} time, he can do so by defining
9834 the variable @code{EXTRA_DEJAGNU_SITE_CONFIG}; the files listed
9835 there will be considered @file{site.exp} prerequisites, and their
9836 content will be appended to it (in the same order in which they
9837 appear in @code{EXTRA_DEJAGNU_SITE_CONFIG}). Note that files are
9838 @emph{not} distributed by default.
9840 For more information regarding DejaGnu test suites, see @ref{Top, , ,
9841 dejagnu, The DejaGnu Manual}.
9844 @section Install Tests
9846 The @code{installcheck} target is available to the user as a way to
9847 run any tests after the package has been installed. You can add tests
9848 to this by writing an @code{installcheck-local} rule.
9852 @chapter Rebuilding Makefiles
9853 @cindex rebuild rules
9855 Automake generates rules to automatically rebuild @file{Makefile}s,
9856 @file{configure}, and other derived files like @file{Makefile.in}.
9858 @acindex AM_MAINTAINER_MODE
9859 If you are using @code{AM_MAINTAINER_MODE} in @file{configure.ac}, then
9860 these automatic rebuilding rules are only enabled in maintainer mode.
9862 @vindex ACLOCAL_AMFLAGS
9863 Sometimes you need to run @command{aclocal} with an argument like
9864 @option{-I} to tell it where to find @file{.m4} files. Since
9865 sometimes @command{make} will automatically run @command{aclocal}, you
9866 need a way to specify these arguments. You can do this by defining
9867 @code{ACLOCAL_AMFLAGS}; this holds arguments that are passed verbatim
9868 to @command{aclocal}. This variable is only useful in the top-level
9871 @vindex CONFIG_STATUS_DEPENDENCIES
9872 @vindex CONFIGURE_DEPENDENCIES
9873 @cindex @file{version.sh}, example
9874 @cindex @file{version.m4}, example
9876 Sometimes it is convenient to supplement the rebuild rules for
9877 @file{configure} or @file{config.status} with additional dependencies.
9878 The variables @code{CONFIGURE_DEPENDENCIES} and
9879 @code{CONFIG_STATUS_DEPENDENCIES} can be used to list these extra
9880 dependencies. These variables should be defined in all
9881 @file{Makefile}s of the tree (because these two rebuild rules are
9882 output in all them), so it is safer and easier to @code{AC_SUBST} them
9883 from @file{configure.ac}. For instance, the following statement will
9884 cause @file{configure} to be rerun each time @file{version.sh} is
9888 AC_SUBST([CONFIG_STATUS_DEPENDENCIES], ['$(top_srcdir)/version.sh'])
9892 Note the @samp{$(top_srcdir)/} in the file name. Since this variable
9893 is to be used in all @file{Makefile}s, its value must be sensible at
9894 any level in the build hierarchy.
9896 Beware not to mistake @code{CONFIGURE_DEPENDENCIES} for
9897 @code{CONFIG_STATUS_DEPENDENCIES}.
9899 @code{CONFIGURE_DEPENDENCIES} adds dependencies to the
9900 @file{configure} rule, whose effect is to run @command{autoconf}. This
9901 variable should be seldom used, because @command{automake} already tracks
9902 @code{m4_include}d files. However it can be useful when playing
9903 tricky games with @code{m4_esyscmd} or similar non-recommendable
9904 macros with side effects.
9906 @code{CONFIG_STATUS_DEPENDENCIES} adds dependencies to the
9907 @file{config.status} rule, whose effect is to run @file{configure}.
9908 This variable should therefore carry any non-standard source that may
9909 be read as a side effect of running @command{configure}, like @file{version.sh}
9910 in the example above.
9912 Speaking of @file{version.sh} scripts, we recommend against them
9913 today. They are mainly used when the version of a package is updated
9914 automatically by a script (e.g., in daily builds). Here is what some
9915 old-style @file{configure.ac}s may look like:
9919 . $srcdir/version.sh
9920 AM_INIT_AUTOMAKE([name], $VERSION_NUMBER)
9925 Here, @file{version.sh} is a shell fragment that sets
9926 @code{VERSION_NUMBER}. The problem with this example is that
9927 @command{automake} cannot track dependencies (listing @file{version.sh}
9928 in @command{CONFIG_STATUS_DEPENDENCIES}, and distributing this file is up
9929 to the user), and that it uses the obsolete form of @code{AC_INIT} and
9930 @code{AM_INIT_AUTOMAKE}. Upgrading to the new syntax is not
9931 straightforward, because shell variables are not allowed in
9932 @code{AC_INIT}'s arguments. We recommend that @file{version.sh} be
9933 replaced by an M4 file that is included by @file{configure.ac}:
9936 m4_include([version.m4])
9937 AC_INIT([name], VERSION_NUMBER)
9943 Here @file{version.m4} could contain something like
9944 @samp{m4_define([VERSION_NUMBER], [1.2])}. The advantage of this
9945 second form is that @command{automake} will take care of the
9946 dependencies when defining the rebuild rule, and will also distribute
9947 the file automatically. An inconvenience is that @command{autoconf}
9948 will now be rerun each time the version number is bumped, when only
9949 @file{configure} had to be rerun in the previous setup.
9953 @chapter Changing Automake's Behavior
9956 * Options generalities:: Semantics of Automake option
9957 * List of Automake options:: A comprehensive list of Automake options
9960 @node Options generalities
9961 @section Options generalities
9963 Various features of Automake can be controlled by options. Except where
9964 noted otherwise, options can be specified in one of several ways. Most
9965 options can be applied on a per-@file{Makefile} basis when listed in a
9966 special @file{Makefile} variable named @code{AUTOMAKE_OPTIONS}. Some
9967 of these options only make sense when specified in the toplevel
9968 @file{Makefile.am} file. Options are applied globally to all processed
9969 @file{Makefile} files when listed in the first argument of
9970 @code{AM_INIT_AUTOMAKE} in @file{configure.ac}, and some options which
9971 require changes to the @command{configure} script can only be specified
9972 there. These are annotated below.
9974 As a general rule, options specified in @code{AUTOMAKE_OPTIONS} take
9975 precedence over those specified in @code{AM_INIT_AUTOMAKE}, which in
9976 turn take precedence over those specified on the command line.
9978 Also, some care must be taken about the interactions among strictness
9979 level and warning categories. As a general rule, strictness-implied
9980 warnings are overridden by those specified by explicit options. For
9981 example, even if @samp{portability} warnings are disabled by default
9982 in @option{foreign} strictness, an usage like this will end up enabling
9986 AUTOMAKE_OPTIONS = -Wportability foreign
9989 However, a strictness level specified in a higher-priority context
9990 will override all the explicit warnings specified in a lower-priority
9991 context. For example, if @file{configure.ac} contains:
9994 AM_INIT_AUTOMAKE([-Wportability])
9998 and @file{Makefile.am} contains:
10001 AUTOMAKE_OPTIONS = foreign
10005 then @samp{portability} warnings will be @emph{disabled} in
10006 @file{Makefile.am}.
10008 @node List of Automake options
10009 @section List of Automake options
10011 @vindex AUTOMAKE_OPTIONS
10014 @item @option{gnits}
10015 @itemx @option{gnu}
10016 @itemx @option{foreign}
10017 @itemx @option{cygnus}
10018 @cindex Option, @option{gnits}
10019 @cindex Option, @option{gnu}
10020 @cindex Option, @option{foreign}
10021 @cindex Option, @option{cygnus}
10027 Set the strictness as appropriate. The @option{gnits} option also
10028 implies options @option{readme-alpha} and @option{check-news}.
10030 @item @option{check-news}
10031 @cindex Option, @option{check-news}
10032 @opindex check-news
10033 Cause @samp{make dist} to fail unless the current version number appears
10034 in the first few lines of the @file{NEWS} file.
10036 @item @option{color-tests}
10037 @cindex Option, @option{color-tests}
10038 @opindex color-tests
10039 Cause output of the serial and parallel test harnesses (see @ref{Simple
10040 Tests}) and of properly-written custom test drivers (@pxref{Custom Test
10041 Drivers}) to be colorized on capable terminals.
10043 @item @option{dejagnu}
10044 @cindex Option, @option{dejagnu}
10046 Cause @command{dejagnu}-specific rules to be generated. @xref{DejaGnu Tests}.
10048 @item @option{dist-bzip2}
10049 @cindex Option, @option{dist-bzip2}
10050 @opindex dist-bzip2
10051 Hook @code{dist-bzip2} to @code{dist}.
10052 @trindex dist-bzip2
10054 @item @option{dist-lzip}
10055 @cindex Option, @option{dist-lzip}
10057 Hook @code{dist-lzip} to @code{dist}.
10060 @item @option{dist-lzma}
10061 @cindex Option, @option{dist-lzma}
10063 Hook @code{dist-lzma} to @code{dist}. Obsoleted by @code{dist-xz}.
10066 @item @option{dist-shar}
10067 @cindex Option, @option{dist-shar}
10069 Hook @code{dist-shar} to @code{dist}.
10072 @item @option{dist-zip}
10073 @cindex Option, @option{dist-zip}
10075 Hook @code{dist-zip} to @code{dist}.
10078 @item @option{dist-tarZ}
10079 @cindex Option, @option{dist-tarZ}
10081 Hook @code{dist-tarZ} to @code{dist}.
10084 @item @option{filename-length-max=99}
10085 @cindex Option, @option{filename-length-max=99}
10086 @opindex filename-length-max=99
10087 Abort if file names longer than 99 characters are found during
10088 @samp{make dist}. Such long file names are generally considered not to
10089 be portable in tarballs. See the @option{tar-v7} and @option{tar-ustar}
10090 options below. This option should be used in the top-level
10091 @file{Makefile.am} or as an argument of @code{AM_INIT_AUTOMAKE} in
10092 @file{configure.ac}, it will be ignored otherwise. It will also be
10093 ignored in sub-packages of nested packages (@pxref{Subpackages}).
10095 @item @option{no-define}
10096 @cindex Option, @option{no-define}
10098 This option is meaningful only when passed as an argument to
10099 @code{AM_INIT_AUTOMAKE}. It will prevent the @code{PACKAGE} and
10100 @code{VERSION} variables from being @code{AC_DEFINE}d.
10102 @item @option{no-dependencies}
10103 @cindex Option, @option{no-dependencies}
10104 @opindex no-dependencies
10105 This is similar to using @option{--ignore-deps} on the command line,
10106 but is useful for those situations where you don't have the necessary
10107 bits to make automatic dependency tracking work
10108 (@pxref{Dependencies}). In this case the effect is to effectively
10109 disable automatic dependency tracking.
10111 @item @option{no-dist}
10112 @cindex Option, @option{no-dist}
10114 Don't emit any code related to @code{dist} target. This is useful
10115 when a package has its own method for making distributions.
10117 @item @option{no-dist-gzip}
10118 @cindex Option, @option{no-dist-gzip}
10119 @opindex no-dist-gzip
10120 Do not hook @code{dist-gzip} to @code{dist}.
10121 @trindex no-dist-gzip
10123 @item @option{no-exeext}
10124 @cindex Option, @option{no-exeext}
10126 If your @file{Makefile.am} defines a rule for target @code{foo}, it
10127 will override a rule for a target named @samp{foo$(EXEEXT)}. This is
10128 necessary when @code{EXEEXT} is found to be empty. However, by
10129 default @command{automake} will generate an error for this use. The
10130 @option{no-exeext} option will disable this error. This is intended for
10131 use only where it is known in advance that the package will not be
10132 ported to Windows, or any other operating system using extensions on
10135 @item @option{no-installinfo}
10136 @cindex Option, @option{no-installinfo}
10137 @opindex no-installinfo
10138 The generated @file{Makefile.in} will not cause info pages to be built
10139 or installed by default. However, @code{info} and @code{install-info}
10140 targets will still be available. This option is disallowed at
10141 @option{gnu} strictness and above.
10143 @trindex install-info
10145 @item @option{no-installman}
10146 @cindex Option, @option{no-installman}
10147 @opindex no-installman
10148 The generated @file{Makefile.in} will not cause man pages to be
10149 installed by default. However, an @code{install-man} target will still
10150 be available for optional installation. This option is disallowed at
10151 @option{gnu} strictness and above.
10152 @trindex install-man
10154 @item @option{nostdinc}
10155 @cindex Option, @option{nostdinc}
10157 This option can be used to disable the standard @option{-I} options that
10158 are ordinarily automatically provided by Automake.
10160 @item @option{no-texinfo.tex}
10161 @cindex Option, @option{no-texinfo.tex}
10162 @opindex no-texinfo.tex
10163 Don't require @file{texinfo.tex}, even if there are texinfo files in
10166 @item @option{parallel-tests}
10167 @cindex Option, @option{parallel-tests}
10168 @opindex parallel-tests
10169 Enable test suite harness for @code{TESTS} that can run tests in parallel
10170 (@pxref{Parallel Test Harness}, for more information).
10172 @item @option{readme-alpha}
10173 @cindex Option, @option{readme-alpha}
10174 @opindex readme-alpha
10175 If this release is an alpha release, and the file @file{README-alpha}
10176 exists, then it will be added to the distribution. If this option is
10177 given, version numbers are expected to follow one of two forms. The
10178 first form is @samp{@var{major}.@var{minor}.@var{alpha}}, where each
10179 element is a number; the final period and number should be left off for
10180 non-alpha releases. The second form is
10181 @samp{@var{major}.@var{minor}@var{alpha}}, where @var{alpha} is a
10182 letter; it should be omitted for non-alpha releases.
10184 @item @option{silent-rules}
10185 @cindex Option, @option{silent-rules}
10186 @opindex silent-rules
10187 Enable less verbose build rules. This can be used to let build rules
10188 output status lines of the form:
10190 GEN @var{output-file}
10191 CC @var{object-file}
10194 instead of printing the command that will be executed to update
10195 @var{output-file} or to compile @var{object-file}. It can also
10196 silence @command{libtool} output.
10198 For more information about how to use, enable, or disable silent
10199 rules, @pxref{Automake silent-rules Option}.
10201 @item @option{std-options}
10202 @cindex Options, @option{std-options}
10203 @cindex @samp{make installcheck}, testing @option{--help} and @option{--version}
10204 @cindex @option{--help} check
10205 @cindex @option{--version} check
10206 @opindex std-options
10208 Make the @code{installcheck} rule check that installed scripts and
10209 programs support the @option{--help} and @option{--version} options.
10210 This also provides a basic check that the program's
10211 run-time dependencies are satisfied after installation.
10213 @vindex AM_INSTALLCHECK_STD_OPTIONS_EXEMPT
10214 In a few situations, programs (or scripts) have to be exempted from this
10215 test. For instance, @command{false} (from GNU coreutils) is never
10216 successful, even for @option{--help} or @option{--version}. You can list
10217 such programs in the variable @code{AM_INSTALLCHECK_STD_OPTIONS_EXEMPT}.
10218 Programs (not scripts) listed in this variable should be suffixed by
10219 @samp{$(EXEEXT)} for the sake of Windows or OS/2. For instance, suppose we
10220 build @file{false} as a program but @file{true.sh} as a script, and that
10221 neither of them support @option{--help} or @option{--version}:
10224 AUTOMAKE_OPTIONS = std-options
10225 bin_PROGRAMS = false ...
10226 bin_SCRIPTS = true.sh ...
10227 AM_INSTALLCHECK_STD_OPTIONS_EXEMPT = false$(EXEEXT) true.sh
10230 @item @option{subdir-objects}
10231 @cindex Options, @option{subdir-objects}
10232 @opindex subdir-objects
10233 If this option is specified, then objects are placed into the
10234 subdirectory of the build directory corresponding to the subdirectory of
10235 the source file. For instance, if the source file is
10236 @file{subdir/file.cxx}, then the output file would be
10237 @file{subdir/file.o}.
10239 In order to use this option with C sources, you should add
10240 @code{AM_PROG_CC_C_O} to @file{configure.ac}.
10242 @anchor{tar-formats}
10243 @item @option{tar-v7}
10244 @itemx @option{tar-ustar}
10245 @itemx @option{tar-pax}
10246 @cindex Option, @option{tar-v7}
10247 @cindex Option, @option{tar-ustar}
10248 @cindex Option, @option{tar-pax}
10249 @cindex @command{tar} formats
10250 @cindex v7 @command{tar} format
10251 @cindex ustar format
10257 These three mutually exclusive options select the tar format to use
10258 when generating tarballs with @samp{make dist}. (The tar file created
10259 is then compressed according to the set of @option{no-dist-gzip},
10260 @option{dist-bzip2}, @option{dist-lzip}, @option{dist-xz} and
10261 @option{dist-tarZ} options in use.)
10263 These options must be passed as arguments to @code{AM_INIT_AUTOMAKE}
10264 (@pxref{Macros}) because they can require additional configure checks.
10265 Automake will complain if it sees such options in an
10266 @code{AUTOMAKE_OPTIONS} variable.
10268 @option{tar-v7} selects the old V7 tar format. This is the historical
10269 default. This antiquated format is understood by all tar
10270 implementations and supports file names with up to 99 characters. When
10271 given longer file names some tar implementations will diagnose the
10272 problem while other will generate broken tarballs or use non-portable
10273 extensions. Furthermore, the V7 format cannot store empty
10274 directories. When using this format, consider using the
10275 @option{filename-length-max=99} option to catch file names too long.
10277 @option{tar-ustar} selects the ustar format defined by POSIX
10278 1003.1-1988. This format is believed to be old enough to be portable.
10279 It fully supports empty directories. It can store file names with up
10280 to 256 characters, provided that the file name can be split at
10281 directory separator in two parts, first of them being at most 155
10282 bytes long. So, in most cases the maximum file name length will be
10283 shorter than 256 characters. However you may run against broken tar
10284 implementations that incorrectly handle file names longer than 99
10285 characters (please report them to @email{@value{PACKAGE_BUGREPORT}} so we
10286 can document this accurately).
10288 @option{tar-pax} selects the new pax interchange format defined by POSIX
10289 1003.1-2001. It does not limit the length of file names. However,
10290 this format is very young and should probably be restricted to
10291 packages that target only very modern platforms. There are moves to
10292 change the pax format in an upward-compatible way, so this option may
10293 refer to a more recent version in the future.
10295 @xref{Formats, , Controlling the Archive Format, tar, GNU Tar}, for
10296 further discussion about tar formats.
10298 @command{configure} knows several ways to construct these formats. It
10299 will not abort if it cannot find a tool up to the task (so that the
10300 package can still be built), but @samp{make dist} will fail.
10302 @item @var{version}
10303 @cindex Option, @var{version}
10304 A version number (e.g., @samp{0.30}) can be specified. If Automake is not
10305 newer than the version specified, creation of the @file{Makefile.in}
10306 will be suppressed.
10308 @item @option{-W@var{category}} or @option{--warnings=@var{category}}
10309 @cindex Option, warnings
10310 @cindex Option, @option{-W@var{category}}
10311 @cindex Option, @option{--warnings=@var{category}}
10312 These options behave exactly like their command-line counterpart
10313 (@pxref{automake Invocation}). This allows you to enable or disable some
10314 warning categories on a per-file basis. You can also setup some warnings
10315 for your entire project; for instance, try @samp{AM_INIT_AUTOMAKE([-Wall])}
10316 in your @file{configure.ac}.
10320 Unrecognized options are diagnosed by @command{automake}.
10322 If you want an option to apply to all the files in the tree, you can use
10323 the @code{AM_INIT_AUTOMAKE} macro in @file{configure.ac}.
10327 @node Miscellaneous
10328 @chapter Miscellaneous Rules
10330 There are a few rules and variables that didn't fit anywhere else.
10333 * Tags:: Interfacing to cscope, etags and mkid
10334 * Suffixes:: Handling new file extensions
10335 * Multilibs:: Support for multilibs.
10340 @section Interfacing to @command{etags}
10342 @cindex @file{TAGS} support
10344 Automake will generate rules to generate @file{TAGS} files for use with
10345 GNU Emacs under some circumstances.
10348 If any C, C++ or Fortran 77 source code or headers are present, then
10349 @code{tags} and @code{TAGS} rules will be generated for the directory.
10350 All files listed using the @code{_SOURCES}, @code{_HEADERS}, and
10351 @code{_LISP} primaries will be used to generate tags. Note that
10352 generated source files that are not distributed must be declared in
10353 variables like @code{nodist_noinst_HEADERS} or
10354 @code{nodist_@var{prog}_SOURCES} or they will be ignored.
10356 A @code{tags} rule will be output at the topmost directory of a
10357 multi-directory package. When run from this topmost directory,
10358 @samp{make tags} will generate a @file{TAGS} file that includes by
10359 reference all @file{TAGS} files from subdirectories.
10361 The @code{tags} rule will also be generated if the variable
10362 @code{ETAGS_ARGS} is defined. This variable is intended for use in
10363 directories that contain taggable source that @command{etags} does
10364 not understand. The user can use the @code{ETAGSFLAGS} to pass
10365 additional flags to @command{etags}; @code{AM_ETAGSFLAGS} is also
10366 available for use in @file{Makefile.am}.
10369 @vindex AM_ETAGSFLAGS
10371 Here is how Automake generates tags for its source, and for nodes in its
10375 ETAGS_ARGS = automake.in --lang=none \
10376 --regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi
10379 If you add file names to @code{ETAGS_ARGS}, you will probably also
10380 want to define @code{TAGS_DEPENDENCIES}. The contents of this variable
10381 are added directly to the dependencies for the @code{tags} rule.
10382 @vindex TAGS_DEPENDENCIES
10384 Automake also generates a @code{ctags} rule that can be used to
10385 build @command{vi}-style @file{tags} files. The variable @code{CTAGS}
10386 is the name of the program to invoke (by default @command{ctags});
10387 @code{CTAGSFLAGS} can be used by the user to pass additional flags,
10388 and @code{AM_CTAGSFLAGS} can be used by the @file{Makefile.am}.
10390 Automake will also generate an @code{ID} rule that will run
10391 @command{mkid} on the source. This is only supported on a
10392 directory-by-directory basis.
10395 Similarly, the @code{cscope} rule will create a list of all the source
10396 files in the tree and run @command{cscope} to build an inverted index
10397 database. The variable @code{CSCOPE} is the name of the program to invoke
10398 (by default @command{cscope}); @code{CSCOPEFLAGS} and
10399 @code{CSCOPE_ARGS} can be used by the user to pass additional flags and
10400 file names respectively, while @code{AM_CSCOPEFLAGS} can be used by the
10401 @file{Makefile.am}.
10403 Finally, Automake also emits rules to support the
10404 @uref{http://www.gnu.org/software/global/, GNU Global Tags program}.
10405 The @code{GTAGS} rule runs Global Tags and puts the
10406 result in the top build directory. The variable @code{GTAGS_ARGS}
10407 holds arguments that are passed to @command{gtags}.
10412 @section Handling new file extensions
10414 @cindex Adding new @code{SUFFIXES}
10415 @cindex @code{SUFFIXES}, adding
10418 It is sometimes useful to introduce a new implicit rule to handle a file
10419 type that Automake does not know about.
10421 For instance, suppose you had a compiler that could compile @file{.foo}
10422 files to @file{.o} files. You would simply define a suffix rule for
10430 Then you could directly use a @file{.foo} file in a @code{_SOURCES}
10431 variable and expect the correct results:
10434 bin_PROGRAMS = doit
10435 doit_SOURCES = doit.foo
10438 This was the simpler and more common case. In other cases, you will
10439 have to help Automake to figure out which extensions you are defining your
10440 suffix rule for. This usually happens when your extension does not
10441 start with a dot. Then, all you have to do is to put a list of new
10442 suffixes in the @code{SUFFIXES} variable @strong{before} you define your
10445 For instance, the following definition prevents Automake from misinterpreting
10446 the @samp{.idlC.cpp:} rule as an attempt to transform @file{.idlC} files into
10449 @c Keep in sync with suffix7.test.
10451 SUFFIXES = .idl C.cpp
10456 As you may have noted, the @code{SUFFIXES} variable behaves like the
10457 @code{.SUFFIXES} special target of @command{make}. You should not touch
10458 @code{.SUFFIXES} yourself, but use @code{SUFFIXES} instead and let
10459 Automake generate the suffix list for @code{.SUFFIXES}. Any given
10460 @code{SUFFIXES} go at the start of the generated suffixes list, followed
10461 by Automake generated suffixes not already in the list.
10464 @section Support for Multilibs
10466 Automake has support for an obscure feature called multilibs. A
10467 @dfn{multilib} is a library that is built for multiple different ABIs
10468 at a single time; each time the library is built with a different target
10469 flag combination. This is only useful when the library is intended to
10470 be cross-compiled, and it is almost exclusively used for compiler
10473 The multilib support is still experimental. Only use it if you are
10474 familiar with multilibs and can debug problems you might encounter.
10481 @cindex Including @file{Makefile} fragment
10482 @cindex @file{Makefile} fragment, including
10484 Automake supports an @code{include} directive that can be used to
10485 include other @file{Makefile} fragments when @command{automake} is run.
10486 Note that these fragments are read and interpreted by @command{automake},
10487 not by @command{make}. As with conditionals, @command{make} has no idea that
10488 @code{include} is in use.
10490 There are two forms of @code{include}:
10493 @item include $(srcdir)/file
10494 Include a fragment that is found relative to the current source
10497 @item include $(top_srcdir)/file
10498 Include a fragment that is found relative to the top source directory.
10501 Note that if a fragment is included inside a conditional, then the
10502 condition applies to the entire contents of that fragment.
10504 Makefile fragments included this way are always distributed because
10505 they are needed to rebuild @file{Makefile.in}.
10508 @chapter Conditionals
10510 @cindex Conditionals
10512 Automake supports a simple type of conditionals.
10514 These conditionals are not the same as conditionals in
10515 GNU Make. Automake conditionals are checked at configure time by the
10516 @file{configure} script, and affect the translation from
10517 @file{Makefile.in} to @file{Makefile}. They are based on options passed
10518 to @file{configure} and on results that @file{configure} has discovered
10519 about the host system. GNU Make conditionals are checked at @command{make}
10520 time, and are based on variables passed to the make program or defined
10521 in the @file{Makefile}.
10523 Automake conditionals will work with any make program.
10526 * Usage of Conditionals:: Declaring conditional content
10527 * Limits of Conditionals:: Enclosing complete statements
10530 @node Usage of Conditionals
10531 @section Usage of Conditionals
10533 @acindex AM_CONDITIONAL
10534 Before using a conditional, you must define it by using
10535 @code{AM_CONDITIONAL} in the @file{configure.ac} file (@pxref{Macros}).
10537 @defmac AM_CONDITIONAL (@var{conditional}, @var{condition})
10538 The conditional name, @var{conditional}, should be a simple string
10539 starting with a letter and containing only letters, digits, and
10540 underscores. It must be different from @samp{TRUE} and @samp{FALSE}
10541 that are reserved by Automake.
10543 The shell @var{condition} (suitable for use in a shell @code{if}
10544 statement) is evaluated when @command{configure} is run. Note that you
10545 must arrange for @emph{every} @code{AM_CONDITIONAL} to be invoked every
10546 time @command{configure} is run. If @code{AM_CONDITIONAL} is run
10547 conditionally (e.g., in a shell @code{if} statement), then the result
10548 will confuse @command{automake}.
10551 @cindex @option{--enable-debug}, example
10552 @cindex Example conditional @option{--enable-debug}
10553 @cindex Conditional example, @option{--enable-debug}
10555 Conditionals typically depend upon options that the user provides to
10556 the @command{configure} script. Here is an example of how to write a
10557 conditional that is true if the user uses the @option{--enable-debug}
10561 AC_ARG_ENABLE([debug],
10562 [ --enable-debug Turn on debugging],
10563 [case "$@{enableval@}" in
10566 *) AC_MSG_ERROR([bad value $@{enableval@} for --enable-debug]) ;;
10567 esac],[debug=false])
10568 AM_CONDITIONAL([DEBUG], [test x$debug = xtrue])
10571 Here is an example of how to use that conditional in @file{Makefile.am}:
10583 noinst_PROGRAMS = $(DBG)
10586 This trivial example could also be handled using @code{EXTRA_PROGRAMS}
10587 (@pxref{Conditional Programs}).
10589 You may only test a single variable in an @code{if} statement, possibly
10590 negated using @samp{!}. The @code{else} statement may be omitted.
10591 Conditionals may be nested to any depth. You may specify an argument to
10592 @code{else} in which case it must be the negation of the condition used
10593 for the current @code{if}. Similarly you may specify the condition
10594 that is closed on the @code{endif} line:
10605 Unbalanced conditions are errors. The @code{if}, @code{else}, and
10606 @code{endif} statements should not be indented, i.e., start on column
10609 The @code{else} branch of the above two examples could be omitted,
10610 since assigning the empty string to an otherwise undefined variable
10611 makes no difference.
10613 @acindex AM_COND_IF
10614 In order to allow access to the condition registered by
10615 @code{AM_CONDITIONAL} inside @file{configure.ac}, and to allow
10616 conditional @code{AC_CONFIG_FILES}, @code{AM_COND_IF} may be used:
10618 @defmac AM_COND_IF (@var{conditional}, @ovar{if-true}, @ovar{if-false})
10619 If @var{conditional} is fulfilled, execute @var{if-true}, otherwise
10620 execute @var{if-false}. If either branch contains @code{AC_CONFIG_FILES},
10621 it will cause @command{automake} to output the rules for the respective
10622 files only for the given condition.
10625 @code{AM_COND_IF} macros may be nested when m4 quotation is used
10626 properly (@pxref{M4 Quotation, ,, autoconf, The Autoconf Manual}).
10628 @cindex Example conditional @code{AC_CONFIG_FILES}
10629 @cindex @code{AC_CONFIG_FILES}, conditional
10631 Here is an example of how to define a conditional config file:
10634 AM_CONDITIONAL([SHELL_WRAPPER], [test "x$with_wrapper" = xtrue])
10635 AM_COND_IF([SHELL_WRAPPER],
10636 [AC_CONFIG_FILES([wrapper:wrapper.in])])
10639 @node Limits of Conditionals
10640 @section Limits of Conditionals
10642 Conditionals should enclose complete statements like variables or
10643 rules definitions. Automake cannot deal with conditionals used inside
10644 a variable definition, for instance, and is not even able to diagnose
10645 this situation. The following example would not work:
10648 # This syntax is not understood by Automake
10657 However the intended definition of @code{AM_CPPFLAGS} can be achieved
10662 DEBUGFLAGS = -DDEBUG
10664 AM_CPPFLAGS = -DFEATURE_A $(DEBUGFLAGS) -DFEATURE_B
10671 AM_CPPFLAGS = -DFEATURE_A
10673 AM_CPPFLAGS += -DDEBUG
10675 AM_CPPFLAGS += -DFEATURE_B
10678 More details and examples of conditionals are described alongside
10679 various Automake features in this manual (@pxref{Conditional
10680 Subdirectories}, @pxref{Conditional Sources}, @pxref{Conditional
10681 Programs}, @pxref{Conditional Libtool Libraries}, @pxref{Conditional
10684 @node Silencing Make
10685 @chapter Silencing @command{make}
10687 @cindex Silent @command{make}
10688 @cindex Silencing @command{make}
10689 @cindex Silent rules
10690 @cindex Silent @command{make} rules
10693 * Make verbosity:: Make is verbose by default
10694 * Tricks For Silencing Make:: Standard and generic ways to silence make
10695 * Automake silent-rules Option:: How Automake can help in silencing make
10698 @node Make verbosity
10699 @section Make is verbose by default
10701 Normally, when executing the set of rules associated with a target,
10702 @command{make} prints each rule before it is executed. This behaviour,
10703 while having been in place for a long time, and being even mandated by
10704 the POSIX standard, starkly violates the ``silence is golden'' UNIX
10705 principle@footnote{See also
10706 @uref{http://catb.org/~esr/writings/taoup/html/ch11s09.html}.}:
10709 When a program has nothing interesting or surprising to say, it should
10710 say nothing. Well-behaved Unix programs do their jobs unobtrusively,
10711 with a minimum of fuss and bother. Silence is golden.
10714 In fact, while such verbosity of @command{make} can theoretically be
10715 useful to track bugs and understand reasons of failures right away, it
10716 can also hide warning and error messages from @command{make}-invoked
10717 tools, drowning them in a flood of uninteresting and seldom useful
10718 messages, and thus allowing them to go easily undetected.
10720 This problem can be very annoying, especially for developers, who usually
10721 know quite well what's going on behind the scenes, and for whom the
10722 verbose output from @command{make} ends up being mostly noise that hampers
10723 the easy detection of potentially important warning messages.
10725 @node Tricks For Silencing Make
10726 @section Standard and generic ways to silence make
10728 Here we describe some common idioms/tricks to obtain a quieter make
10729 output, with their relative advantages and drawbacks. In the next
10730 section (@ref{Automake silent-rules Option}) we'll see how Automake
10731 can help in this respect.
10735 @item @command{make -s}
10737 This simply causes @command{make} not to print @emph{any} rule before
10740 The @option{-s} flag is mandated by POSIX, universally supported, and
10741 its purpose and function are easy to understand.
10743 But it also has its serious limitations too. First of all, it embodies
10744 an ``all or nothing'' strategy, i.e., either everything is silenced, or
10745 nothing is; this lack of granularity can sometimes be a fatal flaw.
10746 Moreover, when the @option{-s} flag is used, the @command{make} output
10747 might turn out to be too much terse; in case of errors, the user won't
10748 be able to easily see what rule or command have caused them, or even,
10749 in case of tools with poor error reporting, what the errors were!
10751 @item @command{make >/dev/null || make}
10753 Apparently, this perfectly obeys the ``silence is golden'' rule: warnings
10754 from stderr are passed through, output reporting is done only in case of
10755 error, and in that case it should provide a verbose-enough report to allow
10756 an easy determination of the error location and causes.
10758 However, calling @command{make} two times in a row might hide errors
10759 (especially intermittent ones), or subtly change the expected semantic
10760 of the @command{make} calls --- things these which can clearly make
10761 debugging and error assessment very difficult.
10763 @item @command{make --no-print-directory}
10765 This is GNU @command{make} specific. When called with the
10766 @option{--no-print-directory} option, GNU @command{make} will disable
10767 printing of the working directory by invoked sub-@command{make}s (the
10768 well-known ``@i{Entering/Leaving directory ...}'' messages). This helps
10769 to decrease the verbosity of the output, but experience has shown that
10770 it can also often render debugging considerably harder in projects using
10771 deeply-nested @command{make} recursion.
10773 As an aside, notice that the @option{--no-print-directory} option is
10774 automatically activated if the @option{-s} flag is used.
10776 @c TODO: Other tricks?
10777 @c TODO: Maybe speak about the @code{.SILENT} target?
10778 @c TODO: - Pros: More granularity on what to silence.
10779 @c TODO: - Cons: No easy way to temporarily override.
10783 @node Automake silent-rules Option
10784 @section How Automake can help in silencing make
10786 The tricks and idioms for silencing @command{make} described in the
10787 previous section can be useful from time to time, but we've seen that
10788 they all have their serious drawbacks and limitations. That's why
10789 automake provides support for a more advanced and flexible way of
10790 obtaining quieter output from @command{make}: the @option{silent-rules}
10793 @c TODO: Maybe describe in brief the precedent set by the build system
10794 @c of the Linux Kernel, from which Automake took inspiration ... Links?
10796 To give the gist of what @option{silent-rules} can do, here is a simple
10797 comparison between a typical @command{make} output (where silent rules
10798 are disabled) and one with silent rules enabled:
10801 % @kbd{cat Makefile.am}
10803 foo_SOURCES = main.c func.c
10805 int main (void) @{ return func (); @} /* func used undeclared */
10807 int func (void) @{ int i; return i; @} /* i used uninitialized */
10809 @i{The make output is by default very verbose. This causes warnings
10810 from the compiler to be somewhat hidden, and not immediate to spot.}
10811 % @kbd{make CFLAGS=-Wall}
10812 gcc -DPACKAGE_NAME=\"foo\" -DPACKAGE_TARNAME=\"foo\" ...
10813 -DPACKAGE_STRING=\"foo\ 1.0\" -DPACKAGE_BUGREPORT=\"\" ...
10814 -DPACKAGE=\"foo\" -DVERSION=\"1.0\" -I. -Wall -MT main.o
10815 -MD -MP -MF .deps/main.Tpo -c -o main.o main.c
10816 main.c: In function ‘main’:
10817 main.c:3:3: warning: implicit declaration of function ‘func’
10818 mv -f .deps/main.Tpo .deps/main.Po
10819 gcc -DPACKAGE_NAME=\"foo\" -DPACKAGE_TARNAME=\"foo\" ...
10820 -DPACKAGE_STRING=\"foo\ 1.0\" -DPACKAGE_BUGREPORT=\"\" ...
10821 -DPACKAGE=\"foo\" -DVERSION=\"1.0\" -I. -Wall -MT func.o
10822 -MD -MP -MF .deps/func.Tpo -c -o func.o func.c
10823 func.c: In function ‘func’:
10824 func.c:4:3: warning: ‘i’ used uninitialized in this function
10825 mv -f .deps/func.Tpo .deps/func.Po
10826 gcc -Wall -o foo main.o func.o
10828 @i{Clean up, so that we we can rebuild everything from scratch.}
10830 test -z "foo" || rm -f foo
10833 @i{Silent rules enabled: the output is minimal but informative. In
10834 particular, the warnings from the compiler stick out very clearly.}
10835 % @kbd{make V=0 CFLAGS=-Wall}
10837 main.c: In function ‘main’:
10838 main.c:3:3: warning: implicit declaration of function ‘func’
10840 func.c: In function ‘func’:
10841 func.c:4:3: warning: ‘i’ used uninitialized in this function
10845 @cindex silent-rules and libtool
10846 Also, in projects using @command{libtool}, the use of silent rules can
10847 automatically enable the @command{libtool}'s @option{--silent} option:
10850 % @kbd{cat Makefile.am}
10851 lib_LTLIBRARIES = libx.la
10853 % @kbd{make # Both make and libtool are verbose by default.}
10855 libtool: compile: gcc -DPACKAGE_NAME=\"foo\" ... -DLT_OBJDIR=\".libs/\"
10856 -I. -g -O2 -MT libx.lo -MD -MP -MF .deps/libx.Tpo -c libx.c -fPIC
10857 -DPIC -o .libs/libx.o
10858 mv -f .deps/libx.Tpo .deps/libx.Plo
10859 /bin/sh ./libtool --tag=CC --mode=link gcc -g -O2 -o libx.la -rpath
10860 /usr/local/lib libx.lo
10861 libtool: link: gcc -shared .libs/libx.o -Wl,-soname -Wl,libx.so.0
10862 -o .libs/libx.so.0.0.0
10863 libtool: link: cd .libs && rm -f libx.so && ln -s libx.so.0.0.0 libx.so
10871 Let's now see how the @option{silent-rules} mode interfaces with the
10872 package developer and the package user.
10874 To enable the use of @option{silent-rules} in his package, a developer
10875 needs to do either of the following:
10879 Add the @option{silent-rules} option as argument to @code{AM_INIT_AUTOMAKE}.
10881 Call the @code{AM_SILENT_RULES} macro from within the @file{configure.ac}
10885 It is not possible to instead specify @option{silent-rules} in a
10886 @file{Makefile.am} file.
10888 If the developer has done either of the above, then the user of the
10889 package may influence the verbosity at @command{configure} run time as
10890 well as at @command{make} run time:
10894 @opindex --enable-silent-rules
10895 @opindex --disable-silent-rules
10896 Passing @option{--enable-silent-rules} to @command{configure} will cause
10897 build rules to be less verbose; the option @option{--disable-silent-rules}
10898 will cause normal verbose output.
10901 At @command{make} run time, the default chosen at @command{configure}
10902 time may be overridden: @code{make V=1} will produce verbose output,
10903 @code{make V=0} less verbose output.
10906 @cindex default verbosity for silent-rules
10907 Note that silent rules are @emph{disabled} by default; the user must
10908 enable them explicitly at either @command{configure} run time or at
10909 @command{make} run time. We think that this is a good policy, since
10910 it provides the casual user with enough information to prepare a good
10911 bug report in case anything breaks.
10913 Still, notwithstanding the rationales above, a developer who wants to
10914 make silent rules enabled by default in his own package can do so by
10915 adding a @samp{yes} argument to the @code{AM_SILENT_RULES} call in
10916 @file{configure.ac}. We advise against this approach, though.
10918 @c Keep in sync with silent-configsite.test
10919 Users who prefer to have silent rules enabled by default can edit their
10920 @file{config.site} file to make the variable @code{enable_silent_rules}
10921 default to @samp{yes}. This should still allow disabling silent rules
10922 at @command{configure} time and at @command{make} time.
10924 @c FIXME: there's really a need to specify this explicitly?
10925 For portability to different @command{make} implementations, package authors
10926 are advised to not set the variable @code{V} inside the @file{Makefile.am}
10927 file, to allow the user to override the value for subdirectories as well.
10929 The current implementation of this feature normally uses nested
10930 variable expansion @samp{$(@var{var1}$(V))}, a @file{Makefile} feature
10931 that is not required by POSIX 2008 but is widely supported in
10932 practice. The @option{silent-rules} option thus turns off warnings
10933 about recursive variable expansion, which are in turn enabled by
10934 @option{-Wportability} (@pxref{automake Invocation}). On the rare
10935 @command{make} implementations that do not support nested variable
10936 expansion, whether rules are silent is always determined at configure
10937 time, and cannot be overridden at make time. Future versions of POSIX
10938 are likely to require nested variable expansion, so this minor
10939 limitation should go away with time.
10941 @vindex @code{AM_V_GEN}
10942 @vindex @code{AM_V_at}
10943 @vindex @code{AM_DEFAULT_VERBOSITY}
10944 @vindex @code{AM_V}
10945 @vindex @code{AM_DEFAULT_V}
10946 To extend the silent mode to your own rules, you have two choices:
10950 You can use the predefined variable @code{AM_V_GEN} as a prefix to
10951 commands that should output a status line in silent mode, and
10952 @code{AM_V_at} as a prefix to commands that should not output anything
10953 in silent mode. When output is to be verbose, both of these variables
10954 will expand to the empty string.
10956 You can add your own variables, so strings of your own choice are shown.
10957 The following snippet shows how you would define your own equivalent of
10961 pkg_verbose = $(pkg_verbose_@@AM_V@@)
10962 pkg_verbose_ = $(pkg_verbose_@@AM_DEFAULT_V@@)
10963 pkg_verbose_0 = @@echo PKG-GEN $@@;
10966 $(pkg_verbose)cp $(srcdir)/foo.in $@@
10971 As a final note, observe that, even when silent rules are enabled,
10972 the @option{--no-print-directory} option is still required with GNU
10973 @command{make} if the ``@i{Entering/Leaving directory ...}'' messages
10974 are to be disabled.
10977 @chapter The effect of @option{--gnu} and @option{--gnits}
10979 @cindex @option{--gnu}, required files
10980 @cindex @option{--gnu}, complete description
10982 The @option{--gnu} option (or @option{gnu} in the
10983 @code{AUTOMAKE_OPTIONS} variable) causes @command{automake} to check
10988 The files @file{INSTALL}, @file{NEWS}, @file{README}, @file{AUTHORS},
10989 and @file{ChangeLog}, plus one of @file{COPYING.LIB}, @file{COPYING.LESSER}
10990 or @file{COPYING}, are required at the topmost directory of the package.
10992 If the @option{--add-missing} option is given, @command{automake} will
10993 add a generic version of the @file{INSTALL} file as well as the
10994 @file{COPYING} file containing the text of the current version of the
10995 GNU General Public License existing at the time of this Automake release
10996 (version 3 as this is written, @uref{http://www.gnu.org/@/copyleft/@/gpl.html}).
10997 However, an existing @file{COPYING} file will never be overwritten by
10998 @command{automake}.
11001 The options @option{no-installman} and @option{no-installinfo} are
11005 Note that this option will be extended in the future to do even more
11006 checking; it is advisable to be familiar with the precise requirements
11007 of the GNU standards. Also, @option{--gnu} can require certain
11008 non-standard GNU programs to exist for use by various maintainer-only
11009 rules; for instance, in the future @command{pathchk} might be required for
11012 @cindex @option{--gnits}, complete description
11014 The @option{--gnits} option does everything that @option{--gnu} does, and
11015 checks the following as well:
11019 @samp{make installcheck} will check to make sure that the @option{--help}
11020 and @option{--version} really print a usage message and a version string,
11021 respectively. This is the @option{std-options} option (@pxref{Options}).
11024 @samp{make dist} will check to make sure the @file{NEWS} file has been
11025 updated to the current version.
11028 @code{VERSION} is checked to make sure its format complies with Gnits
11030 @c FIXME xref when standards are finished
11033 @cindex @file{README-alpha}
11034 If @code{VERSION} indicates that this is an alpha release, and the file
11035 @file{README-alpha} appears in the topmost directory of a package, then
11036 it is included in the distribution. This is done in @option{--gnits}
11037 mode, and no other, because this mode is the only one where version
11038 number formats are constrained, and hence the only mode where Automake
11039 can automatically determine whether @file{README-alpha} should be
11043 The file @file{THANKS} is required.
11048 @chapter The effect of @option{--cygnus}
11050 @cindex @option{cygnus} strictness
11052 Some packages, notably GNU GCC and GNU gdb, have a build environment
11053 originally written at Cygnus Support (subsequently renamed Cygnus
11054 Solutions, and then later purchased by Red Hat). Packages with this
11055 ancestry are sometimes referred to as ``Cygnus'' trees.
11057 A Cygnus tree has slightly different rules for how a
11058 @file{Makefile.in} is to be constructed. Passing @option{--cygnus} to
11059 @command{automake} will cause any generated @file{Makefile.in} to
11060 comply with Cygnus rules.
11062 Here are the precise effects of @option{--cygnus}:
11066 Info files are always created in the build directory, and not in the
11070 @file{texinfo.tex} is not required if a Texinfo source file is
11071 specified. The assumption is that the file will be supplied, but in a
11072 place that Automake cannot find. This assumption is an artifact of how
11073 Cygnus packages are typically bundled.
11076 @samp{make dist} is not supported, and the rules for it are not
11077 generated. Cygnus-style trees use their own distribution mechanism.
11080 Certain tools will be searched for in the build tree as well as in the
11081 user's @env{PATH}. These tools are @command{runtest}, @command{expect},
11082 @command{makeinfo} and @command{texi2dvi}.
11085 @option{--foreign} is implied.
11088 The options @option{no-installinfo} and @option{no-dependencies} are
11092 The macro @code{AM_MAINTAINER_MODE} is required.
11095 The @code{check} target doesn't depend on @code{all}.
11098 GNU maintainers are advised to use @option{gnu} strictness in preference
11099 to the special Cygnus mode. Some day, perhaps, the differences between
11100 Cygnus trees and GNU trees will disappear (for instance, as GCC is made
11101 more standards compliant). At that time the special Cygnus mode will be
11106 @chapter When Automake Isn't Enough
11108 In some situations, where Automake is not up to one task, one has to
11109 resort to handwritten rules or even handwritten @file{Makefile}s.
11112 * Extending:: Adding new rules or overriding existing ones.
11113 * Third-Party Makefiles:: Integrating Non-Automake @file{Makefile}s.
11117 @section Extending Automake Rules
11119 With some minor exceptions (for example @code{_PROGRAMS} variables,
11120 @code{TESTS}, or @code{XFAIL_TESTS}) being rewritten to append
11121 @samp{$(EXEEXT)}), the contents of a @file{Makefile.am} is copied to
11122 @file{Makefile.in} verbatim.
11124 @cindex copying semantics
11126 These copying semantics mean that many problems can be worked around
11127 by simply adding some @command{make} variables and rules to
11128 @file{Makefile.am}. Automake will ignore these additions.
11130 @cindex conflicting definitions
11131 @cindex rules, conflicting
11132 @cindex variables, conflicting
11133 @cindex definitions, conflicts
11135 Since a @file{Makefile.in} is built from data gathered from three
11136 different places (@file{Makefile.am}, @file{configure.ac}, and
11137 @command{automake} itself), it is possible to have conflicting
11138 definitions of rules or variables. When building @file{Makefile.in}
11139 the following priorities are respected by @command{automake} to ensure
11140 the user always has the last word:
11144 User defined variables in @file{Makefile.am} have priority over
11145 variables @code{AC_SUBST}ed from @file{configure.ac}, and
11146 @code{AC_SUBST}ed variables have priority over
11147 @command{automake}-defined variables.
11149 As far as rules are concerned, a user-defined rule overrides any
11150 @command{automake}-defined rule for the same target.
11153 @cindex overriding rules
11154 @cindex overriding semantics
11155 @cindex rules, overriding
11157 These overriding semantics make it possible to fine tune some default
11158 settings of Automake, or replace some of its rules. Overriding
11159 Automake rules is often inadvisable, particularly in the topmost
11160 directory of a package with subdirectories. The @option{-Woverride}
11161 option (@pxref{automake Invocation}) comes in handy to catch overridden
11164 Note that Automake does not make any distinction between rules with
11165 commands and rules that only specify dependencies. So it is not
11166 possible to append new dependencies to an @command{automake}-defined
11167 target without redefining the entire rule.
11169 @cindex @option{-local} targets
11170 @cindex local targets
11172 However, various useful targets have a @samp{-local} version you can
11173 specify in your @file{Makefile.am}. Automake will supplement the
11174 standard target with these user-supplied targets.
11179 @trindex info-local
11187 @trindex html-local
11189 @trindex check-local
11191 @trindex install-data
11192 @trindex install-data-local
11193 @trindex install-dvi
11194 @trindex install-dvi-local
11195 @trindex install-exec
11196 @trindex install-exec-local
11197 @trindex install-html
11198 @trindex install-html-local
11199 @trindex install-info
11200 @trindex install-info-local
11201 @trindex install-pdf
11202 @trindex install-pdf-local
11203 @trindex install-ps
11204 @trindex install-ps-local
11206 @trindex uninstall-local
11207 @trindex mostlyclean
11208 @trindex mostlyclean-local
11210 @trindex clean-local
11212 @trindex distclean-local
11213 @trindex installdirs
11214 @trindex installdirs-local
11215 @trindex installcheck
11216 @trindex installcheck-local
11218 The targets that support a local version are @code{all}, @code{info},
11219 @code{dvi}, @code{ps}, @code{pdf}, @code{html}, @code{check},
11220 @code{install-data}, @code{install-dvi}, @code{install-exec},
11221 @code{install-html}, @code{install-info}, @code{install-pdf},
11222 @code{install-ps}, @code{uninstall}, @code{installdirs},
11223 @code{installcheck} and the various @code{clean} targets
11224 (@code{mostlyclean}, @code{clean}, @code{distclean}, and
11225 @code{maintainer-clean}).
11227 Note that there are no @code{uninstall-exec-local} or
11228 @code{uninstall-data-local} targets; just use @code{uninstall-local}.
11229 It doesn't make sense to uninstall just data or just executables.
11231 For instance, here is one way to erase a subdirectory during
11232 @samp{make clean} (@pxref{Clean}).
11239 You may be tempted to use @code{install-data-local} to install a file
11240 to some hard-coded location, but you should avoid this
11241 (@pxref{Hard-Coded Install Paths}).
11243 With the @code{-local} targets, there is no particular guarantee of
11244 execution order; typically, they are run early, but with parallel
11245 make, there is no way to be sure of that.
11247 @cindex @option{-hook} targets
11248 @cindex hook targets
11249 @trindex install-data-hook
11250 @trindex install-exec-hook
11251 @trindex uninstall-hook
11254 In contrast, some rules also have a way to run another rule, called a
11255 @dfn{hook}; hooks are always executed after the main rule's work is done.
11256 The hook is named after the principal target, with @samp{-hook} appended.
11257 The targets allowing hooks are @code{install-data},
11258 @code{install-exec}, @code{uninstall}, @code{dist}, and
11261 For instance, here is how to create a hard link to an installed program:
11265 ln $(DESTDIR)$(bindir)/program$(EXEEXT) \
11266 $(DESTDIR)$(bindir)/proglink$(EXEEXT)
11269 Although cheaper and more portable than symbolic links, hard links
11270 will not work everywhere (for instance, OS/2 does not have
11271 @command{ln}). Ideally you should fall back to @samp{cp -p} when
11272 @command{ln} does not work. An easy way, if symbolic links are
11273 acceptable to you, is to add @code{AC_PROG_LN_S} to
11274 @file{configure.ac} (@pxref{Particular Programs, , Particular Program
11275 Checks, autoconf, The Autoconf Manual}) and use @samp{$(LN_S)} in
11276 @file{Makefile.am}.
11278 @cindex versioned binaries, installing
11279 @cindex installing versioned binaries
11280 @cindex @code{LN_S} example
11281 For instance, here is how you could install a versioned copy of a
11282 program using @samp{$(LN_S)}:
11284 @c Keep in sync with insthook.test
11287 cd $(DESTDIR)$(bindir) && \
11288 mv -f prog$(EXEEXT) prog-$(VERSION)$(EXEEXT) && \
11289 $(LN_S) prog-$(VERSION)$(EXEEXT) prog$(EXEEXT)
11292 Note that we rename the program so that a new version will erase the
11293 symbolic link, not the real binary. Also we @command{cd} into the
11294 destination directory in order to create relative links.
11296 When writing @code{install-exec-hook} or @code{install-data-hook},
11297 please bear in mind that the exec/data distinction is based on the
11298 installation directory, not on the primary used (@pxref{The Two Parts of
11300 @c Keep in sync with primary-prefix-couples-documented-valid.test.
11301 So a @code{foo_SCRIPTS} will be installed by
11302 @code{install-data}, and a @code{barexec_SCRIPTS} will be installed by
11303 @code{install-exec}. You should define your hooks consequently.
11305 @c FIXME should include discussion of variables you can use in these
11308 @node Third-Party Makefiles
11309 @section Third-Party @file{Makefile}s
11311 @cindex Third-party packages, interfacing with
11312 @cindex Interfacing with third-party packages
11314 In most projects all @file{Makefile}s are generated by Automake. In
11315 some cases, however, projects need to embed subdirectories with
11316 handwritten @file{Makefile}s. For instance, one subdirectory could be
11317 a third-party project with its own build system, not using Automake.
11319 It is possible to list arbitrary directories in @code{SUBDIRS} or
11320 @code{DIST_SUBDIRS} provided each of these directories has a
11321 @file{Makefile} that recognizes all the following recursive targets.
11323 @cindex recursive targets and third-party @file{Makefile}s
11324 When a user runs one of these targets, that target is run recursively
11325 in all subdirectories. This is why it is important that even
11326 third-party @file{Makefile}s support them.
11330 Compile the entire package. This is the default target in
11331 Automake-generated @file{Makefile}s, but it does not need to be the
11332 default in third-party @file{Makefile}s.
11337 @vindex top_distdir
11338 Copy files to distribute into @samp{$(distdir)}, before a tarball is
11339 constructed. Of course this target is not required if the
11340 @option{no-dist} option (@pxref{Options}) is used.
11342 The variables @samp{$(top_distdir)} and @samp{$(distdir)}
11343 (@pxref{The dist Hook}) will be passed from the outer package to the subpackage
11344 when the @code{distdir} target is invoked. These two variables have
11345 been adjusted for the directory that is being recursed into, so they
11349 @itemx install-data
11350 @itemx install-exec
11352 Install or uninstall files (@pxref{Install}).
11355 @itemx install-html
11356 @itemx install-info
11359 Install only some specific documentation format (@pxref{Texinfo}).
11362 Create install directories, but do not install any files.
11365 @itemx installcheck
11366 Check the package (@pxref{Tests}).
11371 @itemx maintainer-clean
11372 Cleaning rules (@pxref{Clean}).
11379 Build the documentation in various formats (@pxref{Texinfo}).
11383 Build @file{TAGS} and @file{CTAGS} (@pxref{Tags}).
11386 If you have ever used Gettext in a project, this is a good example of
11387 how third-party @file{Makefile}s can be used with Automake. The
11388 @file{Makefile}s @command{gettextize} puts in the @file{po/} and
11389 @file{intl/} directories are handwritten @file{Makefile}s that
11390 implement all these targets. That way they can be added to
11391 @code{SUBDIRS} in Automake packages.
11393 Directories that are only listed in @code{DIST_SUBDIRS} but not in
11394 @code{SUBDIRS} need only the @code{distclean},
11395 @code{maintainer-clean}, and @code{distdir} rules (@pxref{Conditional
11398 Usually, many of these rules are irrelevant to the third-party
11399 subproject, but they are required for the whole package to work. It's
11400 OK to have a rule that does nothing, so if you are integrating a
11401 third-party project with no documentation or tag support, you could
11402 simply augment its @file{Makefile} as follows:
11405 EMPTY_AUTOMAKE_TARGETS = dvi pdf ps info html tags ctags
11406 .PHONY: $(EMPTY_AUTOMAKE_TARGETS)
11407 $(EMPTY_AUTOMAKE_TARGETS):
11410 Another aspect of integrating third-party build systems is whether
11411 they support VPATH builds (@pxref{VPATH Builds}). Obviously if the
11412 subpackage does not support VPATH builds the whole package will not
11413 support VPATH builds. This in turns means that @samp{make distcheck}
11414 will not work, because it relies on VPATH builds. Some people can
11415 live without this (actually, many Automake users have never heard of
11416 @samp{make distcheck}). Other people may prefer to revamp the
11417 existing @file{Makefile}s to support VPATH@. Doing so does not
11418 necessarily require Automake, only Autoconf is needed (@pxref{Build
11419 Directories, , Build Directories, autoconf, The Autoconf Manual}).
11420 The necessary substitutions: @samp{@@srcdir@@}, @samp{@@top_srcdir@@},
11421 and @samp{@@top_builddir@@} are defined by @file{configure} when it
11422 processes a @file{Makefile} (@pxref{Preset Output Variables, , Preset
11423 Output Variables, autoconf, The Autoconf Manual}), they are not
11424 computed by the Makefile like the aforementioned @samp{$(distdir)} and
11425 @samp{$(top_distdir)} variables.
11427 It is sometimes inconvenient to modify a third-party @file{Makefile}
11428 to introduce the above required targets. For instance, one may want to
11429 keep the third-party sources untouched to ease upgrades to new
11432 @cindex @file{GNUmakefile} including @file{Makefile}
11433 Here are two other ideas. If GNU make is assumed, one possibility is
11434 to add to that subdirectory a @file{GNUmakefile} that defines the
11435 required targets and includes the third-party @file{Makefile}. For
11436 this to work in VPATH builds, @file{GNUmakefile} must lie in the build
11437 directory; the easiest way to do this is to write a
11438 @file{GNUmakefile.in} instead, and have it processed with
11439 @code{AC_CONFIG_FILES} from the outer package. For example if we
11440 assume @file{Makefile} defines all targets except the documentation
11441 targets, and that the @code{check} target is actually called
11442 @code{test}, we could write @file{GNUmakefile} (or
11443 @file{GNUmakefile.in}) like this:
11446 # First, include the real Makefile
11448 # Then, define the other targets needed by Automake Makefiles.
11449 .PHONY: dvi pdf ps info html check
11450 dvi pdf ps info html:
11454 @cindex Proxy @file{Makefile} for third-party packages
11455 A similar idea that does not use @code{include} is to write a proxy
11456 @file{Makefile} that dispatches rules to the real @file{Makefile},
11457 either with @samp{$(MAKE) -f Makefile.real $(AM_MAKEFLAGS) target} (if
11458 it's OK to rename the original @file{Makefile}) or with @samp{cd
11459 subdir && $(MAKE) $(AM_MAKEFLAGS) target} (if it's OK to store the
11460 subdirectory project one directory deeper). The good news is that
11461 this proxy @file{Makefile} can be generated with Automake. All we
11462 need are @option{-local} targets (@pxref{Extending}) that perform the
11463 dispatch. Of course the other Automake features are available, so you
11464 could decide to let Automake perform distribution or installation.
11465 Here is a possible @file{Makefile.am}:
11469 cd subdir && $(MAKE) $(AM_MAKEFLAGS) all
11471 cd subdir && $(MAKE) $(AM_MAKEFLAGS) test
11473 cd subdir && $(MAKE) $(AM_MAKEFLAGS) clean
11475 # Assuming the package knows how to install itself
11476 install-data-local:
11477 cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-data
11478 install-exec-local:
11479 cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-exec
11481 cd subdir && $(MAKE) $(AM_MAKEFLAGS) uninstall
11483 # Distribute files from here.
11484 EXTRA_DIST = subdir/Makefile subdir/program.c ...
11487 Pushing this idea to the extreme, it is also possible to ignore the
11488 subproject build system and build everything from this proxy
11489 @file{Makefile.am}. This might sound very sensible if you need VPATH
11490 builds but the subproject does not support them.
11493 @chapter Distributing @file{Makefile.in}s
11495 Automake places no restrictions on the distribution of the resulting
11496 @file{Makefile.in}s. We still encourage software authors to
11497 distribute their work under terms like those of the GPL, but doing so
11498 is not required to use Automake.
11500 Some of the files that can be automatically installed via the
11501 @option{--add-missing} switch do fall under the GPL@. However, these also
11502 have a special exception allowing you to distribute them with your
11503 package, regardless of the licensing you choose.
11506 @node API Versioning
11507 @chapter Automake API Versioning
11509 New Automake releases usually include bug fixes and new features.
11510 Unfortunately they may also introduce new bugs and incompatibilities.
11511 This makes four reasons why a package may require a particular Automake
11514 Things get worse when maintaining a large tree of packages, each one
11515 requiring a different version of Automake. In the past, this meant that
11516 any developer (and sometimes users) had to install several versions of
11517 Automake in different places, and switch @samp{$PATH} appropriately for
11520 Starting with version 1.6, Automake installs versioned binaries. This
11521 means you can install several versions of Automake in the same
11522 @samp{$prefix}, and can select an arbitrary Automake version by running
11523 @command{automake-1.6} or @command{automake-1.7} without juggling with
11524 @samp{$PATH}. Furthermore, @file{Makefile}'s generated by Automake 1.6
11525 will use @command{automake-1.6} explicitly in their rebuild rules.
11527 The number @samp{1.6} in @command{automake-1.6} is Automake's API version,
11528 not Automake's version. If a bug fix release is made, for instance
11529 Automake 1.6.1, the API version will remain 1.6. This means that a
11530 package that works with Automake 1.6 should also work with 1.6.1; after
11531 all, this is what people expect from bug fix releases.
11533 If your package relies on a feature or a bug fix introduced in
11534 a release, you can pass this version as an option to Automake to ensure
11535 older releases will not be used. For instance, use this in your
11536 @file{configure.ac}:
11539 AM_INIT_AUTOMAKE([1.6.1]) dnl Require Automake 1.6.1 or better.
11543 or, in a particular @file{Makefile.am}:
11546 AUTOMAKE_OPTIONS = 1.6.1 # Require Automake 1.6.1 or better.
11550 Automake will print an error message if its version is
11551 older than the requested version.
11554 @heading What is in the API
11556 Automake's programming interface is not easy to define. Basically it
11557 should include at least all @strong{documented} variables and targets
11558 that a @file{Makefile.am} author can use, any behavior associated with
11559 them (e.g., the places where @samp{-hook}'s are run), the command line
11560 interface of @command{automake} and @command{aclocal}, @dots{}
11562 @heading What is not in the API
11564 Every undocumented variable, target, or command line option, is not part
11565 of the API@. You should avoid using them, as they could change from one
11566 version to the other (even in bug fix releases, if this helps to fix a
11569 If it turns out you need to use such an undocumented feature, contact
11570 @email{automake@@gnu.org} and try to get it documented and exercised by
11574 @chapter Upgrading a Package to a Newer Automake Version
11576 Automake maintains three kind of files in a package.
11579 @item @file{aclocal.m4}
11580 @item @file{Makefile.in}s
11581 @item auxiliary tools like @file{install-sh} or @file{py-compile}
11584 @file{aclocal.m4} is generated by @command{aclocal} and contains some
11585 Automake-supplied M4 macros. Auxiliary tools are installed by
11586 @samp{automake --add-missing} when needed. @file{Makefile.in}s are
11587 built from @file{Makefile.am} by @command{automake}, and rely on the
11588 definitions of the M4 macros put in @file{aclocal.m4} as well as the
11589 behavior of the auxiliary tools installed.
11591 Because all these files are closely related, it is important to
11592 regenerate all of them when upgrading to a newer Automake release.
11593 The usual way to do that is
11596 aclocal # with any option needed (such a -I m4)
11598 automake --add-missing --force-missing
11602 or more conveniently:
11608 The use of @option{--force-missing} ensures that auxiliary tools will be
11609 overridden by new versions (@pxref{automake Invocation}).
11611 It is important to regenerate all these files each time Automake is
11612 upgraded, even between bug fixes releases. For instance, it is not
11613 unusual for a bug fix to involve changes to both the rules generated
11614 in @file{Makefile.in} and the supporting M4 macros copied to
11617 Presently @command{automake} is able to diagnose situations where
11618 @file{aclocal.m4} has been generated with another version of
11619 @command{aclocal}. However it never checks whether auxiliary scripts
11620 are up-to-date. In other words, @command{automake} will tell you when
11621 @command{aclocal} needs to be rerun, but it will never diagnose a
11622 missing @option{--force-missing}.
11624 Before upgrading to a new major release, it is a good idea to read the
11625 file @file{NEWS}. This file lists all changes between releases: new
11626 features, obsolete constructs, known incompatibilities, and
11630 @chapter Frequently Asked Questions about Automake
11632 This chapter covers some questions that often come up on the mailing
11636 * CVS:: CVS and generated files
11637 * maintainer-mode:: missing and AM_MAINTAINER_MODE
11638 * Wildcards:: Why doesn't Automake support wildcards?
11639 * Limitations on File Names:: Limitations on source and installed file names
11640 * distcleancheck:: Files left in build directory after distclean
11641 * Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS
11642 * Renamed Objects:: Why are object files sometimes renamed?
11643 * Per-Object Flags:: How to simulate per-object flags?
11644 * Multiple Outputs:: Writing rules for tools with many output files
11645 * Hard-Coded Install Paths:: Installing to hard-coded locations
11646 * Debugging Make Rules:: Strategies when things don't work as expected
11647 * Reporting Bugs:: Feedback on bugs and feature requests
11651 @section CVS and generated files
11653 @subheading Background: distributed generated Files
11654 @cindex generated files, distributed
11655 @cindex rebuild rules
11657 Packages made with Autoconf and Automake ship with some generated
11658 files like @file{configure} or @file{Makefile.in}. These files were
11659 generated on the developer's host and are distributed so that
11660 end-users do not have to install the maintainer tools required to
11661 rebuild them. Other generated files like Lex scanners, Yacc parsers,
11662 or Info documentation, are usually distributed on similar grounds.
11664 Automake outputs rules in @file{Makefile}s to rebuild these files. For
11665 instance, @command{make} will run @command{autoconf} to rebuild
11666 @file{configure} whenever @file{configure.ac} is changed. This makes
11667 development safer by ensuring a @file{configure} is never out-of-date
11668 with respect to @file{configure.ac}.
11670 As generated files shipped in packages are up-to-date, and because
11671 @command{tar} preserves times-tamps, these rebuild rules are not
11672 triggered when a user unpacks and builds a package.
11674 @subheading Background: CVS and Timestamps
11675 @cindex timestamps and CVS
11676 @cindex CVS and timestamps
11678 Unless you use CVS keywords (in which case files must be updated at
11679 commit time), CVS preserves timestamp during @samp{cvs commit} and
11680 @samp{cvs import -d} operations.
11682 When you check out a file using @samp{cvs checkout} its timestamp is
11683 set to that of the revision that is being checked out.
11685 However, during @command{cvs update}, files will have the date of the
11686 update, not the original timestamp of this revision. This is meant to
11687 make sure that @command{make} notices sources files have been updated.
11689 This timestamp shift is troublesome when both sources and generated
11690 files are kept under CVS@. Because CVS processes files in lexical
11691 order, @file{configure.ac} will appear newer than @file{configure}
11692 after a @command{cvs update} that updates both files, even if
11693 @file{configure} was newer than @file{configure.ac} when it was
11694 checked in. Calling @command{make} will then trigger a spurious rebuild
11695 of @file{configure}.
11697 @subheading Living with CVS in Autoconfiscated Projects
11698 @cindex CVS and generated files
11699 @cindex generated files and CVS
11701 There are basically two clans amongst maintainers: those who keep all
11702 distributed files under CVS, including generated files, and those who
11703 keep generated files @emph{out} of CVS.
11705 @subsubheading All Files in CVS
11709 The CVS repository contains all distributed files so you know exactly
11710 what is distributed, and you can checkout any prior version entirely.
11713 Maintainers can see how generated files evolve (for instance, you can
11714 see what happens to your @file{Makefile.in}s when you upgrade Automake
11715 and make sure they look OK).
11718 Users do not need the autotools to build a checkout of the project, it
11719 works just like a released tarball.
11722 If users use @command{cvs update} to update their copy, instead of
11723 @command{cvs checkout} to fetch a fresh one, timestamps will be
11724 inaccurate. Some rebuild rules will be triggered and attempt to
11725 run developer tools such as @command{autoconf} or @command{automake}.
11727 Actually, calls to such tools are all wrapped into a call to the
11728 @command{missing} script discussed later (@pxref{maintainer-mode}).
11729 @command{missing} will take care of fixing the timestamps when these
11730 tools are not installed, so that the build can continue.
11733 In distributed development, developers are likely to have different
11734 version of the maintainer tools installed. In this case rebuilds
11735 triggered by timestamp lossage will lead to spurious changes
11736 to generated files. There are several solutions to this:
11740 All developers should use the same versions, so that the rebuilt files
11741 are identical to files in CVS@. (This starts to be difficult when each
11742 project you work on uses different versions.)
11744 Or people use a script to fix the timestamp after a checkout (the GCC
11745 folks have such a script).
11747 Or @file{configure.ac} uses @code{AM_MAINTAINER_MODE}, which will
11748 disable all these rebuild rules by default. This is further discussed
11749 in @ref{maintainer-mode}.
11753 Although we focused on spurious rebuilds, the converse can also
11754 happen. CVS's timestamp handling can also let you think an
11755 out-of-date file is up-to-date.
11757 For instance, suppose a developer has modified @file{Makefile.am} and
11758 has rebuilt @file{Makefile.in}, and then decides to do a last-minute
11759 change to @file{Makefile.am} right before checking in both files
11760 (without rebuilding @file{Makefile.in} to account for the change).
11762 This last change to @file{Makefile.am} makes the copy of
11763 @file{Makefile.in} out-of-date. Since CVS processes files
11764 alphabetically, when another developer @samp{cvs update}s his or her
11765 tree, @file{Makefile.in} will happen to be newer than
11766 @file{Makefile.am}. This other developer will not see that
11767 @file{Makefile.in} is out-of-date.
11771 @subsubheading Generated Files out of CVS
11773 One way to get CVS and @command{make} working peacefully is to never
11774 store generated files in CVS, i.e., do not CVS-control files that
11775 are @file{Makefile} targets (also called @emph{derived} files).
11777 This way developers are not annoyed by changes to generated files. It
11778 does not matter if they all have different versions (assuming they are
11779 compatible, of course). And finally, timestamps are not lost, changes
11780 to sources files can't be missed as in the
11781 @file{Makefile.am}/@file{Makefile.in} example discussed earlier.
11783 The drawback is that the CVS repository is not an exact copy of what
11784 is distributed and that users now need to install various development
11785 tools (maybe even specific versions) before they can build a checkout.
11786 But, after all, CVS's job is versioning, not distribution.
11788 Allowing developers to use different versions of their tools can also
11789 hide bugs during distributed development. Indeed, developers will be
11790 using (hence testing) their own generated files, instead of the
11791 generated files that will be released actually. The developer who
11792 prepares the tarball might be using a version of the tool that
11793 produces bogus output (for instance a non-portable C file), something
11794 other developers could have noticed if they weren't using their own
11795 versions of this tool.
11797 @subheading Third-party Files
11798 @cindex CVS and third-party files
11799 @cindex third-party files and CVS
11801 Another class of files not discussed here (because they do not cause
11802 timestamp issues) are files that are shipped with a package, but
11803 maintained elsewhere. For instance, tools like @command{gettextize}
11804 and @command{autopoint} (from Gettext) or @command{libtoolize} (from
11805 Libtool), will install or update files in your package.
11807 These files, whether they are kept under CVS or not, raise similar
11808 concerns about version mismatch between developers' tools. The
11809 Gettext manual has a section about this, see @ref{CVS Issues, CVS
11810 Issues, Integrating with CVS, gettext, GNU gettext tools}.
11812 @node maintainer-mode
11813 @section @command{missing} and @code{AM_MAINTAINER_MODE}
11815 @subheading @command{missing}
11816 @cindex @command{missing}, purpose
11818 The @command{missing} script is a wrapper around several maintainer
11819 tools, designed to warn users if a maintainer tool is required but
11820 missing. Typical maintainer tools are @command{autoconf},
11821 @command{automake}, @command{bison}, etc. Because file generated by
11822 these tools are shipped with the other sources of a package, these
11823 tools shouldn't be required during a user build and they are not
11824 checked for in @file{configure}.
11826 However, if for some reason a rebuild rule is triggered and involves a
11827 missing tool, @command{missing} will notice it and warn the user.
11828 Besides the warning, when a tool is missing, @command{missing} will
11829 attempt to fix timestamps in a way that allows the build to continue.
11830 For instance, @command{missing} will touch @file{configure} if
11831 @command{autoconf} is not installed. When all distributed files are
11832 kept under version control, this feature of @command{missing} allows a
11833 user @emph{with no maintainer tools} to build a package off its version
11834 control repository, bypassing any timestamp inconsistency (implied by
11835 e.g.@: @samp{cvs update} or @samp{git clone}).
11837 If the required tool is installed, @command{missing} will run it and
11838 won't attempt to continue after failures. This is correct during
11839 development: developers love fixing failures. However, users with
11840 wrong versions of maintainer tools may get an error when the rebuild
11841 rule is spuriously triggered, halting the build. This failure to let
11842 the build continue is one of the arguments of the
11843 @code{AM_MAINTAINER_MODE} advocates.
11845 @subheading @code{AM_MAINTAINER_MODE}
11846 @cindex @code{AM_MAINTAINER_MODE}, purpose
11847 @acindex AM_MAINTAINER_MODE
11849 @code{AM_MAINTAINER_MODE} allows you to choose whether the so called
11850 "rebuild rules" should be enabled or disabled. With
11851 @code{AM_MAINTAINER_MODE([enable])}, they are enabled by default,
11852 otherwise they are disabled by default. In the latter case, if
11853 you have @code{AM_MAINTAINER_MODE} in @file{configure.ac}, and run
11854 @samp{./configure && make}, then @command{make} will *never* attempt to
11855 rebuild @file{configure}, @file{Makefile.in}s, Lex or Yacc outputs, etc.
11856 I.e., this disables build rules for files that are usually distributed
11857 and that users should normally not have to update.
11859 The user can override the default setting by passing either
11860 @samp{--enable-maintainer-mode} or @samp{--disable-maintainer-mode}
11861 to @command{configure}.
11863 People use @code{AM_MAINTAINER_MODE} either because they do not want their
11864 users (or themselves) annoyed by timestamps lossage (@pxref{CVS}), or
11865 because they simply can't stand the rebuild rules and prefer running
11866 maintainer tools explicitly.
11868 @code{AM_MAINTAINER_MODE} also allows you to disable some custom build
11869 rules conditionally. Some developers use this feature to disable
11870 rules that need exotic tools that users may not have available.
11872 Several years ago Fran@,{c}ois Pinard pointed out several arguments
11873 against this @code{AM_MAINTAINER_MODE} macro. Most of them relate to
11874 insecurity. By removing dependencies you get non-dependable builds:
11875 changes to sources files can have no effect on generated files and this
11876 can be very confusing when unnoticed. He adds that security shouldn't
11877 be reserved to maintainers (what @option{--enable-maintainer-mode}
11878 suggests), on the contrary. If one user has to modify a
11879 @file{Makefile.am}, then either @file{Makefile.in} should be updated
11880 or a warning should be output (this is what Automake uses
11881 @command{missing} for) but the last thing you want is that nothing
11882 happens and the user doesn't notice it (this is what happens when
11883 rebuild rules are disabled by @code{AM_MAINTAINER_MODE}).
11885 Jim Meyering, the inventor of the @code{AM_MAINTAINER_MODE} macro was
11886 swayed by Fran@,{c}ois's arguments, and got rid of
11887 @code{AM_MAINTAINER_MODE} in all of his packages.
11889 Still many people continue to use @code{AM_MAINTAINER_MODE}, because
11890 it helps them working on projects where all files are kept under version
11891 control, and because @command{missing} isn't enough if you have the
11892 wrong version of the tools.
11896 @section Why doesn't Automake support wildcards?
11899 Developers are lazy. They would often like to use wildcards in
11900 @file{Makefile.am}s, so that they would not need to remember to
11901 update @file{Makefile.am}s every time they add, delete, or rename
11904 There are several objections to this:
11907 When using CVS (or similar) developers need to remember they have to
11908 run @samp{cvs add} or @samp{cvs rm} anyway. Updating
11909 @file{Makefile.am} accordingly quickly becomes a reflex.
11911 Conversely, if your application doesn't compile
11912 because you forgot to add a file in @file{Makefile.am}, it will help
11913 you remember to @samp{cvs add} it.
11916 Using wildcards makes it easy to distribute files by mistake. For
11917 instance, some code a developer is experimenting with (a test case,
11918 say) that should not be part of the distribution.
11921 Using wildcards it's easy to omit some files by mistake. For
11922 instance, one developer creates a new file, uses it in many places,
11923 but forgets to commit it. Another developer then checks out the
11924 incomplete project and is able to run @samp{make dist} successfully,
11925 even though a file is missing. By listing files, @samp{make dist}
11926 @emph{will} complain.
11929 Wildcards are not portable to some non-GNU @command{make} implementations,
11930 e.g., NetBSD @command{make} will not expand globs such as @samp{*} in
11931 prerequisites of a target.
11934 Finally, it's really hard to @emph{forget} to add a file to
11935 @file{Makefile.am}: files that are not listed in @file{Makefile.am} are
11936 not compiled or installed, so you can't even test them.
11939 Still, these are philosophical objections, and as such you may disagree,
11940 or find enough value in wildcards to dismiss all of them. Before you
11941 start writing a patch against Automake to teach it about wildcards,
11942 let's see the main technical issue: portability.
11944 Although @samp{$(wildcard ...)} works with GNU @command{make}, it is
11945 not portable to other @command{make} implementations.
11947 The only way Automake could support @command{$(wildcard ...)} is by
11948 expending @command{$(wildcard ...)} when @command{automake} is run.
11949 The resulting @file{Makefile.in}s would be portable since they would
11950 list all files and not use @samp{$(wildcard ...)}. However that
11951 means developers would need to remember to run @command{automake} each
11952 time they add, delete, or rename files.
11954 Compared to editing @file{Makefile.am}, this is a very small gain. Sure,
11955 it's easier and faster to type @samp{automake; make} than to type
11956 @samp{emacs Makefile.am; make}. But nobody bothered enough to write a
11957 patch to add support for this syntax. Some people use scripts to
11958 generate file lists in @file{Makefile.am} or in separate
11959 @file{Makefile} fragments.
11961 Even if you don't care about portability, and are tempted to use
11962 @samp{$(wildcard ...)} anyway because you target only GNU Make, you
11963 should know there are many places where Automake needs to know exactly
11964 which files should be processed. As Automake doesn't know how to
11965 expand @samp{$(wildcard ...)}, you cannot use it in these places.
11966 @samp{$(wildcard ...)} is a black box comparable to @code{AC_SUBST}ed
11967 variables as far Automake is concerned.
11969 You can get warnings about @samp{$(wildcard ...}) constructs using the
11970 @option{-Wportability} flag.
11972 @node Limitations on File Names
11973 @section Limitations on File Names
11974 @cindex file names, limitations on
11976 Automake attempts to support all kinds of file names, even those that
11977 contain unusual characters or are unusually long. However, some
11978 limitations are imposed by the underlying operating system and tools.
11980 Most operating systems prohibit the use of the null byte in file
11981 names, and reserve @samp{/} as a directory separator. Also, they
11982 require that file names are properly encoded for the user's locale.
11983 Automake is subject to these limits.
11985 Portable packages should limit themselves to POSIX file
11986 names. These can contain ASCII letters and digits,
11987 @samp{_}, @samp{.}, and @samp{-}. File names consist of components
11988 separated by @samp{/}. File name components cannot begin with
11991 Portable POSIX file names cannot contain components that exceed a
11992 14-byte limit, but nowadays it's normally safe to assume the
11993 more-generous XOPEN limit of 255 bytes. POSIX
11994 limits file names to 255 bytes (XOPEN allows 1023 bytes),
11995 but you may want to limit a source tarball to file names of 99 bytes
11996 to avoid interoperability problems with old versions of @command{tar}.
11998 If you depart from these rules (e.g., by using non-ASCII
11999 characters in file names, or by using lengthy file names), your
12000 installers may have problems for reasons unrelated to Automake.
12001 However, if this does not concern you, you should know about the
12002 limitations imposed by Automake itself. These limitations are
12003 undesirable, but some of them seem to be inherent to underlying tools
12004 like Autoconf, Make, M4, and the shell. They fall into three
12005 categories: install directories, build directories, and file names.
12007 The following characters:
12010 @r{newline} " # $ ' `
12013 should not appear in the names of install directories. For example,
12014 the operand of @command{configure}'s @option{--prefix} option should
12015 not contain these characters.
12017 Build directories suffer the same limitations as install directories,
12018 and in addition should not contain the following characters:
12024 For example, the full name of the directory containing the source
12025 files should not contain these characters.
12027 Source and installation file names like @file{main.c} are limited even
12028 further: they should conform to the POSIX/XOPEN
12029 rules described above. In addition, if you plan to port to
12030 non-POSIX environments, you should avoid file names that
12031 differ only in case (e.g., @file{makefile} and @file{Makefile}).
12032 Nowadays it is no longer worth worrying about the 8.3 limits of
12035 @node distcleancheck
12036 @section Files left in build directory after distclean
12037 @cindex @code{distclean}, diagnostic
12038 @cindex @samp{make distclean}, diagnostic
12039 @cindex dependencies and distributed files
12041 @trindex distcleancheck
12043 This is a diagnostic you might encounter while running @samp{make
12046 As explained in @ref{Checking the Distribution}, @samp{make distcheck}
12047 attempts to build and check your package for errors like this one.
12049 @samp{make distcheck} will perform a @code{VPATH} build of your
12050 package (@pxref{VPATH Builds}), and then call @samp{make distclean}.
12051 Files left in the build directory after @samp{make distclean} has run
12052 are listed after this error.
12054 This diagnostic really covers two kinds of errors:
12058 files that are forgotten by distclean;
12060 distributed files that are erroneously rebuilt.
12063 The former left-over files are not distributed, so the fix is to mark
12064 them for cleaning (@pxref{Clean}), this is obvious and doesn't deserve
12067 The latter bug is not always easy to understand and fix, so let's
12068 proceed with an example. Suppose our package contains a program for
12069 which we want to build a man page using @command{help2man}. GNU
12070 @command{help2man} produces simple manual pages from the @option{--help}
12071 and @option{--version} output of other commands (@pxref{Top, , Overview,
12072 help2man, The Help2man Manual}). Because we don't want to force our
12073 users to install @command{help2man}, we decide to distribute the
12074 generated man page using the following setup.
12077 # This Makefile.am is bogus.
12079 foo_SOURCES = foo.c
12080 dist_man_MANS = foo.1
12082 foo.1: foo$(EXEEXT)
12083 help2man --output=foo.1 ./foo$(EXEEXT)
12086 This will effectively distribute the man page. However,
12087 @samp{make distcheck} will fail with:
12090 ERROR: files left in build directory after distclean:
12094 Why was @file{foo.1} rebuilt? Because although distributed,
12095 @file{foo.1} depends on a non-distributed built file:
12096 @file{foo$(EXEEXT)}. @file{foo$(EXEEXT)} is built by the user, so it
12097 will always appear to be newer than the distributed @file{foo.1}.
12099 @samp{make distcheck} caught an inconsistency in our package. Our
12100 intent was to distribute @file{foo.1} so users do not need to install
12101 @command{help2man}, however since this rule causes this file to be
12102 always rebuilt, users @emph{do} need @command{help2man}. Either we
12103 should ensure that @file{foo.1} is not rebuilt by users, or there is
12104 no point in distributing @file{foo.1}.
12106 More generally, the rule is that distributed files should never depend
12107 on non-distributed built files. If you distribute something
12108 generated, distribute its sources.
12110 One way to fix the above example, while still distributing
12111 @file{foo.1} is to not depend on @file{foo$(EXEEXT)}. For instance,
12112 assuming @command{foo --version} and @command{foo --help} do not
12113 change unless @file{foo.c} or @file{configure.ac} change, we could
12114 write the following @file{Makefile.am}:
12118 foo_SOURCES = foo.c
12119 dist_man_MANS = foo.1
12121 foo.1: foo.c $(top_srcdir)/configure.ac
12122 $(MAKE) $(AM_MAKEFLAGS) foo$(EXEEXT)
12123 help2man --output=foo.1 ./foo$(EXEEXT)
12126 This way, @file{foo.1} will not get rebuilt every time
12127 @file{foo$(EXEEXT)} changes. The @command{make} call makes sure
12128 @file{foo$(EXEEXT)} is up-to-date before @command{help2man}. Another
12129 way to ensure this would be to use separate directories for binaries
12130 and man pages, and set @code{SUBDIRS} so that binaries are built
12133 We could also decide not to distribute @file{foo.1}. In
12134 this case it's fine to have @file{foo.1} dependent upon
12135 @file{foo$(EXEEXT)}, since both will have to be rebuilt.
12136 However it would be impossible to build the package in a
12137 cross-compilation, because building @file{foo.1} involves
12138 an @emph{execution} of @file{foo$(EXEEXT)}.
12140 Another context where such errors are common is when distributed files
12141 are built by tools that are built by the package. The pattern is
12145 distributed-file: built-tools distributed-sources
12150 should be changed to
12153 distributed-file: distributed-sources
12154 $(MAKE) $(AM_MAKEFLAGS) built-tools
12159 or you could choose not to distribute @file{distributed-file}, if
12160 cross-compilation does not matter.
12162 The points made through these examples are worth a summary:
12167 Distributed files should never depend upon non-distributed built
12170 Distributed files should be distributed with all their dependencies.
12172 If a file is @emph{intended} to be rebuilt by users, then there is no point
12173 in distributing it.
12177 @vrindex distcleancheck_listfiles
12178 For desperate cases, it's always possible to disable this check by
12179 setting @code{distcleancheck_listfiles} as documented in @ref{Checking
12181 Make sure you do understand the reason why @samp{make distcheck}
12182 complains before you do this. @code{distcleancheck_listfiles} is a
12183 way to @emph{hide} errors, not to fix them. You can always do better.
12185 @node Flag Variables Ordering
12186 @section Flag Variables Ordering
12187 @cindex Ordering flag variables
12188 @cindex Flag variables, ordering
12191 What is the difference between @code{AM_CFLAGS}, @code{CFLAGS}, and
12192 @code{mumble_CFLAGS}?
12196 Why does @command{automake} output @code{CPPFLAGS} after
12197 @code{AM_CPPFLAGS} on compile lines? Shouldn't it be the converse?
12201 My @file{configure} adds some warning flags into @code{CXXFLAGS}. In
12202 one @file{Makefile.am} I would like to append a new flag, however if I
12203 put the flag into @code{AM_CXXFLAGS} it is prepended to the other
12204 flags, not appended.
12207 @subheading Compile Flag Variables
12208 @cindex Flag Variables, Ordering
12209 @cindex Compile Flag Variables
12210 @cindex @code{AM_CCASFLAGS} and @code{CCASFLAGS}
12211 @cindex @code{AM_CFLAGS} and @code{CFLAGS}
12212 @cindex @code{AM_CPPFLAGS} and @code{CPPFLAGS}
12213 @cindex @code{AM_CXXFLAGS} and @code{CXXFLAGS}
12214 @cindex @code{AM_FCFLAGS} and @code{FCFLAGS}
12215 @cindex @code{AM_FFLAGS} and @code{FFLAGS}
12216 @cindex @code{AM_GCJFLAGS} and @code{GCJFLAGS}
12217 @cindex @code{AM_LDFLAGS} and @code{LDFLAGS}
12218 @cindex @code{AM_LFLAGS} and @code{LFLAGS}
12219 @cindex @code{AM_LIBTOOLFLAGS} and @code{LIBTOOLFLAGS}
12220 @cindex @code{AM_OBJCFLAGS} and @code{OBJCFLAGS}
12221 @cindex @code{AM_RFLAGS} and @code{RFLAGS}
12222 @cindex @code{AM_UPCFLAGS} and @code{UPCFLAGS}
12223 @cindex @code{AM_YFLAGS} and @code{YFLAGS}
12224 @cindex @code{CCASFLAGS} and @code{AM_CCASFLAGS}
12225 @cindex @code{CFLAGS} and @code{AM_CFLAGS}
12226 @cindex @code{CPPFLAGS} and @code{AM_CPPFLAGS}
12227 @cindex @code{CXXFLAGS} and @code{AM_CXXFLAGS}
12228 @cindex @code{FCFLAGS} and @code{AM_FCFLAGS}
12229 @cindex @code{FFLAGS} and @code{AM_FFLAGS}
12230 @cindex @code{GCJFLAGS} and @code{AM_GCJFLAGS}
12231 @cindex @code{LDFLAGS} and @code{AM_LDFLAGS}
12232 @cindex @code{LFLAGS} and @code{AM_LFLAGS}
12233 @cindex @code{LIBTOOLFLAGS} and @code{AM_LIBTOOLFLAGS}
12234 @cindex @code{OBJCFLAGS} and @code{AM_OBJCFLAGS}
12235 @cindex @code{RFLAGS} and @code{AM_RFLAGS}
12236 @cindex @code{UPCFLAGS} and @code{AM_UPCFLAGS}
12237 @cindex @code{YFLAGS} and @code{AM_YFLAGS}
12239 This section attempts to answer all the above questions. We will
12240 mostly discuss @code{CPPFLAGS} in our examples, but actually the
12241 answer holds for all the compile flags used in Automake:
12242 @code{CCASFLAGS}, @code{CFLAGS}, @code{CPPFLAGS}, @code{CXXFLAGS},
12243 @code{FCFLAGS}, @code{FFLAGS}, @code{GCJFLAGS}, @code{LDFLAGS},
12244 @code{LFLAGS}, @code{LIBTOOLFLAGS}, @code{OBJCFLAGS}, @code{RFLAGS},
12245 @code{UPCFLAGS}, and @code{YFLAGS}.
12247 @code{CPPFLAGS}, @code{AM_CPPFLAGS}, and @code{mumble_CPPFLAGS} are
12248 three variables that can be used to pass flags to the C preprocessor
12249 (actually these variables are also used for other languages like C++
12250 or preprocessed Fortran). @code{CPPFLAGS} is the user variable
12251 (@pxref{User Variables}), @code{AM_CPPFLAGS} is the Automake variable,
12252 and @code{mumble_CPPFLAGS} is the variable specific to the
12253 @code{mumble} target (we call this a per-target variable,
12254 @pxref{Program and Library Variables}).
12256 Automake always uses two of these variables when compiling C sources
12257 files. When compiling an object file for the @code{mumble} target,
12258 the first variable will be @code{mumble_CPPFLAGS} if it is defined, or
12259 @code{AM_CPPFLAGS} otherwise. The second variable is always
12262 In the following example,
12265 bin_PROGRAMS = foo bar
12266 foo_SOURCES = xyz.c
12267 bar_SOURCES = main.c
12268 foo_CPPFLAGS = -DFOO
12269 AM_CPPFLAGS = -DBAZ
12273 @file{xyz.o} will be compiled with @samp{$(foo_CPPFLAGS) $(CPPFLAGS)},
12274 (because @file{xyz.o} is part of the @code{foo} target), while
12275 @file{main.o} will be compiled with @samp{$(AM_CPPFLAGS) $(CPPFLAGS)}
12276 (because there is no per-target variable for target @code{bar}).
12278 The difference between @code{mumble_CPPFLAGS} and @code{AM_CPPFLAGS}
12279 being clear enough, let's focus on @code{CPPFLAGS}. @code{CPPFLAGS}
12280 is a user variable, i.e., a variable that users are entitled to modify
12281 in order to compile the package. This variable, like many others,
12282 is documented at the end of the output of @samp{configure --help}.
12284 For instance, someone who needs to add @file{/home/my/usr/include} to
12285 the C compiler's search path would configure a package with
12288 ./configure CPPFLAGS='-I /home/my/usr/include'
12292 and this flag would be propagated to the compile rules of all
12295 It is also not uncommon to override a user variable at
12296 @command{make}-time. Many installers do this with @code{prefix}, but
12297 this can be useful with compiler flags too. For instance, if, while
12298 debugging a C++ project, you need to disable optimization in one
12299 specific object file, you can run something like
12303 make CXXFLAGS=-O0 file.o
12307 The reason @samp{$(CPPFLAGS)} appears after @samp{$(AM_CPPFLAGS)} or
12308 @samp{$(mumble_CPPFLAGS)} in the compile command is that users
12309 should always have the last say. It probably makes more sense if you
12310 think about it while looking at the @samp{CXXFLAGS=-O0} above, which
12311 should supersede any other switch from @code{AM_CXXFLAGS} or
12312 @code{mumble_CXXFLAGS} (and this of course replaces the previous value
12313 of @code{CXXFLAGS}).
12315 You should never redefine a user variable such as @code{CPPFLAGS} in
12316 @file{Makefile.am}. Use @samp{automake -Woverride} to diagnose such
12317 mistakes. Even something like
12320 CPPFLAGS = -DDATADIR=\"$(datadir)\" @@CPPFLAGS@@
12324 is erroneous. Although this preserves @file{configure}'s value of
12325 @code{CPPFLAGS}, the definition of @code{DATADIR} will disappear if a
12326 user attempts to override @code{CPPFLAGS} from the @command{make}
12330 AM_CPPFLAGS = -DDATADIR=\"$(datadir)\"
12334 is all that is needed here if no per-target flags are used.
12336 You should not add options to these user variables within
12337 @file{configure} either, for the same reason. Occasionally you need
12338 to modify these variables to perform a test, but you should reset
12339 their values afterwards. In contrast, it is OK to modify the
12340 @samp{AM_} variables within @file{configure} if you @code{AC_SUBST}
12341 them, but it is rather rare that you need to do this, unless you
12342 really want to change the default definitions of the @samp{AM_}
12343 variables in all @file{Makefile}s.
12345 What we recommend is that you define extra flags in separate
12346 variables. For instance, you may write an Autoconf macro that computes
12347 a set of warning options for the C compiler, and @code{AC_SUBST} them
12348 in @code{WARNINGCFLAGS}; you may also have an Autoconf macro that
12349 determines which compiler and which linker flags should be used to
12350 link with library @file{libfoo}, and @code{AC_SUBST} these in
12351 @code{LIBFOOCFLAGS} and @code{LIBFOOLDFLAGS}. Then, a
12352 @file{Makefile.am} could use these variables as follows:
12355 AM_CFLAGS = $(WARNINGCFLAGS)
12356 bin_PROGRAMS = prog1 prog2
12357 prog1_SOURCES = @dots{}
12358 prog2_SOURCES = @dots{}
12359 prog2_CFLAGS = $(LIBFOOCFLAGS) $(AM_CFLAGS)
12360 prog2_LDFLAGS = $(LIBFOOLDFLAGS)
12363 In this example both programs will be compiled with the flags
12364 substituted into @samp{$(WARNINGCFLAGS)}, and @code{prog2} will
12365 additionally be compiled with the flags required to link with
12368 Note that listing @code{AM_CFLAGS} in a per-target @code{CFLAGS}
12369 variable is a common idiom to ensure that @code{AM_CFLAGS} applies to
12370 every target in a @file{Makefile.in}.
12372 Using variables like this gives you full control over the ordering of
12373 the flags. For instance, if there is a flag in $(WARNINGCFLAGS) that
12374 you want to negate for a particular target, you can use something like
12375 @samp{prog1_CFLAGS = $(AM_CFLAGS) -no-flag}. If all these flags had
12376 been forcefully appended to @code{CFLAGS}, there would be no way to
12377 disable one flag. Yet another reason to leave user variables to
12380 Finally, we have avoided naming the variable of the example
12381 @code{LIBFOO_LDFLAGS} (with an underscore) because that would cause
12382 Automake to think that this is actually a per-target variable (like
12383 @code{mumble_LDFLAGS}) for some non-declared @code{LIBFOO} target.
12385 @subheading Other Variables
12387 There are other variables in Automake that follow similar principles
12388 to allow user options. For instance, Texinfo rules (@pxref{Texinfo})
12389 use @code{MAKEINFOFLAGS} and @code{AM_MAKEINFOFLAGS}. Similarly,
12390 DejaGnu tests (@pxref{DejaGnu Tests}) use @code{RUNTESTDEFAULTFLAGS} and
12391 @code{AM_RUNTESTDEFAULTFLAGS}. The tags and ctags rules
12392 (@pxref{Tags}) use @code{ETAGSFLAGS}, @code{AM_ETAGSFLAGS},
12393 @code{CTAGSFLAGS}, and @code{AM_CTAGSFLAGS}. Java rules
12394 (@pxref{Java}) use @code{JAVACFLAGS} and @code{AM_JAVACFLAGS}. None
12395 of these rules support per-target flags (yet).
12397 To some extent, even @code{AM_MAKEFLAGS} (@pxref{Subdirectories})
12398 obeys this naming scheme. The slight difference is that
12399 @code{MAKEFLAGS} is passed to sub-@command{make}s implicitly by
12400 @command{make} itself.
12402 However you should not think that all variables ending with
12403 @code{FLAGS} follow this convention. For instance,
12404 @code{DISTCHECK_CONFIGURE_FLAGS} (@pxref{Checking the Distribution}) and
12405 @code{ACLOCAL_AMFLAGS} (see @ref{Rebuilding} and @ref{Local Macros}),
12406 are two variables that are only useful to the maintainer and have no
12409 @code{ARFLAGS} (@pxref{A Library}) is usually defined by Automake and
12410 has neither @code{AM_} nor per-target cousin.
12412 Finally you should not think that the existence of a per-target
12413 variable implies the existance of an @code{AM_} variable or of a user
12414 variable. For instance, the @code{mumble_LDADD} per-target variable
12415 overrides the makefile-wide @code{LDADD} variable (which is not a user
12416 variable), and @code{mumble_LIBADD} exists only as a per-target
12417 variable. @xref{Program and Library Variables}.
12420 @node Renamed Objects
12421 @section Why are object files sometimes renamed?
12423 This happens when per-target compilation flags are used. Object
12424 files need to be renamed just in case they would clash with object
12425 files compiled from the same sources, but with different flags.
12426 Consider the following example.
12429 bin_PROGRAMS = true false
12430 true_SOURCES = generic.c
12431 true_CPPFLAGS = -DEXIT_CODE=0
12432 false_SOURCES = generic.c
12433 false_CPPFLAGS = -DEXIT_CODE=1
12437 Obviously the two programs are built from the same source, but it
12438 would be bad if they shared the same object, because @file{generic.o}
12439 cannot be built with both @samp{-DEXIT_CODE=0} @emph{and}
12440 @samp{-DEXIT_CODE=1}. Therefore @command{automake} outputs rules to
12441 build two different objects: @file{true-generic.o} and
12442 @file{false-generic.o}.
12444 @command{automake} doesn't actually look whether source files are
12445 shared to decide if it must rename objects. It will just rename all
12446 objects of a target as soon as it sees per-target compilation flags
12449 It's OK to share object files when per-target compilation flags are not
12450 used. For instance, @file{true} and @file{false} will both use
12451 @file{version.o} in the following example.
12454 AM_CPPFLAGS = -DVERSION=1.0
12455 bin_PROGRAMS = true false
12456 true_SOURCES = true.c version.c
12457 false_SOURCES = false.c version.c
12460 Note that the renaming of objects is also affected by the
12461 @code{_SHORTNAME} variable (@pxref{Program and Library Variables}).
12464 @node Per-Object Flags
12465 @section Per-Object Flags Emulation
12466 @cindex Per-object flags, emulated
12469 One of my source files needs to be compiled with different flags. How
12473 Automake supports per-program and per-library compilation flags (see
12474 @ref{Program and Library Variables} and @ref{Flag Variables
12475 Ordering}). With this you can define compilation flags that apply to
12476 all files compiled for a target. For instance, in
12480 foo_SOURCES = foo.c foo.h bar.c bar.h main.c
12481 foo_CFLAGS = -some -flags
12485 @file{foo-foo.o}, @file{foo-bar.o}, and @file{foo-main.o} will all be
12486 compiled with @samp{-some -flags}. (If you wonder about the names of
12487 these object files, see @ref{Renamed Objects}.) Note that
12488 @code{foo_CFLAGS} gives the flags to use when compiling all the C
12489 sources of the @emph{program} @code{foo}, it has nothing to do with
12490 @file{foo.c} or @file{foo-foo.o} specifically.
12492 What if @file{foo.c} needs to be compiled into @file{foo.o} using some
12493 specific flags, that none of the other files requires? Obviously
12494 per-program flags are not directly applicable here. Something like
12495 per-object flags are expected, i.e., flags that would be used only
12496 when creating @file{foo-foo.o}. Automake does not support that,
12497 however this is easy to simulate using a library that contains only
12498 that object, and compiling this library with per-library flags.
12502 foo_SOURCES = bar.c bar.h main.c
12503 foo_CFLAGS = -some -flags
12504 foo_LDADD = libfoo.a
12505 noinst_LIBRARIES = libfoo.a
12506 libfoo_a_SOURCES = foo.c foo.h
12507 libfoo_a_CFLAGS = -some -other -flags
12510 Here @file{foo-bar.o} and @file{foo-main.o} will all be
12511 compiled with @samp{-some -flags}, while @file{libfoo_a-foo.o} will
12512 be compiled using @samp{-some -other -flags}. Eventually, all
12513 three objects will be linked to form @file{foo}.
12515 This trick can also be achieved using Libtool convenience libraries,
12516 for instance @samp{noinst_LTLIBRARIES = libfoo.la} (@pxref{Libtool
12517 Convenience Libraries}).
12519 Another tempting idea to implement per-object flags is to override the
12520 compile rules @command{automake} would output for these files.
12521 Automake will not define a rule for a target you have defined, so you
12522 could think about defining the @samp{foo-foo.o: foo.c} rule yourself.
12523 We recommend against this, because this is error prone. For instance,
12524 if you add such a rule to the first example, it will break the day you
12525 decide to remove @code{foo_CFLAGS} (because @file{foo.c} will then be
12526 compiled as @file{foo.o} instead of @file{foo-foo.o}, @pxref{Renamed
12527 Objects}). Also in order to support dependency tracking, the two
12528 @file{.o}/@file{.obj} extensions, and all the other flags variables
12529 involved in a compilation, you will end up modifying a copy of the
12530 rule previously output by @command{automake} for this file. If a new
12531 release of Automake generates a different rule, your copy will need to
12532 be updated by hand.
12534 @node Multiple Outputs
12535 @section Handling Tools that Produce Many Outputs
12536 @cindex multiple outputs, rules with
12537 @cindex many outputs, rules with
12538 @cindex rules with multiple outputs
12540 This section describes a @command{make} idiom that can be used when a
12541 tool produces multiple output files. It is not specific to Automake
12542 and can be used in ordinary @file{Makefile}s.
12544 Suppose we have a program called @command{foo} that will read one file
12545 called @file{data.foo} and produce two files named @file{data.c} and
12546 @file{data.h}. We want to write a @file{Makefile} rule that captures
12547 this one-to-two dependency.
12549 The naive rule is incorrect:
12552 # This is incorrect.
12553 data.c data.h: data.foo
12558 What the above rule really says is that @file{data.c} and
12559 @file{data.h} each depend on @file{data.foo}, and can each be built by
12560 running @samp{foo data.foo}. In other words it is equivalent to:
12563 # We do not want this.
12571 which means that @command{foo} can be run twice. Usually it will not
12572 be run twice, because @command{make} implementations are smart enough
12573 to check for the existence of the second file after the first one has
12574 been built; they will therefore detect that it already exists.
12575 However there are a few situations where it can run twice anyway:
12579 The most worrying case is when running a parallel @command{make}. If
12580 @file{data.c} and @file{data.h} are built in parallel, two @samp{foo
12581 data.foo} commands will run concurrently. This is harmful.
12583 Another case is when the dependency (here @file{data.foo}) is
12584 (or depends upon) a phony target.
12587 A solution that works with parallel @command{make} but not with
12588 phony dependencies is the following:
12591 data.c data.h: data.foo
12597 The above rules are equivalent to
12602 data.h: data.foo data.c
12607 therefore a parallel @command{make} will have to serialize the builds
12608 of @file{data.c} and @file{data.h}, and will detect that the second is
12609 no longer needed once the first is over.
12611 Using this pattern is probably enough for most cases. However it does
12612 not scale easily to more output files (in this scheme all output files
12613 must be totally ordered by the dependency relation), so we will
12614 explore a more complicated solution.
12616 Another idea is to write the following:
12619 # There is still a problem with this one.
12626 The idea is that @samp{foo data.foo} is run only when @file{data.c}
12627 needs to be updated, but we further state that @file{data.h} depends
12628 upon @file{data.c}. That way, if @file{data.h} is required and
12629 @file{data.foo} is out of date, the dependency on @file{data.c} will
12632 This is almost perfect, but suppose we have built @file{data.h} and
12633 @file{data.c}, and then we erase @file{data.h}. Then, running
12634 @samp{make data.h} will not rebuild @file{data.h}. The above rules
12635 just state that @file{data.c} must be up-to-date with respect to
12636 @file{data.foo}, and this is already the case.
12638 What we need is a rule that forces a rebuild when @file{data.h} is
12639 missing. Here it is:
12645 ## Recover from the removal of $@@
12646 @@if test -f $@@; then :; else \
12648 $(MAKE) $(AM_MAKEFLAGS) data.c; \
12652 The above scheme can be extended to handle more outputs and more
12653 inputs. One of the outputs is selected to serve as a witness to the
12654 successful completion of the command, it depends upon all inputs, and
12655 all other outputs depend upon it. For instance, if @command{foo}
12656 should additionally read @file{data.bar} and also produce
12657 @file{data.w} and @file{data.x}, we would write:
12660 data.c: data.foo data.bar
12661 foo data.foo data.bar
12662 data.h data.w data.x: data.c
12663 ## Recover from the removal of $@@
12664 @@if test -f $@@; then :; else \
12666 $(MAKE) $(AM_MAKEFLAGS) data.c; \
12670 However there are now three minor problems in this setup. One is related
12671 to the timestamp ordering of @file{data.h}, @file{data.w},
12672 @file{data.x}, and @file{data.c}. Another one is a race condition
12673 if a parallel @command{make} attempts to run multiple instances of the
12674 recover block at once. Finally, the recursive rule breaks @samp{make -n}
12675 when run with GNU @command{make} (as well as some other @command{make}
12676 implementations), as it may remove @file{data.h} even when it should not
12677 (@pxref{MAKE Variable, , How the @code{MAKE} Variable Works, make,
12678 The GNU Make Manual}).
12680 Let us deal with the first problem. @command{foo} outputs four files,
12681 but we do not know in which order these files are created. Suppose
12682 that @file{data.h} is created before @file{data.c}. Then we have a
12683 weird situation. The next time @command{make} is run, @file{data.h}
12684 will appear older than @file{data.c}, the second rule will be
12685 triggered, a shell will be started to execute the @samp{if@dots{}fi}
12686 command, but actually it will just execute the @code{then} branch,
12687 that is: nothing. In other words, because the witness we selected is
12688 not the first file created by @command{foo}, @command{make} will start
12689 a shell to do nothing each time it is run.
12691 A simple riposte is to fix the timestamps when this happens.
12694 data.c: data.foo data.bar
12695 foo data.foo data.bar
12696 data.h data.w data.x: data.c
12697 @@if test -f $@@; then \
12700 ## Recover from the removal of $@@
12702 $(MAKE) $(AM_MAKEFLAGS) data.c; \
12706 Another solution is to use a different and dedicated file as witness,
12707 rather than using any of @command{foo}'s outputs.
12710 data.stamp: data.foo data.bar
12713 foo data.foo data.bar
12714 @@mv -f data.tmp $@@
12715 data.c data.h data.w data.x: data.stamp
12716 ## Recover from the removal of $@@
12717 @@if test -f $@@; then :; else \
12718 rm -f data.stamp; \
12719 $(MAKE) $(AM_MAKEFLAGS) data.stamp; \
12723 @file{data.tmp} is created before @command{foo} is run, so it has a
12724 timestamp older than output files output by @command{foo}. It is then
12725 renamed to @file{data.stamp} after @command{foo} has run, because we
12726 do not want to update @file{data.stamp} if @command{foo} fails.
12728 This solution still suffers from the second problem: the race
12729 condition in the recover rule. If, after a successful build, a user
12730 erases @file{data.c} and @file{data.h}, and runs @samp{make -j}, then
12731 @command{make} may start both recover rules in parallel. If the two
12732 instances of the rule execute @samp{$(MAKE) $(AM_MAKEFLAGS)
12733 data.stamp} concurrently the build is likely to fail (for instance, the
12734 two rules will create @file{data.tmp}, but only one can rename it).
12736 Admittedly, such a weird situation does not arise during ordinary
12737 builds. It occurs only when the build tree is mutilated. Here
12738 @file{data.c} and @file{data.h} have been explicitly removed without
12739 also removing @file{data.stamp} and the other output files.
12740 @code{make clean; make} will always recover from these situations even
12741 with parallel makes, so you may decide that the recover rule is solely
12742 to help non-parallel make users and leave things as-is. Fixing this
12743 requires some locking mechanism to ensure only one instance of the
12744 recover rule rebuilds @file{data.stamp}. One could imagine something
12745 along the following lines.
12748 data.c data.h data.w data.x: data.stamp
12749 ## Recover from the removal of $@@
12750 @@if test -f $@@; then :; else \
12751 trap 'rm -rf data.lock data.stamp' 1 2 13 15; \
12752 ## mkdir is a portable test-and-set
12753 if mkdir data.lock 2>/dev/null; then \
12754 ## This code is being executed by the first process.
12755 rm -f data.stamp; \
12756 $(MAKE) $(AM_MAKEFLAGS) data.stamp; \
12757 result=$$?; rm -rf data.lock; exit $$result; \
12759 ## This code is being executed by the follower processes.
12760 ## Wait until the first process is done.
12761 while test -d data.lock; do sleep 1; done; \
12762 ## Succeed if and only if the first process succeeded.
12763 test -f data.stamp; \
12768 Using a dedicated witness, like @file{data.stamp}, is very handy when
12769 the list of output files is not known beforehand. As an illustration,
12770 consider the following rules to compile many @file{*.el} files into
12771 @file{*.elc} files in a single command. It does not matter how
12772 @code{ELFILES} is defined (as long as it is not empty: empty targets
12773 are not accepted by POSIX).
12776 ELFILES = one.el two.el three.el @dots{}
12777 ELCFILES = $(ELFILES:=c)
12779 elc-stamp: $(ELFILES)
12782 $(elisp_comp) $(ELFILES)
12783 @@mv -f elc-temp $@@
12785 $(ELCFILES): elc-stamp
12786 @@if test -f $@@; then :; else \
12787 ## Recover from the removal of $@@
12788 trap 'rm -rf elc-lock elc-stamp' 1 2 13 15; \
12789 if mkdir elc-lock 2>/dev/null; then \
12790 ## This code is being executed by the first process.
12792 $(MAKE) $(AM_MAKEFLAGS) elc-stamp; \
12795 ## This code is being executed by the follower processes.
12796 ## Wait until the first process is done.
12797 while test -d elc-lock; do sleep 1; done; \
12798 ## Succeed if and only if the first process succeeded.
12799 test -f elc-stamp; exit $$?; \
12805 These solutions all still suffer from the third problem, namely that
12806 they break the promise that @samp{make -n} should not cause any actual
12807 changes to the tree. For those solutions that do not create lock files,
12808 it is possible to split the recover rules into two separate recipe
12809 commands, one of which does all work but the recursion, and the
12810 other invokes the recursive @samp{$(MAKE)}. The solutions involving
12811 locking could act upon the contents of the @samp{MAKEFLAGS} variable,
12812 but parsing that portably is not easy (@pxref{The Make Macro MAKEFLAGS,,,
12813 autoconf, The Autoconf Manual}). Here is an example:
12816 ELFILES = one.el two.el three.el @dots{}
12817 ELCFILES = $(ELFILES:=c)
12819 elc-stamp: $(ELFILES)
12822 $(elisp_comp) $(ELFILES)
12823 @@mv -f elc-temp $@@
12825 $(ELCFILES): elc-stamp
12826 ## Recover from the removal of $@@
12827 @@dry=; for f in x $$MAKEFLAGS; do \
12833 if test -f $@@; then :; else \
12834 $$dry trap 'rm -rf elc-lock elc-stamp' 1 2 13 15; \
12835 if $$dry mkdir elc-lock 2>/dev/null; then \
12836 ## This code is being executed by the first process.
12837 $$dry rm -f elc-stamp; \
12838 $(MAKE) $(AM_MAKEFLAGS) elc-stamp; \
12839 $$dry rmdir elc-lock; \
12841 ## This code is being executed by the follower processes.
12842 ## Wait until the first process is done.
12843 while test -d elc-lock && test -z "$$dry"; do \
12847 ## Succeed if and only if the first process succeeded.
12848 $$dry test -f elc-stamp; exit $$?; \
12853 For completeness it should be noted that GNU @command{make} is able to
12854 express rules with multiple output files using pattern rules
12855 (@pxref{Pattern Examples, , Pattern Rule Examples, make, The GNU Make
12856 Manual}). We do not discuss pattern rules here because they are not
12857 portable, but they can be convenient in packages that assume GNU
12861 @node Hard-Coded Install Paths
12862 @section Installing to Hard-Coded Locations
12865 My package needs to install some configuration file. I tried to use
12866 the following rule, but @samp{make distcheck} fails. Why?
12870 install-data-local:
12871 $(INSTALL_DATA) $(srcdir)/afile $(DESTDIR)/etc/afile
12876 My package needs to populate the installation directory of another
12877 package at install-time. I can easily compute that installation
12878 directory in @file{configure}, but if I install files therein,
12879 @samp{make distcheck} fails. How else should I do?
12882 These two setups share their symptoms: @samp{make distcheck} fails
12883 because they are installing files to hard-coded paths. In the later
12884 case the path is not really hard-coded in the package, but we can
12885 consider it to be hard-coded in the system (or in whichever tool that
12886 supplies the path). As long as the path does not use any of the
12887 standard directory variables (@samp{$(prefix)}, @samp{$(bindir)},
12888 @samp{$(datadir)}, etc.), the effect will be the same:
12889 user-installations are impossible.
12891 As a (non-root) user who wants to install a package, you usually have no
12892 right to install anything in @file{/usr} or @file{/usr/local}. So you
12893 do something like @samp{./configure --prefix ~/usr} to install a
12894 package in your own @file{~/usr} tree.
12896 If a package attempts to install something to some hard-coded path
12897 (e.g., @file{/etc/afile}), regardless of this @option{--prefix} setting,
12898 then the installation will fail. @samp{make distcheck} performs such
12899 a @option{--prefix} installation, hence it will fail too.
12901 Now, there are some easy solutions.
12903 The above @code{install-data-local} example for installing
12904 @file{/etc/afile} would be better replaced by
12907 sysconf_DATA = afile
12911 by default @code{sysconfdir} will be @samp{$(prefix)/etc}, because
12912 this is what the GNU Standards require. When such a package is
12913 installed on an FHS compliant system, the installer will have to set
12914 @samp{--sysconfdir=/etc}. As the maintainer of the package you
12915 should not be concerned by such site policies: use the appropriate
12916 standard directory variable to install your files so that the installer
12917 can easily redefine these variables to match their site conventions.
12919 Installing files that should be used by another package is slightly
12920 more involved. Let's take an example and assume you want to install
12921 a shared library that is a Python extension module. If you ask Python
12922 where to install the library, it will answer something like this:
12925 % @kbd{python -c 'from distutils import sysconfig;
12926 print sysconfig.get_python_lib(1,0)'}
12927 /usr/lib/python2.5/site-packages
12930 If you indeed use this absolute path to install your shared library,
12931 non-root users will not be able to install the package, hence
12934 Let's do better. The @samp{sysconfig.get_python_lib()} function
12935 actually accepts a third argument that will replace Python's
12936 installation prefix.
12939 % @kbd{python -c 'from distutils import sysconfig;
12940 print sysconfig.get_python_lib(1,0,"$@{exec_prefix@}")'}
12941 $@{exec_prefix@}/lib/python2.5/site-packages
12944 You can also use this new path. If you do
12947 root users can install your package with the same @option{--prefix}
12948 as Python (you get the behavior of the previous attempt)
12951 non-root users can install your package too, they will have the
12952 extension module in a place that is not searched by Python but they
12953 can work around this using environment variables (and if you installed
12954 scripts that use this shared library, it's easy to tell Python were to
12955 look in the beginning of your script, so the script works in both
12959 The @code{AM_PATH_PYTHON} macro uses similar commands to define
12960 @samp{$(pythondir)} and @samp{$(pyexecdir)} (@pxref{Python}).
12962 Of course not all tools are as advanced as Python regarding that
12963 substitution of @var{prefix}. So another strategy is to figure the
12964 part of the installation directory that must be preserved. For
12965 instance, here is how @code{AM_PATH_LISPDIR} (@pxref{Emacs Lisp})
12966 computes @samp{$(lispdir)}:
12969 $EMACS -batch -q -eval '(while load-path
12970 (princ (concat (car load-path) "\n"))
12971 (setq load-path (cdr load-path)))' >conftest.out
12974 -e '/.*\/lib\/x*emacs\/site-lisp$/@{
12975 s,.*/lib/\(x*emacs/site-lisp\)$,$@{libdir@}/\1,;p;q;
12977 -e '/.*\/share\/x*emacs\/site-lisp$/@{
12978 s,.*/share/\(x*emacs/site-lisp\),$@{datarootdir@}/\1,;p;q;
12983 I.e., it just picks the first directory that looks like
12984 @file{*/lib/*emacs/site-lisp} or @file{*/share/*emacs/site-lisp} in
12985 the search path of emacs, and then substitutes @samp{$@{libdir@}} or
12986 @samp{$@{datadir@}} appropriately.
12988 The emacs case looks complicated because it processes a list and
12989 expects two possible layouts, otherwise it's easy, and the benefits for
12990 non-root users are really worth the extra @command{sed} invocation.
12993 @node Debugging Make Rules
12994 @section Debugging Make Rules
12995 @cindex debugging rules
12996 @cindex rules, debugging
12998 The rules and dependency trees generated by @command{automake} can get
12999 rather complex, and leave the developer head-scratching when things
13000 don't work as expected. Besides the debug options provided by the
13001 @command{make} command (@pxref{Options Summary,,, make, The GNU Make
13002 Manual}), here's a couple of further hints for debugging makefiles
13003 generated by @command{automake} effectively:
13007 If less verbose output has been enabled in the package with the
13008 @samp{silent-rules} option (@pxref{Options}), you can use
13009 @code{make V=1} to see the commands being executed.
13011 @code{make -n} can help show what would be done without actually doing
13012 it. Note however, that this will @emph{still execute} commands prefixed
13013 with @samp{+}, and, when using GNU @command{make}, commands that contain
13014 the strings @samp{$(MAKE)} or @samp{$@{MAKE@}} (@pxref{Instead of
13015 Execution,,, make, The GNU Make Manual}).
13016 Typically, this is helpful to show what recursive rules would do, but it
13017 means that, in your own rules, you should not mix such recursion with
13018 actions that change any files.@footnote{Automake's @samp{dist} and
13019 @samp{distcheck} rules had a bug in this regard in that they created
13020 directories even with @option{-n}, but this has been fixed in Automake
13021 1.11.} Furthermore, note that GNU @command{make} will update
13022 prerequisites for the @file{Makefile} file itself even with @option{-n}
13023 (@pxref{Remaking Makefiles,,, make, The GNU Make Manual}).
13025 @code{make SHELL="/bin/bash -vx"} can help debug complex rules.
13026 @xref{The Make Macro SHELL,,, autoconf, The Autoconf Manual}, for some
13027 portability quirks associated with this construct.
13029 @code{echo 'print: ; @@echo "$(VAR)"' | make -f Makefile -f - print}
13030 can be handy to examine the expanded value of variables. You may need
13031 to use a target other than @samp{print} if that is already used or a
13032 file with that name exists.
13034 @url{http://bashdb.sourceforge.net/@/remake/} provides a modified
13035 GNU @command{make} command called @command{remake} that copes with
13036 complex GNU @command{make}-specific Makefiles and allows to trace
13037 execution, examine variables, and call rules interactively, much like
13042 @node Reporting Bugs
13043 @section Reporting Bugs
13045 Most nontrivial software has bugs. Automake is no exception. Although
13046 we cannot promise we can or will fix a bug, and we might not even agree
13047 that it is a bug, we want to hear about problems you encounter. Often we
13048 agree they are bugs and want to fix them.
13050 To make it possible for us to fix a bug, please report it. In order to
13051 do so effectively, it helps to know when and how to do it.
13053 Before reporting a bug, it is a good idea to see if it is already known.
13054 You can look at the @uref{http://debbugs.gnu.org/, GNU Bug Tracker}
13055 and the @uref{http://lists.gnu.org/@/archive/@/html/@/bug-automake/,
13056 bug-automake mailing list archives} for previous bug reports. We
13058 @uref{http://sourceware.org/@/cgi-bin/@/gnatsweb.pl?database=automake,
13059 Gnats database} for bug tracking, so some bugs might have been reported
13060 there already. Please do not use it for new bug reports, however.
13062 If the bug is not already known, it should be reported. It is very
13063 important to report bugs in a way that is useful and efficient. For
13064 this, please familiarize yourself with
13065 @uref{http://www.chiark.greenend.org.uk/@/~sgtatham/@/bugs.html, How to
13066 Report Bugs Effectively} and
13067 @uref{http://catb.org/@/~esr/@/faqs/@/smart-questions.html, How to Ask
13068 Questions the Smart Way}. This helps you and developers to save time
13069 which can then be spent on fixing more bugs and implementing more
13072 For a bug report, a feature request or other suggestions, please send
13073 email to @email{@value{PACKAGE_BUGREPORT}}. This will then open a new
13074 bug in the @uref{http://debbugs.gnu.org/@/automake, bug tracker}. Be
13075 sure to include the versions of Autoconf and Automake that you use.
13076 Ideally, post a minimal @file{Makefile.am} and @file{configure.ac} that
13077 reproduces the problem you encounter. If you have encountered test
13078 suite failures, please attach the @file{tests/test-suite.log} file.
13082 @chapter History of Automake
13084 This chapter presents various aspects of the history of Automake. The
13085 exhausted reader can safely skip it; this will be more of interest to
13086 nostalgic people, or to those curious to learn about the evolution of
13090 * Timeline:: The Automake story.
13091 * Dependency Tracking Evolution:: Evolution of Automatic Dependency Tracking
13092 * Releases:: Statistics about Automake Releases
13099 @item 1994-09-19 First CVS commit.
13101 If we can trust the CVS repository, David J.@tie{}MacKenzie (djm) started
13102 working on Automake (or AutoMake, as it was spelt then) this Monday.
13104 The first version of the @command{automake} script looks as follows.
13113 if test ! -f $@{makefile@}.am; then
13114 echo "automake: $@{makefile@}.am: No such honkin' file"
13119 exec 4> $@{makefile@}.in
13124 From this you can already see that Automake will be about reading
13125 @file{*.am} file and producing @file{*.in} files. You cannot see
13126 anything else, but if you also know that David is the one who created
13127 Autoconf two years before you can guess the rest.
13129 Several commits follow, and by the end of the day Automake is
13130 reported to work for GNU fileutils and GNU m4.
13132 The modus operandi is the one that is still used today: variable
13133 assignments in @file{Makefile.am} files trigger injections of
13134 precanned @file{Makefile} fragments into the generated
13135 @file{Makefile.in}. The use of @file{Makefile} fragments was inspired
13136 by the 4.4BSD @command{make} and include files, however Automake aims
13137 to be portable and to conform to the GNU standards for @file{Makefile}
13138 variables and targets.
13140 At this point, the most recent release of Autoconf is version 1.11,
13141 and David is preparing to release Autoconf 2.0 in late October. As a
13142 matter of fact, he will barely touch Automake after September.
13144 @item 1994-11-05 David MacKenzie's last commit.
13146 At this point Automake is a 200 line portable shell script, plus 332
13147 lines of @file{Makefile} fragments. In the @file{README}, David
13148 states his ambivalence between ``portable shell'' and ``more
13149 appropriate language'':
13152 I wrote it keeping in mind the possibility of it becoming an Autoconf
13153 macro, so it would run at configure-time. That would slow
13154 configuration down a bit, but allow users to modify the Makefile.am
13155 without needing to fetch the AutoMake package. And, the Makefile.in
13156 files wouldn't need to be distributed. But all of AutoMake would. So
13157 I might reimplement AutoMake in Perl, m4, or some other more
13158 appropriate language.
13161 Automake is described as ``an experimental Makefile generator''.
13162 There is no documentation. Adventurous users are referred to the
13163 examples and patches needed to use Automake with GNU m4 1.3, fileutils
13164 3.9, time 1.6, and development versions of find and indent.
13166 These examples seem to have been lost. However at the time of writing
13167 (10 years later in September, 2004) the FSF still distributes a
13168 package that uses this version of Automake: check out GNU termutils
13171 @item 1995-11-12 Tom Tromey's first commit.
13173 After one year of inactivity, Tom Tromey takes over the package.
13174 Tom was working on GNU cpio back then, and doing this just for fun,
13175 having trouble finding a project to contribute to. So while hacking
13176 he wanted to bring the @file{Makefile.in} up to GNU standards. This
13177 was hard, and one day he saw Automake on @url{ftp://alpha.gnu.org/},
13178 grabbed it and tried it out.
13180 Tom didn't talk to djm about it until later, just to make sure he
13181 didn't mind if he made a release. He did a bunch of early releases to
13184 Gnits was (and still is) totally informal, just a few GNU friends who
13185 Fran@,cois Pinard knew, who were all interested in making a common
13186 infrastructure for GNU projects, and shared a similar outlook on how
13187 to do it. So they were able to make some progress. It came along
13188 with Autoconf and extensions thereof, and then Automake from David and
13189 Tom (who were both gnitsians). One of their ideas was to write a
13190 document paralleling the GNU standards, that was more strict in some
13191 ways and more detailed. They never finished the GNITS standards, but
13192 the ideas mostly made their way into Automake.
13194 @item 1995-11-23 Automake 0.20
13196 Besides introducing automatic dependency tracking (@pxref{Dependency
13197 Tracking Evolution}), this version also supplies a 9-page manual.
13199 At this time @command{aclocal} and @code{AM_INIT_AUTOMAKE} did not
13200 exist, so many things had to be done by hand. For instance, here is
13201 what a configure.in (this is the former name of the
13202 @file{configure.ac} we use today) must contain in order to use
13208 AC_DEFINE_UNQUOTED(PACKAGE, "$PACKAGE")
13209 AC_DEFINE_UNQUOTED(VERSION, "$VERSION")
13216 (Today all of the above is achieved by @code{AC_INIT} and
13217 @code{AM_INIT_AUTOMAKE}.)
13219 Here is how programs are specified in @file{Makefile.am}:
13223 hello_SOURCES = hello.c
13226 This looks pretty much like what we do today, except the
13227 @code{PROGRAMS} variable has no directory prefix specifying where
13228 @file{hello} should be installed: all programs are installed in
13229 @samp{$(bindir)}. @code{LIBPROGRAMS} can be used to specify programs
13230 that must be built but not installed (it is called
13231 @code{noinst_PROGRAMS} nowadays).
13233 Programs can be built conditionally using @code{AC_SUBST}itutions:
13236 PROGRAMS = @@progs@@
13237 AM_PROGRAMS = foo bar baz
13240 (@code{AM_PROGRAMS} has since then been renamed to
13241 @code{EXTRA_PROGRAMS}.)
13243 Similarly scripts, static libraries, and data can be built and installed
13244 using the @code{LIBRARIES}, @code{SCRIPTS}, and @code{DATA} variables.
13245 However @code{LIBRARIES} were treated a bit specially in that Automake
13246 did automatically supply the @file{lib} and @file{.a} prefixes.
13247 Therefore to build @file{libcpio.a}, one had to write
13254 Extra files to distribute must be listed in @code{DIST_OTHER} (the
13255 ancestor of @code{EXTRA_DIST}). Also extra directories that are to be
13256 distributed should appear in @code{DIST_SUBDIRS}, but the manual
13257 describes this as a temporary ugly hack (today extra directories should
13258 also be listed in @code{EXTRA_DIST}, and @code{DIST_SUBDIRS} is used
13259 for another purpose, @pxref{Conditional Subdirectories}).
13261 @item 1995-11-26 Automake 0.21
13263 In less time than it takes to cook a frozen pizza, Tom rewrites
13264 Automake using Perl. At this time Perl 5 is only one year old, and
13265 Perl 4.036 is in use at many sites. Supporting several Perl versions
13266 has been a source of problems through the whole history of Automake.
13268 If you never used Perl 4, imagine Perl 5 without objects, without
13269 @samp{my} variables (only dynamically scoped @samp{local} variables),
13270 without function prototypes, with function calls that needs to be
13271 prefixed with @samp{&}, etc. Traces of this old style can still be
13272 found in today's @command{automake}.
13274 @item 1995-11-28 Automake 0.22
13275 @itemx 1995-11-29 Automake 0.23
13279 @item 1995-12-08 Automake 0.24
13280 @itemx 1995-12-10 Automake 0.25
13282 Releases are raining. 0.24 introduces the uniform naming scheme we
13283 use today, i.e., @code{bin_PROGRAMS} instead of @code{PROGRAMS},
13284 @code{noinst_LIBRARIES} instead of @code{LIBLIBRARIES}, etc. (However
13285 @code{EXTRA_PROGRAMS} does not exist yet, @code{AM_PROGRAMS} is still
13286 in use; and @code{TEXINFOS} and @code{MANS} still have no directory
13287 prefixes.) Adding support for prefixes like that was one of the major
13288 ideas in @command{automake}; it has lasted pretty well.
13290 AutoMake is renamed to Automake (Tom seems to recall it was Fran@,cois
13293 0.25 fixes a Perl 4 portability bug.
13295 @item 1995-12-18 Jim Meyering starts using Automake in GNU Textutils.
13296 @item 1995-12-31 Fran@,cois Pinard starts using Automake in GNU tar.
13298 @item 1996-01-03 Automake 0.26
13299 @itemx 1996-01-03 Automake 0.27
13301 Of the many changes and suggestions sent by Fran@,cois Pinard and
13302 included in 0.26, perhaps the most important is the advice that to
13303 ease customization a user rule or variable definition should always
13304 override an Automake rule or definition.
13306 Gordon Matzigkeit and Jim Meyering are two other early contributors
13307 that have been sending fixes.
13309 0.27 fixes yet another Perl 4 portability bug.
13311 @item 1996-01-13 Automake 0.28
13313 Automake starts scanning @file{configure.in} for @code{LIBOBJS}
13314 support. This is an important step because until this version
13315 Automake only knew about the @file{Makefile.am}s it processed.
13316 @file{configure.in} was Autoconf's world and the link between Autoconf
13317 and Automake had to be done by the @file{Makefile.am} author. For
13318 instance, if @file{config.h} was generated by @file{configure}, it was the
13319 package maintainer's responsibility to define the @code{CONFIG_HEADER}
13320 variable in each @file{Makefile.am}.
13322 Succeeding releases will rely more and more on scanning
13323 @file{configure.in} to better automate the Autoconf integration.
13325 0.28 also introduces the @code{AUTOMAKE_OPTIONS} variable and the
13326 @option{--gnu} and @option{--gnits} options, the latter being stricter.
13328 @item 1996-02-07 Automake 0.29
13330 Thanks to @file{configure.in} scanning, @code{CONFIG_HEADER} is gone,
13331 and rebuild rules for @file{configure}-generated file are
13332 automatically output.
13334 @code{TEXINFOS} and @code{MANS} converted to the uniform naming
13337 @item 1996-02-24 Automake 0.30
13339 The test suite is born. It contains 9 tests. From now on test cases
13340 will be added pretty regularly (@pxref{Releases}), and this proved to
13341 be really helpful later on.
13343 @code{EXTRA_PROGRAMS} finally replaces @code{AM_PROGRAMS}.
13345 All the third-party Autoconf macros, written mostly by Fran@,cois
13346 Pinard (and later Jim Meyering), are distributed in Automake's
13347 hand-written @file{aclocal.m4} file. Package maintainers are expected
13348 to extract the necessary macros from this file. (In previous versions
13349 you had to copy and paste them from the manual...)
13351 @item 1996-03-11 Automake 0.31
13353 The test suite in 0.30 was run via a long @code{check-local} rule. Upon
13354 Ulrich Drepper's suggestion, 0.31 makes it an Automake rule output
13355 whenever the @code{TESTS} variable is defined.
13357 @code{DIST_OTHER} is renamed to @code{EXTRA_DIST}, and the @code{check_}
13358 prefix is introduced. The syntax is now the same as today.
13360 @item 1996-03-15 Gordon Matzigkeit starts writing libtool.
13362 @item 1996-04-27 Automake 0.32
13364 @code{-hook} targets are introduced; an idea from Dieter Baron.
13366 @file{*.info} files, which were output in the build directory are
13367 now built in the source directory, because they are distributed. It
13368 seems these files like to move back and forth as that will happen
13369 again in future versions.
13371 @item 1996-05-18 Automake 0.33
13373 Gord Matzigkeit's main two contributions:
13376 @item very preliminary libtool support
13377 @item the distcheck rule
13380 Although they were very basic at this point, these are probably
13381 among the top features for Automake today.
13383 Jim Meyering also provides the infamous @code{jm_MAINTAINER_MODE},
13384 since then renamed to @code{AM_MAINTAINER_MODE} and abandoned by its
13385 author (@pxref{maintainer-mode}).
13387 @item 1996-05-28 Automake 1.0
13389 After only six months of heavy development, the @command{automake} script is
13390 3134 lines long, plus 973 lines of @file{Makefile} fragments. The
13391 package has 30 pages of documentation, and 38 test cases.
13392 @file{aclocal.m4} contains 4 macros.
13394 From now on and until version 1.4, new releases will occur at a rate
13395 of about one a year. 1.1 did not exist, actually 1.1b to 1.1p have
13396 been the name of beta releases for 1.2. This is the first time
13397 Automake uses suffix letters to designate beta releases, a habit that
13400 @item 1996-10-10 Kevin Dalley packages Automake 1.0 for Debian GNU/Linux.
13402 @item 1996-11-26 David J.@tie{}MacKenzie releases Autoconf 2.12.
13404 Between June and October, the Autoconf development is almost stalled.
13405 Roland McGrath has been working at the beginning of the year. David
13406 comes back in November to release 2.12, but he won't touch Autoconf
13407 anymore after this year, and Autoconf then really stagnates. The
13408 desolate Autoconf @file{ChangeLog} for 1997 lists only 7 commits.
13410 @item 1997-02-28 @email{automake@@gnu.ai.mit.edu} list alive
13412 The mailing list is announced as follows:
13414 I've created the "automake" mailing list. It is
13415 "automake@@gnu.ai.mit.edu". Administrivia, as always, to
13416 automake-request@@gnu.ai.mit.edu.
13418 The charter of this list is discussion of automake, autoconf, and
13419 other configuration/portability tools (e.g., libtool). It is expected
13420 that discussion will range from pleas for help all the way up to
13423 This list is archived on the FSF machines. Offhand I don't know if
13424 you can get the archive without an account there.
13426 This list is open to anybody who wants to join. Tell all your
13431 Before that people were discussing Automake privately, on the Gnits
13432 mailing list (which is not public either), and less frequently on
13433 @code{gnu.misc.discuss}.
13435 @code{gnu.ai.mit.edu} is now @code{gnu.org}, in case you never
13436 noticed. The archives of the early years of the
13437 @code{automake@@gnu.org} list have been lost, so today it is almost
13438 impossible to find traces of discussions that occurred before 1999.
13439 This has been annoying more than once, as such discussions can be
13440 useful to understand the rationale behind a piece of uncommented code
13441 that was introduced back then.
13443 @item 1997-06-22 Automake 1.2
13445 Automake developments continues, and more and more new Autoconf macros
13446 are required. Distributing them in @file{aclocal.m4} and requiring
13447 people to browse this file to extract the relevant macros becomes
13448 uncomfortable. Ideally, some of them should be contributed to
13449 Autoconf so that they can be used directly, however Autoconf is
13450 currently inactive. Automake 1.2 consequently introduces
13451 @command{aclocal} (@command{aclocal} was actually started on
13452 1996-07-28), a tool that automatically constructs an @file{aclocal.m4}
13453 file from a repository of third-party macros. Because Autoconf has
13454 stalled, Automake also becomes a kind of repository for such
13455 third-party macros, even macros completely unrelated to Automake (for
13456 instance macros that fix broken Autoconf macros).
13458 The 1.2 release contains 20 macros, including the
13459 @code{AM_INIT_AUTOMAKE} macro that simplifies the creation of
13460 @file{configure.in}.
13462 Libtool is fully supported using @code{*_LTLIBRARIES}.
13464 The missing script is introduced by Fran@,cois Pinard; it is meant to be
13465 a better solution than @code{AM_MAINTAINER_MODE}
13466 (@pxref{maintainer-mode}).
13468 Conditionals support was implemented by Ian Lance Taylor. At the
13469 time, Tom and Ian were working on an internal project at Cygnus. They
13470 were using ILU, which is pretty similar to CORBA@. They wanted to
13471 integrate ILU into their build, which was all @file{configure}-based,
13472 and Ian thought that adding conditionals to @command{automake} was
13473 simpler than doing all the work in @file{configure} (which was the
13474 standard at the time). So this was actually funded by Cygnus.
13476 This very useful but tricky feature will take a lot of time to
13477 stabilize. (At the time this text is written, there are still
13478 primaries that have not been updated to support conditional
13479 definitions in Automake 1.9.)
13481 The @command{automake} script has almost doubled: 6089 lines of Perl,
13482 plus 1294 lines of @file{Makefile} fragments.
13484 @item 1997-07-08 Gordon Matzigkeit releases Libtool 1.0.
13486 @item 1998-04-05 Automake 1.3
13488 This is a small advance compared to 1.2.
13489 It adds support for assembly, and preliminary support for Java.
13491 Perl 5.004_04 is out, but fixes to support Perl 4 are still
13492 regularly submitted whenever Automake breaks it.
13494 @item 1998-09-06 @code{sourceware.cygnus.com} is on-line.
13496 Sourceware was setup by Jason Molenda to host open source projects.
13498 @item 1998-09-19 Automake CVS repository moved to @code{sourceware.cygnus.com}
13499 @itemx 1998-10-26 @code{sourceware.cygnus.com} announces it hosts Automake:
13500 Automake is now hosted on @code{sourceware.cygnus.com}. It has a
13501 publicly accessible CVS repository. This CVS repository is a copy of
13502 the one Tom was using on his machine, which in turn is based on
13503 a copy of the CVS repository of David MacKenzie. This is why we still
13504 have to full source history. (Automake was on Sourceware until 2007-10-29,
13505 when it moved to a git repository on @code{savannah.gnu.org},
13506 but the Sourceware host had been renamed to @code{sources.redhat.com}.)
13508 The oldest file in the administrative directory of the CVS repository
13509 that was created on Sourceware is dated 1998-09-19, while the
13510 announcement that @command{automake} and @command{autoconf} had joined
13511 @command{sourceware} was made on 1998-10-26. They were among the
13512 first projects to be hosted there.
13514 The heedful reader will have noticed Automake was exactly 4 years old
13517 @item 1999-01-05 Ben Elliston releases Autoconf 2.13.
13519 @item 1999-01-14 Automake 1.4
13521 This release adds support for Fortran 77 and for the @code{include}
13522 statement. Also, @samp{+=} assignments are introduced, but it is
13523 still quite easy to fool Automake when mixing this with conditionals.
13525 These two releases, Automake 1.4 and Autoconf 2.13 make a duo that
13526 will be used together for years.
13528 @command{automake} is 7228 lines, plus 1591 lines of Makefile
13529 fragment, 20 macros (some 1.3 macros were finally contributed back to
13530 Autoconf), 197 test cases, and 51 pages of documentation.
13532 @item 1999-03-27 The @code{user-dep-branch} is created on the CVS repository.
13534 This implements a new dependency tracking schemed that should be
13535 able to handle automatic dependency tracking using any compiler (not
13536 just gcc) and any make (not just GNU @command{make}). In addition,
13537 the new scheme should be more reliable than the old one, as
13538 dependencies are generated on the end user's machine. Alexandre Oliva
13539 creates depcomp for this purpose.
13541 @xref{Dependency Tracking Evolution}, for more details about the
13542 evolution of automatic dependency tracking in Automake.
13544 @item 1999-11-21 The @code{user-dep-branch} is merged into the main trunk.
13546 This was a huge problem since we also had patches going in on the
13547 trunk. The merge took a long time and was very painful.
13551 Since September 1999 and until 2003, Akim Demaille will be zealously
13552 revamping Autoconf.
13555 I think the next release should be called "3.0".@*
13556 Let's face it: you've basically rewritten autoconf.@*
13557 Every weekend there are 30 new patches.@*
13558 I don't see how we could call this "2.15" with a straight face.@*
13559 -- Tom Tromey on @email{autoconf@@gnu.org}
13562 Actually Akim works like a submarine: he will pile up patches while he
13563 works off-line during the weekend, and flush them in batch when he
13564 resurfaces on Monday.
13568 On this Wednesday, Autoconf 2.49c, the last beta before Autoconf 2.50
13569 is out, and Akim has to find something to do during his week-end :)
13573 Akim sends a batch of 14 patches to @email{automake@@gnu.org}.
13576 Aiieeee! I was dreading the day that the Demaillator turned his
13577 sights on automake@dots{} and now it has arrived! -- Tom Tromey
13580 It's only the beginning: in two months he will send 192 patches. Then
13581 he would slow down so Tom can catch up and review all this. Initially
13582 Tom actually read all these patches, then he probably trustingly
13583 answered OK to most of them, and finally gave up and let Akim apply
13584 whatever he wanted. There was no way to keep up with that patch rate.
13587 Anyway the patch below won't apply since it predates Akim's
13588 sourcequake; I have yet to figure where the relevant passage has
13589 been moved :) -- Alexandre Duret-Lutz
13592 All these patches were sent to and discussed on
13593 @email{automake@@gnu.org}, so subscribed users were literally drowning in
13594 technical mails. Eventually, the @email{automake-patches@@gnu.org}
13595 mailing list was created in May.
13597 Year after year, Automake had drifted away from its initial design:
13598 construct @file{Makefile.in} by assembling various @file{Makefile}
13599 fragments. In 1.4, lots of @file{Makefile} rules are being emitted at
13600 various places in the @command{automake} script itself; this does not
13601 help ensuring a consistent treatment of these rules (for instance
13602 making sure that user-defined rules override Automake's own rules).
13603 One of Akim's goal was moving all these hard-coded rules to separate
13604 @file{Makefile} fragments, so the logic could be centralized in a
13605 @file{Makefile} fragment processor.
13607 Another significant contribution of Akim is the interface with the
13608 ``trace'' feature of Autoconf. The way to scan @file{configure.in} at
13609 this time was to read the file and grep the various macro of interest
13610 to Automake. Doing so could break in many unexpected ways; @command{automake}
13611 could miss some definition (for instance @samp{AC_SUBST([$1], [$2])}
13612 where the arguments are known only when M4 is run), or conversely it
13613 could detect some macro that was not expanded (because it is called
13614 conditionally). In the CVS version of Autoconf, Akim had implemented
13615 the @option{--trace} option, which provides accurate information about
13616 where macros are actually called and with what arguments. Akim will
13617 equip Automake with a second @file{configure.in} scanner that uses
13618 this @option{--trace} interface. Since it was not sensible to drop the
13619 Autoconf 2.13 compatibility yet, this experimental scanner was only
13620 used when an environment variable was set, the traditional
13621 grep-scanner being still the default.
13623 @item 2001-04-25 Gary V.@tie{}Vaughan releases Libtool 1.4
13625 It has been more than two years since Automake 1.4, CVS Automake has
13626 suffered lot's of heavy changes and still is not ready for release.
13627 Libtool 1.4 had to be distributed with a patch against Automake 1.4.
13629 @item 2001-05-08 Automake 1.4-p1
13630 @itemx 2001-05-24 Automake 1.4-p2
13632 Gary V.@tie{}Vaughan, the principal Libtool maintainer, makes a ``patch
13633 release'' of Automake:
13636 The main purpose of this release is to have a stable automake
13637 which is compatible with the latest stable libtool.
13640 The release also contains obvious fixes for bugs in Automake 1.4,
13641 some of which were reported almost monthly.
13643 @item 2001-05-21 Akim Demaille releases Autoconf 2.50
13645 @item 2001-06-07 Automake 1.4-p3
13646 @itemx 2001-06-10 Automake 1.4-p4
13647 @itemx 2001-07-15 Automake 1.4-p5
13649 Gary continues his patch-release series. These also add support for
13650 some new Autoconf 2.50 idioms. Essentially, Autoconf now advocates
13651 @file{configure.ac} over @file{configure.in}, and it introduces a new
13652 syntax for @code{AC_OUTPUT}ing files.
13654 @item 2001-08-23 Automake 1.5
13656 A major and long-awaited release, that comes more than two years after
13657 1.4. It brings many changes, among which:
13659 @item The new dependency tracking scheme that uses @command{depcomp}.
13660 Aside from the improvement on the dependency tracking itself
13661 (@pxref{Dependency Tracking Evolution}), this also streamlines the use
13662 of @command{automake}-generated @file{Makefile.in}s as the @file{Makefile.in}s
13663 used during development are now the same as those used in
13664 distributions. Before that the @file{Makefile.in}s generated for
13665 maintainers required GNU @command{make} and GCC, they were different
13666 from the portable @file{Makefile} generated for distribution; this was
13667 causing some confusion.
13669 @item Support for per-target compilation flags.
13671 @item Support for reference to files in subdirectories in most
13672 @file{Makefile.am} variables.
13674 @item Introduction of the @code{dist_}, @code{nodist_}, and @code{nobase_}
13676 @item Perl 4 support is finally dropped.
13679 1.5 did break several packages that worked with 1.4. Enough so that
13680 Linux distributions could not easily install the new Automake version
13681 without breaking many of the packages for which they had to run
13682 @command{automake}.
13684 Some of these breakages were effectively bugs that would eventually be
13685 fixed in the next release. However, a lot of damage was caused by
13686 some changes made deliberately to render Automake stricter on some
13687 setup we did consider bogus. For instance, @samp{make distcheck} was
13688 improved to check that @samp{make uninstall} did remove all the files
13689 @samp{make install} installed, that @samp{make distclean} did not omit
13690 some file, and that a VPATH build would work even if the source
13691 directory was read-only. Similarly, Automake now rejects multiple
13692 definitions of the same variable (because that would mix very badly
13693 with conditionals), and @samp{+=} assignments with no previous
13694 definition. Because these changes all occurred suddenly after 1.4 had
13695 been established for more than two years, it hurt users.
13697 To make matter worse, meanwhile Autoconf (now at version 2.52) was
13698 facing similar troubles, for similar reasons.
13700 @item 2002-03-05 Automake 1.6
13702 This release introduced versioned installation (@pxref{API
13703 Versioning}). This was mainly pushed by Havoc Pennington, taking the
13704 GNOME source tree as motive: due to incompatibilities between the
13705 autotools it's impossible for the GNOME packages to switch to Autoconf
13706 2.53 and Automake 1.5 all at once, so they are currently stuck with
13707 Autoconf 2.13 and Automake 1.4.
13709 The idea was to call this version @file{automake-1.6}, call all its
13710 bug-fix versions identically, and switch to @file{automake-1.7} for
13711 the next release that adds new features or changes some rules. This
13712 scheme implies maintaining a bug-fix branch in addition to the
13713 development trunk, which means more work from the maintainer, but
13714 providing regular bug-fix releases proved to be really worthwhile.
13716 Like 1.5, 1.6 also introduced a bunch of incompatibilities, intentional or
13717 not. Perhaps the more annoying was the dependence on the newly
13718 released Autoconf 2.53. Autoconf seemed to have stabilized enough
13719 since its explosive 2.50 release and included changes required to fix
13720 some bugs in Automake. In order to upgrade to Automake 1.6, people
13721 now had to upgrade Autoconf too; for some packages it was no picnic.
13723 While versioned installation helped people to upgrade, it also
13724 unfortunately allowed people not to upgrade. At the time of writing,
13725 some Linux distributions are shipping packages for Automake 1.4, 1.5,
13726 1.6, 1.7, 1.8, and 1.9. Most of these still install 1.4 by default.
13727 Some distribution also call 1.4 the ``stable'' version, and present
13728 ``1.9'' as the development version; this does not really makes sense
13729 since 1.9 is way more solid than 1.4. All this does not help the
13732 @item 2002-04-11 Automake 1.6.1
13734 1.6, and the upcoming 1.4-p6 release were the last release by Tom.
13735 This one and those following will be handled by Alexandre
13736 Duret-Lutz. Tom is still around, and will be there until about 1.7,
13737 but his interest into Automake is drifting away towards projects like
13740 Alexandre has been using Automake since 2000, and started to
13741 contribute mostly on Akim's incitement (Akim and Alexandre have been
13742 working in the same room from 1999 to 2002). In 2001 and 2002 he had
13743 a lot of free time to enjoy hacking Automake.
13745 @item 2002-06-14 Automake 1.6.2
13747 @item 2002-07-28 Automake 1.6.3
13748 @itemx 2002-07-28 Automake 1.4-p6
13750 Two releases on the same day. 1.6.3 is a bug-fix release.
13752 Tom Tromey backported the versioned installation mechanism on the 1.4
13753 branch, so that Automake 1.6.x and Automake 1.4-p6 could be installed
13754 side by side. Another request from the GNOME folks.
13756 @item 2002-09-25 Automake 1.7
13758 This release switches to the new @file{configure.ac} scanner Akim
13759 was experimenting in 1.5.
13761 @item 2002-10-16 Automake 1.7.1
13762 @itemx 2002-12-06 Automake 1.7.2
13763 @itemx 2003-02-20 Automake 1.7.3
13764 @itemx 2003-04-23 Automake 1.7.4
13765 @itemx 2003-05-18 Automake 1.7.5
13766 @itemx 2003-07-10 Automake 1.7.6
13767 @itemx 2003-09-07 Automake 1.7.7
13768 @itemx 2003-10-07 Automake 1.7.8
13770 Many bug-fix releases. 1.7 lasted because the development version
13771 (upcoming 1.8) was suffering some major internal revamping.
13773 @item 2003-10-26 Automake on screen
13775 Episode 49, `Repercussions', in the third season of the `Alias' TV
13776 show is first aired.
13778 Marshall, one of the characters, is working on a computer virus that he
13779 has to modify before it gets into the wrong hands or something like
13780 that. The screenshots you see do not show any program code, they show
13781 a @file{Makefile.in} @code{generated by automake}...
13783 @item 2003-11-09 Automake 1.7.9
13785 @item 2003-12-10 Automake 1.8
13787 The most striking update is probably that of @command{aclocal}.
13789 @command{aclocal} now uses @code{m4_include} in the produced
13790 @file{aclocal.m4} when the included macros are already distributed
13791 with the package (an idiom used in many packages), which reduces code
13792 duplication. Many people liked that, but in fact this change was
13793 really introduced to fix a bug in rebuild rules: @file{Makefile.in}
13794 must be rebuilt whenever a dependency of @file{configure} changes, but
13795 all the @file{m4} files included in @file{aclocal.m4} where unknown
13796 from @command{automake}. Now @command{automake} can just trace the
13797 @code{m4_include}s to discover the dependencies.
13799 @command{aclocal} also starts using the @option{--trace} Autoconf option
13800 in order to discover used macros more accurately. This will turn out
13801 to be very tricky (later releases will improve this) as people had
13802 devised many ways to cope with the limitation of previous
13803 @command{aclocal} versions, notably using handwritten
13804 @code{m4_include}s: @command{aclocal} must make sure not to redefine a
13805 rule that is already included by such statement.
13807 Automake also has seen its guts rewritten. Although this rewriting
13808 took a lot of efforts, it is only apparent to the users in that some
13809 constructions previously disallowed by the implementation now work
13810 nicely. Conditionals, Locations, Variable and Rule definitions,
13811 Options: these items on which Automake works have been rewritten as
13812 separate Perl modules, and documented.
13814 @itemx 2004-01-11 Automake 1.8.1
13815 @itemx 2004-01-12 Automake 1.8.2
13816 @itemx 2004-03-07 Automake 1.8.3
13817 @itemx 2004-04-25 Automake 1.8.4
13818 @itemx 2004-05-16 Automake 1.8.5
13820 @item 2004-07-28 Automake 1.9
13822 This release tries to simplify the compilation rules it outputs to
13823 reduce the size of the Makefile. The complaint initially come from
13824 the libgcj developers. Their @file{Makefile.in} generated with
13825 Automake 1.4 and custom build rules (1.4 did not support compiled
13826 Java) is 250KB@. The one generated by 1.8 was over 9MB@! 1.9 gets it
13829 Aside from this it contains mainly minor changes and bug-fixes.
13831 @itemx 2004-08-11 Automake 1.9.1
13832 @itemx 2004-09-19 Automake 1.9.2
13834 Automake has ten years. This chapter of the manual was initially
13835 written for this occasion.
13837 @itemx 2007-10-29 Automake repository moves to @code{savannah.gnu.org} and uses
13838 git as primary repository.
13842 @node Dependency Tracking Evolution
13843 @section Dependency Tracking in Automake
13845 Over the years Automake has deployed three different dependency
13846 tracking methods. Each method, including the current one, has had
13847 flaws of various sorts. Here we lay out the different dependency
13848 tracking methods, their flaws, and their fixes. We conclude with
13849 recommendations for tool writers, and by indicating future directions
13850 for dependency tracking work in Automake.
13853 * First Take on Dependencies:: Precomputed dependency tracking
13854 * Dependencies As Side Effects:: Update at developer compile time
13855 * Dependencies for the User:: Update at user compile time
13856 * Techniques for Dependencies:: Alternative approaches
13857 * Recommendations for Tool Writers:: What tool writers can do to help
13858 * Future Directions for Dependencies:: Languages Automake does not know
13861 @node First Take on Dependencies
13862 @subsection First Take on Dependency Tracking
13863 @unnumberedsubsubsec Description
13865 Our first attempt at automatic dependency tracking was based on the
13866 method recommended by GNU @command{make}. (@pxref{Automatic
13867 Prerequisites, , Generating Prerequisites Automatically, make, The GNU
13870 This version worked by precomputing dependencies ahead of time. For
13871 each source file, it had a special @file{.P} file that held the
13872 dependencies. There was a rule to generate a @file{.P} file by
13873 invoking the compiler appropriately. All such @file{.P} files were
13874 included by the @file{Makefile}, thus implicitly becoming dependencies
13875 of @file{Makefile}.
13877 @unnumberedsubsubsec Bugs
13879 This approach had several critical bugs.
13883 The code to generate the @file{.P} file relied on @command{gcc}.
13884 (A limitation, not technically a bug.)
13886 The dependency tracking mechanism itself relied on GNU @command{make}.
13887 (A limitation, not technically a bug.)
13889 Because each @file{.P} file was a dependency of @file{Makefile}, this
13890 meant that dependency tracking was done eagerly by @command{make}.
13891 For instance, @samp{make clean} would cause all the dependency files
13892 to be updated, and then immediately removed. This eagerness also
13893 caused problems with some configurations; if a certain source file
13894 could not be compiled on a given architecture for some reason,
13895 dependency tracking would fail, aborting the entire build.
13897 As dependency tracking was done as a pre-pass, compile times were
13898 doubled--the compiler had to be run twice per source file.
13900 @samp{make dist} re-ran @command{automake} to generate a
13901 @file{Makefile} that did not have automatic dependency tracking (and
13902 that was thus portable to any version of @command{make}). In order to
13903 do this portably, Automake had to scan the dependency files and remove
13904 any reference that was to a source file not in the distribution.
13905 This process was error-prone. Also, if @samp{make dist} was run in an
13906 environment where some object file had a dependency on a source file
13907 that was only conditionally created, Automake would generate a
13908 @file{Makefile} that referred to a file that might not appear in the
13909 end user's build. A special, hacky mechanism was required to work
13913 @unnumberedsubsubsec Historical Note
13915 The code generated by Automake is often inspired by the
13916 @file{Makefile} style of a particular author. In the case of the first
13917 implementation of dependency tracking, I believe the impetus and
13918 inspiration was Jim Meyering. (I could be mistaken. If you know
13919 otherwise feel free to correct me.)
13921 @node Dependencies As Side Effects
13922 @subsection Dependencies As Side Effects
13923 @unnumberedsubsubsec Description
13925 The next refinement of Automake's automatic dependency tracking scheme
13926 was to implement dependencies as side effects of the compilation.
13927 This was aimed at solving the most commonly reported problems with the
13928 first approach. In particular we were most concerned with eliminating
13929 the weird rebuilding effect associated with make clean.
13931 In this approach, the @file{.P} files were included using the
13932 @code{-include} command, which let us create these files lazily. This
13933 avoided the @samp{make clean} problem.
13935 We only computed dependencies when a file was actually compiled. This
13936 avoided the performance penalty associated with scanning each file
13937 twice. It also let us avoid the other problems associated with the
13938 first, eager, implementation. For instance, dependencies would never
13939 be generated for a source file that was not compilable on a given
13940 architecture (because it in fact would never be compiled).
13942 @unnumberedsubsubsec Bugs
13946 This approach also relied on the existence of @command{gcc} and GNU
13947 @command{make}. (A limitation, not technically a bug.)
13949 Dependency tracking was still done by the developer, so the problems
13950 from the first implementation relating to massaging of dependencies by
13951 @samp{make dist} were still in effect.
13953 This implementation suffered from the ``deleted header file'' problem.
13954 Suppose a lazily-created @file{.P} file includes a dependency on a
13955 given header file, like this:
13958 maude.o: maude.c something.h
13961 Now suppose that you remove @file{something.h} and update @file{maude.c}
13962 so that this include is no longer needed. If you run @command{make},
13963 you will get an error because there is no way to create
13964 @file{something.h}.
13966 We fixed this problem in a later release by further massaging the
13967 output of @command{gcc} to include a dummy dependency for each header
13971 @node Dependencies for the User
13972 @subsection Dependencies for the User
13973 @unnumberedsubsubsec Description
13975 The bugs associated with @samp{make dist}, over time, became a real
13976 problem. Packages using Automake were being built on a large number
13977 of platforms, and were becoming increasingly complex. Broken
13978 dependencies were distributed in ``portable'' @file{Makefile.in}s,
13979 leading to user complaints. Also, the requirement for @command{gcc}
13980 and GNU @command{make} was a constant source of bug reports. The next
13981 implementation of dependency tracking aimed to remove these problems.
13983 We realized that the only truly reliable way to automatically track
13984 dependencies was to do it when the package itself was built. This
13985 meant discovering a method portable to any version of make and any
13986 compiler. Also, we wanted to preserve what we saw as the best point
13987 of the second implementation: dependency computation as a side effect
13990 In the end we found that most modern make implementations support some
13991 form of include directive. Also, we wrote a wrapper script that let
13992 us abstract away differences between dependency tracking methods for
13993 compilers. For instance, some compilers cannot generate dependencies
13994 as a side effect of compilation. In this case we simply have the
13995 script run the compiler twice. Currently our wrapper script
13996 (@command{depcomp}) knows about twelve different compilers (including
13997 a "compiler" that simply invokes @command{makedepend} and then the
13998 real compiler, which is assumed to be a standard Unix-like C compiler
13999 with no way to do dependency tracking).
14001 @unnumberedsubsubsec Bugs
14005 Running a wrapper script for each compilation slows down the build.
14007 Many users don't really care about precise dependencies.
14009 This implementation, like every other automatic dependency tracking
14010 scheme in common use today (indeed, every one we've ever heard of),
14011 suffers from the ``duplicated new header'' bug.
14013 This bug occurs because dependency tracking tools, such as the
14014 compiler, only generate dependencies on the successful opening of a
14015 file, and not on every probe.
14017 Suppose for instance that the compiler searches three directories for
14018 a given header, and that the header is found in the third directory.
14019 If the programmer erroneously adds a header file with the same name to
14020 the first directory, then a clean rebuild from scratch could fail
14021 (suppose the new header file is buggy), whereas an incremental rebuild
14024 What has happened here is that people have a misunderstanding of what
14025 a dependency is. Tool writers think a dependency encodes information
14026 about which files were read by the compiler. However, a dependency
14027 must actually encode information about what the compiler tried to do.
14029 This problem is not serious in practice. Programmers typically do not
14030 use the same name for a header file twice in a given project. (At
14031 least, not in C or C++. This problem may be more troublesome in
14032 Java.) This problem is easy to fix, by modifying dependency
14033 generators to record every probe, instead of every successful open.
14036 Since Automake generates dependencies as a side effect of compilation,
14037 there is a bootstrapping problem when header files are generated by
14038 running a program. The problem is that, the first time the build is
14039 done, there is no way by default to know that the headers are
14040 required, so make might try to run a compilation for which the headers
14041 have not yet been built.
14043 This was also a problem in the previous dependency tracking implementation.
14045 The current fix is to use @code{BUILT_SOURCES} to list built headers
14046 (@pxref{Sources}). This causes them to be built before any other
14047 build rules are run. This is unsatisfactory as a general solution,
14048 however in practice it seems sufficient for most actual programs.
14051 This code is used since Automake 1.5.
14053 In GCC 3.0, we managed to convince the maintainers to add special
14054 command-line options to help Automake more efficiently do its job. We
14055 hoped this would let us avoid the use of a wrapper script when
14056 Automake's automatic dependency tracking was used with @command{gcc}.
14058 Unfortunately, this code doesn't quite do what we want. In
14059 particular, it removes the dependency file if the compilation fails;
14060 we'd prefer that it instead only touch the file in any way if the
14061 compilation succeeds.
14063 Nevertheless, since Automake 1.7, when a recent @command{gcc} is
14064 detected at @command{configure} time, we inline the
14065 dependency-generation code and do not use the @command{depcomp}
14066 wrapper script. This makes compilations faster for those using this
14067 compiler (probably our primary user base). The counterpart is that
14068 because we have to encode two compilation rules in @file{Makefile}
14069 (with or without @command{depcomp}), the produced @file{Makefile}s are
14072 @node Techniques for Dependencies
14073 @subsection Techniques for Computing Dependencies
14075 There are actually several ways for a build tool like Automake to
14076 cause tools to generate dependencies.
14079 @item @command{makedepend}
14080 This was a commonly-used method in the past. The idea is to run a
14081 special program over the source and have it generate dependency
14082 information. Traditional implementations of @command{makedepend} are
14083 not completely precise; ordinarily they were conservative and
14084 discovered too many dependencies.
14086 An obvious way to generate dependencies is to simply write the tool so
14087 that it can generate the information needed by the build tool. This is
14088 also the most portable method. Many compilers have an option to
14089 generate dependencies. Unfortunately, not all tools provide such an
14091 @item The file system
14092 It is possible to write a special file system that tracks opens,
14093 reads, writes, etc, and then feed this information back to the build
14094 tool. @command{clearmake} does this. This is a very powerful
14095 technique, as it doesn't require cooperation from the
14096 tool. Unfortunately it is also very difficult to implement and also
14097 not practical in the general case.
14098 @item @code{LD_PRELOAD}
14099 Rather than use the file system, one could write a special library to
14100 intercept @code{open} and other syscalls. This technique is also quite
14101 powerful, but unfortunately it is not portable enough for use in
14102 @command{automake}.
14105 @node Recommendations for Tool Writers
14106 @subsection Recommendations for Tool Writers
14108 We think that every compilation tool ought to be able to generate
14109 dependencies as a side effect of compilation. Furthermore, at least
14110 while @command{make}-based tools are nearly universally in use (at
14111 least in the free software community), the tool itself should generate
14112 dummy dependencies for header files, to avoid the deleted header file
14113 bug. Finally, the tool should generate a dependency for each probe,
14114 instead of each successful file open, in order to avoid the duplicated
14117 @node Future Directions for Dependencies
14118 @subsection Future Directions for Dependencies
14120 Currently, only languages and compilers understood by Automake can
14121 have dependency tracking enabled. We would like to see if it is
14122 practical (and worthwhile) to let this support be extended by the user
14123 to languages unknown to Automake.
14126 @section Release Statistics
14128 The following table (inspired by @samp{perlhist(1)}) quantifies the
14129 evolution of Automake using these metrics:
14133 The date and version of the release.
14135 The number of lines of the @command{automake} script.
14137 The number of lines of the @command{aclocal} script.
14139 The number of lines of the @command{Perl} supporting modules.
14141 The number of lines of the @file{Makefile} fragments. The number in
14142 parentheses is the number of files.
14144 The number of lines (and files) of Autoconf macros.
14146 The number of pages of the documentation (the Postscript version).
14148 The number of test cases in the test suite. Of those, the number in
14149 parentheses is the number of generated test cases.
14152 @multitable {8888-88-88} {8.8-p8} {8888} {8888} {8888} {8888 (88)} {8888 (88)} {888} {888 (88)}
14153 @headitem Date @tab Rel @tab am @tab acl @tab pm @tab @file{*.am} @tab m4 @tab doc @tab t
14154 @item 1994-09-19 @tab CVS @tab 141 @tab @tab @tab 299 (24) @tab @tab @tab
14155 @item 1994-11-05 @tab CVS @tab 208 @tab @tab @tab 332 (28) @tab @tab @tab
14156 @item 1995-11-23 @tab 0.20 @tab 533 @tab @tab @tab 458 (35) @tab @tab 9 @tab
14157 @item 1995-11-26 @tab 0.21 @tab 613 @tab @tab @tab 480 (36) @tab @tab 11 @tab
14158 @item 1995-11-28 @tab 0.22 @tab 1116 @tab @tab @tab 539 (38) @tab @tab 12 @tab
14159 @item 1995-11-29 @tab 0.23 @tab 1240 @tab @tab @tab 541 (38) @tab @tab 12 @tab
14160 @item 1995-12-08 @tab 0.24 @tab 1462 @tab @tab @tab 504 (33) @tab @tab 14 @tab
14161 @item 1995-12-10 @tab 0.25 @tab 1513 @tab @tab @tab 511 (37) @tab @tab 15 @tab
14162 @item 1996-01-03 @tab 0.26 @tab 1706 @tab @tab @tab 438 (36) @tab @tab 16 @tab
14163 @item 1996-01-03 @tab 0.27 @tab 1706 @tab @tab @tab 438 (36) @tab @tab 16 @tab
14164 @item 1996-01-13 @tab 0.28 @tab 1964 @tab @tab @tab 934 (33) @tab @tab 16 @tab
14165 @item 1996-02-07 @tab 0.29 @tab 2299 @tab @tab @tab 936 (33) @tab @tab 17 @tab
14166 @item 1996-02-24 @tab 0.30 @tab 2544 @tab @tab @tab 919 (32) @tab 85 (1) @tab 20 @tab 9
14167 @item 1996-03-11 @tab 0.31 @tab 2877 @tab @tab @tab 919 (32) @tab 85 (1) @tab 29 @tab 17
14168 @item 1996-04-27 @tab 0.32 @tab 3058 @tab @tab @tab 921 (31) @tab 85 (1) @tab 30 @tab 26
14169 @item 1996-05-18 @tab 0.33 @tab 3110 @tab @tab @tab 926 (31) @tab 105 (1) @tab 30 @tab 35
14170 @item 1996-05-28 @tab 1.0 @tab 3134 @tab @tab @tab 973 (32) @tab 105 (1) @tab 30 @tab 38
14171 @item 1997-06-22 @tab 1.2 @tab 6089 @tab 385 @tab @tab 1294 (36) @tab 592 (20) @tab 37 @tab 126
14172 @item 1998-04-05 @tab 1.3 @tab 6415 @tab 422 @tab @tab 1470 (39) @tab 741 (23) @tab 39 @tab 156
14173 @item 1999-01-14 @tab 1.4 @tab 7240 @tab 426 @tab @tab 1591 (40) @tab 734 (20) @tab 51 @tab 197
14174 @item 2001-05-08 @tab 1.4-p1 @tab 7251 @tab 426 @tab @tab 1591 (40) @tab 734 (20) @tab 51 @tab 197
14175 @item 2001-05-24 @tab 1.4-p2 @tab 7268 @tab 439 @tab @tab 1591 (40) @tab 734 (20) @tab 49 @tab 197
14176 @item 2001-06-07 @tab 1.4-p3 @tab 7312 @tab 439 @tab @tab 1591 (40) @tab 734 (20) @tab 49 @tab 197
14177 @item 2001-06-10 @tab 1.4-p4 @tab 7321 @tab 439 @tab @tab 1591 (40) @tab 734 (20) @tab 49 @tab 198
14178 @item 2001-07-15 @tab 1.4-p5 @tab 7228 @tab 426 @tab @tab 1596 (40) @tab 734 (20) @tab 51 @tab 198
14179 @item 2001-08-23 @tab 1.5 @tab 8016 @tab 475 @tab 600 @tab 2654 (39) @tab 1166 (29) @tab 63 @tab 327
14180 @item 2002-03-05 @tab 1.6 @tab 8465 @tab 475 @tab 1136 @tab 2732 (39) @tab 1603 (27) @tab 66 @tab 365
14181 @item 2002-04-11 @tab 1.6.1 @tab 8544 @tab 475 @tab 1136 @tab 2741 (39) @tab 1603 (27) @tab 66 @tab 372
14182 @item 2002-06-14 @tab 1.6.2 @tab 8575 @tab 475 @tab 1136 @tab 2800 (39) @tab 1609 (27) @tab 67 @tab 386
14183 @item 2002-07-28 @tab 1.6.3 @tab 8600 @tab 475 @tab 1153 @tab 2809 (39) @tab 1609 (27) @tab 67 @tab 391
14184 @item 2002-07-28 @tab 1.4-p6 @tab 7332 @tab 455 @tab @tab 1596 (40) @tab 735 (20) @tab 49 @tab 197
14185 @item 2002-09-25 @tab 1.7 @tab 9189 @tab 471 @tab 1790 @tab 2965 (39) @tab 1606 (28) @tab 73 @tab 430
14186 @item 2002-10-16 @tab 1.7.1 @tab 9229 @tab 475 @tab 1790 @tab 2977 (39) @tab 1606 (28) @tab 73 @tab 437
14187 @item 2002-12-06 @tab 1.7.2 @tab 9334 @tab 475 @tab 1790 @tab 2988 (39) @tab 1606 (28) @tab 77 @tab 445
14188 @item 2003-02-20 @tab 1.7.3 @tab 9389 @tab 475 @tab 1790 @tab 3023 (39) @tab 1651 (29) @tab 84 @tab 448
14189 @item 2003-04-23 @tab 1.7.4 @tab 9429 @tab 475 @tab 1790 @tab 3031 (39) @tab 1644 (29) @tab 85 @tab 458
14190 @item 2003-05-18 @tab 1.7.5 @tab 9429 @tab 475 @tab 1790 @tab 3033 (39) @tab 1645 (29) @tab 85 @tab 459
14191 @item 2003-07-10 @tab 1.7.6 @tab 9442 @tab 475 @tab 1790 @tab 3033 (39) @tab 1660 (29) @tab 85 @tab 461
14192 @item 2003-09-07 @tab 1.7.7 @tab 9443 @tab 475 @tab 1790 @tab 3041 (39) @tab 1660 (29) @tab 90 @tab 467
14193 @item 2003-10-07 @tab 1.7.8 @tab 9444 @tab 475 @tab 1790 @tab 3041 (39) @tab 1660 (29) @tab 90 @tab 468
14194 @item 2003-11-09 @tab 1.7.9 @tab 9444 @tab 475 @tab 1790 @tab 3048 (39) @tab 1660 (29) @tab 90 @tab 468
14195 @item 2003-12-10 @tab 1.8 @tab 7171 @tab 585 @tab 7730 @tab 3236 (39) @tab 1666 (31) @tab 104 @tab 521
14196 @item 2004-01-11 @tab 1.8.1 @tab 7217 @tab 663 @tab 7726 @tab 3287 (39) @tab 1686 (31) @tab 104 @tab 525
14197 @item 2004-01-12 @tab 1.8.2 @tab 7217 @tab 663 @tab 7726 @tab 3288 (39) @tab 1686 (31) @tab 104 @tab 526
14198 @item 2004-03-07 @tab 1.8.3 @tab 7214 @tab 686 @tab 7735 @tab 3303 (39) @tab 1695 (31) @tab 111 @tab 530
14199 @item 2004-04-25 @tab 1.8.4 @tab 7214 @tab 686 @tab 7736 @tab 3310 (39) @tab 1701 (31) @tab 112 @tab 531
14200 @item 2004-05-16 @tab 1.8.5 @tab 7240 @tab 686 @tab 7736 @tab 3299 (39) @tab 1701 (31) @tab 112 @tab 533
14201 @item 2004-07-28 @tab 1.9 @tab 7508 @tab 715 @tab 7794 @tab 3352 (40) @tab 1812 (32) @tab 115 @tab 551
14202 @item 2004-08-11 @tab 1.9.1 @tab 7512 @tab 715 @tab 7794 @tab 3354 (40) @tab 1812 (32) @tab 115 @tab 552
14203 @item 2004-09-19 @tab 1.9.2 @tab 7512 @tab 715 @tab 7794 @tab 3354 (40) @tab 1812 (32) @tab 132 @tab 554
14204 @item 2004-11-01 @tab 1.9.3 @tab 7507 @tab 718 @tab 7804 @tab 3354 (40) @tab 1812 (32) @tab 134 @tab 556
14205 @item 2004-12-18 @tab 1.9.4 @tab 7508 @tab 718 @tab 7856 @tab 3361 (40) @tab 1811 (32) @tab 140 @tab 560
14206 @item 2005-02-13 @tab 1.9.5 @tab 7523 @tab 719 @tab 7859 @tab 3373 (40) @tab 1453 (32) @tab 142 @tab 562
14207 @item 2005-07-10 @tab 1.9.6 @tab 7539 @tab 699 @tab 7867 @tab 3400 (40) @tab 1453 (32) @tab 144 @tab 570
14208 @item 2006-10-15 @tab 1.10 @tab 7859 @tab 1072 @tab 8024 @tab 3512 (40) @tab 1496 (34) @tab 172 @tab 604
14209 @item 2008-01-19 @tab 1.10.1 @tab 7870 @tab 1089 @tab 8025 @tab 3520 (40) @tab 1499 (34) @tab 173 @tab 617
14210 @item 2008-11-23 @tab 1.10.2 @tab 7882 @tab 1089 @tab 8027 @tab 3540 (40) @tab 1509 (34) @tab 176 @tab 628
14211 @item 2009-05-17 @tab 1.11 @tab 8721 @tab 1092 @tab 8289 @tab 4164 (42) @tab 1714 (37) @tab 181 @tab 732 (20)
14215 @c ========================================================== Appendices
14218 @node Copying This Manual
14219 @appendix Copying This Manual
14222 * GNU Free Documentation License:: License for copying this manual
14225 @node GNU Free Documentation License
14226 @appendixsec GNU Free Documentation License
14234 * Macro Index:: Index of Autoconf macros
14235 * Variable Index:: Index of Makefile variables
14236 * General Index:: General index
14240 @appendixsec Macro Index
14244 @node Variable Index
14245 @appendixsec Variable Index
14249 @node General Index
14250 @appendixsec General Index
14257 @c LocalWords: texinfo setfilename settitle setchapternewpage texi direntry
14258 @c LocalWords: dircategory in's aclocal ifinfo titlepage Tromey vskip pt sp
14259 @c LocalWords: filll defcodeindex ov cv op tr syncodeindex fn cp vr ifnottex
14260 @c LocalWords: dir Automake's ac Dist Gnits gnits cygnus dfn Autoconf's pxref
14261 @c LocalWords: cindex Autoconf autoconf perl samp cvs dist trindex SUBST foo
14262 @c LocalWords: xs emph FIXME ref vindex pkglibdir pkgincludedir pkgdatadir mt
14263 @c LocalWords: pkg libdir cpio bindir sbindir rmt pax sbin zar zardir acindex
14264 @c LocalWords: HTML htmldir html noinst TEXINFOS nodist nobase strudel CFLAGS
14265 @c LocalWords: libmumble CC YFLAGS itemx de fication config url comp
14266 @c LocalWords: depcomp elisp sh mdate mkinstalldirs mkdir py tex dvi ps pdf
14267 @c LocalWords: ylwrap zardoz INIT gettext acinclude mv FUNCS LIBOBJS LDADD fr
14268 @c LocalWords: uref featureful dnl src LINGUAS es ko nl pl sl sv PROG ISC doc
14269 @c LocalWords: POSIX STDC fcntl FUNC ALLOCA blksize struct stat intl po chmod
14270 @c LocalWords: ChangeLog SUBDIRS gettextize gpl testdata getopt INTLLIBS cpp
14271 @c LocalWords: localedir datadir DLOCALEDIR DEXIT CPPFLAGS autoreconf opindex
14272 @c LocalWords: AUX var symlink deps Wno Wnone package's aclocal's distclean
14273 @c LocalWords: ltmain xref LIBSOURCE LIBSOURCES LIBOBJ MEMCMP vs RANLIB CXX
14274 @c LocalWords: LDFLAGS LIBTOOL libtool XTRA LIBS gettext's acdir APIVERSION
14275 @c LocalWords: dirlist noindent usr MULTILIB multilib Multilibs TIOCGWINSZ sc
14276 @c LocalWords: GWINSZ termios SRCDIR tarball bzip LISPDIR lispdir XEmacs CCAS
14277 @c LocalWords: emacsen MicroEmacs CCASFLAGS UX GCJ gcj GCJFLAGS posix DMALLOC
14278 @c LocalWords: dmalloc ldmalloc REGEX regex DEPDIR DEP DEFUN aclocaldir fi
14279 @c LocalWords: mymacro myothermacro AMFLAGS autopoint autogen libtoolize yum
14280 @c LocalWords: autoheader README MAKEFLAGS subdir Inetutils sync COND endif
14281 @c LocalWords: Miller's installable includedir inc pkgdata EXEEXT libexec bsd
14282 @c LocalWords: pkglib libexecdir prog libcpio cpio's dlopen dlpreopen linux
14283 @c LocalWords: subsubsection OBJEXT esac lib LTLIBRARIES liblob LIBADD AR ar
14284 @c LocalWords: ARFLAGS cru ing maude libgettext lo LTLIBOBJS rpath SGI PRE yy
14285 @c LocalWords: libmaude CCLD CXXFLAGS FFLAGS LFLAGS OBJCFLAGS RFLAGS DEFS cc
14286 @c LocalWords: SHORTNAME vtable srcdir nostdinc basename yxx cxx ll lxx gdb
14287 @c LocalWords: lexers yymaxdepth maxdepth yyparse yylex yyerror yylval lval
14288 @c LocalWords: yychar yydebug yypact yyr yydef def yychk chk yypgo pgo yyact
14289 @c LocalWords: yyexca exca yyerrflag errflag yynerrs nerrs yyps yypv pv yys
14290 @c LocalWords: yystate yytmp tmp yyv yyval val yylloc lloc yyreds yytoks toks
14291 @c LocalWords: yylhs yylen yydefred yydgoto yysindex yyrindex yygindex yyname
14292 @c LocalWords: yytable yycheck yyrule byacc CXXCOMPILE CXXLINK FLINK cfortran
14293 @c LocalWords: Catalogue preprocessable FLIBS libfoo baz JAVACFLAGS java exe
14294 @c LocalWords: SunOS fying basenames exeext uninstalled oldinclude kr FSF's
14295 @c LocalWords: pkginclude oldincludedir sysconf sharedstate localstate gcc rm
14296 @c LocalWords: sysconfdir sharedstatedir localstatedir preexist CLEANFILES gz
14297 @c LocalWords: depfile tmpdepfile depmode const interoperate
14298 @c LocalWords: JAVAC javac JAVAROOT builddir CLASSPATH ENV pyc pyo pkgpython
14299 @c LocalWords: pyexecdir pkgpyexecdir Python's pythondir pkgpythondir txi ois
14300 @c LocalWords: installinfo vers MAKEINFO makeinfo MAKEINFOFLAGS noinstall rf
14301 @c LocalWords: mandir thesame alsothesame installman myexecbin DESTDIR Pinard
14302 @c LocalWords: uninstall installdirs uninstalls MOSTLYCLEANFILES mostlyclean
14303 @c LocalWords: DISTCLEANFILES MAINTAINERCLEANFILES GZIP gzip shar exp
14304 @c LocalWords: distdir distcheck distcleancheck listfiles distuninstallcheck
14305 @c LocalWords: VPATH tarfile stdout XFAIL DejaGnu dejagnu DEJATOOL runtest ln
14306 @c LocalWords: RUNTESTDEFAULTFLAGS toolchain RUNTESTFLAGS asis readme DVIPS
14307 @c LocalWords: installcheck gzipped tarZ std utils etags mkid multilibbing cd
14308 @c LocalWords: ARGS taggable ETAGSFLAGS lang ctags CTAGSFLAGS GTAGS gtags idl
14309 @c LocalWords: foocc doit idlC multilibs ABIs cmindex defmac ARG enableval FC
14310 @c LocalWords: MSG xtrue DBG pathchk CYGWIN afile proglink versioned CVS's TE
14311 @c LocalWords: wildcards Autoconfiscated subsubheading autotools Meyering API
14312 @c LocalWords: ois's wildcard Wportability cartouche vrindex printindex Duret
14313 @c LocalWords: DSOMEFLAG DVERSION automake Lutz insertcopying versioning FAQ
14314 @c LocalWords: LTLIBOBJ Libtool's libtool's libltdl dlopening itutions libbar
14315 @c LocalWords: WANTEDLIBS libhello sublibraries libtop libsub dlopened Ratfor
14316 @c LocalWords: mymodule timestamps timestamp underquoted MAKEINFOHTMLFLAGS te
14317 @c LocalWords: GNUmakefile Subpackages subpackage's subpackages aux
14318 @c LocalWords: detailmenu Timeline pwd reldir AUTOM autom PREREQ FOOBAR libc
14319 @c LocalWords: libhand subpackage moduleN libmain libmisc FCFLAGS FCCOMPILE
14320 @c LocalWords: FCLINK subst sed ELCFILES elc MAKEINFOHTML dvips esyscmd ustar
14321 @c LocalWords: tarballs Woverride vfi ELFILES djm AutoMake honkin FSF
14322 @c LocalWords: fileutils precanned MacKenzie's reimplement termutils Tromey's
14323 @c LocalWords: cois gnitsians LIBPROGRAMS progs LIBLIBRARIES Textutils Ulrich
14324 @c LocalWords: Matzigkeit Drepper's Gord Matzigkeit's jm Dalley Debian org
14325 @c LocalWords: Administrivia ILU CORBA Sourceware Molenda sourceware Elliston
14326 @c LocalWords: dep Oliva Akim Demaille Aiieeee Demaillator Akim's sourcequake
14327 @c LocalWords: grep backported screenshots libgcj KB unnumberedsubsubsec pre
14328 @c LocalWords: precomputing hacky makedepend inline clearmake LD PRELOAD Rel
14329 @c LocalWords: syscalls perlhist acl pm multitable headitem fdl appendixsec
14330 @c LocalWords: LTALLOCA MALLOC malloc memcmp strdup alloca libcompat xyz DFOO
14331 @c LocalWords: unprefixed buildable preprocessed DBAZ DDATADIR WARNINGCFLAGS
14332 @c LocalWords: LIBFOOCFLAGS LIBFOOLDFLAGS ftable testSubDir obj LIBTOOLFLAGS
14333 @c LocalWords: barexec Pinard's automatize initialize lzip lzma xz cscope