1 \input texinfo @c -*-texinfo-*-
3 @setfilename automake.info
12 This manual is for @acronym{GNU} Automake (version @value{VERSION},
13 @value{UPDATED}), a program that creates GNU standards-compliant
14 Makefiles from template files.
16 Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
17 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
20 Permission is granted to copy, distribute and/or modify this document
21 under the terms of the @acronym{GNU} Free Documentation License,
22 Version 1.2 or any later version published by the Free Software
23 Foundation; with no Invariant Sections, with no Front-Cover texts,
24 and with no Back-Cover Texts. A copy of the license is included in the
25 section entitled ``@acronym{GNU} Free Documentation License.''
30 @c info Automake points to the Automake package's documentation
31 @c info automake points to the automake script's documentation
32 @c (Autoconf has a similar setup.)
33 @dircategory Software development
35 * Automake: (automake). Making GNU standards-compliant Makefiles.
38 @dircategory Individual utilities
40 * aclocal: (automake)Invoking aclocal. Generating aclocal.m4.
41 * automake: (automake)Invoking Automake. Generating Makefile.in.
46 @subtitle For version @value{VERSION}, @value{UPDATED}
47 @author David MacKenzie
49 @author Alexandre Duret-Lutz
51 @vskip 0pt plus 1filll
56 @c We use the following macros to define indices:
57 @c @cindex concepts, and anything that does not fit elsewhere
58 @c @vindex Makefile variables
60 @c @acindex Autoconf/Automake/Libtool/M4/... macros
61 @c @opindex tool options
63 @c Define an index of configure macros.
65 @c Define an index of options.
67 @c Define an index of targets.
69 @c Define an index of commands.
72 @c Put the macros in the function index.
75 @c Put everything else into one index (arbitrarily chosen to be the concept index).
82 @comment node-name, next, previous, up
88 * Introduction:: Automake's purpose
89 * Autotools Introduction:: An Introduction to the Autotools
90 * Generalities:: General ideas
91 * Examples:: Some example packages
92 * Invoking Automake:: Creating a Makefile.in
93 * configure:: Scanning configure.ac or configure.in
94 * Directories:: Declaring subdirectories
95 * Programs:: Building programs and libraries
96 * Other objects:: Other derived objects
97 * Other GNU Tools:: Other GNU Tools
98 * Documentation:: Building documentation
99 * Install:: What gets installed
100 * Clean:: What gets cleaned
101 * Dist:: What goes in a distribution
102 * Tests:: Support for test suites
103 * Rebuilding:: Automatic rebuilding of Makefile
104 * Options:: Changing Automake's behavior
105 * Miscellaneous:: Miscellaneous rules
106 * Include:: Including extra files in an Automake template.
107 * Conditionals:: Conditionals
108 * Gnits:: The effect of @option{--gnu} and @option{--gnits}
109 * Cygnus:: The effect of @option{--cygnus}
110 * Not Enough:: When Automake is not Enough
111 * Distributing:: Distributing the Makefile.in
112 * API versioning:: About compatibility between Automake versions
113 * Upgrading:: Upgrading to a Newer Automake Version
114 * FAQ:: Frequently Asked Questions
115 * History:: Notes about the history of Automake
116 * Copying This Manual:: How to make copies of this manual
117 * Indices:: Indices of variables, macros, and concepts
120 --- The Detailed Node Listing ---
122 An Introduction to the Autotools
124 * GNU Build System:: Introducing the GNU Build System
125 * Use Cases:: Use Cases for the GNU Build System
126 * Why Autotools:: How Autotools Help
127 * Hello World:: A Small Hello World Package
129 Use Cases for the GNU Build System
131 * Basic Installation:: Common installation procedure
132 * Standard Targets:: A list of standard Makefile targets
133 * Standard Directory Variables:: A list of standard directory variables
134 * Standard Configuration Variables:: Using configuration variables
135 * config.site:: Using a config.site file
136 * VPATH Builds:: Parallel build trees
137 * Two-Part Install:: Installing data and programs separately
138 * Cross-Compilation:: Building for other architectures
139 * Renaming:: Renaming programs at install time
140 * DESTDIR:: Building binary packages with DESTDIR
141 * Preparing Distributions:: Rolling out tarballs
142 * Dependency Tracking:: Automatic dependency tracking
143 * Nested Packages:: The GNU Build Systems can be nested
147 * Creating amhello:: Create @file{amhello-1.0.tar.gz} from scratch
148 * amhello Explained:: @file{configure.ac} and @file{Makefile.am} explained
152 * General Operation:: General operation of Automake
153 * Strictness:: Standards conformance checking
154 * Uniform:: The Uniform Naming Scheme
155 * Canonicalization:: How derived variables are named
156 * User Variables:: Variables reserved for the user
157 * Auxiliary Programs:: Programs automake might require
159 Some example packages
161 * Complete:: A simple example, start to finish
162 * true:: Building true and false
164 Scanning @file{configure.ac}
166 * Requirements:: Configuration requirements
167 * Optional:: Other things Automake recognizes
168 * Invoking aclocal:: Auto-generating aclocal.m4
169 * Macros:: Autoconf macros supplied with Automake
171 Auto-generating aclocal.m4
173 * aclocal options:: Options supported by aclocal
174 * Macro search path:: How aclocal finds .m4 files
175 * Extending aclocal:: Writing your own aclocal macros
176 * Local Macros:: Organizing local macros
177 * Serials:: Serial lines in Autoconf macros
178 * Future of aclocal:: aclocal's scheduled death
180 Autoconf macros supplied with Automake
182 * Public macros:: Macros that you can use.
183 * Obsolete macros:: Macros that you should stop using.
184 * Private macros:: Macros that you should not use.
188 * Subdirectories:: Building subdirectories recursively
189 * Conditional Subdirectories:: Conditionally not building directories
190 * Alternative:: Subdirectories without recursion
191 * Subpackages:: Nesting packages
193 Building Programs and Libraries
195 * A Program:: Building a program
196 * A Library:: Building a library
197 * A Shared Library:: Building a Libtool library
198 * Program and Library Variables:: Variables controlling program and
200 * Default _SOURCES:: Default source files
201 * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
202 * Program variables:: Variables used when building a program
203 * Yacc and Lex:: Yacc and Lex support
204 * C++ Support:: Compiling C++ sources
205 * Objective C Support:: Compiling Objective C sources
206 * Unified Parallel C Support:: Compiling Unified Parallel C sources
207 * Assembly Support:: Compiling assembly sources
208 * Fortran 77 Support:: Compiling Fortran 77 sources
209 * Fortran 9x Support:: Compiling Fortran 9x sources
210 * Java Support:: Compiling Java sources
211 * Support for Other Languages:: Compiling other languages
212 * ANSI:: Automatic de-ANSI-fication (obsolete)
213 * Dependencies:: Automatic dependency tracking
214 * EXEEXT:: Support for executable extensions
218 * Program Sources:: Defining program sources
219 * Linking:: Linking with libraries or extra objects
220 * Conditional Sources:: Handling conditional sources
221 * Conditional Programs:: Building program conditionally
223 Building a Shared Library
225 * Libtool Concept:: Introducing Libtool
226 * Libtool Libraries:: Declaring Libtool Libraries
227 * Conditional Libtool Libraries:: Building Libtool Libraries Conditionally
228 * Conditional Libtool Sources:: Choosing Library Sources Conditionally
229 * Libtool Convenience Libraries:: Building Convenience Libtool Libraries
230 * Libtool Modules:: Building Libtool Modules
231 * Libtool Flags:: Using _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS
232 * LTLIBOBJS:: Using $(LTLIBOBJS) and $(LTALLOCA)
233 * Libtool Issues:: Common Issues Related to Libtool's Use
237 * Preprocessing Fortran 77:: Preprocessing Fortran 77 sources
238 * Compiling Fortran 77 Files:: Compiling Fortran 77 sources
239 * Mixing Fortran 77 With C and C++:: Mixing Fortran 77 With C and C++
241 Mixing Fortran 77 With C and C++
243 * How the Linker is Chosen:: Automatic linker selection
247 * Compiling Fortran 9x Files:: Compiling Fortran 9x sources
249 Other Derived Objects
251 * Scripts:: Executable scripts
252 * Headers:: Header files
253 * Data:: Architecture-independent data files
254 * Sources:: Derived sources
258 * Built sources example:: Several ways to handle built sources.
262 * Emacs Lisp:: Emacs Lisp
268 Building documentation
271 * Man pages:: Man pages
275 * Tags:: Interfacing to etags and mkid
276 * Suffixes:: Handling new file extensions
277 * Multilibs:: Support for multilibs.
279 When Automake Isn't Enough
281 * Extending:: Adding new rules or overriding existing ones.
282 * Third-Party Makefiles:: Integrating Non-Automake @file{Makefile}s.
284 Frequently Asked Questions about Automake
286 * CVS:: CVS and generated files
287 * maintainer-mode:: missing and AM_MAINTAINER_MODE
288 * wildcards:: Why doesn't Automake support wildcards?
289 * limitations on file names:: Limitations on source and installed file names
290 * distcleancheck:: Files left in build directory after distclean
291 * Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS
292 * renamed objects:: Why are object files sometimes renamed?
293 * Per-Object Flags:: How to simulate per-object flags?
294 * Multiple Outputs:: Writing rules for tools with many output files
295 * Hard-Coded Install Paths:: Installing to Hard-Coded Locations
299 * Timeline:: The Automake story.
300 * Dependency Tracking Evolution:: Evolution of Automatic Dependency Tracking
301 * Releases:: Statistics about Automake Releases
305 * GNU Free Documentation License:: License for copying this manual
309 * Macro Index:: Index of Autoconf macros
310 * Variable Index:: Index of Makefile variables
311 * General Index:: General index
320 @chapter Introduction
322 Automake is a tool for automatically generating @file{Makefile.in}s
323 from files called @file{Makefile.am}. Each @file{Makefile.am} is
324 basically a series of @command{make} variable
325 definitions@footnote{These variables are also called @dfn{make macros}
326 in Make terminology, however in this manual we reserve the term
327 @dfn{macro} for Autoconf's macros.}, with rules being thrown in
328 occasionally. The generated @file{Makefile.in}s are compliant with
329 the GNU Makefile standards.
331 @cindex GNU Makefile standards
333 The GNU Makefile Standards Document
334 (@pxref{Makefile Conventions, , , standards, The GNU Coding Standards})
335 is long, complicated, and subject to change. The goal of Automake is to
336 remove the burden of Makefile maintenance from the back of the
337 individual GNU maintainer (and put it on the back of the Automake
340 The typical Automake input file is simply a series of variable definitions.
341 Each such file is processed to create a @file{Makefile.in}. There
342 should generally be one @file{Makefile.am} per directory of a project.
344 @cindex Constraints of Automake
345 @cindex Automake constraints
347 Automake does constrain a project in certain ways; for instance, it
348 assumes that the project uses Autoconf (@pxref{Top, , Introduction,
349 autoconf, The Autoconf Manual}), and enforces certain restrictions on
350 the @file{configure.ac} contents@footnote{Older Autoconf versions used
351 @file{configure.in}. Autoconf 2.50 and greater promotes
352 @file{configure.ac} over @file{configure.in}. The rest of this
353 documentation will refer to @file{configure.ac}, but Automake also
354 supports @file{configure.in} for backward compatibility.}.
356 @cindex Automake requirements
357 @cindex Requirements, Automake
359 Automake requires @command{perl} in order to generate the
360 @file{Makefile.in}s. However, the distributions created by Automake are
361 fully GNU standards-compliant, and do not require @command{perl} in order
364 @cindex Bugs, reporting
365 @cindex Reporting bugs
366 @cindex E-mail, bug reports
368 Mail suggestions and bug reports for Automake to
369 @email{bug-automake@@gnu.org}.
371 @node Autotools Introduction
372 @chapter An Introduction to the Autotools
374 If you are new to Automake, maybe you know that it is part of a set of
375 tools called @emph{The Autotools}. Maybe you've already delved into a
376 package full of files named @file{configure}, @file{configure.ac},
377 @file{Makefile.in}, @file{Makefile.am}, @file{aclocal.m4}, @dots{},
378 some of them claiming to be @emph{generated by} Autoconf or Automake.
379 But the exact purpose of these files and their relations is probably
380 fuzzy. The goal of this chapter is to introduce you to this machinery,
381 to show you how it works and how powerful it is. If you've never
382 installed or seen such a package, do not worry: this chapter will walk
385 If you need some teaching material, more illustrations, or a less
386 @command{automake}-centered continuation, some slides for this
387 introduction are available in Alexandre Duret-Lutz's
388 @uref{http://www-src.lip6.fr/@/~Alexandre.Duret-Lutz/@/autotools.html,
390 This chapter is the written version of the first part of his tutorial.
393 * GNU Build System:: Introducing the GNU Build System
394 * Use Cases:: Use Cases for the GNU Build System
395 * Why Autotools:: How Autotools Help
396 * Hello World:: A Small Hello World Package
399 @node GNU Build System
400 @section Introducing the GNU Build System
401 @cindex GNU Build System, introduction
403 It is a truth universally acknowledged, that a developer in
404 possession of a new package, must be in want of a build system.
406 In the Unix world, such a build system is traditionally achieved using
407 the command @command{make} (@pxref{Top, , Overview, make, The GNU Make
408 Manual}). The developer expresses the recipe to build his package in
409 a @file{Makefile}. This file is a set of rules to build the files in
410 the package. For instance the program @file{prog} may be built by
411 running the linker on the files @file{main.o}, @file{foo.o}, and
412 @file{bar.o}; the file @file{main.o} may be built by running the
413 compiler on @file{main.c}; etc. Each time @command{make} is run, it
414 reads @file{Makefile}, checks the existence and modification time of
415 the files mentioned, decides what files need to be built (or rebuilt),
416 and runs the associated commands.
418 When a package needs to be built on a different platform than the one
419 it was developed on, its @file{Makefile} usually needs to be adjusted.
420 For instance the compiler may have another name or require more
421 options. In 1991, David J. MacKenzie got tired of customizing
422 @file{Makefile} for the 20 platforms he had to deal with. Instead, he
423 handcrafted a little shell script called @file{configure} to
424 automatically adjust the @file{Makefile} (@pxref{Genesis, , Genesis,
425 autoconf, The Autoconf Manual}). Compiling his package was now
426 as simple as running @code{./configure && make}.
428 @cindex GNU Coding Standards
430 Today this process has been standardized in the GNU project. The GNU
431 Coding Standards (@pxref{Managing Releases, The Release Process, ,
432 standards, The GNU Coding Standards}) explains how each package of the
433 GNU project should have a @file{configure} script, and the minimal
434 interface it should have. The @file{Makefile} too should follow some
435 established conventions. The result? A unified build system that
436 makes all packages almost indistinguishable by the installer. In its
437 simplest scenario, all the installer has to do is to unpack the
438 package, run @code{./configure && make && make install}, and repeat
439 with the next package to install.
441 We call this build system the @dfn{GNU Build System}, since it was
442 grown out of the GNU project. However it is used by a vast number of
443 other packages: following any existing convention has its advantages.
445 @cindex Autotools, introduction
447 The Autotools are tools that will create a GNU Build System for your
448 package. Autoconf mostly focuses on @file{configure} and Automake on
449 @file{Makefile}s. It is entirely possible to create a GNU Build
450 System without the help of these tools. However it is rather
451 burdensome and error-prone. We will discuss this again after some
452 illustration of the GNU Build System in action.
455 @section Use Cases for the GNU Build System
456 @cindex GNU Build System, use cases
457 @cindex GNU Build System, features
458 @cindex Features of the GNU Build System
459 @cindex Use Cases for the GNU Build System
460 @cindex @file{amhello-1.0.tar.gz}, location
461 @cindex @file{amhello-1.0.tar.gz}, use cases
463 In this section we explore several use cases for the GNU Build System.
464 You can replay all these examples on the @file{amhello-1.0.tar.gz}
465 package distributed with Automake. If Automake is installed on your
466 system, you should find a copy of this file in
467 @file{@var{prefix}/share/doc/automake/amhello-1.0.tar.gz}, where
468 @var{prefix} is the installation prefix specified during configuration
469 (@var{prefix} defaults to @file{/usr/local}, however if Automake was
470 installed by some GNU/Linux distribution it most likely has been set
471 to @file{/usr}). If you do not have a copy of Automake installed,
472 you can find a copy of this file inside the @file{doc/} directory of
473 the Automake package.
475 Some of the following use cases present features that are in fact
476 extensions to the GNU Build System. Read: they are not specified by
477 the GNU Coding Standards, but they are nonetheless part of the build
478 system created by the Autotools. To keep things simple, we do not
479 point out the difference. Our objective is to show you many of the
480 features that the build system created by the Autotools will offer to
484 * Basic Installation:: Common installation procedure
485 * Standard Targets:: A list of standard Makefile targets
486 * Standard Directory Variables:: A list of standard directory variables
487 * Standard Configuration Variables:: Using configuration variables
488 * config.site:: Using a config.site file
489 * VPATH Builds:: Parallel build trees
490 * Two-Part Install:: Installing data and programs separately
491 * Cross-Compilation:: Building for other architectures
492 * Renaming:: Renaming programs at install time
493 * DESTDIR:: Building binary packages with DESTDIR
494 * Preparing Distributions:: Rolling out tarballs
495 * Dependency Tracking:: Automatic dependency tracking
496 * Nested Packages:: The GNU Build Systems can be nested
499 @node Basic Installation
500 @subsection Basic Installation
501 @cindex Configuration, basics
502 @cindex Installation, basics
503 @cindex GNU Build System, basics
505 The most common installation procedure looks as follows.
508 ~ % @kbd{tar zxf amhello-1.0.tar.gz}
509 ~ % @kbd{cd amhello-1.0}
510 ~/amhello-1.0 % @kbd{./configure}
512 config.status: creating Makefile
513 config.status: creating src/Makefile
515 ~/amhello-1.0 % @kbd{make}
517 ~/amhello-1.0 % @kbd{make check}
519 ~/amhello-1.0 % @kbd{su}
521 /home/adl/amhello-1.0 # @kbd{make install}
523 /home/adl/amhello-1.0 # @kbd{exit}
524 ~/amhello-1.0 % @kbd{make installcheck}
530 The user first unpacks the package. Here, and in the following
531 examples, we will use the non-portable @code{tar zxf} command for
532 simplicity. On a system without GNU @command{tar} installed, this
533 command should read @code{gunzip -c amhello-1.0.tar.gz | tar xf -}.
535 The user then enters the newly created directory to run the
536 @file{configure} script. This script probes the system for various
537 features, and finally creates the @file{Makefile}s. In this toy
538 example there are only two @file{Makefile}s, but in real-world projects,
539 there may be many more, usually one @file{Makefile} per directory.
541 It is now possible to run @code{make}. This will construct all the
542 programs, libraries, and scripts that need to be constructed for the
543 package. In our example, this compiles the @file{hello} program.
544 All files are constructed in place, in the source tree; we will see
545 later how this can be changed.
547 @code{make check} causes the package's tests to be run. This step is
548 not mandatory, but it is often good to make sure the programs that
549 have been built behave as they should, before you decide to install
550 them. Our example does not contain any tests, so running @code{make
553 @cindex su, before @code{make install}
554 After everything has been built, and maybe tested, it is time to
555 install it on the system. That means copying the programs,
556 libraries, header files, scripts, and other data files from the
557 source directory to their final destination on the system. The
558 command @code{make install} will do that. However, by default
559 everything will be installed in subdirectories of @file{/usr/local}:
560 binaries will go into @file{/usr/local/bin}, libraries will end up in
561 @file{/usr/local/lib}, etc. This destination is usually not writable
562 by any user, so we assume that we have to become root before we can
563 run @code{make install}. In our example, running @code{make install}
564 will copy the program @file{hello} into @file{/usr/local/bin}
565 and @file{README} into @file{/usr/local/share/doc/amhello}.
567 A last and optional step is to run @code{make installcheck}. This
568 command may run tests on the installed files. @code{make check} tests
569 the files in the source tree, while @code{make installcheck} tests
570 their installed copies. The tests run by the latter can be different
571 from those run by the former. For instance, there are tests that
572 cannot be run in the source tree. Conversely, some packages are set
573 up so that @code{make installcheck} will run the very same tests as
574 @code{make check}, only on different files (non-installed
575 vs.@: installed). It can make a difference, for instance when the
576 source tree's layout is different from that of the installation.
577 Furthermore it may help to diagnose an incomplete installation.
579 Presently most packages do not have any @code{installcheck} tests
580 because the existence of @code{installcheck} is little known, and its
581 usefulness is neglected. Our little toy package is no better: @code{make
582 installcheck} does nothing.
584 @node Standard Targets
585 @subsection Standard @file{Makefile} Targets
587 So far we have come across four ways to run @command{make} in the GNU
588 Build System: @code{make}, @code{make check}, @code{make install}, and
589 @code{make installcheck}. The words @code{check}, @code{install}, and
590 @code{installcheck}, passed as arguments to @command{make}, are called
591 @dfn{targets}. @code{make} is a shorthand for @code{make all},
592 @code{all} being the default target in the GNU Build System.
594 Here is a list of the most useful targets that the GNU Coding Standards
600 Build programs, libraries, documentation, etc.@: (same as @code{make}).
603 Install what needs to be installed, copying the files from the
604 package's tree to system-wide directories.
605 @item make install-strip
606 @trindex install-strip
607 Same as @code{make install}, then strip debugging symbols. Some
608 users like to trade space for useful bug reports@enddots{}
611 The opposite of @code{make install}: erase the installed files.
612 (This needs to be run from the same build tree that was installed.)
615 Erase from the build tree the files built by @code{make all}.
618 Additionally erase anything @code{./configure} created.
621 Run the test suite, if any.
622 @item make installcheck
623 @trindex installcheck
624 Check the installed programs or libraries, if supported.
627 Recreate @file{@var{package}-@var{version}.tar.gz} from all the source
631 @node Standard Directory Variables
632 @subsection Standard Directory Variables
633 @cindex directory variables
635 The GNU Coding Standards also specify a hierarchy of variables to
636 denote installation directories. Some of these are:
638 @multitable {Directory variable} {@code{$@{datarootdir@}/doc/$@{PACKAGE@}}}
639 @headitem Directory variable @tab Default value
640 @item @code{prefix} @tab @code{/usr/local}
641 @item @w{@ @ @code{exec_prefix}} @tab @code{$@{prefix@}}
642 @item @w{@ @ @ @ @code{bindir}} @tab @code{$@{exec_prefix@}/bin}
643 @item @w{@ @ @ @ @code{libdir}} @tab @code{$@{exec_prefix@}/lib}
644 @item @w{@ @ @ @ @dots{}}
645 @item @w{@ @ @code{includedir}} @tab @code{$@{prefix@}/include}
646 @item @w{@ @ @code{datarootdir}} @tab @code{$@{prefix@}/share}
647 @item @w{@ @ @ @ @code{datadir}} @tab @code{$@{datarootdir@}}
648 @item @w{@ @ @ @ @code{mandir}} @tab @code{$@{datarootdir@}/man}
649 @item @w{@ @ @ @ @code{infodir}} @tab @code{$@{datarootdir@}/info}
650 @item @w{@ @ @ @ @code{docdir}} @tab @code{$@{datarootdir@}/doc/$@{PACKAGE@}}
651 @item @w{@ @ @dots{}}
654 @c We should provide a complete table somewhere, but not here. The
655 @c complete list of directory variables it too confusing as-is. It
656 @c requires some explanations that are too complicated for this
657 @c introduction. Besides listing directories like localstatedir
658 @c would make the explanations in ``Two-Part Install'' harder.
660 Each of these directories has a role which is often obvious from its
661 name. In a package, any installable file will be installed in one of
662 these directories. For instance in @code{amhello-1.0}, the program
663 @file{hello} is to be installed in @var{bindir}, the directory for
664 binaries. The default value for this directory is
665 @file{/usr/local/bin}, but the user can supply a different value when
666 calling @command{configure}. Also the file @file{README} will be
667 installed into @var{docdir}, which defaults to
668 @file{/usr/local/share/doc/amhello}.
672 A user who wishes to install a package on his own account could proceed
676 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr}
678 ~/amhello-1.0 % @kbd{make}
680 ~/amhello-1.0 % @kbd{make install}
684 This would install @file{~/usr/bin/hello} and
685 @file{~/usr/share/doc/amhello/README}.
687 The list of all such directory options is shown by
688 @code{./configure --help}.
690 @node Standard Configuration Variables
691 @subsection Standard Configuration Variables
692 @cindex configuration variables, overriding
694 The GNU Coding Standards also define a set of standard configuration
695 variables used during the build. Here are some:
704 @item @code{CXXFLAGS}
708 @item @code{CPPFLAGS}
709 C/C++ preprocessor flags
713 @command{configure} usually does a good job at setting appropriate
714 values for these variables, but there are cases where you may want to
715 override them. For instance you may have several versions of a
716 compiler installed and would like to use another one, you may have
717 header files installed outside the default search path of the
718 compiler, or even libraries out of the way of the linker.
720 Here is how one would call @command{configure} to force it to use
721 @command{gcc-3} as C compiler, use header files from
722 @file{~/usr/include} when compiling, and libraries from
723 @file{~/usr/lib} when linking.
726 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr CC=gcc-3 \
727 CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib}
730 Again, a full list of these variables appears in the output of
731 @code{./configure --help}.
734 @subsection Overriding Default Configuration Setting with @file{config.site}
735 @cindex @file{config.site} example
737 When installing several packages using the same setup, it can be
738 convenient to create a file to capture common settings.
739 If a file named @file{@var{prefix}/share/config.site} exists,
740 @command{configure} will source it at the beginning of its execution.
742 Recall the command from the previous section:
745 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr CC=gcc-3 \
746 CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib}
749 Assuming we are installing many package in @file{~/usr}, and will
750 always want to use these definitions of @code{CC}, @code{CPPFLAGS}, and
751 @code{LDFLAGS}, we can automate this by creating the following
752 @file{~/usr/share/config.site} file:
755 test -z "$CC" && CC=gcc-3
756 test -z "$CPPFLAGS" && CPPFLAGS=-I$HOME/usr/include
757 test -z "$LDFLAGS" && LDFLAGS=-L$HOME/usr/lib
760 Now, any time a @file{configure} script is using the @file{~/usr}
761 prefix, it will execute the above @file{config.site} and define
762 these three variables.
765 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr}
766 configure: loading site script /home/adl/usr/share/config.site
770 @xref{Site Defaults, , Setting Site Defaults, autoconf, The Autoconf
771 Manual}, for more information about this feature.
775 @subsection Parallel Build Trees (a.k.a.@: VPATH Builds)
776 @cindex Parallel build trees
778 @cindex source tree and build tree
779 @cindex build tree and source tree
780 @cindex trees, source vs.@: build
782 The GNU Build System distinguishes two trees: the source tree, and
785 The source tree is rooted in the directory containing
786 @file{configure}. It contains all the sources files (those that are
787 distributed), and may be arranged using several subdirectories.
789 The build tree is rooted in the directory in which @file{configure}
790 was run, and is populated with all object files, programs, libraries,
791 and other derived files built from the sources (and hence not
792 distributed). The build tree usually has the same subdirectory layout
793 as the source tree; its subdirectories are created automatically by
796 If @file{configure} is executed in its own directory, the source and
797 build trees are combined: derived files are constructed in the same
798 directories as their sources. This was the case in our first
799 installation example (@pxref{Basic Installation}).
801 A common request from users is that they want to confine all derived
802 files to a single directory, to keep their source directories
803 uncluttered. Here is how we could run @file{configure} to build
804 everything in a subdirectory called @file{build/}.
807 ~ % @kbd{tar zxf ~/amhello-1.0.tar.gz}
808 ~ % @kbd{cd amhello-1.0}
809 ~/amhello-1.0 % @kbd{mkdir build && cd build}
810 ~/amhello-1.0/build % @kbd{../configure}
812 ~/amhello-1.0/build % @kbd{make}
816 These setups, where source and build trees are different, are often
817 called @dfn{parallel builds} or @dfn{VPATH builds}. The expression
818 @emph{parallel build} is misleading: the word @emph{parallel} is a
819 reference to the way the build tree shadows the source tree, it is not
820 about some concurrency in the way build commands are run. For this
821 reason we refer to such setups using the name @emph{VPATH builds} in
822 the following. @emph{VPATH} is the name of the @command{make} feature
823 used by the @file{Makefile}s to allow these builds (@pxref{General
824 Search, , @code{VPATH}: Search Path for All Prerequisites, make, The
827 @cindex multiple configurations, example
828 @cindex debug build, example
829 @cindex optimized build, example
831 VPATH builds have other interesting uses. One is to build the same
832 sources with multiple configurations. For instance:
835 ~ % @kbd{tar zxf ~/amhello-1.0.tar.gz}
836 ~ % @kbd{cd amhello-1.0}
837 ~/amhello-1.0 % @kbd{mkdir debug optim && cd debug}
838 ~/amhello-1.0/debug % @kbd{../configure CFLAGS='-g -O0'}
840 ~/amhello-1.0/debug % @kbd{make}
842 ~/amhello-1.0/debug % cd ../optim
843 ~/amhello-1.0/optim % @kbd{../configure CFLAGS='-O3 -fomit-frame-pointer'}
845 ~/amhello-1.0/optim % @kbd{make}
849 With network file systems, a similar approach can be used to build the
850 same sources on different machines. For instance, suppose that the
851 sources are installed on a directory shared by two hosts: @code{HOST1}
852 and @code{HOST2}, which may be different platforms.
855 ~ % @kbd{cd /nfs/src}
856 /nfs/src % @kbd{tar zxf ~/amhello-1.0.tar.gz}
859 On the first host, you could create a local build directory:
861 [HOST1] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
862 [HOST1] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure}
864 [HOST1] /tmp/amh % @kbd{make && sudo make install}
869 (Here we assume the that installer has configured @command{sudo} so it
870 can execute @code{make install} with root privileges; it is more convenient
871 than using @command{su} like in @ref{Basic Installation}).
873 On the second host, you would do exactly the same, possibly at
876 [HOST2] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
877 [HOST2] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure}
879 [HOST2] /tmp/amh % @kbd{make && sudo make install}
883 @cindex read-only source tree
884 @cindex source tree, read-only
886 In this scenario, nothing forbids the @file{/nfs/src/amhello-1.0}
887 directory from being read-only. In fact VPATH builds are also a means
888 of building packages from a read-only medium such as a CD-ROM. (The
889 FSF used to sell CD-ROM with unpacked source code, before the GNU
890 project grew so big.)
892 @node Two-Part Install
893 @subsection Two-Part Installation
895 In our last example (@pxref{VPATH Builds}), a source tree was shared
896 by two hosts, but compilation and installation were done separately on
899 The GNU Build System also supports networked setups where part of the
900 installed files should be shared amongst multiple hosts. It does so
901 by distinguishing architecture-dependent files from
902 architecture-independent files, and providing two @file{Makefile}
903 targets to install each of these classes of files.
905 @trindex install-exec
906 @trindex install-data
908 These targets are @code{install-exec} for architecture-dependent files
909 and @code{install-data} for architecture-independent files.
910 The command we used up to now, @code{make install}, can be thought of
911 as a shorthand for @code{make install-exec install-data}.
913 From the GNU Build System point of view, the distinction between
914 architecture-dependent files and architecture-independent files is
915 based exclusively on the directory variable used to specify their
916 installation destination. In the list of directory variables we
917 provided earlier (@pxref{Standard Directory Variables}), all the
918 variables based on @var{exec-prefix} designate architecture-dependent
919 directories whose files will be installed by @code{make install-exec}.
920 The others designate architecture-independent directories and will
921 serve files installed by @code{make install-data}. @xref{Install},
924 Here is how we could revisit our two-host installation example,
925 assuming that (1) we want to install the package directly in
926 @file{/usr}, and (2) the directory @file{/usr/share} is shared by the
929 On the first host we would run
931 [HOST1] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
932 [HOST1] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure --prefix /usr}
934 [HOST1] /tmp/amh % @kbd{make && sudo make install}
938 On the second host, however, we need only install the
939 architecture-specific files.
941 [HOST2] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
942 [HOST2] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure --prefix /usr}
944 [HOST2] /tmp/amh % @kbd{make && sudo make install-exec}
948 In packages that have installation checks, it would make sense to run
949 @code{make installcheck} (@pxref{Basic Installation}) to verify that
950 the package works correctly despite the apparent partial installation.
952 @node Cross-Compilation
953 @subsection Cross-Compilation
954 @cindex cross-compilation
956 To @dfn{cross-compile} is to build on one platform a binary that will
957 run on another platform. When speaking of cross-compilation, it is
958 important to distinguish between the @dfn{build platform} on which
959 the compilation is performed, and the @dfn{host platform} on which the
960 resulting executable is expected to run. The following
961 @command{configure} options are used to specify each of them:
964 @item --build=@var{BUILD}
965 @opindex --build=@var{BUILD}
966 The system on which the package is built.
967 @item --host=@var{HOST}
968 @opindex --host=@var{HOST}
969 The system where built programs and libraries will run.
972 When the @option{--host} is used, @command{configure} will search for
973 the cross-compiling suite for this platform. Cross-compilation tools
974 commonly have their target architecture as prefix of their name. For
975 instance my cross-compiler for MinGW32 has its binaries called
976 @code{i586-mingw32msvc-gcc}, @code{i586-mingw32msvc-ld},
977 @code{i586-mingw32msvc-as}, etc.
979 @cindex MinGW cross-compilation example
980 @cindex cross-compilation example
982 Here is how we could build @code{amhello-1.0} for
983 @code{i586-mingw32msvc} on a GNU/Linux PC.
986 ~/amhello-1.0 % @kbd{./configure --build i686-pc-linux-gnu --host i586-mingw32msvc}
987 checking for a BSD-compatible install... /usr/bin/install -c
988 checking whether build environment is sane... yes
989 checking for gawk... gawk
990 checking whether make sets $(MAKE)... yes
991 checking for i586-mingw32msvc-strip... i586-mingw32msvc-strip
992 checking for i586-mingw32msvc-gcc... i586-mingw32msvc-gcc
993 checking for C compiler default output file name... a.exe
994 checking whether the C compiler works... yes
995 checking whether we are cross compiling... yes
996 checking for suffix of executables... .exe
997 checking for suffix of object files... o
998 checking whether we are using the GNU C compiler... yes
999 checking whether i586-mingw32msvc-gcc accepts -g... yes
1000 checking for i586-mingw32msvc-gcc option to accept ANSI C...
1002 ~/amhello-1.0 % @kbd{make}
1004 ~/amhello-1.0 % @kbd{cd src; file hello.exe}
1005 hello.exe: MS Windows PE 32-bit Intel 80386 console executable not relocatable
1008 The @option{--host} and @option{--build} options are usually all we
1009 need for cross-compiling. The only exception is if the package being
1010 built is itself a cross-compiler: we need a third option to specify
1011 its target architecture.
1014 @item --target=@var{TARGET}
1015 @opindex --target=@var{TARGET}
1016 When building compiler tools: the system for which the tools will
1020 For instance when installing GCC, the GNU Compiler Collection, we can
1021 use @option{--target=@var{TARGET}} to specify that we want to build
1022 GCC as a cross-compiler for @var{TARGET}. Mixing @option{--build} and
1023 @option{--target}, we can actually cross-compile a cross-compiler;
1024 such a three-way cross-compilation is known as a @dfn{Canadian cross}.
1026 @xref{Specifying Names, , Specifying the System Type, autoconf, The
1027 Autoconf Manual}, for more information about these @command{configure}
1031 @subsection Renaming Programs at Install Time
1032 @cindex Renaming programs
1033 @cindex Transforming program names
1034 @cindex Programs, renaming during installation
1036 The GNU Build System provides means to automatically rename
1037 executables before they are installed. This is especially convenient
1038 when installing a GNU package on a system that already has a
1039 proprietary implementation you do not want to overwrite. For instance,
1040 you may want to install GNU @command{tar} as @command{gtar} so you can
1041 distinguish it from your vendor's @command{tar}.
1043 This can be done using one of these three @command{configure} options.
1046 @item --program-prefix=@var{PREFIX}
1047 @opindex --program-prefix=@var{PREFIX}
1048 Prepend @var{PREFIX} to installed program names.
1049 @item --program-suffix=@var{SUFFIX}
1050 @opindex --program-suffix=@var{SUFFIX}
1051 Append @var{SUFFIX} to installed program names.
1052 @item --program-transform-name=@var{PROGRAM}
1053 @opindex --program-transform-name=@var{PROGRAM}
1054 Run @code{sed @var{PROGRAM}} on installed program names.
1057 The following commands would install @file{hello}
1058 as @file{/usr/local/bin/test-hello}, for instance.
1061 ~/amhello-1.0 % @kbd{./configure --program-prefix test-}
1063 ~/amhello-1.0 % @kbd{make}
1065 ~/amhello-1.0 % @kbd{sudo make install}
1070 @subsection Building Binary Packages Using DESTDIR
1073 The GNU Build System's @code{make install} and @code{make uninstall}
1074 interface does not exactly fit the needs of a system administrator
1075 who has to deploy and upgrade packages on lots of hosts. In other
1076 words, the GNU Build System does not replace a package manager.
1078 Such package managers usually need to know which files have been
1079 installed by a package, so a mere @code{make install} is
1082 @cindex Staged installation
1084 The @code{DESTDIR} variable can be used to perform a staged
1085 installation. The package should be configured as if it was going to
1086 be installed in its final location (e.g., @code{--prefix /usr}), but
1087 when running @code{make install}, the @code{DESTDIR} should be set to
1088 the absolute name of a directory into which the installation will be
1089 diverted. From this directory it is easy to review which files are
1090 being installed where, and finally copy them to their final location
1093 @cindex Binary package
1095 For instance here is how we could create a binary package containing a
1096 snapshot of all the files to be installed.
1099 ~/amhello-1.0 % @kbd{./configure --prefix /usr}
1101 ~/amhello-1.0 % @kbd{make}
1103 ~/amhello-1.0 % @kbd{make DESTDIR=$HOME/inst install}
1105 ~/amhello-1.0 % @kbd{cd ~/inst}
1106 ~/inst % @kbd{find . -type f -print > ../files.lst}
1107 ~/inst % @kbd{tar zcvf ~/amhello-1.0-i686.tar.gz `cat ../file.lst`}
1109 ./usr/share/doc/amhello/README
1112 After this example, @code{amhello-1.0-i686.tar.gz} is ready to be
1113 uncompressed in @file{/} on many hosts. (Using @code{`cat ../file.lst`}
1114 instead of @samp{.} as argument for @command{tar} avoids entries for
1115 each subdirectory in the archive: we would not like @command{tar} to
1116 restore the modification time of @file{/}, @file{/usr/}, etc.)
1118 Note that when building packages for several architectures, it might
1119 be convenient to use @code{make install-data} and @code{make
1120 install-exec} (@pxref{Two-Part Install}) to gather
1121 architecture-independent files in a single package.
1123 @xref{Install}, for more information.
1125 @c We should document PRE_INSTALL/POST_INSTALL/NORMAL_INSTALL and their
1126 @c UNINSTALL counterparts.
1128 @node Preparing Distributions
1129 @subsection Preparing Distributions
1130 @cindex Preparing distributions
1131 @cindex Packages, preparation
1132 @cindex Distributions, preparation
1134 We have already mentioned @code{make dist}. This target collects all
1135 your source files and the necessary parts of the build system to
1136 create a tarball named @file{@var{package}-@var{version}.tar.gz}.
1138 @cindex @code{distcheck} better than @code{dist}
1140 Another, more useful command is @code{make distcheck}. The
1141 @code{distcheck} target constructs
1142 @file{@var{package}-@var{version}.tar.gz} just as well as @code{dist},
1143 but it additionally ensures most of the use cases presented so far
1148 It attempts a full compilation of the package (@pxref{Basic
1149 Installation}), unpacking the newly constructed tarball, running
1150 @code{make}, @code{make check}, @code{make install}, as well as
1151 @code{make installcheck}, and even @code{make dist},
1153 it tests VPATH builds with read-only source tree (@pxref{VPATH Builds}),
1155 it makes sure @code{make clean}, @code{make distclean}, and @code{make
1156 uninstall} do not omit any file (@pxref{Standard Targets}),
1158 and it checks that @code{DESTDIR} installations work (@pxref{DESTDIR}).
1161 All of these actions are performed in a temporary subdirectory, so
1162 that no root privileges are required.
1164 Releasing a package that fails @code{make distcheck} means that one of
1165 the scenarios we presented will not work and some users will be
1166 disappointed. Therefore it is a good practice to release a package
1167 only after a successful @code{make distcheck}. This of course does
1168 not imply that the package will be flawless, but at least it will
1169 prevent some of the embarrassing errors you may find in packages
1170 released by people who have never heard about @code{distcheck} (like
1171 @code{DESTDIR} not working because of a typo, or a distributed file
1172 being erased by @code{make clean}, or even @code{VPATH} builds not
1175 @xref{Creating amhello}, to recreate @file{amhello-1.0.tar.gz} using
1176 @code{make distcheck}. @xref{Dist}, for more information about
1179 @node Dependency Tracking
1180 @subsection Automatic Dependency Tracking
1181 @cindex Dependency tracking
1183 Dependency tracking is performed as a side-effect of compilation.
1184 Each time the build system compiles a source file, it computes its
1185 list of dependencies (in C these are the header files included by the
1186 source being compiled). Later, any time @command{make} is run and a
1187 dependency appears to have changed, the dependent files will be
1190 When @command{configure} is executed, you can see it probing each
1191 compiler for the dependency mechanism it supports (several mechanisms
1195 ~/amhello-1.0 % @kbd{./configure --prefix /usr}
1197 checking dependency style of gcc... gcc3
1201 Because dependencies are only computed as a side-effect of the
1202 compilation, no dependency information exists the first time a package
1203 is built. This is OK because all the files need to be built anyway:
1204 @code{make} does not have to decide which files need to be rebuilt.
1205 In fact, dependency tracking is completely useless for one-time builds
1206 and there is a @command{configure} option to disable this:
1209 @item --disable-dependency-tracking
1210 @opindex --disable-dependency-tracking
1211 Speed up one-time builds.
1214 Some compilers do not offer any practical way to derive the list of
1215 dependencies as a side-effect of the compilation, requiring a separate
1216 run (maybe of another tool) to compute these dependencies. The
1217 performance penalty implied by these methods is important enough to
1218 disable them by default. The option @option{--enable-dependency-tracking}
1219 must be passed to @command{configure} to activate them.
1222 @item --enable-dependency-tracking
1223 @opindex --enable-dependency-tracking
1224 Do not reject slow dependency extractors.
1227 @xref{Dependency Tracking Evolution}, for some discussion about the
1228 different dependency tracking schemes used by Automake over the years.
1230 @node Nested Packages
1231 @subsection Nested Packages
1232 @cindex Nested packages
1233 @cindex Packages, nested
1236 Although nesting packages isn't something we would recommend to
1237 someone who is discovering the Autotools, it is a nice feature worthy
1238 of mention in this small advertising tour.
1240 Autoconfiscated packages (that means packages whose build system have
1241 been created by Autoconf and friends) can be nested to arbitrary
1244 A typical setup is that a package A will distribute one of the libraries
1245 it needs in a subdirectory. This library B is a complete package with
1246 its own GNU Build System. The @command{configure} script of A will
1247 run the @command{configure} script of B as part of its execution,
1248 building and installing A will also build and install B. Generating a
1249 distribution for A will also include B.
1251 It is possible to gather several package like this. GCC is a heavy
1252 user of this feature. This gives installers a single package to
1253 configure, build and install, while it allows developers to work on
1254 subpackages independently.
1256 When configuring nested packages, the @command{configure} options
1257 given to the top-level @command{configure} are passed recursively to
1258 nested @command{configure}s. A package that does not understand an
1259 option will ignore it, assuming it is meaningful to some other
1262 @opindex --help=recursive
1264 The command @code{configure --help=recursive} can be used to display
1265 the options supported by all the included packages.
1267 @xref{Subpackages}, for an example setup.
1270 @section How Autotools Help
1271 @cindex Autotools, purpose
1273 There are several reasons why you may not want to implement the GNU
1274 Build System yourself (read: write a @file{configure} script and
1275 @file{Makefile}s yourself).
1279 As we have seen, the GNU Build System has a lot of
1280 features (@pxref{Use Cases}).
1281 Some users may expect features you have not implemented because
1282 you did not need them.
1284 Implementing these features portably is difficult and exhausting.
1285 Think of writing portable shell scripts, and portable
1286 @file{Makefile}s, for systems you may not have handy. @xref{Portable
1287 Shell, , Portable Shell Programming, autoconf, The Autoconf Manual}, to
1290 You will have to upgrade your setup to follow changes to the GNU
1294 The GNU Autotools take all this burden off your back and provide:
1298 Tools to create a portable, complete, and self-contained GNU Build
1299 System, from simple instructions.
1300 @emph{Self-contained} meaning the resulting build system does not
1301 require the GNU Autotools.
1303 A central place where fixes and improvements are made:
1304 a bug-fix for a portability issue will benefit every package.
1307 Yet there also exist reasons why you may want NOT to use the
1308 Autotools@enddots{} For instance you may be already using (or used to)
1309 another incompatible build system. Autotools will only be useful if
1310 you do accept the concepts of the GNU Build System. People who have their
1311 own idea of how a build system should work will feel frustrated by the
1315 @section A Small Hello World
1316 @cindex Example Hello World
1317 @cindex Hello World example
1318 @cindex @file{amhello-1.0.tar.gz}, creation
1320 In this section we recreate the @file{amhello-1.0} package from
1321 scratch. The first subsection shows how to call the Autotools to
1322 instantiate the GNU Build System, while the second explains the
1323 meaning of the @file{configure.ac} and @file{Makefile.am} files read
1327 * Creating amhello:: Create @file{amhello-1.0.tar.gz} from scratch
1328 * amhello Explained:: @file{configure.ac} and @file{Makefile.am} explained
1331 @node Creating amhello
1332 @subsection Creating @file{amhello-1.0.tar.gz}
1334 Here is how we can recreate @file{amhello-1.0.tar.gz} from scratch.
1335 The package is simple enough so that we will only need to write 5
1336 files. (You may copy them from the final @file{amhello-1.0.tar.gz}
1337 that is distributed with Automake if you do not want to write them.)
1339 Create the following files in an empty directory.
1344 @file{src/main.c} is the source file for the @file{hello} program. We
1345 store it in the @file{src/} subdirectory, because later, when the package
1346 evolves, it will ease the addition of a @file{man/} directory for man
1347 pages, a @file{data/} directory for data files, etc.
1349 ~/amhello % @kbd{cat src/main.c}
1356 puts ("Hello World!");
1357 puts ("This is " PACKAGE_STRING ".");
1363 @file{README} contains some very limited documentation for our little
1366 ~/amhello % @kbd{cat README}
1367 This is a demonstration package for GNU Automake.
1368 Type `info Automake' to read the Automake manual.
1372 @file{Makefile.am} and @file{src/Makefile.am} contain Automake
1373 instructions for these two directories.
1376 ~/amhello % @kbd{cat src/Makefile.am}
1377 bin_PROGRAMS = hello
1378 hello_SOURCES = main.c
1379 ~/amhello % @kbd{cat Makefile.am}
1381 dist_doc_DATA = README
1385 Finally, @file{configure.ac} contains Autoconf instructions to
1386 create the @command{configure} script.
1389 ~/amhello % @kbd{cat configure.ac}
1390 AC_INIT([amhello], [1.0], [bug-automake@@gnu.org])
1391 AM_INIT_AUTOMAKE([-Wall -Werror foreign])
1393 AC_CONFIG_HEADERS([config.h])
1402 @cindex @command{autoreconf}, example
1404 Once you have these five files, it is time to run the Autotools to
1405 instantiate the build system. Do this using the @command{autoreconf}
1409 ~/amhello % @kbd{autoreconf --install}
1410 configure.ac: installing `./install-sh'
1411 configure.ac: installing `./missing'
1412 src/Makefile.am: installing `./depcomp'
1415 At this point the build system is complete.
1417 In addition to the three scripts mentioned in its output, you can see
1418 that @command{autoreconf} created four other files: @file{configure},
1419 @file{config.h.in}, @file{Makefile.in}, and @file{src/Makefile.in}.
1420 The latter three files are templates that will be adapted to the
1421 system by @command{configure} under the names @file{config.h},
1422 @file{Makefile}, and @file{src/Makefile}. Let's do this:
1425 ~/amhello % @kbd{./configure}
1426 checking for a BSD-compatible install... /usr/bin/install -c
1427 checking whether build environment is sane... yes
1428 checking for gawk... no
1429 checking for mawk... mawk
1430 checking whether make sets $(MAKE)... yes
1431 checking for gcc... gcc
1432 checking for C compiler default output file name... a.out
1433 checking whether the C compiler works... yes
1434 checking whether we are cross compiling... no
1435 checking for suffix of executables...
1436 checking for suffix of object files... o
1437 checking whether we are using the GNU C compiler... yes
1438 checking whether gcc accepts -g... yes
1439 checking for gcc option to accept ISO C89... none needed
1440 checking for style of include used by make... GNU
1441 checking dependency style of gcc... gcc3
1442 configure: creating ./config.status
1443 config.status: creating Makefile
1444 config.status: creating src/Makefile
1445 config.status: creating config.h
1446 config.status: executing depfiles commands
1450 @cindex @code{distcheck} example
1452 You can see @file{Makefile}, @file{src/Makefile}, and @file{config.h}
1453 being created at the end after @command{configure} has probed the
1454 system. It is now possible to run all the targets we wish
1455 (@pxref{Standard Targets}). For instance:
1458 ~/amhello % @kbd{make}
1460 ~/amhello % @kbd{src/hello}
1462 This is amhello 1.0.
1463 ~/amhello % @kbd{make distcheck}
1465 =============================================
1466 amhello-1.0 archives ready for distribution:
1468 =============================================
1471 Note that running @command{autoreconf} is only needed initially when
1472 the GNU Build System does not exist. When you later change some
1473 instructions in a @file{Makefile.am} or @file{configure.ac}, the
1474 relevant part of the build system will be regenerated automatically
1475 when you execute @command{make}.
1477 @command{autoreconf} is a script that calls @command{autoconf},
1478 @command{automake}, and a bunch of other commands in the right order.
1479 If you are beginning with these tools, it is not important to figure
1480 out in which order all these tools should be invoked and why. However,
1481 because Autoconf and Automake have separate manuals, the important
1482 point to understand is that @command{autoconf} is in charge of
1483 creating @file{configure} from @file{configure.ac}, while
1484 @command{automake} is in charge of creating @file{Makefile.in}s from
1485 @file{Makefile.am}s and @file{configure.ac}. This should at least
1486 direct you to the right manual when seeking answers.
1489 @node amhello Explained
1490 @subsection @file{amhello-1.0} Explained
1492 Let us begin with the contents of @file{configure.ac}.
1495 AC_INIT([amhello], [1.0], [bug-automake@@gnu.org])
1496 AM_INIT_AUTOMAKE([-Wall -Werror foreign])
1498 AC_CONFIG_HEADERS([config.h])
1506 This file is read by both @command{autoconf} (to create
1507 @file{configure}) and @command{automake} (to create the various
1508 @file{Makefile.in}s). It contains a series of M4 macros that will be
1509 expanded as shell code to finally form the @file{configure} script.
1510 We will not elaborate on the syntax of this file, because the Autoconf
1511 manual has a whole section about it (@pxref{Writing configure.ac, ,
1512 Writing @file{configure.ac}, autoconf, The Autoconf Manual}).
1514 The macros prefixed with @code{AC_} are Autoconf macros, documented
1515 in the Autoconf manual (@pxref{Autoconf Macro Index, , Autoconf Macro
1516 Index, autoconf, The Autoconf Manual}). The macros that start with
1517 @code{AM_} are Automake macros, documented later in this manual
1518 (@pxref{Macro Index}).
1520 The first two lines of @file{configure.ac} initialize Autoconf and
1521 Automake. @code{AC_INIT} takes in as parameters the name of the package,
1522 its version number, and a contact address for bug-reports about the
1523 package (this address is output at the end of @code{./configure
1524 --help}, for instance). When adapting this setup to your own package,
1525 by all means please do not blindly copy Automake's address: use the
1526 mailing list of your package, or your own mail address.
1532 The argument to @code{AM_INIT_AUTOMAKE} is a list of options for
1533 @command{automake} (@pxref{Options}). @option{-Wall} and
1534 @option{-Werror} ask @command{automake} to turn on all warnings and
1535 report them as errors. We are speaking of @strong{Automake} warnings
1536 here, such as dubious instructions in @file{Makefile.am}. This has
1537 absolutely nothing to do with how the compiler will be called, even
1538 though it may support options with similar names. Using @option{-Wall
1539 -Werror} is a safe setting when starting to work on a package: you do
1540 not want to miss any issues. Later you may decide to relax things a
1541 bit. The @option{foreign} option tells Automake that this package
1542 will not follow the GNU Standards. GNU packages should always
1543 distribute additional files such as @file{ChangeLog}, @file{AUTHORS},
1544 etc. We do not want @command{automake} to complain about these
1545 missing files in our small example.
1547 The @code{AC_PROG_CC} line causes the @command{configure} script to
1548 search for a C compiler and define the variable @code{CC} with its
1549 name. The @file{src/Makefile.in} file generated by Automake uses the
1550 variable @code{CC} to build @file{hello}, so when @command{configure}
1551 creates @file{src/Makefile} from @file{src/Makefile.in}, it will define
1552 @code{CC} with the value it has found. If Automake is asked to create
1553 a @file{Makefile.in} that uses @code{CC} but @file{configure.ac} does
1554 not define it, it will suggest you add a call to @code{AC_PROG_CC}.
1556 The @code{AC_CONFIG_HEADERS([config.h])} invocation causes the
1557 @command{configure} script to create a @file{config.h} file gathering
1558 @samp{#define}s defined by other macros in @file{configure.ac}. In our
1559 case, the @code{AC_INIT} macro already defined a few of them. Here
1560 is an excerpt of @file{config.h} after @command{configure} has run:
1564 /* Define to the address where bug reports for this package should be sent. */
1565 #define PACKAGE_BUGREPORT "bug-automake@@gnu.org"
1567 /* Define to the full name and version of this package. */
1568 #define PACKAGE_STRING "amhello 1.0"
1572 As you probably noticed, @file{src/main.c} includes @file{config.h} so
1573 it can use @code{PACKAGE_STRING}. In a real-world project,
1574 @file{config.h} can grow really big, with one @samp{#define} per
1575 feature probed on the system.
1577 The @code{AC_CONFIG_FILES} macro declares the list of files that
1578 @command{configure} should create from their @file{*.in} templates.
1579 Automake also scans this list to find the @file{Makefile.am} files it must
1580 process. (This is important to remember: when adding a new directory
1581 to your project, you should add its @file{Makefile} to this list,
1582 otherwise Automake will never process the new @file{Makefile.am} you
1583 wrote in that directory.)
1585 Finally, the @code{AC_OUTPUT} line is a closing command that actually
1586 produces the part of the script in charge of creating the files
1587 registered with @code{AC_CONFIG_HEADERS} and @code{AC_CONFIG_FILES}.
1589 @cindex @command{autoscan}
1591 When starting a new project, we suggest you start with such a simple
1592 @file{configure.ac}, and gradually add the other tests it requires.
1593 The command @command{autoscan} can also suggest a few of the tests
1594 your package may need (@pxref{autoscan Invocation, , Using
1595 @command{autoscan} to Create @file{configure.ac}, autoconf, The
1598 @cindex @file{Makefile.am}, Hello World
1600 We now turn to @file{src/Makefile.am}. This file contains
1601 Automake instructions to build and install @file{hello}.
1604 bin_PROGRAMS = hello
1605 hello_SOURCES = main.c
1608 A @file{Makefile.am} has the same syntax as an ordinary
1609 @file{Makefile}. When @command{automake} processes a
1610 @file{Makefile.am} it copies the entire file into the output
1611 @file{Makefile.in} (that will be later turned into @file{Makefile} by
1612 @command{configure}) but will react to certain variable definitions
1613 by generating some build rules and other variables.
1614 Often @file{Makefile.am}s contain only a list of variable definitions as
1615 above, but they can also contain other variable and rule definitions that
1616 @command{automake} will pass along without interpretation.
1618 Variables that end with @code{_PROGRAMS} are special variables
1619 that list programs that the resulting @file{Makefile} should build.
1620 In Automake speak, this @code{_PROGRAMS} suffix is called a
1621 @dfn{primary}; Automake recognizes other primaries such as
1622 @code{_SCRIPTS}, @code{_DATA}, @code{_LIBRARIES}, etc.@: corresponding
1623 to different types of files.
1625 The @samp{bin} part of the @code{bin_PROGRAMS} tells
1626 @command{automake} that the resulting programs should be installed in
1627 @var{bindir}. Recall that the GNU Build System uses a set of variables
1628 to denote destination directories and allow users to customize these
1629 locations (@pxref{Standard Directory Variables}). Any such directory
1630 variable can be put in front of a primary (omitting the @code{dir}
1631 suffix) to tell @command{automake} where to install the listed files.
1633 Programs need to be built from source files, so for each program
1634 @code{@var{prog}} listed in a @code{@w{_PROGRAMS}} variable,
1635 @command{automake} will look for another variable named
1636 @code{@var{prog}_SOURCES} listing its source files. There may be more
1637 than one source file: they will all be compiled and linked together.
1639 Automake also knows that source files need to be distributed when
1640 creating a tarball (unlike built programs). So a side-effect of this
1641 @code{hello_SOURCES} declaration is that @file{main.c} will be
1642 part of the tarball created by @code{make dist}.
1644 Finally here are some explanations regarding the top-level
1649 dist_doc_DATA = README
1652 @code{SUBDIRS} is a special variable listing all directories that
1653 @command{make} should recurse into before processing the current
1654 directory. So this line is responsible for @command{make} building
1655 @file{src/hello} even though we run it from the top-level. This line
1656 also causes @code{make install} to install @file{src/hello} before
1657 installing @file{README} (not that this order matters).
1659 The line @code{dist_doc_DATA = README} causes @file{README} to be
1660 distributed and installed in @var{docdir}. Files listed with the
1661 @code{_DATA} primary are not automatically part of the tarball built
1662 with @code{make dist}, so we add the @code{dist_} prefix so they get
1663 distributed. However, for @file{README} it would not have been
1664 necessary: @command{automake} automatically distributes any
1665 @file{README} file it encounters (the list of other files
1666 automatically distributed is presented by @code{automake --help}).
1667 The only important effect of this second line is therefore to install
1668 @file{README} during @code{make install}.
1672 @chapter General ideas
1674 The following sections cover a few basic ideas that will help you
1675 understand how Automake works.
1678 * General Operation:: General operation of Automake
1679 * Strictness:: Standards conformance checking
1680 * Uniform:: The Uniform Naming Scheme
1681 * Canonicalization:: How derived variables are named
1682 * User Variables:: Variables reserved for the user
1683 * Auxiliary Programs:: Programs automake might require
1687 @node General Operation
1688 @section General Operation
1690 Automake works by reading a @file{Makefile.am} and generating a
1691 @file{Makefile.in}. Certain variables and rules defined in the
1692 @file{Makefile.am} instruct Automake to generate more specialized code;
1693 for instance, a @code{bin_PROGRAMS} variable definition will cause rules
1694 for compiling and linking programs to be generated.
1696 @cindex Non-standard targets
1697 @cindex @code{cvs-dist}, non-standard example
1701 The variable definitions and rules in the @file{Makefile.am} are
1702 copied verbatim into the generated file. This allows you to add
1703 arbitrary code into the generated @file{Makefile.in}. For instance,
1704 the Automake distribution includes a non-standard rule for the
1705 @code{git-dist} target, which the Automake maintainer uses to make
1706 distributions from his source control system.
1708 @cindex GNU make extensions
1710 Note that most GNU make extensions are not recognized by Automake. Using
1711 such extensions in a @file{Makefile.am} will lead to errors or confusing
1714 @cindex Append operator
1716 A special exception is that the GNU make append operator, @samp{+=}, is
1717 supported. This operator appends its right hand argument to the variable
1718 specified on the left. Automake will translate the operator into
1719 an ordinary @samp{=} operator; @samp{+=} will thus work with any make program.
1721 Automake tries to keep comments grouped with any adjoining rules or
1722 variable definitions.
1724 @cindex Make targets, overriding
1725 @cindex Make rules, overriding
1726 @cindex Overriding make rules
1727 @cindex Overriding make targets
1729 A rule defined in @file{Makefile.am} generally overrides any such
1730 rule of a similar name that would be automatically generated by
1731 @command{automake}. Although this is a supported feature, it is generally
1732 best to avoid making use of it, as sometimes the generated rules are
1735 @cindex Variables, overriding
1736 @cindex Overriding make variables
1738 Similarly, a variable defined in @file{Makefile.am} or
1739 @code{AC_SUBST}ed from @file{configure.ac} will override any
1740 definition of the variable that @command{automake} would ordinarily
1741 create. This feature is more often useful than the ability to
1742 override a rule. Be warned that many of the variables generated by
1743 @command{automake} are considered to be for internal use only, and their
1744 names might change in future releases.
1746 @cindex Recursive operation of Automake
1747 @cindex Automake, recursive operation
1748 @cindex Example of recursive operation
1750 When examining a variable definition, Automake will recursively examine
1751 variables referenced in the definition. For example, if Automake is
1752 looking at the content of @code{foo_SOURCES} in this snippet
1756 foo_SOURCES = c.c $(xs)
1759 it would use the files @file{a.c}, @file{b.c}, and @file{c.c} as the
1760 contents of @code{foo_SOURCES}.
1762 @cindex @code{##} (special Automake comment)
1763 @cindex Special Automake comment
1764 @cindex Comment, special to Automake
1766 Automake also allows a form of comment that is @emph{not} copied into
1767 the output; all lines beginning with @samp{##} (leading spaces allowed)
1768 are completely ignored by Automake.
1770 It is customary to make the first line of @file{Makefile.am} read:
1772 @cindex Makefile.am, first line
1773 @cindex First line of Makefile.am
1776 ## Process this file with automake to produce Makefile.in
1779 @c FIXME discuss putting a copyright into Makefile.am here? I would but
1780 @c I don't know quite what to say.
1782 @c FIXME document customary ordering of Makefile.am here!
1788 @cindex Non-GNU packages
1790 While Automake is intended to be used by maintainers of GNU packages, it
1791 does make some effort to accommodate those who wish to use it, but do
1792 not want to use all the GNU conventions.
1794 @cindex Strictness, defined
1795 @cindex Strictness, @option{foreign}
1796 @cindex @option{foreign} strictness
1797 @cindex Strictness, @option{gnu}
1798 @cindex @option{gnu} strictness
1799 @cindex Strictness, @option{gnits}
1800 @cindex @option{gnits} strictness
1802 To this end, Automake supports three levels of @dfn{strictness}---the
1803 strictness indicating how stringently Automake should check standards
1806 The valid strictness levels are:
1810 Automake will check for only those things that are absolutely
1811 required for proper operations. For instance, whereas GNU standards
1812 dictate the existence of a @file{NEWS} file, it will not be required in
1813 this mode. The name comes from the fact that Automake is intended to be
1814 used for GNU programs; these relaxed rules are not the standard mode of
1818 Automake will check---as much as possible---for compliance to the GNU
1819 standards for packages. This is the default.
1822 Automake will check for compliance to the as-yet-unwritten @dfn{Gnits
1823 standards}. These are based on the GNU standards, but are even more
1824 detailed. Unless you are a Gnits standards contributor, it is
1825 recommended that you avoid this option until such time as the Gnits
1826 standard is actually published (which may never happen).
1829 @xref{Gnits}, for more information on the precise implications of the
1832 Automake also has a special ``cygnus'' mode that is similar to
1833 strictness but handled differently. This mode is useful for packages
1834 that are put into a ``Cygnus'' style tree (e.g., the GCC tree).
1835 @xref{Cygnus}, for more information on this mode.
1839 @section The Uniform Naming Scheme
1841 @cindex Uniform naming scheme
1843 Automake variables generally follow a @dfn{uniform naming scheme} that
1844 makes it easy to decide how programs (and other derived objects) are
1845 built, and how they are installed. This scheme also supports
1846 @command{configure} time determination of what should be built.
1848 @cindex @code{_PROGRAMS} primary variable
1849 @cindex @code{PROGRAMS} primary variable
1850 @cindex Primary variable, @code{PROGRAMS}
1851 @cindex Primary variable, defined
1854 At @command{make} time, certain variables are used to determine which
1855 objects are to be built. The variable names are made of several pieces
1856 that are concatenated together.
1858 The piece that tells automake what is being built is commonly called
1859 the @dfn{primary}. For instance, the primary @code{PROGRAMS} holds a
1860 list of programs that are to be compiled and linked.
1863 @cindex @code{pkgdatadir}, defined
1864 @cindex @code{pkgincludedir}, defined
1865 @cindex @code{pkglibdir}, defined
1866 @cindex @code{pkglibexecdir}, defined
1869 @vindex pkgincludedir
1871 @vindex pkglibexecdir
1873 @cindex @code{PACKAGE}, directory
1874 A different set of names is used to decide where the built objects
1875 should be installed. These names are prefixes to the primary, and they
1876 indicate which standard directory should be used as the installation
1877 directory. The standard directory names are given in the GNU standards
1878 (@pxref{Directory Variables, , , standards, The GNU Coding Standards}).
1879 Automake extends this list with @code{pkgdatadir}, @code{pkgincludedir},
1880 @code{pkglibdir}, and @code{pkglibexecdir}; these are the same as the
1881 non-@samp{pkg} versions, but with @samp{$(PACKAGE)} appended. For instance,
1882 @code{pkglibdir} is defined as @samp{$(libdir)/$(PACKAGE)}.
1884 @cindex @code{EXTRA_}, prepending
1885 For each primary, there is one additional variable named by prepending
1886 @samp{EXTRA_} to the primary name. This variable is used to list
1887 objects that may or may not be built, depending on what
1888 @command{configure} decides. This variable is required because Automake
1889 must statically know the entire list of objects that may be built in
1890 order to generate a @file{Makefile.in} that will work in all cases.
1892 @cindex @code{EXTRA_PROGRAMS}, defined
1893 @cindex Example, @code{EXTRA_PROGRAMS}
1894 @cindex @command{cpio} example
1896 For instance, @command{cpio} decides at configure time which programs
1897 should be built. Some of the programs are installed in @code{bindir},
1898 and some are installed in @code{sbindir}:
1901 EXTRA_PROGRAMS = mt rmt
1902 bin_PROGRAMS = cpio pax
1903 sbin_PROGRAMS = $(MORE_PROGRAMS)
1906 Defining a primary without a prefix as a variable, e.g.,
1907 @samp{PROGRAMS}, is an error.
1909 Note that the common @samp{dir} suffix is left off when constructing the
1910 variable names; thus one writes @samp{bin_PROGRAMS} and not
1911 @samp{bindir_PROGRAMS}.
1913 Not every sort of object can be installed in every directory. Automake
1914 will flag those attempts it finds in error.
1915 Automake will also diagnose obvious misspellings in directory names.
1917 @cindex Extending list of installation directories
1918 @cindex Installation directories, extending list
1920 Sometimes the standard directories---even as augmented by
1921 Automake---are not enough. In particular it is sometimes useful, for
1922 clarity, to install objects in a subdirectory of some predefined
1923 directory. To this end, Automake allows you to extend the list of
1924 possible installation directories. A given prefix (e.g., @samp{zar})
1925 is valid if a variable of the same name with @samp{dir} appended is
1926 defined (e.g., @samp{zardir}).
1928 For instance, the following snippet will install @file{file.xml} into
1929 @samp{$(datadir)/xml}.
1932 xmldir = $(datadir)/xml
1936 @cindex @samp{noinst_} primary prefix, definition
1939 The special prefix @samp{noinst_} indicates that the objects in question
1940 should be built but not installed at all. This is usually used for
1941 objects required to build the rest of your package, for instance static
1942 libraries (@pxref{A Library}), or helper scripts.
1944 @cindex @samp{check_} primary prefix, definition
1947 The special prefix @samp{check_} indicates that the objects in question
1948 should not be built until the @samp{make check} command is run. Those
1949 objects are not installed either.
1951 The current primary names are @samp{PROGRAMS}, @samp{LIBRARIES},
1952 @samp{LISP}, @samp{PYTHON}, @samp{JAVA}, @samp{SCRIPTS}, @samp{DATA},
1953 @samp{HEADERS}, @samp{MANS}, and @samp{TEXINFOS}.
1965 Some primaries also allow additional prefixes that control other
1966 aspects of @command{automake}'s behavior. The currently defined prefixes
1967 are @samp{dist_}, @samp{nodist_}, and @samp{nobase_}. These prefixes
1968 are explained later (@pxref{Program and Library Variables}).
1971 @node Canonicalization
1972 @section How derived variables are named
1974 @cindex canonicalizing Automake variables
1976 Sometimes a Makefile variable name is derived from some text the
1977 maintainer supplies. For instance, a program name listed in
1978 @samp{_PROGRAMS} is rewritten into the name of a @samp{_SOURCES}
1979 variable. In cases like this, Automake canonicalizes the text, so that
1980 program names and the like do not have to follow Makefile variable naming
1981 rules. All characters in the name except for letters, numbers, the
1982 strudel (@@), and the underscore are turned into underscores when making
1983 variable references.
1985 For example, if your program is named @file{sniff-glue}, the derived
1986 variable name would be @samp{sniff_glue_SOURCES}, not
1987 @samp{sniff-glue_SOURCES}. Similarly the sources for a library named
1988 @file{libmumble++.a} should be listed in the
1989 @samp{libmumble___a_SOURCES} variable.
1991 The strudel is an addition, to make the use of Autoconf substitutions in
1992 variable names less obfuscating.
1995 @node User Variables
1996 @section Variables reserved for the user
1998 @cindex variables, reserved for the user
1999 @cindex user variables
2001 Some @file{Makefile} variables are reserved by the GNU Coding Standards
2002 for the use of the ``user''---the person building the package. For
2003 instance, @code{CFLAGS} is one such variable.
2005 Sometimes package developers are tempted to set user variables such as
2006 @code{CFLAGS} because it appears to make their job easier. However,
2007 the package itself should never set a user variable, particularly not
2008 to include switches that are required for proper compilation of the
2009 package. Since these variables are documented as being for the
2010 package builder, that person rightfully expects to be able to override
2011 any of these variables at build time.
2013 To get around this problem, Automake introduces an automake-specific
2014 shadow variable for each user flag variable. (Shadow variables are
2015 not introduced for variables like @code{CC}, where they would make no
2016 sense.) The shadow variable is named by prepending @samp{AM_} to the
2017 user variable's name. For instance, the shadow variable for
2018 @code{YFLAGS} is @code{AM_YFLAGS}. The package maintainer---that is,
2019 the author(s) of the @file{Makefile.am} and @file{configure.ac}
2020 files---may adjust these shadow variables however necessary.
2022 @xref{Flag Variables Ordering}, for more discussion about these
2023 variables and how they interact with per-target variables.
2025 @node Auxiliary Programs
2026 @section Programs automake might require
2028 @cindex Programs, auxiliary
2029 @cindex Auxiliary programs
2031 Automake sometimes requires helper programs so that the generated
2032 @file{Makefile} can do its work properly. There are a fairly large
2033 number of them, and we list them here.
2035 Although all of these files are distributed and installed with
2036 Automake, a couple of them are maintained separately. The Automake
2037 copies are updated before each release, but we mention the original
2038 source in case you need more recent versions.
2043 These two files are used by the obsolete de-ANSI-fication support
2047 This is a wrapper for compilers that do not accept options @option{-c}
2048 and @option{-o} at the same time. It is only used when absolutely
2049 required. Such compilers are rare.
2053 These two programs compute the canonical triplets for the given build,
2054 host, or target architecture. These programs are updated regularly to
2055 support new architectures and fix probes broken by changes in new
2056 kernel versions. Each new release of Automake comes with up-to-date
2057 copies of these programs. If your copy of Automake is getting old,
2058 you are encouraged to fetch the latest versions of these files from
2059 @url{http://savannah.gnu.org/cvs/?group=config} before making a
2063 This file is not a program, it is a @file{configure} fragment used for
2064 multilib support (@pxref{Multilibs}). This file is maintained in the
2065 GCC tree at @url{http://gcc.gnu.org/svn.html}.
2068 This program understands how to run a compiler so that it will
2069 generate not only the desired output but also dependency information
2070 that is then used by the automatic dependency tracking feature
2071 (@pxref{Dependencies}).
2074 This program is used to byte-compile Emacs Lisp code.
2077 This is a replacement for the @command{install} program that works on
2078 platforms where @command{install} is unavailable or unusable.
2081 This script is used to generate a @file{version.texi} file. It examines
2082 a file and prints some date information about it.
2085 This wraps a number of programs that are typically only required by
2086 maintainers. If the program in question doesn't exist,
2087 @command{missing} prints an informative warning and attempts to fix
2088 things so that the build can continue.
2091 This script used to be a wrapper around @samp{mkdir -p}, which is not
2092 portable. Now we prefer to use @samp{install-sh -d} when configure
2093 finds that @samp{mkdir -p} does not work, this makes one less script to
2096 For backward compatibility @file{mkinstalldirs} is still used and
2097 distributed when @command{automake} finds it in a package. But it is no
2098 longer installed automatically, and it should be safe to remove it.
2101 This is used to byte-compile Python scripts.
2104 This program duplicates a tree of directories, using symbolic links
2105 instead of copying files. Such operation is performed when building
2106 multilibs (@pxref{Multilibs}). This file is maintained in the GCC
2107 tree at @url{http://gcc.gnu.org/svn.html}.
2110 Not a program, this file is required for @samp{make dvi}, @samp{make
2111 ps} and @samp{make pdf} to work when Texinfo sources are in the
2112 package. The latest version can be downloaded from
2113 @url{http://www.gnu.org/software/texinfo/}.
2116 This program wraps @command{lex} and @command{yacc} to rename their
2117 output files. It also ensures that, for instance, multiple
2118 @command{yacc} instances can be invoked in a single directory in
2125 @chapter Some example packages
2127 This section contains two small examples.
2129 The first example (@pxref{Complete}) assumes you have an existing
2130 project already using Autoconf, with handcrafted @file{Makefile}s, and
2131 that you want to convert it to using Automake. If you are discovering
2132 both tools, it is probably better that you look at the Hello World
2133 example presented earlier (@pxref{Hello World}).
2135 The second example (@pxref{true}) shows how two programs can be built
2136 from the same file, using different compilation parameters. It
2137 contains some technical digressions that are probably best skipped on
2141 * Complete:: A simple example, start to finish
2142 * true:: Building true and false
2147 @section A simple example, start to finish
2149 @cindex Complete example
2151 Let's suppose you just finished writing @code{zardoz}, a program to make
2152 your head float from vortex to vortex. You've been using Autoconf to
2153 provide a portability framework, but your @file{Makefile.in}s have been
2154 ad-hoc. You want to make them bulletproof, so you turn to Automake.
2156 @cindex @code{AM_INIT_AUTOMAKE}, example use
2158 The first step is to update your @file{configure.ac} to include the
2159 commands that @command{automake} needs. The way to do this is to add an
2160 @code{AM_INIT_AUTOMAKE} call just after @code{AC_INIT}:
2163 AC_INIT([zardoz], [1.0])
2168 Since your program doesn't have any complicating factors (e.g., it
2169 doesn't use @code{gettext}, it doesn't want to build a shared library),
2170 you're done with this part. That was easy!
2172 @cindex @command{aclocal} program, introduction
2173 @cindex @file{aclocal.m4}, preexisting
2174 @cindex @file{acinclude.m4}, defined
2176 Now you must regenerate @file{configure}. But to do that, you'll need
2177 to tell @command{autoconf} how to find the new macro you've used. The
2178 easiest way to do this is to use the @command{aclocal} program to
2179 generate your @file{aclocal.m4} for you. But wait@dots{} maybe you
2180 already have an @file{aclocal.m4}, because you had to write some hairy
2181 macros for your program. The @command{aclocal} program lets you put
2182 your own macros into @file{acinclude.m4}, so simply rename and then
2186 mv aclocal.m4 acinclude.m4
2191 @cindex @command{zardoz} example
2193 Now it is time to write your @file{Makefile.am} for @code{zardoz}.
2194 Since @code{zardoz} is a user program, you want to install it where the
2195 rest of the user programs go: @code{bindir}. Additionally,
2196 @code{zardoz} has some Texinfo documentation. Your @file{configure.ac}
2197 script uses @code{AC_REPLACE_FUNCS}, so you need to link against
2198 @samp{$(LIBOBJS)}. So here's what you'd write:
2201 bin_PROGRAMS = zardoz
2202 zardoz_SOURCES = main.c head.c float.c vortex9.c gun.c
2203 zardoz_LDADD = $(LIBOBJS)
2205 info_TEXINFOS = zardoz.texi
2208 Now you can run @samp{automake --add-missing} to generate your
2209 @file{Makefile.in} and grab any auxiliary files you might need, and
2214 @section Building true and false
2216 @cindex Example, @command{false} and @command{true}
2217 @cindex @command{false} Example
2218 @cindex @command{true} Example
2220 Here is another, trickier example. It shows how to generate two
2221 programs (@code{true} and @code{false}) from the same source file
2222 (@file{true.c}). The difficult part is that each compilation of
2223 @file{true.c} requires different @code{cpp} flags.
2226 bin_PROGRAMS = true false
2228 false_LDADD = false.o
2231 $(COMPILE) -DEXIT_CODE=0 -c true.c
2234 $(COMPILE) -DEXIT_CODE=1 -o false.o -c true.c
2237 Note that there is no @code{true_SOURCES} definition. Automake will
2238 implicitly assume that there is a source file named @file{true.c}, and
2239 define rules to compile @file{true.o} and link @file{true}. The
2240 @samp{true.o: true.c} rule supplied by the above @file{Makefile.am},
2241 will override the Automake generated rule to build @file{true.o}.
2243 @code{false_SOURCES} is defined to be empty---that way no implicit value
2244 is substituted. Because we have not listed the source of
2245 @file{false}, we have to tell Automake how to link the program. This is
2246 the purpose of the @code{false_LDADD} line. A @code{false_DEPENDENCIES}
2247 variable, holding the dependencies of the @file{false} target will be
2248 automatically generated by Automake from the content of
2251 The above rules won't work if your compiler doesn't accept both
2252 @option{-c} and @option{-o}. The simplest fix for this is to introduce a
2253 bogus dependency (to avoid problems with a parallel @command{make}):
2256 true.o: true.c false.o
2257 $(COMPILE) -DEXIT_CODE=0 -c true.c
2260 $(COMPILE) -DEXIT_CODE=1 -c true.c && mv true.o false.o
2263 Also, these explicit rules do not work if the obsolete de-ANSI-fication feature
2264 is used (@pxref{ANSI}). Supporting de-ANSI-fication requires a little
2268 true_.o: true_.c false_.o
2269 $(COMPILE) -DEXIT_CODE=0 -c true_.c
2272 $(COMPILE) -DEXIT_CODE=1 -c true_.c && mv true_.o false_.o
2275 As it turns out, there is also a much easier way to do this same task.
2276 Some of the above techniques are useful enough that we've kept the
2277 example in the manual. However if you were to build @code{true} and
2278 @code{false} in real life, you would probably use per-program
2279 compilation flags, like so:
2282 bin_PROGRAMS = false true
2284 false_SOURCES = true.c
2285 false_CPPFLAGS = -DEXIT_CODE=1
2287 true_SOURCES = true.c
2288 true_CPPFLAGS = -DEXIT_CODE=0
2291 In this case Automake will cause @file{true.c} to be compiled twice,
2292 with different flags. De-ANSI-fication will work automatically. In
2293 this instance, the names of the object files would be chosen by
2294 automake; they would be @file{false-true.o} and @file{true-true.o}.
2295 (The name of the object files rarely matters.)
2298 @node Invoking Automake
2299 @chapter Creating a @file{Makefile.in}
2301 @cindex Multiple @file{configure.ac} files
2302 @cindex Invoking @command{automake}
2303 @cindex @command{automake}, invoking
2305 To create all the @file{Makefile.in}s for a package, run the
2306 @command{automake} program in the top level directory, with no
2307 arguments. @command{automake} will automatically find each
2308 appropriate @file{Makefile.am} (by scanning @file{configure.ac};
2309 @pxref{configure}) and generate the corresponding @file{Makefile.in}.
2310 Note that @command{automake} has a rather simplistic view of what
2311 constitutes a package; it assumes that a package has only one
2312 @file{configure.ac}, at the top. If your package has multiple
2313 @file{configure.ac}s, then you must run @command{automake} in each
2314 directory holding a @file{configure.ac}. (Alternatively, you may rely
2315 on Autoconf's @command{autoreconf}, which is able to recurse your
2316 package tree and run @command{automake} where appropriate.)
2318 You can optionally give @command{automake} an argument; @file{.am} is
2319 appended to the argument and the result is used as the name of the
2320 input file. This feature is generally only used to automatically
2321 rebuild an out-of-date @file{Makefile.in}. Note that
2322 @command{automake} must always be run from the topmost directory of a
2323 project, even if being used to regenerate the @file{Makefile.in} in
2324 some subdirectory. This is necessary because @command{automake} must
2325 scan @file{configure.ac}, and because @command{automake} uses the
2326 knowledge that a @file{Makefile.in} is in a subdirectory to change its
2327 behavior in some cases.
2330 Automake will run @command{autoconf} to scan @file{configure.ac} and
2331 its dependencies (i.e., @file{aclocal.m4} and any included file),
2332 therefore @command{autoconf} must be in your @env{PATH}. If there is
2333 an @env{AUTOCONF} variable in your environment it will be used
2334 instead of @command{autoconf}, this allows you to select a particular
2335 version of Autoconf. By the way, don't misunderstand this paragraph:
2336 @command{automake} runs @command{autoconf} to @strong{scan} your
2337 @file{configure.ac}, this won't build @file{configure} and you still
2338 have to run @command{autoconf} yourself for this purpose.
2340 @cindex @command{automake} options
2341 @cindex Options, @command{automake}
2342 @cindex Strictness, command line
2344 @command{automake} accepts the following options:
2346 @cindex Extra files distributed with Automake
2347 @cindex Files distributed with Automake
2348 @cindex @file{config.guess}
2352 @itemx --add-missing
2354 @opindex --add-missing
2355 Automake requires certain common files to exist in certain situations;
2356 for instance, @file{config.guess} is required if @file{configure.ac} runs
2357 @code{AC_CANONICAL_HOST}. Automake is distributed with several of these
2358 files (@pxref{Auxiliary Programs}); this option will cause the missing
2359 ones to be automatically added to the package, whenever possible. In
2360 general if Automake tells you a file is missing, try using this option.
2361 By default Automake tries to make a symbolic link pointing to its own
2362 copy of the missing file; this can be changed with @option{--copy}.
2364 Many of the potentially-missing files are common scripts whose
2365 location may be specified via the @code{AC_CONFIG_AUX_DIR} macro.
2366 Therefore, @code{AC_CONFIG_AUX_DIR}'s setting affects whether a
2367 file is considered missing, and where the missing file is added
2370 @item --libdir=@var{dir}
2372 Look for Automake data files in directory @var{dir} instead of in the
2373 installation directory. This is typically used for debugging.
2379 When used with @option{--add-missing}, causes installed files to be
2380 copied. The default is to make a symbolic link.
2384 Causes the generated @file{Makefile.in}s to follow Cygnus rules, instead
2385 of GNU or Gnits rules. For more information, see @ref{Cygnus}.
2389 @itemx --force-missing
2390 @opindex --force-missing
2391 When used with @option{--add-missing}, causes standard files to be reinstalled
2392 even if they already exist in the source tree. This involves removing
2393 the file from the source tree before creating the new symlink (or, with
2394 @option{--copy}, copying the new file).
2398 Set the global strictness to @option{foreign}. For more information, see
2403 Set the global strictness to @option{gnits}. For more information, see
2408 Set the global strictness to @option{gnu}. For more information, see
2409 @ref{Gnits}. This is the default strictness.
2413 Print a summary of the command line options and exit.
2416 @itemx --ignore-deps
2418 This disables the dependency tracking feature in generated
2419 @file{Makefile}s; see @ref{Dependencies}.
2421 @item --include-deps
2422 @opindex --include-deps
2423 This enables the dependency tracking feature. This feature is enabled
2424 by default. This option is provided for historical reasons only and
2425 probably should not be used.
2429 Ordinarily @command{automake} creates all @file{Makefile.in}s mentioned in
2430 @file{configure.ac}. This option causes it to only update those
2431 @file{Makefile.in}s that are out of date with respect to one of their
2435 @itemx --output-dir=@var{dir}
2437 @opindex --output-dir
2438 Put the generated @file{Makefile.in} in the directory @var{dir}.
2439 Ordinarily each @file{Makefile.in} is created in the directory of the
2440 corresponding @file{Makefile.am}. This option is deprecated and will be
2441 removed in a future release.
2447 Cause Automake to print information about which files are being read or
2452 Print the version number of Automake and exit.
2455 @item --warnings=@var{category}
2458 Output warnings falling in @var{category}. @var{category} can be
2462 warnings related to the GNU Coding Standards
2463 (@pxref{Top, , , standards, The GNU Coding Standards}).
2465 obsolete features or constructions
2467 user redefinitions of Automake rules or variables
2469 portability issues (e.g., use of @command{make} features that are
2470 known to be not portable)
2472 weird syntax, unused variables, typos
2474 unsupported or incomplete features
2478 turn off all the warnings
2480 treat warnings as errors
2483 A category can be turned off by prefixing its name with @samp{no-}. For
2484 instance, @option{-Wno-syntax} will hide the warnings about unused
2487 The categories output by default are @samp{syntax} and
2488 @samp{unsupported}. Additionally, @samp{gnu} and @samp{portability}
2489 are enabled in @option{--gnu} and @option{--gnits} strictness.
2492 The environment variable @env{WARNINGS} can contain a comma separated
2493 list of categories to enable. It will be taken into account before the
2494 command-line switches, this way @option{-Wnone} will also ignore any
2495 warning category enabled by @env{WARNINGS}. This variable is also used
2496 by other tools like @command{autoconf}; unknown categories are ignored
2503 @chapter Scanning @file{configure.ac}
2505 @cindex @file{configure.ac}, scanning
2506 @cindex Scanning @file{configure.ac}
2508 Automake scans the package's @file{configure.ac} to determine certain
2509 information about the package. Some @command{autoconf} macros are required
2510 and some variables must be defined in @file{configure.ac}. Automake
2511 will also use information from @file{configure.ac} to further tailor its
2514 Automake also supplies some Autoconf macros to make the maintenance
2515 easier. These macros can automatically be put into your
2516 @file{aclocal.m4} using the @command{aclocal} program.
2519 * Requirements:: Configuration requirements
2520 * Optional:: Other things Automake recognizes
2521 * Invoking aclocal:: Auto-generating aclocal.m4
2522 * Macros:: Autoconf macros supplied with Automake
2527 @section Configuration requirements
2529 @cindex Automake requirements
2530 @cindex Requirements of Automake
2532 @acindex AM_INIT_AUTOMAKE
2533 The one real requirement of Automake is that your @file{configure.ac}
2534 call @code{AM_INIT_AUTOMAKE}. This macro does several things that are
2535 required for proper Automake operation (@pxref{Macros}).
2537 Here are the other macros that Automake requires but which are not run
2538 by @code{AM_INIT_AUTOMAKE}:
2541 @item AC_CONFIG_FILES
2543 @acindex AC_CONFIG_FILES
2545 These two macros are usually invoked as follows near the end of
2546 @file{configure.ac}.
2560 Automake uses these to determine which files to create (@pxref{Output, ,
2561 Creating Output Files, autoconf, The Autoconf Manual}). A listed file
2562 is considered to be an Automake generated @file{Makefile} if there
2563 exists a file with the same name and the @file{.am} extension appended.
2564 Typically, @samp{AC_CONFIG_FILES([foo/Makefile])} will cause Automake to
2565 generate @file{foo/Makefile.in} if @file{foo/Makefile.am} exists.
2567 When using @code{AC_CONFIG_FILES} with multiple input files, as in
2570 AC_CONFIG_FILES([Makefile:top.in:Makefile.in:bot.in])
2574 @command{automake} will generate the first @file{.in} input file for
2575 which a @file{.am} file exists. If no such file exists the output
2576 file is not considered to be Automake generated.
2578 Files created by @code{AC_CONFIG_FILES}, be they Automake
2579 @file{Makefile}s or not, are all removed by @samp{make distclean}.
2580 Their inputs are automatically distributed, except for inputs that
2581 turn out the be outputs of prior @code{AC_CONFIG_FILES} commands.
2582 Finally, rebuild rules are generated in the Automake @file{Makefile}
2583 existing in the subdirectory of the output file, if there is one, or
2584 in the top-level @file{Makefile} otherwise.
2586 The above machinery (cleaning, distributing, and rebuilding) works
2587 fine if the @code{AC_CONFIG_FILES} specifications contain only
2588 literals. If part of the specification uses shell variables,
2589 @command{automake} will not be able to fulfill this setup, and you will
2590 have to complete the missing bits by hand. For instance, on
2595 AC_CONFIG_FILES([output:$file],, [file=$file])
2599 @command{automake} will output rules to clean @file{output}, and
2600 rebuild it. However the rebuild rule will not depend on @file{input},
2601 and this file will not be distributed either. (You must add
2602 @samp{EXTRA_DIST = input} to your @file{Makefile} if @file{input} is a
2611 AC_CONFIG_FILES([$file:input],, [file=$file])
2612 AC_CONFIG_FILES([$file2],, [file2=$file2])
2616 will only cause @file{input} to be distributed. No file will be
2617 cleaned automatically (add @samp{DISTCLEANFILES = output out}
2618 yourself), and no rebuild rule will be output.
2620 Obviously @command{automake} cannot guess what value @samp{$file} is
2621 going to hold later when @file{configure} is run, and it cannot use
2622 the shell variable @samp{$file} in a @file{Makefile}. However, if you
2623 make reference to @samp{$file} as @samp{$@{file@}} (i.e., in a way
2624 that is compatible with @command{make}'s syntax) and furthermore use
2625 @code{AC_SUBST} to ensure that @samp{$@{file@}} is meaningful in a
2626 @file{Makefile}, then @command{automake} will be able to use
2627 @samp{$@{file@}} to generate all these rules. For instance, here is
2628 how the Automake package itself generates versioned scripts for its
2632 AC_SUBST([APIVERSION], @dots{})
2635 [tests/aclocal-$@{APIVERSION@}:tests/aclocal.in],
2636 [chmod +x tests/aclocal-$@{APIVERSION@}],
2637 [APIVERSION=$APIVERSION])
2639 [tests/automake-$@{APIVERSION@}:tests/automake.in],
2640 [chmod +x tests/automake-$@{APIVERSION@}])
2644 Here cleaning, distributing, and rebuilding are done automatically,
2645 because @samp{$@{APIVERSION@}} is known at @command{make}-time.
2647 Note that you should not use shell variables to declare
2648 @file{Makefile} files for which @command{automake} must create
2649 @file{Makefile.in}. Even @code{AC_SUBST} does not help here, because
2650 @command{automake} needs to know the file name when it runs in order
2651 to check whether @file{Makefile.am} exists. (In the very hairy case
2652 that your setup requires such use of variables, you will have to tell
2653 Automake which @file{Makefile.in}s to generate on the command-line.)
2658 Use literals for @file{Makefile}s, and for other files whenever possible.
2660 Use @samp{$file} (or @samp{$@{file@}} without @samp{AC_SUBST([file])})
2661 for files that @command{automake} should ignore.
2663 Use @samp{$@{file@}} and @samp{AC_SUBST([file])} for files
2664 that @command{automake} should not ignore.
2671 @section Other things Automake recognizes
2673 @cindex Macros Automake recognizes
2674 @cindex Recognized macros by Automake
2676 Every time Automake is run it calls Autoconf to trace
2677 @file{configure.ac}. This way it can recognize the use of certain
2678 macros and tailor the generated @file{Makefile.in} appropriately.
2679 Currently recognized macros and their effects are:
2682 @item AC_CANONICAL_BUILD
2683 @itemx AC_CANONICAL_HOST
2684 @itemx AC_CANONICAL_TARGET
2685 @vindex build_triplet
2686 @vindex host_triplet
2687 @vindex target_triplet
2688 Automake will ensure that @file{config.guess} and @file{config.sub}
2689 exist. Also, the @file{Makefile} variables @code{build_triplet},
2690 @code{host_triplet} and @code{target_triplet} are introduced. See
2691 @ref{Canonicalizing, , Getting the Canonical System Type, autoconf,
2692 The Autoconf Manual}.
2694 @item AC_CONFIG_AUX_DIR
2695 Automake will look for various helper scripts, such as
2696 @file{install-sh}, in the directory named in this macro invocation.
2697 @c This list is accurate relative to version 1.8
2698 (The full list of scripts is: @file{config.guess}, @file{config.sub},
2699 @file{depcomp}, @file{elisp-comp}, @file{compile}, @file{install-sh},
2700 @file{ltmain.sh}, @file{mdate-sh}, @file{missing}, @file{mkinstalldirs},
2701 @file{py-compile}, @file{texinfo.tex}, and @file{ylwrap}.) Not all
2702 scripts are always searched for; some scripts will only be sought if the
2703 generated @file{Makefile.in} requires them.
2705 If @code{AC_CONFIG_AUX_DIR} is not given, the scripts are looked for in
2706 their standard locations. For @file{mdate-sh},
2707 @file{texinfo.tex}, and @file{ylwrap}, the standard location is the
2708 source directory corresponding to the current @file{Makefile.am}. For
2709 the rest, the standard location is the first one of @file{.}, @file{..},
2710 or @file{../..} (relative to the top source directory) that provides any
2711 one of the helper scripts. @xref{Input, , Finding `configure' Input,
2712 autoconf, The Autoconf Manual}.
2714 Required files from @code{AC_CONFIG_AUX_DIR} are automatically
2715 distributed, even if there is no @file{Makefile.am} in this directory.
2717 @item AC_CONFIG_LIBOBJ_DIR
2718 Automake will require the sources file declared with
2719 @code{AC_LIBSOURCE} (see below) in the directory specified by this
2722 @item AC_CONFIG_HEADERS
2723 Automake will generate rules to rebuild these headers. Older versions
2724 of Automake required the use of @code{AM_CONFIG_HEADER}
2725 (@pxref{Macros}); this is no longer the case today.
2727 As for @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the
2728 specification using shell variables will be ignored as far as
2729 cleaning, distributing, and rebuilding is concerned.
2731 @item AC_CONFIG_LINKS
2732 Automake will generate rules to remove @file{configure} generated
2733 links on @samp{make distclean} and to distribute named source files as
2734 part of @samp{make dist}.
2736 As for @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the
2737 specification using shell variables will be ignored as far as cleaning
2738 and distributing is concerned. (There is no rebuild rules for links.)
2742 @itemx AC_LIBSOURCES
2744 Automake will automatically distribute any file listed in
2745 @code{AC_LIBSOURCE} or @code{AC_LIBSOURCES}.
2747 Note that the @code{AC_LIBOBJ} macro calls @code{AC_LIBSOURCE}. So if
2748 an Autoconf macro is documented to call @samp{AC_LIBOBJ([file])}, then
2749 @file{file.c} will be distributed automatically by Automake. This
2750 encompasses many macros like @code{AC_FUNC_ALLOCA},
2751 @code{AC_FUNC_MEMCMP}, @code{AC_REPLACE_FUNCS}, and others.
2753 By the way, direct assignments to @code{LIBOBJS} are no longer
2754 supported. You should always use @code{AC_LIBOBJ} for this purpose.
2755 @xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs.@: @code{LIBOBJS},
2756 autoconf, The Autoconf Manual}.
2758 @item AC_PROG_RANLIB
2759 This is required if any libraries are built in the package.
2760 @xref{Particular Programs, , Particular Program Checks, autoconf, The
2764 This is required if any C++ source is included. @xref{Particular
2765 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
2768 This is required if any Objective C source is included. @xref{Particular
2769 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
2772 This is required if any Fortran 77 source is included. This macro is
2773 distributed with Autoconf version 2.13 and later. @xref{Particular
2774 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
2776 @item AC_F77_LIBRARY_LDFLAGS
2777 This is required for programs and shared libraries that are a mixture of
2778 languages that include Fortran 77 (@pxref{Mixing Fortran 77 With C and
2779 C++}). @xref{Macros, , Autoconf macros supplied with Automake}.
2782 Automake will add the flags computed by @code{AC_FC_SRCEXT} to compilation
2783 of files with the respective source extension (@pxref{Fortran Compiler, ,
2784 Fortran Compiler Characteristics, autoconf, The Autoconf Manual}).
2787 This is required if any Fortran 90/95 source is included. This macro is
2788 distributed with Autoconf version 2.58 and later. @xref{Particular
2789 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
2791 @item AC_PROG_LIBTOOL
2792 Automake will turn on processing for @command{libtool} (@pxref{Top, ,
2793 Introduction, libtool, The Libtool Manual}).
2797 If a Yacc source file is seen, then you must either use this macro or
2798 define the variable @code{YACC} in @file{configure.ac}. The former is
2799 preferred (@pxref{Particular Programs, , Particular Program Checks,
2800 autoconf, The Autoconf Manual}).
2803 If a Lex source file is seen, then this macro must be used.
2804 @xref{Particular Programs, , Particular Program Checks, autoconf, The
2807 @item AC_REQUIRE_AUX_FILE
2808 @command{automake} will ensure each file for which this macro is
2809 called exists in the aux directory, and will complain otherwise. It
2810 will also automatically distribute the file. This macro should be
2811 used by third-party Autoconf macros that requires some supporting
2812 files in the aux directory specified with @code{AC_CONFIG_AUX_DIR}
2813 above. @xref{Input, , Finding @command{configure} Input, autoconf,
2814 The Autoconf Manual}.
2817 The first argument is automatically defined as a variable in each
2818 generated @file{Makefile.in}. @xref{Setting Output Variables, , Setting
2819 Output Variables, autoconf, The Autoconf Manual}.
2821 If the Autoconf manual says that a macro calls @code{AC_SUBST} for
2822 @var{var}, or defines the output variable @var{var} then @var{var} will
2823 be defined in each @file{Makefile.in} generated by Automake.
2824 E.g.@: @code{AC_PATH_XTRA} defines @code{X_CFLAGS} and @code{X_LIBS}, so
2825 you can use these variables in any @file{Makefile.am} if
2826 @code{AC_PATH_XTRA} is called.
2828 @item AM_C_PROTOTYPES
2829 This is required when using the obsolete de-ANSI-fication feature; see
2832 @item AM_GNU_GETTEXT
2833 This macro is required for packages that use GNU gettext
2834 (@pxref{gettext}). It is distributed with gettext. If Automake sees
2835 this macro it ensures that the package meets some of gettext's
2838 @item AM_GNU_GETTEXT_INTL_SUBDIR
2839 This macro specifies that the @file{intl/} subdirectory is to be built,
2840 even if the @code{AM_GNU_GETTEXT} macro was invoked with a first argument
2843 @item AM_MAINTAINER_MODE
2844 @opindex --enable-maintainer-mode
2845 This macro adds a @option{--enable-maintainer-mode} option to
2846 @command{configure}. If this is used, @command{automake} will cause
2847 ``maintainer-only'' rules to be turned off by default in the
2848 generated @file{Makefile.in}s. This macro defines the
2849 @code{MAINTAINER_MODE} conditional, which you can use in your own
2850 @file{Makefile.am}. @xref{maintainer-mode}.
2853 Files included by @file{configure.ac} using this macro will be
2854 detected by Automake and automatically distributed. They will also
2855 appear as dependencies in @file{Makefile} rules.
2857 @code{m4_include} is seldom used by @file{configure.ac} authors, but
2858 can appear in @file{aclocal.m4} when @command{aclocal} detects that
2859 some required macros come from files local to your package (as opposed
2860 to macros installed in a system-wide directory, @pxref{Invoking
2866 @node Invoking aclocal
2867 @section Auto-generating aclocal.m4
2869 @cindex Invoking @command{aclocal}
2870 @cindex @command{aclocal}, Invoking
2872 Automake includes a number of Autoconf macros that can be used in
2873 your package (@pxref{Macros}); some of them are actually required by
2874 Automake in certain situations. These macros must be defined in your
2875 @file{aclocal.m4}; otherwise they will not be seen by
2878 The @command{aclocal} program will automatically generate
2879 @file{aclocal.m4} files based on the contents of @file{configure.ac}.
2880 This provides a convenient way to get Automake-provided macros,
2881 without having to search around. The @command{aclocal} mechanism
2882 allows other packages to supply their own macros (@pxref{Extending
2883 aclocal}). You can also use it to maintain your own set of custom
2884 macros (@pxref{Local Macros}).
2886 At startup, @command{aclocal} scans all the @file{.m4} files it can
2887 find, looking for macro definitions (@pxref{Macro search path}). Then
2888 it scans @file{configure.ac}. Any mention of one of the macros found
2889 in the first step causes that macro, and any macros it in turn
2890 requires, to be put into @file{aclocal.m4}.
2892 @emph{Putting} the file that contains the macro definition into
2893 @file{aclocal.m4} is usually done by copying the entire text of this
2894 file, including unused macro definitions as well as both @samp{#} and
2895 @samp{dnl} comments. If you want to make a comment that will be
2896 completely ignored by @command{aclocal}, use @samp{##} as the comment
2899 When a file selected by @command{aclocal} is located in a subdirectory
2900 specified as a relative search path with @command{aclocal}'s @option{-I}
2901 argument, @command{aclocal} assumes the file belongs to the package
2902 and uses @code{m4_include} instead of copying it into
2903 @file{aclocal.m4}. This makes the package smaller, eases dependency
2904 tracking, and cause the file to be distributed automatically.
2905 (@xref{Local Macros}, for an example.) Any macro that is found in a
2906 system-wide directory, or via an absolute search path will be copied.
2907 So use @samp{-I `pwd`/reldir} instead of @samp{-I reldir} whenever
2908 some relative directory need to be considered outside the package.
2910 The contents of @file{acinclude.m4}, if this file exists, are also
2911 automatically included in @file{aclocal.m4}. We recommend against
2912 using @file{acinclude.m4} in new packages (@pxref{Local Macros}).
2916 While computing @file{aclocal.m4}, @command{aclocal} runs
2917 @command{autom4te} (@pxref{Using autom4te, , Using @command{Autom4te},
2918 autoconf, The Autoconf Manual}) in order to trace the macros that are
2919 really used, and omit from @file{aclocal.m4} all macros that are
2920 mentioned but otherwise unexpanded (this can happen when a macro is
2921 called conditionally). @command{autom4te} is expected to be in the
2922 @env{PATH}, just as @command{autoconf}. Its location can be
2923 overridden using the @env{AUTOM4TE} environment variable.
2926 * aclocal options:: Options supported by aclocal
2927 * Macro search path:: How aclocal finds .m4 files
2928 * Extending aclocal:: Writing your own aclocal macros
2929 * Local Macros:: Organizing local macros
2930 * Serials:: Serial lines in Autoconf macros
2931 * Future of aclocal:: aclocal's scheduled death
2934 @node aclocal options
2935 @subsection aclocal options
2937 @cindex @command{aclocal}, Options
2938 @cindex Options, @command{aclocal}
2940 @command{aclocal} accepts the following options:
2943 @item --acdir=@var{dir}
2945 Look for the macro files in @var{dir} instead of the installation
2946 directory. This is typically used for debugging.
2948 @item --diff[=@var{command}]
2950 Run @var{command} on M4 file that would be installed or overwritten
2951 by @option{--install}. The default @var{command} is @samp{diff -u}.
2952 This option implies @option{--install} and @option{--dry-run}.
2956 Do not actually overwrite (or create) @file{aclocal.m4} and M4
2957 files installed by @option{--install}.
2961 Print a summary of the command line options and exit.
2965 Add the directory @var{dir} to the list of directories searched for
2970 Install system-wide third-party macros into the first directory
2971 specified with @samp{-I @var{dir}} instead of copying them in the
2974 @cindex serial number and @option{--install}
2975 When this option is used, and only when this option is used,
2976 @command{aclocal} will also honor @samp{#serial @var{NUMBER}} lines
2977 that appear in macros: an M4 file is ignored if there exists another
2978 M4 file with the same basename and a greater serial number in the
2979 search path (@pxref{Serials}).
2983 Always overwrite the output file. The default is to overwrite the output
2984 file only when really needed, i.e., when its contents changes or if one
2985 of its dependencies is younger.
2987 This option forces the update of @file{aclocal.m4} (or the file
2988 specified with @file{--output} below) and only this file, it has
2989 absolutely no influence on files that may need to be installed by
2992 @item --output=@var{file}
2994 Cause the output to be put into @var{file} instead of @file{aclocal.m4}.
2996 @item --print-ac-dir
2997 @opindex --print-ac-dir
2998 Prints the name of the directory that @command{aclocal} will search to
2999 find third-party @file{.m4} files. When this option is given, normal
3000 processing is suppressed. This option can be used by a package to
3001 determine where to install a macro file.
3005 Print the names of the files it examines.
3009 Print the version number of Automake and exit.
3012 @item --warnings=@var{category}
3015 Output warnings falling in @var{category}. @var{category} can be
3019 dubious syntactic constructs, underquoted macros, unused macros, etc.
3023 all the warnings, this is the default
3025 turn off all the warnings
3027 treat warnings as errors
3030 All warnings are output by default.
3033 The environment variable @env{WARNINGS} is honored in the same
3034 way as it is for @command{automake} (@pxref{Invoking Automake}).
3038 @node Macro search path
3039 @subsection Macro search path
3041 @cindex Macro search path
3042 @cindex @command{aclocal} search path
3044 By default, @command{aclocal} searches for @file{.m4} files in the following
3045 directories, in this order:
3048 @item @var{acdir-APIVERSION}
3049 This is where the @file{.m4} macros distributed with automake itself
3050 are stored. @var{APIVERSION} depends on the automake release used;
3051 for automake 1.6.x, @var{APIVERSION} = @code{1.6}.
3054 This directory is intended for third party @file{.m4} files, and is
3055 configured when @command{automake} itself is built. This is
3056 @file{@@datadir@@/aclocal/}, which typically
3057 expands to @file{$@{prefix@}/share/aclocal/}. To find the compiled-in
3058 value of @var{acdir}, use the @option{--print-ac-dir} option
3059 (@pxref{aclocal options}).
3062 As an example, suppose that @command{automake-1.6.2} was configured with
3063 @option{--prefix=@-/usr/local}. Then, the search path would be:
3066 @item @file{/usr/local/share/aclocal-1.6/}
3067 @item @file{/usr/local/share/aclocal/}
3070 As explained in (@pxref{aclocal options}), there are several options that
3071 can be used to change or extend this search path.
3073 @subsubsection Modifying the macro search path: @option{--acdir}
3075 The most erroneous option to modify the search path is
3076 @option{--acdir=@var{dir}}, which changes default directory and
3077 drops the @var{APIVERSION} directory. For example, if one specifies
3078 @samp{--acdir=/opt/private/}, then the search path becomes:
3081 @item @file{/opt/private/}
3084 This option, @option{--acdir}, is intended for use by the internal
3085 automake test suite only; it is not ordinarily needed by end-users.
3087 @subsubsection Modifying the macro search path: @samp{-I @var{dir}}
3089 Any extra directories specified using @option{-I} options
3090 (@pxref{aclocal options}) are @emph{prepended} to this search list. Thus,
3091 @samp{aclocal -I /foo -I /bar} results in the following search path:
3096 @item @var{acdir}-@var{APIVERSION}
3100 @subsubsection Modifying the macro search path: @file{dirlist}
3101 @cindex @file{dirlist}
3103 There is a third mechanism for customizing the search path. If a
3104 @file{dirlist} file exists in @var{acdir}, then that file is assumed to
3105 contain a list of directory patterns, one per line. @command{aclocal}
3106 expands these patterns to directory names, and adds them to the search
3107 list @emph{after} all other directories. @file{dirlist} entries may
3108 use shell wildcards such as @samp{*}, @samp{?}, or @code{[...]}.
3110 For example, suppose
3111 @file{@var{acdir}/dirlist} contains the following:
3120 and that @command{aclocal} was called with the @samp{-I /foo -I /bar} options.
3121 Then, the search path would be
3123 @c @code looks better than @file here
3127 @item @var{acdir}-@var{APIVERSION}
3134 and all directories with path names starting with @code{/test3}.
3136 If the @option{--acdir=@var{dir}} option is used, then @command{aclocal}
3137 will search for the @file{dirlist} file in @var{dir}. In the
3138 @samp{--acdir=/opt/private/} example above, @command{aclocal} would look
3139 for @file{/opt/private/dirlist}. Again, however, the @option{--acdir}
3140 option is intended for use by the internal automake test suite only;
3141 @option{--acdir} is not ordinarily needed by end-users.
3143 @file{dirlist} is useful in the following situation: suppose that
3144 @command{automake} version @code{1.6.2} is installed with
3145 @samp{--prefix=/usr} by the system vendor. Thus, the default search
3148 @c @code looks better than @file here
3150 @item @code{/usr/share/aclocal-1.6/}
3151 @item @code{/usr/share/aclocal/}
3154 However, suppose further that many packages have been manually
3155 installed on the system, with $prefix=/usr/local, as is typical. In
3156 that case, many of these ``extra'' @file{.m4} files are in
3157 @file{/usr/local/share/aclocal}. The only way to force
3158 @file{/usr/bin/aclocal} to find these ``extra'' @file{.m4} files is to
3159 always call @samp{aclocal -I /usr/local/share/aclocal}. This is
3160 inconvenient. With @file{dirlist}, one may create a file
3161 @file{/usr/share/aclocal/dirlist} containing only the single line
3164 /usr/local/share/aclocal
3167 Now, the ``default'' search path on the affected system is
3169 @c @code looks better than @file here
3171 @item @code{/usr/share/aclocal-1.6/}
3172 @item @code{/usr/share/aclocal/}
3173 @item @code{/usr/local/share/aclocal/}
3176 without the need for @option{-I} options; @option{-I} options can be reserved
3177 for project-specific needs (@file{my-source-dir/m4/}), rather than
3178 using it to work around local system-dependent tool installation
3181 Similarly, @file{dirlist} can be handy if you have installed a local
3182 copy Automake on your account and want @command{aclocal} to look for
3183 macros installed at other places on the system.
3186 @node Extending aclocal
3187 @subsection Writing your own aclocal macros
3189 @cindex @command{aclocal}, extending
3190 @cindex Extending @command{aclocal}
3192 The @command{aclocal} program doesn't have any built-in knowledge of any
3193 macros, so it is easy to extend it with your own macros.
3195 This can be used by libraries that want to supply their own Autoconf
3196 macros for use by other programs. For instance, the @command{gettext}
3197 library supplies a macro @code{AM_GNU_GETTEXT} that should be used by
3198 any package using @command{gettext}. When the library is installed, it
3199 installs this macro so that @command{aclocal} will find it.
3201 A macro file's name should end in @file{.m4}. Such files should be
3202 installed in @file{$(datadir)/aclocal}. This is as simple as writing:
3205 aclocaldir = $(datadir)/aclocal
3206 aclocal_DATA = mymacro.m4 myothermacro.m4
3210 Please do use @file{$(datadir)/aclocal}, and not something based on
3211 the result of @samp{aclocal --print-ac-dir}. @xref{Hard-Coded Install
3212 Paths}, for arguments.
3214 A file of macros should be a series of properly quoted
3215 @code{AC_DEFUN}'s (@pxref{Macro Definitions, , , autoconf, The
3216 Autoconf Manual}). The @command{aclocal} programs also understands
3217 @code{AC_REQUIRE} (@pxref{Prerequisite Macros, , , autoconf, The
3218 Autoconf Manual}), so it is safe to put each macro in a separate file.
3219 Each file should have no side effects but macro definitions.
3220 Especially, any call to @code{AC_PREREQ} should be done inside the
3221 defined macro, not at the beginning of the file.
3223 @cindex underquoted @code{AC_DEFUN}
3227 Starting with Automake 1.8, @command{aclocal} will warn about all
3228 underquoted calls to @code{AC_DEFUN}. We realize this will annoy a
3229 lot of people, because @command{aclocal} was not so strict in the past
3230 and many third party macros are underquoted; and we have to apologize
3231 for this temporary inconvenience. The reason we have to be stricter
3232 is that a future implementation of @command{aclocal} (@pxref{Future of
3233 aclocal}) will have to temporarily include all these third party
3234 @file{.m4} files, maybe several times, including even files that are
3235 not actually needed. Doing so should alleviate many problems of the
3236 current implementation, however it requires a stricter style from the
3237 macro authors. Hopefully it is easy to revise the existing macros.
3243 [AC_REQUIRE([AX_SOMETHING])dnl
3249 should be rewritten as
3251 AC_DEFUN([AX_FOOBAR],
3252 [AC_PREREQ([2.57])dnl
3253 AC_REQUIRE([AX_SOMETHING])dnl
3259 Wrapping the @code{AC_PREREQ} call inside the macro ensures that
3260 Autoconf 2.57 will not be required if @code{AX_FOOBAR} is not actually
3261 used. Most importantly, quoting the first argument of @code{AC_DEFUN}
3262 allows the macro to be redefined or included twice (otherwise this
3263 first argument would be expanded during the second definition). For
3264 consistency we like to quote even arguments such as @code{2.57} that
3267 If you have been directed here by the @command{aclocal} diagnostic but
3268 are not the maintainer of the implicated macro, you will want to
3269 contact the maintainer of that macro. Please make sure you have the
3270 last version of the macro and that the problem already hasn't been
3271 reported before doing so: people tend to work faster when they aren't
3274 Another situation where @command{aclocal} is commonly used is to
3275 manage macros that are used locally by the package, @ref{Local
3279 @subsection Handling Local Macros
3281 Feature tests offered by Autoconf do not cover all needs. People
3282 often have to supplement existing tests with their own macros, or
3283 with third-party macros.
3285 There are two ways to organize custom macros in a package.
3287 The first possibility (the historical practice) is to list all your
3288 macros in @file{acinclude.m4}. This file will be included in
3289 @file{aclocal.m4} when you run @command{aclocal}, and its macro(s) will
3290 henceforth be visible to @command{autoconf}. However if it contains
3291 numerous macros, it will rapidly become difficult to maintain, and it
3292 will be almost impossible to share macros between packages.
3294 @vindex ACLOCAL_AMFLAGS
3295 The second possibility, which we do recommend, is to write each macro
3296 in its own file and gather all these files in a directory. This
3297 directory is usually called @file{m4/}. To build @file{aclocal.m4},
3298 one should therefore instruct @command{aclocal} to scan @file{m4/}.
3299 From the command line, this is done with @samp{aclocal -I m4}. The
3300 top-level @file{Makefile.am} should also be updated to define
3303 ACLOCAL_AMFLAGS = -I m4
3306 @code{ACLOCAL_AMFLAGS} contains options to pass to @command{aclocal}
3307 when @file{aclocal.m4} is to be rebuilt by @command{make}. This line is
3308 also used by @command{autoreconf} (@pxref{autoreconf Invocation, ,
3309 Using @command{autoreconf} to Update @file{configure} Scripts,
3310 autoconf, The Autoconf Manual}) to run @command{aclocal} with suitable
3311 options, or by @command{autopoint} (@pxref{autopoint Invocation, ,
3312 Invoking the @command{autopoint} Program, gettext, GNU gettext tools})
3313 and @command{gettextize} (@pxref{gettextize Invocation, , Invoking the
3314 @command{gettextize} Program, gettext, GNU gettext tools}) to locate
3315 the place where Gettext's macros should be installed. So even if you
3316 do not really care about the rebuild rules, you should define
3317 @code{ACLOCAL_AMFLAGS}.
3319 When @samp{aclocal -I m4} is run, it will build a @file{aclocal.m4}
3320 that @code{m4_include}s any file from @file{m4/} that defines a
3321 required macro. Macros not found locally will still be searched in
3322 system-wide directories, as explained in @ref{Macro search path}.
3324 Custom macros should be distributed for the same reason that
3325 @file{configure.ac} is: so that other people have all the sources of
3326 your package if they want to work on it. Actually, this distribution
3327 happens automatically because all @code{m4_include}d files are
3330 However there is no consensus on the distribution of third-party
3331 macros that your package may use. Many libraries install their own
3332 macro in the system-wide @command{aclocal} directory (@pxref{Extending
3333 aclocal}). For instance, Guile ships with a file called
3334 @file{guile.m4} that contains the macro @code{GUILE_FLAGS} that can
3335 be used to define setup compiler and linker flags appropriate for
3336 using Guile. Using @code{GUILE_FLAGS} in @file{configure.ac} will
3337 cause @command{aclocal} to copy @file{guile.m4} into
3338 @file{aclocal.m4}, but as @file{guile.m4} is not part of the project,
3339 it will not be distributed. Technically, that means a user who
3340 needs to rebuild @file{aclocal.m4} will have to install Guile first.
3341 This is probably OK, if Guile already is a requirement to build the
3342 package. However, if Guile is only an optional feature, or if your
3343 package might run on architectures where Guile cannot be installed,
3344 this requirement will hinder development. An easy solution is to copy
3345 such third-party macros in your local @file{m4/} directory so they get
3348 Since Automake 1.10, @command{aclocal} offers an option to copy these
3349 system-wide third-party macros in your local macro directory, solving
3350 the above problem. Simply use:
3353 ACLOCAL_AMFLAGS = -I m4 --install
3357 With this setup, system-wide macros will be copied to @file{m4/}
3358 the first time you run @command{autoreconf}. Then the locally
3359 installed macros will have precedence over the system-wide installed
3360 macros each time @command{aclocal} is run again.
3362 One reason why you should keep @option{--install} in the flags even
3363 after the first run is that when you later edit @file{configure.ac}
3364 and depend on a new macro, this macro will be installed in your
3365 @file{m4/} automatically. Another one is that serial numbers
3366 (@pxref{Serials}) can be used to update the macros in your source tree
3367 automatically when new system-wide versions are installed. A serial
3368 number should be a single line of the form
3375 where @var{NNN} contains only digits and dots. It should appear in
3376 the M4 file before any macro definition. It is a good practice to
3377 maintain a serial number for each macro you distribute, even if you do
3378 not use the @option{--install} option of @command{aclocal}: this allows
3379 other people to use it.
3383 @subsection Serial Numbers
3384 @cindex serial numbers in macros
3385 @cindex macro serial numbers
3386 @cindex @code{#serial} syntax
3387 @cindex @command{aclocal} and serial numbers
3389 Because third-party macros defined in @file{*.m4} files are naturally
3390 shared between multiple projects, some people like to version them.
3391 This makes it easier to tell which of two M4 files is newer. Since at
3392 least 1996, the tradition is to use a @samp{#serial} line for this.
3394 A serial number should be a single line of the form
3397 # serial @var{version}
3401 where @var{version} is a version number containing only digits and
3402 dots. Usually people use a single integer, and they increment it each
3403 time they change the macro (hence the name of ``serial''). Such a
3404 line should appear in the M4 file before any macro definition.
3406 The @samp{#} must be the first character on the line,
3407 and it is OK to have extra words after the version, as in
3410 #serial @var{version} @var{garbage}
3413 Normally these serial numbers are completely ignored by
3414 @command{aclocal} and @command{autoconf}, like any genuine comment.
3415 However when using @command{aclocal}'s @option{--install} feature, these
3416 serial numbers will modify the way @command{aclocal} selects the
3417 macros to install in the package: if two files with the same basename
3418 exists in your search path, and if at least one of them use a
3419 @samp{#serial} line, @command{aclocal} will ignore the file that has
3420 the older @samp{#serial} line (or the file that has none).
3422 Note that a serial number applies to a whole M4 file, not to any macro
3423 it contains. A file can contains multiple macros, but only one
3426 Here is a use case that illustrate the use of @option{--install} and
3427 its interaction with serial numbers. Let's assume we maintain a
3428 package called MyPackage, the @file{configure.ac} of which requires a
3429 third-party macro @code{AX_THIRD_PARTY} defined in
3430 @file{/usr/share/aclocal/thirdparty.m4} as follows:
3434 AC_DEFUN([AX_THIRD_PARTY], [...])
3437 MyPackage uses an @file{m4/} directory to store local macros as
3438 explained in @ref{Local Macros}, and has
3441 ACLOCAL_AMFLAGS = -I m4 --install
3445 in its top-level @file{Makefile.am}.
3447 Initially the @file{m4/} directory is empty. The first time we run
3448 @command{autoreconf}, it will fetch the options to pass to
3449 @command{aclocal} in @file{Makefile.am}, and run @samp{aclocal -I m4
3450 --install}. @command{aclocal} will notice that
3454 @file{configure.ac} uses @code{AX_THIRD_PARTY}
3456 No local macros define @code{AX_THIRD_PARTY}
3458 @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3463 Because @file{/usr/share/aclocal/thirdparty.m4} is a system-wide macro
3464 and @command{aclocal} was given the @option{--install} option, it will
3465 copy this file in @file{m4/thirdparty.m4}, and output an
3466 @file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}.
3468 The next time @samp{aclocal -I m4 --install} is run (either via
3469 @command{autoreconf}, by hand, or from the @file{Makefile} rebuild
3470 rules) something different happens. @command{aclocal} notices that
3474 @file{configure.ac} uses @code{AX_THIRD_PARTY}
3476 @file{m4/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3479 @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3484 Because both files have the same serial number, @command{aclocal} uses
3485 the first it found in its search path order (@pxref{Macro search
3486 path}). @command{aclocal} therefore ignores
3487 @file{/usr/share/aclocal/thirdparty.m4} and outputs an
3488 @file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}.
3490 Local directories specified with @option{-I} are always searched before
3491 system-wide directories, so a local file will always be preferred to
3492 the system-wide file in case of equal serial numbers.
3494 Now suppose the system-wide third-party macro is changed. This can
3495 happen if the package installing this macro is updated. Let's suppose
3496 the new macro has serial number 2. The next time @samp{aclocal -I m4
3497 --install} is run the situation is the following:
3501 @file{configure.ac} uses @code{AX_THIRD_PARTY}
3503 @file{m4/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3506 @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3511 When @command{aclocal} sees a greater serial number, it immediately
3512 forgets anything it knows from files that have the same basename and a
3513 smaller serial number. So after it has found
3514 @file{/usr/share/aclocal/thirdparty.m4} with serial 2,
3515 @command{aclocal} will proceed as if it had never seen
3516 @file{m4/thirdparty.m4}. This brings us back to a situation similar
3517 to that at the beginning of our example, where no local file defined
3518 the macro. @command{aclocal} will install the new version of the
3519 macro in @file{m4/thirdparty.m4}, in this case overriding the old
3520 version. MyPackage just had its macro updated as a side effect of
3521 running @command{aclocal}.
3523 If you are leery of letting @command{aclocal} update your local macro,
3524 you can run @samp{aclocal -I m4 --diff} to review the changes
3525 @samp{aclocal -I m4 --install} would perform on these macros.
3527 Finally, note that the @option{--force} option of @command{aclocal} has
3528 absolutely no effect on the files installed by @option{--install}. For
3529 instance, if you have modified your local macros, do not expect
3530 @option{--install --force} to replace the local macros by their
3531 system-wide versions. If you want to do so, simply erase the local
3532 macros you want to revert, and run @samp{aclocal -I m4 --install}.
3535 @node Future of aclocal
3536 @subsection The Future of @command{aclocal}
3537 @cindex @command{aclocal}'s scheduled death
3539 @command{aclocal} is expected to disappear. This feature really
3540 should not be offered by Automake. Automake should focus on
3541 generating @file{Makefile}s; dealing with M4 macros really is
3542 Autoconf's job. That some people install Automake just to use
3543 @command{aclocal}, but do not use @command{automake} otherwise is an
3544 indication of how that feature is misplaced.
3546 The new implementation will probably be done slightly differently.
3547 For instance, it could enforce the @file{m4/}-style layout discussed in
3550 We have no idea when and how this will happen. This has been
3551 discussed several times in the past, but someone still has to commit
3552 itself to that non-trivial task.
3554 From the user point of view, @command{aclocal}'s removal might turn
3555 out to be painful. There is a simple precaution that you may take to
3556 make that switch more seamless: never call @command{aclocal} yourself.
3557 Keep this guy under the exclusive control of @command{autoreconf} and
3558 Automake's rebuild rules. Hopefully you won't need to worry about
3559 things breaking, when @command{aclocal} disappears, because everything
3560 will have been taken care of. If otherwise you used to call
3561 @command{aclocal} directly yourself or from some script, you will
3562 quickly notice the change.
3564 Many packages come with a script called @file{bootstrap.sh} or
3565 @file{autogen.sh}, that will just call @command{aclocal},
3566 @command{libtoolize}, @command{gettextize} or @command{autopoint},
3567 @command{autoconf}, @command{autoheader}, and @command{automake} in
3568 the right order. Actually this is precisely what @command{autoreconf}
3569 can do for you. If your package has such a @file{bootstrap.sh} or
3570 @file{autogen.sh} script, consider using @command{autoreconf}. That
3571 should simplify its logic a lot (less things to maintain, yum!), it's
3572 even likely you will not need the script anymore, and more to the point
3573 you will not call @command{aclocal} directly anymore.
3575 For the time being, third-party packages should continue to install
3576 public macros into @file{/usr/share/aclocal/}. If @command{aclocal}
3577 is replaced by another tool it might make sense to rename the
3578 directory, but supporting @file{/usr/share/aclocal/} for backward
3579 compatibility should be really easy provided all macros are properly
3580 written (@pxref{Extending aclocal}).
3585 @section Autoconf macros supplied with Automake
3587 Automake ships with several Autoconf macros that you can use from your
3588 @file{configure.ac}. When you use one of them it will be included by
3589 @command{aclocal} in @file{aclocal.m4}.
3592 * Public macros:: Macros that you can use.
3593 * Obsolete macros:: Macros that you should stop using.
3594 * Private macros:: Macros that you should not use.
3597 @c consider generating the following subsections automatically from m4 files.
3600 @subsection Public macros
3604 @item AM_ENABLE_MULTILIB
3605 @acindex AM_ENABLE_MULTILIB
3606 This is used when a ``multilib'' library is being built. The first
3607 optional argument is the name of the @file{Makefile} being generated; it
3608 defaults to @samp{Makefile}. The second option argument is used to find
3609 the top source directory; it defaults to the empty string (generally
3610 this should not be used unless you are familiar with the internals).
3613 @item AM_INIT_AUTOMAKE([OPTIONS])
3614 @itemx AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])
3615 @acindex AM_INIT_AUTOMAKE
3616 Runs many macros required for proper operation of the generated Makefiles.
3618 @vindex AUTOMAKE_OPTIONS
3619 This macro has two forms, the first of which is preferred.
3620 In this form, @code{AM_INIT_AUTOMAKE} is called with a
3621 single argument: a space-separated list of Automake options that should
3622 be applied to every @file{Makefile.am} in the tree. The effect is as if
3623 each option were listed in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
3626 The second, deprecated, form of @code{AM_INIT_AUTOMAKE} has two required
3627 arguments: the package and the version number. This form is
3628 obsolete because the @var{package} and @var{version} can be obtained
3629 from Autoconf's @code{AC_INIT} macro (which itself has an old and a new
3632 If your @file{configure.ac} has:
3635 AC_INIT([src/foo.c])
3636 AM_INIT_AUTOMAKE([mumble], [1.5])
3640 you can modernize it as follows:
3643 AC_INIT([mumble], [1.5])
3644 AC_CONFIG_SRCDIR([src/foo.c])
3648 Note that if you're upgrading your @file{configure.ac} from an earlier
3649 version of Automake, it is not always correct to simply move the
3650 package and version arguments from @code{AM_INIT_AUTOMAKE} directly to
3651 @code{AC_INIT}, as in the example above. The first argument to
3652 @code{AC_INIT} should be the name of your package (e.g., @samp{GNU
3653 Automake}), not the tarball name (e.g., @samp{automake}) that you used
3654 to pass to @code{AM_INIT_AUTOMAKE}. Autoconf tries to derive a
3655 tarball name from the package name, which should work for most but not
3656 all package names. (If it doesn't work for yours, you can use the
3657 four-argument form of @code{AC_INIT} to provide the tarball name
3660 @cindex @code{PACKAGE}, prevent definition
3661 @cindex @code{VERSION}, prevent definition
3663 By default this macro @code{AC_DEFINE}'s @code{PACKAGE} and
3664 @code{VERSION}. This can be avoided by passing the @option{no-define}
3667 AM_INIT_AUTOMAKE([gnits 1.5 no-define dist-bzip2])
3669 or by passing a third non-empty argument to the obsolete form.
3671 @item AM_PATH_LISPDIR
3672 @acindex AM_PATH_LISPDIR
3675 Searches for the program @command{emacs}, and, if found, sets the
3676 output variable @code{lispdir} to the full path to Emacs' site-lisp
3679 Note that this test assumes the @command{emacs} found to be a version
3680 that supports Emacs Lisp (such as @sc{gnu} Emacs or XEmacs). Other
3681 emacsen can cause this test to hang (some, like old versions of
3682 MicroEmacs, start up in interactive mode, requiring @kbd{C-x C-c} to
3683 exit, which is hardly obvious for a non-emacs user). In most cases,
3684 however, you should be able to use @kbd{C-c} to kill the test. In
3685 order to avoid problems, you can set @env{EMACS} to ``no'' in the
3686 environment, or use the @option{--with-lispdir} option to
3687 @command{configure} to explicitly set the correct path (if you're sure
3688 you have an @command{emacs} that supports Emacs Lisp.
3694 Use this macro when you have assembly code in your project. This will
3695 choose the assembler for you (by default the C compiler) and set
3696 @code{CCAS}, and will also set @code{CCASFLAGS} if required.
3698 @item AM_PROG_CC_C_O
3699 @acindex AM_PROG_CC_C_O
3700 @acindex AC_PROG_CC_C_O
3701 This is like @code{AC_PROG_CC_C_O}, but it generates its results in
3702 the manner required by automake. You must use this instead of
3703 @code{AC_PROG_CC_C_O} when you need this functionality, that is, when
3704 using per-target flags or subdir-objects with C sources.
3707 @acindex AM_PROG_LEX
3708 @acindex AC_PROG_LEX
3709 @cindex HP-UX 10, @command{lex} problems
3710 @cindex @command{lex} problems with HP-UX 10
3711 Like @code{AC_PROG_LEX} (@pxref{Particular Programs, , Particular
3712 Program Checks, autoconf, The Autoconf Manual}), but uses the
3713 @command{missing} script on systems that do not have @command{lex}.
3714 HP-UX 10 is one such system.
3717 @acindex AM_PROG_GCJ
3720 This macro finds the @command{gcj} program or causes an error. It sets
3721 @code{GCJ} and @code{GCJFLAGS}. @command{gcj} is the Java front-end to the
3722 GNU Compiler Collection.
3724 @item AM_PROG_UPC([@var{compiler-search-list}])
3725 @acindex AM_PROG_UPC
3727 Find a compiler for Unified Parallel C and define the @code{UPC}
3728 variable. The default @var{compiler-search-list} is @samp{upcc upc}.
3729 This macro will abort @command{configure} if no Unified Parallel C
3732 @item AM_WITH_DMALLOC
3733 @acindex AM_WITH_DMALLOC
3734 @cindex @command{dmalloc}, support for
3735 @vindex WITH_DMALLOC
3736 @opindex --with-dmalloc
3737 Add support for the @uref{http://dmalloc.com/, Dmalloc package}. If
3738 the user runs @command{configure} with @option{--with-dmalloc}, then
3739 define @code{WITH_DMALLOC} and add @option{-ldmalloc} to @code{LIBS}.
3742 @acindex AM_WITH_REGEX
3744 @opindex --with-regex
3745 @cindex regex package
3747 Adds @option{--with-regex} to the @command{configure} command line. If
3748 specified (the default), then the @samp{regex} regular expression
3749 library is used, @file{regex.o} is put into @code{LIBOBJS}, and
3750 @code{WITH_REGEX} is defined. If @option{--without-regex} is given, then
3751 the @code{rx} regular expression library is used, and @file{rx.o} is put
3752 into @code{LIBOBJS}.
3757 @node Obsolete macros
3758 @subsection Obsolete macros
3759 @cindex obsolete macros
3762 Although using some of the following macros was required in past
3763 releases, you should not use any of them in new code. Running
3764 @command{autoupdate} should adjust your @file{configure.ac}
3765 automatically (@pxref{autoupdate Invocation, , Using
3766 @command{autoupdate} to Modernize @file{configure.ac}, autoconf, The
3770 @item AM_C_PROTOTYPES
3771 @acindex AM_C_PROTOTYPES
3774 Check to see if function prototypes are understood by the compiler. If
3775 so, define @samp{PROTOTYPES} and set the output variables @code{U} and
3776 @code{ANSI2KNR} to the empty string. Otherwise, set @code{U} to
3777 @samp{_} and @code{ANSI2KNR} to @samp{./ansi2knr}. Automake uses these
3778 values to implement the obsolete de-ANSI-fication feature.
3780 @item AM_CONFIG_HEADER
3781 @acindex AM_CONFIG_HEADER
3782 Automake will generate rules to automatically regenerate the config
3783 header. This obsolete macro is a synonym of @code{AC_CONFIG_HEADERS}
3784 today (@pxref{Optional}).
3786 @item AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
3787 @acindex AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
3788 If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
3789 define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be
3790 found in @file{<termios.h>}. This macro is obsolete, you should
3791 use Autoconf's @code{AC_HEADER_TIOCGWINSZ} instead.
3793 @item AM_PROG_MKDIR_P
3794 @acindex AM_PROG_MKDIR_P
3795 @cindex @code{mkdir -p}, macro check
3799 From Automake 1.8 to 1.9.6 this macro used to define the output
3800 variable @code{mkdir_p} to one of @code{mkdir -p}, @code{install-sh
3801 -d}, or @code{mkinstalldirs}.
3803 Nowadays Autoconf provides a similar functionality with
3804 @code{AC_PROG_MKDIR_P} (@pxref{Particular Programs, , Particular
3805 Program Checks, autoconf, The Autoconf Manual}), however this defines
3806 the output variable @code{MKDIR_P} instead. Therefore
3807 @code{AM_PROG_MKDIR_P} has been rewritten as a thin wrapper around
3808 @code{AC_PROG_MKDIR_P} to define @code{mkdir_p} to the same value as
3809 @code{MKDIR_P} for backward compatibility.
3811 If you are using Automake, there is normally no reason to call this
3812 macro, because @code{AM_INIT_AUTOMAKE} already does so. However, make
3813 sure that the custom rules in your @file{Makefile}s use
3814 @code{$(MKDIR_P)} and not @code{$(mkdir_p)}. Even if both variables
3815 still work, the latter should be considered obsolete.
3817 If you are not using Automake, please call @code{AC_PROG_MKDIR_P}
3818 instead of @code{AM_PROG_MKDIR_P}.
3820 @item AM_SYS_POSIX_TERMIOS
3821 @acindex AM_SYS_POSIX_TERMIOS
3822 @cindex POSIX termios headers
3823 @cindex termios POSIX headers
3824 Check to see if POSIX termios headers and functions are available on the
3825 system. If so, set the shell variable @code{am_cv_sys_posix_termios} to
3826 @samp{yes}. If not, set the variable to @samp{no}. This macro is obsolete,
3827 you should use Autoconf's @code{AC_SYS_POSIX_TERMIOS} instead.
3832 @node Private macros
3833 @subsection Private macros
3835 The following macros are private macros you should not call directly.
3836 They are called by the other public macros when appropriate. Do not
3837 rely on them, as they might be changed in a future version. Consider
3838 them as implementation details; or better, do not consider them at all:
3842 @item _AM_DEPENDENCIES
3843 @itemx AM_SET_DEPDIR
3845 @itemx AM_OUTPUT_DEPENDENCY_COMMANDS
3846 These macros are used to implement Automake's automatic dependency
3847 tracking scheme. They are called automatically by automake when
3848 required, and there should be no need to invoke them manually.
3850 @item AM_MAKE_INCLUDE
3851 This macro is used to discover how the user's @command{make} handles
3852 @code{include} statements. This macro is automatically invoked when
3853 needed; there should be no need to invoke it manually.
3855 @item AM_PROG_INSTALL_STRIP
3856 This is used to find a version of @code{install} that can be used to
3857 strip a program at installation time. This macro is automatically
3858 included when required.
3860 @item AM_SANITY_CHECK
3861 This checks to make sure that a file created in the build directory is
3862 newer than a file in the source directory. This can fail on systems
3863 where the clock is set incorrectly. This macro is automatically run
3864 from @code{AM_INIT_AUTOMAKE}.
3870 @chapter Directories
3872 For simple projects that distributes all files in the same directory
3873 it is enough to have a single @file{Makefile.am} that builds
3874 everything in place.
3876 In larger projects it is common to organize files in different
3877 directories, in a tree. For instance one directory per program, per
3878 library or per module. The traditional approach is to build these
3879 subdirectory recursively: each directory contains its @file{Makefile}
3880 (generated from @file{Makefile.am}), and when @command{make} is run
3881 from the top level directory it enters each subdirectory in turn to
3885 * Subdirectories:: Building subdirectories recursively
3886 * Conditional Subdirectories:: Conditionally not building directories
3887 * Alternative:: Subdirectories without recursion
3888 * Subpackages:: Nesting packages
3891 @node Subdirectories
3892 @section Recursing subdirectories
3894 @cindex @code{SUBDIRS}, explained
3896 In packages with subdirectories, the top level @file{Makefile.am} must
3897 tell Automake which subdirectories are to be built. This is done via
3898 the @code{SUBDIRS} variable.
3901 The @code{SUBDIRS} variable holds a list of subdirectories in which
3902 building of various sorts can occur. The rules for many targets
3903 (e.g., @code{all}) in the generated @file{Makefile} will run commands
3904 both locally and in all specified subdirectories. Note that the
3905 directories listed in @code{SUBDIRS} are not required to contain
3906 @file{Makefile.am}s; only @file{Makefile}s (after configuration).
3907 This allows inclusion of libraries from packages that do not use
3908 Automake (such as @code{gettext}; see also @ref{Third-Party
3911 In packages that use subdirectories, the top-level @file{Makefile.am} is
3912 often very short. For instance, here is the @file{Makefile.am} from the
3913 GNU Hello distribution:
3916 EXTRA_DIST = BUGS ChangeLog.O README-alpha
3917 SUBDIRS = doc intl po src tests
3920 When Automake invokes @command{make} in a subdirectory, it uses the value
3921 of the @code{MAKE} variable. It passes the value of the variable
3922 @code{AM_MAKEFLAGS} to the @command{make} invocation; this can be set in
3923 @file{Makefile.am} if there are flags you must always pass to
3926 @vindex AM_MAKEFLAGS
3928 The directories mentioned in @code{SUBDIRS} are usually direct
3929 children of the current directory, each subdirectory containing its
3930 own @file{Makefile.am} with a @code{SUBDIRS} pointing to deeper
3931 subdirectories. Automake can be used to construct packages of
3932 arbitrary depth this way.
3934 By default, Automake generates @file{Makefiles} that work depth-first
3935 in postfix order: the subdirectories are built before the current
3936 directory. However, it is possible to change this ordering. You can
3937 do this by putting @samp{.} into @code{SUBDIRS}. For instance,
3938 putting @samp{.} first will cause a prefix ordering of
3944 SUBDIRS = lib src . test
3948 will cause @file{lib/} to be built before @file{src/}, then the
3949 current directory will be built, finally the @file{test/} directory
3950 will be built. It is customary to arrange test directories to be
3951 built after everything else since they are meant to test what has
3954 All @code{clean} rules are run in reverse order of build rules.
3956 @node Conditional Subdirectories
3957 @section Conditional Subdirectories
3958 @cindex Subdirectories, building conditionally
3959 @cindex Conditional subdirectories
3960 @cindex @code{SUBDIRS}, conditional
3961 @cindex Conditional @code{SUBDIRS}
3963 It is possible to define the @code{SUBDIRS} variable conditionally if,
3964 like in the case of GNU Inetutils, you want to only build a subset of
3967 To illustrate how this works, let's assume we have two directories
3968 @file{src/} and @file{opt/}. @file{src/} should always be built, but we
3969 want to decide in @command{configure} whether @file{opt/} will be built
3970 or not. (For this example we will assume that @file{opt/} should be
3971 built when the variable @samp{$want_opt} was set to @samp{yes}.)
3973 Running @command{make} should thus recurse into @file{src/} always, and
3974 then maybe in @file{opt/}.
3976 However @samp{make dist} should always recurse into both @file{src/}
3977 and @file{opt/}. Because @file{opt/} should be distributed even if it
3978 is not needed in the current configuration. This means
3979 @file{opt/Makefile} should be created @emph{unconditionally}.
3981 There are two ways to setup a project like this. You can use Automake
3982 conditionals (@pxref{Conditionals}) or use Autoconf @code{AC_SUBST}
3983 variables (@pxref{Setting Output Variables, , Setting Output
3984 Variables, autoconf, The Autoconf Manual}). Using Automake
3985 conditionals is the preferred solution. Before we illustrate these
3986 two possibilities, let's introduce @code{DIST_SUBDIRS}.
3988 @subsection @code{SUBDIRS} vs.@: @code{DIST_SUBDIRS}
3989 @cindex @code{DIST_SUBDIRS}, explained
3991 Automake considers two sets of directories, defined by the variables
3992 @code{SUBDIRS} and @code{DIST_SUBDIRS}.
3994 @code{SUBDIRS} contains the subdirectories of the current directory
3995 that must be built (@pxref{Subdirectories}). It must be defined
3996 manually; Automake will never guess a directory is to be built. As we
3997 will see in the next two sections, it is possible to define it
3998 conditionally so that some directory will be omitted from the build.
4000 @code{DIST_SUBDIRS} is used in rules that need to recurse in all
4001 directories, even those that have been conditionally left out of the
4002 build. Recall our example where we may not want to build subdirectory
4003 @file{opt/}, but yet we want to distribute it? This is where
4004 @code{DIST_SUBDIRS} come into play: @samp{opt} may not appear in
4005 @code{SUBDIRS}, but it must appear in @code{DIST_SUBDIRS}.
4007 Precisely, @code{DIST_SUBDIRS} is used by @samp{make
4008 maintainer-clean}, @samp{make distclean} and @samp{make dist}. All
4009 other recursive rules use @code{SUBDIRS}.
4011 If @code{SUBDIRS} is defined conditionally using Automake
4012 conditionals, Automake will define @code{DIST_SUBDIRS} automatically
4013 from the possibles values of @code{SUBDIRS} in all conditions.
4015 If @code{SUBDIRS} contains @code{AC_SUBST} variables,
4016 @code{DIST_SUBDIRS} will not be defined correctly because Automake
4017 does not know the possible values of these variables. In this case
4018 @code{DIST_SUBDIRS} needs to be defined manually.
4020 @subsection Conditional subdirectories with @code{AM_CONDITIONAL}
4021 @cindex @code{SUBDIRS} and @code{AM_CONDITIONAL}
4022 @cindex @code{AM_CONDITIONAL} and @code{SUBDIRS}
4024 @c The test case for the setup described here is
4025 @c test/subdircond2.test
4026 @c Try to keep it in sync.
4028 @file{configure} should output the @file{Makefile} for each directory
4029 and define a condition into which @file{opt/} should be built.
4033 AM_CONDITIONAL([COND_OPT], [test "$want_opt" = yes])
4034 AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
4038 Then @code{SUBDIRS} can be defined in the top-level @file{Makefile.am}
4045 SUBDIRS = src $(MAYBE_OPT)
4048 As you can see, running @command{make} will rightly recurse into
4049 @file{src/} and maybe @file{opt/}.
4051 @vindex DIST_SUBDIRS
4052 As you can't see, running @samp{make dist} will recurse into both
4053 @file{src/} and @file{opt/} directories because @samp{make dist}, unlike
4054 @samp{make all}, doesn't use the @code{SUBDIRS} variable. It uses the
4055 @code{DIST_SUBDIRS} variable.
4057 In this case Automake will define @samp{DIST_SUBDIRS = src opt}
4058 automatically because it knows that @code{MAYBE_OPT} can contain
4059 @samp{opt} in some condition.
4061 @subsection Conditional Subdirectories with @code{AC_SUBST}
4062 @cindex @code{SUBDIRS} and @code{AC_SUBST}
4063 @cindex @code{AC_SUBST} and @code{SUBDIRS}
4065 @c The test case for the setup described here is
4066 @c test/subdircond3.test
4067 @c Try to keep it in sync.
4069 Another possibility is to define @code{MAYBE_OPT} from
4070 @file{./configure} using @code{AC_SUBST}:
4074 if test "$want_opt" = yes; then
4079 AC_SUBST([MAYBE_OPT])
4080 AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
4084 In this case the top-level @file{Makefile.am} should look as follows.
4087 SUBDIRS = src $(MAYBE_OPT)
4088 DIST_SUBDIRS = src opt
4091 The drawback is that since Automake cannot guess what the possible
4092 values of @code{MAYBE_OPT} are, it is necessary to define
4093 @code{DIST_SUBDIRS}.
4095 @subsection Non-configured Subdirectories
4096 @cindex Subdirectories, configured conditionally
4098 The semantic of @code{DIST_SUBDIRS} is often misunderstood by some
4099 users that try to @emph{configure and build} subdirectories
4100 conditionally. Here by configuring we mean creating the
4101 @file{Makefile} (it might also involve running a nested
4102 @command{configure} script: this is a costly operation that explains
4103 why people want to do it conditionally, but only the @file{Makefile}
4104 is relevant to the discussion).
4106 The above examples all assume that every @file{Makefile} is created,
4107 even in directories that are not going to be built. The simple reason
4108 is that we want @samp{make dist} to distribute even the directories
4109 that are not being built (e.g., platform-dependent code), hence
4110 @file{make dist} must recurse into the subdirectory, hence this
4111 directory must be configured and appear in @code{DIST_SUBDIRS}.
4113 Building packages that do not configure every subdirectory is a tricky
4114 business, and we do not recommend it to the novice as it is easy to
4115 produce an incomplete tarball by mistake. We will not discuss this
4116 topic in depth here, yet for the adventurous here are a few rules to
4121 @item @code{SUBDIRS} should always be a subset of @code{DIST_SUBDIRS}.
4123 It makes little sense to have a directory in @code{SUBDIRS} that
4124 is not in @code{DIST_SUBDIRS}. Think of the former as a way to tell
4125 which directories listed in the latter should be built.
4126 @item Any directory listed in @code{DIST_SUBDIRS} and @code{SUBDIRS}
4129 I.e., the @file{Makefile} must exists or the recursive @command{make}
4130 rules will not be able to process the directory.
4131 @item Any configured directory must be listed in @code{DIST_SUBDIRS}.
4133 So that the cleaning rule remove the generated @file{Makefile}s.
4134 It would be correct to see @code{DIST_SUBDIRS} as a variable that
4135 lists all the directories that have been configured.
4139 In order to prevent recursion in some non-configured directory you
4140 must therefore ensure that this directory does not appear in
4141 @code{DIST_SUBDIRS} (and @code{SUBDIRS}). For instance, if you define
4142 @code{SUBDIRS} conditionally using @code{AC_SUBST} and do not define
4143 @code{DIST_SUBDIRS} explicitly, it will be default to
4144 @samp{$(SUBDIRS)}; another possibility is to force @code{DIST_SUBDIRS
4147 Of course, directories that are omitted from @code{DIST_SUBDIRS} will
4148 not be distributed unless you make other arrangements for this to
4149 happen (for instance, always running @samp{make dist} in a
4150 configuration where all directories are known to appear in
4151 @code{DIST_SUBDIRS}; or writing a @code{dist-hook} target to
4152 distribute these directories).
4154 @cindex Subdirectories, not distributed
4155 In few packages, non-configured directories are not even expected to
4156 be distributed. Although these packages do not require the
4157 aforementioned extra arrangements, there is another pitfall. If the
4158 name of a directory appears in @code{SUBDIRS} or @code{DIST_SUBDIRS},
4159 @command{automake} will make sure the directory exists. Consequently
4160 @command{automake} cannot be run on such a distribution when one
4161 directory has been omitted. One way to avoid this check is to use the
4162 @code{AC_SUBST} method to declare conditional directories; since
4163 @command{automake} does not know the values of @code{AC_SUBST}
4164 variables it cannot ensure the corresponding directory exist.
4167 @section An Alternative Approach to Subdirectories
4169 If you've ever read Peter Miller's excellent paper,
4170 @uref{http://www.pcug.org.au/~millerp/rmch/recu-make-cons-harm.html,
4171 Recursive Make Considered Harmful}, the preceding sections on the use of
4172 subdirectories will probably come as unwelcome advice. For those who
4173 haven't read the paper, Miller's main thesis is that recursive
4174 @command{make} invocations are both slow and error-prone.
4176 Automake provides sufficient cross-directory support @footnote{We
4177 believe. This work is new and there are probably warts.
4178 @xref{Introduction}, for information on reporting bugs.} to enable you
4179 to write a single @file{Makefile.am} for a complex multi-directory
4183 By default an installable file specified in a subdirectory will have its
4184 directory name stripped before installation. For instance, in this
4185 example, the header file will be installed as
4186 @file{$(includedir)/stdio.h}:
4189 include_HEADERS = inc/stdio.h
4193 @cindex @code{nobase_} prefix
4194 @cindex Path stripping, avoiding
4195 @cindex Avoiding path stripping
4197 However, the @samp{nobase_} prefix can be used to circumvent this path
4198 stripping. In this example, the header file will be installed as
4199 @file{$(includedir)/sys/types.h}:
4202 nobase_include_HEADERS = sys/types.h
4205 @cindex @code{nobase_} and @code{dist_} or @code{nodist_}
4206 @cindex @code{dist_} and @code{nobase_}
4207 @cindex @code{nodist_} and @code{nobase_}
4211 @samp{nobase_} should be specified first when used in conjunction with
4212 either @samp{dist_} or @samp{nodist_} (@pxref{Dist}). For instance:
4215 nobase_dist_pkgdata_DATA = images/vortex.pgm sounds/whirl.ogg
4218 Finally, note that a variable using the @samp{nobase_} prefix can
4219 always be replaced by several variables, one for each destination
4220 directory (@pxref{Uniform}). For instance, the last example could be
4221 rewritten as follows:
4224 imagesdir = $(pkgdatadir)/images
4225 soundsdir = $(pkgdatadir)/sounds
4226 dist_images_DATA = images/vortex.pgm
4227 dist_sounds_DATA = sounds/whirl.ogg
4231 This latter syntax makes it possible to change one destination
4232 directory without changing the layout of the source tree.
4235 @section Nesting Packages
4236 @cindex Nesting packages
4238 @acindex AC_CONFIG_SUBDIRS
4239 @acindex AC_CONFIG_AUX_DIR
4242 In the GNU Build System, packages can be nested to arbitrary depth.
4243 This means that a package can embedded other packages with their own
4244 @file{configure}, @file{Makefile}s, etc.
4246 These other packages should just appear as subdirectories of their
4247 parent package. They must be listed in @code{SUBDIRS} like other
4248 ordinary directories. However the subpackage's @file{Makefile}s
4249 should be output by its own @file{configure} script, not by the
4250 parent's @file{configure}. This is achieved using the
4251 @code{AC_CONFIG_SUBDIRS} Autoconf macro (@pxref{Subdirectories,
4252 AC_CONFIG_SUBDIRS, Configuring Other Packages in Subdirectories,
4253 autoconf, The Autoconf Manual}).
4255 Here is an example package for an @code{arm} program that links with
4256 an @code{hand} library that is a nested package in subdirectory
4259 @code{arm}'s @file{configure.ac}:
4262 AC_INIT([arm], [1.0])
4263 AC_CONFIG_AUX_DIR([.])
4266 AC_CONFIG_FILES([Makefile])
4267 # Call hand's ./configure script recursively.
4268 AC_CONFIG_SUBDIRS([hand])
4272 @code{arm}'s @file{Makefile.am}:
4275 # Build the library in the hand subdirectory first.
4278 # Include hand's header when compiling this directory.
4279 AM_CPPFLAGS = -I$(srcdir)/hand
4283 # link with the hand library.
4284 arm_LDADD = hand/libhand.a
4287 Now here is @code{hand}'s @file{hand/configure.ac}:
4290 AC_INIT([hand], [1.2])
4291 AC_CONFIG_AUX_DIR([.])
4295 AC_CONFIG_FILES([Makefile])
4300 and its @file{hand/Makefile.am}:
4303 lib_LIBRARIES = libhand.a
4304 libhand_a_SOURCES = hand.c
4307 When @samp{make dist} is run from the top-level directory it will
4308 create an archive @file{arm-1.0.tar.gz} that contains the @code{arm}
4309 code as well as the @file{hand} subdirectory. This package can be
4310 built and installed like any ordinary package, with the usual
4311 @samp{./configure && make && make install} sequence (the @code{hand}
4312 subpackage will be built and installed by the process).
4314 When @samp{make dist} is run from the hand directory, it will create a
4315 self-contained @file{hand-1.2.tar.gz} archive. So although it appears
4316 to be embedded in another package, it can still be used separately.
4318 The purpose of the @samp{AC_CONFIG_AUX_DIR([.])} instruction is to
4319 force Automake and Autoconf to search for auxiliary scripts in the
4320 current directory. For instance, this means that there will be two
4321 copies of @file{install-sh}: one in the top-level of the @code{arm}
4322 package, and another one in the @file{hand/} subdirectory for the
4323 @code{hand} package.
4325 The historical default is to search for these auxiliary scripts in
4326 the parent directory and the grandparent directory. So if the
4327 @samp{AC_CONFIG_AUX_DIR([.])} line was removed from
4328 @file{hand/configure.ac}, that subpackage would share the auxiliary
4329 script of the @code{arm} package. This may looks like a gain in size
4330 (a few kilobytes), but it is actually a loss of modularity as the
4331 @code{hand} subpackage is no longer self-contained (@samp{make dist}
4332 in the subdirectory will not work anymore).
4334 Packages that do not use Automake need more work to be integrated this
4335 way. @xref{Third-Party Makefiles}.
4338 @chapter Building Programs and Libraries
4340 A large part of Automake's functionality is dedicated to making it easy
4341 to build programs and libraries.
4344 * A Program:: Building a program
4345 * A Library:: Building a library
4346 * A Shared Library:: Building a Libtool library
4347 * Program and Library Variables:: Variables controlling program and
4349 * Default _SOURCES:: Default source files
4350 * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
4351 * Program variables:: Variables used when building a program
4352 * Yacc and Lex:: Yacc and Lex support
4353 * C++ Support:: Compiling C++ sources
4354 * Objective C Support:: Compiling Objective C sources
4355 * Unified Parallel C Support:: Compiling Unified Parallel C sources
4356 * Assembly Support:: Compiling assembly sources
4357 * Fortran 77 Support:: Compiling Fortran 77 sources
4358 * Fortran 9x Support:: Compiling Fortran 9x sources
4359 * Java Support:: Compiling Java sources
4360 * Support for Other Languages:: Compiling other languages
4361 * ANSI:: Automatic de-ANSI-fication (obsolete)
4362 * Dependencies:: Automatic dependency tracking
4363 * EXEEXT:: Support for executable extensions
4368 @section Building a program
4370 In order to build a program, you need to tell Automake which sources
4371 are part of it, and which libraries it should be linked with.
4373 This section also covers conditional compilation of sources or
4374 programs. Most of the comments about these also apply to libraries
4375 (@pxref{A Library}) and libtool libraries (@pxref{A Shared Library}).
4378 * Program Sources:: Defining program sources
4379 * Linking:: Linking with libraries or extra objects
4380 * Conditional Sources:: Handling conditional sources
4381 * Conditional Programs:: Building program conditionally
4384 @node Program Sources
4385 @subsection Defining program sources
4387 @cindex @code{PROGRAMS}, @code{bindir}
4389 @vindex bin_PROGRAMS
4390 @vindex sbin_PROGRAMS
4391 @vindex libexec_PROGRAMS
4392 @vindex pkglib_PROGRAMS
4393 @vindex noinst_PROGRAMS
4394 @vindex check_PROGRAMS
4396 In a directory containing source that gets built into a program (as
4397 opposed to a library or a script), the @code{PROGRAMS} primary is used.
4398 Programs can be installed in @code{bindir}, @code{sbindir},
4399 @code{libexecdir}, @code{pkglibdir}, @code{pkglibexecdir}, or not at all
4400 (@code{noinst_}). They can also be built only for @samp{make check}, in
4401 which case the prefix is @samp{check_}.
4406 bin_PROGRAMS = hello
4409 In this simple case, the resulting @file{Makefile.in} will contain code
4410 to generate a program named @code{hello}.
4412 Associated with each program are several assisting variables that are
4413 named after the program. These variables are all optional, and have
4414 reasonable defaults. Each variable, its use, and default is spelled out
4415 below; we use the ``hello'' example throughout.
4417 The variable @code{hello_SOURCES} is used to specify which source files
4418 get built into an executable:
4421 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
4424 This causes each mentioned @file{.c} file to be compiled into the
4425 corresponding @file{.o}. Then all are linked to produce @file{hello}.
4427 @cindex @code{_SOURCES} primary, defined
4428 @cindex @code{SOURCES} primary, defined
4429 @cindex Primary variable, @code{SOURCES}
4432 If @code{hello_SOURCES} is not specified, then it defaults to the single
4433 file @file{hello.c} (@pxref{Default _SOURCES}).
4437 Multiple programs can be built in a single directory. Multiple programs
4438 can share a single source file, which must be listed in each
4439 @code{_SOURCES} definition.
4441 @cindex Header files in @code{_SOURCES}
4442 @cindex @code{_SOURCES} and header files
4444 Header files listed in a @code{_SOURCES} definition will be included in
4445 the distribution but otherwise ignored. In case it isn't obvious, you
4446 should not include the header file generated by @file{configure} in a
4447 @code{_SOURCES} variable; this file should not be distributed. Lex
4448 (@file{.l}) and Yacc (@file{.y}) files can also be listed; see @ref{Yacc
4453 @subsection Linking the program
4455 If you need to link against libraries that are not found by
4456 @command{configure}, you can use @code{LDADD} to do so. This variable is
4457 used to specify additional objects or libraries to link with; it is
4458 inappropriate for specifying specific linker flags, you should use
4459 @code{AM_LDFLAGS} for this purpose.
4463 @cindex @code{prog_LDADD}, defined
4465 Sometimes, multiple programs are built in one directory but do not share
4466 the same link-time requirements. In this case, you can use the
4467 @code{@var{prog}_LDADD} variable (where @var{prog} is the name of the
4468 program as it appears in some @code{_PROGRAMS} variable, and usually
4469 written in lowercase) to override the global @code{LDADD}. If this
4470 variable exists for a given program, then that program is not linked
4474 For instance, in GNU cpio, @code{pax}, @code{cpio} and @code{mt} are
4475 linked against the library @file{libcpio.a}. However, @code{rmt} is
4476 built in the same directory, and has no such link requirement. Also,
4477 @code{mt} and @code{rmt} are only built on certain architectures. Here
4478 is what cpio's @file{src/Makefile.am} looks like (abridged):
4481 bin_PROGRAMS = cpio pax $(MT)
4482 libexec_PROGRAMS = $(RMT)
4483 EXTRA_PROGRAMS = mt rmt
4485 LDADD = ../lib/libcpio.a $(INTLLIBS)
4488 cpio_SOURCES = @dots{}
4489 pax_SOURCES = @dots{}
4490 mt_SOURCES = @dots{}
4491 rmt_SOURCES = @dots{}
4494 @cindex @code{_LDFLAGS}, defined
4495 @vindex maude_LDFLAGS
4496 @code{@var{prog}_LDADD} is inappropriate for passing program-specific
4497 linker flags (except for @option{-l}, @option{-L}, @option{-dlopen} and
4498 @option{-dlpreopen}). So, use the @code{@var{prog}_LDFLAGS} variable for
4501 @cindex @code{_DEPENDENCIES}, defined
4502 @vindex maude_DEPENDENCIES
4503 It is also occasionally useful to have a program depend on some other
4504 target that is not actually part of that program. This can be done
4505 using the @code{@var{prog}_DEPENDENCIES} variable. Each program
4506 depends on the contents of such a variable, but no further
4507 interpretation is done.
4509 Since these dependencies are associated to the link rule used to
4510 create the programs they should normally list files used by the link
4511 command. That is @file{*.$(OBJEXT)}, @file{*.a}, or @file{*.la}
4512 files. In rare cases you may need to add other kinds of files such as
4513 linker scripts, but @emph{listing a source file in
4514 @code{_DEPENDENCIES} is wrong}. If some source file needs to be built
4515 before all the components of a program are built, consider using the
4516 @code{BUILT_SOURCES} variable instead (@pxref{Sources}).
4518 If @code{@var{prog}_DEPENDENCIES} is not supplied, it is computed by
4519 Automake. The automatically-assigned value is the contents of
4520 @code{@var{prog}_LDADD}, with most configure substitutions, @option{-l},
4521 @option{-L}, @option{-dlopen} and @option{-dlpreopen} options removed. The
4522 configure substitutions that are left in are only @samp{$(LIBOBJS)} and
4523 @samp{$(ALLOCA)}; these are left because it is known that they will not
4524 cause an invalid value for @code{@var{prog}_DEPENDENCIES} to be
4527 @ref{Conditional Sources} shows a situation where @code{_DEPENDENCIES}
4530 @cindex @code{LDADD} and @option{-l}
4531 @cindex @option{-l} and @code{LDADD}
4532 We recommend that you avoid using @option{-l} options in @code{LDADD}
4533 or @code{@var{prog}_LDADD} when referring to libraries built by your
4534 package. Instead, write the file name of the library explicitly as in
4535 the above @code{cpio} example. Use @option{-l} only to list
4536 third-party libraries. If you follow this rule, the default value of
4537 @code{@var{prog}_DEPENDENCIES} will list all your local libraries and
4538 omit the other ones.
4541 @node Conditional Sources
4542 @subsection Conditional compilation of sources
4544 You can't put a configure substitution (e.g., @samp{@@FOO@@} or
4545 @samp{$(FOO)} where @code{FOO} is defined via @code{AC_SUBST}) into a
4546 @code{_SOURCES} variable. The reason for this is a bit hard to
4547 explain, but suffice to say that it simply won't work. Automake will
4548 give an error if you try to do this.
4550 Fortunately there are two other ways to achieve the same result. One is
4551 to use configure substitutions in @code{_LDADD} variables, the other is
4552 to use an Automake conditional.
4554 @subsubsection Conditional compilation using @code{_LDADD} substitutions
4556 @cindex @code{EXTRA_prog_SOURCES}, defined
4558 Automake must know all the source files that could possibly go into a
4559 program, even if not all the files are built in every circumstance. Any
4560 files that are only conditionally built should be listed in the
4561 appropriate @code{EXTRA_} variable. For instance, if
4562 @file{hello-linux.c} or @file{hello-generic.c} were conditionally included
4563 in @code{hello}, the @file{Makefile.am} would contain:
4566 bin_PROGRAMS = hello
4567 hello_SOURCES = hello-common.c
4568 EXTRA_hello_SOURCES = hello-linux.c hello-generic.c
4569 hello_LDADD = $(HELLO_SYSTEM)
4570 hello_DEPENDENCIES = $(HELLO_SYSTEM)
4574 You can then setup the @samp{$(HELLO_SYSTEM)} substitution from
4575 @file{configure.ac}:
4580 *linux*) HELLO_SYSTEM='hello-linux.$(OBJEXT)' ;;
4581 *) HELLO_SYSTEM='hello-generic.$(OBJEXT)' ;;
4583 AC_SUBST([HELLO_SYSTEM])
4587 In this case, the variable @code{HELLO_SYSTEM} should be replaced by
4588 either @file{hello-linux.o} or @file{hello-generic.o}, and added to
4589 both @code{hello_DEPENDENCIES} and @code{hello_LDADD} in order to be
4590 built and linked in.
4592 @subsubsection Conditional compilation using Automake conditionals
4594 An often simpler way to compile source files conditionally is to use
4595 Automake conditionals. For instance, you could use this
4596 @file{Makefile.am} construct to build the same @file{hello} example:
4599 bin_PROGRAMS = hello
4601 hello_SOURCES = hello-linux.c hello-common.c
4603 hello_SOURCES = hello-generic.c hello-common.c
4607 In this case, @file{configure.ac} should setup the @code{LINUX}
4608 conditional using @code{AM_CONDITIONAL} (@pxref{Conditionals}).
4610 When using conditionals like this you don't need to use the
4611 @code{EXTRA_} variable, because Automake will examine the contents of
4612 each variable to construct the complete list of source files.
4614 If your program uses a lot of files, you will probably prefer a
4615 conditional @samp{+=}.
4618 bin_PROGRAMS = hello
4619 hello_SOURCES = hello-common.c
4621 hello_SOURCES += hello-linux.c
4623 hello_SOURCES += hello-generic.c
4627 @node Conditional Programs
4628 @subsection Conditional compilation of programs
4629 @cindex Conditional programs
4630 @cindex Programs, conditional
4632 Sometimes it is useful to determine the programs that are to be built
4633 at configure time. For instance, GNU @code{cpio} only builds
4634 @code{mt} and @code{rmt} under special circumstances. The means to
4635 achieve conditional compilation of programs are the same you can use
4636 to compile source files conditionally: substitutions or conditionals.
4638 @subsubsection Conditional programs using @command{configure} substitutions
4640 @vindex EXTRA_PROGRAMS
4641 @cindex @code{EXTRA_PROGRAMS}, defined
4642 In this case, you must notify Automake of all the programs that can
4643 possibly be built, but at the same time cause the generated
4644 @file{Makefile.in} to use the programs specified by @command{configure}.
4645 This is done by having @command{configure} substitute values into each
4646 @code{_PROGRAMS} definition, while listing all optionally built programs
4647 in @code{EXTRA_PROGRAMS}.
4650 bin_PROGRAMS = cpio pax $(MT)
4651 libexec_PROGRAMS = $(RMT)
4652 EXTRA_PROGRAMS = mt rmt
4655 As explained in @ref{EXEEXT}, Automake will rewrite
4656 @code{bin_PROGRAMS}, @code{libexec_PROGRAMS}, and
4657 @code{EXTRA_PROGRAMS}, appending @samp{$(EXEEXT)} to each binary.
4658 Obviously it cannot rewrite values obtained at run-time through
4659 @command{configure} substitutions, therefore you should take care of
4660 appending @samp{$(EXEEXT)} yourself, as in @samp{AC_SUBST([MT],
4661 ['mt$@{EXEEXT@}'])}.
4663 @subsubsection Conditional programs using Automake conditionals
4665 You can also use Automake conditionals (@pxref{Conditionals}) to
4666 select programs to be built. In this case you don't have to worry
4667 about @samp{$(EXEEXT)} or @code{EXTRA_PROGRAMS}.
4670 bin_PROGRAMS = cpio pax
4675 libexec_PROGRAMS = rmt
4681 @section Building a library
4683 @cindex @code{_LIBRARIES} primary, defined
4684 @cindex @code{LIBRARIES} primary, defined
4685 @cindex Primary variable, @code{LIBRARIES}
4688 @vindex lib_LIBRARIES
4689 @vindex pkglib_LIBRARIES
4690 @vindex noinst_LIBRARIES
4692 Building a library is much like building a program. In this case, the
4693 name of the primary is @code{LIBRARIES}. Libraries can be installed in
4694 @code{libdir} or @code{pkglibdir}.
4696 @xref{A Shared Library}, for information on how to build shared
4697 libraries using libtool and the @code{LTLIBRARIES} primary.
4699 Each @code{_LIBRARIES} variable is a list of the libraries to be built.
4700 For instance, to create a library named @file{libcpio.a}, but not install
4701 it, you would write:
4704 noinst_LIBRARIES = libcpio.a
4705 libcpio_a_SOURCES = @dots{}
4708 The sources that go into a library are determined exactly as they are
4709 for programs, via the @code{_SOURCES} variables. Note that the library
4710 name is canonicalized (@pxref{Canonicalization}), so the @code{_SOURCES}
4711 variable corresponding to @file{libcpio.a} is @samp{libcpio_a_SOURCES},
4712 not @samp{libcpio.a_SOURCES}.
4714 @vindex maude_LIBADD
4715 Extra objects can be added to a library using the
4716 @code{@var{library}_LIBADD} variable. This should be used for objects
4717 determined by @command{configure}. Again from @code{cpio}:
4720 libcpio_a_LIBADD = $(LIBOBJS) $(ALLOCA)
4723 In addition, sources for extra objects that will not exist until
4724 configure-time must be added to the @code{BUILT_SOURCES} variable
4727 Building a static library is done by compiling all object files, then
4728 by invoking @samp{$(AR) $(ARFLAGS)} followed by the name of the
4729 library and the list of objects, and finally by calling
4730 @samp{$(RANLIB)} on that library. You should call
4731 @code{AC_PROG_RANLIB} from your @file{configure.ac} to define
4732 @code{RANLIB} (Automake will complain otherwise). @code{AR} and
4733 @code{ARFLAGS} default to @code{ar} and @code{cru} respectively; you
4734 can override these two variables my setting them in your
4735 @file{Makefile.am}, by @code{AC_SUBST}ing them from your
4736 @file{configure.ac}, or by defining a per-library @code{maude_AR}
4737 variable (@pxref{Program and Library Variables}).
4739 @cindex Empty libraries
4740 Be careful when selecting library components conditionally. Because
4741 building an empty library is not portable, you should ensure that any
4742 library contains always at least one object.
4744 To use a static library when building a program, add it to
4745 @code{LDADD} for this program. In the following example, the program
4746 @file{cpio} is statically linked with the library @file{libcpio.a}.
4749 noinst_LIBRARIES = libcpio.a
4750 libcpio_a_SOURCES = @dots{}
4753 cpio_SOURCES = cpio.c @dots{}
4754 cpio_LDADD = libcpio.a
4758 @node A Shared Library
4759 @section Building a Shared Library
4761 @cindex Shared libraries, support for
4763 Building shared libraries portably is a relatively complex matter.
4764 For this reason, GNU Libtool (@pxref{Top, , Introduction, libtool, The
4765 Libtool Manual}) was created to help build shared libraries in a
4766 platform-independent way.
4769 * Libtool Concept:: Introducing Libtool
4770 * Libtool Libraries:: Declaring Libtool Libraries
4771 * Conditional Libtool Libraries:: Building Libtool Libraries Conditionally
4772 * Conditional Libtool Sources:: Choosing Library Sources Conditionally
4773 * Libtool Convenience Libraries:: Building Convenience Libtool Libraries
4774 * Libtool Modules:: Building Libtool Modules
4775 * Libtool Flags:: Using _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS
4776 * LTLIBOBJS:: Using $(LTLIBOBJS) and $(LTALLOCA)
4777 * Libtool Issues:: Common Issues Related to Libtool's Use
4780 @node Libtool Concept
4781 @subsection The Libtool Concept
4783 @cindex @command{libtool}, introduction
4784 @cindex libtool library, definition
4785 @cindex suffix @file{.la}, defined
4786 @cindex @file{.la} suffix, defined
4788 Libtool abstracts shared and static libraries into a unified concept
4789 henceforth called @dfn{libtool libraries}. Libtool libraries are
4790 files using the @file{.la} suffix, and can designate a static library,
4791 a shared library, or maybe both. Their exact nature cannot be
4792 determined until @file{./configure} is run: not all platforms support
4793 all kinds of libraries, and users can explicitly select which
4794 libraries should be built. (However the package's maintainers can
4795 tune the default, @pxref{AC_PROG_LIBTOOL, , The @code{AC_PROG_LIBTOOL}
4796 macro, libtool, The Libtool Manual}.)
4798 @cindex suffix @file{.lo}, defined
4799 Because object files for shared and static libraries must be compiled
4800 differently, libtool is also used during compilation. Object files
4801 built by libtool are called @dfn{libtool objects}: these are files
4802 using the @file{.lo} suffix. Libtool libraries are built from these
4805 You should not assume anything about the structure of @file{.la} or
4806 @file{.lo} files and how libtool constructs them: this is libtool's
4807 concern, and the last thing one wants is to learn about libtool's
4808 guts. However the existence of these files matters, because they are
4809 used as targets and dependencies in @file{Makefile}s rules when
4810 building libtool libraries. There are situations where you may have
4811 to refer to these, for instance when expressing dependencies for
4812 building source files conditionally (@pxref{Conditional Libtool
4815 @cindex @file{libltdl}, introduction
4817 People considering writing a plug-in system, with dynamically loaded
4818 modules, should look into @file{libltdl}: libtool's dlopening library
4819 (@pxref{Using libltdl, , Using libltdl, libtool, The Libtool Manual}).
4820 This offers a portable dlopening facility to load libtool libraries
4821 dynamically, and can also achieve static linking where unavoidable.
4823 Before we discuss how to use libtool with Automake in details, it
4824 should be noted that the libtool manual also has a section about how
4825 to use Automake with libtool (@pxref{Using Automake, , Using Automake
4826 with Libtool, libtool, The Libtool Manual}).
4828 @node Libtool Libraries
4829 @subsection Building Libtool Libraries
4831 @cindex @code{_LTLIBRARIES} primary, defined
4832 @cindex @code{LTLIBRARIES} primary, defined
4833 @cindex Primary variable, @code{LTLIBRARIES}
4834 @cindex Example of shared libraries
4835 @vindex lib_LTLIBRARIES
4836 @vindex pkglib_LTLIBRARIES
4837 @vindex _LTLIBRARIES
4839 Automake uses libtool to build libraries declared with the
4840 @code{LTLIBRARIES} primary. Each @code{_LTLIBRARIES} variable is a
4841 list of libtool libraries to build. For instance, to create a libtool
4842 library named @file{libgettext.la}, and install it in @code{libdir},
4846 lib_LTLIBRARIES = libgettext.la
4847 libgettext_la_SOURCES = gettext.c gettext.h @dots{}
4850 Automake predefines the variable @code{pkglibdir}, so you can use
4851 @code{pkglib_LTLIBRARIES} to install libraries in
4852 @samp{$(libdir)/@@PACKAGE@@/}.
4854 If @file{gettext.h} is a public header file that needs to be installed
4855 in order for people to use the library, it should be declared using a
4856 @code{_HEADERS} variable, not in @code{libgettext_la_SOURCES}.
4857 Headers listed in the latter should be internal headers that are not
4858 part of the public interface.
4861 lib_LTLIBRARIES = libgettext.la
4862 libgettext_la_SOURCES = gettext.c @dots{}
4863 include_HEADERS = gettext.h @dots{}
4866 A package can build and install such a library along with other
4867 programs that use it. This dependency should be specified using
4868 @code{LDADD}. The following example builds a program named
4869 @file{hello} that is linked with @file{libgettext.la}.
4872 lib_LTLIBRARIES = libgettext.la
4873 libgettext_la_SOURCES = gettext.c @dots{}
4875 bin_PROGRAMS = hello
4876 hello_SOURCES = hello.c @dots{}
4877 hello_LDADD = libgettext.la
4881 Whether @file{hello} is statically or dynamically linked with
4882 @file{libgettext.la} is not yet known: this will depend on the
4883 configuration of libtool and the capabilities of the host.
4886 @node Conditional Libtool Libraries
4887 @subsection Building Libtool Libraries Conditionally
4888 @cindex libtool libraries, conditional
4889 @cindex conditional libtool libraries
4891 Like conditional programs (@pxref{Conditional Programs}), there are
4892 two main ways to build conditional libraries: using Automake
4893 conditionals or using Autoconf @code{AC_SUBST}itutions.
4895 The important implementation detail you have to be aware of is that
4896 the place where a library will be installed matters to libtool: it
4897 needs to be indicated @emph{at link-time} using the @option{-rpath}
4900 For libraries whose destination directory is known when Automake runs,
4901 Automake will automatically supply the appropriate @option{-rpath}
4902 option to libtool. This is the case for libraries listed explicitly in
4903 some installable @code{_LTLIBRARIES} variables such as
4904 @code{lib_LTLIBRARIES}.
4906 However, for libraries determined at configure time (and thus
4907 mentioned in @code{EXTRA_LTLIBRARIES}), Automake does not know the
4908 final installation directory. For such libraries you must add the
4909 @option{-rpath} option to the appropriate @code{_LDFLAGS} variable by
4912 The examples below illustrate the differences between these two methods.
4914 Here is an example where @code{WANTEDLIBS} is an @code{AC_SUBST}ed
4915 variable set at @file{./configure}-time to either @file{libfoo.la},
4916 @file{libbar.la}, both, or none. Although @samp{$(WANTEDLIBS)}
4917 appears in the @code{lib_LTLIBRARIES}, Automake cannot guess it
4918 relates to @file{libfoo.la} or @file{libbar.la} by the time it creates
4919 the link rule for these two libraries. Therefore the @option{-rpath}
4920 argument must be explicitly supplied.
4923 EXTRA_LTLIBRARIES = libfoo.la libbar.la
4924 lib_LTLIBRARIES = $(WANTEDLIBS)
4925 libfoo_la_SOURCES = foo.c @dots{}
4926 libfoo_la_LDFLAGS = -rpath '$(libdir)'
4927 libbar_la_SOURCES = bar.c @dots{}
4928 libbar_la_LDFLAGS = -rpath '$(libdir)'
4931 Here is how the same @file{Makefile.am} would look using Automake
4932 conditionals named @code{WANT_LIBFOO} and @code{WANT_LIBBAR}. Now
4933 Automake is able to compute the @option{-rpath} setting itself, because
4934 it's clear that both libraries will end up in @samp{$(libdir)} if they
4940 lib_LTLIBRARIES += libfoo.la
4943 lib_LTLIBRARIES += libbar.la
4945 libfoo_la_SOURCES = foo.c @dots{}
4946 libbar_la_SOURCES = bar.c @dots{}
4949 @node Conditional Libtool Sources
4950 @subsection Libtool Libraries with Conditional Sources
4952 Conditional compilation of sources in a library can be achieved in the
4953 same way as conditional compilation of sources in a program
4954 (@pxref{Conditional Sources}). The only difference is that
4955 @code{_LIBADD} should be used instead of @code{_LDADD} and that it
4956 should mention libtool objects (@file{.lo} files).
4958 So, to mimic the @file{hello} example from @ref{Conditional Sources},
4959 we could build a @file{libhello.la} library using either
4960 @file{hello-linux.c} or @file{hello-generic.c} with the following
4964 lib_LTLIBRARIES = libhello.la
4965 libhello_la_SOURCES = hello-common.c
4966 EXTRA_libhello_la_SOURCES = hello-linux.c hello-generic.c
4967 libhello_la_LIBADD = $(HELLO_SYSTEM)
4968 libhello_la_DEPENDENCIES = $(HELLO_SYSTEM)
4972 And make sure @command{configure} defines @code{HELLO_SYSTEM} as
4973 either @file{hello-linux.lo} or @file{hello-@-generic.lo}.
4975 Or we could simply use an Automake conditional as follows.
4978 lib_LTLIBRARIES = libhello.la
4979 libhello_la_SOURCES = hello-common.c
4981 libhello_la_SOURCES += hello-linux.c
4983 libhello_la_SOURCES += hello-generic.c
4987 @node Libtool Convenience Libraries
4988 @subsection Libtool Convenience Libraries
4989 @cindex convenience libraries, libtool
4990 @cindex libtool convenience libraries
4991 @vindex noinst_LTLIBRARIES
4992 @vindex check_LTLIBRARIES
4994 Sometimes you want to build libtool libraries that should not be
4995 installed. These are called @dfn{libtool convenience libraries} and
4996 are typically used to encapsulate many sublibraries, later gathered
4997 into one big installed library.
4999 Libtool convenience libraries are declared by directory-less variables
5000 such as @code{noinst_LTLIBRARIES}, @code{check_LTLIBRARIES}, or even
5001 @code{EXTRA_LTLIBRARIES}. Unlike installed libtool libraries they do
5002 not need an @option{-rpath} flag at link time (actually this is the only
5005 Convenience libraries listed in @code{noinst_LTLIBRARIES} are always
5006 built. Those listed in @code{check_LTLIBRARIES} are built only upon
5007 @samp{make check}. Finally, libraries listed in
5008 @code{EXTRA_LTLIBRARIES} are never built explicitly: Automake outputs
5009 rules to build them, but if the library does not appear as a Makefile
5010 dependency anywhere it won't be built (this is why
5011 @code{EXTRA_LTLIBRARIES} is used for conditional compilation).
5013 Here is a sample setup merging libtool convenience libraries from
5014 subdirectories into one main @file{libtop.la} library.
5017 # -- Top-level Makefile.am --
5018 SUBDIRS = sub1 sub2 @dots{}
5019 lib_LTLIBRARIES = libtop.la
5021 libtop_la_LIBADD = \
5026 # -- sub1/Makefile.am --
5027 noinst_LTLIBRARIES = libsub1.la
5028 libsub1_la_SOURCES = @dots{}
5030 # -- sub2/Makefile.am --
5031 # showing nested convenience libraries
5032 SUBDIRS = sub2.1 sub2.2 @dots{}
5033 noinst_LTLIBRARIES = libsub2.la
5034 libsub2_la_SOURCES =
5035 libsub2_la_LIBADD = \
5041 When using such setup, beware that @command{automake} will assume
5042 @file{libtop.la} is to be linked with the C linker. This is because
5043 @code{libtop_la_SOURCES} is empty, so @command{automake} picks C as
5044 default language. If @code{libtop_la_SOURCES} was not empty,
5045 @command{automake} would select the linker as explained in @ref{How
5046 the Linker is Chosen}.
5048 If one of the sublibraries contains non-C source, it is important that
5049 the appropriate linker be chosen. One way to achieve this is to
5050 pretend that there is such a non-C file among the sources of the
5051 library, thus forcing @command{automake} to select the appropriate
5052 linker. Here is the top-level @file{Makefile} of our example updated
5053 to force C++ linking.
5056 SUBDIRS = sub1 sub2 @dots{}
5057 lib_LTLIBRARIES = libtop.la
5059 # Dummy C++ source to cause C++ linking.
5060 nodist_EXTRA_libtop_la_SOURCES = dummy.cxx
5061 libtop_la_LIBADD = \
5067 @samp{EXTRA_*_SOURCES} variables are used to keep track of source
5068 files that might be compiled (this is mostly useful when doing
5069 conditional compilation using @code{AC_SUBST}, @pxref{Conditional
5070 Libtool Sources}), and the @code{nodist_} prefix means the listed
5071 sources are not to be distributed (@pxref{Program and Library
5072 Variables}). In effect the file @file{dummy.cxx} does not need to
5073 exist in the source tree. Of course if you have some real source file
5074 to list in @code{libtop_la_SOURCES} there is no point in cheating with
5075 @code{nodist_EXTRA_libtop_la_SOURCES}.
5078 @node Libtool Modules
5079 @subsection Libtool Modules
5080 @cindex modules, libtool
5081 @cindex libtool modules
5082 @cindex @option{-module}, libtool
5084 These are libtool libraries meant to be dlopened. They are
5085 indicated to libtool by passing @option{-module} at link-time.
5088 pkglib_LTLIBRARIES = mymodule.la
5089 mymodule_la_SOURCES = doit.c
5090 mymodule_la_LDFLAGS = -module
5093 Ordinarily, Automake requires that a library's name starts with
5094 @code{lib}. However, when building a dynamically loadable module you
5095 might wish to use a "nonstandard" name. Automake will not complain
5096 about such nonstandard name if it knows the library being built is a
5097 libtool module, i.e., if @option{-module} explicitly appears in the
5098 library's @code{_LDFLAGS} variable (or in the common @code{AM_LDFLAGS}
5099 variable when no per-library @code{_LDFLAGS} variable is defined).
5101 As always, @code{AC_SUBST} variables are black boxes to Automake since
5102 their values are not yet known when @command{automake} is run.
5103 Therefore if @option{-module} is set via such a variable, Automake
5104 cannot notice it and will proceed as if the library was an ordinary
5105 libtool library, with strict naming.
5107 If @code{mymodule_la_SOURCES} is not specified, then it defaults to
5108 the single file @file{mymodule.c} (@pxref{Default _SOURCES}).
5111 @subsection @code{_LIBADD}, @code{_LDFLAGS}, and @code{_LIBTOOLFLAGS}
5112 @cindex @code{_LIBADD}, libtool
5113 @cindex @code{_LDFLAGS}, libtool
5114 @cindex @code{_LIBTOOLFLAGS}, libtool
5115 @vindex AM_LIBTOOLFLAGS
5116 @vindex LIBTOOLFLAGS
5117 @vindex maude_LIBTOOLFLAGS
5119 As shown in previous sections, the @samp{@var{library}_LIBADD}
5120 variable should be used to list extra libtool objects (@file{.lo}
5121 files) or libtool libraries (@file{.la}) to add to @var{library}.
5123 The @samp{@var{library}_LDFLAGS} variable is the place to list
5124 additional libtool linking flags, such as @option{-version-info},
5125 @option{-static}, and a lot more. @xref{Link mode, , Link mode,
5126 libtool, The Libtool Manual}.
5128 The @command{libtool} command has two kinds of options: mode-specific
5129 options and generic options. Mode-specific options such as the
5130 aforementioned linking flags should be lumped with the other flags
5131 passed to the tool invoked by @command{libtool} (hence the use of
5132 @samp{@var{library}_LDFLAGS} for libtool linking flags). Generic
5133 options include @option{--tag=@var{TAG}} and @option{--silent}
5134 (@pxref{Invoking libtool, , Invoking @command{libtool}, libtool, The
5135 Libtool Manual} for more options) should appear before the mode
5136 selection on the command line; in @file{Makefile.am}s they should
5137 be listed in the @samp{@var{library}_LIBTOOLFLAGS} variable.
5139 If @samp{@var{library}_LIBTOOLFLAGS} is not defined, the global
5140 @code{AM_LIBTOOLFLAGS} variable is used instead.
5142 These flags are passed to libtool after the @option{--tag=@var{TAG}}
5143 option computed by Automake (if any), so
5144 @samp{@var{library}_LIBTOOLFLAGS} (or @code{AM_LIBTOOLFLAGS}) is the
5145 good place to override or supplement the @option{--tag=@var{TAG}}
5148 The libtool rules also use a @code{LIBTOOLFLAGS} variable that should
5149 not be set in @file{Makefile.am}: this is a user variable (@pxref{Flag
5150 Variables Ordering}. It allows users to run @samp{make
5151 LIBTOOLFLAGS=--silent}, for instance.
5154 @node LTLIBOBJS, Libtool Issues, Libtool Flags, A Shared Library
5155 @subsection @code{LTLIBOBJS} and @code{LTALLOCA}
5156 @cindex @code{LTLIBOBJS}, special handling
5157 @cindex @code{LIBOBJS}, and Libtool
5158 @cindex @code{LTALLOCA}, special handling
5159 @cindex @code{ALLOCA}, and Libtool
5166 Where an ordinary library might include @samp{$(LIBOBJS)} or
5167 @samp{$(ALLOCA)} (@pxref{LIBOBJS}), a libtool library must use
5168 @samp{$(LTLIBOBJS)} or @samp{$(LTALLOCA)}. This is required because
5169 the object files that libtool operates on do not necessarily end in
5172 Nowadays, the computation of @code{LTLIBOBJS} from @code{LIBOBJS} is
5173 performed automatically by Autoconf (@pxref{AC_LIBOBJ vs LIBOBJS, ,
5174 @code{AC_LIBOBJ} vs.@: @code{LIBOBJS}, autoconf, The Autoconf Manual}).
5176 @node Libtool Issues
5177 @subsection Common Issues Related to Libtool's Use
5179 @subsubsection @samp{required file `./ltmain.sh' not found}
5180 @cindex @file{ltmain.sh} not found
5181 @cindex @command{libtoolize}, no longer run by @command{automake}
5182 @cindex @command{libtoolize} and @command{autoreconf}
5183 @cindex @command{autoreconf} and @command{libtoolize}
5184 @cindex @file{bootstrap.sh} and @command{autoreconf}
5185 @cindex @file{autogen.sh} and @command{autoreconf}
5187 Libtool comes with a tool called @command{libtoolize} that will
5188 install libtool's supporting files into a package. Running this
5189 command will install @file{ltmain.sh}. You should execute it before
5190 @command{aclocal} and @command{automake}.
5192 People upgrading old packages to newer autotools are likely to face
5193 this issue because older Automake versions used to call
5194 @command{libtoolize}. Therefore old build scripts do not call
5195 @command{libtoolize}.
5197 Since Automake 1.6, it has been decided that running
5198 @command{libtoolize} was none of Automake's business. Instead, that
5199 functionality has been moved into the @command{autoreconf} command
5200 (@pxref{autoreconf Invocation, , Using @command{autoreconf}, autoconf,
5201 The Autoconf Manual}). If you do not want to remember what to run and
5202 when, just learn the @command{autoreconf} command. Hopefully,
5203 replacing existing @file{bootstrap.sh} or @file{autogen.sh} scripts by
5204 a call to @command{autoreconf} should also free you from any similar
5205 incompatible change in the future.
5207 @subsubsection Objects @samp{created with both libtool and without}
5209 Sometimes, the same source file is used both to build a libtool
5210 library and to build another non-libtool target (be it a program or
5213 Let's consider the following @file{Makefile.am}.
5217 prog_SOURCES = prog.c foo.c @dots{}
5219 lib_LTLIBRARIES = libfoo.la
5220 libfoo_la_SOURCES = foo.c @dots{}
5224 (In this trivial case the issue could be avoided by linking
5225 @file{libfoo.la} with @file{prog} instead of listing @file{foo.c} in
5226 @code{prog_SOURCES}. But let's assume we really want to keep
5227 @file{prog} and @file{libfoo.la} separate.)
5229 Technically, it means that we should build @file{foo.$(OBJEXT)} for
5230 @file{prog}, and @file{foo.lo} for @file{libfoo.la}. The problem is
5231 that in the course of creating @file{foo.lo}, libtool may erase (or
5232 replace) @file{foo.$(OBJEXT)}, and this cannot be avoided.
5234 Therefore, when Automake detects this situation it will complain
5235 with a message such as
5237 object `foo.$(OBJEXT)' created both with libtool and without
5240 A workaround for this issue is to ensure that these two objects get
5241 different basenames. As explained in @ref{renamed objects}, this
5242 happens automatically when per-targets flags are used.
5246 prog_SOURCES = prog.c foo.c @dots{}
5247 prog_CFLAGS = $(AM_CFLAGS)
5249 lib_LTLIBRARIES = libfoo.la
5250 libfoo_la_SOURCES = foo.c @dots{}
5254 Adding @samp{prog_CFLAGS = $(AM_CFLAGS)} is almost a no-op, because
5255 when the @code{prog_CFLAGS} is defined, it is used instead of
5256 @code{AM_CFLAGS}. However as a side effect it will cause
5257 @file{prog.c} and @file{foo.c} to be compiled as
5258 @file{prog-prog.$(OBJEXT)} and @file{prog-foo.$(OBJEXT)}, which solves
5261 @node Program and Library Variables
5262 @section Program and Library Variables
5264 Associated with each program are a collection of variables that can be
5265 used to modify how that program is built. There is a similar list of
5266 such variables for each library. The canonical name of the program (or
5267 library) is used as a base for naming these variables.
5269 In the list below, we use the name ``maude'' to refer to the program or
5270 library. In your @file{Makefile.am} you would replace this with the
5271 canonical name of your program. This list also refers to ``maude'' as a
5272 program, but in general the same rules apply for both static and dynamic
5273 libraries; the documentation below notes situations where programs and
5278 This variable, if it exists, lists all the source files that are
5279 compiled to build the program. These files are added to the
5280 distribution by default. When building the program, Automake will cause
5281 each source file to be compiled to a single @file{.o} file (or
5282 @file{.lo} when using libtool). Normally these object files are named
5283 after the source file, but other factors can change this. If a file in
5284 the @code{_SOURCES} variable has an unrecognized extension, Automake
5285 will do one of two things with it. If a suffix rule exists for turning
5286 files with the unrecognized extension into @file{.o} files, then
5287 automake will treat this file as it will any other source file
5288 (@pxref{Support for Other Languages}). Otherwise, the file will be
5289 ignored as though it were a header file.
5291 The prefixes @code{dist_} and @code{nodist_} can be used to control
5292 whether files listed in a @code{_SOURCES} variable are distributed.
5293 @code{dist_} is redundant, as sources are distributed by default, but it
5294 can be specified for clarity if desired.
5296 It is possible to have both @code{dist_} and @code{nodist_} variants of
5297 a given @code{_SOURCES} variable at once; this lets you easily
5298 distribute some files and not others, for instance:
5301 nodist_maude_SOURCES = nodist.c
5302 dist_maude_SOURCES = dist-me.c
5305 By default the output file (on Unix systems, the @file{.o} file) will
5306 be put into the current build directory. However, if the option
5307 @option{subdir-objects} is in effect in the current directory then the
5308 @file{.o} file will be put into the subdirectory named after the
5309 source file. For instance, with @option{subdir-objects} enabled,
5310 @file{sub/dir/file.c} will be compiled to @file{sub/dir/file.o}. Some
5311 people prefer this mode of operation. You can specify
5312 @option{subdir-objects} in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
5313 @cindex Subdirectory, objects in
5314 @cindex Objects in subdirectory
5317 @item EXTRA_maude_SOURCES
5318 Automake needs to know the list of files you intend to compile
5319 @emph{statically}. For one thing, this is the only way Automake has of
5320 knowing what sort of language support a given @file{Makefile.in}
5321 requires. @footnote{There are other, more obscure reasons for
5322 this limitation as well.} This means that, for example, you can't put a
5323 configure substitution like @samp{@@my_sources@@} into a @samp{_SOURCES}
5324 variable. If you intend to conditionally compile source files and use
5325 @file{configure} to substitute the appropriate object names into, e.g.,
5326 @code{_LDADD} (see below), then you should list the corresponding source
5327 files in the @code{EXTRA_} variable.
5329 This variable also supports @code{dist_} and @code{nodist_} prefixes.
5330 For instance, @code{nodist_EXTRA_maude_SOURCES} would list extra
5331 sources that may need to be built, but should not be distributed.
5334 A static library is created by default by invoking @samp{$(AR)
5335 $(ARFLAGS)} followed by the name of the library and then the objects
5336 being put into the library. You can override this by setting the
5337 @code{_AR} variable. This is usually used with C++; some C++
5338 compilers require a special invocation in order to instantiate all the
5339 templates that should go into a library. For instance, the SGI C++
5340 compiler likes this variable set like so:
5342 libmaude_a_AR = $(CXX) -ar -o
5346 Extra objects can be added to a @emph{library} using the @code{_LIBADD}
5347 variable. For instance, this should be used for objects determined by
5348 @command{configure} (@pxref{A Library}).
5350 In the case of libtool libraries, @code{maude_LIBADD} can also refer
5351 to other libtool libraries.
5354 Extra objects (@file{*.$(OBJEXT)}) and libraries (@file{*.a},
5355 @file{*.la}) can be added to a @emph{program} by listing them in the
5356 @code{_LDADD} variable. For instance, this should be used for objects
5357 determined by @command{configure} (@pxref{Linking}).
5359 @code{_LDADD} and @code{_LIBADD} are inappropriate for passing
5360 program-specific linker flags (except for @option{-l}, @option{-L},
5361 @option{-dlopen} and @option{-dlpreopen}). Use the @code{_LDFLAGS} variable
5364 For instance, if your @file{configure.ac} uses @code{AC_PATH_XTRA}, you
5365 could link your program against the X libraries like so:
5368 maude_LDADD = $(X_PRE_LIBS) $(X_LIBS) $(X_EXTRA_LIBS)
5371 We recommend that you use @option{-l} and @option{-L} only when
5372 referring to third-party libraries, and give the explicit file names
5373 of any library built by your package. Doing so will ensure that
5374 @code{maude_DEPENDENCIES} (see below) is correctly defined by default.
5377 This variable is used to pass extra flags to the link step of a program
5378 or a shared library. It overrides the global @code{AM_LDFLAGS} variable.
5380 @item maude_LIBTOOLFLAGS
5381 This variable is used to pass extra options to @command{libtool}.
5382 It overrides the global @code{AM_LIBTOOLFLAGS} variable.
5383 These options are output before @command{libtool}'s @option{--mode=@var{MODE}}
5384 option, so they should not be mode-specific options (those belong to
5385 the compiler or linker flags). @xref{Libtool Flags}.
5387 @item maude_DEPENDENCIES
5388 It is also occasionally useful to have a target (program or library)
5389 depend on some other file that is not actually part of that target.
5390 This can be done using the @code{_DEPENDENCIES} variable. Each
5391 targets depends on the contents of such a variable, but no further
5392 interpretation is done.
5394 Since these dependencies are associated to the link rule used to
5395 create the programs they should normally list files used by the link
5396 command. That is @file{*.$(OBJEXT)}, @file{*.a}, or @file{*.la} files
5397 for programs; @file{*.lo} and @file{*.la} files for Libtool libraries;
5398 and @file{*.$(OBJEXT)} files for static libraries. In rare cases you
5399 may need to add other kinds of files such as linker scripts, but
5400 @emph{listing a source file in @code{_DEPENDENCIES} is wrong}. If
5401 some source file needs to be built before all the components of a
5402 program are built, consider using the @code{BUILT_SOURCES} variable
5405 If @code{_DEPENDENCIES} is not supplied, it is computed by Automake.
5406 The automatically-assigned value is the contents of @code{_LDADD} or
5407 @code{_LIBADD}, with most configure substitutions, @option{-l}, @option{-L},
5408 @option{-dlopen} and @option{-dlpreopen} options removed. The configure
5409 substitutions that are left in are only @samp{$(LIBOBJS)} and
5410 @samp{$(ALLOCA)}; these are left because it is known that they will not
5411 cause an invalid value for @code{_DEPENDENCIES} to be generated.
5413 @code{_DEPENDENCIES} is more likely used to perform conditional
5414 compilation using an @code{AC_SUBST} variable that contains a list of
5415 objects. @xref{Conditional Sources}, and @ref{Conditional Libtool
5419 You can override the linker on a per-program basis. By default the
5420 linker is chosen according to the languages used by the program. For
5421 instance, a program that includes C++ source code would use the C++
5422 compiler to link. The @code{_LINK} variable must hold the name of a
5423 command that can be passed all the @file{.o} file names as arguments.
5424 Note that the name of the underlying program is @emph{not} passed to
5425 @code{_LINK}; typically one uses @samp{$@@}:
5428 maude_LINK = $(CCLD) -magic -o $@@
5431 @item maude_CCASFLAGS
5433 @itemx maude_CPPFLAGS
5434 @itemx maude_CXXFLAGS
5436 @itemx maude_GCJFLAGS
5438 @itemx maude_OBJCFLAGS
5440 @itemx maude_UPCFLAGS
5442 @cindex per-target compilation flags, defined
5443 Automake allows you to set compilation flags on a per-program (or
5444 per-library) basis. A single source file can be included in several
5445 programs, and it will potentially be compiled with different flags for
5446 each program. This works for any language directly supported by
5447 Automake. These @dfn{per-target compilation flags} are
5457 @samp{_UPCFLAGS}, and
5460 When using a per-target compilation flag, Automake will choose a
5461 different name for the intermediate object files. Ordinarily a file
5462 like @file{sample.c} will be compiled to produce @file{sample.o}.
5463 However, if the program's @code{_CFLAGS} variable is set, then the
5464 object file will be named, for instance, @file{maude-sample.o}. (See
5465 also @ref{renamed objects}.) The use of per-target compilation flags
5466 with C sources requires that the macro @code{AM_PROG_CC_C_O} be called
5467 from @file{configure.ac}.
5469 In compilations with per-target flags, the ordinary @samp{AM_} form of
5470 the flags variable is @emph{not} automatically included in the
5471 compilation (however, the user form of the variable @emph{is} included).
5472 So for instance, if you want the hypothetical @file{maude} compilations
5473 to also use the value of @code{AM_CFLAGS}, you would need to write:
5476 maude_CFLAGS = @dots{} your flags @dots{} $(AM_CFLAGS)
5479 @xref{Flag Variables Ordering}, for more discussion about the
5480 interaction between user variables, @samp{AM_} shadow variables, and
5481 per-target variables.
5483 @item maude_SHORTNAME
5484 On some platforms the allowable file names are very short. In order to
5485 support these systems and per-target compilation flags at the same
5486 time, Automake allows you to set a ``short name'' that will influence
5487 how intermediate object files are named. For instance, in the following
5491 bin_PROGRAMS = maude
5492 maude_CPPFLAGS = -DSOMEFLAG
5494 maude_SOURCES = sample.c @dots{}
5498 the object file would be named @file{m-sample.o} rather than
5499 @file{maude-sample.o}.
5501 This facility is rarely needed in practice,
5502 and we recommend avoiding it until you find it is required.
5505 @node Default _SOURCES
5506 @section Default @code{_SOURCES}
5510 @cindex @code{_SOURCES}, default
5511 @cindex default @code{_SOURCES}
5513 @code{_SOURCES} variables are used to specify source files of programs
5514 (@pxref{A Program}), libraries (@pxref{A Library}), and Libtool
5515 libraries (@pxref{A Shared Library}).
5517 When no such variable is specified for a target, Automake will define
5518 one itself. The default is to compile a single C file whose base name
5519 is the name of the target itself, with any extension replaced by
5520 @file{.c}. (Defaulting to C is terrible but we are stuck with it for
5521 historical reasons.)
5523 For example if you have the following somewhere in your
5524 @file{Makefile.am} with no corresponding @code{libfoo_a_SOURCES}:
5527 lib_LIBRARIES = libfoo.a sub/libc++.a
5531 @file{libfoo.a} will be built using a default source file named
5532 @file{libfoo.c}, and @file{sub/libc++.a} will be built from
5533 @file{sub/libc++.c}. (In older versions @file{sub/libc++.a}
5534 would be built from @file{sub_libc___a.c}, i.e., the default source
5535 was the canonized name of the target, with @file{.c} appended.
5536 We believe the new behavior is more sensible, but for backward
5537 compatibility automake will use the old name if a file or a rule
5538 with that name exist.)
5540 @cindex @code{check_PROGRAMS} example
5541 @vindex check_PROGRAMS
5542 Default sources are mainly useful in test suites, when building many
5543 tests programs each from a single source. For instance, in
5546 check_PROGRAMS = test1 test2 test3
5550 @file{test1}, @file{test2}, and @file{test3} will be built
5551 from @file{test1.c}, @file{test2.c}, and @file{test3.c}.
5553 @cindex Libtool modules, default source example
5554 @cindex default source, Libtool modules example
5555 Another case where is this convenient is building many Libtool modules
5556 (@file{moduleN.la}), each defined in its own file (@file{moduleN.c}).
5559 AM_LDFLAGS = -module
5560 lib_LTLIBRARIES = module1.la module2.la module3.la
5563 @cindex empty @code{_SOURCES}
5564 @cindex @code{_SOURCES}, empty
5565 Finally, there is one situation where this default source computation
5566 needs to be avoided: when a target should not be built from sources.
5567 We already saw such an example in @ref{true}; this happens when all
5568 the constituents of a target have already been compiled and need just
5569 to be combined using a @code{_LDADD} variable. Then it is necessary
5570 to define an empty @code{_SOURCES} variable, so that automake does not
5574 bin_PROGRAMS = target
5576 target_LDADD = libmain.a libmisc.a
5580 @section Special handling for @code{LIBOBJS} and @code{ALLOCA}
5582 @cindex @code{LIBOBJS}, example
5583 @cindex @code{ALLOCA}, example
5584 @cindex @code{LIBOBJS}, special handling
5585 @cindex @code{ALLOCA}, special handling
5591 The @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} variables list object
5592 files that should be compiled into the project to provide an
5593 implementation for functions that are missing or broken on the host
5594 system. They are substituted by @file{configure}.
5598 These variables are defined by Autoconf macros such as
5599 @code{AC_LIBOBJ}, @code{AC_REPLACE_FUNCS} (@pxref{Generic Functions, ,
5600 Generic Function Checks, autoconf, The Autoconf Manual}), or
5601 @code{AC_FUNC_ALLOCA} (@pxref{Particular Functions, , Particular
5602 Function Checks, autoconf, The Autoconf Manual}). Many other Autoconf
5603 macros call @code{AC_LIBOBJ} or @code{AC_REPLACE_FUNCS} to
5604 populate @samp{$(LIBOBJS)}.
5606 @acindex AC_LIBSOURCE
5608 Using these variables is very similar to doing conditional compilation
5609 using @code{AC_SUBST} variables, as described in @ref{Conditional
5610 Sources}. That is, when building a program, @samp{$(LIBOBJS)} and
5611 @samp{$(ALLOCA)} should be added to the associated @samp{*_LDADD}
5612 variable, or to the @samp{*_LIBADD} variable when building a library.
5613 However there is no need to list the corresponding sources in
5614 @samp{EXTRA_*_SOURCES} nor to define @samp{*_DEPENDENCIES}. Automake
5615 automatically adds @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} to the
5616 dependencies, and it will discover the list of corresponding source
5617 files automatically (by tracing the invocations of the
5618 @code{AC_LIBSOURCE} Autoconf macros).
5620 These variables are usually used to build a portability library that
5621 is linked with all the programs of the project. We now review a
5622 sample setup. First, @file{configure.ac} contains some checks that
5623 affect either @code{LIBOBJS} or @code{ALLOCA}.
5628 AC_CONFIG_LIBOBJ_DIR([lib])
5630 AC_FUNC_MALLOC dnl May add malloc.$(OBJEXT) to LIBOBJS
5631 AC_FUNC_MEMCMP dnl May add memcmp.$(OBJEXT) to LIBOBJS
5632 AC_REPLACE_FUNCS([strdup]) dnl May add strdup.$(OBJEXT) to LIBOBJS
5633 AC_FUNC_ALLOCA dnl May add alloca.$(OBJEXT) to ALLOCA
5642 @acindex AC_CONFIG_LIBOBJ_DIR
5644 The @code{AC_CONFIG_LIBOBJ_DIR} tells Autoconf that the source files
5645 of these object files are to be found in the @file{lib/} directory.
5646 Automake can also use this information, otherwise it expects the
5647 source files are to be in the directory where the @samp{$(LIBOBJS)}
5648 and @samp{$(ALLOCA)} variables are used.
5650 The @file{lib/} directory should therefore contain @file{malloc.c},
5651 @file{memcmp.c}, @file{strdup.c}, @file{alloca.c}. Here is its
5657 noinst_LIBRARIES = libcompat.a
5658 libcompat_a_SOURCES =
5659 libcompat_a_LIBADD = $(LIBOBJS) $(ALLOCA)
5662 The library can have any name, of course, and anyway it is not going
5663 to be installed: it just holds the replacement versions of the missing
5664 or broken functions so we can later link them in. In many projects
5665 also include extra functions, specific to the project, in that
5666 library: they are simply added on the @code{_SOURCES} line.
5668 @cindex Empty libraries and @samp{$(LIBOBJS)}
5669 @cindex @samp{$(LIBOBJS)} and empty libraries
5670 There is a small trap here, though: @samp{$(LIBOBJS)} and
5671 @samp{$(ALLOCA)} might be empty, and building an empty library is not
5672 portable. You should ensure that there is always something to put in
5673 @file{libcompat.a}. Most projects will also add some utility
5674 functions in that directory, and list them in
5675 @code{libcompat_a_SOURCES}, so in practice @file{libcompat.a} cannot
5678 Finally here is how this library could be used from the @file{src/}
5684 # Link all programs in this directory with libcompat.a
5685 LDADD = ../lib/libcompat.a
5687 bin_PROGRAMS = tool1 tool2 @dots{}
5688 tool1_SOURCES = @dots{}
5689 tool2_SOURCES = @dots{}
5692 When option @option{subdir-objects} is not used, as in the above
5693 example, the variables @samp{$(LIBOBJS)} or @samp{$(ALLOCA)} can only
5694 be used in the directory where their sources lie. E.g., here it would
5695 be wrong to use @samp{$(LIBOBJS)} or @samp{$(ALLOCA)} in
5696 @file{src/Makefile.am}. However if both @option{subdir-objects} and
5697 @code{AC_CONFIG_LIBOBJ_DIR} are used, it is OK to use these variables
5698 in other directories. For instance @file{src/Makefile.am} could be
5704 AUTOMAKE_OPTIONS = subdir-objects
5705 LDADD = $(LIBOBJS) $(ALLOCA)
5707 bin_PROGRAMS = tool1 tool2 @dots{}
5708 tool1_SOURCES = @dots{}
5709 tool2_SOURCES = @dots{}
5712 Because @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} contain object
5713 file names that end with @samp{.$(OBJEXT)}, they are not suitable for
5714 Libtool libraries (where the expected object extension is @file{.lo}):
5715 @code{LTLIBOBJS} and @code{LTALLOCA} should be used instead.
5717 @code{LTLIBOBJS} is defined automatically by Autoconf and should not
5718 be defined by hand (as in the past), however at the time of writing
5719 @code{LTALLOCA} still needs to be defined from @code{ALLOCA} manually.
5720 @xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs.@: @code{LIBOBJS},
5721 autoconf, The Autoconf Manual}.
5724 @node Program variables
5725 @section Variables used when building a program
5727 Occasionally it is useful to know which @file{Makefile} variables
5728 Automake uses for compilations; for instance, you might need to do your
5729 own compilation in some special cases.
5731 Some variables are inherited from Autoconf; these are @code{CC},
5732 @code{CFLAGS}, @code{CPPFLAGS}, @code{DEFS}, @code{LDFLAGS}, and
5741 There are some additional variables that Automake defines on its own:
5745 The contents of this variable are passed to every compilation that invokes
5746 the C preprocessor; it is a list of arguments to the preprocessor. For
5747 instance, @option{-I} and @option{-D} options should be listed here.
5749 Automake already provides some @option{-I} options automatically, in a
5750 separate variable that is also passed to every compilation that invokes
5751 the C preprocessor. In particular it generates @samp{-I.},
5752 @samp{-I$(srcdir)}, and a @option{-I} pointing to the directory holding
5753 @file{config.h} (if you've used @code{AC_CONFIG_HEADERS} or
5754 @code{AM_CONFIG_HEADER}). You can disable the default @option{-I}
5755 options using the @option{nostdinc} option.
5757 @code{AM_CPPFLAGS} is ignored in preference to a per-executable (or
5758 per-library) @code{_CPPFLAGS} variable if it is defined.
5761 This does the same job as @code{AM_CPPFLAGS} (or any per-target
5762 @code{_CPPFLAGS} variable if it is used). It is an older name for the
5763 same functionality. This variable is deprecated; we suggest using
5764 @code{AM_CPPFLAGS} and per-target @code{_CPPFLAGS} instead.
5767 This is the variable the @file{Makefile.am} author can use to pass
5768 in additional C compiler flags. It is more fully documented elsewhere.
5769 In some situations, this is not used, in preference to the
5770 per-executable (or per-library) @code{_CFLAGS}.
5773 This is the command used to actually compile a C source file. The
5774 file name is appended to form the complete command line.
5777 This is the variable the @file{Makefile.am} author can use to pass
5778 in additional linker flags. In some situations, this is not used, in
5779 preference to the per-executable (or per-library) @code{_LDFLAGS}.
5782 This is the command used to actually link a C program. It already
5783 includes @samp{-o $@@} and the usual variable references (for instance,
5784 @code{CFLAGS}); it takes as ``arguments'' the names of the object files
5785 and libraries to link in.
5790 @section Yacc and Lex support
5792 Automake has somewhat idiosyncratic support for Yacc and Lex.
5794 Automake assumes that the @file{.c} file generated by @command{yacc}
5795 (or @command{lex}) should be named using the basename of the input
5796 file. That is, for a yacc source file @file{foo.y}, Automake will
5797 cause the intermediate file to be named @file{foo.c} (as opposed to
5798 @file{y.tab.c}, which is more traditional).
5800 The extension of a yacc source file is used to determine the extension
5801 of the resulting C or C++ file. Files with the extension @file{.y}
5802 will be turned into @file{.c} files; likewise, @file{.yy} will become
5803 @file{.cc}; @file{.y++}, @file{c++}; @file{.yxx}, @file{.cxx}; and
5804 @file{.ypp}, @file{.cpp}.
5806 Likewise, lex source files can be used to generate C or C++; the
5807 extensions @file{.l}, @file{.ll}, @file{.l++}, @file{.lxx}, and
5808 @file{.lpp} are recognized.
5810 You should never explicitly mention the intermediate (C or C++) file
5811 in any @code{SOURCES} variable; only list the source file.
5813 The intermediate files generated by @command{yacc} (or @command{lex})
5814 will be included in any distribution that is made. That way the user
5815 doesn't need to have @command{yacc} or @command{lex}.
5817 If a @command{yacc} source file is seen, then your @file{configure.ac} must
5818 define the variable @code{YACC}. This is most easily done by invoking
5819 the macro @code{AC_PROG_YACC} (@pxref{Particular Programs, , Particular
5820 Program Checks, autoconf, The Autoconf Manual}).
5824 When @code{yacc} is invoked, it is passed @code{YFLAGS} and
5825 @code{AM_YFLAGS}. The former is a user variable and the latter is
5826 intended for the @file{Makefile.am} author.
5828 @code{AM_YFLAGS} is usually used to pass the @option{-d} option to
5829 @command{yacc}. Automake knows what this means and will automatically
5830 adjust its rules to update and distribute the header file built by
5831 @samp{yacc -d}. What Automake cannot guess, though, is where this
5832 header will be used: it is up to you to ensure the header gets built
5833 before it is first used. Typically this is necessary in order for
5834 dependency tracking to work when the header is included by another
5835 file. The common solution is listing the header file in
5836 @code{BUILT_SOURCES} (@pxref{Sources}) as follows.
5839 BUILT_SOURCES = parser.h
5842 foo_SOURCES = @dots{} parser.y @dots{}
5845 If a @command{lex} source file is seen, then your @file{configure.ac}
5846 must define the variable @code{LEX}. You can use @code{AC_PROG_LEX}
5847 to do this (@pxref{Particular Programs, , Particular Program Checks,
5848 autoconf, The Autoconf Manual}), but using @code{AM_PROG_LEX} macro
5849 (@pxref{Macros}) is recommended.
5853 When @command{lex} is invoked, it is passed @code{LFLAGS} and
5854 @code{AM_LFLAGS}. The former is a user variable and the latter is
5855 intended for the @file{Makefile.am} author.
5857 When @code{AM_MAINTAINER_MODE} (@pxref{maintainer-mode}) is used, the
5858 rebuild rule for distributed Yacc and Lex sources are only used when
5859 @code{maintainer-mode} is enabled, or when the files have been erased.
5861 @cindex @command{ylwrap}
5862 @cindex @command{yacc}, multiple parsers
5863 @cindex Multiple @command{yacc} parsers
5864 @cindex Multiple @command{lex} lexers
5865 @cindex @command{lex}, multiple lexers
5867 When @command{lex} or @command{yacc} sources are used, @code{automake
5868 -i} automatically installs an auxiliary program called
5869 @command{ylwrap} in your package (@pxref{Auxiliary Programs}). This
5870 program is used by the build rules to rename the output of these
5871 tools, and makes it possible to include multiple @command{yacc} (or
5872 @command{lex}) source files in a single directory. (This is necessary
5873 because yacc's output file name is fixed, and a parallel make could
5874 conceivably invoke more than one instance of @command{yacc}
5877 For @command{yacc}, simply managing locking is insufficient. The output of
5878 @command{yacc} always uses the same symbol names internally, so it isn't
5879 possible to link two @command{yacc} parsers into the same executable.
5881 We recommend using the following renaming hack used in @command{gdb}:
5883 #define yymaxdepth c_maxdepth
5884 #define yyparse c_parse
5886 #define yyerror c_error
5887 #define yylval c_lval
5888 #define yychar c_char
5889 #define yydebug c_debug
5890 #define yypact c_pact
5897 #define yyexca c_exca
5898 #define yyerrflag c_errflag
5899 #define yynerrs c_nerrs
5903 #define yy_yys c_yys
5904 #define yystate c_state
5907 #define yy_yyv c_yyv
5909 #define yylloc c_lloc
5910 #define yyreds c_reds
5911 #define yytoks c_toks
5912 #define yylhs c_yylhs
5913 #define yylen c_yylen
5914 #define yydefred c_yydefred
5915 #define yydgoto c_yydgoto
5916 #define yysindex c_yysindex
5917 #define yyrindex c_yyrindex
5918 #define yygindex c_yygindex
5919 #define yytable c_yytable
5920 #define yycheck c_yycheck
5921 #define yyname c_yyname
5922 #define yyrule c_yyrule
5925 For each define, replace the @samp{c_} prefix with whatever you like.
5926 These defines work for @command{bison}, @command{byacc}, and
5927 traditional @code{yacc}s. If you find a parser generator that uses a
5928 symbol not covered here, please report the new name so it can be added
5933 @section C++ Support
5936 @cindex Support for C++
5938 Automake includes full support for C++.
5940 Any package including C++ code must define the output variable
5941 @code{CXX} in @file{configure.ac}; the simplest way to do this is to use
5942 the @code{AC_PROG_CXX} macro (@pxref{Particular Programs, , Particular
5943 Program Checks, autoconf, The Autoconf Manual}).
5945 A few additional variables are defined when a C++ source file is seen:
5949 The name of the C++ compiler.
5952 Any flags to pass to the C++ compiler.
5955 The maintainer's variant of @code{CXXFLAGS}.
5958 The command used to actually compile a C++ source file. The file name
5959 is appended to form the complete command line.
5962 The command used to actually link a C++ program.
5966 @node Objective C Support
5967 @section Objective C Support
5969 @cindex Objective C support
5970 @cindex Support for Objective C
5972 Automake includes some support for Objective C.
5974 Any package including Objective C code must define the output variable
5975 @code{OBJC} in @file{configure.ac}; the simplest way to do this is to use
5976 the @code{AC_PROG_OBJC} macro (@pxref{Particular Programs, , Particular
5977 Program Checks, autoconf, The Autoconf Manual}).
5979 A few additional variables are defined when an Objective C source file
5984 The name of the Objective C compiler.
5987 Any flags to pass to the Objective C compiler.
5990 The maintainer's variant of @code{OBJCFLAGS}.
5993 The command used to actually compile a Objective C source file. The
5994 file name is appended to form the complete command line.
5997 The command used to actually link a Objective C program.
6001 @node Unified Parallel C Support
6002 @section Unified Parallel C Support
6004 @cindex Unified Parallel C support
6005 @cindex Support for Unified Parallel C
6007 Automake includes some support for Unified Parallel C.
6009 Any package including Unified Parallel C code must define the output
6010 variable @code{UPC} in @file{configure.ac}; the simplest way to do
6011 this is to use the @code{AM_PROG_UPC} macro (@pxref{Public macros}).
6013 A few additional variables are defined when an Unified Parallel C
6014 source file is seen:
6018 The name of the Unified Parallel C compiler.
6021 Any flags to pass to the Unified Parallel C compiler.
6024 The maintainer's variant of @code{UPCFLAGS}.
6027 The command used to actually compile a Unified Parallel C source file.
6028 The file name is appended to form the complete command line.
6031 The command used to actually link a Unified Parallel C program.
6035 @node Assembly Support
6036 @section Assembly Support
6038 Automake includes some support for assembly code. There are two forms
6039 of assembler files: normal (@file{*.s}) and preprocessed by @code{CPP}
6040 (@file{*.S} or @file{*.sx}).
6045 @vindex AM_CCASFLAGS
6047 The variable @code{CCAS} holds the name of the compiler used to build
6048 assembly code. This compiler must work a bit like a C compiler; in
6049 particular it must accept @option{-c} and @option{-o}. The values of
6050 @code{CCASFLAGS} and @code{AM_CCASFLAGS} (or its per-target
6051 definition) is passed to the compilation. For preprocessed files,
6052 @code{DEFS}, @code{DEFAULT_INCLUDES}, @code{INCLUDES}, @code{CPPFLAGS}
6053 and @code{AM_CPPFLAGS} are also used.
6055 The autoconf macro @code{AM_PROG_AS} will define @code{CCAS} and
6056 @code{CCASFLAGS} for you (unless they are already set, it simply sets
6057 @code{CCAS} to the C compiler and @code{CCASFLAGS} to the C compiler
6058 flags), but you are free to define these variables by other means.
6060 Only the suffixes @file{.s}, @file{.S}, and @file{.sx} are recognized by
6061 @command{automake} as being files containing assembly code.
6064 @node Fortran 77 Support
6065 @comment node-name, next, previous, up
6066 @section Fortran 77 Support
6068 @cindex Fortran 77 support
6069 @cindex Support for Fortran 77
6071 Automake includes full support for Fortran 77.
6073 Any package including Fortran 77 code must define the output variable
6074 @code{F77} in @file{configure.ac}; the simplest way to do this is to use
6075 the @code{AC_PROG_F77} macro (@pxref{Particular Programs, , Particular
6076 Program Checks, autoconf, The Autoconf Manual}).
6078 A few additional variables are defined when a Fortran 77 source file is
6084 The name of the Fortran 77 compiler.
6087 Any flags to pass to the Fortran 77 compiler.
6090 The maintainer's variant of @code{FFLAGS}.
6093 Any flags to pass to the Ratfor compiler.
6096 The maintainer's variant of @code{RFLAGS}.
6099 The command used to actually compile a Fortran 77 source file. The file
6100 name is appended to form the complete command line.
6103 The command used to actually link a pure Fortran 77 program or shared
6108 Automake can handle preprocessing Fortran 77 and Ratfor source files in
6109 addition to compiling them@footnote{Much, if not most, of the
6110 information in the following sections pertaining to preprocessing
6111 Fortran 77 programs was taken almost verbatim from @ref{Catalogue of
6112 Rules, , Catalogue of Rules, make, The GNU Make Manual}.}. Automake
6113 also contains some support for creating programs and shared libraries
6114 that are a mixture of Fortran 77 and other languages (@pxref{Mixing
6115 Fortran 77 With C and C++}).
6117 These issues are covered in the following sections.
6120 * Preprocessing Fortran 77:: Preprocessing Fortran 77 sources
6121 * Compiling Fortran 77 Files:: Compiling Fortran 77 sources
6122 * Mixing Fortran 77 With C and C++:: Mixing Fortran 77 With C and C++
6126 @node Preprocessing Fortran 77
6127 @comment node-name, next, previous, up
6128 @subsection Preprocessing Fortran 77
6130 @cindex Preprocessing Fortran 77
6131 @cindex Fortran 77, Preprocessing
6132 @cindex Ratfor programs
6134 @file{N.f} is made automatically from @file{N.F} or @file{N.r}. This
6135 rule runs just the preprocessor to convert a preprocessable Fortran 77
6136 or Ratfor source file into a strict Fortran 77 source file. The precise
6137 command used is as follows:
6142 @code{$(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)@*
6143 $(AM_FFLAGS) $(FFLAGS)}
6146 @code{$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
6151 @node Compiling Fortran 77 Files
6152 @comment node-name, next, previous, up
6153 @subsection Compiling Fortran 77 Files
6155 @file{N.o} is made automatically from @file{N.f}, @file{N.F} or
6156 @file{N.r} by running the Fortran 77 compiler. The precise command used
6162 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS)}
6165 @code{$(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)@*
6166 $(AM_FFLAGS) $(FFLAGS)}
6169 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
6174 @node Mixing Fortran 77 With C and C++
6175 @comment node-name, next, previous, up
6176 @subsection Mixing Fortran 77 With C and C++
6178 @cindex Fortran 77, mixing with C and C++
6179 @cindex Mixing Fortran 77 with C and C++
6180 @cindex Linking Fortran 77 with C and C++
6182 @cindex Mixing Fortran 77 with C and/or C++
6184 Automake currently provides @emph{limited} support for creating programs
6185 and shared libraries that are a mixture of Fortran 77 and C and/or C++.
6186 However, there are many other issues related to mixing Fortran 77 with
6187 other languages that are @emph{not} (currently) handled by Automake, but
6188 that are handled by other packages@footnote{For example,
6189 @uref{http://www-zeus.desy.de/~burow/cfortran/, the cfortran package}
6190 addresses all of these inter-language issues, and runs under nearly all
6191 Fortran 77, C and C++ compilers on nearly all platforms. However,
6192 @command{cfortran} is not yet Free Software, but it will be in the next
6196 Automake can help in two ways:
6200 Automatic selection of the linker depending on which combinations of
6204 Automatic selection of the appropriate linker flags (e.g., @option{-L} and
6205 @option{-l}) to pass to the automatically selected linker in order to link
6206 in the appropriate Fortran 77 intrinsic and run-time libraries.
6208 @cindex @code{FLIBS}, defined
6210 These extra Fortran 77 linker flags are supplied in the output variable
6211 @code{FLIBS} by the @code{AC_F77_LIBRARY_LDFLAGS} Autoconf macro
6212 supplied with newer versions of Autoconf (Autoconf version 2.13 and
6213 later). @xref{Fortran 77 Compiler Characteristics, , , autoconf, The
6217 If Automake detects that a program or shared library (as mentioned in
6218 some @code{_PROGRAMS} or @code{_LTLIBRARIES} primary) contains source
6219 code that is a mixture of Fortran 77 and C and/or C++, then it requires
6220 that the macro @code{AC_F77_LIBRARY_LDFLAGS} be called in
6221 @file{configure.ac}, and that either @code{$(FLIBS)}
6222 appear in the appropriate @code{_LDADD} (for programs) or @code{_LIBADD}
6223 (for shared libraries) variables. It is the responsibility of the
6224 person writing the @file{Makefile.am} to make sure that @samp{$(FLIBS)}
6225 appears in the appropriate @code{_LDADD} or
6226 @code{_LIBADD} variable.
6228 @cindex Mixed language example
6229 @cindex Example, mixed language
6231 For example, consider the following @file{Makefile.am}:
6235 foo_SOURCES = main.cc foo.f
6236 foo_LDADD = libfoo.la $(FLIBS)
6238 pkglib_LTLIBRARIES = libfoo.la
6239 libfoo_la_SOURCES = bar.f baz.c zardoz.cc
6240 libfoo_la_LIBADD = $(FLIBS)
6243 In this case, Automake will insist that @code{AC_F77_LIBRARY_LDFLAGS}
6244 is mentioned in @file{configure.ac}. Also, if @samp{$(FLIBS)} hadn't
6245 been mentioned in @code{foo_LDADD} and @code{libfoo_la_LIBADD}, then
6246 Automake would have issued a warning.
6251 * How the Linker is Chosen:: Automatic linker selection
6254 @node How the Linker is Chosen
6255 @comment node-name, next, previous, up
6256 @subsubsection How the Linker is Chosen
6258 @cindex Automatic linker selection
6259 @cindex Selecting the linker automatically
6261 When a program or library mixes several languages, Automake choose the
6262 linker according to the following priorities. (The names in
6263 parentheses are the variables containing the link command.)
6268 Native Java (@code{GCJLINK})
6271 C++ (@code{CXXLINK})
6274 Fortran 77 (@code{F77LINK})
6277 Fortran (@code{FCLINK})
6280 Objective C (@code{OBJCLINK})
6283 Unified Parallel C (@code{UPCLINK})
6289 For example, if Fortran 77, C and C++ source code is compiled
6290 into a program, then the C++ linker will be used. In this case, if the
6291 C or Fortran 77 linkers required any special libraries that weren't
6292 included by the C++ linker, then they must be manually added to an
6293 @code{_LDADD} or @code{_LIBADD} variable by the user writing the
6296 Automake only looks at the file names listed in @file{_SOURCES}
6297 variables to choose the linker, and defaults to the C linker.
6298 Sometimes this is inconvenient because you are linking against a
6299 library written in another language and would like to set the linker
6300 more appropriately. @xref{Libtool Convenience Libraries}, for a
6301 trick with @code{nodist_EXTRA_@dots{}_SOURCES}.
6304 @node Fortran 9x Support
6305 @comment node-name, next, previous, up
6306 @section Fortran 9x Support
6308 @cindex Fortran 9x support
6309 @cindex Support for Fortran 9x
6311 Automake includes support for Fortran 9x.
6313 Any package including Fortran 9x code must define the output variable
6314 @code{FC} in @file{configure.ac}; the simplest way to do this is to use
6315 the @code{AC_PROG_FC} macro (@pxref{Particular Programs, , Particular
6316 Program Checks, autoconf, The Autoconf Manual}).
6318 A few additional variables are defined when a Fortran 9x source file is
6324 The name of the Fortran 9x compiler.
6327 Any flags to pass to the Fortran 9x compiler.
6330 The maintainer's variant of @code{FCFLAGS}.
6333 The command used to actually compile a Fortran 9x source file. The file
6334 name is appended to form the complete command line.
6337 The command used to actually link a pure Fortran 9x program or shared
6343 * Compiling Fortran 9x Files:: Compiling Fortran 9x sources
6346 @node Compiling Fortran 9x Files
6347 @comment node-name, next, previous, up
6348 @subsection Compiling Fortran 9x Files
6350 @file{@var{N}.o} is made automatically from @file{@var{N}.f90},
6351 @file{@var{N}.f95}, @file{@var{N}.f03}, or @file{@var{N}.f08}
6352 by running the Fortran 9x compiler. The precise command used
6358 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f90) $<}
6361 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f95) $<}
6364 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f03) $<}
6367 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f08) $<}
6372 @comment node-name, next, previous, up
6373 @section Java Support
6375 @cindex Java support
6376 @cindex Support for Java
6378 Automake includes support for compiled Java, using @command{gcj}, the Java
6379 front end to the GNU Compiler Collection.
6381 Any package including Java code to be compiled must define the output
6382 variable @code{GCJ} in @file{configure.ac}; the variable @code{GCJFLAGS}
6383 must also be defined somehow (either in @file{configure.ac} or
6384 @file{Makefile.am}). The simplest way to do this is to use the
6385 @code{AM_PROG_GCJ} macro.
6389 By default, programs including Java source files are linked with
6392 As always, the contents of @code{AM_GCJFLAGS} are passed to every
6393 compilation invoking @command{gcj} (in its role as an ahead-of-time
6394 compiler, when invoking it to create @file{.class} files,
6395 @code{AM_JAVACFLAGS} is used instead). If it is necessary to pass
6396 options to @command{gcj} from @file{Makefile.am}, this variable, and not
6397 the user variable @code{GCJFLAGS}, should be used.
6401 @command{gcj} can be used to compile @file{.java}, @file{.class},
6402 @file{.zip}, or @file{.jar} files.
6404 When linking, @command{gcj} requires that the main class be specified
6405 using the @option{--main=} option. The easiest way to do this is to use
6406 the @code{_LDFLAGS} variable for the program.
6409 @node Support for Other Languages
6410 @comment node-name, next, previous, up
6411 @section Support for Other Languages
6413 Automake currently only includes full support for C, C++ (@pxref{C++
6414 Support}), Objective C (@pxref{Objective C Support}), Fortran 77
6415 (@pxref{Fortran 77 Support}), Fortran 9x (@pxref{Fortran 9x Support}),
6416 and Java (@pxref{Java Support}). There is only rudimentary support for other
6417 languages, support for which will be improved based on user demand.
6419 Some limited support for adding your own languages is available via the
6420 suffix rule handling (@pxref{Suffixes}).
6424 @section Automatic de-ANSI-fication
6426 @cindex de-ANSI-fication, defined
6428 The features described in this section are obsolete; you should not
6429 used any of them in new code, and they may be withdrawn in future
6432 When the C language was standardized in 1989, there was a long
6433 transition period where package developers needed to worry about
6434 porting to older systems that did not support ANSI C by default.
6435 These older systems are no longer in practical use and are no longer
6436 supported by their original suppliers, so developers need not worry
6437 about this problem any more.
6439 Automake allows you to write packages that are portable to K&R C by
6440 @dfn{de-ANSI-fying} each source file before the actual compilation takes
6443 @vindex AUTOMAKE_OPTIONS
6446 If the @file{Makefile.am} variable @code{AUTOMAKE_OPTIONS}
6447 (@pxref{Options}) contains the option @option{ansi2knr} then code to
6448 handle de-ANSI-fication is inserted into the generated
6451 This causes each C source file in the directory to be treated as ANSI C@.
6452 If an ANSI C compiler is available, it is used. If no ANSI C compiler
6453 is available, the @command{ansi2knr} program is used to convert the source
6454 files into K&R C, which is then compiled.
6456 The @command{ansi2knr} program is simple-minded. It assumes the source
6457 code will be formatted in a particular way; see the @command{ansi2knr} man
6460 @acindex AM_C_PROTOTYPES
6461 Support for the obsolete de-ANSI-fication feature
6462 requires the source files @file{ansi2knr.c}
6463 and @file{ansi2knr.1} to be in the same package as the ANSI C source;
6464 these files are distributed with Automake. Also, the package
6465 @file{configure.ac} must call the macro @code{AM_C_PROTOTYPES}
6468 Automake also handles finding the @command{ansi2knr} support files in some
6469 other directory in the current package. This is done by prepending the
6470 relative path to the appropriate directory to the @command{ansi2knr}
6471 option. For instance, suppose the package has ANSI C code in the
6472 @file{src} and @file{lib} subdirectories. The files @file{ansi2knr.c} and
6473 @file{ansi2knr.1} appear in @file{lib}. Then this could appear in
6474 @file{src/Makefile.am}:
6477 AUTOMAKE_OPTIONS = ../lib/ansi2knr
6480 If no directory prefix is given, the files are assumed to be in the
6483 Note that automatic de-ANSI-fication will not work when the package is
6484 being built for a different host architecture. That is because automake
6485 currently has no way to build @command{ansi2knr} for the build machine.
6487 @c FIXME: this paragraph might be better moved to an `upgrading' section.
6488 @cindex @code{LTLIBOBJS} and @code{ansi2knr}
6489 @cindex @code{LIBOBJS} and @code{ansi2knr}
6490 @cindex @code{ansi2knr} and @code{LTLIBOBJS}
6491 @cindex @code{ansi2knr} and @code{LIBOBJS}
6492 Using @code{LIBOBJS} with source de-ANSI-fication used to require
6493 hand-crafted code in @file{configure} to append @samp{$U} to basenames
6494 in @code{LIBOBJS}. This is no longer true today. Starting with version
6495 2.54, Autoconf takes care of rewriting @code{LIBOBJS} and
6496 @code{LTLIBOBJS}. (@pxref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ}
6497 vs.@: @code{LIBOBJS}, autoconf, The Autoconf Manual})
6500 @section Automatic dependency tracking
6502 As a developer it is often painful to continually update the
6503 @file{Makefile.in} whenever the include-file dependencies change in a
6504 project. Automake supplies a way to automatically track dependency
6505 changes (@pxref{Dependency Tracking}).
6507 @cindex Dependency tracking
6508 @cindex Automatic dependency tracking
6510 Automake always uses complete dependencies for a compilation,
6511 including system headers. Automake's model is that dependency
6512 computation should be a side effect of the build. To this end,
6513 dependencies are computed by running all compilations through a
6514 special wrapper program called @command{depcomp}. @command{depcomp}
6515 understands how to coax many different C and C++ compilers into
6516 generating dependency information in the format it requires.
6517 @samp{automake -a} will install @command{depcomp} into your source
6518 tree for you. If @command{depcomp} can't figure out how to properly
6519 invoke your compiler, dependency tracking will simply be disabled for
6522 @cindex @command{depcomp}
6524 Experience with earlier versions of Automake (@pxref{Dependency
6525 Tracking Evolution}) taught us that it is not reliable to generate
6526 dependencies only on the maintainer's system, as configurations vary
6527 too much. So instead Automake implements dependency tracking at build
6530 Automatic dependency tracking can be suppressed by putting
6531 @option{no-dependencies} in the variable @code{AUTOMAKE_OPTIONS}, or
6532 passing @option{no-dependencies} as an argument to @code{AM_INIT_AUTOMAKE}
6533 (this should be the preferred way). Or, you can invoke @command{automake}
6534 with the @option{-i} option. Dependency tracking is enabled by default.
6536 @vindex AUTOMAKE_OPTIONS
6537 @opindex no-dependencies
6539 The person building your package also can choose to disable dependency
6540 tracking by configuring with @option{--disable-dependency-tracking}.
6542 @cindex Disabling dependency tracking
6543 @cindex Dependency tracking, disabling
6547 @section Support for executable extensions
6549 @cindex Executable extension
6550 @cindex Extension, executable
6553 On some platforms, such as Windows, executables are expected to have an
6554 extension such as @file{.exe}. On these platforms, some compilers (GCC
6555 among them) will automatically generate @file{foo.exe} when asked to
6556 generate @file{foo}.
6558 Automake provides mostly-transparent support for this. Unfortunately
6559 @emph{mostly} doesn't yet mean @emph{fully}. Until the English
6560 dictionary is revised, you will have to assist Automake if your package
6561 must support those platforms.
6563 One thing you must be aware of is that, internally, Automake rewrites
6564 something like this:
6567 bin_PROGRAMS = liver
6573 bin_PROGRAMS = liver$(EXEEXT)
6576 The targets Automake generates are likewise given the @samp{$(EXEEXT)}
6579 The variables @code{TESTS}, @code{XFAIL_TESTS} (@pxref{Tests}) are also
6580 rewritten if it contains filenames that have been declared as programs
6581 in the same @file{Makefile}. (This is mostly useful when some programs
6582 from @code{check_PROGRAMS} are listed in @code{TESTS}.)
6584 However, Automake cannot apply this rewriting to @command{configure}
6585 substitutions. This means that if you are conditionally building a
6586 program using such a substitution, then your @file{configure.ac} must
6587 take care to add @samp{$(EXEEXT)} when constructing the output variable.
6589 With Autoconf 2.13 and earlier, you must explicitly use @code{AC_EXEEXT}
6590 to get this support. With Autoconf 2.50, @code{AC_EXEEXT} is run
6591 automatically if you configure a compiler (say, through
6594 Sometimes maintainers like to write an explicit link rule for their
6595 program. Without executable extension support, this is easy---you
6596 simply write a rule whose target is the name of the program. However,
6597 when executable extension support is enabled, you must instead add the
6598 @samp{$(EXEEXT)} suffix.
6600 Unfortunately, due to the change in Autoconf 2.50, this means you must
6601 always add this extension. However, this is a problem for maintainers
6602 who know their package will never run on a platform that has
6603 executable extensions. For those maintainers, the @option{no-exeext}
6604 option (@pxref{Options}) will disable this feature. This works in a
6605 fairly ugly way; if @option{no-exeext} is seen, then the presence of a
6606 rule for a target named @code{foo} in @file{Makefile.am} will override
6607 an automake-generated rule for @samp{foo$(EXEEXT)}. Without
6608 the @option{no-exeext} option, this use will give a diagnostic.
6612 @chapter Other Derived Objects
6614 Automake can handle derived objects that are not C programs. Sometimes
6615 the support for actually building such objects must be explicitly
6616 supplied, but Automake will still automatically handle installation and
6620 * Scripts:: Executable scripts
6621 * Headers:: Header files
6622 * Data:: Architecture-independent data files
6623 * Sources:: Derived sources
6628 @section Executable Scripts
6630 @cindex @code{_SCRIPTS} primary, defined
6631 @cindex @code{SCRIPTS} primary, defined
6632 @cindex Primary variable, @code{SCRIPTS}
6634 @cindex Installing scripts
6636 It is possible to define and install programs that are scripts. Such
6637 programs are listed using the @code{SCRIPTS} primary name. When the
6638 script is distributed in its final, installable form, the
6639 @file{Makefile} usually looks as follows:
6643 # Install my_script in $(bindir) and distribute it.
6644 dist_bin_SCRIPTS = my_script
6647 Script are not distributed by default; as we have just seen, those
6648 that should be distributed can be specified using a @code{dist_}
6649 prefix as with other primaries.
6651 @cindex @code{SCRIPTS}, installation directories
6653 @vindex sbin_SCRIPTS
6654 @vindex libexec_SCRIPTS
6655 @vindex pkgdata_SCRIPTS
6656 @vindex noinst_SCRIPTS
6657 @vindex check_SCRIPTS
6659 Scripts can be installed in @code{bindir}, @code{sbindir},
6660 @code{libexecdir}, or @code{pkgdatadir}.
6662 Scripts that need not being installed can be listed in
6663 @code{noinst_SCRIPTS}, and among them, those which are needed only by
6664 @samp{make check} should go in @code{check_SCRIPTS}.
6666 When a script needs to be built, the @file{Makefile.am} should include
6667 the appropriate rules. For instance the @command{automake} program
6668 itself is a Perl script that is generated from @file{automake.in}.
6669 Here is how this is handled:
6672 bin_SCRIPTS = automake
6673 CLEANFILES = $(bin_SCRIPTS)
6674 EXTRA_DIST = automake.in
6676 do_subst = sed -e 's,[@@]datadir[@@],$(datadir),g' \
6677 -e 's,[@@]PERL[@@],$(PERL),g' \
6678 -e 's,[@@]PACKAGE[@@],$(PACKAGE),g' \
6679 -e 's,[@@]VERSION[@@],$(VERSION),g' \
6682 automake: automake.in Makefile
6683 $(do_subst) < $(srcdir)/automake.in > automake
6687 Such scripts for which a build rule has been supplied need to be
6688 deleted explicitly using @code{CLEANFILES} (@pxref{Clean}), and their
6689 sources have to be distributed, usually with @code{EXTRA_DIST}
6692 Another common way to build scripts is to process them from
6693 @file{configure} with @code{AC_CONFIG_FILES}. In this situation
6694 Automake knows which files should be cleaned and distributed, and what
6695 the rebuild rules should look like.
6697 For instance if @file{configure.ac} contains
6700 AC_CONFIG_FILES([src/my_script], [chmod +x src/my_script])
6704 to build @file{src/my_script} from @file{src/my_script.in}, then an
6705 @file{src/Makefile.am} to install this script in @code{$(bindir)} can
6709 bin_SCRIPTS = my_script
6710 CLEANFILES = $(bin_SCRIPTS)
6714 There is no need for @code{EXTRA_DIST} or any build rule: Automake
6715 infers them from @code{AC_CONFIG_FILES} (@pxref{Requirements}).
6716 @code{CLEANFILES} is still useful, because by default Automake will
6717 clean targets of @code{AC_CONFIG_FILES} in @code{distclean}, not
6720 Although this looks simpler, building scripts this way has one
6721 drawback: directory variables such as @code{$(datadir)} are not fully
6722 expanded and may refer to other directory variables.
6725 @section Header files
6727 @cindex @code{_HEADERS} primary, defined
6728 @cindex @code{HEADERS} primary, defined
6729 @cindex Primary variable, @code{HEADERS}
6731 @vindex noinst_HEADERS
6732 @cindex @code{HEADERS}, installation directories
6733 @cindex Installing headers
6734 @vindex include_HEADERS
6735 @vindex oldinclude_HEADERS
6736 @vindex pkginclude_HEADERS
6739 Header files that must be installed are specified by the
6740 @code{HEADERS} family of variables. Headers can be installed in
6741 @code{includedir}, @code{oldincludedir}, @code{pkgincludedir} or any
6742 other directory you may have defined (@pxref{Uniform}). For instance,
6745 include_HEADERS = foo.h bar/bar.h
6749 will install the two files as @file{$(includedir)/foo.h} and
6750 @file{$(includedir)/bar.h}.
6752 The @code{nobase_} prefix is also supported,
6755 nobase_include_HEADERS = foo.h bar/bar.h
6759 will install the two files as @file{$(includedir)/foo.h} and
6760 @file{$(includedir)/bar/bar.h} (@pxref{Alternative}).
6762 @vindex noinst_HEADERS
6763 Usually, only header files that accompany installed libraries need to
6764 be installed. Headers used by programs or convenience libraries are
6765 not installed. The @code{noinst_HEADERS} variable can be used for
6766 such headers. However when the header actually belongs to one
6767 convenient library or program, we recommend listing it in the
6768 program's or library's @code{_SOURCES} variable (@pxref{Program
6769 Sources}) instead of in @code{noinst_HEADERS}. This is clearer for
6770 the @file{Makefile.am} reader. @code{noinst_HEADERS} would be the
6771 right variable to use in a directory containing only headers and no
6772 associated library or program.
6774 All header files must be listed somewhere; in a @code{_SOURCES}
6775 variable or in a @code{_HEADERS} variable. Missing ones will not
6776 appear in the distribution.
6778 For header files that are built and must not be distributed, use the
6779 @code{nodist_} prefix as in @code{nodist_include_HEADERS} or
6780 @code{nodist_prog_SOURCES}. If these generated headers are needed
6781 during the build, you must also ensure they exist before they are
6782 used (@pxref{Sources}).
6786 @section Architecture-independent data files
6788 @cindex @code{_DATA} primary, defined
6789 @cindex @code{DATA} primary, defined
6790 @cindex Primary variable, @code{DATA}
6793 Automake supports the installation of miscellaneous data files using the
6794 @code{DATA} family of variables.
6798 @vindex sysconf_DATA
6799 @vindex sharedstate_DATA
6800 @vindex localstate_DATA
6801 @vindex pkgdata_DATA
6803 Such data can be installed in the directories @code{datadir},
6804 @code{sysconfdir}, @code{sharedstatedir}, @code{localstatedir}, or
6807 By default, data files are @emph{not} included in a distribution. Of
6808 course, you can use the @code{dist_} prefix to change this on a
6811 Here is how Automake declares its auxiliary data files:
6814 dist_pkgdata_DATA = clean-kr.am clean.am @dots{}
6819 @section Built sources
6821 Because Automake's automatic dependency tracking works as a side-effect
6822 of compilation (@pxref{Dependencies}) there is a bootstrap issue: a
6823 target should not be compiled before its dependencies are made, but
6824 these dependencies are unknown until the target is first compiled.
6826 Ordinarily this is not a problem, because dependencies are distributed
6827 sources: they preexist and do not need to be built. Suppose that
6828 @file{foo.c} includes @file{foo.h}. When it first compiles
6829 @file{foo.o}, @command{make} only knows that @file{foo.o} depends on
6830 @file{foo.c}. As a side-effect of this compilation @command{depcomp}
6831 records the @file{foo.h} dependency so that following invocations of
6832 @command{make} will honor it. In these conditions, it's clear there is
6833 no problem: either @file{foo.o} doesn't exist and has to be built
6834 (regardless of the dependencies), or accurate dependencies exist and
6835 they can be used to decide whether @file{foo.o} should be rebuilt.
6837 It's a different story if @file{foo.h} doesn't exist by the first
6838 @command{make} run. For instance, there might be a rule to build
6839 @file{foo.h}. This time @file{file.o}'s build will fail because the
6840 compiler can't find @file{foo.h}. @command{make} failed to trigger the
6841 rule to build @file{foo.h} first by lack of dependency information.
6843 @vindex BUILT_SOURCES
6844 @cindex @code{BUILT_SOURCES}, defined
6846 The @code{BUILT_SOURCES} variable is a workaround for this problem. A
6847 source file listed in @code{BUILT_SOURCES} is made on @samp{make all}
6848 or @samp{make check} (or even @samp{make install}) before other
6849 targets are processed. However, such a source file is not
6850 @emph{compiled} unless explicitly requested by mentioning it in some
6851 other @code{_SOURCES} variable.
6853 So, to conclude our introductory example, we could use
6854 @samp{BUILT_SOURCES = foo.h} to ensure @file{foo.h} gets built before
6855 any other target (including @file{foo.o}) during @samp{make all} or
6858 @code{BUILT_SOURCES} is actually a bit of a misnomer, as any file which
6859 must be created early in the build process can be listed in this
6860 variable. Moreover, all built sources do not necessarily have to be
6861 listed in @code{BUILT_SOURCES}. For instance, a generated @file{.c} file
6862 doesn't need to appear in @code{BUILT_SOURCES} (unless it is included by
6863 another source), because it's a known dependency of the associated
6866 It might be important to emphasize that @code{BUILT_SOURCES} is
6867 honored only by @samp{make all}, @samp{make check} and @samp{make
6868 install}. This means you cannot build a specific target (e.g.,
6869 @samp{make foo}) in a clean tree if it depends on a built source.
6870 However it will succeed if you have run @samp{make all} earlier,
6871 because accurate dependencies are already available.
6873 The next section illustrates and discusses the handling of built sources
6877 * Built sources example:: Several ways to handle built sources.
6880 @node Built sources example
6881 @subsection Built sources example
6883 Suppose that @file{foo.c} includes @file{bindir.h}, which is
6884 installation-dependent and not distributed: it needs to be built. Here
6885 @file{bindir.h} defines the preprocessor macro @code{bindir} to the
6886 value of the @command{make} variable @code{bindir} (inherited from
6889 We suggest several implementations below. It's not meant to be an
6890 exhaustive listing of all ways to handle built sources, but it will give
6891 you a few ideas if you encounter this issue.
6893 @unnumberedsubsec First try
6895 This first implementation will illustrate the bootstrap issue mentioned
6896 in the previous section (@pxref{Sources}).
6898 Here is a tentative @file{Makefile.am}.
6904 nodist_foo_SOURCES = bindir.h
6905 CLEANFILES = bindir.h
6907 echo '#define bindir "$(bindir)"' >$@@
6910 This setup doesn't work, because Automake doesn't know that @file{foo.c}
6911 includes @file{bindir.h}. Remember, automatic dependency tracking works
6912 as a side-effect of compilation, so the dependencies of @file{foo.o} will
6913 be known only after @file{foo.o} has been compiled (@pxref{Dependencies}).
6914 The symptom is as follows.
6918 source='foo.c' object='foo.o' libtool=no \
6919 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
6920 depmode=gcc /bin/sh ./depcomp \
6921 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
6922 foo.c:2: bindir.h: No such file or directory
6923 make: *** [foo.o] Error 1
6926 In this example @file{bindir.h} is not distributed nor installed, and
6927 it is not even being built on-time. One may wonder if the
6928 @samp{nodist_foo_SOURCES = bindir.h} line has any use at all. This
6929 line simply states that @file{bindir.h} is a source of @code{foo}, so
6930 for instance, it should be inspected while generating tags
6931 (@pxref{Tags}). In other words, it does not help our present problem,
6932 and the build would fail identically without it.
6934 @unnumberedsubsec Using @code{BUILT_SOURCES}
6936 A solution is to require @file{bindir.h} to be built before anything
6937 else. This is what @code{BUILT_SOURCES} is meant for (@pxref{Sources}).
6942 nodist_foo_SOURCES = bindir.h
6943 BUILT_SOURCES = bindir.h
6944 CLEANFILES = bindir.h
6946 echo '#define bindir "$(bindir)"' >$@@
6949 See how @file{bindir.h} get built first:
6953 echo '#define bindir "/usr/local/bin"' >bindir.h
6955 make[1]: Entering directory `/home/adl/tmp'
6956 source='foo.c' object='foo.o' libtool=no \
6957 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
6958 depmode=gcc /bin/sh ./depcomp \
6959 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
6960 gcc -g -O2 -o foo foo.o
6961 make[1]: Leaving directory `/home/adl/tmp'
6964 However, as said earlier, @code{BUILT_SOURCES} applies only to the
6965 @code{all}, @code{check}, and @code{install} targets. It still fails
6966 if you try to run @samp{make foo} explicitly:
6970 test -z "bindir.h" || rm -f bindir.h
6971 test -z "foo" || rm -f foo
6973 % : > .deps/foo.Po # Suppress previously recorded dependencies
6975 source='foo.c' object='foo.o' libtool=no \
6976 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
6977 depmode=gcc /bin/sh ./depcomp \
6978 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
6979 foo.c:2: bindir.h: No such file or directory
6980 make: *** [foo.o] Error 1
6983 @unnumberedsubsec Recording dependencies manually
6985 Usually people are happy enough with @code{BUILT_SOURCES} because they
6986 never build targets such as @samp{make foo} before @samp{make all}, as
6987 in the previous example. However if this matters to you, you can
6988 avoid @code{BUILT_SOURCES} and record such dependencies explicitly in
6989 the @file{Makefile.am}.
6994 nodist_foo_SOURCES = bindir.h
6995 foo.$(OBJEXT): bindir.h
6996 CLEANFILES = bindir.h
6998 echo '#define bindir "$(bindir)"' >$@@
7001 You don't have to list @emph{all} the dependencies of @file{foo.o}
7002 explicitly, only those that might need to be built. If a dependency
7003 already exists, it will not hinder the first compilation and will be
7004 recorded by the normal dependency tracking code. (Note that after
7005 this first compilation the dependency tracking code will also have
7006 recorded the dependency between @file{foo.o} and
7007 @file{bindir.h}; so our explicit dependency is really useful to
7008 the first build only.)
7010 Adding explicit dependencies like this can be a bit dangerous if you are
7011 not careful enough. This is due to the way Automake tries not to
7012 overwrite your rules (it assumes you know better than it).
7013 @samp{foo.$(OBJEXT): bindir.h} supersedes any rule Automake may want to
7014 output to build @samp{foo.$(OBJEXT)}. It happens to work in this case
7015 because Automake doesn't have to output any @samp{foo.$(OBJEXT):}
7016 target: it relies on a suffix rule instead (i.e., @samp{.c.$(OBJEXT):}).
7017 Always check the generated @file{Makefile.in} if you do this.
7019 @unnumberedsubsec Build @file{bindir.h} from @file{configure}
7021 It's possible to define this preprocessor macro from @file{configure},
7022 either in @file{config.h} (@pxref{Defining Directories, , Defining
7023 Directories, autoconf, The Autoconf Manual}), or by processing a
7024 @file{bindir.h.in} file using @code{AC_CONFIG_FILES}
7025 (@pxref{Configuration Actions, ,Configuration Actions, autoconf, The
7028 At this point it should be clear that building @file{bindir.h} from
7029 @file{configure} work well for this example. @file{bindir.h} will exist
7030 before you build any target, hence will not cause any dependency issue.
7032 The Makefile can be shrunk as follows. We do not even have to mention
7040 However, it's not always possible to build sources from
7041 @file{configure}, especially when these sources are generated by a tool
7042 that needs to be built first...
7044 @unnumberedsubsec Build @file{bindir.c}, not @file{bindir.h}.
7046 Another attractive idea is to define @code{bindir} as a variable or
7047 function exported from @file{bindir.o}, and build @file{bindir.c}
7048 instead of @file{bindir.h}.
7051 noinst_PROGRAMS = foo
7052 foo_SOURCES = foo.c bindir.h
7053 nodist_foo_SOURCES = bindir.c
7054 CLEANFILES = bindir.c
7056 echo 'const char bindir[] = "$(bindir)";' >$@@
7059 @file{bindir.h} contains just the variable's declaration and doesn't
7060 need to be built, so it won't cause any trouble. @file{bindir.o} is
7061 always dependent on @file{bindir.c}, so @file{bindir.c} will get built
7064 @unnumberedsubsec Which is best?
7066 There is no panacea, of course. Each solution has its merits and
7069 You cannot use @code{BUILT_SOURCES} if the ability to run @samp{make
7070 foo} on a clean tree is important to you.
7072 You won't add explicit dependencies if you are leery of overriding
7073 an Automake rule by mistake.
7075 Building files from @file{./configure} is not always possible, neither
7076 is converting @file{.h} files into @file{.c} files.
7079 @node Other GNU Tools
7080 @chapter Other GNU Tools
7082 Since Automake is primarily intended to generate @file{Makefile.in}s for
7083 use in GNU programs, it tries hard to interoperate with other GNU tools.
7086 * Emacs Lisp:: Emacs Lisp
7097 @cindex @code{_LISP} primary, defined
7098 @cindex @code{LISP} primary, defined
7099 @cindex Primary variable, @code{LISP}
7105 Automake provides some support for Emacs Lisp. The @code{LISP} primary
7106 is used to hold a list of @file{.el} files. Possible prefixes for this
7107 primary are @code{lisp_} and @code{noinst_}. Note that if
7108 @code{lisp_LISP} is defined, then @file{configure.ac} must run
7109 @code{AM_PATH_LISPDIR} (@pxref{Macros}).
7111 @vindex dist_lisp_LISP
7112 @vindex dist_noinst_LISP
7113 Lisp sources are not distributed by default. You can prefix the
7114 @code{LISP} primary with @code{dist_}, as in @code{dist_lisp_LISP} or
7115 @code{dist_noinst_LISP}, to indicate that these files should be
7118 Automake will byte-compile all Emacs Lisp source files using the Emacs
7119 found by @code{AM_PATH_LISPDIR}, if any was found.
7121 Byte-compiled Emacs Lisp files are not portable among all versions of
7122 Emacs, so it makes sense to turn this off if you expect sites to have
7123 more than one version of Emacs installed. Furthermore, many packages
7124 don't actually benefit from byte-compilation. Still, we recommend
7125 that you byte-compile your Emacs Lisp sources. It is probably better
7126 for sites with strange setups to cope for themselves than to make the
7127 installation less nice for everybody else.
7129 There are two ways to avoid byte-compiling. Historically, we have
7130 recommended the following construct.
7132 lisp_LISP = file1.el file2.el
7136 @code{ELCFILES} is an internal Automake variable that normally lists
7137 all @file{.elc} files that must be byte-compiled. Automake defines
7138 @code{ELCFILES} automatically from @code{lisp_LISP}. Emptying this
7139 variable explicitly prevents byte-compilation to occur.
7141 Since Automake 1.8, we now recommend using @code{lisp_DATA} instead. As
7144 lisp_DATA = file1.el file2.el
7147 Note that these two constructs are not equivalent. @code{_LISP} will
7148 not install a file if Emacs is not installed, while @code{_DATA} will
7149 always install its files.
7154 @cindex GNU Gettext support
7155 @cindex Gettext support
7156 @cindex Support for GNU Gettext
7158 If @code{AM_GNU_GETTEXT} is seen in @file{configure.ac}, then Automake
7159 turns on support for GNU gettext, a message catalog system for
7160 internationalization
7161 (@pxref{Top, , Introduction, gettext, GNU gettext utilities}).
7163 The @code{gettext} support in Automake requires the addition of one or
7164 two subdirectories to the package, @file{po} and possibly also @file{intl}.
7165 The latter is needed if @code{AM_GNU_GETTEXT} is not invoked with the
7166 @samp{external} argument, or if @code{AM_GNU_GETTEXT_INTL_SUBDIR} is used.
7167 Automake ensures that these directories exist and are mentioned in
7173 Automake provides support for GNU Libtool (@pxref{Top, , Introduction,
7174 libtool, The Libtool Manual}) with the @code{LTLIBRARIES} primary.
7175 @xref{A Shared Library}.
7181 @cindex @code{_JAVA} primary, defined
7182 @cindex @code{JAVA} primary, defined
7183 @cindex Primary variable, @code{JAVA}
7185 Automake provides some minimal support for Java compilation with the
7186 @code{JAVA} primary.
7188 Any @file{.java} files listed in a @code{_JAVA} variable will be
7189 compiled with @code{JAVAC} at build time. By default, @file{.java}
7190 files are not included in the distribution, you should use the
7191 @code{dist_} prefix to distribute them.
7193 Here is a typical setup for distributing @file{.java} files and
7194 installing the @file{.class} files resulting from their compilation.
7197 javadir = $(datadir)/java
7198 dist_java_JAVA = a.java b.java @dots{}
7201 @cindex @code{JAVA} restrictions
7202 @cindex Restrictions for @code{JAVA}
7204 Currently Automake enforces the restriction that only one @code{_JAVA}
7205 primary can be used in a given @file{Makefile.am}. The reason for this
7206 restriction is that, in general, it isn't possible to know which
7207 @file{.class} files were generated from which @file{.java} files, so
7208 it would be impossible to know which files to install where. For
7209 instance, a @file{.java} file can define multiple classes; the resulting
7210 @file{.class} file names cannot be predicted without parsing the
7213 There are a few variables that are used when compiling Java sources:
7217 The name of the Java compiler. This defaults to @samp{javac}.
7220 The flags to pass to the compiler. This is considered to be a user
7221 variable (@pxref{User Variables}).
7224 More flags to pass to the Java compiler. This, and not
7225 @code{JAVACFLAGS}, should be used when it is necessary to put Java
7226 compiler flags into @file{Makefile.am}.
7229 The value of this variable is passed to the @option{-d} option to
7230 @code{javac}. It defaults to @samp{$(top_builddir)}.
7233 This variable is an @code{sh} expression that is used to set the
7234 @env{CLASSPATH} environment variable on the @code{javac} command line.
7235 (In the future we will probably handle class path setting differently.)
7242 @cindex @code{_PYTHON} primary, defined
7243 @cindex @code{PYTHON} primary, defined
7244 @cindex Primary variable, @code{PYTHON}
7247 Automake provides support for Python compilation with the
7248 @code{PYTHON} primary. A typical setup is to call
7249 @code{AM_PATH_PYTHON} in @file{configure.ac} and use a line like the
7250 following in @file{Makefile.am}:
7253 python_PYTHON = tree.py leave.py
7256 Any files listed in a @code{_PYTHON} variable will be byte-compiled
7257 with @command{py-compile} at install time. @command{py-compile}
7258 actually creates both standard (@file{.pyc}) and optimized
7259 (@file{.pyo}) byte-compiled versions of the source files. Note that
7260 because byte-compilation occurs at install time, any files listed in
7261 @code{noinst_PYTHON} will not be compiled. Python source files are
7262 included in the distribution by default, prepend @code{nodist_} (as in
7263 @code{nodist_python_PYTHON}) to omit them.
7265 Automake ships with an Autoconf macro called @code{AM_PATH_PYTHON}
7266 that will determine some Python-related directory variables (see
7267 below). If you have called @code{AM_PATH_PYTHON} from
7268 @file{configure.ac}, then you may use the variables
7269 @code{python_PYTHON} or @code{pkgpython_PYTHON} to list Python source
7270 files in your @file{Makefile.am}, depending where you want your files
7271 installed (see the definitions of @code{pythondir} and
7272 @code{pkgpythondir} below).
7274 @defmac AM_PATH_PYTHON ([@var{VERSION}], [@var{ACTION-IF-FOUND}], [@var{ACTION-IF-NOT-FOUND}])
7276 Search for a Python interpreter on the system. This macro takes three
7277 optional arguments. The first argument, if present, is the minimum
7278 version of Python required for this package: @code{AM_PATH_PYTHON}
7279 will skip any Python interpreter that is older than @var{VERSION}.
7280 If an interpreter is found and satisfies @var{VERSION}, then
7281 @var{ACTION-IF-FOUND} is run. Otherwise, @var{ACTION-IF-NOT-FOUND} is
7284 If @var{ACTION-IF-NOT-FOUND} is not specified, as in the following
7285 example, the default is to abort @command{configure}.
7288 AM_PATH_PYTHON([2.2])
7292 This is fine when Python is an absolute requirement for the package.
7293 If Python >= 2.2 was only @emph{optional} to the package,
7294 @code{AM_PATH_PYTHON} could be called as follows.
7297 AM_PATH_PYTHON([2.2],, [:])
7300 @code{AM_PATH_PYTHON} creates the following output variables based on
7301 the Python installation found during configuration.
7306 The name of the Python executable, or @samp{:} if no suitable
7307 interpreter could be found.
7309 Assuming @var{ACTION-IF-NOT-FOUND} is used (otherwise @file{./configure}
7310 will abort if Python is absent), the value of @code{PYTHON} can be used
7311 to setup a conditional in order to disable the relevant part of a build
7315 AM_PATH_PYTHON(,, [:])
7316 AM_CONDITIONAL([HAVE_PYTHON], [test "$PYTHON" != :])
7319 @item PYTHON_VERSION
7320 The Python version number, in the form @var{major}.@var{minor}
7321 (e.g., @samp{1.5}). This is currently the value of
7322 @samp{sys.version[:3]}.
7325 The string @samp{$@{prefix@}}. This term may be used in future work
7326 that needs the contents of Python's @samp{sys.prefix}, but general
7327 consensus is to always use the value from configure.
7329 @item PYTHON_EXEC_PREFIX
7330 The string @samp{$@{exec_prefix@}}. This term may be used in future work
7331 that needs the contents of Python's @samp{sys.exec_prefix}, but general
7332 consensus is to always use the value from configure.
7334 @item PYTHON_PLATFORM
7335 The canonical name used by Python to describe the operating system, as
7336 given by @samp{sys.platform}. This value is sometimes needed when
7337 building Python extensions.
7340 The directory name for the @file{site-packages} subdirectory of the
7341 standard Python install tree.
7344 This is the directory under @code{pythondir} that is named after the
7345 package. That is, it is @samp{$(pythondir)/$(PACKAGE)}. It is provided
7349 This is the directory where Python extension modules (shared libraries)
7350 should be installed. An extension module written in C could be declared
7351 as follows to Automake:
7354 pyexec_LTLIBRARIES = quaternion.la
7355 quaternion_SOURCES = quaternion.c support.c support.h
7356 quaternion_la_LDFLAGS = -avoid-version -module
7360 This is a convenience variable that is defined as
7361 @samp{$(pyexecdir)/$(PACKAGE)}.
7364 All these directory variables have values that start with either
7365 @samp{$@{prefix@}} or @samp{$@{exec_prefix@}} unexpanded. This works
7366 fine in @file{Makefiles}, but it makes these variables hard to use in
7367 @file{configure}. This is mandated by the GNU coding standards, so
7368 that the user can run @samp{make prefix=/foo install}. The Autoconf
7369 manual has a section with more details on this topic
7370 (@pxref{Installation Directory Variables, , Installation Directory
7371 Variables, autoconf, The Autoconf Manual}). See also @ref{Hard-Coded
7376 @chapter Building documentation
7378 Currently Automake provides support for Texinfo and man pages.
7382 * Man pages:: Man pages
7389 @cindex @code{_TEXINFOS} primary, defined
7390 @cindex @code{TEXINFOS} primary, defined
7391 @cindex Primary variable, @code{TEXINFOS}
7392 @cindex HTML output using Texinfo
7393 @cindex PDF output using Texinfo
7394 @cindex PS output using Texinfo
7395 @cindex DVI output using Texinfo
7397 @vindex info_TEXINFOS
7399 If the current directory contains Texinfo source, you must declare it
7400 with the @code{TEXINFOS} primary. Generally Texinfo files are converted
7401 into info, and thus the @code{info_TEXINFOS} variable is most commonly used
7402 here. Any Texinfo source file must end in the @file{.texi},
7403 @file{.txi}, or @file{.texinfo} extension. We recommend @file{.texi}
7406 Automake generates rules to build @file{.info}, @file{.dvi},
7407 @file{.ps}, @file{.pdf} and @file{.html} files from your Texinfo
7408 sources. Following the GNU Coding Standards, only the @file{.info}
7409 files are built by @samp{make all} and installed by @samp{make
7410 install} (unless you use @option{no-installinfo}, see below).
7411 Furthermore, @file{.info} files are automatically distributed so that
7412 Texinfo is not a prerequisite for installing your package.
7418 @trindex install-dvi
7419 @trindex install-html
7420 @trindex install-pdf
7422 Other documentation formats can be built on request by @samp{make
7423 dvi}, @samp{make ps}, @samp{make pdf} and @samp{make html}, and they
7424 can be installed with @samp{make install-dvi}, @samp{make install-ps},
7425 @samp{make install-pdf} and @samp{make install-html} explicitly.
7426 @samp{make uninstall} will remove everything: the Texinfo
7427 documentation installed by default as well as all the above optional
7430 All these targets can be extended using @samp{-local} rules
7431 (@pxref{Extending}).
7433 @cindex Texinfo flag, @code{VERSION}
7434 @cindex Texinfo flag, @code{UPDATED}
7435 @cindex Texinfo flag, @code{EDITION}
7436 @cindex Texinfo flag, @code{UPDATED-MONTH}
7438 @cindex @code{VERSION} Texinfo flag
7439 @cindex @code{UPDATED} Texinfo flag
7440 @cindex @code{EDITION} Texinfo flag
7441 @cindex @code{UPDATED-MONTH} Texinfo flag
7443 @cindex @file{mdate-sh}
7445 If the @file{.texi} file @code{@@include}s @file{version.texi}, then
7446 that file will be automatically generated. The file @file{version.texi}
7447 defines four Texinfo flag you can reference using
7448 @code{@@value@{EDITION@}}, @code{@@value@{VERSION@}},
7449 @code{@@value@{UPDATED@}}, and @code{@@value@{UPDATED-MONTH@}}.
7454 Both of these flags hold the version number of your program. They are
7455 kept separate for clarity.
7458 This holds the date the primary @file{.texi} file was last modified.
7461 This holds the name of the month in which the primary @file{.texi} file
7465 The @file{version.texi} support requires the @command{mdate-sh}
7466 script; this script is supplied with Automake and automatically
7467 included when @command{automake} is invoked with the
7468 @option{--add-missing} option.
7470 If you have multiple Texinfo files, and you want to use the
7471 @file{version.texi} feature, then you have to have a separate version
7472 file for each Texinfo file. Automake will treat any include in a
7473 Texinfo file that matches @file{vers*.texi} just as an automatically
7474 generated version file.
7476 Sometimes an info file actually depends on more than one @file{.texi}
7477 file. For instance, in GNU Hello, @file{hello.texi} includes the file
7478 @file{gpl.texi}. You can tell Automake about these dependencies using
7479 the @code{@var{texi}_TEXINFOS} variable. Here is how GNU Hello does it:
7484 info_TEXINFOS = hello.texi
7485 hello_TEXINFOS = gpl.texi
7488 @cindex @file{texinfo.tex}
7490 By default, Automake requires the file @file{texinfo.tex} to appear in
7491 the same directory as the @file{Makefile.am} file that lists the
7492 @file{.texi} files. If you used @code{AC_CONFIG_AUX_DIR} in
7493 @file{configure.ac} (@pxref{Input, , Finding `configure' Input,
7494 autoconf, The Autoconf Manual}), then @file{texinfo.tex} is looked for
7495 there. In both cases, automake then supplies @file{texinfo.tex} if
7496 @option{--add-missing} is given, and takes care of its distribution.
7497 However, if you set the @code{TEXINFO_TEX} variable (see below),
7498 it overrides the location of the file and turns off its installation
7499 into the source as well as its distribution.
7501 The option @option{no-texinfo.tex} can be used to eliminate the
7502 requirement for the file @file{texinfo.tex}. Use of the variable
7503 @code{TEXINFO_TEX} is preferable, however, because that allows the
7504 @code{dvi}, @code{ps}, and @code{pdf} targets to still work.
7506 @cindex Option, @code{no-installinfo}
7507 @cindex Target, @code{install-info}
7508 @cindex @code{install-info} target
7509 @cindex @code{no-installinfo} option
7511 @opindex no-installinfo
7512 @trindex install-info
7514 Automake generates an @code{install-info} rule; some people apparently
7515 use this. By default, info pages are installed by @samp{make
7516 install}, so running @code{make install-info} is pointless. This can
7517 be prevented via the @code{no-installinfo} option. In this case,
7518 @file{.info} files are not installed by default, and user must
7519 request this explicitly using @samp{make install-info}
7521 The following variables are used by the Texinfo build rules.
7525 The name of the program invoked to build @file{.info} files. This
7526 variable is defined by Automake. If the @command{makeinfo} program is
7527 found on the system then it will be used by default; otherwise
7528 @command{missing} will be used instead.
7531 The command invoked to build @file{.html} files. Automake
7532 defines this to @samp{$(MAKEINFO) --html}.
7535 User flags passed to each invocation of @samp{$(MAKEINFO)} and
7536 @samp{$(MAKEINFOHTML)}. This user variable (@pxref{User Variables}) is
7537 not expected to be defined in any @file{Makefile}; it can be used by
7538 users to pass extra flags to suit their needs.
7540 @item AM_MAKEINFOFLAGS
7541 @itemx AM_MAKEINFOHTMLFLAGS
7542 Maintainer flags passed to each @command{makeinfo} invocation. Unlike
7543 @code{MAKEINFOFLAGS}, these variables are meant to be defined by
7544 maintainers in @file{Makefile.am}. @samp{$(AM_MAKEINFOFLAGS)} is
7545 passed to @code{makeinfo} when building @file{.info} files; and
7546 @samp{$(AM_MAKEINFOHTMLFLAGS)} is used when building @file{.html}
7549 For instance, the following setting can be used to obtain one single
7550 @file{.html} file per manual, without node separators.
7552 AM_MAKEINFOHTMLFLAGS = --no-headers --no-split
7555 @code{AM_MAKEINFOHTMLFLAGS} defaults to @samp{$(AM_MAKEINFOFLAGS)}.
7556 This means that defining @code{AM_MAKEINFOFLAGS} without defining
7557 @code{AM_MAKEINFOHTMLFLAGS} will impact builds of both @file{.info}
7558 and @file{.html} files.
7561 The name of the command that converts a @file{.texi} file into a
7562 @file{.dvi} file. This defaults to @samp{texi2dvi}, a script that ships
7563 with the Texinfo package.
7566 The name of the command that translates a @file{.texi} file into a
7567 @file{.pdf} file. This defaults to @samp{$(TEXI2DVI) --pdf --batch}.
7570 The name of the command that build a @file{.ps} file out of a
7571 @file{.dvi} file. This defaults to @samp{dvips}.
7575 If your package has Texinfo files in many directories, you can use the
7576 variable @code{TEXINFO_TEX} to tell Automake where to find the canonical
7577 @file{texinfo.tex} for your package. The value of this variable should
7578 be the relative path from the current @file{Makefile.am} to
7582 TEXINFO_TEX = ../doc/texinfo.tex
7590 @cindex @code{_MANS} primary, defined
7591 @cindex @code{MANS} primary, defined
7592 @cindex Primary variable, @code{MANS}
7596 A package can also include man pages (but see the GNU standards on this
7597 matter, @ref{Man Pages, , , standards, The GNU Coding Standards}.) Man
7598 pages are declared using the @code{MANS} primary. Generally the
7599 @code{man_MANS} variable is used. Man pages are automatically installed in
7600 the correct subdirectory of @code{mandir}, based on the file extension.
7602 File extensions such as @file{.1c} are handled by looking for the valid
7603 part of the extension and using that to determine the correct
7604 subdirectory of @code{mandir}. Valid section names are the digits
7605 @samp{0} through @samp{9}, and the letters @samp{l} and @samp{n}.
7607 Sometimes developers prefer to name a man page something like
7608 @file{foo.man} in the source, and then rename it to have the correct
7609 suffix, for example @file{foo.1}, when installing the file. Automake
7610 also supports this mode. For a valid section named @var{SECTION},
7611 there is a corresponding directory named @samp{man@var{SECTION}dir},
7612 and a corresponding @code{_MANS} variable. Files listed in such a
7613 variable are installed in the indicated section. If the file already
7614 has a valid suffix, then it is installed as-is; otherwise the file
7615 suffix is changed to match the section.
7617 For instance, consider this example:
7619 man1_MANS = rename.man thesame.1 alsothesame.1c
7622 In this case, @file{rename.man} will be renamed to @file{rename.1} when
7623 installed, but the other files will keep their names.
7625 @cindex Target, @code{install-man}
7626 @cindex Option, @option{no-installman}
7627 @cindex @code{install-man} target
7628 @cindex @option{no-installman} option
7629 @opindex no-installman
7630 @trindex install-man
7632 By default, man pages are installed by @samp{make install}. However,
7633 since the GNU project does not require man pages, many maintainers do
7634 not expend effort to keep the man pages up to date. In these cases, the
7635 @option{no-installman} option will prevent the man pages from being
7636 installed by default. The user can still explicitly install them via
7637 @samp{make install-man}.
7639 Man pages are not currently considered to be source, because it is not
7640 uncommon for man pages to be automatically generated. Therefore they
7641 are not automatically included in the distribution. However, this can
7642 be changed by use of the @code{dist_} prefix. For instance here is
7643 how to distribute and install the two man pages of GNU @command{cpio}
7644 (which includes both Texinfo documentation and man pages):
7647 dist_man_MANS = cpio.1 mt.1
7650 The @code{nobase_} prefix is meaningless for man pages and is
7655 @chapter What Gets Installed
7657 @cindex Installation support
7658 @cindex @samp{make install} support
7660 @section Basics of installation
7662 Naturally, Automake handles the details of actually installing your
7663 program once it has been built. All files named by the various
7664 primaries are automatically installed in the appropriate places when the
7665 user runs @samp{make install}.
7667 A file named in a primary is installed by copying the built file into
7668 the appropriate directory. The base name of the file is used when
7672 bin_PROGRAMS = hello subdir/goodbye
7675 In this example, both @samp{hello} and @samp{goodbye} will be installed
7676 in @samp{$(bindir)}.
7678 Sometimes it is useful to avoid the basename step at install time. For
7679 instance, you might have a number of header files in subdirectories of
7680 the source tree that are laid out precisely how you want to install
7681 them. In this situation you can use the @code{nobase_} prefix to
7682 suppress the base name step. For example:
7685 nobase_include_HEADERS = stdio.h sys/types.h
7688 Will install @file{stdio.h} in @samp{$(includedir)} and @file{types.h}
7689 in @samp{$(includedir)/sys}.
7691 @section The two parts of install
7693 Automake generates separate @code{install-data} and @code{install-exec}
7694 rules, in case the installer is installing on multiple machines that
7695 share directory structure---these targets allow the machine-independent
7696 parts to be installed only once. @code{install-exec} installs
7697 platform-dependent files, and @code{install-data} installs
7698 platform-independent files. The @code{install} target depends on both
7699 of these targets. While Automake tries to automatically segregate
7700 objects into the correct category, the @file{Makefile.am} author is, in
7701 the end, responsible for making sure this is done correctly.
7702 @trindex install-data
7703 @trindex install-exec
7705 @cindex Install, two parts of
7707 Variables using the standard directory prefixes @samp{data},
7708 @samp{info}, @samp{man}, @samp{include}, @samp{oldinclude},
7709 @samp{pkgdata}, or @samp{pkginclude} are installed by
7710 @code{install-data}.
7712 Variables using the standard directory prefixes @samp{bin},
7713 @samp{sbin}, @samp{libexec}, @samp{sysconf}, @samp{localstate},
7714 @samp{lib}, or @samp{pkglib} are installed by @code{install-exec}.
7716 For instance, @code{data_DATA} files are installed by @code{install-data},
7717 while @code{bin_PROGRAMS} files are installed by @code{install-exec}.
7719 Any variable using a user-defined directory prefix with @samp{exec} in
7720 the name (e.g., @code{myexecbin_PROGRAMS}) is installed by
7721 @code{install-exec}. All other user-defined prefixes are installed by
7722 @code{install-data}.
7724 @section Extending installation
7726 It is possible to extend this mechanism by defining an
7727 @code{install-exec-local} or @code{install-data-local} rule. If these
7728 rules exist, they will be run at @samp{make install} time. These
7729 rules can do almost anything; care is required.
7730 @trindex install-exec-local
7731 @trindex install-data-local
7733 Automake also supports two install hooks, @code{install-exec-hook} and
7734 @code{install-data-hook}. These hooks are run after all other install
7735 rules of the appropriate type, exec or data, have completed. So, for
7736 instance, it is possible to perform post-installation modifications
7737 using an install hook. @ref{Extending} gives some examples.
7738 @cindex Install hook
7740 @section Staged installs
7743 Automake generates support for the @code{DESTDIR} variable in all
7744 install rules. @code{DESTDIR} is used during the @samp{make install}
7745 step to relocate install objects into a staging area. Each object and
7746 path is prefixed with the value of @code{DESTDIR} before being copied
7747 into the install area. Here is an example of typical DESTDIR usage:
7750 mkdir /tmp/staging &&
7751 make DESTDIR=/tmp/staging install
7754 The @command{mkdir} command avoids a security problem if the attacker
7755 creates a symbolic link from @file{/tmp/staging} to a victim area;
7756 then @command{make} places install objects in a directory tree built under
7757 @file{/tmp/staging}. If @file{/gnu/bin/foo} and
7758 @file{/gnu/share/aclocal/foo.m4} are to be installed, the above command
7759 would install @file{/tmp/staging/gnu/bin/foo} and
7760 @file{/tmp/staging/gnu/share/aclocal/foo.m4}.
7762 This feature is commonly used to build install images and packages
7765 Support for @code{DESTDIR} is implemented by coding it directly into
7766 the install rules. If your @file{Makefile.am} uses a local install
7767 rule (e.g., @code{install-exec-local}) or an install hook, then you
7768 must write that code to respect @code{DESTDIR}.
7770 @xref{Makefile Conventions, , , standards, The GNU Coding Standards},
7771 for another usage example.
7773 @section Rules for the user
7775 Automake also generates rules for targets @code{uninstall},
7776 @code{installdirs}, and @code{install-strip}.
7778 @trindex installdirs
7779 @trindex install-strip
7781 Automake supports @code{uninstall-local} and @code{uninstall-hook}.
7782 There is no notion of separate uninstalls for ``exec'' and ``data'', as
7783 these features would not provide additional functionality.
7785 Note that @code{uninstall} is not meant as a replacement for a real
7790 @chapter What Gets Cleaned
7792 @cindex @samp{make clean} support
7794 The GNU Makefile Standards specify a number of different clean rules.
7795 @xref{Standard Targets, , Standard Targets for Users, standards,
7796 The GNU Coding Standards}.
7798 Generally the files that can be cleaned are determined automatically by
7799 Automake. Of course, Automake also recognizes some variables that can
7800 be defined to specify additional files to clean. These variables are
7801 @code{MOSTLYCLEANFILES}, @code{CLEANFILES}, @code{DISTCLEANFILES}, and
7802 @code{MAINTAINERCLEANFILES}.
7803 @vindex MOSTLYCLEANFILES
7805 @vindex DISTCLEANFILES
7806 @vindex MAINTAINERCLEANFILES
7808 @trindex mostlyclean-local
7809 @trindex clean-local
7810 @trindex distclean-local
7811 @trindex maintainer-clean-local
7812 When cleaning involves more than deleting some hard-coded list of
7813 files, it is also possible to supplement the cleaning rules with your
7814 own commands. Simply define a rule for any of the
7815 @code{mostlyclean-local}, @code{clean-local}, @code{distclean-local},
7816 or @code{maintainer-clean-local} targets (@pxref{Extending}). A common
7817 case is deleting a directory, for instance, a directory created by the
7825 As the GNU Standards aren't always explicit as to which files should
7826 be removed by which rule, we've adopted a heuristic that we believe
7827 was first formulated by Fran@,{c}ois Pinard:
7831 If @command{make} built it, and it is commonly something that one would
7832 want to rebuild (for instance, a @file{.o} file), then
7833 @code{mostlyclean} should delete it.
7836 Otherwise, if @command{make} built it, then @code{clean} should delete it.
7839 If @command{configure} built it, then @code{distclean} should delete it.
7842 If the maintainer built it (for instance, a @file{.info} file), then
7843 @code{maintainer-clean} should delete it. However
7844 @code{maintainer-clean} should not delete anything that needs to exist
7845 in order to run @samp{./configure && make}.
7848 We recommend that you follow this same set of heuristics in your
7853 @chapter What Goes in a Distribution
7855 @section Basics of distribution
7857 @cindex @samp{make dist}
7862 The @code{dist} rule in the generated @file{Makefile.in} can be used
7863 to generate a gzipped @code{tar} file and other flavors of archive for
7864 distribution. The files is named based on the @code{PACKAGE} and
7865 @code{VERSION} variables defined by @code{AM_INIT_AUTOMAKE}
7866 (@pxref{Macros}); more precisely the gzipped @code{tar} file is named
7867 @samp{@var{package}-@var{version}.tar.gz}.
7869 You can use the @command{make} variable @code{GZIP_ENV} to control how gzip
7870 is run. The default setting is @option{--best}.
7872 @cindex @code{m4_include}, distribution
7873 @cindex @code{include}, distribution
7876 For the most part, the files to distribute are automatically found by
7877 Automake: all source files are automatically included in a distribution,
7878 as are all @file{Makefile.am}s and @file{Makefile.in}s. Automake also
7879 has a built-in list of commonly used files that are automatically
7880 included if they are found in the current directory (either physically,
7881 or as the target of a @file{Makefile.am} rule). This list is printed by
7882 @samp{automake --help}. Also, files that are read by @command{configure}
7883 (i.e.@: the source files corresponding to the files specified in various
7884 Autoconf macros such as @code{AC_CONFIG_FILES} and siblings) are
7885 automatically distributed. Files included in @file{Makefile.am}s (using
7886 @code{include}) or in @file{configure.ac} (using @code{m4_include}), and
7887 helper scripts installed with @samp{automake --add-missing} are also
7891 Still, sometimes there are files that must be distributed, but which
7892 are not covered in the automatic rules. These files should be listed in
7893 the @code{EXTRA_DIST} variable. You can mention files from
7894 subdirectories in @code{EXTRA_DIST}.
7896 You can also mention a directory in @code{EXTRA_DIST}; in this case the
7897 entire directory will be recursively copied into the distribution.
7898 Please note that this will also copy @emph{everything} in the directory,
7899 including CVS/RCS version control files. We recommend against using
7903 @vindex DIST_SUBDIRS
7904 If you define @code{SUBDIRS}, Automake will recursively include the
7905 subdirectories in the distribution. If @code{SUBDIRS} is defined
7906 conditionally (@pxref{Conditionals}), Automake will normally include
7907 all directories that could possibly appear in @code{SUBDIRS} in the
7908 distribution. If you need to specify the set of directories
7909 conditionally, you can set the variable @code{DIST_SUBDIRS} to the
7910 exact list of subdirectories to include in the distribution
7911 (@pxref{Conditional Subdirectories}).
7914 @section Fine-grained distribution control
7918 Sometimes you need tighter control over what does @emph{not} go into the
7919 distribution; for instance, you might have source files that are
7920 generated and that you do not want to distribute. In this case
7921 Automake gives fine-grained control using the @code{dist} and
7922 @code{nodist} prefixes. Any primary or @code{_SOURCES} variable can be
7923 prefixed with @code{dist_} to add the listed files to the distribution.
7924 Similarly, @code{nodist_} can be used to omit the files from the
7927 As an example, here is how you would cause some data to be distributed
7928 while leaving some source code out of the distribution:
7931 dist_data_DATA = distribute-this
7933 nodist_foo_SOURCES = do-not-distribute.c
7936 @section The dist hook
7940 Occasionally it is useful to be able to change the distribution before
7941 it is packaged up. If the @code{dist-hook} rule exists, it is run
7942 after the distribution directory is filled, but before the actual tar
7943 (or shar) file is created. One way to use this is for distributing
7944 files in subdirectories for which a new @file{Makefile.am} is overkill:
7948 mkdir $(distdir)/random
7949 cp -p $(srcdir)/random/a1 $(srcdir)/random/a2 $(distdir)/random
7952 Another way to use this is for removing unnecessary files that get
7953 recursively included by specifying a directory in EXTRA_DIST:
7959 rm -rf `find $(distdir)/doc -name CVS`
7964 Two variables that come handy when writing @code{dist-hook} rules are
7965 @samp{$(distdir)} and @samp{$(top_distdir)}.
7967 @samp{$(distdir)} points to the directory where the @code{dist} rule
7968 will copy files from the current directory before creating the
7969 tarball. If you are at the top-level directory, then @samp{distdir =
7970 $(PACKAGE)-$(VERSION)}. When used from subdirectory named
7971 @file{foo/}, then @samp{distdir = ../$(PACKAGE)-$(VERSION)/foo}.
7972 @samp{$(distdir)} can be a relative or absolute path, do not assume
7975 @samp{$(top_distdir)} always points to the root directory of the
7976 distributed tree. At the top-level it's equal to @samp{$(distdir)}.
7977 In the @file{foo/} subdirectory
7978 @samp{top_distdir = ../$(PACKAGE)-$(VERSION)}.
7979 @samp{$(top_distdir)} too can be a relative or absolute path.
7981 Note that when packages are nested using @code{AC_CONFIG_SUBDIRS}
7982 (@pxref{Subpackages}), then @samp{$(distdir)} and
7983 @samp{$(top_distdir)} are relative to the package where @samp{make
7984 dist} was run, not to any sub-packages involved.
7986 @section Checking the distribution
7988 @cindex @samp{make distcheck}
7989 @cindex @samp{make distcleancheck}
7990 @vindex distcleancheck_listfiles
7991 @cindex @samp{make distuninstallcheck}
7992 @vindex distuninstallcheck_listfiles
7995 Automake also generates a @code{distcheck} rule that can be of help to
7996 ensure that a given distribution will actually work. @code{distcheck}
7997 makes a distribution, then tries to do a @code{VPATH} build
7998 (@pxref{VPATH Builds}), run the test suite, and finally make another
7999 tarball to ensure the distribution is self-contained.
8001 @vindex DISTCHECK_CONFIGURE_FLAGS
8002 Building the package involves running @samp{./configure}. If you need
8003 to supply additional flags to @command{configure}, define them in the
8004 @code{DISTCHECK_CONFIGURE_FLAGS} variable, either in your top-level
8005 @file{Makefile.am}, or on the command line when invoking @command{make}.
8007 @trindex distcheck-hook
8008 If the @code{distcheck-hook} rule is defined in your top-level
8009 @file{Makefile.am}, then it will be invoked by @code{distcheck} after
8010 the new distribution has been unpacked, but before the unpacked copy
8011 is configured and built. Your @code{distcheck-hook} can do almost
8012 anything, though as always caution is advised. Generally this hook is
8013 used to check for potential distribution errors not caught by the
8014 standard mechanism. Note that @code{distcheck-hook} as well as
8015 @code{DISTCHECK_CONFIGURE_FLAGS} are not honored in a subpackage
8016 @file{Makefile.am}, but the @code{DISTCHECK_CONFIGURE_FLAGS} are
8017 passed down to the @command{configure} script of the subpackage.
8019 @trindex distcleancheck
8020 @vindex DISTCLEANFILES
8021 @vindex distcleancheck_listfiles
8022 Speaking of potential distribution errors, @code{distcheck} also
8023 ensures that the @code{distclean} rule actually removes all built
8024 files. This is done by running @samp{make distcleancheck} at the end of
8025 the @code{VPATH} build. By default, @code{distcleancheck} will run
8026 @code{distclean} and then make sure the build tree has been emptied by
8027 running @samp{$(distcleancheck_listfiles)}. Usually this check will
8028 find generated files that you forgot to add to the @code{DISTCLEANFILES}
8029 variable (@pxref{Clean}).
8031 The @code{distcleancheck} behavior should be OK for most packages,
8032 otherwise you have the possibility to override the definition of
8033 either the @code{distcleancheck} rule, or the
8034 @samp{$(distcleancheck_listfiles)} variable. For instance, to disable
8035 @code{distcleancheck} completely, add the following rule to your
8036 top-level @file{Makefile.am}:
8043 If you want @code{distcleancheck} to ignore built files that have not
8044 been cleaned because they are also part of the distribution, add the
8045 following definition instead:
8048 distcleancheck_listfiles = \
8049 find -type f -exec sh -c 'test -f $(srcdir)/@{@} || echo @{@}' ';'
8052 The above definition is not the default because it's usually an error if
8053 your Makefiles cause some distributed files to be rebuilt when the user
8054 build the package. (Think about the user missing the tool required to
8055 build the file; or if the required tool is built by your package,
8056 consider the cross-compilation case where it can't be run.) There is
8057 a FAQ entry about this (@pxref{distcleancheck}), make sure you read it
8058 before playing with @code{distcleancheck_listfiles}.
8060 @code{distcheck} also checks that the @code{uninstall} rule works
8061 properly, both for ordinary and @code{DESTDIR} builds. It does this
8062 by invoking @samp{make uninstall}, and then it checks the install tree
8063 to see if any files are left over. This check will make sure that you
8064 correctly coded your @code{uninstall}-related rules.
8066 By default, the checking is done by the @code{distuninstallcheck} rule,
8067 and the list of files in the install tree is generated by
8068 @samp{$(distuninstallcheck_listfiles}) (this is a variable whose value is
8069 a shell command to run that prints the list of files to stdout).
8071 Either of these can be overridden to modify the behavior of
8072 @code{distcheck}. For instance, to disable this check completely, you
8080 @section The types of distributions
8082 Automake generates rules to provide archives of the project for
8083 distributions in various formats. Their targets are:
8086 @item @code{dist-bzip2}
8087 Generate a bzip2 tar archive of the distribution. bzip2 archives are
8088 frequently smaller than gzipped archives.
8091 @item @code{dist-gzip}
8092 Generate a gzip tar archive of the distribution.
8095 @item @code{dist-lzma}
8096 Generate a lzma tar archive of the distribution. lzma archives are
8097 frequently smaller than @command{bzip2}-compressed archives.
8100 @item @code{dist-shar}
8101 Generate a shar archive of the distribution.
8104 @item @code{dist-zip}
8105 Generate a zip archive of the distribution.
8108 @item @code{dist-tarZ}
8109 Generate a compressed tar archive of
8114 The rule @code{dist} (and its historical synonym @code{dist-all}) will
8115 create archives in all the enabled formats, @ref{Options}. By
8116 default, only the @code{dist-gzip} target is hooked to @code{dist}.
8120 @chapter Support for test suites
8123 @cindex @code{make check}
8126 Automake supports two forms of test suites.
8128 @section Simple Tests
8130 If the variable @code{TESTS} is defined, its value is taken to be a
8131 list of programs or scripts to run in order to do the testing.
8132 Programs needing data files should look for them in @code{srcdir}
8133 (which is both an environment variable and a make variable) so they
8134 work when building in a separate directory (@pxref{Build Directories,
8135 , Build Directories , autoconf, The Autoconf Manual}), and in
8136 particular for the @code{distcheck} rule (@pxref{Dist}).
8138 For each of the @code{TESTS}, the result of execution is printed along
8139 with the test name, where @code{PASS} denotes a successful test,
8140 @code{FAIL} denotes a failed test, @code{XFAIL} an expected failure,
8141 @code{XPASS} an unexpected pass for a test that is supposed to fail,
8142 and @code{SKIP} denotes a skipped test.
8144 @cindex Exit status 77, special interpretation
8146 The number of failures will be printed at the end of the run. If a
8147 given test program exits with a status of 77, then its result is ignored
8148 in the final count. This feature allows non-portable tests to be
8149 ignored in environments where they don't make sense.
8151 @vindex AM_COLOR_TESTS
8152 If the Automake option @code{color-tests} is used (@pxref{Options})
8153 and standard output is connected to a capable terminal, then the test
8154 results and the summary are colored appropriately. The user can disable
8155 colored output by setting the @command{make} variable
8156 @samp{AM_COLOR_TESTS=no}, or force colored output even without a connecting
8157 terminal with @samp{AM_COLOR_TESTS=always}.
8160 @vindex TESTS_ENVIRONMENT
8161 The variable @code{TESTS_ENVIRONMENT} can be used to set environment
8162 variables for the test run; the environment variable @code{srcdir} is
8163 set in the rule. If all your test programs are scripts, you can also
8164 set @code{TESTS_ENVIRONMENT} to an invocation of the shell (e.g.
8165 @samp{$(SHELL) -x} can be useful for debugging the tests), or any other
8166 interpreter. For instance the following setup is used by the Automake
8167 package to run four tests in Perl.
8169 TESTS_ENVIRONMENT = $(PERL) -Mstrict -I $(top_srcdir)/lib -w
8170 TESTS = Condition.pl DisjConditions.pl Version.pl Wrap.pl
8174 @cindex Tests, expected failure
8175 @cindex Expected test failure
8177 You may define the variable @code{XFAIL_TESTS} to a list of tests
8178 (usually a subset of @code{TESTS}) that are expected to fail. This will
8179 reverse the result of those tests.
8182 Automake ensures that each file listed in @code{TESTS} is built before
8183 any tests are run; you can list both source and derived programs (or
8184 scripts) in @code{TESTS}; the generated rule will look both in
8185 @code{srcdir} and @file{.}. For instance, you might want to run a C
8186 program as a test. To do this you would list its name in @code{TESTS}
8187 and also in @code{check_PROGRAMS}, and then specify it as you would
8190 Programs listed in @code{check_PROGRAMS} (and @code{check_LIBRARIES},
8191 @code{check_LTLIBRARIES}...) are only built during @code{make check},
8192 not during @code{make all}. You should list there any program needed
8193 by your tests that does not need to be built by @code{make all}. Note
8194 that @code{check_PROGRAMS} are @emph{not} automatically added to
8195 @code{TESTS} because @code{check_PROGRAMS} usually lists programs used
8196 by the tests, not the tests themselves. Of course you can set
8197 @code{TESTS = $(check_PROGRAMS)} if all your programs are test cases.
8199 @section DejaGnu Tests
8201 If @uref{ftp://ftp.gnu.org/gnu/dejagnu/, @command{dejagnu}} appears in
8202 @code{AUTOMAKE_OPTIONS}, then a @command{dejagnu}-based test suite is
8203 assumed. The variable @code{DEJATOOL} is a list of names that are
8204 passed, one at a time, as the @option{--tool} argument to
8205 @command{runtest} invocations; it defaults to the name of the package.
8207 The variable @code{RUNTESTDEFAULTFLAGS} holds the @option{--tool} and
8208 @option{--srcdir} flags that are passed to dejagnu by default; this can be
8209 overridden if necessary.
8210 @vindex RUNTESTDEFAULTFLAGS
8212 The variables @code{EXPECT} and @code{RUNTEST} can
8213 also be overridden to provide project-specific values. For instance,
8214 you will need to do this if you are testing a compiler toolchain,
8215 because the default values do not take into account host and target
8222 The contents of the variable @code{RUNTESTFLAGS} are passed to the
8223 @code{runtest} invocation. This is considered a ``user variable''
8224 (@pxref{User Variables}). If you need to set @command{runtest} flags in
8225 @file{Makefile.am}, you can use @code{AM_RUNTESTFLAGS} instead.
8226 @vindex RUNTESTFLAGS
8227 @vindex AM_RUNTESTFLAGS
8229 @cindex @file{site.exp}
8230 Automake will generate rules to create a local @file{site.exp} file,
8231 defining various variables detected by @command{configure}. This file
8232 is automatically read by DejaGnu. It is OK for the user of a package
8233 to edit this file in order to tune the test suite. However this is
8234 not the place where the test suite author should define new variables:
8235 this should be done elsewhere in the real test suite code.
8236 Especially, @file{site.exp} should not be distributed.
8238 For more information regarding DejaGnu test suites, see @ref{Top, , ,
8239 dejagnu, The DejaGnu Manual}.
8241 In either case, the testing is done via @samp{make check}.
8243 @section Install Tests
8245 The @code{installcheck} target is available to the user as a way to
8246 run any tests after the package has been installed. You can add tests
8247 to this by writing an @code{installcheck-local} rule.
8251 @chapter Rebuilding Makefiles
8252 @cindex rebuild rules
8254 Automake generates rules to automatically rebuild @file{Makefile}s,
8255 @file{configure}, and other derived files like @file{Makefile.in}.
8257 @acindex AM_MAINTAINER_MODE
8258 If you are using @code{AM_MAINTAINER_MODE} in @file{configure.ac}, then
8259 these automatic rebuilding rules are only enabled in maintainer mode.
8261 @vindex ACLOCAL_AMFLAGS
8262 Sometimes you need to run @command{aclocal} with an argument like
8263 @option{-I} to tell it where to find @file{.m4} files. Since
8264 sometimes @command{make} will automatically run @command{aclocal}, you
8265 need a way to specify these arguments. You can do this by defining
8266 @code{ACLOCAL_AMFLAGS}; this holds arguments that are passed verbatim
8267 to @command{aclocal}. This variable is only useful in the top-level
8270 @vindex CONFIG_STATUS_DEPENDENCIES
8271 @vindex CONFIGURE_DEPENDENCIES
8272 @cindex @file{version.sh}, example
8273 @cindex @file{version.m4}, example
8275 Sometimes it is convenient to supplement the rebuild rules for
8276 @file{configure} or @file{config.status} with additional dependencies.
8277 The variables @code{CONFIGURE_DEPENDENCIES} and
8278 @code{CONFIG_STATUS_DEPENDENCIES} can be used to list these extra
8279 dependencies. These variable should be defined in all
8280 @file{Makefile}s of the tree (because these two rebuild rules are
8281 output in all them), so it is safer and easier to @code{AC_SUBST} them
8282 from @file{configure.ac}. For instance, the following statement will
8283 cause @file{configure} to be rerun each time @file{version.sh} is
8286 AC_SUBST([CONFIG_STATUS_DEPENDENCIES], ['$(top_srcdir)/version.sh'])
8289 Note the @samp{$(top_srcdir)/} in the file name. Since this variable
8290 is to be used in all @file{Makefile}s, its value must be sensible at
8291 any level in the build hierarchy.
8293 Beware not to mistake @code{CONFIGURE_DEPENDENCIES} for
8294 @code{CONFIG_STATUS_DEPENDENCIES}.
8296 @code{CONFIGURE_DEPENDENCIES} adds dependencies to the
8297 @file{configure} rule, whose effect is to run @command{autoconf}. This
8298 variable should be seldom used, because @command{automake} already tracks
8299 @code{m4_include}d files. However it can be useful when playing
8300 tricky games with @code{m4_esyscmd} or similar non-recommendable
8301 macros with side effects.
8303 @code{CONFIG_STATUS_DEPENDENCIES} adds dependencies to the
8304 @file{config.status} rule, whose effect is to run @file{configure}.
8305 This variable should therefore carry any non-standard source that may
8306 be read as a side effect of running configure, like @file{version.sh}
8307 in the example above.
8309 Speaking of @file{version.sh} scripts, we recommend against them
8310 today. They are mainly used when the version of a package is updated
8311 automatically by a script (e.g., in daily builds). Here is what some
8312 old-style @file{configure.ac}s may look like:
8315 . $srcdir/version.sh
8316 AM_INIT_AUTOMAKE([name], $VERSION_NUMBER)
8320 Here, @file{version.sh} is a shell fragment that sets
8321 @code{VERSION_NUMBER}. The problem with this example is that
8322 @command{automake} cannot track dependencies (listing @file{version.sh}
8323 in @command{CONFIG_STATUS_DEPENDENCIES}, and distributing this file is up
8324 to the user), and that it uses the obsolete form of @code{AC_INIT} and
8325 @code{AM_INIT_AUTOMAKE}. Upgrading to the new syntax is not
8326 straightforward, because shell variables are not allowed in
8327 @code{AC_INIT}'s arguments. We recommend that @file{version.sh} be
8328 replaced by an M4 file that is included by @file{configure.ac}:
8330 m4_include([version.m4])
8331 AC_INIT([name], VERSION_NUMBER)
8336 Here @file{version.m4} could contain something like
8337 @samp{m4_define([VERSION_NUMBER], [1.2])}. The advantage of this
8338 second form is that @command{automake} will take care of the
8339 dependencies when defining the rebuild rule, and will also distribute
8340 the file automatically. An inconvenience is that @command{autoconf}
8341 will now be rerun each time the version number is bumped, when only
8342 @file{configure} had to be rerun in the previous setup.
8346 @chapter Changing Automake's Behavior
8348 Various features of Automake can be controlled by options in the
8349 @file{Makefile.am}. Such options are applied on a per-@file{Makefile}
8350 basis when listed in a special @file{Makefile} variable named
8351 @code{AUTOMAKE_OPTIONS}. They are applied globally to all processed
8352 @file{Makefiles} when listed in the first argument of
8353 @code{AM_INIT_AUTOMAKE} in @file{configure.ac}. Currently understood
8355 @vindex AUTOMAKE_OPTIONS
8358 @item @option{gnits}
8360 @itemx @option{foreign}
8361 @itemx @option{cygnus}
8362 @cindex Option, @option{gnits}
8363 @cindex Option, @option{gnu}
8364 @cindex Option, @option{foreign}
8365 @cindex Option, @option{cygnus}
8371 Set the strictness as appropriate. The @option{gnits} option also
8372 implies options @option{readme-alpha} and @option{check-news}.
8374 @item @option{ansi2knr}
8375 @itemx @option{@var{path}/ansi2knr}
8376 @cindex Option, @option{ansi2knr}
8378 Turn on the obsolete de-ANSI-fication feature. @xref{ANSI}. If preceded by a
8379 path, the generated @file{Makefile.in} will look in the specified
8380 directory to find the @file{ansi2knr} program. The path should be a
8381 relative path to another directory in the same distribution (Automake
8382 currently does not check this).
8384 @item @option{check-news}
8385 @cindex Option, @option{check-news}
8387 Cause @samp{make dist} to fail unless the current version number appears
8388 in the first few lines of the @file{NEWS} file.
8390 @item @option{color-tests}
8391 @cindex Option, @option{color-tests}
8392 @opindex color-tests
8393 Cause output of the simple test suite (@pxref{Tests}) to be
8394 colorized on capable terminals.
8396 @item @option{dejagnu}
8397 @cindex Option, @option{dejagnu}
8399 Cause @command{dejagnu}-specific rules to be generated. @xref{Tests}.
8401 @item @option{dist-bzip2}
8402 @cindex Option, @option{dist-bzip2}
8404 Hook @code{dist-bzip2} to @code{dist}.
8407 @item @option{dist-lzma}
8408 @cindex Option, @option{dist-lzma}
8410 Hook @code{dist-lzma} to @code{dist}.
8413 @item @option{dist-shar}
8414 @cindex Option, @option{dist-shar}
8416 Hook @code{dist-shar} to @code{dist}.
8419 @item @option{dist-zip}
8420 @cindex Option, @option{dist-zip}
8422 Hook @code{dist-zip} to @code{dist}.
8425 @item @option{dist-tarZ}
8426 @cindex Option, @option{dist-tarZ}
8428 Hook @code{dist-tarZ} to @code{dist}.
8431 @item @option{filename-length-max=99}
8432 @cindex Option, @option{filename-length-max=99}
8433 @opindex filename-length-max=99
8434 Abort if file names longer than 99 characters are found during
8435 @samp{make dist}. Such long file names are generally considered not to
8436 be portable in tarballs. See the @option{tar-v7} and @option{tar-ustar}
8437 options below. This option should be used in the top-level
8438 @file{Makefile.am} or as an argument of @code{AM_INIT_AUTOMAKE} in
8439 @file{configure.ac}, it will be ignored otherwise. It will also be
8440 ignored in sub-packages of nested packages (@pxref{Subpackages}).
8442 @item @option{no-define}
8443 @cindex Option, @option{no-define}
8445 This options is meaningful only when passed as an argument to
8446 @code{AM_INIT_AUTOMAKE}. It will prevent the @code{PACKAGE} and
8447 @code{VERSION} variables to be @code{AC_DEFINE}d.
8449 @item @option{no-dependencies}
8450 @cindex Option, @option{no-dependencies}
8451 @opindex no-dependencies
8452 This is similar to using @option{--ignore-deps} on the command line,
8453 but is useful for those situations where you don't have the necessary
8454 bits to make automatic dependency tracking work
8455 (@pxref{Dependencies}). In this case the effect is to effectively
8456 disable automatic dependency tracking.
8458 @item @option{no-dist}
8459 @cindex Option, @option{no-dist}
8461 Don't emit any code related to @code{dist} target. This is useful
8462 when a package has its own method for making distributions.
8464 @item @option{no-dist-gzip}
8465 @cindex Option, @option{no-dist-gzip}
8466 @opindex no-dist-gzip
8467 Do not hook @code{dist-gzip} to @code{dist}.
8468 @trindex no-dist-gzip
8470 @item @option{no-exeext}
8471 @cindex Option, @option{no-exeext}
8473 If your @file{Makefile.am} defines a rule for target @code{foo}, it
8474 will override a rule for a target named @samp{foo$(EXEEXT)}. This is
8475 necessary when @code{EXEEXT} is found to be empty. However, by
8476 default automake will generate an error for this use. The
8477 @option{no-exeext} option will disable this error. This is intended for
8478 use only where it is known in advance that the package will not be
8479 ported to Windows, or any other operating system using extensions on
8482 @item @option{no-installinfo}
8483 @cindex Option, @option{no-installinfo}
8484 @opindex no-installinfo
8485 The generated @file{Makefile.in} will not cause info pages to be built
8486 or installed by default. However, @code{info} and @code{install-info}
8487 targets will still be available. This option is disallowed at
8488 @option{gnu} strictness and above.
8490 @trindex install-info
8492 @item @option{no-installman}
8493 @cindex Option, @option{no-installman}
8494 @opindex no-installman
8495 The generated @file{Makefile.in} will not cause man pages to be
8496 installed by default. However, an @code{install-man} target will still
8497 be available for optional installation. This option is disallowed at
8498 @option{gnu} strictness and above.
8499 @trindex install-man
8501 @item @option{nostdinc}
8502 @cindex Option, @option{nostdinc}
8504 This option can be used to disable the standard @option{-I} options that
8505 are ordinarily automatically provided by Automake.
8507 @item @option{no-texinfo.tex}
8508 @cindex Option, @option{no-texinfo.tex}
8509 @opindex no-texinfo.tex
8510 Don't require @file{texinfo.tex}, even if there are texinfo files in
8513 @item @option{readme-alpha}
8514 @cindex Option, @option{readme-alpha}
8515 @opindex readme-alpha
8516 If this release is an alpha release, and the file @file{README-alpha}
8517 exists, then it will be added to the distribution. If this option is
8518 given, version numbers are expected to follow one of two forms. The
8519 first form is @samp{@var{MAJOR}.@var{MINOR}.@var{ALPHA}}, where each
8520 element is a number; the final period and number should be left off for
8521 non-alpha releases. The second form is
8522 @samp{@var{MAJOR}.@var{MINOR}@var{ALPHA}}, where @var{ALPHA} is a
8523 letter; it should be omitted for non-alpha releases.
8525 @item @option{std-options}
8526 @cindex Options, @option{std-options}
8527 @cindex @samp{make installcheck}, testing @option{--help} and @option{--version}
8528 @cindex @option{--help} check
8529 @cindex @option{--version} check
8530 @opindex std-options
8532 Make the @code{installcheck} rule check that installed scripts and
8533 programs support the @option{--help} and @option{--version} options.
8534 This also provides a basic check that the program's
8535 run-time dependencies are satisfied after installation.
8537 @vindex AM_INSTALLCHECK_STD_OPTIONS_EXEMPT
8538 In a few situations, programs (or scripts) have to be exempted from this
8539 test. For instance, @command{false} (from GNU sh-utils) is never
8540 successful, even for @option{--help} or @option{--version}. You can list
8541 such programs in the variable @code{AM_INSTALLCHECK_STD_OPTIONS_EXEMPT}.
8542 Programs (not scripts) listed in this variable should be suffixed by
8543 @samp{$(EXEEXT)} for the sake of Win32 or OS/2. For instance, suppose we
8544 build @file{false} as a program but @file{true.sh} as a script, and that
8545 neither of them support @option{--help} or @option{--version}:
8548 AUTOMAKE_OPTIONS = std-options
8549 bin_PROGRAMS = false ...
8550 bin_SCRIPTS = true.sh ...
8551 AM_INSTALLCHECK_STD_OPTIONS_EXEMPT = false$(EXEEXT) true.sh
8554 @item @option{subdir-objects}
8555 @cindex Options, @option{subdir-objects}
8556 @opindex subdir-objects
8557 If this option is specified, then objects are placed into the
8558 subdirectory of the build directory corresponding to the subdirectory of
8559 the source file. For instance, if the source file is
8560 @file{subdir/file.cxx}, then the output file would be
8561 @file{subdir/file.o}.
8563 In order to use this option with C sources, you should add
8564 @code{AM_PROG_CC_C_O} to @file{configure.ac}.
8566 @anchor{tar-formats}
8567 @item @option{tar-v7}
8568 @itemx @option{tar-ustar}
8569 @itemx @option{tar-pax}
8570 @cindex Option, @option{tar-v7}
8571 @cindex Option, @option{tar-ustar}
8572 @cindex Option, @option{tar-pax}
8573 @cindex @command{tar} formats
8574 @cindex v7 @command{tar} format
8575 @cindex ustar format
8581 These three mutually exclusive options select the tar format to use
8582 when generating tarballs with @samp{make dist}. (The tar file created
8583 is then compressed according to the set of @option{no-dist-gzip},
8584 @option{dist-bzip2}, @option{dist-lzma} and @option{dist-tarZ} options in use.)
8586 These options must be passed as argument to @code{AM_INIT_AUTOMAKE}
8587 (@pxref{Macros}) because they can require additional configure checks.
8588 Automake will complain if it sees such options in an
8589 @code{AUTOMAKE_OPTIONS} variable.
8591 @option{tar-v7} selects the old V7 tar format. This is the historical
8592 default. This antiquated format is understood by all tar
8593 implementations and supports file names with up to 99 characters. When
8594 given longer file names some tar implementations will diagnose the
8595 problem while other will generate broken tarballs or use non-portable
8596 extensions. Furthermore, the V7 format cannot store empty
8597 directories. When using this format, consider using the
8598 @option{filename-length-max=99} option to catch file names too long.
8600 @option{tar-ustar} selects the ustar format defined by POSIX
8601 1003.1-1988. This format is believed to be old enough to be portable.
8602 It fully supports empty directories. It can store file names with up
8603 to 256 characters, provided that the file name can be split at
8604 directory separator in two parts, first of them being at most 155
8605 bytes long. So, in most cases the maximum file name length will be
8606 shorter than 256 characters. However you may run against broken tar
8607 implementations that incorrectly handle file names longer than 99
8608 characters (please report them to @email{bug-automake@@gnu.org} so we
8609 can document this accurately).
8611 @option{tar-pax} selects the new pax interchange format defined by POSIX
8612 1003.1-2001. It does not limit the length of file names. However,
8613 this format is very young and should probably be restricted to
8614 packages that target only very modern platforms. There are moves to
8615 change the pax format in an upward-compatible way, so this option may
8616 refer to a more recent version in the future.
8618 @xref{Formats, , Controlling the Archive Format, tar, GNU Tar}, for
8619 further discussion about tar formats.
8621 @command{configure} knows several ways to construct these formats. It
8622 will not abort if it cannot find a tool up to the task (so that the
8623 package can still be built), but @samp{make dist} will fail.
8626 @cindex Option, @var{version}
8627 A version number (e.g., @samp{0.30}) can be specified. If Automake is not
8628 newer than the version specified, creation of the @file{Makefile.in}
8631 @item @option{-W@var{category}} or @option{--warnings=@var{category}}
8632 @cindex Option, warnings
8633 @cindex Option, @option{-W@var{category}}
8634 @cindex Option, @option{--warnings=@var{category}}
8635 These options behave exactly like their command-line counterpart
8636 (@pxref{Invoking Automake}). This allows you to enable or disable some
8637 warning categories on a per-file basis. You can also setup some warnings
8638 for your entire project; for instance, try @samp{AM_INIT_AUTOMAKE([-Wall])}
8639 in your @file{configure.ac}.
8643 Unrecognized options are diagnosed by @command{automake}.
8645 If you want an option to apply to all the files in the tree, you can use
8646 the @code{AM_INIT_AUTOMAKE} macro in @file{configure.ac}.
8651 @chapter Miscellaneous Rules
8653 There are a few rules and variables that didn't fit anywhere else.
8656 * Tags:: Interfacing to etags and mkid
8657 * Suffixes:: Handling new file extensions
8658 * Multilibs:: Support for multilibs.
8663 @section Interfacing to @command{etags}
8665 @cindex @file{TAGS} support
8667 Automake will generate rules to generate @file{TAGS} files for use with
8668 GNU Emacs under some circumstances.
8671 If any C, C++ or Fortran 77 source code or headers are present, then
8672 @code{tags} and @code{TAGS} rules will be generated for the directory.
8673 All files listed using the @code{_SOURCES}, @code{_HEADERS}, and
8674 @code{_LISP} primaries will be used to generate tags. Note that
8675 generated source files that are not distributed must be declared in
8676 variables like @code{nodist_noinst_HEADERS} or
8677 @code{nodist_@var{prog}_SOURCES} or they will be ignored.
8679 A @code{tags} rule will be output at the topmost directory of a
8680 multi-directory package. When run from this topmost directory,
8681 @samp{make tags} will generate a @file{TAGS} file that includes by
8682 reference all @file{TAGS} files from subdirectories.
8684 The @code{tags} rule will also be generated if the variable
8685 @code{ETAGS_ARGS} is defined. This variable is intended for use in
8686 directories that contain taggable source that @command{etags} does
8687 not understand. The user can use the @code{ETAGSFLAGS} to pass
8688 additional flags to @command{etags}; @code{AM_ETAGSFLAGS} is also
8689 available for use in @file{Makefile.am}.
8692 @vindex AM_ETAGSFLAGS
8694 Here is how Automake generates tags for its source, and for nodes in its
8698 ETAGS_ARGS = automake.in --lang=none \
8699 --regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi
8702 If you add file names to @code{ETAGS_ARGS}, you will probably also
8703 want to define @code{TAGS_DEPENDENCIES}. The contents of this variable
8704 are added directly to the dependencies for the @code{tags} rule.
8705 @vindex TAGS_DEPENDENCIES
8707 Automake also generates a @code{ctags} rule that can be used to
8708 build @command{vi}-style @file{tags} files. The variable @code{CTAGS}
8709 is the name of the program to invoke (by default @command{ctags});
8710 @code{CTAGSFLAGS} can be used by the user to pass additional flags,
8711 and @code{AM_CTAGSFLAGS} can be used by the @file{Makefile.am}.
8713 Automake will also generate an @code{ID} rule that will run
8714 @command{mkid} on the source. This is only supported on a
8715 directory-by-directory basis.
8718 Finally, Automake also emit rules to support the
8719 @uref{http://www.gnu.org/software/global/, GNU Global Tags program}.
8720 The @code{GTAGS} rule runs Global Tags and puts the
8721 result in the top build directory. The variable @code{GTAGS_ARGS}
8722 holds arguments that are passed to @command{gtags}.
8727 @section Handling new file extensions
8729 @cindex Adding new @code{SUFFIXES}
8730 @cindex @code{SUFFIXES}, adding
8733 It is sometimes useful to introduce a new implicit rule to handle a file
8734 type that Automake does not know about.
8736 For instance, suppose you had a compiler that could compile @file{.foo}
8737 files to @file{.o} files. You would simply define an suffix rule for
8745 Then you could directly use a @file{.foo} file in a @code{_SOURCES}
8746 variable and expect the correct results:
8750 doit_SOURCES = doit.foo
8753 This was the simpler and more common case. In other cases, you will
8754 have to help Automake to figure which extensions you are defining your
8755 suffix rule for. This usually happens when your extensions does not
8756 start with a dot. Then, all you have to do is to put a list of new
8757 suffixes in the @code{SUFFIXES} variable @strong{before} you define your
8760 For instance, the following definition prevents Automake to misinterpret
8761 @samp{.idlC.cpp:} as an attempt to transform @file{.idlC} files into
8765 SUFFIXES = .idl C.cpp
8770 As you may have noted, the @code{SUFFIXES} variable behaves like the
8771 @code{.SUFFIXES} special target of @command{make}. You should not touch
8772 @code{.SUFFIXES} yourself, but use @code{SUFFIXES} instead and let
8773 Automake generate the suffix list for @code{.SUFFIXES}. Any given
8774 @code{SUFFIXES} go at the start of the generated suffixes list, followed
8775 by Automake generated suffixes not already in the list.
8778 @section Support for Multilibs
8780 Automake has support for an obscure feature called multilibs. A
8781 @dfn{multilib} is a library that is built for multiple different ABIs
8782 at a single time; each time the library is built with a different target
8783 flag combination. This is only useful when the library is intended to
8784 be cross-compiled, and it is almost exclusively used for compiler
8787 The multilib support is still experimental. Only use it if you are
8788 familiar with multilibs and can debug problems you might encounter.
8795 @cindex Including @file{Makefile} fragment
8796 @cindex @file{Makefile} fragment, including
8798 Automake supports an @code{include} directive that can be used to
8799 include other @file{Makefile} fragments when @command{automake} is run.
8800 Note that these fragments are read and interpreted by @command{automake},
8801 not by @command{make}. As with conditionals, @command{make} has no idea that
8802 @code{include} is in use.
8804 There are two forms of @code{include}:
8807 @item include $(srcdir)/file
8808 Include a fragment that is found relative to the current source
8811 @item include $(top_srcdir)/file
8812 Include a fragment that is found relative to the top source directory.
8815 Note that if a fragment is included inside a conditional, then the
8816 condition applies to the entire contents of that fragment.
8818 Makefile fragments included this way are always distributed because
8819 they are needed to rebuild @file{Makefile.in}.
8822 @chapter Conditionals
8824 @cindex Conditionals
8826 Automake supports a simple type of conditionals.
8828 @unnumberedsec Usage
8830 @acindex AM_CONDITIONAL
8831 Before using a conditional, you must define it by using
8832 @code{AM_CONDITIONAL} in the @file{configure.ac} file (@pxref{Macros}).
8834 @defmac AM_CONDITIONAL (@var{conditional}, @var{condition})
8835 The conditional name, @var{conditional}, should be a simple string
8836 starting with a letter and containing only letters, digits, and
8837 underscores. It must be different from @samp{TRUE} and @samp{FALSE}
8838 that are reserved by Automake.
8840 The shell @var{condition} (suitable for use in a shell @code{if}
8841 statement) is evaluated when @command{configure} is run. Note that you
8842 must arrange for @emph{every} @code{AM_CONDITIONAL} to be invoked every
8843 time @command{configure} is run. If @code{AM_CONDITIONAL} is run
8844 conditionally (e.g., in a shell @code{if} statement), then the result
8845 will confuse automake.
8848 @cindex @option{--enable-debug}, example
8849 @cindex Example conditional @option{--enable-debug}
8850 @cindex Conditional example, @option{--enable-debug}
8852 Conditionals typically depend upon options that the user provides to
8853 the @command{configure} script. Here is an example of how to write a
8854 conditional that is true if the user uses the @option{--enable-debug}
8858 AC_ARG_ENABLE([debug],
8859 [ --enable-debug Turn on debugging],
8860 [case "$@{enableval@}" in
8863 *) AC_MSG_ERROR([bad value $@{enableval@} for --enable-debug]) ;;
8864 esac],[debug=false])
8865 AM_CONDITIONAL([DEBUG], [test x$debug = xtrue])
8868 Here is an example of how to use that conditional in @file{Makefile.am}:
8880 noinst_PROGRAMS = $(DBG)
8883 This trivial example could also be handled using @code{EXTRA_PROGRAMS}
8884 (@pxref{Conditional Programs}).
8886 You may only test a single variable in an @code{if} statement, possibly
8887 negated using @samp{!}. The @code{else} statement may be omitted.
8888 Conditionals may be nested to any depth. You may specify an argument to
8889 @code{else} in which case it must be the negation of the condition used
8890 for the current @code{if}. Similarly you may specify the condition
8891 that is closed by an @code{end}:
8902 Unbalanced conditions are errors.
8904 The @code{else} branch of the above two examples could be omitted,
8905 since assigning the empty string to an otherwise undefined variable
8906 makes no difference.
8908 @unnumberedsec Portability
8910 Note that conditionals in Automake are not the same as conditionals in
8911 GNU Make. Automake conditionals are checked at configure time by the
8912 @file{configure} script, and affect the translation from
8913 @file{Makefile.in} to @file{Makefile}. They are based on options passed
8914 to @file{configure} and on results that @file{configure} has discovered
8915 about the host system. GNU Make conditionals are checked at @command{make}
8916 time, and are based on variables passed to the make program or defined
8917 in the @file{Makefile}.
8919 Automake conditionals will work with any make program.
8921 @unnumberedsec Limits
8923 Conditionals should enclose complete statements like variables or
8924 rules definitions. Automake cannot deal with conditionals used inside
8925 a variable definition, for instance, and is not even able to diagnose
8926 this situation. The following example would not work:
8929 # This syntax is not understood by Automake
8938 However the intended definition of @code{AM_CPPFLAGS} can be achieved
8943 DEBUGFLAGS = -DDEBUG
8945 AM_CPPFLAGS = -DFEATURE_A $(DEBUGFLAGS) -DFEATURE_B
8951 AM_CPPFLAGS = -DFEATURE_A
8953 AM_CPPFLAGS += -DDEBUG
8955 AM_CPPFLAGS += -DFEATURE_B
8959 @chapter The effect of @option{--gnu} and @option{--gnits}
8961 @cindex @option{--gnu}, required files
8962 @cindex @option{--gnu}, complete description
8964 The @option{--gnu} option (or @option{gnu} in the
8965 @code{AUTOMAKE_OPTIONS} variable) causes @command{automake} to check
8970 The files @file{INSTALL}, @file{NEWS}, @file{README}, @file{AUTHORS},
8971 and @file{ChangeLog}, plus one of @file{COPYING.LIB}, @file{COPYING.LESSER}
8972 or @file{COPYING}, are required at the topmost directory of the package.
8975 The options @option{no-installman} and @option{no-installinfo} are
8979 Note that this option will be extended in the future to do even more
8980 checking; it is advisable to be familiar with the precise requirements
8981 of the GNU standards. Also, @option{--gnu} can require certain
8982 non-standard GNU programs to exist for use by various maintainer-only
8983 rules; for instance, in the future @command{pathchk} might be required for
8986 @cindex @option{--gnits}, complete description
8988 The @option{--gnits} option does everything that @option{--gnu} does, and
8989 checks the following as well:
8993 @samp{make installcheck} will check to make sure that the @option{--help}
8994 and @option{--version} really print a usage message and a version string,
8995 respectively. This is the @option{std-options} option (@pxref{Options}).
8998 @samp{make dist} will check to make sure the @file{NEWS} file has been
8999 updated to the current version.
9002 @code{VERSION} is checked to make sure its format complies with Gnits
9004 @c FIXME xref when standards are finished
9007 @cindex @file{README-alpha}
9008 If @code{VERSION} indicates that this is an alpha release, and the file
9009 @file{README-alpha} appears in the topmost directory of a package, then
9010 it is included in the distribution. This is done in @option{--gnits}
9011 mode, and no other, because this mode is the only one where version
9012 number formats are constrained, and hence the only mode where Automake
9013 can automatically determine whether @file{README-alpha} should be
9017 The file @file{THANKS} is required.
9022 @chapter The effect of @option{--cygnus}
9024 @cindex @option{cygnus} strictness
9026 Some packages, notably GNU GCC and GNU gdb, have a build environment
9027 originally written at Cygnus Support (subsequently renamed Cygnus
9028 Solutions, and then later purchased by Red Hat). Packages with this
9029 ancestry are sometimes referred to as ``Cygnus'' trees.
9031 A Cygnus tree has slightly different rules for how a
9032 @file{Makefile.in} is to be constructed. Passing @option{--cygnus} to
9033 @command{automake} will cause any generated @file{Makefile.in} to
9034 comply with Cygnus rules.
9036 Here are the precise effects of @option{--cygnus}:
9040 Info files are always created in the build directory, and not in the
9044 @file{texinfo.tex} is not required if a Texinfo source file is
9045 specified. The assumption is that the file will be supplied, but in a
9046 place that Automake cannot find. This assumption is an artifact of how
9047 Cygnus packages are typically bundled.
9050 @samp{make dist} is not supported, and the rules for it are not
9051 generated. Cygnus-style trees use their own distribution mechanism.
9054 Certain tools will be searched for in the build tree as well as in the
9055 user's @env{PATH}. These tools are @command{runtest}, @command{expect},
9056 @command{makeinfo} and @command{texi2dvi}.
9059 @option{--foreign} is implied.
9062 The options @option{no-installinfo} and @option{no-dependencies} are
9066 The macros @code{AM_MAINTAINER_MODE} and @code{AM_CYGWIN32} are
9070 The @code{check} target doesn't depend on @code{all}.
9073 GNU maintainers are advised to use @option{gnu} strictness in preference
9074 to the special Cygnus mode. Some day, perhaps, the differences between
9075 Cygnus trees and GNU trees will disappear (for instance, as GCC is made
9076 more standards compliant). At that time the special Cygnus mode will be
9081 @chapter When Automake Isn't Enough
9083 In some situations, where Automake is not up to one task, one has to
9084 resort to handwritten rules or even handwritten @file{Makefile}s.
9087 * Extending:: Adding new rules or overriding existing ones.
9088 * Third-Party Makefiles:: Integrating Non-Automake @file{Makefile}s.
9092 @section Extending Automake Rules
9094 With some minor exceptions (like @code{_PROGRAMS} variables, @code{TESTS},
9095 or @code{XFAIL_TESTS}) being rewritten to append @samp{$(EXEEXT)}), the
9096 contents of a @file{Makefile.am} is copied to @file{Makefile.in} verbatim.
9098 @cindex copying semantics
9100 These copying semantics means that many problems can be worked around
9101 by simply adding some @command{make} variables and rules to
9102 @file{Makefile.am}. Automake will ignore these additions.
9104 @cindex conflicting definitions
9105 @cindex rules, conflicting
9106 @cindex variables, conflicting
9107 @cindex definitions, conflicts
9109 Since a @file{Makefile.in} is built from data gathered from three
9110 different places (@file{Makefile.am}, @file{configure.ac}, and
9111 @command{automake} itself), it is possible to have conflicting
9112 definitions of rules or variables. When building @file{Makefile.in}
9113 the following priorities are respected by @command{automake} to ensure
9114 the user always have the last word. User defined variables in
9115 @file{Makefile.am} have priority over variables @code{AC_SUBST}ed from
9116 @file{configure.ac}, and @code{AC_SUBST}ed variables have priority
9117 over @command{automake}-defined variables. As far rules are
9118 concerned, a user-defined rule overrides any
9119 @command{automake}-defined rule for the same target.
9121 @cindex overriding rules
9122 @cindex overriding semantics
9123 @cindex rules, overriding
9125 These overriding semantics make it possible to fine tune some default
9126 settings of Automake, or replace some of its rules. Overriding
9127 Automake rules is often inadvisable, particularly in the topmost
9128 directory of a package with subdirectories. The @option{-Woverride}
9129 option (@pxref{Invoking Automake}) comes handy to catch overridden
9132 Note that Automake does not make any difference between rules with
9133 commands and rules that only specify dependencies. So it is not
9134 possible to append new dependencies to an @command{automake}-defined
9135 target without redefining the entire rule.
9137 @cindex @option{-local} targets
9138 @cindex local targets
9140 However, various useful targets have a @samp{-local} version you can
9141 specify in your @file{Makefile.am}. Automake will supplement the
9142 standard target with these user-supplied targets.
9157 @trindex check-local
9159 @trindex install-data
9160 @trindex install-data-local
9161 @trindex install-dvi
9162 @trindex install-dvi-local
9163 @trindex install-exec
9164 @trindex install-exec-local
9165 @trindex install-html
9166 @trindex install-html-local
9167 @trindex install-info
9168 @trindex install-info-local
9169 @trindex install-pdf
9170 @trindex install-pdf-local
9172 @trindex install-ps-local
9174 @trindex uninstall-local
9175 @trindex mostlyclean
9176 @trindex mostlyclean-local
9178 @trindex clean-local
9180 @trindex distclean-local
9181 @trindex installdirs
9182 @trindex installdirs-local
9183 @trindex installcheck
9184 @trindex installcheck-local
9186 The targets that support a local version are @code{all}, @code{info},
9187 @code{dvi}, @code{ps}, @code{pdf}, @code{html}, @code{check},
9188 @code{install-data}, @code{install-dvi}, @code{install-exec},
9189 @code{install-html}, @code{install-info}, @code{install-pdf},
9190 @code{install-ps}, @code{uninstall}, @code{installdirs},
9191 @code{installcheck} and the various @code{clean} targets
9192 (@code{mostlyclean}, @code{clean}, @code{distclean}, and
9193 @code{maintainer-clean}).
9195 Note that there are no @code{uninstall-exec-local} or
9196 @code{uninstall-data-local} targets; just use @code{uninstall-local}.
9197 It doesn't make sense to uninstall just data or just executables.
9199 For instance, here is one way to erase a subdirectory during
9200 @samp{make clean} (@pxref{Clean}).
9207 Older version of this manual used to show how to use
9208 @code{install-data-local} to install a file to some hard-coded
9209 location, but you should avoid this. (@pxref{Hard-Coded Install Paths})
9211 @cindex @option{-hook} targets
9212 @cindex hook targets
9214 Some rule also have a way to run another rule, called a @dfn{hook},
9215 after their work is done. The hook is named after the principal target,
9216 with @samp{-hook} appended. The targets allowing hooks are
9217 @code{install-data}, @code{install-exec}, @code{uninstall}, @code{dist},
9218 and @code{distcheck}.
9219 @trindex install-data-hook
9220 @trindex install-exec-hook
9221 @trindex uninstall-hook
9224 For instance, here is how to create a hard link to an installed program:
9228 ln $(DESTDIR)$(bindir)/program$(EXEEXT) \
9229 $(DESTDIR)$(bindir)/proglink$(EXEEXT)
9232 Although cheaper and more portable than symbolic links, hard links
9233 will not work everywhere (for instance, OS/2 does not have
9234 @command{ln}). Ideally you should fall back to @samp{cp -p} when
9235 @command{ln} does not work. An easy way, if symbolic links are
9236 acceptable to you, is to add @code{AC_PROG_LN_S} to
9237 @file{configure.ac} (@pxref{Particular Programs, , Particular Program
9238 Checks, autoconf, The Autoconf Manual}) and use @samp{$(LN_S)} in
9241 @cindex versioned binaries, installing
9242 @cindex installing versioned binaries
9243 @cindex @code{LN_S} example
9244 For instance, here is how you could install a versioned copy of a
9245 program using @samp{$(LN_S)}:
9249 cd $(DESTDIR)$(bindir) && \
9250 mv -f prog$(EXEEXT) prog-$(VERSION)$(EXEEXT) && \
9251 $(LN_S) prog-$(VERSION)$(EXEEXT) prog$(EXEEXT)
9254 Note that we rename the program so that a new version will erase the
9255 symbolic link, not the real binary. Also we @command{cd} into the
9256 destination directory in order to create relative links.
9258 When writing @code{install-exec-hook} or @code{install-data-hook},
9259 please bear in mind that the exec/data distinction is based on the
9260 installation directory, not on the primary used (@pxref{Install}). So
9261 a @code{foo_SCRIPTS} will be installed by @code{install-data}, and a
9262 @code{barexec_SCRIPTS} will be installed by @code{install-exec}. You
9263 should define your hooks consequently.
9265 @c FIXME should include discussion of variables you can use in these
9268 @node Third-Party Makefiles
9269 @section Third-Party @file{Makefile}s
9271 @cindex Third-party packages, interfacing with
9272 @cindex Interfacing with third-party packages
9274 In most projects all @file{Makefile}s are generated by Automake. In
9275 some cases, however, projects need to embed subdirectories with
9276 handwritten @file{Makefile}s. For instance, one subdirectory could be
9277 a third-party project with its own build system, not using Automake.
9279 It is possible to list arbitrary directories in @code{SUBDIRS} or
9280 @code{DIST_SUBDIRS} provided each of these directories has a
9281 @file{Makefile} that recognizes all the following recursive targets.
9283 @cindex recursive targets and third-party @file{Makefile}s
9284 When a user runs one of these targets, that target is run recursively
9285 in all subdirectories. This is why it is important that even
9286 third-party @file{Makefile}s support them.
9290 Compile the entire package. This is the default target in
9291 Automake-generated @file{Makefile}s, but it does not need to be the
9292 default in third-party @file{Makefile}s.
9298 Copy files to distribute into @samp{$(distdir)}, before a tarball is
9299 constructed. Of course this target is not required if the
9300 @option{no-dist} option (@pxref{Options}) is used.
9302 The variables @samp{$(top_distdir)} and @samp{$(distdir)}
9303 (@pxref{Dist}) will be passed from the outer package to the subpackage
9304 when the @code{distdir} target is invoked. These two variables have
9305 been adjusted for the directory that is being recursed into, so they
9312 Install or uninstall files (@pxref{Install}).
9319 Install only some specific documentation format (@pxref{Texinfo}).
9322 Create install directories, but do not install any files.
9326 Check the package (@pxref{Tests}).
9331 @itemx maintainer-clean
9332 Cleaning rules (@pxref{Clean}).
9339 Build the documentation in various formats (@pxref{Texinfo}).
9343 Build @file{TAGS} and @file{CTAGS} (@pxref{Tags}).
9346 If you have ever used Gettext in a project, this is a good example of
9347 how third-party @file{Makefile}s can be used with Automake. The
9348 @file{Makefile}s @command{gettextize} puts in the @file{po/} and
9349 @file{intl/} directories are handwritten @file{Makefile}s that
9350 implement all these targets. That way they can be added to
9351 @code{SUBDIRS} in Automake packages.
9353 Directories that are only listed in @code{DIST_SUBDIRS} but not in
9354 @code{SUBDIRS} need only the @code{distclean},
9355 @code{maintainer-clean}, and @code{distdir} rules (@pxref{Conditional
9358 Usually, many of these rules are irrelevant to the third-party
9359 subproject, but they are required for the whole package to work. It's
9360 OK to have a rule that does nothing, so if you are integrating a
9361 third-party project with no documentation or tag support, you could
9362 simply augment its @file{Makefile} as follows:
9365 EMPTY_AUTOMAKE_TARGETS = dvi pdf ps info html tags ctags
9366 .PHONY: $(EMPTY_AUTOMAKE_TARGETS)
9367 $(EMPTY_AUTOMAKE_TARGETS):
9370 Another aspect of integrating third-party build systems is whether
9371 they support VPATH builds (@pxref{VPATH Builds}). Obviously if the
9372 subpackage does not support VPATH builds the whole package will not
9373 support VPATH builds. This in turns means that @samp{make distcheck}
9374 will not work, because it relies on VPATH builds. Some people can
9375 live without this (actually, many Automake users have never heard of
9376 @samp{make distcheck}). Other people may prefer to revamp the
9377 existing @file{Makefile}s to support VPATH@. Doing so does not
9378 necessarily require Automake, only Autoconf is needed (@pxref{Build
9379 Directories, , Build Directories, autoconf, The Autoconf Manual}).
9380 The necessary substitutions: @samp{@@srcdir@@}, @samp{@@top_srcdir@@},
9381 and @samp{@@top_builddir@@} are defined by @file{configure} when it
9382 processes a @file{Makefile} (@pxref{Preset Output Variables, , Preset
9383 Output Variables, autoconf, The Autoconf Manual}), they are not
9384 computed by the Makefile like the aforementioned @samp{$(distdir)} and
9385 @samp{$(top_distdir)} variables..
9387 It is sometimes inconvenient to modify a third-party @file{Makefile}
9388 to introduce the above required targets. For instance, one may want to
9389 keep the third-party sources untouched to ease upgrades to new
9392 @cindex @file{GNUmakefile} including @file{Makefile}
9393 Here are two other ideas. If GNU make is assumed, one possibility is
9394 to add to that subdirectory a @file{GNUmakefile} that defines the
9395 required targets and include the third-party @file{Makefile}. For
9396 this to work in VPATH builds, @file{GNUmakefile} must lie in the build
9397 directory; the easiest way to do this is to write a
9398 @file{GNUmakefile.in} instead, and have it processed with
9399 @code{AC_CONFIG_FILES} from the outer package. For example if we
9400 assume @file{Makefile} defines all targets except the documentation
9401 targets, and that the @code{check} target is actually called
9402 @code{test}, we could write @file{GNUmakefile} (or
9403 @file{GNUmakefile.in}) like this:
9406 # First, include the real Makefile
9408 # Then, define the other targets needed by Automake Makefiles.
9409 .PHONY: dvi pdf ps info html check
9410 dvi pdf ps info html:
9414 @cindex Proxy @file{Makefile} for third-party packages
9415 A similar idea that does not use @code{include} is to write a proxy
9416 @file{Makefile} that dispatches rules to the real @file{Makefile},
9417 either with @samp{$(MAKE) -f Makefile.real $(AM_MAKEFLAGS) target} (if
9418 it's OK to rename the original @file{Makefile}) or with @samp{cd
9419 subdir && $(MAKE) $(AM_MAKEFLAGS) target} (if it's OK to store the
9420 subdirectory project one directory deeper). The good news is that
9421 this proxy @file{Makefile} can be generated with Automake. All we
9422 need are @option{-local} targets (@pxref{Extending}) that perform the
9423 dispatch. Of course the other Automake features are available, so you
9424 could decide to let Automake perform distribution or installation.
9425 Here is a possible @file{Makefile.am}:
9429 cd subdir && $(MAKE) $(AM_MAKEFLAGS) all
9431 cd subdir && $(MAKE) $(AM_MAKEFLAGS) test
9433 cd subdir && $(MAKE) $(AM_MAKEFLAGS) clean
9435 # Assuming the package knows how to install itself
9437 cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-data
9439 cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-exec
9441 cd subdir && $(MAKE) $(AM_MAKEFLAGS) uninstall
9443 # Distribute files from here.
9444 EXTRA_DIST = subdir/Makefile subdir/program.c ...
9447 Pushing this idea to the extreme, it is also possible to ignore the
9448 subproject build system and build everything from this proxy
9449 @file{Makefile.am}. This might sounds very sensible if you need VPATH
9450 builds but the subproject does not support them.
9453 @chapter Distributing @file{Makefile.in}s
9455 Automake places no restrictions on the distribution of the resulting
9456 @file{Makefile.in}s. We still encourage software authors to
9457 distribute their work under terms like those of the GPL, but doing so
9458 is not required to use Automake.
9460 Some of the files that can be automatically installed via the
9461 @option{--add-missing} switch do fall under the GPL@. However, these also
9462 have a special exception allowing you to distribute them with your
9463 package, regardless of the licensing you choose.
9466 @node API versioning
9467 @chapter Automake API versioning
9469 New Automake releases usually include bug fixes and new features.
9470 Unfortunately they may also introduce new bugs and incompatibilities.
9471 This makes four reasons why a package may require a particular Automake
9474 Things get worse when maintaining a large tree of packages, each one
9475 requiring a different version of Automake. In the past, this meant that
9476 any developer (and sometime users) had to install several versions of
9477 Automake in different places, and switch @samp{$PATH} appropriately for
9480 Starting with version 1.6, Automake installs versioned binaries. This
9481 means you can install several versions of Automake in the same
9482 @samp{$prefix}, and can select an arbitrary Automake version by running
9483 @command{automake-1.6} or @command{automake-1.7} without juggling with
9484 @samp{$PATH}. Furthermore, @file{Makefile}'s generated by Automake 1.6
9485 will use @command{automake-1.6} explicitly in their rebuild rules.
9487 The number @samp{1.6} in @command{automake-1.6} is Automake's API version,
9488 not Automake's version. If a bug fix release is made, for instance
9489 Automake 1.6.1, the API version will remain 1.6. This means that a
9490 package that works with Automake 1.6 should also work with 1.6.1; after
9491 all, this is what people expect from bug fix releases.
9493 If your package relies on a feature or a bug fix introduced in
9494 a release, you can pass this version as an option to Automake to ensure
9495 older releases will not be used. For instance, use this in your
9496 @file{configure.ac}:
9499 AM_INIT_AUTOMAKE([1.6.1]) dnl Require Automake 1.6.1 or better.
9502 or, in a particular @file{Makefile.am}:
9505 AUTOMAKE_OPTIONS = 1.6.1 # Require Automake 1.6.1 or better.
9508 Automake will print an error message if its version is
9509 older than the requested version.
9512 @heading What is in the API
9514 Automake's programming interface is not easy to define. Basically it
9515 should include at least all @strong{documented} variables and targets
9516 that a @file{Makefile.am} author can use, any behavior associated with
9517 them (e.g., the places where @samp{-hook}'s are run), the command line
9518 interface of @command{automake} and @command{aclocal}, @dots{}
9520 @heading What is not in the API
9522 Every undocumented variable, target, or command line option, is not part
9523 of the API@. You should avoid using them, as they could change from one
9524 version to the other (even in bug fix releases, if this helps to fix a
9527 If it turns out you need to use such a undocumented feature, contact
9528 @email{automake@@gnu.org} and try to get it documented and exercised by
9532 @chapter Upgrading a Package to a Newer Automake Version
9534 Automake maintains three kind of files in a package.
9537 @item @file{aclocal.m4}
9538 @item @file{Makefile.in}s
9539 @item auxiliary tools like @file{install-sh} or @file{py-compile}
9542 @file{aclocal.m4} is generated by @command{aclocal} and contains some
9543 Automake-supplied M4 macros. Auxiliary tools are installed by
9544 @samp{automake --add-missing} when needed. @file{Makefile.in}s are
9545 built from @file{Makefile.am} by @command{automake}, and rely on the
9546 definitions of the M4 macros put in @file{aclocal.m4} as well as the
9547 behavior of the auxiliary tools installed.
9549 Because all these files are closely related, it is important to
9550 regenerate all of them when upgrading to a newer Automake release.
9551 The usual way to do that is
9554 aclocal # with any option needed (such a -I m4)
9556 automake --add-missing --force-missing
9560 or more conveniently:
9566 The use of @option{--force-missing} ensures that auxiliary tools will be
9567 overridden by new versions (@pxref{Invoking Automake}).
9569 It is important to regenerate all these files each time Automake is
9570 upgraded, even between bug fixes releases. For instance, it is not
9571 unusual for a bug fix to involve changes to both the rules generated
9572 in @file{Makefile.in} and the supporting M4 macros copied to
9575 Presently @command{automake} is able to diagnose situations where
9576 @file{aclocal.m4} has been generated with another version of
9577 @command{aclocal}. However it never checks whether auxiliary scripts
9578 are up-to-date. In other words, @command{automake} will tell you when
9579 @command{aclocal} needs to be rerun, but it will never diagnose a
9580 missing @option{--force-missing}.
9582 Before upgrading to a new major release, it is a good idea to read the
9583 file @file{NEWS}. This file lists all changes between releases: new
9584 features, obsolete constructs, known incompatibilities, and
9588 @chapter Frequently Asked Questions about Automake
9590 This chapter covers some questions that often come up on the mailing
9594 * CVS:: CVS and generated files
9595 * maintainer-mode:: missing and AM_MAINTAINER_MODE
9596 * wildcards:: Why doesn't Automake support wildcards?
9597 * limitations on file names:: Limitations on source and installed file names
9598 * distcleancheck:: Files left in build directory after distclean
9599 * Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS
9600 * renamed objects:: Why are object files sometimes renamed?
9601 * Per-Object Flags:: How to simulate per-object flags?
9602 * Multiple Outputs:: Writing rules for tools with many output files
9603 * Hard-Coded Install Paths:: Installing to Hard-Coded Locations
9607 @section CVS and generated files
9609 @subsection Background: distributed generated files
9610 @cindex generated files, distributed
9611 @cindex rebuild rules
9613 Packages made with Autoconf and Automake ship with some generated
9614 files like @file{configure} or @file{Makefile.in}. These files were
9615 generated on the developer's host and are distributed so that
9616 end-users do not have to install the maintainer tools required to
9617 rebuild them. Other generated files like Lex scanners, Yacc parsers,
9618 or Info documentation, are usually distributed on similar grounds.
9620 Automake outputs rules in @file{Makefile}s to rebuild these files. For
9621 instance, @command{make} will run @command{autoconf} to rebuild
9622 @file{configure} whenever @file{configure.ac} is changed. This makes
9623 development safer by ensuring a @file{configure} is never out-of-date
9624 with respect to @file{configure.ac}.
9626 As generated files shipped in packages are up-to-date, and because
9627 @command{tar} preserves times-tamps, these rebuild rules are not
9628 triggered when a user unpacks and builds a package.
9630 @subsection Background: CVS and timestamps
9631 @cindex timestamps and CVS
9632 @cindex CVS and timestamps
9634 Unless you use CVS keywords (in which case files must be updated at
9635 commit time), CVS preserves timestamp during @samp{cvs commit} and
9636 @samp{cvs import -d} operations.
9638 When you check out a file using @samp{cvs checkout} its timestamp is
9639 set to that of the revision that is being checked out.
9641 However, during @command{cvs update}, files will have the date of the
9642 update, not the original timestamp of this revision. This is meant to
9643 make sure that @command{make} notices sources files have been updated.
9645 This timestamp shift is troublesome when both sources and generated
9646 files are kept under CVS@. Because CVS processes files in lexical
9647 order, @file{configure.ac} will appear newer than @file{configure}
9648 after a @command{cvs update} that updates both files, even if
9649 @file{configure} was newer than @file{configure.ac} when it was
9650 checked in. Calling @command{make} will then trigger a spurious rebuild
9651 of @file{configure}.
9653 @subsection Living with CVS in Autoconfiscated projects
9654 @cindex CVS and generated files
9655 @cindex generated files and CVS
9657 There are basically two clans amongst maintainers: those who keep all
9658 distributed files under CVS, including generated files, and those who
9659 keep generated files @emph{out} of CVS.
9661 @subsubheading All files in CVS
9665 The CVS repository contains all distributed files so you know exactly
9666 what is distributed, and you can checkout any prior version entirely.
9669 Maintainers can see how generated files evolve (for instance, you can
9670 see what happens to your @file{Makefile.in}s when you upgrade Automake
9671 and make sure they look OK).
9674 Users do not need the autotools to build a checkout of the project, it
9675 works just like a released tarball.
9678 If users use @command{cvs update} to update their copy, instead of
9679 @command{cvs checkout} to fetch a fresh one, timestamps will be
9680 inaccurate. Some rebuild rules will be triggered and attempt to
9681 run developer tools such as @command{autoconf} or @command{automake}.
9683 Actually, calls to such tools are all wrapped into a call to the
9684 @command{missing} script discussed later (@pxref{maintainer-mode}).
9685 @command{missing} will take care of fixing the timestamps when these
9686 tools are not installed, so that the build can continue.
9689 In distributed development, developers are likely to have different
9690 version of the maintainer tools installed. In this case rebuilds
9691 triggered by timestamp lossage will lead to spurious changes
9692 to generated files. There are several solutions to this:
9696 All developers should use the same versions, so that the rebuilt files
9697 are identical to files in CVS@. (This starts to be difficult when each
9698 project you work on uses different versions.)
9700 Or people use a script to fix the timestamp after a checkout (the GCC
9701 folks have such a script).
9703 Or @file{configure.ac} uses @code{AM_MAINTAINER_MODE}, which will
9704 disable all these rebuild rules by default. This is further discussed
9705 in @ref{maintainer-mode}.
9709 Although we focused on spurious rebuilds, the converse can also
9710 happen. CVS's timestamp handling can also let you think an
9711 out-of-date file is up-to-date.
9713 For instance, suppose a developer has modified @file{Makefile.am} and
9714 has rebuilt @file{Makefile.in}. He then decide to do a last-minute
9715 change to @file{Makefile.am} right before checking in both files
9716 (without rebuilding @file{Makefile.in} to account for the change).
9718 This last change to @file{Makefile.am} make the copy of
9719 @file{Makefile.in} out-of-date. Since CVS processes files
9720 alphabetically, when another developer @samp{cvs update} his or her
9721 tree, @file{Makefile.in} will happen to be newer than
9722 @file{Makefile.am}. This other developer will not see
9723 @file{Makefile.in} is out-of-date.
9727 @subsubheading Generated files out of CVS
9729 One way to get CVS and @command{make} working peacefully is to never
9730 store generated files in CVS, i.e., do not CVS-control files that
9731 are @file{Makefile} targets (also called @emph{derived} files).
9733 This way developers are not annoyed by changes to generated files. It
9734 does not matter if they all have different versions (assuming they are
9735 compatible, of course). And finally, timestamps are not lost, changes
9736 to sources files can't be missed as in the
9737 @file{Makefile.am}/@file{Makefile.in} example discussed earlier.
9739 The drawback is that the CVS repository is not an exact copy of what
9740 is distributed and that users now need to install various development
9741 tools (maybe even specific versions) before they can build a checkout.
9742 But, after all, CVS's job is versioning, not distribution.
9744 Allowing developers to use different versions of their tools can also
9745 hide bugs during distributed development. Indeed, developers will be
9746 using (hence testing) their own generated files, instead of the
9747 generated files that will be released actually. The developer who
9748 prepares the tarball might be using a version of the tool that
9749 produces bogus output (for instance a non-portable C file), something
9750 other developers could have noticed if they weren't using their own
9751 versions of this tool.
9753 @subsection Third-party files
9754 @cindex CVS and third-party files
9755 @cindex third-party files and CVS
9757 Another class of files not discussed here (because they do not cause
9758 timestamp issues) are files that are shipped with a package, but
9759 maintained elsewhere. For instance, tools like @command{gettextize}
9760 and @command{autopoint} (from Gettext) or @command{libtoolize} (from
9761 Libtool), will install or update files in your package.
9763 These files, whether they are kept under CVS or not, raise similar
9764 concerns about version mismatch between developers' tools. The
9765 Gettext manual has a section about this, see @ref{CVS Issues, CVS
9766 Issues, Integrating with CVS, gettext, GNU gettext tools}.
9768 @node maintainer-mode
9769 @section @command{missing} and @code{AM_MAINTAINER_MODE}
9771 @subsection @command{missing}
9772 @cindex @command{missing}, purpose
9774 The @command{missing} script is a wrapper around several maintainer
9775 tools, designed to warn users if a maintainer tool is required but
9776 missing. Typical maintainer tools are @command{autoconf},
9777 @command{automake}, @command{bison}, etc. Because file generated by
9778 these tools are shipped with the other sources of a package, these
9779 tools shouldn't be required during a user build and they are not
9780 checked for in @file{configure}.
9782 However, if for some reason a rebuild rule is triggered and involves a
9783 missing tool, @command{missing} will notice it and warn the user.
9784 Besides the warning, when a tool is missing, @command{missing} will
9785 attempt to fix timestamps in a way that allows the build to continue.
9786 For instance, @command{missing} will touch @file{configure} if
9787 @command{autoconf} is not installed. When all distributed files are
9788 kept under CVS, this feature of @command{missing} allows user
9789 @emph{with no maintainer tools} to build a package off CVS, bypassing
9790 any timestamp inconsistency implied by @samp{cvs update}.
9792 If the required tool is installed, @command{missing} will run it and
9793 won't attempt to continue after failures. This is correct during
9794 development: developers love fixing failures. However, users with
9795 wrong versions of maintainer tools may get an error when the rebuild
9796 rule is spuriously triggered, halting the build. This failure to let
9797 the build continue is one of the arguments of the
9798 @code{AM_MAINTAINER_MODE} advocates.
9800 @subsection @code{AM_MAINTAINER_MODE}
9801 @cindex @code{AM_MAINTAINER_MODE}, purpose
9802 @acindex AM_MAINTAINER_MODE
9804 @code{AM_MAINTAINER_MODE} disables the so called "rebuild rules" by
9805 default. If you have @code{AM_MAINTAINER_MODE} in
9806 @file{configure.ac}, and run @samp{./configure && make}, then
9807 @command{make} will *never* attempt to rebuilt @file{configure},
9808 @file{Makefile.in}s, Lex or Yacc outputs, etc. I.e., this disables
9809 build rules for files that are usually distributed and that users
9810 should normally not have to update.
9812 If you run @samp{./configure --enable-maintainer-mode}, then these
9813 rebuild rules will be active.
9815 People use @code{AM_MAINTAINER_MODE} either because they do want their
9816 users (or themselves) annoyed by timestamps lossage (@pxref{CVS}), or
9817 because they simply can't stand the rebuild rules and prefer running
9818 maintainer tools explicitly.
9820 @code{AM_MAINTAINER_MODE} also allows you to disable some custom build
9821 rules conditionally. Some developers use this feature to disable
9822 rules that need exotic tools that users may not have available.
9824 Several years ago Fran@,{c}ois Pinard pointed out several arguments
9825 against this @code{AM_MAINTAINER_MODE} macro. Most of them relate to
9826 insecurity. By removing dependencies you get non-dependable builds:
9827 change to sources files can have no effect on generated files and this
9828 can be very confusing when unnoticed. He adds that security shouldn't
9829 be reserved to maintainers (what @option{--enable-maintainer-mode}
9830 suggests), on the contrary. If one user has to modify a
9831 @file{Makefile.am}, then either @file{Makefile.in} should be updated
9832 or a warning should be output (this is what Automake uses
9833 @command{missing} for) but the last thing you want is that nothing
9834 happens and the user doesn't notice it (this is what happens when
9835 rebuild rules are disabled by @code{AM_MAINTAINER_MODE}).
9837 Jim Meyering, the inventor of the @code{AM_MAINTAINER_MODE} macro was
9838 swayed by Fran@,{c}ois's arguments, and got rid of
9839 @code{AM_MAINTAINER_MODE} in all of his packages.
9841 Still many people continue to use @code{AM_MAINTAINER_MODE}, because
9842 it helps them working on projects where all files are kept under CVS,
9843 and because @command{missing} isn't enough if you have the wrong
9844 version of the tools.
9848 @section Why doesn't Automake support wildcards?
9851 Developers are lazy. They would often like to use wildcards in
9852 @file{Makefile.am}s, so that they would not need to remember to
9853 update @file{Makefile.am}s every time they add, delete, or rename
9856 There are several objections to this:
9859 When using CVS (or similar) developers need to remember they have to
9860 run @samp{cvs add} or @samp{cvs rm} anyway. Updating
9861 @file{Makefile.am} accordingly quickly becomes a reflex.
9863 Conversely, if your application doesn't compile
9864 because you forgot to add a file in @file{Makefile.am}, it will help
9865 you remember to @samp{cvs add} it.
9868 Using wildcards makes it easy to distribute files by mistake. For
9869 instance, some code a developer is experimenting with (a test case,
9870 say) that should not be part of the distribution.
9873 Using wildcards it's easy to omit some files by mistake. For
9874 instance, one developer creates a new file, uses it in many places,
9875 but forgets to commit it. Another developer then checks out the
9876 incomplete project and is able to run @samp{make dist} successfully,
9877 even though a file is missing. By listing files, @samp{make dist}
9878 @emph{will} complain.
9881 Finally, it's really hard to @emph{forget} to add a file to
9882 @file{Makefile.am}: files that are not listed in @file{Makefile.am} are
9883 not compiled or installed, so you can't even test them.
9886 Still, these are philosophical objections, and as such you may disagree,
9887 or find enough value in wildcards to dismiss all of them. Before you
9888 start writing a patch against Automake to teach it about wildcards,
9889 let's see the main technical issue: portability.
9891 Although @samp{$(wildcard ...)} works with GNU @command{make}, it is
9892 not portable to other @command{make} implementations.
9894 The only way Automake could support @command{$(wildcard ...)} is by
9895 expending @command{$(wildcard ...)} when @command{automake} is run.
9896 The resulting @file{Makefile.in}s would be portable since they would
9897 list all files and not use @samp{$(wildcard ...)}. However that
9898 means developers would need to remember to run @command{automake} each
9899 time they add, delete, or rename files.
9901 Compared to editing @file{Makefile.am}, this is a very small gain. Sure,
9902 it's easier and faster to type @samp{automake; make} than to type
9903 @samp{emacs Makefile.am; make}. But nobody bothered enough to write a
9904 patch to add support for this syntax. Some people use scripts to
9905 generate file lists in @file{Makefile.am} or in separate
9906 @file{Makefile} fragments.
9908 Even if you don't care about portability, and are tempted to use
9909 @samp{$(wildcard ...)} anyway because you target only GNU Make, you
9910 should know there are many places where Automake need to know exactly
9911 which files should be processed. As Automake doesn't know how to
9912 expand @samp{$(wildcard ...)}, you cannot use it in these places.
9913 @samp{$(wildcard ...)} is a black box comparable to @code{AC_SUBST}ed
9914 variables as far Automake is concerned.
9916 You can get warnings about @samp{$(wildcard ...}) constructs using the
9917 @option{-Wportability} flag.
9919 @node limitations on file names
9920 @section Limitations on file names
9921 @cindex file names, limitations on
9923 Automake attempts to support all kinds of file names, even those that
9924 contain unusual characters or are unusually long. However, some
9925 limitations are imposed by the underlying operating system and tools.
9927 Most operating systems prohibit the use of the null byte in file
9928 names, and reserve @samp{/} as a directory separator. Also, they
9929 require that file names are properly encoded for the user's locale.
9930 Automake is subject to these limits.
9932 Portable packages should limit themselves to @acronym{POSIX} file
9933 names. These can contain @acronym{ASCII} letters and digits,
9934 @samp{_}, @samp{.}, and @samp{-}. File names consist of components
9935 separated by @samp{/}. File name components cannot begin with
9938 Portable POSIX file names cannot contain components that exceed a
9939 14-byte limit, but nowadays it's normally safe to assume the
9940 more-generous @acronym{XOPEN} limit of 255 bytes. @acronym{POSIX}
9941 limits file names to 255 bytes (@acronym{XOPEN} allows 1023 bytes),
9942 but you may want to limit a source tarball to file names to 99 bytes
9943 to avoid interoperability problems with old versions of @command{tar}.
9945 If you depart from these rules (e.g., by using non-@acronym{ASCII}
9946 characters in file names, or by using lengthy file names), your
9947 installers may have problems for reasons unrelated to Automake.
9948 However, if this does not concern you, you should know about the
9949 limitations imposed by Automake itself. These limitations are
9950 undesirable, but some of them seem to be inherent to underlying tools
9951 like Autoconf, Make, M4, and the shell. They fall into three
9952 categories: install directories, build directories, and file names.
9954 The following characters:
9957 @r{newline} " # $ ' `
9960 should not appear in the names of install directories. For example,
9961 the operand of @command{configure}'s @option{--prefix} option should
9962 not contain these characters.
9964 Build directories suffer the same limitations as install directories,
9965 and in addition should not contain the following characters:
9971 For example, the full name of the directory containing the source
9972 files should not contain these characters.
9974 Source and installation file names like @file{main.c} are limited even
9975 further: they should conform to the @acronym{POSIX}/@acronym{XOPEN}
9976 rules described above. In addition, if you plan to port to
9977 non-@acronym{POSIX} environments, you should avoid file names that
9978 differ only in case (e.g., @file{makefile} and @file{Makefile}).
9979 Nowadays it is no longer worth worrying about the 8.3 limits of
9980 @acronym{DOS} file systems.
9982 @node distcleancheck
9983 @section Files left in build directory after distclean
9984 @cindex @code{distclean}, diagnostic
9985 @cindex @samp{make distclean}, diagnostic
9986 @cindex dependencies and distributed files
9988 @trindex distcleancheck
9990 This is a diagnostic you might encounter while running @samp{make
9993 As explained in @ref{Dist}, @samp{make distcheck} attempts to build
9994 and check your package for errors like this one.
9996 @samp{make distcheck} will perform a @code{VPATH} build of your
9997 package (@pxref{VPATH Builds}), and then call @samp{make distclean}.
9998 Files left in the build directory after @samp{make distclean} has run
9999 are listed after this error.
10001 This diagnostic really covers two kinds of errors:
10005 files that are forgotten by distclean;
10007 distributed files that are erroneously rebuilt.
10010 The former left-over files are not distributed, so the fix is to mark
10011 them for cleaning (@pxref{Clean}), this is obvious and doesn't deserve
10014 The latter bug is not always easy to understand and fix, so let's
10015 proceed with an example. Suppose our package contains a program for
10016 which we want to build a man page using @command{help2man}. GNU
10017 @command{help2man} produces simple manual pages from the @option{--help}
10018 and @option{--version} output of other commands (@pxref{Top, , Overview,
10019 help2man, The Help2man Manual}). Because we don't to force want our
10020 users to install @command{help2man}, we decide to distribute the
10021 generated man page using the following setup.
10024 # This Makefile.am is bogus.
10026 foo_SOURCES = foo.c
10027 dist_man_MANS = foo.1
10029 foo.1: foo$(EXEEXT)
10030 help2man --output=foo.1 ./foo$(EXEEXT)
10033 This will effectively distribute the man page. However,
10034 @samp{make distcheck} will fail with:
10037 ERROR: files left in build directory after distclean:
10041 Why was @file{foo.1} rebuilt? Because although distributed,
10042 @file{foo.1} depends on a non-distributed built file:
10043 @file{foo$(EXEEXT)}. @file{foo$(EXEEXT)} is built by the user, so it
10044 will always appear to be newer than the distributed @file{foo.1}.
10046 @samp{make distcheck} caught an inconsistency in our package. Our
10047 intent was to distribute @file{foo.1} so users do not need installing
10048 @command{help2man}, however since this our rule causes this file to be
10049 always rebuilt, users @emph{do} need @command{help2man}. Either we
10050 should ensure that @file{foo.1} is not rebuilt by users, or there is
10051 no point in distributing @file{foo.1}.
10053 More generally, the rule is that distributed files should never depend
10054 on non-distributed built files. If you distribute something
10055 generated, distribute its sources.
10057 One way to fix the above example, while still distributing
10058 @file{foo.1} is to not depend on @file{foo$(EXEEXT)}. For instance,
10059 assuming @command{foo --version} and @command{foo --help} do not
10060 change unless @file{foo.c} or @file{configure.ac} change, we could
10061 write the following @file{Makefile.am}:
10065 foo_SOURCES = foo.c
10066 dist_man_MANS = foo.1
10068 foo.1: foo.c $(top_srcdir)/configure.ac
10069 $(MAKE) $(AM_MAKEFLAGS) foo$(EXEEXT)
10070 help2man --output=foo.1 ./foo$(EXEEXT)
10073 This way, @file{foo.1} will not get rebuilt every time
10074 @file{foo$(EXEEXT)} changes. The @command{make} call makes sure
10075 @file{foo$(EXEEXT)} is up-to-date before @command{help2man}. Another
10076 way to ensure this would be to use separate directories for binaries
10077 and man pages, and set @code{SUBDIRS} so that binaries are built
10080 We could also decide not to distribute @file{foo.1}. In
10081 this case it's fine to have @file{foo.1} dependent upon
10082 @file{foo$(EXEEXT)}, since both will have to be rebuilt.
10083 However it would be impossible to build the package in a
10084 cross-compilation, because building @file{foo.1} involves
10085 an @emph{execution} of @file{foo$(EXEEXT)}.
10087 Another context where such errors are common is when distributed files
10088 are built by tools that are built by the package. The pattern is
10092 distributed-file: built-tools distributed-sources
10097 should be changed to
10100 distributed-file: distributed-sources
10101 $(MAKE) $(AM_MAKEFLAGS) built-tools
10106 or you could choose not to distribute @file{distributed-file}, if
10107 cross-compilation does not matter.
10109 The points made through these examples are worth a summary:
10114 Distributed files should never depend upon non-distributed built
10117 Distributed files should be distributed with all their dependencies.
10119 If a file is @emph{intended} to be rebuilt by users, then there is no point
10120 in distributing it.
10124 @vrindex distcleancheck_listfiles
10125 For desperate cases, it's always possible to disable this check by
10126 setting @code{distcleancheck_listfiles} as documented in @ref{Dist}.
10127 Make sure you do understand the reason why @samp{make distcheck}
10128 complains before you do this. @code{distcleancheck_listfiles} is a
10129 way to @emph{hide} errors, not to fix them. You can always do better.
10131 @node Flag Variables Ordering
10132 @section Flag Variables Ordering
10133 @cindex Ordering flag variables
10134 @cindex Flag variables, ordering
10137 What is the difference between @code{AM_CFLAGS}, @code{CFLAGS}, and
10138 @code{mumble_CFLAGS}?
10142 Why does @command{automake} output @code{CPPFLAGS} after
10143 @code{AM_CPPFLAGS} on compile lines? Shouldn't it be the converse?
10147 My @file{configure} adds some warning flags into @code{CXXFLAGS}. In
10148 one @file{Makefile.am} I would like to append a new flag, however if I
10149 put the flag into @code{AM_CXXFLAGS} it is prepended to the other
10150 flags, not appended.
10153 @subsection Compile Flag Variables
10154 @cindex Flag Variables, Ordering
10155 @cindex Compile Flag Variables
10156 @cindex @code{AM_CCASFLAGS} and @code{CCASFLAGS}
10157 @cindex @code{AM_CFLAGS} and @code{CFLAGS}
10158 @cindex @code{AM_CPPFLAGS} and @code{CPPFLAGS}
10159 @cindex @code{AM_CXXFLAGS} and @code{CXXFLAGS}
10160 @cindex @code{AM_FCFLAGS} and @code{FCFLAGS}
10161 @cindex @code{AM_FFLAGS} and @code{FFLAGS}
10162 @cindex @code{AM_GCJFLAGS} and @code{GCJFLAGS}
10163 @cindex @code{AM_LDFLAGS} and @code{LDFLAGS}
10164 @cindex @code{AM_LFLAGS} and @code{LFLAGS}
10165 @cindex @code{AM_LIBTOOLFLAGS} and @code{LIBTOOLFLAGS}
10166 @cindex @code{AM_OBJCFLAGS} and @code{OBJCFLAGS}
10167 @cindex @code{AM_RFLAGS} and @code{RFLAGS}
10168 @cindex @code{AM_UPCFLAGS} and @code{UPCFLAGS}
10169 @cindex @code{AM_YFLAGS} and @code{YFLAGS}
10170 @cindex @code{CCASFLAGS} and @code{AM_CCASFLAGS}
10171 @cindex @code{CFLAGS} and @code{AM_CFLAGS}
10172 @cindex @code{CPPFLAGS} and @code{AM_CPPFLAGS}
10173 @cindex @code{CXXFLAGS} and @code{AM_CXXFLAGS}
10174 @cindex @code{FCFLAGS} and @code{AM_FCFLAGS}
10175 @cindex @code{FFLAGS} and @code{AM_FFLAGS}
10176 @cindex @code{GCJFLAGS} and @code{AM_GCJFLAGS}
10177 @cindex @code{LDFLAGS} and @code{AM_LDFLAGS}
10178 @cindex @code{LFLAGS} and @code{AM_LFLAGS}
10179 @cindex @code{LIBTOOLFLAGS} and @code{AM_LIBTOOLFLAGS}
10180 @cindex @code{OBJCFLAGS} and @code{AM_OBJCFLAGS}
10181 @cindex @code{RFLAGS} and @code{AM_RFLAGS}
10182 @cindex @code{UPCFLAGS} and @code{AM_UPCFLAGS}
10183 @cindex @code{YFLAGS} and @code{AM_YFLAGS}
10185 This section attempts to answer all the above questions. We will
10186 mostly discuss @code{CPPFLAGS} in our examples, but actually the
10187 answer holds for all the compile flags used in Automake:
10188 @code{CCASFLAGS}, @code{CFLAGS}, @code{CPPFLAGS}, @code{CXXFLAGS},
10189 @code{FCFLAGS}, @code{FFLAGS}, @code{GCJFLAGS}, @code{LDFLAGS},
10190 @code{LFLAGS}, @code{LIBTOOLFLAGS}, @code{OBJCFLAGS}, @code{RFLAGS},
10191 @code{UPCFLAGS}, and @code{YFLAGS}.
10193 @code{CPPFLAGS}, @code{AM_CPPFLAGS}, and @code{mumble_CPPFLAGS} are
10194 three variables that can be used to pass flags to the C preprocessor
10195 (actually these variables are also used for other languages like C++
10196 or preprocessed Fortran). @code{CPPFLAGS} is the user variable
10197 (@pxref{User Variables}), @code{AM_CPPFLAGS} is the Automake variable,
10198 and @code{mumble_CPPFLAGS} is the variable specific to the
10199 @code{mumble} target (we call this a per-target variable,
10200 @pxref{Program and Library Variables}).
10202 Automake always uses two of these variables when compiling C sources
10203 files. When compiling an object file for the @code{mumble} target,
10204 the first variable will be @code{mumble_CPPFLAGS} if it is defined, or
10205 @code{AM_CPPFLAGS} otherwise. The second variable is always
10208 In the following example,
10211 bin_PROGRAMS = foo bar
10212 foo_SOURCES = xyz.c
10213 bar_SOURCES = main.c
10214 foo_CPPFLAGS = -DFOO
10215 AM_CPPFLAGS = -DBAZ
10219 @file{xyz.o} will be compiled with @samp{$(foo_CPPFLAGS) $(CPPFLAGS)},
10220 (because @file{xyz.o} is part of the @code{foo} target), while
10221 @file{main.o} will be compiled with @samp{$(AM_CPPFLAGS) $(CPPFLAGS)}
10222 (because there is no per-target variable for target @code{bar}).
10224 The difference between @code{mumble_CPPFLAGS} and @code{AM_CPPFLAGS}
10225 being clear enough, let's focus on @code{CPPFLAGS}. @code{CPPFLAGS}
10226 is a user variable, i.e., a variable that users are entitled to modify
10227 in order to compile the package. This variable, like many others,
10228 is documented at the end of the output of @samp{configure --help}.
10230 For instance, someone who needs to add @file{/home/my/usr/include} to
10231 the C compiler's search path would configure a package with
10234 ./configure CPPFLAGS='-I /home/my/usr/include'
10238 and this flag would be propagated to the compile rules of all
10241 It is also not uncommon to override a user variable at
10242 @command{make}-time. Many installers do this with @code{prefix}, but
10243 this can be useful with compiler flags too. For instance, if, while
10244 debugging a C++ project, you need to disable optimization in one
10245 specific object file, you can run something like
10249 make CXXFLAGS=-O0 file.o
10253 The reason @samp{$(CPPFLAGS)} appears after @samp{$(AM_CPPFLAGS)} or
10254 @samp{$(mumble_CPPFLAGS)} in the compile command is that users
10255 should always have the last say. It probably makes more sense if you
10256 think about it while looking at the @samp{CXXFLAGS=-O0} above, which
10257 should supersede any other switch from @code{AM_CXXFLAGS} or
10258 @code{mumble_CXXFLAGS} (and this of course replaces the previous value
10259 of @code{CXXFLAGS}).
10261 You should never redefine a user variable such as @code{CPPFLAGS} in
10262 @file{Makefile.am}. Use @samp{automake -Woverride} to diagnose such
10263 mistakes. Even something like
10266 CPPFLAGS = -DDATADIR=\"$(datadir)\" @@CPPFLAGS@@
10270 is erroneous. Although this preserves @file{configure}'s value of
10271 @code{CPPFLAGS}, the definition of @code{DATADIR} will disappear if a
10272 user attempts to override @code{CPPFLAGS} from the @command{make}
10276 AM_CPPFLAGS = -DDATADIR=\"$(datadir)\"
10280 is all what is needed here if no per-target flags are used.
10282 You should not add options to these user variables within
10283 @file{configure} either, for the same reason. Occasionally you need
10284 to modify these variables to perform a test, but you should reset
10285 their values afterwards. In contrast, it is OK to modify the
10286 @samp{AM_} variables within @file{configure} if you @code{AC_SUBST}
10287 them, but it is rather rare that you need to do this, unless you
10288 really want to change the default definitions of the @samp{AM_}
10289 variables in all @file{Makefile}s.
10291 What we recommend is that you define extra flags in separate
10292 variables. For instance, you may write an Autoconf macro that computes
10293 a set of warning options for the C compiler, and @code{AC_SUBST} them
10294 in @code{WARNINGCFLAGS}; you may also have an Autoconf macro that
10295 determines which compiler and which linker flags should be used to
10296 link with library @file{libfoo}, and @code{AC_SUBST} these in
10297 @code{LIBFOOCFLAGS} and @code{LIBFOOLDFLAGS}. Then, a
10298 @file{Makefile.am} could use these variables as follows:
10301 AM_CFLAGS = $(WARNINGCFLAGS)
10302 bin_PROGRAMS = prog1 prog2
10303 prog1_SOURCES = @dots{}
10304 prog2_SOURCES = @dots{}
10305 prog2_CFLAGS = $(LIBFOOCFLAGS) $(AM_CFLAGS)
10306 prog2_LDFLAGS = $(LIBFOOLDFLAGS)
10309 In this example both programs will be compiled with the flags
10310 substituted into @samp{$(WARNINGCFLAGS)}, and @code{prog2} will
10311 additionally be compiled with the flags required to link with
10314 Note that listing @code{AM_CFLAGS} in a per-target @code{CFLAGS}
10315 variable is a common idiom to ensure that @code{AM_CFLAGS} applies to
10316 every target in a @file{Makefile.in}.
10318 Using variables like this gives you full control over the ordering of
10319 the flags. For instance, if there is a flag in $(WARNINGCFLAGS) that
10320 you want to negate for a particular target, you can use something like
10321 @samp{prog1_CFLAGS = $(AM_CFLAGS) -no-flag}. If all these flags had
10322 been forcefully appended to @code{CFLAGS}, there would be no way to
10323 disable one flag. Yet another reason to leave user variables to
10326 Finally, we have avoided naming the variable of the example
10327 @code{LIBFOO_LDFLAGS} (with an underscore) because that would cause
10328 Automake to think that this is actually a per-target variable (like
10329 @code{mumble_LDFLAGS}) for some non-declared @code{LIBFOO} target.
10331 @subsection Other Variables
10333 There are other variables in Automake that follow similar principles
10334 to allow user options. For instance, Texinfo rules (@pxref{Texinfo})
10335 use @code{MAKEINFOFLAGS} and @code{AM_MAKEINFOFLAGS}. Similarly,
10336 DejaGnu tests (@pxref{Tests}) use @code{RUNTESTDEFAULTFLAGS} and
10337 @code{AM_RUNTESTDEFAULTFLAGS}. The tags and ctags rules
10338 (@pxref{Tags}) use @code{ETAGSFLAGS}, @code{AM_ETAGSFLAGS},
10339 @code{CTAGSFLAGS}, and @code{AM_CTAGSFLAGS}. Java rules
10340 (@pxref{Java}) use @code{JAVACFLAGS} and @code{AM_JAVACFLAGS}. None
10341 of these rules do support per-target flags (yet).
10343 To some extent, even @code{AM_MAKEFLAGS} (@pxref{Subdirectories})
10344 obeys this naming scheme. The slight difference is that
10345 @code{MAKEFLAGS} is passed to sub-@command{make}s implicitly by
10346 @command{make} itself.
10348 However you should not think that all variables ending with
10349 @code{FLAGS} follow this convention. For instance,
10350 @code{DISTCHECK_CONFIGURE_FLAGS} (@pxref{Dist}),
10351 @code{ACLOCAL_AMFLAGS} (see @ref{Rebuilding} and @ref{Local Macros}),
10352 are two variables that are only useful to the maintainer and have no
10355 @code{ARFLAGS} (@pxref{A Library}) is usually defined by Automake and
10356 has neither @code{AM_} nor per-target cousin.
10358 Finally you should not think either that the existence of a per-target
10359 variable implies that of an @code{AM_} variable or that of a user
10360 variable. For instance, the @code{mumble_LDADD} per-target variable
10361 overrides the global @code{LDADD} variable (which is not a user
10362 variable), and @code{mumble_LIBADD} exists only as a per-target
10363 variable. @xref{Program and Library Variables}.
10366 @node renamed objects
10367 @section Why are object files sometimes renamed?
10369 This happens when per-target compilation flags are used. Object
10370 files need to be renamed just in case they would clash with object
10371 files compiled from the same sources, but with different flags.
10372 Consider the following example.
10375 bin_PROGRAMS = true false
10376 true_SOURCES = generic.c
10377 true_CPPFLAGS = -DEXIT_CODE=0
10378 false_SOURCES = generic.c
10379 false_CPPFLAGS = -DEXIT_CODE=1
10382 Obviously the two programs are built from the same source, but it
10383 would be bad if they shared the same object, because @file{generic.o}
10384 cannot be built with both @samp{-DEXIT_CODE=0} @emph{and}
10385 @samp{-DEXIT_CODE=1}. Therefore @command{automake} outputs rules to
10386 build two different objects: @file{true-generic.o} and
10387 @file{false-generic.o}.
10389 @command{automake} doesn't actually look whether source files are
10390 shared to decide if it must rename objects. It will just rename all
10391 objects of a target as soon as it sees per-target compilation flags
10394 It's OK to share object files when per-target compilation flags are not
10395 used. For instance, @file{true} and @file{false} will both use
10396 @file{version.o} in the following example.
10399 AM_CPPFLAGS = -DVERSION=1.0
10400 bin_PROGRAMS = true false
10401 true_SOURCES = true.c version.c
10402 false_SOURCES = false.c version.c
10405 Note that the renaming of objects is also affected by the
10406 @code{_SHORTNAME} variable (@pxref{Program and Library Variables}).
10409 @node Per-Object Flags
10410 @section Per-Object Flags Emulation
10411 @cindex Per-object flags, emulated
10414 One of my source files needs to be compiled with different flags. How
10418 Automake supports per-program and per-library compilation flags (see
10419 @ref{Program and Library Variables} and @ref{Flag Variables
10420 Ordering}). With this you can define compilation flags that apply to
10421 all files compiled for a target. For instance, in
10425 foo_SOURCES = foo.c foo.h bar.c bar.h main.c
10426 foo_CFLAGS = -some -flags
10430 @file{foo-foo.o}, @file{foo-bar.o}, and @file{foo-main.o} will all be
10431 compiled with @samp{-some -flags}. (If you wonder about the names of
10432 these object files, see @ref{renamed objects}.) Note that
10433 @code{foo_CFLAGS} gives the flags to use when compiling all the C
10434 sources of the @emph{program} @code{foo}, it has nothing to do with
10435 @file{foo.c} or @file{foo-foo.o} specifically.
10437 What if @file{foo.c} needs to be compiled into @file{foo.o} using some
10438 specific flags, that none of the other files require? Obviously
10439 per-program flags are not directly applicable here. Something like
10440 per-object flags are expected, i.e., flags that would be used only
10441 when creating @file{foo-foo.o}. Automake does not support that,
10442 however this is easy to simulate using a library that contains only
10443 that object, and compiling this library with per-library flags.
10447 foo_SOURCES = bar.c bar.h main.c
10448 foo_CFLAGS = -some -flags
10449 foo_LDADD = libfoo.a
10450 noinst_LIBRARIES = libfoo.a
10451 libfoo_a_SOURCES = foo.c foo.h
10452 libfoo_a_CFLAGS = -some -other -flags
10455 Here @file{foo-bar.o} and @file{foo-main.o} will all be
10456 compiled with @samp{-some -flags}, while @file{libfoo_a-foo.o} will
10457 be compiled using @samp{-some -other -flags}. Eventually, all
10458 three objects will be linked to form @file{foo}.
10460 This trick can also be achieved using Libtool convenience libraries,
10461 for instance @samp{noinst_LTLIBRARIES = libfoo.la} (@pxref{Libtool
10462 Convenience Libraries}).
10464 Another tempting idea to implement per-object flags is to override the
10465 compile rules @command{automake} would output for these files.
10466 Automake will not define a rule for a target you have defined, so you
10467 could think about defining the @samp{foo-foo.o: foo.c} rule yourself.
10468 We recommend against this, because this is error prone. For instance,
10469 if you add such a rule to the first example, it will break the day you
10470 decide to remove @code{foo_CFLAGS} (because @file{foo.c} will then be
10471 compiled as @file{foo.o} instead of @file{foo-foo.o}, @pxref{renamed
10472 objects}). Also in order to support dependency tracking, the two
10473 @file{.o}/@file{.obj} extensions, and all the other flags variables
10474 involved in a compilation, you will end up modifying a copy of the
10475 rule previously output by @command{automake} for this file. If a new
10476 release of Automake generates a different rule, your copy will need to
10477 be updated by hand.
10479 @node Multiple Outputs
10480 @section Handling Tools that Produce Many Outputs
10481 @cindex multiple outputs, rules with
10482 @cindex many outputs, rules with
10483 @cindex rules with multiple outputs
10485 This section describes a @command{make} idiom that can be used when a
10486 tool produces multiple output files. It is not specific to Automake
10487 and can be used in ordinary @file{Makefile}s.
10489 Suppose we have a program called @command{foo} that will read one file
10490 called @file{data.foo} and produce two files named @file{data.c} and
10491 @file{data.h}. We want to write a @file{Makefile} rule that captures
10492 this one-to-two dependency.
10494 The naive rule is incorrect:
10497 # This is incorrect.
10498 data.c data.h: data.foo
10503 What the above rule really says is that @file{data.c} and
10504 @file{data.h} each depend on @file{data.foo}, and can each be built by
10505 running @samp{foo data.foo}. In other words it is equivalent to:
10508 # We do not want this.
10516 which means that @command{foo} can be run twice. Usually it will not
10517 be run twice, because @command{make} implementations are smart enough
10518 to check for the existence of the second file after the first one has
10519 been built; they will therefore detect that it already exists.
10520 However there are a few situations where it can run twice anyway:
10524 The most worrying case is when running a parallel @command{make}. If
10525 @file{data.c} and @file{data.h} are built in parallel, two @samp{foo
10526 data.foo} commands will run concurrently. This is harmful.
10528 Another case is when the dependency (here @file{data.foo}) is
10529 (or depends upon) a phony target.
10532 A solution that works with parallel @command{make} but not with
10533 phony dependencies is the following:
10536 data.c data.h: data.foo
10542 The above rules are equivalent to
10547 data.h: data.foo data.c
10551 therefore a parallel @command{make} will have to serialize the builds
10552 of @file{data.c} and @file{data.h}, and will detect that the second is
10553 no longer needed once the first is over.
10555 Using this pattern is probably enough for most cases. However it does
10556 not scale easily to more output files (in this scheme all output files
10557 must be totally ordered by the dependency relation), so we will
10558 explore a more complicated solution.
10560 Another idea is to write the following:
10563 # There is still a problem with this one.
10570 The idea is that @samp{foo data.foo} is run only when @file{data.c}
10571 needs to be updated, but we further state that @file{data.h} depends
10572 upon @file{data.c}. That way, if @file{data.h} is required and
10573 @file{data.foo} is out of date, the dependency on @file{data.c} will
10576 This is almost perfect, but suppose we have built @file{data.h} and
10577 @file{data.c}, and then we erase @file{data.h}. Then, running
10578 @samp{make data.h} will not rebuild @file{data.h}. The above rules
10579 just state that @file{data.c} must be up-to-date with respect to
10580 @file{data.foo}, and this is already the case.
10582 What we need is a rule that forces a rebuild when @file{data.h} is
10583 missing. Here it is:
10589 ## Recover from the removal of $@@
10590 @@if test -f $@@; then :; else \
10592 $(MAKE) $(AM_MAKEFLAGS) data.c; \
10596 The above scheme can be extended to handle more outputs and more
10597 inputs. One of the outputs is selected to serve as a witness to the
10598 successful completion of the command, it depends upon all inputs, and
10599 all other outputs depend upon it. For instance, if @command{foo}
10600 should additionally read @file{data.bar} and also produce
10601 @file{data.w} and @file{data.x}, we would write:
10604 data.c: data.foo data.bar
10605 foo data.foo data.bar
10606 data.h data.w data.x: data.c
10607 ## Recover from the removal of $@@
10608 @@if test -f $@@; then :; else \
10610 $(MAKE) $(AM_MAKEFLAGS) data.c; \
10614 However there are now two minor problems in this setup. One is related
10615 to the timestamp ordering of @file{data.h}, @file{data.w},
10616 @file{data.x}, and @file{data.c}. The other one is a race condition
10617 if a parallel @command{make} attempts to run multiple instances of the
10618 recover block at once.
10620 Let us deal with the first problem. @command{foo} outputs four files,
10621 but we do not know in which order these files are created. Suppose
10622 that @file{data.h} is created before @file{data.c}. Then we have a
10623 weird situation. The next time @command{make} is run, @file{data.h}
10624 will appear older than @file{data.c}, the second rule will be
10625 triggered, a shell will be started to execute the @samp{if@dots{}fi}
10626 command, but actually it will just execute the @code{then} branch,
10627 that is: nothing. In other words, because the witness we selected is
10628 not the first file created by @command{foo}, @command{make} will start
10629 a shell to do nothing each time it is run.
10631 A simple riposte is to fix the timestamps when this happens.
10634 data.c: data.foo data.bar
10635 foo data.foo data.bar
10636 data.h data.w data.x: data.c
10637 @@if test -f $@@; then \
10640 ## Recover from the removal of $@@
10642 $(MAKE) $(AM_MAKEFLAGS) data.c; \
10646 Another solution is to use a different and dedicated file as witness,
10647 rather than using any of @command{foo}'s outputs.
10650 data.stamp: data.foo data.bar
10653 foo data.foo data.bar
10654 @@mv -f data.tmp $@@
10655 data.c data.h data.w data.x: data.stamp
10656 ## Recover from the removal of $@@
10657 @@if test -f $@@; then :; else \
10658 rm -f data.stamp; \
10659 $(MAKE) $(AM_MAKEFLAGS) data.stamp; \
10663 @file{data.tmp} is created before @command{foo} is run, so it has a
10664 timestamp older than output files output by @command{foo}. It is then
10665 renamed to @file{data.stamp} after @command{foo} has run, because we
10666 do not want to update @file{data.stamp} if @command{foo} fails.
10668 This solution still suffers from the second problem: the race
10669 condition in the recover rule. If, after a successful build, a user
10670 erases @file{data.c} and @file{data.h}, and runs @samp{make -j}, then
10671 @command{make} may start both recover rules in parallel. If the two
10672 instances of the rule execute @samp{$(MAKE) $(AM_MAKEFLAGS)
10673 data.stamp} concurrently the build is likely to fail (for instance, the
10674 two rules will create @file{data.tmp}, but only one can rename it).
10676 Admittedly, such a weird situation does not arise during ordinary
10677 builds. It occurs only when the build tree is mutilated. Here
10678 @file{data.c} and @file{data.h} have been explicitly removed without
10679 also removing @file{data.stamp} and the other output files.
10680 @code{make clean; make} will always recover from these situations even
10681 with parallel makes, so you may decide that the recover rule is solely
10682 to help non-parallel make users and leave things as-is. Fixing this
10683 requires some locking mechanism to ensure only one instance of the
10684 recover rule rebuilds @file{data.stamp}. One could imagine something
10685 along the following lines.
10688 data.c data.h data.w data.x: data.stamp
10689 ## Recover from the removal of $@@
10690 @@if test -f $@@; then :; else \
10691 trap 'rm -rf data.lock data.stamp' 1 2 13 15; \
10692 ## mkdir is a portable test-and-set
10693 if mkdir data.lock 2>/dev/null; then \
10694 ## This code is being executed by the first process.
10695 rm -f data.stamp; \
10696 $(MAKE) $(AM_MAKEFLAGS) data.stamp; \
10697 result=$$?; rm -rf data.lock; exit $$result; \
10699 ## This code is being executed by the follower processes.
10700 ## Wait until the first process is done.
10701 while test -d data.lock; do sleep 1; done; \
10702 ## Succeed if and only if the first process succeeded.
10703 test -f data.stamp; \
10708 Using a dedicated witness, like @file{data.stamp}, is very handy when
10709 the list of output files is not known beforehand. As an illustration,
10710 consider the following rules to compile many @file{*.el} files into
10711 @file{*.elc} files in a single command. It does not matter how
10712 @code{ELFILES} is defined (as long as it is not empty: empty targets
10713 are not accepted by POSIX).
10716 ELFILES = one.el two.el three.el @dots{}
10717 ELCFILES = $(ELFILES:=c)
10719 elc-stamp: $(ELFILES)
10722 $(elisp_comp) $(ELFILES)
10723 @@mv -f elc-temp $@@
10725 $(ELCFILES): elc-stamp
10726 ## Recover from the removal of $@@
10727 @@if test -f $@@; then :; else \
10728 trap 'rm -rf elc-lock elc-stamp' 1 2 13 15; \
10729 if mkdir elc-lock 2>/dev/null; then \
10730 ## This code is being executed by the first process.
10732 $(MAKE) $(AM_MAKEFLAGS) elc-stamp; \
10735 ## This code is being executed by the follower processes.
10736 ## Wait until the first process is done.
10737 while test -d elc-lock; do sleep 1; done; \
10738 ## Succeed if and only if the first process succeeded.
10739 test -f elc-stamp; exit $$?; \
10744 For completeness it should be noted that GNU @command{make} is able to
10745 express rules with multiple output files using pattern rules
10746 (@pxref{Pattern Examples, , Pattern Rule Examples, make, The GNU Make
10747 Manual}). We do not discuss pattern rules here because they are not
10748 portable, but they can be convenient in packages that assume GNU
10752 @node Hard-Coded Install Paths
10753 @section Installing to Hard-Coded Locations
10756 My package needs to install some configuration file. I tried to use
10757 the following rule, but @samp{make distcheck} fails. Why?
10761 install-data-local:
10762 $(INSTALL_DATA) $(srcdir)/afile $(DESTDIR)/etc/afile
10767 My package needs to populate the installation directory of another
10768 package at install-time. I can easily compute that installation
10769 directory in @file{configure}, but if I install files therein,
10770 @samp{make distcheck} fails. How else should I do?
10773 These two setups share their symptoms: @samp{make distcheck} fails
10774 because they are installing files to hard-coded paths. In the later
10775 case the path is not really hard-coded in the package, but we can
10776 consider it to be hard-coded in the system (or in whichever tool that
10777 supplies the path). As long as the path does not use any of the
10778 standard directory variables (@samp{$(prefix)}, @samp{$(bindir)},
10779 @samp{$(datadir)}, etc.), the effect will be the same:
10780 user-installations are impossible.
10782 When a (non-root) user wants to install a package, he usually has no
10783 right to install anything in @file{/usr} or @file{/usr/local}. So he
10784 does something like @samp{./configure --prefix ~/usr} to install
10785 package in his own @file{~/usr} tree.
10787 If a package attempts to install something to some hard-coded path
10788 (e.g., @file{/etc/afile}), regardless of this @option{--prefix} setting,
10789 then the installation will fail. @samp{make distcheck} performs such
10790 a @option{--prefix} installation, hence it will fail too.
10792 Now, there are some easy solutions.
10794 The above @code{install-data-local} example for installing
10795 @file{/etc/afile} would be better replaced by
10798 sysconf_DATA = afile
10802 by default @code{sysconfdir} will be @samp{$(prefix)/etc}, because
10803 this is what the GNU Standards require. When such a package is
10804 installed on a FHS compliant system, the installer will have to set
10805 @samp{--sysconfdir=/etc}. As the maintainer of the package you
10806 should not be concerned by such site policies: use the appropriate
10807 standard directory variable to install your files so that installer
10808 can easily redefine these variables to match their site conventions.
10810 Installing files that should be used by another package, is slightly
10811 more involved. Let's take an example and assume you want to install
10812 shared library that is a Python extension module. If you ask Python
10813 where to install the library, it will answer something like this:
10816 % @kbd{python -c 'from distutils import sysconfig;
10817 print sysconfig.get_python_lib(1,0)'}
10818 /usr/lib/python2.3/site-packages
10821 If you indeed use this absolute path to install your shared library,
10822 non-root users will not be able to install the package, hence
10825 Let's do better. The @samp{sysconfig.get_python_lib()} function
10826 actually accepts a third argument that will replace Python's
10827 installation prefix.
10830 % @kbd{python -c 'from distutils import sysconfig;
10831 print sysconfig.get_python_lib(1,0,"$@{exec_prefix@}")'}
10832 $@{exec_prefix@}/lib/python2.3/site-packages
10835 You can also use this new path. If you do
10838 root users can install your package with the same @option{--prefix}
10839 as Python (you get the behavior of the previous attempt)
10842 non-root users can install your package too, they will have the
10843 extension module in a place that is not searched by Python but they
10844 can work around this using environment variables (and if you installed
10845 scripts that use this shared library, it's easy to tell Python were to
10846 look in the beginning of your script, so the script works in both
10850 The @code{AM_PATH_PYTHON} macro uses similar commands to define
10851 @samp{$(pythondir)} and @samp{$(pyexecdir)} (@pxref{Python}).
10853 Of course not all tools are as advanced as Python regarding that
10854 substitution of @var{prefix}. So another strategy is to figure the
10855 part of the of the installation directory that must be preserved. For
10856 instance, here is how @code{AM_PATH_LISPDIR} (@pxref{Emacs Lisp})
10857 computes @samp{$(lispdir)}:
10860 $EMACS -batch -q -eval '(while load-path
10861 (princ (concat (car load-path) "\n"))
10862 (setq load-path (cdr load-path)))' >conftest.out
10865 -e '/.*\/lib\/x*emacs\/site-lisp$/@{
10866 s,.*/lib/\(x*emacs/site-lisp\)$,$@{libdir@}/\1,;p;q;
10868 -e '/.*\/share\/x*emacs\/site-lisp$/@{
10869 s,.*/share/\(x*emacs/site-lisp\),$@{datarootdir@}/\1,;p;q;
10874 I.e., it just picks the first directory that looks like
10875 @file{*/lib/*emacs/site-lisp} or @file{*/share/*emacs/site-lisp} in
10876 the search path of emacs, and then substitutes @samp{$@{libdir@}} or
10877 @samp{$@{datadir@}} appropriately.
10879 The emacs case looks complicated because it processes a list and
10880 expect two possible layouts, otherwise it's easy, and the benefit for
10881 non-root users are really worth the extra @command{sed} invocation.
10885 @chapter History of Automake
10887 This chapter presents various aspects of the history of Automake. The
10888 exhausted reader can safely skip it; this will be more of interest to
10889 nostalgic people, or to those curious to learn about the evolution of
10893 * Timeline:: The Automake story.
10894 * Dependency Tracking Evolution:: Evolution of Automatic Dependency Tracking
10895 * Releases:: Statistics about Automake Releases
10902 @item 1994-09-19 First CVS commit.
10904 If we can trust the CVS repository, David J.@tie{}MacKenzie (djm) started
10905 working on Automake (or AutoMake, as it was spelt then) this Monday.
10907 The first version of the @command{automake} script looks as follows.
10916 if test ! -f $@{makefile@}.am; then
10917 echo "automake: $@{makefile@}.am: No such honkin' file"
10922 exec 4> $@{makefile@}.in
10927 From this you can already see that Automake will be about reading
10928 @file{*.am} file and producing @file{*.in} files. You cannot see
10929 anything else, but if you also know that David is the one who created
10930 Autoconf two years before you can guess the rest.
10932 Several commits follow, and by the end of the day Automake is
10933 reported to work for GNU fileutils and GNU m4.
10935 The modus operandi is the one that is still used today: variables
10936 assignments in @file{Makefile.am} files trigger injections of
10937 precanned @file{Makefile} fragments into the generated
10938 @file{Makefile.in}. The use of @file{Makefile} fragments was inspired
10939 by the 4.4BSD @command{make} and include files, however Automake aims
10940 to be portable and to conform to the GNU standards for @file{Makefile}
10941 variables and targets.
10943 At this point, the most recent release of Autoconf is version 1.11,
10944 and David is preparing to release Autoconf 2.0 in late October. As a
10945 matter of fact, he will barely touch Automake after September.
10947 @item 1994-11-05 David MacKenzie's last commit.
10949 At this point Automake is a 200 line portable shell script, plus 332
10950 lines of @file{Makefile} fragments. In the @file{README}, David
10951 states his ambivalence between ``portable shell'' and ``more
10952 appropriate language'':
10955 I wrote it keeping in mind the possibility of it becoming an Autoconf
10956 macro, so it would run at configure-time. That would slow
10957 configuration down a bit, but allow users to modify the Makefile.am
10958 without needing to fetch the AutoMake package. And, the Makefile.in
10959 files wouldn't need to be distributed. But all of AutoMake would. So
10960 I might reimplement AutoMake in Perl, m4, or some other more
10961 appropriate language.
10964 Automake is described as ``an experimental Makefile generator''.
10965 There is no documentation. Adventurous users are referred to the
10966 examples and patches needed to use Automake with GNU m4 1.3, fileutils
10967 3.9, time 1.6, and development versions of find and indent.
10969 These examples seem to have been lost. However at the time of writing
10970 (10 years later in September, 2004) the FSF still distributes a
10971 package that uses this version of Automake: check out GNU termutils
10974 @item 1995-11-12 Tom Tromey's first commit.
10976 After one year of inactivity, Tom Tromey takes over the package.
10977 Tom was working on GNU cpio back then, and doing this just for fun,
10978 having trouble finding a project to contribute to. So while hacking
10979 he wanted to bring the @file{Makefile.in} up to GNU standards. This
10980 was hard, and one day he saw Automake on @url{ftp://alpha.gnu.org/},
10981 grabbed it and tried it out.
10983 Tom didn't talk to djm about it until later, just to make sure he
10984 didn't mind if he made a release. He did a bunch of early releases to
10987 Gnits was (and still is) totally informal, just a few GNU friends who
10988 Fran@,cois Pinard knew, who were all interested in making a common
10989 infrastructure for GNU projects, and shared a similar outlook on how
10990 to do it. So they were able to make some progress. It came along
10991 with Autoconf and extensions thereof, and then Automake from David and
10992 Tom (who were both gnitsians). One of their ideas was to write a
10993 document paralleling the GNU standards, that was more strict in some
10994 ways and more detailed. They never finished the GNITS standards, but
10995 the ideas mostly made their way into Automake.
10997 @item 1995-11-23 Automake 0.20
10999 Besides introducing automatic dependency tracking (@pxref{Dependency
11000 Tracking Evolution}), this version also supplies a 9-page manual.
11002 At this time @command{aclocal} and @code{AM_INIT_AUTOMAKE} did not
11003 exist, so many things had to be done by hand. For instance, here is
11004 what a configure.in (this is the former name of the
11005 @file{configure.ac} we use today) must contain in order to use
11011 AC_DEFINE_UNQUOTED(PACKAGE, "$PACKAGE")
11012 AC_DEFINE_UNQUOTED(VERSION, "$VERSION")
11019 (Today all of the above is achieved by @code{AC_INIT} and
11020 @code{AM_INIT_AUTOMAKE}.)
11022 Here is how programs are specified in @file{Makefile.am}:
11026 hello_SOURCES = hello.c
11029 This looks pretty much like what we do today, except the
11030 @code{PROGRAMS} variable has no directory prefix specifying where
11031 @file{hello} should be installed: all programs are installed in
11032 @samp{$(bindir)}. @code{LIBPROGRAMS} can be used to specify programs
11033 that must be built but not installed (it is called
11034 @code{noinst_PROGRAMS} nowadays).
11036 Programs can be built conditionally using @code{AC_SUBST}itutions:
11039 PROGRAMS = @@progs@@
11040 AM_PROGRAMS = foo bar baz
11043 (@code{AM_PROGRAMS} has since then been renamed to
11044 @code{EXTRA_PROGRAMS}.)
11046 Similarly scripts, static libraries, and data can built and installed
11047 using the @code{LIBRARIES}, @code{SCRIPTS}, and @code{DATA} variables.
11048 However @code{LIBRARIES} were treated a bit specially in that Automake
11049 did automatically supply the @file{lib} and @file{.a} prefixes.
11050 Therefore to build @file{libcpio.a}, one had to write
11057 Extra files to distribute must be listed in @code{DIST_OTHER} (the
11058 ancestor of @code{EXTRA_DIST}). Also extra directories that are to be
11059 distributed should appear in @code{DIST_SUBDIRS}, but the manual
11060 describes this as a temporary ugly hack (today extra directories should
11061 also be listed in @code{EXTRA_DIST}, and @code{DIST_SUBDIRS} is used
11062 for another purpose, @pxref{Conditional Subdirectories}).
11064 @item 1995-11-26 Automake 0.21
11066 In less time that it takes to cook a frozen pizza, Tom rewrites
11067 Automake using Perl. At this time Perl 5 is only one year old, and
11068 Perl 4.036 is in use at many sites. Supporting several Perl versions
11069 has been a source of problems through the whole history of Automake.
11071 If you never used Perl 4, imagine Perl 5 without objects, without
11072 @samp{my} variables (only dynamically scoped @samp{local} variables),
11073 without function prototypes, with function calls that needs to be
11074 prefixed with @samp{&}, etc. Traces of this old style can still be
11075 found in today's @command{automake}.
11077 @item 1995-11-28 Automake 0.22
11078 @itemx 1995-11-29 Automake 0.23
11082 @item 1995-12-08 Automake 0.24
11083 @itemx 1995-12-10 Automake 0.25
11085 Releases are raining. 0.24 introduces the uniform naming scheme we
11086 use today, i.e., @code{bin_PROGRAMS} instead of @code{PROGRAMS},
11087 @code{noinst_LIBRARIES} instead of @code{LIBLIBRARIES}, etc. (However
11088 @code{EXTRA_PROGRAMS} does not exist yet, @code{AM_PROGRAMS} is still
11089 in use; and @code{TEXINFOS} and @code{MANS} still have no directory
11090 prefixes.) Adding support for prefixes like that was one of the major
11091 ideas in automake; it has lasted pretty well.
11093 AutoMake is renamed to Automake (Tom seems to recall it was Fran@,cois
11096 0.25 fixes a Perl 4 portability bug.
11098 @item 1995-12-18 Jim Meyering starts using Automake in GNU Textutils.
11099 @item 1995-12-31 Fran@,cois Pinard starts using Automake in GNU tar.
11101 @item 1996-01-03 Automake 0.26
11102 @itemx 1996-01-03 Automake 0.27
11104 Of the many change and suggestions sent by Fran@,cois Pinard and
11105 included in 0.26, the most important is perhaps the advise that to
11106 ease customization a user rule or variable definition should always
11107 override an Automake rule or definition.
11109 Gordon Matzigkeit and Jim Meyering are two other early contributors
11110 that have been sending fixes.
11112 0.27 fixes yet another Perl 4 portability bug.
11114 @item 1996-01-13 Automake 0.28
11116 Automake starts scanning @file{configure.in} for @code{LIBOBJS}
11117 support. This is an important step because until this version
11118 Automake did only know about the @file{Makefile.am}s it processed.
11119 @file{configure.in} was Autoconf's world and the link between Autoconf
11120 and Automake had to be done by the @file{Makefile.am} author. For
11121 instance, if @file{config.h} was generated by @file{configure}, it was the
11122 package maintainer's responsibility to define the @code{CONFIG_HEADER}
11123 variable in each @file{Makefile.am}.
11125 Succeeding releases will rely more and more on scanning
11126 @file{configure.in} to better automate the Autoconf integration.
11128 0.28 also introduces the @code{AUTOMAKE_OPTIONS} variable and the
11129 @option{--gnu} and @option{--gnits} options, the latter being stricter.
11131 @item 1996-02-07 Automake 0.29
11133 Thanks to @file{configure.in} scanning, @code{CONFIG_HEADER} is gone,
11134 and rebuild rules for @file{configure}-generated file are
11135 automatically output.
11137 @code{TEXINFOS} and @code{MANS} converted to the uniform naming
11140 @item 1996-02-24 Automake 0.30
11142 The test suite is born. It contains 9 tests. From now on test cases
11143 will be added pretty regularly (@pxref{Releases}), and this proved to
11144 be really helpful later on.
11146 @code{EXTRA_PROGRAMS} finally replaces @code{AM_PROGRAMS}.
11148 All the third-party Autoconf macros, written mostly by Fran@,cois
11149 Pinard (and later Jim Meyering), are distributed in Automake's
11150 hand-written @file{aclocal.m4} file. Package maintainers are expected
11151 to extract the necessary macros from this file. (In previous version
11152 you had to copy and paste them from the manual...)
11154 @item 1996-03-11 Automake 0.31
11156 The test suite in 0.30 was run via a long @code{check-local} rule. Upon
11157 Ulrich Drepper's suggestion, 0.31 makes it an Automake rule output
11158 whenever the @code{TESTS} variable is defined.
11160 @code{DIST_OTHER} is renamed to @code{EXTRA_DIST}, and the @code{check_}
11161 prefix is introduced. The syntax is now the same as today.
11163 @item 1996-03-15 Gordon Matzigkeit starts writing libtool.
11165 @item 1996-04-27 Automake 0.32
11167 @code{-hook} targets are introduced; an idea from Dieter Baron.
11169 @file{*.info} files, which were output in the build directory are
11170 now built in the source directory, because they are distributed. It
11171 seems these files like to move back and forth as that will happen
11172 again in future versions.
11174 @item 1996-05-18 Automake 0.33
11176 Gord Matzigkeit's main two contributions:
11179 @item very preliminary libtool support
11180 @item the distcheck rule
11183 Although they were very basic at this point, these are probably
11184 among the top features for Automake today.
11186 Jim Meyering also provides the infamous @code{jm_MAINTAINER_MODE},
11187 since then renamed to @code{AM_MAINTAINER_MODE} and abandoned by its
11188 author (@pxref{maintainer-mode}).
11190 @item 1996-05-28 Automake 1.0
11192 After only six months of heavy development, the automake script is
11193 3134 lines long, plus 973 lines of @file{Makefile} fragments. The
11194 package has 30 pages of documentation, and 38 test cases.
11195 @file{aclocal.m4} contains 4 macros.
11197 From now on and until version 1.4, new releases will occur at a rate
11198 of about one a year. 1.1 did not exist, actually 1.1b to 1.1p have
11199 been the name of beta releases for 1.2. This is the first time
11200 Automake uses suffix letters to designate beta releases, an habit that
11203 @item 1996-10-10 Kevin Dalley packages Automake 1.0 for Debian GNU/Linux.
11205 @item 1996-11-26 David J.@tie{}MacKenzie releases Autoconf 2.12.
11207 Between June and October, the Autoconf development is almost staled.
11208 Roland McGrath has been working at the beginning of the year. David
11209 comes back in November to release 2.12, but he won't touch Autoconf
11210 anymore after this year, and Autoconf then really stagnates. The
11211 desolate Autoconf @file{ChangeLog} for 1997 lists only 7 commits.
11213 @item 1997-02-28 @email{automake@@gnu.ai.mit.edu} list alive
11215 The mailing list is announced as follows:
11217 I've created the "automake" mailing list. It is
11218 "automake@@gnu.ai.mit.edu". Administrivia, as always, to
11219 automake-request@@gnu.ai.mit.edu.
11221 The charter of this list is discussion of automake, autoconf, and
11222 other configuration/portability tools (e.g., libtool). It is expected
11223 that discussion will range from pleas for help all the way up to
11226 This list is archived on the FSF machines. Offhand I don't know if
11227 you can get the archive without an account there.
11229 This list is open to anybody who wants to join. Tell all your
11234 Before that people were discussing Automake privately, on the Gnits
11235 mailing list (which is not public either), and less frequently on
11236 @code{gnu.misc.discuss}.
11238 @code{gnu.ai.mit.edu} is now @code{gnu.org}, in case you never
11239 noticed. The archives of the early years of the
11240 @code{automake@@gnu.org} list have been lost, so today it is almost
11241 impossible to find traces of discussions that occurred before 1999.
11242 This has been annoying more than once, as such discussions can be
11243 useful to understand the rationale behind a piece of uncommented code
11244 that was introduced back then.
11246 @item 1997-06-22 Automake 1.2
11248 Automake developments continues, and more and more new Autoconf macros
11249 are required. Distributing them in @file{aclocal.m4} and requiring
11250 people to browse this file to extract the relevant macros becomes
11251 uncomfortable. Ideally, some of them should be contributed to
11252 Autoconf so that they can be used directly, however Autoconf is
11253 currently inactive. Automake 1.2 consequently introduces
11254 @command{aclocal} (@command{aclocal} was actually started on
11255 1996-07-28), a tool that automatically constructs an @file{aclocal.m4}
11256 file from a repository of third-party macros. Because Autoconf has
11257 stalled, Automake also becomes a kind of repository for such
11258 third-party macros, even macros completely unrelated to Automake (for
11259 instance macros that fix broken Autoconf macros).
11261 The 1.2 release contains 20 macros, among which the
11262 @code{AM_INIT_AUTOMAKE} macro that simplifies the creation of
11263 @file{configure.in}.
11265 Libtool is fully supported using @code{*_LTLIBRARIES}.
11267 The missing script is introduced by Fran@,cois Pinard; it is meant to be
11268 a better solution than @code{AM_MAINTAINER_MODE}
11269 (@pxref{maintainer-mode}).
11271 Conditionals support was implemented by Ian Lance Taylor. At the
11272 time, Tom and Ian were working on an internal project at Cygnus. They
11273 were using ILU, which is pretty similar to CORBA@. They wanted to
11274 integrate ILU into their build, which was all @file{configure}-based,
11275 and Ian thought that adding conditionals to @command{automake} was
11276 simpler than doing all the work in @file{configure} (which was the
11277 standard at the time). So this was actually funded by Cygnus.
11279 This very useful but tricky feature will take a lot of time to
11280 stabilize. (At the time this text is written, there are still
11281 primaries that have not been updated to support conditional
11282 definitions in Automake 1.9.)
11284 The @command{automake} script has almost doubled: 6089 lines of Perl,
11285 plus 1294 lines of @file{Makefile} fragments.
11287 @item 1997-07-08 Gordon Matzigkeit releases Libtool 1.0.
11289 @item 1998-04-05 Automake 1.3
11291 This is a small advance compared to 1.2.
11292 It add support for assembly, and preliminary support for Java.
11294 Perl 5.004_04 is out, but fixes to support Perl 4 are still
11295 regularly submitted whenever Automake breaks it.
11297 @item 1998-09-06 @code{sourceware.cygnus.com} is on-line.
11299 Sourceware was setup by Jason Molenda to host open source projects.
11301 @item 1998-09-19 Automake CVS repository moved to @code{sourceware.cygnus.com}
11302 @itemx 1998-10-26 @code{sourceware.cygnus.com} announces it hosts Automake
11303 Automake is now hosted on @code{sourceware.cygnus.com}. It has a
11304 publicly accessible CVS repository. This CVS repository is a copy of
11305 the one Tom was using on his machine, which in turn is based on
11306 a copy of the CVS repository of David MacKenzie. This is why we still
11307 have to full source history. (Automake was on Sourceware until 2007-10-29,
11308 when it moved to a git repository on @code{savannah.gnu.org},
11309 but the Sourceware host had been renamed to @code{sources.redhat.com}.)
11311 The oldest file in the administrative directory of the CVS repository
11312 that was created on Sourceware is dated 1998-09-19, while the
11313 announcement that @command{automake} and @command{autoconf} had joined
11314 @command{sourceware} was made on 1998-10-26. They were among the
11315 first projects to be hosted there.
11317 The heedful reader will have noticed Automake was exactly 4-year-old
11320 @item 1999-01-05 Ben Elliston releases Autoconf 2.13.
11322 @item 1999-01-14 Automake 1.4
11324 This release adds support for Fortran 77 and for the @code{include}
11325 statement. Also, @samp{+=} assignments are introduced, but it is
11326 still quite easy to fool Automake when mixing this with conditionals.
11328 These two releases, Automake 1.4 and Autoconf 2.13 makes a duo that
11329 will be used together for years.
11331 @command{automake} is 7228 lines, plus 1591 lines of Makefile
11332 fragment, 20 macros (some 1.3 macros were finally contributed back to
11333 Autoconf), 197 test cases, and 51 pages of documentation.
11335 @item 1999-03-27 The @code{user-dep-branch} is created on the CVS repository.
11337 This implements a new dependency tracking schemed that should be
11338 able to handle automatic dependency tracking using any compiler (not
11339 just gcc) and any make (not just GNU @command{make}). In addition,
11340 the new scheme should be more reliable than the old one, as
11341 dependencies are generated on the end user's machine. Alexandre Oliva
11342 creates depcomp for this purpose.
11344 @xref{Dependency Tracking Evolution}, for more details about the
11345 evolution of automatic dependency tracking in Automake.
11347 @item 1999-11-21 The @code{user-dep-branch} is merged into the main trunk.
11349 This was a huge problem since we also had patches going in on the
11350 trunk. The merge took a long time and was very painful.
11354 Since September 1999 and until 2003, Akim Demaille will be zealously
11355 revamping Autoconf.
11358 I think the next release should be called "3.0".@*
11359 Let's face it: you've basically rewritten autoconf.@*
11360 Every weekend there are 30 new patches.@*
11361 I don't see how we could call this "2.15" with a straight face.@*
11362 -- Tom Tromey on @email{autoconf@@gnu.org}
11365 Actually Akim works like a submarine: he will pile up patches while he
11366 works off-line during the weekend, and flush them in batch when he
11367 resurfaces on Monday.
11371 On this Wednesday, Autoconf 2.49c, the last beta before Autoconf 2.50
11372 is out, and Akim has to find something to do during his week-end :)
11376 Akim sends a batch of 14 patches to @email{automake@@gnu.org}.
11379 Aiieeee! I was dreading the day that the Demaillator turned his
11380 sights on automake@dots{} and now it has arrived! -- Tom Tromey
11383 It's only the beginning: in two months he will send 192 patches. Then
11384 he would slow down so Tom can catch up and review all this. Initially
11385 Tom actually read all these patches, then he probably trustingly
11386 answered OK to most of them, and finally gave up and let Akim apply
11387 whatever he wanted. There was no way to keep up with that patch rate.
11390 Anyway the patch below won't apply since it predates Akim's
11391 sourcequake; I have yet to figure where the relevant passage has
11392 been moved :) -- Alexandre Duret-Lutz
11395 All these patches were sent to and discussed on
11396 @email{automake@@gnu.org}, so subscribed users were literally drown in
11397 technical mails. Eventually, the @email{automake-patches@@gnu.org}
11398 mailing list was created in May.
11400 Year after year, Automake had drifted away from its initial design:
11401 construct @file{Makefile.in} by assembling various @file{Makefile}
11402 fragments. In 1.4, lots of @file{Makefile} rules are being emitted at
11403 various places in the @command{automake} script itself; this does not
11404 help ensuring a consistent treatment of these rules (for instance
11405 making sure that user-defined rules override Automake's own rules).
11406 One of Akim's goal was moving all these hard-coded rules to separate
11407 @file{Makefile} fragments, so the logic could be centralized in a
11408 @file{Makefile} fragment processor.
11410 Another significant contribution of Akim is the interface with the
11411 ``trace'' feature of Autoconf. The way to scan @file{configure.in} at
11412 this time was to read the file and grep the various macro of interest
11413 to Automake. Doing so could break in many unexpected ways; automake
11414 could miss some definition (for instance @samp{AC_SUBST([$1], [$2])}
11415 where the arguments are known only when M4 is run), or conversely it
11416 could detect some macro that was not expanded (because it is called
11417 conditionally). In the CVS version of Autoconf, Akim had implemented
11418 the @option{--trace} option, which provides accurate information about
11419 where macros are actually called and with what arguments. Akim will
11420 equip Automake with a second @file{configure.in} scanner that uses
11421 this @option{--trace} interface. Since it was not sensible to drop the
11422 Autoconf 2.13 compatibility yet, this experimental scanner was only
11423 used when an environment variable was set, the traditional
11424 grep-scanner being still the default.
11426 @item 2001-04-25 Gary V.@tie{}Vaughan releases Libtool 1.4
11428 It has been more than two years since Automake 1.4, CVS Automake has
11429 suffered lot's of heavy changes and still is not ready for release.
11430 Libtool 1.4 had to be distributed with a patch against Automake 1.4.
11432 @item 2001-05-08 Automake 1.4-p1
11433 @itemx 2001-05-24 Automake 1.4-p2
11435 Gary V.@tie{}Vaughan, the principal Libtool maintainer, makes a ``patch
11436 release'' of Automake:
11439 The main purpose of this release is to have a stable automake
11440 which is compatible with the latest stable libtool.
11443 The release also contains obvious fixes for bugs in Automake 1.4,
11444 some of which were reported almost monthly.
11446 @item 2001-05-21 Akim Demaille releases Autoconf 2.50
11448 @item 2001-06-07 Automake 1.4-p3
11449 @itemx 2001-06-10 Automake 1.4-p4
11450 @itemx 2001-07-15 Automake 1.4-p5
11452 Gary continues his patch-release series. These also add support for
11453 some new Autoconf 2.50 idioms. Essentially, Autoconf now advocates
11454 @file{configure.ac} over @file{configure.in}, and it introduces a new
11455 syntax for @code{AC_OUTPUT}ing files.
11457 @item 2001-08-23 Automake 1.5
11459 A major and long-awaited release, that comes more than two years after
11460 1.4. It brings many changes, among which:
11462 @item The new dependency tracking scheme that uses @command{depcomp}.
11463 Aside from the improvement on the dependency tracking itself
11464 (@pxref{Dependency Tracking Evolution}), this also streamlines the use
11465 of automake generated @file{Makefile.in}s as the @file{Makefile.in}s
11466 used during development are now the same as those used in
11467 distributions. Before that the @file{Makefile.in}s generated for
11468 maintainers required GNU @command{make} and GCC, they were different
11469 from the portable @file{Makefile} generated for distribution; this was
11470 causing some confusion.
11472 @item Support for per-target compilation flags.
11474 @item Support for reference to files in subdirectories in most
11475 @file{Makefile.am} variables.
11477 @item Introduction of the @code{dist_}, @code{nodist_}, and @code{nobase_}
11479 @item Perl 4 support is finally dropped.
11482 1.5 did broke several packages that worked with 1.4. Enough so that
11483 Linux distributions could not easily install the new Automake version
11484 without breaking many of the packages for which they had to run
11485 @command{automake}.
11487 Some of these breakages were effectively bugs that would eventually be
11488 fixed in the next release. However, a lot of damage was caused by
11489 some changes made deliberately to render Automake stricter on some
11490 setup we did consider bogus. For instance, @samp{make distcheck} was
11491 improved to check that @samp{make uninstall} did remove all the files
11492 @samp{make install} installed, that @samp{make distclean} did not omit
11493 some file, and that a VPATH build would work even if the source
11494 directory was read-only. Similarly, Automake now rejects multiple
11495 definitions of the same variable (because that would mix very badly
11496 with conditionals), and @samp{+=} assignments with no previous
11497 definition. Because these changes all occurred suddenly after 1.4 had
11498 been established for more than two years, it hurt users.
11500 To make matter worse, meanwhile Autoconf (now at version 2.52) was
11501 facing similar troubles, for similar reasons.
11503 @item 2002-03-05 Automake 1.6
11505 This release introduced versioned installation (@pxref{API
11506 versioning}). This was mainly pushed by Havoc Pennington, taking the
11507 GNOME source tree as motive: due to incompatibilities between the
11508 autotools it's impossible for the GNOME packages to switch to Autoconf
11509 2.53 and Automake 1.5 all at once, so they are currently stuck with
11510 Autoconf 2.13 and Automake 1.4.
11512 The idea was to call this version @file{automake-1.6}, call all its
11513 bug-fix versions identically, and switch to @file{automake-1.7} for
11514 the next release that adds new features or changes some rules. This
11515 scheme implies maintaining a bug-fix branch in addition to the
11516 development trunk, which means more work from the maintainer, but
11517 providing regular bug-fix releases proved to be really worthwhile.
11519 Like 1.5, 1.6 also introduced a bunch of incompatibilities, meant or
11520 not. Perhaps the more annoying was the dependence on the newly
11521 released Autoconf 2.53. Autoconf seemed to have stabilized enough
11522 since its explosive 2.50 release, and included changes required to fix
11523 some bugs in Automake. In order to upgrade to Automake 1.6, people
11524 now had to upgrade Autoconf too; for some packages it was no picnic.
11526 While versioned installation helped people to upgrade, it also
11527 unfortunately allowed people not to upgrade. At the time of writing,
11528 some Linux distributions are shipping packages for Automake 1.4, 1.5,
11529 1.6, 1.7, 1.8, and 1.9. Most of these still install 1.4 by default.
11530 Some distribution also call 1.4 the ``stable'' version, and present
11531 ``1.9'' as the development version; this does not really makes sense
11532 since 1.9 is way more solid than 1.4. All this does not help the
11535 @item 2002-04-11 Automake 1.6.1
11537 1.6, and the upcoming 1.4-p6 release were the last release by Tom.
11538 This one and those following will be handled by Alexandre
11539 Duret-Lutz. Tom is still around, and will be there until about 1.7,
11540 but his interest into Automake is drifting away towards projects like
11543 Alexandre has been using Automake since 2000, and started to
11544 contribute mostly on Akim's incitement (Akim and Alexandre have been
11545 working in the same room from 1999 to 2002). In 2001 and 2002 he had
11546 a lot of free time to enjoy hacking Automake.
11548 @item 2002-06-14 Automake 1.6.2
11550 @item 2002-07-28 Automake 1.6.3
11551 @itemx 2002-07-28 Automake 1.4-p6
11553 Two releases on the same day. 1.6.3 is a bug-fix release.
11555 Tom Tromey backported the versioned installation mechanism on the 1.4
11556 branch, so that Automake 1.6.x and Automake 1.4-p6 could be installed
11557 side by side. Another request from the GNOME folks.
11559 @item 2002-09-25 Automake 1.7
11561 This release switches to the new @file{configure.ac} scanner Akim
11562 was experimenting in 1.5.
11564 @item 2002-10-16 Automake 1.7.1
11565 @itemx 2002-12-06 Automake 1.7.2
11566 @itemx 2003-02-20 Automake 1.7.3
11567 @itemx 2003-04-23 Automake 1.7.4
11568 @itemx 2003-05-18 Automake 1.7.5
11569 @itemx 2003-07-10 Automake 1.7.6
11570 @itemx 2003-09-07 Automake 1.7.7
11571 @itemx 2003-10-07 Automake 1.7.8
11573 Many bug-fix releases. 1.7 lasted because the development version
11574 (upcoming 1.8) was suffering some major internal revamping.
11576 @item 2003-10-26 Automake on screen
11578 Episode 49, `Repercussions', in the third season of the `Alias' TV
11579 show is first aired.
11581 Marshall, one of the character, is working on a computer virus that he
11582 has to modify before it gets into the wrong hands or something like
11583 that. The screenshots you see do not show any program code, they show
11584 a @file{Makefile.in} @code{generated by automake}...
11586 @item 2003-11-09 Automake 1.7.9
11588 @item 2003-12-10 Automake 1.8
11590 The most striking update is probably that of @command{aclocal}.
11592 @command{aclocal} now uses @code{m4_include} in the produced
11593 @file{aclocal.m4} when the included macros are already distributed
11594 with the package (an idiom used in many packages), which reduces code
11595 duplication. Many people liked that, but in fact this change was
11596 really introduced to fix a bug in rebuild rules: @file{Makefile.in}
11597 must be rebuilt whenever a dependency of @file{configure} changes, but
11598 all the @file{m4} files included in @file{aclocal.m4} where unknown
11599 from @command{automake}. Now @command{automake} can just trace the
11600 @code{m4_include}s to discover the dependencies.
11602 @command{aclocal} also starts using the @option{--trace} Autoconf option
11603 in order to discover used macros more accurately. This will turn out
11604 to be very tricky (later releases will improve this) as people had
11605 devised many ways to cope with the limitation of previous
11606 @command{aclocal} versions, notably using handwritten
11607 @code{m4_include}s: @command{aclocal} must make sure not to redefine a
11608 rule that is already included by such statement.
11610 Automake also has seen its guts rewritten. Although this rewriting
11611 took a lot of efforts, it is only apparent to the users in that some
11612 constructions previously disallowed by the implementation now work
11613 nicely. Conditionals, Locations, Variable and Rule definitions,
11614 Options: these items on which Automake works have been rewritten as
11615 separate Perl modules, and documented.
11617 @itemx 2004-01-11 Automake 1.8.1
11618 @itemx 2004-01-12 Automake 1.8.2
11619 @itemx 2004-03-07 Automake 1.8.3
11620 @itemx 2004-04-25 Automake 1.8.4
11621 @itemx 2004-05-16 Automake 1.8.5
11623 @item 2004-07-28 Automake 1.9
11625 This release tries to simplify the compilation rules it outputs to
11626 reduce the size of the Makefile. The complaint initially come from
11627 the libgcj developers. Their @file{Makefile.in} generated with
11628 Automake 1.4 and custom build rules (1.4 did not support compiled
11629 Java) is 250KB@. The one generated by 1.8 was over 9MB@! 1.9 gets it
11632 Aside from this it contains mainly minor changes and bug-fixes.
11634 @itemx 2004-08-11 Automake 1.9.1
11635 @itemx 2004-09-19 Automake 1.9.2
11637 Automake has ten years. This chapter of the manual was initially
11638 written for this occasion.
11640 @itemx 2007-10-29 Automake repository moves to @code{savannah.gnu.org} and uses
11641 git as primary repository.
11645 @node Dependency Tracking Evolution
11646 @section Dependency Tracking in Automake
11648 Over the years Automake has deployed three different dependency
11649 tracking methods. Each method, including the current one, has had
11650 flaws of various sorts. Here we lay out the different dependency
11651 tracking methods, their flaws, and their fixes. We conclude with
11652 recommendations for tool writers, and by indicating future directions
11653 for dependency tracking work in Automake.
11655 @subsection First Take
11656 @unnumberedsubsubsec Description
11658 Our first attempt at automatic dependency tracking was based on the
11659 method recommended by GNU @command{make}. (@pxref{Automatic
11660 Prerequisites, , Generating Prerequisites Automatically, make, The GNU
11663 This version worked by precomputing dependencies ahead of time. For
11664 each source file, it had a special @file{.P} file that held the
11665 dependencies. There was a rule to generate a @file{.P} file by
11666 invoking the compiler appropriately. All such @file{.P} files were
11667 included by the @file{Makefile}, thus implicitly becoming dependencies
11668 of @file{Makefile}.
11670 @unnumberedsubsubsec Bugs
11672 This approach had several critical bugs.
11676 The code to generate the @file{.P} file relied on @command{gcc}.
11677 (A limitation, not technically a bug.)
11679 The dependency tracking mechanism itself relied on GNU @command{make}.
11680 (A limitation, not technically a bug.)
11682 Because each @file{.P} file was a dependency of @file{Makefile}, this
11683 meant that dependency tracking was done eagerly by @command{make}.
11684 For instance, @samp{make clean} would cause all the dependency files
11685 to be updated, and then immediately removed. This eagerness also
11686 caused problems with some configurations; if a certain source file
11687 could not be compiled on a given architecture for some reason,
11688 dependency tracking would fail, aborting the entire build.
11690 As dependency tracking was done as a pre-pass, compile times were
11691 doubled--the compiler had to be run twice per source file.
11693 @samp{make dist} re-ran @command{automake} to generate a
11694 @file{Makefile} that did not have automatic dependency tracking (and
11695 that was thus portable to any version of @command{make}). In order to
11696 do this portably, Automake had to scan the dependency files and remove
11697 any reference that was to a source file not in the distribution.
11698 This process was error-prone. Also, if @samp{make dist} was run in an
11699 environment where some object file had a dependency on a source file
11700 that was only conditionally created, Automake would generate a
11701 @file{Makefile} that referred to a file that might not appear in the
11702 end user's build. A special, hacky mechanism was required to work
11706 @unnumberedsubsubsec Historical Note
11708 The code generated by Automake is often inspired by the
11709 @file{Makefile} style of a particular author. In the case of the first
11710 implementation of dependency tracking, I believe the impetus and
11711 inspiration was Jim Meyering. (I could be mistaken. If you know
11712 otherwise feel free to correct me.)
11714 @subsection Dependencies As Side Effects
11715 @unnumberedsubsubsec Description
11717 The next refinement of Automake's automatic dependency tracking scheme
11718 was to implement dependencies as side effects of the compilation.
11719 This was aimed at solving the most commonly reported problems with the
11720 first approach. In particular we were most concerned with eliminating
11721 the weird rebuilding effect associated with make clean.
11723 In this approach, the @file{.P} files were included using the
11724 @code{-include} command, which let us create these files lazily. This
11725 avoided the @samp{make clean} problem.
11727 We only computed dependencies when a file was actually compiled. This
11728 avoided the performance penalty associated with scanning each file
11729 twice. It also let us avoid the other problems associated with the
11730 first, eager, implementation. For instance, dependencies would never
11731 be generated for a source file that was not compilable on a given
11732 architecture (because it in fact would never be compiled).
11734 @unnumberedsubsubsec Bugs
11738 This approach also relied on the existence of @command{gcc} and GNU
11739 @command{make}. (A limitation, not technically a bug.)
11741 Dependency tracking was still done by the developer, so the problems
11742 from the first implementation relating to massaging of dependencies by
11743 @samp{make dist} were still in effect.
11745 This implementation suffered from the ``deleted header file'' problem.
11746 Suppose a lazily-created @file{.P} file includes a dependency on a
11747 given header file, like this:
11750 maude.o: maude.c something.h
11753 Now suppose that the developer removes @file{something.h} and updates
11754 @file{maude.c} so that this include is no longer needed. If he runs
11755 @command{make}, he will get an error because there is no way to create
11756 @file{something.h}.
11758 We fixed this problem in a later release by further massaging the
11759 output of @command{gcc} to include a dummy dependency for each header
11763 @subsection Dependencies for the User
11764 @unnumberedsubsubsec Description
11766 The bugs associated with @samp{make dist}, over time, became a real
11767 problem. Packages using Automake were being built on a large number
11768 of platforms, and were becoming increasingly complex. Broken
11769 dependencies were distributed in ``portable'' @file{Makefile.in}s,
11770 leading to user complaints. Also, the requirement for @command{gcc}
11771 and GNU @command{make} was a constant source of bug reports. The next
11772 implementation of dependency tracking aimed to remove these problems.
11774 We realized that the only truly reliable way to automatically track
11775 dependencies was to do it when the package itself was built. This
11776 meant discovering a method portable to any version of make and any
11777 compiler. Also, we wanted to preserve what we saw as the best point
11778 of the second implementation: dependency computation as a side effect
11781 In the end we found that most modern make implementations support some
11782 form of include directive. Also, we wrote a wrapper script that let
11783 us abstract away differences between dependency tracking methods for
11784 compilers. For instance, some compilers cannot generate dependencies
11785 as a side effect of compilation. In this case we simply have the
11786 script run the compiler twice. Currently our wrapper script
11787 (@command{depcomp}) knows about twelve different compilers (including
11788 a "compiler" that simply invokes @command{makedepend} and then the
11789 real compiler, which is assumed to be a standard Unix-like C compiler
11790 with no way to do dependency tracking).
11792 @unnumberedsubsubsec Bugs
11796 Running a wrapper script for each compilation slows down the build.
11798 Many users don't really care about precise dependencies.
11800 This implementation, like every other automatic dependency tracking
11801 scheme in common use today (indeed, every one we've ever heard of),
11802 suffers from the ``duplicated new header'' bug.
11804 This bug occurs because dependency tracking tools, such as the
11805 compiler, only generate dependencies on the successful opening of a
11806 file, and not on every probe.
11808 Suppose for instance that the compiler searches three directories for
11809 a given header, and that the header is found in the third directory.
11810 If the programmer erroneously adds a header file with the same name to
11811 the first directory, then a clean rebuild from scratch could fail
11812 (suppose the new header file is buggy), whereas an incremental rebuild
11815 What has happened here is that people have a misunderstanding of what
11816 a dependency is. Tool writers think a dependency encodes information
11817 about which files were read by the compiler. However, a dependency
11818 must actually encode information about what the compiler tried to do.
11820 This problem is not serious in practice. Programmers typically do not
11821 use the same name for a header file twice in a given project. (At
11822 least, not in C or C++. This problem may be more troublesome in
11823 Java.) This problem is easy to fix, by modifying dependency
11824 generators to record every probe, instead of every successful open.
11827 Since automake generates dependencies as a side effect of compilation,
11828 there is a bootstrapping problem when header files are generated by
11829 running a program. The problem is that, the first time the build is
11830 done, there is no way by default to know that the headers are
11831 required, so make might try to run a compilation for which the headers
11832 have not yet been built.
11834 This was also a problem in the previous dependency tracking implementation.
11836 The current fix is to use @code{BUILT_SOURCES} to list built headers
11837 (@pxref{Sources}). This causes them to be built before any other
11838 build rules are run. This is unsatisfactory as a general solution,
11839 however in practice it seems sufficient for most actual programs.
11842 This code is used since Automake 1.5.
11844 In GCC 3.0, we managed to convince the maintainers to add special
11845 command-line options to help Automake more efficiently do its job. We
11846 hoped this would let us avoid the use of a wrapper script when
11847 Automake's automatic dependency tracking was used with @command{gcc}.
11849 Unfortunately, this code doesn't quite do what we want. In
11850 particular, it removes the dependency file if the compilation fails;
11851 we'd prefer that it instead only touch the file in any way if the
11852 compilation succeeds.
11854 Nevertheless, since Automake 1.7, when a recent @command{gcc} is
11855 detected at @command{configure} time, we inline the
11856 dependency-generation code and do not use the @command{depcomp}
11857 wrapper script. This makes compilations faster for those using this
11858 compiler (probably our primary user base). The counterpart is that
11859 because we have to encode two compilation rules in @file{Makefile}
11860 (with or without @command{depcomp}), the produced @file{Makefile}s are
11863 @subsection Techniques for Computing Dependencies
11865 There are actually several ways for a build tool like Automake to
11866 cause tools to generate dependencies.
11869 @item @command{makedepend}
11870 This was a commonly-used method in the past. The idea is to run a
11871 special program over the source and have it generate dependency
11872 information. Traditional implementations of @command{makedepend} are
11873 not completely precise; ordinarily they were conservative and
11874 discovered too many dependencies.
11876 An obvious way to generate dependencies is to simply write the tool so
11877 that it can generate the information needed by the build tool. This is
11878 also the most portable method. Many compilers have an option to
11879 generate dependencies. Unfortunately, not all tools provide such an
11881 @item The file system
11882 It is possible to write a special file system that tracks opens,
11883 reads, writes, etc, and then feed this information back to the build
11884 tool. @command{clearmake} does this. This is a very powerful
11885 technique, as it doesn't require cooperation from the
11886 tool. Unfortunately it is also very difficult to implement and also
11887 not practical in the general case.
11888 @item @code{LD_PRELOAD}
11889 Rather than use the file system, one could write a special library to
11890 intercept @code{open} and other syscalls. This technique is also quite
11891 powerful, but unfortunately it is not portable enough for use in
11892 @command{automake}.
11895 @subsection Recommendations for Tool Writers
11897 We think that every compilation tool ought to be able to generate
11898 dependencies as a side effect of compilation. Furthermore, at least
11899 while @command{make}-based tools are nearly universally in use (at
11900 least in the free software community), the tool itself should generate
11901 dummy dependencies for header files, to avoid the deleted header file
11902 bug. Finally, the tool should generate a dependency for each probe,
11903 instead of each successful file open, in order to avoid the duplicated
11906 @subsection Future Directions for Automake's Dependency Tracking
11908 Currently, only languages and compilers understood by Automake can
11909 have dependency tracking enabled. We would like to see if it is
11910 practical (and worthwhile) to let this support be extended by the user
11911 to languages unknown to Automake.
11914 @section Release Statistics
11916 The following table (inspired by @samp{perlhist(1)}) quantifies the
11917 evolution of Automake using these metrics:
11921 The date and version of the release.
11923 The number of lines of the @command{automake} script.
11925 The number of lines of the @command{aclocal} script.
11927 The number of lines of the @command{Perl} supporting modules.
11929 The number of lines of the @file{Makefile} fragments. The number in parenthesis
11930 is the number of files.
11932 The number of lines (and files) of Autoconf macros.
11934 The number of pages of the documentation (the Postscript version).
11936 The number of test cases in the test suite.
11939 @multitable {8888-88-88} {8.8-p8} {8888} {8888} {8888} {8888 (88)} {8888 (88)} {888} {888}
11940 @headitem Date @tab Rel @tab am @tab acl @tab pm @tab @file{*.am} @tab m4 @tab doc @tab t
11941 @item 1994-09-19 @tab CVS @tab 141 @tab @tab @tab 299 (24) @tab @tab @tab
11942 @item 1994-11-05 @tab CVS @tab 208 @tab @tab @tab 332 (28) @tab @tab @tab
11943 @item 1995-11-23 @tab 0.20 @tab 533 @tab @tab @tab 458 (35) @tab @tab 9 @tab
11944 @item 1995-11-26 @tab 0.21 @tab 613 @tab @tab @tab 480 (36) @tab @tab 11 @tab
11945 @item 1995-11-28 @tab 0.22 @tab 1116 @tab @tab @tab 539 (38) @tab @tab 12 @tab
11946 @item 1995-11-29 @tab 0.23 @tab 1240 @tab @tab @tab 541 (38) @tab @tab 12 @tab
11947 @item 1995-12-08 @tab 0.24 @tab 1462 @tab @tab @tab 504 (33) @tab @tab 14 @tab
11948 @item 1995-12-10 @tab 0.25 @tab 1513 @tab @tab @tab 511 (37) @tab @tab 15 @tab
11949 @item 1996-01-03 @tab 0.26 @tab 1706 @tab @tab @tab 438 (36) @tab @tab 16 @tab
11950 @item 1996-01-03 @tab 0.27 @tab 1706 @tab @tab @tab 438 (36) @tab @tab 16 @tab
11951 @item 1996-01-13 @tab 0.28 @tab 1964 @tab @tab @tab 934 (33) @tab @tab 16 @tab
11952 @item 1996-02-07 @tab 0.29 @tab 2299 @tab @tab @tab 936 (33) @tab @tab 17 @tab
11953 @item 1996-02-24 @tab 0.30 @tab 2544 @tab @tab @tab 919 (32) @tab 85 (1) @tab 20 @tab 9
11954 @item 1996-03-11 @tab 0.31 @tab 2877 @tab @tab @tab 919 (32) @tab 85 (1) @tab 29 @tab 17
11955 @item 1996-04-27 @tab 0.32 @tab 3058 @tab @tab @tab 921 (31) @tab 85 (1) @tab 30 @tab 26
11956 @item 1996-05-18 @tab 0.33 @tab 3110 @tab @tab @tab 926 (31) @tab 105 (1) @tab 30 @tab 35
11957 @item 1996-05-28 @tab 1.0 @tab 3134 @tab @tab @tab 973 (32) @tab 105 (1) @tab 30 @tab 38
11958 @item 1997-06-22 @tab 1.2 @tab 6089 @tab 385 @tab @tab 1294 (36) @tab 592 (20) @tab 37 @tab 126
11959 @item 1998-04-05 @tab 1.3 @tab 6415 @tab 422 @tab @tab 1470 (39) @tab 741 (23) @tab 39 @tab 156
11960 @item 1999-01-14 @tab 1.4 @tab 7240 @tab 426 @tab @tab 1591 (40) @tab 734 (20) @tab 51 @tab 197
11961 @item 2001-05-08 @tab 1.4-p1 @tab 7251 @tab 426 @tab @tab 1591 (40) @tab 734 (20) @tab 51 @tab 197
11962 @item 2001-05-24 @tab 1.4-p2 @tab 7268 @tab 439 @tab @tab 1591 (40) @tab 734 (20) @tab 49 @tab 197
11963 @item 2001-06-07 @tab 1.4-p3 @tab 7312 @tab 439 @tab @tab 1591 (40) @tab 734 (20) @tab 49 @tab 197
11964 @item 2001-06-10 @tab 1.4-p4 @tab 7321 @tab 439 @tab @tab 1591 (40) @tab 734 (20) @tab 49 @tab 198
11965 @item 2001-07-15 @tab 1.4-p5 @tab 7228 @tab 426 @tab @tab 1596 (40) @tab 734 (20) @tab 51 @tab 198
11966 @item 2001-08-23 @tab 1.5 @tab 8016 @tab 475 @tab 600 @tab 2654 (39) @tab 1166 (29) @tab 63 @tab 327
11967 @item 2002-03-05 @tab 1.6 @tab 8465 @tab 475 @tab 1136 @tab 2732 (39) @tab 1603 (27) @tab 66 @tab 365
11968 @item 2002-04-11 @tab 1.6.1 @tab 8544 @tab 475 @tab 1136 @tab 2741 (39) @tab 1603 (27) @tab 66 @tab 372
11969 @item 2002-06-14 @tab 1.6.2 @tab 8575 @tab 475 @tab 1136 @tab 2800 (39) @tab 1609 (27) @tab 67 @tab 386
11970 @item 2002-07-28 @tab 1.6.3 @tab 8600 @tab 475 @tab 1153 @tab 2809 (39) @tab 1609 (27) @tab 67 @tab 391
11971 @item 2002-07-28 @tab 1.4-p6 @tab 7332 @tab 455 @tab @tab 1596 (40) @tab 735 (20) @tab 49 @tab 197
11972 @item 2002-09-25 @tab 1.7 @tab 9189 @tab 471 @tab 1790 @tab 2965 (39) @tab 1606 (28) @tab 73 @tab 430
11973 @item 2002-10-16 @tab 1.7.1 @tab 9229 @tab 475 @tab 1790 @tab 2977 (39) @tab 1606 (28) @tab 73 @tab 437
11974 @item 2002-12-06 @tab 1.7.2 @tab 9334 @tab 475 @tab 1790 @tab 2988 (39) @tab 1606 (28) @tab 77 @tab 445
11975 @item 2003-02-20 @tab 1.7.3 @tab 9389 @tab 475 @tab 1790 @tab 3023 (39) @tab 1651 (29) @tab 84 @tab 448
11976 @item 2003-04-23 @tab 1.7.4 @tab 9429 @tab 475 @tab 1790 @tab 3031 (39) @tab 1644 (29) @tab 85 @tab 458
11977 @item 2003-05-18 @tab 1.7.5 @tab 9429 @tab 475 @tab 1790 @tab 3033 (39) @tab 1645 (29) @tab 85 @tab 459
11978 @item 2003-07-10 @tab 1.7.6 @tab 9442 @tab 475 @tab 1790 @tab 3033 (39) @tab 1660 (29) @tab 85 @tab 461
11979 @item 2003-09-07 @tab 1.7.7 @tab 9443 @tab 475 @tab 1790 @tab 3041 (39) @tab 1660 (29) @tab 90 @tab 467
11980 @item 2003-10-07 @tab 1.7.8 @tab 9444 @tab 475 @tab 1790 @tab 3041 (39) @tab 1660 (29) @tab 90 @tab 468
11981 @item 2003-11-09 @tab 1.7.9 @tab 9444 @tab 475 @tab 1790 @tab 3048 (39) @tab 1660 (29) @tab 90 @tab 468
11982 @item 2003-12-10 @tab 1.8 @tab 7171 @tab 585 @tab 7730 @tab 3236 (39) @tab 1666 (31) @tab 104 @tab 521
11983 @item 2004-01-11 @tab 1.8.1 @tab 7217 @tab 663 @tab 7726 @tab 3287 (39) @tab 1686 (31) @tab 104 @tab 525
11984 @item 2004-01-12 @tab 1.8.2 @tab 7217 @tab 663 @tab 7726 @tab 3288 (39) @tab 1686 (31) @tab 104 @tab 526
11985 @item 2004-03-07 @tab 1.8.3 @tab 7214 @tab 686 @tab 7735 @tab 3303 (39) @tab 1695 (31) @tab 111 @tab 530
11986 @item 2004-04-25 @tab 1.8.4 @tab 7214 @tab 686 @tab 7736 @tab 3310 (39) @tab 1701 (31) @tab 112 @tab 531
11987 @item 2004-05-16 @tab 1.8.5 @tab 7240 @tab 686 @tab 7736 @tab 3299 (39) @tab 1701 (31) @tab 112 @tab 533
11988 @item 2004-07-28 @tab 1.9 @tab 7508 @tab 715 @tab 7794 @tab 3352 (40) @tab 1812 (32) @tab 115 @tab 551
11989 @item 2004-08-11 @tab 1.9.1 @tab 7512 @tab 715 @tab 7794 @tab 3354 (40) @tab 1812 (32) @tab 115 @tab 552
11990 @item 2004-09-19 @tab 1.9.2 @tab 7512 @tab 715 @tab 7794 @tab 3354 (40) @tab 1812 (32) @tab 132 @tab 554
11991 @item 2004-11-01 @tab 1.9.3 @tab 7507 @tab 718 @tab 7804 @tab 3354 (40) @tab 1812 (32) @tab 134 @tab 556
11992 @item 2004-12-18 @tab 1.9.4 @tab 7508 @tab 718 @tab 7856 @tab 3361 (40) @tab 1811 (32) @tab 140 @tab 560
11993 @item 2005-02-13 @tab 1.9.5 @tab 7523 @tab 719 @tab 7859 @tab 3373 (40) @tab 1453 (32) @tab 142 @tab 562
11994 @item 2005-07-10 @tab 1.9.6 @tab 7539 @tab 699 @tab 7867 @tab 3400 (40) @tab 1453 (32) @tab 144 @tab 570
11995 @item 2006-10-15 @tab 1.10 @tab 7859 @tab 1072 @tab 8024 @tab 3512 (40) @tab 1496 (34) @tab 172 @tab 604
11999 @c ========================================================== Appendices
12002 @node Copying This Manual
12003 @appendix Copying This Manual
12006 * GNU Free Documentation License:: License for copying this manual
12016 * Macro Index:: Index of Autoconf macros
12017 * Variable Index:: Index of Makefile variables
12018 * General Index:: General index
12022 @appendixsec Macro Index
12026 @node Variable Index
12027 @appendixsec Variable Index
12031 @node General Index
12032 @appendixsec General Index
12041 @c LocalWords: texinfo setfilename settitle setchapternewpage texi direntry
12042 @c LocalWords: dircategory in's aclocal ifinfo titlepage Tromey vskip pt sp
12043 @c LocalWords: filll defcodeindex ov cv op tr syncodeindex fn cp vr ifnottex
12044 @c LocalWords: dir Automake's ac Dist Gnits gnits cygnus dfn Autoconf's pxref
12045 @c LocalWords: cindex Autoconf autoconf perl samp cvs dist trindex SUBST foo
12046 @c LocalWords: xs emph FIXME ref vindex pkglibdir pkgincludedir pkgdatadir mt
12047 @c LocalWords: pkg libdir cpio bindir sbindir rmt pax sbin zar zardir acindex
12048 @c LocalWords: HTML htmldir html noinst TEXINFOS nodist nobase strudel CFLAGS
12049 @c LocalWords: libmumble CC YFLAGS ansi knr itemx de fication config url comp
12050 @c LocalWords: depcomp elisp sh mdate mkinstalldirs mkdir py tex dvi ps pdf
12051 @c LocalWords: ylwrap zardoz INIT gettext acinclude mv FUNCS LIBOBJS LDADD fr
12052 @c LocalWords: uref featureful dnl src LINGUAS es ko nl pl sl sv PROG ISC doc
12053 @c LocalWords: POSIX STDC fcntl FUNC ALLOCA blksize struct stat intl po chmod
12054 @c LocalWords: ChangeLog SUBDIRS gettextize gpl testdata getopt INTLLIBS cpp
12055 @c LocalWords: localedir datadir DLOCALEDIR DEXIT CPPFLAGS autoreconf opindex
12056 @c LocalWords: AUX var symlink deps Wno Wnone package's aclocal's distclean
12057 @c LocalWords: ltmain xref LIBSOURCE LIBSOURCES LIBOBJ MEMCMP vs RANLIB CXX
12058 @c LocalWords: LDFLAGS LIBTOOL libtool XTRA LIBS gettext's acdir APIVERSION
12059 @c LocalWords: dirlist noindent usr MULTILIB multilib Multilibs TIOCGWINSZ sc
12060 @c LocalWords: GWINSZ termios SRCDIR tarball bzip LISPDIR lispdir XEmacs CCAS
12061 @c LocalWords: emacsen MicroEmacs CCASFLAGS UX GCJ gcj GCJFLAGS posix DMALLOC
12062 @c LocalWords: dmalloc ldmalloc REGEX regex rx DEPDIR DEP DEFUN aclocaldir fi
12063 @c LocalWords: mymacro myothermacro AMFLAGS autopoint autogen libtoolize yum
12064 @c LocalWords: autoheader README MAKEFLAGS subdir Inetutils sync COND endif
12065 @c LocalWords: Miller's installable includedir inc pkgdata EXEEXT libexec bsd
12066 @c LocalWords: pkglib libexecdir prog libcpio cpio's dlopen dlpreopen linux
12067 @c LocalWords: subsubsection OBJEXT esac lib LTLIBRARIES liblob LIBADD AR ar
12068 @c LocalWords: ARFLAGS cru ing maude libgettext lo LTLIBOBJS rpath SGI PRE yy
12069 @c LocalWords: libmaude CCLD CXXFLAGS FFLAGS LFLAGS OBJCFLAGS RFLAGS DEFS cc
12070 @c LocalWords: SHORTNAME vtable srcdir nostdinc basename yxx cxx ll lxx gdb
12071 @c LocalWords: lexers yymaxdepth maxdepth yyparse yylex yyerror yylval lval
12072 @c LocalWords: yychar yydebug yypact yyr yydef def yychk chk yypgo pgo yyact
12073 @c LocalWords: yyexca exca yyerrflag errflag yynerrs nerrs yyps yypv pv yys
12074 @c LocalWords: yystate yytmp tmp yyv yyval val yylloc lloc yyreds yytoks toks
12075 @c LocalWords: yylhs yylen yydefred yydgoto yysindex yyrindex yygindex yyname
12076 @c LocalWords: yytable yycheck yyrule byacc CXXCOMPILE CXXLINK FLINK cfortran
12077 @c LocalWords: Catalogue preprocessable FLIBS libfoo baz JAVACFLAGS java exe
12078 @c LocalWords: SunOS fying basenames exeext uninstalled oldinclude kr FSF's
12079 @c LocalWords: pkginclude oldincludedir sysconf sharedstate localstate gcc rm
12080 @c LocalWords: sysconfdir sharedstatedir localstatedir preexist CLEANFILES gz
12081 @c LocalWords: unnumberedsubsec depfile tmpdepfile depmode const interoperate
12082 @c LocalWords: JAVAC javac JAVAROOT builddir CLASSPATH ENV pyc pyo pkgpython
12083 @c LocalWords: pyexecdir pkgpyexecdir Python's pythondir pkgpythondir txi ois
12084 @c LocalWords: installinfo vers MAKEINFO makeinfo MAKEINFOFLAGS noinstall rf
12085 @c LocalWords: mandir thesame alsothesame installman myexecbin DESTDIR Pinard
12086 @c LocalWords: uninstall installdirs uninstalls MOSTLYCLEANFILES mostlyclean
12087 @c LocalWords: DISTCLEANFILES MAINTAINERCLEANFILES GZIP gzip shar exp
12088 @c LocalWords: distdir distcheck distcleancheck listfiles distuninstallcheck
12089 @c LocalWords: VPATH tarfile stdout XFAIL DejaGnu dejagnu DEJATOOL runtest ln
12090 @c LocalWords: RUNTESTDEFAULTFLAGS toolchain RUNTESTFLAGS asis readme DVIPS
12091 @c LocalWords: installcheck gzipped tarZ std utils etags mkid multilibbing cd
12092 @c LocalWords: ARGS taggable ETAGSFLAGS lang ctags CTAGSFLAGS GTAGS gtags idl
12093 @c LocalWords: foocc doit idlC multilibs ABIs cmindex defmac ARG enableval FC
12094 @c LocalWords: MSG xtrue DBG pathchk CYGWIN afile proglink versioned CVS's TE
12095 @c LocalWords: wildcards Autoconfiscated subsubheading autotools Meyering API
12096 @c LocalWords: ois's wildcard Wportability cartouche vrindex printindex Duret
12097 @c LocalWords: DSOMEFLAG DVERSION automake Lutz insertcopying versioning FAQ
12098 @c LocalWords: LTLIBOBJ Libtool's libtool's libltdl dlopening itutions libbar
12099 @c LocalWords: WANTEDLIBS libhello sublibraries libtop libsub dlopened Ratfor
12100 @c LocalWords: mymodule timestamps timestamp underquoted MAKEINFOHTMLFLAGS te
12101 @c LocalWords: GNUmakefile Subpackages subpackage's subpackages aux
12102 @c LocalWords: detailmenu Timeline pwd reldir AUTOM autom PREREQ FOOBAR libc
12103 @c LocalWords: libhand subpackage moduleN libmain libmisc FCFLAGS FCCOMPILE
12104 @c LocalWords: FCLINK subst sed ELCFILES elc MAKEINFOHTML dvips esyscmd ustar
12105 @c LocalWords: tarballs Woverride vfi ELFILES djm AutoMake honkin FSF
12106 @c LocalWords: fileutils precanned MacKenzie's reimplement termutils Tromey's
12107 @c LocalWords: cois gnitsians LIBPROGRAMS progs LIBLIBRARIES Textutils Ulrich
12108 @c LocalWords: Matzigkeit Drepper's Gord Matzigkeit's jm Dalley Debian org
12109 @c LocalWords: Administrivia ILU CORBA Sourceware Molenda sourceware Elliston
12110 @c LocalWords: dep Oliva Akim Demaille Aiieeee Demaillator Akim's sourcequake
12111 @c LocalWords: grep backported screenshots libgcj KB unnumberedsubsubsec pre
12112 @c LocalWords: precomputing hacky makedepend inline clearmake LD PRELOAD Rel
12113 @c LocalWords: syscalls perlhist acl pm multitable headitem fdl appendixsec
12114 @c LocalWords: LTALLOCA MALLOC malloc memcmp strdup alloca libcompat xyz DFOO
12115 @c LocalWords: unprefixed buildable preprocessed DBAZ DDATADIR WARNINGCFLAGS
12116 @c LocalWords: LIBFOOCFLAGS LIBFOOLDFLAGS ftable testSubDir obj LIBTOOLFLAGS
12117 @c LocalWords: barexec Pinard's automatize initialize lzma