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{]}
20 This manual is for @acronym{GNU} Automake (version @value{VERSION},
21 @value{UPDATED}), a program that creates GNU standards-compliant
22 Makefiles from template files.
24 Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
25 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
28 Permission is granted to copy, distribute and/or modify this document
29 under the terms of the @acronym{GNU} Free Documentation License,
30 Version 1.2 or any later version published by the Free Software
31 Foundation; with no Invariant Sections, with no Front-Cover texts,
32 and with no Back-Cover Texts. A copy of the license is included in the
33 section entitled ``@acronym{GNU} Free Documentation License.''
38 @c info Automake points to the Automake package's documentation
39 @c info automake points to the automake script's documentation
40 @c (Autoconf has a similar setup.)
41 @dircategory Software development
43 * Automake: (automake). Making GNU standards-compliant Makefiles.
46 @dircategory Individual utilities
48 * aclocal: (automake)Invoking aclocal. Generating aclocal.m4.
49 * automake: (automake)Invoking Automake. 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
64 @c We use the following macros to define indices:
65 @c @cindex concepts, and anything that does not fit elsewhere
66 @c @vindex Makefile variables
68 @c @acindex Autoconf/Automake/Libtool/M4/... macros
69 @c @opindex tool options
71 @c Define an index of configure macros.
73 @c Define an index of options.
75 @c Define an index of targets.
77 @c Define an index of commands.
80 @c Put the macros in the function index.
83 @c Put everything else into one index (arbitrarily chosen to be the concept index).
90 @comment node-name, next, previous, up
96 * Introduction:: Automake's purpose
97 * Autotools Introduction:: An Introduction to the Autotools
98 * Generalities:: General ideas
99 * Examples:: Some example packages
100 * Invoking Automake:: Creating a Makefile.in
101 * configure:: Scanning configure.ac or configure.in
102 * Directories:: Declaring subdirectories
103 * Programs:: Building programs and libraries
104 * Other objects:: Other derived objects
105 * Other GNU Tools:: Other GNU Tools
106 * Documentation:: Building documentation
107 * Install:: What gets installed
108 * Clean:: What gets cleaned
109 * Dist:: What goes in a distribution
110 * Tests:: Support for test suites
111 * Rebuilding:: Automatic rebuilding of Makefile
112 * Options:: Changing Automake's behavior
113 * Miscellaneous:: Miscellaneous rules
114 * Include:: Including extra files in an Automake template.
115 * Conditionals:: Conditionals
116 * Gnits:: The effect of @option{--gnu} and @option{--gnits}
117 * Cygnus:: The effect of @option{--cygnus}
118 * Not Enough:: When Automake is not Enough
119 * Distributing:: Distributing the Makefile.in
120 * API versioning:: About compatibility between Automake versions
121 * Upgrading:: Upgrading to a Newer Automake Version
122 * FAQ:: Frequently Asked Questions
123 * History:: Notes about the history of Automake
124 * Copying This Manual:: How to make copies of this manual
125 * Indices:: Indices of variables, macros, and concepts
128 --- The Detailed Node Listing ---
130 An Introduction to the Autotools
132 * GNU Build System:: Introducing the GNU Build System
133 * Use Cases:: Use Cases for the GNU Build System
134 * Why Autotools:: How Autotools Help
135 * Hello World:: A Small Hello World Package
137 Use Cases for the GNU Build System
139 * Basic Installation:: Common installation procedure
140 * Standard Targets:: A list of standard Makefile targets
141 * Standard Directory Variables:: A list of standard directory variables
142 * Standard Configuration Variables:: Using configuration variables
143 * config.site:: Using a config.site file
144 * VPATH Builds:: Parallel build trees
145 * Two-Part Install:: Installing data and programs separately
146 * Cross-Compilation:: Building for other architectures
147 * Renaming:: Renaming programs at install time
148 * DESTDIR:: Building binary packages with DESTDIR
149 * Preparing Distributions:: Rolling out tarballs
150 * Dependency Tracking:: Automatic dependency tracking
151 * Nested Packages:: The GNU Build Systems can be nested
155 * Creating amhello:: Create @file{amhello-1.0.tar.gz} from scratch
156 * amhello Explained:: @file{configure.ac} and @file{Makefile.am} explained
160 * General Operation:: General operation of Automake
161 * Strictness:: Standards conformance checking
162 * Uniform:: The Uniform Naming Scheme
163 * Canonicalization:: How derived variables are named
164 * User Variables:: Variables reserved for the user
165 * Auxiliary Programs:: Programs automake might require
167 Some example packages
169 * Complete:: A simple example, start to finish
170 * true:: Building true and false
172 Scanning @file{configure.ac}
174 * Requirements:: Configuration requirements
175 * Optional:: Other things Automake recognizes
176 * Invoking aclocal:: Auto-generating aclocal.m4
177 * Macros:: Autoconf macros supplied with Automake
179 Auto-generating aclocal.m4
181 * aclocal options:: Options supported by aclocal
182 * Macro search path:: How aclocal finds .m4 files
183 * Extending aclocal:: Writing your own aclocal macros
184 * Local Macros:: Organizing local macros
185 * Serials:: Serial lines in Autoconf macros
186 * Future of aclocal:: aclocal's scheduled death
188 Autoconf macros supplied with Automake
190 * Public macros:: Macros that you can use.
191 * Obsolete macros:: Macros that you should stop using.
192 * Private macros:: Macros that you should not use.
196 * Subdirectories:: Building subdirectories recursively
197 * Conditional Subdirectories:: Conditionally not building directories
198 * Alternative:: Subdirectories without recursion
199 * Subpackages:: Nesting packages
201 Building Programs and Libraries
203 * A Program:: Building a program
204 * A Library:: Building a library
205 * A Shared Library:: Building a Libtool library
206 * Program and Library Variables:: Variables controlling program and
208 * Default _SOURCES:: Default source files
209 * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
210 * Program variables:: Variables used when building a program
211 * Yacc and Lex:: Yacc and Lex support
212 * C++ Support:: Compiling C++ sources
213 * Objective C Support:: Compiling Objective C sources
214 * Unified Parallel C Support:: Compiling Unified Parallel C sources
215 * Assembly Support:: Compiling assembly sources
216 * Fortran 77 Support:: Compiling Fortran 77 sources
217 * Fortran 9x Support:: Compiling Fortran 9x sources
218 * Java Support:: Compiling Java sources
219 * Support for Other Languages:: Compiling other languages
220 * ANSI:: Automatic de-ANSI-fication (obsolete)
221 * Dependencies:: Automatic dependency tracking
222 * EXEEXT:: Support for executable extensions
226 * Program Sources:: Defining program sources
227 * Linking:: Linking with libraries or extra objects
228 * Conditional Sources:: Handling conditional sources
229 * Conditional Programs:: Building program conditionally
231 Building a Shared Library
233 * Libtool Concept:: Introducing Libtool
234 * Libtool Libraries:: Declaring Libtool Libraries
235 * Conditional Libtool Libraries:: Building Libtool Libraries Conditionally
236 * Conditional Libtool Sources:: Choosing Library Sources Conditionally
237 * Libtool Convenience Libraries:: Building Convenience Libtool Libraries
238 * Libtool Modules:: Building Libtool Modules
239 * Libtool Flags:: Using _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS
240 * LTLIBOBJS:: Using $(LTLIBOBJS) and $(LTALLOCA)
241 * Libtool Issues:: Common Issues Related to Libtool's Use
245 * Preprocessing Fortran 77:: Preprocessing Fortran 77 sources
246 * Compiling Fortran 77 Files:: Compiling Fortran 77 sources
247 * Mixing Fortran 77 With C and C++:: Mixing Fortran 77 With C and C++
249 Mixing Fortran 77 With C and C++
251 * How the Linker is Chosen:: Automatic linker selection
255 * Compiling Fortran 9x Files:: Compiling Fortran 9x sources
257 Other Derived Objects
259 * Scripts:: Executable scripts
260 * Headers:: Header files
261 * Data:: Architecture-independent data files
262 * Sources:: Derived sources
266 * Built sources example:: Several ways to handle built sources.
270 * Emacs Lisp:: Emacs Lisp
276 Building documentation
279 * Man pages:: Man pages
283 * Tags:: Interfacing to etags and mkid
284 * Suffixes:: Handling new file extensions
285 * Multilibs:: Support for multilibs.
287 When Automake Isn't Enough
289 * Extending:: Adding new rules or overriding existing ones.
290 * Third-Party Makefiles:: Integrating Non-Automake @file{Makefile}s.
292 Frequently Asked Questions about Automake
294 * CVS:: CVS and generated files
295 * maintainer-mode:: missing and AM_MAINTAINER_MODE
296 * wildcards:: Why doesn't Automake support wildcards?
297 * limitations on file names:: Limitations on source and installed file names
298 * distcleancheck:: Files left in build directory after distclean
299 * Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS
300 * renamed objects:: Why are object files sometimes renamed?
301 * Per-Object Flags:: How to simulate per-object flags?
302 * Multiple Outputs:: Writing rules for tools with many output files
303 * Hard-Coded Install Paths:: Installing to Hard-Coded Locations
307 * Timeline:: The Automake story.
308 * Dependency Tracking Evolution:: Evolution of Automatic Dependency Tracking
309 * Releases:: Statistics about Automake Releases
313 * GNU Free Documentation License:: License for copying this manual
317 * Macro Index:: Index of Autoconf macros
318 * Variable Index:: Index of Makefile variables
319 * General Index:: General index
328 @chapter Introduction
330 Automake is a tool for automatically generating @file{Makefile.in}s
331 from files called @file{Makefile.am}. Each @file{Makefile.am} is
332 basically a series of @command{make} variable
333 definitions@footnote{These variables are also called @dfn{make macros}
334 in Make terminology, however in this manual we reserve the term
335 @dfn{macro} for Autoconf's macros.}, with rules being thrown in
336 occasionally. The generated @file{Makefile.in}s are compliant with
337 the GNU Makefile standards.
339 @cindex GNU Makefile standards
341 The GNU Makefile Standards Document
342 (@pxref{Makefile Conventions, , , standards, The GNU Coding Standards})
343 is long, complicated, and subject to change. The goal of Automake is to
344 remove the burden of Makefile maintenance from the back of the
345 individual GNU maintainer (and put it on the back of the Automake
348 The typical Automake input file is simply a series of variable definitions.
349 Each such file is processed to create a @file{Makefile.in}. There
350 should generally be one @file{Makefile.am} per directory of a project.
352 @cindex Constraints of Automake
353 @cindex Automake constraints
355 Automake does constrain a project in certain ways; for instance, it
356 assumes that the project uses Autoconf (@pxref{Top, , Introduction,
357 autoconf, The Autoconf Manual}), and enforces certain restrictions on
358 the @file{configure.ac} contents@footnote{Older Autoconf versions used
359 @file{configure.in}. Autoconf 2.50 and greater promotes
360 @file{configure.ac} over @file{configure.in}. The rest of this
361 documentation will refer to @file{configure.ac}, but Automake also
362 supports @file{configure.in} for backward compatibility.}.
364 @cindex Automake requirements
365 @cindex Requirements, Automake
367 Automake requires @command{perl} in order to generate the
368 @file{Makefile.in}s. However, the distributions created by Automake are
369 fully GNU standards-compliant, and do not require @command{perl} in order
372 @cindex Bugs, reporting
373 @cindex Reporting bugs
374 @cindex E-mail, bug reports
376 Mail suggestions and bug reports for Automake to
377 @email{bug-automake@@gnu.org}.
379 @node Autotools Introduction
380 @chapter An Introduction to the Autotools
382 If you are new to Automake, maybe you know that it is part of a set of
383 tools called @emph{The Autotools}. Maybe you've already delved into a
384 package full of files named @file{configure}, @file{configure.ac},
385 @file{Makefile.in}, @file{Makefile.am}, @file{aclocal.m4}, @dots{},
386 some of them claiming to be @emph{generated by} Autoconf or Automake.
387 But the exact purpose of these files and their relations is probably
388 fuzzy. The goal of this chapter is to introduce you to this machinery,
389 to show you how it works and how powerful it is. If you've never
390 installed or seen such a package, do not worry: this chapter will walk
393 If you need some teaching material, more illustrations, or a less
394 @command{automake}-centered continuation, some slides for this
395 introduction are available in Alexandre Duret-Lutz's
396 @uref{http://www-src.lip6.fr/@/~Alexandre.Duret-Lutz/@/autotools.html,
398 This chapter is the written version of the first part of his tutorial.
401 * GNU Build System:: Introducing the GNU Build System
402 * Use Cases:: Use Cases for the GNU Build System
403 * Why Autotools:: How Autotools Help
404 * Hello World:: A Small Hello World Package
407 @node GNU Build System
408 @section Introducing the GNU Build System
409 @cindex GNU Build System, introduction
411 It is a truth universally acknowledged, that a developer in
412 possession of a new package, must be in want of a build system.
414 In the Unix world, such a build system is traditionally achieved using
415 the command @command{make} (@pxref{Top, , Overview, make, The GNU Make
416 Manual}). The developer expresses the recipe to build his package in
417 a @file{Makefile}. This file is a set of rules to build the files in
418 the package. For instance the program @file{prog} may be built by
419 running the linker on the files @file{main.o}, @file{foo.o}, and
420 @file{bar.o}; the file @file{main.o} may be built by running the
421 compiler on @file{main.c}; etc. Each time @command{make} is run, it
422 reads @file{Makefile}, checks the existence and modification time of
423 the files mentioned, decides what files need to be built (or rebuilt),
424 and runs the associated commands.
426 When a package needs to be built on a different platform than the one
427 it was developed on, its @file{Makefile} usually needs to be adjusted.
428 For instance the compiler may have another name or require more
429 options. In 1991, David J. MacKenzie got tired of customizing
430 @file{Makefile} for the 20 platforms he had to deal with. Instead, he
431 handcrafted a little shell script called @file{configure} to
432 automatically adjust the @file{Makefile} (@pxref{Genesis, , Genesis,
433 autoconf, The Autoconf Manual}). Compiling his package was now
434 as simple as running @code{./configure && make}.
436 @cindex GNU Coding Standards
438 Today this process has been standardized in the GNU project. The GNU
439 Coding Standards (@pxref{Managing Releases, The Release Process, ,
440 standards, The GNU Coding Standards}) explains how each package of the
441 GNU project should have a @file{configure} script, and the minimal
442 interface it should have. The @file{Makefile} too should follow some
443 established conventions. The result? A unified build system that
444 makes all packages almost indistinguishable by the installer. In its
445 simplest scenario, all the installer has to do is to unpack the
446 package, run @code{./configure && make && make install}, and repeat
447 with the next package to install.
449 We call this build system the @dfn{GNU Build System}, since it was
450 grown out of the GNU project. However it is used by a vast number of
451 other packages: following any existing convention has its advantages.
453 @cindex Autotools, introduction
455 The Autotools are tools that will create a GNU Build System for your
456 package. Autoconf mostly focuses on @file{configure} and Automake on
457 @file{Makefile}s. It is entirely possible to create a GNU Build
458 System without the help of these tools. However it is rather
459 burdensome and error-prone. We will discuss this again after some
460 illustration of the GNU Build System in action.
463 @section Use Cases for the GNU Build System
464 @cindex GNU Build System, use cases
465 @cindex GNU Build System, features
466 @cindex Features of the GNU Build System
467 @cindex Use Cases for the GNU Build System
468 @cindex @file{amhello-1.0.tar.gz}, location
469 @cindex @file{amhello-1.0.tar.gz}, use cases
471 In this section we explore several use cases for the GNU Build System.
472 You can replay all these examples on the @file{amhello-1.0.tar.gz}
473 package distributed with Automake. If Automake is installed on your
474 system, you should find a copy of this file in
475 @file{@var{prefix}/share/doc/automake/amhello-1.0.tar.gz}, where
476 @var{prefix} is the installation prefix specified during configuration
477 (@var{prefix} defaults to @file{/usr/local}, however if Automake was
478 installed by some GNU/Linux distribution it most likely has been set
479 to @file{/usr}). If you do not have a copy of Automake installed,
480 you can find a copy of this file inside the @file{doc/} directory of
481 the Automake package.
483 Some of the following use cases present features that are in fact
484 extensions to the GNU Build System. Read: they are not specified by
485 the GNU Coding Standards, but they are nonetheless part of the build
486 system created by the Autotools. To keep things simple, we do not
487 point out the difference. Our objective is to show you many of the
488 features that the build system created by the Autotools will offer to
492 * Basic Installation:: Common installation procedure
493 * Standard Targets:: A list of standard Makefile targets
494 * Standard Directory Variables:: A list of standard directory variables
495 * Standard Configuration Variables:: Using configuration variables
496 * config.site:: Using a config.site file
497 * VPATH Builds:: Parallel build trees
498 * Two-Part Install:: Installing data and programs separately
499 * Cross-Compilation:: Building for other architectures
500 * Renaming:: Renaming programs at install time
501 * DESTDIR:: Building binary packages with DESTDIR
502 * Preparing Distributions:: Rolling out tarballs
503 * Dependency Tracking:: Automatic dependency tracking
504 * Nested Packages:: The GNU Build Systems can be nested
507 @node Basic Installation
508 @subsection Basic Installation
509 @cindex Configuration, basics
510 @cindex Installation, basics
511 @cindex GNU Build System, basics
513 The most common installation procedure looks as follows.
516 ~ % @kbd{tar zxf amhello-1.0.tar.gz}
517 ~ % @kbd{cd amhello-1.0}
518 ~/amhello-1.0 % @kbd{./configure}
520 config.status: creating Makefile
521 config.status: creating src/Makefile
523 ~/amhello-1.0 % @kbd{make}
525 ~/amhello-1.0 % @kbd{make check}
527 ~/amhello-1.0 % @kbd{su}
529 /home/adl/amhello-1.0 # @kbd{make install}
531 /home/adl/amhello-1.0 # @kbd{exit}
532 ~/amhello-1.0 % @kbd{make installcheck}
538 The user first unpacks the package. Here, and in the following
539 examples, we will use the non-portable @code{tar zxf} command for
540 simplicity. On a system without GNU @command{tar} installed, this
541 command should read @code{gunzip -c amhello-1.0.tar.gz | tar xf -}.
543 The user then enters the newly created directory to run the
544 @file{configure} script. This script probes the system for various
545 features, and finally creates the @file{Makefile}s. In this toy
546 example there are only two @file{Makefile}s, but in real-world projects,
547 there may be many more, usually one @file{Makefile} per directory.
549 It is now possible to run @code{make}. This will construct all the
550 programs, libraries, and scripts that need to be constructed for the
551 package. In our example, this compiles the @file{hello} program.
552 All files are constructed in place, in the source tree; we will see
553 later how this can be changed.
555 @code{make check} causes the package's tests to be run. This step is
556 not mandatory, but it is often good to make sure the programs that
557 have been built behave as they should, before you decide to install
558 them. Our example does not contain any tests, so running @code{make
561 @cindex su, before @code{make install}
562 After everything has been built, and maybe tested, it is time to
563 install it on the system. That means copying the programs,
564 libraries, header files, scripts, and other data files from the
565 source directory to their final destination on the system. The
566 command @code{make install} will do that. However, by default
567 everything will be installed in subdirectories of @file{/usr/local}:
568 binaries will go into @file{/usr/local/bin}, libraries will end up in
569 @file{/usr/local/lib}, etc. This destination is usually not writable
570 by any user, so we assume that we have to become root before we can
571 run @code{make install}. In our example, running @code{make install}
572 will copy the program @file{hello} into @file{/usr/local/bin}
573 and @file{README} into @file{/usr/local/share/doc/amhello}.
575 A last and optional step is to run @code{make installcheck}. This
576 command may run tests on the installed files. @code{make check} tests
577 the files in the source tree, while @code{make installcheck} tests
578 their installed copies. The tests run by the latter can be different
579 from those run by the former. For instance, there are tests that
580 cannot be run in the source tree. Conversely, some packages are set
581 up so that @code{make installcheck} will run the very same tests as
582 @code{make check}, only on different files (non-installed
583 vs.@: installed). It can make a difference, for instance when the
584 source tree's layout is different from that of the installation.
585 Furthermore it may help to diagnose an incomplete installation.
587 Presently most packages do not have any @code{installcheck} tests
588 because the existence of @code{installcheck} is little known, and its
589 usefulness is neglected. Our little toy package is no better: @code{make
590 installcheck} does nothing.
592 @node Standard Targets
593 @subsection Standard @file{Makefile} Targets
595 So far we have come across four ways to run @command{make} in the GNU
596 Build System: @code{make}, @code{make check}, @code{make install}, and
597 @code{make installcheck}. The words @code{check}, @code{install}, and
598 @code{installcheck}, passed as arguments to @command{make}, are called
599 @dfn{targets}. @code{make} is a shorthand for @code{make all},
600 @code{all} being the default target in the GNU Build System.
602 Here is a list of the most useful targets that the GNU Coding Standards
608 Build programs, libraries, documentation, etc.@: (same as @code{make}).
611 Install what needs to be installed, copying the files from the
612 package's tree to system-wide directories.
613 @item make install-strip
614 @trindex install-strip
615 Same as @code{make install}, then strip debugging symbols. Some
616 users like to trade space for useful bug reports@enddots{}
619 The opposite of @code{make install}: erase the installed files.
620 (This needs to be run from the same build tree that was installed.)
623 Erase from the build tree the files built by @code{make all}.
626 Additionally erase anything @code{./configure} created.
629 Run the test suite, if any.
630 @item make installcheck
631 @trindex installcheck
632 Check the installed programs or libraries, if supported.
635 Recreate @file{@var{package}-@var{version}.tar.gz} from all the source
639 @node Standard Directory Variables
640 @subsection Standard Directory Variables
641 @cindex directory variables
643 The GNU Coding Standards also specify a hierarchy of variables to
644 denote installation directories. Some of these are:
646 @multitable {Directory variable} {@code{$@{datarootdir@}/doc/$@{PACKAGE@}}}
647 @headitem Directory variable @tab Default value
648 @item @code{prefix} @tab @code{/usr/local}
649 @item @w{@ @ @code{exec_prefix}} @tab @code{$@{prefix@}}
650 @item @w{@ @ @ @ @code{bindir}} @tab @code{$@{exec_prefix@}/bin}
651 @item @w{@ @ @ @ @code{libdir}} @tab @code{$@{exec_prefix@}/lib}
652 @item @w{@ @ @ @ @dots{}}
653 @item @w{@ @ @code{includedir}} @tab @code{$@{prefix@}/include}
654 @item @w{@ @ @code{datarootdir}} @tab @code{$@{prefix@}/share}
655 @item @w{@ @ @ @ @code{datadir}} @tab @code{$@{datarootdir@}}
656 @item @w{@ @ @ @ @code{mandir}} @tab @code{$@{datarootdir@}/man}
657 @item @w{@ @ @ @ @code{infodir}} @tab @code{$@{datarootdir@}/info}
658 @item @w{@ @ @ @ @code{docdir}} @tab @code{$@{datarootdir@}/doc/$@{PACKAGE@}}
659 @item @w{@ @ @dots{}}
662 @c We should provide a complete table somewhere, but not here. The
663 @c complete list of directory variables it too confusing as-is. It
664 @c requires some explanations that are too complicated for this
665 @c introduction. Besides listing directories like localstatedir
666 @c would make the explanations in ``Two-Part Install'' harder.
668 Each of these directories has a role which is often obvious from its
669 name. In a package, any installable file will be installed in one of
670 these directories. For instance in @code{amhello-1.0}, the program
671 @file{hello} is to be installed in @var{bindir}, the directory for
672 binaries. The default value for this directory is
673 @file{/usr/local/bin}, but the user can supply a different value when
674 calling @command{configure}. Also the file @file{README} will be
675 installed into @var{docdir}, which defaults to
676 @file{/usr/local/share/doc/amhello}.
680 A user who wishes to install a package on his own account could proceed
684 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr}
686 ~/amhello-1.0 % @kbd{make}
688 ~/amhello-1.0 % @kbd{make install}
692 This would install @file{~/usr/bin/hello} and
693 @file{~/usr/share/doc/amhello/README}.
695 The list of all such directory options is shown by
696 @code{./configure --help}.
698 @node Standard Configuration Variables
699 @subsection Standard Configuration Variables
700 @cindex configuration variables, overriding
702 The GNU Coding Standards also define a set of standard configuration
703 variables used during the build. Here are some:
712 @item @code{CXXFLAGS}
716 @item @code{CPPFLAGS}
717 C/C++ preprocessor flags
721 @command{configure} usually does a good job at setting appropriate
722 values for these variables, but there are cases where you may want to
723 override them. For instance you may have several versions of a
724 compiler installed and would like to use another one, you may have
725 header files installed outside the default search path of the
726 compiler, or even libraries out of the way of the linker.
728 Here is how one would call @command{configure} to force it to use
729 @command{gcc-3} as C compiler, use header files from
730 @file{~/usr/include} when compiling, and libraries from
731 @file{~/usr/lib} when linking.
734 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr CC=gcc-3 \
735 CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib}
738 Again, a full list of these variables appears in the output of
739 @code{./configure --help}.
742 @subsection Overriding Default Configuration Setting with @file{config.site}
743 @cindex @file{config.site} example
745 When installing several packages using the same setup, it can be
746 convenient to create a file to capture common settings.
747 If a file named @file{@var{prefix}/share/config.site} exists,
748 @command{configure} will source it at the beginning of its execution.
750 Recall the command from the previous section:
753 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr CC=gcc-3 \
754 CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib}
757 Assuming we are installing many package in @file{~/usr}, and will
758 always want to use these definitions of @code{CC}, @code{CPPFLAGS}, and
759 @code{LDFLAGS}, we can automate this by creating the following
760 @file{~/usr/share/config.site} file:
763 test -z "$CC" && CC=gcc-3
764 test -z "$CPPFLAGS" && CPPFLAGS=-I$HOME/usr/include
765 test -z "$LDFLAGS" && LDFLAGS=-L$HOME/usr/lib
768 Now, any time a @file{configure} script is using the @file{~/usr}
769 prefix, it will execute the above @file{config.site} and define
770 these three variables.
773 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr}
774 configure: loading site script /home/adl/usr/share/config.site
778 @xref{Site Defaults, , Setting Site Defaults, autoconf, The Autoconf
779 Manual}, for more information about this feature.
783 @subsection Parallel Build Trees (a.k.a.@: VPATH Builds)
784 @cindex Parallel build trees
786 @cindex source tree and build tree
787 @cindex build tree and source tree
788 @cindex trees, source vs.@: build
790 The GNU Build System distinguishes two trees: the source tree, and
793 The source tree is rooted in the directory containing
794 @file{configure}. It contains all the sources files (those that are
795 distributed), and may be arranged using several subdirectories.
797 The build tree is rooted in the directory in which @file{configure}
798 was run, and is populated with all object files, programs, libraries,
799 and other derived files built from the sources (and hence not
800 distributed). The build tree usually has the same subdirectory layout
801 as the source tree; its subdirectories are created automatically by
804 If @file{configure} is executed in its own directory, the source and
805 build trees are combined: derived files are constructed in the same
806 directories as their sources. This was the case in our first
807 installation example (@pxref{Basic Installation}).
809 A common request from users is that they want to confine all derived
810 files to a single directory, to keep their source directories
811 uncluttered. Here is how we could run @file{configure} to build
812 everything in a subdirectory called @file{build/}.
815 ~ % @kbd{tar zxf ~/amhello-1.0.tar.gz}
816 ~ % @kbd{cd amhello-1.0}
817 ~/amhello-1.0 % @kbd{mkdir build && cd build}
818 ~/amhello-1.0/build % @kbd{../configure}
820 ~/amhello-1.0/build % @kbd{make}
824 These setups, where source and build trees are different, are often
825 called @dfn{parallel builds} or @dfn{VPATH builds}. The expression
826 @emph{parallel build} is misleading: the word @emph{parallel} is a
827 reference to the way the build tree shadows the source tree, it is not
828 about some concurrency in the way build commands are run. For this
829 reason we refer to such setups using the name @emph{VPATH builds} in
830 the following. @emph{VPATH} is the name of the @command{make} feature
831 used by the @file{Makefile}s to allow these builds (@pxref{General
832 Search, , @code{VPATH}: Search Path for All Prerequisites, make, The
835 @cindex multiple configurations, example
836 @cindex debug build, example
837 @cindex optimized build, example
839 VPATH builds have other interesting uses. One is to build the same
840 sources with multiple configurations. For instance:
843 ~ % @kbd{tar zxf ~/amhello-1.0.tar.gz}
844 ~ % @kbd{cd amhello-1.0}
845 ~/amhello-1.0 % @kbd{mkdir debug optim && cd debug}
846 ~/amhello-1.0/debug % @kbd{../configure CFLAGS='-g -O0'}
848 ~/amhello-1.0/debug % @kbd{make}
850 ~/amhello-1.0/debug % cd ../optim
851 ~/amhello-1.0/optim % @kbd{../configure CFLAGS='-O3 -fomit-frame-pointer'}
853 ~/amhello-1.0/optim % @kbd{make}
857 With network file systems, a similar approach can be used to build the
858 same sources on different machines. For instance, suppose that the
859 sources are installed on a directory shared by two hosts: @code{HOST1}
860 and @code{HOST2}, which may be different platforms.
863 ~ % @kbd{cd /nfs/src}
864 /nfs/src % @kbd{tar zxf ~/amhello-1.0.tar.gz}
867 On the first host, you could create a local build directory:
869 [HOST1] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
870 [HOST1] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure}
872 [HOST1] /tmp/amh % @kbd{make && sudo make install}
877 (Here we assume the that installer has configured @command{sudo} so it
878 can execute @code{make install} with root privileges; it is more convenient
879 than using @command{su} like in @ref{Basic Installation}).
881 On the second host, you would do exactly the same, possibly at
884 [HOST2] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
885 [HOST2] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure}
887 [HOST2] /tmp/amh % @kbd{make && sudo make install}
891 @cindex read-only source tree
892 @cindex source tree, read-only
894 In this scenario, nothing forbids the @file{/nfs/src/amhello-1.0}
895 directory from being read-only. In fact VPATH builds are also a means
896 of building packages from a read-only medium such as a CD-ROM. (The
897 FSF used to sell CD-ROM with unpacked source code, before the GNU
898 project grew so big.)
900 @node Two-Part Install
901 @subsection Two-Part Installation
903 In our last example (@pxref{VPATH Builds}), a source tree was shared
904 by two hosts, but compilation and installation were done separately on
907 The GNU Build System also supports networked setups where part of the
908 installed files should be shared amongst multiple hosts. It does so
909 by distinguishing architecture-dependent files from
910 architecture-independent files, and providing two @file{Makefile}
911 targets to install each of these classes of files.
913 @trindex install-exec
914 @trindex install-data
916 These targets are @code{install-exec} for architecture-dependent files
917 and @code{install-data} for architecture-independent files.
918 The command we used up to now, @code{make install}, can be thought of
919 as a shorthand for @code{make install-exec install-data}.
921 From the GNU Build System point of view, the distinction between
922 architecture-dependent files and architecture-independent files is
923 based exclusively on the directory variable used to specify their
924 installation destination. In the list of directory variables we
925 provided earlier (@pxref{Standard Directory Variables}), all the
926 variables based on @var{exec-prefix} designate architecture-dependent
927 directories whose files will be installed by @code{make install-exec}.
928 The others designate architecture-independent directories and will
929 serve files installed by @code{make install-data}. @xref{Install},
932 Here is how we could revisit our two-host installation example,
933 assuming that (1) we want to install the package directly in
934 @file{/usr}, and (2) the directory @file{/usr/share} is shared by the
937 On the first host we would run
939 [HOST1] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
940 [HOST1] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure --prefix /usr}
942 [HOST1] /tmp/amh % @kbd{make && sudo make install}
946 On the second host, however, we need only install the
947 architecture-specific files.
949 [HOST2] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
950 [HOST2] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure --prefix /usr}
952 [HOST2] /tmp/amh % @kbd{make && sudo make install-exec}
956 In packages that have installation checks, it would make sense to run
957 @code{make installcheck} (@pxref{Basic Installation}) to verify that
958 the package works correctly despite the apparent partial installation.
960 @node Cross-Compilation
961 @subsection Cross-Compilation
962 @cindex cross-compilation
964 To @dfn{cross-compile} is to build on one platform a binary that will
965 run on another platform. When speaking of cross-compilation, it is
966 important to distinguish between the @dfn{build platform} on which
967 the compilation is performed, and the @dfn{host platform} on which the
968 resulting executable is expected to run. The following
969 @command{configure} options are used to specify each of them:
972 @item --build=@var{BUILD}
973 @opindex --build=@var{BUILD}
974 The system on which the package is built.
975 @item --host=@var{HOST}
976 @opindex --host=@var{HOST}
977 The system where built programs and libraries will run.
980 When the @option{--host} is used, @command{configure} will search for
981 the cross-compiling suite for this platform. Cross-compilation tools
982 commonly have their target architecture as prefix of their name. For
983 instance my cross-compiler for MinGW32 has its binaries called
984 @code{i586-mingw32msvc-gcc}, @code{i586-mingw32msvc-ld},
985 @code{i586-mingw32msvc-as}, etc.
987 @cindex MinGW cross-compilation example
988 @cindex cross-compilation example
990 Here is how we could build @code{amhello-1.0} for
991 @code{i586-mingw32msvc} on a GNU/Linux PC.
994 ~/amhello-1.0 % @kbd{./configure --build i686-pc-linux-gnu --host i586-mingw32msvc}
995 checking for a BSD-compatible install... /usr/bin/install -c
996 checking whether build environment is sane... yes
997 checking for gawk... gawk
998 checking whether make sets $(MAKE)... yes
999 checking for i586-mingw32msvc-strip... i586-mingw32msvc-strip
1000 checking for i586-mingw32msvc-gcc... i586-mingw32msvc-gcc
1001 checking for C compiler default output file name... a.exe
1002 checking whether the C compiler works... yes
1003 checking whether we are cross compiling... yes
1004 checking for suffix of executables... .exe
1005 checking for suffix of object files... o
1006 checking whether we are using the GNU C compiler... yes
1007 checking whether i586-mingw32msvc-gcc accepts -g... yes
1008 checking for i586-mingw32msvc-gcc option to accept ANSI C...
1010 ~/amhello-1.0 % @kbd{make}
1012 ~/amhello-1.0 % @kbd{cd src; file hello.exe}
1013 hello.exe: MS Windows PE 32-bit Intel 80386 console executable not relocatable
1016 The @option{--host} and @option{--build} options are usually all we
1017 need for cross-compiling. The only exception is if the package being
1018 built is itself a cross-compiler: we need a third option to specify
1019 its target architecture.
1022 @item --target=@var{TARGET}
1023 @opindex --target=@var{TARGET}
1024 When building compiler tools: the system for which the tools will
1028 For instance when installing GCC, the GNU Compiler Collection, we can
1029 use @option{--target=@var{TARGET}} to specify that we want to build
1030 GCC as a cross-compiler for @var{TARGET}. Mixing @option{--build} and
1031 @option{--target}, we can actually cross-compile a cross-compiler;
1032 such a three-way cross-compilation is known as a @dfn{Canadian cross}.
1034 @xref{Specifying Names, , Specifying the System Type, autoconf, The
1035 Autoconf Manual}, for more information about these @command{configure}
1039 @subsection Renaming Programs at Install Time
1040 @cindex Renaming programs
1041 @cindex Transforming program names
1042 @cindex Programs, renaming during installation
1044 The GNU Build System provides means to automatically rename
1045 executables and manpages before they are installed (@pxref{Man pages}).
1046 This is especially convenient
1047 when installing a GNU package on a system that already has a
1048 proprietary implementation you do not want to overwrite. For instance,
1049 you may want to install GNU @command{tar} as @command{gtar} so you can
1050 distinguish it from your vendor's @command{tar}.
1052 This can be done using one of these three @command{configure} options.
1055 @item --program-prefix=@var{PREFIX}
1056 @opindex --program-prefix=@var{PREFIX}
1057 Prepend @var{PREFIX} to installed program names.
1058 @item --program-suffix=@var{SUFFIX}
1059 @opindex --program-suffix=@var{SUFFIX}
1060 Append @var{SUFFIX} to installed program names.
1061 @item --program-transform-name=@var{PROGRAM}
1062 @opindex --program-transform-name=@var{PROGRAM}
1063 Run @code{sed @var{PROGRAM}} on installed program names.
1066 The following commands would install @file{hello}
1067 as @file{/usr/local/bin/test-hello}, for instance.
1070 ~/amhello-1.0 % @kbd{./configure --program-prefix test-}
1072 ~/amhello-1.0 % @kbd{make}
1074 ~/amhello-1.0 % @kbd{sudo make install}
1079 @subsection Building Binary Packages Using DESTDIR
1082 The GNU Build System's @code{make install} and @code{make uninstall}
1083 interface does not exactly fit the needs of a system administrator
1084 who has to deploy and upgrade packages on lots of hosts. In other
1085 words, the GNU Build System does not replace a package manager.
1087 Such package managers usually need to know which files have been
1088 installed by a package, so a mere @code{make install} is
1091 @cindex Staged installation
1093 The @code{DESTDIR} variable can be used to perform a staged
1094 installation. The package should be configured as if it was going to
1095 be installed in its final location (e.g., @code{--prefix /usr}), but
1096 when running @code{make install}, the @code{DESTDIR} should be set to
1097 the absolute name of a directory into which the installation will be
1098 diverted. From this directory it is easy to review which files are
1099 being installed where, and finally copy them to their final location
1102 @cindex Binary package
1104 For instance here is how we could create a binary package containing a
1105 snapshot of all the files to be installed.
1108 ~/amhello-1.0 % @kbd{./configure --prefix /usr}
1110 ~/amhello-1.0 % @kbd{make}
1112 ~/amhello-1.0 % @kbd{make DESTDIR=$HOME/inst install}
1114 ~/amhello-1.0 % @kbd{cd ~/inst}
1115 ~/inst % @kbd{find . -type f -print > ../files.lst}
1116 ~/inst % @kbd{tar zcvf ~/amhello-1.0-i686.tar.gz `cat ../file.lst`}
1118 ./usr/share/doc/amhello/README
1121 After this example, @code{amhello-1.0-i686.tar.gz} is ready to be
1122 uncompressed in @file{/} on many hosts. (Using @code{`cat ../file.lst`}
1123 instead of @samp{.} as argument for @command{tar} avoids entries for
1124 each subdirectory in the archive: we would not like @command{tar} to
1125 restore the modification time of @file{/}, @file{/usr/}, etc.)
1127 Note that when building packages for several architectures, it might
1128 be convenient to use @code{make install-data} and @code{make
1129 install-exec} (@pxref{Two-Part Install}) to gather
1130 architecture-independent files in a single package.
1132 @xref{Install}, for more information.
1134 @c We should document PRE_INSTALL/POST_INSTALL/NORMAL_INSTALL and their
1135 @c UNINSTALL counterparts.
1137 @node Preparing Distributions
1138 @subsection Preparing Distributions
1139 @cindex Preparing distributions
1140 @cindex Packages, preparation
1141 @cindex Distributions, preparation
1143 We have already mentioned @code{make dist}. This target collects all
1144 your source files and the necessary parts of the build system to
1145 create a tarball named @file{@var{package}-@var{version}.tar.gz}.
1147 @cindex @code{distcheck} better than @code{dist}
1149 Another, more useful command is @code{make distcheck}. The
1150 @code{distcheck} target constructs
1151 @file{@var{package}-@var{version}.tar.gz} just as well as @code{dist},
1152 but it additionally ensures most of the use cases presented so far
1157 It attempts a full compilation of the package (@pxref{Basic
1158 Installation}), unpacking the newly constructed tarball, running
1159 @code{make}, @code{make check}, @code{make install}, as well as
1160 @code{make installcheck}, and even @code{make dist},
1162 it tests VPATH builds with read-only source tree (@pxref{VPATH Builds}),
1164 it makes sure @code{make clean}, @code{make distclean}, and @code{make
1165 uninstall} do not omit any file (@pxref{Standard Targets}),
1167 and it checks that @code{DESTDIR} installations work (@pxref{DESTDIR}).
1170 All of these actions are performed in a temporary subdirectory, so
1171 that no root privileges are required.
1173 Releasing a package that fails @code{make distcheck} means that one of
1174 the scenarios we presented will not work and some users will be
1175 disappointed. Therefore it is a good practice to release a package
1176 only after a successful @code{make distcheck}. This of course does
1177 not imply that the package will be flawless, but at least it will
1178 prevent some of the embarrassing errors you may find in packages
1179 released by people who have never heard about @code{distcheck} (like
1180 @code{DESTDIR} not working because of a typo, or a distributed file
1181 being erased by @code{make clean}, or even @code{VPATH} builds not
1184 @xref{Creating amhello}, to recreate @file{amhello-1.0.tar.gz} using
1185 @code{make distcheck}. @xref{Dist}, for more information about
1188 @node Dependency Tracking
1189 @subsection Automatic Dependency Tracking
1190 @cindex Dependency tracking
1192 Dependency tracking is performed as a side-effect of compilation.
1193 Each time the build system compiles a source file, it computes its
1194 list of dependencies (in C these are the header files included by the
1195 source being compiled). Later, any time @command{make} is run and a
1196 dependency appears to have changed, the dependent files will be
1199 When @command{configure} is executed, you can see it probing each
1200 compiler for the dependency mechanism it supports (several mechanisms
1204 ~/amhello-1.0 % @kbd{./configure --prefix /usr}
1206 checking dependency style of gcc... gcc3
1210 Because dependencies are only computed as a side-effect of the
1211 compilation, no dependency information exists the first time a package
1212 is built. This is OK because all the files need to be built anyway:
1213 @code{make} does not have to decide which files need to be rebuilt.
1214 In fact, dependency tracking is completely useless for one-time builds
1215 and there is a @command{configure} option to disable this:
1218 @item --disable-dependency-tracking
1219 @opindex --disable-dependency-tracking
1220 Speed up one-time builds.
1223 Some compilers do not offer any practical way to derive the list of
1224 dependencies as a side-effect of the compilation, requiring a separate
1225 run (maybe of another tool) to compute these dependencies. The
1226 performance penalty implied by these methods is important enough to
1227 disable them by default. The option @option{--enable-dependency-tracking}
1228 must be passed to @command{configure} to activate them.
1231 @item --enable-dependency-tracking
1232 @opindex --enable-dependency-tracking
1233 Do not reject slow dependency extractors.
1236 @xref{Dependency Tracking Evolution}, for some discussion about the
1237 different dependency tracking schemes used by Automake over the years.
1239 @node Nested Packages
1240 @subsection Nested Packages
1241 @cindex Nested packages
1242 @cindex Packages, nested
1245 Although nesting packages isn't something we would recommend to
1246 someone who is discovering the Autotools, it is a nice feature worthy
1247 of mention in this small advertising tour.
1249 Autoconfiscated packages (that means packages whose build system have
1250 been created by Autoconf and friends) can be nested to arbitrary
1253 A typical setup is that a package A will distribute one of the libraries
1254 it needs in a subdirectory. This library B is a complete package with
1255 its own GNU Build System. The @command{configure} script of A will
1256 run the @command{configure} script of B as part of its execution,
1257 building and installing A will also build and install B. Generating a
1258 distribution for A will also include B.
1260 It is possible to gather several package like this. GCC is a heavy
1261 user of this feature. This gives installers a single package to
1262 configure, build and install, while it allows developers to work on
1263 subpackages independently.
1265 When configuring nested packages, the @command{configure} options
1266 given to the top-level @command{configure} are passed recursively to
1267 nested @command{configure}s. A package that does not understand an
1268 option will ignore it, assuming it is meaningful to some other
1271 @opindex --help=recursive
1273 The command @code{configure --help=recursive} can be used to display
1274 the options supported by all the included packages.
1276 @xref{Subpackages}, for an example setup.
1279 @section How Autotools Help
1280 @cindex Autotools, purpose
1282 There are several reasons why you may not want to implement the GNU
1283 Build System yourself (read: write a @file{configure} script and
1284 @file{Makefile}s yourself).
1288 As we have seen, the GNU Build System has a lot of
1289 features (@pxref{Use Cases}).
1290 Some users may expect features you have not implemented because
1291 you did not need them.
1293 Implementing these features portably is difficult and exhausting.
1294 Think of writing portable shell scripts, and portable
1295 @file{Makefile}s, for systems you may not have handy. @xref{Portable
1296 Shell, , Portable Shell Programming, autoconf, The Autoconf Manual}, to
1299 You will have to upgrade your setup to follow changes to the GNU
1303 The GNU Autotools take all this burden off your back and provide:
1307 Tools to create a portable, complete, and self-contained GNU Build
1308 System, from simple instructions.
1309 @emph{Self-contained} meaning the resulting build system does not
1310 require the GNU Autotools.
1312 A central place where fixes and improvements are made:
1313 a bug-fix for a portability issue will benefit every package.
1316 Yet there also exist reasons why you may want NOT to use the
1317 Autotools@enddots{} For instance you may be already using (or used to)
1318 another incompatible build system. Autotools will only be useful if
1319 you do accept the concepts of the GNU Build System. People who have their
1320 own idea of how a build system should work will feel frustrated by the
1324 @section A Small Hello World
1325 @cindex Example Hello World
1326 @cindex Hello World example
1327 @cindex @file{amhello-1.0.tar.gz}, creation
1329 In this section we recreate the @file{amhello-1.0} package from
1330 scratch. The first subsection shows how to call the Autotools to
1331 instantiate the GNU Build System, while the second explains the
1332 meaning of the @file{configure.ac} and @file{Makefile.am} files read
1336 * Creating amhello:: Create @file{amhello-1.0.tar.gz} from scratch
1337 * amhello Explained:: @file{configure.ac} and @file{Makefile.am} explained
1340 @node Creating amhello
1341 @subsection Creating @file{amhello-1.0.tar.gz}
1343 Here is how we can recreate @file{amhello-1.0.tar.gz} from scratch.
1344 The package is simple enough so that we will only need to write 5
1345 files. (You may copy them from the final @file{amhello-1.0.tar.gz}
1346 that is distributed with Automake if you do not want to write them.)
1348 Create the following files in an empty directory.
1353 @file{src/main.c} is the source file for the @file{hello} program. We
1354 store it in the @file{src/} subdirectory, because later, when the package
1355 evolves, it will ease the addition of a @file{man/} directory for man
1356 pages, a @file{data/} directory for data files, etc.
1358 ~/amhello % @kbd{cat src/main.c}
1365 puts ("Hello World!");
1366 puts ("This is " PACKAGE_STRING ".");
1372 @file{README} contains some very limited documentation for our little
1375 ~/amhello % @kbd{cat README}
1376 This is a demonstration package for GNU Automake.
1377 Type `info Automake' to read the Automake manual.
1381 @file{Makefile.am} and @file{src/Makefile.am} contain Automake
1382 instructions for these two directories.
1385 ~/amhello % @kbd{cat src/Makefile.am}
1386 bin_PROGRAMS = hello
1387 hello_SOURCES = main.c
1388 ~/amhello % @kbd{cat Makefile.am}
1390 dist_doc_DATA = README
1394 Finally, @file{configure.ac} contains Autoconf instructions to
1395 create the @command{configure} script.
1398 ~/amhello % @kbd{cat configure.ac}
1399 AC_INIT([amhello], [1.0], [bug-automake@@gnu.org])
1400 AM_INIT_AUTOMAKE([-Wall -Werror foreign])
1402 AC_CONFIG_HEADERS([config.h])
1411 @cindex @command{autoreconf}, example
1413 Once you have these five files, it is time to run the Autotools to
1414 instantiate the build system. Do this using the @command{autoreconf}
1418 ~/amhello % @kbd{autoreconf --install}
1419 configure.ac: installing `./install-sh'
1420 configure.ac: installing `./missing'
1421 src/Makefile.am: installing `./depcomp'
1424 At this point the build system is complete.
1426 In addition to the three scripts mentioned in its output, you can see
1427 that @command{autoreconf} created four other files: @file{configure},
1428 @file{config.h.in}, @file{Makefile.in}, and @file{src/Makefile.in}.
1429 The latter three files are templates that will be adapted to the
1430 system by @command{configure} under the names @file{config.h},
1431 @file{Makefile}, and @file{src/Makefile}. Let's do this:
1434 ~/amhello % @kbd{./configure}
1435 checking for a BSD-compatible install... /usr/bin/install -c
1436 checking whether build environment is sane... yes
1437 checking for gawk... no
1438 checking for mawk... mawk
1439 checking whether make sets $(MAKE)... yes
1440 checking for gcc... gcc
1441 checking for C compiler default output file name... a.out
1442 checking whether the C compiler works... yes
1443 checking whether we are cross compiling... no
1444 checking for suffix of executables...
1445 checking for suffix of object files... o
1446 checking whether we are using the GNU C compiler... yes
1447 checking whether gcc accepts -g... yes
1448 checking for gcc option to accept ISO C89... none needed
1449 checking for style of include used by make... GNU
1450 checking dependency style of gcc... gcc3
1451 configure: creating ./config.status
1452 config.status: creating Makefile
1453 config.status: creating src/Makefile
1454 config.status: creating config.h
1455 config.status: executing depfiles commands
1459 @cindex @code{distcheck} example
1461 You can see @file{Makefile}, @file{src/Makefile}, and @file{config.h}
1462 being created at the end after @command{configure} has probed the
1463 system. It is now possible to run all the targets we wish
1464 (@pxref{Standard Targets}). For instance:
1467 ~/amhello % @kbd{make}
1469 ~/amhello % @kbd{src/hello}
1471 This is amhello 1.0.
1472 ~/amhello % @kbd{make distcheck}
1474 =============================================
1475 amhello-1.0 archives ready for distribution:
1477 =============================================
1480 Note that running @command{autoreconf} is only needed initially when
1481 the GNU Build System does not exist. When you later change some
1482 instructions in a @file{Makefile.am} or @file{configure.ac}, the
1483 relevant part of the build system will be regenerated automatically
1484 when you execute @command{make}.
1486 @command{autoreconf} is a script that calls @command{autoconf},
1487 @command{automake}, and a bunch of other commands in the right order.
1488 If you are beginning with these tools, it is not important to figure
1489 out in which order all these tools should be invoked and why. However,
1490 because Autoconf and Automake have separate manuals, the important
1491 point to understand is that @command{autoconf} is in charge of
1492 creating @file{configure} from @file{configure.ac}, while
1493 @command{automake} is in charge of creating @file{Makefile.in}s from
1494 @file{Makefile.am}s and @file{configure.ac}. This should at least
1495 direct you to the right manual when seeking answers.
1498 @node amhello Explained
1499 @subsection @file{amhello-1.0} Explained
1501 Let us begin with the contents of @file{configure.ac}.
1504 AC_INIT([amhello], [1.0], [bug-automake@@gnu.org])
1505 AM_INIT_AUTOMAKE([-Wall -Werror foreign])
1507 AC_CONFIG_HEADERS([config.h])
1515 This file is read by both @command{autoconf} (to create
1516 @file{configure}) and @command{automake} (to create the various
1517 @file{Makefile.in}s). It contains a series of M4 macros that will be
1518 expanded as shell code to finally form the @file{configure} script.
1519 We will not elaborate on the syntax of this file, because the Autoconf
1520 manual has a whole section about it (@pxref{Writing configure.ac, ,
1521 Writing @file{configure.ac}, autoconf, The Autoconf Manual}).
1523 The macros prefixed with @code{AC_} are Autoconf macros, documented
1524 in the Autoconf manual (@pxref{Autoconf Macro Index, , Autoconf Macro
1525 Index, autoconf, The Autoconf Manual}). The macros that start with
1526 @code{AM_} are Automake macros, documented later in this manual
1527 (@pxref{Macro Index}).
1529 The first two lines of @file{configure.ac} initialize Autoconf and
1530 Automake. @code{AC_INIT} takes in as parameters the name of the package,
1531 its version number, and a contact address for bug-reports about the
1532 package (this address is output at the end of @code{./configure
1533 --help}, for instance). When adapting this setup to your own package,
1534 by all means please do not blindly copy Automake's address: use the
1535 mailing list of your package, or your own mail address.
1541 The argument to @code{AM_INIT_AUTOMAKE} is a list of options for
1542 @command{automake} (@pxref{Options}). @option{-Wall} and
1543 @option{-Werror} ask @command{automake} to turn on all warnings and
1544 report them as errors. We are speaking of @strong{Automake} warnings
1545 here, such as dubious instructions in @file{Makefile.am}. This has
1546 absolutely nothing to do with how the compiler will be called, even
1547 though it may support options with similar names. Using @option{-Wall
1548 -Werror} is a safe setting when starting to work on a package: you do
1549 not want to miss any issues. Later you may decide to relax things a
1550 bit. The @option{foreign} option tells Automake that this package
1551 will not follow the GNU Standards. GNU packages should always
1552 distribute additional files such as @file{ChangeLog}, @file{AUTHORS},
1553 etc. We do not want @command{automake} to complain about these
1554 missing files in our small example.
1556 The @code{AC_PROG_CC} line causes the @command{configure} script to
1557 search for a C compiler and define the variable @code{CC} with its
1558 name. The @file{src/Makefile.in} file generated by Automake uses the
1559 variable @code{CC} to build @file{hello}, so when @command{configure}
1560 creates @file{src/Makefile} from @file{src/Makefile.in}, it will define
1561 @code{CC} with the value it has found. If Automake is asked to create
1562 a @file{Makefile.in} that uses @code{CC} but @file{configure.ac} does
1563 not define it, it will suggest you add a call to @code{AC_PROG_CC}.
1565 The @code{AC_CONFIG_HEADERS([config.h])} invocation causes the
1566 @command{configure} script to create a @file{config.h} file gathering
1567 @samp{#define}s defined by other macros in @file{configure.ac}. In our
1568 case, the @code{AC_INIT} macro already defined a few of them. Here
1569 is an excerpt of @file{config.h} after @command{configure} has run:
1573 /* Define to the address where bug reports for this package should be sent. */
1574 #define PACKAGE_BUGREPORT "bug-automake@@gnu.org"
1576 /* Define to the full name and version of this package. */
1577 #define PACKAGE_STRING "amhello 1.0"
1581 As you probably noticed, @file{src/main.c} includes @file{config.h} so
1582 it can use @code{PACKAGE_STRING}. In a real-world project,
1583 @file{config.h} can grow really big, with one @samp{#define} per
1584 feature probed on the system.
1586 The @code{AC_CONFIG_FILES} macro declares the list of files that
1587 @command{configure} should create from their @file{*.in} templates.
1588 Automake also scans this list to find the @file{Makefile.am} files it must
1589 process. (This is important to remember: when adding a new directory
1590 to your project, you should add its @file{Makefile} to this list,
1591 otherwise Automake will never process the new @file{Makefile.am} you
1592 wrote in that directory.)
1594 Finally, the @code{AC_OUTPUT} line is a closing command that actually
1595 produces the part of the script in charge of creating the files
1596 registered with @code{AC_CONFIG_HEADERS} and @code{AC_CONFIG_FILES}.
1598 @cindex @command{autoscan}
1600 When starting a new project, we suggest you start with such a simple
1601 @file{configure.ac}, and gradually add the other tests it requires.
1602 The command @command{autoscan} can also suggest a few of the tests
1603 your package may need (@pxref{autoscan Invocation, , Using
1604 @command{autoscan} to Create @file{configure.ac}, autoconf, The
1607 @cindex @file{Makefile.am}, Hello World
1609 We now turn to @file{src/Makefile.am}. This file contains
1610 Automake instructions to build and install @file{hello}.
1613 bin_PROGRAMS = hello
1614 hello_SOURCES = main.c
1617 A @file{Makefile.am} has the same syntax as an ordinary
1618 @file{Makefile}. When @command{automake} processes a
1619 @file{Makefile.am} it copies the entire file into the output
1620 @file{Makefile.in} (that will be later turned into @file{Makefile} by
1621 @command{configure}) but will react to certain variable definitions
1622 by generating some build rules and other variables.
1623 Often @file{Makefile.am}s contain only a list of variable definitions as
1624 above, but they can also contain other variable and rule definitions that
1625 @command{automake} will pass along without interpretation.
1627 Variables that end with @code{_PROGRAMS} are special variables
1628 that list programs that the resulting @file{Makefile} should build.
1629 In Automake speak, this @code{_PROGRAMS} suffix is called a
1630 @dfn{primary}; Automake recognizes other primaries such as
1631 @code{_SCRIPTS}, @code{_DATA}, @code{_LIBRARIES}, etc.@: corresponding
1632 to different types of files.
1634 The @samp{bin} part of the @code{bin_PROGRAMS} tells
1635 @command{automake} that the resulting programs should be installed in
1636 @var{bindir}. Recall that the GNU Build System uses a set of variables
1637 to denote destination directories and allow users to customize these
1638 locations (@pxref{Standard Directory Variables}). Any such directory
1639 variable can be put in front of a primary (omitting the @code{dir}
1640 suffix) to tell @command{automake} where to install the listed files.
1642 Programs need to be built from source files, so for each program
1643 @code{@var{prog}} listed in a @code{@w{_PROGRAMS}} variable,
1644 @command{automake} will look for another variable named
1645 @code{@var{prog}_SOURCES} listing its source files. There may be more
1646 than one source file: they will all be compiled and linked together.
1648 Automake also knows that source files need to be distributed when
1649 creating a tarball (unlike built programs). So a side-effect of this
1650 @code{hello_SOURCES} declaration is that @file{main.c} will be
1651 part of the tarball created by @code{make dist}.
1653 Finally here are some explanations regarding the top-level
1658 dist_doc_DATA = README
1661 @code{SUBDIRS} is a special variable listing all directories that
1662 @command{make} should recurse into before processing the current
1663 directory. So this line is responsible for @command{make} building
1664 @file{src/hello} even though we run it from the top-level. This line
1665 also causes @code{make install} to install @file{src/hello} before
1666 installing @file{README} (not that this order matters).
1668 The line @code{dist_doc_DATA = README} causes @file{README} to be
1669 distributed and installed in @var{docdir}. Files listed with the
1670 @code{_DATA} primary are not automatically part of the tarball built
1671 with @code{make dist}, so we add the @code{dist_} prefix so they get
1672 distributed. However, for @file{README} it would not have been
1673 necessary: @command{automake} automatically distributes any
1674 @file{README} file it encounters (the list of other files
1675 automatically distributed is presented by @code{automake --help}).
1676 The only important effect of this second line is therefore to install
1677 @file{README} during @code{make install}.
1681 @chapter General ideas
1683 The following sections cover a few basic ideas that will help you
1684 understand how Automake works.
1687 * General Operation:: General operation of Automake
1688 * Strictness:: Standards conformance checking
1689 * Uniform:: The Uniform Naming Scheme
1690 * Canonicalization:: How derived variables are named
1691 * User Variables:: Variables reserved for the user
1692 * Auxiliary Programs:: Programs automake might require
1696 @node General Operation
1697 @section General Operation
1699 Automake works by reading a @file{Makefile.am} and generating a
1700 @file{Makefile.in}. Certain variables and rules defined in the
1701 @file{Makefile.am} instruct Automake to generate more specialized code;
1702 for instance, a @code{bin_PROGRAMS} variable definition will cause rules
1703 for compiling and linking programs to be generated.
1705 @cindex Non-standard targets
1706 @cindex @code{cvs-dist}, non-standard example
1710 The variable definitions and rules in the @file{Makefile.am} are
1711 copied verbatim into the generated file. This allows you to add
1712 arbitrary code into the generated @file{Makefile.in}. For instance,
1713 the Automake distribution includes a non-standard rule for the
1714 @code{git-dist} target, which the Automake maintainer uses to make
1715 distributions from his source control system.
1717 @cindex GNU make extensions
1719 Note that most GNU make extensions are not recognized by Automake. Using
1720 such extensions in a @file{Makefile.am} will lead to errors or confusing
1723 @cindex Append operator
1725 A special exception is that the GNU make append operator, @samp{+=}, is
1726 supported. This operator appends its right hand argument to the variable
1727 specified on the left. Automake will translate the operator into
1728 an ordinary @samp{=} operator; @samp{+=} will thus work with any make program.
1730 Automake tries to keep comments grouped with any adjoining rules or
1731 variable definitions.
1733 @cindex Make targets, overriding
1734 @cindex Make rules, overriding
1735 @cindex Overriding make rules
1736 @cindex Overriding make targets
1738 A rule defined in @file{Makefile.am} generally overrides any such
1739 rule of a similar name that would be automatically generated by
1740 @command{automake}. Although this is a supported feature, it is generally
1741 best to avoid making use of it, as sometimes the generated rules are
1744 @cindex Variables, overriding
1745 @cindex Overriding make variables
1747 Similarly, a variable defined in @file{Makefile.am} or
1748 @code{AC_SUBST}ed from @file{configure.ac} will override any
1749 definition of the variable that @command{automake} would ordinarily
1750 create. This feature is more often useful than the ability to
1751 override a rule. Be warned that many of the variables generated by
1752 @command{automake} are considered to be for internal use only, and their
1753 names might change in future releases.
1755 @cindex Recursive operation of Automake
1756 @cindex Automake, recursive operation
1757 @cindex Example of recursive operation
1759 When examining a variable definition, Automake will recursively examine
1760 variables referenced in the definition. For example, if Automake is
1761 looking at the content of @code{foo_SOURCES} in this snippet
1765 foo_SOURCES = c.c $(xs)
1768 it would use the files @file{a.c}, @file{b.c}, and @file{c.c} as the
1769 contents of @code{foo_SOURCES}.
1771 @cindex @code{##} (special Automake comment)
1772 @cindex Special Automake comment
1773 @cindex Comment, special to Automake
1775 Automake also allows a form of comment that is @emph{not} copied into
1776 the output; all lines beginning with @samp{##} (leading spaces allowed)
1777 are completely ignored by Automake.
1779 It is customary to make the first line of @file{Makefile.am} read:
1781 @cindex Makefile.am, first line
1782 @cindex First line of Makefile.am
1785 ## Process this file with automake to produce Makefile.in
1788 @c FIXME discuss putting a copyright into Makefile.am here? I would but
1789 @c I don't know quite what to say.
1791 @c FIXME document customary ordering of Makefile.am here!
1797 @cindex Non-GNU packages
1799 While Automake is intended to be used by maintainers of GNU packages, it
1800 does make some effort to accommodate those who wish to use it, but do
1801 not want to use all the GNU conventions.
1803 @cindex Strictness, defined
1804 @cindex Strictness, @option{foreign}
1805 @cindex @option{foreign} strictness
1806 @cindex Strictness, @option{gnu}
1807 @cindex @option{gnu} strictness
1808 @cindex Strictness, @option{gnits}
1809 @cindex @option{gnits} strictness
1811 To this end, Automake supports three levels of @dfn{strictness}---the
1812 strictness indicating how stringently Automake should check standards
1815 The valid strictness levels are:
1819 Automake will check for only those things that are absolutely
1820 required for proper operations. For instance, whereas GNU standards
1821 dictate the existence of a @file{NEWS} file, it will not be required in
1822 this mode. The name comes from the fact that Automake is intended to be
1823 used for GNU programs; these relaxed rules are not the standard mode of
1827 Automake will check---as much as possible---for compliance to the GNU
1828 standards for packages. This is the default.
1831 Automake will check for compliance to the as-yet-unwritten @dfn{Gnits
1832 standards}. These are based on the GNU standards, but are even more
1833 detailed. Unless you are a Gnits standards contributor, it is
1834 recommended that you avoid this option until such time as the Gnits
1835 standard is actually published (which may never happen).
1838 @xref{Gnits}, for more information on the precise implications of the
1841 Automake also has a special ``cygnus'' mode that is similar to
1842 strictness but handled differently. This mode is useful for packages
1843 that are put into a ``Cygnus'' style tree (e.g., the GCC tree).
1844 @xref{Cygnus}, for more information on this mode.
1848 @section The Uniform Naming Scheme
1850 @cindex Uniform naming scheme
1852 Automake variables generally follow a @dfn{uniform naming scheme} that
1853 makes it easy to decide how programs (and other derived objects) are
1854 built, and how they are installed. This scheme also supports
1855 @command{configure} time determination of what should be built.
1857 @cindex @code{_PROGRAMS} primary variable
1858 @cindex @code{PROGRAMS} primary variable
1859 @cindex Primary variable, @code{PROGRAMS}
1860 @cindex Primary variable, defined
1863 At @command{make} time, certain variables are used to determine which
1864 objects are to be built. The variable names are made of several pieces
1865 that are concatenated together.
1867 The piece that tells automake what is being built is commonly called
1868 the @dfn{primary}. For instance, the primary @code{PROGRAMS} holds a
1869 list of programs that are to be compiled and linked.
1872 @cindex @code{pkgdatadir}, defined
1873 @cindex @code{pkgincludedir}, defined
1874 @cindex @code{pkglibdir}, defined
1875 @cindex @code{pkglibexecdir}, defined
1878 @vindex pkgincludedir
1880 @vindex pkglibexecdir
1882 @cindex @code{PACKAGE}, directory
1883 A different set of names is used to decide where the built objects
1884 should be installed. These names are prefixes to the primary, and they
1885 indicate which standard directory should be used as the installation
1886 directory. The standard directory names are given in the GNU standards
1887 (@pxref{Directory Variables, , , standards, The GNU Coding Standards}).
1888 Automake extends this list with @code{pkgdatadir}, @code{pkgincludedir},
1889 @code{pkglibdir}, and @code{pkglibexecdir}; these are the same as the
1890 non-@samp{pkg} versions, but with @samp{$(PACKAGE)} appended. For instance,
1891 @code{pkglibdir} is defined as @samp{$(libdir)/$(PACKAGE)}.
1893 @cindex @code{EXTRA_}, prepending
1894 For each primary, there is one additional variable named by prepending
1895 @samp{EXTRA_} to the primary name. This variable is used to list
1896 objects that may or may not be built, depending on what
1897 @command{configure} decides. This variable is required because Automake
1898 must statically know the entire list of objects that may be built in
1899 order to generate a @file{Makefile.in} that will work in all cases.
1901 @cindex @code{EXTRA_PROGRAMS}, defined
1902 @cindex Example, @code{EXTRA_PROGRAMS}
1903 @cindex @command{cpio} example
1905 For instance, @command{cpio} decides at configure time which programs
1906 should be built. Some of the programs are installed in @code{bindir},
1907 and some are installed in @code{sbindir}:
1910 EXTRA_PROGRAMS = mt rmt
1911 bin_PROGRAMS = cpio pax
1912 sbin_PROGRAMS = $(MORE_PROGRAMS)
1915 Defining a primary without a prefix as a variable, e.g.,
1916 @samp{PROGRAMS}, is an error.
1918 Note that the common @samp{dir} suffix is left off when constructing the
1919 variable names; thus one writes @samp{bin_PROGRAMS} and not
1920 @samp{bindir_PROGRAMS}.
1922 Not every sort of object can be installed in every directory. Automake
1923 will flag those attempts it finds in error.
1924 Automake will also diagnose obvious misspellings in directory names.
1926 @cindex Extending list of installation directories
1927 @cindex Installation directories, extending list
1929 Sometimes the standard directories---even as augmented by
1930 Automake---are not enough. In particular it is sometimes useful, for
1931 clarity, to install objects in a subdirectory of some predefined
1932 directory. To this end, Automake allows you to extend the list of
1933 possible installation directories. A given prefix (e.g., @samp{zar})
1934 is valid if a variable of the same name with @samp{dir} appended is
1935 defined (e.g., @samp{zardir}).
1937 For instance, the following snippet will install @file{file.xml} into
1938 @samp{$(datadir)/xml}.
1941 xmldir = $(datadir)/xml
1945 @cindex @samp{noinst_} primary prefix, definition
1948 The special prefix @samp{noinst_} indicates that the objects in question
1949 should be built but not installed at all. This is usually used for
1950 objects required to build the rest of your package, for instance static
1951 libraries (@pxref{A Library}), or helper scripts.
1953 @cindex @samp{check_} primary prefix, definition
1956 The special prefix @samp{check_} indicates that the objects in question
1957 should not be built until the @samp{make check} command is run. Those
1958 objects are not installed either.
1960 The current primary names are @samp{PROGRAMS}, @samp{LIBRARIES},
1961 @samp{LISP}, @samp{PYTHON}, @samp{JAVA}, @samp{SCRIPTS}, @samp{DATA},
1962 @samp{HEADERS}, @samp{MANS}, and @samp{TEXINFOS}.
1974 Some primaries also allow additional prefixes that control other
1975 aspects of @command{automake}'s behavior. The currently defined prefixes
1976 are @samp{dist_}, @samp{nodist_}, @samp{nobase_}, and @samp{notrans_}.
1977 These prefixes are explained later (@pxref{Program and Library Variables})
1978 (@pxref{Man pages}).
1981 @node Canonicalization
1982 @section How derived variables are named
1984 @cindex canonicalizing Automake variables
1986 Sometimes a Makefile variable name is derived from some text the
1987 maintainer supplies. For instance, a program name listed in
1988 @samp{_PROGRAMS} is rewritten into the name of a @samp{_SOURCES}
1989 variable. In cases like this, Automake canonicalizes the text, so that
1990 program names and the like do not have to follow Makefile variable naming
1991 rules. All characters in the name except for letters, numbers, the
1992 strudel (@@), and the underscore are turned into underscores when making
1993 variable references.
1995 For example, if your program is named @file{sniff-glue}, the derived
1996 variable name would be @samp{sniff_glue_SOURCES}, not
1997 @samp{sniff-glue_SOURCES}. Similarly the sources for a library named
1998 @file{libmumble++.a} should be listed in the
1999 @samp{libmumble___a_SOURCES} variable.
2001 The strudel is an addition, to make the use of Autoconf substitutions in
2002 variable names less obfuscating.
2005 @node User Variables
2006 @section Variables reserved for the user
2008 @cindex variables, reserved for the user
2009 @cindex user variables
2011 Some @file{Makefile} variables are reserved by the GNU Coding Standards
2012 for the use of the ``user''---the person building the package. For
2013 instance, @code{CFLAGS} is one such variable.
2015 Sometimes package developers are tempted to set user variables such as
2016 @code{CFLAGS} because it appears to make their job easier. However,
2017 the package itself should never set a user variable, particularly not
2018 to include switches that are required for proper compilation of the
2019 package. Since these variables are documented as being for the
2020 package builder, that person rightfully expects to be able to override
2021 any of these variables at build time.
2023 To get around this problem, Automake introduces an automake-specific
2024 shadow variable for each user flag variable. (Shadow variables are
2025 not introduced for variables like @code{CC}, where they would make no
2026 sense.) The shadow variable is named by prepending @samp{AM_} to the
2027 user variable's name. For instance, the shadow variable for
2028 @code{YFLAGS} is @code{AM_YFLAGS}. The package maintainer---that is,
2029 the author(s) of the @file{Makefile.am} and @file{configure.ac}
2030 files---may adjust these shadow variables however necessary.
2032 @xref{Flag Variables Ordering}, for more discussion about these
2033 variables and how they interact with per-target variables.
2035 @node Auxiliary Programs
2036 @section Programs automake might require
2038 @cindex Programs, auxiliary
2039 @cindex Auxiliary programs
2041 Automake sometimes requires helper programs so that the generated
2042 @file{Makefile} can do its work properly. There are a fairly large
2043 number of them, and we list them here.
2045 Although all of these files are distributed and installed with
2046 Automake, a couple of them are maintained separately. The Automake
2047 copies are updated before each release, but we mention the original
2048 source in case you need more recent versions.
2053 These two files are used by the obsolete de-ANSI-fication support
2057 This is a wrapper for compilers that do not accept options @option{-c}
2058 and @option{-o} at the same time. It is only used when absolutely
2059 required. Such compilers are rare.
2063 These two programs compute the canonical triplets for the given build,
2064 host, or target architecture. These programs are updated regularly to
2065 support new architectures and fix probes broken by changes in new
2066 kernel versions. Each new release of Automake comes with up-to-date
2067 copies of these programs. If your copy of Automake is getting old,
2068 you are encouraged to fetch the latest versions of these files from
2069 @url{http://savannah.gnu.org/cvs/?group=config} before making a
2073 This file is not a program, it is a @file{configure} fragment used for
2074 multilib support (@pxref{Multilibs}). This file is maintained in the
2075 GCC tree at @url{http://gcc.gnu.org/svn.html}.
2078 This program understands how to run a compiler so that it will
2079 generate not only the desired output but also dependency information
2080 that is then used by the automatic dependency tracking feature
2081 (@pxref{Dependencies}).
2084 This program is used to byte-compile Emacs Lisp code.
2087 This is a replacement for the @command{install} program that works on
2088 platforms where @command{install} is unavailable or unusable.
2091 This script is used to generate a @file{version.texi} file. It examines
2092 a file and prints some date information about it.
2095 This wraps a number of programs that are typically only required by
2096 maintainers. If the program in question doesn't exist,
2097 @command{missing} prints an informative warning and attempts to fix
2098 things so that the build can continue.
2101 This script used to be a wrapper around @samp{mkdir -p}, which is not
2102 portable. Now we prefer to use @samp{install-sh -d} when configure
2103 finds that @samp{mkdir -p} does not work, this makes one less script to
2106 For backward compatibility @file{mkinstalldirs} is still used and
2107 distributed when @command{automake} finds it in a package. But it is no
2108 longer installed automatically, and it should be safe to remove it.
2111 This is used to byte-compile Python scripts.
2114 This program duplicates a tree of directories, using symbolic links
2115 instead of copying files. Such operation is performed when building
2116 multilibs (@pxref{Multilibs}). This file is maintained in the GCC
2117 tree at @url{http://gcc.gnu.org/svn.html}.
2120 Not a program, this file is required for @samp{make dvi}, @samp{make
2121 ps} and @samp{make pdf} to work when Texinfo sources are in the
2122 package. The latest version can be downloaded from
2123 @url{http://www.gnu.org/software/texinfo/}.
2126 This program wraps @command{lex} and @command{yacc} to rename their
2127 output files. It also ensures that, for instance, multiple
2128 @command{yacc} instances can be invoked in a single directory in
2135 @chapter Some example packages
2137 This section contains two small examples.
2139 The first example (@pxref{Complete}) assumes you have an existing
2140 project already using Autoconf, with handcrafted @file{Makefile}s, and
2141 that you want to convert it to using Automake. If you are discovering
2142 both tools, it is probably better that you look at the Hello World
2143 example presented earlier (@pxref{Hello World}).
2145 The second example (@pxref{true}) shows how two programs can be built
2146 from the same file, using different compilation parameters. It
2147 contains some technical digressions that are probably best skipped on
2151 * Complete:: A simple example, start to finish
2152 * true:: Building true and false
2157 @section A simple example, start to finish
2159 @cindex Complete example
2161 Let's suppose you just finished writing @code{zardoz}, a program to make
2162 your head float from vortex to vortex. You've been using Autoconf to
2163 provide a portability framework, but your @file{Makefile.in}s have been
2164 ad-hoc. You want to make them bulletproof, so you turn to Automake.
2166 @cindex @code{AM_INIT_AUTOMAKE}, example use
2168 The first step is to update your @file{configure.ac} to include the
2169 commands that @command{automake} needs. The way to do this is to add an
2170 @code{AM_INIT_AUTOMAKE} call just after @code{AC_INIT}:
2173 AC_INIT([zardoz], [1.0])
2178 Since your program doesn't have any complicating factors (e.g., it
2179 doesn't use @code{gettext}, it doesn't want to build a shared library),
2180 you're done with this part. That was easy!
2182 @cindex @command{aclocal} program, introduction
2183 @cindex @file{aclocal.m4}, preexisting
2184 @cindex @file{acinclude.m4}, defined
2186 Now you must regenerate @file{configure}. But to do that, you'll need
2187 to tell @command{autoconf} how to find the new macro you've used. The
2188 easiest way to do this is to use the @command{aclocal} program to
2189 generate your @file{aclocal.m4} for you. But wait@dots{} maybe you
2190 already have an @file{aclocal.m4}, because you had to write some hairy
2191 macros for your program. The @command{aclocal} program lets you put
2192 your own macros into @file{acinclude.m4}, so simply rename and then
2196 mv aclocal.m4 acinclude.m4
2201 @cindex @command{zardoz} example
2203 Now it is time to write your @file{Makefile.am} for @code{zardoz}.
2204 Since @code{zardoz} is a user program, you want to install it where the
2205 rest of the user programs go: @code{bindir}. Additionally,
2206 @code{zardoz} has some Texinfo documentation. Your @file{configure.ac}
2207 script uses @code{AC_REPLACE_FUNCS}, so you need to link against
2208 @samp{$(LIBOBJS)}. So here's what you'd write:
2211 bin_PROGRAMS = zardoz
2212 zardoz_SOURCES = main.c head.c float.c vortex9.c gun.c
2213 zardoz_LDADD = $(LIBOBJS)
2215 info_TEXINFOS = zardoz.texi
2218 Now you can run @samp{automake --add-missing} to generate your
2219 @file{Makefile.in} and grab any auxiliary files you might need, and
2224 @section Building true and false
2226 @cindex Example, @command{false} and @command{true}
2227 @cindex @command{false} Example
2228 @cindex @command{true} Example
2230 Here is another, trickier example. It shows how to generate two
2231 programs (@code{true} and @code{false}) from the same source file
2232 (@file{true.c}). The difficult part is that each compilation of
2233 @file{true.c} requires different @code{cpp} flags.
2236 bin_PROGRAMS = true false
2238 false_LDADD = false.o
2241 $(COMPILE) -DEXIT_CODE=0 -c true.c
2244 $(COMPILE) -DEXIT_CODE=1 -o false.o -c true.c
2247 Note that there is no @code{true_SOURCES} definition. Automake will
2248 implicitly assume that there is a source file named @file{true.c}, and
2249 define rules to compile @file{true.o} and link @file{true}. The
2250 @samp{true.o: true.c} rule supplied by the above @file{Makefile.am},
2251 will override the Automake generated rule to build @file{true.o}.
2253 @code{false_SOURCES} is defined to be empty---that way no implicit value
2254 is substituted. Because we have not listed the source of
2255 @file{false}, we have to tell Automake how to link the program. This is
2256 the purpose of the @code{false_LDADD} line. A @code{false_DEPENDENCIES}
2257 variable, holding the dependencies of the @file{false} target will be
2258 automatically generated by Automake from the content of
2261 The above rules won't work if your compiler doesn't accept both
2262 @option{-c} and @option{-o}. The simplest fix for this is to introduce a
2263 bogus dependency (to avoid problems with a parallel @command{make}):
2266 true.o: true.c false.o
2267 $(COMPILE) -DEXIT_CODE=0 -c true.c
2270 $(COMPILE) -DEXIT_CODE=1 -c true.c && mv true.o false.o
2273 Also, these explicit rules do not work if the obsolete de-ANSI-fication feature
2274 is used (@pxref{ANSI}). Supporting de-ANSI-fication requires a little
2278 true_.o: true_.c false_.o
2279 $(COMPILE) -DEXIT_CODE=0 -c true_.c
2282 $(COMPILE) -DEXIT_CODE=1 -c true_.c && mv true_.o false_.o
2285 As it turns out, there is also a much easier way to do this same task.
2286 Some of the above techniques are useful enough that we've kept the
2287 example in the manual. However if you were to build @code{true} and
2288 @code{false} in real life, you would probably use per-program
2289 compilation flags, like so:
2292 bin_PROGRAMS = false true
2294 false_SOURCES = true.c
2295 false_CPPFLAGS = -DEXIT_CODE=1
2297 true_SOURCES = true.c
2298 true_CPPFLAGS = -DEXIT_CODE=0
2301 In this case Automake will cause @file{true.c} to be compiled twice,
2302 with different flags. De-ANSI-fication will work automatically. In
2303 this instance, the names of the object files would be chosen by
2304 automake; they would be @file{false-true.o} and @file{true-true.o}.
2305 (The name of the object files rarely matters.)
2308 @node Invoking Automake
2309 @chapter Creating a @file{Makefile.in}
2311 @cindex Multiple @file{configure.ac} files
2312 @cindex Invoking @command{automake}
2313 @cindex @command{automake}, invoking
2315 To create all the @file{Makefile.in}s for a package, run the
2316 @command{automake} program in the top level directory, with no
2317 arguments. @command{automake} will automatically find each
2318 appropriate @file{Makefile.am} (by scanning @file{configure.ac};
2319 @pxref{configure}) and generate the corresponding @file{Makefile.in}.
2320 Note that @command{automake} has a rather simplistic view of what
2321 constitutes a package; it assumes that a package has only one
2322 @file{configure.ac}, at the top. If your package has multiple
2323 @file{configure.ac}s, then you must run @command{automake} in each
2324 directory holding a @file{configure.ac}. (Alternatively, you may rely
2325 on Autoconf's @command{autoreconf}, which is able to recurse your
2326 package tree and run @command{automake} where appropriate.)
2328 You can optionally give @command{automake} an argument; @file{.am} is
2329 appended to the argument and the result is used as the name of the
2330 input file. This feature is generally only used to automatically
2331 rebuild an out-of-date @file{Makefile.in}. Note that
2332 @command{automake} must always be run from the topmost directory of a
2333 project, even if being used to regenerate the @file{Makefile.in} in
2334 some subdirectory. This is necessary because @command{automake} must
2335 scan @file{configure.ac}, and because @command{automake} uses the
2336 knowledge that a @file{Makefile.in} is in a subdirectory to change its
2337 behavior in some cases.
2340 Automake will run @command{autoconf} to scan @file{configure.ac} and
2341 its dependencies (i.e., @file{aclocal.m4} and any included file),
2342 therefore @command{autoconf} must be in your @env{PATH}. If there is
2343 an @env{AUTOCONF} variable in your environment it will be used
2344 instead of @command{autoconf}, this allows you to select a particular
2345 version of Autoconf. By the way, don't misunderstand this paragraph:
2346 @command{automake} runs @command{autoconf} to @strong{scan} your
2347 @file{configure.ac}, this won't build @file{configure} and you still
2348 have to run @command{autoconf} yourself for this purpose.
2350 @cindex @command{automake} options
2351 @cindex Options, @command{automake}
2352 @cindex Strictness, command line
2354 @command{automake} accepts the following options:
2356 @cindex Extra files distributed with Automake
2357 @cindex Files distributed with Automake
2358 @cindex @file{config.guess}
2362 @itemx --add-missing
2364 @opindex --add-missing
2365 Automake requires certain common files to exist in certain situations;
2366 for instance, @file{config.guess} is required if @file{configure.ac} runs
2367 @code{AC_CANONICAL_HOST}. Automake is distributed with several of these
2368 files (@pxref{Auxiliary Programs}); this option will cause the missing
2369 ones to be automatically added to the package, whenever possible. In
2370 general if Automake tells you a file is missing, try using this option.
2371 By default Automake tries to make a symbolic link pointing to its own
2372 copy of the missing file; this can be changed with @option{--copy}.
2374 Many of the potentially-missing files are common scripts whose
2375 location may be specified via the @code{AC_CONFIG_AUX_DIR} macro.
2376 Therefore, @code{AC_CONFIG_AUX_DIR}'s setting affects whether a
2377 file is considered missing, and where the missing file is added
2380 @item --libdir=@var{dir}
2382 Look for Automake data files in directory @var{dir} instead of in the
2383 installation directory. This is typically used for debugging.
2389 When used with @option{--add-missing}, causes installed files to be
2390 copied. The default is to make a symbolic link.
2394 Causes the generated @file{Makefile.in}s to follow Cygnus rules, instead
2395 of GNU or Gnits rules. For more information, see @ref{Cygnus}.
2399 @itemx --force-missing
2400 @opindex --force-missing
2401 When used with @option{--add-missing}, causes standard files to be reinstalled
2402 even if they already exist in the source tree. This involves removing
2403 the file from the source tree before creating the new symlink (or, with
2404 @option{--copy}, copying the new file).
2408 Set the global strictness to @option{foreign}. For more information, see
2413 Set the global strictness to @option{gnits}. For more information, see
2418 Set the global strictness to @option{gnu}. For more information, see
2419 @ref{Gnits}. This is the default strictness.
2423 Print a summary of the command line options and exit.
2426 @itemx --ignore-deps
2428 This disables the dependency tracking feature in generated
2429 @file{Makefile}s; see @ref{Dependencies}.
2431 @item --include-deps
2432 @opindex --include-deps
2433 This enables the dependency tracking feature. This feature is enabled
2434 by default. This option is provided for historical reasons only and
2435 probably should not be used.
2439 Ordinarily @command{automake} creates all @file{Makefile.in}s mentioned in
2440 @file{configure.ac}. This option causes it to only update those
2441 @file{Makefile.in}s that are out of date with respect to one of their
2445 @itemx --output-dir=@var{dir}
2447 @opindex --output-dir
2448 Put the generated @file{Makefile.in} in the directory @var{dir}.
2449 Ordinarily each @file{Makefile.in} is created in the directory of the
2450 corresponding @file{Makefile.am}. This option is deprecated and will be
2451 removed in a future release.
2457 Cause Automake to print information about which files are being read or
2462 Print the version number of Automake and exit.
2465 @item --warnings=@var{category}
2468 Output warnings falling in @var{category}. @var{category} can be
2472 warnings related to the GNU Coding Standards
2473 (@pxref{Top, , , standards, The GNU Coding Standards}).
2475 obsolete features or constructions
2477 user redefinitions of Automake rules or variables
2479 portability issues (e.g., use of @command{make} features that are
2480 known to be not portable)
2482 weird syntax, unused variables, typos
2484 unsupported or incomplete features
2488 turn off all the warnings
2490 treat warnings as errors
2493 A category can be turned off by prefixing its name with @samp{no-}. For
2494 instance, @option{-Wno-syntax} will hide the warnings about unused
2497 The categories output by default are @samp{syntax} and
2498 @samp{unsupported}. Additionally, @samp{gnu} and @samp{portability}
2499 are enabled in @option{--gnu} and @option{--gnits} strictness.
2502 The environment variable @env{WARNINGS} can contain a comma separated
2503 list of categories to enable. It will be taken into account before the
2504 command-line switches, this way @option{-Wnone} will also ignore any
2505 warning category enabled by @env{WARNINGS}. This variable is also used
2506 by other tools like @command{autoconf}; unknown categories are ignored
2513 @chapter Scanning @file{configure.ac}
2515 @cindex @file{configure.ac}, scanning
2516 @cindex Scanning @file{configure.ac}
2518 Automake scans the package's @file{configure.ac} to determine certain
2519 information about the package. Some @command{autoconf} macros are required
2520 and some variables must be defined in @file{configure.ac}. Automake
2521 will also use information from @file{configure.ac} to further tailor its
2524 Automake also supplies some Autoconf macros to make the maintenance
2525 easier. These macros can automatically be put into your
2526 @file{aclocal.m4} using the @command{aclocal} program.
2529 * Requirements:: Configuration requirements
2530 * Optional:: Other things Automake recognizes
2531 * Invoking aclocal:: Auto-generating aclocal.m4
2532 * Macros:: Autoconf macros supplied with Automake
2537 @section Configuration requirements
2539 @cindex Automake requirements
2540 @cindex Requirements of Automake
2542 @acindex AM_INIT_AUTOMAKE
2543 The one real requirement of Automake is that your @file{configure.ac}
2544 call @code{AM_INIT_AUTOMAKE}. This macro does several things that are
2545 required for proper Automake operation (@pxref{Macros}).
2547 Here are the other macros that Automake requires but which are not run
2548 by @code{AM_INIT_AUTOMAKE}:
2551 @item AC_CONFIG_FILES
2553 @acindex AC_CONFIG_FILES
2555 These two macros are usually invoked as follows near the end of
2556 @file{configure.ac}.
2570 Automake uses these to determine which files to create (@pxref{Output, ,
2571 Creating Output Files, autoconf, The Autoconf Manual}). A listed file
2572 is considered to be an Automake generated @file{Makefile} if there
2573 exists a file with the same name and the @file{.am} extension appended.
2574 Typically, @samp{AC_CONFIG_FILES([foo/Makefile])} will cause Automake to
2575 generate @file{foo/Makefile.in} if @file{foo/Makefile.am} exists.
2577 When using @code{AC_CONFIG_FILES} with multiple input files, as in
2580 AC_CONFIG_FILES([Makefile:top.in:Makefile.in:bot.in])
2584 @command{automake} will generate the first @file{.in} input file for
2585 which a @file{.am} file exists. If no such file exists the output
2586 file is not considered to be generated by Automake.
2588 Files created by @code{AC_CONFIG_FILES}, be they Automake
2589 @file{Makefile}s or not, are all removed by @samp{make distclean}.
2590 Their inputs are automatically distributed, except for inputs that
2591 turn out the be outputs of prior @code{AC_CONFIG_FILES} commands.
2592 Finally, rebuild rules are generated in the Automake @file{Makefile}
2593 existing in the subdirectory of the output file, if there is one, or
2594 in the top-level @file{Makefile} otherwise.
2596 The above machinery (cleaning, distributing, and rebuilding) works
2597 fine if the @code{AC_CONFIG_FILES} specifications contain only
2598 literals. If part of the specification uses shell variables,
2599 @command{automake} will not be able to fulfill this setup, and you will
2600 have to complete the missing bits by hand. For instance, on
2605 AC_CONFIG_FILES([output:$file],, [file=$file])
2609 @command{automake} will output rules to clean @file{output}, and
2610 rebuild it. However the rebuild rule will not depend on @file{input},
2611 and this file will not be distributed either. (You must add
2612 @samp{EXTRA_DIST = input} to your @file{Makefile} if @file{input} is a
2621 AC_CONFIG_FILES([$file:input],, [file=$file])
2622 AC_CONFIG_FILES([$file2],, [file2=$file2])
2626 will only cause @file{input} to be distributed. No file will be
2627 cleaned automatically (add @samp{DISTCLEANFILES = output out}
2628 yourself), and no rebuild rule will be output.
2630 Obviously @command{automake} cannot guess what value @samp{$file} is
2631 going to hold later when @file{configure} is run, and it cannot use
2632 the shell variable @samp{$file} in a @file{Makefile}. However, if you
2633 make reference to @samp{$file} as @samp{$@{file@}} (i.e., in a way
2634 that is compatible with @command{make}'s syntax) and furthermore use
2635 @code{AC_SUBST} to ensure that @samp{$@{file@}} is meaningful in a
2636 @file{Makefile}, then @command{automake} will be able to use
2637 @samp{$@{file@}} to generate all these rules. For instance, here is
2638 how the Automake package itself generates versioned scripts for its
2642 AC_SUBST([APIVERSION], @dots{})
2645 [tests/aclocal-$@{APIVERSION@}:tests/aclocal.in],
2646 [chmod +x tests/aclocal-$@{APIVERSION@}],
2647 [APIVERSION=$APIVERSION])
2649 [tests/automake-$@{APIVERSION@}:tests/automake.in],
2650 [chmod +x tests/automake-$@{APIVERSION@}])
2654 Here cleaning, distributing, and rebuilding are done automatically,
2655 because @samp{$@{APIVERSION@}} is known at @command{make}-time.
2657 Note that you should not use shell variables to declare
2658 @file{Makefile} files for which @command{automake} must create
2659 @file{Makefile.in}. Even @code{AC_SUBST} does not help here, because
2660 @command{automake} needs to know the file name when it runs in order
2661 to check whether @file{Makefile.am} exists. (In the very hairy case
2662 that your setup requires such use of variables, you will have to tell
2663 Automake which @file{Makefile.in}s to generate on the command-line.)
2668 Use literals for @file{Makefile}s, and for other files whenever possible.
2670 Use @samp{$file} (or @samp{$@{file@}} without @samp{AC_SUBST([file])})
2671 for files that @command{automake} should ignore.
2673 Use @samp{$@{file@}} and @samp{AC_SUBST([file])} for files
2674 that @command{automake} should not ignore.
2681 @section Other things Automake recognizes
2683 @cindex Macros Automake recognizes
2684 @cindex Recognized macros by Automake
2686 Every time Automake is run it calls Autoconf to trace
2687 @file{configure.ac}. This way it can recognize the use of certain
2688 macros and tailor the generated @file{Makefile.in} appropriately.
2689 Currently recognized macros and their effects are:
2692 @item AC_CANONICAL_BUILD
2693 @itemx AC_CANONICAL_HOST
2694 @itemx AC_CANONICAL_TARGET
2695 @vindex build_triplet
2696 @vindex host_triplet
2697 @vindex target_triplet
2698 Automake will ensure that @file{config.guess} and @file{config.sub}
2699 exist. Also, the @file{Makefile} variables @code{build_triplet},
2700 @code{host_triplet} and @code{target_triplet} are introduced. See
2701 @ref{Canonicalizing, , Getting the Canonical System Type, autoconf,
2702 The Autoconf Manual}.
2704 @item AC_CONFIG_AUX_DIR
2705 Automake will look for various helper scripts, such as
2706 @file{install-sh}, in the directory named in this macro invocation.
2707 @c This list is accurate relative to version 1.8
2708 (The full list of scripts is: @file{config.guess}, @file{config.sub},
2709 @file{depcomp}, @file{elisp-comp}, @file{compile}, @file{install-sh},
2710 @file{ltmain.sh}, @file{mdate-sh}, @file{missing}, @file{mkinstalldirs},
2711 @file{py-compile}, @file{texinfo.tex}, and @file{ylwrap}.) Not all
2712 scripts are always searched for; some scripts will only be sought if the
2713 generated @file{Makefile.in} requires them.
2715 If @code{AC_CONFIG_AUX_DIR} is not given, the scripts are looked for in
2716 their standard locations. For @file{mdate-sh},
2717 @file{texinfo.tex}, and @file{ylwrap}, the standard location is the
2718 source directory corresponding to the current @file{Makefile.am}. For
2719 the rest, the standard location is the first one of @file{.}, @file{..},
2720 or @file{../..} (relative to the top source directory) that provides any
2721 one of the helper scripts. @xref{Input, , Finding `configure' Input,
2722 autoconf, The Autoconf Manual}.
2724 Required files from @code{AC_CONFIG_AUX_DIR} are automatically
2725 distributed, even if there is no @file{Makefile.am} in this directory.
2727 @item AC_CONFIG_LIBOBJ_DIR
2728 Automake will require the sources file declared with
2729 @code{AC_LIBSOURCE} (see below) in the directory specified by this
2732 @item AC_CONFIG_HEADERS
2733 Automake will generate rules to rebuild these headers. Older versions
2734 of Automake required the use of @code{AM_CONFIG_HEADER}
2735 (@pxref{Macros}); this is no longer the case today.
2737 As for @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the
2738 specification using shell variables will be ignored as far as
2739 cleaning, distributing, and rebuilding is concerned.
2741 @item AC_CONFIG_LINKS
2742 Automake will generate rules to remove @file{configure} generated
2743 links on @samp{make distclean} and to distribute named source files as
2744 part of @samp{make dist}.
2746 As for @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the
2747 specification using shell variables will be ignored as far as cleaning
2748 and distributing is concerned. (There is no rebuild rules for links.)
2752 @itemx AC_LIBSOURCES
2754 Automake will automatically distribute any file listed in
2755 @code{AC_LIBSOURCE} or @code{AC_LIBSOURCES}.
2757 Note that the @code{AC_LIBOBJ} macro calls @code{AC_LIBSOURCE}. So if
2758 an Autoconf macro is documented to call @samp{AC_LIBOBJ([file])}, then
2759 @file{file.c} will be distributed automatically by Automake. This
2760 encompasses many macros like @code{AC_FUNC_ALLOCA},
2761 @code{AC_FUNC_MEMCMP}, @code{AC_REPLACE_FUNCS}, and others.
2763 By the way, direct assignments to @code{LIBOBJS} are no longer
2764 supported. You should always use @code{AC_LIBOBJ} for this purpose.
2765 @xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs.@: @code{LIBOBJS},
2766 autoconf, The Autoconf Manual}.
2768 @item AC_PROG_RANLIB
2769 This is required if any libraries are built in the package.
2770 @xref{Particular Programs, , Particular Program Checks, autoconf, The
2774 This is required if any C++ source is included. @xref{Particular
2775 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
2778 This is required if any Objective C source is included. @xref{Particular
2779 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
2782 This is required if any Fortran 77 source is included. This macro is
2783 distributed with Autoconf version 2.13 and later. @xref{Particular
2784 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
2786 @item AC_F77_LIBRARY_LDFLAGS
2787 This is required for programs and shared libraries that are a mixture of
2788 languages that include Fortran 77 (@pxref{Mixing Fortran 77 With C and
2789 C++}). @xref{Macros, , Autoconf macros supplied with Automake}.
2792 Automake will add the flags computed by @code{AC_FC_SRCEXT} to compilation
2793 of files with the respective source extension (@pxref{Fortran Compiler, ,
2794 Fortran Compiler Characteristics, autoconf, The Autoconf Manual}).
2797 This is required if any Fortran 90/95 source is included. This macro is
2798 distributed with Autoconf version 2.58 and later. @xref{Particular
2799 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
2801 @item AC_PROG_LIBTOOL
2802 Automake will turn on processing for @command{libtool} (@pxref{Top, ,
2803 Introduction, libtool, The Libtool Manual}).
2807 If a Yacc source file is seen, then you must either use this macro or
2808 define the variable @code{YACC} in @file{configure.ac}. The former is
2809 preferred (@pxref{Particular Programs, , Particular Program Checks,
2810 autoconf, The Autoconf Manual}).
2813 If a Lex source file is seen, then this macro must be used.
2814 @xref{Particular Programs, , Particular Program Checks, autoconf, The
2817 @item AC_REQUIRE_AUX_FILE
2818 @command{automake} will ensure each file for which this macro is
2819 called exists in the aux directory, and will complain otherwise. It
2820 will also automatically distribute the file. This macro should be
2821 used by third-party Autoconf macros that requires some supporting
2822 files in the aux directory specified with @code{AC_CONFIG_AUX_DIR}
2823 above. @xref{Input, , Finding @command{configure} Input, autoconf,
2824 The Autoconf Manual}.
2827 The first argument is automatically defined as a variable in each
2828 generated @file{Makefile.in}. @xref{Setting Output Variables, , Setting
2829 Output Variables, autoconf, The Autoconf Manual}.
2831 If the Autoconf manual says that a macro calls @code{AC_SUBST} for
2832 @var{var}, or defines the output variable @var{var} then @var{var} will
2833 be defined in each @file{Makefile.in} generated by Automake.
2834 E.g.@: @code{AC_PATH_XTRA} defines @code{X_CFLAGS} and @code{X_LIBS}, so
2835 you can use these variables in any @file{Makefile.am} if
2836 @code{AC_PATH_XTRA} is called.
2838 @item AM_C_PROTOTYPES
2839 This is required when using the obsolete de-ANSI-fication feature; see
2842 @item AM_GNU_GETTEXT
2843 This macro is required for packages that use GNU gettext
2844 (@pxref{gettext}). It is distributed with gettext. If Automake sees
2845 this macro it ensures that the package meets some of gettext's
2848 @item AM_GNU_GETTEXT_INTL_SUBDIR
2849 This macro specifies that the @file{intl/} subdirectory is to be built,
2850 even if the @code{AM_GNU_GETTEXT} macro was invoked with a first argument
2853 @item AM_MAINTAINER_MODE
2854 @opindex --enable-maintainer-mode
2855 This macro adds a @option{--enable-maintainer-mode} option to
2856 @command{configure}. If this is used, @command{automake} will cause
2857 ``maintainer-only'' rules to be turned off by default in the
2858 generated @file{Makefile.in}s. This macro defines the
2859 @code{MAINTAINER_MODE} conditional, which you can use in your own
2860 @file{Makefile.am}. @xref{maintainer-mode}.
2863 Files included by @file{configure.ac} using this macro will be
2864 detected by Automake and automatically distributed. They will also
2865 appear as dependencies in @file{Makefile} rules.
2867 @code{m4_include} is seldom used by @file{configure.ac} authors, but
2868 can appear in @file{aclocal.m4} when @command{aclocal} detects that
2869 some required macros come from files local to your package (as opposed
2870 to macros installed in a system-wide directory, @pxref{Invoking
2876 @node Invoking aclocal
2877 @section Auto-generating aclocal.m4
2879 @cindex Invoking @command{aclocal}
2880 @cindex @command{aclocal}, Invoking
2882 Automake includes a number of Autoconf macros that can be used in
2883 your package (@pxref{Macros}); some of them are actually required by
2884 Automake in certain situations. These macros must be defined in your
2885 @file{aclocal.m4}; otherwise they will not be seen by
2888 The @command{aclocal} program will automatically generate
2889 @file{aclocal.m4} files based on the contents of @file{configure.ac}.
2890 This provides a convenient way to get Automake-provided macros,
2891 without having to search around. The @command{aclocal} mechanism
2892 allows other packages to supply their own macros (@pxref{Extending
2893 aclocal}). You can also use it to maintain your own set of custom
2894 macros (@pxref{Local Macros}).
2896 At startup, @command{aclocal} scans all the @file{.m4} files it can
2897 find, looking for macro definitions (@pxref{Macro search path}). Then
2898 it scans @file{configure.ac}. Any mention of one of the macros found
2899 in the first step causes that macro, and any macros it in turn
2900 requires, to be put into @file{aclocal.m4}.
2902 @emph{Putting} the file that contains the macro definition into
2903 @file{aclocal.m4} is usually done by copying the entire text of this
2904 file, including unused macro definitions as well as both @samp{#} and
2905 @samp{dnl} comments. If you want to make a comment that will be
2906 completely ignored by @command{aclocal}, use @samp{##} as the comment
2909 When a file selected by @command{aclocal} is located in a subdirectory
2910 specified as a relative search path with @command{aclocal}'s @option{-I}
2911 argument, @command{aclocal} assumes the file belongs to the package
2912 and uses @code{m4_include} instead of copying it into
2913 @file{aclocal.m4}. This makes the package smaller, eases dependency
2914 tracking, and cause the file to be distributed automatically.
2915 (@xref{Local Macros}, for an example.) Any macro that is found in a
2916 system-wide directory, or via an absolute search path will be copied.
2917 So use @samp{-I `pwd`/reldir} instead of @samp{-I reldir} whenever
2918 some relative directory need to be considered outside the package.
2920 The contents of @file{acinclude.m4}, if this file exists, are also
2921 automatically included in @file{aclocal.m4}. We recommend against
2922 using @file{acinclude.m4} in new packages (@pxref{Local Macros}).
2926 While computing @file{aclocal.m4}, @command{aclocal} runs
2927 @command{autom4te} (@pxref{Using autom4te, , Using @command{Autom4te},
2928 autoconf, The Autoconf Manual}) in order to trace the macros that are
2929 really used, and omit from @file{aclocal.m4} all macros that are
2930 mentioned but otherwise unexpanded (this can happen when a macro is
2931 called conditionally). @command{autom4te} is expected to be in the
2932 @env{PATH}, just as @command{autoconf}. Its location can be
2933 overridden using the @env{AUTOM4TE} environment variable.
2936 * aclocal options:: Options supported by aclocal
2937 * Macro search path:: How aclocal finds .m4 files
2938 * Extending aclocal:: Writing your own aclocal macros
2939 * Local Macros:: Organizing local macros
2940 * Serials:: Serial lines in Autoconf macros
2941 * Future of aclocal:: aclocal's scheduled death
2944 @node aclocal options
2945 @subsection aclocal options
2947 @cindex @command{aclocal}, Options
2948 @cindex Options, @command{aclocal}
2950 @command{aclocal} accepts the following options:
2953 @item --acdir=@var{dir}
2955 Look for the macro files in @var{dir} instead of the installation
2956 directory. This is typically used for debugging.
2958 @item --diff[=@var{command}]
2960 Run @var{command} on M4 file that would be installed or overwritten
2961 by @option{--install}. The default @var{command} is @samp{diff -u}.
2962 This option implies @option{--install} and @option{--dry-run}.
2966 Do not actually overwrite (or create) @file{aclocal.m4} and M4
2967 files installed by @option{--install}.
2971 Print a summary of the command line options and exit.
2975 Add the directory @var{dir} to the list of directories searched for
2980 Install system-wide third-party macros into the first directory
2981 specified with @samp{-I @var{dir}} instead of copying them in the
2984 @cindex serial number and @option{--install}
2985 When this option is used, and only when this option is used,
2986 @command{aclocal} will also honor @samp{#serial @var{NUMBER}} lines
2987 that appear in macros: an M4 file is ignored if there exists another
2988 M4 file with the same basename and a greater serial number in the
2989 search path (@pxref{Serials}).
2993 Always overwrite the output file. The default is to overwrite the output
2994 file only when really needed, i.e., when its contents changes or if one
2995 of its dependencies is younger.
2997 This option forces the update of @file{aclocal.m4} (or the file
2998 specified with @file{--output} below) and only this file, it has
2999 absolutely no influence on files that may need to be installed by
3002 @item --output=@var{file}
3004 Cause the output to be put into @var{file} instead of @file{aclocal.m4}.
3006 @item --print-ac-dir
3007 @opindex --print-ac-dir
3008 Prints the name of the directory that @command{aclocal} will search to
3009 find third-party @file{.m4} files. When this option is given, normal
3010 processing is suppressed. This option can be used by a package to
3011 determine where to install a macro file.
3015 Print the names of the files it examines.
3019 Print the version number of Automake and exit.
3022 @item --warnings=@var{category}
3025 Output warnings falling in @var{category}. @var{category} can be
3029 dubious syntactic constructs, underquoted macros, unused macros, etc.
3033 all the warnings, this is the default
3035 turn off all the warnings
3037 treat warnings as errors
3040 All warnings are output by default.
3043 The environment variable @env{WARNINGS} is honored in the same
3044 way as it is for @command{automake} (@pxref{Invoking Automake}).
3048 @node Macro search path
3049 @subsection Macro search path
3051 @cindex Macro search path
3052 @cindex @command{aclocal} search path
3054 By default, @command{aclocal} searches for @file{.m4} files in the following
3055 directories, in this order:
3058 @item @var{acdir-APIVERSION}
3059 This is where the @file{.m4} macros distributed with automake itself
3060 are stored. @var{APIVERSION} depends on the automake release used;
3061 for automake 1.6.x, @var{APIVERSION} = @code{1.6}.
3064 This directory is intended for third party @file{.m4} files, and is
3065 configured when @command{automake} itself is built. This is
3066 @file{@@datadir@@/aclocal/}, which typically
3067 expands to @file{$@{prefix@}/share/aclocal/}. To find the compiled-in
3068 value of @var{acdir}, use the @option{--print-ac-dir} option
3069 (@pxref{aclocal options}).
3072 As an example, suppose that @command{automake-1.6.2} was configured with
3073 @option{--prefix=@-/usr/local}. Then, the search path would be:
3076 @item @file{/usr/local/share/aclocal-1.6/}
3077 @item @file{/usr/local/share/aclocal/}
3080 As explained in (@pxref{aclocal options}), there are several options that
3081 can be used to change or extend this search path.
3083 @subsubsection Modifying the macro search path: @option{--acdir}
3085 The most erroneous option to modify the search path is
3086 @option{--acdir=@var{dir}}, which changes default directory and
3087 drops the @var{APIVERSION} directory. For example, if one specifies
3088 @samp{--acdir=/opt/private/}, then the search path becomes:
3091 @item @file{/opt/private/}
3094 This option, @option{--acdir}, is intended for use by the internal
3095 automake test suite only; it is not ordinarily needed by end-users.
3097 @subsubsection Modifying the macro search path: @samp{-I @var{dir}}
3099 Any extra directories specified using @option{-I} options
3100 (@pxref{aclocal options}) are @emph{prepended} to this search list. Thus,
3101 @samp{aclocal -I /foo -I /bar} results in the following search path:
3106 @item @var{acdir}-@var{APIVERSION}
3110 @subsubsection Modifying the macro search path: @file{dirlist}
3111 @cindex @file{dirlist}
3113 There is a third mechanism for customizing the search path. If a
3114 @file{dirlist} file exists in @var{acdir}, then that file is assumed to
3115 contain a list of directory patterns, one per line. @command{aclocal}
3116 expands these patterns to directory names, and adds them to the search
3117 list @emph{after} all other directories. @file{dirlist} entries may
3118 use shell wildcards such as @samp{*}, @samp{?}, or @code{[...]}.
3120 For example, suppose
3121 @file{@var{acdir}/dirlist} contains the following:
3130 and that @command{aclocal} was called with the @samp{-I /foo -I /bar} options.
3131 Then, the search path would be
3133 @c @code looks better than @file here
3137 @item @var{acdir}-@var{APIVERSION}
3144 and all directories with path names starting with @code{/test3}.
3146 If the @option{--acdir=@var{dir}} option is used, then @command{aclocal}
3147 will search for the @file{dirlist} file in @var{dir}. In the
3148 @samp{--acdir=/opt/private/} example above, @command{aclocal} would look
3149 for @file{/opt/private/dirlist}. Again, however, the @option{--acdir}
3150 option is intended for use by the internal automake test suite only;
3151 @option{--acdir} is not ordinarily needed by end-users.
3153 @file{dirlist} is useful in the following situation: suppose that
3154 @command{automake} version @code{1.6.2} is installed with
3155 @samp{--prefix=/usr} by the system vendor. Thus, the default search
3158 @c @code looks better than @file here
3160 @item @code{/usr/share/aclocal-1.6/}
3161 @item @code{/usr/share/aclocal/}
3164 However, suppose further that many packages have been manually
3165 installed on the system, with $prefix=/usr/local, as is typical. In
3166 that case, many of these ``extra'' @file{.m4} files are in
3167 @file{/usr/local/share/aclocal}. The only way to force
3168 @file{/usr/bin/aclocal} to find these ``extra'' @file{.m4} files is to
3169 always call @samp{aclocal -I /usr/local/share/aclocal}. This is
3170 inconvenient. With @file{dirlist}, one may create a file
3171 @file{/usr/share/aclocal/dirlist} containing only the single line
3174 /usr/local/share/aclocal
3177 Now, the ``default'' search path on the affected system is
3179 @c @code looks better than @file here
3181 @item @code{/usr/share/aclocal-1.6/}
3182 @item @code{/usr/share/aclocal/}
3183 @item @code{/usr/local/share/aclocal/}
3186 without the need for @option{-I} options; @option{-I} options can be reserved
3187 for project-specific needs (@file{my-source-dir/m4/}), rather than
3188 using it to work around local system-dependent tool installation
3191 Similarly, @file{dirlist} can be handy if you have installed a local
3192 copy Automake on your account and want @command{aclocal} to look for
3193 macros installed at other places on the system.
3196 @node Extending aclocal
3197 @subsection Writing your own aclocal macros
3199 @cindex @command{aclocal}, extending
3200 @cindex Extending @command{aclocal}
3202 The @command{aclocal} program doesn't have any built-in knowledge of any
3203 macros, so it is easy to extend it with your own macros.
3205 This can be used by libraries that want to supply their own Autoconf
3206 macros for use by other programs. For instance, the @command{gettext}
3207 library supplies a macro @code{AM_GNU_GETTEXT} that should be used by
3208 any package using @command{gettext}. When the library is installed, it
3209 installs this macro so that @command{aclocal} will find it.
3211 A macro file's name should end in @file{.m4}. Such files should be
3212 installed in @file{$(datadir)/aclocal}. This is as simple as writing:
3215 aclocaldir = $(datadir)/aclocal
3216 aclocal_DATA = mymacro.m4 myothermacro.m4
3220 Please do use @file{$(datadir)/aclocal}, and not something based on
3221 the result of @samp{aclocal --print-ac-dir}. @xref{Hard-Coded Install
3222 Paths}, for arguments.
3224 A file of macros should be a series of properly quoted
3225 @code{AC_DEFUN}'s (@pxref{Macro Definitions, , , autoconf, The
3226 Autoconf Manual}). The @command{aclocal} programs also understands
3227 @code{AC_REQUIRE} (@pxref{Prerequisite Macros, , , autoconf, The
3228 Autoconf Manual}), so it is safe to put each macro in a separate file.
3229 Each file should have no side effects but macro definitions.
3230 Especially, any call to @code{AC_PREREQ} should be done inside the
3231 defined macro, not at the beginning of the file.
3233 @cindex underquoted @code{AC_DEFUN}
3237 Starting with Automake 1.8, @command{aclocal} will warn about all
3238 underquoted calls to @code{AC_DEFUN}. We realize this will annoy a
3239 lot of people, because @command{aclocal} was not so strict in the past
3240 and many third party macros are underquoted; and we have to apologize
3241 for this temporary inconvenience. The reason we have to be stricter
3242 is that a future implementation of @command{aclocal} (@pxref{Future of
3243 aclocal}) will have to temporarily include all these third party
3244 @file{.m4} files, maybe several times, including even files that are
3245 not actually needed. Doing so should alleviate many problems of the
3246 current implementation, however it requires a stricter style from the
3247 macro authors. Hopefully it is easy to revise the existing macros.
3253 [AC_REQUIRE([AX_SOMETHING])dnl
3259 should be rewritten as
3261 AC_DEFUN([AX_FOOBAR],
3262 [AC_PREREQ([2.57])dnl
3263 AC_REQUIRE([AX_SOMETHING])dnl
3269 Wrapping the @code{AC_PREREQ} call inside the macro ensures that
3270 Autoconf 2.57 will not be required if @code{AX_FOOBAR} is not actually
3271 used. Most importantly, quoting the first argument of @code{AC_DEFUN}
3272 allows the macro to be redefined or included twice (otherwise this
3273 first argument would be expanded during the second definition). For
3274 consistency we like to quote even arguments such as @code{2.57} that
3277 If you have been directed here by the @command{aclocal} diagnostic but
3278 are not the maintainer of the implicated macro, you will want to
3279 contact the maintainer of that macro. Please make sure you have the
3280 last version of the macro and that the problem already hasn't been
3281 reported before doing so: people tend to work faster when they aren't
3284 Another situation where @command{aclocal} is commonly used is to
3285 manage macros that are used locally by the package, @ref{Local
3289 @subsection Handling Local Macros
3291 Feature tests offered by Autoconf do not cover all needs. People
3292 often have to supplement existing tests with their own macros, or
3293 with third-party macros.
3295 There are two ways to organize custom macros in a package.
3297 The first possibility (the historical practice) is to list all your
3298 macros in @file{acinclude.m4}. This file will be included in
3299 @file{aclocal.m4} when you run @command{aclocal}, and its macro(s) will
3300 henceforth be visible to @command{autoconf}. However if it contains
3301 numerous macros, it will rapidly become difficult to maintain, and it
3302 will be almost impossible to share macros between packages.
3304 @vindex ACLOCAL_AMFLAGS
3305 The second possibility, which we do recommend, is to write each macro
3306 in its own file and gather all these files in a directory. This
3307 directory is usually called @file{m4/}. To build @file{aclocal.m4},
3308 one should therefore instruct @command{aclocal} to scan @file{m4/}.
3309 From the command line, this is done with @samp{aclocal -I m4}. The
3310 top-level @file{Makefile.am} should also be updated to define
3313 ACLOCAL_AMFLAGS = -I m4
3316 @code{ACLOCAL_AMFLAGS} contains options to pass to @command{aclocal}
3317 when @file{aclocal.m4} is to be rebuilt by @command{make}. This line is
3318 also used by @command{autoreconf} (@pxref{autoreconf Invocation, ,
3319 Using @command{autoreconf} to Update @file{configure} Scripts,
3320 autoconf, The Autoconf Manual}) to run @command{aclocal} with suitable
3321 options, or by @command{autopoint} (@pxref{autopoint Invocation, ,
3322 Invoking the @command{autopoint} Program, gettext, GNU gettext tools})
3323 and @command{gettextize} (@pxref{gettextize Invocation, , Invoking the
3324 @command{gettextize} Program, gettext, GNU gettext tools}) to locate
3325 the place where Gettext's macros should be installed. So even if you
3326 do not really care about the rebuild rules, you should define
3327 @code{ACLOCAL_AMFLAGS}.
3329 When @samp{aclocal -I m4} is run, it will build a @file{aclocal.m4}
3330 that @code{m4_include}s any file from @file{m4/} that defines a
3331 required macro. Macros not found locally will still be searched in
3332 system-wide directories, as explained in @ref{Macro search path}.
3334 Custom macros should be distributed for the same reason that
3335 @file{configure.ac} is: so that other people have all the sources of
3336 your package if they want to work on it. Actually, this distribution
3337 happens automatically because all @code{m4_include}d files are
3340 However there is no consensus on the distribution of third-party
3341 macros that your package may use. Many libraries install their own
3342 macro in the system-wide @command{aclocal} directory (@pxref{Extending
3343 aclocal}). For instance, Guile ships with a file called
3344 @file{guile.m4} that contains the macro @code{GUILE_FLAGS} that can
3345 be used to define setup compiler and linker flags appropriate for
3346 using Guile. Using @code{GUILE_FLAGS} in @file{configure.ac} will
3347 cause @command{aclocal} to copy @file{guile.m4} into
3348 @file{aclocal.m4}, but as @file{guile.m4} is not part of the project,
3349 it will not be distributed. Technically, that means a user who
3350 needs to rebuild @file{aclocal.m4} will have to install Guile first.
3351 This is probably OK, if Guile already is a requirement to build the
3352 package. However, if Guile is only an optional feature, or if your
3353 package might run on architectures where Guile cannot be installed,
3354 this requirement will hinder development. An easy solution is to copy
3355 such third-party macros in your local @file{m4/} directory so they get
3358 Since Automake 1.10, @command{aclocal} offers an option to copy these
3359 system-wide third-party macros in your local macro directory, solving
3360 the above problem. Simply use:
3363 ACLOCAL_AMFLAGS = -I m4 --install
3367 With this setup, system-wide macros will be copied to @file{m4/}
3368 the first time you run @command{autoreconf}. Then the locally
3369 installed macros will have precedence over the system-wide installed
3370 macros each time @command{aclocal} is run again.
3372 One reason why you should keep @option{--install} in the flags even
3373 after the first run is that when you later edit @file{configure.ac}
3374 and depend on a new macro, this macro will be installed in your
3375 @file{m4/} automatically. Another one is that serial numbers
3376 (@pxref{Serials}) can be used to update the macros in your source tree
3377 automatically when new system-wide versions are installed. A serial
3378 number should be a single line of the form
3385 where @var{NNN} contains only digits and dots. It should appear in
3386 the M4 file before any macro definition. It is a good practice to
3387 maintain a serial number for each macro you distribute, even if you do
3388 not use the @option{--install} option of @command{aclocal}: this allows
3389 other people to use it.
3393 @subsection Serial Numbers
3394 @cindex serial numbers in macros
3395 @cindex macro serial numbers
3396 @cindex @code{#serial} syntax
3397 @cindex @command{aclocal} and serial numbers
3399 Because third-party macros defined in @file{*.m4} files are naturally
3400 shared between multiple projects, some people like to version them.
3401 This makes it easier to tell which of two M4 files is newer. Since at
3402 least 1996, the tradition is to use a @samp{#serial} line for this.
3404 A serial number should be a single line of the form
3407 # serial @var{version}
3411 where @var{version} is a version number containing only digits and
3412 dots. Usually people use a single integer, and they increment it each
3413 time they change the macro (hence the name of ``serial''). Such a
3414 line should appear in the M4 file before any macro definition.
3416 The @samp{#} must be the first character on the line,
3417 and it is OK to have extra words after the version, as in
3420 #serial @var{version} @var{garbage}
3423 Normally these serial numbers are completely ignored by
3424 @command{aclocal} and @command{autoconf}, like any genuine comment.
3425 However when using @command{aclocal}'s @option{--install} feature, these
3426 serial numbers will modify the way @command{aclocal} selects the
3427 macros to install in the package: if two files with the same basename
3428 exists in your search path, and if at least one of them use a
3429 @samp{#serial} line, @command{aclocal} will ignore the file that has
3430 the older @samp{#serial} line (or the file that has none).
3432 Note that a serial number applies to a whole M4 file, not to any macro
3433 it contains. A file can contains multiple macros, but only one
3436 Here is a use case that illustrate the use of @option{--install} and
3437 its interaction with serial numbers. Let's assume we maintain a
3438 package called MyPackage, the @file{configure.ac} of which requires a
3439 third-party macro @code{AX_THIRD_PARTY} defined in
3440 @file{/usr/share/aclocal/thirdparty.m4} as follows:
3444 AC_DEFUN([AX_THIRD_PARTY], [...])
3447 MyPackage uses an @file{m4/} directory to store local macros as
3448 explained in @ref{Local Macros}, and has
3451 ACLOCAL_AMFLAGS = -I m4 --install
3455 in its top-level @file{Makefile.am}.
3457 Initially the @file{m4/} directory is empty. The first time we run
3458 @command{autoreconf}, it will fetch the options to pass to
3459 @command{aclocal} in @file{Makefile.am}, and run @samp{aclocal -I m4
3460 --install}. @command{aclocal} will notice that
3464 @file{configure.ac} uses @code{AX_THIRD_PARTY}
3466 No local macros define @code{AX_THIRD_PARTY}
3468 @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3473 Because @file{/usr/share/aclocal/thirdparty.m4} is a system-wide macro
3474 and @command{aclocal} was given the @option{--install} option, it will
3475 copy this file in @file{m4/thirdparty.m4}, and output an
3476 @file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}.
3478 The next time @samp{aclocal -I m4 --install} is run (either via
3479 @command{autoreconf}, by hand, or from the @file{Makefile} rebuild
3480 rules) something different happens. @command{aclocal} notices that
3484 @file{configure.ac} uses @code{AX_THIRD_PARTY}
3486 @file{m4/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3489 @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3494 Because both files have the same serial number, @command{aclocal} uses
3495 the first it found in its search path order (@pxref{Macro search
3496 path}). @command{aclocal} therefore ignores
3497 @file{/usr/share/aclocal/thirdparty.m4} and outputs an
3498 @file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}.
3500 Local directories specified with @option{-I} are always searched before
3501 system-wide directories, so a local file will always be preferred to
3502 the system-wide file in case of equal serial numbers.
3504 Now suppose the system-wide third-party macro is changed. This can
3505 happen if the package installing this macro is updated. Let's suppose
3506 the new macro has serial number 2. The next time @samp{aclocal -I m4
3507 --install} is run the situation is the following:
3511 @file{configure.ac} uses @code{AX_THIRD_PARTY}
3513 @file{m4/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3516 @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3521 When @command{aclocal} sees a greater serial number, it immediately
3522 forgets anything it knows from files that have the same basename and a
3523 smaller serial number. So after it has found
3524 @file{/usr/share/aclocal/thirdparty.m4} with serial 2,
3525 @command{aclocal} will proceed as if it had never seen
3526 @file{m4/thirdparty.m4}. This brings us back to a situation similar
3527 to that at the beginning of our example, where no local file defined
3528 the macro. @command{aclocal} will install the new version of the
3529 macro in @file{m4/thirdparty.m4}, in this case overriding the old
3530 version. MyPackage just had its macro updated as a side effect of
3531 running @command{aclocal}.
3533 If you are leery of letting @command{aclocal} update your local macro,
3534 you can run @samp{aclocal -I m4 --diff} to review the changes
3535 @samp{aclocal -I m4 --install} would perform on these macros.
3537 Finally, note that the @option{--force} option of @command{aclocal} has
3538 absolutely no effect on the files installed by @option{--install}. For
3539 instance, if you have modified your local macros, do not expect
3540 @option{--install --force} to replace the local macros by their
3541 system-wide versions. If you want to do so, simply erase the local
3542 macros you want to revert, and run @samp{aclocal -I m4 --install}.
3545 @node Future of aclocal
3546 @subsection The Future of @command{aclocal}
3547 @cindex @command{aclocal}'s scheduled death
3549 @command{aclocal} is expected to disappear. This feature really
3550 should not be offered by Automake. Automake should focus on
3551 generating @file{Makefile}s; dealing with M4 macros really is
3552 Autoconf's job. That some people install Automake just to use
3553 @command{aclocal}, but do not use @command{automake} otherwise is an
3554 indication of how that feature is misplaced.
3556 The new implementation will probably be done slightly differently.
3557 For instance, it could enforce the @file{m4/}-style layout discussed in
3560 We have no idea when and how this will happen. This has been
3561 discussed several times in the past, but someone still has to commit
3562 itself to that non-trivial task.
3564 From the user point of view, @command{aclocal}'s removal might turn
3565 out to be painful. There is a simple precaution that you may take to
3566 make that switch more seamless: never call @command{aclocal} yourself.
3567 Keep this guy under the exclusive control of @command{autoreconf} and
3568 Automake's rebuild rules. Hopefully you won't need to worry about
3569 things breaking, when @command{aclocal} disappears, because everything
3570 will have been taken care of. If otherwise you used to call
3571 @command{aclocal} directly yourself or from some script, you will
3572 quickly notice the change.
3574 Many packages come with a script called @file{bootstrap.sh} or
3575 @file{autogen.sh}, that will just call @command{aclocal},
3576 @command{libtoolize}, @command{gettextize} or @command{autopoint},
3577 @command{autoconf}, @command{autoheader}, and @command{automake} in
3578 the right order. Actually this is precisely what @command{autoreconf}
3579 can do for you. If your package has such a @file{bootstrap.sh} or
3580 @file{autogen.sh} script, consider using @command{autoreconf}. That
3581 should simplify its logic a lot (less things to maintain, yum!), it's
3582 even likely you will not need the script anymore, and more to the point
3583 you will not call @command{aclocal} directly anymore.
3585 For the time being, third-party packages should continue to install
3586 public macros into @file{/usr/share/aclocal/}. If @command{aclocal}
3587 is replaced by another tool it might make sense to rename the
3588 directory, but supporting @file{/usr/share/aclocal/} for backward
3589 compatibility should be really easy provided all macros are properly
3590 written (@pxref{Extending aclocal}).
3595 @section Autoconf macros supplied with Automake
3597 Automake ships with several Autoconf macros that you can use from your
3598 @file{configure.ac}. When you use one of them it will be included by
3599 @command{aclocal} in @file{aclocal.m4}.
3602 * Public macros:: Macros that you can use.
3603 * Obsolete macros:: Macros that you should stop using.
3604 * Private macros:: Macros that you should not use.
3607 @c consider generating the following subsections automatically from m4 files.
3610 @subsection Public macros
3614 @item AM_ENABLE_MULTILIB
3615 @acindex AM_ENABLE_MULTILIB
3616 This is used when a ``multilib'' library is being built. The first
3617 optional argument is the name of the @file{Makefile} being generated; it
3618 defaults to @samp{Makefile}. The second option argument is used to find
3619 the top source directory; it defaults to the empty string (generally
3620 this should not be used unless you are familiar with the internals).
3623 @item AM_INIT_AUTOMAKE([OPTIONS])
3624 @itemx AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])
3625 @acindex AM_INIT_AUTOMAKE
3626 Runs many macros required for proper operation of the generated Makefiles.
3628 @vindex AUTOMAKE_OPTIONS
3629 This macro has two forms, the first of which is preferred.
3630 In this form, @code{AM_INIT_AUTOMAKE} is called with a
3631 single argument: a space-separated list of Automake options that should
3632 be applied to every @file{Makefile.am} in the tree. The effect is as if
3633 each option were listed in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
3636 The second, deprecated, form of @code{AM_INIT_AUTOMAKE} has two required
3637 arguments: the package and the version number. This form is
3638 obsolete because the @var{package} and @var{version} can be obtained
3639 from Autoconf's @code{AC_INIT} macro (which itself has an old and a new
3642 If your @file{configure.ac} has:
3645 AC_INIT([src/foo.c])
3646 AM_INIT_AUTOMAKE([mumble], [1.5])
3650 you can modernize it as follows:
3653 AC_INIT([mumble], [1.5])
3654 AC_CONFIG_SRCDIR([src/foo.c])
3658 Note that if you're upgrading your @file{configure.ac} from an earlier
3659 version of Automake, it is not always correct to simply move the
3660 package and version arguments from @code{AM_INIT_AUTOMAKE} directly to
3661 @code{AC_INIT}, as in the example above. The first argument to
3662 @code{AC_INIT} should be the name of your package (e.g., @samp{GNU
3663 Automake}), not the tarball name (e.g., @samp{automake}) that you used
3664 to pass to @code{AM_INIT_AUTOMAKE}. Autoconf tries to derive a
3665 tarball name from the package name, which should work for most but not
3666 all package names. (If it doesn't work for yours, you can use the
3667 four-argument form of @code{AC_INIT} to provide the tarball name
3670 @cindex @code{PACKAGE}, prevent definition
3671 @cindex @code{VERSION}, prevent definition
3673 By default this macro @code{AC_DEFINE}'s @code{PACKAGE} and
3674 @code{VERSION}. This can be avoided by passing the @option{no-define}
3677 AM_INIT_AUTOMAKE([gnits 1.5 no-define dist-bzip2])
3679 or by passing a third non-empty argument to the obsolete form.
3681 @item AM_PATH_LISPDIR
3682 @acindex AM_PATH_LISPDIR
3685 Searches for the program @command{emacs}, and, if found, sets the
3686 output variable @code{lispdir} to the full path to Emacs' site-lisp
3689 Note that this test assumes the @command{emacs} found to be a version
3690 that supports Emacs Lisp (such as @sc{gnu} Emacs or XEmacs). Other
3691 emacsen can cause this test to hang (some, like old versions of
3692 MicroEmacs, start up in interactive mode, requiring @kbd{C-x C-c} to
3693 exit, which is hardly obvious for a non-emacs user). In most cases,
3694 however, you should be able to use @kbd{C-c} to kill the test. In
3695 order to avoid problems, you can set @env{EMACS} to ``no'' in the
3696 environment, or use the @option{--with-lispdir} option to
3697 @command{configure} to explicitly set the correct path (if you're sure
3698 you have an @command{emacs} that supports Emacs Lisp.
3704 Use this macro when you have assembly code in your project. This will
3705 choose the assembler for you (by default the C compiler) and set
3706 @code{CCAS}, and will also set @code{CCASFLAGS} if required.
3708 @item AM_PROG_CC_C_O
3709 @acindex AM_PROG_CC_C_O
3710 @acindex AC_PROG_CC_C_O
3711 This is like @code{AC_PROG_CC_C_O}, but it generates its results in
3712 the manner required by automake. You must use this instead of
3713 @code{AC_PROG_CC_C_O} when you need this functionality, that is, when
3714 using per-target flags or subdir-objects with C sources.
3717 @acindex AM_PROG_LEX
3718 @acindex AC_PROG_LEX
3719 @cindex HP-UX 10, @command{lex} problems
3720 @cindex @command{lex} problems with HP-UX 10
3721 Like @code{AC_PROG_LEX} (@pxref{Particular Programs, , Particular
3722 Program Checks, autoconf, The Autoconf Manual}), but uses the
3723 @command{missing} script on systems that do not have @command{lex}.
3724 HP-UX 10 is one such system.
3727 @acindex AM_PROG_GCJ
3730 This macro finds the @command{gcj} program or causes an error. It sets
3731 @code{GCJ} and @code{GCJFLAGS}. @command{gcj} is the Java front-end to the
3732 GNU Compiler Collection.
3734 @item AM_PROG_UPC([@var{compiler-search-list}])
3735 @acindex AM_PROG_UPC
3737 Find a compiler for Unified Parallel C and define the @code{UPC}
3738 variable. The default @var{compiler-search-list} is @samp{upcc upc}.
3739 This macro will abort @command{configure} if no Unified Parallel C
3742 @item AM_WITH_DMALLOC
3743 @acindex AM_WITH_DMALLOC
3744 @cindex @command{dmalloc}, support for
3745 @vindex WITH_DMALLOC
3746 @opindex --with-dmalloc
3747 Add support for the @uref{http://dmalloc.com/, Dmalloc package}. If
3748 the user runs @command{configure} with @option{--with-dmalloc}, then
3749 define @code{WITH_DMALLOC} and add @option{-ldmalloc} to @code{LIBS}.
3752 @acindex AM_WITH_REGEX
3754 @opindex --with-regex
3755 @cindex regex package
3757 Adds @option{--with-regex} to the @command{configure} command line. If
3758 specified (the default), then the @samp{regex} regular expression
3759 library is used, @file{regex.o} is put into @code{LIBOBJS}, and
3760 @code{WITH_REGEX} is defined. If @option{--without-regex} is given, then
3761 the @code{rx} regular expression library is used, and @file{rx.o} is put
3762 into @code{LIBOBJS}.
3767 @node Obsolete macros
3768 @subsection Obsolete macros
3769 @cindex obsolete macros
3772 Although using some of the following macros was required in past
3773 releases, you should not use any of them in new code. Running
3774 @command{autoupdate} should adjust your @file{configure.ac}
3775 automatically (@pxref{autoupdate Invocation, , Using
3776 @command{autoupdate} to Modernize @file{configure.ac}, autoconf, The
3780 @item AM_C_PROTOTYPES
3781 @acindex AM_C_PROTOTYPES
3784 Check to see if function prototypes are understood by the compiler. If
3785 so, define @samp{PROTOTYPES} and set the output variables @code{U} and
3786 @code{ANSI2KNR} to the empty string. Otherwise, set @code{U} to
3787 @samp{_} and @code{ANSI2KNR} to @samp{./ansi2knr}. Automake uses these
3788 values to implement the obsolete de-ANSI-fication feature.
3790 @item AM_CONFIG_HEADER
3791 @acindex AM_CONFIG_HEADER
3792 Automake will generate rules to automatically regenerate the config
3793 header. This obsolete macro is a synonym of @code{AC_CONFIG_HEADERS}
3794 today (@pxref{Optional}).
3796 @item AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
3797 @acindex AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
3798 If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
3799 define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be
3800 found in @file{<termios.h>}. This macro is obsolete, you should
3801 use Autoconf's @code{AC_HEADER_TIOCGWINSZ} instead.
3803 @item AM_PROG_MKDIR_P
3804 @acindex AM_PROG_MKDIR_P
3805 @cindex @code{mkdir -p}, macro check
3809 From Automake 1.8 to 1.9.6 this macro used to define the output
3810 variable @code{mkdir_p} to one of @code{mkdir -p}, @code{install-sh
3811 -d}, or @code{mkinstalldirs}.
3813 Nowadays Autoconf provides a similar functionality with
3814 @code{AC_PROG_MKDIR_P} (@pxref{Particular Programs, , Particular
3815 Program Checks, autoconf, The Autoconf Manual}), however this defines
3816 the output variable @code{MKDIR_P} instead. Therefore
3817 @code{AM_PROG_MKDIR_P} has been rewritten as a thin wrapper around
3818 @code{AC_PROG_MKDIR_P} to define @code{mkdir_p} to the same value as
3819 @code{MKDIR_P} for backward compatibility.
3821 If you are using Automake, there is normally no reason to call this
3822 macro, because @code{AM_INIT_AUTOMAKE} already does so. However, make
3823 sure that the custom rules in your @file{Makefile}s use
3824 @code{$(MKDIR_P)} and not @code{$(mkdir_p)}. Even if both variables
3825 still work, the latter should be considered obsolete.
3827 If you are not using Automake, please call @code{AC_PROG_MKDIR_P}
3828 instead of @code{AM_PROG_MKDIR_P}.
3830 @item AM_SYS_POSIX_TERMIOS
3831 @acindex AM_SYS_POSIX_TERMIOS
3832 @cindex POSIX termios headers
3833 @cindex termios POSIX headers
3834 Check to see if POSIX termios headers and functions are available on the
3835 system. If so, set the shell variable @code{am_cv_sys_posix_termios} to
3836 @samp{yes}. If not, set the variable to @samp{no}. This macro is obsolete,
3837 you should use Autoconf's @code{AC_SYS_POSIX_TERMIOS} instead.
3842 @node Private macros
3843 @subsection Private macros
3845 The following macros are private macros you should not call directly.
3846 They are called by the other public macros when appropriate. Do not
3847 rely on them, as they might be changed in a future version. Consider
3848 them as implementation details; or better, do not consider them at all:
3852 @item _AM_DEPENDENCIES
3853 @itemx AM_SET_DEPDIR
3855 @itemx AM_OUTPUT_DEPENDENCY_COMMANDS
3856 These macros are used to implement Automake's automatic dependency
3857 tracking scheme. They are called automatically by automake when
3858 required, and there should be no need to invoke them manually.
3860 @item AM_MAKE_INCLUDE
3861 This macro is used to discover how the user's @command{make} handles
3862 @code{include} statements. This macro is automatically invoked when
3863 needed; there should be no need to invoke it manually.
3865 @item AM_PROG_INSTALL_STRIP
3866 This is used to find a version of @code{install} that can be used to
3867 strip a program at installation time. This macro is automatically
3868 included when required.
3870 @item AM_SANITY_CHECK
3871 This checks to make sure that a file created in the build directory is
3872 newer than a file in the source directory. This can fail on systems
3873 where the clock is set incorrectly. This macro is automatically run
3874 from @code{AM_INIT_AUTOMAKE}.
3880 @chapter Directories
3882 For simple projects that distributes all files in the same directory
3883 it is enough to have a single @file{Makefile.am} that builds
3884 everything in place.
3886 In larger projects it is common to organize files in different
3887 directories, in a tree. For instance one directory per program, per
3888 library or per module. The traditional approach is to build these
3889 subdirectory recursively: each directory contains its @file{Makefile}
3890 (generated from @file{Makefile.am}), and when @command{make} is run
3891 from the top level directory it enters each subdirectory in turn to
3895 * Subdirectories:: Building subdirectories recursively
3896 * Conditional Subdirectories:: Conditionally not building directories
3897 * Alternative:: Subdirectories without recursion
3898 * Subpackages:: Nesting packages
3901 @node Subdirectories
3902 @section Recursing subdirectories
3904 @cindex @code{SUBDIRS}, explained
3906 In packages with subdirectories, the top level @file{Makefile.am} must
3907 tell Automake which subdirectories are to be built. This is done via
3908 the @code{SUBDIRS} variable.
3911 The @code{SUBDIRS} variable holds a list of subdirectories in which
3912 building of various sorts can occur. The rules for many targets
3913 (e.g., @code{all}) in the generated @file{Makefile} will run commands
3914 both locally and in all specified subdirectories. Note that the
3915 directories listed in @code{SUBDIRS} are not required to contain
3916 @file{Makefile.am}s; only @file{Makefile}s (after configuration).
3917 This allows inclusion of libraries from packages that do not use
3918 Automake (such as @code{gettext}; see also @ref{Third-Party
3921 In packages that use subdirectories, the top-level @file{Makefile.am} is
3922 often very short. For instance, here is the @file{Makefile.am} from the
3923 GNU Hello distribution:
3926 EXTRA_DIST = BUGS ChangeLog.O README-alpha
3927 SUBDIRS = doc intl po src tests
3930 When Automake invokes @command{make} in a subdirectory, it uses the value
3931 of the @code{MAKE} variable. It passes the value of the variable
3932 @code{AM_MAKEFLAGS} to the @command{make} invocation; this can be set in
3933 @file{Makefile.am} if there are flags you must always pass to
3936 @vindex AM_MAKEFLAGS
3938 The directories mentioned in @code{SUBDIRS} are usually direct
3939 children of the current directory, each subdirectory containing its
3940 own @file{Makefile.am} with a @code{SUBDIRS} pointing to deeper
3941 subdirectories. Automake can be used to construct packages of
3942 arbitrary depth this way.
3944 By default, Automake generates @file{Makefiles} that work depth-first
3945 in postfix order: the subdirectories are built before the current
3946 directory. However, it is possible to change this ordering. You can
3947 do this by putting @samp{.} into @code{SUBDIRS}. For instance,
3948 putting @samp{.} first will cause a prefix ordering of
3954 SUBDIRS = lib src . test
3958 will cause @file{lib/} to be built before @file{src/}, then the
3959 current directory will be built, finally the @file{test/} directory
3960 will be built. It is customary to arrange test directories to be
3961 built after everything else since they are meant to test what has
3964 All @code{clean} rules are run in reverse order of build rules.
3966 @node Conditional Subdirectories
3967 @section Conditional Subdirectories
3968 @cindex Subdirectories, building conditionally
3969 @cindex Conditional subdirectories
3970 @cindex @code{SUBDIRS}, conditional
3971 @cindex Conditional @code{SUBDIRS}
3973 It is possible to define the @code{SUBDIRS} variable conditionally if,
3974 like in the case of GNU Inetutils, you want to only build a subset of
3977 To illustrate how this works, let's assume we have two directories
3978 @file{src/} and @file{opt/}. @file{src/} should always be built, but we
3979 want to decide in @command{configure} whether @file{opt/} will be built
3980 or not. (For this example we will assume that @file{opt/} should be
3981 built when the variable @samp{$want_opt} was set to @samp{yes}.)
3983 Running @command{make} should thus recurse into @file{src/} always, and
3984 then maybe in @file{opt/}.
3986 However @samp{make dist} should always recurse into both @file{src/}
3987 and @file{opt/}. Because @file{opt/} should be distributed even if it
3988 is not needed in the current configuration. This means
3989 @file{opt/Makefile} should be created @emph{unconditionally}.
3991 There are two ways to setup a project like this. You can use Automake
3992 conditionals (@pxref{Conditionals}) or use Autoconf @code{AC_SUBST}
3993 variables (@pxref{Setting Output Variables, , Setting Output
3994 Variables, autoconf, The Autoconf Manual}). Using Automake
3995 conditionals is the preferred solution. Before we illustrate these
3996 two possibilities, let's introduce @code{DIST_SUBDIRS}.
3998 @subsection @code{SUBDIRS} vs.@: @code{DIST_SUBDIRS}
3999 @cindex @code{DIST_SUBDIRS}, explained
4001 Automake considers two sets of directories, defined by the variables
4002 @code{SUBDIRS} and @code{DIST_SUBDIRS}.
4004 @code{SUBDIRS} contains the subdirectories of the current directory
4005 that must be built (@pxref{Subdirectories}). It must be defined
4006 manually; Automake will never guess a directory is to be built. As we
4007 will see in the next two sections, it is possible to define it
4008 conditionally so that some directory will be omitted from the build.
4010 @code{DIST_SUBDIRS} is used in rules that need to recurse in all
4011 directories, even those that have been conditionally left out of the
4012 build. Recall our example where we may not want to build subdirectory
4013 @file{opt/}, but yet we want to distribute it? This is where
4014 @code{DIST_SUBDIRS} come into play: @samp{opt} may not appear in
4015 @code{SUBDIRS}, but it must appear in @code{DIST_SUBDIRS}.
4017 Precisely, @code{DIST_SUBDIRS} is used by @samp{make
4018 maintainer-clean}, @samp{make distclean} and @samp{make dist}. All
4019 other recursive rules use @code{SUBDIRS}.
4021 If @code{SUBDIRS} is defined conditionally using Automake
4022 conditionals, Automake will define @code{DIST_SUBDIRS} automatically
4023 from the possibles values of @code{SUBDIRS} in all conditions.
4025 If @code{SUBDIRS} contains @code{AC_SUBST} variables,
4026 @code{DIST_SUBDIRS} will not be defined correctly because Automake
4027 does not know the possible values of these variables. In this case
4028 @code{DIST_SUBDIRS} needs to be defined manually.
4030 @subsection Conditional subdirectories with @code{AM_CONDITIONAL}
4031 @cindex @code{SUBDIRS} and @code{AM_CONDITIONAL}
4032 @cindex @code{AM_CONDITIONAL} and @code{SUBDIRS}
4034 @c The test case for the setup described here is
4035 @c test/subdircond2.test
4036 @c Try to keep it in sync.
4038 @file{configure} should output the @file{Makefile} for each directory
4039 and define a condition into which @file{opt/} should be built.
4043 AM_CONDITIONAL([COND_OPT], [test "$want_opt" = yes])
4044 AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
4048 Then @code{SUBDIRS} can be defined in the top-level @file{Makefile.am}
4055 SUBDIRS = src $(MAYBE_OPT)
4058 As you can see, running @command{make} will rightly recurse into
4059 @file{src/} and maybe @file{opt/}.
4061 @vindex DIST_SUBDIRS
4062 As you can't see, running @samp{make dist} will recurse into both
4063 @file{src/} and @file{opt/} directories because @samp{make dist}, unlike
4064 @samp{make all}, doesn't use the @code{SUBDIRS} variable. It uses the
4065 @code{DIST_SUBDIRS} variable.
4067 In this case Automake will define @samp{DIST_SUBDIRS = src opt}
4068 automatically because it knows that @code{MAYBE_OPT} can contain
4069 @samp{opt} in some condition.
4071 @subsection Conditional Subdirectories with @code{AC_SUBST}
4072 @cindex @code{SUBDIRS} and @code{AC_SUBST}
4073 @cindex @code{AC_SUBST} and @code{SUBDIRS}
4075 @c The test case for the setup described here is
4076 @c test/subdircond3.test
4077 @c Try to keep it in sync.
4079 Another possibility is to define @code{MAYBE_OPT} from
4080 @file{./configure} using @code{AC_SUBST}:
4084 if test "$want_opt" = yes; then
4089 AC_SUBST([MAYBE_OPT])
4090 AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
4094 In this case the top-level @file{Makefile.am} should look as follows.
4097 SUBDIRS = src $(MAYBE_OPT)
4098 DIST_SUBDIRS = src opt
4101 The drawback is that since Automake cannot guess what the possible
4102 values of @code{MAYBE_OPT} are, it is necessary to define
4103 @code{DIST_SUBDIRS}.
4105 @subsection Non-configured Subdirectories
4106 @cindex Subdirectories, configured conditionally
4108 The semantic of @code{DIST_SUBDIRS} is often misunderstood by some
4109 users that try to @emph{configure and build} subdirectories
4110 conditionally. Here by configuring we mean creating the
4111 @file{Makefile} (it might also involve running a nested
4112 @command{configure} script: this is a costly operation that explains
4113 why people want to do it conditionally, but only the @file{Makefile}
4114 is relevant to the discussion).
4116 The above examples all assume that every @file{Makefile} is created,
4117 even in directories that are not going to be built. The simple reason
4118 is that we want @samp{make dist} to distribute even the directories
4119 that are not being built (e.g., platform-dependent code), hence
4120 @file{make dist} must recurse into the subdirectory, hence this
4121 directory must be configured and appear in @code{DIST_SUBDIRS}.
4123 Building packages that do not configure every subdirectory is a tricky
4124 business, and we do not recommend it to the novice as it is easy to
4125 produce an incomplete tarball by mistake. We will not discuss this
4126 topic in depth here, yet for the adventurous here are a few rules to
4131 @item @code{SUBDIRS} should always be a subset of @code{DIST_SUBDIRS}.
4133 It makes little sense to have a directory in @code{SUBDIRS} that
4134 is not in @code{DIST_SUBDIRS}. Think of the former as a way to tell
4135 which directories listed in the latter should be built.
4136 @item Any directory listed in @code{DIST_SUBDIRS} and @code{SUBDIRS}
4139 I.e., the @file{Makefile} must exists or the recursive @command{make}
4140 rules will not be able to process the directory.
4141 @item Any configured directory must be listed in @code{DIST_SUBDIRS}.
4143 So that the cleaning rule remove the generated @file{Makefile}s.
4144 It would be correct to see @code{DIST_SUBDIRS} as a variable that
4145 lists all the directories that have been configured.
4149 In order to prevent recursion in some non-configured directory you
4150 must therefore ensure that this directory does not appear in
4151 @code{DIST_SUBDIRS} (and @code{SUBDIRS}). For instance, if you define
4152 @code{SUBDIRS} conditionally using @code{AC_SUBST} and do not define
4153 @code{DIST_SUBDIRS} explicitly, it will be default to
4154 @samp{$(SUBDIRS)}; another possibility is to force @code{DIST_SUBDIRS
4157 Of course, directories that are omitted from @code{DIST_SUBDIRS} will
4158 not be distributed unless you make other arrangements for this to
4159 happen (for instance, always running @samp{make dist} in a
4160 configuration where all directories are known to appear in
4161 @code{DIST_SUBDIRS}; or writing a @code{dist-hook} target to
4162 distribute these directories).
4164 @cindex Subdirectories, not distributed
4165 In few packages, non-configured directories are not even expected to
4166 be distributed. Although these packages do not require the
4167 aforementioned extra arrangements, there is another pitfall. If the
4168 name of a directory appears in @code{SUBDIRS} or @code{DIST_SUBDIRS},
4169 @command{automake} will make sure the directory exists. Consequently
4170 @command{automake} cannot be run on such a distribution when one
4171 directory has been omitted. One way to avoid this check is to use the
4172 @code{AC_SUBST} method to declare conditional directories; since
4173 @command{automake} does not know the values of @code{AC_SUBST}
4174 variables it cannot ensure the corresponding directory exist.
4177 @section An Alternative Approach to Subdirectories
4179 If you've ever read Peter Miller's excellent paper,
4180 @uref{http://www.pcug.org.au/~millerp/rmch/recu-make-cons-harm.html,
4181 Recursive Make Considered Harmful}, the preceding sections on the use of
4182 subdirectories will probably come as unwelcome advice. For those who
4183 haven't read the paper, Miller's main thesis is that recursive
4184 @command{make} invocations are both slow and error-prone.
4186 Automake provides sufficient cross-directory support @footnote{We
4187 believe. This work is new and there are probably warts.
4188 @xref{Introduction}, for information on reporting bugs.} to enable you
4189 to write a single @file{Makefile.am} for a complex multi-directory
4193 By default an installable file specified in a subdirectory will have its
4194 directory name stripped before installation. For instance, in this
4195 example, the header file will be installed as
4196 @file{$(includedir)/stdio.h}:
4199 include_HEADERS = inc/stdio.h
4203 @cindex @code{nobase_} prefix
4204 @cindex Path stripping, avoiding
4205 @cindex Avoiding path stripping
4207 However, the @samp{nobase_} prefix can be used to circumvent this path
4208 stripping. In this example, the header file will be installed as
4209 @file{$(includedir)/sys/types.h}:
4212 nobase_include_HEADERS = sys/types.h
4215 @cindex @code{nobase_} and @code{dist_} or @code{nodist_}
4216 @cindex @code{dist_} and @code{nobase_}
4217 @cindex @code{nodist_} and @code{nobase_}
4221 @samp{nobase_} should be specified first when used in conjunction with
4222 either @samp{dist_} or @samp{nodist_} (@pxref{Dist}). For instance:
4225 nobase_dist_pkgdata_DATA = images/vortex.pgm sounds/whirl.ogg
4228 Finally, note that a variable using the @samp{nobase_} prefix can
4229 always be replaced by several variables, one for each destination
4230 directory (@pxref{Uniform}). For instance, the last example could be
4231 rewritten as follows:
4234 imagesdir = $(pkgdatadir)/images
4235 soundsdir = $(pkgdatadir)/sounds
4236 dist_images_DATA = images/vortex.pgm
4237 dist_sounds_DATA = sounds/whirl.ogg
4241 This latter syntax makes it possible to change one destination
4242 directory without changing the layout of the source tree.
4245 @section Nesting Packages
4246 @cindex Nesting packages
4248 @acindex AC_CONFIG_SUBDIRS
4249 @acindex AC_CONFIG_AUX_DIR
4252 In the GNU Build System, packages can be nested to arbitrary depth.
4253 This means that a package can embedded other packages with their own
4254 @file{configure}, @file{Makefile}s, etc.
4256 These other packages should just appear as subdirectories of their
4257 parent package. They must be listed in @code{SUBDIRS} like other
4258 ordinary directories. However the subpackage's @file{Makefile}s
4259 should be output by its own @file{configure} script, not by the
4260 parent's @file{configure}. This is achieved using the
4261 @code{AC_CONFIG_SUBDIRS} Autoconf macro (@pxref{Subdirectories,
4262 AC_CONFIG_SUBDIRS, Configuring Other Packages in Subdirectories,
4263 autoconf, The Autoconf Manual}).
4265 Here is an example package for an @code{arm} program that links with
4266 an @code{hand} library that is a nested package in subdirectory
4269 @code{arm}'s @file{configure.ac}:
4272 AC_INIT([arm], [1.0])
4273 AC_CONFIG_AUX_DIR([.])
4276 AC_CONFIG_FILES([Makefile])
4277 # Call hand's ./configure script recursively.
4278 AC_CONFIG_SUBDIRS([hand])
4282 @code{arm}'s @file{Makefile.am}:
4285 # Build the library in the hand subdirectory first.
4288 # Include hand's header when compiling this directory.
4289 AM_CPPFLAGS = -I$(srcdir)/hand
4293 # link with the hand library.
4294 arm_LDADD = hand/libhand.a
4297 Now here is @code{hand}'s @file{hand/configure.ac}:
4300 AC_INIT([hand], [1.2])
4301 AC_CONFIG_AUX_DIR([.])
4305 AC_CONFIG_FILES([Makefile])
4310 and its @file{hand/Makefile.am}:
4313 lib_LIBRARIES = libhand.a
4314 libhand_a_SOURCES = hand.c
4317 When @samp{make dist} is run from the top-level directory it will
4318 create an archive @file{arm-1.0.tar.gz} that contains the @code{arm}
4319 code as well as the @file{hand} subdirectory. This package can be
4320 built and installed like any ordinary package, with the usual
4321 @samp{./configure && make && make install} sequence (the @code{hand}
4322 subpackage will be built and installed by the process).
4324 When @samp{make dist} is run from the hand directory, it will create a
4325 self-contained @file{hand-1.2.tar.gz} archive. So although it appears
4326 to be embedded in another package, it can still be used separately.
4328 The purpose of the @samp{AC_CONFIG_AUX_DIR([.])} instruction is to
4329 force Automake and Autoconf to search for auxiliary scripts in the
4330 current directory. For instance, this means that there will be two
4331 copies of @file{install-sh}: one in the top-level of the @code{arm}
4332 package, and another one in the @file{hand/} subdirectory for the
4333 @code{hand} package.
4335 The historical default is to search for these auxiliary scripts in
4336 the parent directory and the grandparent directory. So if the
4337 @samp{AC_CONFIG_AUX_DIR([.])} line was removed from
4338 @file{hand/configure.ac}, that subpackage would share the auxiliary
4339 script of the @code{arm} package. This may looks like a gain in size
4340 (a few kilobytes), but it is actually a loss of modularity as the
4341 @code{hand} subpackage is no longer self-contained (@samp{make dist}
4342 in the subdirectory will not work anymore).
4344 Packages that do not use Automake need more work to be integrated this
4345 way. @xref{Third-Party Makefiles}.
4348 @chapter Building Programs and Libraries
4350 A large part of Automake's functionality is dedicated to making it easy
4351 to build programs and libraries.
4354 * A Program:: Building a program
4355 * A Library:: Building a library
4356 * A Shared Library:: Building a Libtool library
4357 * Program and Library Variables:: Variables controlling program and
4359 * Default _SOURCES:: Default source files
4360 * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
4361 * Program variables:: Variables used when building a program
4362 * Yacc and Lex:: Yacc and Lex support
4363 * C++ Support:: Compiling C++ sources
4364 * Objective C Support:: Compiling Objective C sources
4365 * Unified Parallel C Support:: Compiling Unified Parallel C sources
4366 * Assembly Support:: Compiling assembly sources
4367 * Fortran 77 Support:: Compiling Fortran 77 sources
4368 * Fortran 9x Support:: Compiling Fortran 9x sources
4369 * Java Support:: Compiling Java sources
4370 * Support for Other Languages:: Compiling other languages
4371 * ANSI:: Automatic de-ANSI-fication (obsolete)
4372 * Dependencies:: Automatic dependency tracking
4373 * EXEEXT:: Support for executable extensions
4378 @section Building a program
4380 In order to build a program, you need to tell Automake which sources
4381 are part of it, and which libraries it should be linked with.
4383 This section also covers conditional compilation of sources or
4384 programs. Most of the comments about these also apply to libraries
4385 (@pxref{A Library}) and libtool libraries (@pxref{A Shared Library}).
4388 * Program Sources:: Defining program sources
4389 * Linking:: Linking with libraries or extra objects
4390 * Conditional Sources:: Handling conditional sources
4391 * Conditional Programs:: Building program conditionally
4394 @node Program Sources
4395 @subsection Defining program sources
4397 @cindex @code{PROGRAMS}, @code{bindir}
4399 @vindex bin_PROGRAMS
4400 @vindex sbin_PROGRAMS
4401 @vindex libexec_PROGRAMS
4402 @vindex pkglib_PROGRAMS
4403 @vindex noinst_PROGRAMS
4404 @vindex check_PROGRAMS
4406 In a directory containing source that gets built into a program (as
4407 opposed to a library or a script), the @code{PROGRAMS} primary is used.
4408 Programs can be installed in @code{bindir}, @code{sbindir},
4409 @code{libexecdir}, @code{pkglibdir}, @code{pkglibexecdir}, or not at all
4410 (@code{noinst_}). They can also be built only for @samp{make check}, in
4411 which case the prefix is @samp{check_}.
4416 bin_PROGRAMS = hello
4419 In this simple case, the resulting @file{Makefile.in} will contain code
4420 to generate a program named @code{hello}.
4422 Associated with each program are several assisting variables that are
4423 named after the program. These variables are all optional, and have
4424 reasonable defaults. Each variable, its use, and default is spelled out
4425 below; we use the ``hello'' example throughout.
4427 The variable @code{hello_SOURCES} is used to specify which source files
4428 get built into an executable:
4431 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
4434 This causes each mentioned @file{.c} file to be compiled into the
4435 corresponding @file{.o}. Then all are linked to produce @file{hello}.
4437 @cindex @code{_SOURCES} primary, defined
4438 @cindex @code{SOURCES} primary, defined
4439 @cindex Primary variable, @code{SOURCES}
4442 If @code{hello_SOURCES} is not specified, then it defaults to the single
4443 file @file{hello.c} (@pxref{Default _SOURCES}).
4447 Multiple programs can be built in a single directory. Multiple programs
4448 can share a single source file, which must be listed in each
4449 @code{_SOURCES} definition.
4451 @cindex Header files in @code{_SOURCES}
4452 @cindex @code{_SOURCES} and header files
4454 Header files listed in a @code{_SOURCES} definition will be included in
4455 the distribution but otherwise ignored. In case it isn't obvious, you
4456 should not include the header file generated by @file{configure} in a
4457 @code{_SOURCES} variable; this file should not be distributed. Lex
4458 (@file{.l}) and Yacc (@file{.y}) files can also be listed; see @ref{Yacc
4463 @subsection Linking the program
4465 If you need to link against libraries that are not found by
4466 @command{configure}, you can use @code{LDADD} to do so. This variable is
4467 used to specify additional objects or libraries to link with; it is
4468 inappropriate for specifying specific linker flags, you should use
4469 @code{AM_LDFLAGS} for this purpose.
4473 @cindex @code{prog_LDADD}, defined
4475 Sometimes, multiple programs are built in one directory but do not share
4476 the same link-time requirements. In this case, you can use the
4477 @code{@var{prog}_LDADD} variable (where @var{prog} is the name of the
4478 program as it appears in some @code{_PROGRAMS} variable, and usually
4479 written in lowercase) to override the global @code{LDADD}. If this
4480 variable exists for a given program, then that program is not linked
4484 For instance, in GNU cpio, @code{pax}, @code{cpio} and @code{mt} are
4485 linked against the library @file{libcpio.a}. However, @code{rmt} is
4486 built in the same directory, and has no such link requirement. Also,
4487 @code{mt} and @code{rmt} are only built on certain architectures. Here
4488 is what cpio's @file{src/Makefile.am} looks like (abridged):
4491 bin_PROGRAMS = cpio pax $(MT)
4492 libexec_PROGRAMS = $(RMT)
4493 EXTRA_PROGRAMS = mt rmt
4495 LDADD = ../lib/libcpio.a $(INTLLIBS)
4498 cpio_SOURCES = @dots{}
4499 pax_SOURCES = @dots{}
4500 mt_SOURCES = @dots{}
4501 rmt_SOURCES = @dots{}
4504 @cindex @code{_LDFLAGS}, defined
4505 @vindex maude_LDFLAGS
4506 @code{@var{prog}_LDADD} is inappropriate for passing program-specific
4507 linker flags (except for @option{-l}, @option{-L}, @option{-dlopen} and
4508 @option{-dlpreopen}). So, use the @code{@var{prog}_LDFLAGS} variable for
4511 @cindex @code{_DEPENDENCIES}, defined
4512 @vindex maude_DEPENDENCIES
4513 It is also occasionally useful to have a program depend on some other
4514 target that is not actually part of that program. This can be done
4515 using the @code{@var{prog}_DEPENDENCIES} variable. Each program
4516 depends on the contents of such a variable, but no further
4517 interpretation is done.
4519 Since these dependencies are associated to the link rule used to
4520 create the programs they should normally list files used by the link
4521 command. That is @file{*.$(OBJEXT)}, @file{*.a}, or @file{*.la}
4522 files. In rare cases you may need to add other kinds of files such as
4523 linker scripts, but @emph{listing a source file in
4524 @code{_DEPENDENCIES} is wrong}. If some source file needs to be built
4525 before all the components of a program are built, consider using the
4526 @code{BUILT_SOURCES} variable instead (@pxref{Sources}).
4528 If @code{@var{prog}_DEPENDENCIES} is not supplied, it is computed by
4529 Automake. The automatically-assigned value is the contents of
4530 @code{@var{prog}_LDADD}, with most configure substitutions, @option{-l},
4531 @option{-L}, @option{-dlopen} and @option{-dlpreopen} options removed. The
4532 configure substitutions that are left in are only @samp{$(LIBOBJS)} and
4533 @samp{$(ALLOCA)}; these are left because it is known that they will not
4534 cause an invalid value for @code{@var{prog}_DEPENDENCIES} to be
4537 @ref{Conditional Sources} shows a situation where @code{_DEPENDENCIES}
4540 @cindex @code{LDADD} and @option{-l}
4541 @cindex @option{-l} and @code{LDADD}
4542 We recommend that you avoid using @option{-l} options in @code{LDADD}
4543 or @code{@var{prog}_LDADD} when referring to libraries built by your
4544 package. Instead, write the file name of the library explicitly as in
4545 the above @code{cpio} example. Use @option{-l} only to list
4546 third-party libraries. If you follow this rule, the default value of
4547 @code{@var{prog}_DEPENDENCIES} will list all your local libraries and
4548 omit the other ones.
4551 @node Conditional Sources
4552 @subsection Conditional compilation of sources
4554 You can't put a configure substitution (e.g., @samp{@@FOO@@} or
4555 @samp{$(FOO)} where @code{FOO} is defined via @code{AC_SUBST}) into a
4556 @code{_SOURCES} variable. The reason for this is a bit hard to
4557 explain, but suffice to say that it simply won't work. Automake will
4558 give an error if you try to do this.
4560 Fortunately there are two other ways to achieve the same result. One is
4561 to use configure substitutions in @code{_LDADD} variables, the other is
4562 to use an Automake conditional.
4564 @subsubsection Conditional compilation using @code{_LDADD} substitutions
4566 @cindex @code{EXTRA_prog_SOURCES}, defined
4568 Automake must know all the source files that could possibly go into a
4569 program, even if not all the files are built in every circumstance. Any
4570 files that are only conditionally built should be listed in the
4571 appropriate @code{EXTRA_} variable. For instance, if
4572 @file{hello-linux.c} or @file{hello-generic.c} were conditionally included
4573 in @code{hello}, the @file{Makefile.am} would contain:
4576 bin_PROGRAMS = hello
4577 hello_SOURCES = hello-common.c
4578 EXTRA_hello_SOURCES = hello-linux.c hello-generic.c
4579 hello_LDADD = $(HELLO_SYSTEM)
4580 hello_DEPENDENCIES = $(HELLO_SYSTEM)
4584 You can then setup the @samp{$(HELLO_SYSTEM)} substitution from
4585 @file{configure.ac}:
4590 *linux*) HELLO_SYSTEM='hello-linux.$(OBJEXT)' ;;
4591 *) HELLO_SYSTEM='hello-generic.$(OBJEXT)' ;;
4593 AC_SUBST([HELLO_SYSTEM])
4597 In this case, the variable @code{HELLO_SYSTEM} should be replaced by
4598 either @file{hello-linux.o} or @file{hello-generic.o}, and added to
4599 both @code{hello_DEPENDENCIES} and @code{hello_LDADD} in order to be
4600 built and linked in.
4602 @subsubsection Conditional compilation using Automake conditionals
4604 An often simpler way to compile source files conditionally is to use
4605 Automake conditionals. For instance, you could use this
4606 @file{Makefile.am} construct to build the same @file{hello} example:
4609 bin_PROGRAMS = hello
4611 hello_SOURCES = hello-linux.c hello-common.c
4613 hello_SOURCES = hello-generic.c hello-common.c
4617 In this case, @file{configure.ac} should setup the @code{LINUX}
4618 conditional using @code{AM_CONDITIONAL} (@pxref{Conditionals}).
4620 When using conditionals like this you don't need to use the
4621 @code{EXTRA_} variable, because Automake will examine the contents of
4622 each variable to construct the complete list of source files.
4624 If your program uses a lot of files, you will probably prefer a
4625 conditional @samp{+=}.
4628 bin_PROGRAMS = hello
4629 hello_SOURCES = hello-common.c
4631 hello_SOURCES += hello-linux.c
4633 hello_SOURCES += hello-generic.c
4637 @node Conditional Programs
4638 @subsection Conditional compilation of programs
4639 @cindex Conditional programs
4640 @cindex Programs, conditional
4642 Sometimes it is useful to determine the programs that are to be built
4643 at configure time. For instance, GNU @code{cpio} only builds
4644 @code{mt} and @code{rmt} under special circumstances. The means to
4645 achieve conditional compilation of programs are the same you can use
4646 to compile source files conditionally: substitutions or conditionals.
4648 @subsubsection Conditional programs using @command{configure} substitutions
4650 @vindex EXTRA_PROGRAMS
4651 @cindex @code{EXTRA_PROGRAMS}, defined
4652 In this case, you must notify Automake of all the programs that can
4653 possibly be built, but at the same time cause the generated
4654 @file{Makefile.in} to use the programs specified by @command{configure}.
4655 This is done by having @command{configure} substitute values into each
4656 @code{_PROGRAMS} definition, while listing all optionally built programs
4657 in @code{EXTRA_PROGRAMS}.
4660 bin_PROGRAMS = cpio pax $(MT)
4661 libexec_PROGRAMS = $(RMT)
4662 EXTRA_PROGRAMS = mt rmt
4665 As explained in @ref{EXEEXT}, Automake will rewrite
4666 @code{bin_PROGRAMS}, @code{libexec_PROGRAMS}, and
4667 @code{EXTRA_PROGRAMS}, appending @samp{$(EXEEXT)} to each binary.
4668 Obviously it cannot rewrite values obtained at run-time through
4669 @command{configure} substitutions, therefore you should take care of
4670 appending @samp{$(EXEEXT)} yourself, as in @samp{AC_SUBST([MT],
4671 ['mt$@{EXEEXT@}'])}.
4673 @subsubsection Conditional programs using Automake conditionals
4675 You can also use Automake conditionals (@pxref{Conditionals}) to
4676 select programs to be built. In this case you don't have to worry
4677 about @samp{$(EXEEXT)} or @code{EXTRA_PROGRAMS}.
4680 bin_PROGRAMS = cpio pax
4685 libexec_PROGRAMS = rmt
4691 @section Building a library
4693 @cindex @code{_LIBRARIES} primary, defined
4694 @cindex @code{LIBRARIES} primary, defined
4695 @cindex Primary variable, @code{LIBRARIES}
4698 @vindex lib_LIBRARIES
4699 @vindex pkglib_LIBRARIES
4700 @vindex noinst_LIBRARIES
4702 Building a library is much like building a program. In this case, the
4703 name of the primary is @code{LIBRARIES}. Libraries can be installed in
4704 @code{libdir} or @code{pkglibdir}.
4706 @xref{A Shared Library}, for information on how to build shared
4707 libraries using libtool and the @code{LTLIBRARIES} primary.
4709 Each @code{_LIBRARIES} variable is a list of the libraries to be built.
4710 For instance, to create a library named @file{libcpio.a}, but not install
4711 it, you would write:
4714 noinst_LIBRARIES = libcpio.a
4715 libcpio_a_SOURCES = @dots{}
4718 The sources that go into a library are determined exactly as they are
4719 for programs, via the @code{_SOURCES} variables. Note that the library
4720 name is canonicalized (@pxref{Canonicalization}), so the @code{_SOURCES}
4721 variable corresponding to @file{libcpio.a} is @samp{libcpio_a_SOURCES},
4722 not @samp{libcpio.a_SOURCES}.
4724 @vindex maude_LIBADD
4725 Extra objects can be added to a library using the
4726 @code{@var{library}_LIBADD} variable. This should be used for objects
4727 determined by @command{configure}. Again from @code{cpio}:
4730 libcpio_a_LIBADD = $(LIBOBJS) $(ALLOCA)
4733 In addition, sources for extra objects that will not exist until
4734 configure-time must be added to the @code{BUILT_SOURCES} variable
4737 Building a static library is done by compiling all object files, then
4738 by invoking @samp{$(AR) $(ARFLAGS)} followed by the name of the
4739 library and the list of objects, and finally by calling
4740 @samp{$(RANLIB)} on that library. You should call
4741 @code{AC_PROG_RANLIB} from your @file{configure.ac} to define
4742 @code{RANLIB} (Automake will complain otherwise). @code{AR} and
4743 @code{ARFLAGS} default to @code{ar} and @code{cru} respectively; you
4744 can override these two variables my setting them in your
4745 @file{Makefile.am}, by @code{AC_SUBST}ing them from your
4746 @file{configure.ac}, or by defining a per-library @code{maude_AR}
4747 variable (@pxref{Program and Library Variables}).
4749 @cindex Empty libraries
4750 Be careful when selecting library components conditionally. Because
4751 building an empty library is not portable, you should ensure that any
4752 library contains always at least one object.
4754 To use a static library when building a program, add it to
4755 @code{LDADD} for this program. In the following example, the program
4756 @file{cpio} is statically linked with the library @file{libcpio.a}.
4759 noinst_LIBRARIES = libcpio.a
4760 libcpio_a_SOURCES = @dots{}
4763 cpio_SOURCES = cpio.c @dots{}
4764 cpio_LDADD = libcpio.a
4768 @node A Shared Library
4769 @section Building a Shared Library
4771 @cindex Shared libraries, support for
4773 Building shared libraries portably is a relatively complex matter.
4774 For this reason, GNU Libtool (@pxref{Top, , Introduction, libtool, The
4775 Libtool Manual}) was created to help build shared libraries in a
4776 platform-independent way.
4779 * Libtool Concept:: Introducing Libtool
4780 * Libtool Libraries:: Declaring Libtool Libraries
4781 * Conditional Libtool Libraries:: Building Libtool Libraries Conditionally
4782 * Conditional Libtool Sources:: Choosing Library Sources Conditionally
4783 * Libtool Convenience Libraries:: Building Convenience Libtool Libraries
4784 * Libtool Modules:: Building Libtool Modules
4785 * Libtool Flags:: Using _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS
4786 * LTLIBOBJS:: Using $(LTLIBOBJS) and $(LTALLOCA)
4787 * Libtool Issues:: Common Issues Related to Libtool's Use
4790 @node Libtool Concept
4791 @subsection The Libtool Concept
4793 @cindex @command{libtool}, introduction
4794 @cindex libtool library, definition
4795 @cindex suffix @file{.la}, defined
4796 @cindex @file{.la} suffix, defined
4798 Libtool abstracts shared and static libraries into a unified concept
4799 henceforth called @dfn{libtool libraries}. Libtool libraries are
4800 files using the @file{.la} suffix, and can designate a static library,
4801 a shared library, or maybe both. Their exact nature cannot be
4802 determined until @file{./configure} is run: not all platforms support
4803 all kinds of libraries, and users can explicitly select which
4804 libraries should be built. (However the package's maintainers can
4805 tune the default, @pxref{AC_PROG_LIBTOOL, , The @code{AC_PROG_LIBTOOL}
4806 macro, libtool, The Libtool Manual}.)
4808 @cindex suffix @file{.lo}, defined
4809 Because object files for shared and static libraries must be compiled
4810 differently, libtool is also used during compilation. Object files
4811 built by libtool are called @dfn{libtool objects}: these are files
4812 using the @file{.lo} suffix. Libtool libraries are built from these
4815 You should not assume anything about the structure of @file{.la} or
4816 @file{.lo} files and how libtool constructs them: this is libtool's
4817 concern, and the last thing one wants is to learn about libtool's
4818 guts. However the existence of these files matters, because they are
4819 used as targets and dependencies in @file{Makefile}s rules when
4820 building libtool libraries. There are situations where you may have
4821 to refer to these, for instance when expressing dependencies for
4822 building source files conditionally (@pxref{Conditional Libtool
4825 @cindex @file{libltdl}, introduction
4827 People considering writing a plug-in system, with dynamically loaded
4828 modules, should look into @file{libltdl}: libtool's dlopening library
4829 (@pxref{Using libltdl, , Using libltdl, libtool, The Libtool Manual}).
4830 This offers a portable dlopening facility to load libtool libraries
4831 dynamically, and can also achieve static linking where unavoidable.
4833 Before we discuss how to use libtool with Automake in details, it
4834 should be noted that the libtool manual also has a section about how
4835 to use Automake with libtool (@pxref{Using Automake, , Using Automake
4836 with Libtool, libtool, The Libtool Manual}).
4838 @node Libtool Libraries
4839 @subsection Building Libtool Libraries
4841 @cindex @code{_LTLIBRARIES} primary, defined
4842 @cindex @code{LTLIBRARIES} primary, defined
4843 @cindex Primary variable, @code{LTLIBRARIES}
4844 @cindex Example of shared libraries
4845 @vindex lib_LTLIBRARIES
4846 @vindex pkglib_LTLIBRARIES
4847 @vindex _LTLIBRARIES
4849 Automake uses libtool to build libraries declared with the
4850 @code{LTLIBRARIES} primary. Each @code{_LTLIBRARIES} variable is a
4851 list of libtool libraries to build. For instance, to create a libtool
4852 library named @file{libgettext.la}, and install it in @code{libdir},
4856 lib_LTLIBRARIES = libgettext.la
4857 libgettext_la_SOURCES = gettext.c gettext.h @dots{}
4860 Automake predefines the variable @code{pkglibdir}, so you can use
4861 @code{pkglib_LTLIBRARIES} to install libraries in
4862 @samp{$(libdir)/@@PACKAGE@@/}.
4864 If @file{gettext.h} is a public header file that needs to be installed
4865 in order for people to use the library, it should be declared using a
4866 @code{_HEADERS} variable, not in @code{libgettext_la_SOURCES}.
4867 Headers listed in the latter should be internal headers that are not
4868 part of the public interface.
4871 lib_LTLIBRARIES = libgettext.la
4872 libgettext_la_SOURCES = gettext.c @dots{}
4873 include_HEADERS = gettext.h @dots{}
4876 A package can build and install such a library along with other
4877 programs that use it. This dependency should be specified using
4878 @code{LDADD}. The following example builds a program named
4879 @file{hello} that is linked with @file{libgettext.la}.
4882 lib_LTLIBRARIES = libgettext.la
4883 libgettext_la_SOURCES = gettext.c @dots{}
4885 bin_PROGRAMS = hello
4886 hello_SOURCES = hello.c @dots{}
4887 hello_LDADD = libgettext.la
4891 Whether @file{hello} is statically or dynamically linked with
4892 @file{libgettext.la} is not yet known: this will depend on the
4893 configuration of libtool and the capabilities of the host.
4896 @node Conditional Libtool Libraries
4897 @subsection Building Libtool Libraries Conditionally
4898 @cindex libtool libraries, conditional
4899 @cindex conditional libtool libraries
4901 Like conditional programs (@pxref{Conditional Programs}), there are
4902 two main ways to build conditional libraries: using Automake
4903 conditionals or using Autoconf @code{AC_SUBST}itutions.
4905 The important implementation detail you have to be aware of is that
4906 the place where a library will be installed matters to libtool: it
4907 needs to be indicated @emph{at link-time} using the @option{-rpath}
4910 For libraries whose destination directory is known when Automake runs,
4911 Automake will automatically supply the appropriate @option{-rpath}
4912 option to libtool. This is the case for libraries listed explicitly in
4913 some installable @code{_LTLIBRARIES} variables such as
4914 @code{lib_LTLIBRARIES}.
4916 However, for libraries determined at configure time (and thus
4917 mentioned in @code{EXTRA_LTLIBRARIES}), Automake does not know the
4918 final installation directory. For such libraries you must add the
4919 @option{-rpath} option to the appropriate @code{_LDFLAGS} variable by
4922 The examples below illustrate the differences between these two methods.
4924 Here is an example where @code{WANTEDLIBS} is an @code{AC_SUBST}ed
4925 variable set at @file{./configure}-time to either @file{libfoo.la},
4926 @file{libbar.la}, both, or none. Although @samp{$(WANTEDLIBS)}
4927 appears in the @code{lib_LTLIBRARIES}, Automake cannot guess it
4928 relates to @file{libfoo.la} or @file{libbar.la} by the time it creates
4929 the link rule for these two libraries. Therefore the @option{-rpath}
4930 argument must be explicitly supplied.
4933 EXTRA_LTLIBRARIES = libfoo.la libbar.la
4934 lib_LTLIBRARIES = $(WANTEDLIBS)
4935 libfoo_la_SOURCES = foo.c @dots{}
4936 libfoo_la_LDFLAGS = -rpath '$(libdir)'
4937 libbar_la_SOURCES = bar.c @dots{}
4938 libbar_la_LDFLAGS = -rpath '$(libdir)'
4941 Here is how the same @file{Makefile.am} would look using Automake
4942 conditionals named @code{WANT_LIBFOO} and @code{WANT_LIBBAR}. Now
4943 Automake is able to compute the @option{-rpath} setting itself, because
4944 it's clear that both libraries will end up in @samp{$(libdir)} if they
4950 lib_LTLIBRARIES += libfoo.la
4953 lib_LTLIBRARIES += libbar.la
4955 libfoo_la_SOURCES = foo.c @dots{}
4956 libbar_la_SOURCES = bar.c @dots{}
4959 @node Conditional Libtool Sources
4960 @subsection Libtool Libraries with Conditional Sources
4962 Conditional compilation of sources in a library can be achieved in the
4963 same way as conditional compilation of sources in a program
4964 (@pxref{Conditional Sources}). The only difference is that
4965 @code{_LIBADD} should be used instead of @code{_LDADD} and that it
4966 should mention libtool objects (@file{.lo} files).
4968 So, to mimic the @file{hello} example from @ref{Conditional Sources},
4969 we could build a @file{libhello.la} library using either
4970 @file{hello-linux.c} or @file{hello-generic.c} with the following
4974 lib_LTLIBRARIES = libhello.la
4975 libhello_la_SOURCES = hello-common.c
4976 EXTRA_libhello_la_SOURCES = hello-linux.c hello-generic.c
4977 libhello_la_LIBADD = $(HELLO_SYSTEM)
4978 libhello_la_DEPENDENCIES = $(HELLO_SYSTEM)
4982 And make sure @command{configure} defines @code{HELLO_SYSTEM} as
4983 either @file{hello-linux.lo} or @file{hello-@-generic.lo}.
4985 Or we could simply use an Automake conditional as follows.
4988 lib_LTLIBRARIES = libhello.la
4989 libhello_la_SOURCES = hello-common.c
4991 libhello_la_SOURCES += hello-linux.c
4993 libhello_la_SOURCES += hello-generic.c
4997 @node Libtool Convenience Libraries
4998 @subsection Libtool Convenience Libraries
4999 @cindex convenience libraries, libtool
5000 @cindex libtool convenience libraries
5001 @vindex noinst_LTLIBRARIES
5002 @vindex check_LTLIBRARIES
5004 Sometimes you want to build libtool libraries that should not be
5005 installed. These are called @dfn{libtool convenience libraries} and
5006 are typically used to encapsulate many sublibraries, later gathered
5007 into one big installed library.
5009 Libtool convenience libraries are declared by directory-less variables
5010 such as @code{noinst_LTLIBRARIES}, @code{check_LTLIBRARIES}, or even
5011 @code{EXTRA_LTLIBRARIES}. Unlike installed libtool libraries they do
5012 not need an @option{-rpath} flag at link time (actually this is the only
5015 Convenience libraries listed in @code{noinst_LTLIBRARIES} are always
5016 built. Those listed in @code{check_LTLIBRARIES} are built only upon
5017 @samp{make check}. Finally, libraries listed in
5018 @code{EXTRA_LTLIBRARIES} are never built explicitly: Automake outputs
5019 rules to build them, but if the library does not appear as a Makefile
5020 dependency anywhere it won't be built (this is why
5021 @code{EXTRA_LTLIBRARIES} is used for conditional compilation).
5023 Here is a sample setup merging libtool convenience libraries from
5024 subdirectories into one main @file{libtop.la} library.
5027 # -- Top-level Makefile.am --
5028 SUBDIRS = sub1 sub2 @dots{}
5029 lib_LTLIBRARIES = libtop.la
5031 libtop_la_LIBADD = \
5036 # -- sub1/Makefile.am --
5037 noinst_LTLIBRARIES = libsub1.la
5038 libsub1_la_SOURCES = @dots{}
5040 # -- sub2/Makefile.am --
5041 # showing nested convenience libraries
5042 SUBDIRS = sub2.1 sub2.2 @dots{}
5043 noinst_LTLIBRARIES = libsub2.la
5044 libsub2_la_SOURCES =
5045 libsub2_la_LIBADD = \
5051 When using such setup, beware that @command{automake} will assume
5052 @file{libtop.la} is to be linked with the C linker. This is because
5053 @code{libtop_la_SOURCES} is empty, so @command{automake} picks C as
5054 default language. If @code{libtop_la_SOURCES} was not empty,
5055 @command{automake} would select the linker as explained in @ref{How
5056 the Linker is Chosen}.
5058 If one of the sublibraries contains non-C source, it is important that
5059 the appropriate linker be chosen. One way to achieve this is to
5060 pretend that there is such a non-C file among the sources of the
5061 library, thus forcing @command{automake} to select the appropriate
5062 linker. Here is the top-level @file{Makefile} of our example updated
5063 to force C++ linking.
5066 SUBDIRS = sub1 sub2 @dots{}
5067 lib_LTLIBRARIES = libtop.la
5069 # Dummy C++ source to cause C++ linking.
5070 nodist_EXTRA_libtop_la_SOURCES = dummy.cxx
5071 libtop_la_LIBADD = \
5077 @samp{EXTRA_*_SOURCES} variables are used to keep track of source
5078 files that might be compiled (this is mostly useful when doing
5079 conditional compilation using @code{AC_SUBST}, @pxref{Conditional
5080 Libtool Sources}), and the @code{nodist_} prefix means the listed
5081 sources are not to be distributed (@pxref{Program and Library
5082 Variables}). In effect the file @file{dummy.cxx} does not need to
5083 exist in the source tree. Of course if you have some real source file
5084 to list in @code{libtop_la_SOURCES} there is no point in cheating with
5085 @code{nodist_EXTRA_libtop_la_SOURCES}.
5088 @node Libtool Modules
5089 @subsection Libtool Modules
5090 @cindex modules, libtool
5091 @cindex libtool modules
5092 @cindex @option{-module}, libtool
5094 These are libtool libraries meant to be dlopened. They are
5095 indicated to libtool by passing @option{-module} at link-time.
5098 pkglib_LTLIBRARIES = mymodule.la
5099 mymodule_la_SOURCES = doit.c
5100 mymodule_la_LDFLAGS = -module
5103 Ordinarily, Automake requires that a library's name starts with
5104 @code{lib}. However, when building a dynamically loadable module you
5105 might wish to use a "nonstandard" name. Automake will not complain
5106 about such nonstandard name if it knows the library being built is a
5107 libtool module, i.e., if @option{-module} explicitly appears in the
5108 library's @code{_LDFLAGS} variable (or in the common @code{AM_LDFLAGS}
5109 variable when no per-library @code{_LDFLAGS} variable is defined).
5111 As always, @code{AC_SUBST} variables are black boxes to Automake since
5112 their values are not yet known when @command{automake} is run.
5113 Therefore if @option{-module} is set via such a variable, Automake
5114 cannot notice it and will proceed as if the library was an ordinary
5115 libtool library, with strict naming.
5117 If @code{mymodule_la_SOURCES} is not specified, then it defaults to
5118 the single file @file{mymodule.c} (@pxref{Default _SOURCES}).
5121 @subsection @code{_LIBADD}, @code{_LDFLAGS}, and @code{_LIBTOOLFLAGS}
5122 @cindex @code{_LIBADD}, libtool
5123 @cindex @code{_LDFLAGS}, libtool
5124 @cindex @code{_LIBTOOLFLAGS}, libtool
5125 @vindex AM_LIBTOOLFLAGS
5126 @vindex LIBTOOLFLAGS
5127 @vindex maude_LIBTOOLFLAGS
5129 As shown in previous sections, the @samp{@var{library}_LIBADD}
5130 variable should be used to list extra libtool objects (@file{.lo}
5131 files) or libtool libraries (@file{.la}) to add to @var{library}.
5133 The @samp{@var{library}_LDFLAGS} variable is the place to list
5134 additional libtool linking flags, such as @option{-version-info},
5135 @option{-static}, and a lot more. @xref{Link mode, , Link mode,
5136 libtool, The Libtool Manual}.
5138 The @command{libtool} command has two kinds of options: mode-specific
5139 options and generic options. Mode-specific options such as the
5140 aforementioned linking flags should be lumped with the other flags
5141 passed to the tool invoked by @command{libtool} (hence the use of
5142 @samp{@var{library}_LDFLAGS} for libtool linking flags). Generic
5143 options include @option{--tag=@var{TAG}} and @option{--silent}
5144 (@pxref{Invoking libtool, , Invoking @command{libtool}, libtool, The
5145 Libtool Manual} for more options) should appear before the mode
5146 selection on the command line; in @file{Makefile.am}s they should
5147 be listed in the @samp{@var{library}_LIBTOOLFLAGS} variable.
5149 If @samp{@var{library}_LIBTOOLFLAGS} is not defined, the global
5150 @code{AM_LIBTOOLFLAGS} variable is used instead.
5152 These flags are passed to libtool after the @option{--tag=@var{TAG}}
5153 option computed by Automake (if any), so
5154 @samp{@var{library}_LIBTOOLFLAGS} (or @code{AM_LIBTOOLFLAGS}) is the
5155 good place to override or supplement the @option{--tag=@var{TAG}}
5158 The libtool rules also use a @code{LIBTOOLFLAGS} variable that should
5159 not be set in @file{Makefile.am}: this is a user variable (@pxref{Flag
5160 Variables Ordering}. It allows users to run @samp{make
5161 LIBTOOLFLAGS=--silent}, for instance.
5164 @node LTLIBOBJS, Libtool Issues, Libtool Flags, A Shared Library
5165 @subsection @code{LTLIBOBJS} and @code{LTALLOCA}
5166 @cindex @code{LTLIBOBJS}, special handling
5167 @cindex @code{LIBOBJS}, and Libtool
5168 @cindex @code{LTALLOCA}, special handling
5169 @cindex @code{ALLOCA}, and Libtool
5176 Where an ordinary library might include @samp{$(LIBOBJS)} or
5177 @samp{$(ALLOCA)} (@pxref{LIBOBJS}), a libtool library must use
5178 @samp{$(LTLIBOBJS)} or @samp{$(LTALLOCA)}. This is required because
5179 the object files that libtool operates on do not necessarily end in
5182 Nowadays, the computation of @code{LTLIBOBJS} from @code{LIBOBJS} is
5183 performed automatically by Autoconf (@pxref{AC_LIBOBJ vs LIBOBJS, ,
5184 @code{AC_LIBOBJ} vs.@: @code{LIBOBJS}, autoconf, The Autoconf Manual}).
5186 @node Libtool Issues
5187 @subsection Common Issues Related to Libtool's Use
5189 @subsubsection @samp{required file `./ltmain.sh' not found}
5190 @cindex @file{ltmain.sh} not found
5191 @cindex @command{libtoolize}, no longer run by @command{automake}
5192 @cindex @command{libtoolize} and @command{autoreconf}
5193 @cindex @command{autoreconf} and @command{libtoolize}
5194 @cindex @file{bootstrap.sh} and @command{autoreconf}
5195 @cindex @file{autogen.sh} and @command{autoreconf}
5197 Libtool comes with a tool called @command{libtoolize} that will
5198 install libtool's supporting files into a package. Running this
5199 command will install @file{ltmain.sh}. You should execute it before
5200 @command{aclocal} and @command{automake}.
5202 People upgrading old packages to newer autotools are likely to face
5203 this issue because older Automake versions used to call
5204 @command{libtoolize}. Therefore old build scripts do not call
5205 @command{libtoolize}.
5207 Since Automake 1.6, it has been decided that running
5208 @command{libtoolize} was none of Automake's business. Instead, that
5209 functionality has been moved into the @command{autoreconf} command
5210 (@pxref{autoreconf Invocation, , Using @command{autoreconf}, autoconf,
5211 The Autoconf Manual}). If you do not want to remember what to run and
5212 when, just learn the @command{autoreconf} command. Hopefully,
5213 replacing existing @file{bootstrap.sh} or @file{autogen.sh} scripts by
5214 a call to @command{autoreconf} should also free you from any similar
5215 incompatible change in the future.
5217 @subsubsection Objects @samp{created with both libtool and without}
5219 Sometimes, the same source file is used both to build a libtool
5220 library and to build another non-libtool target (be it a program or
5223 Let's consider the following @file{Makefile.am}.
5227 prog_SOURCES = prog.c foo.c @dots{}
5229 lib_LTLIBRARIES = libfoo.la
5230 libfoo_la_SOURCES = foo.c @dots{}
5234 (In this trivial case the issue could be avoided by linking
5235 @file{libfoo.la} with @file{prog} instead of listing @file{foo.c} in
5236 @code{prog_SOURCES}. But let's assume we really want to keep
5237 @file{prog} and @file{libfoo.la} separate.)
5239 Technically, it means that we should build @file{foo.$(OBJEXT)} for
5240 @file{prog}, and @file{foo.lo} for @file{libfoo.la}. The problem is
5241 that in the course of creating @file{foo.lo}, libtool may erase (or
5242 replace) @file{foo.$(OBJEXT)}, and this cannot be avoided.
5244 Therefore, when Automake detects this situation it will complain
5245 with a message such as
5247 object `foo.$(OBJEXT)' created both with libtool and without
5250 A workaround for this issue is to ensure that these two objects get
5251 different basenames. As explained in @ref{renamed objects}, this
5252 happens automatically when per-targets flags are used.
5256 prog_SOURCES = prog.c foo.c @dots{}
5257 prog_CFLAGS = $(AM_CFLAGS)
5259 lib_LTLIBRARIES = libfoo.la
5260 libfoo_la_SOURCES = foo.c @dots{}
5264 Adding @samp{prog_CFLAGS = $(AM_CFLAGS)} is almost a no-op, because
5265 when the @code{prog_CFLAGS} is defined, it is used instead of
5266 @code{AM_CFLAGS}. However as a side effect it will cause
5267 @file{prog.c} and @file{foo.c} to be compiled as
5268 @file{prog-prog.$(OBJEXT)} and @file{prog-foo.$(OBJEXT)}, which solves
5271 @node Program and Library Variables
5272 @section Program and Library Variables
5274 Associated with each program are a collection of variables that can be
5275 used to modify how that program is built. There is a similar list of
5276 such variables for each library. The canonical name of the program (or
5277 library) is used as a base for naming these variables.
5279 In the list below, we use the name ``maude'' to refer to the program or
5280 library. In your @file{Makefile.am} you would replace this with the
5281 canonical name of your program. This list also refers to ``maude'' as a
5282 program, but in general the same rules apply for both static and dynamic
5283 libraries; the documentation below notes situations where programs and
5288 This variable, if it exists, lists all the source files that are
5289 compiled to build the program. These files are added to the
5290 distribution by default. When building the program, Automake will cause
5291 each source file to be compiled to a single @file{.o} file (or
5292 @file{.lo} when using libtool). Normally these object files are named
5293 after the source file, but other factors can change this. If a file in
5294 the @code{_SOURCES} variable has an unrecognized extension, Automake
5295 will do one of two things with it. If a suffix rule exists for turning
5296 files with the unrecognized extension into @file{.o} files, then
5297 automake will treat this file as it will any other source file
5298 (@pxref{Support for Other Languages}). Otherwise, the file will be
5299 ignored as though it were a header file.
5301 The prefixes @code{dist_} and @code{nodist_} can be used to control
5302 whether files listed in a @code{_SOURCES} variable are distributed.
5303 @code{dist_} is redundant, as sources are distributed by default, but it
5304 can be specified for clarity if desired.
5306 It is possible to have both @code{dist_} and @code{nodist_} variants of
5307 a given @code{_SOURCES} variable at once; this lets you easily
5308 distribute some files and not others, for instance:
5311 nodist_maude_SOURCES = nodist.c
5312 dist_maude_SOURCES = dist-me.c
5315 By default the output file (on Unix systems, the @file{.o} file) will
5316 be put into the current build directory. However, if the option
5317 @option{subdir-objects} is in effect in the current directory then the
5318 @file{.o} file will be put into the subdirectory named after the
5319 source file. For instance, with @option{subdir-objects} enabled,
5320 @file{sub/dir/file.c} will be compiled to @file{sub/dir/file.o}. Some
5321 people prefer this mode of operation. You can specify
5322 @option{subdir-objects} in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
5323 @cindex Subdirectory, objects in
5324 @cindex Objects in subdirectory
5327 @item EXTRA_maude_SOURCES
5328 Automake needs to know the list of files you intend to compile
5329 @emph{statically}. For one thing, this is the only way Automake has of
5330 knowing what sort of language support a given @file{Makefile.in}
5331 requires. @footnote{There are other, more obscure reasons for
5332 this limitation as well.} This means that, for example, you can't put a
5333 configure substitution like @samp{@@my_sources@@} into a @samp{_SOURCES}
5334 variable. If you intend to conditionally compile source files and use
5335 @file{configure} to substitute the appropriate object names into, e.g.,
5336 @code{_LDADD} (see below), then you should list the corresponding source
5337 files in the @code{EXTRA_} variable.
5339 This variable also supports @code{dist_} and @code{nodist_} prefixes.
5340 For instance, @code{nodist_EXTRA_maude_SOURCES} would list extra
5341 sources that may need to be built, but should not be distributed.
5344 A static library is created by default by invoking @samp{$(AR)
5345 $(ARFLAGS)} followed by the name of the library and then the objects
5346 being put into the library. You can override this by setting the
5347 @code{_AR} variable. This is usually used with C++; some C++
5348 compilers require a special invocation in order to instantiate all the
5349 templates that should go into a library. For instance, the SGI C++
5350 compiler likes this variable set like so:
5352 libmaude_a_AR = $(CXX) -ar -o
5356 Extra objects can be added to a @emph{library} using the @code{_LIBADD}
5357 variable. For instance, this should be used for objects determined by
5358 @command{configure} (@pxref{A Library}).
5360 In the case of libtool libraries, @code{maude_LIBADD} can also refer
5361 to other libtool libraries.
5364 Extra objects (@file{*.$(OBJEXT)}) and libraries (@file{*.a},
5365 @file{*.la}) can be added to a @emph{program} by listing them in the
5366 @code{_LDADD} variable. For instance, this should be used for objects
5367 determined by @command{configure} (@pxref{Linking}).
5369 @code{_LDADD} and @code{_LIBADD} are inappropriate for passing
5370 program-specific linker flags (except for @option{-l}, @option{-L},
5371 @option{-dlopen} and @option{-dlpreopen}). Use the @code{_LDFLAGS} variable
5374 For instance, if your @file{configure.ac} uses @code{AC_PATH_XTRA}, you
5375 could link your program against the X libraries like so:
5378 maude_LDADD = $(X_PRE_LIBS) $(X_LIBS) $(X_EXTRA_LIBS)
5381 We recommend that you use @option{-l} and @option{-L} only when
5382 referring to third-party libraries, and give the explicit file names
5383 of any library built by your package. Doing so will ensure that
5384 @code{maude_DEPENDENCIES} (see below) is correctly defined by default.
5387 This variable is used to pass extra flags to the link step of a program
5388 or a shared library. It overrides the global @code{AM_LDFLAGS} variable.
5390 @item maude_LIBTOOLFLAGS
5391 This variable is used to pass extra options to @command{libtool}.
5392 It overrides the global @code{AM_LIBTOOLFLAGS} variable.
5393 These options are output before @command{libtool}'s @option{--mode=@var{MODE}}
5394 option, so they should not be mode-specific options (those belong to
5395 the compiler or linker flags). @xref{Libtool Flags}.
5397 @item maude_DEPENDENCIES
5398 It is also occasionally useful to have a target (program or library)
5399 depend on some other file that is not actually part of that target.
5400 This can be done using the @code{_DEPENDENCIES} variable. Each
5401 targets depends on the contents of such a variable, but no further
5402 interpretation is done.
5404 Since these dependencies are associated to the link rule used to
5405 create the programs they should normally list files used by the link
5406 command. That is @file{*.$(OBJEXT)}, @file{*.a}, or @file{*.la} files
5407 for programs; @file{*.lo} and @file{*.la} files for Libtool libraries;
5408 and @file{*.$(OBJEXT)} files for static libraries. In rare cases you
5409 may need to add other kinds of files such as linker scripts, but
5410 @emph{listing a source file in @code{_DEPENDENCIES} is wrong}. If
5411 some source file needs to be built before all the components of a
5412 program are built, consider using the @code{BUILT_SOURCES} variable
5415 If @code{_DEPENDENCIES} is not supplied, it is computed by Automake.
5416 The automatically-assigned value is the contents of @code{_LDADD} or
5417 @code{_LIBADD}, with most configure substitutions, @option{-l}, @option{-L},
5418 @option{-dlopen} and @option{-dlpreopen} options removed. The configure
5419 substitutions that are left in are only @samp{$(LIBOBJS)} and
5420 @samp{$(ALLOCA)}; these are left because it is known that they will not
5421 cause an invalid value for @code{_DEPENDENCIES} to be generated.
5423 @code{_DEPENDENCIES} is more likely used to perform conditional
5424 compilation using an @code{AC_SUBST} variable that contains a list of
5425 objects. @xref{Conditional Sources}, and @ref{Conditional Libtool
5429 You can override the linker on a per-program basis. By default the
5430 linker is chosen according to the languages used by the program. For
5431 instance, a program that includes C++ source code would use the C++
5432 compiler to link. The @code{_LINK} variable must hold the name of a
5433 command that can be passed all the @file{.o} file names as arguments.
5434 Note that the name of the underlying program is @emph{not} passed to
5435 @code{_LINK}; typically one uses @samp{$@@}:
5438 maude_LINK = $(CCLD) -magic -o $@@
5441 @item maude_CCASFLAGS
5443 @itemx maude_CPPFLAGS
5444 @itemx maude_CXXFLAGS
5446 @itemx maude_GCJFLAGS
5448 @itemx maude_OBJCFLAGS
5450 @itemx maude_UPCFLAGS
5452 @cindex per-target compilation flags, defined
5453 Automake allows you to set compilation flags on a per-program (or
5454 per-library) basis. A single source file can be included in several
5455 programs, and it will potentially be compiled with different flags for
5456 each program. This works for any language directly supported by
5457 Automake. These @dfn{per-target compilation flags} are
5467 @samp{_UPCFLAGS}, and
5470 When using a per-target compilation flag, Automake will choose a
5471 different name for the intermediate object files. Ordinarily a file
5472 like @file{sample.c} will be compiled to produce @file{sample.o}.
5473 However, if the program's @code{_CFLAGS} variable is set, then the
5474 object file will be named, for instance, @file{maude-sample.o}. (See
5475 also @ref{renamed objects}.) The use of per-target compilation flags
5476 with C sources requires that the macro @code{AM_PROG_CC_C_O} be called
5477 from @file{configure.ac}.
5479 In compilations with per-target flags, the ordinary @samp{AM_} form of
5480 the flags variable is @emph{not} automatically included in the
5481 compilation (however, the user form of the variable @emph{is} included).
5482 So for instance, if you want the hypothetical @file{maude} compilations
5483 to also use the value of @code{AM_CFLAGS}, you would need to write:
5486 maude_CFLAGS = @dots{} your flags @dots{} $(AM_CFLAGS)
5489 @xref{Flag Variables Ordering}, for more discussion about the
5490 interaction between user variables, @samp{AM_} shadow variables, and
5491 per-target variables.
5493 @item maude_SHORTNAME
5494 On some platforms the allowable file names are very short. In order to
5495 support these systems and per-target compilation flags at the same
5496 time, Automake allows you to set a ``short name'' that will influence
5497 how intermediate object files are named. For instance, in the following
5501 bin_PROGRAMS = maude
5502 maude_CPPFLAGS = -DSOMEFLAG
5504 maude_SOURCES = sample.c @dots{}
5508 the object file would be named @file{m-sample.o} rather than
5509 @file{maude-sample.o}.
5511 This facility is rarely needed in practice,
5512 and we recommend avoiding it until you find it is required.
5515 @node Default _SOURCES
5516 @section Default @code{_SOURCES}
5520 @cindex @code{_SOURCES}, default
5521 @cindex default @code{_SOURCES}
5523 @code{_SOURCES} variables are used to specify source files of programs
5524 (@pxref{A Program}), libraries (@pxref{A Library}), and Libtool
5525 libraries (@pxref{A Shared Library}).
5527 When no such variable is specified for a target, Automake will define
5528 one itself. The default is to compile a single C file whose base name
5529 is the name of the target itself, with any extension replaced by
5530 @file{.c}. (Defaulting to C is terrible but we are stuck with it for
5531 historical reasons.)
5533 For example if you have the following somewhere in your
5534 @file{Makefile.am} with no corresponding @code{libfoo_a_SOURCES}:
5537 lib_LIBRARIES = libfoo.a sub/libc++.a
5541 @file{libfoo.a} will be built using a default source file named
5542 @file{libfoo.c}, and @file{sub/libc++.a} will be built from
5543 @file{sub/libc++.c}. (In older versions @file{sub/libc++.a}
5544 would be built from @file{sub_libc___a.c}, i.e., the default source
5545 was the canonized name of the target, with @file{.c} appended.
5546 We believe the new behavior is more sensible, but for backward
5547 compatibility automake will use the old name if a file or a rule
5548 with that name exist.)
5550 @cindex @code{check_PROGRAMS} example
5551 @vindex check_PROGRAMS
5552 Default sources are mainly useful in test suites, when building many
5553 tests programs each from a single source. For instance, in
5556 check_PROGRAMS = test1 test2 test3
5560 @file{test1}, @file{test2}, and @file{test3} will be built
5561 from @file{test1.c}, @file{test2.c}, and @file{test3.c}.
5563 @cindex Libtool modules, default source example
5564 @cindex default source, Libtool modules example
5565 Another case where is this convenient is building many Libtool modules
5566 (@file{moduleN.la}), each defined in its own file (@file{moduleN.c}).
5569 AM_LDFLAGS = -module
5570 lib_LTLIBRARIES = module1.la module2.la module3.la
5573 @cindex empty @code{_SOURCES}
5574 @cindex @code{_SOURCES}, empty
5575 Finally, there is one situation where this default source computation
5576 needs to be avoided: when a target should not be built from sources.
5577 We already saw such an example in @ref{true}; this happens when all
5578 the constituents of a target have already been compiled and need just
5579 to be combined using a @code{_LDADD} variable. Then it is necessary
5580 to define an empty @code{_SOURCES} variable, so that automake does not
5584 bin_PROGRAMS = target
5586 target_LDADD = libmain.a libmisc.a
5590 @section Special handling for @code{LIBOBJS} and @code{ALLOCA}
5592 @cindex @code{LIBOBJS}, example
5593 @cindex @code{ALLOCA}, example
5594 @cindex @code{LIBOBJS}, special handling
5595 @cindex @code{ALLOCA}, special handling
5601 The @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} variables list object
5602 files that should be compiled into the project to provide an
5603 implementation for functions that are missing or broken on the host
5604 system. They are substituted by @file{configure}.
5608 These variables are defined by Autoconf macros such as
5609 @code{AC_LIBOBJ}, @code{AC_REPLACE_FUNCS} (@pxref{Generic Functions, ,
5610 Generic Function Checks, autoconf, The Autoconf Manual}), or
5611 @code{AC_FUNC_ALLOCA} (@pxref{Particular Functions, , Particular
5612 Function Checks, autoconf, The Autoconf Manual}). Many other Autoconf
5613 macros call @code{AC_LIBOBJ} or @code{AC_REPLACE_FUNCS} to
5614 populate @samp{$(LIBOBJS)}.
5616 @acindex AC_LIBSOURCE
5618 Using these variables is very similar to doing conditional compilation
5619 using @code{AC_SUBST} variables, as described in @ref{Conditional
5620 Sources}. That is, when building a program, @samp{$(LIBOBJS)} and
5621 @samp{$(ALLOCA)} should be added to the associated @samp{*_LDADD}
5622 variable, or to the @samp{*_LIBADD} variable when building a library.
5623 However there is no need to list the corresponding sources in
5624 @samp{EXTRA_*_SOURCES} nor to define @samp{*_DEPENDENCIES}. Automake
5625 automatically adds @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} to the
5626 dependencies, and it will discover the list of corresponding source
5627 files automatically (by tracing the invocations of the
5628 @code{AC_LIBSOURCE} Autoconf macros).
5630 These variables are usually used to build a portability library that
5631 is linked with all the programs of the project. We now review a
5632 sample setup. First, @file{configure.ac} contains some checks that
5633 affect either @code{LIBOBJS} or @code{ALLOCA}.
5638 AC_CONFIG_LIBOBJ_DIR([lib])
5640 AC_FUNC_MALLOC dnl May add malloc.$(OBJEXT) to LIBOBJS
5641 AC_FUNC_MEMCMP dnl May add memcmp.$(OBJEXT) to LIBOBJS
5642 AC_REPLACE_FUNCS([strdup]) dnl May add strdup.$(OBJEXT) to LIBOBJS
5643 AC_FUNC_ALLOCA dnl May add alloca.$(OBJEXT) to ALLOCA
5652 @acindex AC_CONFIG_LIBOBJ_DIR
5654 The @code{AC_CONFIG_LIBOBJ_DIR} tells Autoconf that the source files
5655 of these object files are to be found in the @file{lib/} directory.
5656 Automake can also use this information, otherwise it expects the
5657 source files are to be in the directory where the @samp{$(LIBOBJS)}
5658 and @samp{$(ALLOCA)} variables are used.
5660 The @file{lib/} directory should therefore contain @file{malloc.c},
5661 @file{memcmp.c}, @file{strdup.c}, @file{alloca.c}. Here is its
5667 noinst_LIBRARIES = libcompat.a
5668 libcompat_a_SOURCES =
5669 libcompat_a_LIBADD = $(LIBOBJS) $(ALLOCA)
5672 The library can have any name, of course, and anyway it is not going
5673 to be installed: it just holds the replacement versions of the missing
5674 or broken functions so we can later link them in. In many projects
5675 also include extra functions, specific to the project, in that
5676 library: they are simply added on the @code{_SOURCES} line.
5678 @cindex Empty libraries and @samp{$(LIBOBJS)}
5679 @cindex @samp{$(LIBOBJS)} and empty libraries
5680 There is a small trap here, though: @samp{$(LIBOBJS)} and
5681 @samp{$(ALLOCA)} might be empty, and building an empty library is not
5682 portable. You should ensure that there is always something to put in
5683 @file{libcompat.a}. Most projects will also add some utility
5684 functions in that directory, and list them in
5685 @code{libcompat_a_SOURCES}, so in practice @file{libcompat.a} cannot
5688 Finally here is how this library could be used from the @file{src/}
5694 # Link all programs in this directory with libcompat.a
5695 LDADD = ../lib/libcompat.a
5697 bin_PROGRAMS = tool1 tool2 @dots{}
5698 tool1_SOURCES = @dots{}
5699 tool2_SOURCES = @dots{}
5702 When option @option{subdir-objects} is not used, as in the above
5703 example, the variables @samp{$(LIBOBJS)} or @samp{$(ALLOCA)} can only
5704 be used in the directory where their sources lie. E.g., here it would
5705 be wrong to use @samp{$(LIBOBJS)} or @samp{$(ALLOCA)} in
5706 @file{src/Makefile.am}. However if both @option{subdir-objects} and
5707 @code{AC_CONFIG_LIBOBJ_DIR} are used, it is OK to use these variables
5708 in other directories. For instance @file{src/Makefile.am} could be
5714 AUTOMAKE_OPTIONS = subdir-objects
5715 LDADD = $(LIBOBJS) $(ALLOCA)
5717 bin_PROGRAMS = tool1 tool2 @dots{}
5718 tool1_SOURCES = @dots{}
5719 tool2_SOURCES = @dots{}
5722 Because @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} contain object
5723 file names that end with @samp{.$(OBJEXT)}, they are not suitable for
5724 Libtool libraries (where the expected object extension is @file{.lo}):
5725 @code{LTLIBOBJS} and @code{LTALLOCA} should be used instead.
5727 @code{LTLIBOBJS} is defined automatically by Autoconf and should not
5728 be defined by hand (as in the past), however at the time of writing
5729 @code{LTALLOCA} still needs to be defined from @code{ALLOCA} manually.
5730 @xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs.@: @code{LIBOBJS},
5731 autoconf, The Autoconf Manual}.
5734 @node Program variables
5735 @section Variables used when building a program
5737 Occasionally it is useful to know which @file{Makefile} variables
5738 Automake uses for compilations; for instance, you might need to do your
5739 own compilation in some special cases.
5741 Some variables are inherited from Autoconf; these are @code{CC},
5742 @code{CFLAGS}, @code{CPPFLAGS}, @code{DEFS}, @code{LDFLAGS}, and
5751 There are some additional variables that Automake defines on its own:
5755 The contents of this variable are passed to every compilation that invokes
5756 the C preprocessor; it is a list of arguments to the preprocessor. For
5757 instance, @option{-I} and @option{-D} options should be listed here.
5759 Automake already provides some @option{-I} options automatically, in a
5760 separate variable that is also passed to every compilation that invokes
5761 the C preprocessor. In particular it generates @samp{-I.},
5762 @samp{-I$(srcdir)}, and a @option{-I} pointing to the directory holding
5763 @file{config.h} (if you've used @code{AC_CONFIG_HEADERS} or
5764 @code{AM_CONFIG_HEADER}). You can disable the default @option{-I}
5765 options using the @option{nostdinc} option.
5767 @code{AM_CPPFLAGS} is ignored in preference to a per-executable (or
5768 per-library) @code{_CPPFLAGS} variable if it is defined.
5771 This does the same job as @code{AM_CPPFLAGS} (or any per-target
5772 @code{_CPPFLAGS} variable if it is used). It is an older name for the
5773 same functionality. This variable is deprecated; we suggest using
5774 @code{AM_CPPFLAGS} and per-target @code{_CPPFLAGS} instead.
5777 This is the variable the @file{Makefile.am} author can use to pass
5778 in additional C compiler flags. It is more fully documented elsewhere.
5779 In some situations, this is not used, in preference to the
5780 per-executable (or per-library) @code{_CFLAGS}.
5783 This is the command used to actually compile a C source file. The
5784 file name is appended to form the complete command line.
5787 This is the variable the @file{Makefile.am} author can use to pass
5788 in additional linker flags. In some situations, this is not used, in
5789 preference to the per-executable (or per-library) @code{_LDFLAGS}.
5792 This is the command used to actually link a C program. It already
5793 includes @samp{-o $@@} and the usual variable references (for instance,
5794 @code{CFLAGS}); it takes as ``arguments'' the names of the object files
5795 and libraries to link in.
5800 @section Yacc and Lex support
5802 Automake has somewhat idiosyncratic support for Yacc and Lex.
5804 Automake assumes that the @file{.c} file generated by @command{yacc}
5805 (or @command{lex}) should be named using the basename of the input
5806 file. That is, for a yacc source file @file{foo.y}, Automake will
5807 cause the intermediate file to be named @file{foo.c} (as opposed to
5808 @file{y.tab.c}, which is more traditional).
5810 The extension of a yacc source file is used to determine the extension
5811 of the resulting C or C++ file. Files with the extension @file{.y}
5812 will be turned into @file{.c} files; likewise, @file{.yy} will become
5813 @file{.cc}; @file{.y++}, @file{c++}; @file{.yxx}, @file{.cxx}; and
5814 @file{.ypp}, @file{.cpp}.
5816 Likewise, lex source files can be used to generate C or C++; the
5817 extensions @file{.l}, @file{.ll}, @file{.l++}, @file{.lxx}, and
5818 @file{.lpp} are recognized.
5820 You should never explicitly mention the intermediate (C or C++) file
5821 in any @code{SOURCES} variable; only list the source file.
5823 The intermediate files generated by @command{yacc} (or @command{lex})
5824 will be included in any distribution that is made. That way the user
5825 doesn't need to have @command{yacc} or @command{lex}.
5827 If a @command{yacc} source file is seen, then your @file{configure.ac} must
5828 define the variable @code{YACC}. This is most easily done by invoking
5829 the macro @code{AC_PROG_YACC} (@pxref{Particular Programs, , Particular
5830 Program Checks, autoconf, The Autoconf Manual}).
5834 When @code{yacc} is invoked, it is passed @code{YFLAGS} and
5835 @code{AM_YFLAGS}. The former is a user variable and the latter is
5836 intended for the @file{Makefile.am} author.
5838 @code{AM_YFLAGS} is usually used to pass the @option{-d} option to
5839 @command{yacc}. Automake knows what this means and will automatically
5840 adjust its rules to update and distribute the header file built by
5841 @samp{yacc -d}. What Automake cannot guess, though, is where this
5842 header will be used: it is up to you to ensure the header gets built
5843 before it is first used. Typically this is necessary in order for
5844 dependency tracking to work when the header is included by another
5845 file. The common solution is listing the header file in
5846 @code{BUILT_SOURCES} (@pxref{Sources}) as follows.
5849 BUILT_SOURCES = parser.h
5852 foo_SOURCES = @dots{} parser.y @dots{}
5855 If a @command{lex} source file is seen, then your @file{configure.ac}
5856 must define the variable @code{LEX}. You can use @code{AC_PROG_LEX}
5857 to do this (@pxref{Particular Programs, , Particular Program Checks,
5858 autoconf, The Autoconf Manual}), but using @code{AM_PROG_LEX} macro
5859 (@pxref{Macros}) is recommended.
5863 When @command{lex} is invoked, it is passed @code{LFLAGS} and
5864 @code{AM_LFLAGS}. The former is a user variable and the latter is
5865 intended for the @file{Makefile.am} author.
5867 When @code{AM_MAINTAINER_MODE} (@pxref{maintainer-mode}) is used, the
5868 rebuild rule for distributed Yacc and Lex sources are only used when
5869 @code{maintainer-mode} is enabled, or when the files have been erased.
5871 @cindex @command{ylwrap}
5872 @cindex @command{yacc}, multiple parsers
5873 @cindex Multiple @command{yacc} parsers
5874 @cindex Multiple @command{lex} lexers
5875 @cindex @command{lex}, multiple lexers
5877 When @command{lex} or @command{yacc} sources are used, @code{automake
5878 -i} automatically installs an auxiliary program called
5879 @command{ylwrap} in your package (@pxref{Auxiliary Programs}). This
5880 program is used by the build rules to rename the output of these
5881 tools, and makes it possible to include multiple @command{yacc} (or
5882 @command{lex}) source files in a single directory. (This is necessary
5883 because yacc's output file name is fixed, and a parallel make could
5884 conceivably invoke more than one instance of @command{yacc}
5887 For @command{yacc}, simply managing locking is insufficient. The output of
5888 @command{yacc} always uses the same symbol names internally, so it isn't
5889 possible to link two @command{yacc} parsers into the same executable.
5891 We recommend using the following renaming hack used in @command{gdb}:
5893 #define yymaxdepth c_maxdepth
5894 #define yyparse c_parse
5896 #define yyerror c_error
5897 #define yylval c_lval
5898 #define yychar c_char
5899 #define yydebug c_debug
5900 #define yypact c_pact
5907 #define yyexca c_exca
5908 #define yyerrflag c_errflag
5909 #define yynerrs c_nerrs
5913 #define yy_yys c_yys
5914 #define yystate c_state
5917 #define yy_yyv c_yyv
5919 #define yylloc c_lloc
5920 #define yyreds c_reds
5921 #define yytoks c_toks
5922 #define yylhs c_yylhs
5923 #define yylen c_yylen
5924 #define yydefred c_yydefred
5925 #define yydgoto c_yydgoto
5926 #define yysindex c_yysindex
5927 #define yyrindex c_yyrindex
5928 #define yygindex c_yygindex
5929 #define yytable c_yytable
5930 #define yycheck c_yycheck
5931 #define yyname c_yyname
5932 #define yyrule c_yyrule
5935 For each define, replace the @samp{c_} prefix with whatever you like.
5936 These defines work for @command{bison}, @command{byacc}, and
5937 traditional @code{yacc}s. If you find a parser generator that uses a
5938 symbol not covered here, please report the new name so it can be added
5943 @section C++ Support
5946 @cindex Support for C++
5948 Automake includes full support for C++.
5950 Any package including C++ code must define the output variable
5951 @code{CXX} in @file{configure.ac}; the simplest way to do this is to use
5952 the @code{AC_PROG_CXX} macro (@pxref{Particular Programs, , Particular
5953 Program Checks, autoconf, The Autoconf Manual}).
5955 A few additional variables are defined when a C++ source file is seen:
5959 The name of the C++ compiler.
5962 Any flags to pass to the C++ compiler.
5965 The maintainer's variant of @code{CXXFLAGS}.
5968 The command used to actually compile a C++ source file. The file name
5969 is appended to form the complete command line.
5972 The command used to actually link a C++ program.
5976 @node Objective C Support
5977 @section Objective C Support
5979 @cindex Objective C support
5980 @cindex Support for Objective C
5982 Automake includes some support for Objective C.
5984 Any package including Objective C code must define the output variable
5985 @code{OBJC} in @file{configure.ac}; the simplest way to do this is to use
5986 the @code{AC_PROG_OBJC} macro (@pxref{Particular Programs, , Particular
5987 Program Checks, autoconf, The Autoconf Manual}).
5989 A few additional variables are defined when an Objective C source file
5994 The name of the Objective C compiler.
5997 Any flags to pass to the Objective C compiler.
6000 The maintainer's variant of @code{OBJCFLAGS}.
6003 The command used to actually compile a Objective C source file. The
6004 file name is appended to form the complete command line.
6007 The command used to actually link a Objective C program.
6011 @node Unified Parallel C Support
6012 @section Unified Parallel C Support
6014 @cindex Unified Parallel C support
6015 @cindex Support for Unified Parallel C
6017 Automake includes some support for Unified Parallel C.
6019 Any package including Unified Parallel C code must define the output
6020 variable @code{UPC} in @file{configure.ac}; the simplest way to do
6021 this is to use the @code{AM_PROG_UPC} macro (@pxref{Public macros}).
6023 A few additional variables are defined when an Unified Parallel C
6024 source file is seen:
6028 The name of the Unified Parallel C compiler.
6031 Any flags to pass to the Unified Parallel C compiler.
6034 The maintainer's variant of @code{UPCFLAGS}.
6037 The command used to actually compile a Unified Parallel C source file.
6038 The file name is appended to form the complete command line.
6041 The command used to actually link a Unified Parallel C program.
6045 @node Assembly Support
6046 @section Assembly Support
6048 Automake includes some support for assembly code. There are two forms
6049 of assembler files: normal (@file{*.s}) and preprocessed by @code{CPP}
6050 (@file{*.S} or @file{*.sx}).
6055 @vindex AM_CCASFLAGS
6057 The variable @code{CCAS} holds the name of the compiler used to build
6058 assembly code. This compiler must work a bit like a C compiler; in
6059 particular it must accept @option{-c} and @option{-o}. The values of
6060 @code{CCASFLAGS} and @code{AM_CCASFLAGS} (or its per-target
6061 definition) is passed to the compilation. For preprocessed files,
6062 @code{DEFS}, @code{DEFAULT_INCLUDES}, @code{INCLUDES}, @code{CPPFLAGS}
6063 and @code{AM_CPPFLAGS} are also used.
6065 The autoconf macro @code{AM_PROG_AS} will define @code{CCAS} and
6066 @code{CCASFLAGS} for you (unless they are already set, it simply sets
6067 @code{CCAS} to the C compiler and @code{CCASFLAGS} to the C compiler
6068 flags), but you are free to define these variables by other means.
6070 Only the suffixes @file{.s}, @file{.S}, and @file{.sx} are recognized by
6071 @command{automake} as being files containing assembly code.
6074 @node Fortran 77 Support
6075 @comment node-name, next, previous, up
6076 @section Fortran 77 Support
6078 @cindex Fortran 77 support
6079 @cindex Support for Fortran 77
6081 Automake includes full support for Fortran 77.
6083 Any package including Fortran 77 code must define the output variable
6084 @code{F77} in @file{configure.ac}; the simplest way to do this is to use
6085 the @code{AC_PROG_F77} macro (@pxref{Particular Programs, , Particular
6086 Program Checks, autoconf, The Autoconf Manual}).
6088 A few additional variables are defined when a Fortran 77 source file is
6094 The name of the Fortran 77 compiler.
6097 Any flags to pass to the Fortran 77 compiler.
6100 The maintainer's variant of @code{FFLAGS}.
6103 Any flags to pass to the Ratfor compiler.
6106 The maintainer's variant of @code{RFLAGS}.
6109 The command used to actually compile a Fortran 77 source file. The file
6110 name is appended to form the complete command line.
6113 The command used to actually link a pure Fortran 77 program or shared
6118 Automake can handle preprocessing Fortran 77 and Ratfor source files in
6119 addition to compiling them@footnote{Much, if not most, of the
6120 information in the following sections pertaining to preprocessing
6121 Fortran 77 programs was taken almost verbatim from @ref{Catalogue of
6122 Rules, , Catalogue of Rules, make, The GNU Make Manual}.}. Automake
6123 also contains some support for creating programs and shared libraries
6124 that are a mixture of Fortran 77 and other languages (@pxref{Mixing
6125 Fortran 77 With C and C++}).
6127 These issues are covered in the following sections.
6130 * Preprocessing Fortran 77:: Preprocessing Fortran 77 sources
6131 * Compiling Fortran 77 Files:: Compiling Fortran 77 sources
6132 * Mixing Fortran 77 With C and C++:: Mixing Fortran 77 With C and C++
6136 @node Preprocessing Fortran 77
6137 @comment node-name, next, previous, up
6138 @subsection Preprocessing Fortran 77
6140 @cindex Preprocessing Fortran 77
6141 @cindex Fortran 77, Preprocessing
6142 @cindex Ratfor programs
6144 @file{N.f} is made automatically from @file{N.F} or @file{N.r}. This
6145 rule runs just the preprocessor to convert a preprocessable Fortran 77
6146 or Ratfor source file into a strict Fortran 77 source file. The precise
6147 command used is as follows:
6152 @code{$(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)@*
6153 $(AM_FFLAGS) $(FFLAGS)}
6156 @code{$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
6161 @node Compiling Fortran 77 Files
6162 @comment node-name, next, previous, up
6163 @subsection Compiling Fortran 77 Files
6165 @file{N.o} is made automatically from @file{N.f}, @file{N.F} or
6166 @file{N.r} by running the Fortran 77 compiler. The precise command used
6172 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS)}
6175 @code{$(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)@*
6176 $(AM_FFLAGS) $(FFLAGS)}
6179 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
6184 @node Mixing Fortran 77 With C and C++
6185 @comment node-name, next, previous, up
6186 @subsection Mixing Fortran 77 With C and C++
6188 @cindex Fortran 77, mixing with C and C++
6189 @cindex Mixing Fortran 77 with C and C++
6190 @cindex Linking Fortran 77 with C and C++
6192 @cindex Mixing Fortran 77 with C and/or C++
6194 Automake currently provides @emph{limited} support for creating programs
6195 and shared libraries that are a mixture of Fortran 77 and C and/or C++.
6196 However, there are many other issues related to mixing Fortran 77 with
6197 other languages that are @emph{not} (currently) handled by Automake, but
6198 that are handled by other packages@footnote{For example,
6199 @uref{http://www-zeus.desy.de/~burow/cfortran/, the cfortran package}
6200 addresses all of these inter-language issues, and runs under nearly all
6201 Fortran 77, C and C++ compilers on nearly all platforms. However,
6202 @command{cfortran} is not yet Free Software, but it will be in the next
6206 Automake can help in two ways:
6210 Automatic selection of the linker depending on which combinations of
6214 Automatic selection of the appropriate linker flags (e.g., @option{-L} and
6215 @option{-l}) to pass to the automatically selected linker in order to link
6216 in the appropriate Fortran 77 intrinsic and run-time libraries.
6218 @cindex @code{FLIBS}, defined
6220 These extra Fortran 77 linker flags are supplied in the output variable
6221 @code{FLIBS} by the @code{AC_F77_LIBRARY_LDFLAGS} Autoconf macro
6222 supplied with newer versions of Autoconf (Autoconf version 2.13 and
6223 later). @xref{Fortran 77 Compiler Characteristics, , , autoconf, The
6227 If Automake detects that a program or shared library (as mentioned in
6228 some @code{_PROGRAMS} or @code{_LTLIBRARIES} primary) contains source
6229 code that is a mixture of Fortran 77 and C and/or C++, then it requires
6230 that the macro @code{AC_F77_LIBRARY_LDFLAGS} be called in
6231 @file{configure.ac}, and that either @code{$(FLIBS)}
6232 appear in the appropriate @code{_LDADD} (for programs) or @code{_LIBADD}
6233 (for shared libraries) variables. It is the responsibility of the
6234 person writing the @file{Makefile.am} to make sure that @samp{$(FLIBS)}
6235 appears in the appropriate @code{_LDADD} or
6236 @code{_LIBADD} variable.
6238 @cindex Mixed language example
6239 @cindex Example, mixed language
6241 For example, consider the following @file{Makefile.am}:
6245 foo_SOURCES = main.cc foo.f
6246 foo_LDADD = libfoo.la $(FLIBS)
6248 pkglib_LTLIBRARIES = libfoo.la
6249 libfoo_la_SOURCES = bar.f baz.c zardoz.cc
6250 libfoo_la_LIBADD = $(FLIBS)
6253 In this case, Automake will insist that @code{AC_F77_LIBRARY_LDFLAGS}
6254 is mentioned in @file{configure.ac}. Also, if @samp{$(FLIBS)} hadn't
6255 been mentioned in @code{foo_LDADD} and @code{libfoo_la_LIBADD}, then
6256 Automake would have issued a warning.
6261 * How the Linker is Chosen:: Automatic linker selection
6264 @node How the Linker is Chosen
6265 @comment node-name, next, previous, up
6266 @subsubsection How the Linker is Chosen
6268 @cindex Automatic linker selection
6269 @cindex Selecting the linker automatically
6271 When a program or library mixes several languages, Automake choose the
6272 linker according to the following priorities. (The names in
6273 parentheses are the variables containing the link command.)
6278 Native Java (@code{GCJLINK})
6281 C++ (@code{CXXLINK})
6284 Fortran 77 (@code{F77LINK})
6287 Fortran (@code{FCLINK})
6290 Objective C (@code{OBJCLINK})
6293 Unified Parallel C (@code{UPCLINK})
6299 For example, if Fortran 77, C and C++ source code is compiled
6300 into a program, then the C++ linker will be used. In this case, if the
6301 C or Fortran 77 linkers required any special libraries that weren't
6302 included by the C++ linker, then they must be manually added to an
6303 @code{_LDADD} or @code{_LIBADD} variable by the user writing the
6306 Automake only looks at the file names listed in @file{_SOURCES}
6307 variables to choose the linker, and defaults to the C linker.
6308 Sometimes this is inconvenient because you are linking against a
6309 library written in another language and would like to set the linker
6310 more appropriately. @xref{Libtool Convenience Libraries}, for a
6311 trick with @code{nodist_EXTRA_@dots{}_SOURCES}.
6314 @node Fortran 9x Support
6315 @comment node-name, next, previous, up
6316 @section Fortran 9x Support
6318 @cindex Fortran 9x support
6319 @cindex Support for Fortran 9x
6321 Automake includes support for Fortran 9x.
6323 Any package including Fortran 9x code must define the output variable
6324 @code{FC} in @file{configure.ac}; the simplest way to do this is to use
6325 the @code{AC_PROG_FC} macro (@pxref{Particular Programs, , Particular
6326 Program Checks, autoconf, The Autoconf Manual}).
6328 A few additional variables are defined when a Fortran 9x source file is
6334 The name of the Fortran 9x compiler.
6337 Any flags to pass to the Fortran 9x compiler.
6340 The maintainer's variant of @code{FCFLAGS}.
6343 The command used to actually compile a Fortran 9x source file. The file
6344 name is appended to form the complete command line.
6347 The command used to actually link a pure Fortran 9x program or shared
6353 * Compiling Fortran 9x Files:: Compiling Fortran 9x sources
6356 @node Compiling Fortran 9x Files
6357 @comment node-name, next, previous, up
6358 @subsection Compiling Fortran 9x Files
6360 @file{@var{N}.o} is made automatically from @file{@var{N}.f90},
6361 @file{@var{N}.f95}, @file{@var{N}.f03}, or @file{@var{N}.f08}
6362 by running the Fortran 9x compiler. The precise command used
6368 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f90) $<}
6371 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f95) $<}
6374 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f03) $<}
6377 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f08) $<}
6382 @comment node-name, next, previous, up
6383 @section Java Support
6385 @cindex Java support
6386 @cindex Support for Java
6388 Automake includes support for compiled Java, using @command{gcj}, the Java
6389 front end to the GNU Compiler Collection.
6391 Any package including Java code to be compiled must define the output
6392 variable @code{GCJ} in @file{configure.ac}; the variable @code{GCJFLAGS}
6393 must also be defined somehow (either in @file{configure.ac} or
6394 @file{Makefile.am}). The simplest way to do this is to use the
6395 @code{AM_PROG_GCJ} macro.
6399 By default, programs including Java source files are linked with
6402 As always, the contents of @code{AM_GCJFLAGS} are passed to every
6403 compilation invoking @command{gcj} (in its role as an ahead-of-time
6404 compiler, when invoking it to create @file{.class} files,
6405 @code{AM_JAVACFLAGS} is used instead). If it is necessary to pass
6406 options to @command{gcj} from @file{Makefile.am}, this variable, and not
6407 the user variable @code{GCJFLAGS}, should be used.
6411 @command{gcj} can be used to compile @file{.java}, @file{.class},
6412 @file{.zip}, or @file{.jar} files.
6414 When linking, @command{gcj} requires that the main class be specified
6415 using the @option{--main=} option. The easiest way to do this is to use
6416 the @code{_LDFLAGS} variable for the program.
6419 @node Support for Other Languages
6420 @comment node-name, next, previous, up
6421 @section Support for Other Languages
6423 Automake currently only includes full support for C, C++ (@pxref{C++
6424 Support}), Objective C (@pxref{Objective C Support}), Fortran 77
6425 (@pxref{Fortran 77 Support}), Fortran 9x (@pxref{Fortran 9x Support}),
6426 and Java (@pxref{Java Support}). There is only rudimentary support for other
6427 languages, support for which will be improved based on user demand.
6429 Some limited support for adding your own languages is available via the
6430 suffix rule handling (@pxref{Suffixes}).
6434 @section Automatic de-ANSI-fication
6436 @cindex de-ANSI-fication, defined
6438 The features described in this section are obsolete; you should not
6439 used any of them in new code, and they may be withdrawn in future
6442 When the C language was standardized in 1989, there was a long
6443 transition period where package developers needed to worry about
6444 porting to older systems that did not support ANSI C by default.
6445 These older systems are no longer in practical use and are no longer
6446 supported by their original suppliers, so developers need not worry
6447 about this problem any more.
6449 Automake allows you to write packages that are portable to K&R C by
6450 @dfn{de-ANSI-fying} each source file before the actual compilation takes
6453 @vindex AUTOMAKE_OPTIONS
6456 If the @file{Makefile.am} variable @code{AUTOMAKE_OPTIONS}
6457 (@pxref{Options}) contains the option @option{ansi2knr} then code to
6458 handle de-ANSI-fication is inserted into the generated
6461 This causes each C source file in the directory to be treated as ANSI C@.
6462 If an ANSI C compiler is available, it is used. If no ANSI C compiler
6463 is available, the @command{ansi2knr} program is used to convert the source
6464 files into K&R C, which is then compiled.
6466 The @command{ansi2knr} program is simple-minded. It assumes the source
6467 code will be formatted in a particular way; see the @command{ansi2knr} man
6470 @acindex AM_C_PROTOTYPES
6471 Support for the obsolete de-ANSI-fication feature
6472 requires the source files @file{ansi2knr.c}
6473 and @file{ansi2knr.1} to be in the same package as the ANSI C source;
6474 these files are distributed with Automake. Also, the package
6475 @file{configure.ac} must call the macro @code{AM_C_PROTOTYPES}
6478 Automake also handles finding the @command{ansi2knr} support files in some
6479 other directory in the current package. This is done by prepending the
6480 relative path to the appropriate directory to the @command{ansi2knr}
6481 option. For instance, suppose the package has ANSI C code in the
6482 @file{src} and @file{lib} subdirectories. The files @file{ansi2knr.c} and
6483 @file{ansi2knr.1} appear in @file{lib}. Then this could appear in
6484 @file{src/Makefile.am}:
6487 AUTOMAKE_OPTIONS = ../lib/ansi2knr
6490 If no directory prefix is given, the files are assumed to be in the
6493 Note that automatic de-ANSI-fication will not work when the package is
6494 being built for a different host architecture. That is because automake
6495 currently has no way to build @command{ansi2knr} for the build machine.
6497 @c FIXME: this paragraph might be better moved to an `upgrading' section.
6498 @cindex @code{LTLIBOBJS} and @code{ansi2knr}
6499 @cindex @code{LIBOBJS} and @code{ansi2knr}
6500 @cindex @code{ansi2knr} and @code{LTLIBOBJS}
6501 @cindex @code{ansi2knr} and @code{LIBOBJS}
6502 Using @code{LIBOBJS} with source de-ANSI-fication used to require
6503 hand-crafted code in @file{configure} to append @samp{$U} to basenames
6504 in @code{LIBOBJS}. This is no longer true today. Starting with version
6505 2.54, Autoconf takes care of rewriting @code{LIBOBJS} and
6506 @code{LTLIBOBJS}. (@pxref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ}
6507 vs.@: @code{LIBOBJS}, autoconf, The Autoconf Manual})
6510 @section Automatic dependency tracking
6512 As a developer it is often painful to continually update the
6513 @file{Makefile.in} whenever the include-file dependencies change in a
6514 project. Automake supplies a way to automatically track dependency
6515 changes (@pxref{Dependency Tracking}).
6517 @cindex Dependency tracking
6518 @cindex Automatic dependency tracking
6520 Automake always uses complete dependencies for a compilation,
6521 including system headers. Automake's model is that dependency
6522 computation should be a side effect of the build. To this end,
6523 dependencies are computed by running all compilations through a
6524 special wrapper program called @command{depcomp}. @command{depcomp}
6525 understands how to coax many different C and C++ compilers into
6526 generating dependency information in the format it requires.
6527 @samp{automake -a} will install @command{depcomp} into your source
6528 tree for you. If @command{depcomp} can't figure out how to properly
6529 invoke your compiler, dependency tracking will simply be disabled for
6532 @cindex @command{depcomp}
6534 Experience with earlier versions of Automake (@pxref{Dependency
6535 Tracking Evolution}) taught us that it is not reliable to generate
6536 dependencies only on the maintainer's system, as configurations vary
6537 too much. So instead Automake implements dependency tracking at build
6540 Automatic dependency tracking can be suppressed by putting
6541 @option{no-dependencies} in the variable @code{AUTOMAKE_OPTIONS}, or
6542 passing @option{no-dependencies} as an argument to @code{AM_INIT_AUTOMAKE}
6543 (this should be the preferred way). Or, you can invoke @command{automake}
6544 with the @option{-i} option. Dependency tracking is enabled by default.
6546 @vindex AUTOMAKE_OPTIONS
6547 @opindex no-dependencies
6549 The person building your package also can choose to disable dependency
6550 tracking by configuring with @option{--disable-dependency-tracking}.
6552 @cindex Disabling dependency tracking
6553 @cindex Dependency tracking, disabling
6557 @section Support for executable extensions
6559 @cindex Executable extension
6560 @cindex Extension, executable
6563 On some platforms, such as Windows, executables are expected to have an
6564 extension such as @file{.exe}. On these platforms, some compilers (GCC
6565 among them) will automatically generate @file{foo.exe} when asked to
6566 generate @file{foo}.
6568 Automake provides mostly-transparent support for this. Unfortunately
6569 @emph{mostly} doesn't yet mean @emph{fully}. Until the English
6570 dictionary is revised, you will have to assist Automake if your package
6571 must support those platforms.
6573 One thing you must be aware of is that, internally, Automake rewrites
6574 something like this:
6577 bin_PROGRAMS = liver
6583 bin_PROGRAMS = liver$(EXEEXT)
6586 The targets Automake generates are likewise given the @samp{$(EXEEXT)}
6589 The variables @code{TESTS}, @code{XFAIL_TESTS} (@pxref{Tests}) are also
6590 rewritten if it contains filenames that have been declared as programs
6591 in the same @file{Makefile}. (This is mostly useful when some programs
6592 from @code{check_PROGRAMS} are listed in @code{TESTS}.)
6594 However, Automake cannot apply this rewriting to @command{configure}
6595 substitutions. This means that if you are conditionally building a
6596 program using such a substitution, then your @file{configure.ac} must
6597 take care to add @samp{$(EXEEXT)} when constructing the output variable.
6599 With Autoconf 2.13 and earlier, you must explicitly use @code{AC_EXEEXT}
6600 to get this support. With Autoconf 2.50, @code{AC_EXEEXT} is run
6601 automatically if you configure a compiler (say, through
6604 Sometimes maintainers like to write an explicit link rule for their
6605 program. Without executable extension support, this is easy---you
6606 simply write a rule whose target is the name of the program. However,
6607 when executable extension support is enabled, you must instead add the
6608 @samp{$(EXEEXT)} suffix.
6610 Unfortunately, due to the change in Autoconf 2.50, this means you must
6611 always add this extension. However, this is a problem for maintainers
6612 who know their package will never run on a platform that has
6613 executable extensions. For those maintainers, the @option{no-exeext}
6614 option (@pxref{Options}) will disable this feature. This works in a
6615 fairly ugly way; if @option{no-exeext} is seen, then the presence of a
6616 rule for a target named @code{foo} in @file{Makefile.am} will override
6617 an automake-generated rule for @samp{foo$(EXEEXT)}. Without
6618 the @option{no-exeext} option, this use will give a diagnostic.
6622 @chapter Other Derived Objects
6624 Automake can handle derived objects that are not C programs. Sometimes
6625 the support for actually building such objects must be explicitly
6626 supplied, but Automake will still automatically handle installation and
6630 * Scripts:: Executable scripts
6631 * Headers:: Header files
6632 * Data:: Architecture-independent data files
6633 * Sources:: Derived sources
6638 @section Executable Scripts
6640 @cindex @code{_SCRIPTS} primary, defined
6641 @cindex @code{SCRIPTS} primary, defined
6642 @cindex Primary variable, @code{SCRIPTS}
6644 @cindex Installing scripts
6646 It is possible to define and install programs that are scripts. Such
6647 programs are listed using the @code{SCRIPTS} primary name. When the
6648 script is distributed in its final, installable form, the
6649 @file{Makefile} usually looks as follows:
6653 # Install my_script in $(bindir) and distribute it.
6654 dist_bin_SCRIPTS = my_script
6657 Script are not distributed by default; as we have just seen, those
6658 that should be distributed can be specified using a @code{dist_}
6659 prefix as with other primaries.
6661 @cindex @code{SCRIPTS}, installation directories
6663 @vindex sbin_SCRIPTS
6664 @vindex libexec_SCRIPTS
6665 @vindex pkgdata_SCRIPTS
6666 @vindex noinst_SCRIPTS
6667 @vindex check_SCRIPTS
6669 Scripts can be installed in @code{bindir}, @code{sbindir},
6670 @code{libexecdir}, or @code{pkgdatadir}.
6672 Scripts that need not being installed can be listed in
6673 @code{noinst_SCRIPTS}, and among them, those which are needed only by
6674 @samp{make check} should go in @code{check_SCRIPTS}.
6676 When a script needs to be built, the @file{Makefile.am} should include
6677 the appropriate rules. For instance the @command{automake} program
6678 itself is a Perl script that is generated from @file{automake.in}.
6679 Here is how this is handled:
6682 bin_SCRIPTS = automake
6683 CLEANFILES = $(bin_SCRIPTS)
6684 EXTRA_DIST = automake.in
6686 do_subst = sed -e 's,[@@]datadir[@@],$(datadir),g' \
6687 -e 's,[@@]PERL[@@],$(PERL),g' \
6688 -e 's,[@@]PACKAGE[@@],$(PACKAGE),g' \
6689 -e 's,[@@]VERSION[@@],$(VERSION),g' \
6692 automake: automake.in Makefile
6693 $(do_subst) < $(srcdir)/automake.in > automake
6697 Such scripts for which a build rule has been supplied need to be
6698 deleted explicitly using @code{CLEANFILES} (@pxref{Clean}), and their
6699 sources have to be distributed, usually with @code{EXTRA_DIST}
6702 Another common way to build scripts is to process them from
6703 @file{configure} with @code{AC_CONFIG_FILES}. In this situation
6704 Automake knows which files should be cleaned and distributed, and what
6705 the rebuild rules should look like.
6707 For instance if @file{configure.ac} contains
6710 AC_CONFIG_FILES([src/my_script], [chmod +x src/my_script])
6714 to build @file{src/my_script} from @file{src/my_script.in}, then an
6715 @file{src/Makefile.am} to install this script in @code{$(bindir)} can
6719 bin_SCRIPTS = my_script
6720 CLEANFILES = $(bin_SCRIPTS)
6724 There is no need for @code{EXTRA_DIST} or any build rule: Automake
6725 infers them from @code{AC_CONFIG_FILES} (@pxref{Requirements}).
6726 @code{CLEANFILES} is still useful, because by default Automake will
6727 clean targets of @code{AC_CONFIG_FILES} in @code{distclean}, not
6730 Although this looks simpler, building scripts this way has one
6731 drawback: directory variables such as @code{$(datadir)} are not fully
6732 expanded and may refer to other directory variables.
6735 @section Header files
6737 @cindex @code{_HEADERS} primary, defined
6738 @cindex @code{HEADERS} primary, defined
6739 @cindex Primary variable, @code{HEADERS}
6741 @vindex noinst_HEADERS
6742 @cindex @code{HEADERS}, installation directories
6743 @cindex Installing headers
6744 @vindex include_HEADERS
6745 @vindex oldinclude_HEADERS
6746 @vindex pkginclude_HEADERS
6749 Header files that must be installed are specified by the
6750 @code{HEADERS} family of variables. Headers can be installed in
6751 @code{includedir}, @code{oldincludedir}, @code{pkgincludedir} or any
6752 other directory you may have defined (@pxref{Uniform}). For instance,
6755 include_HEADERS = foo.h bar/bar.h
6759 will install the two files as @file{$(includedir)/foo.h} and
6760 @file{$(includedir)/bar.h}.
6762 The @code{nobase_} prefix is also supported,
6765 nobase_include_HEADERS = foo.h bar/bar.h
6769 will install the two files as @file{$(includedir)/foo.h} and
6770 @file{$(includedir)/bar/bar.h} (@pxref{Alternative}).
6772 @vindex noinst_HEADERS
6773 Usually, only header files that accompany installed libraries need to
6774 be installed. Headers used by programs or convenience libraries are
6775 not installed. The @code{noinst_HEADERS} variable can be used for
6776 such headers. However when the header actually belongs to one
6777 convenient library or program, we recommend listing it in the
6778 program's or library's @code{_SOURCES} variable (@pxref{Program
6779 Sources}) instead of in @code{noinst_HEADERS}. This is clearer for
6780 the @file{Makefile.am} reader. @code{noinst_HEADERS} would be the
6781 right variable to use in a directory containing only headers and no
6782 associated library or program.
6784 All header files must be listed somewhere; in a @code{_SOURCES}
6785 variable or in a @code{_HEADERS} variable. Missing ones will not
6786 appear in the distribution.
6788 For header files that are built and must not be distributed, use the
6789 @code{nodist_} prefix as in @code{nodist_include_HEADERS} or
6790 @code{nodist_prog_SOURCES}. If these generated headers are needed
6791 during the build, you must also ensure they exist before they are
6792 used (@pxref{Sources}).
6796 @section Architecture-independent data files
6798 @cindex @code{_DATA} primary, defined
6799 @cindex @code{DATA} primary, defined
6800 @cindex Primary variable, @code{DATA}
6803 Automake supports the installation of miscellaneous data files using the
6804 @code{DATA} family of variables.
6808 @vindex sysconf_DATA
6809 @vindex sharedstate_DATA
6810 @vindex localstate_DATA
6811 @vindex pkgdata_DATA
6813 Such data can be installed in the directories @code{datadir},
6814 @code{sysconfdir}, @code{sharedstatedir}, @code{localstatedir}, or
6817 By default, data files are @emph{not} included in a distribution. Of
6818 course, you can use the @code{dist_} prefix to change this on a
6821 Here is how Automake declares its auxiliary data files:
6824 dist_pkgdata_DATA = clean-kr.am clean.am @dots{}
6829 @section Built sources
6831 Because Automake's automatic dependency tracking works as a side-effect
6832 of compilation (@pxref{Dependencies}) there is a bootstrap issue: a
6833 target should not be compiled before its dependencies are made, but
6834 these dependencies are unknown until the target is first compiled.
6836 Ordinarily this is not a problem, because dependencies are distributed
6837 sources: they preexist and do not need to be built. Suppose that
6838 @file{foo.c} includes @file{foo.h}. When it first compiles
6839 @file{foo.o}, @command{make} only knows that @file{foo.o} depends on
6840 @file{foo.c}. As a side-effect of this compilation @command{depcomp}
6841 records the @file{foo.h} dependency so that following invocations of
6842 @command{make} will honor it. In these conditions, it's clear there is
6843 no problem: either @file{foo.o} doesn't exist and has to be built
6844 (regardless of the dependencies), or accurate dependencies exist and
6845 they can be used to decide whether @file{foo.o} should be rebuilt.
6847 It's a different story if @file{foo.h} doesn't exist by the first
6848 @command{make} run. For instance, there might be a rule to build
6849 @file{foo.h}. This time @file{file.o}'s build will fail because the
6850 compiler can't find @file{foo.h}. @command{make} failed to trigger the
6851 rule to build @file{foo.h} first by lack of dependency information.
6853 @vindex BUILT_SOURCES
6854 @cindex @code{BUILT_SOURCES}, defined
6856 The @code{BUILT_SOURCES} variable is a workaround for this problem. A
6857 source file listed in @code{BUILT_SOURCES} is made on @samp{make all}
6858 or @samp{make check} (or even @samp{make install}) before other
6859 targets are processed. However, such a source file is not
6860 @emph{compiled} unless explicitly requested by mentioning it in some
6861 other @code{_SOURCES} variable.
6863 So, to conclude our introductory example, we could use
6864 @samp{BUILT_SOURCES = foo.h} to ensure @file{foo.h} gets built before
6865 any other target (including @file{foo.o}) during @samp{make all} or
6868 @code{BUILT_SOURCES} is actually a bit of a misnomer, as any file which
6869 must be created early in the build process can be listed in this
6870 variable. Moreover, all built sources do not necessarily have to be
6871 listed in @code{BUILT_SOURCES}. For instance, a generated @file{.c} file
6872 doesn't need to appear in @code{BUILT_SOURCES} (unless it is included by
6873 another source), because it's a known dependency of the associated
6876 It might be important to emphasize that @code{BUILT_SOURCES} is
6877 honored only by @samp{make all}, @samp{make check} and @samp{make
6878 install}. This means you cannot build a specific target (e.g.,
6879 @samp{make foo}) in a clean tree if it depends on a built source.
6880 However it will succeed if you have run @samp{make all} earlier,
6881 because accurate dependencies are already available.
6883 The next section illustrates and discusses the handling of built sources
6887 * Built sources example:: Several ways to handle built sources.
6890 @node Built sources example
6891 @subsection Built sources example
6893 Suppose that @file{foo.c} includes @file{bindir.h}, which is
6894 installation-dependent and not distributed: it needs to be built. Here
6895 @file{bindir.h} defines the preprocessor macro @code{bindir} to the
6896 value of the @command{make} variable @code{bindir} (inherited from
6899 We suggest several implementations below. It's not meant to be an
6900 exhaustive listing of all ways to handle built sources, but it will give
6901 you a few ideas if you encounter this issue.
6903 @unnumberedsubsec First try
6905 This first implementation will illustrate the bootstrap issue mentioned
6906 in the previous section (@pxref{Sources}).
6908 Here is a tentative @file{Makefile.am}.
6914 nodist_foo_SOURCES = bindir.h
6915 CLEANFILES = bindir.h
6917 echo '#define bindir "$(bindir)"' >$@@
6920 This setup doesn't work, because Automake doesn't know that @file{foo.c}
6921 includes @file{bindir.h}. Remember, automatic dependency tracking works
6922 as a side-effect of compilation, so the dependencies of @file{foo.o} will
6923 be known only after @file{foo.o} has been compiled (@pxref{Dependencies}).
6924 The symptom is as follows.
6928 source='foo.c' object='foo.o' libtool=no \
6929 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
6930 depmode=gcc /bin/sh ./depcomp \
6931 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
6932 foo.c:2: bindir.h: No such file or directory
6933 make: *** [foo.o] Error 1
6936 In this example @file{bindir.h} is not distributed nor installed, and
6937 it is not even being built on-time. One may wonder if the
6938 @samp{nodist_foo_SOURCES = bindir.h} line has any use at all. This
6939 line simply states that @file{bindir.h} is a source of @code{foo}, so
6940 for instance, it should be inspected while generating tags
6941 (@pxref{Tags}). In other words, it does not help our present problem,
6942 and the build would fail identically without it.
6944 @unnumberedsubsec Using @code{BUILT_SOURCES}
6946 A solution is to require @file{bindir.h} to be built before anything
6947 else. This is what @code{BUILT_SOURCES} is meant for (@pxref{Sources}).
6952 nodist_foo_SOURCES = bindir.h
6953 BUILT_SOURCES = bindir.h
6954 CLEANFILES = bindir.h
6956 echo '#define bindir "$(bindir)"' >$@@
6959 See how @file{bindir.h} get built first:
6963 echo '#define bindir "/usr/local/bin"' >bindir.h
6965 make[1]: Entering directory `/home/adl/tmp'
6966 source='foo.c' object='foo.o' libtool=no \
6967 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
6968 depmode=gcc /bin/sh ./depcomp \
6969 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
6970 gcc -g -O2 -o foo foo.o
6971 make[1]: Leaving directory `/home/adl/tmp'
6974 However, as said earlier, @code{BUILT_SOURCES} applies only to the
6975 @code{all}, @code{check}, and @code{install} targets. It still fails
6976 if you try to run @samp{make foo} explicitly:
6980 test -z "bindir.h" || rm -f bindir.h
6981 test -z "foo" || rm -f foo
6983 % : > .deps/foo.Po # Suppress previously recorded dependencies
6985 source='foo.c' object='foo.o' libtool=no \
6986 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
6987 depmode=gcc /bin/sh ./depcomp \
6988 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
6989 foo.c:2: bindir.h: No such file or directory
6990 make: *** [foo.o] Error 1
6993 @unnumberedsubsec Recording dependencies manually
6995 Usually people are happy enough with @code{BUILT_SOURCES} because they
6996 never build targets such as @samp{make foo} before @samp{make all}, as
6997 in the previous example. However if this matters to you, you can
6998 avoid @code{BUILT_SOURCES} and record such dependencies explicitly in
6999 the @file{Makefile.am}.
7004 nodist_foo_SOURCES = bindir.h
7005 foo.$(OBJEXT): bindir.h
7006 CLEANFILES = bindir.h
7008 echo '#define bindir "$(bindir)"' >$@@
7011 You don't have to list @emph{all} the dependencies of @file{foo.o}
7012 explicitly, only those that might need to be built. If a dependency
7013 already exists, it will not hinder the first compilation and will be
7014 recorded by the normal dependency tracking code. (Note that after
7015 this first compilation the dependency tracking code will also have
7016 recorded the dependency between @file{foo.o} and
7017 @file{bindir.h}; so our explicit dependency is really useful to
7018 the first build only.)
7020 Adding explicit dependencies like this can be a bit dangerous if you are
7021 not careful enough. This is due to the way Automake tries not to
7022 overwrite your rules (it assumes you know better than it).
7023 @samp{foo.$(OBJEXT): bindir.h} supersedes any rule Automake may want to
7024 output to build @samp{foo.$(OBJEXT)}. It happens to work in this case
7025 because Automake doesn't have to output any @samp{foo.$(OBJEXT):}
7026 target: it relies on a suffix rule instead (i.e., @samp{.c.$(OBJEXT):}).
7027 Always check the generated @file{Makefile.in} if you do this.
7029 @unnumberedsubsec Build @file{bindir.h} from @file{configure}
7031 It's possible to define this preprocessor macro from @file{configure},
7032 either in @file{config.h} (@pxref{Defining Directories, , Defining
7033 Directories, autoconf, The Autoconf Manual}), or by processing a
7034 @file{bindir.h.in} file using @code{AC_CONFIG_FILES}
7035 (@pxref{Configuration Actions, ,Configuration Actions, autoconf, The
7038 At this point it should be clear that building @file{bindir.h} from
7039 @file{configure} work well for this example. @file{bindir.h} will exist
7040 before you build any target, hence will not cause any dependency issue.
7042 The Makefile can be shrunk as follows. We do not even have to mention
7050 However, it's not always possible to build sources from
7051 @file{configure}, especially when these sources are generated by a tool
7052 that needs to be built first...
7054 @unnumberedsubsec Build @file{bindir.c}, not @file{bindir.h}.
7056 Another attractive idea is to define @code{bindir} as a variable or
7057 function exported from @file{bindir.o}, and build @file{bindir.c}
7058 instead of @file{bindir.h}.
7061 noinst_PROGRAMS = foo
7062 foo_SOURCES = foo.c bindir.h
7063 nodist_foo_SOURCES = bindir.c
7064 CLEANFILES = bindir.c
7066 echo 'const char bindir[] = "$(bindir)";' >$@@
7069 @file{bindir.h} contains just the variable's declaration and doesn't
7070 need to be built, so it won't cause any trouble. @file{bindir.o} is
7071 always dependent on @file{bindir.c}, so @file{bindir.c} will get built
7074 @unnumberedsubsec Which is best?
7076 There is no panacea, of course. Each solution has its merits and
7079 You cannot use @code{BUILT_SOURCES} if the ability to run @samp{make
7080 foo} on a clean tree is important to you.
7082 You won't add explicit dependencies if you are leery of overriding
7083 an Automake rule by mistake.
7085 Building files from @file{./configure} is not always possible, neither
7086 is converting @file{.h} files into @file{.c} files.
7089 @node Other GNU Tools
7090 @chapter Other GNU Tools
7092 Since Automake is primarily intended to generate @file{Makefile.in}s for
7093 use in GNU programs, it tries hard to interoperate with other GNU tools.
7096 * Emacs Lisp:: Emacs Lisp
7107 @cindex @code{_LISP} primary, defined
7108 @cindex @code{LISP} primary, defined
7109 @cindex Primary variable, @code{LISP}
7115 Automake provides some support for Emacs Lisp. The @code{LISP} primary
7116 is used to hold a list of @file{.el} files. Possible prefixes for this
7117 primary are @code{lisp_} and @code{noinst_}. Note that if
7118 @code{lisp_LISP} is defined, then @file{configure.ac} must run
7119 @code{AM_PATH_LISPDIR} (@pxref{Macros}).
7121 @vindex dist_lisp_LISP
7122 @vindex dist_noinst_LISP
7123 Lisp sources are not distributed by default. You can prefix the
7124 @code{LISP} primary with @code{dist_}, as in @code{dist_lisp_LISP} or
7125 @code{dist_noinst_LISP}, to indicate that these files should be
7128 Automake will byte-compile all Emacs Lisp source files using the Emacs
7129 found by @code{AM_PATH_LISPDIR}, if any was found.
7131 Byte-compiled Emacs Lisp files are not portable among all versions of
7132 Emacs, so it makes sense to turn this off if you expect sites to have
7133 more than one version of Emacs installed. Furthermore, many packages
7134 don't actually benefit from byte-compilation. Still, we recommend
7135 that you byte-compile your Emacs Lisp sources. It is probably better
7136 for sites with strange setups to cope for themselves than to make the
7137 installation less nice for everybody else.
7139 There are two ways to avoid byte-compiling. Historically, we have
7140 recommended the following construct.
7142 lisp_LISP = file1.el file2.el
7146 @code{ELCFILES} is an internal Automake variable that normally lists
7147 all @file{.elc} files that must be byte-compiled. Automake defines
7148 @code{ELCFILES} automatically from @code{lisp_LISP}. Emptying this
7149 variable explicitly prevents byte-compilation to occur.
7151 Since Automake 1.8, we now recommend using @code{lisp_DATA} instead. As
7154 lisp_DATA = file1.el file2.el
7157 Note that these two constructs are not equivalent. @code{_LISP} will
7158 not install a file if Emacs is not installed, while @code{_DATA} will
7159 always install its files.
7164 @cindex GNU Gettext support
7165 @cindex Gettext support
7166 @cindex Support for GNU Gettext
7168 If @code{AM_GNU_GETTEXT} is seen in @file{configure.ac}, then Automake
7169 turns on support for GNU gettext, a message catalog system for
7170 internationalization
7171 (@pxref{Top, , Introduction, gettext, GNU gettext utilities}).
7173 The @code{gettext} support in Automake requires the addition of one or
7174 two subdirectories to the package, @file{po} and possibly also @file{intl}.
7175 The latter is needed if @code{AM_GNU_GETTEXT} is not invoked with the
7176 @samp{external} argument, or if @code{AM_GNU_GETTEXT_INTL_SUBDIR} is used.
7177 Automake ensures that these directories exist and are mentioned in
7183 Automake provides support for GNU Libtool (@pxref{Top, , Introduction,
7184 libtool, The Libtool Manual}) with the @code{LTLIBRARIES} primary.
7185 @xref{A Shared Library}.
7191 @cindex @code{_JAVA} primary, defined
7192 @cindex @code{JAVA} primary, defined
7193 @cindex Primary variable, @code{JAVA}
7195 Automake provides some minimal support for Java compilation with the
7196 @code{JAVA} primary.
7198 Any @file{.java} files listed in a @code{_JAVA} variable will be
7199 compiled with @code{JAVAC} at build time. By default, @file{.java}
7200 files are not included in the distribution, you should use the
7201 @code{dist_} prefix to distribute them.
7203 Here is a typical setup for distributing @file{.java} files and
7204 installing the @file{.class} files resulting from their compilation.
7207 javadir = $(datadir)/java
7208 dist_java_JAVA = a.java b.java @dots{}
7211 @cindex @code{JAVA} restrictions
7212 @cindex Restrictions for @code{JAVA}
7214 Currently Automake enforces the restriction that only one @code{_JAVA}
7215 primary can be used in a given @file{Makefile.am}. The reason for this
7216 restriction is that, in general, it isn't possible to know which
7217 @file{.class} files were generated from which @file{.java} files, so
7218 it would be impossible to know which files to install where. For
7219 instance, a @file{.java} file can define multiple classes; the resulting
7220 @file{.class} file names cannot be predicted without parsing the
7223 There are a few variables that are used when compiling Java sources:
7227 The name of the Java compiler. This defaults to @samp{javac}.
7230 The flags to pass to the compiler. This is considered to be a user
7231 variable (@pxref{User Variables}).
7234 More flags to pass to the Java compiler. This, and not
7235 @code{JAVACFLAGS}, should be used when it is necessary to put Java
7236 compiler flags into @file{Makefile.am}.
7239 The value of this variable is passed to the @option{-d} option to
7240 @code{javac}. It defaults to @samp{$(top_builddir)}.
7243 This variable is an @code{sh} expression that is used to set the
7244 @env{CLASSPATH} environment variable on the @code{javac} command line.
7245 (In the future we will probably handle class path setting differently.)
7252 @cindex @code{_PYTHON} primary, defined
7253 @cindex @code{PYTHON} primary, defined
7254 @cindex Primary variable, @code{PYTHON}
7257 Automake provides support for Python compilation with the
7258 @code{PYTHON} primary. A typical setup is to call
7259 @code{AM_PATH_PYTHON} in @file{configure.ac} and use a line like the
7260 following in @file{Makefile.am}:
7263 python_PYTHON = tree.py leave.py
7266 Any files listed in a @code{_PYTHON} variable will be byte-compiled
7267 with @command{py-compile} at install time. @command{py-compile}
7268 actually creates both standard (@file{.pyc}) and optimized
7269 (@file{.pyo}) byte-compiled versions of the source files. Note that
7270 because byte-compilation occurs at install time, any files listed in
7271 @code{noinst_PYTHON} will not be compiled. Python source files are
7272 included in the distribution by default, prepend @code{nodist_} (as in
7273 @code{nodist_python_PYTHON}) to omit them.
7275 Automake ships with an Autoconf macro called @code{AM_PATH_PYTHON}
7276 that will determine some Python-related directory variables (see
7277 below). If you have called @code{AM_PATH_PYTHON} from
7278 @file{configure.ac}, then you may use the variables
7279 @code{python_PYTHON} or @code{pkgpython_PYTHON} to list Python source
7280 files in your @file{Makefile.am}, depending where you want your files
7281 installed (see the definitions of @code{pythondir} and
7282 @code{pkgpythondir} below).
7284 @defmac AM_PATH_PYTHON (@ovar{VERSION}, @ovar{ACTION-IF-FOUND}, @ovar{ACTION-IF-NOT-FOUND})
7286 Search for a Python interpreter on the system. This macro takes three
7287 optional arguments. The first argument, if present, is the minimum
7288 version of Python required for this package: @code{AM_PATH_PYTHON}
7289 will skip any Python interpreter that is older than @var{VERSION}.
7290 If an interpreter is found and satisfies @var{VERSION}, then
7291 @var{ACTION-IF-FOUND} is run. Otherwise, @var{ACTION-IF-NOT-FOUND} is
7294 If @var{ACTION-IF-NOT-FOUND} is not specified, as in the following
7295 example, the default is to abort @command{configure}.
7298 AM_PATH_PYTHON([2.2])
7302 This is fine when Python is an absolute requirement for the package.
7303 If Python >= 2.2 was only @emph{optional} to the package,
7304 @code{AM_PATH_PYTHON} could be called as follows.
7307 AM_PATH_PYTHON([2.2],, [:])
7310 @code{AM_PATH_PYTHON} creates the following output variables based on
7311 the Python installation found during configuration.
7316 The name of the Python executable, or @samp{:} if no suitable
7317 interpreter could be found.
7319 Assuming @var{ACTION-IF-NOT-FOUND} is used (otherwise @file{./configure}
7320 will abort if Python is absent), the value of @code{PYTHON} can be used
7321 to setup a conditional in order to disable the relevant part of a build
7325 AM_PATH_PYTHON(,, [:])
7326 AM_CONDITIONAL([HAVE_PYTHON], [test "$PYTHON" != :])
7329 @item PYTHON_VERSION
7330 The Python version number, in the form @var{major}.@var{minor}
7331 (e.g., @samp{1.5}). This is currently the value of
7332 @samp{sys.version[:3]}.
7335 The string @samp{$@{prefix@}}. This term may be used in future work
7336 that needs the contents of Python's @samp{sys.prefix}, but general
7337 consensus is to always use the value from configure.
7339 @item PYTHON_EXEC_PREFIX
7340 The string @samp{$@{exec_prefix@}}. This term may be used in future work
7341 that needs the contents of Python's @samp{sys.exec_prefix}, but general
7342 consensus is to always use the value from configure.
7344 @item PYTHON_PLATFORM
7345 The canonical name used by Python to describe the operating system, as
7346 given by @samp{sys.platform}. This value is sometimes needed when
7347 building Python extensions.
7350 The directory name for the @file{site-packages} subdirectory of the
7351 standard Python install tree.
7354 This is the directory under @code{pythondir} that is named after the
7355 package. That is, it is @samp{$(pythondir)/$(PACKAGE)}. It is provided
7359 This is the directory where Python extension modules (shared libraries)
7360 should be installed. An extension module written in C could be declared
7361 as follows to Automake:
7364 pyexec_LTLIBRARIES = quaternion.la
7365 quaternion_SOURCES = quaternion.c support.c support.h
7366 quaternion_la_LDFLAGS = -avoid-version -module
7370 This is a convenience variable that is defined as
7371 @samp{$(pyexecdir)/$(PACKAGE)}.
7374 All these directory variables have values that start with either
7375 @samp{$@{prefix@}} or @samp{$@{exec_prefix@}} unexpanded. This works
7376 fine in @file{Makefiles}, but it makes these variables hard to use in
7377 @file{configure}. This is mandated by the GNU coding standards, so
7378 that the user can run @samp{make prefix=/foo install}. The Autoconf
7379 manual has a section with more details on this topic
7380 (@pxref{Installation Directory Variables, , Installation Directory
7381 Variables, autoconf, The Autoconf Manual}). See also @ref{Hard-Coded
7386 @chapter Building documentation
7388 Currently Automake provides support for Texinfo and man pages.
7392 * Man pages:: Man pages
7399 @cindex @code{_TEXINFOS} primary, defined
7400 @cindex @code{TEXINFOS} primary, defined
7401 @cindex Primary variable, @code{TEXINFOS}
7402 @cindex HTML output using Texinfo
7403 @cindex PDF output using Texinfo
7404 @cindex PS output using Texinfo
7405 @cindex DVI output using Texinfo
7407 @vindex info_TEXINFOS
7409 If the current directory contains Texinfo source, you must declare it
7410 with the @code{TEXINFOS} primary. Generally Texinfo files are converted
7411 into info, and thus the @code{info_TEXINFOS} variable is most commonly used
7412 here. Any Texinfo source file must end in the @file{.texi},
7413 @file{.txi}, or @file{.texinfo} extension. We recommend @file{.texi}
7416 Automake generates rules to build @file{.info}, @file{.dvi},
7417 @file{.ps}, @file{.pdf} and @file{.html} files from your Texinfo
7418 sources. Following the GNU Coding Standards, only the @file{.info}
7419 files are built by @samp{make all} and installed by @samp{make
7420 install} (unless you use @option{no-installinfo}, see below).
7421 Furthermore, @file{.info} files are automatically distributed so that
7422 Texinfo is not a prerequisite for installing your package.
7428 @trindex install-dvi
7429 @trindex install-html
7430 @trindex install-pdf
7432 Other documentation formats can be built on request by @samp{make
7433 dvi}, @samp{make ps}, @samp{make pdf} and @samp{make html}, and they
7434 can be installed with @samp{make install-dvi}, @samp{make install-ps},
7435 @samp{make install-pdf} and @samp{make install-html} explicitly.
7436 @samp{make uninstall} will remove everything: the Texinfo
7437 documentation installed by default as well as all the above optional
7440 All these targets can be extended using @samp{-local} rules
7441 (@pxref{Extending}).
7443 @cindex Texinfo flag, @code{VERSION}
7444 @cindex Texinfo flag, @code{UPDATED}
7445 @cindex Texinfo flag, @code{EDITION}
7446 @cindex Texinfo flag, @code{UPDATED-MONTH}
7448 @cindex @code{VERSION} Texinfo flag
7449 @cindex @code{UPDATED} Texinfo flag
7450 @cindex @code{EDITION} Texinfo flag
7451 @cindex @code{UPDATED-MONTH} Texinfo flag
7453 @cindex @file{mdate-sh}
7455 If the @file{.texi} file @code{@@include}s @file{version.texi}, then
7456 that file will be automatically generated. The file @file{version.texi}
7457 defines four Texinfo flag you can reference using
7458 @code{@@value@{EDITION@}}, @code{@@value@{VERSION@}},
7459 @code{@@value@{UPDATED@}}, and @code{@@value@{UPDATED-MONTH@}}.
7464 Both of these flags hold the version number of your program. They are
7465 kept separate for clarity.
7468 This holds the date the primary @file{.texi} file was last modified.
7471 This holds the name of the month in which the primary @file{.texi} file
7475 The @file{version.texi} support requires the @command{mdate-sh}
7476 script; this script is supplied with Automake and automatically
7477 included when @command{automake} is invoked with the
7478 @option{--add-missing} option.
7480 If you have multiple Texinfo files, and you want to use the
7481 @file{version.texi} feature, then you have to have a separate version
7482 file for each Texinfo file. Automake will treat any include in a
7483 Texinfo file that matches @file{vers*.texi} just as an automatically
7484 generated version file.
7486 Sometimes an info file actually depends on more than one @file{.texi}
7487 file. For instance, in GNU Hello, @file{hello.texi} includes the file
7488 @file{gpl.texi}. You can tell Automake about these dependencies using
7489 the @code{@var{texi}_TEXINFOS} variable. Here is how GNU Hello does it:
7494 info_TEXINFOS = hello.texi
7495 hello_TEXINFOS = gpl.texi
7498 @cindex @file{texinfo.tex}
7500 By default, Automake requires the file @file{texinfo.tex} to appear in
7501 the same directory as the @file{Makefile.am} file that lists the
7502 @file{.texi} files. If you used @code{AC_CONFIG_AUX_DIR} in
7503 @file{configure.ac} (@pxref{Input, , Finding `configure' Input,
7504 autoconf, The Autoconf Manual}), then @file{texinfo.tex} is looked for
7505 there. In both cases, automake then supplies @file{texinfo.tex} if
7506 @option{--add-missing} is given, and takes care of its distribution.
7507 However, if you set the @code{TEXINFO_TEX} variable (see below),
7508 it overrides the location of the file and turns off its installation
7509 into the source as well as its distribution.
7511 The option @option{no-texinfo.tex} can be used to eliminate the
7512 requirement for the file @file{texinfo.tex}. Use of the variable
7513 @code{TEXINFO_TEX} is preferable, however, because that allows the
7514 @code{dvi}, @code{ps}, and @code{pdf} targets to still work.
7516 @cindex Option, @code{no-installinfo}
7517 @cindex Target, @code{install-info}
7518 @cindex @code{install-info} target
7519 @cindex @code{no-installinfo} option
7521 @opindex no-installinfo
7522 @trindex install-info
7524 Automake generates an @code{install-info} rule; some people apparently
7525 use this. By default, info pages are installed by @samp{make
7526 install}, so running @code{make install-info} is pointless. This can
7527 be prevented via the @code{no-installinfo} option. In this case,
7528 @file{.info} files are not installed by default, and user must
7529 request this explicitly using @samp{make install-info}
7531 The following variables are used by the Texinfo build rules.
7535 The name of the program invoked to build @file{.info} files. This
7536 variable is defined by Automake. If the @command{makeinfo} program is
7537 found on the system then it will be used by default; otherwise
7538 @command{missing} will be used instead.
7541 The command invoked to build @file{.html} files. Automake
7542 defines this to @samp{$(MAKEINFO) --html}.
7545 User flags passed to each invocation of @samp{$(MAKEINFO)} and
7546 @samp{$(MAKEINFOHTML)}. This user variable (@pxref{User Variables}) is
7547 not expected to be defined in any @file{Makefile}; it can be used by
7548 users to pass extra flags to suit their needs.
7550 @item AM_MAKEINFOFLAGS
7551 @itemx AM_MAKEINFOHTMLFLAGS
7552 Maintainer flags passed to each @command{makeinfo} invocation. Unlike
7553 @code{MAKEINFOFLAGS}, these variables are meant to be defined by
7554 maintainers in @file{Makefile.am}. @samp{$(AM_MAKEINFOFLAGS)} is
7555 passed to @code{makeinfo} when building @file{.info} files; and
7556 @samp{$(AM_MAKEINFOHTMLFLAGS)} is used when building @file{.html}
7559 For instance, the following setting can be used to obtain one single
7560 @file{.html} file per manual, without node separators.
7562 AM_MAKEINFOHTMLFLAGS = --no-headers --no-split
7565 @code{AM_MAKEINFOHTMLFLAGS} defaults to @samp{$(AM_MAKEINFOFLAGS)}.
7566 This means that defining @code{AM_MAKEINFOFLAGS} without defining
7567 @code{AM_MAKEINFOHTMLFLAGS} will impact builds of both @file{.info}
7568 and @file{.html} files.
7571 The name of the command that converts a @file{.texi} file into a
7572 @file{.dvi} file. This defaults to @samp{texi2dvi}, a script that ships
7573 with the Texinfo package.
7576 The name of the command that translates a @file{.texi} file into a
7577 @file{.pdf} file. This defaults to @samp{$(TEXI2DVI) --pdf --batch}.
7580 The name of the command that build a @file{.ps} file out of a
7581 @file{.dvi} file. This defaults to @samp{dvips}.
7585 If your package has Texinfo files in many directories, you can use the
7586 variable @code{TEXINFO_TEX} to tell Automake where to find the canonical
7587 @file{texinfo.tex} for your package. The value of this variable should
7588 be the relative path from the current @file{Makefile.am} to
7592 TEXINFO_TEX = ../doc/texinfo.tex
7600 @cindex @code{_MANS} primary, defined
7601 @cindex @code{MANS} primary, defined
7602 @cindex Primary variable, @code{MANS}
7606 A package can also include man pages (but see the GNU standards on this
7607 matter, @ref{Man Pages, , , standards, The GNU Coding Standards}.) Man
7608 pages are declared using the @code{MANS} primary. Generally the
7609 @code{man_MANS} variable is used. Man pages are automatically installed in
7610 the correct subdirectory of @code{mandir}, based on the file extension.
7612 File extensions such as @file{.1c} are handled by looking for the valid
7613 part of the extension and using that to determine the correct
7614 subdirectory of @code{mandir}. Valid section names are the digits
7615 @samp{0} through @samp{9}, and the letters @samp{l} and @samp{n}.
7617 Sometimes developers prefer to name a man page something like
7618 @file{foo.man} in the source, and then rename it to have the correct
7619 suffix, for example @file{foo.1}, when installing the file. Automake
7620 also supports this mode. For a valid section named @var{SECTION},
7621 there is a corresponding directory named @samp{man@var{SECTION}dir},
7622 and a corresponding @code{_MANS} variable. Files listed in such a
7623 variable are installed in the indicated section. If the file already
7624 has a valid suffix, then it is installed as-is; otherwise the file
7625 suffix is changed to match the section.
7627 For instance, consider this example:
7629 man1_MANS = rename.man thesame.1 alsothesame.1c
7632 In this case, @file{rename.man} will be renamed to @file{rename.1} when
7633 installed, but the other files will keep their names.
7635 @cindex Target, @code{install-man}
7636 @cindex Option, @option{no-installman}
7637 @cindex @code{install-man} target
7638 @cindex @option{no-installman} option
7639 @opindex no-installman
7640 @trindex install-man
7642 By default, man pages are installed by @samp{make install}. However,
7643 since the GNU project does not require man pages, many maintainers do
7644 not expend effort to keep the man pages up to date. In these cases, the
7645 @option{no-installman} option will prevent the man pages from being
7646 installed by default. The user can still explicitly install them via
7647 @samp{make install-man}.
7649 Man pages are not currently considered to be source, because it is not
7650 uncommon for man pages to be automatically generated. Therefore they
7651 are not automatically included in the distribution. However, this can
7652 be changed by use of the @code{dist_} prefix. For instance here is
7653 how to distribute and install the two man pages of GNU @command{cpio}
7654 (which includes both Texinfo documentation and man pages):
7657 dist_man_MANS = cpio.1 mt.1
7660 The @code{nobase_} prefix is meaningless for man pages and is
7664 @cindex @code{notrans_} prefix
7665 @cindex Man page renaming, avoiding
7666 @cindex Avoiding man page renaming
7668 Executables and manpages may be renamed upon installation
7669 (@pxref{Renaming}). For manpages this can be avoided by use of the
7670 @code{notrans_} prefix. For instance, suppose an executable @samp{foo}
7671 allowing to access a library function @samp{foo} from the command line.
7672 The way to avoid renaming of the @file{foo.3} manpage is:
7676 notrans_man_MANS = foo.3
7679 @cindex @code{notrans_} and @code{dist_} or @code{nodist_}
7680 @cindex @code{dist_} and @code{notrans_}
7681 @cindex @code{nodist_} and @code{notrans_}
7683 @samp{notrans_} must be specified first when used in conjunction with
7684 either @samp{dist_} or @samp{nodist_} (@pxref{Dist}). For instance:
7687 notrans_dist_man3_MANS = bar.3
7691 @chapter What Gets Installed
7693 @cindex Installation support
7694 @cindex @samp{make install} support
7696 @section Basics of installation
7698 Naturally, Automake handles the details of actually installing your
7699 program once it has been built. All files named by the various
7700 primaries are automatically installed in the appropriate places when the
7701 user runs @samp{make install}.
7703 A file named in a primary is installed by copying the built file into
7704 the appropriate directory. The base name of the file is used when
7708 bin_PROGRAMS = hello subdir/goodbye
7711 In this example, both @samp{hello} and @samp{goodbye} will be installed
7712 in @samp{$(bindir)}.
7714 Sometimes it is useful to avoid the basename step at install time. For
7715 instance, you might have a number of header files in subdirectories of
7716 the source tree that are laid out precisely how you want to install
7717 them. In this situation you can use the @code{nobase_} prefix to
7718 suppress the base name step. For example:
7721 nobase_include_HEADERS = stdio.h sys/types.h
7724 Will install @file{stdio.h} in @samp{$(includedir)} and @file{types.h}
7725 in @samp{$(includedir)/sys}.
7727 @section The two parts of install
7729 Automake generates separate @code{install-data} and @code{install-exec}
7730 rules, in case the installer is installing on multiple machines that
7731 share directory structure---these targets allow the machine-independent
7732 parts to be installed only once. @code{install-exec} installs
7733 platform-dependent files, and @code{install-data} installs
7734 platform-independent files. The @code{install} target depends on both
7735 of these targets. While Automake tries to automatically segregate
7736 objects into the correct category, the @file{Makefile.am} author is, in
7737 the end, responsible for making sure this is done correctly.
7738 @trindex install-data
7739 @trindex install-exec
7741 @cindex Install, two parts of
7743 Variables using the standard directory prefixes @samp{data},
7744 @samp{info}, @samp{man}, @samp{include}, @samp{oldinclude},
7745 @samp{pkgdata}, or @samp{pkginclude} are installed by
7746 @code{install-data}.
7748 Variables using the standard directory prefixes @samp{bin},
7749 @samp{sbin}, @samp{libexec}, @samp{sysconf}, @samp{localstate},
7750 @samp{lib}, or @samp{pkglib} are installed by @code{install-exec}.
7752 For instance, @code{data_DATA} files are installed by @code{install-data},
7753 while @code{bin_PROGRAMS} files are installed by @code{install-exec}.
7755 Any variable using a user-defined directory prefix with @samp{exec} in
7756 the name (e.g., @code{myexecbin_PROGRAMS}) is installed by
7757 @code{install-exec}. All other user-defined prefixes are installed by
7758 @code{install-data}.
7760 @section Extending installation
7762 It is possible to extend this mechanism by defining an
7763 @code{install-exec-local} or @code{install-data-local} rule. If these
7764 rules exist, they will be run at @samp{make install} time. These
7765 rules can do almost anything; care is required.
7766 @trindex install-exec-local
7767 @trindex install-data-local
7769 Automake also supports two install hooks, @code{install-exec-hook} and
7770 @code{install-data-hook}. These hooks are run after all other install
7771 rules of the appropriate type, exec or data, have completed. So, for
7772 instance, it is possible to perform post-installation modifications
7773 using an install hook. @ref{Extending} gives some examples.
7774 @cindex Install hook
7776 @section Staged installs
7779 Automake generates support for the @code{DESTDIR} variable in all
7780 install rules. @code{DESTDIR} is used during the @samp{make install}
7781 step to relocate install objects into a staging area. Each object and
7782 path is prefixed with the value of @code{DESTDIR} before being copied
7783 into the install area. Here is an example of typical DESTDIR usage:
7786 mkdir /tmp/staging &&
7787 make DESTDIR=/tmp/staging install
7790 The @command{mkdir} command avoids a security problem if the attacker
7791 creates a symbolic link from @file{/tmp/staging} to a victim area;
7792 then @command{make} places install objects in a directory tree built under
7793 @file{/tmp/staging}. If @file{/gnu/bin/foo} and
7794 @file{/gnu/share/aclocal/foo.m4} are to be installed, the above command
7795 would install @file{/tmp/staging/gnu/bin/foo} and
7796 @file{/tmp/staging/gnu/share/aclocal/foo.m4}.
7798 This feature is commonly used to build install images and packages
7801 Support for @code{DESTDIR} is implemented by coding it directly into
7802 the install rules. If your @file{Makefile.am} uses a local install
7803 rule (e.g., @code{install-exec-local}) or an install hook, then you
7804 must write that code to respect @code{DESTDIR}.
7806 @xref{Makefile Conventions, , , standards, The GNU Coding Standards},
7807 for another usage example.
7809 @section Rules for the user
7811 Automake also generates rules for targets @code{uninstall},
7812 @code{installdirs}, and @code{install-strip}.
7814 @trindex installdirs
7815 @trindex install-strip
7817 Automake supports @code{uninstall-local} and @code{uninstall-hook}.
7818 There is no notion of separate uninstalls for ``exec'' and ``data'', as
7819 these features would not provide additional functionality.
7821 Note that @code{uninstall} is not meant as a replacement for a real
7826 @chapter What Gets Cleaned
7828 @cindex @samp{make clean} support
7830 The GNU Makefile Standards specify a number of different clean rules.
7831 @xref{Standard Targets, , Standard Targets for Users, standards,
7832 The GNU Coding Standards}.
7834 Generally the files that can be cleaned are determined automatically by
7835 Automake. Of course, Automake also recognizes some variables that can
7836 be defined to specify additional files to clean. These variables are
7837 @code{MOSTLYCLEANFILES}, @code{CLEANFILES}, @code{DISTCLEANFILES}, and
7838 @code{MAINTAINERCLEANFILES}.
7839 @vindex MOSTLYCLEANFILES
7841 @vindex DISTCLEANFILES
7842 @vindex MAINTAINERCLEANFILES
7844 @trindex mostlyclean-local
7845 @trindex clean-local
7846 @trindex distclean-local
7847 @trindex maintainer-clean-local
7848 When cleaning involves more than deleting some hard-coded list of
7849 files, it is also possible to supplement the cleaning rules with your
7850 own commands. Simply define a rule for any of the
7851 @code{mostlyclean-local}, @code{clean-local}, @code{distclean-local},
7852 or @code{maintainer-clean-local} targets (@pxref{Extending}). A common
7853 case is deleting a directory, for instance, a directory created by the
7861 As the GNU Standards aren't always explicit as to which files should
7862 be removed by which rule, we've adopted a heuristic that we believe
7863 was first formulated by Fran@,{c}ois Pinard:
7867 If @command{make} built it, and it is commonly something that one would
7868 want to rebuild (for instance, a @file{.o} file), then
7869 @code{mostlyclean} should delete it.
7872 Otherwise, if @command{make} built it, then @code{clean} should delete it.
7875 If @command{configure} built it, then @code{distclean} should delete it.
7878 If the maintainer built it (for instance, a @file{.info} file), then
7879 @code{maintainer-clean} should delete it. However
7880 @code{maintainer-clean} should not delete anything that needs to exist
7881 in order to run @samp{./configure && make}.
7884 We recommend that you follow this same set of heuristics in your
7889 @chapter What Goes in a Distribution
7891 @section Basics of distribution
7893 @cindex @samp{make dist}
7898 The @code{dist} rule in the generated @file{Makefile.in} can be used
7899 to generate a gzipped @code{tar} file and other flavors of archive for
7900 distribution. The files is named based on the @code{PACKAGE} and
7901 @code{VERSION} variables defined by @code{AM_INIT_AUTOMAKE}
7902 (@pxref{Macros}); more precisely the gzipped @code{tar} file is named
7903 @samp{@var{package}-@var{version}.tar.gz}.
7905 You can use the @command{make} variable @code{GZIP_ENV} to control how gzip
7906 is run. The default setting is @option{--best}.
7908 @cindex @code{m4_include}, distribution
7909 @cindex @code{include}, distribution
7912 For the most part, the files to distribute are automatically found by
7913 Automake: all source files are automatically included in a distribution,
7914 as are all @file{Makefile.am}s and @file{Makefile.in}s. Automake also
7915 has a built-in list of commonly used files that are automatically
7916 included if they are found in the current directory (either physically,
7917 or as the target of a @file{Makefile.am} rule). This list is printed by
7918 @samp{automake --help}. Also, files that are read by @command{configure}
7919 (i.e.@: the source files corresponding to the files specified in various
7920 Autoconf macros such as @code{AC_CONFIG_FILES} and siblings) are
7921 automatically distributed. Files included in @file{Makefile.am}s (using
7922 @code{include}) or in @file{configure.ac} (using @code{m4_include}), and
7923 helper scripts installed with @samp{automake --add-missing} are also
7927 Still, sometimes there are files that must be distributed, but which
7928 are not covered in the automatic rules. These files should be listed in
7929 the @code{EXTRA_DIST} variable. You can mention files from
7930 subdirectories in @code{EXTRA_DIST}.
7932 You can also mention a directory in @code{EXTRA_DIST}; in this case the
7933 entire directory will be recursively copied into the distribution.
7934 Please note that this will also copy @emph{everything} in the directory,
7935 including CVS/RCS version control files. We recommend against using
7939 @vindex DIST_SUBDIRS
7940 If you define @code{SUBDIRS}, Automake will recursively include the
7941 subdirectories in the distribution. If @code{SUBDIRS} is defined
7942 conditionally (@pxref{Conditionals}), Automake will normally include
7943 all directories that could possibly appear in @code{SUBDIRS} in the
7944 distribution. If you need to specify the set of directories
7945 conditionally, you can set the variable @code{DIST_SUBDIRS} to the
7946 exact list of subdirectories to include in the distribution
7947 (@pxref{Conditional Subdirectories}).
7950 @section Fine-grained distribution control
7954 Sometimes you need tighter control over what does @emph{not} go into the
7955 distribution; for instance, you might have source files that are
7956 generated and that you do not want to distribute. In this case
7957 Automake gives fine-grained control using the @code{dist} and
7958 @code{nodist} prefixes. Any primary or @code{_SOURCES} variable can be
7959 prefixed with @code{dist_} to add the listed files to the distribution.
7960 Similarly, @code{nodist_} can be used to omit the files from the
7963 As an example, here is how you would cause some data to be distributed
7964 while leaving some source code out of the distribution:
7967 dist_data_DATA = distribute-this
7969 nodist_foo_SOURCES = do-not-distribute.c
7972 @section The dist hook
7976 Occasionally it is useful to be able to change the distribution before
7977 it is packaged up. If the @code{dist-hook} rule exists, it is run
7978 after the distribution directory is filled, but before the actual tar
7979 (or shar) file is created. One way to use this is for distributing
7980 files in subdirectories for which a new @file{Makefile.am} is overkill:
7984 mkdir $(distdir)/random
7985 cp -p $(srcdir)/random/a1 $(srcdir)/random/a2 $(distdir)/random
7988 Another way to use this is for removing unnecessary files that get
7989 recursively included by specifying a directory in EXTRA_DIST:
7995 rm -rf `find $(distdir)/doc -name CVS`
8000 Two variables that come handy when writing @code{dist-hook} rules are
8001 @samp{$(distdir)} and @samp{$(top_distdir)}.
8003 @samp{$(distdir)} points to the directory where the @code{dist} rule
8004 will copy files from the current directory before creating the
8005 tarball. If you are at the top-level directory, then @samp{distdir =
8006 $(PACKAGE)-$(VERSION)}. When used from subdirectory named
8007 @file{foo/}, then @samp{distdir = ../$(PACKAGE)-$(VERSION)/foo}.
8008 @samp{$(distdir)} can be a relative or absolute path, do not assume
8011 @samp{$(top_distdir)} always points to the root directory of the
8012 distributed tree. At the top-level it's equal to @samp{$(distdir)}.
8013 In the @file{foo/} subdirectory
8014 @samp{top_distdir = ../$(PACKAGE)-$(VERSION)}.
8015 @samp{$(top_distdir)} too can be a relative or absolute path.
8017 Note that when packages are nested using @code{AC_CONFIG_SUBDIRS}
8018 (@pxref{Subpackages}), then @samp{$(distdir)} and
8019 @samp{$(top_distdir)} are relative to the package where @samp{make
8020 dist} was run, not to any sub-packages involved.
8022 @section Checking the distribution
8024 @cindex @samp{make distcheck}
8025 @cindex @samp{make distcleancheck}
8026 @vindex distcleancheck_listfiles
8027 @cindex @samp{make distuninstallcheck}
8028 @vindex distuninstallcheck_listfiles
8031 Automake also generates a @code{distcheck} rule that can be of help to
8032 ensure that a given distribution will actually work. @code{distcheck}
8033 makes a distribution, then tries to do a @code{VPATH} build
8034 (@pxref{VPATH Builds}), run the test suite, and finally make another
8035 tarball to ensure the distribution is self-contained.
8037 @vindex DISTCHECK_CONFIGURE_FLAGS
8038 Building the package involves running @samp{./configure}. If you need
8039 to supply additional flags to @command{configure}, define them in the
8040 @code{DISTCHECK_CONFIGURE_FLAGS} variable, either in your top-level
8041 @file{Makefile.am}, or on the command line when invoking @command{make}.
8043 @trindex distcheck-hook
8044 If the @code{distcheck-hook} rule is defined in your top-level
8045 @file{Makefile.am}, then it will be invoked by @code{distcheck} after
8046 the new distribution has been unpacked, but before the unpacked copy
8047 is configured and built. Your @code{distcheck-hook} can do almost
8048 anything, though as always caution is advised. Generally this hook is
8049 used to check for potential distribution errors not caught by the
8050 standard mechanism. Note that @code{distcheck-hook} as well as
8051 @code{DISTCHECK_CONFIGURE_FLAGS} are not honored in a subpackage
8052 @file{Makefile.am}, but the @code{DISTCHECK_CONFIGURE_FLAGS} are
8053 passed down to the @command{configure} script of the subpackage.
8055 @trindex distcleancheck
8056 @vindex DISTCLEANFILES
8057 @vindex distcleancheck_listfiles
8058 Speaking of potential distribution errors, @code{distcheck} also
8059 ensures that the @code{distclean} rule actually removes all built
8060 files. This is done by running @samp{make distcleancheck} at the end of
8061 the @code{VPATH} build. By default, @code{distcleancheck} will run
8062 @code{distclean} and then make sure the build tree has been emptied by
8063 running @samp{$(distcleancheck_listfiles)}. Usually this check will
8064 find generated files that you forgot to add to the @code{DISTCLEANFILES}
8065 variable (@pxref{Clean}).
8067 The @code{distcleancheck} behavior should be OK for most packages,
8068 otherwise you have the possibility to override the definition of
8069 either the @code{distcleancheck} rule, or the
8070 @samp{$(distcleancheck_listfiles)} variable. For instance, to disable
8071 @code{distcleancheck} completely, add the following rule to your
8072 top-level @file{Makefile.am}:
8079 If you want @code{distcleancheck} to ignore built files that have not
8080 been cleaned because they are also part of the distribution, add the
8081 following definition instead:
8084 distcleancheck_listfiles = \
8085 find -type f -exec sh -c 'test -f $(srcdir)/@{@} || echo @{@}' ';'
8088 The above definition is not the default because it's usually an error if
8089 your Makefiles cause some distributed files to be rebuilt when the user
8090 build the package. (Think about the user missing the tool required to
8091 build the file; or if the required tool is built by your package,
8092 consider the cross-compilation case where it can't be run.) There is
8093 a FAQ entry about this (@pxref{distcleancheck}), make sure you read it
8094 before playing with @code{distcleancheck_listfiles}.
8096 @code{distcheck} also checks that the @code{uninstall} rule works
8097 properly, both for ordinary and @code{DESTDIR} builds. It does this
8098 by invoking @samp{make uninstall}, and then it checks the install tree
8099 to see if any files are left over. This check will make sure that you
8100 correctly coded your @code{uninstall}-related rules.
8102 By default, the checking is done by the @code{distuninstallcheck} rule,
8103 and the list of files in the install tree is generated by
8104 @samp{$(distuninstallcheck_listfiles}) (this is a variable whose value is
8105 a shell command to run that prints the list of files to stdout).
8107 Either of these can be overridden to modify the behavior of
8108 @code{distcheck}. For instance, to disable this check completely, you
8116 @section The types of distributions
8118 Automake generates rules to provide archives of the project for
8119 distributions in various formats. Their targets are:
8122 @item @code{dist-bzip2}
8123 Generate a bzip2 tar archive of the distribution. bzip2 archives are
8124 frequently smaller than gzipped archives.
8127 @item @code{dist-gzip}
8128 Generate a gzip tar archive of the distribution.
8131 @item @code{dist-lzma}
8132 Generate a lzma tar archive of the distribution. lzma archives are
8133 frequently smaller than @command{bzip2}-compressed archives.
8136 @item @code{dist-shar}
8137 Generate a shar archive of the distribution.
8140 @item @code{dist-zip}
8141 Generate a zip archive of the distribution.
8144 @item @code{dist-tarZ}
8145 Generate a compressed tar archive of
8150 The rule @code{dist} (and its historical synonym @code{dist-all}) will
8151 create archives in all the enabled formats, @ref{Options}. By
8152 default, only the @code{dist-gzip} target is hooked to @code{dist}.
8156 @chapter Support for test suites
8159 @cindex @code{make check}
8162 Automake supports two forms of test suites.
8164 @section Simple Tests
8166 If the variable @code{TESTS} is defined, its value is taken to be a
8167 list of programs or scripts to run in order to do the testing.
8168 Programs needing data files should look for them in @code{srcdir}
8169 (which is both an environment variable and a make variable) so they
8170 work when building in a separate directory (@pxref{Build Directories,
8171 , Build Directories , autoconf, The Autoconf Manual}), and in
8172 particular for the @code{distcheck} rule (@pxref{Dist}).
8174 For each of the @code{TESTS}, the result of execution is printed along
8175 with the test name, where @code{PASS} denotes a successful test,
8176 @code{FAIL} denotes a failed test, @code{XFAIL} an expected failure,
8177 @code{XPASS} an unexpected pass for a test that is supposed to fail,
8178 and @code{SKIP} denotes a skipped test.
8180 @cindex Exit status 77, special interpretation
8182 The number of failures will be printed at the end of the run. If a
8183 given test program exits with a status of 77, then its result is ignored
8184 in the final count. This feature allows non-portable tests to be
8185 ignored in environments where they don't make sense.
8187 @vindex AM_COLOR_TESTS
8188 If the Automake option @code{color-tests} is used (@pxref{Options})
8189 and standard output is connected to a capable terminal, then the test
8190 results and the summary are colored appropriately. The user can disable
8191 colored output by setting the @command{make} variable
8192 @samp{AM_COLOR_TESTS=no}, or force colored output even without a connecting
8193 terminal with @samp{AM_COLOR_TESTS=always}.
8196 @vindex TESTS_ENVIRONMENT
8197 The variable @code{TESTS_ENVIRONMENT} can be used to set environment
8198 variables for the test run; the environment variable @code{srcdir} is
8199 set in the rule. If all your test programs are scripts, you can also
8200 set @code{TESTS_ENVIRONMENT} to an invocation of the shell (e.g.
8201 @samp{$(SHELL) -x} can be useful for debugging the tests), or any other
8202 interpreter. For instance the following setup is used by the Automake
8203 package to run four tests in Perl.
8205 TESTS_ENVIRONMENT = $(PERL) -Mstrict -I $(top_srcdir)/lib -w
8206 TESTS = Condition.pl DisjConditions.pl Version.pl Wrap.pl
8210 @cindex Tests, expected failure
8211 @cindex Expected test failure
8213 You may define the variable @code{XFAIL_TESTS} to a list of tests
8214 (usually a subset of @code{TESTS}) that are expected to fail. This will
8215 reverse the result of those tests.
8218 Automake ensures that each file listed in @code{TESTS} is built before
8219 any tests are run; you can list both source and derived programs (or
8220 scripts) in @code{TESTS}; the generated rule will look both in
8221 @code{srcdir} and @file{.}. For instance, you might want to run a C
8222 program as a test. To do this you would list its name in @code{TESTS}
8223 and also in @code{check_PROGRAMS}, and then specify it as you would
8226 Programs listed in @code{check_PROGRAMS} (and @code{check_LIBRARIES},
8227 @code{check_LTLIBRARIES}...) are only built during @code{make check},
8228 not during @code{make all}. You should list there any program needed
8229 by your tests that does not need to be built by @code{make all}. Note
8230 that @code{check_PROGRAMS} are @emph{not} automatically added to
8231 @code{TESTS} because @code{check_PROGRAMS} usually lists programs used
8232 by the tests, not the tests themselves. Of course you can set
8233 @code{TESTS = $(check_PROGRAMS)} if all your programs are test cases.
8235 @section DejaGnu Tests
8237 If @uref{ftp://ftp.gnu.org/gnu/dejagnu/, @command{dejagnu}} appears in
8238 @code{AUTOMAKE_OPTIONS}, then a @command{dejagnu}-based test suite is
8239 assumed. The variable @code{DEJATOOL} is a list of names that are
8240 passed, one at a time, as the @option{--tool} argument to
8241 @command{runtest} invocations; it defaults to the name of the package.
8243 The variable @code{RUNTESTDEFAULTFLAGS} holds the @option{--tool} and
8244 @option{--srcdir} flags that are passed to dejagnu by default; this can be
8245 overridden if necessary.
8246 @vindex RUNTESTDEFAULTFLAGS
8248 The variables @code{EXPECT} and @code{RUNTEST} can
8249 also be overridden to provide project-specific values. For instance,
8250 you will need to do this if you are testing a compiler toolchain,
8251 because the default values do not take into account host and target
8258 The contents of the variable @code{RUNTESTFLAGS} are passed to the
8259 @code{runtest} invocation. This is considered a ``user variable''
8260 (@pxref{User Variables}). If you need to set @command{runtest} flags in
8261 @file{Makefile.am}, you can use @code{AM_RUNTESTFLAGS} instead.
8262 @vindex RUNTESTFLAGS
8263 @vindex AM_RUNTESTFLAGS
8265 @cindex @file{site.exp}
8266 Automake will generate rules to create a local @file{site.exp} file,
8267 defining various variables detected by @command{configure}. This file
8268 is automatically read by DejaGnu. It is OK for the user of a package
8269 to edit this file in order to tune the test suite. However this is
8270 not the place where the test suite author should define new variables:
8271 this should be done elsewhere in the real test suite code.
8272 Especially, @file{site.exp} should not be distributed.
8274 For more information regarding DejaGnu test suites, see @ref{Top, , ,
8275 dejagnu, The DejaGnu Manual}.
8277 In either case, the testing is done via @samp{make check}.
8279 @section Install Tests
8281 The @code{installcheck} target is available to the user as a way to
8282 run any tests after the package has been installed. You can add tests
8283 to this by writing an @code{installcheck-local} rule.
8287 @chapter Rebuilding Makefiles
8288 @cindex rebuild rules
8290 Automake generates rules to automatically rebuild @file{Makefile}s,
8291 @file{configure}, and other derived files like @file{Makefile.in}.
8293 @acindex AM_MAINTAINER_MODE
8294 If you are using @code{AM_MAINTAINER_MODE} in @file{configure.ac}, then
8295 these automatic rebuilding rules are only enabled in maintainer mode.
8297 @vindex ACLOCAL_AMFLAGS
8298 Sometimes you need to run @command{aclocal} with an argument like
8299 @option{-I} to tell it where to find @file{.m4} files. Since
8300 sometimes @command{make} will automatically run @command{aclocal}, you
8301 need a way to specify these arguments. You can do this by defining
8302 @code{ACLOCAL_AMFLAGS}; this holds arguments that are passed verbatim
8303 to @command{aclocal}. This variable is only useful in the top-level
8306 @vindex CONFIG_STATUS_DEPENDENCIES
8307 @vindex CONFIGURE_DEPENDENCIES
8308 @cindex @file{version.sh}, example
8309 @cindex @file{version.m4}, example
8311 Sometimes it is convenient to supplement the rebuild rules for
8312 @file{configure} or @file{config.status} with additional dependencies.
8313 The variables @code{CONFIGURE_DEPENDENCIES} and
8314 @code{CONFIG_STATUS_DEPENDENCIES} can be used to list these extra
8315 dependencies. These variable should be defined in all
8316 @file{Makefile}s of the tree (because these two rebuild rules are
8317 output in all them), so it is safer and easier to @code{AC_SUBST} them
8318 from @file{configure.ac}. For instance, the following statement will
8319 cause @file{configure} to be rerun each time @file{version.sh} is
8322 AC_SUBST([CONFIG_STATUS_DEPENDENCIES], ['$(top_srcdir)/version.sh'])
8325 Note the @samp{$(top_srcdir)/} in the file name. Since this variable
8326 is to be used in all @file{Makefile}s, its value must be sensible at
8327 any level in the build hierarchy.
8329 Beware not to mistake @code{CONFIGURE_DEPENDENCIES} for
8330 @code{CONFIG_STATUS_DEPENDENCIES}.
8332 @code{CONFIGURE_DEPENDENCIES} adds dependencies to the
8333 @file{configure} rule, whose effect is to run @command{autoconf}. This
8334 variable should be seldom used, because @command{automake} already tracks
8335 @code{m4_include}d files. However it can be useful when playing
8336 tricky games with @code{m4_esyscmd} or similar non-recommendable
8337 macros with side effects.
8339 @code{CONFIG_STATUS_DEPENDENCIES} adds dependencies to the
8340 @file{config.status} rule, whose effect is to run @file{configure}.
8341 This variable should therefore carry any non-standard source that may
8342 be read as a side effect of running configure, like @file{version.sh}
8343 in the example above.
8345 Speaking of @file{version.sh} scripts, we recommend against them
8346 today. They are mainly used when the version of a package is updated
8347 automatically by a script (e.g., in daily builds). Here is what some
8348 old-style @file{configure.ac}s may look like:
8351 . $srcdir/version.sh
8352 AM_INIT_AUTOMAKE([name], $VERSION_NUMBER)
8356 Here, @file{version.sh} is a shell fragment that sets
8357 @code{VERSION_NUMBER}. The problem with this example is that
8358 @command{automake} cannot track dependencies (listing @file{version.sh}
8359 in @command{CONFIG_STATUS_DEPENDENCIES}, and distributing this file is up
8360 to the user), and that it uses the obsolete form of @code{AC_INIT} and
8361 @code{AM_INIT_AUTOMAKE}. Upgrading to the new syntax is not
8362 straightforward, because shell variables are not allowed in
8363 @code{AC_INIT}'s arguments. We recommend that @file{version.sh} be
8364 replaced by an M4 file that is included by @file{configure.ac}:
8366 m4_include([version.m4])
8367 AC_INIT([name], VERSION_NUMBER)
8372 Here @file{version.m4} could contain something like
8373 @samp{m4_define([VERSION_NUMBER], [1.2])}. The advantage of this
8374 second form is that @command{automake} will take care of the
8375 dependencies when defining the rebuild rule, and will also distribute
8376 the file automatically. An inconvenience is that @command{autoconf}
8377 will now be rerun each time the version number is bumped, when only
8378 @file{configure} had to be rerun in the previous setup.
8382 @chapter Changing Automake's Behavior
8384 Various features of Automake can be controlled by options in the
8385 @file{Makefile.am}. Such options are applied on a per-@file{Makefile}
8386 basis when listed in a special @file{Makefile} variable named
8387 @code{AUTOMAKE_OPTIONS}. They are applied globally to all processed
8388 @file{Makefiles} when listed in the first argument of
8389 @code{AM_INIT_AUTOMAKE} in @file{configure.ac}. Currently understood
8391 @vindex AUTOMAKE_OPTIONS
8394 @item @option{gnits}
8396 @itemx @option{foreign}
8397 @itemx @option{cygnus}
8398 @cindex Option, @option{gnits}
8399 @cindex Option, @option{gnu}
8400 @cindex Option, @option{foreign}
8401 @cindex Option, @option{cygnus}
8407 Set the strictness as appropriate. The @option{gnits} option also
8408 implies options @option{readme-alpha} and @option{check-news}.
8410 @item @option{ansi2knr}
8411 @itemx @option{@var{path}/ansi2knr}
8412 @cindex Option, @option{ansi2knr}
8414 Turn on the obsolete de-ANSI-fication feature. @xref{ANSI}. If preceded by a
8415 path, the generated @file{Makefile.in} will look in the specified
8416 directory to find the @file{ansi2knr} program. The path should be a
8417 relative path to another directory in the same distribution (Automake
8418 currently does not check this).
8420 @item @option{check-news}
8421 @cindex Option, @option{check-news}
8423 Cause @samp{make dist} to fail unless the current version number appears
8424 in the first few lines of the @file{NEWS} file.
8426 @item @option{color-tests}
8427 @cindex Option, @option{color-tests}
8428 @opindex color-tests
8429 Cause output of the simple test suite (@pxref{Tests}) to be
8430 colorized on capable terminals.
8432 @item @option{dejagnu}
8433 @cindex Option, @option{dejagnu}
8435 Cause @command{dejagnu}-specific rules to be generated. @xref{Tests}.
8437 @item @option{dist-bzip2}
8438 @cindex Option, @option{dist-bzip2}
8440 Hook @code{dist-bzip2} to @code{dist}.
8443 @item @option{dist-lzma}
8444 @cindex Option, @option{dist-lzma}
8446 Hook @code{dist-lzma} to @code{dist}.
8449 @item @option{dist-shar}
8450 @cindex Option, @option{dist-shar}
8452 Hook @code{dist-shar} to @code{dist}.
8455 @item @option{dist-zip}
8456 @cindex Option, @option{dist-zip}
8458 Hook @code{dist-zip} to @code{dist}.
8461 @item @option{dist-tarZ}
8462 @cindex Option, @option{dist-tarZ}
8464 Hook @code{dist-tarZ} to @code{dist}.
8467 @item @option{filename-length-max=99}
8468 @cindex Option, @option{filename-length-max=99}
8469 @opindex filename-length-max=99
8470 Abort if file names longer than 99 characters are found during
8471 @samp{make dist}. Such long file names are generally considered not to
8472 be portable in tarballs. See the @option{tar-v7} and @option{tar-ustar}
8473 options below. This option should be used in the top-level
8474 @file{Makefile.am} or as an argument of @code{AM_INIT_AUTOMAKE} in
8475 @file{configure.ac}, it will be ignored otherwise. It will also be
8476 ignored in sub-packages of nested packages (@pxref{Subpackages}).
8478 @item @option{no-define}
8479 @cindex Option, @option{no-define}
8481 This options is meaningful only when passed as an argument to
8482 @code{AM_INIT_AUTOMAKE}. It will prevent the @code{PACKAGE} and
8483 @code{VERSION} variables to be @code{AC_DEFINE}d.
8485 @item @option{no-dependencies}
8486 @cindex Option, @option{no-dependencies}
8487 @opindex no-dependencies
8488 This is similar to using @option{--ignore-deps} on the command line,
8489 but is useful for those situations where you don't have the necessary
8490 bits to make automatic dependency tracking work
8491 (@pxref{Dependencies}). In this case the effect is to effectively
8492 disable automatic dependency tracking.
8494 @item @option{no-dist}
8495 @cindex Option, @option{no-dist}
8497 Don't emit any code related to @code{dist} target. This is useful
8498 when a package has its own method for making distributions.
8500 @item @option{no-dist-gzip}
8501 @cindex Option, @option{no-dist-gzip}
8502 @opindex no-dist-gzip
8503 Do not hook @code{dist-gzip} to @code{dist}.
8504 @trindex no-dist-gzip
8506 @item @option{no-exeext}
8507 @cindex Option, @option{no-exeext}
8509 If your @file{Makefile.am} defines a rule for target @code{foo}, it
8510 will override a rule for a target named @samp{foo$(EXEEXT)}. This is
8511 necessary when @code{EXEEXT} is found to be empty. However, by
8512 default automake will generate an error for this use. The
8513 @option{no-exeext} option will disable this error. This is intended for
8514 use only where it is known in advance that the package will not be
8515 ported to Windows, or any other operating system using extensions on
8518 @item @option{no-installinfo}
8519 @cindex Option, @option{no-installinfo}
8520 @opindex no-installinfo
8521 The generated @file{Makefile.in} will not cause info pages to be built
8522 or installed by default. However, @code{info} and @code{install-info}
8523 targets will still be available. This option is disallowed at
8524 @option{gnu} strictness and above.
8526 @trindex install-info
8528 @item @option{no-installman}
8529 @cindex Option, @option{no-installman}
8530 @opindex no-installman
8531 The generated @file{Makefile.in} will not cause man pages to be
8532 installed by default. However, an @code{install-man} target will still
8533 be available for optional installation. This option is disallowed at
8534 @option{gnu} strictness and above.
8535 @trindex install-man
8537 @item @option{nostdinc}
8538 @cindex Option, @option{nostdinc}
8540 This option can be used to disable the standard @option{-I} options that
8541 are ordinarily automatically provided by Automake.
8543 @item @option{no-texinfo.tex}
8544 @cindex Option, @option{no-texinfo.tex}
8545 @opindex no-texinfo.tex
8546 Don't require @file{texinfo.tex}, even if there are texinfo files in
8549 @item @option{readme-alpha}
8550 @cindex Option, @option{readme-alpha}
8551 @opindex readme-alpha
8552 If this release is an alpha release, and the file @file{README-alpha}
8553 exists, then it will be added to the distribution. If this option is
8554 given, version numbers are expected to follow one of two forms. The
8555 first form is @samp{@var{MAJOR}.@var{MINOR}.@var{ALPHA}}, where each
8556 element is a number; the final period and number should be left off for
8557 non-alpha releases. The second form is
8558 @samp{@var{MAJOR}.@var{MINOR}@var{ALPHA}}, where @var{ALPHA} is a
8559 letter; it should be omitted for non-alpha releases.
8561 @item @option{std-options}
8562 @cindex Options, @option{std-options}
8563 @cindex @samp{make installcheck}, testing @option{--help} and @option{--version}
8564 @cindex @option{--help} check
8565 @cindex @option{--version} check
8566 @opindex std-options
8568 Make the @code{installcheck} rule check that installed scripts and
8569 programs support the @option{--help} and @option{--version} options.
8570 This also provides a basic check that the program's
8571 run-time dependencies are satisfied after installation.
8573 @vindex AM_INSTALLCHECK_STD_OPTIONS_EXEMPT
8574 In a few situations, programs (or scripts) have to be exempted from this
8575 test. For instance, @command{false} (from GNU sh-utils) is never
8576 successful, even for @option{--help} or @option{--version}. You can list
8577 such programs in the variable @code{AM_INSTALLCHECK_STD_OPTIONS_EXEMPT}.
8578 Programs (not scripts) listed in this variable should be suffixed by
8579 @samp{$(EXEEXT)} for the sake of Win32 or OS/2. For instance, suppose we
8580 build @file{false} as a program but @file{true.sh} as a script, and that
8581 neither of them support @option{--help} or @option{--version}:
8584 AUTOMAKE_OPTIONS = std-options
8585 bin_PROGRAMS = false ...
8586 bin_SCRIPTS = true.sh ...
8587 AM_INSTALLCHECK_STD_OPTIONS_EXEMPT = false$(EXEEXT) true.sh
8590 @item @option{subdir-objects}
8591 @cindex Options, @option{subdir-objects}
8592 @opindex subdir-objects
8593 If this option is specified, then objects are placed into the
8594 subdirectory of the build directory corresponding to the subdirectory of
8595 the source file. For instance, if the source file is
8596 @file{subdir/file.cxx}, then the output file would be
8597 @file{subdir/file.o}.
8599 In order to use this option with C sources, you should add
8600 @code{AM_PROG_CC_C_O} to @file{configure.ac}.
8602 @anchor{tar-formats}
8603 @item @option{tar-v7}
8604 @itemx @option{tar-ustar}
8605 @itemx @option{tar-pax}
8606 @cindex Option, @option{tar-v7}
8607 @cindex Option, @option{tar-ustar}
8608 @cindex Option, @option{tar-pax}
8609 @cindex @command{tar} formats
8610 @cindex v7 @command{tar} format
8611 @cindex ustar format
8617 These three mutually exclusive options select the tar format to use
8618 when generating tarballs with @samp{make dist}. (The tar file created
8619 is then compressed according to the set of @option{no-dist-gzip},
8620 @option{dist-bzip2}, @option{dist-lzma} and @option{dist-tarZ} options in use.)
8622 These options must be passed as argument to @code{AM_INIT_AUTOMAKE}
8623 (@pxref{Macros}) because they can require additional configure checks.
8624 Automake will complain if it sees such options in an
8625 @code{AUTOMAKE_OPTIONS} variable.
8627 @option{tar-v7} selects the old V7 tar format. This is the historical
8628 default. This antiquated format is understood by all tar
8629 implementations and supports file names with up to 99 characters. When
8630 given longer file names some tar implementations will diagnose the
8631 problem while other will generate broken tarballs or use non-portable
8632 extensions. Furthermore, the V7 format cannot store empty
8633 directories. When using this format, consider using the
8634 @option{filename-length-max=99} option to catch file names too long.
8636 @option{tar-ustar} selects the ustar format defined by POSIX
8637 1003.1-1988. This format is believed to be old enough to be portable.
8638 It fully supports empty directories. It can store file names with up
8639 to 256 characters, provided that the file name can be split at
8640 directory separator in two parts, first of them being at most 155
8641 bytes long. So, in most cases the maximum file name length will be
8642 shorter than 256 characters. However you may run against broken tar
8643 implementations that incorrectly handle file names longer than 99
8644 characters (please report them to @email{bug-automake@@gnu.org} so we
8645 can document this accurately).
8647 @option{tar-pax} selects the new pax interchange format defined by POSIX
8648 1003.1-2001. It does not limit the length of file names. However,
8649 this format is very young and should probably be restricted to
8650 packages that target only very modern platforms. There are moves to
8651 change the pax format in an upward-compatible way, so this option may
8652 refer to a more recent version in the future.
8654 @xref{Formats, , Controlling the Archive Format, tar, GNU Tar}, for
8655 further discussion about tar formats.
8657 @command{configure} knows several ways to construct these formats. It
8658 will not abort if it cannot find a tool up to the task (so that the
8659 package can still be built), but @samp{make dist} will fail.
8662 @cindex Option, @var{version}
8663 A version number (e.g., @samp{0.30}) can be specified. If Automake is not
8664 newer than the version specified, creation of the @file{Makefile.in}
8667 @item @option{-W@var{category}} or @option{--warnings=@var{category}}
8668 @cindex Option, warnings
8669 @cindex Option, @option{-W@var{category}}
8670 @cindex Option, @option{--warnings=@var{category}}
8671 These options behave exactly like their command-line counterpart
8672 (@pxref{Invoking Automake}). This allows you to enable or disable some
8673 warning categories on a per-file basis. You can also setup some warnings
8674 for your entire project; for instance, try @samp{AM_INIT_AUTOMAKE([-Wall])}
8675 in your @file{configure.ac}.
8679 Unrecognized options are diagnosed by @command{automake}.
8681 If you want an option to apply to all the files in the tree, you can use
8682 the @code{AM_INIT_AUTOMAKE} macro in @file{configure.ac}.
8687 @chapter Miscellaneous Rules
8689 There are a few rules and variables that didn't fit anywhere else.
8692 * Tags:: Interfacing to etags and mkid
8693 * Suffixes:: Handling new file extensions
8694 * Multilibs:: Support for multilibs.
8699 @section Interfacing to @command{etags}
8701 @cindex @file{TAGS} support
8703 Automake will generate rules to generate @file{TAGS} files for use with
8704 GNU Emacs under some circumstances.
8707 If any C, C++ or Fortran 77 source code or headers are present, then
8708 @code{tags} and @code{TAGS} rules will be generated for the directory.
8709 All files listed using the @code{_SOURCES}, @code{_HEADERS}, and
8710 @code{_LISP} primaries will be used to generate tags. Note that
8711 generated source files that are not distributed must be declared in
8712 variables like @code{nodist_noinst_HEADERS} or
8713 @code{nodist_@var{prog}_SOURCES} or they will be ignored.
8715 A @code{tags} rule will be output at the topmost directory of a
8716 multi-directory package. When run from this topmost directory,
8717 @samp{make tags} will generate a @file{TAGS} file that includes by
8718 reference all @file{TAGS} files from subdirectories.
8720 The @code{tags} rule will also be generated if the variable
8721 @code{ETAGS_ARGS} is defined. This variable is intended for use in
8722 directories that contain taggable source that @command{etags} does
8723 not understand. The user can use the @code{ETAGSFLAGS} to pass
8724 additional flags to @command{etags}; @code{AM_ETAGSFLAGS} is also
8725 available for use in @file{Makefile.am}.
8728 @vindex AM_ETAGSFLAGS
8730 Here is how Automake generates tags for its source, and for nodes in its
8734 ETAGS_ARGS = automake.in --lang=none \
8735 --regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi
8738 If you add file names to @code{ETAGS_ARGS}, you will probably also
8739 want to define @code{TAGS_DEPENDENCIES}. The contents of this variable
8740 are added directly to the dependencies for the @code{tags} rule.
8741 @vindex TAGS_DEPENDENCIES
8743 Automake also generates a @code{ctags} rule that can be used to
8744 build @command{vi}-style @file{tags} files. The variable @code{CTAGS}
8745 is the name of the program to invoke (by default @command{ctags});
8746 @code{CTAGSFLAGS} can be used by the user to pass additional flags,
8747 and @code{AM_CTAGSFLAGS} can be used by the @file{Makefile.am}.
8749 Automake will also generate an @code{ID} rule that will run
8750 @command{mkid} on the source. This is only supported on a
8751 directory-by-directory basis.
8754 Finally, Automake also emit rules to support the
8755 @uref{http://www.gnu.org/software/global/, GNU Global Tags program}.
8756 The @code{GTAGS} rule runs Global Tags and puts the
8757 result in the top build directory. The variable @code{GTAGS_ARGS}
8758 holds arguments that are passed to @command{gtags}.
8763 @section Handling new file extensions
8765 @cindex Adding new @code{SUFFIXES}
8766 @cindex @code{SUFFIXES}, adding
8769 It is sometimes useful to introduce a new implicit rule to handle a file
8770 type that Automake does not know about.
8772 For instance, suppose you had a compiler that could compile @file{.foo}
8773 files to @file{.o} files. You would simply define an suffix rule for
8781 Then you could directly use a @file{.foo} file in a @code{_SOURCES}
8782 variable and expect the correct results:
8786 doit_SOURCES = doit.foo
8789 This was the simpler and more common case. In other cases, you will
8790 have to help Automake to figure which extensions you are defining your
8791 suffix rule for. This usually happens when your extensions does not
8792 start with a dot. Then, all you have to do is to put a list of new
8793 suffixes in the @code{SUFFIXES} variable @strong{before} you define your
8796 For instance, the following definition prevents Automake to misinterpret
8797 @samp{.idlC.cpp:} as an attempt to transform @file{.idlC} files into
8801 SUFFIXES = .idl C.cpp
8806 As you may have noted, the @code{SUFFIXES} variable behaves like the
8807 @code{.SUFFIXES} special target of @command{make}. You should not touch
8808 @code{.SUFFIXES} yourself, but use @code{SUFFIXES} instead and let
8809 Automake generate the suffix list for @code{.SUFFIXES}. Any given
8810 @code{SUFFIXES} go at the start of the generated suffixes list, followed
8811 by Automake generated suffixes not already in the list.
8814 @section Support for Multilibs
8816 Automake has support for an obscure feature called multilibs. A
8817 @dfn{multilib} is a library that is built for multiple different ABIs
8818 at a single time; each time the library is built with a different target
8819 flag combination. This is only useful when the library is intended to
8820 be cross-compiled, and it is almost exclusively used for compiler
8823 The multilib support is still experimental. Only use it if you are
8824 familiar with multilibs and can debug problems you might encounter.
8831 @cindex Including @file{Makefile} fragment
8832 @cindex @file{Makefile} fragment, including
8834 Automake supports an @code{include} directive that can be used to
8835 include other @file{Makefile} fragments when @command{automake} is run.
8836 Note that these fragments are read and interpreted by @command{automake},
8837 not by @command{make}. As with conditionals, @command{make} has no idea that
8838 @code{include} is in use.
8840 There are two forms of @code{include}:
8843 @item include $(srcdir)/file
8844 Include a fragment that is found relative to the current source
8847 @item include $(top_srcdir)/file
8848 Include a fragment that is found relative to the top source directory.
8851 Note that if a fragment is included inside a conditional, then the
8852 condition applies to the entire contents of that fragment.
8854 Makefile fragments included this way are always distributed because
8855 they are needed to rebuild @file{Makefile.in}.
8858 @chapter Conditionals
8860 @cindex Conditionals
8862 Automake supports a simple type of conditionals.
8864 @unnumberedsec Usage
8866 @acindex AM_CONDITIONAL
8867 Before using a conditional, you must define it by using
8868 @code{AM_CONDITIONAL} in the @file{configure.ac} file (@pxref{Macros}).
8870 @defmac AM_CONDITIONAL (@var{conditional}, @var{condition})
8871 The conditional name, @var{conditional}, should be a simple string
8872 starting with a letter and containing only letters, digits, and
8873 underscores. It must be different from @samp{TRUE} and @samp{FALSE}
8874 that are reserved by Automake.
8876 The shell @var{condition} (suitable for use in a shell @code{if}
8877 statement) is evaluated when @command{configure} is run. Note that you
8878 must arrange for @emph{every} @code{AM_CONDITIONAL} to be invoked every
8879 time @command{configure} is run. If @code{AM_CONDITIONAL} is run
8880 conditionally (e.g., in a shell @code{if} statement), then the result
8881 will confuse automake.
8884 @cindex @option{--enable-debug}, example
8885 @cindex Example conditional @option{--enable-debug}
8886 @cindex Conditional example, @option{--enable-debug}
8888 Conditionals typically depend upon options that the user provides to
8889 the @command{configure} script. Here is an example of how to write a
8890 conditional that is true if the user uses the @option{--enable-debug}
8894 AC_ARG_ENABLE([debug],
8895 [ --enable-debug Turn on debugging],
8896 [case "$@{enableval@}" in
8899 *) AC_MSG_ERROR([bad value $@{enableval@} for --enable-debug]) ;;
8900 esac],[debug=false])
8901 AM_CONDITIONAL([DEBUG], [test x$debug = xtrue])
8904 Here is an example of how to use that conditional in @file{Makefile.am}:
8916 noinst_PROGRAMS = $(DBG)
8919 This trivial example could also be handled using @code{EXTRA_PROGRAMS}
8920 (@pxref{Conditional Programs}).
8922 You may only test a single variable in an @code{if} statement, possibly
8923 negated using @samp{!}. The @code{else} statement may be omitted.
8924 Conditionals may be nested to any depth. You may specify an argument to
8925 @code{else} in which case it must be the negation of the condition used
8926 for the current @code{if}. Similarly you may specify the condition
8927 that is closed by an @code{end}:
8938 Unbalanced conditions are errors.
8940 The @code{else} branch of the above two examples could be omitted,
8941 since assigning the empty string to an otherwise undefined variable
8942 makes no difference.
8944 @unnumberedsec Portability
8946 Note that conditionals in Automake are not the same as conditionals in
8947 GNU Make. Automake conditionals are checked at configure time by the
8948 @file{configure} script, and affect the translation from
8949 @file{Makefile.in} to @file{Makefile}. They are based on options passed
8950 to @file{configure} and on results that @file{configure} has discovered
8951 about the host system. GNU Make conditionals are checked at @command{make}
8952 time, and are based on variables passed to the make program or defined
8953 in the @file{Makefile}.
8955 Automake conditionals will work with any make program.
8957 @unnumberedsec Limits
8959 Conditionals should enclose complete statements like variables or
8960 rules definitions. Automake cannot deal with conditionals used inside
8961 a variable definition, for instance, and is not even able to diagnose
8962 this situation. The following example would not work:
8965 # This syntax is not understood by Automake
8974 However the intended definition of @code{AM_CPPFLAGS} can be achieved
8979 DEBUGFLAGS = -DDEBUG
8981 AM_CPPFLAGS = -DFEATURE_A $(DEBUGFLAGS) -DFEATURE_B
8987 AM_CPPFLAGS = -DFEATURE_A
8989 AM_CPPFLAGS += -DDEBUG
8991 AM_CPPFLAGS += -DFEATURE_B
8995 @chapter The effect of @option{--gnu} and @option{--gnits}
8997 @cindex @option{--gnu}, required files
8998 @cindex @option{--gnu}, complete description
9000 The @option{--gnu} option (or @option{gnu} in the
9001 @code{AUTOMAKE_OPTIONS} variable) causes @command{automake} to check
9006 The files @file{INSTALL}, @file{NEWS}, @file{README}, @file{AUTHORS},
9007 and @file{ChangeLog}, plus one of @file{COPYING.LIB}, @file{COPYING.LESSER}
9008 or @file{COPYING}, are required at the topmost directory of the package.
9011 The options @option{no-installman} and @option{no-installinfo} are
9015 Note that this option will be extended in the future to do even more
9016 checking; it is advisable to be familiar with the precise requirements
9017 of the GNU standards. Also, @option{--gnu} can require certain
9018 non-standard GNU programs to exist for use by various maintainer-only
9019 rules; for instance, in the future @command{pathchk} might be required for
9022 @cindex @option{--gnits}, complete description
9024 The @option{--gnits} option does everything that @option{--gnu} does, and
9025 checks the following as well:
9029 @samp{make installcheck} will check to make sure that the @option{--help}
9030 and @option{--version} really print a usage message and a version string,
9031 respectively. This is the @option{std-options} option (@pxref{Options}).
9034 @samp{make dist} will check to make sure the @file{NEWS} file has been
9035 updated to the current version.
9038 @code{VERSION} is checked to make sure its format complies with Gnits
9040 @c FIXME xref when standards are finished
9043 @cindex @file{README-alpha}
9044 If @code{VERSION} indicates that this is an alpha release, and the file
9045 @file{README-alpha} appears in the topmost directory of a package, then
9046 it is included in the distribution. This is done in @option{--gnits}
9047 mode, and no other, because this mode is the only one where version
9048 number formats are constrained, and hence the only mode where Automake
9049 can automatically determine whether @file{README-alpha} should be
9053 The file @file{THANKS} is required.
9058 @chapter The effect of @option{--cygnus}
9060 @cindex @option{cygnus} strictness
9062 Some packages, notably GNU GCC and GNU gdb, have a build environment
9063 originally written at Cygnus Support (subsequently renamed Cygnus
9064 Solutions, and then later purchased by Red Hat). Packages with this
9065 ancestry are sometimes referred to as ``Cygnus'' trees.
9067 A Cygnus tree has slightly different rules for how a
9068 @file{Makefile.in} is to be constructed. Passing @option{--cygnus} to
9069 @command{automake} will cause any generated @file{Makefile.in} to
9070 comply with Cygnus rules.
9072 Here are the precise effects of @option{--cygnus}:
9076 Info files are always created in the build directory, and not in the
9080 @file{texinfo.tex} is not required if a Texinfo source file is
9081 specified. The assumption is that the file will be supplied, but in a
9082 place that Automake cannot find. This assumption is an artifact of how
9083 Cygnus packages are typically bundled.
9086 @samp{make dist} is not supported, and the rules for it are not
9087 generated. Cygnus-style trees use their own distribution mechanism.
9090 Certain tools will be searched for in the build tree as well as in the
9091 user's @env{PATH}. These tools are @command{runtest}, @command{expect},
9092 @command{makeinfo} and @command{texi2dvi}.
9095 @option{--foreign} is implied.
9098 The options @option{no-installinfo} and @option{no-dependencies} are
9102 The macros @code{AM_MAINTAINER_MODE} and @code{AM_CYGWIN32} are
9106 The @code{check} target doesn't depend on @code{all}.
9109 GNU maintainers are advised to use @option{gnu} strictness in preference
9110 to the special Cygnus mode. Some day, perhaps, the differences between
9111 Cygnus trees and GNU trees will disappear (for instance, as GCC is made
9112 more standards compliant). At that time the special Cygnus mode will be
9117 @chapter When Automake Isn't Enough
9119 In some situations, where Automake is not up to one task, one has to
9120 resort to handwritten rules or even handwritten @file{Makefile}s.
9123 * Extending:: Adding new rules or overriding existing ones.
9124 * Third-Party Makefiles:: Integrating Non-Automake @file{Makefile}s.
9128 @section Extending Automake Rules
9130 With some minor exceptions (for example @code{_PROGRAMS} variables,
9131 @code{TESTS}, or @code{XFAIL_TESTS}) being rewritten to append
9132 @samp{$(EXEEXT)}), the contents of a @file{Makefile.am} is copied to
9133 @file{Makefile.in} verbatim.
9135 @cindex copying semantics
9137 These copying semantics means that many problems can be worked around
9138 by simply adding some @command{make} variables and rules to
9139 @file{Makefile.am}. Automake will ignore these additions.
9141 @cindex conflicting definitions
9142 @cindex rules, conflicting
9143 @cindex variables, conflicting
9144 @cindex definitions, conflicts
9146 Since a @file{Makefile.in} is built from data gathered from three
9147 different places (@file{Makefile.am}, @file{configure.ac}, and
9148 @command{automake} itself), it is possible to have conflicting
9149 definitions of rules or variables. When building @file{Makefile.in}
9150 the following priorities are respected by @command{automake} to ensure
9151 the user always have the last word. User defined variables in
9152 @file{Makefile.am} have priority over variables @code{AC_SUBST}ed from
9153 @file{configure.ac}, and @code{AC_SUBST}ed variables have priority
9154 over @command{automake}-defined variables. As far rules are
9155 concerned, a user-defined rule overrides any
9156 @command{automake}-defined rule for the same target.
9158 @cindex overriding rules
9159 @cindex overriding semantics
9160 @cindex rules, overriding
9162 These overriding semantics make it possible to fine tune some default
9163 settings of Automake, or replace some of its rules. Overriding
9164 Automake rules is often inadvisable, particularly in the topmost
9165 directory of a package with subdirectories. The @option{-Woverride}
9166 option (@pxref{Invoking Automake}) comes handy to catch overridden
9169 Note that Automake does not make any difference between rules with
9170 commands and rules that only specify dependencies. So it is not
9171 possible to append new dependencies to an @command{automake}-defined
9172 target without redefining the entire rule.
9174 @cindex @option{-local} targets
9175 @cindex local targets
9177 However, various useful targets have a @samp{-local} version you can
9178 specify in your @file{Makefile.am}. Automake will supplement the
9179 standard target with these user-supplied targets.
9194 @trindex check-local
9196 @trindex install-data
9197 @trindex install-data-local
9198 @trindex install-dvi
9199 @trindex install-dvi-local
9200 @trindex install-exec
9201 @trindex install-exec-local
9202 @trindex install-html
9203 @trindex install-html-local
9204 @trindex install-info
9205 @trindex install-info-local
9206 @trindex install-pdf
9207 @trindex install-pdf-local
9209 @trindex install-ps-local
9211 @trindex uninstall-local
9212 @trindex mostlyclean
9213 @trindex mostlyclean-local
9215 @trindex clean-local
9217 @trindex distclean-local
9218 @trindex installdirs
9219 @trindex installdirs-local
9220 @trindex installcheck
9221 @trindex installcheck-local
9223 The targets that support a local version are @code{all}, @code{info},
9224 @code{dvi}, @code{ps}, @code{pdf}, @code{html}, @code{check},
9225 @code{install-data}, @code{install-dvi}, @code{install-exec},
9226 @code{install-html}, @code{install-info}, @code{install-pdf},
9227 @code{install-ps}, @code{uninstall}, @code{installdirs},
9228 @code{installcheck} and the various @code{clean} targets
9229 (@code{mostlyclean}, @code{clean}, @code{distclean}, and
9230 @code{maintainer-clean}).
9232 Note that there are no @code{uninstall-exec-local} or
9233 @code{uninstall-data-local} targets; just use @code{uninstall-local}.
9234 It doesn't make sense to uninstall just data or just executables.
9236 For instance, here is one way to erase a subdirectory during
9237 @samp{make clean} (@pxref{Clean}).
9244 Older version of this manual used to show how to use
9245 @code{install-data-local} to install a file to some hard-coded
9246 location, but you should avoid this. (@pxref{Hard-Coded Install Paths})
9248 @cindex @option{-hook} targets
9249 @cindex hook targets
9251 Some rule also have a way to run another rule, called a @dfn{hook},
9252 after their work is done. The hook is named after the principal target,
9253 with @samp{-hook} appended. The targets allowing hooks are
9254 @code{install-data}, @code{install-exec}, @code{uninstall}, @code{dist},
9255 and @code{distcheck}.
9256 @trindex install-data-hook
9257 @trindex install-exec-hook
9258 @trindex uninstall-hook
9261 For instance, here is how to create a hard link to an installed program:
9265 ln $(DESTDIR)$(bindir)/program$(EXEEXT) \
9266 $(DESTDIR)$(bindir)/proglink$(EXEEXT)
9269 Although cheaper and more portable than symbolic links, hard links
9270 will not work everywhere (for instance, OS/2 does not have
9271 @command{ln}). Ideally you should fall back to @samp{cp -p} when
9272 @command{ln} does not work. An easy way, if symbolic links are
9273 acceptable to you, is to add @code{AC_PROG_LN_S} to
9274 @file{configure.ac} (@pxref{Particular Programs, , Particular Program
9275 Checks, autoconf, The Autoconf Manual}) and use @samp{$(LN_S)} in
9278 @cindex versioned binaries, installing
9279 @cindex installing versioned binaries
9280 @cindex @code{LN_S} example
9281 For instance, here is how you could install a versioned copy of a
9282 program using @samp{$(LN_S)}:
9286 cd $(DESTDIR)$(bindir) && \
9287 mv -f prog$(EXEEXT) prog-$(VERSION)$(EXEEXT) && \
9288 $(LN_S) prog-$(VERSION)$(EXEEXT) prog$(EXEEXT)
9291 Note that we rename the program so that a new version will erase the
9292 symbolic link, not the real binary. Also we @command{cd} into the
9293 destination directory in order to create relative links.
9295 When writing @code{install-exec-hook} or @code{install-data-hook},
9296 please bear in mind that the exec/data distinction is based on the
9297 installation directory, not on the primary used (@pxref{Install}). So
9298 a @code{foo_SCRIPTS} will be installed by @code{install-data}, and a
9299 @code{barexec_SCRIPTS} will be installed by @code{install-exec}. You
9300 should define your hooks consequently.
9302 @c FIXME should include discussion of variables you can use in these
9305 @node Third-Party Makefiles
9306 @section Third-Party @file{Makefile}s
9308 @cindex Third-party packages, interfacing with
9309 @cindex Interfacing with third-party packages
9311 In most projects all @file{Makefile}s are generated by Automake. In
9312 some cases, however, projects need to embed subdirectories with
9313 handwritten @file{Makefile}s. For instance, one subdirectory could be
9314 a third-party project with its own build system, not using Automake.
9316 It is possible to list arbitrary directories in @code{SUBDIRS} or
9317 @code{DIST_SUBDIRS} provided each of these directories has a
9318 @file{Makefile} that recognizes all the following recursive targets.
9320 @cindex recursive targets and third-party @file{Makefile}s
9321 When a user runs one of these targets, that target is run recursively
9322 in all subdirectories. This is why it is important that even
9323 third-party @file{Makefile}s support them.
9327 Compile the entire package. This is the default target in
9328 Automake-generated @file{Makefile}s, but it does not need to be the
9329 default in third-party @file{Makefile}s.
9335 Copy files to distribute into @samp{$(distdir)}, before a tarball is
9336 constructed. Of course this target is not required if the
9337 @option{no-dist} option (@pxref{Options}) is used.
9339 The variables @samp{$(top_distdir)} and @samp{$(distdir)}
9340 (@pxref{Dist}) will be passed from the outer package to the subpackage
9341 when the @code{distdir} target is invoked. These two variables have
9342 been adjusted for the directory that is being recursed into, so they
9349 Install or uninstall files (@pxref{Install}).
9356 Install only some specific documentation format (@pxref{Texinfo}).
9359 Create install directories, but do not install any files.
9363 Check the package (@pxref{Tests}).
9368 @itemx maintainer-clean
9369 Cleaning rules (@pxref{Clean}).
9376 Build the documentation in various formats (@pxref{Texinfo}).
9380 Build @file{TAGS} and @file{CTAGS} (@pxref{Tags}).
9383 If you have ever used Gettext in a project, this is a good example of
9384 how third-party @file{Makefile}s can be used with Automake. The
9385 @file{Makefile}s @command{gettextize} puts in the @file{po/} and
9386 @file{intl/} directories are handwritten @file{Makefile}s that
9387 implement all these targets. That way they can be added to
9388 @code{SUBDIRS} in Automake packages.
9390 Directories that are only listed in @code{DIST_SUBDIRS} but not in
9391 @code{SUBDIRS} need only the @code{distclean},
9392 @code{maintainer-clean}, and @code{distdir} rules (@pxref{Conditional
9395 Usually, many of these rules are irrelevant to the third-party
9396 subproject, but they are required for the whole package to work. It's
9397 OK to have a rule that does nothing, so if you are integrating a
9398 third-party project with no documentation or tag support, you could
9399 simply augment its @file{Makefile} as follows:
9402 EMPTY_AUTOMAKE_TARGETS = dvi pdf ps info html tags ctags
9403 .PHONY: $(EMPTY_AUTOMAKE_TARGETS)
9404 $(EMPTY_AUTOMAKE_TARGETS):
9407 Another aspect of integrating third-party build systems is whether
9408 they support VPATH builds (@pxref{VPATH Builds}). Obviously if the
9409 subpackage does not support VPATH builds the whole package will not
9410 support VPATH builds. This in turns means that @samp{make distcheck}
9411 will not work, because it relies on VPATH builds. Some people can
9412 live without this (actually, many Automake users have never heard of
9413 @samp{make distcheck}). Other people may prefer to revamp the
9414 existing @file{Makefile}s to support VPATH@. Doing so does not
9415 necessarily require Automake, only Autoconf is needed (@pxref{Build
9416 Directories, , Build Directories, autoconf, The Autoconf Manual}).
9417 The necessary substitutions: @samp{@@srcdir@@}, @samp{@@top_srcdir@@},
9418 and @samp{@@top_builddir@@} are defined by @file{configure} when it
9419 processes a @file{Makefile} (@pxref{Preset Output Variables, , Preset
9420 Output Variables, autoconf, The Autoconf Manual}), they are not
9421 computed by the Makefile like the aforementioned @samp{$(distdir)} and
9422 @samp{$(top_distdir)} variables..
9424 It is sometimes inconvenient to modify a third-party @file{Makefile}
9425 to introduce the above required targets. For instance, one may want to
9426 keep the third-party sources untouched to ease upgrades to new
9429 @cindex @file{GNUmakefile} including @file{Makefile}
9430 Here are two other ideas. If GNU make is assumed, one possibility is
9431 to add to that subdirectory a @file{GNUmakefile} that defines the
9432 required targets and include the third-party @file{Makefile}. For
9433 this to work in VPATH builds, @file{GNUmakefile} must lie in the build
9434 directory; the easiest way to do this is to write a
9435 @file{GNUmakefile.in} instead, and have it processed with
9436 @code{AC_CONFIG_FILES} from the outer package. For example if we
9437 assume @file{Makefile} defines all targets except the documentation
9438 targets, and that the @code{check} target is actually called
9439 @code{test}, we could write @file{GNUmakefile} (or
9440 @file{GNUmakefile.in}) like this:
9443 # First, include the real Makefile
9445 # Then, define the other targets needed by Automake Makefiles.
9446 .PHONY: dvi pdf ps info html check
9447 dvi pdf ps info html:
9451 @cindex Proxy @file{Makefile} for third-party packages
9452 A similar idea that does not use @code{include} is to write a proxy
9453 @file{Makefile} that dispatches rules to the real @file{Makefile},
9454 either with @samp{$(MAKE) -f Makefile.real $(AM_MAKEFLAGS) target} (if
9455 it's OK to rename the original @file{Makefile}) or with @samp{cd
9456 subdir && $(MAKE) $(AM_MAKEFLAGS) target} (if it's OK to store the
9457 subdirectory project one directory deeper). The good news is that
9458 this proxy @file{Makefile} can be generated with Automake. All we
9459 need are @option{-local} targets (@pxref{Extending}) that perform the
9460 dispatch. Of course the other Automake features are available, so you
9461 could decide to let Automake perform distribution or installation.
9462 Here is a possible @file{Makefile.am}:
9466 cd subdir && $(MAKE) $(AM_MAKEFLAGS) all
9468 cd subdir && $(MAKE) $(AM_MAKEFLAGS) test
9470 cd subdir && $(MAKE) $(AM_MAKEFLAGS) clean
9472 # Assuming the package knows how to install itself
9474 cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-data
9476 cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-exec
9478 cd subdir && $(MAKE) $(AM_MAKEFLAGS) uninstall
9480 # Distribute files from here.
9481 EXTRA_DIST = subdir/Makefile subdir/program.c ...
9484 Pushing this idea to the extreme, it is also possible to ignore the
9485 subproject build system and build everything from this proxy
9486 @file{Makefile.am}. This might sounds very sensible if you need VPATH
9487 builds but the subproject does not support them.
9490 @chapter Distributing @file{Makefile.in}s
9492 Automake places no restrictions on the distribution of the resulting
9493 @file{Makefile.in}s. We still encourage software authors to
9494 distribute their work under terms like those of the GPL, but doing so
9495 is not required to use Automake.
9497 Some of the files that can be automatically installed via the
9498 @option{--add-missing} switch do fall under the GPL@. However, these also
9499 have a special exception allowing you to distribute them with your
9500 package, regardless of the licensing you choose.
9503 @node API versioning
9504 @chapter Automake API versioning
9506 New Automake releases usually include bug fixes and new features.
9507 Unfortunately they may also introduce new bugs and incompatibilities.
9508 This makes four reasons why a package may require a particular Automake
9511 Things get worse when maintaining a large tree of packages, each one
9512 requiring a different version of Automake. In the past, this meant that
9513 any developer (and sometime users) had to install several versions of
9514 Automake in different places, and switch @samp{$PATH} appropriately for
9517 Starting with version 1.6, Automake installs versioned binaries. This
9518 means you can install several versions of Automake in the same
9519 @samp{$prefix}, and can select an arbitrary Automake version by running
9520 @command{automake-1.6} or @command{automake-1.7} without juggling with
9521 @samp{$PATH}. Furthermore, @file{Makefile}'s generated by Automake 1.6
9522 will use @command{automake-1.6} explicitly in their rebuild rules.
9524 The number @samp{1.6} in @command{automake-1.6} is Automake's API version,
9525 not Automake's version. If a bug fix release is made, for instance
9526 Automake 1.6.1, the API version will remain 1.6. This means that a
9527 package that works with Automake 1.6 should also work with 1.6.1; after
9528 all, this is what people expect from bug fix releases.
9530 If your package relies on a feature or a bug fix introduced in
9531 a release, you can pass this version as an option to Automake to ensure
9532 older releases will not be used. For instance, use this in your
9533 @file{configure.ac}:
9536 AM_INIT_AUTOMAKE([1.6.1]) dnl Require Automake 1.6.1 or better.
9539 or, in a particular @file{Makefile.am}:
9542 AUTOMAKE_OPTIONS = 1.6.1 # Require Automake 1.6.1 or better.
9545 Automake will print an error message if its version is
9546 older than the requested version.
9549 @heading What is in the API
9551 Automake's programming interface is not easy to define. Basically it
9552 should include at least all @strong{documented} variables and targets
9553 that a @file{Makefile.am} author can use, any behavior associated with
9554 them (e.g., the places where @samp{-hook}'s are run), the command line
9555 interface of @command{automake} and @command{aclocal}, @dots{}
9557 @heading What is not in the API
9559 Every undocumented variable, target, or command line option, is not part
9560 of the API@. You should avoid using them, as they could change from one
9561 version to the other (even in bug fix releases, if this helps to fix a
9564 If it turns out you need to use such a undocumented feature, contact
9565 @email{automake@@gnu.org} and try to get it documented and exercised by
9569 @chapter Upgrading a Package to a Newer Automake Version
9571 Automake maintains three kind of files in a package.
9574 @item @file{aclocal.m4}
9575 @item @file{Makefile.in}s
9576 @item auxiliary tools like @file{install-sh} or @file{py-compile}
9579 @file{aclocal.m4} is generated by @command{aclocal} and contains some
9580 Automake-supplied M4 macros. Auxiliary tools are installed by
9581 @samp{automake --add-missing} when needed. @file{Makefile.in}s are
9582 built from @file{Makefile.am} by @command{automake}, and rely on the
9583 definitions of the M4 macros put in @file{aclocal.m4} as well as the
9584 behavior of the auxiliary tools installed.
9586 Because all these files are closely related, it is important to
9587 regenerate all of them when upgrading to a newer Automake release.
9588 The usual way to do that is
9591 aclocal # with any option needed (such a -I m4)
9593 automake --add-missing --force-missing
9597 or more conveniently:
9603 The use of @option{--force-missing} ensures that auxiliary tools will be
9604 overridden by new versions (@pxref{Invoking Automake}).
9606 It is important to regenerate all these files each time Automake is
9607 upgraded, even between bug fixes releases. For instance, it is not
9608 unusual for a bug fix to involve changes to both the rules generated
9609 in @file{Makefile.in} and the supporting M4 macros copied to
9612 Presently @command{automake} is able to diagnose situations where
9613 @file{aclocal.m4} has been generated with another version of
9614 @command{aclocal}. However it never checks whether auxiliary scripts
9615 are up-to-date. In other words, @command{automake} will tell you when
9616 @command{aclocal} needs to be rerun, but it will never diagnose a
9617 missing @option{--force-missing}.
9619 Before upgrading to a new major release, it is a good idea to read the
9620 file @file{NEWS}. This file lists all changes between releases: new
9621 features, obsolete constructs, known incompatibilities, and
9625 @chapter Frequently Asked Questions about Automake
9627 This chapter covers some questions that often come up on the mailing
9631 * CVS:: CVS and generated files
9632 * maintainer-mode:: missing and AM_MAINTAINER_MODE
9633 * wildcards:: Why doesn't Automake support wildcards?
9634 * limitations on file names:: Limitations on source and installed file names
9635 * distcleancheck:: Files left in build directory after distclean
9636 * Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS
9637 * renamed objects:: Why are object files sometimes renamed?
9638 * Per-Object Flags:: How to simulate per-object flags?
9639 * Multiple Outputs:: Writing rules for tools with many output files
9640 * Hard-Coded Install Paths:: Installing to Hard-Coded Locations
9644 @section CVS and generated files
9646 @subsection Background: distributed generated files
9647 @cindex generated files, distributed
9648 @cindex rebuild rules
9650 Packages made with Autoconf and Automake ship with some generated
9651 files like @file{configure} or @file{Makefile.in}. These files were
9652 generated on the developer's host and are distributed so that
9653 end-users do not have to install the maintainer tools required to
9654 rebuild them. Other generated files like Lex scanners, Yacc parsers,
9655 or Info documentation, are usually distributed on similar grounds.
9657 Automake outputs rules in @file{Makefile}s to rebuild these files. For
9658 instance, @command{make} will run @command{autoconf} to rebuild
9659 @file{configure} whenever @file{configure.ac} is changed. This makes
9660 development safer by ensuring a @file{configure} is never out-of-date
9661 with respect to @file{configure.ac}.
9663 As generated files shipped in packages are up-to-date, and because
9664 @command{tar} preserves times-tamps, these rebuild rules are not
9665 triggered when a user unpacks and builds a package.
9667 @subsection Background: CVS and timestamps
9668 @cindex timestamps and CVS
9669 @cindex CVS and timestamps
9671 Unless you use CVS keywords (in which case files must be updated at
9672 commit time), CVS preserves timestamp during @samp{cvs commit} and
9673 @samp{cvs import -d} operations.
9675 When you check out a file using @samp{cvs checkout} its timestamp is
9676 set to that of the revision that is being checked out.
9678 However, during @command{cvs update}, files will have the date of the
9679 update, not the original timestamp of this revision. This is meant to
9680 make sure that @command{make} notices sources files have been updated.
9682 This timestamp shift is troublesome when both sources and generated
9683 files are kept under CVS@. Because CVS processes files in lexical
9684 order, @file{configure.ac} will appear newer than @file{configure}
9685 after a @command{cvs update} that updates both files, even if
9686 @file{configure} was newer than @file{configure.ac} when it was
9687 checked in. Calling @command{make} will then trigger a spurious rebuild
9688 of @file{configure}.
9690 @subsection Living with CVS in Autoconfiscated projects
9691 @cindex CVS and generated files
9692 @cindex generated files and CVS
9694 There are basically two clans amongst maintainers: those who keep all
9695 distributed files under CVS, including generated files, and those who
9696 keep generated files @emph{out} of CVS.
9698 @subsubheading All files in CVS
9702 The CVS repository contains all distributed files so you know exactly
9703 what is distributed, and you can checkout any prior version entirely.
9706 Maintainers can see how generated files evolve (for instance, you can
9707 see what happens to your @file{Makefile.in}s when you upgrade Automake
9708 and make sure they look OK).
9711 Users do not need the autotools to build a checkout of the project, it
9712 works just like a released tarball.
9715 If users use @command{cvs update} to update their copy, instead of
9716 @command{cvs checkout} to fetch a fresh one, timestamps will be
9717 inaccurate. Some rebuild rules will be triggered and attempt to
9718 run developer tools such as @command{autoconf} or @command{automake}.
9720 Actually, calls to such tools are all wrapped into a call to the
9721 @command{missing} script discussed later (@pxref{maintainer-mode}).
9722 @command{missing} will take care of fixing the timestamps when these
9723 tools are not installed, so that the build can continue.
9726 In distributed development, developers are likely to have different
9727 version of the maintainer tools installed. In this case rebuilds
9728 triggered by timestamp lossage will lead to spurious changes
9729 to generated files. There are several solutions to this:
9733 All developers should use the same versions, so that the rebuilt files
9734 are identical to files in CVS@. (This starts to be difficult when each
9735 project you work on uses different versions.)
9737 Or people use a script to fix the timestamp after a checkout (the GCC
9738 folks have such a script).
9740 Or @file{configure.ac} uses @code{AM_MAINTAINER_MODE}, which will
9741 disable all these rebuild rules by default. This is further discussed
9742 in @ref{maintainer-mode}.
9746 Although we focused on spurious rebuilds, the converse can also
9747 happen. CVS's timestamp handling can also let you think an
9748 out-of-date file is up-to-date.
9750 For instance, suppose a developer has modified @file{Makefile.am} and
9751 has rebuilt @file{Makefile.in}. He then decide to do a last-minute
9752 change to @file{Makefile.am} right before checking in both files
9753 (without rebuilding @file{Makefile.in} to account for the change).
9755 This last change to @file{Makefile.am} make the copy of
9756 @file{Makefile.in} out-of-date. Since CVS processes files
9757 alphabetically, when another developer @samp{cvs update} his or her
9758 tree, @file{Makefile.in} will happen to be newer than
9759 @file{Makefile.am}. This other developer will not see
9760 @file{Makefile.in} is out-of-date.
9764 @subsubheading Generated files out of CVS
9766 One way to get CVS and @command{make} working peacefully is to never
9767 store generated files in CVS, i.e., do not CVS-control files that
9768 are @file{Makefile} targets (also called @emph{derived} files).
9770 This way developers are not annoyed by changes to generated files. It
9771 does not matter if they all have different versions (assuming they are
9772 compatible, of course). And finally, timestamps are not lost, changes
9773 to sources files can't be missed as in the
9774 @file{Makefile.am}/@file{Makefile.in} example discussed earlier.
9776 The drawback is that the CVS repository is not an exact copy of what
9777 is distributed and that users now need to install various development
9778 tools (maybe even specific versions) before they can build a checkout.
9779 But, after all, CVS's job is versioning, not distribution.
9781 Allowing developers to use different versions of their tools can also
9782 hide bugs during distributed development. Indeed, developers will be
9783 using (hence testing) their own generated files, instead of the
9784 generated files that will be released actually. The developer who
9785 prepares the tarball might be using a version of the tool that
9786 produces bogus output (for instance a non-portable C file), something
9787 other developers could have noticed if they weren't using their own
9788 versions of this tool.
9790 @subsection Third-party files
9791 @cindex CVS and third-party files
9792 @cindex third-party files and CVS
9794 Another class of files not discussed here (because they do not cause
9795 timestamp issues) are files that are shipped with a package, but
9796 maintained elsewhere. For instance, tools like @command{gettextize}
9797 and @command{autopoint} (from Gettext) or @command{libtoolize} (from
9798 Libtool), will install or update files in your package.
9800 These files, whether they are kept under CVS or not, raise similar
9801 concerns about version mismatch between developers' tools. The
9802 Gettext manual has a section about this, see @ref{CVS Issues, CVS
9803 Issues, Integrating with CVS, gettext, GNU gettext tools}.
9805 @node maintainer-mode
9806 @section @command{missing} and @code{AM_MAINTAINER_MODE}
9808 @subsection @command{missing}
9809 @cindex @command{missing}, purpose
9811 The @command{missing} script is a wrapper around several maintainer
9812 tools, designed to warn users if a maintainer tool is required but
9813 missing. Typical maintainer tools are @command{autoconf},
9814 @command{automake}, @command{bison}, etc. Because file generated by
9815 these tools are shipped with the other sources of a package, these
9816 tools shouldn't be required during a user build and they are not
9817 checked for in @file{configure}.
9819 However, if for some reason a rebuild rule is triggered and involves a
9820 missing tool, @command{missing} will notice it and warn the user.
9821 Besides the warning, when a tool is missing, @command{missing} will
9822 attempt to fix timestamps in a way that allows the build to continue.
9823 For instance, @command{missing} will touch @file{configure} if
9824 @command{autoconf} is not installed. When all distributed files are
9825 kept under CVS, this feature of @command{missing} allows user
9826 @emph{with no maintainer tools} to build a package off CVS, bypassing
9827 any timestamp inconsistency implied by @samp{cvs update}.
9829 If the required tool is installed, @command{missing} will run it and
9830 won't attempt to continue after failures. This is correct during
9831 development: developers love fixing failures. However, users with
9832 wrong versions of maintainer tools may get an error when the rebuild
9833 rule is spuriously triggered, halting the build. This failure to let
9834 the build continue is one of the arguments of the
9835 @code{AM_MAINTAINER_MODE} advocates.
9837 @subsection @code{AM_MAINTAINER_MODE}
9838 @cindex @code{AM_MAINTAINER_MODE}, purpose
9839 @acindex AM_MAINTAINER_MODE
9841 @code{AM_MAINTAINER_MODE} disables the so called "rebuild rules" by
9842 default. If you have @code{AM_MAINTAINER_MODE} in
9843 @file{configure.ac}, and run @samp{./configure && make}, then
9844 @command{make} will *never* attempt to rebuilt @file{configure},
9845 @file{Makefile.in}s, Lex or Yacc outputs, etc. I.e., this disables
9846 build rules for files that are usually distributed and that users
9847 should normally not have to update.
9849 If you run @samp{./configure --enable-maintainer-mode}, then these
9850 rebuild rules will be active.
9852 People use @code{AM_MAINTAINER_MODE} either because they do want their
9853 users (or themselves) annoyed by timestamps lossage (@pxref{CVS}), or
9854 because they simply can't stand the rebuild rules and prefer running
9855 maintainer tools explicitly.
9857 @code{AM_MAINTAINER_MODE} also allows you to disable some custom build
9858 rules conditionally. Some developers use this feature to disable
9859 rules that need exotic tools that users may not have available.
9861 Several years ago Fran@,{c}ois Pinard pointed out several arguments
9862 against this @code{AM_MAINTAINER_MODE} macro. Most of them relate to
9863 insecurity. By removing dependencies you get non-dependable builds:
9864 change to sources files can have no effect on generated files and this
9865 can be very confusing when unnoticed. He adds that security shouldn't
9866 be reserved to maintainers (what @option{--enable-maintainer-mode}
9867 suggests), on the contrary. If one user has to modify a
9868 @file{Makefile.am}, then either @file{Makefile.in} should be updated
9869 or a warning should be output (this is what Automake uses
9870 @command{missing} for) but the last thing you want is that nothing
9871 happens and the user doesn't notice it (this is what happens when
9872 rebuild rules are disabled by @code{AM_MAINTAINER_MODE}).
9874 Jim Meyering, the inventor of the @code{AM_MAINTAINER_MODE} macro was
9875 swayed by Fran@,{c}ois's arguments, and got rid of
9876 @code{AM_MAINTAINER_MODE} in all of his packages.
9878 Still many people continue to use @code{AM_MAINTAINER_MODE}, because
9879 it helps them working on projects where all files are kept under CVS,
9880 and because @command{missing} isn't enough if you have the wrong
9881 version of the tools.
9885 @section Why doesn't Automake support wildcards?
9888 Developers are lazy. They would often like to use wildcards in
9889 @file{Makefile.am}s, so that they would not need to remember to
9890 update @file{Makefile.am}s every time they add, delete, or rename
9893 There are several objections to this:
9896 When using CVS (or similar) developers need to remember they have to
9897 run @samp{cvs add} or @samp{cvs rm} anyway. Updating
9898 @file{Makefile.am} accordingly quickly becomes a reflex.
9900 Conversely, if your application doesn't compile
9901 because you forgot to add a file in @file{Makefile.am}, it will help
9902 you remember to @samp{cvs add} it.
9905 Using wildcards makes it easy to distribute files by mistake. For
9906 instance, some code a developer is experimenting with (a test case,
9907 say) that should not be part of the distribution.
9910 Using wildcards it's easy to omit some files by mistake. For
9911 instance, one developer creates a new file, uses it in many places,
9912 but forgets to commit it. Another developer then checks out the
9913 incomplete project and is able to run @samp{make dist} successfully,
9914 even though a file is missing. By listing files, @samp{make dist}
9915 @emph{will} complain.
9918 Finally, it's really hard to @emph{forget} to add a file to
9919 @file{Makefile.am}: files that are not listed in @file{Makefile.am} are
9920 not compiled or installed, so you can't even test them.
9923 Still, these are philosophical objections, and as such you may disagree,
9924 or find enough value in wildcards to dismiss all of them. Before you
9925 start writing a patch against Automake to teach it about wildcards,
9926 let's see the main technical issue: portability.
9928 Although @samp{$(wildcard ...)} works with GNU @command{make}, it is
9929 not portable to other @command{make} implementations.
9931 The only way Automake could support @command{$(wildcard ...)} is by
9932 expending @command{$(wildcard ...)} when @command{automake} is run.
9933 The resulting @file{Makefile.in}s would be portable since they would
9934 list all files and not use @samp{$(wildcard ...)}. However that
9935 means developers would need to remember to run @command{automake} each
9936 time they add, delete, or rename files.
9938 Compared to editing @file{Makefile.am}, this is a very small gain. Sure,
9939 it's easier and faster to type @samp{automake; make} than to type
9940 @samp{emacs Makefile.am; make}. But nobody bothered enough to write a
9941 patch to add support for this syntax. Some people use scripts to
9942 generate file lists in @file{Makefile.am} or in separate
9943 @file{Makefile} fragments.
9945 Even if you don't care about portability, and are tempted to use
9946 @samp{$(wildcard ...)} anyway because you target only GNU Make, you
9947 should know there are many places where Automake need to know exactly
9948 which files should be processed. As Automake doesn't know how to
9949 expand @samp{$(wildcard ...)}, you cannot use it in these places.
9950 @samp{$(wildcard ...)} is a black box comparable to @code{AC_SUBST}ed
9951 variables as far Automake is concerned.
9953 You can get warnings about @samp{$(wildcard ...}) constructs using the
9954 @option{-Wportability} flag.
9956 @node limitations on file names
9957 @section Limitations on file names
9958 @cindex file names, limitations on
9960 Automake attempts to support all kinds of file names, even those that
9961 contain unusual characters or are unusually long. However, some
9962 limitations are imposed by the underlying operating system and tools.
9964 Most operating systems prohibit the use of the null byte in file
9965 names, and reserve @samp{/} as a directory separator. Also, they
9966 require that file names are properly encoded for the user's locale.
9967 Automake is subject to these limits.
9969 Portable packages should limit themselves to @acronym{POSIX} file
9970 names. These can contain @acronym{ASCII} letters and digits,
9971 @samp{_}, @samp{.}, and @samp{-}. File names consist of components
9972 separated by @samp{/}. File name components cannot begin with
9975 Portable POSIX file names cannot contain components that exceed a
9976 14-byte limit, but nowadays it's normally safe to assume the
9977 more-generous @acronym{XOPEN} limit of 255 bytes. @acronym{POSIX}
9978 limits file names to 255 bytes (@acronym{XOPEN} allows 1023 bytes),
9979 but you may want to limit a source tarball to file names to 99 bytes
9980 to avoid interoperability problems with old versions of @command{tar}.
9982 If you depart from these rules (e.g., by using non-@acronym{ASCII}
9983 characters in file names, or by using lengthy file names), your
9984 installers may have problems for reasons unrelated to Automake.
9985 However, if this does not concern you, you should know about the
9986 limitations imposed by Automake itself. These limitations are
9987 undesirable, but some of them seem to be inherent to underlying tools
9988 like Autoconf, Make, M4, and the shell. They fall into three
9989 categories: install directories, build directories, and file names.
9991 The following characters:
9994 @r{newline} " # $ ' `
9997 should not appear in the names of install directories. For example,
9998 the operand of @command{configure}'s @option{--prefix} option should
9999 not contain these characters.
10001 Build directories suffer the same limitations as install directories,
10002 and in addition should not contain the following characters:
10008 For example, the full name of the directory containing the source
10009 files should not contain these characters.
10011 Source and installation file names like @file{main.c} are limited even
10012 further: they should conform to the @acronym{POSIX}/@acronym{XOPEN}
10013 rules described above. In addition, if you plan to port to
10014 non-@acronym{POSIX} environments, you should avoid file names that
10015 differ only in case (e.g., @file{makefile} and @file{Makefile}).
10016 Nowadays it is no longer worth worrying about the 8.3 limits of
10017 @acronym{DOS} file systems.
10019 @node distcleancheck
10020 @section Files left in build directory after distclean
10021 @cindex @code{distclean}, diagnostic
10022 @cindex @samp{make distclean}, diagnostic
10023 @cindex dependencies and distributed files
10025 @trindex distcleancheck
10027 This is a diagnostic you might encounter while running @samp{make
10030 As explained in @ref{Dist}, @samp{make distcheck} attempts to build
10031 and check your package for errors like this one.
10033 @samp{make distcheck} will perform a @code{VPATH} build of your
10034 package (@pxref{VPATH Builds}), and then call @samp{make distclean}.
10035 Files left in the build directory after @samp{make distclean} has run
10036 are listed after this error.
10038 This diagnostic really covers two kinds of errors:
10042 files that are forgotten by distclean;
10044 distributed files that are erroneously rebuilt.
10047 The former left-over files are not distributed, so the fix is to mark
10048 them for cleaning (@pxref{Clean}), this is obvious and doesn't deserve
10051 The latter bug is not always easy to understand and fix, so let's
10052 proceed with an example. Suppose our package contains a program for
10053 which we want to build a man page using @command{help2man}. GNU
10054 @command{help2man} produces simple manual pages from the @option{--help}
10055 and @option{--version} output of other commands (@pxref{Top, , Overview,
10056 help2man, The Help2man Manual}). Because we don't to force want our
10057 users to install @command{help2man}, we decide to distribute the
10058 generated man page using the following setup.
10061 # This Makefile.am is bogus.
10063 foo_SOURCES = foo.c
10064 dist_man_MANS = foo.1
10066 foo.1: foo$(EXEEXT)
10067 help2man --output=foo.1 ./foo$(EXEEXT)
10070 This will effectively distribute the man page. However,
10071 @samp{make distcheck} will fail with:
10074 ERROR: files left in build directory after distclean:
10078 Why was @file{foo.1} rebuilt? Because although distributed,
10079 @file{foo.1} depends on a non-distributed built file:
10080 @file{foo$(EXEEXT)}. @file{foo$(EXEEXT)} is built by the user, so it
10081 will always appear to be newer than the distributed @file{foo.1}.
10083 @samp{make distcheck} caught an inconsistency in our package. Our
10084 intent was to distribute @file{foo.1} so users do not need installing
10085 @command{help2man}, however since this our rule causes this file to be
10086 always rebuilt, users @emph{do} need @command{help2man}. Either we
10087 should ensure that @file{foo.1} is not rebuilt by users, or there is
10088 no point in distributing @file{foo.1}.
10090 More generally, the rule is that distributed files should never depend
10091 on non-distributed built files. If you distribute something
10092 generated, distribute its sources.
10094 One way to fix the above example, while still distributing
10095 @file{foo.1} is to not depend on @file{foo$(EXEEXT)}. For instance,
10096 assuming @command{foo --version} and @command{foo --help} do not
10097 change unless @file{foo.c} or @file{configure.ac} change, we could
10098 write the following @file{Makefile.am}:
10102 foo_SOURCES = foo.c
10103 dist_man_MANS = foo.1
10105 foo.1: foo.c $(top_srcdir)/configure.ac
10106 $(MAKE) $(AM_MAKEFLAGS) foo$(EXEEXT)
10107 help2man --output=foo.1 ./foo$(EXEEXT)
10110 This way, @file{foo.1} will not get rebuilt every time
10111 @file{foo$(EXEEXT)} changes. The @command{make} call makes sure
10112 @file{foo$(EXEEXT)} is up-to-date before @command{help2man}. Another
10113 way to ensure this would be to use separate directories for binaries
10114 and man pages, and set @code{SUBDIRS} so that binaries are built
10117 We could also decide not to distribute @file{foo.1}. In
10118 this case it's fine to have @file{foo.1} dependent upon
10119 @file{foo$(EXEEXT)}, since both will have to be rebuilt.
10120 However it would be impossible to build the package in a
10121 cross-compilation, because building @file{foo.1} involves
10122 an @emph{execution} of @file{foo$(EXEEXT)}.
10124 Another context where such errors are common is when distributed files
10125 are built by tools that are built by the package. The pattern is
10129 distributed-file: built-tools distributed-sources
10134 should be changed to
10137 distributed-file: distributed-sources
10138 $(MAKE) $(AM_MAKEFLAGS) built-tools
10143 or you could choose not to distribute @file{distributed-file}, if
10144 cross-compilation does not matter.
10146 The points made through these examples are worth a summary:
10151 Distributed files should never depend upon non-distributed built
10154 Distributed files should be distributed with all their dependencies.
10156 If a file is @emph{intended} to be rebuilt by users, then there is no point
10157 in distributing it.
10161 @vrindex distcleancheck_listfiles
10162 For desperate cases, it's always possible to disable this check by
10163 setting @code{distcleancheck_listfiles} as documented in @ref{Dist}.
10164 Make sure you do understand the reason why @samp{make distcheck}
10165 complains before you do this. @code{distcleancheck_listfiles} is a
10166 way to @emph{hide} errors, not to fix them. You can always do better.
10168 @node Flag Variables Ordering
10169 @section Flag Variables Ordering
10170 @cindex Ordering flag variables
10171 @cindex Flag variables, ordering
10174 What is the difference between @code{AM_CFLAGS}, @code{CFLAGS}, and
10175 @code{mumble_CFLAGS}?
10179 Why does @command{automake} output @code{CPPFLAGS} after
10180 @code{AM_CPPFLAGS} on compile lines? Shouldn't it be the converse?
10184 My @file{configure} adds some warning flags into @code{CXXFLAGS}. In
10185 one @file{Makefile.am} I would like to append a new flag, however if I
10186 put the flag into @code{AM_CXXFLAGS} it is prepended to the other
10187 flags, not appended.
10190 @subsection Compile Flag Variables
10191 @cindex Flag Variables, Ordering
10192 @cindex Compile Flag Variables
10193 @cindex @code{AM_CCASFLAGS} and @code{CCASFLAGS}
10194 @cindex @code{AM_CFLAGS} and @code{CFLAGS}
10195 @cindex @code{AM_CPPFLAGS} and @code{CPPFLAGS}
10196 @cindex @code{AM_CXXFLAGS} and @code{CXXFLAGS}
10197 @cindex @code{AM_FCFLAGS} and @code{FCFLAGS}
10198 @cindex @code{AM_FFLAGS} and @code{FFLAGS}
10199 @cindex @code{AM_GCJFLAGS} and @code{GCJFLAGS}
10200 @cindex @code{AM_LDFLAGS} and @code{LDFLAGS}
10201 @cindex @code{AM_LFLAGS} and @code{LFLAGS}
10202 @cindex @code{AM_LIBTOOLFLAGS} and @code{LIBTOOLFLAGS}
10203 @cindex @code{AM_OBJCFLAGS} and @code{OBJCFLAGS}
10204 @cindex @code{AM_RFLAGS} and @code{RFLAGS}
10205 @cindex @code{AM_UPCFLAGS} and @code{UPCFLAGS}
10206 @cindex @code{AM_YFLAGS} and @code{YFLAGS}
10207 @cindex @code{CCASFLAGS} and @code{AM_CCASFLAGS}
10208 @cindex @code{CFLAGS} and @code{AM_CFLAGS}
10209 @cindex @code{CPPFLAGS} and @code{AM_CPPFLAGS}
10210 @cindex @code{CXXFLAGS} and @code{AM_CXXFLAGS}
10211 @cindex @code{FCFLAGS} and @code{AM_FCFLAGS}
10212 @cindex @code{FFLAGS} and @code{AM_FFLAGS}
10213 @cindex @code{GCJFLAGS} and @code{AM_GCJFLAGS}
10214 @cindex @code{LDFLAGS} and @code{AM_LDFLAGS}
10215 @cindex @code{LFLAGS} and @code{AM_LFLAGS}
10216 @cindex @code{LIBTOOLFLAGS} and @code{AM_LIBTOOLFLAGS}
10217 @cindex @code{OBJCFLAGS} and @code{AM_OBJCFLAGS}
10218 @cindex @code{RFLAGS} and @code{AM_RFLAGS}
10219 @cindex @code{UPCFLAGS} and @code{AM_UPCFLAGS}
10220 @cindex @code{YFLAGS} and @code{AM_YFLAGS}
10222 This section attempts to answer all the above questions. We will
10223 mostly discuss @code{CPPFLAGS} in our examples, but actually the
10224 answer holds for all the compile flags used in Automake:
10225 @code{CCASFLAGS}, @code{CFLAGS}, @code{CPPFLAGS}, @code{CXXFLAGS},
10226 @code{FCFLAGS}, @code{FFLAGS}, @code{GCJFLAGS}, @code{LDFLAGS},
10227 @code{LFLAGS}, @code{LIBTOOLFLAGS}, @code{OBJCFLAGS}, @code{RFLAGS},
10228 @code{UPCFLAGS}, and @code{YFLAGS}.
10230 @code{CPPFLAGS}, @code{AM_CPPFLAGS}, and @code{mumble_CPPFLAGS} are
10231 three variables that can be used to pass flags to the C preprocessor
10232 (actually these variables are also used for other languages like C++
10233 or preprocessed Fortran). @code{CPPFLAGS} is the user variable
10234 (@pxref{User Variables}), @code{AM_CPPFLAGS} is the Automake variable,
10235 and @code{mumble_CPPFLAGS} is the variable specific to the
10236 @code{mumble} target (we call this a per-target variable,
10237 @pxref{Program and Library Variables}).
10239 Automake always uses two of these variables when compiling C sources
10240 files. When compiling an object file for the @code{mumble} target,
10241 the first variable will be @code{mumble_CPPFLAGS} if it is defined, or
10242 @code{AM_CPPFLAGS} otherwise. The second variable is always
10245 In the following example,
10248 bin_PROGRAMS = foo bar
10249 foo_SOURCES = xyz.c
10250 bar_SOURCES = main.c
10251 foo_CPPFLAGS = -DFOO
10252 AM_CPPFLAGS = -DBAZ
10256 @file{xyz.o} will be compiled with @samp{$(foo_CPPFLAGS) $(CPPFLAGS)},
10257 (because @file{xyz.o} is part of the @code{foo} target), while
10258 @file{main.o} will be compiled with @samp{$(AM_CPPFLAGS) $(CPPFLAGS)}
10259 (because there is no per-target variable for target @code{bar}).
10261 The difference between @code{mumble_CPPFLAGS} and @code{AM_CPPFLAGS}
10262 being clear enough, let's focus on @code{CPPFLAGS}. @code{CPPFLAGS}
10263 is a user variable, i.e., a variable that users are entitled to modify
10264 in order to compile the package. This variable, like many others,
10265 is documented at the end of the output of @samp{configure --help}.
10267 For instance, someone who needs to add @file{/home/my/usr/include} to
10268 the C compiler's search path would configure a package with
10271 ./configure CPPFLAGS='-I /home/my/usr/include'
10275 and this flag would be propagated to the compile rules of all
10278 It is also not uncommon to override a user variable at
10279 @command{make}-time. Many installers do this with @code{prefix}, but
10280 this can be useful with compiler flags too. For instance, if, while
10281 debugging a C++ project, you need to disable optimization in one
10282 specific object file, you can run something like
10286 make CXXFLAGS=-O0 file.o
10290 The reason @samp{$(CPPFLAGS)} appears after @samp{$(AM_CPPFLAGS)} or
10291 @samp{$(mumble_CPPFLAGS)} in the compile command is that users
10292 should always have the last say. It probably makes more sense if you
10293 think about it while looking at the @samp{CXXFLAGS=-O0} above, which
10294 should supersede any other switch from @code{AM_CXXFLAGS} or
10295 @code{mumble_CXXFLAGS} (and this of course replaces the previous value
10296 of @code{CXXFLAGS}).
10298 You should never redefine a user variable such as @code{CPPFLAGS} in
10299 @file{Makefile.am}. Use @samp{automake -Woverride} to diagnose such
10300 mistakes. Even something like
10303 CPPFLAGS = -DDATADIR=\"$(datadir)\" @@CPPFLAGS@@
10307 is erroneous. Although this preserves @file{configure}'s value of
10308 @code{CPPFLAGS}, the definition of @code{DATADIR} will disappear if a
10309 user attempts to override @code{CPPFLAGS} from the @command{make}
10313 AM_CPPFLAGS = -DDATADIR=\"$(datadir)\"
10317 is all what is needed here if no per-target flags are used.
10319 You should not add options to these user variables within
10320 @file{configure} either, for the same reason. Occasionally you need
10321 to modify these variables to perform a test, but you should reset
10322 their values afterwards. In contrast, it is OK to modify the
10323 @samp{AM_} variables within @file{configure} if you @code{AC_SUBST}
10324 them, but it is rather rare that you need to do this, unless you
10325 really want to change the default definitions of the @samp{AM_}
10326 variables in all @file{Makefile}s.
10328 What we recommend is that you define extra flags in separate
10329 variables. For instance, you may write an Autoconf macro that computes
10330 a set of warning options for the C compiler, and @code{AC_SUBST} them
10331 in @code{WARNINGCFLAGS}; you may also have an Autoconf macro that
10332 determines which compiler and which linker flags should be used to
10333 link with library @file{libfoo}, and @code{AC_SUBST} these in
10334 @code{LIBFOOCFLAGS} and @code{LIBFOOLDFLAGS}. Then, a
10335 @file{Makefile.am} could use these variables as follows:
10338 AM_CFLAGS = $(WARNINGCFLAGS)
10339 bin_PROGRAMS = prog1 prog2
10340 prog1_SOURCES = @dots{}
10341 prog2_SOURCES = @dots{}
10342 prog2_CFLAGS = $(LIBFOOCFLAGS) $(AM_CFLAGS)
10343 prog2_LDFLAGS = $(LIBFOOLDFLAGS)
10346 In this example both programs will be compiled with the flags
10347 substituted into @samp{$(WARNINGCFLAGS)}, and @code{prog2} will
10348 additionally be compiled with the flags required to link with
10351 Note that listing @code{AM_CFLAGS} in a per-target @code{CFLAGS}
10352 variable is a common idiom to ensure that @code{AM_CFLAGS} applies to
10353 every target in a @file{Makefile.in}.
10355 Using variables like this gives you full control over the ordering of
10356 the flags. For instance, if there is a flag in $(WARNINGCFLAGS) that
10357 you want to negate for a particular target, you can use something like
10358 @samp{prog1_CFLAGS = $(AM_CFLAGS) -no-flag}. If all these flags had
10359 been forcefully appended to @code{CFLAGS}, there would be no way to
10360 disable one flag. Yet another reason to leave user variables to
10363 Finally, we have avoided naming the variable of the example
10364 @code{LIBFOO_LDFLAGS} (with an underscore) because that would cause
10365 Automake to think that this is actually a per-target variable (like
10366 @code{mumble_LDFLAGS}) for some non-declared @code{LIBFOO} target.
10368 @subsection Other Variables
10370 There are other variables in Automake that follow similar principles
10371 to allow user options. For instance, Texinfo rules (@pxref{Texinfo})
10372 use @code{MAKEINFOFLAGS} and @code{AM_MAKEINFOFLAGS}. Similarly,
10373 DejaGnu tests (@pxref{Tests}) use @code{RUNTESTDEFAULTFLAGS} and
10374 @code{AM_RUNTESTDEFAULTFLAGS}. The tags and ctags rules
10375 (@pxref{Tags}) use @code{ETAGSFLAGS}, @code{AM_ETAGSFLAGS},
10376 @code{CTAGSFLAGS}, and @code{AM_CTAGSFLAGS}. Java rules
10377 (@pxref{Java}) use @code{JAVACFLAGS} and @code{AM_JAVACFLAGS}. None
10378 of these rules do support per-target flags (yet).
10380 To some extent, even @code{AM_MAKEFLAGS} (@pxref{Subdirectories})
10381 obeys this naming scheme. The slight difference is that
10382 @code{MAKEFLAGS} is passed to sub-@command{make}s implicitly by
10383 @command{make} itself.
10385 However you should not think that all variables ending with
10386 @code{FLAGS} follow this convention. For instance,
10387 @code{DISTCHECK_CONFIGURE_FLAGS} (@pxref{Dist}),
10388 @code{ACLOCAL_AMFLAGS} (see @ref{Rebuilding} and @ref{Local Macros}),
10389 are two variables that are only useful to the maintainer and have no
10392 @code{ARFLAGS} (@pxref{A Library}) is usually defined by Automake and
10393 has neither @code{AM_} nor per-target cousin.
10395 Finally you should not think either that the existence of a per-target
10396 variable implies that of an @code{AM_} variable or that of a user
10397 variable. For instance, the @code{mumble_LDADD} per-target variable
10398 overrides the global @code{LDADD} variable (which is not a user
10399 variable), and @code{mumble_LIBADD} exists only as a per-target
10400 variable. @xref{Program and Library Variables}.
10403 @node renamed objects
10404 @section Why are object files sometimes renamed?
10406 This happens when per-target compilation flags are used. Object
10407 files need to be renamed just in case they would clash with object
10408 files compiled from the same sources, but with different flags.
10409 Consider the following example.
10412 bin_PROGRAMS = true false
10413 true_SOURCES = generic.c
10414 true_CPPFLAGS = -DEXIT_CODE=0
10415 false_SOURCES = generic.c
10416 false_CPPFLAGS = -DEXIT_CODE=1
10419 Obviously the two programs are built from the same source, but it
10420 would be bad if they shared the same object, because @file{generic.o}
10421 cannot be built with both @samp{-DEXIT_CODE=0} @emph{and}
10422 @samp{-DEXIT_CODE=1}. Therefore @command{automake} outputs rules to
10423 build two different objects: @file{true-generic.o} and
10424 @file{false-generic.o}.
10426 @command{automake} doesn't actually look whether source files are
10427 shared to decide if it must rename objects. It will just rename all
10428 objects of a target as soon as it sees per-target compilation flags
10431 It's OK to share object files when per-target compilation flags are not
10432 used. For instance, @file{true} and @file{false} will both use
10433 @file{version.o} in the following example.
10436 AM_CPPFLAGS = -DVERSION=1.0
10437 bin_PROGRAMS = true false
10438 true_SOURCES = true.c version.c
10439 false_SOURCES = false.c version.c
10442 Note that the renaming of objects is also affected by the
10443 @code{_SHORTNAME} variable (@pxref{Program and Library Variables}).
10446 @node Per-Object Flags
10447 @section Per-Object Flags Emulation
10448 @cindex Per-object flags, emulated
10451 One of my source files needs to be compiled with different flags. How
10455 Automake supports per-program and per-library compilation flags (see
10456 @ref{Program and Library Variables} and @ref{Flag Variables
10457 Ordering}). With this you can define compilation flags that apply to
10458 all files compiled for a target. For instance, in
10462 foo_SOURCES = foo.c foo.h bar.c bar.h main.c
10463 foo_CFLAGS = -some -flags
10467 @file{foo-foo.o}, @file{foo-bar.o}, and @file{foo-main.o} will all be
10468 compiled with @samp{-some -flags}. (If you wonder about the names of
10469 these object files, see @ref{renamed objects}.) Note that
10470 @code{foo_CFLAGS} gives the flags to use when compiling all the C
10471 sources of the @emph{program} @code{foo}, it has nothing to do with
10472 @file{foo.c} or @file{foo-foo.o} specifically.
10474 What if @file{foo.c} needs to be compiled into @file{foo.o} using some
10475 specific flags, that none of the other files require? Obviously
10476 per-program flags are not directly applicable here. Something like
10477 per-object flags are expected, i.e., flags that would be used only
10478 when creating @file{foo-foo.o}. Automake does not support that,
10479 however this is easy to simulate using a library that contains only
10480 that object, and compiling this library with per-library flags.
10484 foo_SOURCES = bar.c bar.h main.c
10485 foo_CFLAGS = -some -flags
10486 foo_LDADD = libfoo.a
10487 noinst_LIBRARIES = libfoo.a
10488 libfoo_a_SOURCES = foo.c foo.h
10489 libfoo_a_CFLAGS = -some -other -flags
10492 Here @file{foo-bar.o} and @file{foo-main.o} will all be
10493 compiled with @samp{-some -flags}, while @file{libfoo_a-foo.o} will
10494 be compiled using @samp{-some -other -flags}. Eventually, all
10495 three objects will be linked to form @file{foo}.
10497 This trick can also be achieved using Libtool convenience libraries,
10498 for instance @samp{noinst_LTLIBRARIES = libfoo.la} (@pxref{Libtool
10499 Convenience Libraries}).
10501 Another tempting idea to implement per-object flags is to override the
10502 compile rules @command{automake} would output for these files.
10503 Automake will not define a rule for a target you have defined, so you
10504 could think about defining the @samp{foo-foo.o: foo.c} rule yourself.
10505 We recommend against this, because this is error prone. For instance,
10506 if you add such a rule to the first example, it will break the day you
10507 decide to remove @code{foo_CFLAGS} (because @file{foo.c} will then be
10508 compiled as @file{foo.o} instead of @file{foo-foo.o}, @pxref{renamed
10509 objects}). Also in order to support dependency tracking, the two
10510 @file{.o}/@file{.obj} extensions, and all the other flags variables
10511 involved in a compilation, you will end up modifying a copy of the
10512 rule previously output by @command{automake} for this file. If a new
10513 release of Automake generates a different rule, your copy will need to
10514 be updated by hand.
10516 @node Multiple Outputs
10517 @section Handling Tools that Produce Many Outputs
10518 @cindex multiple outputs, rules with
10519 @cindex many outputs, rules with
10520 @cindex rules with multiple outputs
10522 This section describes a @command{make} idiom that can be used when a
10523 tool produces multiple output files. It is not specific to Automake
10524 and can be used in ordinary @file{Makefile}s.
10526 Suppose we have a program called @command{foo} that will read one file
10527 called @file{data.foo} and produce two files named @file{data.c} and
10528 @file{data.h}. We want to write a @file{Makefile} rule that captures
10529 this one-to-two dependency.
10531 The naive rule is incorrect:
10534 # This is incorrect.
10535 data.c data.h: data.foo
10540 What the above rule really says is that @file{data.c} and
10541 @file{data.h} each depend on @file{data.foo}, and can each be built by
10542 running @samp{foo data.foo}. In other words it is equivalent to:
10545 # We do not want this.
10553 which means that @command{foo} can be run twice. Usually it will not
10554 be run twice, because @command{make} implementations are smart enough
10555 to check for the existence of the second file after the first one has
10556 been built; they will therefore detect that it already exists.
10557 However there are a few situations where it can run twice anyway:
10561 The most worrying case is when running a parallel @command{make}. If
10562 @file{data.c} and @file{data.h} are built in parallel, two @samp{foo
10563 data.foo} commands will run concurrently. This is harmful.
10565 Another case is when the dependency (here @file{data.foo}) is
10566 (or depends upon) a phony target.
10569 A solution that works with parallel @command{make} but not with
10570 phony dependencies is the following:
10573 data.c data.h: data.foo
10579 The above rules are equivalent to
10584 data.h: data.foo data.c
10588 therefore a parallel @command{make} will have to serialize the builds
10589 of @file{data.c} and @file{data.h}, and will detect that the second is
10590 no longer needed once the first is over.
10592 Using this pattern is probably enough for most cases. However it does
10593 not scale easily to more output files (in this scheme all output files
10594 must be totally ordered by the dependency relation), so we will
10595 explore a more complicated solution.
10597 Another idea is to write the following:
10600 # There is still a problem with this one.
10607 The idea is that @samp{foo data.foo} is run only when @file{data.c}
10608 needs to be updated, but we further state that @file{data.h} depends
10609 upon @file{data.c}. That way, if @file{data.h} is required and
10610 @file{data.foo} is out of date, the dependency on @file{data.c} will
10613 This is almost perfect, but suppose we have built @file{data.h} and
10614 @file{data.c}, and then we erase @file{data.h}. Then, running
10615 @samp{make data.h} will not rebuild @file{data.h}. The above rules
10616 just state that @file{data.c} must be up-to-date with respect to
10617 @file{data.foo}, and this is already the case.
10619 What we need is a rule that forces a rebuild when @file{data.h} is
10620 missing. Here it is:
10626 ## Recover from the removal of $@@
10627 @@if test -f $@@; then :; else \
10629 $(MAKE) $(AM_MAKEFLAGS) data.c; \
10633 The above scheme can be extended to handle more outputs and more
10634 inputs. One of the outputs is selected to serve as a witness to the
10635 successful completion of the command, it depends upon all inputs, and
10636 all other outputs depend upon it. For instance, if @command{foo}
10637 should additionally read @file{data.bar} and also produce
10638 @file{data.w} and @file{data.x}, we would write:
10641 data.c: data.foo data.bar
10642 foo data.foo data.bar
10643 data.h data.w data.x: data.c
10644 ## Recover from the removal of $@@
10645 @@if test -f $@@; then :; else \
10647 $(MAKE) $(AM_MAKEFLAGS) data.c; \
10651 However there are now two minor problems in this setup. One is related
10652 to the timestamp ordering of @file{data.h}, @file{data.w},
10653 @file{data.x}, and @file{data.c}. The other one is a race condition
10654 if a parallel @command{make} attempts to run multiple instances of the
10655 recover block at once.
10657 Let us deal with the first problem. @command{foo} outputs four files,
10658 but we do not know in which order these files are created. Suppose
10659 that @file{data.h} is created before @file{data.c}. Then we have a
10660 weird situation. The next time @command{make} is run, @file{data.h}
10661 will appear older than @file{data.c}, the second rule will be
10662 triggered, a shell will be started to execute the @samp{if@dots{}fi}
10663 command, but actually it will just execute the @code{then} branch,
10664 that is: nothing. In other words, because the witness we selected is
10665 not the first file created by @command{foo}, @command{make} will start
10666 a shell to do nothing each time it is run.
10668 A simple riposte is to fix the timestamps when this happens.
10671 data.c: data.foo data.bar
10672 foo data.foo data.bar
10673 data.h data.w data.x: data.c
10674 @@if test -f $@@; then \
10677 ## Recover from the removal of $@@
10679 $(MAKE) $(AM_MAKEFLAGS) data.c; \
10683 Another solution is to use a different and dedicated file as witness,
10684 rather than using any of @command{foo}'s outputs.
10687 data.stamp: data.foo data.bar
10690 foo data.foo data.bar
10691 @@mv -f data.tmp $@@
10692 data.c data.h data.w data.x: data.stamp
10693 ## Recover from the removal of $@@
10694 @@if test -f $@@; then :; else \
10695 rm -f data.stamp; \
10696 $(MAKE) $(AM_MAKEFLAGS) data.stamp; \
10700 @file{data.tmp} is created before @command{foo} is run, so it has a
10701 timestamp older than output files output by @command{foo}. It is then
10702 renamed to @file{data.stamp} after @command{foo} has run, because we
10703 do not want to update @file{data.stamp} if @command{foo} fails.
10705 This solution still suffers from the second problem: the race
10706 condition in the recover rule. If, after a successful build, a user
10707 erases @file{data.c} and @file{data.h}, and runs @samp{make -j}, then
10708 @command{make} may start both recover rules in parallel. If the two
10709 instances of the rule execute @samp{$(MAKE) $(AM_MAKEFLAGS)
10710 data.stamp} concurrently the build is likely to fail (for instance, the
10711 two rules will create @file{data.tmp}, but only one can rename it).
10713 Admittedly, such a weird situation does not arise during ordinary
10714 builds. It occurs only when the build tree is mutilated. Here
10715 @file{data.c} and @file{data.h} have been explicitly removed without
10716 also removing @file{data.stamp} and the other output files.
10717 @code{make clean; make} will always recover from these situations even
10718 with parallel makes, so you may decide that the recover rule is solely
10719 to help non-parallel make users and leave things as-is. Fixing this
10720 requires some locking mechanism to ensure only one instance of the
10721 recover rule rebuilds @file{data.stamp}. One could imagine something
10722 along the following lines.
10725 data.c data.h data.w data.x: data.stamp
10726 ## Recover from the removal of $@@
10727 @@if test -f $@@; then :; else \
10728 trap 'rm -rf data.lock data.stamp' 1 2 13 15; \
10729 ## mkdir is a portable test-and-set
10730 if mkdir data.lock 2>/dev/null; then \
10731 ## This code is being executed by the first process.
10732 rm -f data.stamp; \
10733 $(MAKE) $(AM_MAKEFLAGS) data.stamp; \
10734 result=$$?; rm -rf data.lock; exit $$result; \
10736 ## This code is being executed by the follower processes.
10737 ## Wait until the first process is done.
10738 while test -d data.lock; do sleep 1; done; \
10739 ## Succeed if and only if the first process succeeded.
10740 test -f data.stamp; \
10745 Using a dedicated witness, like @file{data.stamp}, is very handy when
10746 the list of output files is not known beforehand. As an illustration,
10747 consider the following rules to compile many @file{*.el} files into
10748 @file{*.elc} files in a single command. It does not matter how
10749 @code{ELFILES} is defined (as long as it is not empty: empty targets
10750 are not accepted by POSIX).
10753 ELFILES = one.el two.el three.el @dots{}
10754 ELCFILES = $(ELFILES:=c)
10756 elc-stamp: $(ELFILES)
10759 $(elisp_comp) $(ELFILES)
10760 @@mv -f elc-temp $@@
10762 $(ELCFILES): elc-stamp
10763 ## Recover from the removal of $@@
10764 @@if test -f $@@; then :; else \
10765 trap 'rm -rf elc-lock elc-stamp' 1 2 13 15; \
10766 if mkdir elc-lock 2>/dev/null; then \
10767 ## This code is being executed by the first process.
10769 $(MAKE) $(AM_MAKEFLAGS) elc-stamp; \
10772 ## This code is being executed by the follower processes.
10773 ## Wait until the first process is done.
10774 while test -d elc-lock; do sleep 1; done; \
10775 ## Succeed if and only if the first process succeeded.
10776 test -f elc-stamp; exit $$?; \
10781 For completeness it should be noted that GNU @command{make} is able to
10782 express rules with multiple output files using pattern rules
10783 (@pxref{Pattern Examples, , Pattern Rule Examples, make, The GNU Make
10784 Manual}). We do not discuss pattern rules here because they are not
10785 portable, but they can be convenient in packages that assume GNU
10789 @node Hard-Coded Install Paths
10790 @section Installing to Hard-Coded Locations
10793 My package needs to install some configuration file. I tried to use
10794 the following rule, but @samp{make distcheck} fails. Why?
10798 install-data-local:
10799 $(INSTALL_DATA) $(srcdir)/afile $(DESTDIR)/etc/afile
10804 My package needs to populate the installation directory of another
10805 package at install-time. I can easily compute that installation
10806 directory in @file{configure}, but if I install files therein,
10807 @samp{make distcheck} fails. How else should I do?
10810 These two setups share their symptoms: @samp{make distcheck} fails
10811 because they are installing files to hard-coded paths. In the later
10812 case the path is not really hard-coded in the package, but we can
10813 consider it to be hard-coded in the system (or in whichever tool that
10814 supplies the path). As long as the path does not use any of the
10815 standard directory variables (@samp{$(prefix)}, @samp{$(bindir)},
10816 @samp{$(datadir)}, etc.), the effect will be the same:
10817 user-installations are impossible.
10819 When a (non-root) user wants to install a package, he usually has no
10820 right to install anything in @file{/usr} or @file{/usr/local}. So he
10821 does something like @samp{./configure --prefix ~/usr} to install
10822 package in his own @file{~/usr} tree.
10824 If a package attempts to install something to some hard-coded path
10825 (e.g., @file{/etc/afile}), regardless of this @option{--prefix} setting,
10826 then the installation will fail. @samp{make distcheck} performs such
10827 a @option{--prefix} installation, hence it will fail too.
10829 Now, there are some easy solutions.
10831 The above @code{install-data-local} example for installing
10832 @file{/etc/afile} would be better replaced by
10835 sysconf_DATA = afile
10839 by default @code{sysconfdir} will be @samp{$(prefix)/etc}, because
10840 this is what the GNU Standards require. When such a package is
10841 installed on a FHS compliant system, the installer will have to set
10842 @samp{--sysconfdir=/etc}. As the maintainer of the package you
10843 should not be concerned by such site policies: use the appropriate
10844 standard directory variable to install your files so that installer
10845 can easily redefine these variables to match their site conventions.
10847 Installing files that should be used by another package, is slightly
10848 more involved. Let's take an example and assume you want to install
10849 shared library that is a Python extension module. If you ask Python
10850 where to install the library, it will answer something like this:
10853 % @kbd{python -c 'from distutils import sysconfig;
10854 print sysconfig.get_python_lib(1,0)'}
10855 /usr/lib/python2.3/site-packages
10858 If you indeed use this absolute path to install your shared library,
10859 non-root users will not be able to install the package, hence
10862 Let's do better. The @samp{sysconfig.get_python_lib()} function
10863 actually accepts a third argument that will replace Python's
10864 installation prefix.
10867 % @kbd{python -c 'from distutils import sysconfig;
10868 print sysconfig.get_python_lib(1,0,"$@{exec_prefix@}")'}
10869 $@{exec_prefix@}/lib/python2.3/site-packages
10872 You can also use this new path. If you do
10875 root users can install your package with the same @option{--prefix}
10876 as Python (you get the behavior of the previous attempt)
10879 non-root users can install your package too, they will have the
10880 extension module in a place that is not searched by Python but they
10881 can work around this using environment variables (and if you installed
10882 scripts that use this shared library, it's easy to tell Python were to
10883 look in the beginning of your script, so the script works in both
10887 The @code{AM_PATH_PYTHON} macro uses similar commands to define
10888 @samp{$(pythondir)} and @samp{$(pyexecdir)} (@pxref{Python}).
10890 Of course not all tools are as advanced as Python regarding that
10891 substitution of @var{prefix}. So another strategy is to figure the
10892 part of the of the installation directory that must be preserved. For
10893 instance, here is how @code{AM_PATH_LISPDIR} (@pxref{Emacs Lisp})
10894 computes @samp{$(lispdir)}:
10897 $EMACS -batch -q -eval '(while load-path
10898 (princ (concat (car load-path) "\n"))
10899 (setq load-path (cdr load-path)))' >conftest.out
10902 -e '/.*\/lib\/x*emacs\/site-lisp$/@{
10903 s,.*/lib/\(x*emacs/site-lisp\)$,$@{libdir@}/\1,;p;q;
10905 -e '/.*\/share\/x*emacs\/site-lisp$/@{
10906 s,.*/share/\(x*emacs/site-lisp\),$@{datarootdir@}/\1,;p;q;
10911 I.e., it just picks the first directory that looks like
10912 @file{*/lib/*emacs/site-lisp} or @file{*/share/*emacs/site-lisp} in
10913 the search path of emacs, and then substitutes @samp{$@{libdir@}} or
10914 @samp{$@{datadir@}} appropriately.
10916 The emacs case looks complicated because it processes a list and
10917 expect two possible layouts, otherwise it's easy, and the benefit for
10918 non-root users are really worth the extra @command{sed} invocation.
10922 @chapter History of Automake
10924 This chapter presents various aspects of the history of Automake. The
10925 exhausted reader can safely skip it; this will be more of interest to
10926 nostalgic people, or to those curious to learn about the evolution of
10930 * Timeline:: The Automake story.
10931 * Dependency Tracking Evolution:: Evolution of Automatic Dependency Tracking
10932 * Releases:: Statistics about Automake Releases
10939 @item 1994-09-19 First CVS commit.
10941 If we can trust the CVS repository, David J.@tie{}MacKenzie (djm) started
10942 working on Automake (or AutoMake, as it was spelt then) this Monday.
10944 The first version of the @command{automake} script looks as follows.
10953 if test ! -f $@{makefile@}.am; then
10954 echo "automake: $@{makefile@}.am: No such honkin' file"
10959 exec 4> $@{makefile@}.in
10964 From this you can already see that Automake will be about reading
10965 @file{*.am} file and producing @file{*.in} files. You cannot see
10966 anything else, but if you also know that David is the one who created
10967 Autoconf two years before you can guess the rest.
10969 Several commits follow, and by the end of the day Automake is
10970 reported to work for GNU fileutils and GNU m4.
10972 The modus operandi is the one that is still used today: variables
10973 assignments in @file{Makefile.am} files trigger injections of
10974 precanned @file{Makefile} fragments into the generated
10975 @file{Makefile.in}. The use of @file{Makefile} fragments was inspired
10976 by the 4.4BSD @command{make} and include files, however Automake aims
10977 to be portable and to conform to the GNU standards for @file{Makefile}
10978 variables and targets.
10980 At this point, the most recent release of Autoconf is version 1.11,
10981 and David is preparing to release Autoconf 2.0 in late October. As a
10982 matter of fact, he will barely touch Automake after September.
10984 @item 1994-11-05 David MacKenzie's last commit.
10986 At this point Automake is a 200 line portable shell script, plus 332
10987 lines of @file{Makefile} fragments. In the @file{README}, David
10988 states his ambivalence between ``portable shell'' and ``more
10989 appropriate language'':
10992 I wrote it keeping in mind the possibility of it becoming an Autoconf
10993 macro, so it would run at configure-time. That would slow
10994 configuration down a bit, but allow users to modify the Makefile.am
10995 without needing to fetch the AutoMake package. And, the Makefile.in
10996 files wouldn't need to be distributed. But all of AutoMake would. So
10997 I might reimplement AutoMake in Perl, m4, or some other more
10998 appropriate language.
11001 Automake is described as ``an experimental Makefile generator''.
11002 There is no documentation. Adventurous users are referred to the
11003 examples and patches needed to use Automake with GNU m4 1.3, fileutils
11004 3.9, time 1.6, and development versions of find and indent.
11006 These examples seem to have been lost. However at the time of writing
11007 (10 years later in September, 2004) the FSF still distributes a
11008 package that uses this version of Automake: check out GNU termutils
11011 @item 1995-11-12 Tom Tromey's first commit.
11013 After one year of inactivity, Tom Tromey takes over the package.
11014 Tom was working on GNU cpio back then, and doing this just for fun,
11015 having trouble finding a project to contribute to. So while hacking
11016 he wanted to bring the @file{Makefile.in} up to GNU standards. This
11017 was hard, and one day he saw Automake on @url{ftp://alpha.gnu.org/},
11018 grabbed it and tried it out.
11020 Tom didn't talk to djm about it until later, just to make sure he
11021 didn't mind if he made a release. He did a bunch of early releases to
11024 Gnits was (and still is) totally informal, just a few GNU friends who
11025 Fran@,cois Pinard knew, who were all interested in making a common
11026 infrastructure for GNU projects, and shared a similar outlook on how
11027 to do it. So they were able to make some progress. It came along
11028 with Autoconf and extensions thereof, and then Automake from David and
11029 Tom (who were both gnitsians). One of their ideas was to write a
11030 document paralleling the GNU standards, that was more strict in some
11031 ways and more detailed. They never finished the GNITS standards, but
11032 the ideas mostly made their way into Automake.
11034 @item 1995-11-23 Automake 0.20
11036 Besides introducing automatic dependency tracking (@pxref{Dependency
11037 Tracking Evolution}), this version also supplies a 9-page manual.
11039 At this time @command{aclocal} and @code{AM_INIT_AUTOMAKE} did not
11040 exist, so many things had to be done by hand. For instance, here is
11041 what a configure.in (this is the former name of the
11042 @file{configure.ac} we use today) must contain in order to use
11048 AC_DEFINE_UNQUOTED(PACKAGE, "$PACKAGE")
11049 AC_DEFINE_UNQUOTED(VERSION, "$VERSION")
11056 (Today all of the above is achieved by @code{AC_INIT} and
11057 @code{AM_INIT_AUTOMAKE}.)
11059 Here is how programs are specified in @file{Makefile.am}:
11063 hello_SOURCES = hello.c
11066 This looks pretty much like what we do today, except the
11067 @code{PROGRAMS} variable has no directory prefix specifying where
11068 @file{hello} should be installed: all programs are installed in
11069 @samp{$(bindir)}. @code{LIBPROGRAMS} can be used to specify programs
11070 that must be built but not installed (it is called
11071 @code{noinst_PROGRAMS} nowadays).
11073 Programs can be built conditionally using @code{AC_SUBST}itutions:
11076 PROGRAMS = @@progs@@
11077 AM_PROGRAMS = foo bar baz
11080 (@code{AM_PROGRAMS} has since then been renamed to
11081 @code{EXTRA_PROGRAMS}.)
11083 Similarly scripts, static libraries, and data can built and installed
11084 using the @code{LIBRARIES}, @code{SCRIPTS}, and @code{DATA} variables.
11085 However @code{LIBRARIES} were treated a bit specially in that Automake
11086 did automatically supply the @file{lib} and @file{.a} prefixes.
11087 Therefore to build @file{libcpio.a}, one had to write
11094 Extra files to distribute must be listed in @code{DIST_OTHER} (the
11095 ancestor of @code{EXTRA_DIST}). Also extra directories that are to be
11096 distributed should appear in @code{DIST_SUBDIRS}, but the manual
11097 describes this as a temporary ugly hack (today extra directories should
11098 also be listed in @code{EXTRA_DIST}, and @code{DIST_SUBDIRS} is used
11099 for another purpose, @pxref{Conditional Subdirectories}).
11101 @item 1995-11-26 Automake 0.21
11103 In less time that it takes to cook a frozen pizza, Tom rewrites
11104 Automake using Perl. At this time Perl 5 is only one year old, and
11105 Perl 4.036 is in use at many sites. Supporting several Perl versions
11106 has been a source of problems through the whole history of Automake.
11108 If you never used Perl 4, imagine Perl 5 without objects, without
11109 @samp{my} variables (only dynamically scoped @samp{local} variables),
11110 without function prototypes, with function calls that needs to be
11111 prefixed with @samp{&}, etc. Traces of this old style can still be
11112 found in today's @command{automake}.
11114 @item 1995-11-28 Automake 0.22
11115 @itemx 1995-11-29 Automake 0.23
11119 @item 1995-12-08 Automake 0.24
11120 @itemx 1995-12-10 Automake 0.25
11122 Releases are raining. 0.24 introduces the uniform naming scheme we
11123 use today, i.e., @code{bin_PROGRAMS} instead of @code{PROGRAMS},
11124 @code{noinst_LIBRARIES} instead of @code{LIBLIBRARIES}, etc. (However
11125 @code{EXTRA_PROGRAMS} does not exist yet, @code{AM_PROGRAMS} is still
11126 in use; and @code{TEXINFOS} and @code{MANS} still have no directory
11127 prefixes.) Adding support for prefixes like that was one of the major
11128 ideas in automake; it has lasted pretty well.
11130 AutoMake is renamed to Automake (Tom seems to recall it was Fran@,cois
11133 0.25 fixes a Perl 4 portability bug.
11135 @item 1995-12-18 Jim Meyering starts using Automake in GNU Textutils.
11136 @item 1995-12-31 Fran@,cois Pinard starts using Automake in GNU tar.
11138 @item 1996-01-03 Automake 0.26
11139 @itemx 1996-01-03 Automake 0.27
11141 Of the many change and suggestions sent by Fran@,cois Pinard and
11142 included in 0.26, the most important is perhaps the advise that to
11143 ease customization a user rule or variable definition should always
11144 override an Automake rule or definition.
11146 Gordon Matzigkeit and Jim Meyering are two other early contributors
11147 that have been sending fixes.
11149 0.27 fixes yet another Perl 4 portability bug.
11151 @item 1996-01-13 Automake 0.28
11153 Automake starts scanning @file{configure.in} for @code{LIBOBJS}
11154 support. This is an important step because until this version
11155 Automake did only know about the @file{Makefile.am}s it processed.
11156 @file{configure.in} was Autoconf's world and the link between Autoconf
11157 and Automake had to be done by the @file{Makefile.am} author. For
11158 instance, if @file{config.h} was generated by @file{configure}, it was the
11159 package maintainer's responsibility to define the @code{CONFIG_HEADER}
11160 variable in each @file{Makefile.am}.
11162 Succeeding releases will rely more and more on scanning
11163 @file{configure.in} to better automate the Autoconf integration.
11165 0.28 also introduces the @code{AUTOMAKE_OPTIONS} variable and the
11166 @option{--gnu} and @option{--gnits} options, the latter being stricter.
11168 @item 1996-02-07 Automake 0.29
11170 Thanks to @file{configure.in} scanning, @code{CONFIG_HEADER} is gone,
11171 and rebuild rules for @file{configure}-generated file are
11172 automatically output.
11174 @code{TEXINFOS} and @code{MANS} converted to the uniform naming
11177 @item 1996-02-24 Automake 0.30
11179 The test suite is born. It contains 9 tests. From now on test cases
11180 will be added pretty regularly (@pxref{Releases}), and this proved to
11181 be really helpful later on.
11183 @code{EXTRA_PROGRAMS} finally replaces @code{AM_PROGRAMS}.
11185 All the third-party Autoconf macros, written mostly by Fran@,cois
11186 Pinard (and later Jim Meyering), are distributed in Automake's
11187 hand-written @file{aclocal.m4} file. Package maintainers are expected
11188 to extract the necessary macros from this file. (In previous version
11189 you had to copy and paste them from the manual...)
11191 @item 1996-03-11 Automake 0.31
11193 The test suite in 0.30 was run via a long @code{check-local} rule. Upon
11194 Ulrich Drepper's suggestion, 0.31 makes it an Automake rule output
11195 whenever the @code{TESTS} variable is defined.
11197 @code{DIST_OTHER} is renamed to @code{EXTRA_DIST}, and the @code{check_}
11198 prefix is introduced. The syntax is now the same as today.
11200 @item 1996-03-15 Gordon Matzigkeit starts writing libtool.
11202 @item 1996-04-27 Automake 0.32
11204 @code{-hook} targets are introduced; an idea from Dieter Baron.
11206 @file{*.info} files, which were output in the build directory are
11207 now built in the source directory, because they are distributed. It
11208 seems these files like to move back and forth as that will happen
11209 again in future versions.
11211 @item 1996-05-18 Automake 0.33
11213 Gord Matzigkeit's main two contributions:
11216 @item very preliminary libtool support
11217 @item the distcheck rule
11220 Although they were very basic at this point, these are probably
11221 among the top features for Automake today.
11223 Jim Meyering also provides the infamous @code{jm_MAINTAINER_MODE},
11224 since then renamed to @code{AM_MAINTAINER_MODE} and abandoned by its
11225 author (@pxref{maintainer-mode}).
11227 @item 1996-05-28 Automake 1.0
11229 After only six months of heavy development, the automake script is
11230 3134 lines long, plus 973 lines of @file{Makefile} fragments. The
11231 package has 30 pages of documentation, and 38 test cases.
11232 @file{aclocal.m4} contains 4 macros.
11234 From now on and until version 1.4, new releases will occur at a rate
11235 of about one a year. 1.1 did not exist, actually 1.1b to 1.1p have
11236 been the name of beta releases for 1.2. This is the first time
11237 Automake uses suffix letters to designate beta releases, an habit that
11240 @item 1996-10-10 Kevin Dalley packages Automake 1.0 for Debian GNU/Linux.
11242 @item 1996-11-26 David J.@tie{}MacKenzie releases Autoconf 2.12.
11244 Between June and October, the Autoconf development is almost staled.
11245 Roland McGrath has been working at the beginning of the year. David
11246 comes back in November to release 2.12, but he won't touch Autoconf
11247 anymore after this year, and Autoconf then really stagnates. The
11248 desolate Autoconf @file{ChangeLog} for 1997 lists only 7 commits.
11250 @item 1997-02-28 @email{automake@@gnu.ai.mit.edu} list alive
11252 The mailing list is announced as follows:
11254 I've created the "automake" mailing list. It is
11255 "automake@@gnu.ai.mit.edu". Administrivia, as always, to
11256 automake-request@@gnu.ai.mit.edu.
11258 The charter of this list is discussion of automake, autoconf, and
11259 other configuration/portability tools (e.g., libtool). It is expected
11260 that discussion will range from pleas for help all the way up to
11263 This list is archived on the FSF machines. Offhand I don't know if
11264 you can get the archive without an account there.
11266 This list is open to anybody who wants to join. Tell all your
11271 Before that people were discussing Automake privately, on the Gnits
11272 mailing list (which is not public either), and less frequently on
11273 @code{gnu.misc.discuss}.
11275 @code{gnu.ai.mit.edu} is now @code{gnu.org}, in case you never
11276 noticed. The archives of the early years of the
11277 @code{automake@@gnu.org} list have been lost, so today it is almost
11278 impossible to find traces of discussions that occurred before 1999.
11279 This has been annoying more than once, as such discussions can be
11280 useful to understand the rationale behind a piece of uncommented code
11281 that was introduced back then.
11283 @item 1997-06-22 Automake 1.2
11285 Automake developments continues, and more and more new Autoconf macros
11286 are required. Distributing them in @file{aclocal.m4} and requiring
11287 people to browse this file to extract the relevant macros becomes
11288 uncomfortable. Ideally, some of them should be contributed to
11289 Autoconf so that they can be used directly, however Autoconf is
11290 currently inactive. Automake 1.2 consequently introduces
11291 @command{aclocal} (@command{aclocal} was actually started on
11292 1996-07-28), a tool that automatically constructs an @file{aclocal.m4}
11293 file from a repository of third-party macros. Because Autoconf has
11294 stalled, Automake also becomes a kind of repository for such
11295 third-party macros, even macros completely unrelated to Automake (for
11296 instance macros that fix broken Autoconf macros).
11298 The 1.2 release contains 20 macros, among which the
11299 @code{AM_INIT_AUTOMAKE} macro that simplifies the creation of
11300 @file{configure.in}.
11302 Libtool is fully supported using @code{*_LTLIBRARIES}.
11304 The missing script is introduced by Fran@,cois Pinard; it is meant to be
11305 a better solution than @code{AM_MAINTAINER_MODE}
11306 (@pxref{maintainer-mode}).
11308 Conditionals support was implemented by Ian Lance Taylor. At the
11309 time, Tom and Ian were working on an internal project at Cygnus. They
11310 were using ILU, which is pretty similar to CORBA@. They wanted to
11311 integrate ILU into their build, which was all @file{configure}-based,
11312 and Ian thought that adding conditionals to @command{automake} was
11313 simpler than doing all the work in @file{configure} (which was the
11314 standard at the time). So this was actually funded by Cygnus.
11316 This very useful but tricky feature will take a lot of time to
11317 stabilize. (At the time this text is written, there are still
11318 primaries that have not been updated to support conditional
11319 definitions in Automake 1.9.)
11321 The @command{automake} script has almost doubled: 6089 lines of Perl,
11322 plus 1294 lines of @file{Makefile} fragments.
11324 @item 1997-07-08 Gordon Matzigkeit releases Libtool 1.0.
11326 @item 1998-04-05 Automake 1.3
11328 This is a small advance compared to 1.2.
11329 It add support for assembly, and preliminary support for Java.
11331 Perl 5.004_04 is out, but fixes to support Perl 4 are still
11332 regularly submitted whenever Automake breaks it.
11334 @item 1998-09-06 @code{sourceware.cygnus.com} is on-line.
11336 Sourceware was setup by Jason Molenda to host open source projects.
11338 @item 1998-09-19 Automake CVS repository moved to @code{sourceware.cygnus.com}
11339 @itemx 1998-10-26 @code{sourceware.cygnus.com} announces it hosts Automake
11340 Automake is now hosted on @code{sourceware.cygnus.com}. It has a
11341 publicly accessible CVS repository. This CVS repository is a copy of
11342 the one Tom was using on his machine, which in turn is based on
11343 a copy of the CVS repository of David MacKenzie. This is why we still
11344 have to full source history. (Automake was on Sourceware until 2007-10-29,
11345 when it moved to a git repository on @code{savannah.gnu.org},
11346 but the Sourceware host had been renamed to @code{sources.redhat.com}.)
11348 The oldest file in the administrative directory of the CVS repository
11349 that was created on Sourceware is dated 1998-09-19, while the
11350 announcement that @command{automake} and @command{autoconf} had joined
11351 @command{sourceware} was made on 1998-10-26. They were among the
11352 first projects to be hosted there.
11354 The heedful reader will have noticed Automake was exactly 4-year-old
11357 @item 1999-01-05 Ben Elliston releases Autoconf 2.13.
11359 @item 1999-01-14 Automake 1.4
11361 This release adds support for Fortran 77 and for the @code{include}
11362 statement. Also, @samp{+=} assignments are introduced, but it is
11363 still quite easy to fool Automake when mixing this with conditionals.
11365 These two releases, Automake 1.4 and Autoconf 2.13 makes a duo that
11366 will be used together for years.
11368 @command{automake} is 7228 lines, plus 1591 lines of Makefile
11369 fragment, 20 macros (some 1.3 macros were finally contributed back to
11370 Autoconf), 197 test cases, and 51 pages of documentation.
11372 @item 1999-03-27 The @code{user-dep-branch} is created on the CVS repository.
11374 This implements a new dependency tracking schemed that should be
11375 able to handle automatic dependency tracking using any compiler (not
11376 just gcc) and any make (not just GNU @command{make}). In addition,
11377 the new scheme should be more reliable than the old one, as
11378 dependencies are generated on the end user's machine. Alexandre Oliva
11379 creates depcomp for this purpose.
11381 @xref{Dependency Tracking Evolution}, for more details about the
11382 evolution of automatic dependency tracking in Automake.
11384 @item 1999-11-21 The @code{user-dep-branch} is merged into the main trunk.
11386 This was a huge problem since we also had patches going in on the
11387 trunk. The merge took a long time and was very painful.
11391 Since September 1999 and until 2003, Akim Demaille will be zealously
11392 revamping Autoconf.
11395 I think the next release should be called "3.0".@*
11396 Let's face it: you've basically rewritten autoconf.@*
11397 Every weekend there are 30 new patches.@*
11398 I don't see how we could call this "2.15" with a straight face.@*
11399 -- Tom Tromey on @email{autoconf@@gnu.org}
11402 Actually Akim works like a submarine: he will pile up patches while he
11403 works off-line during the weekend, and flush them in batch when he
11404 resurfaces on Monday.
11408 On this Wednesday, Autoconf 2.49c, the last beta before Autoconf 2.50
11409 is out, and Akim has to find something to do during his week-end :)
11413 Akim sends a batch of 14 patches to @email{automake@@gnu.org}.
11416 Aiieeee! I was dreading the day that the Demaillator turned his
11417 sights on automake@dots{} and now it has arrived! -- Tom Tromey
11420 It's only the beginning: in two months he will send 192 patches. Then
11421 he would slow down so Tom can catch up and review all this. Initially
11422 Tom actually read all these patches, then he probably trustingly
11423 answered OK to most of them, and finally gave up and let Akim apply
11424 whatever he wanted. There was no way to keep up with that patch rate.
11427 Anyway the patch below won't apply since it predates Akim's
11428 sourcequake; I have yet to figure where the relevant passage has
11429 been moved :) -- Alexandre Duret-Lutz
11432 All these patches were sent to and discussed on
11433 @email{automake@@gnu.org}, so subscribed users were literally drown in
11434 technical mails. Eventually, the @email{automake-patches@@gnu.org}
11435 mailing list was created in May.
11437 Year after year, Automake had drifted away from its initial design:
11438 construct @file{Makefile.in} by assembling various @file{Makefile}
11439 fragments. In 1.4, lots of @file{Makefile} rules are being emitted at
11440 various places in the @command{automake} script itself; this does not
11441 help ensuring a consistent treatment of these rules (for instance
11442 making sure that user-defined rules override Automake's own rules).
11443 One of Akim's goal was moving all these hard-coded rules to separate
11444 @file{Makefile} fragments, so the logic could be centralized in a
11445 @file{Makefile} fragment processor.
11447 Another significant contribution of Akim is the interface with the
11448 ``trace'' feature of Autoconf. The way to scan @file{configure.in} at
11449 this time was to read the file and grep the various macro of interest
11450 to Automake. Doing so could break in many unexpected ways; automake
11451 could miss some definition (for instance @samp{AC_SUBST([$1], [$2])}
11452 where the arguments are known only when M4 is run), or conversely it
11453 could detect some macro that was not expanded (because it is called
11454 conditionally). In the CVS version of Autoconf, Akim had implemented
11455 the @option{--trace} option, which provides accurate information about
11456 where macros are actually called and with what arguments. Akim will
11457 equip Automake with a second @file{configure.in} scanner that uses
11458 this @option{--trace} interface. Since it was not sensible to drop the
11459 Autoconf 2.13 compatibility yet, this experimental scanner was only
11460 used when an environment variable was set, the traditional
11461 grep-scanner being still the default.
11463 @item 2001-04-25 Gary V.@tie{}Vaughan releases Libtool 1.4
11465 It has been more than two years since Automake 1.4, CVS Automake has
11466 suffered lot's of heavy changes and still is not ready for release.
11467 Libtool 1.4 had to be distributed with a patch against Automake 1.4.
11469 @item 2001-05-08 Automake 1.4-p1
11470 @itemx 2001-05-24 Automake 1.4-p2
11472 Gary V.@tie{}Vaughan, the principal Libtool maintainer, makes a ``patch
11473 release'' of Automake:
11476 The main purpose of this release is to have a stable automake
11477 which is compatible with the latest stable libtool.
11480 The release also contains obvious fixes for bugs in Automake 1.4,
11481 some of which were reported almost monthly.
11483 @item 2001-05-21 Akim Demaille releases Autoconf 2.50
11485 @item 2001-06-07 Automake 1.4-p3
11486 @itemx 2001-06-10 Automake 1.4-p4
11487 @itemx 2001-07-15 Automake 1.4-p5
11489 Gary continues his patch-release series. These also add support for
11490 some new Autoconf 2.50 idioms. Essentially, Autoconf now advocates
11491 @file{configure.ac} over @file{configure.in}, and it introduces a new
11492 syntax for @code{AC_OUTPUT}ing files.
11494 @item 2001-08-23 Automake 1.5
11496 A major and long-awaited release, that comes more than two years after
11497 1.4. It brings many changes, among which:
11499 @item The new dependency tracking scheme that uses @command{depcomp}.
11500 Aside from the improvement on the dependency tracking itself
11501 (@pxref{Dependency Tracking Evolution}), this also streamlines the use
11502 of automake generated @file{Makefile.in}s as the @file{Makefile.in}s
11503 used during development are now the same as those used in
11504 distributions. Before that the @file{Makefile.in}s generated for
11505 maintainers required GNU @command{make} and GCC, they were different
11506 from the portable @file{Makefile} generated for distribution; this was
11507 causing some confusion.
11509 @item Support for per-target compilation flags.
11511 @item Support for reference to files in subdirectories in most
11512 @file{Makefile.am} variables.
11514 @item Introduction of the @code{dist_}, @code{nodist_}, and @code{nobase_}
11516 @item Perl 4 support is finally dropped.
11519 1.5 did broke several packages that worked with 1.4. Enough so that
11520 Linux distributions could not easily install the new Automake version
11521 without breaking many of the packages for which they had to run
11522 @command{automake}.
11524 Some of these breakages were effectively bugs that would eventually be
11525 fixed in the next release. However, a lot of damage was caused by
11526 some changes made deliberately to render Automake stricter on some
11527 setup we did consider bogus. For instance, @samp{make distcheck} was
11528 improved to check that @samp{make uninstall} did remove all the files
11529 @samp{make install} installed, that @samp{make distclean} did not omit
11530 some file, and that a VPATH build would work even if the source
11531 directory was read-only. Similarly, Automake now rejects multiple
11532 definitions of the same variable (because that would mix very badly
11533 with conditionals), and @samp{+=} assignments with no previous
11534 definition. Because these changes all occurred suddenly after 1.4 had
11535 been established for more than two years, it hurt users.
11537 To make matter worse, meanwhile Autoconf (now at version 2.52) was
11538 facing similar troubles, for similar reasons.
11540 @item 2002-03-05 Automake 1.6
11542 This release introduced versioned installation (@pxref{API
11543 versioning}). This was mainly pushed by Havoc Pennington, taking the
11544 GNOME source tree as motive: due to incompatibilities between the
11545 autotools it's impossible for the GNOME packages to switch to Autoconf
11546 2.53 and Automake 1.5 all at once, so they are currently stuck with
11547 Autoconf 2.13 and Automake 1.4.
11549 The idea was to call this version @file{automake-1.6}, call all its
11550 bug-fix versions identically, and switch to @file{automake-1.7} for
11551 the next release that adds new features or changes some rules. This
11552 scheme implies maintaining a bug-fix branch in addition to the
11553 development trunk, which means more work from the maintainer, but
11554 providing regular bug-fix releases proved to be really worthwhile.
11556 Like 1.5, 1.6 also introduced a bunch of incompatibilities, meant or
11557 not. Perhaps the more annoying was the dependence on the newly
11558 released Autoconf 2.53. Autoconf seemed to have stabilized enough
11559 since its explosive 2.50 release, and included changes required to fix
11560 some bugs in Automake. In order to upgrade to Automake 1.6, people
11561 now had to upgrade Autoconf too; for some packages it was no picnic.
11563 While versioned installation helped people to upgrade, it also
11564 unfortunately allowed people not to upgrade. At the time of writing,
11565 some Linux distributions are shipping packages for Automake 1.4, 1.5,
11566 1.6, 1.7, 1.8, and 1.9. Most of these still install 1.4 by default.
11567 Some distribution also call 1.4 the ``stable'' version, and present
11568 ``1.9'' as the development version; this does not really makes sense
11569 since 1.9 is way more solid than 1.4. All this does not help the
11572 @item 2002-04-11 Automake 1.6.1
11574 1.6, and the upcoming 1.4-p6 release were the last release by Tom.
11575 This one and those following will be handled by Alexandre
11576 Duret-Lutz. Tom is still around, and will be there until about 1.7,
11577 but his interest into Automake is drifting away towards projects like
11580 Alexandre has been using Automake since 2000, and started to
11581 contribute mostly on Akim's incitement (Akim and Alexandre have been
11582 working in the same room from 1999 to 2002). In 2001 and 2002 he had
11583 a lot of free time to enjoy hacking Automake.
11585 @item 2002-06-14 Automake 1.6.2
11587 @item 2002-07-28 Automake 1.6.3
11588 @itemx 2002-07-28 Automake 1.4-p6
11590 Two releases on the same day. 1.6.3 is a bug-fix release.
11592 Tom Tromey backported the versioned installation mechanism on the 1.4
11593 branch, so that Automake 1.6.x and Automake 1.4-p6 could be installed
11594 side by side. Another request from the GNOME folks.
11596 @item 2002-09-25 Automake 1.7
11598 This release switches to the new @file{configure.ac} scanner Akim
11599 was experimenting in 1.5.
11601 @item 2002-10-16 Automake 1.7.1
11602 @itemx 2002-12-06 Automake 1.7.2
11603 @itemx 2003-02-20 Automake 1.7.3
11604 @itemx 2003-04-23 Automake 1.7.4
11605 @itemx 2003-05-18 Automake 1.7.5
11606 @itemx 2003-07-10 Automake 1.7.6
11607 @itemx 2003-09-07 Automake 1.7.7
11608 @itemx 2003-10-07 Automake 1.7.8
11610 Many bug-fix releases. 1.7 lasted because the development version
11611 (upcoming 1.8) was suffering some major internal revamping.
11613 @item 2003-10-26 Automake on screen
11615 Episode 49, `Repercussions', in the third season of the `Alias' TV
11616 show is first aired.
11618 Marshall, one of the character, is working on a computer virus that he
11619 has to modify before it gets into the wrong hands or something like
11620 that. The screenshots you see do not show any program code, they show
11621 a @file{Makefile.in} @code{generated by automake}...
11623 @item 2003-11-09 Automake 1.7.9
11625 @item 2003-12-10 Automake 1.8
11627 The most striking update is probably that of @command{aclocal}.
11629 @command{aclocal} now uses @code{m4_include} in the produced
11630 @file{aclocal.m4} when the included macros are already distributed
11631 with the package (an idiom used in many packages), which reduces code
11632 duplication. Many people liked that, but in fact this change was
11633 really introduced to fix a bug in rebuild rules: @file{Makefile.in}
11634 must be rebuilt whenever a dependency of @file{configure} changes, but
11635 all the @file{m4} files included in @file{aclocal.m4} where unknown
11636 from @command{automake}. Now @command{automake} can just trace the
11637 @code{m4_include}s to discover the dependencies.
11639 @command{aclocal} also starts using the @option{--trace} Autoconf option
11640 in order to discover used macros more accurately. This will turn out
11641 to be very tricky (later releases will improve this) as people had
11642 devised many ways to cope with the limitation of previous
11643 @command{aclocal} versions, notably using handwritten
11644 @code{m4_include}s: @command{aclocal} must make sure not to redefine a
11645 rule that is already included by such statement.
11647 Automake also has seen its guts rewritten. Although this rewriting
11648 took a lot of efforts, it is only apparent to the users in that some
11649 constructions previously disallowed by the implementation now work
11650 nicely. Conditionals, Locations, Variable and Rule definitions,
11651 Options: these items on which Automake works have been rewritten as
11652 separate Perl modules, and documented.
11654 @itemx 2004-01-11 Automake 1.8.1
11655 @itemx 2004-01-12 Automake 1.8.2
11656 @itemx 2004-03-07 Automake 1.8.3
11657 @itemx 2004-04-25 Automake 1.8.4
11658 @itemx 2004-05-16 Automake 1.8.5
11660 @item 2004-07-28 Automake 1.9
11662 This release tries to simplify the compilation rules it outputs to
11663 reduce the size of the Makefile. The complaint initially come from
11664 the libgcj developers. Their @file{Makefile.in} generated with
11665 Automake 1.4 and custom build rules (1.4 did not support compiled
11666 Java) is 250KB@. The one generated by 1.8 was over 9MB@! 1.9 gets it
11669 Aside from this it contains mainly minor changes and bug-fixes.
11671 @itemx 2004-08-11 Automake 1.9.1
11672 @itemx 2004-09-19 Automake 1.9.2
11674 Automake has ten years. This chapter of the manual was initially
11675 written for this occasion.
11677 @itemx 2007-10-29 Automake repository moves to @code{savannah.gnu.org} and uses
11678 git as primary repository.
11682 @node Dependency Tracking Evolution
11683 @section Dependency Tracking in Automake
11685 Over the years Automake has deployed three different dependency
11686 tracking methods. Each method, including the current one, has had
11687 flaws of various sorts. Here we lay out the different dependency
11688 tracking methods, their flaws, and their fixes. We conclude with
11689 recommendations for tool writers, and by indicating future directions
11690 for dependency tracking work in Automake.
11692 @subsection First Take
11693 @unnumberedsubsubsec Description
11695 Our first attempt at automatic dependency tracking was based on the
11696 method recommended by GNU @command{make}. (@pxref{Automatic
11697 Prerequisites, , Generating Prerequisites Automatically, make, The GNU
11700 This version worked by precomputing dependencies ahead of time. For
11701 each source file, it had a special @file{.P} file that held the
11702 dependencies. There was a rule to generate a @file{.P} file by
11703 invoking the compiler appropriately. All such @file{.P} files were
11704 included by the @file{Makefile}, thus implicitly becoming dependencies
11705 of @file{Makefile}.
11707 @unnumberedsubsubsec Bugs
11709 This approach had several critical bugs.
11713 The code to generate the @file{.P} file relied on @command{gcc}.
11714 (A limitation, not technically a bug.)
11716 The dependency tracking mechanism itself relied on GNU @command{make}.
11717 (A limitation, not technically a bug.)
11719 Because each @file{.P} file was a dependency of @file{Makefile}, this
11720 meant that dependency tracking was done eagerly by @command{make}.
11721 For instance, @samp{make clean} would cause all the dependency files
11722 to be updated, and then immediately removed. This eagerness also
11723 caused problems with some configurations; if a certain source file
11724 could not be compiled on a given architecture for some reason,
11725 dependency tracking would fail, aborting the entire build.
11727 As dependency tracking was done as a pre-pass, compile times were
11728 doubled--the compiler had to be run twice per source file.
11730 @samp{make dist} re-ran @command{automake} to generate a
11731 @file{Makefile} that did not have automatic dependency tracking (and
11732 that was thus portable to any version of @command{make}). In order to
11733 do this portably, Automake had to scan the dependency files and remove
11734 any reference that was to a source file not in the distribution.
11735 This process was error-prone. Also, if @samp{make dist} was run in an
11736 environment where some object file had a dependency on a source file
11737 that was only conditionally created, Automake would generate a
11738 @file{Makefile} that referred to a file that might not appear in the
11739 end user's build. A special, hacky mechanism was required to work
11743 @unnumberedsubsubsec Historical Note
11745 The code generated by Automake is often inspired by the
11746 @file{Makefile} style of a particular author. In the case of the first
11747 implementation of dependency tracking, I believe the impetus and
11748 inspiration was Jim Meyering. (I could be mistaken. If you know
11749 otherwise feel free to correct me.)
11751 @subsection Dependencies As Side Effects
11752 @unnumberedsubsubsec Description
11754 The next refinement of Automake's automatic dependency tracking scheme
11755 was to implement dependencies as side effects of the compilation.
11756 This was aimed at solving the most commonly reported problems with the
11757 first approach. In particular we were most concerned with eliminating
11758 the weird rebuilding effect associated with make clean.
11760 In this approach, the @file{.P} files were included using the
11761 @code{-include} command, which let us create these files lazily. This
11762 avoided the @samp{make clean} problem.
11764 We only computed dependencies when a file was actually compiled. This
11765 avoided the performance penalty associated with scanning each file
11766 twice. It also let us avoid the other problems associated with the
11767 first, eager, implementation. For instance, dependencies would never
11768 be generated for a source file that was not compilable on a given
11769 architecture (because it in fact would never be compiled).
11771 @unnumberedsubsubsec Bugs
11775 This approach also relied on the existence of @command{gcc} and GNU
11776 @command{make}. (A limitation, not technically a bug.)
11778 Dependency tracking was still done by the developer, so the problems
11779 from the first implementation relating to massaging of dependencies by
11780 @samp{make dist} were still in effect.
11782 This implementation suffered from the ``deleted header file'' problem.
11783 Suppose a lazily-created @file{.P} file includes a dependency on a
11784 given header file, like this:
11787 maude.o: maude.c something.h
11790 Now suppose that the developer removes @file{something.h} and updates
11791 @file{maude.c} so that this include is no longer needed. If he runs
11792 @command{make}, he will get an error because there is no way to create
11793 @file{something.h}.
11795 We fixed this problem in a later release by further massaging the
11796 output of @command{gcc} to include a dummy dependency for each header
11800 @subsection Dependencies for the User
11801 @unnumberedsubsubsec Description
11803 The bugs associated with @samp{make dist}, over time, became a real
11804 problem. Packages using Automake were being built on a large number
11805 of platforms, and were becoming increasingly complex. Broken
11806 dependencies were distributed in ``portable'' @file{Makefile.in}s,
11807 leading to user complaints. Also, the requirement for @command{gcc}
11808 and GNU @command{make} was a constant source of bug reports. The next
11809 implementation of dependency tracking aimed to remove these problems.
11811 We realized that the only truly reliable way to automatically track
11812 dependencies was to do it when the package itself was built. This
11813 meant discovering a method portable to any version of make and any
11814 compiler. Also, we wanted to preserve what we saw as the best point
11815 of the second implementation: dependency computation as a side effect
11818 In the end we found that most modern make implementations support some
11819 form of include directive. Also, we wrote a wrapper script that let
11820 us abstract away differences between dependency tracking methods for
11821 compilers. For instance, some compilers cannot generate dependencies
11822 as a side effect of compilation. In this case we simply have the
11823 script run the compiler twice. Currently our wrapper script
11824 (@command{depcomp}) knows about twelve different compilers (including
11825 a "compiler" that simply invokes @command{makedepend} and then the
11826 real compiler, which is assumed to be a standard Unix-like C compiler
11827 with no way to do dependency tracking).
11829 @unnumberedsubsubsec Bugs
11833 Running a wrapper script for each compilation slows down the build.
11835 Many users don't really care about precise dependencies.
11837 This implementation, like every other automatic dependency tracking
11838 scheme in common use today (indeed, every one we've ever heard of),
11839 suffers from the ``duplicated new header'' bug.
11841 This bug occurs because dependency tracking tools, such as the
11842 compiler, only generate dependencies on the successful opening of a
11843 file, and not on every probe.
11845 Suppose for instance that the compiler searches three directories for
11846 a given header, and that the header is found in the third directory.
11847 If the programmer erroneously adds a header file with the same name to
11848 the first directory, then a clean rebuild from scratch could fail
11849 (suppose the new header file is buggy), whereas an incremental rebuild
11852 What has happened here is that people have a misunderstanding of what
11853 a dependency is. Tool writers think a dependency encodes information
11854 about which files were read by the compiler. However, a dependency
11855 must actually encode information about what the compiler tried to do.
11857 This problem is not serious in practice. Programmers typically do not
11858 use the same name for a header file twice in a given project. (At
11859 least, not in C or C++. This problem may be more troublesome in
11860 Java.) This problem is easy to fix, by modifying dependency
11861 generators to record every probe, instead of every successful open.
11864 Since automake generates dependencies as a side effect of compilation,
11865 there is a bootstrapping problem when header files are generated by
11866 running a program. The problem is that, the first time the build is
11867 done, there is no way by default to know that the headers are
11868 required, so make might try to run a compilation for which the headers
11869 have not yet been built.
11871 This was also a problem in the previous dependency tracking implementation.
11873 The current fix is to use @code{BUILT_SOURCES} to list built headers
11874 (@pxref{Sources}). This causes them to be built before any other
11875 build rules are run. This is unsatisfactory as a general solution,
11876 however in practice it seems sufficient for most actual programs.
11879 This code is used since Automake 1.5.
11881 In GCC 3.0, we managed to convince the maintainers to add special
11882 command-line options to help Automake more efficiently do its job. We
11883 hoped this would let us avoid the use of a wrapper script when
11884 Automake's automatic dependency tracking was used with @command{gcc}.
11886 Unfortunately, this code doesn't quite do what we want. In
11887 particular, it removes the dependency file if the compilation fails;
11888 we'd prefer that it instead only touch the file in any way if the
11889 compilation succeeds.
11891 Nevertheless, since Automake 1.7, when a recent @command{gcc} is
11892 detected at @command{configure} time, we inline the
11893 dependency-generation code and do not use the @command{depcomp}
11894 wrapper script. This makes compilations faster for those using this
11895 compiler (probably our primary user base). The counterpart is that
11896 because we have to encode two compilation rules in @file{Makefile}
11897 (with or without @command{depcomp}), the produced @file{Makefile}s are
11900 @subsection Techniques for Computing Dependencies
11902 There are actually several ways for a build tool like Automake to
11903 cause tools to generate dependencies.
11906 @item @command{makedepend}
11907 This was a commonly-used method in the past. The idea is to run a
11908 special program over the source and have it generate dependency
11909 information. Traditional implementations of @command{makedepend} are
11910 not completely precise; ordinarily they were conservative and
11911 discovered too many dependencies.
11913 An obvious way to generate dependencies is to simply write the tool so
11914 that it can generate the information needed by the build tool. This is
11915 also the most portable method. Many compilers have an option to
11916 generate dependencies. Unfortunately, not all tools provide such an
11918 @item The file system
11919 It is possible to write a special file system that tracks opens,
11920 reads, writes, etc, and then feed this information back to the build
11921 tool. @command{clearmake} does this. This is a very powerful
11922 technique, as it doesn't require cooperation from the
11923 tool. Unfortunately it is also very difficult to implement and also
11924 not practical in the general case.
11925 @item @code{LD_PRELOAD}
11926 Rather than use the file system, one could write a special library to
11927 intercept @code{open} and other syscalls. This technique is also quite
11928 powerful, but unfortunately it is not portable enough for use in
11929 @command{automake}.
11932 @subsection Recommendations for Tool Writers
11934 We think that every compilation tool ought to be able to generate
11935 dependencies as a side effect of compilation. Furthermore, at least
11936 while @command{make}-based tools are nearly universally in use (at
11937 least in the free software community), the tool itself should generate
11938 dummy dependencies for header files, to avoid the deleted header file
11939 bug. Finally, the tool should generate a dependency for each probe,
11940 instead of each successful file open, in order to avoid the duplicated
11943 @subsection Future Directions for Automake's Dependency Tracking
11945 Currently, only languages and compilers understood by Automake can
11946 have dependency tracking enabled. We would like to see if it is
11947 practical (and worthwhile) to let this support be extended by the user
11948 to languages unknown to Automake.
11951 @section Release Statistics
11953 The following table (inspired by @samp{perlhist(1)}) quantifies the
11954 evolution of Automake using these metrics:
11958 The date and version of the release.
11960 The number of lines of the @command{automake} script.
11962 The number of lines of the @command{aclocal} script.
11964 The number of lines of the @command{Perl} supporting modules.
11966 The number of lines of the @file{Makefile} fragments. The number in parenthesis
11967 is the number of files.
11969 The number of lines (and files) of Autoconf macros.
11971 The number of pages of the documentation (the Postscript version).
11973 The number of test cases in the test suite.
11976 @multitable {8888-88-88} {8.8-p8} {8888} {8888} {8888} {8888 (88)} {8888 (88)} {888} {888}
11977 @headitem Date @tab Rel @tab am @tab acl @tab pm @tab @file{*.am} @tab m4 @tab doc @tab t
11978 @item 1994-09-19 @tab CVS @tab 141 @tab @tab @tab 299 (24) @tab @tab @tab
11979 @item 1994-11-05 @tab CVS @tab 208 @tab @tab @tab 332 (28) @tab @tab @tab
11980 @item 1995-11-23 @tab 0.20 @tab 533 @tab @tab @tab 458 (35) @tab @tab 9 @tab
11981 @item 1995-11-26 @tab 0.21 @tab 613 @tab @tab @tab 480 (36) @tab @tab 11 @tab
11982 @item 1995-11-28 @tab 0.22 @tab 1116 @tab @tab @tab 539 (38) @tab @tab 12 @tab
11983 @item 1995-11-29 @tab 0.23 @tab 1240 @tab @tab @tab 541 (38) @tab @tab 12 @tab
11984 @item 1995-12-08 @tab 0.24 @tab 1462 @tab @tab @tab 504 (33) @tab @tab 14 @tab
11985 @item 1995-12-10 @tab 0.25 @tab 1513 @tab @tab @tab 511 (37) @tab @tab 15 @tab
11986 @item 1996-01-03 @tab 0.26 @tab 1706 @tab @tab @tab 438 (36) @tab @tab 16 @tab
11987 @item 1996-01-03 @tab 0.27 @tab 1706 @tab @tab @tab 438 (36) @tab @tab 16 @tab
11988 @item 1996-01-13 @tab 0.28 @tab 1964 @tab @tab @tab 934 (33) @tab @tab 16 @tab
11989 @item 1996-02-07 @tab 0.29 @tab 2299 @tab @tab @tab 936 (33) @tab @tab 17 @tab
11990 @item 1996-02-24 @tab 0.30 @tab 2544 @tab @tab @tab 919 (32) @tab 85 (1) @tab 20 @tab 9
11991 @item 1996-03-11 @tab 0.31 @tab 2877 @tab @tab @tab 919 (32) @tab 85 (1) @tab 29 @tab 17
11992 @item 1996-04-27 @tab 0.32 @tab 3058 @tab @tab @tab 921 (31) @tab 85 (1) @tab 30 @tab 26
11993 @item 1996-05-18 @tab 0.33 @tab 3110 @tab @tab @tab 926 (31) @tab 105 (1) @tab 30 @tab 35
11994 @item 1996-05-28 @tab 1.0 @tab 3134 @tab @tab @tab 973 (32) @tab 105 (1) @tab 30 @tab 38
11995 @item 1997-06-22 @tab 1.2 @tab 6089 @tab 385 @tab @tab 1294 (36) @tab 592 (20) @tab 37 @tab 126
11996 @item 1998-04-05 @tab 1.3 @tab 6415 @tab 422 @tab @tab 1470 (39) @tab 741 (23) @tab 39 @tab 156
11997 @item 1999-01-14 @tab 1.4 @tab 7240 @tab 426 @tab @tab 1591 (40) @tab 734 (20) @tab 51 @tab 197
11998 @item 2001-05-08 @tab 1.4-p1 @tab 7251 @tab 426 @tab @tab 1591 (40) @tab 734 (20) @tab 51 @tab 197
11999 @item 2001-05-24 @tab 1.4-p2 @tab 7268 @tab 439 @tab @tab 1591 (40) @tab 734 (20) @tab 49 @tab 197
12000 @item 2001-06-07 @tab 1.4-p3 @tab 7312 @tab 439 @tab @tab 1591 (40) @tab 734 (20) @tab 49 @tab 197
12001 @item 2001-06-10 @tab 1.4-p4 @tab 7321 @tab 439 @tab @tab 1591 (40) @tab 734 (20) @tab 49 @tab 198
12002 @item 2001-07-15 @tab 1.4-p5 @tab 7228 @tab 426 @tab @tab 1596 (40) @tab 734 (20) @tab 51 @tab 198
12003 @item 2001-08-23 @tab 1.5 @tab 8016 @tab 475 @tab 600 @tab 2654 (39) @tab 1166 (29) @tab 63 @tab 327
12004 @item 2002-03-05 @tab 1.6 @tab 8465 @tab 475 @tab 1136 @tab 2732 (39) @tab 1603 (27) @tab 66 @tab 365
12005 @item 2002-04-11 @tab 1.6.1 @tab 8544 @tab 475 @tab 1136 @tab 2741 (39) @tab 1603 (27) @tab 66 @tab 372
12006 @item 2002-06-14 @tab 1.6.2 @tab 8575 @tab 475 @tab 1136 @tab 2800 (39) @tab 1609 (27) @tab 67 @tab 386
12007 @item 2002-07-28 @tab 1.6.3 @tab 8600 @tab 475 @tab 1153 @tab 2809 (39) @tab 1609 (27) @tab 67 @tab 391
12008 @item 2002-07-28 @tab 1.4-p6 @tab 7332 @tab 455 @tab @tab 1596 (40) @tab 735 (20) @tab 49 @tab 197
12009 @item 2002-09-25 @tab 1.7 @tab 9189 @tab 471 @tab 1790 @tab 2965 (39) @tab 1606 (28) @tab 73 @tab 430
12010 @item 2002-10-16 @tab 1.7.1 @tab 9229 @tab 475 @tab 1790 @tab 2977 (39) @tab 1606 (28) @tab 73 @tab 437
12011 @item 2002-12-06 @tab 1.7.2 @tab 9334 @tab 475 @tab 1790 @tab 2988 (39) @tab 1606 (28) @tab 77 @tab 445
12012 @item 2003-02-20 @tab 1.7.3 @tab 9389 @tab 475 @tab 1790 @tab 3023 (39) @tab 1651 (29) @tab 84 @tab 448
12013 @item 2003-04-23 @tab 1.7.4 @tab 9429 @tab 475 @tab 1790 @tab 3031 (39) @tab 1644 (29) @tab 85 @tab 458
12014 @item 2003-05-18 @tab 1.7.5 @tab 9429 @tab 475 @tab 1790 @tab 3033 (39) @tab 1645 (29) @tab 85 @tab 459
12015 @item 2003-07-10 @tab 1.7.6 @tab 9442 @tab 475 @tab 1790 @tab 3033 (39) @tab 1660 (29) @tab 85 @tab 461
12016 @item 2003-09-07 @tab 1.7.7 @tab 9443 @tab 475 @tab 1790 @tab 3041 (39) @tab 1660 (29) @tab 90 @tab 467
12017 @item 2003-10-07 @tab 1.7.8 @tab 9444 @tab 475 @tab 1790 @tab 3041 (39) @tab 1660 (29) @tab 90 @tab 468
12018 @item 2003-11-09 @tab 1.7.9 @tab 9444 @tab 475 @tab 1790 @tab 3048 (39) @tab 1660 (29) @tab 90 @tab 468
12019 @item 2003-12-10 @tab 1.8 @tab 7171 @tab 585 @tab 7730 @tab 3236 (39) @tab 1666 (31) @tab 104 @tab 521
12020 @item 2004-01-11 @tab 1.8.1 @tab 7217 @tab 663 @tab 7726 @tab 3287 (39) @tab 1686 (31) @tab 104 @tab 525
12021 @item 2004-01-12 @tab 1.8.2 @tab 7217 @tab 663 @tab 7726 @tab 3288 (39) @tab 1686 (31) @tab 104 @tab 526
12022 @item 2004-03-07 @tab 1.8.3 @tab 7214 @tab 686 @tab 7735 @tab 3303 (39) @tab 1695 (31) @tab 111 @tab 530
12023 @item 2004-04-25 @tab 1.8.4 @tab 7214 @tab 686 @tab 7736 @tab 3310 (39) @tab 1701 (31) @tab 112 @tab 531
12024 @item 2004-05-16 @tab 1.8.5 @tab 7240 @tab 686 @tab 7736 @tab 3299 (39) @tab 1701 (31) @tab 112 @tab 533
12025 @item 2004-07-28 @tab 1.9 @tab 7508 @tab 715 @tab 7794 @tab 3352 (40) @tab 1812 (32) @tab 115 @tab 551
12026 @item 2004-08-11 @tab 1.9.1 @tab 7512 @tab 715 @tab 7794 @tab 3354 (40) @tab 1812 (32) @tab 115 @tab 552
12027 @item 2004-09-19 @tab 1.9.2 @tab 7512 @tab 715 @tab 7794 @tab 3354 (40) @tab 1812 (32) @tab 132 @tab 554
12028 @item 2004-11-01 @tab 1.9.3 @tab 7507 @tab 718 @tab 7804 @tab 3354 (40) @tab 1812 (32) @tab 134 @tab 556
12029 @item 2004-12-18 @tab 1.9.4 @tab 7508 @tab 718 @tab 7856 @tab 3361 (40) @tab 1811 (32) @tab 140 @tab 560
12030 @item 2005-02-13 @tab 1.9.5 @tab 7523 @tab 719 @tab 7859 @tab 3373 (40) @tab 1453 (32) @tab 142 @tab 562
12031 @item 2005-07-10 @tab 1.9.6 @tab 7539 @tab 699 @tab 7867 @tab 3400 (40) @tab 1453 (32) @tab 144 @tab 570
12032 @item 2006-10-15 @tab 1.10 @tab 7859 @tab 1072 @tab 8024 @tab 3512 (40) @tab 1496 (34) @tab 172 @tab 604
12036 @c ========================================================== Appendices
12039 @node Copying This Manual
12040 @appendix Copying This Manual
12043 * GNU Free Documentation License:: License for copying this manual
12053 * Macro Index:: Index of Autoconf macros
12054 * Variable Index:: Index of Makefile variables
12055 * General Index:: General index
12059 @appendixsec Macro Index
12063 @node Variable Index
12064 @appendixsec Variable Index
12068 @node General Index
12069 @appendixsec General Index
12078 @c LocalWords: texinfo setfilename settitle setchapternewpage texi direntry
12079 @c LocalWords: dircategory in's aclocal ifinfo titlepage Tromey vskip pt sp
12080 @c LocalWords: filll defcodeindex ov cv op tr syncodeindex fn cp vr ifnottex
12081 @c LocalWords: dir Automake's ac Dist Gnits gnits cygnus dfn Autoconf's pxref
12082 @c LocalWords: cindex Autoconf autoconf perl samp cvs dist trindex SUBST foo
12083 @c LocalWords: xs emph FIXME ref vindex pkglibdir pkgincludedir pkgdatadir mt
12084 @c LocalWords: pkg libdir cpio bindir sbindir rmt pax sbin zar zardir acindex
12085 @c LocalWords: HTML htmldir html noinst TEXINFOS nodist nobase strudel CFLAGS
12086 @c LocalWords: libmumble CC YFLAGS ansi knr itemx de fication config url comp
12087 @c LocalWords: depcomp elisp sh mdate mkinstalldirs mkdir py tex dvi ps pdf
12088 @c LocalWords: ylwrap zardoz INIT gettext acinclude mv FUNCS LIBOBJS LDADD fr
12089 @c LocalWords: uref featureful dnl src LINGUAS es ko nl pl sl sv PROG ISC doc
12090 @c LocalWords: POSIX STDC fcntl FUNC ALLOCA blksize struct stat intl po chmod
12091 @c LocalWords: ChangeLog SUBDIRS gettextize gpl testdata getopt INTLLIBS cpp
12092 @c LocalWords: localedir datadir DLOCALEDIR DEXIT CPPFLAGS autoreconf opindex
12093 @c LocalWords: AUX var symlink deps Wno Wnone package's aclocal's distclean
12094 @c LocalWords: ltmain xref LIBSOURCE LIBSOURCES LIBOBJ MEMCMP vs RANLIB CXX
12095 @c LocalWords: LDFLAGS LIBTOOL libtool XTRA LIBS gettext's acdir APIVERSION
12096 @c LocalWords: dirlist noindent usr MULTILIB multilib Multilibs TIOCGWINSZ sc
12097 @c LocalWords: GWINSZ termios SRCDIR tarball bzip LISPDIR lispdir XEmacs CCAS
12098 @c LocalWords: emacsen MicroEmacs CCASFLAGS UX GCJ gcj GCJFLAGS posix DMALLOC
12099 @c LocalWords: dmalloc ldmalloc REGEX regex rx DEPDIR DEP DEFUN aclocaldir fi
12100 @c LocalWords: mymacro myothermacro AMFLAGS autopoint autogen libtoolize yum
12101 @c LocalWords: autoheader README MAKEFLAGS subdir Inetutils sync COND endif
12102 @c LocalWords: Miller's installable includedir inc pkgdata EXEEXT libexec bsd
12103 @c LocalWords: pkglib libexecdir prog libcpio cpio's dlopen dlpreopen linux
12104 @c LocalWords: subsubsection OBJEXT esac lib LTLIBRARIES liblob LIBADD AR ar
12105 @c LocalWords: ARFLAGS cru ing maude libgettext lo LTLIBOBJS rpath SGI PRE yy
12106 @c LocalWords: libmaude CCLD CXXFLAGS FFLAGS LFLAGS OBJCFLAGS RFLAGS DEFS cc
12107 @c LocalWords: SHORTNAME vtable srcdir nostdinc basename yxx cxx ll lxx gdb
12108 @c LocalWords: lexers yymaxdepth maxdepth yyparse yylex yyerror yylval lval
12109 @c LocalWords: yychar yydebug yypact yyr yydef def yychk chk yypgo pgo yyact
12110 @c LocalWords: yyexca exca yyerrflag errflag yynerrs nerrs yyps yypv pv yys
12111 @c LocalWords: yystate yytmp tmp yyv yyval val yylloc lloc yyreds yytoks toks
12112 @c LocalWords: yylhs yylen yydefred yydgoto yysindex yyrindex yygindex yyname
12113 @c LocalWords: yytable yycheck yyrule byacc CXXCOMPILE CXXLINK FLINK cfortran
12114 @c LocalWords: Catalogue preprocessable FLIBS libfoo baz JAVACFLAGS java exe
12115 @c LocalWords: SunOS fying basenames exeext uninstalled oldinclude kr FSF's
12116 @c LocalWords: pkginclude oldincludedir sysconf sharedstate localstate gcc rm
12117 @c LocalWords: sysconfdir sharedstatedir localstatedir preexist CLEANFILES gz
12118 @c LocalWords: unnumberedsubsec depfile tmpdepfile depmode const interoperate
12119 @c LocalWords: JAVAC javac JAVAROOT builddir CLASSPATH ENV pyc pyo pkgpython
12120 @c LocalWords: pyexecdir pkgpyexecdir Python's pythondir pkgpythondir txi ois
12121 @c LocalWords: installinfo vers MAKEINFO makeinfo MAKEINFOFLAGS noinstall rf
12122 @c LocalWords: mandir thesame alsothesame installman myexecbin DESTDIR Pinard
12123 @c LocalWords: uninstall installdirs uninstalls MOSTLYCLEANFILES mostlyclean
12124 @c LocalWords: DISTCLEANFILES MAINTAINERCLEANFILES GZIP gzip shar exp
12125 @c LocalWords: distdir distcheck distcleancheck listfiles distuninstallcheck
12126 @c LocalWords: VPATH tarfile stdout XFAIL DejaGnu dejagnu DEJATOOL runtest ln
12127 @c LocalWords: RUNTESTDEFAULTFLAGS toolchain RUNTESTFLAGS asis readme DVIPS
12128 @c LocalWords: installcheck gzipped tarZ std utils etags mkid multilibbing cd
12129 @c LocalWords: ARGS taggable ETAGSFLAGS lang ctags CTAGSFLAGS GTAGS gtags idl
12130 @c LocalWords: foocc doit idlC multilibs ABIs cmindex defmac ARG enableval FC
12131 @c LocalWords: MSG xtrue DBG pathchk CYGWIN afile proglink versioned CVS's TE
12132 @c LocalWords: wildcards Autoconfiscated subsubheading autotools Meyering API
12133 @c LocalWords: ois's wildcard Wportability cartouche vrindex printindex Duret
12134 @c LocalWords: DSOMEFLAG DVERSION automake Lutz insertcopying versioning FAQ
12135 @c LocalWords: LTLIBOBJ Libtool's libtool's libltdl dlopening itutions libbar
12136 @c LocalWords: WANTEDLIBS libhello sublibraries libtop libsub dlopened Ratfor
12137 @c LocalWords: mymodule timestamps timestamp underquoted MAKEINFOHTMLFLAGS te
12138 @c LocalWords: GNUmakefile Subpackages subpackage's subpackages aux
12139 @c LocalWords: detailmenu Timeline pwd reldir AUTOM autom PREREQ FOOBAR libc
12140 @c LocalWords: libhand subpackage moduleN libmain libmisc FCFLAGS FCCOMPILE
12141 @c LocalWords: FCLINK subst sed ELCFILES elc MAKEINFOHTML dvips esyscmd ustar
12142 @c LocalWords: tarballs Woverride vfi ELFILES djm AutoMake honkin FSF
12143 @c LocalWords: fileutils precanned MacKenzie's reimplement termutils Tromey's
12144 @c LocalWords: cois gnitsians LIBPROGRAMS progs LIBLIBRARIES Textutils Ulrich
12145 @c LocalWords: Matzigkeit Drepper's Gord Matzigkeit's jm Dalley Debian org
12146 @c LocalWords: Administrivia ILU CORBA Sourceware Molenda sourceware Elliston
12147 @c LocalWords: dep Oliva Akim Demaille Aiieeee Demaillator Akim's sourcequake
12148 @c LocalWords: grep backported screenshots libgcj KB unnumberedsubsubsec pre
12149 @c LocalWords: precomputing hacky makedepend inline clearmake LD PRELOAD Rel
12150 @c LocalWords: syscalls perlhist acl pm multitable headitem fdl appendixsec
12151 @c LocalWords: LTALLOCA MALLOC malloc memcmp strdup alloca libcompat xyz DFOO
12152 @c LocalWords: unprefixed buildable preprocessed DBAZ DDATADIR WARNINGCFLAGS
12153 @c LocalWords: LIBFOOCFLAGS LIBFOOLDFLAGS ftable testSubDir obj LIBTOOLFLAGS
12154 @c LocalWords: barexec Pinard's automatize initialize lzma