1 \input texinfo @c -*-texinfo-*-
3 @setfilename automake.info
10 @c @ovar(ARG, DEFAULT)
11 @c -------------------
12 @c The ARG is an optional argument. To be used for macro arguments in
13 @c their documentation (@defmac).
15 @r{[}@var{\varname\}@r{]}
18 @set PACKAGE_BUGREPORT bug-automake@@gnu.org
22 This manual is for GNU Automake (version @value{VERSION},
23 @value{UPDATED}), a program that creates GNU standards-compliant
24 Makefiles from template files.
26 Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
27 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation,
31 Permission is granted to copy, distribute and/or modify this document
32 under the terms of the GNU Free Documentation License,
33 Version 1.3 or any later version published by the Free Software
34 Foundation; with no Invariant Sections, with no Front-Cover texts,
35 and with no Back-Cover Texts. A copy of the license is included in the
36 section entitled ``GNU Free Documentation License.''
41 @c info Automake points to the Automake package's documentation
42 @c info automake points to the automake script's documentation
43 @c (Autoconf has a similar setup.)
44 @dircategory Software development
46 * Automake: (automake). Making GNU standards-compliant Makefiles.
49 @dircategory Individual utilities
51 * aclocal: (automake)Invoking aclocal. Generating aclocal.m4.
52 * automake: (automake)Invoking Automake. Generating Makefile.in.
57 @subtitle For version @value{VERSION}, @value{UPDATED}
58 @author David MacKenzie
60 @author Alexandre Duret-Lutz
62 @vskip 0pt plus 1filll
67 @c We use the following macros to define indices:
68 @c @cindex concepts, and anything that does not fit elsewhere
69 @c @vindex Makefile variables
71 @c @acindex Autoconf/Automake/Libtool/M4/... macros
72 @c @opindex tool options
74 @c Define an index of configure macros.
76 @c Define an index of options.
78 @c Define an index of targets.
80 @c Define an index of commands.
83 @c Put the macros in the function index.
86 @c Put everything else into one index (arbitrarily chosen to be the concept index).
93 @comment node-name, next, previous, up
99 * Introduction:: Automake's purpose
100 * Autotools Introduction:: An Introduction to the Autotools
101 * Generalities:: General ideas
102 * Examples:: Some example packages
103 * Invoking Automake:: Creating a Makefile.in
104 * configure:: Scanning configure.ac or configure.in
105 * Directories:: Declaring subdirectories
106 * Programs:: Building programs and libraries
107 * Other Objects:: Other derived objects
108 * Other GNU Tools:: Other GNU Tools
109 * Documentation:: Building documentation
110 * Install:: What gets installed
111 * Clean:: What gets cleaned
112 * Dist:: What goes in a distribution
113 * Tests:: Support for test suites
114 * Rebuilding:: Automatic rebuilding of Makefile
115 * Options:: Changing Automake's behavior
116 * Miscellaneous:: Miscellaneous rules
117 * Include:: Including extra files in an Automake template
118 * Conditionals:: Conditionals
119 * Gnits:: The effect of @option{--gnu} and @option{--gnits}
120 * Cygnus:: The effect of @option{--cygnus}
121 * Not Enough:: When Automake is not Enough
122 * Distributing:: Distributing the Makefile.in
123 * API Versioning:: About compatibility between Automake versions
124 * Upgrading:: Upgrading to a Newer Automake Version
125 * FAQ:: Frequently Asked Questions
126 * History:: Notes about the history of Automake
127 * Copying This Manual:: How to make copies of this manual
128 * Indices:: Indices of variables, macros, and concepts
131 --- The Detailed Node Listing ---
133 An Introduction to the Autotools
135 * GNU Build System:: Introducing the GNU Build System
136 * Use Cases:: Use Cases for the GNU Build System
137 * Why Autotools:: How Autotools Help
138 * Hello World:: A Small Hello World Package
140 Use Cases for the GNU Build System
142 * Basic Installation:: Common installation procedure
143 * Standard Targets:: A list of standard Makefile targets
144 * Standard Directory Variables:: A list of standard directory variables
145 * Standard Configuration Variables:: Using configuration variables
146 * config.site:: Using a config.site file
147 * VPATH Builds:: Parallel build trees
148 * Two-Part Install:: Installing data and programs separately
149 * Cross-Compilation:: Building for other architectures
150 * Renaming:: Renaming programs at install time
151 * DESTDIR:: Building binary packages with DESTDIR
152 * Preparing Distributions:: Rolling out tarballs
153 * Dependency Tracking:: Automatic dependency tracking
154 * Nested Packages:: The GNU Build Systems can be nested
158 * Creating amhello:: Create @file{amhello-1.0.tar.gz} from scratch
159 * amhello Explained:: @file{configure.ac} and @file{Makefile.am} explained
163 * General Operation:: General operation of Automake
164 * Strictness:: Standards conformance checking
165 * Uniform:: The Uniform Naming Scheme
166 * Canonicalization:: How derived variables are named
167 * Length Limitations:: Staying below the command line length limit
168 * User Variables:: Variables reserved for the user
169 * Auxiliary Programs:: Programs automake might require
171 Some example packages
173 * Complete:: A simple example, start to finish
174 * true:: Building true and false
176 Scanning @file{configure.ac}
178 * Requirements:: Configuration requirements
179 * Optional:: Other things Automake recognizes
180 * Invoking aclocal:: Auto-generating aclocal.m4
181 * Macros:: Autoconf macros supplied with Automake
183 Auto-generating aclocal.m4
185 * aclocal Options:: Options supported by aclocal
186 * Macro Search Path:: How aclocal finds .m4 files
187 * Extending aclocal:: Writing your own aclocal macros
188 * Local Macros:: Organizing local macros
189 * Serials:: Serial lines in Autoconf macros
190 * Future of aclocal:: aclocal's scheduled death
192 Autoconf macros supplied with Automake
194 * Public Macros:: Macros that you can use.
195 * Obsolete Macros:: Macros that you should stop using.
196 * Private Macros:: Macros that you should not use.
200 * Subdirectories:: Building subdirectories recursively
201 * Conditional Subdirectories:: Conditionally not building directories
202 * Alternative:: Subdirectories without recursion
203 * Subpackages:: Nesting packages
205 Conditional Subdirectories
207 * SUBDIRS vs DIST_SUBDIRS:: Two sets of directories
208 * Subdirectories with AM_CONDITIONAL:: Specifying conditional subdirectories
209 * Subdirectories with AC_SUBST:: Another way for conditional recursion
210 * Unconfigured Subdirectories:: Not even creating a @samp{Makefile}
212 Building Programs and Libraries
214 * A Program:: Building a program
215 * A Library:: Building a library
216 * A Shared Library:: Building a Libtool library
217 * Program and Library Variables:: Variables controlling program and
219 * Default _SOURCES:: Default source files
220 * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
221 * Program Variables:: Variables used when building a program
222 * Yacc and Lex:: Yacc and Lex support
223 * C++ Support:: Compiling C++ sources
224 * Objective C Support:: Compiling Objective C sources
225 * Unified Parallel C Support:: Compiling Unified Parallel C sources
226 * Assembly Support:: Compiling assembly sources
227 * Fortran 77 Support:: Compiling Fortran 77 sources
228 * Fortran 9x Support:: Compiling Fortran 9x sources
229 * Java Support:: Compiling Java sources
230 * Vala Support:: Compiling Vala sources
231 * Support for Other Languages:: Compiling other languages
232 * ANSI:: Automatic de-ANSI-fication (obsolete)
233 * Dependencies:: Automatic dependency tracking
234 * EXEEXT:: Support for executable extensions
238 * Program Sources:: Defining program sources
239 * Linking:: Linking with libraries or extra objects
240 * Conditional Sources:: Handling conditional sources
241 * Conditional Programs:: Building program conditionally
243 Building a Shared Library
245 * Libtool Concept:: Introducing Libtool
246 * Libtool Libraries:: Declaring Libtool Libraries
247 * Conditional Libtool Libraries:: Building Libtool Libraries Conditionally
248 * Conditional Libtool Sources:: Choosing Library Sources Conditionally
249 * Libtool Convenience Libraries:: Building Convenience Libtool Libraries
250 * Libtool Modules:: Building Libtool Modules
251 * Libtool Flags:: Using _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS
252 * LTLIBOBJS:: Using $(LTLIBOBJS) and $(LTALLOCA)
253 * Libtool Issues:: Common Issues Related to Libtool's Use
257 * Preprocessing Fortran 77:: Preprocessing Fortran 77 sources
258 * Compiling Fortran 77 Files:: Compiling Fortran 77 sources
259 * Mixing Fortran 77 With C and C++:: Mixing Fortran 77 With C and C++
261 Mixing Fortran 77 With C and C++
263 * How the Linker is Chosen:: Automatic linker selection
267 * Compiling Fortran 9x Files:: Compiling Fortran 9x sources
269 Other Derived Objects
271 * Scripts:: Executable scripts
272 * Headers:: Header files
273 * Data:: Architecture-independent data files
274 * Sources:: Derived sources
278 * Built Sources Example:: Several ways to handle built sources.
282 * Emacs Lisp:: Emacs Lisp
288 Building documentation
291 * Man Pages:: Man pages
295 * Basics of Installation:: What gets installed where
296 * The Two Parts of Install:: Installing data and programs separately
297 * Extending Installation:: Adding your own rules for installation
298 * Staged Installs:: Installation in a temporary location
299 * Install Rules for the User:: Useful additional rules
303 * Basics of Distribution:: Files distributed by default
304 * Fine-grained Distribution Control:: @code{dist_} and @code{nodist_} prefixes
305 * The dist Hook:: A target for last-minute distribution changes
306 * Checking the Distribution:: @samp{make distcheck} explained
307 * The Types of Distributions:: A variety of formats and compression methods
309 Support for Test Suites
311 * Simple Tests:: Listing programs and scripts in @code{TESTS}
312 * Simple Tests using parallel-tests:: More powerful test driver
313 * DejaGnu Tests:: Interfacing with the external testing framework
314 * Install Tests:: Running tests on installed packages
318 * Tags:: Interfacing to etags and mkid
319 * Suffixes:: Handling new file extensions
320 * Multilibs:: Support for multilibs.
324 * Usage of Conditionals:: Declaring conditional content
325 * Limits of Conditionals:: Enclosing complete statements
327 When Automake Isn't Enough
329 * Extending:: Adding new rules or overriding existing ones.
330 * Third-Party Makefiles:: Integrating Non-Automake @file{Makefile}s.
332 Frequently Asked Questions about Automake
334 * CVS:: CVS and generated files
335 * maintainer-mode:: missing and AM_MAINTAINER_MODE
336 * Wildcards:: Why doesn't Automake support wildcards?
337 * Limitations on File Names:: Limitations on source and installed file names
338 * distcleancheck:: Files left in build directory after distclean
339 * Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS
340 * Renamed Objects:: Why are object files sometimes renamed?
341 * Per-Object Flags:: How to simulate per-object flags?
342 * Multiple Outputs:: Writing rules for tools with many output files
343 * Hard-Coded Install Paths:: Installing to hard-coded locations
344 * Debugging Make Rules:: Strategies when things don't work as expected
348 * Timeline:: The Automake story.
349 * Dependency Tracking Evolution:: Evolution of Automatic Dependency Tracking
350 * Releases:: Statistics about Automake Releases
352 Dependency Tracking Evolution
354 * First Take on Dependencies:: Precomputed dependency tracking
355 * Dependencies As Side Effects:: Update at developer compile time
356 * Dependencies for the User:: Update at user compile time
357 * Techniques for Dependencies:: Alternative approaches
358 * Recommendations for Tool Writers:: What tool writers can do to help
359 * Future Directions for Dependencies:: Languages Automake does not know
363 * GNU Free Documentation License:: License for copying this manual
367 * Macro Index:: Index of Autoconf macros
368 * Variable Index:: Index of Makefile variables
369 * General Index:: General index
378 @chapter Introduction
380 Automake is a tool for automatically generating @file{Makefile.in}s
381 from files called @file{Makefile.am}. Each @file{Makefile.am} is
382 basically a series of @command{make} variable
383 definitions@footnote{These variables are also called @dfn{make macros}
384 in Make terminology, however in this manual we reserve the term
385 @dfn{macro} for Autoconf's macros.}, with rules being thrown in
386 occasionally. The generated @file{Makefile.in}s are compliant with
387 the GNU Makefile standards.
389 @cindex GNU Makefile standards
391 The GNU Makefile Standards Document
392 (@pxref{Makefile Conventions, , , standards, The GNU Coding Standards})
393 is long, complicated, and subject to change. The goal of Automake is to
394 remove the burden of Makefile maintenance from the back of the
395 individual GNU maintainer (and put it on the back of the Automake
398 The typical Automake input file is simply a series of variable definitions.
399 Each such file is processed to create a @file{Makefile.in}. There
400 should generally be one @file{Makefile.am} per directory of a project.
402 @cindex Constraints of Automake
403 @cindex Automake constraints
405 Automake does constrain a project in certain ways; for instance, it
406 assumes that the project uses Autoconf (@pxref{Top, , Introduction,
407 autoconf, The Autoconf Manual}), and enforces certain restrictions on
408 the @file{configure.ac} contents@footnote{Older Autoconf versions used
409 @file{configure.in}. Autoconf 2.50 and greater promotes
410 @file{configure.ac} over @file{configure.in}. The rest of this
411 documentation will refer to @file{configure.ac}, but Automake also
412 supports @file{configure.in} for backward compatibility.}.
414 @cindex Automake requirements
415 @cindex Requirements, Automake
417 Automake requires @command{perl} in order to generate the
418 @file{Makefile.in}s. However, the distributions created by Automake are
419 fully GNU standards-compliant, and do not require @command{perl} in order
422 @cindex Bugs, reporting
423 @cindex Reporting bugs
424 @cindex E-mail, bug reports
426 Mail suggestions and bug reports for Automake to
427 @email{@value{PACKAGE_BUGREPORT}}.
429 @node Autotools Introduction
430 @chapter An Introduction to the Autotools
432 If you are new to Automake, maybe you know that it is part of a set of
433 tools called @emph{The Autotools}. Maybe you've already delved into a
434 package full of files named @file{configure}, @file{configure.ac},
435 @file{Makefile.in}, @file{Makefile.am}, @file{aclocal.m4}, @dots{},
436 some of them claiming to be @emph{generated by} Autoconf or Automake.
437 But the exact purpose of these files and their relations is probably
438 fuzzy. The goal of this chapter is to introduce you to this machinery,
439 to show you how it works and how powerful it is. If you've never
440 installed or seen such a package, do not worry: this chapter will walk
443 If you need some teaching material, more illustrations, or a less
444 @command{automake}-centered continuation, some slides for this
445 introduction are available in Alexandre Duret-Lutz's
446 @uref{http://www.lrde.epita.fr/@/~adl/@/autotools.html,
448 This chapter is the written version of the first part of his tutorial.
451 * GNU Build System:: Introducing the GNU Build System
452 * Use Cases:: Use Cases for the GNU Build System
453 * Why Autotools:: How Autotools Help
454 * Hello World:: A Small Hello World Package
457 @node GNU Build System
458 @section Introducing the GNU Build System
459 @cindex GNU Build System, introduction
461 It is a truth universally acknowledged, that as a developer in
462 possession of a new package, you must be in want of a build system.
464 In the Unix world, such a build system is traditionally achieved using
465 the command @command{make} (@pxref{Top, , Overview, make, The GNU Make
466 Manual}). You express the recipe to build your package in a
467 @file{Makefile}. This file is a set of rules to build the files in
468 the package. For instance the program @file{prog} may be built by
469 running the linker on the files @file{main.o}, @file{foo.o}, and
470 @file{bar.o}; the file @file{main.o} may be built by running the
471 compiler on @file{main.c}; etc. Each time @command{make} is run, it
472 reads @file{Makefile}, checks the existence and modification time of
473 the files mentioned, decides what files need to be built (or rebuilt),
474 and runs the associated commands.
476 When a package needs to be built on a different platform than the one
477 it was developed on, its @file{Makefile} usually needs to be adjusted.
478 For instance the compiler may have another name or require more
479 options. In 1991, David J. MacKenzie got tired of customizing
480 @file{Makefile} for the 20 platforms he had to deal with. Instead, he
481 handcrafted a little shell script called @file{configure} to
482 automatically adjust the @file{Makefile} (@pxref{Genesis, , Genesis,
483 autoconf, The Autoconf Manual}). Compiling his package was now
484 as simple as running @code{./configure && make}.
486 @cindex GNU Coding Standards
488 Today this process has been standardized in the GNU project. The GNU
489 Coding Standards (@pxref{Managing Releases, The Release Process, ,
490 standards, The GNU Coding Standards}) explains how each package of the
491 GNU project should have a @file{configure} script, and the minimal
492 interface it should have. The @file{Makefile} too should follow some
493 established conventions. The result? A unified build system that
494 makes all packages almost indistinguishable by the installer. In its
495 simplest scenario, all the installer has to do is to unpack the
496 package, run @code{./configure && make && make install}, and repeat
497 with the next package to install.
499 We call this build system the @dfn{GNU Build System}, since it was
500 grown out of the GNU project. However it is used by a vast number of
501 other packages: following any existing convention has its advantages.
503 @cindex Autotools, introduction
505 The Autotools are tools that will create a GNU Build System for your
506 package. Autoconf mostly focuses on @file{configure} and Automake on
507 @file{Makefile}s. It is entirely possible to create a GNU Build
508 System without the help of these tools. However it is rather
509 burdensome and error-prone. We will discuss this again after some
510 illustration of the GNU Build System in action.
513 @section Use Cases for the GNU Build System
514 @cindex GNU Build System, use cases
515 @cindex GNU Build System, features
516 @cindex Features of the GNU Build System
517 @cindex Use Cases for the GNU Build System
518 @cindex @file{amhello-1.0.tar.gz}, location
519 @cindex @file{amhello-1.0.tar.gz}, use cases
521 In this section we explore several use cases for the GNU Build System.
522 You can replay all these examples on the @file{amhello-1.0.tar.gz}
523 package distributed with Automake. If Automake is installed on your
524 system, you should find a copy of this file in
525 @file{@var{prefix}/share/doc/automake/amhello-1.0.tar.gz}, where
526 @var{prefix} is the installation prefix specified during configuration
527 (@var{prefix} defaults to @file{/usr/local}, however if Automake was
528 installed by some GNU/Linux distribution it most likely has been set
529 to @file{/usr}). If you do not have a copy of Automake installed,
530 you can find a copy of this file inside the @file{doc/} directory of
531 the Automake package.
533 Some of the following use cases present features that are in fact
534 extensions to the GNU Build System. Read: they are not specified by
535 the GNU Coding Standards, but they are nonetheless part of the build
536 system created by the Autotools. To keep things simple, we do not
537 point out the difference. Our objective is to show you many of the
538 features that the build system created by the Autotools will offer to
542 * Basic Installation:: Common installation procedure
543 * Standard Targets:: A list of standard Makefile targets
544 * Standard Directory Variables:: A list of standard directory variables
545 * Standard Configuration Variables:: Using configuration variables
546 * config.site:: Using a config.site file
547 * VPATH Builds:: Parallel build trees
548 * Two-Part Install:: Installing data and programs separately
549 * Cross-Compilation:: Building for other architectures
550 * Renaming:: Renaming programs at install time
551 * DESTDIR:: Building binary packages with DESTDIR
552 * Preparing Distributions:: Rolling out tarballs
553 * Dependency Tracking:: Automatic dependency tracking
554 * Nested Packages:: The GNU Build Systems can be nested
557 @node Basic Installation
558 @subsection Basic Installation
559 @cindex Configuration, basics
560 @cindex Installation, basics
561 @cindex GNU Build System, basics
563 The most common installation procedure looks as follows.
566 ~ % @kbd{tar zxf amhello-1.0.tar.gz}
567 ~ % @kbd{cd amhello-1.0}
568 ~/amhello-1.0 % @kbd{./configure}
570 config.status: creating Makefile
571 config.status: creating src/Makefile
573 ~/amhello-1.0 % @kbd{make}
575 ~/amhello-1.0 % @kbd{make check}
577 ~/amhello-1.0 % @kbd{su}
579 /home/adl/amhello-1.0 # @kbd{make install}
581 /home/adl/amhello-1.0 # @kbd{exit}
582 ~/amhello-1.0 % @kbd{make installcheck}
588 The user first unpacks the package. Here, and in the following
589 examples, we will use the non-portable @code{tar zxf} command for
590 simplicity. On a system without GNU @command{tar} installed, this
591 command should read @code{gunzip -c amhello-1.0.tar.gz | tar xf -}.
593 The user then enters the newly created directory to run the
594 @file{configure} script. This script probes the system for various
595 features, and finally creates the @file{Makefile}s. In this toy
596 example there are only two @file{Makefile}s, but in real-world projects,
597 there may be many more, usually one @file{Makefile} per directory.
599 It is now possible to run @code{make}. This will construct all the
600 programs, libraries, and scripts that need to be constructed for the
601 package. In our example, this compiles the @file{hello} program.
602 All files are constructed in place, in the source tree; we will see
603 later how this can be changed.
605 @code{make check} causes the package's tests to be run. This step is
606 not mandatory, but it is often good to make sure the programs that
607 have been built behave as they should, before you decide to install
608 them. Our example does not contain any tests, so running @code{make
611 @cindex su, before @code{make install}
612 After everything has been built, and maybe tested, it is time to
613 install it on the system. That means copying the programs,
614 libraries, header files, scripts, and other data files from the
615 source directory to their final destination on the system. The
616 command @code{make install} will do that. However, by default
617 everything will be installed in subdirectories of @file{/usr/local}:
618 binaries will go into @file{/usr/local/bin}, libraries will end up in
619 @file{/usr/local/lib}, etc. This destination is usually not writable
620 by any user, so we assume that we have to become root before we can
621 run @code{make install}. In our example, running @code{make install}
622 will copy the program @file{hello} into @file{/usr/local/bin}
623 and @file{README} into @file{/usr/local/share/doc/amhello}.
625 A last and optional step is to run @code{make installcheck}. This
626 command may run tests on the installed files. @code{make check} tests
627 the files in the source tree, while @code{make installcheck} tests
628 their installed copies. The tests run by the latter can be different
629 from those run by the former. For instance, there are tests that
630 cannot be run in the source tree. Conversely, some packages are set
631 up so that @code{make installcheck} will run the very same tests as
632 @code{make check}, only on different files (non-installed
633 vs.@: installed). It can make a difference, for instance when the
634 source tree's layout is different from that of the installation.
635 Furthermore it may help to diagnose an incomplete installation.
637 Presently most packages do not have any @code{installcheck} tests
638 because the existence of @code{installcheck} is little known, and its
639 usefulness is neglected. Our little toy package is no better: @code{make
640 installcheck} does nothing.
642 @node Standard Targets
643 @subsection Standard @file{Makefile} Targets
645 So far we have come across four ways to run @command{make} in the GNU
646 Build System: @code{make}, @code{make check}, @code{make install}, and
647 @code{make installcheck}. The words @code{check}, @code{install}, and
648 @code{installcheck}, passed as arguments to @command{make}, are called
649 @dfn{targets}. @code{make} is a shorthand for @code{make all},
650 @code{all} being the default target in the GNU Build System.
652 Here is a list of the most useful targets that the GNU Coding Standards
658 Build programs, libraries, documentation, etc.@: (same as @code{make}).
661 Install what needs to be installed, copying the files from the
662 package's tree to system-wide directories.
663 @item make install-strip
664 @trindex install-strip
665 Same as @code{make install}, then strip debugging symbols. Some
666 users like to trade space for useful bug reports@enddots{}
669 The opposite of @code{make install}: erase the installed files.
670 (This needs to be run from the same build tree that was installed.)
673 Erase from the build tree the files built by @code{make all}.
676 Additionally erase anything @code{./configure} created.
679 Run the test suite, if any.
680 @item make installcheck
681 @trindex installcheck
682 Check the installed programs or libraries, if supported.
685 Recreate @file{@var{package}-@var{version}.tar.gz} from all the source
689 @node Standard Directory Variables
690 @subsection Standard Directory Variables
691 @cindex directory variables
693 The GNU Coding Standards also specify a hierarchy of variables to
694 denote installation directories. Some of these are:
696 @multitable {Directory variable} {@code{$@{datarootdir@}/doc/$@{PACKAGE@}}}
697 @headitem Directory variable @tab Default value
698 @item @code{prefix} @tab @code{/usr/local}
699 @item @w{@ @ @code{exec_prefix}} @tab @code{$@{prefix@}}
700 @item @w{@ @ @ @ @code{bindir}} @tab @code{$@{exec_prefix@}/bin}
701 @item @w{@ @ @ @ @code{libdir}} @tab @code{$@{exec_prefix@}/lib}
702 @item @w{@ @ @ @ @dots{}}
703 @item @w{@ @ @code{includedir}} @tab @code{$@{prefix@}/include}
704 @item @w{@ @ @code{datarootdir}} @tab @code{$@{prefix@}/share}
705 @item @w{@ @ @ @ @code{datadir}} @tab @code{$@{datarootdir@}}
706 @item @w{@ @ @ @ @code{mandir}} @tab @code{$@{datarootdir@}/man}
707 @item @w{@ @ @ @ @code{infodir}} @tab @code{$@{datarootdir@}/info}
708 @item @w{@ @ @ @ @code{docdir}} @tab @code{$@{datarootdir@}/doc/$@{PACKAGE@}}
709 @item @w{@ @ @dots{}}
712 @c We should provide a complete table somewhere, but not here. The
713 @c complete list of directory variables it too confusing as-is. It
714 @c requires some explanations that are too complicated for this
715 @c introduction. Besides listing directories like localstatedir
716 @c would make the explanations in ``Two-Part Install'' harder.
718 Each of these directories has a role which is often obvious from its
719 name. In a package, any installable file will be installed in one of
720 these directories. For instance in @code{amhello-1.0}, the program
721 @file{hello} is to be installed in @var{bindir}, the directory for
722 binaries. The default value for this directory is
723 @file{/usr/local/bin}, but the user can supply a different value when
724 calling @command{configure}. Also the file @file{README} will be
725 installed into @var{docdir}, which defaults to
726 @file{/usr/local/share/doc/amhello}.
730 As a user, if you wish to install a package on your own account, you
731 could proceed as follows:
734 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr}
736 ~/amhello-1.0 % @kbd{make}
738 ~/amhello-1.0 % @kbd{make install}
742 This would install @file{~/usr/bin/hello} and
743 @file{~/usr/share/doc/amhello/README}.
745 The list of all such directory options is shown by
746 @code{./configure --help}.
748 @node Standard Configuration Variables
749 @subsection Standard Configuration Variables
750 @cindex configuration variables, overriding
752 The GNU Coding Standards also define a set of standard configuration
753 variables used during the build. Here are some:
762 @item @code{CXXFLAGS}
766 @item @code{CPPFLAGS}
767 C/C++ preprocessor flags
771 @command{configure} usually does a good job at setting appropriate
772 values for these variables, but there are cases where you may want to
773 override them. For instance you may have several versions of a
774 compiler installed and would like to use another one, you may have
775 header files installed outside the default search path of the
776 compiler, or even libraries out of the way of the linker.
778 Here is how one would call @command{configure} to force it to use
779 @command{gcc-3} as C compiler, use header files from
780 @file{~/usr/include} when compiling, and libraries from
781 @file{~/usr/lib} when linking.
784 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr CC=gcc-3 \
785 CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib}
788 Again, a full list of these variables appears in the output of
789 @code{./configure --help}.
792 @subsection Overriding Default Configuration Setting with @file{config.site}
793 @cindex @file{config.site} example
795 When installing several packages using the same setup, it can be
796 convenient to create a file to capture common settings.
797 If a file named @file{@var{prefix}/share/config.site} exists,
798 @command{configure} will source it at the beginning of its execution.
800 Recall the command from the previous section:
803 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr CC=gcc-3 \
804 CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib}
807 Assuming we are installing many package in @file{~/usr}, and will
808 always want to use these definitions of @code{CC}, @code{CPPFLAGS}, and
809 @code{LDFLAGS}, we can automate this by creating the following
810 @file{~/usr/share/config.site} file:
813 test -z "$CC" && CC=gcc-3
814 test -z "$CPPFLAGS" && CPPFLAGS=-I$HOME/usr/include
815 test -z "$LDFLAGS" && LDFLAGS=-L$HOME/usr/lib
818 Now, any time a @file{configure} script is using the @file{~/usr}
819 prefix, it will execute the above @file{config.site} and define
820 these three variables.
823 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr}
824 configure: loading site script /home/adl/usr/share/config.site
828 @xref{Site Defaults, , Setting Site Defaults, autoconf, The Autoconf
829 Manual}, for more information about this feature.
833 @subsection Parallel Build Trees (a.k.a.@: VPATH Builds)
834 @cindex Parallel build trees
836 @cindex source tree and build tree
837 @cindex build tree and source tree
838 @cindex trees, source vs.@: build
840 The GNU Build System distinguishes two trees: the source tree, and
843 The source tree is rooted in the directory containing
844 @file{configure}. It contains all the sources files (those that are
845 distributed), and may be arranged using several subdirectories.
847 The build tree is rooted in the directory in which @file{configure}
848 was run, and is populated with all object files, programs, libraries,
849 and other derived files built from the sources (and hence not
850 distributed). The build tree usually has the same subdirectory layout
851 as the source tree; its subdirectories are created automatically by
854 If @file{configure} is executed in its own directory, the source and
855 build trees are combined: derived files are constructed in the same
856 directories as their sources. This was the case in our first
857 installation example (@pxref{Basic Installation}).
859 A common request from users is that they want to confine all derived
860 files to a single directory, to keep their source directories
861 uncluttered. Here is how we could run @file{configure} to build
862 everything in a subdirectory called @file{build/}.
865 ~ % @kbd{tar zxf ~/amhello-1.0.tar.gz}
866 ~ % @kbd{cd amhello-1.0}
867 ~/amhello-1.0 % @kbd{mkdir build && cd build}
868 ~/amhello-1.0/build % @kbd{../configure}
870 ~/amhello-1.0/build % @kbd{make}
874 These setups, where source and build trees are different, are often
875 called @dfn{parallel builds} or @dfn{VPATH builds}. The expression
876 @emph{parallel build} is misleading: the word @emph{parallel} is a
877 reference to the way the build tree shadows the source tree, it is not
878 about some concurrency in the way build commands are run. For this
879 reason we refer to such setups using the name @emph{VPATH builds} in
880 the following. @emph{VPATH} is the name of the @command{make} feature
881 used by the @file{Makefile}s to allow these builds (@pxref{General
882 Search, , @code{VPATH}: Search Path for All Prerequisites, make, The
885 @cindex multiple configurations, example
886 @cindex debug build, example
887 @cindex optimized build, example
889 VPATH builds have other interesting uses. One is to build the same
890 sources with multiple configurations. For instance:
893 ~ % @kbd{tar zxf ~/amhello-1.0.tar.gz}
894 ~ % @kbd{cd amhello-1.0}
895 ~/amhello-1.0 % @kbd{mkdir debug optim && cd debug}
896 ~/amhello-1.0/debug % @kbd{../configure CFLAGS='-g -O0'}
898 ~/amhello-1.0/debug % @kbd{make}
900 ~/amhello-1.0/debug % cd ../optim
901 ~/amhello-1.0/optim % @kbd{../configure CFLAGS='-O3 -fomit-frame-pointer'}
903 ~/amhello-1.0/optim % @kbd{make}
907 With network file systems, a similar approach can be used to build the
908 same sources on different machines. For instance, suppose that the
909 sources are installed on a directory shared by two hosts: @code{HOST1}
910 and @code{HOST2}, which may be different platforms.
913 ~ % @kbd{cd /nfs/src}
914 /nfs/src % @kbd{tar zxf ~/amhello-1.0.tar.gz}
917 On the first host, you could create a local build directory:
919 [HOST1] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
920 [HOST1] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure}
922 [HOST1] /tmp/amh % @kbd{make && sudo make install}
927 (Here we assume that the installer has configured @command{sudo} so it
928 can execute @code{make install} with root privileges; it is more convenient
929 than using @command{su} like in @ref{Basic Installation}).
931 On the second host, you would do exactly the same, possibly at
934 [HOST2] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
935 [HOST2] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure}
937 [HOST2] /tmp/amh % @kbd{make && sudo make install}
941 @cindex read-only source tree
942 @cindex source tree, read-only
944 In this scenario, nothing forbids the @file{/nfs/src/amhello-1.0}
945 directory from being read-only. In fact VPATH builds are also a means
946 of building packages from a read-only medium such as a CD-ROM. (The
947 FSF used to sell CD-ROM with unpacked source code, before the GNU
948 project grew so big.)
950 @node Two-Part Install
951 @subsection Two-Part Installation
953 In our last example (@pxref{VPATH Builds}), a source tree was shared
954 by two hosts, but compilation and installation were done separately on
957 The GNU Build System also supports networked setups where part of the
958 installed files should be shared amongst multiple hosts. It does so
959 by distinguishing architecture-dependent files from
960 architecture-independent files, and providing two @file{Makefile}
961 targets to install each of these classes of files.
963 @trindex install-exec
964 @trindex install-data
966 These targets are @code{install-exec} for architecture-dependent files
967 and @code{install-data} for architecture-independent files.
968 The command we used up to now, @code{make install}, can be thought of
969 as a shorthand for @code{make install-exec install-data}.
971 From the GNU Build System point of view, the distinction between
972 architecture-dependent files and architecture-independent files is
973 based exclusively on the directory variable used to specify their
974 installation destination. In the list of directory variables we
975 provided earlier (@pxref{Standard Directory Variables}), all the
976 variables based on @var{exec-prefix} designate architecture-dependent
977 directories whose files will be installed by @code{make install-exec}.
978 The others designate architecture-independent directories and will
979 serve files installed by @code{make install-data}. @xref{The Two Parts
980 of Install}, for more details.
982 Here is how we could revisit our two-host installation example,
983 assuming that (1) we want to install the package directly in
984 @file{/usr}, and (2) the directory @file{/usr/share} is shared by the
987 On the first host we would run
989 [HOST1] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
990 [HOST1] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure --prefix /usr}
992 [HOST1] /tmp/amh % @kbd{make && sudo make install}
996 On the second host, however, we need only install the
997 architecture-specific files.
999 [HOST2] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
1000 [HOST2] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure --prefix /usr}
1002 [HOST2] /tmp/amh % @kbd{make && sudo make install-exec}
1006 In packages that have installation checks, it would make sense to run
1007 @code{make installcheck} (@pxref{Basic Installation}) to verify that
1008 the package works correctly despite the apparent partial installation.
1010 @node Cross-Compilation
1011 @subsection Cross-Compilation
1012 @cindex cross-compilation
1014 To @dfn{cross-compile} is to build on one platform a binary that will
1015 run on another platform. When speaking of cross-compilation, it is
1016 important to distinguish between the @dfn{build platform} on which
1017 the compilation is performed, and the @dfn{host platform} on which the
1018 resulting executable is expected to run. The following
1019 @command{configure} options are used to specify each of them:
1022 @item --build=@var{build}
1023 @opindex --build=@var{build}
1024 The system on which the package is built.
1025 @item --host=@var{host}
1026 @opindex --host=@var{host}
1027 The system where built programs and libraries will run.
1030 When the @option{--host} is used, @command{configure} will search for
1031 the cross-compiling suite for this platform. Cross-compilation tools
1032 commonly have their target architecture as prefix of their name. For
1033 instance my cross-compiler for MinGW32 has its binaries called
1034 @code{i586-mingw32msvc-gcc}, @code{i586-mingw32msvc-ld},
1035 @code{i586-mingw32msvc-as}, etc.
1037 @cindex MinGW cross-compilation example
1038 @cindex cross-compilation example
1040 Here is how we could build @code{amhello-1.0} for
1041 @code{i586-mingw32msvc} on a GNU/Linux PC.
1044 ~/amhello-1.0 % @kbd{./configure --build i686-pc-linux-gnu --host i586-mingw32msvc}
1045 checking for a BSD-compatible install... /usr/bin/install -c
1046 checking whether build environment is sane... yes
1047 checking for gawk... gawk
1048 checking whether make sets $(MAKE)... yes
1049 checking for i586-mingw32msvc-strip... i586-mingw32msvc-strip
1050 checking for i586-mingw32msvc-gcc... i586-mingw32msvc-gcc
1051 checking for C compiler default output file name... a.exe
1052 checking whether the C compiler works... yes
1053 checking whether we are cross compiling... yes
1054 checking for suffix of executables... .exe
1055 checking for suffix of object files... o
1056 checking whether we are using the GNU C compiler... yes
1057 checking whether i586-mingw32msvc-gcc accepts -g... yes
1058 checking for i586-mingw32msvc-gcc option to accept ANSI C...
1060 ~/amhello-1.0 % @kbd{make}
1062 ~/amhello-1.0 % @kbd{cd src; file hello.exe}
1063 hello.exe: MS Windows PE 32-bit Intel 80386 console executable not relocatable
1066 The @option{--host} and @option{--build} options are usually all we
1067 need for cross-compiling. The only exception is if the package being
1068 built is itself a cross-compiler: we need a third option to specify
1069 its target architecture.
1072 @item --target=@var{target}
1073 @opindex --target=@var{target}
1074 When building compiler tools: the system for which the tools will
1078 For instance when installing GCC, the GNU Compiler Collection, we can
1079 use @option{--target=@/@var{target}} to specify that we want to build
1080 GCC as a cross-compiler for @var{target}. Mixing @option{--build} and
1081 @option{--target}, we can actually cross-compile a cross-compiler;
1082 such a three-way cross-compilation is known as a @dfn{Canadian cross}.
1084 @xref{Specifying Names, , Specifying the System Type, autoconf, The
1085 Autoconf Manual}, for more information about these @command{configure}
1089 @subsection Renaming Programs at Install Time
1090 @cindex Renaming programs
1091 @cindex Transforming program names
1092 @cindex Programs, renaming during installation
1094 The GNU Build System provides means to automatically rename
1095 executables and manpages before they are installed (@pxref{Man Pages}).
1096 This is especially convenient
1097 when installing a GNU package on a system that already has a
1098 proprietary implementation you do not want to overwrite. For instance,
1099 you may want to install GNU @command{tar} as @command{gtar} so you can
1100 distinguish it from your vendor's @command{tar}.
1102 This can be done using one of these three @command{configure} options.
1105 @item --program-prefix=@var{prefix}
1106 @opindex --program-prefix=@var{prefix}
1107 Prepend @var{prefix} to installed program names.
1108 @item --program-suffix=@var{suffix}
1109 @opindex --program-suffix=@var{suffix}
1110 Append @var{suffix} to installed program names.
1111 @item --program-transform-name=@var{program}
1112 @opindex --program-transform-name=@var{program}
1113 Run @code{sed @var{program}} on installed program names.
1116 The following commands would install @file{hello}
1117 as @file{/usr/local/bin/test-hello}, for instance.
1120 ~/amhello-1.0 % @kbd{./configure --program-prefix test-}
1122 ~/amhello-1.0 % @kbd{make}
1124 ~/amhello-1.0 % @kbd{sudo make install}
1129 @subsection Building Binary Packages Using DESTDIR
1132 The GNU Build System's @code{make install} and @code{make uninstall}
1133 interface does not exactly fit the needs of a system administrator
1134 who has to deploy and upgrade packages on lots of hosts. In other
1135 words, the GNU Build System does not replace a package manager.
1137 Such package managers usually need to know which files have been
1138 installed by a package, so a mere @code{make install} is
1141 @cindex Staged installation
1143 The @code{DESTDIR} variable can be used to perform a staged
1144 installation. The package should be configured as if it was going to
1145 be installed in its final location (e.g., @code{--prefix /usr}), but
1146 when running @code{make install}, the @code{DESTDIR} should be set to
1147 the absolute name of a directory into which the installation will be
1148 diverted. From this directory it is easy to review which files are
1149 being installed where, and finally copy them to their final location
1152 @cindex Binary package
1154 For instance here is how we could create a binary package containing a
1155 snapshot of all the files to be installed.
1158 ~/amhello-1.0 % @kbd{./configure --prefix /usr}
1160 ~/amhello-1.0 % @kbd{make}
1162 ~/amhello-1.0 % @kbd{make DESTDIR=$HOME/inst install}
1164 ~/amhello-1.0 % @kbd{cd ~/inst}
1165 ~/inst % @kbd{find . -type f -print > ../files.lst}
1166 ~/inst % @kbd{tar zcvf ~/amhello-1.0-i686.tar.gz `cat ../files.lst`}
1168 ./usr/share/doc/amhello/README
1171 After this example, @code{amhello-1.0-i686.tar.gz} is ready to be
1172 uncompressed in @file{/} on many hosts. (Using @code{`cat ../files.lst`}
1173 instead of @samp{.} as argument for @command{tar} avoids entries for
1174 each subdirectory in the archive: we would not like @command{tar} to
1175 restore the modification time of @file{/}, @file{/usr/}, etc.)
1177 Note that when building packages for several architectures, it might
1178 be convenient to use @code{make install-data} and @code{make
1179 install-exec} (@pxref{Two-Part Install}) to gather
1180 architecture-independent files in a single package.
1182 @xref{Install}, for more information.
1184 @c We should document PRE_INSTALL/POST_INSTALL/NORMAL_INSTALL and their
1185 @c UNINSTALL counterparts.
1187 @node Preparing Distributions
1188 @subsection Preparing Distributions
1189 @cindex Preparing distributions
1190 @cindex Packages, preparation
1191 @cindex Distributions, preparation
1193 We have already mentioned @code{make dist}. This target collects all
1194 your source files and the necessary parts of the build system to
1195 create a tarball named @file{@var{package}-@var{version}.tar.gz}.
1197 @cindex @code{distcheck} better than @code{dist}
1199 Another, more useful command is @code{make distcheck}. The
1200 @code{distcheck} target constructs
1201 @file{@var{package}-@var{version}.tar.gz} just as well as @code{dist},
1202 but it additionally ensures most of the use cases presented so far
1207 It attempts a full compilation of the package (@pxref{Basic
1208 Installation}), unpacking the newly constructed tarball, running
1209 @code{make}, @code{make check}, @code{make install}, as well as
1210 @code{make installcheck}, and even @code{make dist},
1212 it tests VPATH builds with read-only source tree (@pxref{VPATH Builds}),
1214 it makes sure @code{make clean}, @code{make distclean}, and @code{make
1215 uninstall} do not omit any file (@pxref{Standard Targets}),
1217 and it checks that @code{DESTDIR} installations work (@pxref{DESTDIR}).
1220 All of these actions are performed in a temporary subdirectory, so
1221 that no root privileges are required.
1223 Releasing a package that fails @code{make distcheck} means that one of
1224 the scenarios we presented will not work and some users will be
1225 disappointed. Therefore it is a good practice to release a package
1226 only after a successful @code{make distcheck}. This of course does
1227 not imply that the package will be flawless, but at least it will
1228 prevent some of the embarrassing errors you may find in packages
1229 released by people who have never heard about @code{distcheck} (like
1230 @code{DESTDIR} not working because of a typo, or a distributed file
1231 being erased by @code{make clean}, or even @code{VPATH} builds not
1234 @xref{Creating amhello}, to recreate @file{amhello-1.0.tar.gz} using
1235 @code{make distcheck}. @xref{Checking the Distribution}, for more
1236 information about @code{distcheck}.
1238 @node Dependency Tracking
1239 @subsection Automatic Dependency Tracking
1240 @cindex Dependency tracking
1242 Dependency tracking is performed as a side-effect of compilation.
1243 Each time the build system compiles a source file, it computes its
1244 list of dependencies (in C these are the header files included by the
1245 source being compiled). Later, any time @command{make} is run and a
1246 dependency appears to have changed, the dependent files will be
1249 When @command{configure} is executed, you can see it probing each
1250 compiler for the dependency mechanism it supports (several mechanisms
1254 ~/amhello-1.0 % @kbd{./configure --prefix /usr}
1256 checking dependency style of gcc... gcc3
1260 Because dependencies are only computed as a side-effect of the
1261 compilation, no dependency information exists the first time a package
1262 is built. This is OK because all the files need to be built anyway:
1263 @code{make} does not have to decide which files need to be rebuilt.
1264 In fact, dependency tracking is completely useless for one-time builds
1265 and there is a @command{configure} option to disable this:
1268 @item --disable-dependency-tracking
1269 @opindex --disable-dependency-tracking
1270 Speed up one-time builds.
1273 Some compilers do not offer any practical way to derive the list of
1274 dependencies as a side-effect of the compilation, requiring a separate
1275 run (maybe of another tool) to compute these dependencies. The
1276 performance penalty implied by these methods is important enough to
1277 disable them by default. The option @option{--enable-dependency-tracking}
1278 must be passed to @command{configure} to activate them.
1281 @item --enable-dependency-tracking
1282 @opindex --enable-dependency-tracking
1283 Do not reject slow dependency extractors.
1286 @xref{Dependency Tracking Evolution}, for some discussion about the
1287 different dependency tracking schemes used by Automake over the years.
1289 @node Nested Packages
1290 @subsection Nested Packages
1291 @cindex Nested packages
1292 @cindex Packages, nested
1295 Although nesting packages isn't something we would recommend to
1296 someone who is discovering the Autotools, it is a nice feature worthy
1297 of mention in this small advertising tour.
1299 Autoconfiscated packages (that means packages whose build system have
1300 been created by Autoconf and friends) can be nested to arbitrary
1303 A typical setup is that package A will distribute one of the libraries
1304 it needs in a subdirectory. This library B is a complete package with
1305 its own GNU Build System. The @command{configure} script of A will
1306 run the @command{configure} script of B as part of its execution,
1307 building and installing A will also build and install B. Generating a
1308 distribution for A will also include B.
1310 It is possible to gather several packages like this. GCC is a heavy
1311 user of this feature. This gives installers a single package to
1312 configure, build and install, while it allows developers to work on
1313 subpackages independently.
1315 When configuring nested packages, the @command{configure} options
1316 given to the top-level @command{configure} are passed recursively to
1317 nested @command{configure}s. A package that does not understand an
1318 option will ignore it, assuming it is meaningful to some other
1321 @opindex --help=recursive
1323 The command @code{configure --help=recursive} can be used to display
1324 the options supported by all the included packages.
1326 @xref{Subpackages}, for an example setup.
1329 @section How Autotools Help
1330 @cindex Autotools, purpose
1332 There are several reasons why you may not want to implement the GNU
1333 Build System yourself (read: write a @file{configure} script and
1334 @file{Makefile}s yourself).
1338 As we have seen, the GNU Build System has a lot of
1339 features (@pxref{Use Cases}).
1340 Some users may expect features you have not implemented because
1341 you did not need them.
1343 Implementing these features portably is difficult and exhausting.
1344 Think of writing portable shell scripts, and portable
1345 @file{Makefile}s, for systems you may not have handy. @xref{Portable
1346 Shell, , Portable Shell Programming, autoconf, The Autoconf Manual}, to
1349 You will have to upgrade your setup to follow changes to the GNU
1353 The GNU Autotools take all this burden off your back and provide:
1357 Tools to create a portable, complete, and self-contained GNU Build
1358 System, from simple instructions.
1359 @emph{Self-contained} meaning the resulting build system does not
1360 require the GNU Autotools.
1362 A central place where fixes and improvements are made:
1363 a bug-fix for a portability issue will benefit every package.
1366 Yet there also exist reasons why you may want NOT to use the
1367 Autotools@enddots{} For instance you may be already using (or used to)
1368 another incompatible build system. Autotools will only be useful if
1369 you do accept the concepts of the GNU Build System. People who have their
1370 own idea of how a build system should work will feel frustrated by the
1374 @section A Small Hello World
1375 @cindex Example Hello World
1376 @cindex Hello World example
1377 @cindex @file{amhello-1.0.tar.gz}, creation
1379 In this section we recreate the @file{amhello-1.0} package from
1380 scratch. The first subsection shows how to call the Autotools to
1381 instantiate the GNU Build System, while the second explains the
1382 meaning of the @file{configure.ac} and @file{Makefile.am} files read
1386 * Creating amhello:: Create @file{amhello-1.0.tar.gz} from scratch
1387 * amhello Explained:: @file{configure.ac} and @file{Makefile.am} explained
1390 @node Creating amhello
1391 @subsection Creating @file{amhello-1.0.tar.gz}
1393 Here is how we can recreate @file{amhello-1.0.tar.gz} from scratch.
1394 The package is simple enough so that we will only need to write 5
1395 files. (You may copy them from the final @file{amhello-1.0.tar.gz}
1396 that is distributed with Automake if you do not want to write them.)
1398 Create the following files in an empty directory.
1403 @file{src/main.c} is the source file for the @file{hello} program. We
1404 store it in the @file{src/} subdirectory, because later, when the package
1405 evolves, it will ease the addition of a @file{man/} directory for man
1406 pages, a @file{data/} directory for data files, etc.
1408 ~/amhello % @kbd{cat src/main.c}
1415 puts ("Hello World!");
1416 puts ("This is " PACKAGE_STRING ".");
1422 @file{README} contains some very limited documentation for our little
1425 ~/amhello % @kbd{cat README}
1426 This is a demonstration package for GNU Automake.
1427 Type `info Automake' to read the Automake manual.
1431 @file{Makefile.am} and @file{src/Makefile.am} contain Automake
1432 instructions for these two directories.
1435 ~/amhello % @kbd{cat src/Makefile.am}
1436 bin_PROGRAMS = hello
1437 hello_SOURCES = main.c
1438 ~/amhello % @kbd{cat Makefile.am}
1440 dist_doc_DATA = README
1444 Finally, @file{configure.ac} contains Autoconf instructions to
1445 create the @command{configure} script.
1448 ~/amhello % @kbd{cat configure.ac}
1449 AC_INIT([amhello], [1.0], [@value{PACKAGE_BUGREPORT}])
1450 AM_INIT_AUTOMAKE([-Wall -Werror foreign])
1452 AC_CONFIG_HEADERS([config.h])
1461 @cindex @command{autoreconf}, example
1463 Once you have these five files, it is time to run the Autotools to
1464 instantiate the build system. Do this using the @command{autoreconf}
1468 ~/amhello % @kbd{autoreconf --install}
1469 configure.ac: installing `./install-sh'
1470 configure.ac: installing `./missing'
1471 src/Makefile.am: installing `./depcomp'
1474 At this point the build system is complete.
1476 In addition to the three scripts mentioned in its output, you can see
1477 that @command{autoreconf} created four other files: @file{configure},
1478 @file{config.h.in}, @file{Makefile.in}, and @file{src/Makefile.in}.
1479 The latter three files are templates that will be adapted to the
1480 system by @command{configure} under the names @file{config.h},
1481 @file{Makefile}, and @file{src/Makefile}. Let's do this:
1484 ~/amhello % @kbd{./configure}
1485 checking for a BSD-compatible install... /usr/bin/install -c
1486 checking whether build environment is sane... yes
1487 checking for gawk... no
1488 checking for mawk... mawk
1489 checking whether make sets $(MAKE)... yes
1490 checking for gcc... gcc
1491 checking for C compiler default output file name... a.out
1492 checking whether the C compiler works... yes
1493 checking whether we are cross compiling... no
1494 checking for suffix of executables...
1495 checking for suffix of object files... o
1496 checking whether we are using the GNU C compiler... yes
1497 checking whether gcc accepts -g... yes
1498 checking for gcc option to accept ISO C89... none needed
1499 checking for style of include used by make... GNU
1500 checking dependency style of gcc... gcc3
1501 configure: creating ./config.status
1502 config.status: creating Makefile
1503 config.status: creating src/Makefile
1504 config.status: creating config.h
1505 config.status: executing depfiles commands
1509 @cindex @code{distcheck} example
1511 You can see @file{Makefile}, @file{src/Makefile}, and @file{config.h}
1512 being created at the end after @command{configure} has probed the
1513 system. It is now possible to run all the targets we wish
1514 (@pxref{Standard Targets}). For instance:
1517 ~/amhello % @kbd{make}
1519 ~/amhello % @kbd{src/hello}
1521 This is amhello 1.0.
1522 ~/amhello % @kbd{make distcheck}
1524 =============================================
1525 amhello-1.0 archives ready for distribution:
1527 =============================================
1530 Note that running @command{autoreconf} is only needed initially when
1531 the GNU Build System does not exist. When you later change some
1532 instructions in a @file{Makefile.am} or @file{configure.ac}, the
1533 relevant part of the build system will be regenerated automatically
1534 when you execute @command{make}.
1536 @command{autoreconf} is a script that calls @command{autoconf},
1537 @command{automake}, and a bunch of other commands in the right order.
1538 If you are beginning with these tools, it is not important to figure
1539 out in which order all these tools should be invoked and why. However,
1540 because Autoconf and Automake have separate manuals, the important
1541 point to understand is that @command{autoconf} is in charge of
1542 creating @file{configure} from @file{configure.ac}, while
1543 @command{automake} is in charge of creating @file{Makefile.in}s from
1544 @file{Makefile.am}s and @file{configure.ac}. This should at least
1545 direct you to the right manual when seeking answers.
1548 @node amhello Explained
1549 @subsection @file{amhello-1.0} Explained
1551 Let us begin with the contents of @file{configure.ac}.
1554 AC_INIT([amhello], [1.0], [@value{PACKAGE_BUGREPORT}])
1555 AM_INIT_AUTOMAKE([-Wall -Werror foreign])
1557 AC_CONFIG_HEADERS([config.h])
1565 This file is read by both @command{autoconf} (to create
1566 @file{configure}) and @command{automake} (to create the various
1567 @file{Makefile.in}s). It contains a series of M4 macros that will be
1568 expanded as shell code to finally form the @file{configure} script.
1569 We will not elaborate on the syntax of this file, because the Autoconf
1570 manual has a whole section about it (@pxref{Writing Autoconf Input, ,
1571 Writing @file{configure.ac}, autoconf, The Autoconf Manual}).
1573 The macros prefixed with @code{AC_} are Autoconf macros, documented
1574 in the Autoconf manual (@pxref{Autoconf Macro Index, , Autoconf Macro
1575 Index, autoconf, The Autoconf Manual}). The macros that start with
1576 @code{AM_} are Automake macros, documented later in this manual
1577 (@pxref{Macro Index}).
1579 The first two lines of @file{configure.ac} initialize Autoconf and
1580 Automake. @code{AC_INIT} takes in as parameters the name of the package,
1581 its version number, and a contact address for bug-reports about the
1582 package (this address is output at the end of @code{./configure
1583 --help}, for instance). When adapting this setup to your own package,
1584 by all means please do not blindly copy Automake's address: use the
1585 mailing list of your package, or your own mail address.
1591 The argument to @code{AM_INIT_AUTOMAKE} is a list of options for
1592 @command{automake} (@pxref{Options}). @option{-Wall} and
1593 @option{-Werror} ask @command{automake} to turn on all warnings and
1594 report them as errors. We are speaking of @strong{Automake} warnings
1595 here, such as dubious instructions in @file{Makefile.am}. This has
1596 absolutely nothing to do with how the compiler will be called, even
1597 though it may support options with similar names. Using @option{-Wall
1598 -Werror} is a safe setting when starting to work on a package: you do
1599 not want to miss any issues. Later you may decide to relax things a
1600 bit. The @option{foreign} option tells Automake that this package
1601 will not follow the GNU Standards. GNU packages should always
1602 distribute additional files such as @file{ChangeLog}, @file{AUTHORS},
1603 etc. We do not want @command{automake} to complain about these
1604 missing files in our small example.
1606 The @code{AC_PROG_CC} line causes the @command{configure} script to
1607 search for a C compiler and define the variable @code{CC} with its
1608 name. The @file{src/Makefile.in} file generated by Automake uses the
1609 variable @code{CC} to build @file{hello}, so when @command{configure}
1610 creates @file{src/Makefile} from @file{src/Makefile.in}, it will define
1611 @code{CC} with the value it has found. If Automake is asked to create
1612 a @file{Makefile.in} that uses @code{CC} but @file{configure.ac} does
1613 not define it, it will suggest you add a call to @code{AC_PROG_CC}.
1615 The @code{AC_CONFIG_HEADERS([config.h])} invocation causes the
1616 @command{configure} script to create a @file{config.h} file gathering
1617 @samp{#define}s defined by other macros in @file{configure.ac}. In our
1618 case, the @code{AC_INIT} macro already defined a few of them. Here
1619 is an excerpt of @file{config.h} after @command{configure} has run:
1623 /* Define to the address where bug reports for this package should be sent. */
1624 #define PACKAGE_BUGREPORT "@value{PACKAGE_BUGREPORT}"
1626 /* Define to the full name and version of this package. */
1627 #define PACKAGE_STRING "amhello 1.0"
1631 As you probably noticed, @file{src/main.c} includes @file{config.h} so
1632 it can use @code{PACKAGE_STRING}. In a real-world project,
1633 @file{config.h} can grow really big, with one @samp{#define} per
1634 feature probed on the system.
1636 The @code{AC_CONFIG_FILES} macro declares the list of files that
1637 @command{configure} should create from their @file{*.in} templates.
1638 Automake also scans this list to find the @file{Makefile.am} files it must
1639 process. (This is important to remember: when adding a new directory
1640 to your project, you should add its @file{Makefile} to this list,
1641 otherwise Automake will never process the new @file{Makefile.am} you
1642 wrote in that directory.)
1644 Finally, the @code{AC_OUTPUT} line is a closing command that actually
1645 produces the part of the script in charge of creating the files
1646 registered with @code{AC_CONFIG_HEADERS} and @code{AC_CONFIG_FILES}.
1648 @cindex @command{autoscan}
1650 When starting a new project, we suggest you start with such a simple
1651 @file{configure.ac}, and gradually add the other tests it requires.
1652 The command @command{autoscan} can also suggest a few of the tests
1653 your package may need (@pxref{autoscan Invocation, , Using
1654 @command{autoscan} to Create @file{configure.ac}, autoconf, The
1657 @cindex @file{Makefile.am}, Hello World
1659 We now turn to @file{src/Makefile.am}. This file contains
1660 Automake instructions to build and install @file{hello}.
1663 bin_PROGRAMS = hello
1664 hello_SOURCES = main.c
1667 A @file{Makefile.am} has the same syntax as an ordinary
1668 @file{Makefile}. When @command{automake} processes a
1669 @file{Makefile.am} it copies the entire file into the output
1670 @file{Makefile.in} (that will be later turned into @file{Makefile} by
1671 @command{configure}) but will react to certain variable definitions
1672 by generating some build rules and other variables.
1673 Often @file{Makefile.am}s contain only a list of variable definitions as
1674 above, but they can also contain other variable and rule definitions that
1675 @command{automake} will pass along without interpretation.
1677 Variables that end with @code{_PROGRAMS} are special variables
1678 that list programs that the resulting @file{Makefile} should build.
1679 In Automake speak, this @code{_PROGRAMS} suffix is called a
1680 @dfn{primary}; Automake recognizes other primaries such as
1681 @code{_SCRIPTS}, @code{_DATA}, @code{_LIBRARIES}, etc.@: corresponding
1682 to different types of files.
1684 The @samp{bin} part of the @code{bin_PROGRAMS} tells
1685 @command{automake} that the resulting programs should be installed in
1686 @var{bindir}. Recall that the GNU Build System uses a set of variables
1687 to denote destination directories and allow users to customize these
1688 locations (@pxref{Standard Directory Variables}). Any such directory
1689 variable can be put in front of a primary (omitting the @code{dir}
1690 suffix) to tell @command{automake} where to install the listed files.
1692 Programs need to be built from source files, so for each program
1693 @code{@var{prog}} listed in a @code{@w{_PROGRAMS}} variable,
1694 @command{automake} will look for another variable named
1695 @code{@var{prog}_SOURCES} listing its source files. There may be more
1696 than one source file: they will all be compiled and linked together.
1698 Automake also knows that source files need to be distributed when
1699 creating a tarball (unlike built programs). So a side-effect of this
1700 @code{hello_SOURCES} declaration is that @file{main.c} will be
1701 part of the tarball created by @code{make dist}.
1703 Finally here are some explanations regarding the top-level
1708 dist_doc_DATA = README
1711 @code{SUBDIRS} is a special variable listing all directories that
1712 @command{make} should recurse into before processing the current
1713 directory. So this line is responsible for @command{make} building
1714 @file{src/hello} even though we run it from the top-level. This line
1715 also causes @code{make install} to install @file{src/hello} before
1716 installing @file{README} (not that this order matters).
1718 The line @code{dist_doc_DATA = README} causes @file{README} to be
1719 distributed and installed in @var{docdir}. Files listed with the
1720 @code{_DATA} primary are not automatically part of the tarball built
1721 with @code{make dist}, so we add the @code{dist_} prefix so they get
1722 distributed. However, for @file{README} it would not have been
1723 necessary: @command{automake} automatically distributes any
1724 @file{README} file it encounters (the list of other files
1725 automatically distributed is presented by @code{automake --help}).
1726 The only important effect of this second line is therefore to install
1727 @file{README} during @code{make install}.
1731 @chapter General ideas
1733 The following sections cover a few basic ideas that will help you
1734 understand how Automake works.
1737 * General Operation:: General operation of Automake
1738 * Strictness:: Standards conformance checking
1739 * Uniform:: The Uniform Naming Scheme
1740 * Canonicalization:: How derived variables are named
1741 * Length Limitations:: Staying below the command line length limit
1742 * User Variables:: Variables reserved for the user
1743 * Auxiliary Programs:: Programs automake might require
1747 @node General Operation
1748 @section General Operation
1750 Automake works by reading a @file{Makefile.am} and generating a
1751 @file{Makefile.in}. Certain variables and rules defined in the
1752 @file{Makefile.am} instruct Automake to generate more specialized code;
1753 for instance, a @code{bin_PROGRAMS} variable definition will cause rules
1754 for compiling and linking programs to be generated.
1756 @cindex Non-standard targets
1757 @cindex @code{cvs-dist}, non-standard example
1761 The variable definitions and rules in the @file{Makefile.am} are
1762 copied verbatim into the generated file. This allows you to add
1763 arbitrary code into the generated @file{Makefile.in}. For instance,
1764 the Automake distribution includes a non-standard rule for the
1765 @code{git-dist} target, which the Automake maintainer uses to make
1766 distributions from the source control system.
1768 @cindex GNU make extensions
1770 Note that most GNU make extensions are not recognized by Automake. Using
1771 such extensions in a @file{Makefile.am} will lead to errors or confusing
1774 @cindex Append operator
1776 A special exception is that the GNU make append operator, @samp{+=}, is
1777 supported. This operator appends its right hand argument to the variable
1778 specified on the left. Automake will translate the operator into
1779 an ordinary @samp{=} operator; @samp{+=} will thus work with any make program.
1782 Further note that variable assignments should not be indented with
1783 @key{TAB} characters, use spaces if necessary. On the other hand,
1784 rule commands should be indented with a leading @key{TAB} character.
1786 Automake tries to keep comments grouped with any adjoining rules or
1787 variable definitions.
1789 @cindex Make targets, overriding
1790 @cindex Make rules, overriding
1791 @cindex Overriding make rules
1792 @cindex Overriding make targets
1794 A rule defined in @file{Makefile.am} generally overrides any such
1795 rule of a similar name that would be automatically generated by
1796 @command{automake}. Although this is a supported feature, it is generally
1797 best to avoid making use of it, as sometimes the generated rules are
1800 @cindex Variables, overriding
1801 @cindex Overriding make variables
1803 Similarly, a variable defined in @file{Makefile.am} or
1804 @code{AC_SUBST}ed from @file{configure.ac} will override any
1805 definition of the variable that @command{automake} would ordinarily
1806 create. This feature is more often useful than the ability to
1807 override a rule. Be warned that many of the variables generated by
1808 @command{automake} are considered to be for internal use only, and their
1809 names might change in future releases.
1811 @cindex Recursive operation of Automake
1812 @cindex Automake, recursive operation
1813 @cindex Example of recursive operation
1815 When examining a variable definition, Automake will recursively examine
1816 variables referenced in the definition. For example, if Automake is
1817 looking at the content of @code{foo_SOURCES} in this snippet
1821 foo_SOURCES = c.c $(xs)
1824 it would use the files @file{a.c}, @file{b.c}, and @file{c.c} as the
1825 contents of @code{foo_SOURCES}.
1827 @cindex @code{##} (special Automake comment)
1828 @cindex Special Automake comment
1829 @cindex Comment, special to Automake
1831 Automake also allows a form of comment that is @emph{not} copied into
1832 the output; all lines beginning with @samp{##} (leading spaces allowed)
1833 are completely ignored by Automake.
1835 It is customary to make the first line of @file{Makefile.am} read:
1837 @cindex Makefile.am, first line
1838 @cindex First line of Makefile.am
1841 ## Process this file with automake to produce Makefile.in
1844 @c FIXME discuss putting a copyright into Makefile.am here? I would but
1845 @c I don't know quite what to say.
1847 @c FIXME document customary ordering of Makefile.am here!
1853 @cindex Non-GNU packages
1855 While Automake is intended to be used by maintainers of GNU packages, it
1856 does make some effort to accommodate those who wish to use it, but do
1857 not want to use all the GNU conventions.
1859 @cindex Strictness, defined
1860 @cindex Strictness, @option{foreign}
1861 @cindex @option{foreign} strictness
1862 @cindex Strictness, @option{gnu}
1863 @cindex @option{gnu} strictness
1864 @cindex Strictness, @option{gnits}
1865 @cindex @option{gnits} strictness
1867 To this end, Automake supports three levels of @dfn{strictness}---the
1868 strictness indicating how stringently Automake should check standards
1871 The valid strictness levels are:
1875 Automake will check for only those things that are absolutely
1876 required for proper operations. For instance, whereas GNU standards
1877 dictate the existence of a @file{NEWS} file, it will not be required in
1878 this mode. The name comes from the fact that Automake is intended to be
1879 used for GNU programs; these relaxed rules are not the standard mode of
1883 Automake will check---as much as possible---for compliance to the GNU
1884 standards for packages. This is the default.
1887 Automake will check for compliance to the as-yet-unwritten @dfn{Gnits
1888 standards}. These are based on the GNU standards, but are even more
1889 detailed. Unless you are a Gnits standards contributor, it is
1890 recommended that you avoid this option until such time as the Gnits
1891 standard is actually published (which may never happen).
1894 @xref{Gnits}, for more information on the precise implications of the
1897 Automake also has a special ``cygnus'' mode that is similar to
1898 strictness but handled differently. This mode is useful for packages
1899 that are put into a ``Cygnus'' style tree (e.g., the GCC tree).
1900 @xref{Cygnus}, for more information on this mode.
1904 @section The Uniform Naming Scheme
1906 @cindex Uniform naming scheme
1908 Automake variables generally follow a @dfn{uniform naming scheme} that
1909 makes it easy to decide how programs (and other derived objects) are
1910 built, and how they are installed. This scheme also supports
1911 @command{configure} time determination of what should be built.
1913 @cindex @code{_PROGRAMS} primary variable
1914 @cindex @code{PROGRAMS} primary variable
1915 @cindex Primary variable, @code{PROGRAMS}
1916 @cindex Primary variable, defined
1919 At @command{make} time, certain variables are used to determine which
1920 objects are to be built. The variable names are made of several pieces
1921 that are concatenated together.
1923 The piece that tells @command{automake} what is being built is commonly called
1924 the @dfn{primary}. For instance, the primary @code{PROGRAMS} holds a
1925 list of programs that are to be compiled and linked.
1928 @cindex @code{pkgdatadir}, defined
1929 @cindex @code{pkgincludedir}, defined
1930 @cindex @code{pkglibdir}, defined
1931 @cindex @code{pkglibexecdir}, defined
1934 @vindex pkgincludedir
1936 @vindex pkglibexecdir
1938 @cindex @code{PACKAGE}, directory
1939 A different set of names is used to decide where the built objects
1940 should be installed. These names are prefixes to the primary, and they
1941 indicate which standard directory should be used as the installation
1942 directory. The standard directory names are given in the GNU standards
1943 (@pxref{Directory Variables, , , standards, The GNU Coding Standards}).
1944 Automake extends this list with @code{pkgdatadir}, @code{pkgincludedir},
1945 @code{pkglibdir}, and @code{pkglibexecdir}; these are the same as the
1946 non-@samp{pkg} versions, but with @samp{$(PACKAGE)} appended. For instance,
1947 @code{pkglibdir} is defined as @samp{$(libdir)/$(PACKAGE)}.
1949 @cindex @code{EXTRA_}, prepending
1950 For each primary, there is one additional variable named by prepending
1951 @samp{EXTRA_} to the primary name. This variable is used to list
1952 objects that may or may not be built, depending on what
1953 @command{configure} decides. This variable is required because Automake
1954 must statically know the entire list of objects that may be built in
1955 order to generate a @file{Makefile.in} that will work in all cases.
1957 @cindex @code{EXTRA_PROGRAMS}, defined
1958 @cindex Example, @code{EXTRA_PROGRAMS}
1959 @cindex @command{cpio} example
1961 For instance, @command{cpio} decides at configure time which programs
1962 should be built. Some of the programs are installed in @code{bindir},
1963 and some are installed in @code{sbindir}:
1966 EXTRA_PROGRAMS = mt rmt
1967 bin_PROGRAMS = cpio pax
1968 sbin_PROGRAMS = $(MORE_PROGRAMS)
1971 Defining a primary without a prefix as a variable, e.g.,
1972 @samp{PROGRAMS}, is an error.
1974 Note that the common @samp{dir} suffix is left off when constructing the
1975 variable names; thus one writes @samp{bin_PROGRAMS} and not
1976 @samp{bindir_PROGRAMS}.
1978 Not every sort of object can be installed in every directory. Automake
1979 will flag those attempts it finds in error.
1980 Automake will also diagnose obvious misspellings in directory names.
1982 @cindex Extending list of installation directories
1983 @cindex Installation directories, extending list
1985 Sometimes the standard directories---even as augmented by
1986 Automake---are not enough. In particular it is sometimes useful, for
1987 clarity, to install objects in a subdirectory of some predefined
1988 directory. To this end, Automake allows you to extend the list of
1989 possible installation directories. A given prefix (e.g., @samp{zar})
1990 is valid if a variable of the same name with @samp{dir} appended is
1991 defined (e.g., @samp{zardir}).
1993 For instance, the following snippet will install @file{file.xml} into
1994 @samp{$(datadir)/xml}.
1997 xmldir = $(datadir)/xml
2001 @cindex @samp{noinst_} primary prefix, definition
2004 The special prefix @samp{noinst_} indicates that the objects in question
2005 should be built but not installed at all. This is usually used for
2006 objects required to build the rest of your package, for instance static
2007 libraries (@pxref{A Library}), or helper scripts.
2009 @cindex @samp{check_} primary prefix, definition
2012 The special prefix @samp{check_} indicates that the objects in question
2013 should not be built until the @samp{make check} command is run. Those
2014 objects are not installed either.
2016 The current primary names are @samp{PROGRAMS}, @samp{LIBRARIES},
2017 @samp{LISP}, @samp{PYTHON}, @samp{JAVA}, @samp{SCRIPTS}, @samp{DATA},
2018 @samp{HEADERS}, @samp{MANS}, and @samp{TEXINFOS}.
2030 Some primaries also allow additional prefixes that control other
2031 aspects of @command{automake}'s behavior. The currently defined prefixes
2032 are @samp{dist_}, @samp{nodist_}, @samp{nobase_}, and @samp{notrans_}.
2033 These prefixes are explained later (@pxref{Program and Library Variables})
2034 (@pxref{Man Pages}).
2037 @node Length Limitations
2038 @section Staying below the command line length limit
2040 @cindex command line length limit
2043 Traditionally, most unix-like systems have a length limitation for the
2044 command line arguments and environment contents when creating new
2045 processes (see for example
2046 @uref{http://www.in-ulm.de/@/~mascheck/@/various/@/argmax/} for an
2047 overview on this issue),
2048 which of course also applies to commands spawned by @command{make}.
2049 POSIX requires this limit to be at least 4096 bytes, and most modern
2050 systems have quite high limits (or are unlimited).
2052 In order to create portable Makefiles that do not trip over these
2053 limits, it is necessary to keep the length of file lists bounded.
2054 Unfortunately, it is not possible to do so fully transparently within
2055 Automake, so your help may be needed. Typically, you can split long
2056 file lists manually and use different installation directory names for
2057 each list. For example,
2060 data_DATA = file1 @dots{} file@var{N} file@var{N+1} @dots{} file@var{2N}
2064 may also be written as
2067 data_DATA = file1 @dots{} file@var{N}
2068 data2dir = $(datadir)
2069 data2_DATA = file@var{N+1} @dots{} file@var{2N}
2073 and will cause Automake to treat the two lists separately during
2074 @code{make install}. See @ref{The Two Parts of Install} for choosing
2075 directory names that will keep the ordering of the two parts of
2076 installation Note that @code{make dist} may still only work on a host
2077 with a higher length limit in this example.
2079 Automake itself employs a couple of strategies to avoid long command
2080 lines. For example, when @samp{$@{srcdir@}/} is prepended to file
2081 names, as can happen with above @code{$(data_DATA)} lists, it limits
2082 the amount of arguments passed to external commands.
2084 Unfortunately, some system's @command{make} commands may prepend
2085 @code{VPATH} prefixes like @samp{$@{srcdir@}/} to file names from the
2086 source tree automatically (@pxref{Automatic Rule Rewriting, , Automatic
2087 Rule Rewriting, autoconf, The Autoconf Manual}). In this case, the user
2088 may have to switch to use GNU Make, or refrain from using VPATH builds,
2089 in order to stay below the length limit.
2091 For libraries and programs built from many sources, convenience archives
2092 may be used as intermediates in order to limit the object list length
2093 (@pxref{Libtool Convenience Libraries}).
2096 @node Canonicalization
2097 @section How derived variables are named
2099 @cindex canonicalizing Automake variables
2101 Sometimes a Makefile variable name is derived from some text the
2102 maintainer supplies. For instance, a program name listed in
2103 @samp{_PROGRAMS} is rewritten into the name of a @samp{_SOURCES}
2104 variable. In cases like this, Automake canonicalizes the text, so that
2105 program names and the like do not have to follow Makefile variable naming
2106 rules. All characters in the name except for letters, numbers, the
2107 strudel (@@), and the underscore are turned into underscores when making
2108 variable references.
2110 For example, if your program is named @file{sniff-glue}, the derived
2111 variable name would be @samp{sniff_glue_SOURCES}, not
2112 @samp{sniff-glue_SOURCES}. Similarly the sources for a library named
2113 @file{libmumble++.a} should be listed in the
2114 @samp{libmumble___a_SOURCES} variable.
2116 The strudel is an addition, to make the use of Autoconf substitutions in
2117 variable names less obfuscating.
2120 @node User Variables
2121 @section Variables reserved for the user
2123 @cindex variables, reserved for the user
2124 @cindex user variables
2126 Some @file{Makefile} variables are reserved by the GNU Coding Standards
2127 for the use of the ``user''---the person building the package. For
2128 instance, @code{CFLAGS} is one such variable.
2130 Sometimes package developers are tempted to set user variables such as
2131 @code{CFLAGS} because it appears to make their job easier. However,
2132 the package itself should never set a user variable, particularly not
2133 to include switches that are required for proper compilation of the
2134 package. Since these variables are documented as being for the
2135 package builder, that person rightfully expects to be able to override
2136 any of these variables at build time.
2138 To get around this problem, Automake introduces an automake-specific
2139 shadow variable for each user flag variable. (Shadow variables are
2140 not introduced for variables like @code{CC}, where they would make no
2141 sense.) The shadow variable is named by prepending @samp{AM_} to the
2142 user variable's name. For instance, the shadow variable for
2143 @code{YFLAGS} is @code{AM_YFLAGS}. The package maintainer---that is,
2144 the author(s) of the @file{Makefile.am} and @file{configure.ac}
2145 files---may adjust these shadow variables however necessary.
2147 @xref{Flag Variables Ordering}, for more discussion about these
2148 variables and how they interact with per-target variables.
2150 @node Auxiliary Programs
2151 @section Programs automake might require
2153 @cindex Programs, auxiliary
2154 @cindex Auxiliary programs
2156 Automake sometimes requires helper programs so that the generated
2157 @file{Makefile} can do its work properly. There are a fairly large
2158 number of them, and we list them here.
2160 Although all of these files are distributed and installed with
2161 Automake, a couple of them are maintained separately. The Automake
2162 copies are updated before each release, but we mention the original
2163 source in case you need more recent versions.
2167 This is a wrapper primarily for the Microsoft lib archiver, to make
2172 These two files are used for de-ANSI-fication support (obsolete
2176 This is a wrapper for compilers that do not accept options @option{-c}
2177 and @option{-o} at the same time. It is only used when absolutely
2178 required. Such compilers are rare, with the Microsoft C/C++ Compiler
2179 as the most notable exception. This wrapper also makes the following
2180 common options available for that compiler, while performing file name
2181 translation where needed: @option{-I}, @option{-L}, @option{-l},
2182 @option{-Wl,} and @option{-Xlinker}.
2186 These two programs compute the canonical triplets for the given build,
2187 host, or target architecture. These programs are updated regularly to
2188 support new architectures and fix probes broken by changes in new
2189 kernel versions. Each new release of Automake comes with up-to-date
2190 copies of these programs. If your copy of Automake is getting old,
2191 you are encouraged to fetch the latest versions of these files from
2192 @url{http://savannah.gnu.org/git/?group=config} before making a
2196 This file is not a program, it is a @file{configure} fragment used for
2197 multilib support (@pxref{Multilibs}). This file is maintained in the
2198 GCC tree at @url{http://gcc.gnu.org/svn.html}.
2201 This program understands how to run a compiler so that it will
2202 generate not only the desired output but also dependency information
2203 that is then used by the automatic dependency tracking feature
2204 (@pxref{Dependencies}).
2207 This program is used to byte-compile Emacs Lisp code.
2210 This is a replacement for the @command{install} program that works on
2211 platforms where @command{install} is unavailable or unusable.
2214 This script is used to generate a @file{version.texi} file. It examines
2215 a file and prints some date information about it.
2218 This wraps a number of programs that are typically only required by
2219 maintainers. If the program in question doesn't exist,
2220 @command{missing} prints an informative warning and attempts to fix
2221 things so that the build can continue.
2224 This script used to be a wrapper around @samp{mkdir -p}, which is not
2225 portable. Now we prefer to use @samp{install-sh -d} when @command{configure}
2226 finds that @samp{mkdir -p} does not work, this makes one less script to
2229 For backward compatibility @file{mkinstalldirs} is still used and
2230 distributed when @command{automake} finds it in a package. But it is no
2231 longer installed automatically, and it should be safe to remove it.
2234 This is used to byte-compile Python scripts.
2237 This program duplicates a tree of directories, using symbolic links
2238 instead of copying files. Such an operation is performed when building
2239 multilibs (@pxref{Multilibs}). This file is maintained in the GCC
2240 tree at @url{http://gcc.gnu.org/svn.html}.
2243 Not a program, this file is required for @samp{make dvi}, @samp{make
2244 ps} and @samp{make pdf} to work when Texinfo sources are in the
2245 package. The latest version can be downloaded from
2246 @url{http://www.gnu.org/software/texinfo/}.
2249 This program wraps @command{lex} and @command{yacc} to rename their
2250 output files. It also ensures that, for instance, multiple
2251 @command{yacc} instances can be invoked in a single directory in
2258 @chapter Some example packages
2260 This section contains two small examples.
2262 The first example (@pxref{Complete}) assumes you have an existing
2263 project already using Autoconf, with handcrafted @file{Makefile}s, and
2264 that you want to convert it to using Automake. If you are discovering
2265 both tools, it is probably better that you look at the Hello World
2266 example presented earlier (@pxref{Hello World}).
2268 The second example (@pxref{true}) shows how two programs can be built
2269 from the same file, using different compilation parameters. It
2270 contains some technical digressions that are probably best skipped on
2274 * Complete:: A simple example, start to finish
2275 * true:: Building true and false
2280 @section A simple example, start to finish
2282 @cindex Complete example
2284 Let's suppose you just finished writing @code{zardoz}, a program to make
2285 your head float from vortex to vortex. You've been using Autoconf to
2286 provide a portability framework, but your @file{Makefile.in}s have been
2287 ad-hoc. You want to make them bulletproof, so you turn to Automake.
2289 @cindex @code{AM_INIT_AUTOMAKE}, example use
2291 The first step is to update your @file{configure.ac} to include the
2292 commands that @command{automake} needs. The way to do this is to add an
2293 @code{AM_INIT_AUTOMAKE} call just after @code{AC_INIT}:
2296 AC_INIT([zardoz], [1.0])
2301 Since your program doesn't have any complicating factors (e.g., it
2302 doesn't use @code{gettext}, it doesn't want to build a shared library),
2303 you're done with this part. That was easy!
2305 @cindex @command{aclocal} program, introduction
2306 @cindex @file{aclocal.m4}, preexisting
2307 @cindex @file{acinclude.m4}, defined
2309 Now you must regenerate @file{configure}. But to do that, you'll need
2310 to tell @command{autoconf} how to find the new macro you've used. The
2311 easiest way to do this is to use the @command{aclocal} program to
2312 generate your @file{aclocal.m4} for you. But wait@dots{} maybe you
2313 already have an @file{aclocal.m4}, because you had to write some hairy
2314 macros for your program. The @command{aclocal} program lets you put
2315 your own macros into @file{acinclude.m4}, so simply rename and then
2319 mv aclocal.m4 acinclude.m4
2324 @cindex @command{zardoz} example
2326 Now it is time to write your @file{Makefile.am} for @code{zardoz}.
2327 Since @code{zardoz} is a user program, you want to install it where the
2328 rest of the user programs go: @code{bindir}. Additionally,
2329 @code{zardoz} has some Texinfo documentation. Your @file{configure.ac}
2330 script uses @code{AC_REPLACE_FUNCS}, so you need to link against
2331 @samp{$(LIBOBJS)}. So here's what you'd write:
2334 bin_PROGRAMS = zardoz
2335 zardoz_SOURCES = main.c head.c float.c vortex9.c gun.c
2336 zardoz_LDADD = $(LIBOBJS)
2338 info_TEXINFOS = zardoz.texi
2341 Now you can run @samp{automake --add-missing} to generate your
2342 @file{Makefile.in} and grab any auxiliary files you might need, and
2347 @section Building true and false
2349 @cindex Example, @command{false} and @command{true}
2350 @cindex @command{false} Example
2351 @cindex @command{true} Example
2353 Here is another, trickier example. It shows how to generate two
2354 programs (@code{true} and @code{false}) from the same source file
2355 (@file{true.c}). The difficult part is that each compilation of
2356 @file{true.c} requires different @code{cpp} flags.
2359 bin_PROGRAMS = true false
2361 false_LDADD = false.o
2364 $(COMPILE) -DEXIT_CODE=0 -c true.c
2367 $(COMPILE) -DEXIT_CODE=1 -o false.o -c true.c
2370 Note that there is no @code{true_SOURCES} definition. Automake will
2371 implicitly assume that there is a source file named @file{true.c}
2372 (@pxref{Default _SOURCES}), and
2373 define rules to compile @file{true.o} and link @file{true}. The
2374 @samp{true.o: true.c} rule supplied by the above @file{Makefile.am},
2375 will override the Automake generated rule to build @file{true.o}.
2377 @code{false_SOURCES} is defined to be empty---that way no implicit value
2378 is substituted. Because we have not listed the source of
2379 @file{false}, we have to tell Automake how to link the program. This is
2380 the purpose of the @code{false_LDADD} line. A @code{false_DEPENDENCIES}
2381 variable, holding the dependencies of the @file{false} target will be
2382 automatically generated by Automake from the content of
2385 The above rules won't work if your compiler doesn't accept both
2386 @option{-c} and @option{-o}. The simplest fix for this is to introduce a
2387 bogus dependency (to avoid problems with a parallel @command{make}):
2390 true.o: true.c false.o
2391 $(COMPILE) -DEXIT_CODE=0 -c true.c
2394 $(COMPILE) -DEXIT_CODE=1 -c true.c && mv true.o false.o
2397 Also, these explicit rules do not work if the obsolete de-ANSI-fication feature
2398 is used (@pxref{ANSI}). Supporting de-ANSI-fication requires a little
2402 true_.o: true_.c false_.o
2403 $(COMPILE) -DEXIT_CODE=0 -c true_.c
2406 $(COMPILE) -DEXIT_CODE=1 -c true_.c && mv true_.o false_.o
2409 As it turns out, there is also a much easier way to do this same task.
2410 Some of the above techniques are useful enough that we've kept the
2411 example in the manual. However if you were to build @code{true} and
2412 @code{false} in real life, you would probably use per-program
2413 compilation flags, like so:
2416 bin_PROGRAMS = false true
2418 false_SOURCES = true.c
2419 false_CPPFLAGS = -DEXIT_CODE=1
2421 true_SOURCES = true.c
2422 true_CPPFLAGS = -DEXIT_CODE=0
2425 In this case Automake will cause @file{true.c} to be compiled twice,
2426 with different flags. De-ANSI-fication will work automatically. In
2427 this instance, the names of the object files would be chosen by
2428 automake; they would be @file{false-true.o} and @file{true-true.o}.
2429 (The name of the object files rarely matters.)
2432 @node Invoking Automake
2433 @chapter Creating a @file{Makefile.in}
2435 @cindex Multiple @file{configure.ac} files
2436 @cindex Invoking @command{automake}
2437 @cindex @command{automake}, invoking
2439 To create all the @file{Makefile.in}s for a package, run the
2440 @command{automake} program in the top level directory, with no
2441 arguments. @command{automake} will automatically find each
2442 appropriate @file{Makefile.am} (by scanning @file{configure.ac};
2443 @pxref{configure}) and generate the corresponding @file{Makefile.in}.
2444 Note that @command{automake} has a rather simplistic view of what
2445 constitutes a package; it assumes that a package has only one
2446 @file{configure.ac}, at the top. If your package has multiple
2447 @file{configure.ac}s, then you must run @command{automake} in each
2448 directory holding a @file{configure.ac}. (Alternatively, you may rely
2449 on Autoconf's @command{autoreconf}, which is able to recurse your
2450 package tree and run @command{automake} where appropriate.)
2452 You can optionally give @command{automake} an argument; @file{.am} is
2453 appended to the argument and the result is used as the name of the
2454 input file. This feature is generally only used to automatically
2455 rebuild an out-of-date @file{Makefile.in}. Note that
2456 @command{automake} must always be run from the topmost directory of a
2457 project, even if being used to regenerate the @file{Makefile.in} in
2458 some subdirectory. This is necessary because @command{automake} must
2459 scan @file{configure.ac}, and because @command{automake} uses the
2460 knowledge that a @file{Makefile.in} is in a subdirectory to change its
2461 behavior in some cases.
2464 Automake will run @command{autoconf} to scan @file{configure.ac} and
2465 its dependencies (i.e., @file{aclocal.m4} and any included file),
2466 therefore @command{autoconf} must be in your @env{PATH}. If there is
2467 an @env{AUTOCONF} variable in your environment it will be used
2468 instead of @command{autoconf}, this allows you to select a particular
2469 version of Autoconf. By the way, don't misunderstand this paragraph:
2470 @command{automake} runs @command{autoconf} to @strong{scan} your
2471 @file{configure.ac}, this won't build @file{configure} and you still
2472 have to run @command{autoconf} yourself for this purpose.
2474 @cindex @command{automake} options
2475 @cindex Options, @command{automake}
2476 @cindex Strictness, command line
2478 @command{automake} accepts the following options:
2480 @cindex Extra files distributed with Automake
2481 @cindex Files distributed with Automake
2482 @cindex @file{config.guess}
2486 @itemx --add-missing
2488 @opindex --add-missing
2489 Automake requires certain common files to exist in certain situations;
2490 for instance, @file{config.guess} is required if @file{configure.ac} invokes
2491 @code{AC_CANONICAL_HOST}. Automake is distributed with several of these
2492 files (@pxref{Auxiliary Programs}); this option will cause the missing
2493 ones to be automatically added to the package, whenever possible. In
2494 general if Automake tells you a file is missing, try using this option.
2495 By default Automake tries to make a symbolic link pointing to its own
2496 copy of the missing file; this can be changed with @option{--copy}.
2498 Many of the potentially-missing files are common scripts whose
2499 location may be specified via the @code{AC_CONFIG_AUX_DIR} macro.
2500 Therefore, @code{AC_CONFIG_AUX_DIR}'s setting affects whether a
2501 file is considered missing, and where the missing file is added
2504 In some strictness modes, additional files are installed, see @ref{Gnits}
2505 for more information.
2507 @item --libdir=@var{dir}
2509 Look for Automake data files in directory @var{dir} instead of in the
2510 installation directory. This is typically used for debugging.
2516 When used with @option{--add-missing}, causes installed files to be
2517 copied. The default is to make a symbolic link.
2521 Causes the generated @file{Makefile.in}s to follow Cygnus rules, instead
2522 of GNU or Gnits rules. For more information, see @ref{Cygnus}.
2526 @itemx --force-missing
2527 @opindex --force-missing
2528 When used with @option{--add-missing}, causes standard files to be reinstalled
2529 even if they already exist in the source tree. This involves removing
2530 the file from the source tree before creating the new symlink (or, with
2531 @option{--copy}, copying the new file).
2535 Set the global strictness to @option{foreign}. For more information, see
2540 Set the global strictness to @option{gnits}. For more information, see
2545 Set the global strictness to @option{gnu}. For more information, see
2546 @ref{Gnits}. This is the default strictness.
2550 Print a summary of the command line options and exit.
2553 @itemx --ignore-deps
2555 This disables the dependency tracking feature in generated
2556 @file{Makefile}s; see @ref{Dependencies}.
2558 @item --include-deps
2559 @opindex --include-deps
2560 This enables the dependency tracking feature. This feature is enabled
2561 by default. This option is provided for historical reasons only and
2562 probably should not be used.
2566 Ordinarily @command{automake} creates all @file{Makefile.in}s mentioned in
2567 @file{configure.ac}. This option causes it to only update those
2568 @file{Makefile.in}s that are out of date with respect to one of their
2572 @itemx --output-dir=@var{dir}
2574 @opindex --output-dir
2575 Put the generated @file{Makefile.in} in the directory @var{dir}.
2576 Ordinarily each @file{Makefile.in} is created in the directory of the
2577 corresponding @file{Makefile.am}. This option is deprecated and will be
2578 removed in a future release.
2584 Cause Automake to print information about which files are being read or
2589 Print the version number of Automake and exit.
2592 @itemx --warnings=@var{category}
2595 Output warnings falling in @var{category}. @var{category} can be
2599 warnings related to the GNU Coding Standards
2600 (@pxref{Top, , , standards, The GNU Coding Standards}).
2602 obsolete features or constructions
2604 user redefinitions of Automake rules or variables
2606 portability issues (e.g., use of @command{make} features that are
2607 known to be not portable)
2609 weird syntax, unused variables, typos
2611 unsupported or incomplete features
2615 turn off all the warnings
2617 treat warnings as errors
2620 A category can be turned off by prefixing its name with @samp{no-}. For
2621 instance, @option{-Wno-syntax} will hide the warnings about unused
2624 The categories output by default are @samp{syntax} and
2625 @samp{unsupported}. Additionally, @samp{gnu} and @samp{portability}
2626 are enabled in @option{--gnu} and @option{--gnits} strictness.
2627 On the other hand, the @option{silent-rules} options (@pxref{Options})
2628 turns off portability warnings about recursive variable expansions.
2631 The environment variable @env{WARNINGS} can contain a comma separated
2632 list of categories to enable. It will be taken into account before the
2633 command-line switches, this way @option{-Wnone} will also ignore any
2634 warning category enabled by @env{WARNINGS}. This variable is also used
2635 by other tools like @command{autoconf}; unknown categories are ignored
2640 @vindex AUTOMAKE_JOBS
2641 If the environment variable @env{AUTOMAKE_JOBS} contains a positive
2642 number, it is taken as the maximum number of Perl threads to use in
2643 @command{automake} for generating multiple @file{Makefile.in} files
2644 concurrently. This is an experimental feature.
2648 @chapter Scanning @file{configure.ac}
2650 @cindex @file{configure.ac}, scanning
2651 @cindex Scanning @file{configure.ac}
2653 Automake scans the package's @file{configure.ac} to determine certain
2654 information about the package. Some @command{autoconf} macros are required
2655 and some variables must be defined in @file{configure.ac}. Automake
2656 will also use information from @file{configure.ac} to further tailor its
2659 Automake also supplies some Autoconf macros to make the maintenance
2660 easier. These macros can automatically be put into your
2661 @file{aclocal.m4} using the @command{aclocal} program.
2664 * Requirements:: Configuration requirements
2665 * Optional:: Other things Automake recognizes
2666 * Invoking aclocal:: Auto-generating aclocal.m4
2667 * Macros:: Autoconf macros supplied with Automake
2672 @section Configuration requirements
2674 @cindex Automake requirements
2675 @cindex Requirements of Automake
2677 @acindex AM_INIT_AUTOMAKE
2678 The one real requirement of Automake is that your @file{configure.ac}
2679 call @code{AM_INIT_AUTOMAKE}. This macro does several things that are
2680 required for proper Automake operation (@pxref{Macros}).
2682 Here are the other macros that Automake requires but which are not run
2683 by @code{AM_INIT_AUTOMAKE}:
2686 @item AC_CONFIG_FILES
2688 @acindex AC_CONFIG_FILES
2690 These two macros are usually invoked as follows near the end of
2691 @file{configure.ac}.
2705 Automake uses these to determine which files to create (@pxref{Output, ,
2706 Creating Output Files, autoconf, The Autoconf Manual}). A listed file
2707 is considered to be an Automake generated @file{Makefile} if there
2708 exists a file with the same name and the @file{.am} extension appended.
2709 Typically, @samp{AC_CONFIG_FILES([foo/Makefile])} will cause Automake to
2710 generate @file{foo/Makefile.in} if @file{foo/Makefile.am} exists.
2712 When using @code{AC_CONFIG_FILES} with multiple input files, as in
2715 AC_CONFIG_FILES([Makefile:top.in:Makefile.in:bot.in])
2719 @command{automake} will generate the first @file{.in} input file for
2720 which a @file{.am} file exists. If no such file exists the output
2721 file is not considered to be generated by Automake.
2723 Files created by @code{AC_CONFIG_FILES}, be they Automake
2724 @file{Makefile}s or not, are all removed by @samp{make distclean}.
2725 Their inputs are automatically distributed, unless they
2726 are the output of prior @code{AC_CONFIG_FILES} commands.
2727 Finally, rebuild rules are generated in the Automake @file{Makefile}
2728 existing in the subdirectory of the output file, if there is one, or
2729 in the top-level @file{Makefile} otherwise.
2731 The above machinery (cleaning, distributing, and rebuilding) works
2732 fine if the @code{AC_CONFIG_FILES} specifications contain only
2733 literals. If part of the specification uses shell variables,
2734 @command{automake} will not be able to fulfill this setup, and you will
2735 have to complete the missing bits by hand. For instance, on
2740 AC_CONFIG_FILES([output:$file],, [file=$file])
2744 @command{automake} will output rules to clean @file{output}, and
2745 rebuild it. However the rebuild rule will not depend on @file{input},
2746 and this file will not be distributed either. (You must add
2747 @samp{EXTRA_DIST = input} to your @file{Makefile.am} if @file{input} is a
2756 AC_CONFIG_FILES([$file:input],, [file=$file])
2757 AC_CONFIG_FILES([$file2],, [file2=$file2])
2761 will only cause @file{input} to be distributed. No file will be
2762 cleaned automatically (add @samp{DISTCLEANFILES = output out}
2763 yourself), and no rebuild rule will be output.
2765 Obviously @command{automake} cannot guess what value @samp{$file} is
2766 going to hold later when @file{configure} is run, and it cannot use
2767 the shell variable @samp{$file} in a @file{Makefile}. However, if you
2768 make reference to @samp{$file} as @samp{$@{file@}} (i.e., in a way
2769 that is compatible with @command{make}'s syntax) and furthermore use
2770 @code{AC_SUBST} to ensure that @samp{$@{file@}} is meaningful in a
2771 @file{Makefile}, then @command{automake} will be able to use
2772 @samp{$@{file@}} to generate all these rules. For instance, here is
2773 how the Automake package itself generates versioned scripts for its
2777 AC_SUBST([APIVERSION], @dots{})
2780 [tests/aclocal-$@{APIVERSION@}:tests/aclocal.in],
2781 [chmod +x tests/aclocal-$@{APIVERSION@}],
2782 [APIVERSION=$APIVERSION])
2784 [tests/automake-$@{APIVERSION@}:tests/automake.in],
2785 [chmod +x tests/automake-$@{APIVERSION@}])
2789 Here cleaning, distributing, and rebuilding are done automatically,
2790 because @samp{$@{APIVERSION@}} is known at @command{make}-time.
2792 Note that you should not use shell variables to declare
2793 @file{Makefile} files for which @command{automake} must create
2794 @file{Makefile.in}. Even @code{AC_SUBST} does not help here, because
2795 @command{automake} needs to know the file name when it runs in order
2796 to check whether @file{Makefile.am} exists. (In the very hairy case
2797 that your setup requires such use of variables, you will have to tell
2798 Automake which @file{Makefile.in}s to generate on the command-line.)
2800 It is possible to let @command{automake} emit conditional rules for
2801 @code{AC_CONFIG_FILES} with the help of @code{AM_COND_IF}
2807 Use literals for @file{Makefile}s, and for other files whenever possible.
2809 Use @samp{$file} (or @samp{$@{file@}} without @samp{AC_SUBST([file])})
2810 for files that @command{automake} should ignore.
2812 Use @samp{$@{file@}} and @samp{AC_SUBST([file])} for files
2813 that @command{automake} should not ignore.
2820 @section Other things Automake recognizes
2822 @cindex Macros Automake recognizes
2823 @cindex Recognized macros by Automake
2825 Every time Automake is run it calls Autoconf to trace
2826 @file{configure.ac}. This way it can recognize the use of certain
2827 macros and tailor the generated @file{Makefile.in} appropriately.
2828 Currently recognized macros and their effects are:
2831 @item AC_CANONICAL_BUILD
2832 @itemx AC_CANONICAL_HOST
2833 @itemx AC_CANONICAL_TARGET
2834 @vindex build_triplet
2835 @vindex host_triplet
2836 @vindex target_triplet
2837 Automake will ensure that @file{config.guess} and @file{config.sub}
2838 exist. Also, the @file{Makefile} variables @code{build_triplet},
2839 @code{host_triplet} and @code{target_triplet} are introduced. See
2840 @ref{Canonicalizing, , Getting the Canonical System Type, autoconf,
2841 The Autoconf Manual}.
2843 @item AC_CONFIG_AUX_DIR
2844 Automake will look for various helper scripts, such as
2845 @file{install-sh}, in the directory named in this macro invocation.
2846 @c This list is accurate relative to version 1.8
2847 (The full list of scripts is: @file{ar-lib}, @file{config.guess},
2848 @file{config.sub}, @file{depcomp}, @file{elisp-comp}, @file{compile},
2849 @file{install-sh}, @file{ltmain.sh}, @file{mdate-sh}, @file{missing},
2850 @file{mkinstalldirs}, @file{py-compile}, @file{texinfo.tex}, and
2851 @file{ylwrap}.) Not all scripts are always searched for; some scripts
2852 will only be sought if the generated @file{Makefile.in} requires them.
2854 If @code{AC_CONFIG_AUX_DIR} is not given, the scripts are looked for in
2855 their standard locations. For @file{mdate-sh},
2856 @file{texinfo.tex}, and @file{ylwrap}, the standard location is the
2857 source directory corresponding to the current @file{Makefile.am}. For
2858 the rest, the standard location is the first one of @file{.}, @file{..},
2859 or @file{../..} (relative to the top source directory) that provides any
2860 one of the helper scripts. @xref{Input, , Finding `configure' Input,
2861 autoconf, The Autoconf Manual}.
2863 Required files from @code{AC_CONFIG_AUX_DIR} are automatically
2864 distributed, even if there is no @file{Makefile.am} in this directory.
2866 @item AC_CONFIG_LIBOBJ_DIR
2867 Automake will require the sources file declared with
2868 @code{AC_LIBSOURCE} (see below) in the directory specified by this
2871 @item AC_CONFIG_HEADERS
2872 Automake will generate rules to rebuild these headers. Older versions
2873 of Automake required the use of @code{AM_CONFIG_HEADER}
2874 (@pxref{Macros}); this is no longer the case.
2876 As for @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the
2877 specification using shell variables will be ignored as far as
2878 cleaning, distributing, and rebuilding is concerned.
2880 @item AC_CONFIG_LINKS
2881 Automake will generate rules to remove @file{configure} generated
2882 links on @samp{make distclean} and to distribute named source files as
2883 part of @samp{make dist}.
2885 As for @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the
2886 specification using shell variables will be ignored as far as cleaning
2887 and distributing is concerned. (There are no rebuild rules for links.)
2891 @itemx AC_LIBSOURCES
2893 Automake will automatically distribute any file listed in
2894 @code{AC_LIBSOURCE} or @code{AC_LIBSOURCES}.
2896 Note that the @code{AC_LIBOBJ} macro calls @code{AC_LIBSOURCE}. So if
2897 an Autoconf macro is documented to call @samp{AC_LIBOBJ([file])}, then
2898 @file{file.c} will be distributed automatically by Automake. This
2899 encompasses many macros like @code{AC_FUNC_ALLOCA},
2900 @code{AC_FUNC_MEMCMP}, @code{AC_REPLACE_FUNCS}, and others.
2902 By the way, direct assignments to @code{LIBOBJS} are no longer
2903 supported. You should always use @code{AC_LIBOBJ} for this purpose.
2904 @xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs.@: @code{LIBOBJS},
2905 autoconf, The Autoconf Manual}.
2907 @item AC_PROG_RANLIB
2908 This is required if any libraries are built in the package.
2909 @xref{Particular Programs, , Particular Program Checks, autoconf, The
2913 This is required if any C++ source is included. @xref{Particular
2914 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
2917 This is required if any Objective C source is included. @xref{Particular
2918 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
2921 This is required if any Fortran 77 source is included. This macro is
2922 distributed with Autoconf version 2.13 and later. @xref{Particular
2923 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
2925 @item AC_F77_LIBRARY_LDFLAGS
2926 This is required for programs and shared libraries that are a mixture of
2927 languages that include Fortran 77 (@pxref{Mixing Fortran 77 With C and
2928 C++}). @xref{Macros, , Autoconf macros supplied with Automake}.
2931 Automake will add the flags computed by @code{AC_FC_SRCEXT} to compilation
2932 of files with the respective source extension (@pxref{Fortran Compiler, ,
2933 Fortran Compiler Characteristics, autoconf, The Autoconf Manual}).
2936 This is required if any Fortran 90/95 source is included. This macro is
2937 distributed with Autoconf version 2.58 and later. @xref{Particular
2938 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
2940 @item AC_PROG_LIBTOOL
2941 Automake will turn on processing for @command{libtool} (@pxref{Top, ,
2942 Introduction, libtool, The Libtool Manual}).
2946 If a Yacc source file is seen, then you must either use this macro or
2947 define the variable @code{YACC} in @file{configure.ac}. The former is
2948 preferred (@pxref{Particular Programs, , Particular Program Checks,
2949 autoconf, The Autoconf Manual}).
2952 If a Lex source file is seen, then this macro must be used.
2953 @xref{Particular Programs, , Particular Program Checks, autoconf, The
2956 @item AC_REQUIRE_AUX_FILE
2957 For each @code{AC_REQUIRE_AUX_FILE([@var{file}])},
2958 @command{automake} will ensure that @file{@var{file}} exists in the
2959 aux directory, and will complain otherwise. It
2960 will also automatically distribute the file. This macro should be
2961 used by third-party Autoconf macros that require some supporting
2962 files in the aux directory specified with @code{AC_CONFIG_AUX_DIR}
2963 above. @xref{Input, , Finding @command{configure} Input, autoconf,
2964 The Autoconf Manual}.
2967 The first argument is automatically defined as a variable in each
2968 generated @file{Makefile.in}, unless @code{AM_SUBST_NOTMAKE} is also
2969 used for this variable. @xref{Setting Output Variables, , Setting
2970 Output Variables, autoconf, The Autoconf Manual}.
2972 For every substituted variable @var{var}, @command{automake} will add
2973 a line @code{@var{var} = @var{value}} to each @file{Makefile.in} file.
2974 Many Autoconf macros invoke @code{AC_SUBST} to set output variables
2975 this way, e.g., @code{AC_PATH_XTRA} defines @code{X_CFLAGS} and
2976 @code{X_LIBS}. Thus, you can access these variables as
2977 @code{$(X_CFLAGS)} and @code{$(X_LIBS)} in any @file{Makefile.am}
2978 if @code{AC_PATH_XTRA} is called.
2980 @item AM_C_PROTOTYPES
2981 This is required when using the obsolete de-ANSI-fication feature; see
2984 @item AM_CONDITIONAL
2985 This introduces an Automake conditional (@pxref{Conditionals}).
2988 This macro allows @code{automake} to detect subsequent access within
2989 @file{configure.ac} to a conditional previously introduced with
2990 @code{AM_CONDITIONAL}, thus enabling conditional @code{AC_CONFIG_FILES}
2991 (@pxref{Usage of Conditionals}).
2993 @item AM_GNU_GETTEXT
2994 This macro is required for packages that use GNU gettext
2995 (@pxref{gettext}). It is distributed with gettext. If Automake sees
2996 this macro it ensures that the package meets some of gettext's
2999 @item AM_GNU_GETTEXT_INTL_SUBDIR
3000 This macro specifies that the @file{intl/} subdirectory is to be built,
3001 even if the @code{AM_GNU_GETTEXT} macro was invoked with a first argument
3004 @item AM_MAINTAINER_MODE(@ovar{default-mode})
3005 @opindex --enable-maintainer-mode
3006 @opindex --disable-maintainer-mode
3007 This macro adds an @option{--enable-maintainer-mode} option to
3008 @command{configure}. If this is used, @command{automake} will cause
3009 ``maintainer-only'' rules to be turned off by default in the
3010 generated @file{Makefile.in}s, unless @var{default-mode} is
3011 @samp{enable}. This macro defines the @code{MAINTAINER_MODE}
3012 conditional, which you can use in your own @file{Makefile.am}.
3013 @xref{maintainer-mode}.
3015 @item AM_SUBST_NOTMAKE(@var{var})
3016 Prevent Automake from defining a variable @var{var}, even if it is
3017 substituted by @command{config.status}. Normally, Automake defines a
3018 @command{make} variable for each @command{configure} substitution,
3019 i.e., for each @code{AC_SUBST([@var{var}])}. This macro prevents that
3020 definition from Automake. If @code{AC_SUBST} has not been called
3021 for this variable, then @code{AM_SUBST_NOTMAKE} has no effects.
3022 Preventing variable definitions may be useful for substitution of
3023 multi-line values, where @code{@var{var} = @@@var{value}@@} might yield
3027 Files included by @file{configure.ac} using this macro will be
3028 detected by Automake and automatically distributed. They will also
3029 appear as dependencies in @file{Makefile} rules.
3031 @code{m4_include} is seldom used by @file{configure.ac} authors, but
3032 can appear in @file{aclocal.m4} when @command{aclocal} detects that
3033 some required macros come from files local to your package (as opposed
3034 to macros installed in a system-wide directory, @pxref{Invoking
3040 @node Invoking aclocal
3041 @section Auto-generating aclocal.m4
3043 @cindex Invoking @command{aclocal}
3044 @cindex @command{aclocal}, Invoking
3046 Automake includes a number of Autoconf macros that can be used in
3047 your package (@pxref{Macros}); some of them are actually required by
3048 Automake in certain situations. These macros must be defined in your
3049 @file{aclocal.m4}; otherwise they will not be seen by
3052 The @command{aclocal} program will automatically generate
3053 @file{aclocal.m4} files based on the contents of @file{configure.ac}.
3054 This provides a convenient way to get Automake-provided macros,
3055 without having to search around. The @command{aclocal} mechanism
3056 allows other packages to supply their own macros (@pxref{Extending
3057 aclocal}). You can also use it to maintain your own set of custom
3058 macros (@pxref{Local Macros}).
3060 At startup, @command{aclocal} scans all the @file{.m4} files it can
3061 find, looking for macro definitions (@pxref{Macro Search Path}). Then
3062 it scans @file{configure.ac}. Any mention of one of the macros found
3063 in the first step causes that macro, and any macros it in turn
3064 requires, to be put into @file{aclocal.m4}.
3066 @emph{Putting} the file that contains the macro definition into
3067 @file{aclocal.m4} is usually done by copying the entire text of this
3068 file, including unused macro definitions as well as both @samp{#} and
3069 @samp{dnl} comments. If you want to make a comment that will be
3070 completely ignored by @command{aclocal}, use @samp{##} as the comment
3073 When a file selected by @command{aclocal} is located in a subdirectory
3074 specified as a relative search path with @command{aclocal}'s @option{-I}
3075 argument, @command{aclocal} assumes the file belongs to the package
3076 and uses @code{m4_include} instead of copying it into
3077 @file{aclocal.m4}. This makes the package smaller, eases dependency
3078 tracking, and cause the file to be distributed automatically.
3079 (@xref{Local Macros}, for an example.) Any macro that is found in a
3080 system-wide directory, or via an absolute search path will be copied.
3081 So use @samp{-I `pwd`/reldir} instead of @samp{-I reldir} whenever
3082 some relative directory should be considered outside the package.
3084 The contents of @file{acinclude.m4}, if this file exists, are also
3085 automatically included in @file{aclocal.m4}. We recommend against
3086 using @file{acinclude.m4} in new packages (@pxref{Local Macros}).
3090 While computing @file{aclocal.m4}, @command{aclocal} runs
3091 @command{autom4te} (@pxref{Using autom4te, , Using @command{Autom4te},
3092 autoconf, The Autoconf Manual}) in order to trace the macros that are
3093 really used, and omit from @file{aclocal.m4} all macros that are
3094 mentioned but otherwise unexpanded (this can happen when a macro is
3095 called conditionally). @command{autom4te} is expected to be in the
3096 @env{PATH}, just as @command{autoconf}. Its location can be
3097 overridden using the @env{AUTOM4TE} environment variable.
3100 * aclocal Options:: Options supported by aclocal
3101 * Macro Search Path:: How aclocal finds .m4 files
3102 * Extending aclocal:: Writing your own aclocal macros
3103 * Local Macros:: Organizing local macros
3104 * Serials:: Serial lines in Autoconf macros
3105 * Future of aclocal:: aclocal's scheduled death
3108 @node aclocal Options
3109 @subsection aclocal Options
3111 @cindex @command{aclocal}, Options
3112 @cindex Options, @command{aclocal}
3114 @command{aclocal} accepts the following options:
3117 @item --acdir=@var{dir}
3119 Look for the macro files in @var{dir} instead of the installation
3120 directory. This is typically used for debugging.
3122 @item --diff[=@var{command}]
3124 Run @var{command} on M4 file that would be installed or overwritten
3125 by @option{--install}. The default @var{command} is @samp{diff -u}.
3126 This option implies @option{--install} and @option{--dry-run}.
3130 Do not actually overwrite (or create) @file{aclocal.m4} and M4
3131 files installed by @option{--install}.
3135 Print a summary of the command line options and exit.
3139 Add the directory @var{dir} to the list of directories searched for
3144 Install system-wide third-party macros into the first directory
3145 specified with @samp{-I @var{dir}} instead of copying them in the
3148 @cindex serial number and @option{--install}
3149 When this option is used, and only when this option is used,
3150 @command{aclocal} will also honor @samp{#serial @var{number}} lines
3151 that appear in macros: an M4 file is ignored if there exists another
3152 M4 file with the same basename and a greater serial number in the
3153 search path (@pxref{Serials}).
3157 Always overwrite the output file. The default is to overwrite the output
3158 file only when really needed, i.e., when its contents changes or if one
3159 of its dependencies is younger.
3161 This option forces the update of @file{aclocal.m4} (or the file
3162 specified with @file{--output} below) and only this file, it has
3163 absolutely no influence on files that may need to be installed by
3166 @item --output=@var{file}
3168 Cause the output to be put into @var{file} instead of @file{aclocal.m4}.
3170 @item --print-ac-dir
3171 @opindex --print-ac-dir
3172 Prints the name of the directory that @command{aclocal} will search to
3173 find third-party @file{.m4} files. When this option is given, normal
3174 processing is suppressed. This option can be used by a package to
3175 determine where to install a macro file.
3179 Print the names of the files it examines.
3183 Print the version number of Automake and exit.
3186 @item --warnings=@var{category}
3189 Output warnings falling in @var{category}. @var{category} can be
3193 dubious syntactic constructs, underquoted macros, unused macros, etc.
3197 all the warnings, this is the default
3199 turn off all the warnings
3201 treat warnings as errors
3204 All warnings are output by default.
3207 The environment variable @env{WARNINGS} is honored in the same
3208 way as it is for @command{automake} (@pxref{Invoking Automake}).
3212 @node Macro Search Path
3213 @subsection Macro Search Path
3215 @cindex Macro search path
3216 @cindex @command{aclocal} search path
3218 By default, @command{aclocal} searches for @file{.m4} files in the following
3219 directories, in this order:
3222 @item @var{acdir-APIVERSION}
3223 This is where the @file{.m4} macros distributed with Automake itself
3224 are stored. @var{APIVERSION} depends on the Automake release used;
3225 for Automake 1.6.x, @var{APIVERSION} = @code{1.6}.
3228 This directory is intended for third party @file{.m4} files, and is
3229 configured when @command{automake} itself is built. This is
3230 @file{@@datadir@@/aclocal/}, which typically
3231 expands to @file{$@{prefix@}/share/aclocal/}. To find the compiled-in
3232 value of @var{acdir}, use the @option{--print-ac-dir} option
3233 (@pxref{aclocal Options}).
3236 As an example, suppose that @command{automake-1.6.2} was configured with
3237 @option{--prefix=@-/usr/local}. Then, the search path would be:
3240 @item @file{/usr/local/share/aclocal-1.6/}
3241 @item @file{/usr/local/share/aclocal/}
3244 As explained in (@pxref{aclocal Options}), there are several options that
3245 can be used to change or extend this search path.
3247 @subsubheading Modifying the Macro Search Path: @option{--acdir}
3249 The most erroneous option to modify the search path is
3250 @option{--acdir=@var{dir}}, which changes default directory and
3251 drops the @var{APIVERSION} directory. For example, if one specifies
3252 @samp{--acdir=/opt/private/}, then the search path becomes:
3255 @item @file{/opt/private/}
3258 This option, @option{--acdir}, is intended for use by the internal
3259 Automake test suite only; it is not ordinarily needed by end-users.
3261 @subsubheading Modifying the Macro Search Path: @samp{-I @var{dir}}
3263 Any extra directories specified using @option{-I} options
3264 (@pxref{aclocal Options}) are @emph{prepended} to this search list. Thus,
3265 @samp{aclocal -I /foo -I /bar} results in the following search path:
3270 @item @var{acdir}-@var{APIVERSION}
3274 @subsubheading Modifying the Macro Search Path: @file{dirlist}
3275 @cindex @file{dirlist}
3277 There is a third mechanism for customizing the search path. If a
3278 @file{dirlist} file exists in @var{acdir}, then that file is assumed to
3279 contain a list of directory patterns, one per line. @command{aclocal}
3280 expands these patterns to directory names, and adds them to the search
3281 list @emph{after} all other directories. @file{dirlist} entries may
3282 use shell wildcards such as @samp{*}, @samp{?}, or @code{[...]}.
3284 For example, suppose
3285 @file{@var{acdir}/dirlist} contains the following:
3294 and that @command{aclocal} was called with the @samp{-I /foo -I /bar} options.
3295 Then, the search path would be
3297 @c @code looks better than @file here
3301 @item @var{acdir}-@var{APIVERSION}
3308 and all directories with path names starting with @code{/test3}.
3310 If the @option{--acdir=@var{dir}} option is used, then @command{aclocal}
3311 will search for the @file{dirlist} file in @var{dir}. In the
3312 @samp{--acdir=/opt/private/} example above, @command{aclocal} would look
3313 for @file{/opt/private/dirlist}. Again, however, the @option{--acdir}
3314 option is intended for use by the internal Automake test suite only;
3315 @option{--acdir} is not ordinarily needed by end-users.
3317 @file{dirlist} is useful in the following situation: suppose that
3318 @command{automake} version @code{1.6.2} is installed with
3319 @samp{--prefix=/usr} by the system vendor. Thus, the default search
3322 @c @code looks better than @file here
3324 @item @code{/usr/share/aclocal-1.6/}
3325 @item @code{/usr/share/aclocal/}
3328 However, suppose further that many packages have been manually
3329 installed on the system, with $prefix=/usr/local, as is typical. In
3330 that case, many of these ``extra'' @file{.m4} files are in
3331 @file{/usr/local/share/aclocal}. The only way to force
3332 @file{/usr/bin/aclocal} to find these ``extra'' @file{.m4} files is to
3333 always call @samp{aclocal -I /usr/local/share/aclocal}. This is
3334 inconvenient. With @file{dirlist}, one may create a file
3335 @file{/usr/share/aclocal/dirlist} containing only the single line
3338 /usr/local/share/aclocal
3341 Now, the ``default'' search path on the affected system is
3343 @c @code looks better than @file here
3345 @item @code{/usr/share/aclocal-1.6/}
3346 @item @code{/usr/share/aclocal/}
3347 @item @code{/usr/local/share/aclocal/}
3350 without the need for @option{-I} options; @option{-I} options can be reserved
3351 for project-specific needs (@file{my-source-dir/m4/}), rather than
3352 using it to work around local system-dependent tool installation
3355 Similarly, @file{dirlist} can be handy if you have installed a local
3356 copy of Automake in your account and want @command{aclocal} to look for
3357 macros installed at other places on the system.
3360 @node Extending aclocal
3361 @subsection Writing your own aclocal macros
3363 @cindex @command{aclocal}, extending
3364 @cindex Extending @command{aclocal}
3366 The @command{aclocal} program doesn't have any built-in knowledge of any
3367 macros, so it is easy to extend it with your own macros.
3369 This can be used by libraries that want to supply their own Autoconf
3370 macros for use by other programs. For instance, the @command{gettext}
3371 library supplies a macro @code{AM_GNU_GETTEXT} that should be used by
3372 any package using @command{gettext}. When the library is installed, it
3373 installs this macro so that @command{aclocal} will find it.
3375 A macro file's name should end in @file{.m4}. Such files should be
3376 installed in @file{$(datadir)/aclocal}. This is as simple as writing:
3379 aclocaldir = $(datadir)/aclocal
3380 aclocal_DATA = mymacro.m4 myothermacro.m4
3384 Please do use @file{$(datadir)/aclocal}, and not something based on
3385 the result of @samp{aclocal --print-ac-dir}. @xref{Hard-Coded Install
3386 Paths}, for arguments.
3388 A file of macros should be a series of properly quoted
3389 @code{AC_DEFUN}'s (@pxref{Macro Definitions, , , autoconf, The
3390 Autoconf Manual}). The @command{aclocal} programs also understands
3391 @code{AC_REQUIRE} (@pxref{Prerequisite Macros, , , autoconf, The
3392 Autoconf Manual}), so it is safe to put each macro in a separate file.
3393 Each file should have no side effects but macro definitions.
3394 Especially, any call to @code{AC_PREREQ} should be done inside the
3395 defined macro, not at the beginning of the file.
3397 @cindex underquoted @code{AC_DEFUN}
3401 Starting with Automake 1.8, @command{aclocal} will warn about all
3402 underquoted calls to @code{AC_DEFUN}. We realize this will annoy a
3403 lot of people, because @command{aclocal} was not so strict in the past
3404 and many third party macros are underquoted; and we have to apologize
3405 for this temporary inconvenience. The reason we have to be stricter
3406 is that a future implementation of @command{aclocal} (@pxref{Future of
3407 aclocal}) will have to temporarily include all these third party
3408 @file{.m4} files, maybe several times, including even files that are
3409 not actually needed. Doing so should alleviate many problems of the
3410 current implementation, however it requires a stricter style from the
3411 macro authors. Hopefully it is easy to revise the existing macros.
3417 [AC_REQUIRE([AX_SOMETHING])dnl
3423 should be rewritten as
3425 AC_DEFUN([AX_FOOBAR],
3426 [AC_PREREQ([2.57])dnl
3427 AC_REQUIRE([AX_SOMETHING])dnl
3433 Wrapping the @code{AC_PREREQ} call inside the macro ensures that
3434 Autoconf 2.57 will not be required if @code{AX_FOOBAR} is not actually
3435 used. Most importantly, quoting the first argument of @code{AC_DEFUN}
3436 allows the macro to be redefined or included twice (otherwise this
3437 first argument would be expanded during the second definition). For
3438 consistency we like to quote even arguments such as @code{2.57} that
3441 If you have been directed here by the @command{aclocal} diagnostic but
3442 are not the maintainer of the implicated macro, you will want to
3443 contact the maintainer of that macro. Please make sure you have the
3444 latest version of the macro and that the problem hasn't already been
3445 reported before doing so: people tend to work faster when they aren't
3448 Another situation where @command{aclocal} is commonly used is to
3449 manage macros that are used locally by the package, @ref{Local
3453 @subsection Handling Local Macros
3455 Feature tests offered by Autoconf do not cover all needs. People
3456 often have to supplement existing tests with their own macros, or
3457 with third-party macros.
3459 There are two ways to organize custom macros in a package.
3461 The first possibility (the historical practice) is to list all your
3462 macros in @file{acinclude.m4}. This file will be included in
3463 @file{aclocal.m4} when you run @command{aclocal}, and its macro(s) will
3464 henceforth be visible to @command{autoconf}. However if it contains
3465 numerous macros, it will rapidly become difficult to maintain, and it
3466 will be almost impossible to share macros between packages.
3468 @vindex ACLOCAL_AMFLAGS
3469 The second possibility, which we do recommend, is to write each macro
3470 in its own file and gather all these files in a directory. This
3471 directory is usually called @file{m4/}. To build @file{aclocal.m4},
3472 one should therefore instruct @command{aclocal} to scan @file{m4/}.
3473 From the command line, this is done with @samp{aclocal -I m4}. The
3474 top-level @file{Makefile.am} should also be updated to define
3477 ACLOCAL_AMFLAGS = -I m4
3480 @code{ACLOCAL_AMFLAGS} contains options to pass to @command{aclocal}
3481 when @file{aclocal.m4} is to be rebuilt by @command{make}. This line is
3482 also used by @command{autoreconf} (@pxref{autoreconf Invocation, ,
3483 Using @command{autoreconf} to Update @file{configure} Scripts,
3484 autoconf, The Autoconf Manual}) to run @command{aclocal} with suitable
3485 options, or by @command{autopoint} (@pxref{autopoint Invocation, ,
3486 Invoking the @command{autopoint} Program, gettext, GNU gettext tools})
3487 and @command{gettextize} (@pxref{gettextize Invocation, , Invoking the
3488 @command{gettextize} Program, gettext, GNU gettext tools}) to locate
3489 the place where Gettext's macros should be installed. So even if you
3490 do not really care about the rebuild rules, you should define
3491 @code{ACLOCAL_AMFLAGS}.
3493 When @samp{aclocal -I m4} is run, it will build an @file{aclocal.m4}
3494 that @code{m4_include}s any file from @file{m4/} that defines a
3495 required macro. Macros not found locally will still be searched in
3496 system-wide directories, as explained in @ref{Macro Search Path}.
3498 Custom macros should be distributed for the same reason that
3499 @file{configure.ac} is: so that other people have all the sources of
3500 your package if they want to work on it. Actually, this distribution
3501 happens automatically because all @code{m4_include}d files are
3504 However there is no consensus on the distribution of third-party
3505 macros that your package may use. Many libraries install their own
3506 macro in the system-wide @command{aclocal} directory (@pxref{Extending
3507 aclocal}). For instance, Guile ships with a file called
3508 @file{guile.m4} that contains the macro @code{GUILE_FLAGS} that can
3509 be used to define setup compiler and linker flags appropriate for
3510 using Guile. Using @code{GUILE_FLAGS} in @file{configure.ac} will
3511 cause @command{aclocal} to copy @file{guile.m4} into
3512 @file{aclocal.m4}, but as @file{guile.m4} is not part of the project,
3513 it will not be distributed. Technically, that means a user who
3514 needs to rebuild @file{aclocal.m4} will have to install Guile first.
3515 This is probably OK, if Guile already is a requirement to build the
3516 package. However, if Guile is only an optional feature, or if your
3517 package might run on architectures where Guile cannot be installed,
3518 this requirement will hinder development. An easy solution is to copy
3519 such third-party macros in your local @file{m4/} directory so they get
3522 Since Automake 1.10, @command{aclocal} offers an option to copy these
3523 system-wide third-party macros in your local macro directory, solving
3524 the above problem. Simply use:
3527 ACLOCAL_AMFLAGS = -I m4 --install
3531 With this setup, system-wide macros will be copied to @file{m4/}
3532 the first time you run @command{autoreconf}. Then the locally
3533 installed macros will have precedence over the system-wide installed
3534 macros each time @command{aclocal} is run again.
3536 One reason why you should keep @option{--install} in the flags even
3537 after the first run is that when you later edit @file{configure.ac}
3538 and depend on a new macro, this macro will be installed in your
3539 @file{m4/} automatically. Another one is that serial numbers
3540 (@pxref{Serials}) can be used to update the macros in your source tree
3541 automatically when new system-wide versions are installed. A serial
3542 number should be a single line of the form
3549 where @var{nnn} contains only digits and dots. It should appear in
3550 the M4 file before any macro definition. It is a good practice to
3551 maintain a serial number for each macro you distribute, even if you do
3552 not use the @option{--install} option of @command{aclocal}: this allows
3553 other people to use it.
3557 @subsection Serial Numbers
3558 @cindex serial numbers in macros
3559 @cindex macro serial numbers
3560 @cindex @code{#serial} syntax
3561 @cindex @command{aclocal} and serial numbers
3563 Because third-party macros defined in @file{*.m4} files are naturally
3564 shared between multiple projects, some people like to version them.
3565 This makes it easier to tell which of two M4 files is newer. Since at
3566 least 1996, the tradition is to use a @samp{#serial} line for this.
3568 A serial number should be a single line of the form
3571 # serial @var{version}
3575 where @var{version} is a version number containing only digits and
3576 dots. Usually people use a single integer, and they increment it each
3577 time they change the macro (hence the name of ``serial''). Such a
3578 line should appear in the M4 file before any macro definition.
3580 The @samp{#} must be the first character on the line,
3581 and it is OK to have extra words after the version, as in
3584 #serial @var{version} @var{garbage}
3587 Normally these serial numbers are completely ignored by
3588 @command{aclocal} and @command{autoconf}, like any genuine comment.
3589 However when using @command{aclocal}'s @option{--install} feature, these
3590 serial numbers will modify the way @command{aclocal} selects the
3591 macros to install in the package: if two files with the same basename
3592 exist in your search path, and if at least one of them uses a
3593 @samp{#serial} line, @command{aclocal} will ignore the file that has
3594 the older @samp{#serial} line (or the file that has none).
3596 Note that a serial number applies to a whole M4 file, not to any macro
3597 it contains. A file can contains multiple macros, but only one
3600 Here is a use case that illustrates the use of @option{--install} and
3601 its interaction with serial numbers. Let's assume we maintain a
3602 package called MyPackage, the @file{configure.ac} of which requires a
3603 third-party macro @code{AX_THIRD_PARTY} defined in
3604 @file{/usr/share/aclocal/thirdparty.m4} as follows:
3608 AC_DEFUN([AX_THIRD_PARTY], [...])
3611 MyPackage uses an @file{m4/} directory to store local macros as
3612 explained in @ref{Local Macros}, and has
3615 ACLOCAL_AMFLAGS = -I m4 --install
3619 in its top-level @file{Makefile.am}.
3621 Initially the @file{m4/} directory is empty. The first time we run
3622 @command{autoreconf}, it will fetch the options to pass to
3623 @command{aclocal} in @file{Makefile.am}, and run @samp{aclocal -I m4
3624 --install}. @command{aclocal} will notice that
3628 @file{configure.ac} uses @code{AX_THIRD_PARTY}
3630 No local macros define @code{AX_THIRD_PARTY}
3632 @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3637 Because @file{/usr/share/aclocal/thirdparty.m4} is a system-wide macro
3638 and @command{aclocal} was given the @option{--install} option, it will
3639 copy this file in @file{m4/thirdparty.m4}, and output an
3640 @file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}.
3642 The next time @samp{aclocal -I m4 --install} is run (either via
3643 @command{autoreconf}, by hand, or from the @file{Makefile} rebuild
3644 rules) something different happens. @command{aclocal} notices that
3648 @file{configure.ac} uses @code{AX_THIRD_PARTY}
3650 @file{m4/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3653 @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3658 Because both files have the same serial number, @command{aclocal} uses
3659 the first it found in its search path order (@pxref{Macro Search
3660 Path}). @command{aclocal} therefore ignores
3661 @file{/usr/share/aclocal/thirdparty.m4} and outputs an
3662 @file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}.
3664 Local directories specified with @option{-I} are always searched before
3665 system-wide directories, so a local file will always be preferred to
3666 the system-wide file in case of equal serial numbers.
3668 Now suppose the system-wide third-party macro is changed. This can
3669 happen if the package installing this macro is updated. Let's suppose
3670 the new macro has serial number 2. The next time @samp{aclocal -I m4
3671 --install} is run the situation is the following:
3675 @file{configure.ac} uses @code{AX_THIRD_PARTY}
3677 @file{m4/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3680 @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3685 When @command{aclocal} sees a greater serial number, it immediately
3686 forgets anything it knows from files that have the same basename and a
3687 smaller serial number. So after it has found
3688 @file{/usr/share/aclocal/thirdparty.m4} with serial 2,
3689 @command{aclocal} will proceed as if it had never seen
3690 @file{m4/thirdparty.m4}. This brings us back to a situation similar
3691 to that at the beginning of our example, where no local file defined
3692 the macro. @command{aclocal} will install the new version of the
3693 macro in @file{m4/thirdparty.m4}, in this case overriding the old
3694 version. MyPackage just had its macro updated as a side effect of
3695 running @command{aclocal}.
3697 If you are leery of letting @command{aclocal} update your local macro,
3698 you can run @samp{aclocal -I m4 --diff} to review the changes
3699 @samp{aclocal -I m4 --install} would perform on these macros.
3701 Finally, note that the @option{--force} option of @command{aclocal} has
3702 absolutely no effect on the files installed by @option{--install}. For
3703 instance, if you have modified your local macros, do not expect
3704 @option{--install --force} to replace the local macros by their
3705 system-wide versions. If you want to do so, simply erase the local
3706 macros you want to revert, and run @samp{aclocal -I m4 --install}.
3709 @node Future of aclocal
3710 @subsection The Future of @command{aclocal}
3711 @cindex @command{aclocal}'s scheduled death
3713 @command{aclocal} is expected to disappear. This feature really
3714 should not be offered by Automake. Automake should focus on
3715 generating @file{Makefile}s; dealing with M4 macros really is
3716 Autoconf's job. The fact that some people install Automake just to use
3717 @command{aclocal}, but do not use @command{automake} otherwise is an
3718 indication of how that feature is misplaced.
3720 The new implementation will probably be done slightly differently.
3721 For instance, it could enforce the @file{m4/}-style layout discussed in
3724 We have no idea when and how this will happen. This has been
3725 discussed several times in the past, but someone still has to commit
3726 to that non-trivial task.
3728 From the user point of view, @command{aclocal}'s removal might turn
3729 out to be painful. There is a simple precaution that you may take to
3730 make that switch more seamless: never call @command{aclocal} yourself.
3731 Keep this guy under the exclusive control of @command{autoreconf} and
3732 Automake's rebuild rules. Hopefully you won't need to worry about
3733 things breaking, when @command{aclocal} disappears, because everything
3734 will have been taken care of. If otherwise you used to call
3735 @command{aclocal} directly yourself or from some script, you will
3736 quickly notice the change.
3738 Many packages come with a script called @file{bootstrap.sh} or
3739 @file{autogen.sh}, that will just call @command{aclocal},
3740 @command{libtoolize}, @command{gettextize} or @command{autopoint},
3741 @command{autoconf}, @command{autoheader}, and @command{automake} in
3742 the right order. Actually this is precisely what @command{autoreconf}
3743 can do for you. If your package has such a @file{bootstrap.sh} or
3744 @file{autogen.sh} script, consider using @command{autoreconf}. That
3745 should simplify its logic a lot (less things to maintain, yum!), it's
3746 even likely you will not need the script anymore, and more to the point
3747 you will not call @command{aclocal} directly anymore.
3749 For the time being, third-party packages should continue to install
3750 public macros into @file{/usr/share/aclocal/}. If @command{aclocal}
3751 is replaced by another tool it might make sense to rename the
3752 directory, but supporting @file{/usr/share/aclocal/} for backward
3753 compatibility should be really easy provided all macros are properly
3754 written (@pxref{Extending aclocal}).
3759 @section Autoconf macros supplied with Automake
3761 Automake ships with several Autoconf macros that you can use from your
3762 @file{configure.ac}. When you use one of them it will be included by
3763 @command{aclocal} in @file{aclocal.m4}.
3766 * Public Macros:: Macros that you can use.
3767 * Obsolete Macros:: Macros that you should stop using.
3768 * Private Macros:: Macros that you should not use.
3771 @c consider generating the following subsections automatically from m4 files.
3774 @subsection Public Macros
3778 @item AM_ENABLE_MULTILIB
3779 @acindex AM_ENABLE_MULTILIB
3780 This is used when a ``multilib'' library is being built. The first
3781 optional argument is the name of the @file{Makefile} being generated; it
3782 defaults to @samp{Makefile}. The second optional argument is used to find
3783 the top source directory; it defaults to the empty string (generally
3784 this should not be used unless you are familiar with the internals).
3787 @item AM_INIT_AUTOMAKE([OPTIONS])
3788 @itemx AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])
3789 @acindex AM_INIT_AUTOMAKE
3790 Runs many macros required for proper operation of the generated Makefiles.
3792 @vindex AUTOMAKE_OPTIONS
3793 This macro has two forms, the first of which is preferred.
3794 In this form, @code{AM_INIT_AUTOMAKE} is called with a
3795 single argument: a space-separated list of Automake options that should
3796 be applied to every @file{Makefile.am} in the tree. The effect is as if
3797 each option were listed in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
3800 The second, deprecated, form of @code{AM_INIT_AUTOMAKE} has two required
3801 arguments: the package and the version number. This form is
3802 obsolete because the @var{package} and @var{version} can be obtained
3803 from Autoconf's @code{AC_INIT} macro (which itself has an old and a new
3806 If your @file{configure.ac} has:
3809 AC_INIT([src/foo.c])
3810 AM_INIT_AUTOMAKE([mumble], [1.5])
3814 you can modernize it as follows:
3817 AC_INIT([mumble], [1.5])
3818 AC_CONFIG_SRCDIR([src/foo.c])
3822 Note that if you're upgrading your @file{configure.ac} from an earlier
3823 version of Automake, it is not always correct to simply move the
3824 package and version arguments from @code{AM_INIT_AUTOMAKE} directly to
3825 @code{AC_INIT}, as in the example above. The first argument to
3826 @code{AC_INIT} should be the name of your package (e.g., @samp{GNU
3827 Automake}), not the tarball name (e.g., @samp{automake}) that you used
3828 to pass to @code{AM_INIT_AUTOMAKE}. Autoconf tries to derive a
3829 tarball name from the package name, which should work for most but not
3830 all package names. (If it doesn't work for yours, you can use the
3831 four-argument form of @code{AC_INIT} to provide the tarball name
3834 @cindex @code{PACKAGE}, prevent definition
3835 @cindex @code{VERSION}, prevent definition
3837 By default this macro @code{AC_DEFINE}'s @code{PACKAGE} and
3838 @code{VERSION}. This can be avoided by passing the @option{no-define}
3841 AM_INIT_AUTOMAKE([gnits 1.5 no-define dist-bzip2])
3843 or by passing a third non-empty argument to the obsolete form.
3845 @item AM_PATH_LISPDIR
3846 @acindex AM_PATH_LISPDIR
3849 Searches for the program @command{emacs}, and, if found, sets the
3850 output variable @code{lispdir} to the full path to Emacs' site-lisp
3853 Note that this test assumes the @command{emacs} found to be a version
3854 that supports Emacs Lisp (such as GNU Emacs or XEmacs). Other
3855 emacsen can cause this test to hang (some, like old versions of
3856 MicroEmacs, start up in interactive mode, requiring @kbd{C-x C-c} to
3857 exit, which is hardly obvious for a non-emacs user). In most cases,
3858 however, you should be able to use @kbd{C-c} to kill the test. In
3859 order to avoid problems, you can set @env{EMACS} to ``no'' in the
3860 environment, or use the @option{--with-lispdir} option to
3861 @command{configure} to explicitly set the correct path (if you're sure
3862 you have an @command{emacs} that supports Emacs Lisp).
3868 Use this macro when you have assembly code in your project. This will
3869 choose the assembler for you (by default the C compiler) and set
3870 @code{CCAS}, and will also set @code{CCASFLAGS} if required.
3872 @item AM_PROG_CC_C_O
3873 @acindex AM_PROG_CC_C_O
3874 @acindex AC_PROG_CC_C_O
3875 This is like @code{AC_PROG_CC_C_O}, but it generates its results in
3876 the manner required by Automake. You must use this instead of
3877 @code{AC_PROG_CC_C_O} when you need this functionality, that is, when
3878 using per-target flags or subdir-objects with C sources.
3881 @acindex AM_PROG_LEX
3882 @acindex AC_PROG_LEX
3883 @cindex HP-UX 10, @command{lex} problems
3884 @cindex @command{lex} problems with HP-UX 10
3885 Like @code{AC_PROG_LEX} (@pxref{Particular Programs, , Particular
3886 Program Checks, autoconf, The Autoconf Manual}), but uses the
3887 @command{missing} script on systems that do not have @command{lex}.
3888 HP-UX 10 is one such system.
3891 @acindex AM_PROG_GCJ
3894 This macro finds the @command{gcj} program or causes an error. It sets
3895 @code{GCJ} and @code{GCJFLAGS}. @command{gcj} is the Java front-end to the
3896 GNU Compiler Collection.
3898 @item AM_PROG_UPC([@var{compiler-search-list}])
3899 @acindex AM_PROG_UPC
3901 Find a compiler for Unified Parallel C and define the @code{UPC}
3902 variable. The default @var{compiler-search-list} is @samp{upcc upc}.
3903 This macro will abort @command{configure} if no Unified Parallel C
3906 @item AM_SILENT_RULES
3907 @acindex AM_SILENT_RULES
3908 Enable the machinery for less verbose build output (@pxref{Options}).
3910 @item AM_WITH_DMALLOC
3911 @acindex AM_WITH_DMALLOC
3912 @cindex @command{dmalloc}, support for
3913 @vindex WITH_DMALLOC
3914 @opindex --with-dmalloc
3915 Add support for the @uref{http://dmalloc.com/, Dmalloc package}. If
3916 the user runs @command{configure} with @option{--with-dmalloc}, then
3917 define @code{WITH_DMALLOC} and add @option{-ldmalloc} to @code{LIBS}.
3920 @acindex AM_WITH_REGEX
3922 @opindex --with-regex
3923 @cindex regex package
3925 Adds @option{--with-regex} to the @command{configure} command line. If
3926 specified (the default), then the @samp{regex} regular expression
3927 library is used, @file{regex.o} is put into @code{LIBOBJS}, and
3928 @code{WITH_REGEX} is defined. If @option{--without-regex} is given, then
3929 the @code{rx} regular expression library is used, and @file{rx.o} is put
3930 into @code{LIBOBJS}.
3935 @node Obsolete Macros
3936 @subsection Obsolete Macros
3937 @cindex obsolete macros
3940 Although using some of the following macros was required in past
3941 releases, you should not use any of them in new code. Running
3942 @command{autoupdate} should adjust your @file{configure.ac}
3943 automatically (@pxref{autoupdate Invocation, , Using
3944 @command{autoupdate} to Modernize @file{configure.ac}, autoconf, The
3948 @item AM_C_PROTOTYPES
3949 @acindex AM_C_PROTOTYPES
3952 Check to see if function prototypes are understood by the compiler. If
3953 so, define @samp{PROTOTYPES} and set the output variables @code{U} and
3954 @code{ANSI2KNR} to the empty string. Otherwise, set @code{U} to
3955 @samp{_} and @code{ANSI2KNR} to @samp{./ansi2knr}. Automake uses these
3956 values to implement the obsolete de-ANSI-fication feature.
3958 @item AM_CONFIG_HEADER
3959 @acindex AM_CONFIG_HEADER
3960 Automake will generate rules to automatically regenerate the config
3961 header. This obsolete macro is a synonym of @code{AC_CONFIG_HEADERS}
3962 today (@pxref{Optional}).
3964 @item AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
3965 @acindex AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
3966 If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
3967 define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be
3968 found in @file{<termios.h>}. This macro is obsolete, you should
3969 use Autoconf's @code{AC_HEADER_TIOCGWINSZ} instead.
3971 @item AM_PROG_MKDIR_P
3972 @acindex AM_PROG_MKDIR_P
3973 @cindex @code{mkdir -p}, macro check
3977 From Automake 1.8 to 1.9.6 this macro used to define the output
3978 variable @code{mkdir_p} to one of @code{mkdir -p}, @code{install-sh
3979 -d}, or @code{mkinstalldirs}.
3981 Nowadays Autoconf provides a similar functionality with
3982 @code{AC_PROG_MKDIR_P} (@pxref{Particular Programs, , Particular
3983 Program Checks, autoconf, The Autoconf Manual}), however this defines
3984 the output variable @code{MKDIR_P} instead. Therefore
3985 @code{AM_PROG_MKDIR_P} has been rewritten as a thin wrapper around
3986 @code{AC_PROG_MKDIR_P} to define @code{mkdir_p} to the same value as
3987 @code{MKDIR_P} for backward compatibility.
3989 If you are using Automake, there is normally no reason to call this
3990 macro, because @code{AM_INIT_AUTOMAKE} already does so. However, make
3991 sure that the custom rules in your @file{Makefile}s use
3992 @code{$(MKDIR_P)} and not @code{$(mkdir_p)}. Even if both variables
3993 still work, the latter should be considered obsolete.
3995 If you are not using Automake, please call @code{AC_PROG_MKDIR_P}
3996 instead of @code{AM_PROG_MKDIR_P}.
3998 @item AM_SYS_POSIX_TERMIOS
3999 @acindex AM_SYS_POSIX_TERMIOS
4000 @cindex POSIX termios headers
4001 @cindex termios POSIX headers
4002 Check to see if POSIX termios headers and functions are available on the
4003 system. If so, set the shell variable @code{am_cv_sys_posix_termios} to
4004 @samp{yes}. If not, set the variable to @samp{no}. This macro is obsolete,
4005 you should use Autoconf's @code{AC_SYS_POSIX_TERMIOS} instead.
4010 @node Private Macros
4011 @subsection Private Macros
4013 The following macros are private macros you should not call directly.
4014 They are called by the other public macros when appropriate. Do not
4015 rely on them, as they might be changed in a future version. Consider
4016 them as implementation details; or better, do not consider them at all:
4020 @item _AM_DEPENDENCIES
4021 @itemx AM_SET_DEPDIR
4023 @itemx AM_OUTPUT_DEPENDENCY_COMMANDS
4024 These macros are used to implement Automake's automatic dependency
4025 tracking scheme. They are called automatically by Automake when
4026 required, and there should be no need to invoke them manually.
4028 @item AM_MAKE_INCLUDE
4029 This macro is used to discover how the user's @command{make} handles
4030 @code{include} statements. This macro is automatically invoked when
4031 needed; there should be no need to invoke it manually.
4033 @item AM_PROG_INSTALL_STRIP
4034 This is used to find a version of @code{install} that can be used to
4035 strip a program at installation time. This macro is automatically
4036 included when required.
4038 @item AM_SANITY_CHECK
4039 This checks to make sure that a file created in the build directory is
4040 newer than a file in the source directory. This can fail on systems
4041 where the clock is set incorrectly. This macro is automatically run
4042 from @code{AM_INIT_AUTOMAKE}.
4048 @chapter Directories
4050 For simple projects that distribute all files in the same directory
4051 it is enough to have a single @file{Makefile.am} that builds
4052 everything in place.
4054 In larger projects it is common to organize files in different
4055 directories, in a tree. For instance one directory per program, per
4056 library or per module. The traditional approach is to build these
4057 subdirectories recursively: each directory contains its @file{Makefile}
4058 (generated from @file{Makefile.am}), and when @command{make} is run
4059 from the top level directory it enters each subdirectory in turn to
4063 * Subdirectories:: Building subdirectories recursively
4064 * Conditional Subdirectories:: Conditionally not building directories
4065 * Alternative:: Subdirectories without recursion
4066 * Subpackages:: Nesting packages
4069 @node Subdirectories
4070 @section Recursing subdirectories
4072 @cindex @code{SUBDIRS}, explained
4074 In packages with subdirectories, the top level @file{Makefile.am} must
4075 tell Automake which subdirectories are to be built. This is done via
4076 the @code{SUBDIRS} variable.
4079 The @code{SUBDIRS} variable holds a list of subdirectories in which
4080 building of various sorts can occur. The rules for many targets
4081 (e.g., @code{all}) in the generated @file{Makefile} will run commands
4082 both locally and in all specified subdirectories. Note that the
4083 directories listed in @code{SUBDIRS} are not required to contain
4084 @file{Makefile.am}s; only @file{Makefile}s (after configuration).
4085 This allows inclusion of libraries from packages that do not use
4086 Automake (such as @code{gettext}; see also @ref{Third-Party
4089 In packages that use subdirectories, the top-level @file{Makefile.am} is
4090 often very short. For instance, here is the @file{Makefile.am} from the
4091 GNU Hello distribution:
4094 EXTRA_DIST = BUGS ChangeLog.O README-alpha
4095 SUBDIRS = doc intl po src tests
4098 When Automake invokes @command{make} in a subdirectory, it uses the value
4099 of the @code{MAKE} variable. It passes the value of the variable
4100 @code{AM_MAKEFLAGS} to the @command{make} invocation; this can be set in
4101 @file{Makefile.am} if there are flags you must always pass to
4104 @vindex AM_MAKEFLAGS
4106 The directories mentioned in @code{SUBDIRS} are usually direct
4107 children of the current directory, each subdirectory containing its
4108 own @file{Makefile.am} with a @code{SUBDIRS} pointing to deeper
4109 subdirectories. Automake can be used to construct packages of
4110 arbitrary depth this way.
4112 By default, Automake generates @file{Makefiles} that work depth-first
4113 in postfix order: the subdirectories are built before the current
4114 directory. However, it is possible to change this ordering. You can
4115 do this by putting @samp{.} into @code{SUBDIRS}. For instance,
4116 putting @samp{.} first will cause a prefix ordering of
4122 SUBDIRS = lib src . test
4126 will cause @file{lib/} to be built before @file{src/}, then the
4127 current directory will be built, finally the @file{test/} directory
4128 will be built. It is customary to arrange test directories to be
4129 built after everything else since they are meant to test what has
4132 All @code{clean} rules are run in reverse order of build rules.
4134 @node Conditional Subdirectories
4135 @section Conditional Subdirectories
4136 @cindex Subdirectories, building conditionally
4137 @cindex Conditional subdirectories
4138 @cindex @code{SUBDIRS}, conditional
4139 @cindex Conditional @code{SUBDIRS}
4141 It is possible to define the @code{SUBDIRS} variable conditionally if,
4142 like in the case of GNU Inetutils, you want to only build a subset of
4145 To illustrate how this works, let's assume we have two directories
4146 @file{src/} and @file{opt/}. @file{src/} should always be built, but we
4147 want to decide in @command{configure} whether @file{opt/} will be built
4148 or not. (For this example we will assume that @file{opt/} should be
4149 built when the variable @samp{$want_opt} was set to @samp{yes}.)
4151 Running @command{make} should thus recurse into @file{src/} always, and
4152 then maybe in @file{opt/}.
4154 However @samp{make dist} should always recurse into both @file{src/}
4155 and @file{opt/}. Because @file{opt/} should be distributed even if it
4156 is not needed in the current configuration. This means
4157 @file{opt/Makefile} should be created @emph{unconditionally}.
4159 There are two ways to setup a project like this. You can use Automake
4160 conditionals (@pxref{Conditionals}) or use Autoconf @code{AC_SUBST}
4161 variables (@pxref{Setting Output Variables, , Setting Output
4162 Variables, autoconf, The Autoconf Manual}). Using Automake
4163 conditionals is the preferred solution. Before we illustrate these
4164 two possibilities, let's introduce @code{DIST_SUBDIRS}.
4167 * SUBDIRS vs DIST_SUBDIRS:: Two sets of directories
4168 * Subdirectories with AM_CONDITIONAL:: Specifying conditional subdirectories
4169 * Subdirectories with AC_SUBST:: Another way for conditional recursion
4170 * Unconfigured Subdirectories:: Not even creating a @samp{Makefile}
4173 @node SUBDIRS vs DIST_SUBDIRS
4174 @subsection @code{SUBDIRS} vs.@: @code{DIST_SUBDIRS}
4175 @cindex @code{DIST_SUBDIRS}, explained
4177 Automake considers two sets of directories, defined by the variables
4178 @code{SUBDIRS} and @code{DIST_SUBDIRS}.
4180 @code{SUBDIRS} contains the subdirectories of the current directory
4181 that must be built (@pxref{Subdirectories}). It must be defined
4182 manually; Automake will never guess a directory is to be built. As we
4183 will see in the next two sections, it is possible to define it
4184 conditionally so that some directory will be omitted from the build.
4186 @code{DIST_SUBDIRS} is used in rules that need to recurse in all
4187 directories, even those that have been conditionally left out of the
4188 build. Recall our example where we may not want to build subdirectory
4189 @file{opt/}, but yet we want to distribute it? This is where
4190 @code{DIST_SUBDIRS} comes into play: @samp{opt} may not appear in
4191 @code{SUBDIRS}, but it must appear in @code{DIST_SUBDIRS}.
4193 Precisely, @code{DIST_SUBDIRS} is used by @samp{make
4194 maintainer-clean}, @samp{make distclean} and @samp{make dist}. All
4195 other recursive rules use @code{SUBDIRS}.
4197 If @code{SUBDIRS} is defined conditionally using Automake
4198 conditionals, Automake will define @code{DIST_SUBDIRS} automatically
4199 from the possible values of @code{SUBDIRS} in all conditions.
4201 If @code{SUBDIRS} contains @code{AC_SUBST} variables,
4202 @code{DIST_SUBDIRS} will not be defined correctly because Automake
4203 does not know the possible values of these variables. In this case
4204 @code{DIST_SUBDIRS} needs to be defined manually.
4206 @node Subdirectories with AM_CONDITIONAL
4207 @subsection Subdirectories with @code{AM_CONDITIONAL}
4208 @cindex @code{SUBDIRS} and @code{AM_CONDITIONAL}
4209 @cindex @code{AM_CONDITIONAL} and @code{SUBDIRS}
4211 @c The test case for the setup described here is
4212 @c test/subdircond2.test
4213 @c Try to keep it in sync.
4215 @file{configure} should output the @file{Makefile} for each directory
4216 and define a condition into which @file{opt/} should be built.
4220 AM_CONDITIONAL([COND_OPT], [test "$want_opt" = yes])
4221 AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
4225 Then @code{SUBDIRS} can be defined in the top-level @file{Makefile.am}
4232 SUBDIRS = src $(MAYBE_OPT)
4235 As you can see, running @command{make} will rightly recurse into
4236 @file{src/} and maybe @file{opt/}.
4238 @vindex DIST_SUBDIRS
4239 As you can't see, running @samp{make dist} will recurse into both
4240 @file{src/} and @file{opt/} directories because @samp{make dist}, unlike
4241 @samp{make all}, doesn't use the @code{SUBDIRS} variable. It uses the
4242 @code{DIST_SUBDIRS} variable.
4244 In this case Automake will define @samp{DIST_SUBDIRS = src opt}
4245 automatically because it knows that @code{MAYBE_OPT} can contain
4246 @samp{opt} in some condition.
4248 @node Subdirectories with AC_SUBST
4249 @subsection Subdirectories with @code{AC_SUBST}
4250 @cindex @code{SUBDIRS} and @code{AC_SUBST}
4251 @cindex @code{AC_SUBST} and @code{SUBDIRS}
4253 @c The test case for the setup described here is
4254 @c test/subdircond3.test
4255 @c Try to keep it in sync.
4257 Another possibility is to define @code{MAYBE_OPT} from
4258 @file{./configure} using @code{AC_SUBST}:
4262 if test "$want_opt" = yes; then
4267 AC_SUBST([MAYBE_OPT])
4268 AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
4272 In this case the top-level @file{Makefile.am} should look as follows.
4275 SUBDIRS = src $(MAYBE_OPT)
4276 DIST_SUBDIRS = src opt
4279 The drawback is that since Automake cannot guess what the possible
4280 values of @code{MAYBE_OPT} are, it is necessary to define
4281 @code{DIST_SUBDIRS}.
4283 @node Unconfigured Subdirectories
4284 @subsection Unconfigured Subdirectories
4285 @cindex Subdirectories, configured conditionally
4287 The semantics of @code{DIST_SUBDIRS} are often misunderstood by some
4288 users that try to @emph{configure and build} subdirectories
4289 conditionally. Here by configuring we mean creating the
4290 @file{Makefile} (it might also involve running a nested
4291 @command{configure} script: this is a costly operation that explains
4292 why people want to do it conditionally, but only the @file{Makefile}
4293 is relevant to the discussion).
4295 The above examples all assume that every @file{Makefile} is created,
4296 even in directories that are not going to be built. The simple reason
4297 is that we want @samp{make dist} to distribute even the directories
4298 that are not being built (e.g., platform-dependent code), hence
4299 @file{make dist} must recurse into the subdirectory, hence this
4300 directory must be configured and appear in @code{DIST_SUBDIRS}.
4302 Building packages that do not configure every subdirectory is a tricky
4303 business, and we do not recommend it to the novice as it is easy to
4304 produce an incomplete tarball by mistake. We will not discuss this
4305 topic in depth here, yet for the adventurous here are a few rules to
4310 @item @code{SUBDIRS} should always be a subset of @code{DIST_SUBDIRS}.
4312 It makes little sense to have a directory in @code{SUBDIRS} that
4313 is not in @code{DIST_SUBDIRS}. Think of the former as a way to tell
4314 which directories listed in the latter should be built.
4315 @item Any directory listed in @code{DIST_SUBDIRS} and @code{SUBDIRS}
4318 I.e., the @file{Makefile} must exists or the recursive @command{make}
4319 rules will not be able to process the directory.
4320 @item Any configured directory must be listed in @code{DIST_SUBDIRS}.
4322 So that the cleaning rules remove the generated @file{Makefile}s.
4323 It would be correct to see @code{DIST_SUBDIRS} as a variable that
4324 lists all the directories that have been configured.
4328 In order to prevent recursion in some unconfigured directory you
4329 must therefore ensure that this directory does not appear in
4330 @code{DIST_SUBDIRS} (and @code{SUBDIRS}). For instance, if you define
4331 @code{SUBDIRS} conditionally using @code{AC_SUBST} and do not define
4332 @code{DIST_SUBDIRS} explicitly, it will be default to
4333 @samp{$(SUBDIRS)}; another possibility is to force @code{DIST_SUBDIRS
4336 Of course, directories that are omitted from @code{DIST_SUBDIRS} will
4337 not be distributed unless you make other arrangements for this to
4338 happen (for instance, always running @samp{make dist} in a
4339 configuration where all directories are known to appear in
4340 @code{DIST_SUBDIRS}; or writing a @code{dist-hook} target to
4341 distribute these directories).
4343 @cindex Subdirectories, not distributed
4344 In few packages, unconfigured directories are not even expected to
4345 be distributed. Although these packages do not require the
4346 aforementioned extra arrangements, there is another pitfall. If the
4347 name of a directory appears in @code{SUBDIRS} or @code{DIST_SUBDIRS},
4348 @command{automake} will make sure the directory exists. Consequently
4349 @command{automake} cannot be run on such a distribution when one
4350 directory has been omitted. One way to avoid this check is to use the
4351 @code{AC_SUBST} method to declare conditional directories; since
4352 @command{automake} does not know the values of @code{AC_SUBST}
4353 variables it cannot ensure the corresponding directory exists.
4356 @section An Alternative Approach to Subdirectories
4358 If you've ever read Peter Miller's excellent paper,
4359 @uref{http://miller.emu.id.au/pmiller/books/rmch/,
4360 Recursive Make Considered Harmful}, the preceding sections on the use of
4361 subdirectories will probably come as unwelcome advice. For those who
4362 haven't read the paper, Miller's main thesis is that recursive
4363 @command{make} invocations are both slow and error-prone.
4365 Automake provides sufficient cross-directory support @footnote{We
4366 believe. This work is new and there are probably warts.
4367 @xref{Introduction}, for information on reporting bugs.} to enable you
4368 to write a single @file{Makefile.am} for a complex multi-directory
4372 By default an installable file specified in a subdirectory will have its
4373 directory name stripped before installation. For instance, in this
4374 example, the header file will be installed as
4375 @file{$(includedir)/stdio.h}:
4378 include_HEADERS = inc/stdio.h
4382 @cindex @code{nobase_} prefix
4383 @cindex Path stripping, avoiding
4384 @cindex Avoiding path stripping
4386 However, the @samp{nobase_} prefix can be used to circumvent this path
4387 stripping. In this example, the header file will be installed as
4388 @file{$(includedir)/sys/types.h}:
4391 nobase_include_HEADERS = sys/types.h
4394 @cindex @code{nobase_} and @code{dist_} or @code{nodist_}
4395 @cindex @code{dist_} and @code{nobase_}
4396 @cindex @code{nodist_} and @code{nobase_}
4400 @samp{nobase_} should be specified first when used in conjunction with
4401 either @samp{dist_} or @samp{nodist_} (@pxref{Fine-grained Distribution
4402 Control}). For instance:
4405 nobase_dist_pkgdata_DATA = images/vortex.pgm sounds/whirl.ogg
4408 Finally, note that a variable using the @samp{nobase_} prefix can
4409 often be replaced by several variables, one for each destination
4410 directory (@pxref{Uniform}). For instance, the last example could be
4411 rewritten as follows:
4414 imagesdir = $(pkgdatadir)/images
4415 soundsdir = $(pkgdatadir)/sounds
4416 dist_images_DATA = images/vortex.pgm
4417 dist_sounds_DATA = sounds/whirl.ogg
4421 This latter syntax makes it possible to change one destination
4422 directory without changing the layout of the source tree.
4424 Currently, @samp{nobase_*_LTLIBRARIES} are the only exception to this
4425 rule, in that there is no particular installation order guarantee for
4426 an otherwise equivalent set of variables without @samp{nobase_} prefix.
4429 @section Nesting Packages
4430 @cindex Nesting packages
4432 @acindex AC_CONFIG_SUBDIRS
4433 @acindex AC_CONFIG_AUX_DIR
4436 In the GNU Build System, packages can be nested to arbitrary depth.
4437 This means that a package can embed other packages with their own
4438 @file{configure}, @file{Makefile}s, etc.
4440 These other packages should just appear as subdirectories of their
4441 parent package. They must be listed in @code{SUBDIRS} like other
4442 ordinary directories. However the subpackage's @file{Makefile}s
4443 should be output by its own @file{configure} script, not by the
4444 parent's @file{configure}. This is achieved using the
4445 @code{AC_CONFIG_SUBDIRS} Autoconf macro (@pxref{Subdirectories,
4446 AC_CONFIG_SUBDIRS, Configuring Other Packages in Subdirectories,
4447 autoconf, The Autoconf Manual}).
4449 Here is an example package for an @code{arm} program that links with
4450 a @code{hand} library that is a nested package in subdirectory
4453 @code{arm}'s @file{configure.ac}:
4456 AC_INIT([arm], [1.0])
4457 AC_CONFIG_AUX_DIR([.])
4460 AC_CONFIG_FILES([Makefile])
4461 # Call hand's ./configure script recursively.
4462 AC_CONFIG_SUBDIRS([hand])
4466 @code{arm}'s @file{Makefile.am}:
4469 # Build the library in the hand subdirectory first.
4472 # Include hand's header when compiling this directory.
4473 AM_CPPFLAGS = -I$(srcdir)/hand
4477 # link with the hand library.
4478 arm_LDADD = hand/libhand.a
4481 Now here is @code{hand}'s @file{hand/configure.ac}:
4484 AC_INIT([hand], [1.2])
4485 AC_CONFIG_AUX_DIR([.])
4489 AC_CONFIG_FILES([Makefile])
4494 and its @file{hand/Makefile.am}:
4497 lib_LIBRARIES = libhand.a
4498 libhand_a_SOURCES = hand.c
4501 When @samp{make dist} is run from the top-level directory it will
4502 create an archive @file{arm-1.0.tar.gz} that contains the @code{arm}
4503 code as well as the @file{hand} subdirectory. This package can be
4504 built and installed like any ordinary package, with the usual
4505 @samp{./configure && make && make install} sequence (the @code{hand}
4506 subpackage will be built and installed by the process).
4508 When @samp{make dist} is run from the hand directory, it will create a
4509 self-contained @file{hand-1.2.tar.gz} archive. So although it appears
4510 to be embedded in another package, it can still be used separately.
4512 The purpose of the @samp{AC_CONFIG_AUX_DIR([.])} instruction is to
4513 force Automake and Autoconf to search for auxiliary scripts in the
4514 current directory. For instance, this means that there will be two
4515 copies of @file{install-sh}: one in the top-level of the @code{arm}
4516 package, and another one in the @file{hand/} subdirectory for the
4517 @code{hand} package.
4519 The historical default is to search for these auxiliary scripts in
4520 the parent directory and the grandparent directory. So if the
4521 @samp{AC_CONFIG_AUX_DIR([.])} line was removed from
4522 @file{hand/configure.ac}, that subpackage would share the auxiliary
4523 script of the @code{arm} package. This may looks like a gain in size
4524 (a few kilobytes), but it is actually a loss of modularity as the
4525 @code{hand} subpackage is no longer self-contained (@samp{make dist}
4526 in the subdirectory will not work anymore).
4528 Packages that do not use Automake need more work to be integrated this
4529 way. @xref{Third-Party Makefiles}.
4532 @chapter Building Programs and Libraries
4534 A large part of Automake's functionality is dedicated to making it easy
4535 to build programs and libraries.
4538 * A Program:: Building a program
4539 * A Library:: Building a library
4540 * A Shared Library:: Building a Libtool library
4541 * Program and Library Variables:: Variables controlling program and
4543 * Default _SOURCES:: Default source files
4544 * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
4545 * Program Variables:: Variables used when building a program
4546 * Yacc and Lex:: Yacc and Lex support
4547 * C++ Support:: Compiling C++ sources
4548 * Objective C Support:: Compiling Objective C sources
4549 * Unified Parallel C Support:: Compiling Unified Parallel C sources
4550 * Assembly Support:: Compiling assembly sources
4551 * Fortran 77 Support:: Compiling Fortran 77 sources
4552 * Fortran 9x Support:: Compiling Fortran 9x sources
4553 * Java Support:: Compiling Java sources
4554 * Vala Support:: Compiling Vala sources
4555 * Support for Other Languages:: Compiling other languages
4556 * ANSI:: Automatic de-ANSI-fication (obsolete)
4557 * Dependencies:: Automatic dependency tracking
4558 * EXEEXT:: Support for executable extensions
4563 @section Building a program
4565 In order to build a program, you need to tell Automake which sources
4566 are part of it, and which libraries it should be linked with.
4568 This section also covers conditional compilation of sources or
4569 programs. Most of the comments about these also apply to libraries
4570 (@pxref{A Library}) and libtool libraries (@pxref{A Shared Library}).
4573 * Program Sources:: Defining program sources
4574 * Linking:: Linking with libraries or extra objects
4575 * Conditional Sources:: Handling conditional sources
4576 * Conditional Programs:: Building a program conditionally
4579 @node Program Sources
4580 @subsection Defining program sources
4582 @cindex @code{PROGRAMS}, @code{bindir}
4584 @vindex bin_PROGRAMS
4585 @vindex sbin_PROGRAMS
4586 @vindex libexec_PROGRAMS
4587 @vindex pkglib_PROGRAMS
4588 @vindex noinst_PROGRAMS
4589 @vindex check_PROGRAMS
4591 In a directory containing source that gets built into a program (as
4592 opposed to a library or a script), the @code{PROGRAMS} primary is used.
4593 Programs can be installed in @code{bindir}, @code{sbindir},
4594 @code{libexecdir}, @code{pkglibdir}, @code{pkglibexecdir}, or not at all
4595 (@code{noinst_}). They can also be built only for @samp{make check}, in
4596 which case the prefix is @samp{check_}.
4601 bin_PROGRAMS = hello
4604 In this simple case, the resulting @file{Makefile.in} will contain code
4605 to generate a program named @code{hello}.
4607 Associated with each program are several assisting variables that are
4608 named after the program. These variables are all optional, and have
4609 reasonable defaults. Each variable, its use, and default is spelled out
4610 below; we use the ``hello'' example throughout.
4612 The variable @code{hello_SOURCES} is used to specify which source files
4613 get built into an executable:
4616 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
4619 This causes each mentioned @file{.c} file to be compiled into the
4620 corresponding @file{.o}. Then all are linked to produce @file{hello}.
4622 @cindex @code{_SOURCES} primary, defined
4623 @cindex @code{SOURCES} primary, defined
4624 @cindex Primary variable, @code{SOURCES}
4627 If @code{hello_SOURCES} is not specified, then it defaults to the single
4628 file @file{hello.c} (@pxref{Default _SOURCES}).
4632 Multiple programs can be built in a single directory. Multiple programs
4633 can share a single source file, which must be listed in each
4634 @code{_SOURCES} definition.
4636 @cindex Header files in @code{_SOURCES}
4637 @cindex @code{_SOURCES} and header files
4639 Header files listed in a @code{_SOURCES} definition will be included in
4640 the distribution but otherwise ignored. In case it isn't obvious, you
4641 should not include the header file generated by @file{configure} in a
4642 @code{_SOURCES} variable; this file should not be distributed. Lex
4643 (@file{.l}) and Yacc (@file{.y}) files can also be listed; see @ref{Yacc
4648 @subsection Linking the program
4650 If you need to link against libraries that are not found by
4651 @command{configure}, you can use @code{LDADD} to do so. This variable is
4652 used to specify additional objects or libraries to link with; it is
4653 inappropriate for specifying specific linker flags, you should use
4654 @code{AM_LDFLAGS} for this purpose.
4658 @cindex @code{prog_LDADD}, defined
4660 Sometimes, multiple programs are built in one directory but do not share
4661 the same link-time requirements. In this case, you can use the
4662 @code{@var{prog}_LDADD} variable (where @var{prog} is the name of the
4663 program as it appears in some @code{_PROGRAMS} variable, and usually
4664 written in lowercase) to override @code{LDADD}. If this variable exists
4665 for a given program, then that program is not linked using @code{LDADD}.
4668 For instance, in GNU cpio, @code{pax}, @code{cpio} and @code{mt} are
4669 linked against the library @file{libcpio.a}. However, @code{rmt} is
4670 built in the same directory, and has no such link requirement. Also,
4671 @code{mt} and @code{rmt} are only built on certain architectures. Here
4672 is what cpio's @file{src/Makefile.am} looks like (abridged):
4675 bin_PROGRAMS = cpio pax $(MT)
4676 libexec_PROGRAMS = $(RMT)
4677 EXTRA_PROGRAMS = mt rmt
4679 LDADD = ../lib/libcpio.a $(INTLLIBS)
4682 cpio_SOURCES = @dots{}
4683 pax_SOURCES = @dots{}
4684 mt_SOURCES = @dots{}
4685 rmt_SOURCES = @dots{}
4688 @cindex @code{_LDFLAGS}, defined
4689 @vindex maude_LDFLAGS
4690 @code{@var{prog}_LDADD} is inappropriate for passing program-specific
4691 linker flags (except for @option{-l}, @option{-L}, @option{-dlopen} and
4692 @option{-dlpreopen}). So, use the @code{@var{prog}_LDFLAGS} variable for
4695 @cindex @code{_DEPENDENCIES}, defined
4696 @vindex maude_DEPENDENCIES
4697 It is also occasionally useful to have a program depend on some other
4698 target that is not actually part of that program. This can be done
4699 using the @code{@var{prog}_DEPENDENCIES} variable. Each program
4700 depends on the contents of such a variable, but no further
4701 interpretation is done.
4703 Since these dependencies are associated to the link rule used to
4704 create the programs they should normally list files used by the link
4705 command. That is @file{*.$(OBJEXT)}, @file{*.a}, or @file{*.la}
4706 files. In rare cases you may need to add other kinds of files such as
4707 linker scripts, but @emph{listing a source file in
4708 @code{_DEPENDENCIES} is wrong}. If some source file needs to be built
4709 before all the components of a program are built, consider using the
4710 @code{BUILT_SOURCES} variable instead (@pxref{Sources}).
4712 If @code{@var{prog}_DEPENDENCIES} is not supplied, it is computed by
4713 Automake. The automatically-assigned value is the contents of
4714 @code{@var{prog}_LDADD}, with most configure substitutions, @option{-l},
4715 @option{-L}, @option{-dlopen} and @option{-dlpreopen} options removed. The
4716 configure substitutions that are left in are only @samp{$(LIBOBJS)} and
4717 @samp{$(ALLOCA)}; these are left because it is known that they will not
4718 cause an invalid value for @code{@var{prog}_DEPENDENCIES} to be
4721 @ref{Conditional Sources} shows a situation where @code{_DEPENDENCIES}
4724 @cindex @code{LDADD} and @option{-l}
4725 @cindex @option{-l} and @code{LDADD}
4726 We recommend that you avoid using @option{-l} options in @code{LDADD}
4727 or @code{@var{prog}_LDADD} when referring to libraries built by your
4728 package. Instead, write the file name of the library explicitly as in
4729 the above @code{cpio} example. Use @option{-l} only to list
4730 third-party libraries. If you follow this rule, the default value of
4731 @code{@var{prog}_DEPENDENCIES} will list all your local libraries and
4732 omit the other ones.
4735 @node Conditional Sources
4736 @subsection Conditional compilation of sources
4738 You can't put a configure substitution (e.g., @samp{@@FOO@@} or
4739 @samp{$(FOO)} where @code{FOO} is defined via @code{AC_SUBST}) into a
4740 @code{_SOURCES} variable. The reason for this is a bit hard to
4741 explain, but suffice to say that it simply won't work. Automake will
4742 give an error if you try to do this.
4744 Fortunately there are two other ways to achieve the same result. One is
4745 to use configure substitutions in @code{_LDADD} variables, the other is
4746 to use an Automake conditional.
4748 @subsubheading Conditional Compilation using @code{_LDADD} Substitutions
4750 @cindex @code{EXTRA_prog_SOURCES}, defined
4752 Automake must know all the source files that could possibly go into a
4753 program, even if not all the files are built in every circumstance. Any
4754 files that are only conditionally built should be listed in the
4755 appropriate @code{EXTRA_} variable. For instance, if
4756 @file{hello-linux.c} or @file{hello-generic.c} were conditionally included
4757 in @code{hello}, the @file{Makefile.am} would contain:
4760 bin_PROGRAMS = hello
4761 hello_SOURCES = hello-common.c
4762 EXTRA_hello_SOURCES = hello-linux.c hello-generic.c
4763 hello_LDADD = $(HELLO_SYSTEM)
4764 hello_DEPENDENCIES = $(HELLO_SYSTEM)
4768 You can then setup the @samp{$(HELLO_SYSTEM)} substitution from
4769 @file{configure.ac}:
4774 *linux*) HELLO_SYSTEM='hello-linux.$(OBJEXT)' ;;
4775 *) HELLO_SYSTEM='hello-generic.$(OBJEXT)' ;;
4777 AC_SUBST([HELLO_SYSTEM])
4781 In this case, the variable @code{HELLO_SYSTEM} should be replaced by
4782 either @file{hello-linux.o} or @file{hello-generic.o}, and added to
4783 both @code{hello_DEPENDENCIES} and @code{hello_LDADD} in order to be
4784 built and linked in.
4786 @subsubheading Conditional Compilation using Automake Conditionals
4788 An often simpler way to compile source files conditionally is to use
4789 Automake conditionals. For instance, you could use this
4790 @file{Makefile.am} construct to build the same @file{hello} example:
4793 bin_PROGRAMS = hello
4795 hello_SOURCES = hello-linux.c hello-common.c
4797 hello_SOURCES = hello-generic.c hello-common.c
4801 In this case, @file{configure.ac} should setup the @code{LINUX}
4802 conditional using @code{AM_CONDITIONAL} (@pxref{Conditionals}).
4804 When using conditionals like this you don't need to use the
4805 @code{EXTRA_} variable, because Automake will examine the contents of
4806 each variable to construct the complete list of source files.
4808 If your program uses a lot of files, you will probably prefer a
4809 conditional @samp{+=}.
4812 bin_PROGRAMS = hello
4813 hello_SOURCES = hello-common.c
4815 hello_SOURCES += hello-linux.c
4817 hello_SOURCES += hello-generic.c
4821 @node Conditional Programs
4822 @subsection Conditional compilation of programs
4823 @cindex Conditional programs
4824 @cindex Programs, conditional
4826 Sometimes it is useful to determine the programs that are to be built
4827 at configure time. For instance, GNU @code{cpio} only builds
4828 @code{mt} and @code{rmt} under special circumstances. The means to
4829 achieve conditional compilation of programs are the same you can use
4830 to compile source files conditionally: substitutions or conditionals.
4832 @subsubheading Conditional Programs using @command{configure} Substitutions
4834 @vindex EXTRA_PROGRAMS
4835 @cindex @code{EXTRA_PROGRAMS}, defined
4836 In this case, you must notify Automake of all the programs that can
4837 possibly be built, but at the same time cause the generated
4838 @file{Makefile.in} to use the programs specified by @command{configure}.
4839 This is done by having @command{configure} substitute values into each
4840 @code{_PROGRAMS} definition, while listing all optionally built programs
4841 in @code{EXTRA_PROGRAMS}.
4844 bin_PROGRAMS = cpio pax $(MT)
4845 libexec_PROGRAMS = $(RMT)
4846 EXTRA_PROGRAMS = mt rmt
4849 As explained in @ref{EXEEXT}, Automake will rewrite
4850 @code{bin_PROGRAMS}, @code{libexec_PROGRAMS}, and
4851 @code{EXTRA_PROGRAMS}, appending @samp{$(EXEEXT)} to each binary.
4852 Obviously it cannot rewrite values obtained at run-time through
4853 @command{configure} substitutions, therefore you should take care of
4854 appending @samp{$(EXEEXT)} yourself, as in @samp{AC_SUBST([MT],
4855 ['mt$@{EXEEXT@}'])}.
4857 @subsubheading Conditional Programs using Automake Conditionals
4859 You can also use Automake conditionals (@pxref{Conditionals}) to
4860 select programs to be built. In this case you don't have to worry
4861 about @samp{$(EXEEXT)} or @code{EXTRA_PROGRAMS}.
4864 bin_PROGRAMS = cpio pax
4869 libexec_PROGRAMS = rmt
4875 @section Building a library
4877 @cindex @code{_LIBRARIES} primary, defined
4878 @cindex @code{LIBRARIES} primary, defined
4879 @cindex Primary variable, @code{LIBRARIES}
4882 @vindex lib_LIBRARIES
4883 @vindex pkglib_LIBRARIES
4884 @vindex noinst_LIBRARIES
4886 Building a library is much like building a program. In this case, the
4887 name of the primary is @code{LIBRARIES}. Libraries can be installed in
4888 @code{libdir} or @code{pkglibdir}.
4890 @xref{A Shared Library}, for information on how to build shared
4891 libraries using libtool and the @code{LTLIBRARIES} primary.
4893 Each @code{_LIBRARIES} variable is a list of the libraries to be built.
4894 For instance, to create a library named @file{libcpio.a}, but not install
4895 it, you would write:
4898 noinst_LIBRARIES = libcpio.a
4899 libcpio_a_SOURCES = @dots{}
4902 The sources that go into a library are determined exactly as they are
4903 for programs, via the @code{_SOURCES} variables. Note that the library
4904 name is canonicalized (@pxref{Canonicalization}), so the @code{_SOURCES}
4905 variable corresponding to @file{libcpio.a} is @samp{libcpio_a_SOURCES},
4906 not @samp{libcpio.a_SOURCES}.
4908 @vindex maude_LIBADD
4909 Extra objects can be added to a library using the
4910 @code{@var{library}_LIBADD} variable. This should be used for objects
4911 determined by @command{configure}. Again from @code{cpio}:
4914 libcpio_a_LIBADD = $(LIBOBJS) $(ALLOCA)
4917 In addition, sources for extra objects that will not exist until
4918 configure-time must be added to the @code{BUILT_SOURCES} variable
4921 Building a static library is done by compiling all object files, then
4922 by invoking @samp{$(AR) $(ARFLAGS)} followed by the name of the
4923 library and the list of objects, and finally by calling
4924 @samp{$(RANLIB)} on that library. You should call
4925 @code{AC_PROG_RANLIB} from your @file{configure.ac} to define
4926 @code{RANLIB} (Automake will complain otherwise). @code{AR} and
4927 @code{ARFLAGS} default to @code{ar} and @code{cru} respectively; you
4928 can override these two variables my setting them in your
4929 @file{Makefile.am}, by @code{AC_SUBST}ing them from your
4930 @file{configure.ac}, or by defining a per-library @code{maude_AR}
4931 variable (@pxref{Program and Library Variables}).
4933 @cindex Empty libraries
4934 Be careful when selecting library components conditionally. Because
4935 building an empty library is not portable, you should ensure that any
4936 library always contains at least one object.
4938 To use a static library when building a program, add it to
4939 @code{LDADD} for this program. In the following example, the program
4940 @file{cpio} is statically linked with the library @file{libcpio.a}.
4943 noinst_LIBRARIES = libcpio.a
4944 libcpio_a_SOURCES = @dots{}
4947 cpio_SOURCES = cpio.c @dots{}
4948 cpio_LDADD = libcpio.a
4952 @node A Shared Library
4953 @section Building a Shared Library
4955 @cindex Shared libraries, support for
4957 Building shared libraries portably is a relatively complex matter.
4958 For this reason, GNU Libtool (@pxref{Top, , Introduction, libtool, The
4959 Libtool Manual}) was created to help build shared libraries in a
4960 platform-independent way.
4963 * Libtool Concept:: Introducing Libtool
4964 * Libtool Libraries:: Declaring Libtool Libraries
4965 * Conditional Libtool Libraries:: Building Libtool Libraries Conditionally
4966 * Conditional Libtool Sources:: Choosing Library Sources Conditionally
4967 * Libtool Convenience Libraries:: Building Convenience Libtool Libraries
4968 * Libtool Modules:: Building Libtool Modules
4969 * Libtool Flags:: Using _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS
4970 * LTLIBOBJS:: Using $(LTLIBOBJS) and $(LTALLOCA)
4971 * Libtool Issues:: Common Issues Related to Libtool's Use
4974 @node Libtool Concept
4975 @subsection The Libtool Concept
4977 @cindex @command{libtool}, introduction
4978 @cindex libtool library, definition
4979 @cindex suffix @file{.la}, defined
4980 @cindex @file{.la} suffix, defined
4982 Libtool abstracts shared and static libraries into a unified concept
4983 henceforth called @dfn{libtool libraries}. Libtool libraries are
4984 files using the @file{.la} suffix, and can designate a static library,
4985 a shared library, or maybe both. Their exact nature cannot be
4986 determined until @file{./configure} is run: not all platforms support
4987 all kinds of libraries, and users can explicitly select which
4988 libraries should be built. (However the package's maintainers can
4989 tune the default, @pxref{AC_PROG_LIBTOOL, , The @code{AC_PROG_LIBTOOL}
4990 macro, libtool, The Libtool Manual}.)
4992 @cindex suffix @file{.lo}, defined
4993 Because object files for shared and static libraries must be compiled
4994 differently, libtool is also used during compilation. Object files
4995 built by libtool are called @dfn{libtool objects}: these are files
4996 using the @file{.lo} suffix. Libtool libraries are built from these
4999 You should not assume anything about the structure of @file{.la} or
5000 @file{.lo} files and how libtool constructs them: this is libtool's
5001 concern, and the last thing one wants is to learn about libtool's
5002 guts. However the existence of these files matters, because they are
5003 used as targets and dependencies in @file{Makefile}s rules when
5004 building libtool libraries. There are situations where you may have
5005 to refer to these, for instance when expressing dependencies for
5006 building source files conditionally (@pxref{Conditional Libtool
5009 @cindex @file{libltdl}, introduction
5011 People considering writing a plug-in system, with dynamically loaded
5012 modules, should look into @file{libltdl}: libtool's dlopening library
5013 (@pxref{Using libltdl, , Using libltdl, libtool, The Libtool Manual}).
5014 This offers a portable dlopening facility to load libtool libraries
5015 dynamically, and can also achieve static linking where unavoidable.
5017 Before we discuss how to use libtool with Automake in details, it
5018 should be noted that the libtool manual also has a section about how
5019 to use Automake with libtool (@pxref{Using Automake, , Using Automake
5020 with Libtool, libtool, The Libtool Manual}).
5022 @node Libtool Libraries
5023 @subsection Building Libtool Libraries
5025 @cindex @code{_LTLIBRARIES} primary, defined
5026 @cindex @code{LTLIBRARIES} primary, defined
5027 @cindex Primary variable, @code{LTLIBRARIES}
5028 @cindex Example of shared libraries
5029 @vindex lib_LTLIBRARIES
5030 @vindex pkglib_LTLIBRARIES
5031 @vindex _LTLIBRARIES
5033 Automake uses libtool to build libraries declared with the
5034 @code{LTLIBRARIES} primary. Each @code{_LTLIBRARIES} variable is a
5035 list of libtool libraries to build. For instance, to create a libtool
5036 library named @file{libgettext.la}, and install it in @code{libdir},
5040 lib_LTLIBRARIES = libgettext.la
5041 libgettext_la_SOURCES = gettext.c gettext.h @dots{}
5044 Automake predefines the variable @code{pkglibdir}, so you can use
5045 @code{pkglib_LTLIBRARIES} to install libraries in
5046 @samp{$(libdir)/@@PACKAGE@@/}.
5048 If @file{gettext.h} is a public header file that needs to be installed
5049 in order for people to use the library, it should be declared using a
5050 @code{_HEADERS} variable, not in @code{libgettext_la_SOURCES}.
5051 Headers listed in the latter should be internal headers that are not
5052 part of the public interface.
5055 lib_LTLIBRARIES = libgettext.la
5056 libgettext_la_SOURCES = gettext.c @dots{}
5057 include_HEADERS = gettext.h @dots{}
5060 A package can build and install such a library along with other
5061 programs that use it. This dependency should be specified using
5062 @code{LDADD}. The following example builds a program named
5063 @file{hello} that is linked with @file{libgettext.la}.
5066 lib_LTLIBRARIES = libgettext.la
5067 libgettext_la_SOURCES = gettext.c @dots{}
5069 bin_PROGRAMS = hello
5070 hello_SOURCES = hello.c @dots{}
5071 hello_LDADD = libgettext.la
5075 Whether @file{hello} is statically or dynamically linked with
5076 @file{libgettext.la} is not yet known: this will depend on the
5077 configuration of libtool and the capabilities of the host.
5080 @node Conditional Libtool Libraries
5081 @subsection Building Libtool Libraries Conditionally
5082 @cindex libtool libraries, conditional
5083 @cindex conditional libtool libraries
5085 Like conditional programs (@pxref{Conditional Programs}), there are
5086 two main ways to build conditional libraries: using Automake
5087 conditionals or using Autoconf @code{AC_SUBST}itutions.
5089 The important implementation detail you have to be aware of is that
5090 the place where a library will be installed matters to libtool: it
5091 needs to be indicated @emph{at link-time} using the @option{-rpath}
5094 For libraries whose destination directory is known when Automake runs,
5095 Automake will automatically supply the appropriate @option{-rpath}
5096 option to libtool. This is the case for libraries listed explicitly in
5097 some installable @code{_LTLIBRARIES} variables such as
5098 @code{lib_LTLIBRARIES}.
5100 However, for libraries determined at configure time (and thus
5101 mentioned in @code{EXTRA_LTLIBRARIES}), Automake does not know the
5102 final installation directory. For such libraries you must add the
5103 @option{-rpath} option to the appropriate @code{_LDFLAGS} variable by
5106 The examples below illustrate the differences between these two methods.
5108 Here is an example where @code{WANTEDLIBS} is an @code{AC_SUBST}ed
5109 variable set at @file{./configure}-time to either @file{libfoo.la},
5110 @file{libbar.la}, both, or none. Although @samp{$(WANTEDLIBS)}
5111 appears in the @code{lib_LTLIBRARIES}, Automake cannot guess it
5112 relates to @file{libfoo.la} or @file{libbar.la} at the time it creates
5113 the link rule for these two libraries. Therefore the @option{-rpath}
5114 argument must be explicitly supplied.
5117 EXTRA_LTLIBRARIES = libfoo.la libbar.la
5118 lib_LTLIBRARIES = $(WANTEDLIBS)
5119 libfoo_la_SOURCES = foo.c @dots{}
5120 libfoo_la_LDFLAGS = -rpath '$(libdir)'
5121 libbar_la_SOURCES = bar.c @dots{}
5122 libbar_la_LDFLAGS = -rpath '$(libdir)'
5125 Here is how the same @file{Makefile.am} would look using Automake
5126 conditionals named @code{WANT_LIBFOO} and @code{WANT_LIBBAR}. Now
5127 Automake is able to compute the @option{-rpath} setting itself, because
5128 it's clear that both libraries will end up in @samp{$(libdir)} if they
5134 lib_LTLIBRARIES += libfoo.la
5137 lib_LTLIBRARIES += libbar.la
5139 libfoo_la_SOURCES = foo.c @dots{}
5140 libbar_la_SOURCES = bar.c @dots{}
5143 @node Conditional Libtool Sources
5144 @subsection Libtool Libraries with Conditional Sources
5146 Conditional compilation of sources in a library can be achieved in the
5147 same way as conditional compilation of sources in a program
5148 (@pxref{Conditional Sources}). The only difference is that
5149 @code{_LIBADD} should be used instead of @code{_LDADD} and that it
5150 should mention libtool objects (@file{.lo} files).
5152 So, to mimic the @file{hello} example from @ref{Conditional Sources},
5153 we could build a @file{libhello.la} library using either
5154 @file{hello-linux.c} or @file{hello-generic.c} with the following
5158 lib_LTLIBRARIES = libhello.la
5159 libhello_la_SOURCES = hello-common.c
5160 EXTRA_libhello_la_SOURCES = hello-linux.c hello-generic.c
5161 libhello_la_LIBADD = $(HELLO_SYSTEM)
5162 libhello_la_DEPENDENCIES = $(HELLO_SYSTEM)
5166 And make sure @command{configure} defines @code{HELLO_SYSTEM} as
5167 either @file{hello-linux.lo} or @file{hello-@-generic.lo}.
5169 Or we could simply use an Automake conditional as follows.
5172 lib_LTLIBRARIES = libhello.la
5173 libhello_la_SOURCES = hello-common.c
5175 libhello_la_SOURCES += hello-linux.c
5177 libhello_la_SOURCES += hello-generic.c
5181 @node Libtool Convenience Libraries
5182 @subsection Libtool Convenience Libraries
5183 @cindex convenience libraries, libtool
5184 @cindex libtool convenience libraries
5185 @vindex noinst_LTLIBRARIES
5186 @vindex check_LTLIBRARIES
5188 Sometimes you want to build libtool libraries that should not be
5189 installed. These are called @dfn{libtool convenience libraries} and
5190 are typically used to encapsulate many sublibraries, later gathered
5191 into one big installed library.
5193 Libtool convenience libraries are declared by directory-less variables
5194 such as @code{noinst_LTLIBRARIES}, @code{check_LTLIBRARIES}, or even
5195 @code{EXTRA_LTLIBRARIES}. Unlike installed libtool libraries they do
5196 not need an @option{-rpath} flag at link time (actually this is the only
5199 Convenience libraries listed in @code{noinst_LTLIBRARIES} are always
5200 built. Those listed in @code{check_LTLIBRARIES} are built only upon
5201 @samp{make check}. Finally, libraries listed in
5202 @code{EXTRA_LTLIBRARIES} are never built explicitly: Automake outputs
5203 rules to build them, but if the library does not appear as a Makefile
5204 dependency anywhere it won't be built (this is why
5205 @code{EXTRA_LTLIBRARIES} is used for conditional compilation).
5207 Here is a sample setup merging libtool convenience libraries from
5208 subdirectories into one main @file{libtop.la} library.
5211 # -- Top-level Makefile.am --
5212 SUBDIRS = sub1 sub2 @dots{}
5213 lib_LTLIBRARIES = libtop.la
5215 libtop_la_LIBADD = \
5220 # -- sub1/Makefile.am --
5221 noinst_LTLIBRARIES = libsub1.la
5222 libsub1_la_SOURCES = @dots{}
5224 # -- sub2/Makefile.am --
5225 # showing nested convenience libraries
5226 SUBDIRS = sub2.1 sub2.2 @dots{}
5227 noinst_LTLIBRARIES = libsub2.la
5228 libsub2_la_SOURCES =
5229 libsub2_la_LIBADD = \
5235 When using such setup, beware that @command{automake} will assume
5236 @file{libtop.la} is to be linked with the C linker. This is because
5237 @code{libtop_la_SOURCES} is empty, so @command{automake} picks C as
5238 default language. If @code{libtop_la_SOURCES} was not empty,
5239 @command{automake} would select the linker as explained in @ref{How
5240 the Linker is Chosen}.
5242 If one of the sublibraries contains non-C source, it is important that
5243 the appropriate linker be chosen. One way to achieve this is to
5244 pretend that there is such a non-C file among the sources of the
5245 library, thus forcing @command{automake} to select the appropriate
5246 linker. Here is the top-level @file{Makefile} of our example updated
5247 to force C++ linking.
5250 SUBDIRS = sub1 sub2 @dots{}
5251 lib_LTLIBRARIES = libtop.la
5253 # Dummy C++ source to cause C++ linking.
5254 nodist_EXTRA_libtop_la_SOURCES = dummy.cxx
5255 libtop_la_LIBADD = \
5261 @samp{EXTRA_*_SOURCES} variables are used to keep track of source
5262 files that might be compiled (this is mostly useful when doing
5263 conditional compilation using @code{AC_SUBST}, @pxref{Conditional
5264 Libtool Sources}), and the @code{nodist_} prefix means the listed
5265 sources are not to be distributed (@pxref{Program and Library
5266 Variables}). In effect the file @file{dummy.cxx} does not need to
5267 exist in the source tree. Of course if you have some real source file
5268 to list in @code{libtop_la_SOURCES} there is no point in cheating with
5269 @code{nodist_EXTRA_libtop_la_SOURCES}.
5272 @node Libtool Modules
5273 @subsection Libtool Modules
5274 @cindex modules, libtool
5275 @cindex libtool modules
5276 @cindex @option{-module}, libtool
5278 These are libtool libraries meant to be dlopened. They are
5279 indicated to libtool by passing @option{-module} at link-time.
5282 pkglib_LTLIBRARIES = mymodule.la
5283 mymodule_la_SOURCES = doit.c
5284 mymodule_la_LDFLAGS = -module
5287 Ordinarily, Automake requires that a library's name start with
5288 @code{lib}. However, when building a dynamically loadable module you
5289 might wish to use a "nonstandard" name. Automake will not complain
5290 about such nonstandard names if it knows the library being built is a
5291 libtool module, i.e., if @option{-module} explicitly appears in the
5292 library's @code{_LDFLAGS} variable (or in the common @code{AM_LDFLAGS}
5293 variable when no per-library @code{_LDFLAGS} variable is defined).
5295 As always, @code{AC_SUBST} variables are black boxes to Automake since
5296 their values are not yet known when @command{automake} is run.
5297 Therefore if @option{-module} is set via such a variable, Automake
5298 cannot notice it and will proceed as if the library was an ordinary
5299 libtool library, with strict naming.
5301 If @code{mymodule_la_SOURCES} is not specified, then it defaults to
5302 the single file @file{mymodule.c} (@pxref{Default _SOURCES}).
5305 @subsection @code{_LIBADD}, @code{_LDFLAGS}, and @code{_LIBTOOLFLAGS}
5306 @cindex @code{_LIBADD}, libtool
5307 @cindex @code{_LDFLAGS}, libtool
5308 @cindex @code{_LIBTOOLFLAGS}, libtool
5309 @vindex AM_LIBTOOLFLAGS
5310 @vindex LIBTOOLFLAGS
5311 @vindex maude_LIBTOOLFLAGS
5313 As shown in previous sections, the @samp{@var{library}_LIBADD}
5314 variable should be used to list extra libtool objects (@file{.lo}
5315 files) or libtool libraries (@file{.la}) to add to @var{library}.
5317 The @samp{@var{library}_LDFLAGS} variable is the place to list
5318 additional libtool linking flags, such as @option{-version-info},
5319 @option{-static}, and a lot more. @xref{Link mode, , Link mode,
5320 libtool, The Libtool Manual}.
5322 The @command{libtool} command has two kinds of options: mode-specific
5323 options and generic options. Mode-specific options such as the
5324 aforementioned linking flags should be lumped with the other flags
5325 passed to the tool invoked by @command{libtool} (hence the use of
5326 @samp{@var{library}_LDFLAGS} for libtool linking flags). Generic
5327 options include @option{--tag=@var{tag}} and @option{--silent}
5328 (@pxref{Invoking libtool, , Invoking @command{libtool}, libtool, The
5329 Libtool Manual} for more options) should appear before the mode
5330 selection on the command line; in @file{Makefile.am}s they should
5331 be listed in the @samp{@var{library}_LIBTOOLFLAGS} variable.
5333 If @samp{@var{library}_LIBTOOLFLAGS} is not defined, then the variable
5334 @code{AM_LIBTOOLFLAGS} is used instead.
5336 These flags are passed to libtool after the @option{--tag=@var{tag}}
5337 option computed by Automake (if any), so
5338 @samp{@var{library}_LIBTOOLFLAGS} (or @code{AM_LIBTOOLFLAGS}) is a
5339 good place to override or supplement the @option{--tag=@var{tag}}
5342 The libtool rules also use a @code{LIBTOOLFLAGS} variable that should
5343 not be set in @file{Makefile.am}: this is a user variable (@pxref{Flag
5344 Variables Ordering}. It allows users to run @samp{make
5345 LIBTOOLFLAGS=--silent}, for instance. Note that the verbosity of
5346 @command{libtool} can also be influenced with the Automake
5347 @option{silent-rules} option (@pxref{Options}).
5350 @node LTLIBOBJS, Libtool Issues, Libtool Flags, A Shared Library
5351 @subsection @code{LTLIBOBJS} and @code{LTALLOCA}
5352 @cindex @code{LTLIBOBJS}, special handling
5353 @cindex @code{LIBOBJS}, and Libtool
5354 @cindex @code{LTALLOCA}, special handling
5355 @cindex @code{ALLOCA}, and Libtool
5362 Where an ordinary library might include @samp{$(LIBOBJS)} or
5363 @samp{$(ALLOCA)} (@pxref{LIBOBJS}), a libtool library must use
5364 @samp{$(LTLIBOBJS)} or @samp{$(LTALLOCA)}. This is required because
5365 the object files that libtool operates on do not necessarily end in
5368 Nowadays, the computation of @code{LTLIBOBJS} from @code{LIBOBJS} is
5369 performed automatically by Autoconf (@pxref{AC_LIBOBJ vs LIBOBJS, ,
5370 @code{AC_LIBOBJ} vs.@: @code{LIBOBJS}, autoconf, The Autoconf Manual}).
5372 @node Libtool Issues
5373 @subsection Common Issues Related to Libtool's Use
5376 * Error required file ltmain.sh not found:: The need to run libtoolize
5377 * Objects created both with libtool and without:: Avoid a specific build race
5380 @node Error required file ltmain.sh not found
5381 @subsubsection Error: @samp{required file `./ltmain.sh' not found}
5382 @cindex @file{ltmain.sh} not found
5383 @cindex @command{libtoolize}, no longer run by @command{automake}
5384 @cindex @command{libtoolize} and @command{autoreconf}
5385 @cindex @command{autoreconf} and @command{libtoolize}
5386 @cindex @file{bootstrap.sh} and @command{autoreconf}
5387 @cindex @file{autogen.sh} and @command{autoreconf}
5389 Libtool comes with a tool called @command{libtoolize} that will
5390 install libtool's supporting files into a package. Running this
5391 command will install @file{ltmain.sh}. You should execute it before
5392 @command{aclocal} and @command{automake}.
5394 People upgrading old packages to newer autotools are likely to face
5395 this issue because older Automake versions used to call
5396 @command{libtoolize}. Therefore old build scripts do not call
5397 @command{libtoolize}.
5399 Since Automake 1.6, it has been decided that running
5400 @command{libtoolize} was none of Automake's business. Instead, that
5401 functionality has been moved into the @command{autoreconf} command
5402 (@pxref{autoreconf Invocation, , Using @command{autoreconf}, autoconf,
5403 The Autoconf Manual}). If you do not want to remember what to run and
5404 when, just learn the @command{autoreconf} command. Hopefully,
5405 replacing existing @file{bootstrap.sh} or @file{autogen.sh} scripts by
5406 a call to @command{autoreconf} should also free you from any similar
5407 incompatible change in the future.
5409 @node Objects created both with libtool and without
5410 @subsubsection Objects @samp{created with both libtool and without}
5412 Sometimes, the same source file is used both to build a libtool
5413 library and to build another non-libtool target (be it a program or
5416 Let's consider the following @file{Makefile.am}.
5420 prog_SOURCES = prog.c foo.c @dots{}
5422 lib_LTLIBRARIES = libfoo.la
5423 libfoo_la_SOURCES = foo.c @dots{}
5427 (In this trivial case the issue could be avoided by linking
5428 @file{libfoo.la} with @file{prog} instead of listing @file{foo.c} in
5429 @code{prog_SOURCES}. But let's assume we really want to keep
5430 @file{prog} and @file{libfoo.la} separate.)
5432 Technically, it means that we should build @file{foo.$(OBJEXT)} for
5433 @file{prog}, and @file{foo.lo} for @file{libfoo.la}. The problem is
5434 that in the course of creating @file{foo.lo}, libtool may erase (or
5435 replace) @file{foo.$(OBJEXT)}, and this cannot be avoided.
5437 Therefore, when Automake detects this situation it will complain
5438 with a message such as
5440 object `foo.$(OBJEXT)' created both with libtool and without
5443 A workaround for this issue is to ensure that these two objects get
5444 different basenames. As explained in @ref{Renamed Objects}, this
5445 happens automatically when per-targets flags are used.
5449 prog_SOURCES = prog.c foo.c @dots{}
5450 prog_CFLAGS = $(AM_CFLAGS)
5452 lib_LTLIBRARIES = libfoo.la
5453 libfoo_la_SOURCES = foo.c @dots{}
5457 Adding @samp{prog_CFLAGS = $(AM_CFLAGS)} is almost a no-op, because
5458 when the @code{prog_CFLAGS} is defined, it is used instead of
5459 @code{AM_CFLAGS}. However as a side effect it will cause
5460 @file{prog.c} and @file{foo.c} to be compiled as
5461 @file{prog-prog.$(OBJEXT)} and @file{prog-foo.$(OBJEXT)}, which solves
5464 @node Program and Library Variables
5465 @section Program and Library Variables
5467 Associated with each program is a collection of variables that can be
5468 used to modify how that program is built. There is a similar list of
5469 such variables for each library. The canonical name of the program (or
5470 library) is used as a base for naming these variables.
5472 In the list below, we use the name ``maude'' to refer to the program or
5473 library. In your @file{Makefile.am} you would replace this with the
5474 canonical name of your program. This list also refers to ``maude'' as a
5475 program, but in general the same rules apply for both static and dynamic
5476 libraries; the documentation below notes situations where programs and
5481 This variable, if it exists, lists all the source files that are
5482 compiled to build the program. These files are added to the
5483 distribution by default. When building the program, Automake will cause
5484 each source file to be compiled to a single @file{.o} file (or
5485 @file{.lo} when using libtool). Normally these object files are named
5486 after the source file, but other factors can change this. If a file in
5487 the @code{_SOURCES} variable has an unrecognized extension, Automake
5488 will do one of two things with it. If a suffix rule exists for turning
5489 files with the unrecognized extension into @file{.o} files, then
5490 @command{automake} will treat this file as it will any other source file
5491 (@pxref{Support for Other Languages}). Otherwise, the file will be
5492 ignored as though it were a header file.
5494 The prefixes @code{dist_} and @code{nodist_} can be used to control
5495 whether files listed in a @code{_SOURCES} variable are distributed.
5496 @code{dist_} is redundant, as sources are distributed by default, but it
5497 can be specified for clarity if desired.
5499 It is possible to have both @code{dist_} and @code{nodist_} variants of
5500 a given @code{_SOURCES} variable at once; this lets you easily
5501 distribute some files and not others, for instance:
5504 nodist_maude_SOURCES = nodist.c
5505 dist_maude_SOURCES = dist-me.c
5508 By default the output file (on Unix systems, the @file{.o} file) will
5509 be put into the current build directory. However, if the option
5510 @option{subdir-objects} is in effect in the current directory then the
5511 @file{.o} file will be put into the subdirectory named after the
5512 source file. For instance, with @option{subdir-objects} enabled,
5513 @file{sub/dir/file.c} will be compiled to @file{sub/dir/file.o}. Some
5514 people prefer this mode of operation. You can specify
5515 @option{subdir-objects} in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
5516 @cindex Subdirectory, objects in
5517 @cindex Objects in subdirectory
5520 @item EXTRA_maude_SOURCES
5521 Automake needs to know the list of files you intend to compile
5522 @emph{statically}. For one thing, this is the only way Automake has of
5523 knowing what sort of language support a given @file{Makefile.in}
5524 requires. @footnote{There are other, more obscure reasons for
5525 this limitation as well.} This means that, for example, you can't put a
5526 configure substitution like @samp{@@my_sources@@} into a @samp{_SOURCES}
5527 variable. If you intend to conditionally compile source files and use
5528 @file{configure} to substitute the appropriate object names into, e.g.,
5529 @code{_LDADD} (see below), then you should list the corresponding source
5530 files in the @code{EXTRA_} variable.
5532 This variable also supports @code{dist_} and @code{nodist_} prefixes.
5533 For instance, @code{nodist_EXTRA_maude_SOURCES} would list extra
5534 sources that may need to be built, but should not be distributed.
5537 A static library is created by default by invoking @samp{$(AR)
5538 $(ARFLAGS)} followed by the name of the library and then the objects
5539 being put into the library. You can override this by setting the
5540 @code{_AR} variable. This is usually used with C++; some C++
5541 compilers require a special invocation in order to instantiate all the
5542 templates that should go into a library. For instance, the SGI C++
5543 compiler likes this variable set like so:
5545 libmaude_a_AR = $(CXX) -ar -o
5549 Extra objects can be added to a @emph{library} using the @code{_LIBADD}
5550 variable. For instance, this should be used for objects determined by
5551 @command{configure} (@pxref{A Library}).
5553 In the case of libtool libraries, @code{maude_LIBADD} can also refer
5554 to other libtool libraries.
5557 Extra objects (@file{*.$(OBJEXT)}) and libraries (@file{*.a},
5558 @file{*.la}) can be added to a @emph{program} by listing them in the
5559 @code{_LDADD} variable. For instance, this should be used for objects
5560 determined by @command{configure} (@pxref{Linking}).
5562 @code{_LDADD} and @code{_LIBADD} are inappropriate for passing
5563 program-specific linker flags (except for @option{-l}, @option{-L},
5564 @option{-dlopen} and @option{-dlpreopen}). Use the @code{_LDFLAGS} variable
5567 For instance, if your @file{configure.ac} uses @code{AC_PATH_XTRA}, you
5568 could link your program against the X libraries like so:
5571 maude_LDADD = $(X_PRE_LIBS) $(X_LIBS) $(X_EXTRA_LIBS)
5574 We recommend that you use @option{-l} and @option{-L} only when
5575 referring to third-party libraries, and give the explicit file names
5576 of any library built by your package. Doing so will ensure that
5577 @code{maude_DEPENDENCIES} (see below) is correctly defined by default.
5580 This variable is used to pass extra flags to the link step of a program
5581 or a shared library. It overrides the @code{AM_LDFLAGS} variable.
5583 @item maude_LIBTOOLFLAGS
5584 This variable is used to pass extra options to @command{libtool}.
5585 It overrides the @code{AM_LIBTOOLFLAGS} variable.
5586 These options are output before @command{libtool}'s @option{--mode=@var{mode}}
5587 option, so they should not be mode-specific options (those belong to
5588 the compiler or linker flags). @xref{Libtool Flags}.
5590 @item maude_DEPENDENCIES
5591 It is also occasionally useful to have a target (program or library)
5592 depend on some other file that is not actually part of that target.
5593 This can be done using the @code{_DEPENDENCIES} variable. Each
5594 target depends on the contents of such a variable, but no further
5595 interpretation is done.
5597 Since these dependencies are associated to the link rule used to
5598 create the programs they should normally list files used by the link
5599 command. That is @file{*.$(OBJEXT)}, @file{*.a}, or @file{*.la} files
5600 for programs; @file{*.lo} and @file{*.la} files for Libtool libraries;
5601 and @file{*.$(OBJEXT)} files for static libraries. In rare cases you
5602 may need to add other kinds of files such as linker scripts, but
5603 @emph{listing a source file in @code{_DEPENDENCIES} is wrong}. If
5604 some source file needs to be built before all the components of a
5605 program are built, consider using the @code{BUILT_SOURCES} variable
5608 If @code{_DEPENDENCIES} is not supplied, it is computed by Automake.
5609 The automatically-assigned value is the contents of @code{_LDADD} or
5610 @code{_LIBADD}, with most configure substitutions, @option{-l}, @option{-L},
5611 @option{-dlopen} and @option{-dlpreopen} options removed. The configure
5612 substitutions that are left in are only @samp{$(LIBOBJS)} and
5613 @samp{$(ALLOCA)}; these are left because it is known that they will not
5614 cause an invalid value for @code{_DEPENDENCIES} to be generated.
5616 @code{_DEPENDENCIES} is more likely used to perform conditional
5617 compilation using an @code{AC_SUBST} variable that contains a list of
5618 objects. @xref{Conditional Sources}, and @ref{Conditional Libtool
5622 You can override the linker on a per-program basis. By default the
5623 linker is chosen according to the languages used by the program. For
5624 instance, a program that includes C++ source code would use the C++
5625 compiler to link. The @code{_LINK} variable must hold the name of a
5626 command that can be passed all the @file{.o} file names and libraries
5627 to link against as arguments. Note that the name of the underlying
5628 program is @emph{not} passed to @code{_LINK}; typically one uses
5632 maude_LINK = $(CCLD) -magic -o $@@
5635 If a @code{_LINK} variable is not supplied, it may still be generated
5636 and used by Automake due to the use of per-target link flags such as
5637 @code{_CFLAGS}, @code{_LDFLAGS} or @code{_LIBTOOLFLAGS}, in cases where
5640 @item maude_CCASFLAGS
5642 @itemx maude_CPPFLAGS
5643 @itemx maude_CXXFLAGS
5645 @itemx maude_GCJFLAGS
5647 @itemx maude_OBJCFLAGS
5649 @itemx maude_UPCFLAGS
5651 @cindex per-target compilation flags, defined
5652 Automake allows you to set compilation flags on a per-program (or
5653 per-library) basis. A single source file can be included in several
5654 programs, and it will potentially be compiled with different flags for
5655 each program. This works for any language directly supported by
5656 Automake. These @dfn{per-target compilation flags} are
5666 @samp{_UPCFLAGS}, and
5669 When using a per-target compilation flag, Automake will choose a
5670 different name for the intermediate object files. Ordinarily a file
5671 like @file{sample.c} will be compiled to produce @file{sample.o}.
5672 However, if the program's @code{_CFLAGS} variable is set, then the
5673 object file will be named, for instance, @file{maude-sample.o}. (See
5674 also @ref{Renamed Objects}.) The use of per-target compilation flags
5675 with C sources requires that the macro @code{AM_PROG_CC_C_O} be called
5676 from @file{configure.ac}.
5678 In compilations with per-target flags, the ordinary @samp{AM_} form of
5679 the flags variable is @emph{not} automatically included in the
5680 compilation (however, the user form of the variable @emph{is} included).
5681 So for instance, if you want the hypothetical @file{maude} compilations
5682 to also use the value of @code{AM_CFLAGS}, you would need to write:
5685 maude_CFLAGS = @dots{} your flags @dots{} $(AM_CFLAGS)
5688 @xref{Flag Variables Ordering}, for more discussion about the
5689 interaction between user variables, @samp{AM_} shadow variables, and
5690 per-target variables.
5692 @item maude_SHORTNAME
5693 On some platforms the allowable file names are very short. In order to
5694 support these systems and per-target compilation flags at the same
5695 time, Automake allows you to set a ``short name'' that will influence
5696 how intermediate object files are named. For instance, in the following
5700 bin_PROGRAMS = maude
5701 maude_CPPFLAGS = -DSOMEFLAG
5703 maude_SOURCES = sample.c @dots{}
5707 the object file would be named @file{m-sample.o} rather than
5708 @file{maude-sample.o}.
5710 This facility is rarely needed in practice,
5711 and we recommend avoiding it until you find it is required.
5714 @node Default _SOURCES
5715 @section Default @code{_SOURCES}
5719 @cindex @code{_SOURCES}, default
5720 @cindex default @code{_SOURCES}
5721 @vindex AM_DEFAULT_SOURCE_EXT
5723 @code{_SOURCES} variables are used to specify source files of programs
5724 (@pxref{A Program}), libraries (@pxref{A Library}), and Libtool
5725 libraries (@pxref{A Shared Library}).
5727 When no such variable is specified for a target, Automake will define
5728 one itself. The default is to compile a single C file whose base name
5729 is the name of the target itself, with any extension replaced by
5730 @code{AM_DEFAULT_SOURCE_EXT}, which defaults to @file{.c}.
5732 For example if you have the following somewhere in your
5733 @file{Makefile.am} with no corresponding @code{libfoo_a_SOURCES}:
5736 lib_LIBRARIES = libfoo.a sub/libc++.a
5740 @file{libfoo.a} will be built using a default source file named
5741 @file{libfoo.c}, and @file{sub/libc++.a} will be built from
5742 @file{sub/libc++.c}. (In older versions @file{sub/libc++.a}
5743 would be built from @file{sub_libc___a.c}, i.e., the default source
5744 was the canonized name of the target, with @file{.c} appended.
5745 We believe the new behavior is more sensible, but for backward
5746 compatibility @command{automake} will use the old name if a file or a rule
5747 with that name exists and @code{AM_DEFAULT_SOURCE_EXT} is not used.)
5749 @cindex @code{check_PROGRAMS} example
5750 @vindex check_PROGRAMS
5751 Default sources are mainly useful in test suites, when building many
5752 test programs each from a single source. For instance, in
5755 check_PROGRAMS = test1 test2 test3
5756 AM_DEFAULT_SOURCE_EXT = .cpp
5760 @file{test1}, @file{test2}, and @file{test3} will be built
5761 from @file{test1.cpp}, @file{test2.cpp}, and @file{test3.cpp}.
5762 Without the last line, they will be built from @file{test1.c},
5763 @file{test2.c}, and @file{test3.c}.
5765 @cindex Libtool modules, default source example
5766 @cindex default source, Libtool modules example
5767 Another case where this is convenient is building many Libtool modules
5768 (@file{module@var{n}.la}), each defined in its own file
5769 (@file{module@var{n}.c}).
5772 AM_LDFLAGS = -module
5773 lib_LTLIBRARIES = module1.la module2.la module3.la
5776 @cindex empty @code{_SOURCES}
5777 @cindex @code{_SOURCES}, empty
5778 Finally, there is one situation where this default source computation
5779 needs to be avoided: when a target should not be built from sources.
5780 We already saw such an example in @ref{true}; this happens when all
5781 the constituents of a target have already been compiled and just need
5782 to be combined using a @code{_LDADD} variable. Then it is necessary
5783 to define an empty @code{_SOURCES} variable, so that @command{automake} does not
5787 bin_PROGRAMS = target
5789 target_LDADD = libmain.a libmisc.a
5793 @section Special handling for @code{LIBOBJS} and @code{ALLOCA}
5795 @cindex @code{LIBOBJS}, example
5796 @cindex @code{ALLOCA}, example
5797 @cindex @code{LIBOBJS}, special handling
5798 @cindex @code{ALLOCA}, special handling
5804 The @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} variables list object
5805 files that should be compiled into the project to provide an
5806 implementation for functions that are missing or broken on the host
5807 system. They are substituted by @file{configure}.
5811 These variables are defined by Autoconf macros such as
5812 @code{AC_LIBOBJ}, @code{AC_REPLACE_FUNCS} (@pxref{Generic Functions, ,
5813 Generic Function Checks, autoconf, The Autoconf Manual}), or
5814 @code{AC_FUNC_ALLOCA} (@pxref{Particular Functions, , Particular
5815 Function Checks, autoconf, The Autoconf Manual}). Many other Autoconf
5816 macros call @code{AC_LIBOBJ} or @code{AC_REPLACE_FUNCS} to
5817 populate @samp{$(LIBOBJS)}.
5819 @acindex AC_LIBSOURCE
5821 Using these variables is very similar to doing conditional compilation
5822 using @code{AC_SUBST} variables, as described in @ref{Conditional
5823 Sources}. That is, when building a program, @samp{$(LIBOBJS)} and
5824 @samp{$(ALLOCA)} should be added to the associated @samp{*_LDADD}
5825 variable, or to the @samp{*_LIBADD} variable when building a library.
5826 However there is no need to list the corresponding sources in
5827 @samp{EXTRA_*_SOURCES} nor to define @samp{*_DEPENDENCIES}. Automake
5828 automatically adds @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} to the
5829 dependencies, and it will discover the list of corresponding source
5830 files automatically (by tracing the invocations of the
5831 @code{AC_LIBSOURCE} Autoconf macros). However, if you have already
5832 defined @samp{*_DEPENDENCIES} explicitly for an unrelated reason, then
5833 you have to add these variables manually.
5835 These variables are usually used to build a portability library that
5836 is linked with all the programs of the project. We now review a
5837 sample setup. First, @file{configure.ac} contains some checks that
5838 affect either @code{LIBOBJS} or @code{ALLOCA}.
5843 AC_CONFIG_LIBOBJ_DIR([lib])
5845 AC_FUNC_MALLOC dnl May add malloc.$(OBJEXT) to LIBOBJS
5846 AC_FUNC_MEMCMP dnl May add memcmp.$(OBJEXT) to LIBOBJS
5847 AC_REPLACE_FUNCS([strdup]) dnl May add strdup.$(OBJEXT) to LIBOBJS
5848 AC_FUNC_ALLOCA dnl May add alloca.$(OBJEXT) to ALLOCA
5857 @acindex AC_CONFIG_LIBOBJ_DIR
5859 The @code{AC_CONFIG_LIBOBJ_DIR} tells Autoconf that the source files
5860 of these object files are to be found in the @file{lib/} directory.
5861 Automake can also use this information, otherwise it expects the
5862 source files are to be in the directory where the @samp{$(LIBOBJS)}
5863 and @samp{$(ALLOCA)} variables are used.
5865 The @file{lib/} directory should therefore contain @file{malloc.c},
5866 @file{memcmp.c}, @file{strdup.c}, @file{alloca.c}. Here is its
5872 noinst_LIBRARIES = libcompat.a
5873 libcompat_a_SOURCES =
5874 libcompat_a_LIBADD = $(LIBOBJS) $(ALLOCA)
5877 The library can have any name, of course, and anyway it is not going
5878 to be installed: it just holds the replacement versions of the missing
5879 or broken functions so we can later link them in. Many projects
5880 also include extra functions, specific to the project, in that
5881 library: they are simply added on the @code{_SOURCES} line.
5883 @cindex Empty libraries and @samp{$(LIBOBJS)}
5884 @cindex @samp{$(LIBOBJS)} and empty libraries
5885 There is a small trap here, though: @samp{$(LIBOBJS)} and
5886 @samp{$(ALLOCA)} might be empty, and building an empty library is not
5887 portable. You should ensure that there is always something to put in
5888 @file{libcompat.a}. Most projects will also add some utility
5889 functions in that directory, and list them in
5890 @code{libcompat_a_SOURCES}, so in practice @file{libcompat.a} cannot
5893 Finally here is how this library could be used from the @file{src/}
5899 # Link all programs in this directory with libcompat.a
5900 LDADD = ../lib/libcompat.a
5902 bin_PROGRAMS = tool1 tool2 @dots{}
5903 tool1_SOURCES = @dots{}
5904 tool2_SOURCES = @dots{}
5907 When option @option{subdir-objects} is not used, as in the above
5908 example, the variables @samp{$(LIBOBJS)} or @samp{$(ALLOCA)} can only
5909 be used in the directory where their sources lie. E.g., here it would
5910 be wrong to use @samp{$(LIBOBJS)} or @samp{$(ALLOCA)} in
5911 @file{src/Makefile.am}. However if both @option{subdir-objects} and
5912 @code{AC_CONFIG_LIBOBJ_DIR} are used, it is OK to use these variables
5913 in other directories. For instance @file{src/Makefile.am} could be
5919 AUTOMAKE_OPTIONS = subdir-objects
5920 LDADD = $(LIBOBJS) $(ALLOCA)
5922 bin_PROGRAMS = tool1 tool2 @dots{}
5923 tool1_SOURCES = @dots{}
5924 tool2_SOURCES = @dots{}
5927 Because @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} contain object
5928 file names that end with @samp{.$(OBJEXT)}, they are not suitable for
5929 Libtool libraries (where the expected object extension is @file{.lo}):
5930 @code{LTLIBOBJS} and @code{LTALLOCA} should be used instead.
5932 @code{LTLIBOBJS} is defined automatically by Autoconf and should not
5933 be defined by hand (as in the past), however at the time of writing
5934 @code{LTALLOCA} still needs to be defined from @code{ALLOCA} manually.
5935 @xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs.@: @code{LIBOBJS},
5936 autoconf, The Autoconf Manual}.
5939 @node Program Variables
5940 @section Variables used when building a program
5942 Occasionally it is useful to know which @file{Makefile} variables
5943 Automake uses for compilations, and in which order (@pxref{Flag
5944 Variables Ordering}); for instance, you might need to do your own
5945 compilation in some special cases.
5947 Some variables are inherited from Autoconf; these are @code{CC},
5948 @code{CFLAGS}, @code{CPPFLAGS}, @code{DEFS}, @code{LDFLAGS}, and
5957 There are some additional variables that Automake defines on its own:
5961 The contents of this variable are passed to every compilation that invokes
5962 the C preprocessor; it is a list of arguments to the preprocessor. For
5963 instance, @option{-I} and @option{-D} options should be listed here.
5965 Automake already provides some @option{-I} options automatically, in a
5966 separate variable that is also passed to every compilation that invokes
5967 the C preprocessor. In particular it generates @samp{-I.},
5968 @samp{-I$(srcdir)}, and a @option{-I} pointing to the directory holding
5969 @file{config.h} (if you've used @code{AC_CONFIG_HEADERS} or
5970 @code{AM_CONFIG_HEADER}). You can disable the default @option{-I}
5971 options using the @option{nostdinc} option.
5973 @code{AM_CPPFLAGS} is ignored in preference to a per-executable (or
5974 per-library) @code{_CPPFLAGS} variable if it is defined.
5977 This does the same job as @code{AM_CPPFLAGS} (or any per-target
5978 @code{_CPPFLAGS} variable if it is used). It is an older name for the
5979 same functionality. This variable is deprecated; we suggest using
5980 @code{AM_CPPFLAGS} and per-target @code{_CPPFLAGS} instead.
5983 This is the variable the @file{Makefile.am} author can use to pass
5984 in additional C compiler flags. It is more fully documented elsewhere.
5985 In some situations, this is not used, in preference to the
5986 per-executable (or per-library) @code{_CFLAGS}.
5989 This is the command used to actually compile a C source file. The
5990 file name is appended to form the complete command line.
5993 This is the variable the @file{Makefile.am} author can use to pass
5994 in additional linker flags. In some situations, this is not used, in
5995 preference to the per-executable (or per-library) @code{_LDFLAGS}.
5998 This is the command used to actually link a C program. It already
5999 includes @samp{-o $@@} and the usual variable references (for instance,
6000 @code{CFLAGS}); it takes as ``arguments'' the names of the object files
6001 and libraries to link in. This variable is not used when the linker is
6002 overridden with a per-target @code{_LINK} variable or per-target flags
6003 cause Automake to define such a @code{_LINK} variable.
6008 @section Yacc and Lex support
6010 Automake has somewhat idiosyncratic support for Yacc and Lex.
6012 Automake assumes that the @file{.c} file generated by @command{yacc}
6013 (or @command{lex}) should be named using the basename of the input
6014 file. That is, for a yacc source file @file{foo.y}, Automake will
6015 cause the intermediate file to be named @file{foo.c} (as opposed to
6016 @file{y.tab.c}, which is more traditional).
6018 The extension of a yacc source file is used to determine the extension
6019 of the resulting C or C++ file. Files with the extension @file{.y}
6020 will be turned into @file{.c} files; likewise, @file{.yy} will become
6021 @file{.cc}; @file{.y++}, @file{c++}; @file{.yxx}, @file{.cxx}; and
6022 @file{.ypp}, @file{.cpp}.
6024 Likewise, lex source files can be used to generate C or C++; the
6025 extensions @file{.l}, @file{.ll}, @file{.l++}, @file{.lxx}, and
6026 @file{.lpp} are recognized.
6028 You should never explicitly mention the intermediate (C or C++) file
6029 in any @code{SOURCES} variable; only list the source file.
6031 The intermediate files generated by @command{yacc} (or @command{lex})
6032 will be included in any distribution that is made. That way the user
6033 doesn't need to have @command{yacc} or @command{lex}.
6035 If a @command{yacc} source file is seen, then your @file{configure.ac} must
6036 define the variable @code{YACC}. This is most easily done by invoking
6037 the macro @code{AC_PROG_YACC} (@pxref{Particular Programs, , Particular
6038 Program Checks, autoconf, The Autoconf Manual}).
6042 When @code{yacc} is invoked, it is passed @code{AM_YFLAGS} and
6043 @code{YFLAGS}. The latter is a user variable and the former is
6044 intended for the @file{Makefile.am} author.
6046 @code{AM_YFLAGS} is usually used to pass the @option{-d} option to
6047 @command{yacc}. Automake knows what this means and will automatically
6048 adjust its rules to update and distribute the header file built by
6049 @samp{yacc -d}. What Automake cannot guess, though, is where this
6050 header will be used: it is up to you to ensure the header gets built
6051 before it is first used. Typically this is necessary in order for
6052 dependency tracking to work when the header is included by another
6053 file. The common solution is listing the header file in
6054 @code{BUILT_SOURCES} (@pxref{Sources}) as follows.
6057 BUILT_SOURCES = parser.h
6060 foo_SOURCES = @dots{} parser.y @dots{}
6063 If a @command{lex} source file is seen, then your @file{configure.ac}
6064 must define the variable @code{LEX}. You can use @code{AC_PROG_LEX}
6065 to do this (@pxref{Particular Programs, , Particular Program Checks,
6066 autoconf, The Autoconf Manual}), but using @code{AM_PROG_LEX} macro
6067 (@pxref{Macros}) is recommended.
6071 When @command{lex} is invoked, it is passed @code{AM_LFLAGS} and
6072 @code{LFLAGS}. The latter is a user variable and the former is
6073 intended for the @file{Makefile.am} author.
6075 When @code{AM_MAINTAINER_MODE} (@pxref{maintainer-mode}) is used, the
6076 rebuild rule for distributed Yacc and Lex sources are only used when
6077 @code{maintainer-mode} is enabled, or when the files have been erased.
6079 @cindex @command{ylwrap}
6080 @cindex @command{yacc}, multiple parsers
6081 @cindex Multiple @command{yacc} parsers
6082 @cindex Multiple @command{lex} lexers
6083 @cindex @command{lex}, multiple lexers
6085 When @command{lex} or @command{yacc} sources are used, @code{automake
6086 -i} automatically installs an auxiliary program called
6087 @command{ylwrap} in your package (@pxref{Auxiliary Programs}). This
6088 program is used by the build rules to rename the output of these
6089 tools, and makes it possible to include multiple @command{yacc} (or
6090 @command{lex}) source files in a single directory. (This is necessary
6091 because yacc's output file name is fixed, and a parallel make could
6092 conceivably invoke more than one instance of @command{yacc}
6095 For @command{yacc}, simply managing locking is insufficient. The output of
6096 @command{yacc} always uses the same symbol names internally, so it isn't
6097 possible to link two @command{yacc} parsers into the same executable.
6099 We recommend using the following renaming hack used in @command{gdb}:
6101 #define yymaxdepth c_maxdepth
6102 #define yyparse c_parse
6104 #define yyerror c_error
6105 #define yylval c_lval
6106 #define yychar c_char
6107 #define yydebug c_debug
6108 #define yypact c_pact
6115 #define yyexca c_exca
6116 #define yyerrflag c_errflag
6117 #define yynerrs c_nerrs
6121 #define yy_yys c_yys
6122 #define yystate c_state
6125 #define yy_yyv c_yyv
6127 #define yylloc c_lloc
6128 #define yyreds c_reds
6129 #define yytoks c_toks
6130 #define yylhs c_yylhs
6131 #define yylen c_yylen
6132 #define yydefred c_yydefred
6133 #define yydgoto c_yydgoto
6134 #define yysindex c_yysindex
6135 #define yyrindex c_yyrindex
6136 #define yygindex c_yygindex
6137 #define yytable c_yytable
6138 #define yycheck c_yycheck
6139 #define yyname c_yyname
6140 #define yyrule c_yyrule
6143 For each define, replace the @samp{c_} prefix with whatever you like.
6144 These defines work for @command{bison}, @command{byacc}, and
6145 traditional @code{yacc}s. If you find a parser generator that uses a
6146 symbol not covered here, please report the new name so it can be added
6151 @section C++ Support
6154 @cindex Support for C++
6156 Automake includes full support for C++.
6158 Any package including C++ code must define the output variable
6159 @code{CXX} in @file{configure.ac}; the simplest way to do this is to use
6160 the @code{AC_PROG_CXX} macro (@pxref{Particular Programs, , Particular
6161 Program Checks, autoconf, The Autoconf Manual}).
6163 A few additional variables are defined when a C++ source file is seen:
6167 The name of the C++ compiler.
6170 Any flags to pass to the C++ compiler.
6173 The maintainer's variant of @code{CXXFLAGS}.
6176 The command used to actually compile a C++ source file. The file name
6177 is appended to form the complete command line.
6180 The command used to actually link a C++ program.
6184 @node Objective C Support
6185 @section Objective C Support
6187 @cindex Objective C support
6188 @cindex Support for Objective C
6190 Automake includes some support for Objective C.
6192 Any package including Objective C code must define the output variable
6193 @code{OBJC} in @file{configure.ac}; the simplest way to do this is to use
6194 the @code{AC_PROG_OBJC} macro (@pxref{Particular Programs, , Particular
6195 Program Checks, autoconf, The Autoconf Manual}).
6197 A few additional variables are defined when an Objective C source file
6202 The name of the Objective C compiler.
6205 Any flags to pass to the Objective C compiler.
6208 The maintainer's variant of @code{OBJCFLAGS}.
6211 The command used to actually compile an Objective C source file. The
6212 file name is appended to form the complete command line.
6215 The command used to actually link an Objective C program.
6219 @node Unified Parallel C Support
6220 @section Unified Parallel C Support
6222 @cindex Unified Parallel C support
6223 @cindex Support for Unified Parallel C
6225 Automake includes some support for Unified Parallel C.
6227 Any package including Unified Parallel C code must define the output
6228 variable @code{UPC} in @file{configure.ac}; the simplest way to do
6229 this is to use the @code{AM_PROG_UPC} macro (@pxref{Public Macros}).
6231 A few additional variables are defined when a Unified Parallel C
6232 source file is seen:
6236 The name of the Unified Parallel C compiler.
6239 Any flags to pass to the Unified Parallel C compiler.
6242 The maintainer's variant of @code{UPCFLAGS}.
6245 The command used to actually compile a Unified Parallel C source file.
6246 The file name is appended to form the complete command line.
6249 The command used to actually link a Unified Parallel C program.
6253 @node Assembly Support
6254 @section Assembly Support
6256 Automake includes some support for assembly code. There are two forms
6257 of assembler files: normal (@file{*.s}) and preprocessed by @code{CPP}
6258 (@file{*.S} or @file{*.sx}).
6263 @vindex AM_CCASFLAGS
6265 The variable @code{CCAS} holds the name of the compiler used to build
6266 assembly code. This compiler must work a bit like a C compiler; in
6267 particular it must accept @option{-c} and @option{-o}. The values of
6268 @code{CCASFLAGS} and @code{AM_CCASFLAGS} (or its per-target
6269 definition) is passed to the compilation. For preprocessed files,
6270 @code{DEFS}, @code{DEFAULT_INCLUDES}, @code{INCLUDES}, @code{CPPFLAGS}
6271 and @code{AM_CPPFLAGS} are also used.
6273 The autoconf macro @code{AM_PROG_AS} will define @code{CCAS} and
6274 @code{CCASFLAGS} for you (unless they are already set, it simply sets
6275 @code{CCAS} to the C compiler and @code{CCASFLAGS} to the C compiler
6276 flags), but you are free to define these variables by other means.
6278 Only the suffixes @file{.s}, @file{.S}, and @file{.sx} are recognized by
6279 @command{automake} as being files containing assembly code.
6282 @node Fortran 77 Support
6283 @comment node-name, next, previous, up
6284 @section Fortran 77 Support
6286 @cindex Fortran 77 support
6287 @cindex Support for Fortran 77
6289 Automake includes full support for Fortran 77.
6291 Any package including Fortran 77 code must define the output variable
6292 @code{F77} in @file{configure.ac}; the simplest way to do this is to use
6293 the @code{AC_PROG_F77} macro (@pxref{Particular Programs, , Particular
6294 Program Checks, autoconf, The Autoconf Manual}).
6296 A few additional variables are defined when a Fortran 77 source file is
6302 The name of the Fortran 77 compiler.
6305 Any flags to pass to the Fortran 77 compiler.
6308 The maintainer's variant of @code{FFLAGS}.
6311 Any flags to pass to the Ratfor compiler.
6314 The maintainer's variant of @code{RFLAGS}.
6317 The command used to actually compile a Fortran 77 source file. The file
6318 name is appended to form the complete command line.
6321 The command used to actually link a pure Fortran 77 program or shared
6326 Automake can handle preprocessing Fortran 77 and Ratfor source files in
6327 addition to compiling them@footnote{Much, if not most, of the
6328 information in the following sections pertaining to preprocessing
6329 Fortran 77 programs was taken almost verbatim from @ref{Catalogue of
6330 Rules, , Catalogue of Rules, make, The GNU Make Manual}.}. Automake
6331 also contains some support for creating programs and shared libraries
6332 that are a mixture of Fortran 77 and other languages (@pxref{Mixing
6333 Fortran 77 With C and C++}).
6335 These issues are covered in the following sections.
6338 * Preprocessing Fortran 77:: Preprocessing Fortran 77 sources
6339 * Compiling Fortran 77 Files:: Compiling Fortran 77 sources
6340 * Mixing Fortran 77 With C and C++:: Mixing Fortran 77 With C and C++
6344 @node Preprocessing Fortran 77
6345 @comment node-name, next, previous, up
6346 @subsection Preprocessing Fortran 77
6348 @cindex Preprocessing Fortran 77
6349 @cindex Fortran 77, Preprocessing
6350 @cindex Ratfor programs
6352 @file{N.f} is made automatically from @file{N.F} or @file{N.r}. This
6353 rule runs just the preprocessor to convert a preprocessable Fortran 77
6354 or Ratfor source file into a strict Fortran 77 source file. The precise
6355 command used is as follows:
6360 @code{$(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)@*
6361 $(AM_FFLAGS) $(FFLAGS)}
6364 @code{$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
6369 @node Compiling Fortran 77 Files
6370 @comment node-name, next, previous, up
6371 @subsection Compiling Fortran 77 Files
6373 @file{N.o} is made automatically from @file{N.f}, @file{N.F} or
6374 @file{N.r} by running the Fortran 77 compiler. The precise command used
6380 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS)}
6383 @code{$(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)@*
6384 $(AM_FFLAGS) $(FFLAGS)}
6387 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
6392 @node Mixing Fortran 77 With C and C++
6393 @comment node-name, next, previous, up
6394 @subsection Mixing Fortran 77 With C and C++
6396 @cindex Fortran 77, mixing with C and C++
6397 @cindex Mixing Fortran 77 with C and C++
6398 @cindex Linking Fortran 77 with C and C++
6400 @cindex Mixing Fortran 77 with C and/or C++
6402 Automake currently provides @emph{limited} support for creating programs
6403 and shared libraries that are a mixture of Fortran 77 and C and/or C++.
6404 However, there are many other issues related to mixing Fortran 77 with
6405 other languages that are @emph{not} (currently) handled by Automake, but
6406 that are handled by other packages@footnote{For example,
6407 @uref{http://www-zeus.desy.de/~burow/cfortran/, the cfortran package}
6408 addresses all of these inter-language issues, and runs under nearly all
6409 Fortran 77, C and C++ compilers on nearly all platforms. However,
6410 @command{cfortran} is not yet Free Software, but it will be in the next
6413 Automake can help in two ways:
6417 Automatic selection of the linker depending on which combinations of
6421 Automatic selection of the appropriate linker flags (e.g., @option{-L} and
6422 @option{-l}) to pass to the automatically selected linker in order to link
6423 in the appropriate Fortran 77 intrinsic and run-time libraries.
6425 @cindex @code{FLIBS}, defined
6427 These extra Fortran 77 linker flags are supplied in the output variable
6428 @code{FLIBS} by the @code{AC_F77_LIBRARY_LDFLAGS} Autoconf macro
6429 supplied with newer versions of Autoconf (Autoconf version 2.13 and
6430 later). @xref{Fortran Compiler, , Fortran Compiler Characteristics,
6431 autoconf, The Autoconf Manual}.
6434 If Automake detects that a program or shared library (as mentioned in
6435 some @code{_PROGRAMS} or @code{_LTLIBRARIES} primary) contains source
6436 code that is a mixture of Fortran 77 and C and/or C++, then it requires
6437 that the macro @code{AC_F77_LIBRARY_LDFLAGS} be called in
6438 @file{configure.ac}, and that either @code{$(FLIBS)}
6439 appear in the appropriate @code{_LDADD} (for programs) or @code{_LIBADD}
6440 (for shared libraries) variables. It is the responsibility of the
6441 person writing the @file{Makefile.am} to make sure that @samp{$(FLIBS)}
6442 appears in the appropriate @code{_LDADD} or
6443 @code{_LIBADD} variable.
6445 @cindex Mixed language example
6446 @cindex Example, mixed language
6448 For example, consider the following @file{Makefile.am}:
6452 foo_SOURCES = main.cc foo.f
6453 foo_LDADD = libfoo.la $(FLIBS)
6455 pkglib_LTLIBRARIES = libfoo.la
6456 libfoo_la_SOURCES = bar.f baz.c zardoz.cc
6457 libfoo_la_LIBADD = $(FLIBS)
6460 In this case, Automake will insist that @code{AC_F77_LIBRARY_LDFLAGS}
6461 is mentioned in @file{configure.ac}. Also, if @samp{$(FLIBS)} hadn't
6462 been mentioned in @code{foo_LDADD} and @code{libfoo_la_LIBADD}, then
6463 Automake would have issued a warning.
6466 * How the Linker is Chosen:: Automatic linker selection
6469 @node How the Linker is Chosen
6470 @comment node-name, next, previous, up
6471 @subsubsection How the Linker is Chosen
6473 @cindex Automatic linker selection
6474 @cindex Selecting the linker automatically
6476 When a program or library mixes several languages, Automake choose the
6477 linker according to the following priorities. (The names in
6478 parentheses are the variables containing the link command.)
6483 Native Java (@code{GCJLINK})
6486 C++ (@code{CXXLINK})
6489 Fortran 77 (@code{F77LINK})
6492 Fortran (@code{FCLINK})
6495 Objective C (@code{OBJCLINK})
6498 Unified Parallel C (@code{UPCLINK})
6504 For example, if Fortran 77, C and C++ source code is compiled
6505 into a program, then the C++ linker will be used. In this case, if the
6506 C or Fortran 77 linkers required any special libraries that weren't
6507 included by the C++ linker, then they must be manually added to an
6508 @code{_LDADD} or @code{_LIBADD} variable by the user writing the
6511 Automake only looks at the file names listed in @file{_SOURCES}
6512 variables to choose the linker, and defaults to the C linker.
6513 Sometimes this is inconvenient because you are linking against a
6514 library written in another language and would like to set the linker
6515 more appropriately. @xref{Libtool Convenience Libraries}, for a
6516 trick with @code{nodist_EXTRA_@dots{}_SOURCES}.
6518 A per-target @code{_LINK} variable will override the above selection.
6519 Per-target link flags will cause Automake to write a per-target
6520 @code{_LINK} variable according to the language chosen as above.
6523 @node Fortran 9x Support
6524 @comment node-name, next, previous, up
6525 @section Fortran 9x Support
6527 @cindex Fortran 9x support
6528 @cindex Support for Fortran 9x
6530 Automake includes support for Fortran 9x.
6532 Any package including Fortran 9x code must define the output variable
6533 @code{FC} in @file{configure.ac}; the simplest way to do this is to use
6534 the @code{AC_PROG_FC} macro (@pxref{Particular Programs, , Particular
6535 Program Checks, autoconf, The Autoconf Manual}).
6537 A few additional variables are defined when a Fortran 9x source file is
6543 The name of the Fortran 9x compiler.
6546 Any flags to pass to the Fortran 9x compiler.
6549 The maintainer's variant of @code{FCFLAGS}.
6552 The command used to actually compile a Fortran 9x source file. The file
6553 name is appended to form the complete command line.
6556 The command used to actually link a pure Fortran 9x program or shared
6562 * Compiling Fortran 9x Files:: Compiling Fortran 9x sources
6565 @node Compiling Fortran 9x Files
6566 @comment node-name, next, previous, up
6567 @subsection Compiling Fortran 9x Files
6569 @file{@var{file}.o} is made automatically from @file{@var{file}.f90},
6570 @file{@var{file}.f95}, @file{@var{file}.f03}, or @file{@var{file}.f08}
6571 by running the Fortran 9x compiler. The precise command used
6577 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f90) $<}
6580 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f95) $<}
6583 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f03) $<}
6586 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f08) $<}
6591 @comment node-name, next, previous, up
6592 @section Java Support
6594 @cindex Java support
6595 @cindex Support for Java
6597 Automake includes support for compiled Java, using @command{gcj}, the Java
6598 front end to the GNU Compiler Collection.
6600 Any package including Java code to be compiled must define the output
6601 variable @code{GCJ} in @file{configure.ac}; the variable @code{GCJFLAGS}
6602 must also be defined somehow (either in @file{configure.ac} or
6603 @file{Makefile.am}). The simplest way to do this is to use the
6604 @code{AM_PROG_GCJ} macro.
6608 By default, programs including Java source files are linked with
6611 As always, the contents of @code{AM_GCJFLAGS} are passed to every
6612 compilation invoking @command{gcj} (in its role as an ahead-of-time
6613 compiler, when invoking it to create @file{.class} files,
6614 @code{AM_JAVACFLAGS} is used instead). If it is necessary to pass
6615 options to @command{gcj} from @file{Makefile.am}, this variable, and not
6616 the user variable @code{GCJFLAGS}, should be used.
6620 @command{gcj} can be used to compile @file{.java}, @file{.class},
6621 @file{.zip}, or @file{.jar} files.
6623 When linking, @command{gcj} requires that the main class be specified
6624 using the @option{--main=} option. The easiest way to do this is to use
6625 the @code{_LDFLAGS} variable for the program.
6629 @comment node-name, next, previous, up
6630 @section Vala Support
6632 @cindex Vala Support
6633 @cindex Support for Vala
6635 Automake provides initial support for Vala
6636 (@uref{http://www.vala-project.org/}).
6637 This requires valac version 0.7.0 or later, and currently requires
6638 the user to use GNU @command{make}.
6641 foo_SOURCES = foo.vala bar.vala zardoc.c
6644 Any @file{.vala} file listed in a @code{_SOURCES} variable will be
6645 compiled into C code by the Vala compiler. The generated @file{.c} files are
6646 distributed. The end user does not need to have a Vala compiler installed.
6648 Automake ships with an Autoconf macro called @code{AM_PROG_VALAC}
6649 that will locate the Vala compiler and optionally check its version
6652 @defmac AM_PROG_VALAC (@ovar{minimum-version})
6653 Try to find a Vala compiler in @env{PATH}. If it is found, the variable
6654 @code{VALAC} is set. Optionally a minimum release number of the compiler
6658 AM_PROG_VALAC([0.7.0])
6662 There are a few variables that are used when compiling Vala sources:
6666 Path to the Vala compiler.
6669 Additional arguments for the Vala compiler.
6672 The maintainer's variant of @code{VALAFLAGS}.
6675 lib_LTLIBRARIES = libfoo.la
6676 libfoo_la_SOURCES = foo.vala
6680 Note that currently, you cannot use per-target @code{*_VALAFLAGS}
6681 (@pxref{Renamed Objects}) to produce different C files from one Vala
6685 @node Support for Other Languages
6686 @comment node-name, next, previous, up
6687 @section Support for Other Languages
6689 Automake currently only includes full support for C, C++ (@pxref{C++
6690 Support}), Objective C (@pxref{Objective C Support}), Fortran 77
6691 (@pxref{Fortran 77 Support}), Fortran 9x (@pxref{Fortran 9x Support}),
6692 and Java (@pxref{Java Support}). There is only rudimentary support for other
6693 languages, support for which will be improved based on user demand.
6695 Some limited support for adding your own languages is available via the
6696 suffix rule handling (@pxref{Suffixes}).
6700 @section Automatic de-ANSI-fication
6702 @cindex de-ANSI-fication, defined
6704 The features described in this section are obsolete; you should not
6705 used any of them in new code, and they may be withdrawn in future
6708 When the C language was standardized in 1989, there was a long
6709 transition period where package developers needed to worry about
6710 porting to older systems that did not support ANSI C by default.
6711 These older systems are no longer in practical use and are no longer
6712 supported by their original suppliers, so developers need not worry
6713 about this problem any more.
6715 Automake allows you to write packages that are portable to K&R C by
6716 @dfn{de-ANSI-fying} each source file before the actual compilation takes
6719 @vindex AUTOMAKE_OPTIONS
6722 If the @file{Makefile.am} variable @code{AUTOMAKE_OPTIONS}
6723 (@pxref{Options}) contains the option @option{ansi2knr} then code to
6724 handle de-ANSI-fication is inserted into the generated
6727 This causes each C source file in the directory to be treated as ANSI C@.
6728 If an ANSI C compiler is available, it is used. If no ANSI C compiler
6729 is available, the @command{ansi2knr} program is used to convert the source
6730 files into K&R C, which is then compiled.
6732 The @command{ansi2knr} program is simple-minded. It assumes the source
6733 code will be formatted in a particular way; see the @command{ansi2knr} man
6736 @acindex AM_C_PROTOTYPES
6737 Support for the obsolete de-ANSI-fication feature
6738 requires the source files @file{ansi2knr.c}
6739 and @file{ansi2knr.1} to be in the same package as the ANSI C source;
6740 these files are distributed with Automake. Also, the package
6741 @file{configure.ac} must call the macro @code{AM_C_PROTOTYPES}
6744 Automake also handles finding the @command{ansi2knr} support files in some
6745 other directory in the current package. This is done by prepending the
6746 relative path to the appropriate directory to the @command{ansi2knr}
6747 option. For instance, suppose the package has ANSI C code in the
6748 @file{src} and @file{lib} subdirectories. The files @file{ansi2knr.c} and
6749 @file{ansi2knr.1} appear in @file{lib}. Then this could appear in
6750 @file{src/Makefile.am}:
6753 AUTOMAKE_OPTIONS = ../lib/ansi2knr
6756 If no directory prefix is given, the files are assumed to be in the
6759 Note that automatic de-ANSI-fication will not work when the package is
6760 being built for a different host architecture. That is because @command{automake}
6761 currently has no way to build @command{ansi2knr} for the build machine.
6763 @c FIXME: this paragraph might be better moved to an `upgrading' section.
6764 @cindex @code{LTLIBOBJS} and @code{ansi2knr}
6765 @cindex @code{LIBOBJS} and @code{ansi2knr}
6766 @cindex @code{ansi2knr} and @code{LTLIBOBJS}
6767 @cindex @code{ansi2knr} and @code{LIBOBJS}
6768 Using @code{LIBOBJS} with source de-ANSI-fication used to require
6769 hand-crafted code in @file{configure} to append @samp{$U} to basenames
6770 in @code{LIBOBJS}. This is no longer true today. Starting with version
6771 2.54, Autoconf takes care of rewriting @code{LIBOBJS} and
6772 @code{LTLIBOBJS}. (@pxref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ}
6773 vs.@: @code{LIBOBJS}, autoconf, The Autoconf Manual})
6776 @section Automatic dependency tracking
6778 As a developer it is often painful to continually update the
6779 @file{Makefile.in} whenever the include-file dependencies change in a
6780 project. Automake supplies a way to automatically track dependency
6781 changes (@pxref{Dependency Tracking}).
6783 @cindex Dependency tracking
6784 @cindex Automatic dependency tracking
6786 Automake always uses complete dependencies for a compilation,
6787 including system headers. Automake's model is that dependency
6788 computation should be a side effect of the build. To this end,
6789 dependencies are computed by running all compilations through a
6790 special wrapper program called @command{depcomp}. @command{depcomp}
6791 understands how to coax many different C and C++ compilers into
6792 generating dependency information in the format it requires.
6793 @samp{automake -a} will install @command{depcomp} into your source
6794 tree for you. If @command{depcomp} can't figure out how to properly
6795 invoke your compiler, dependency tracking will simply be disabled for
6798 @cindex @command{depcomp}
6800 Experience with earlier versions of Automake (@pxref{Dependency
6801 Tracking Evolution}) taught us that it is not reliable to generate
6802 dependencies only on the maintainer's system, as configurations vary
6803 too much. So instead Automake implements dependency tracking at build
6806 Automatic dependency tracking can be suppressed by putting
6807 @option{no-dependencies} in the variable @code{AUTOMAKE_OPTIONS}, or
6808 passing @option{no-dependencies} as an argument to @code{AM_INIT_AUTOMAKE}
6809 (this should be the preferred way). Or, you can invoke @command{automake}
6810 with the @option{-i} option. Dependency tracking is enabled by default.
6812 @vindex AUTOMAKE_OPTIONS
6813 @opindex no-dependencies
6815 The person building your package also can choose to disable dependency
6816 tracking by configuring with @option{--disable-dependency-tracking}.
6818 @cindex Disabling dependency tracking
6819 @cindex Dependency tracking, disabling
6823 @section Support for executable extensions
6825 @cindex Executable extension
6826 @cindex Extension, executable
6829 On some platforms, such as Windows, executables are expected to have an
6830 extension such as @file{.exe}. On these platforms, some compilers (GCC
6831 among them) will automatically generate @file{foo.exe} when asked to
6832 generate @file{foo}.
6834 Automake provides mostly-transparent support for this. Unfortunately
6835 @emph{mostly} doesn't yet mean @emph{fully}. Until the English
6836 dictionary is revised, you will have to assist Automake if your package
6837 must support those platforms.
6839 One thing you must be aware of is that, internally, Automake rewrites
6840 something like this:
6843 bin_PROGRAMS = liver
6849 bin_PROGRAMS = liver$(EXEEXT)
6852 The targets Automake generates are likewise given the @samp{$(EXEEXT)}
6855 The variables @code{TESTS} and @code{XFAIL_TESTS} (@pxref{Simple Tests}) are also
6856 rewritten if they contain filenames that have been declared as programs
6857 in the same @file{Makefile}. (This is mostly useful when some programs
6858 from @code{check_PROGRAMS} are listed in @code{TESTS}.)
6860 However, Automake cannot apply this rewriting to @command{configure}
6861 substitutions. This means that if you are conditionally building a
6862 program using such a substitution, then your @file{configure.ac} must
6863 take care to add @samp{$(EXEEXT)} when constructing the output variable.
6865 With Autoconf 2.13 and earlier, you must explicitly use @code{AC_EXEEXT}
6866 to get this support. With Autoconf 2.50, @code{AC_EXEEXT} is run
6867 automatically if you configure a compiler (say, through
6870 Sometimes maintainers like to write an explicit link rule for their
6871 program. Without executable extension support, this is easy---you
6872 simply write a rule whose target is the name of the program. However,
6873 when executable extension support is enabled, you must instead add the
6874 @samp{$(EXEEXT)} suffix.
6876 Unfortunately, due to the change in Autoconf 2.50, this means you must
6877 always add this extension. However, this is a problem for maintainers
6878 who know their package will never run on a platform that has
6879 executable extensions. For those maintainers, the @option{no-exeext}
6880 option (@pxref{Options}) will disable this feature. This works in a
6881 fairly ugly way; if @option{no-exeext} is seen, then the presence of a
6882 rule for a target named @code{foo} in @file{Makefile.am} will override
6883 an @command{automake}-generated rule for @samp{foo$(EXEEXT)}. Without
6884 the @option{no-exeext} option, this use will give a diagnostic.
6888 @chapter Other Derived Objects
6890 Automake can handle derived objects that are not C programs. Sometimes
6891 the support for actually building such objects must be explicitly
6892 supplied, but Automake will still automatically handle installation and
6896 * Scripts:: Executable scripts
6897 * Headers:: Header files
6898 * Data:: Architecture-independent data files
6899 * Sources:: Derived sources
6904 @section Executable Scripts
6906 @cindex @code{_SCRIPTS} primary, defined
6907 @cindex @code{SCRIPTS} primary, defined
6908 @cindex Primary variable, @code{SCRIPTS}
6910 @cindex Installing scripts
6912 It is possible to define and install programs that are scripts. Such
6913 programs are listed using the @code{SCRIPTS} primary name. When the
6914 script is distributed in its final, installable form, the
6915 @file{Makefile} usually looks as follows:
6919 # Install my_script in $(bindir) and distribute it.
6920 dist_bin_SCRIPTS = my_script
6923 Scripts are not distributed by default; as we have just seen, those
6924 that should be distributed can be specified using a @code{dist_}
6925 prefix as with other primaries.
6927 @cindex @code{SCRIPTS}, installation directories
6929 @vindex sbin_SCRIPTS
6930 @vindex libexec_SCRIPTS
6931 @vindex pkgdata_SCRIPTS
6932 @vindex noinst_SCRIPTS
6933 @vindex check_SCRIPTS
6935 Scripts can be installed in @code{bindir}, @code{sbindir},
6936 @code{libexecdir}, or @code{pkgdatadir}.
6938 Scripts that need not be installed can be listed in
6939 @code{noinst_SCRIPTS}, and among them, those which are needed only by
6940 @samp{make check} should go in @code{check_SCRIPTS}.
6942 When a script needs to be built, the @file{Makefile.am} should include
6943 the appropriate rules. For instance the @command{automake} program
6944 itself is a Perl script that is generated from @file{automake.in}.
6945 Here is how this is handled:
6948 bin_SCRIPTS = automake
6949 CLEANFILES = $(bin_SCRIPTS)
6950 EXTRA_DIST = automake.in
6952 do_subst = sed -e 's,[@@]datadir[@@],$(datadir),g' \
6953 -e 's,[@@]PERL[@@],$(PERL),g' \
6954 -e 's,[@@]PACKAGE[@@],$(PACKAGE),g' \
6955 -e 's,[@@]VERSION[@@],$(VERSION),g' \
6958 automake: automake.in Makefile
6959 $(do_subst) < $(srcdir)/automake.in > automake
6963 Such scripts for which a build rule has been supplied need to be
6964 deleted explicitly using @code{CLEANFILES} (@pxref{Clean}), and their
6965 sources have to be distributed, usually with @code{EXTRA_DIST}
6966 (@pxref{Basics of Distribution}).
6968 Another common way to build scripts is to process them from
6969 @file{configure} with @code{AC_CONFIG_FILES}. In this situation
6970 Automake knows which files should be cleaned and distributed, and what
6971 the rebuild rules should look like.
6973 For instance if @file{configure.ac} contains
6976 AC_CONFIG_FILES([src/my_script], [chmod +x src/my_script])
6980 to build @file{src/my_script} from @file{src/my_script.in}, then a
6981 @file{src/Makefile.am} to install this script in @code{$(bindir)} can
6985 bin_SCRIPTS = my_script
6986 CLEANFILES = $(bin_SCRIPTS)
6990 There is no need for @code{EXTRA_DIST} or any build rule: Automake
6991 infers them from @code{AC_CONFIG_FILES} (@pxref{Requirements}).
6992 @code{CLEANFILES} is still useful, because by default Automake will
6993 clean targets of @code{AC_CONFIG_FILES} in @code{distclean}, not
6996 Although this looks simpler, building scripts this way has one
6997 drawback: directory variables such as @code{$(datadir)} are not fully
6998 expanded and may refer to other directory variables.
7001 @section Header files
7003 @cindex @code{_HEADERS} primary, defined
7004 @cindex @code{HEADERS} primary, defined
7005 @cindex Primary variable, @code{HEADERS}
7007 @vindex noinst_HEADERS
7008 @cindex @code{HEADERS}, installation directories
7009 @cindex Installing headers
7010 @vindex include_HEADERS
7011 @vindex oldinclude_HEADERS
7012 @vindex pkginclude_HEADERS
7015 Header files that must be installed are specified by the
7016 @code{HEADERS} family of variables. Headers can be installed in
7017 @code{includedir}, @code{oldincludedir}, @code{pkgincludedir} or any
7018 other directory you may have defined (@pxref{Uniform}). For instance,
7021 include_HEADERS = foo.h bar/bar.h
7025 will install the two files as @file{$(includedir)/foo.h} and
7026 @file{$(includedir)/bar.h}.
7028 The @code{nobase_} prefix is also supported,
7031 nobase_include_HEADERS = foo.h bar/bar.h
7035 will install the two files as @file{$(includedir)/foo.h} and
7036 @file{$(includedir)/bar/bar.h} (@pxref{Alternative}).
7038 @vindex noinst_HEADERS
7039 Usually, only header files that accompany installed libraries need to
7040 be installed. Headers used by programs or convenience libraries are
7041 not installed. The @code{noinst_HEADERS} variable can be used for
7042 such headers. However when the header actually belongs to a single
7043 convenience library or program, we recommend listing it in the
7044 program's or library's @code{_SOURCES} variable (@pxref{Program
7045 Sources}) instead of in @code{noinst_HEADERS}. This is clearer for
7046 the @file{Makefile.am} reader. @code{noinst_HEADERS} would be the
7047 right variable to use in a directory containing only headers and no
7048 associated library or program.
7050 All header files must be listed somewhere; in a @code{_SOURCES}
7051 variable or in a @code{_HEADERS} variable. Missing ones will not
7052 appear in the distribution.
7054 For header files that are built and must not be distributed, use the
7055 @code{nodist_} prefix as in @code{nodist_include_HEADERS} or
7056 @code{nodist_prog_SOURCES}. If these generated headers are needed
7057 during the build, you must also ensure they exist before they are
7058 used (@pxref{Sources}).
7062 @section Architecture-independent data files
7064 @cindex @code{_DATA} primary, defined
7065 @cindex @code{DATA} primary, defined
7066 @cindex Primary variable, @code{DATA}
7069 Automake supports the installation of miscellaneous data files using the
7070 @code{DATA} family of variables.
7074 @vindex sysconf_DATA
7075 @vindex sharedstate_DATA
7076 @vindex localstate_DATA
7077 @vindex pkgdata_DATA
7079 Such data can be installed in the directories @code{datadir},
7080 @code{sysconfdir}, @code{sharedstatedir}, @code{localstatedir}, or
7083 By default, data files are @emph{not} included in a distribution. Of
7084 course, you can use the @code{dist_} prefix to change this on a
7087 Here is how Automake declares its auxiliary data files:
7090 dist_pkgdata_DATA = clean-kr.am clean.am @dots{}
7095 @section Built Sources
7097 Because Automake's automatic dependency tracking works as a side-effect
7098 of compilation (@pxref{Dependencies}) there is a bootstrap issue: a
7099 target should not be compiled before its dependencies are made, but
7100 these dependencies are unknown until the target is first compiled.
7102 Ordinarily this is not a problem, because dependencies are distributed
7103 sources: they preexist and do not need to be built. Suppose that
7104 @file{foo.c} includes @file{foo.h}. When it first compiles
7105 @file{foo.o}, @command{make} only knows that @file{foo.o} depends on
7106 @file{foo.c}. As a side-effect of this compilation @command{depcomp}
7107 records the @file{foo.h} dependency so that following invocations of
7108 @command{make} will honor it. In these conditions, it's clear there is
7109 no problem: either @file{foo.o} doesn't exist and has to be built
7110 (regardless of the dependencies), or accurate dependencies exist and
7111 they can be used to decide whether @file{foo.o} should be rebuilt.
7113 It's a different story if @file{foo.h} doesn't exist by the first
7114 @command{make} run. For instance, there might be a rule to build
7115 @file{foo.h}. This time @file{file.o}'s build will fail because the
7116 compiler can't find @file{foo.h}. @command{make} failed to trigger the
7117 rule to build @file{foo.h} first by lack of dependency information.
7119 @vindex BUILT_SOURCES
7120 @cindex @code{BUILT_SOURCES}, defined
7122 The @code{BUILT_SOURCES} variable is a workaround for this problem. A
7123 source file listed in @code{BUILT_SOURCES} is made on @samp{make all}
7124 or @samp{make check} (or even @samp{make install}) before other
7125 targets are processed. However, such a source file is not
7126 @emph{compiled} unless explicitly requested by mentioning it in some
7127 other @code{_SOURCES} variable.
7129 So, to conclude our introductory example, we could use
7130 @samp{BUILT_SOURCES = foo.h} to ensure @file{foo.h} gets built before
7131 any other target (including @file{foo.o}) during @samp{make all} or
7134 @code{BUILT_SOURCES} is actually a bit of a misnomer, as any file which
7135 must be created early in the build process can be listed in this
7136 variable. Moreover, all built sources do not necessarily have to be
7137 listed in @code{BUILT_SOURCES}. For instance, a generated @file{.c} file
7138 doesn't need to appear in @code{BUILT_SOURCES} (unless it is included by
7139 another source), because it's a known dependency of the associated
7142 It might be important to emphasize that @code{BUILT_SOURCES} is
7143 honored only by @samp{make all}, @samp{make check} and @samp{make
7144 install}. This means you cannot build a specific target (e.g.,
7145 @samp{make foo}) in a clean tree if it depends on a built source.
7146 However it will succeed if you have run @samp{make all} earlier,
7147 because accurate dependencies are already available.
7149 The next section illustrates and discusses the handling of built sources
7153 * Built Sources Example:: Several ways to handle built sources.
7156 @node Built Sources Example
7157 @subsection Built Sources Example
7159 Suppose that @file{foo.c} includes @file{bindir.h}, which is
7160 installation-dependent and not distributed: it needs to be built. Here
7161 @file{bindir.h} defines the preprocessor macro @code{bindir} to the
7162 value of the @command{make} variable @code{bindir} (inherited from
7165 We suggest several implementations below. It's not meant to be an
7166 exhaustive listing of all ways to handle built sources, but it will give
7167 you a few ideas if you encounter this issue.
7169 @subsubheading First Try
7171 This first implementation will illustrate the bootstrap issue mentioned
7172 in the previous section (@pxref{Sources}).
7174 Here is a tentative @file{Makefile.am}.
7180 nodist_foo_SOURCES = bindir.h
7181 CLEANFILES = bindir.h
7183 echo '#define bindir "$(bindir)"' >$@@
7186 This setup doesn't work, because Automake doesn't know that @file{foo.c}
7187 includes @file{bindir.h}. Remember, automatic dependency tracking works
7188 as a side-effect of compilation, so the dependencies of @file{foo.o} will
7189 be known only after @file{foo.o} has been compiled (@pxref{Dependencies}).
7190 The symptom is as follows.
7194 source='foo.c' object='foo.o' libtool=no \
7195 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
7196 depmode=gcc /bin/sh ./depcomp \
7197 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
7198 foo.c:2: bindir.h: No such file or directory
7199 make: *** [foo.o] Error 1
7202 In this example @file{bindir.h} is not distributed nor installed, and
7203 it is not even being built on-time. One may wonder if the
7204 @samp{nodist_foo_SOURCES = bindir.h} line has any use at all. This
7205 line simply states that @file{bindir.h} is a source of @code{foo}, so
7206 for instance, it should be inspected while generating tags
7207 (@pxref{Tags}). In other words, it does not help our present problem,
7208 and the build would fail identically without it.
7210 @subsubheading Using @code{BUILT_SOURCES}
7212 A solution is to require @file{bindir.h} to be built before anything
7213 else. This is what @code{BUILT_SOURCES} is meant for (@pxref{Sources}).
7218 nodist_foo_SOURCES = bindir.h
7219 BUILT_SOURCES = bindir.h
7220 CLEANFILES = bindir.h
7222 echo '#define bindir "$(bindir)"' >$@@
7225 See how @file{bindir.h} gets built first:
7229 echo '#define bindir "/usr/local/bin"' >bindir.h
7231 make[1]: Entering directory `/home/adl/tmp'
7232 source='foo.c' object='foo.o' libtool=no \
7233 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
7234 depmode=gcc /bin/sh ./depcomp \
7235 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
7236 gcc -g -O2 -o foo foo.o
7237 make[1]: Leaving directory `/home/adl/tmp'
7240 However, as said earlier, @code{BUILT_SOURCES} applies only to the
7241 @code{all}, @code{check}, and @code{install} targets. It still fails
7242 if you try to run @samp{make foo} explicitly:
7246 test -z "bindir.h" || rm -f bindir.h
7247 test -z "foo" || rm -f foo
7249 % : > .deps/foo.Po # Suppress previously recorded dependencies
7251 source='foo.c' object='foo.o' libtool=no \
7252 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
7253 depmode=gcc /bin/sh ./depcomp \
7254 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
7255 foo.c:2: bindir.h: No such file or directory
7256 make: *** [foo.o] Error 1
7259 @subsubheading Recording Dependencies manually
7261 Usually people are happy enough with @code{BUILT_SOURCES} because they
7262 never build targets such as @samp{make foo} before @samp{make all}, as
7263 in the previous example. However if this matters to you, you can
7264 avoid @code{BUILT_SOURCES} and record such dependencies explicitly in
7265 the @file{Makefile.am}.
7270 nodist_foo_SOURCES = bindir.h
7271 foo.$(OBJEXT): bindir.h
7272 CLEANFILES = bindir.h
7274 echo '#define bindir "$(bindir)"' >$@@
7277 You don't have to list @emph{all} the dependencies of @file{foo.o}
7278 explicitly, only those that might need to be built. If a dependency
7279 already exists, it will not hinder the first compilation and will be
7280 recorded by the normal dependency tracking code. (Note that after
7281 this first compilation the dependency tracking code will also have
7282 recorded the dependency between @file{foo.o} and
7283 @file{bindir.h}; so our explicit dependency is really useful to
7284 the first build only.)
7286 Adding explicit dependencies like this can be a bit dangerous if you are
7287 not careful enough. This is due to the way Automake tries not to
7288 overwrite your rules (it assumes you know better than it).
7289 @samp{foo.$(OBJEXT): bindir.h} supersedes any rule Automake may want to
7290 output to build @samp{foo.$(OBJEXT)}. It happens to work in this case
7291 because Automake doesn't have to output any @samp{foo.$(OBJEXT):}
7292 target: it relies on a suffix rule instead (i.e., @samp{.c.$(OBJEXT):}).
7293 Always check the generated @file{Makefile.in} if you do this.
7295 @subsubheading Build @file{bindir.h} from @file{configure}
7297 It's possible to define this preprocessor macro from @file{configure},
7298 either in @file{config.h} (@pxref{Defining Directories, , Defining
7299 Directories, autoconf, The Autoconf Manual}), or by processing a
7300 @file{bindir.h.in} file using @code{AC_CONFIG_FILES}
7301 (@pxref{Configuration Actions, ,Configuration Actions, autoconf, The
7304 At this point it should be clear that building @file{bindir.h} from
7305 @file{configure} works well for this example. @file{bindir.h} will exist
7306 before you build any target, hence will not cause any dependency issue.
7308 The Makefile can be shrunk as follows. We do not even have to mention
7316 However, it's not always possible to build sources from
7317 @file{configure}, especially when these sources are generated by a tool
7318 that needs to be built first.
7320 @subsubheading Build @file{bindir.c}, not @file{bindir.h}.
7322 Another attractive idea is to define @code{bindir} as a variable or
7323 function exported from @file{bindir.o}, and build @file{bindir.c}
7324 instead of @file{bindir.h}.
7327 noinst_PROGRAMS = foo
7328 foo_SOURCES = foo.c bindir.h
7329 nodist_foo_SOURCES = bindir.c
7330 CLEANFILES = bindir.c
7332 echo 'const char bindir[] = "$(bindir)";' >$@@
7335 @file{bindir.h} contains just the variable's declaration and doesn't
7336 need to be built, so it won't cause any trouble. @file{bindir.o} is
7337 always dependent on @file{bindir.c}, so @file{bindir.c} will get built
7340 @subsubheading Which is best?
7342 There is no panacea, of course. Each solution has its merits and
7345 You cannot use @code{BUILT_SOURCES} if the ability to run @samp{make
7346 foo} on a clean tree is important to you.
7348 You won't add explicit dependencies if you are leery of overriding
7349 an Automake rule by mistake.
7351 Building files from @file{./configure} is not always possible, neither
7352 is converting @file{.h} files into @file{.c} files.
7355 @node Other GNU Tools
7356 @chapter Other GNU Tools
7358 Since Automake is primarily intended to generate @file{Makefile.in}s for
7359 use in GNU programs, it tries hard to interoperate with other GNU tools.
7362 * Emacs Lisp:: Emacs Lisp
7373 @cindex @code{_LISP} primary, defined
7374 @cindex @code{LISP} primary, defined
7375 @cindex Primary variable, @code{LISP}
7381 Automake provides some support for Emacs Lisp. The @code{LISP} primary
7382 is used to hold a list of @file{.el} files. Possible prefixes for this
7383 primary are @code{lisp_} and @code{noinst_}. Note that if
7384 @code{lisp_LISP} is defined, then @file{configure.ac} must run
7385 @code{AM_PATH_LISPDIR} (@pxref{Macros}).
7387 @vindex dist_lisp_LISP
7388 @vindex dist_noinst_LISP
7389 Lisp sources are not distributed by default. You can prefix the
7390 @code{LISP} primary with @code{dist_}, as in @code{dist_lisp_LISP} or
7391 @code{dist_noinst_LISP}, to indicate that these files should be
7394 Automake will byte-compile all Emacs Lisp source files using the Emacs
7395 found by @code{AM_PATH_LISPDIR}, if any was found.
7397 Byte-compiled Emacs Lisp files are not portable among all versions of
7398 Emacs, so it makes sense to turn this off if you expect sites to have
7399 more than one version of Emacs installed. Furthermore, many packages
7400 don't actually benefit from byte-compilation. Still, we recommend
7401 that you byte-compile your Emacs Lisp sources. It is probably better
7402 for sites with strange setups to cope for themselves than to make the
7403 installation less nice for everybody else.
7405 There are two ways to avoid byte-compiling. Historically, we have
7406 recommended the following construct.
7408 lisp_LISP = file1.el file2.el
7412 @code{ELCFILES} is an internal Automake variable that normally lists
7413 all @file{.elc} files that must be byte-compiled. Automake defines
7414 @code{ELCFILES} automatically from @code{lisp_LISP}. Emptying this
7415 variable explicitly prevents byte-compilation.
7417 Since Automake 1.8, we now recommend using @code{lisp_DATA} instead. As
7420 lisp_DATA = file1.el file2.el
7423 Note that these two constructs are not equivalent. @code{_LISP} will
7424 not install a file if Emacs is not installed, while @code{_DATA} will
7425 always install its files.
7430 @cindex GNU Gettext support
7431 @cindex Gettext support
7432 @cindex Support for GNU Gettext
7434 If @code{AM_GNU_GETTEXT} is seen in @file{configure.ac}, then Automake
7435 turns on support for GNU gettext, a message catalog system for
7436 internationalization
7437 (@pxref{Top, , Introduction, gettext, GNU gettext utilities}).
7439 The @code{gettext} support in Automake requires the addition of one or
7440 two subdirectories to the package: @file{po} and possibly also @file{intl}.
7441 The latter is needed if @code{AM_GNU_GETTEXT} is not invoked with the
7442 @samp{external} argument, or if @code{AM_GNU_GETTEXT_INTL_SUBDIR} is used.
7443 Automake ensures that these directories exist and are mentioned in
7449 Automake provides support for GNU Libtool (@pxref{Top, , Introduction,
7450 libtool, The Libtool Manual}) with the @code{LTLIBRARIES} primary.
7451 @xref{A Shared Library}.
7457 @cindex @code{_JAVA} primary, defined
7458 @cindex @code{JAVA} primary, defined
7459 @cindex Primary variable, @code{JAVA}
7461 Automake provides some minimal support for Java compilation with the
7462 @code{JAVA} primary.
7464 Any @file{.java} files listed in a @code{_JAVA} variable will be
7465 compiled with @code{JAVAC} at build time. By default, @file{.java}
7466 files are not included in the distribution, you should use the
7467 @code{dist_} prefix to distribute them.
7469 Here is a typical setup for distributing @file{.java} files and
7470 installing the @file{.class} files resulting from their compilation.
7473 javadir = $(datadir)/java
7474 dist_java_JAVA = a.java b.java @dots{}
7477 @cindex @code{JAVA} restrictions
7478 @cindex Restrictions for @code{JAVA}
7480 Currently Automake enforces the restriction that only one @code{_JAVA}
7481 primary can be used in a given @file{Makefile.am}. The reason for this
7482 restriction is that, in general, it isn't possible to know which
7483 @file{.class} files were generated from which @file{.java} files, so
7484 it would be impossible to know which files to install where. For
7485 instance, a @file{.java} file can define multiple classes; the resulting
7486 @file{.class} file names cannot be predicted without parsing the
7489 There are a few variables that are used when compiling Java sources:
7493 The name of the Java compiler. This defaults to @samp{javac}.
7496 The flags to pass to the compiler. This is considered to be a user
7497 variable (@pxref{User Variables}).
7500 More flags to pass to the Java compiler. This, and not
7501 @code{JAVACFLAGS}, should be used when it is necessary to put Java
7502 compiler flags into @file{Makefile.am}.
7505 The value of this variable is passed to the @option{-d} option to
7506 @code{javac}. It defaults to @samp{$(top_builddir)}.
7509 This variable is a shell expression that is used to set the
7510 @env{CLASSPATH} environment variable on the @code{javac} command line.
7511 (In the future we will probably handle class path setting differently.)
7518 @cindex @code{_PYTHON} primary, defined
7519 @cindex @code{PYTHON} primary, defined
7520 @cindex Primary variable, @code{PYTHON}
7523 Automake provides support for Python compilation with the
7524 @code{PYTHON} primary. A typical setup is to call
7525 @code{AM_PATH_PYTHON} in @file{configure.ac} and use a line like the
7526 following in @file{Makefile.am}:
7529 python_PYTHON = tree.py leave.py
7532 Any files listed in a @code{_PYTHON} variable will be byte-compiled
7533 with @command{py-compile} at install time. @command{py-compile}
7534 actually creates both standard (@file{.pyc}) and optimized
7535 (@file{.pyo}) byte-compiled versions of the source files. Note that
7536 because byte-compilation occurs at install time, any files listed in
7537 @code{noinst_PYTHON} will not be compiled. Python source files are
7538 included in the distribution by default, prepend @code{nodist_} (as in
7539 @code{nodist_python_PYTHON}) to omit them.
7541 Automake ships with an Autoconf macro called @code{AM_PATH_PYTHON}
7542 that will determine some Python-related directory variables (see
7543 below). If you have called @code{AM_PATH_PYTHON} from
7544 @file{configure.ac}, then you may use the variables
7545 @code{python_PYTHON} or @code{pkgpython_PYTHON} to list Python source
7546 files in your @file{Makefile.am}, depending on where you want your files
7547 installed (see the definitions of @code{pythondir} and
7548 @code{pkgpythondir} below).
7550 @defmac AM_PATH_PYTHON (@ovar{version}, @ovar{action-if-found}, @ovar{action-if-not-found})
7552 Search for a Python interpreter on the system. This macro takes three
7553 optional arguments. The first argument, if present, is the minimum
7554 version of Python required for this package: @code{AM_PATH_PYTHON}
7555 will skip any Python interpreter that is older than @var{version}.
7556 If an interpreter is found and satisfies @var{version}, then
7557 @var{action-if-found} is run. Otherwise, @var{action-if-not-found} is
7560 If @var{action-if-not-found} is not specified, as in the following
7561 example, the default is to abort @command{configure}.
7564 AM_PATH_PYTHON([2.2])
7568 This is fine when Python is an absolute requirement for the package.
7569 If Python >= 2.5 was only @emph{optional} to the package,
7570 @code{AM_PATH_PYTHON} could be called as follows.
7573 AM_PATH_PYTHON([2.5],, [:])
7576 @code{AM_PATH_PYTHON} creates the following output variables based on
7577 the Python installation found during configuration.
7582 The name of the Python executable, or @samp{:} if no suitable
7583 interpreter could be found.
7585 Assuming @var{action-if-not-found} is used (otherwise @file{./configure}
7586 will abort if Python is absent), the value of @code{PYTHON} can be used
7587 to setup a conditional in order to disable the relevant part of a build
7591 AM_PATH_PYTHON(,, [:])
7592 AM_CONDITIONAL([HAVE_PYTHON], [test "$PYTHON" != :])
7595 @item PYTHON_VERSION
7596 The Python version number, in the form @var{major}.@var{minor}
7597 (e.g., @samp{2.5}). This is currently the value of
7598 @samp{sys.version[:3]}.
7601 The string @samp{$@{prefix@}}. This term may be used in future work
7602 that needs the contents of Python's @samp{sys.prefix}, but general
7603 consensus is to always use the value from @command{configure}.
7605 @item PYTHON_EXEC_PREFIX
7606 The string @samp{$@{exec_prefix@}}. This term may be used in future work
7607 that needs the contents of Python's @samp{sys.exec_prefix}, but general
7608 consensus is to always use the value from @command{configure}.
7610 @item PYTHON_PLATFORM
7611 The canonical name used by Python to describe the operating system, as
7612 given by @samp{sys.platform}. This value is sometimes needed when
7613 building Python extensions.
7616 The directory name for the @file{site-packages} subdirectory of the
7617 standard Python install tree.
7620 This is the directory under @code{pythondir} that is named after the
7621 package. That is, it is @samp{$(pythondir)/$(PACKAGE)}. It is provided
7625 This is the directory where Python extension modules (shared libraries)
7626 should be installed. An extension module written in C could be declared
7627 as follows to Automake:
7630 pyexec_LTLIBRARIES = quaternion.la
7631 quaternion_SOURCES = quaternion.c support.c support.h
7632 quaternion_la_LDFLAGS = -avoid-version -module
7636 This is a convenience variable that is defined as
7637 @samp{$(pyexecdir)/$(PACKAGE)}.
7640 All these directory variables have values that start with either
7641 @samp{$@{prefix@}} or @samp{$@{exec_prefix@}} unexpanded. This works
7642 fine in @file{Makefiles}, but it makes these variables hard to use in
7643 @file{configure}. This is mandated by the GNU coding standards, so
7644 that the user can run @samp{make prefix=/foo install}. The Autoconf
7645 manual has a section with more details on this topic
7646 (@pxref{Installation Directory Variables, , Installation Directory
7647 Variables, autoconf, The Autoconf Manual}). See also @ref{Hard-Coded
7652 @chapter Building documentation
7654 Currently Automake provides support for Texinfo and man pages.
7658 * Man Pages:: Man pages
7665 @cindex @code{_TEXINFOS} primary, defined
7666 @cindex @code{TEXINFOS} primary, defined
7667 @cindex Primary variable, @code{TEXINFOS}
7668 @cindex HTML output using Texinfo
7669 @cindex PDF output using Texinfo
7670 @cindex PS output using Texinfo
7671 @cindex DVI output using Texinfo
7673 @vindex info_TEXINFOS
7675 If the current directory contains Texinfo source, you must declare it
7676 with the @code{TEXINFOS} primary. Generally Texinfo files are converted
7677 into info, and thus the @code{info_TEXINFOS} variable is most commonly used
7678 here. Any Texinfo source file must end in the @file{.texi},
7679 @file{.txi}, or @file{.texinfo} extension. We recommend @file{.texi}
7682 Automake generates rules to build @file{.info}, @file{.dvi},
7683 @file{.ps}, @file{.pdf} and @file{.html} files from your Texinfo
7684 sources. Following the GNU Coding Standards, only the @file{.info}
7685 files are built by @samp{make all} and installed by @samp{make
7686 install} (unless you use @option{no-installinfo}, see below).
7687 Furthermore, @file{.info} files are automatically distributed so that
7688 Texinfo is not a prerequisite for installing your package.
7694 @trindex install-dvi
7695 @trindex install-html
7696 @trindex install-pdf
7698 Other documentation formats can be built on request by @samp{make
7699 dvi}, @samp{make ps}, @samp{make pdf} and @samp{make html}, and they
7700 can be installed with @samp{make install-dvi}, @samp{make install-ps},
7701 @samp{make install-pdf} and @samp{make install-html} explicitly.
7702 @samp{make uninstall} will remove everything: the Texinfo
7703 documentation installed by default as well as all the above optional
7706 All these targets can be extended using @samp{-local} rules
7707 (@pxref{Extending}).
7709 @cindex Texinfo flag, @code{VERSION}
7710 @cindex Texinfo flag, @code{UPDATED}
7711 @cindex Texinfo flag, @code{EDITION}
7712 @cindex Texinfo flag, @code{UPDATED-MONTH}
7714 @cindex @code{VERSION} Texinfo flag
7715 @cindex @code{UPDATED} Texinfo flag
7716 @cindex @code{EDITION} Texinfo flag
7717 @cindex @code{UPDATED-MONTH} Texinfo flag
7719 @cindex @file{mdate-sh}
7721 If the @file{.texi} file @code{@@include}s @file{version.texi}, then
7722 that file will be automatically generated. The file @file{version.texi}
7723 defines four Texinfo flag you can reference using
7724 @code{@@value@{EDITION@}}, @code{@@value@{VERSION@}},
7725 @code{@@value@{UPDATED@}}, and @code{@@value@{UPDATED-MONTH@}}.
7730 Both of these flags hold the version number of your program. They are
7731 kept separate for clarity.
7734 This holds the date the primary @file{.texi} file was last modified.
7737 This holds the name of the month in which the primary @file{.texi} file
7741 The @file{version.texi} support requires the @command{mdate-sh}
7742 script; this script is supplied with Automake and automatically
7743 included when @command{automake} is invoked with the
7744 @option{--add-missing} option.
7746 If you have multiple Texinfo files, and you want to use the
7747 @file{version.texi} feature, then you have to have a separate version
7748 file for each Texinfo file. Automake will treat any include in a
7749 Texinfo file that matches @file{vers*.texi} just as an automatically
7750 generated version file.
7752 Sometimes an info file actually depends on more than one @file{.texi}
7753 file. For instance, in GNU Hello, @file{hello.texi} includes the file
7754 @file{fdl.texi}. You can tell Automake about these dependencies using
7755 the @code{@var{texi}_TEXINFOS} variable. Here is how GNU Hello does it:
7760 info_TEXINFOS = hello.texi
7761 hello_TEXINFOS = fdl.texi
7764 @cindex @file{texinfo.tex}
7766 By default, Automake requires the file @file{texinfo.tex} to appear in
7767 the same directory as the @file{Makefile.am} file that lists the
7768 @file{.texi} files. If you used @code{AC_CONFIG_AUX_DIR} in
7769 @file{configure.ac} (@pxref{Input, , Finding `configure' Input,
7770 autoconf, The Autoconf Manual}), then @file{texinfo.tex} is looked for
7771 there. In both cases, @command{automake} then supplies @file{texinfo.tex} if
7772 @option{--add-missing} is given, and takes care of its distribution.
7773 However, if you set the @code{TEXINFO_TEX} variable (see below),
7774 it overrides the location of the file and turns off its installation
7775 into the source as well as its distribution.
7777 The option @option{no-texinfo.tex} can be used to eliminate the
7778 requirement for the file @file{texinfo.tex}. Use of the variable
7779 @code{TEXINFO_TEX} is preferable, however, because that allows the
7780 @code{dvi}, @code{ps}, and @code{pdf} targets to still work.
7782 @cindex Option, @code{no-installinfo}
7783 @cindex Target, @code{install-info}
7784 @cindex @code{install-info} target
7785 @cindex @code{no-installinfo} option
7787 @opindex no-installinfo
7788 @trindex install-info
7790 Automake generates an @code{install-info} rule; some people apparently
7791 use this. By default, info pages are installed by @samp{make
7792 install}, so running @code{make install-info} is pointless. This can
7793 be prevented via the @code{no-installinfo} option. In this case,
7794 @file{.info} files are not installed by default, and user must
7795 request this explicitly using @samp{make install-info}.
7797 The following variables are used by the Texinfo build rules.
7801 The name of the program invoked to build @file{.info} files. This
7802 variable is defined by Automake. If the @command{makeinfo} program is
7803 found on the system then it will be used by default; otherwise
7804 @command{missing} will be used instead.
7807 The command invoked to build @file{.html} files. Automake
7808 defines this to @samp{$(MAKEINFO) --html}.
7811 User flags passed to each invocation of @samp{$(MAKEINFO)} and
7812 @samp{$(MAKEINFOHTML)}. This user variable (@pxref{User Variables}) is
7813 not expected to be defined in any @file{Makefile}; it can be used by
7814 users to pass extra flags to suit their needs.
7816 @item AM_MAKEINFOFLAGS
7817 @itemx AM_MAKEINFOHTMLFLAGS
7818 Maintainer flags passed to each @command{makeinfo} invocation. Unlike
7819 @code{MAKEINFOFLAGS}, these variables are meant to be defined by
7820 maintainers in @file{Makefile.am}. @samp{$(AM_MAKEINFOFLAGS)} is
7821 passed to @code{makeinfo} when building @file{.info} files; and
7822 @samp{$(AM_MAKEINFOHTMLFLAGS)} is used when building @file{.html}
7825 For instance, the following setting can be used to obtain one single
7826 @file{.html} file per manual, without node separators.
7828 AM_MAKEINFOHTMLFLAGS = --no-headers --no-split
7831 @code{AM_MAKEINFOHTMLFLAGS} defaults to @samp{$(AM_MAKEINFOFLAGS)}.
7832 This means that defining @code{AM_MAKEINFOFLAGS} without defining
7833 @code{AM_MAKEINFOHTMLFLAGS} will impact builds of both @file{.info}
7834 and @file{.html} files.
7837 The name of the command that converts a @file{.texi} file into a
7838 @file{.dvi} file. This defaults to @samp{texi2dvi}, a script that ships
7839 with the Texinfo package.
7842 The name of the command that translates a @file{.texi} file into a
7843 @file{.pdf} file. This defaults to @samp{$(TEXI2DVI) --pdf --batch}.
7846 The name of the command that builds a @file{.ps} file out of a
7847 @file{.dvi} file. This defaults to @samp{dvips}.
7851 If your package has Texinfo files in many directories, you can use the
7852 variable @code{TEXINFO_TEX} to tell Automake where to find the canonical
7853 @file{texinfo.tex} for your package. The value of this variable should
7854 be the relative path from the current @file{Makefile.am} to
7858 TEXINFO_TEX = ../doc/texinfo.tex
7866 @cindex @code{_MANS} primary, defined
7867 @cindex @code{MANS} primary, defined
7868 @cindex Primary variable, @code{MANS}
7872 A package can also include man pages (but see the GNU standards on this
7873 matter, @ref{Man Pages, , , standards, The GNU Coding Standards}.) Man
7874 pages are declared using the @code{MANS} primary. Generally the
7875 @code{man_MANS} variable is used. Man pages are automatically installed in
7876 the correct subdirectory of @code{mandir}, based on the file extension.
7878 File extensions such as @file{.1c} are handled by looking for the valid
7879 part of the extension and using that to determine the correct
7880 subdirectory of @code{mandir}. Valid section names are the digits
7881 @samp{0} through @samp{9}, and the letters @samp{l} and @samp{n}.
7883 Sometimes developers prefer to name a man page something like
7884 @file{foo.man} in the source, and then rename it to have the correct
7885 suffix, for example @file{foo.1}, when installing the file. Automake
7886 also supports this mode. For a valid section named @var{section},
7887 there is a corresponding directory named @samp{man@var{section}dir},
7888 and a corresponding @code{_MANS} variable. Files listed in such a
7889 variable are installed in the indicated section. If the file already
7890 has a valid suffix, then it is installed as-is; otherwise the file
7891 suffix is changed to match the section.
7893 For instance, consider this example:
7895 man1_MANS = rename.man thesame.1 alsothesame.1c
7899 In this case, @file{rename.man} will be renamed to @file{rename.1} when
7900 installed, but the other files will keep their names.
7902 @cindex Target, @code{install-man}
7903 @cindex Option, @option{no-installman}
7904 @cindex @code{install-man} target
7905 @cindex @option{no-installman} option
7906 @opindex no-installman
7907 @trindex install-man
7909 By default, man pages are installed by @samp{make install}. However,
7910 since the GNU project does not require man pages, many maintainers do
7911 not expend effort to keep the man pages up to date. In these cases, the
7912 @option{no-installman} option will prevent the man pages from being
7913 installed by default. The user can still explicitly install them via
7914 @samp{make install-man}.
7916 For fast installation, with many files it is preferable to use
7917 @samp{man@var{section}_MANS} over @samp{man_MANS} as well as files that
7918 do not need to be renamed.
7920 Man pages are not currently considered to be source, because it is not
7921 uncommon for man pages to be automatically generated. Therefore they
7922 are not automatically included in the distribution. However, this can
7923 be changed by use of the @code{dist_} prefix. For instance here is
7924 how to distribute and install the two man pages of GNU @command{cpio}
7925 (which includes both Texinfo documentation and man pages):
7928 dist_man_MANS = cpio.1 mt.1
7931 The @code{nobase_} prefix is meaningless for man pages and is
7935 @cindex @code{notrans_} prefix
7936 @cindex Man page renaming, avoiding
7937 @cindex Avoiding man page renaming
7939 Executables and manpages may be renamed upon installation
7940 (@pxref{Renaming}). For manpages this can be avoided by use of the
7941 @code{notrans_} prefix. For instance, suppose an executable @samp{foo}
7942 allowing to access a library function @samp{foo} from the command line.
7943 The way to avoid renaming of the @file{foo.3} manpage is:
7947 notrans_man_MANS = foo.3
7950 @cindex @code{notrans_} and @code{dist_} or @code{nodist_}
7951 @cindex @code{dist_} and @code{notrans_}
7952 @cindex @code{nodist_} and @code{notrans_}
7954 @samp{notrans_} must be specified first when used in conjunction with
7955 either @samp{dist_} or @samp{nodist_} (@pxref{Fine-grained Distribution
7956 Control}). For instance:
7959 notrans_dist_man3_MANS = bar.3
7963 @chapter What Gets Installed
7965 @cindex Installation support
7966 @cindex @samp{make install} support
7968 Naturally, Automake handles the details of actually installing your
7969 program once it has been built. All files named by the various
7970 primaries are automatically installed in the appropriate places when the
7971 user runs @samp{make install}.
7974 * Basics of Installation:: What gets installed where
7975 * The Two Parts of Install:: Installing data and programs separately
7976 * Extending Installation:: Adding your own rules for installation
7977 * Staged Installs:: Installation in a temporary location
7978 * Install Rules for the User:: Useful additional rules
7981 @node Basics of Installation
7982 @section Basics of Installation
7984 A file named in a primary is installed by copying the built file into
7985 the appropriate directory. The base name of the file is used when
7989 bin_PROGRAMS = hello subdir/goodbye
7992 In this example, both @samp{hello} and @samp{goodbye} will be installed
7993 in @samp{$(bindir)}.
7995 Sometimes it is useful to avoid the basename step at install time. For
7996 instance, you might have a number of header files in subdirectories of
7997 the source tree that are laid out precisely how you want to install
7998 them. In this situation you can use the @code{nobase_} prefix to
7999 suppress the base name step. For example:
8002 nobase_include_HEADERS = stdio.h sys/types.h
8006 will install @file{stdio.h} in @samp{$(includedir)} and @file{types.h}
8007 in @samp{$(includedir)/sys}.
8009 For most file types, Automake will install multiple files at once, while
8010 avoiding command line length issues (@pxref{Length Limitations}). Since
8011 some @command{install} programs will not install the same file twice in
8012 one invocation, you may need to ensure that file lists are unique within
8013 one variable such as @samp{nobase_include_HEADERS} above.
8015 You should not rely on the order in which files listed in one variable
8016 are installed. Likewise, to cater for parallel make, you should not
8017 rely on any particular file installation order even among different
8018 file types (library dependencies are an exception here).
8021 @node The Two Parts of Install
8022 @section The Two Parts of Install
8024 Automake generates separate @code{install-data} and @code{install-exec}
8025 rules, in case the installer is installing on multiple machines that
8026 share directory structure---these targets allow the machine-independent
8027 parts to be installed only once. @code{install-exec} installs
8028 platform-dependent files, and @code{install-data} installs
8029 platform-independent files. The @code{install} target depends on both
8030 of these targets. While Automake tries to automatically segregate
8031 objects into the correct category, the @file{Makefile.am} author is, in
8032 the end, responsible for making sure this is done correctly.
8033 @trindex install-data
8034 @trindex install-exec
8036 @cindex Install, two parts of
8038 Variables using the standard directory prefixes @samp{data},
8039 @samp{info}, @samp{man}, @samp{include}, @samp{oldinclude},
8040 @samp{pkgdata}, or @samp{pkginclude} are installed by
8041 @code{install-data}.
8043 Variables using the standard directory prefixes @samp{bin},
8044 @samp{sbin}, @samp{libexec}, @samp{sysconf}, @samp{localstate},
8045 @samp{lib}, or @samp{pkglib} are installed by @code{install-exec}.
8047 For instance, @code{data_DATA} files are installed by @code{install-data},
8048 while @code{bin_PROGRAMS} files are installed by @code{install-exec}.
8050 Any variable using a user-defined directory prefix with @samp{exec} in
8051 the name (e.g., @code{myexecbin_PROGRAMS}) is installed by
8052 @code{install-exec}. All other user-defined prefixes are installed by
8053 @code{install-data}.
8055 @node Extending Installation
8056 @section Extending Installation
8058 It is possible to extend this mechanism by defining an
8059 @code{install-exec-local} or @code{install-data-local} rule. If these
8060 rules exist, they will be run at @samp{make install} time. These
8061 rules can do almost anything; care is required.
8062 @trindex install-exec-local
8063 @trindex install-data-local
8065 Automake also supports two install hooks, @code{install-exec-hook} and
8066 @code{install-data-hook}. These hooks are run after all other install
8067 rules of the appropriate type, exec or data, have completed. So, for
8068 instance, it is possible to perform post-installation modifications
8069 using an install hook. @xref{Extending}, for some examples.
8070 @cindex Install hook
8072 @node Staged Installs
8073 @section Staged Installs
8076 Automake generates support for the @code{DESTDIR} variable in all
8077 install rules. @code{DESTDIR} is used during the @samp{make install}
8078 step to relocate install objects into a staging area. Each object and
8079 path is prefixed with the value of @code{DESTDIR} before being copied
8080 into the install area. Here is an example of typical DESTDIR usage:
8083 mkdir /tmp/staging &&
8084 make DESTDIR=/tmp/staging install
8087 The @command{mkdir} command avoids a security problem if the attacker
8088 creates a symbolic link from @file{/tmp/staging} to a victim area;
8089 then @command{make} places install objects in a directory tree built under
8090 @file{/tmp/staging}. If @file{/gnu/bin/foo} and
8091 @file{/gnu/share/aclocal/foo.m4} are to be installed, the above command
8092 would install @file{/tmp/staging/gnu/bin/foo} and
8093 @file{/tmp/staging/gnu/share/aclocal/foo.m4}.
8095 This feature is commonly used to build install images and packages
8098 Support for @code{DESTDIR} is implemented by coding it directly into
8099 the install rules. If your @file{Makefile.am} uses a local install
8100 rule (e.g., @code{install-exec-local}) or an install hook, then you
8101 must write that code to respect @code{DESTDIR}.
8103 @xref{Makefile Conventions, , , standards, The GNU Coding Standards},
8104 for another usage example.
8106 @node Install Rules for the User
8107 @section Install Rules for the User
8109 Automake also generates rules for targets @code{uninstall},
8110 @code{installdirs}, and @code{install-strip}.
8112 @trindex installdirs
8113 @trindex install-strip
8115 Automake supports @code{uninstall-local} and @code{uninstall-hook}.
8116 There is no notion of separate uninstalls for ``exec'' and ``data'', as
8117 these features would not provide additional functionality.
8119 Note that @code{uninstall} is not meant as a replacement for a real
8124 @chapter What Gets Cleaned
8126 @cindex @samp{make clean} support
8128 The GNU Makefile Standards specify a number of different clean rules.
8129 @xref{Standard Targets, , Standard Targets for Users, standards,
8130 The GNU Coding Standards}.
8132 Generally the files that can be cleaned are determined automatically by
8133 Automake. Of course, Automake also recognizes some variables that can
8134 be defined to specify additional files to clean. These variables are
8135 @code{MOSTLYCLEANFILES}, @code{CLEANFILES}, @code{DISTCLEANFILES}, and
8136 @code{MAINTAINERCLEANFILES}.
8137 @vindex MOSTLYCLEANFILES
8139 @vindex DISTCLEANFILES
8140 @vindex MAINTAINERCLEANFILES
8142 @trindex mostlyclean-local
8143 @trindex clean-local
8144 @trindex distclean-local
8145 @trindex maintainer-clean-local
8146 When cleaning involves more than deleting some hard-coded list of
8147 files, it is also possible to supplement the cleaning rules with your
8148 own commands. Simply define a rule for any of the
8149 @code{mostlyclean-local}, @code{clean-local}, @code{distclean-local},
8150 or @code{maintainer-clean-local} targets (@pxref{Extending}). A common
8151 case is deleting a directory, for instance, a directory created by the
8159 Since @command{make} allows only one set of rules for a given target,
8160 a more extensible way of writing this is to use a separate target
8161 listed as a dependency:
8164 clean-local: clean-local-check
8165 .PHONY: clean-local-check
8170 As the GNU Standards aren't always explicit as to which files should
8171 be removed by which rule, we've adopted a heuristic that we believe
8172 was first formulated by Fran@,{c}ois Pinard:
8176 If @command{make} built it, and it is commonly something that one would
8177 want to rebuild (for instance, a @file{.o} file), then
8178 @code{mostlyclean} should delete it.
8181 Otherwise, if @command{make} built it, then @code{clean} should delete it.
8184 If @command{configure} built it, then @code{distclean} should delete it.
8187 If the maintainer built it (for instance, a @file{.info} file), then
8188 @code{maintainer-clean} should delete it. However
8189 @code{maintainer-clean} should not delete anything that needs to exist
8190 in order to run @samp{./configure && make}.
8193 We recommend that you follow this same set of heuristics in your
8198 @chapter What Goes in a Distribution
8201 * Basics of Distribution:: Files distributed by default
8202 * Fine-grained Distribution Control:: @code{dist_} and @code{nodist_} prefixes
8203 * The dist Hook:: A target for last-minute distribution changes
8204 * Checking the Distribution:: @samp{make distcheck} explained
8205 * The Types of Distributions:: A variety of formats and compression methods
8208 @node Basics of Distribution
8209 @section Basics of Distribution
8211 @cindex @samp{make dist}
8216 The @code{dist} rule in the generated @file{Makefile.in} can be used
8217 to generate a gzipped @code{tar} file and other flavors of archive for
8218 distribution. The file is named based on the @code{PACKAGE} and
8219 @code{VERSION} variables defined by @code{AM_INIT_AUTOMAKE}
8220 (@pxref{Macros}); more precisely the gzipped @code{tar} file is named
8221 @samp{@var{package}-@var{version}.tar.gz}.
8223 You can use the @command{make} variable @code{GZIP_ENV} to control how gzip
8224 is run. The default setting is @option{--best}.
8226 @cindex @code{m4_include}, distribution
8227 @cindex @code{include}, distribution
8230 For the most part, the files to distribute are automatically found by
8231 Automake: all source files are automatically included in a distribution,
8232 as are all @file{Makefile.am}s and @file{Makefile.in}s. Automake also
8233 has a built-in list of commonly used files that are automatically
8234 included if they are found in the current directory (either physically,
8235 or as the target of a @file{Makefile.am} rule). This list is printed by
8236 @samp{automake --help}. Also, files that are read by @command{configure}
8237 (i.e.@: the source files corresponding to the files specified in various
8238 Autoconf macros such as @code{AC_CONFIG_FILES} and siblings) are
8239 automatically distributed. Files included in @file{Makefile.am}s (using
8240 @code{include}) or in @file{configure.ac} (using @code{m4_include}), and
8241 helper scripts installed with @samp{automake --add-missing} are also
8245 Still, sometimes there are files that must be distributed, but which
8246 are not covered in the automatic rules. These files should be listed in
8247 the @code{EXTRA_DIST} variable. You can mention files from
8248 subdirectories in @code{EXTRA_DIST}.
8250 You can also mention a directory in @code{EXTRA_DIST}; in this case the
8251 entire directory will be recursively copied into the distribution.
8252 Please note that this will also copy @emph{everything} in the directory,
8253 including CVS/RCS version control files. We recommend against using
8257 @vindex DIST_SUBDIRS
8258 If you define @code{SUBDIRS}, Automake will recursively include the
8259 subdirectories in the distribution. If @code{SUBDIRS} is defined
8260 conditionally (@pxref{Conditionals}), Automake will normally include
8261 all directories that could possibly appear in @code{SUBDIRS} in the
8262 distribution. If you need to specify the set of directories
8263 conditionally, you can set the variable @code{DIST_SUBDIRS} to the
8264 exact list of subdirectories to include in the distribution
8265 (@pxref{Conditional Subdirectories}).
8268 @node Fine-grained Distribution Control
8269 @section Fine-grained Distribution Control
8273 Sometimes you need tighter control over what does @emph{not} go into the
8274 distribution; for instance, you might have source files that are
8275 generated and that you do not want to distribute. In this case
8276 Automake gives fine-grained control using the @code{dist} and
8277 @code{nodist} prefixes. Any primary or @code{_SOURCES} variable can be
8278 prefixed with @code{dist_} to add the listed files to the distribution.
8279 Similarly, @code{nodist_} can be used to omit the files from the
8282 As an example, here is how you would cause some data to be distributed
8283 while leaving some source code out of the distribution:
8286 dist_data_DATA = distribute-this
8288 nodist_foo_SOURCES = do-not-distribute.c
8292 @section The dist Hook
8296 Occasionally it is useful to be able to change the distribution before
8297 it is packaged up. If the @code{dist-hook} rule exists, it is run
8298 after the distribution directory is filled, but before the actual tar
8299 (or shar) file is created. One way to use this is for distributing
8300 files in subdirectories for which a new @file{Makefile.am} is overkill:
8304 mkdir $(distdir)/random
8305 cp -p $(srcdir)/random/a1 $(srcdir)/random/a2 $(distdir)/random
8308 Another way to use this is for removing unnecessary files that get
8309 recursively included by specifying a directory in EXTRA_DIST:
8315 rm -rf `find $(distdir)/doc -name CVS`
8320 Two variables that come handy when writing @code{dist-hook} rules are
8321 @samp{$(distdir)} and @samp{$(top_distdir)}.
8323 @samp{$(distdir)} points to the directory where the @code{dist} rule
8324 will copy files from the current directory before creating the
8325 tarball. If you are at the top-level directory, then @samp{distdir =
8326 $(PACKAGE)-$(VERSION)}. When used from subdirectory named
8327 @file{foo/}, then @samp{distdir = ../$(PACKAGE)-$(VERSION)/foo}.
8328 @samp{$(distdir)} can be a relative or absolute path, do not assume
8331 @samp{$(top_distdir)} always points to the root directory of the
8332 distributed tree. At the top-level it's equal to @samp{$(distdir)}.
8333 In the @file{foo/} subdirectory
8334 @samp{top_distdir = ../$(PACKAGE)-$(VERSION)}.
8335 @samp{$(top_distdir)} too can be a relative or absolute path.
8337 Note that when packages are nested using @code{AC_CONFIG_SUBDIRS}
8338 (@pxref{Subpackages}), then @samp{$(distdir)} and
8339 @samp{$(top_distdir)} are relative to the package where @samp{make
8340 dist} was run, not to any sub-packages involved.
8342 @node Checking the Distribution
8343 @section Checking the Distribution
8345 @cindex @samp{make distcheck}
8346 @cindex @samp{make distcleancheck}
8347 @vindex distcleancheck_listfiles
8348 @cindex @samp{make distuninstallcheck}
8349 @vindex distuninstallcheck_listfiles
8352 Automake also generates a @code{distcheck} rule that can be of help to
8353 ensure that a given distribution will actually work. @code{distcheck}
8354 makes a distribution, then tries to do a @code{VPATH} build
8355 (@pxref{VPATH Builds}), run the test suite, and finally make another
8356 tarball to ensure the distribution is self-contained.
8358 @vindex DISTCHECK_CONFIGURE_FLAGS
8359 Building the package involves running @samp{./configure}. If you need
8360 to supply additional flags to @command{configure}, define them in the
8361 @code{DISTCHECK_CONFIGURE_FLAGS} variable, either in your top-level
8362 @file{Makefile.am}, or on the command line when invoking @command{make}.
8364 @trindex distcheck-hook
8365 If the @code{distcheck-hook} rule is defined in your top-level
8366 @file{Makefile.am}, then it will be invoked by @code{distcheck} after
8367 the new distribution has been unpacked, but before the unpacked copy
8368 is configured and built. Your @code{distcheck-hook} can do almost
8369 anything, though as always caution is advised. Generally this hook is
8370 used to check for potential distribution errors not caught by the
8371 standard mechanism. Note that @code{distcheck-hook} as well as
8372 @code{DISTCHECK_CONFIGURE_FLAGS} are not honored in a subpackage
8373 @file{Makefile.am}, but the @code{DISTCHECK_CONFIGURE_FLAGS} are
8374 passed down to the @command{configure} script of the subpackage.
8376 @trindex distcleancheck
8377 @vindex DISTCLEANFILES
8378 @vindex distcleancheck_listfiles
8379 Speaking of potential distribution errors, @code{distcheck} also
8380 ensures that the @code{distclean} rule actually removes all built
8381 files. This is done by running @samp{make distcleancheck} at the end of
8382 the @code{VPATH} build. By default, @code{distcleancheck} will run
8383 @code{distclean} and then make sure the build tree has been emptied by
8384 running @samp{$(distcleancheck_listfiles)}. Usually this check will
8385 find generated files that you forgot to add to the @code{DISTCLEANFILES}
8386 variable (@pxref{Clean}).
8388 The @code{distcleancheck} behavior should be OK for most packages,
8389 otherwise you have the possibility to override the definition of
8390 either the @code{distcleancheck} rule, or the
8391 @samp{$(distcleancheck_listfiles)} variable. For instance, to disable
8392 @code{distcleancheck} completely, add the following rule to your
8393 top-level @file{Makefile.am}:
8400 If you want @code{distcleancheck} to ignore built files that have not
8401 been cleaned because they are also part of the distribution, add the
8402 following definition instead:
8405 distcleancheck_listfiles = \
8406 find . -type f -exec sh -c 'test -f $(srcdir)/$$1 || echo $$1' \
8410 The above definition is not the default because it's usually an error if
8411 your Makefiles cause some distributed files to be rebuilt when the user
8412 build the package. (Think about the user missing the tool required to
8413 build the file; or if the required tool is built by your package,
8414 consider the cross-compilation case where it can't be run.) There is
8415 an entry in the FAQ about this (@pxref{distcleancheck}), make sure you
8416 read it before playing with @code{distcleancheck_listfiles}.
8418 @code{distcheck} also checks that the @code{uninstall} rule works
8419 properly, both for ordinary and @code{DESTDIR} builds. It does this
8420 by invoking @samp{make uninstall}, and then it checks the install tree
8421 to see if any files are left over. This check will make sure that you
8422 correctly coded your @code{uninstall}-related rules.
8424 By default, the checking is done by the @code{distuninstallcheck} rule,
8425 and the list of files in the install tree is generated by
8426 @samp{$(distuninstallcheck_listfiles)} (this is a variable whose value is
8427 a shell command to run that prints the list of files to stdout).
8429 Either of these can be overridden to modify the behavior of
8430 @code{distcheck}. For instance, to disable this check completely, you
8438 @node The Types of Distributions
8439 @section The Types of Distributions
8441 Automake generates rules to provide archives of the project for
8442 distributions in various formats. Their targets are:
8445 @item @code{dist-bzip2}
8446 Generate a bzip2 tar archive of the distribution. bzip2 archives are
8447 frequently smaller than gzipped archives.
8450 @item @code{dist-gzip}
8451 Generate a gzip tar archive of the distribution.
8454 @item @code{dist-lzma}
8455 Generate an @samp{lzma} tar archive of the distribution. @command{lzma}
8456 archives are frequently smaller than @command{bzip2}-compressed archives.
8457 The @samp{lzma} format is obsolete, you should use the @samp{xz} format
8461 @item @code{dist-shar}
8462 Generate a shar archive of the distribution.
8465 @item @code{dist-xz}
8466 Generate an @samp{xz} tar archive of the distribution. @command{xz}
8467 archives are frequently smaller than @command{bzip2}-compressed archives.
8468 The @samp{xz} format displaces the obsolete @samp{lzma} format.
8471 @item @code{dist-zip}
8472 Generate a zip archive of the distribution.
8475 @item @code{dist-tarZ}
8476 Generate a compressed tar archive of
8481 The rule @code{dist} (and its historical synonym @code{dist-all}) will
8482 create archives in all the enabled formats, @ref{Options}. By
8483 default, only the @code{dist-gzip} target is hooked to @code{dist}.
8487 @chapter Support for test suites
8490 @cindex @code{make check}
8493 Automake supports three forms of test suites, the first two of which
8497 * Simple Tests:: Listing programs and scripts in @code{TESTS}
8498 * Simple Tests using parallel-tests:: More powerful test driver
8499 * DejaGnu Tests:: Interfacing with the external testing framework
8500 * Install Tests:: Running tests on installed packages
8504 @section Simple Tests
8506 If the variable @code{TESTS} is defined, its value is taken to be a
8507 list of programs or scripts to run in order to do the testing.
8508 Programs needing data files should look for them in @code{srcdir}
8509 (which is both an environment variable and a make variable) so they
8510 work when building in a separate directory (@pxref{Build Directories,
8511 , Build Directories , autoconf, The Autoconf Manual}), and in
8512 particular for the @code{distcheck} rule (@pxref{Checking the
8515 For each of the @code{TESTS}, the result of execution is printed along
8516 with the test name, where @code{PASS} denotes a successful test,
8517 @code{FAIL} denotes a failed test, @code{XFAIL} an expected failure,
8518 @code{XPASS} an unexpected pass for a test that is supposed to fail,
8519 and @code{SKIP} denotes a skipped test.
8521 @cindex Exit status 77, special interpretation
8523 The number of failures will be printed at the end of the run. If a
8524 given test program exits with a status of 77, then its result is ignored
8525 in the final count. This feature allows non-portable tests to be
8526 ignored in environments where they don't make sense.
8528 @vindex AM_COLOR_TESTS
8529 If the Automake option @code{color-tests} is used (@pxref{Options})
8530 and standard output is connected to a capable terminal, then the test
8531 results and the summary are colored appropriately. The user can disable
8532 colored output by setting the @command{make} variable
8533 @samp{AM_COLOR_TESTS=no}, or force colored output even without a connecting
8534 terminal with @samp{AM_COLOR_TESTS=always}.
8537 @vindex TESTS_ENVIRONMENT
8538 The variable @code{TESTS_ENVIRONMENT} can be used to set environment
8539 variables for the test run; the environment variable @env{srcdir} is
8540 set in the rule. If all your test programs are scripts, you can also
8541 set @code{TESTS_ENVIRONMENT} to an invocation of the shell (e.g.
8542 @samp{$(SHELL) -x} can be useful for debugging the tests), or any other
8543 interpreter. For instance the following setup is used by the Automake
8544 package to run four tests in Perl.
8546 TESTS_ENVIRONMENT = $(PERL) -Mstrict -I $(top_srcdir)/lib -w
8547 TESTS = Condition.pl DisjConditions.pl Version.pl Wrap.pl
8551 @cindex Tests, expected failure
8552 @cindex Expected test failure
8554 You may define the variable @code{XFAIL_TESTS} to a list of tests
8555 (usually a subset of @code{TESTS}) that are expected to fail. This will
8556 reverse the result of those tests.
8559 Automake ensures that each file listed in @code{TESTS} is built before
8560 any tests are run; you can list both source and derived programs (or
8561 scripts) in @code{TESTS}; the generated rule will look both in
8562 @code{srcdir} and @file{.}. For instance, you might want to run a C
8563 program as a test. To do this you would list its name in @code{TESTS}
8564 and also in @code{check_PROGRAMS}, and then specify it as you would
8567 Programs listed in @code{check_PROGRAMS} (and @code{check_LIBRARIES},
8568 @code{check_LTLIBRARIES}...) are only built during @code{make check},
8569 not during @code{make all}. You should list there any program needed
8570 by your tests that does not need to be built by @code{make all}. Note
8571 that @code{check_PROGRAMS} are @emph{not} automatically added to
8572 @code{TESTS} because @code{check_PROGRAMS} usually lists programs used
8573 by the tests, not the tests themselves. Of course you can set
8574 @code{TESTS = $(check_PROGRAMS)} if all your programs are test cases.
8577 @node Simple Tests using parallel-tests
8578 @section Simple Tests using @samp{parallel-tests}
8579 @cindex @option{parallel-tests}, Using
8581 The option @option{parallel-tests} (@pxref{Options}) enables a test
8582 suite driver that is mostly compatible to the simple test driver described
8583 in the previous section, but provides a few more features and slightly different
8584 semantics. It features concurrent execution of tests with @code{make -j},
8585 allows to specify inter-test dependencies, lazy reruns of tests that
8586 have not completed in a prior run, summary and verbose output in
8587 @samp{RST} (reStructuredText) and @samp{HTML} format, and hard errors
8588 for exceptional failures. Similar to the simple test driver,
8589 @code{TESTS_ENVIRONMENT}, @code{AM_COLOR_TESTS}, @code{XFAIL_TESTS}, and
8590 the @code{check_*} variables are honored, and the environment variable
8591 @env{srcdir} is set during test execution.
8593 This test driver is still experimental and may undergo changes in order
8594 to satisfy additional portability requirements.
8596 @vindex TEST_SUITE_LOG
8598 The driver operates by defining a set of @command{make} rules to create
8599 a summary log file, @code{TEST_SUITE_LOG}, which defaults to
8600 @file{test-suite.log} and requires a @file{.log} suffix. This file
8601 depends upon log files created for each single test program listed in
8602 @code{TESTS}, which in turn contain all output produced by the
8603 corresponding tests.
8605 @vindex TEST_EXTENSIONS
8607 Each log file is created when the corresponding test has completed.
8608 The set of log files is listed in the read-only variable
8609 @code{TEST_LOGS}, and defaults to @code{TESTS}, with the executable
8610 extension if any (@pxref{EXEEXT}), as well as any suffix listed in
8611 @code{TEST_EXTENSIONS} removed, and @file{.log} appended.
8612 @code{TEST_EXTENSIONS} defaults to @file{.test}. Results are undefined
8613 if a test file name ends in several concatenated suffixes.
8615 @vindex _LOG_COMPILE
8616 @vindex _LOG_COMPILER
8619 @vindex LOG_COMPILER
8621 @vindex @var{ext}_LOG_COMPILE
8622 @vindex @var{ext}_LOG_COMPILER
8623 @vindex @var{ext}_LOG_FLAGS
8624 @vindex AM_@var{ext}_LOG_FLAGS
8625 @vindex AM_LOG_FLAGS
8626 For tests that match an extension @code{.@var{ext}} listed in
8627 @code{TEST_EXTENSIONS}, you can provide a test driver using the variable
8628 @code{@var{ext}_LOG_COMPILER} (note the upper-case extension) and pass
8629 options in @code{AM_@var{ext}_LOG_FLAGS} and allow the user to pass
8630 options in @code{@var{ext}_LOG_FLAGS}. It will cause all tests with
8631 this extension to be called with this driver. For all tests without a
8632 registered extension, the variables @code{LOG_COMPILER},
8633 @code{AM_LOG_FLAGS}, and @code{LOG_FLAGS} may be used. For example,
8636 TESTS = foo.pl bar.py baz
8637 TEST_EXTENSIONS = .pl .py
8638 PL_LOG_COMPILER = $(PERL)
8639 AM_PL_LOG_FLAGS = -w
8640 PY_LOG_COMPILER = $(PYTHON)
8641 AM_PY_LOG_FLAGS = -v
8642 LOG_COMPILER = ./wrapper-script
8647 will invoke @samp{$(PERL) -w foo.pl}, @samp{$(PYTHON) -v bar.py},
8648 and @samp{./wrapper-script -d baz} to produce @file{foo.log},
8649 @file{bar.log}, and @file{baz.log}, respectively. The
8650 @samp{TESTS_ENVIRONMENT} variable is still expanded before the driver,
8651 but should be reserved for the user.
8654 As with the simple driver above, by default one status line is printed
8655 per completed test, and a short summary after the suite has completed.
8656 However, standard output and standard error of the test are redirected
8657 to a per-test log file, so that parallel execution does not produce
8658 intermingled output. The output from failed tests is collected in the
8659 @file{test-suite.log} file. If the variable @samp{VERBOSE} is set, this
8660 file is output after the summary. For best results, the tests should be
8661 verbose by default now.
8663 @trindex mostlyclean
8666 @vindex TEST_SUITE_HTML
8667 With @code{make check-html}, the log files may be converted from RST
8668 (reStructuredText, see @uref{http://docutils.sourceforge.net/@/rst.html})
8669 to HTML using @samp{RST2HTML}, which defaults to @command{rst2html} or
8670 @command{rst2html.py}. The variable @samp{TEST_SUITE_HTML} contains the
8671 set of converted log files. The log and HTML files are removed upon
8672 @code{make mostlyclean}.
8674 @vindex DISABLE_HARD_ERRORS
8675 @cindex Exit status 99, special interpretation
8677 Even in the presence of expected failures (see @code{XFAIL_TESTS}), there
8678 may be conditions under which a test outcome needs attention. For
8679 example, with test-driven development, you may write tests for features
8680 that you have not implemented yet, and thus mark these tests as expected
8681 to fail. However, you may still be interested in exceptional conditions,
8682 for example, tests that fail due to a segmentation violation or another
8683 error that is independent of the feature awaiting implementation.
8684 Tests can exit with an exit status of 99 to signal such a @emph{hard
8685 error}. Unless the variable @code{DISABLE_HARD_ERRORS} is set to a
8686 nonempty value, such tests will be counted as failed.
8688 By default, the test suite driver will run all tests, but there are
8689 several ways to limit the set of tests that are run:
8693 You can set the @code{TESTS} variable, similarly to how you can with
8694 the simple test driver from the previous section. For example, you can
8695 use a command like this to run only a subset of the tests:
8698 env TESTS="foo.test bar.test" make -e check
8702 You can set the @code{TEST_LOGS} variable. By default, this variable is
8703 computed at @command{make} run time from the value of @code{TESTS} as
8704 described above. For example, you can use the following:
8707 set x subset*.log; shift
8708 env TEST_LOGS="foo.log $*" make -e check
8712 @vindex RECHECK_LOGS
8713 @cindex lazy test execution
8714 By default, the test driver removes all old per-test log files before it
8715 starts running tests to regenerate them. The variable
8716 @code{RECHECK_LOGS} contains the set of log files which are removed.
8717 @code{RECHECK_LOGS} defaults to @code{TEST_LOGS}, which means all tests
8718 need to be rechecked. By overriding this variable, you can choose which
8719 tests need to be reconsidered. For example, you can lazily rerun only
8720 those tests which are outdated, i.e., older than their prerequisite test
8721 files, by setting this variable to the empty value:
8724 env RECHECK_LOGS= make -e check
8729 @trindex recheck-html
8730 You can ensure that all tests are rerun which have failed or passed
8731 unexpectedly, by running @code{make recheck} in the test directory.
8732 This convenience target will set @code{RECHECK_LOGS} appropriately
8733 before invoking the main test driver. The @code{recheck-html} target
8734 does the same as @code{recheck} but again converts the resulting log
8735 file in HTML format, like the @code{check-html} target.
8738 In order to guarantee an ordering between tests even with @code{make
8739 -j@var{N}}, dependencies between the corresponding log files may be
8740 specified through usual @command{make} dependencies. For example, the
8741 following snippet lets the test named @file{foo-execute.test} depend
8742 upon completion of the test @file{foo-compile.test}:
8745 TESTS = foo-compile.test foo-execute.test
8746 foo-execute.log: foo-compile.log
8750 Please note that this ordering ignores the @emph{results} of required
8751 tests, thus the test @file{foo-execute.test} is run even if the test
8752 @file{foo-compile.test} failed or was skipped beforehand. Further,
8753 please note that specifying such dependencies currently works only for
8754 tests that end in one of the suffixes listed in @code{TEST_EXTENSIONS}.
8756 Tests without such specified dependencies may be run concurrently with
8757 parallel @command{make -j@var{N}}, so be sure they are prepared for
8758 concurrent execution.
8761 The combination of lazy test execution and correct dependencies between
8762 tests and their sources may be exploited for efficient unit testing
8763 during development. To further speed up the edit-compile-test cycle, it
8764 may even be useful to specify compiled programs in @code{EXTRA_PROGRAMS}
8765 instead of with @code{check_PROGRAMS}, as the former allows intertwined
8766 compilation and test execution (but note that @code{EXTRA_PROGRAMS} are
8767 not cleaned automatically, @pxref{Uniform}).
8769 The variables @code{TESTS} and @code{XFAIL_TESTS} may contain
8770 conditional parts as well as configure substitutions. In the latter
8771 case, however, certain restrictions apply: substituted test names
8772 must end with a nonempty test suffix like @file{.test}, so that one of
8773 the inference rules generated by @command{automake} can apply. For
8774 literal test names, @command{automake} can generate per-target rules
8775 to avoid this limitation.
8777 Please note that it is currently not possible to use @code{$(srcdir)/}
8778 or @code{$(top_srcdir)/} in the @code{TESTS} variable. This technical
8779 limitation is necessary to avoid generating test logs in the source tree
8780 and has the unfortunate consequence that it is not possible to specify
8781 distributed tests that are themselves generated by means of explicit
8782 rules, in a way that is portable to all @command{make} implementations
8783 (@pxref{Make Target Lookup,,, autoconf, The Autoconf Manual}, the
8784 semantics of FreeBSD and OpenBSD @command{make} conflict with this).
8785 In case of doubt you may want to require to use GNU @command{make},
8786 or work around the issue with inference rules to generate the tests.
8790 @section DejaGnu Tests
8792 If @uref{ftp://ftp.gnu.org/gnu/dejagnu/, @command{dejagnu}} appears in
8793 @code{AUTOMAKE_OPTIONS}, then a @command{dejagnu}-based test suite is
8794 assumed. The variable @code{DEJATOOL} is a list of names that are
8795 passed, one at a time, as the @option{--tool} argument to
8796 @command{runtest} invocations; it defaults to the name of the package.
8798 The variable @code{RUNTESTDEFAULTFLAGS} holds the @option{--tool} and
8799 @option{--srcdir} flags that are passed to dejagnu by default; this can be
8800 overridden if necessary.
8801 @vindex RUNTESTDEFAULTFLAGS
8803 The variables @code{EXPECT} and @code{RUNTEST} can
8804 also be overridden to provide project-specific values. For instance,
8805 you will need to do this if you are testing a compiler toolchain,
8806 because the default values do not take into account host and target
8813 The contents of the variable @code{RUNTESTFLAGS} are passed to the
8814 @code{runtest} invocation. This is considered a ``user variable''
8815 (@pxref{User Variables}). If you need to set @command{runtest} flags in
8816 @file{Makefile.am}, you can use @code{AM_RUNTESTFLAGS} instead.
8817 @vindex RUNTESTFLAGS
8818 @vindex AM_RUNTESTFLAGS
8820 @cindex @file{site.exp}
8821 Automake will generate rules to create a local @file{site.exp} file,
8822 defining various variables detected by @command{configure}. This file
8823 is automatically read by DejaGnu. It is OK for the user of a package
8824 to edit this file in order to tune the test suite. However this is
8825 not the place where the test suite author should define new variables:
8826 this should be done elsewhere in the real test suite code.
8827 Especially, @file{site.exp} should not be distributed.
8829 For more information regarding DejaGnu test suites, see @ref{Top, , ,
8830 dejagnu, The DejaGnu Manual}.
8832 In either case, the testing is done via @samp{make check}.
8835 @section Install Tests
8837 The @code{installcheck} target is available to the user as a way to
8838 run any tests after the package has been installed. You can add tests
8839 to this by writing an @code{installcheck-local} rule.
8843 @chapter Rebuilding Makefiles
8844 @cindex rebuild rules
8846 Automake generates rules to automatically rebuild @file{Makefile}s,
8847 @file{configure}, and other derived files like @file{Makefile.in}.
8849 @acindex AM_MAINTAINER_MODE
8850 If you are using @code{AM_MAINTAINER_MODE} in @file{configure.ac}, then
8851 these automatic rebuilding rules are only enabled in maintainer mode.
8853 @vindex ACLOCAL_AMFLAGS
8854 Sometimes you need to run @command{aclocal} with an argument like
8855 @option{-I} to tell it where to find @file{.m4} files. Since
8856 sometimes @command{make} will automatically run @command{aclocal}, you
8857 need a way to specify these arguments. You can do this by defining
8858 @code{ACLOCAL_AMFLAGS}; this holds arguments that are passed verbatim
8859 to @command{aclocal}. This variable is only useful in the top-level
8862 @vindex CONFIG_STATUS_DEPENDENCIES
8863 @vindex CONFIGURE_DEPENDENCIES
8864 @cindex @file{version.sh}, example
8865 @cindex @file{version.m4}, example
8867 Sometimes it is convenient to supplement the rebuild rules for
8868 @file{configure} or @file{config.status} with additional dependencies.
8869 The variables @code{CONFIGURE_DEPENDENCIES} and
8870 @code{CONFIG_STATUS_DEPENDENCIES} can be used to list these extra
8871 dependencies. These variables should be defined in all
8872 @file{Makefile}s of the tree (because these two rebuild rules are
8873 output in all them), so it is safer and easier to @code{AC_SUBST} them
8874 from @file{configure.ac}. For instance, the following statement will
8875 cause @file{configure} to be rerun each time @file{version.sh} is
8878 AC_SUBST([CONFIG_STATUS_DEPENDENCIES], ['$(top_srcdir)/version.sh'])
8881 Note the @samp{$(top_srcdir)/} in the file name. Since this variable
8882 is to be used in all @file{Makefile}s, its value must be sensible at
8883 any level in the build hierarchy.
8885 Beware not to mistake @code{CONFIGURE_DEPENDENCIES} for
8886 @code{CONFIG_STATUS_DEPENDENCIES}.
8888 @code{CONFIGURE_DEPENDENCIES} adds dependencies to the
8889 @file{configure} rule, whose effect is to run @command{autoconf}. This
8890 variable should be seldom used, because @command{automake} already tracks
8891 @code{m4_include}d files. However it can be useful when playing
8892 tricky games with @code{m4_esyscmd} or similar non-recommendable
8893 macros with side effects.
8895 @code{CONFIG_STATUS_DEPENDENCIES} adds dependencies to the
8896 @file{config.status} rule, whose effect is to run @file{configure}.
8897 This variable should therefore carry any non-standard source that may
8898 be read as a side effect of running @command{configure}, like @file{version.sh}
8899 in the example above.
8901 Speaking of @file{version.sh} scripts, we recommend against them
8902 today. They are mainly used when the version of a package is updated
8903 automatically by a script (e.g., in daily builds). Here is what some
8904 old-style @file{configure.ac}s may look like:
8907 . $srcdir/version.sh
8908 AM_INIT_AUTOMAKE([name], $VERSION_NUMBER)
8912 Here, @file{version.sh} is a shell fragment that sets
8913 @code{VERSION_NUMBER}. The problem with this example is that
8914 @command{automake} cannot track dependencies (listing @file{version.sh}
8915 in @command{CONFIG_STATUS_DEPENDENCIES}, and distributing this file is up
8916 to the user), and that it uses the obsolete form of @code{AC_INIT} and
8917 @code{AM_INIT_AUTOMAKE}. Upgrading to the new syntax is not
8918 straightforward, because shell variables are not allowed in
8919 @code{AC_INIT}'s arguments. We recommend that @file{version.sh} be
8920 replaced by an M4 file that is included by @file{configure.ac}:
8922 m4_include([version.m4])
8923 AC_INIT([name], VERSION_NUMBER)
8928 Here @file{version.m4} could contain something like
8929 @samp{m4_define([VERSION_NUMBER], [1.2])}. The advantage of this
8930 second form is that @command{automake} will take care of the
8931 dependencies when defining the rebuild rule, and will also distribute
8932 the file automatically. An inconvenience is that @command{autoconf}
8933 will now be rerun each time the version number is bumped, when only
8934 @file{configure} had to be rerun in the previous setup.
8938 @chapter Changing Automake's Behavior
8940 Various features of Automake can be controlled by options. Except where
8941 noted otherwise, options can be specified in one of several ways: Most
8942 options can be applied on a per-@file{Makefile} basis when listed in a
8943 special @file{Makefile} variable named @code{AUTOMAKE_OPTIONS}. Some
8944 of these options only make sense when specified in the toplevel
8945 @file{Makefile.am} file. Options are applied globally to all processed
8946 @file{Makefile} files when listed in the first argument of
8947 @code{AM_INIT_AUTOMAKE} in @file{configure.ac}, and some options which
8948 require changes to the @command{configure} script can only be specified
8949 there. These are annotated below.
8951 Currently understood options are:
8952 @vindex AUTOMAKE_OPTIONS
8955 @item @option{gnits}
8957 @itemx @option{foreign}
8958 @itemx @option{cygnus}
8959 @cindex Option, @option{gnits}
8960 @cindex Option, @option{gnu}
8961 @cindex Option, @option{foreign}
8962 @cindex Option, @option{cygnus}
8968 Set the strictness as appropriate. The @option{gnits} option also
8969 implies options @option{readme-alpha} and @option{check-news}.
8971 @item @option{ansi2knr}
8972 @itemx @option{@var{path}/ansi2knr}
8973 @cindex Option, @option{ansi2knr}
8975 Turn on the obsolete de-ANSI-fication feature. @xref{ANSI}. If preceded by a
8976 path, the generated @file{Makefile.in} will look in the specified
8977 directory to find the @file{ansi2knr} program. The path should be a
8978 relative path to another directory in the same distribution (Automake
8979 currently does not check this).
8981 @item @option{check-news}
8982 @cindex Option, @option{check-news}
8984 Cause @samp{make dist} to fail unless the current version number appears
8985 in the first few lines of the @file{NEWS} file.
8987 @item @option{color-tests}
8988 @cindex Option, @option{color-tests}
8989 @opindex color-tests
8990 Cause output of the simple test suite (@pxref{Simple Tests}) to be
8991 colorized on capable terminals.
8993 @item @option{dejagnu}
8994 @cindex Option, @option{dejagnu}
8996 Cause @command{dejagnu}-specific rules to be generated. @xref{DejaGnu Tests}.
8998 @item @option{dist-bzip2}
8999 @cindex Option, @option{dist-bzip2}
9001 Hook @code{dist-bzip2} to @code{dist}.
9004 @item @option{dist-lzma}
9005 @cindex Option, @option{dist-lzma}
9007 Hook @code{dist-lzma} to @code{dist}. Obsoleted by @code{dist-xz}.
9010 @item @option{dist-shar}
9011 @cindex Option, @option{dist-shar}
9013 Hook @code{dist-shar} to @code{dist}.
9016 @item @option{dist-zip}
9017 @cindex Option, @option{dist-zip}
9019 Hook @code{dist-zip} to @code{dist}.
9022 @item @option{dist-tarZ}
9023 @cindex Option, @option{dist-tarZ}
9025 Hook @code{dist-tarZ} to @code{dist}.
9028 @item @option{filename-length-max=99}
9029 @cindex Option, @option{filename-length-max=99}
9030 @opindex filename-length-max=99
9031 Abort if file names longer than 99 characters are found during
9032 @samp{make dist}. Such long file names are generally considered not to
9033 be portable in tarballs. See the @option{tar-v7} and @option{tar-ustar}
9034 options below. This option should be used in the top-level
9035 @file{Makefile.am} or as an argument of @code{AM_INIT_AUTOMAKE} in
9036 @file{configure.ac}, it will be ignored otherwise. It will also be
9037 ignored in sub-packages of nested packages (@pxref{Subpackages}).
9039 @item @option{no-define}
9040 @cindex Option, @option{no-define}
9042 This option is meaningful only when passed as an argument to
9043 @code{AM_INIT_AUTOMAKE}. It will prevent the @code{PACKAGE} and
9044 @code{VERSION} variables from being @code{AC_DEFINE}d.
9046 @item @option{no-dependencies}
9047 @cindex Option, @option{no-dependencies}
9048 @opindex no-dependencies
9049 This is similar to using @option{--ignore-deps} on the command line,
9050 but is useful for those situations where you don't have the necessary
9051 bits to make automatic dependency tracking work
9052 (@pxref{Dependencies}). In this case the effect is to effectively
9053 disable automatic dependency tracking.
9055 @item @option{no-dist}
9056 @cindex Option, @option{no-dist}
9058 Don't emit any code related to @code{dist} target. This is useful
9059 when a package has its own method for making distributions.
9061 @item @option{no-dist-gzip}
9062 @cindex Option, @option{no-dist-gzip}
9063 @opindex no-dist-gzip
9064 Do not hook @code{dist-gzip} to @code{dist}.
9065 @trindex no-dist-gzip
9067 @item @option{no-exeext}
9068 @cindex Option, @option{no-exeext}
9070 If your @file{Makefile.am} defines a rule for target @code{foo}, it
9071 will override a rule for a target named @samp{foo$(EXEEXT)}. This is
9072 necessary when @code{EXEEXT} is found to be empty. However, by
9073 default @command{automake} will generate an error for this use. The
9074 @option{no-exeext} option will disable this error. This is intended for
9075 use only where it is known in advance that the package will not be
9076 ported to Windows, or any other operating system using extensions on
9079 @item @option{no-installinfo}
9080 @cindex Option, @option{no-installinfo}
9081 @opindex no-installinfo
9082 The generated @file{Makefile.in} will not cause info pages to be built
9083 or installed by default. However, @code{info} and @code{install-info}
9084 targets will still be available. This option is disallowed at
9085 @option{gnu} strictness and above.
9087 @trindex install-info
9089 @item @option{no-installman}
9090 @cindex Option, @option{no-installman}
9091 @opindex no-installman
9092 The generated @file{Makefile.in} will not cause man pages to be
9093 installed by default. However, an @code{install-man} target will still
9094 be available for optional installation. This option is disallowed at
9095 @option{gnu} strictness and above.
9096 @trindex install-man
9098 @item @option{nostdinc}
9099 @cindex Option, @option{nostdinc}
9101 This option can be used to disable the standard @option{-I} options that
9102 are ordinarily automatically provided by Automake.
9104 @item @option{no-texinfo.tex}
9105 @cindex Option, @option{no-texinfo.tex}
9106 @opindex no-texinfo.tex
9107 Don't require @file{texinfo.tex}, even if there are texinfo files in
9110 @item @option{parallel-tests}
9111 @cindex Option, @option{parallel-tests}
9112 @opindex parallel-tests
9113 Enable test suite driver for @code{TESTS} that can run tests in parallel
9114 (@pxref{Simple Tests using parallel-tests}, for more information).
9116 @item @option{readme-alpha}
9117 @cindex Option, @option{readme-alpha}
9118 @opindex readme-alpha
9119 If this release is an alpha release, and the file @file{README-alpha}
9120 exists, then it will be added to the distribution. If this option is
9121 given, version numbers are expected to follow one of two forms. The
9122 first form is @samp{@var{major}.@var{minor}.@var{alpha}}, where each
9123 element is a number; the final period and number should be left off for
9124 non-alpha releases. The second form is
9125 @samp{@var{major}.@var{minor}@var{alpha}}, where @var{alpha} is a
9126 letter; it should be omitted for non-alpha releases.
9128 @item @option{silent-rules}
9129 @cindex Option, @option{silent-rules}
9130 @opindex silent-rules
9131 Enable less verbose build rules. This can be used to let build rules
9132 output a status line of the form
9135 GEN @var{output-file}
9139 instead of printing the command that will be executed to update
9140 @var{output-file}. It can also silence @command{libtool} output.
9142 To enable less verbose build rules, both the developer and the user
9143 of the package have to take a number of steps. The developer needs
9144 to do either of the following:
9148 Add the @option{silent-rules} option as argument to @code{AM_INIT_AUTOMAKE}.
9150 Call the @code{AM_SILENT_RULES} macro from within the @file{configure.ac}
9154 It is not possible to instead specify @option{silent-rules} in a
9155 @file{Makefile.am} file.
9157 @cindex default verbosity for silent-rules
9158 If the developer has done either of the above, then the user of the
9159 package may influence the verbosity at @command{configure} run time as
9160 well as at @command{make} run time:
9164 @opindex --enable-silent-rules
9165 @opindex --disable-silent-rules
9166 Passing @option{--enable-silent-rules} to @command{configure} will cause
9167 build rules to be less verbose; the option @option{--disable-silent-rules}
9168 is the default and will cause normal verbose output.
9171 At @command{make} run time, the default chosen at @command{configure}
9172 time may be overridden: @code{make V=1} will produce verbose output,
9173 @code{make V=0} less verbose output.
9176 For portability to different @command{make} implementations, package authors
9177 are advised to not set the variable @code{V} inside the @file{Makefile.am}
9178 file, to allow the user to override the value for subdirectories as well.
9180 The current implementation of this feature relies on a non-POSIX, but in
9181 practice rather widely supported @file{Makefile} construct of nested
9182 variable expansion @samp{$(@var{var1}$(V))}. Do not use the
9183 @option{silent-rules} option if your package needs to build with
9184 @command{make} implementations that do not support it. The
9185 @option{silent-rules} option turns off warnings about recursive variable
9186 expansion, which are in turn enabled by @option{-Wportability}
9187 (@pxref{Invoking Automake}).
9189 @vindex @code{AM_V_GEN}
9190 @vindex @code{AM_V_at}
9191 @vindex @code{AM_DEFAULT_VERBOSITY}
9192 To extend the silent mode to your own rules, you have two choices:
9196 You can use the predefined variable @code{AM_V_GEN} as a prefix to
9197 commands that should output a status line in silent mode, and
9198 @code{AM_V_at} as a prefix to commands that should not output anything
9199 in silent mode. When output is to be verbose, both of these variables
9200 will expand to the empty string.
9202 You can add your own variables, so strings of your own choice are shown.
9203 The following snippet shows how you would define your own equivalent of
9207 pkg_verbose = $(pkg_verbose_$(V))
9208 pkg_verbose_ = $(pkg_verbose_$(AM_DEFAULT_VERBOSITY))
9209 pkg_verbose_0 = @@echo GEN $@@;
9212 $(pkg_verbose)cp $(srcdir)/foo.in $@@
9217 @item @option{std-options}
9218 @cindex Options, @option{std-options}
9219 @cindex @samp{make installcheck}, testing @option{--help} and @option{--version}
9220 @cindex @option{--help} check
9221 @cindex @option{--version} check
9222 @opindex std-options
9224 Make the @code{installcheck} rule check that installed scripts and
9225 programs support the @option{--help} and @option{--version} options.
9226 This also provides a basic check that the program's
9227 run-time dependencies are satisfied after installation.
9229 @vindex AM_INSTALLCHECK_STD_OPTIONS_EXEMPT
9230 In a few situations, programs (or scripts) have to be exempted from this
9231 test. For instance, @command{false} (from GNU coreutils) is never
9232 successful, even for @option{--help} or @option{--version}. You can list
9233 such programs in the variable @code{AM_INSTALLCHECK_STD_OPTIONS_EXEMPT}.
9234 Programs (not scripts) listed in this variable should be suffixed by
9235 @samp{$(EXEEXT)} for the sake of Win32 or OS/2. For instance, suppose we
9236 build @file{false} as a program but @file{true.sh} as a script, and that
9237 neither of them support @option{--help} or @option{--version}:
9240 AUTOMAKE_OPTIONS = std-options
9241 bin_PROGRAMS = false ...
9242 bin_SCRIPTS = true.sh ...
9243 AM_INSTALLCHECK_STD_OPTIONS_EXEMPT = false$(EXEEXT) true.sh
9246 @item @option{subdir-objects}
9247 @cindex Options, @option{subdir-objects}
9248 @opindex subdir-objects
9249 If this option is specified, then objects are placed into the
9250 subdirectory of the build directory corresponding to the subdirectory of
9251 the source file. For instance, if the source file is
9252 @file{subdir/file.cxx}, then the output file would be
9253 @file{subdir/file.o}.
9255 In order to use this option with C sources, you should add
9256 @code{AM_PROG_CC_C_O} to @file{configure.ac}.
9258 @anchor{tar-formats}
9259 @item @option{tar-v7}
9260 @itemx @option{tar-ustar}
9261 @itemx @option{tar-pax}
9262 @cindex Option, @option{tar-v7}
9263 @cindex Option, @option{tar-ustar}
9264 @cindex Option, @option{tar-pax}
9265 @cindex @command{tar} formats
9266 @cindex v7 @command{tar} format
9267 @cindex ustar format
9273 These three mutually exclusive options select the tar format to use
9274 when generating tarballs with @samp{make dist}. (The tar file created
9275 is then compressed according to the set of @option{no-dist-gzip},
9276 @option{dist-bzip2}, @option{dist-xz} and @option{dist-tarZ} options in use.)
9278 These options must be passed as arguments to @code{AM_INIT_AUTOMAKE}
9279 (@pxref{Macros}) because they can require additional configure checks.
9280 Automake will complain if it sees such options in an
9281 @code{AUTOMAKE_OPTIONS} variable.
9283 @option{tar-v7} selects the old V7 tar format. This is the historical
9284 default. This antiquated format is understood by all tar
9285 implementations and supports file names with up to 99 characters. When
9286 given longer file names some tar implementations will diagnose the
9287 problem while other will generate broken tarballs or use non-portable
9288 extensions. Furthermore, the V7 format cannot store empty
9289 directories. When using this format, consider using the
9290 @option{filename-length-max=99} option to catch file names too long.
9292 @option{tar-ustar} selects the ustar format defined by POSIX
9293 1003.1-1988. This format is believed to be old enough to be portable.
9294 It fully supports empty directories. It can store file names with up
9295 to 256 characters, provided that the file name can be split at
9296 directory separator in two parts, first of them being at most 155
9297 bytes long. So, in most cases the maximum file name length will be
9298 shorter than 256 characters. However you may run against broken tar
9299 implementations that incorrectly handle file names longer than 99
9300 characters (please report them to @email{@value{PACKAGE_BUGREPORT}} so we
9301 can document this accurately).
9303 @option{tar-pax} selects the new pax interchange format defined by POSIX
9304 1003.1-2001. It does not limit the length of file names. However,
9305 this format is very young and should probably be restricted to
9306 packages that target only very modern platforms. There are moves to
9307 change the pax format in an upward-compatible way, so this option may
9308 refer to a more recent version in the future.
9310 @xref{Formats, , Controlling the Archive Format, tar, GNU Tar}, for
9311 further discussion about tar formats.
9313 @command{configure} knows several ways to construct these formats. It
9314 will not abort if it cannot find a tool up to the task (so that the
9315 package can still be built), but @samp{make dist} will fail.
9318 @cindex Option, @var{version}
9319 A version number (e.g., @samp{0.30}) can be specified. If Automake is not
9320 newer than the version specified, creation of the @file{Makefile.in}
9323 @item @option{-W@var{category}} or @option{--warnings=@var{category}}
9324 @cindex Option, warnings
9325 @cindex Option, @option{-W@var{category}}
9326 @cindex Option, @option{--warnings=@var{category}}
9327 These options behave exactly like their command-line counterpart
9328 (@pxref{Invoking Automake}). This allows you to enable or disable some
9329 warning categories on a per-file basis. You can also setup some warnings
9330 for your entire project; for instance, try @samp{AM_INIT_AUTOMAKE([-Wall])}
9331 in your @file{configure.ac}.
9335 Unrecognized options are diagnosed by @command{automake}.
9337 If you want an option to apply to all the files in the tree, you can use
9338 the @code{AM_INIT_AUTOMAKE} macro in @file{configure.ac}.
9343 @chapter Miscellaneous Rules
9345 There are a few rules and variables that didn't fit anywhere else.
9348 * Tags:: Interfacing to etags and mkid
9349 * Suffixes:: Handling new file extensions
9350 * Multilibs:: Support for multilibs.
9355 @section Interfacing to @command{etags}
9357 @cindex @file{TAGS} support
9359 Automake will generate rules to generate @file{TAGS} files for use with
9360 GNU Emacs under some circumstances.
9363 If any C, C++ or Fortran 77 source code or headers are present, then
9364 @code{tags} and @code{TAGS} rules will be generated for the directory.
9365 All files listed using the @code{_SOURCES}, @code{_HEADERS}, and
9366 @code{_LISP} primaries will be used to generate tags. Note that
9367 generated source files that are not distributed must be declared in
9368 variables like @code{nodist_noinst_HEADERS} or
9369 @code{nodist_@var{prog}_SOURCES} or they will be ignored.
9371 A @code{tags} rule will be output at the topmost directory of a
9372 multi-directory package. When run from this topmost directory,
9373 @samp{make tags} will generate a @file{TAGS} file that includes by
9374 reference all @file{TAGS} files from subdirectories.
9376 The @code{tags} rule will also be generated if the variable
9377 @code{ETAGS_ARGS} is defined. This variable is intended for use in
9378 directories that contain taggable source that @command{etags} does
9379 not understand. The user can use the @code{ETAGSFLAGS} to pass
9380 additional flags to @command{etags}; @code{AM_ETAGSFLAGS} is also
9381 available for use in @file{Makefile.am}.
9384 @vindex AM_ETAGSFLAGS
9386 Here is how Automake generates tags for its source, and for nodes in its
9390 ETAGS_ARGS = automake.in --lang=none \
9391 --regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi
9394 If you add file names to @code{ETAGS_ARGS}, you will probably also
9395 want to define @code{TAGS_DEPENDENCIES}. The contents of this variable
9396 are added directly to the dependencies for the @code{tags} rule.
9397 @vindex TAGS_DEPENDENCIES
9399 Automake also generates a @code{ctags} rule that can be used to
9400 build @command{vi}-style @file{tags} files. The variable @code{CTAGS}
9401 is the name of the program to invoke (by default @command{ctags});
9402 @code{CTAGSFLAGS} can be used by the user to pass additional flags,
9403 and @code{AM_CTAGSFLAGS} can be used by the @file{Makefile.am}.
9405 Automake will also generate an @code{ID} rule that will run
9406 @command{mkid} on the source. This is only supported on a
9407 directory-by-directory basis.
9410 Finally, Automake also emits rules to support the
9411 @uref{http://www.gnu.org/software/global/, GNU Global Tags program}.
9412 The @code{GTAGS} rule runs Global Tags and puts the
9413 result in the top build directory. The variable @code{GTAGS_ARGS}
9414 holds arguments that are passed to @command{gtags}.
9419 @section Handling new file extensions
9421 @cindex Adding new @code{SUFFIXES}
9422 @cindex @code{SUFFIXES}, adding
9425 It is sometimes useful to introduce a new implicit rule to handle a file
9426 type that Automake does not know about.
9428 For instance, suppose you had a compiler that could compile @file{.foo}
9429 files to @file{.o} files. You would simply define a suffix rule for
9437 Then you could directly use a @file{.foo} file in a @code{_SOURCES}
9438 variable and expect the correct results:
9442 doit_SOURCES = doit.foo
9445 This was the simpler and more common case. In other cases, you will
9446 have to help Automake to figure out which extensions you are defining your
9447 suffix rule for. This usually happens when your extension does not
9448 start with a dot. Then, all you have to do is to put a list of new
9449 suffixes in the @code{SUFFIXES} variable @strong{before} you define your
9452 For instance, the following definition prevents Automake from misinterpreting
9453 the @samp{.idlC.cpp:} rule as an attempt to transform @file{.idlC} files into
9457 SUFFIXES = .idl C.cpp
9462 As you may have noted, the @code{SUFFIXES} variable behaves like the
9463 @code{.SUFFIXES} special target of @command{make}. You should not touch
9464 @code{.SUFFIXES} yourself, but use @code{SUFFIXES} instead and let
9465 Automake generate the suffix list for @code{.SUFFIXES}. Any given
9466 @code{SUFFIXES} go at the start of the generated suffixes list, followed
9467 by Automake generated suffixes not already in the list.
9470 @section Support for Multilibs
9472 Automake has support for an obscure feature called multilibs. A
9473 @dfn{multilib} is a library that is built for multiple different ABIs
9474 at a single time; each time the library is built with a different target
9475 flag combination. This is only useful when the library is intended to
9476 be cross-compiled, and it is almost exclusively used for compiler
9479 The multilib support is still experimental. Only use it if you are
9480 familiar with multilibs and can debug problems you might encounter.
9487 @cindex Including @file{Makefile} fragment
9488 @cindex @file{Makefile} fragment, including
9490 Automake supports an @code{include} directive that can be used to
9491 include other @file{Makefile} fragments when @command{automake} is run.
9492 Note that these fragments are read and interpreted by @command{automake},
9493 not by @command{make}. As with conditionals, @command{make} has no idea that
9494 @code{include} is in use.
9496 There are two forms of @code{include}:
9499 @item include $(srcdir)/file
9500 Include a fragment that is found relative to the current source
9503 @item include $(top_srcdir)/file
9504 Include a fragment that is found relative to the top source directory.
9507 Note that if a fragment is included inside a conditional, then the
9508 condition applies to the entire contents of that fragment.
9510 Makefile fragments included this way are always distributed because
9511 they are needed to rebuild @file{Makefile.in}.
9514 @chapter Conditionals
9516 @cindex Conditionals
9518 Automake supports a simple type of conditionals.
9520 These conditionals are not the same as conditionals in
9521 GNU Make. Automake conditionals are checked at configure time by the
9522 @file{configure} script, and affect the translation from
9523 @file{Makefile.in} to @file{Makefile}. They are based on options passed
9524 to @file{configure} and on results that @file{configure} has discovered
9525 about the host system. GNU Make conditionals are checked at @command{make}
9526 time, and are based on variables passed to the make program or defined
9527 in the @file{Makefile}.
9529 Automake conditionals will work with any make program.
9532 * Usage of Conditionals:: Declaring conditional content
9533 * Limits of Conditionals:: Enclosing complete statements
9536 @node Usage of Conditionals
9537 @section Usage of Conditionals
9539 @acindex AM_CONDITIONAL
9540 Before using a conditional, you must define it by using
9541 @code{AM_CONDITIONAL} in the @file{configure.ac} file (@pxref{Macros}).
9543 @defmac AM_CONDITIONAL (@var{conditional}, @var{condition})
9544 The conditional name, @var{conditional}, should be a simple string
9545 starting with a letter and containing only letters, digits, and
9546 underscores. It must be different from @samp{TRUE} and @samp{FALSE}
9547 that are reserved by Automake.
9549 The shell @var{condition} (suitable for use in a shell @code{if}
9550 statement) is evaluated when @command{configure} is run. Note that you
9551 must arrange for @emph{every} @code{AM_CONDITIONAL} to be invoked every
9552 time @command{configure} is run. If @code{AM_CONDITIONAL} is run
9553 conditionally (e.g., in a shell @code{if} statement), then the result
9554 will confuse @command{automake}.
9557 @cindex @option{--enable-debug}, example
9558 @cindex Example conditional @option{--enable-debug}
9559 @cindex Conditional example, @option{--enable-debug}
9561 Conditionals typically depend upon options that the user provides to
9562 the @command{configure} script. Here is an example of how to write a
9563 conditional that is true if the user uses the @option{--enable-debug}
9567 AC_ARG_ENABLE([debug],
9568 [ --enable-debug Turn on debugging],
9569 [case "$@{enableval@}" in
9572 *) AC_MSG_ERROR([bad value $@{enableval@} for --enable-debug]) ;;
9573 esac],[debug=false])
9574 AM_CONDITIONAL([DEBUG], [test x$debug = xtrue])
9577 Here is an example of how to use that conditional in @file{Makefile.am}:
9589 noinst_PROGRAMS = $(DBG)
9592 This trivial example could also be handled using @code{EXTRA_PROGRAMS}
9593 (@pxref{Conditional Programs}).
9595 You may only test a single variable in an @code{if} statement, possibly
9596 negated using @samp{!}. The @code{else} statement may be omitted.
9597 Conditionals may be nested to any depth. You may specify an argument to
9598 @code{else} in which case it must be the negation of the condition used
9599 for the current @code{if}. Similarly you may specify the condition
9600 that is closed on the @code{endif} line:
9611 Unbalanced conditions are errors. The @code{if}, @code{else}, and
9612 @code{endif} statements should not be indented, i.e., start on column
9615 The @code{else} branch of the above two examples could be omitted,
9616 since assigning the empty string to an otherwise undefined variable
9617 makes no difference.
9620 In order to allow access to the condition registered by
9621 @code{AM_CONDITIONAL} inside @file{configure.ac}, and to allow
9622 conditional @code{AC_CONFIG_FILES}, @code{AM_COND_IF} may be used:
9624 @defmac AM_COND_IF (@var{conditional}, @ovar{if-true}, @ovar{if-false})
9625 If @var{conditional} is fulfilled, execute @var{if-true}, otherwise
9626 execute @var{if-false}. If either branch contains @code{AC_CONFIG_FILES},
9627 it will cause @command{automake} to output the rules for the respective
9628 files only for the given condition.
9631 @code{AM_COND_IF} macros may be nested when m4 quotation is used
9632 properly (@pxref{M4 Quotation, ,, autoconf, The Autoconf Manual}).
9634 @cindex Example conditional @code{AC_CONFIG_FILES}
9635 @cindex @code{AC_CONFIG_FILES}, conditional
9637 Here is an example of how to define a conditional config file:
9640 AM_CONDITIONAL([SHELL_WRAPPER], [test "x$with_wrapper" = xtrue])
9641 AM_COND_IF([SHELL_WRAPPER],
9642 [AC_CONFIG_FILES([wrapper:wrapper.in])])
9645 @node Limits of Conditionals
9646 @section Limits of Conditionals
9648 Conditionals should enclose complete statements like variables or
9649 rules definitions. Automake cannot deal with conditionals used inside
9650 a variable definition, for instance, and is not even able to diagnose
9651 this situation. The following example would not work:
9654 # This syntax is not understood by Automake
9663 However the intended definition of @code{AM_CPPFLAGS} can be achieved
9668 DEBUGFLAGS = -DDEBUG
9670 AM_CPPFLAGS = -DFEATURE_A $(DEBUGFLAGS) -DFEATURE_B
9677 AM_CPPFLAGS = -DFEATURE_A
9679 AM_CPPFLAGS += -DDEBUG
9681 AM_CPPFLAGS += -DFEATURE_B
9684 More details and examples of conditionals are described alongside
9685 various Automake features in this manual (@pxref{Conditional
9686 Subdirectories}, @pxref{Conditional Sources}, @pxref{Conditional
9687 Programs}, @pxref{Conditional Libtool Libraries}, @pxref{Conditional
9691 @chapter The effect of @option{--gnu} and @option{--gnits}
9693 @cindex @option{--gnu}, required files
9694 @cindex @option{--gnu}, complete description
9696 The @option{--gnu} option (or @option{gnu} in the
9697 @code{AUTOMAKE_OPTIONS} variable) causes @command{automake} to check
9702 The files @file{INSTALL}, @file{NEWS}, @file{README}, @file{AUTHORS},
9703 and @file{ChangeLog}, plus one of @file{COPYING.LIB}, @file{COPYING.LESSER}
9704 or @file{COPYING}, are required at the topmost directory of the package.
9706 If the @option{--add-missing} option is given, @command{automake} will
9707 add a generic version of the @file{INSTALL} file as well as the
9708 @file{COPYING} file containing the text of the current version of the
9709 GNU General Public License existing at the time of this Automake release
9710 (version 3 as this is written, @uref{http://www.gnu.org/@/copyleft/@/gpl.html}).
9711 However, an existing @file{COPYING} file will never be overwritten by
9715 The options @option{no-installman} and @option{no-installinfo} are
9719 Note that this option will be extended in the future to do even more
9720 checking; it is advisable to be familiar with the precise requirements
9721 of the GNU standards. Also, @option{--gnu} can require certain
9722 non-standard GNU programs to exist for use by various maintainer-only
9723 rules; for instance, in the future @command{pathchk} might be required for
9726 @cindex @option{--gnits}, complete description
9728 The @option{--gnits} option does everything that @option{--gnu} does, and
9729 checks the following as well:
9733 @samp{make installcheck} will check to make sure that the @option{--help}
9734 and @option{--version} really print a usage message and a version string,
9735 respectively. This is the @option{std-options} option (@pxref{Options}).
9738 @samp{make dist} will check to make sure the @file{NEWS} file has been
9739 updated to the current version.
9742 @code{VERSION} is checked to make sure its format complies with Gnits
9744 @c FIXME xref when standards are finished
9747 @cindex @file{README-alpha}
9748 If @code{VERSION} indicates that this is an alpha release, and the file
9749 @file{README-alpha} appears in the topmost directory of a package, then
9750 it is included in the distribution. This is done in @option{--gnits}
9751 mode, and no other, because this mode is the only one where version
9752 number formats are constrained, and hence the only mode where Automake
9753 can automatically determine whether @file{README-alpha} should be
9757 The file @file{THANKS} is required.
9762 @chapter The effect of @option{--cygnus}
9764 @cindex @option{cygnus} strictness
9766 Some packages, notably GNU GCC and GNU gdb, have a build environment
9767 originally written at Cygnus Support (subsequently renamed Cygnus
9768 Solutions, and then later purchased by Red Hat). Packages with this
9769 ancestry are sometimes referred to as ``Cygnus'' trees.
9771 A Cygnus tree has slightly different rules for how a
9772 @file{Makefile.in} is to be constructed. Passing @option{--cygnus} to
9773 @command{automake} will cause any generated @file{Makefile.in} to
9774 comply with Cygnus rules.
9776 Here are the precise effects of @option{--cygnus}:
9780 Info files are always created in the build directory, and not in the
9784 @file{texinfo.tex} is not required if a Texinfo source file is
9785 specified. The assumption is that the file will be supplied, but in a
9786 place that Automake cannot find. This assumption is an artifact of how
9787 Cygnus packages are typically bundled.
9790 @samp{make dist} is not supported, and the rules for it are not
9791 generated. Cygnus-style trees use their own distribution mechanism.
9794 Certain tools will be searched for in the build tree as well as in the
9795 user's @env{PATH}. These tools are @command{runtest}, @command{expect},
9796 @command{makeinfo} and @command{texi2dvi}.
9799 @option{--foreign} is implied.
9802 The options @option{no-installinfo} and @option{no-dependencies} are
9806 The macros @code{AM_MAINTAINER_MODE} and @code{AM_CYGWIN32} are
9810 The @code{check} target doesn't depend on @code{all}.
9813 GNU maintainers are advised to use @option{gnu} strictness in preference
9814 to the special Cygnus mode. Some day, perhaps, the differences between
9815 Cygnus trees and GNU trees will disappear (for instance, as GCC is made
9816 more standards compliant). At that time the special Cygnus mode will be
9821 @chapter When Automake Isn't Enough
9823 In some situations, where Automake is not up to one task, one has to
9824 resort to handwritten rules or even handwritten @file{Makefile}s.
9827 * Extending:: Adding new rules or overriding existing ones.
9828 * Third-Party Makefiles:: Integrating Non-Automake @file{Makefile}s.
9832 @section Extending Automake Rules
9834 With some minor exceptions (for example @code{_PROGRAMS} variables,
9835 @code{TESTS}, or @code{XFAIL_TESTS}) being rewritten to append
9836 @samp{$(EXEEXT)}), the contents of a @file{Makefile.am} is copied to
9837 @file{Makefile.in} verbatim.
9839 @cindex copying semantics
9841 These copying semantics mean that many problems can be worked around
9842 by simply adding some @command{make} variables and rules to
9843 @file{Makefile.am}. Automake will ignore these additions.
9845 @cindex conflicting definitions
9846 @cindex rules, conflicting
9847 @cindex variables, conflicting
9848 @cindex definitions, conflicts
9850 Since a @file{Makefile.in} is built from data gathered from three
9851 different places (@file{Makefile.am}, @file{configure.ac}, and
9852 @command{automake} itself), it is possible to have conflicting
9853 definitions of rules or variables. When building @file{Makefile.in}
9854 the following priorities are respected by @command{automake} to ensure
9855 the user always has the last word:
9859 User defined variables in @file{Makefile.am} have priority over
9860 variables @code{AC_SUBST}ed from @file{configure.ac}, and
9861 @code{AC_SUBST}ed variables have priority over
9862 @command{automake}-defined variables.
9864 As far as rules are concerned, a user-defined rule overrides any
9865 @command{automake}-defined rule for the same target.
9868 @cindex overriding rules
9869 @cindex overriding semantics
9870 @cindex rules, overriding
9872 These overriding semantics make it possible to fine tune some default
9873 settings of Automake, or replace some of its rules. Overriding
9874 Automake rules is often inadvisable, particularly in the topmost
9875 directory of a package with subdirectories. The @option{-Woverride}
9876 option (@pxref{Invoking Automake}) comes in handy to catch overridden
9879 Note that Automake does not make any distinction between rules with
9880 commands and rules that only specify dependencies. So it is not
9881 possible to append new dependencies to an @command{automake}-defined
9882 target without redefining the entire rule.
9884 @cindex @option{-local} targets
9885 @cindex local targets
9887 However, various useful targets have a @samp{-local} version you can
9888 specify in your @file{Makefile.am}. Automake will supplement the
9889 standard target with these user-supplied targets.
9904 @trindex check-local
9906 @trindex install-data
9907 @trindex install-data-local
9908 @trindex install-dvi
9909 @trindex install-dvi-local
9910 @trindex install-exec
9911 @trindex install-exec-local
9912 @trindex install-html
9913 @trindex install-html-local
9914 @trindex install-info
9915 @trindex install-info-local
9916 @trindex install-pdf
9917 @trindex install-pdf-local
9919 @trindex install-ps-local
9921 @trindex uninstall-local
9922 @trindex mostlyclean
9923 @trindex mostlyclean-local
9925 @trindex clean-local
9927 @trindex distclean-local
9928 @trindex installdirs
9929 @trindex installdirs-local
9930 @trindex installcheck
9931 @trindex installcheck-local
9933 The targets that support a local version are @code{all}, @code{info},
9934 @code{dvi}, @code{ps}, @code{pdf}, @code{html}, @code{check},
9935 @code{install-data}, @code{install-dvi}, @code{install-exec},
9936 @code{install-html}, @code{install-info}, @code{install-pdf},
9937 @code{install-ps}, @code{uninstall}, @code{installdirs},
9938 @code{installcheck} and the various @code{clean} targets
9939 (@code{mostlyclean}, @code{clean}, @code{distclean}, and
9940 @code{maintainer-clean}).
9942 Note that there are no @code{uninstall-exec-local} or
9943 @code{uninstall-data-local} targets; just use @code{uninstall-local}.
9944 It doesn't make sense to uninstall just data or just executables.
9946 For instance, here is one way to erase a subdirectory during
9947 @samp{make clean} (@pxref{Clean}).
9954 You may be tempted to use @code{install-data-local} to install a file
9955 to some hard-coded location, but you should avoid this
9956 (@pxref{Hard-Coded Install Paths}).
9958 With the @code{-local} targets, there is no particular guarantee of
9959 execution order; typically, they are run early, but with parallel
9960 make, there is no way to be sure of that.
9962 @cindex @option{-hook} targets
9963 @cindex hook targets
9964 @trindex install-data-hook
9965 @trindex install-exec-hook
9966 @trindex uninstall-hook
9969 In contrast, some rules also have a way to run another rule, called a
9970 @dfn{hook}; hooks are always executed after the main rule's work is done.
9971 The hook is named after the principal target, with @samp{-hook} appended.
9972 The targets allowing hooks are @code{install-data},
9973 @code{install-exec}, @code{uninstall}, @code{dist}, and
9976 For instance, here is how to create a hard link to an installed program:
9980 ln $(DESTDIR)$(bindir)/program$(EXEEXT) \
9981 $(DESTDIR)$(bindir)/proglink$(EXEEXT)
9984 Although cheaper and more portable than symbolic links, hard links
9985 will not work everywhere (for instance, OS/2 does not have
9986 @command{ln}). Ideally you should fall back to @samp{cp -p} when
9987 @command{ln} does not work. An easy way, if symbolic links are
9988 acceptable to you, is to add @code{AC_PROG_LN_S} to
9989 @file{configure.ac} (@pxref{Particular Programs, , Particular Program
9990 Checks, autoconf, The Autoconf Manual}) and use @samp{$(LN_S)} in
9993 @cindex versioned binaries, installing
9994 @cindex installing versioned binaries
9995 @cindex @code{LN_S} example
9996 For instance, here is how you could install a versioned copy of a
9997 program using @samp{$(LN_S)}:
10001 cd $(DESTDIR)$(bindir) && \
10002 mv -f prog$(EXEEXT) prog-$(VERSION)$(EXEEXT) && \
10003 $(LN_S) prog-$(VERSION)$(EXEEXT) prog$(EXEEXT)
10006 Note that we rename the program so that a new version will erase the
10007 symbolic link, not the real binary. Also we @command{cd} into the
10008 destination directory in order to create relative links.
10010 When writing @code{install-exec-hook} or @code{install-data-hook},
10011 please bear in mind that the exec/data distinction is based on the
10012 installation directory, not on the primary used (@pxref{The Two Parts of
10013 Install}). So a @code{foo_SCRIPTS} will be installed by
10014 @code{install-data}, and a @code{barexec_SCRIPTS} will be installed by
10015 @code{install-exec}. You should define your hooks consequently.
10017 @c FIXME should include discussion of variables you can use in these
10020 @node Third-Party Makefiles
10021 @section Third-Party @file{Makefile}s
10023 @cindex Third-party packages, interfacing with
10024 @cindex Interfacing with third-party packages
10026 In most projects all @file{Makefile}s are generated by Automake. In
10027 some cases, however, projects need to embed subdirectories with
10028 handwritten @file{Makefile}s. For instance, one subdirectory could be
10029 a third-party project with its own build system, not using Automake.
10031 It is possible to list arbitrary directories in @code{SUBDIRS} or
10032 @code{DIST_SUBDIRS} provided each of these directories has a
10033 @file{Makefile} that recognizes all the following recursive targets.
10035 @cindex recursive targets and third-party @file{Makefile}s
10036 When a user runs one of these targets, that target is run recursively
10037 in all subdirectories. This is why it is important that even
10038 third-party @file{Makefile}s support them.
10042 Compile the entire package. This is the default target in
10043 Automake-generated @file{Makefile}s, but it does not need to be the
10044 default in third-party @file{Makefile}s.
10049 @vindex top_distdir
10050 Copy files to distribute into @samp{$(distdir)}, before a tarball is
10051 constructed. Of course this target is not required if the
10052 @option{no-dist} option (@pxref{Options}) is used.
10054 The variables @samp{$(top_distdir)} and @samp{$(distdir)}
10055 (@pxref{The dist Hook}) will be passed from the outer package to the subpackage
10056 when the @code{distdir} target is invoked. These two variables have
10057 been adjusted for the directory that is being recursed into, so they
10061 @itemx install-data
10062 @itemx install-exec
10064 Install or uninstall files (@pxref{Install}).
10067 @itemx install-html
10068 @itemx install-info
10071 Install only some specific documentation format (@pxref{Texinfo}).
10074 Create install directories, but do not install any files.
10077 @itemx installcheck
10078 Check the package (@pxref{Tests}).
10083 @itemx maintainer-clean
10084 Cleaning rules (@pxref{Clean}).
10091 Build the documentation in various formats (@pxref{Texinfo}).
10095 Build @file{TAGS} and @file{CTAGS} (@pxref{Tags}).
10098 If you have ever used Gettext in a project, this is a good example of
10099 how third-party @file{Makefile}s can be used with Automake. The
10100 @file{Makefile}s @command{gettextize} puts in the @file{po/} and
10101 @file{intl/} directories are handwritten @file{Makefile}s that
10102 implement all these targets. That way they can be added to
10103 @code{SUBDIRS} in Automake packages.
10105 Directories that are only listed in @code{DIST_SUBDIRS} but not in
10106 @code{SUBDIRS} need only the @code{distclean},
10107 @code{maintainer-clean}, and @code{distdir} rules (@pxref{Conditional
10110 Usually, many of these rules are irrelevant to the third-party
10111 subproject, but they are required for the whole package to work. It's
10112 OK to have a rule that does nothing, so if you are integrating a
10113 third-party project with no documentation or tag support, you could
10114 simply augment its @file{Makefile} as follows:
10117 EMPTY_AUTOMAKE_TARGETS = dvi pdf ps info html tags ctags
10118 .PHONY: $(EMPTY_AUTOMAKE_TARGETS)
10119 $(EMPTY_AUTOMAKE_TARGETS):
10122 Another aspect of integrating third-party build systems is whether
10123 they support VPATH builds (@pxref{VPATH Builds}). Obviously if the
10124 subpackage does not support VPATH builds the whole package will not
10125 support VPATH builds. This in turns means that @samp{make distcheck}
10126 will not work, because it relies on VPATH builds. Some people can
10127 live without this (actually, many Automake users have never heard of
10128 @samp{make distcheck}). Other people may prefer to revamp the
10129 existing @file{Makefile}s to support VPATH@. Doing so does not
10130 necessarily require Automake, only Autoconf is needed (@pxref{Build
10131 Directories, , Build Directories, autoconf, The Autoconf Manual}).
10132 The necessary substitutions: @samp{@@srcdir@@}, @samp{@@top_srcdir@@},
10133 and @samp{@@top_builddir@@} are defined by @file{configure} when it
10134 processes a @file{Makefile} (@pxref{Preset Output Variables, , Preset
10135 Output Variables, autoconf, The Autoconf Manual}), they are not
10136 computed by the Makefile like the aforementioned @samp{$(distdir)} and
10137 @samp{$(top_distdir)} variables.
10139 It is sometimes inconvenient to modify a third-party @file{Makefile}
10140 to introduce the above required targets. For instance, one may want to
10141 keep the third-party sources untouched to ease upgrades to new
10144 @cindex @file{GNUmakefile} including @file{Makefile}
10145 Here are two other ideas. If GNU make is assumed, one possibility is
10146 to add to that subdirectory a @file{GNUmakefile} that defines the
10147 required targets and includes the third-party @file{Makefile}. For
10148 this to work in VPATH builds, @file{GNUmakefile} must lie in the build
10149 directory; the easiest way to do this is to write a
10150 @file{GNUmakefile.in} instead, and have it processed with
10151 @code{AC_CONFIG_FILES} from the outer package. For example if we
10152 assume @file{Makefile} defines all targets except the documentation
10153 targets, and that the @code{check} target is actually called
10154 @code{test}, we could write @file{GNUmakefile} (or
10155 @file{GNUmakefile.in}) like this:
10158 # First, include the real Makefile
10160 # Then, define the other targets needed by Automake Makefiles.
10161 .PHONY: dvi pdf ps info html check
10162 dvi pdf ps info html:
10166 @cindex Proxy @file{Makefile} for third-party packages
10167 A similar idea that does not use @code{include} is to write a proxy
10168 @file{Makefile} that dispatches rules to the real @file{Makefile},
10169 either with @samp{$(MAKE) -f Makefile.real $(AM_MAKEFLAGS) target} (if
10170 it's OK to rename the original @file{Makefile}) or with @samp{cd
10171 subdir && $(MAKE) $(AM_MAKEFLAGS) target} (if it's OK to store the
10172 subdirectory project one directory deeper). The good news is that
10173 this proxy @file{Makefile} can be generated with Automake. All we
10174 need are @option{-local} targets (@pxref{Extending}) that perform the
10175 dispatch. Of course the other Automake features are available, so you
10176 could decide to let Automake perform distribution or installation.
10177 Here is a possible @file{Makefile.am}:
10181 cd subdir && $(MAKE) $(AM_MAKEFLAGS) all
10183 cd subdir && $(MAKE) $(AM_MAKEFLAGS) test
10185 cd subdir && $(MAKE) $(AM_MAKEFLAGS) clean
10187 # Assuming the package knows how to install itself
10188 install-data-local:
10189 cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-data
10190 install-exec-local:
10191 cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-exec
10193 cd subdir && $(MAKE) $(AM_MAKEFLAGS) uninstall
10195 # Distribute files from here.
10196 EXTRA_DIST = subdir/Makefile subdir/program.c ...
10199 Pushing this idea to the extreme, it is also possible to ignore the
10200 subproject build system and build everything from this proxy
10201 @file{Makefile.am}. This might sound very sensible if you need VPATH
10202 builds but the subproject does not support them.
10205 @chapter Distributing @file{Makefile.in}s
10207 Automake places no restrictions on the distribution of the resulting
10208 @file{Makefile.in}s. We still encourage software authors to
10209 distribute their work under terms like those of the GPL, but doing so
10210 is not required to use Automake.
10212 Some of the files that can be automatically installed via the
10213 @option{--add-missing} switch do fall under the GPL@. However, these also
10214 have a special exception allowing you to distribute them with your
10215 package, regardless of the licensing you choose.
10218 @node API Versioning
10219 @chapter Automake API Versioning
10221 New Automake releases usually include bug fixes and new features.
10222 Unfortunately they may also introduce new bugs and incompatibilities.
10223 This makes four reasons why a package may require a particular Automake
10226 Things get worse when maintaining a large tree of packages, each one
10227 requiring a different version of Automake. In the past, this meant that
10228 any developer (and sometimes users) had to install several versions of
10229 Automake in different places, and switch @samp{$PATH} appropriately for
10232 Starting with version 1.6, Automake installs versioned binaries. This
10233 means you can install several versions of Automake in the same
10234 @samp{$prefix}, and can select an arbitrary Automake version by running
10235 @command{automake-1.6} or @command{automake-1.7} without juggling with
10236 @samp{$PATH}. Furthermore, @file{Makefile}'s generated by Automake 1.6
10237 will use @command{automake-1.6} explicitly in their rebuild rules.
10239 The number @samp{1.6} in @command{automake-1.6} is Automake's API version,
10240 not Automake's version. If a bug fix release is made, for instance
10241 Automake 1.6.1, the API version will remain 1.6. This means that a
10242 package that works with Automake 1.6 should also work with 1.6.1; after
10243 all, this is what people expect from bug fix releases.
10245 If your package relies on a feature or a bug fix introduced in
10246 a release, you can pass this version as an option to Automake to ensure
10247 older releases will not be used. For instance, use this in your
10248 @file{configure.ac}:
10251 AM_INIT_AUTOMAKE([1.6.1]) dnl Require Automake 1.6.1 or better.
10254 or, in a particular @file{Makefile.am}:
10257 AUTOMAKE_OPTIONS = 1.6.1 # Require Automake 1.6.1 or better.
10260 Automake will print an error message if its version is
10261 older than the requested version.
10264 @heading What is in the API
10266 Automake's programming interface is not easy to define. Basically it
10267 should include at least all @strong{documented} variables and targets
10268 that a @file{Makefile.am} author can use, any behavior associated with
10269 them (e.g., the places where @samp{-hook}'s are run), the command line
10270 interface of @command{automake} and @command{aclocal}, @dots{}
10272 @heading What is not in the API
10274 Every undocumented variable, target, or command line option, is not part
10275 of the API@. You should avoid using them, as they could change from one
10276 version to the other (even in bug fix releases, if this helps to fix a
10279 If it turns out you need to use such an undocumented feature, contact
10280 @email{automake@@gnu.org} and try to get it documented and exercised by
10284 @chapter Upgrading a Package to a Newer Automake Version
10286 Automake maintains three kind of files in a package.
10289 @item @file{aclocal.m4}
10290 @item @file{Makefile.in}s
10291 @item auxiliary tools like @file{install-sh} or @file{py-compile}
10294 @file{aclocal.m4} is generated by @command{aclocal} and contains some
10295 Automake-supplied M4 macros. Auxiliary tools are installed by
10296 @samp{automake --add-missing} when needed. @file{Makefile.in}s are
10297 built from @file{Makefile.am} by @command{automake}, and rely on the
10298 definitions of the M4 macros put in @file{aclocal.m4} as well as the
10299 behavior of the auxiliary tools installed.
10301 Because all these files are closely related, it is important to
10302 regenerate all of them when upgrading to a newer Automake release.
10303 The usual way to do that is
10306 aclocal # with any option needed (such a -I m4)
10308 automake --add-missing --force-missing
10312 or more conveniently:
10318 The use of @option{--force-missing} ensures that auxiliary tools will be
10319 overridden by new versions (@pxref{Invoking Automake}).
10321 It is important to regenerate all these files each time Automake is
10322 upgraded, even between bug fixes releases. For instance, it is not
10323 unusual for a bug fix to involve changes to both the rules generated
10324 in @file{Makefile.in} and the supporting M4 macros copied to
10327 Presently @command{automake} is able to diagnose situations where
10328 @file{aclocal.m4} has been generated with another version of
10329 @command{aclocal}. However it never checks whether auxiliary scripts
10330 are up-to-date. In other words, @command{automake} will tell you when
10331 @command{aclocal} needs to be rerun, but it will never diagnose a
10332 missing @option{--force-missing}.
10334 Before upgrading to a new major release, it is a good idea to read the
10335 file @file{NEWS}. This file lists all changes between releases: new
10336 features, obsolete constructs, known incompatibilities, and
10340 @chapter Frequently Asked Questions about Automake
10342 This chapter covers some questions that often come up on the mailing
10346 * CVS:: CVS and generated files
10347 * maintainer-mode:: missing and AM_MAINTAINER_MODE
10348 * Wildcards:: Why doesn't Automake support wildcards?
10349 * Limitations on File Names:: Limitations on source and installed file names
10350 * distcleancheck:: Files left in build directory after distclean
10351 * Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS
10352 * Renamed Objects:: Why are object files sometimes renamed?
10353 * Per-Object Flags:: How to simulate per-object flags?
10354 * Multiple Outputs:: Writing rules for tools with many output files
10355 * Hard-Coded Install Paths:: Installing to hard-coded locations
10356 * Debugging Make Rules:: Strategies when things don't work as expected
10360 @section CVS and generated files
10362 @subheading Background: distributed generated Files
10363 @cindex generated files, distributed
10364 @cindex rebuild rules
10366 Packages made with Autoconf and Automake ship with some generated
10367 files like @file{configure} or @file{Makefile.in}. These files were
10368 generated on the developer's host and are distributed so that
10369 end-users do not have to install the maintainer tools required to
10370 rebuild them. Other generated files like Lex scanners, Yacc parsers,
10371 or Info documentation, are usually distributed on similar grounds.
10373 Automake outputs rules in @file{Makefile}s to rebuild these files. For
10374 instance, @command{make} will run @command{autoconf} to rebuild
10375 @file{configure} whenever @file{configure.ac} is changed. This makes
10376 development safer by ensuring a @file{configure} is never out-of-date
10377 with respect to @file{configure.ac}.
10379 As generated files shipped in packages are up-to-date, and because
10380 @command{tar} preserves times-tamps, these rebuild rules are not
10381 triggered when a user unpacks and builds a package.
10383 @subheading Background: CVS and Timestamps
10384 @cindex timestamps and CVS
10385 @cindex CVS and timestamps
10387 Unless you use CVS keywords (in which case files must be updated at
10388 commit time), CVS preserves timestamp during @samp{cvs commit} and
10389 @samp{cvs import -d} operations.
10391 When you check out a file using @samp{cvs checkout} its timestamp is
10392 set to that of the revision that is being checked out.
10394 However, during @command{cvs update}, files will have the date of the
10395 update, not the original timestamp of this revision. This is meant to
10396 make sure that @command{make} notices sources files have been updated.
10398 This timestamp shift is troublesome when both sources and generated
10399 files are kept under CVS@. Because CVS processes files in lexical
10400 order, @file{configure.ac} will appear newer than @file{configure}
10401 after a @command{cvs update} that updates both files, even if
10402 @file{configure} was newer than @file{configure.ac} when it was
10403 checked in. Calling @command{make} will then trigger a spurious rebuild
10404 of @file{configure}.
10406 @subheading Living with CVS in Autoconfiscated Projects
10407 @cindex CVS and generated files
10408 @cindex generated files and CVS
10410 There are basically two clans amongst maintainers: those who keep all
10411 distributed files under CVS, including generated files, and those who
10412 keep generated files @emph{out} of CVS.
10414 @subsubheading All Files in CVS
10418 The CVS repository contains all distributed files so you know exactly
10419 what is distributed, and you can checkout any prior version entirely.
10422 Maintainers can see how generated files evolve (for instance, you can
10423 see what happens to your @file{Makefile.in}s when you upgrade Automake
10424 and make sure they look OK).
10427 Users do not need the autotools to build a checkout of the project, it
10428 works just like a released tarball.
10431 If users use @command{cvs update} to update their copy, instead of
10432 @command{cvs checkout} to fetch a fresh one, timestamps will be
10433 inaccurate. Some rebuild rules will be triggered and attempt to
10434 run developer tools such as @command{autoconf} or @command{automake}.
10436 Actually, calls to such tools are all wrapped into a call to the
10437 @command{missing} script discussed later (@pxref{maintainer-mode}).
10438 @command{missing} will take care of fixing the timestamps when these
10439 tools are not installed, so that the build can continue.
10442 In distributed development, developers are likely to have different
10443 version of the maintainer tools installed. In this case rebuilds
10444 triggered by timestamp lossage will lead to spurious changes
10445 to generated files. There are several solutions to this:
10449 All developers should use the same versions, so that the rebuilt files
10450 are identical to files in CVS@. (This starts to be difficult when each
10451 project you work on uses different versions.)
10453 Or people use a script to fix the timestamp after a checkout (the GCC
10454 folks have such a script).
10456 Or @file{configure.ac} uses @code{AM_MAINTAINER_MODE}, which will
10457 disable all these rebuild rules by default. This is further discussed
10458 in @ref{maintainer-mode}.
10462 Although we focused on spurious rebuilds, the converse can also
10463 happen. CVS's timestamp handling can also let you think an
10464 out-of-date file is up-to-date.
10466 For instance, suppose a developer has modified @file{Makefile.am} and
10467 has rebuilt @file{Makefile.in}, and then decides to do a last-minute
10468 change to @file{Makefile.am} right before checking in both files
10469 (without rebuilding @file{Makefile.in} to account for the change).
10471 This last change to @file{Makefile.am} makes the copy of
10472 @file{Makefile.in} out-of-date. Since CVS processes files
10473 alphabetically, when another developer @samp{cvs update}s his or her
10474 tree, @file{Makefile.in} will happen to be newer than
10475 @file{Makefile.am}. This other developer will not see that
10476 @file{Makefile.in} is out-of-date.
10480 @subsubheading Generated Files out of CVS
10482 One way to get CVS and @command{make} working peacefully is to never
10483 store generated files in CVS, i.e., do not CVS-control files that
10484 are @file{Makefile} targets (also called @emph{derived} files).
10486 This way developers are not annoyed by changes to generated files. It
10487 does not matter if they all have different versions (assuming they are
10488 compatible, of course). And finally, timestamps are not lost, changes
10489 to sources files can't be missed as in the
10490 @file{Makefile.am}/@file{Makefile.in} example discussed earlier.
10492 The drawback is that the CVS repository is not an exact copy of what
10493 is distributed and that users now need to install various development
10494 tools (maybe even specific versions) before they can build a checkout.
10495 But, after all, CVS's job is versioning, not distribution.
10497 Allowing developers to use different versions of their tools can also
10498 hide bugs during distributed development. Indeed, developers will be
10499 using (hence testing) their own generated files, instead of the
10500 generated files that will be released actually. The developer who
10501 prepares the tarball might be using a version of the tool that
10502 produces bogus output (for instance a non-portable C file), something
10503 other developers could have noticed if they weren't using their own
10504 versions of this tool.
10506 @subheading Third-party Files
10507 @cindex CVS and third-party files
10508 @cindex third-party files and CVS
10510 Another class of files not discussed here (because they do not cause
10511 timestamp issues) are files that are shipped with a package, but
10512 maintained elsewhere. For instance, tools like @command{gettextize}
10513 and @command{autopoint} (from Gettext) or @command{libtoolize} (from
10514 Libtool), will install or update files in your package.
10516 These files, whether they are kept under CVS or not, raise similar
10517 concerns about version mismatch between developers' tools. The
10518 Gettext manual has a section about this, see @ref{CVS Issues, CVS
10519 Issues, Integrating with CVS, gettext, GNU gettext tools}.
10521 @node maintainer-mode
10522 @section @command{missing} and @code{AM_MAINTAINER_MODE}
10524 @subheading @command{missing}
10525 @cindex @command{missing}, purpose
10527 The @command{missing} script is a wrapper around several maintainer
10528 tools, designed to warn users if a maintainer tool is required but
10529 missing. Typical maintainer tools are @command{autoconf},
10530 @command{automake}, @command{bison}, etc. Because file generated by
10531 these tools are shipped with the other sources of a package, these
10532 tools shouldn't be required during a user build and they are not
10533 checked for in @file{configure}.
10535 However, if for some reason a rebuild rule is triggered and involves a
10536 missing tool, @command{missing} will notice it and warn the user.
10537 Besides the warning, when a tool is missing, @command{missing} will
10538 attempt to fix timestamps in a way that allows the build to continue.
10539 For instance, @command{missing} will touch @file{configure} if
10540 @command{autoconf} is not installed. When all distributed files are
10541 kept under CVS, this feature of @command{missing} allows a user
10542 @emph{with no maintainer tools} to build a package off CVS, bypassing
10543 any timestamp inconsistency implied by @samp{cvs update}.
10545 If the required tool is installed, @command{missing} will run it and
10546 won't attempt to continue after failures. This is correct during
10547 development: developers love fixing failures. However, users with
10548 wrong versions of maintainer tools may get an error when the rebuild
10549 rule is spuriously triggered, halting the build. This failure to let
10550 the build continue is one of the arguments of the
10551 @code{AM_MAINTAINER_MODE} advocates.
10553 @subheading @code{AM_MAINTAINER_MODE}
10554 @cindex @code{AM_MAINTAINER_MODE}, purpose
10555 @acindex AM_MAINTAINER_MODE
10557 @code{AM_MAINTAINER_MODE} allows you to choose whether the so called
10558 "rebuild rules" should be enabled or disabled. With
10559 @code{AM_MAINTAINER_MODE([enable])}, they are enabled by default,
10560 otherwise they are disabled by default. In the latter case, if
10561 you have @code{AM_MAINTAINER_MODE} in @file{configure.ac}, and run
10562 @samp{./configure && make}, then @command{make} will *never* attempt to
10563 rebuild @file{configure}, @file{Makefile.in}s, Lex or Yacc outputs, etc.
10564 I.e., this disables build rules for files that are usually distributed
10565 and that users should normally not have to update.
10567 The user can override the default setting by passing either
10568 @samp{--enable-maintainer-mode} or @samp{--disable-maintainer-mode}
10569 to @command{configure}.
10571 People use @code{AM_MAINTAINER_MODE} either because they do not want their
10572 users (or themselves) annoyed by timestamps lossage (@pxref{CVS}), or
10573 because they simply can't stand the rebuild rules and prefer running
10574 maintainer tools explicitly.
10576 @code{AM_MAINTAINER_MODE} also allows you to disable some custom build
10577 rules conditionally. Some developers use this feature to disable
10578 rules that need exotic tools that users may not have available.
10580 Several years ago Fran@,{c}ois Pinard pointed out several arguments
10581 against this @code{AM_MAINTAINER_MODE} macro. Most of them relate to
10582 insecurity. By removing dependencies you get non-dependable builds:
10583 changes to sources files can have no effect on generated files and this
10584 can be very confusing when unnoticed. He adds that security shouldn't
10585 be reserved to maintainers (what @option{--enable-maintainer-mode}
10586 suggests), on the contrary. If one user has to modify a
10587 @file{Makefile.am}, then either @file{Makefile.in} should be updated
10588 or a warning should be output (this is what Automake uses
10589 @command{missing} for) but the last thing you want is that nothing
10590 happens and the user doesn't notice it (this is what happens when
10591 rebuild rules are disabled by @code{AM_MAINTAINER_MODE}).
10593 Jim Meyering, the inventor of the @code{AM_MAINTAINER_MODE} macro was
10594 swayed by Fran@,{c}ois's arguments, and got rid of
10595 @code{AM_MAINTAINER_MODE} in all of his packages.
10597 Still many people continue to use @code{AM_MAINTAINER_MODE}, because
10598 it helps them working on projects where all files are kept under CVS,
10599 and because @command{missing} isn't enough if you have the wrong
10600 version of the tools.
10604 @section Why doesn't Automake support wildcards?
10607 Developers are lazy. They would often like to use wildcards in
10608 @file{Makefile.am}s, so that they would not need to remember to
10609 update @file{Makefile.am}s every time they add, delete, or rename
10612 There are several objections to this:
10615 When using CVS (or similar) developers need to remember they have to
10616 run @samp{cvs add} or @samp{cvs rm} anyway. Updating
10617 @file{Makefile.am} accordingly quickly becomes a reflex.
10619 Conversely, if your application doesn't compile
10620 because you forgot to add a file in @file{Makefile.am}, it will help
10621 you remember to @samp{cvs add} it.
10624 Using wildcards makes it easy to distribute files by mistake. For
10625 instance, some code a developer is experimenting with (a test case,
10626 say) that should not be part of the distribution.
10629 Using wildcards it's easy to omit some files by mistake. For
10630 instance, one developer creates a new file, uses it in many places,
10631 but forgets to commit it. Another developer then checks out the
10632 incomplete project and is able to run @samp{make dist} successfully,
10633 even though a file is missing. By listing files, @samp{make dist}
10634 @emph{will} complain.
10637 Wildcards are not portable to some non-GNU @command{make} implementations,
10638 e.g., NetBSD @command{make} will not expand globs such as @samp{*} in
10639 prerequisites of a target.
10642 Finally, it's really hard to @emph{forget} to add a file to
10643 @file{Makefile.am}: files that are not listed in @file{Makefile.am} are
10644 not compiled or installed, so you can't even test them.
10647 Still, these are philosophical objections, and as such you may disagree,
10648 or find enough value in wildcards to dismiss all of them. Before you
10649 start writing a patch against Automake to teach it about wildcards,
10650 let's see the main technical issue: portability.
10652 Although @samp{$(wildcard ...)} works with GNU @command{make}, it is
10653 not portable to other @command{make} implementations.
10655 The only way Automake could support @command{$(wildcard ...)} is by
10656 expending @command{$(wildcard ...)} when @command{automake} is run.
10657 The resulting @file{Makefile.in}s would be portable since they would
10658 list all files and not use @samp{$(wildcard ...)}. However that
10659 means developers would need to remember to run @command{automake} each
10660 time they add, delete, or rename files.
10662 Compared to editing @file{Makefile.am}, this is a very small gain. Sure,
10663 it's easier and faster to type @samp{automake; make} than to type
10664 @samp{emacs Makefile.am; make}. But nobody bothered enough to write a
10665 patch to add support for this syntax. Some people use scripts to
10666 generate file lists in @file{Makefile.am} or in separate
10667 @file{Makefile} fragments.
10669 Even if you don't care about portability, and are tempted to use
10670 @samp{$(wildcard ...)} anyway because you target only GNU Make, you
10671 should know there are many places where Automake needs to know exactly
10672 which files should be processed. As Automake doesn't know how to
10673 expand @samp{$(wildcard ...)}, you cannot use it in these places.
10674 @samp{$(wildcard ...)} is a black box comparable to @code{AC_SUBST}ed
10675 variables as far Automake is concerned.
10677 You can get warnings about @samp{$(wildcard ...}) constructs using the
10678 @option{-Wportability} flag.
10680 @node Limitations on File Names
10681 @section Limitations on File Names
10682 @cindex file names, limitations on
10684 Automake attempts to support all kinds of file names, even those that
10685 contain unusual characters or are unusually long. However, some
10686 limitations are imposed by the underlying operating system and tools.
10688 Most operating systems prohibit the use of the null byte in file
10689 names, and reserve @samp{/} as a directory separator. Also, they
10690 require that file names are properly encoded for the user's locale.
10691 Automake is subject to these limits.
10693 Portable packages should limit themselves to POSIX file
10694 names. These can contain ASCII letters and digits,
10695 @samp{_}, @samp{.}, and @samp{-}. File names consist of components
10696 separated by @samp{/}. File name components cannot begin with
10699 Portable POSIX file names cannot contain components that exceed a
10700 14-byte limit, but nowadays it's normally safe to assume the
10701 more-generous XOPEN limit of 255 bytes. POSIX
10702 limits file names to 255 bytes (XOPEN allows 1023 bytes),
10703 but you may want to limit a source tarball to file names of 99 bytes
10704 to avoid interoperability problems with old versions of @command{tar}.
10706 If you depart from these rules (e.g., by using non-ASCII
10707 characters in file names, or by using lengthy file names), your
10708 installers may have problems for reasons unrelated to Automake.
10709 However, if this does not concern you, you should know about the
10710 limitations imposed by Automake itself. These limitations are
10711 undesirable, but some of them seem to be inherent to underlying tools
10712 like Autoconf, Make, M4, and the shell. They fall into three
10713 categories: install directories, build directories, and file names.
10715 The following characters:
10718 @r{newline} " # $ ' `
10721 should not appear in the names of install directories. For example,
10722 the operand of @command{configure}'s @option{--prefix} option should
10723 not contain these characters.
10725 Build directories suffer the same limitations as install directories,
10726 and in addition should not contain the following characters:
10732 For example, the full name of the directory containing the source
10733 files should not contain these characters.
10735 Source and installation file names like @file{main.c} are limited even
10736 further: they should conform to the POSIX/XOPEN
10737 rules described above. In addition, if you plan to port to
10738 non-POSIX environments, you should avoid file names that
10739 differ only in case (e.g., @file{makefile} and @file{Makefile}).
10740 Nowadays it is no longer worth worrying about the 8.3 limits of
10743 @node distcleancheck
10744 @section Files left in build directory after distclean
10745 @cindex @code{distclean}, diagnostic
10746 @cindex @samp{make distclean}, diagnostic
10747 @cindex dependencies and distributed files
10749 @trindex distcleancheck
10751 This is a diagnostic you might encounter while running @samp{make
10754 As explained in @ref{Checking the Distribution}, @samp{make distcheck}
10755 attempts to build and check your package for errors like this one.
10757 @samp{make distcheck} will perform a @code{VPATH} build of your
10758 package (@pxref{VPATH Builds}), and then call @samp{make distclean}.
10759 Files left in the build directory after @samp{make distclean} has run
10760 are listed after this error.
10762 This diagnostic really covers two kinds of errors:
10766 files that are forgotten by distclean;
10768 distributed files that are erroneously rebuilt.
10771 The former left-over files are not distributed, so the fix is to mark
10772 them for cleaning (@pxref{Clean}), this is obvious and doesn't deserve
10775 The latter bug is not always easy to understand and fix, so let's
10776 proceed with an example. Suppose our package contains a program for
10777 which we want to build a man page using @command{help2man}. GNU
10778 @command{help2man} produces simple manual pages from the @option{--help}
10779 and @option{--version} output of other commands (@pxref{Top, , Overview,
10780 help2man, The Help2man Manual}). Because we don't want to force our
10781 users to install @command{help2man}, we decide to distribute the
10782 generated man page using the following setup.
10785 # This Makefile.am is bogus.
10787 foo_SOURCES = foo.c
10788 dist_man_MANS = foo.1
10790 foo.1: foo$(EXEEXT)
10791 help2man --output=foo.1 ./foo$(EXEEXT)
10794 This will effectively distribute the man page. However,
10795 @samp{make distcheck} will fail with:
10798 ERROR: files left in build directory after distclean:
10802 Why was @file{foo.1} rebuilt? Because although distributed,
10803 @file{foo.1} depends on a non-distributed built file:
10804 @file{foo$(EXEEXT)}. @file{foo$(EXEEXT)} is built by the user, so it
10805 will always appear to be newer than the distributed @file{foo.1}.
10807 @samp{make distcheck} caught an inconsistency in our package. Our
10808 intent was to distribute @file{foo.1} so users do not need to install
10809 @command{help2man}, however since this rule causes this file to be
10810 always rebuilt, users @emph{do} need @command{help2man}. Either we
10811 should ensure that @file{foo.1} is not rebuilt by users, or there is
10812 no point in distributing @file{foo.1}.
10814 More generally, the rule is that distributed files should never depend
10815 on non-distributed built files. If you distribute something
10816 generated, distribute its sources.
10818 One way to fix the above example, while still distributing
10819 @file{foo.1} is to not depend on @file{foo$(EXEEXT)}. For instance,
10820 assuming @command{foo --version} and @command{foo --help} do not
10821 change unless @file{foo.c} or @file{configure.ac} change, we could
10822 write the following @file{Makefile.am}:
10826 foo_SOURCES = foo.c
10827 dist_man_MANS = foo.1
10829 foo.1: foo.c $(top_srcdir)/configure.ac
10830 $(MAKE) $(AM_MAKEFLAGS) foo$(EXEEXT)
10831 help2man --output=foo.1 ./foo$(EXEEXT)
10834 This way, @file{foo.1} will not get rebuilt every time
10835 @file{foo$(EXEEXT)} changes. The @command{make} call makes sure
10836 @file{foo$(EXEEXT)} is up-to-date before @command{help2man}. Another
10837 way to ensure this would be to use separate directories for binaries
10838 and man pages, and set @code{SUBDIRS} so that binaries are built
10841 We could also decide not to distribute @file{foo.1}. In
10842 this case it's fine to have @file{foo.1} dependent upon
10843 @file{foo$(EXEEXT)}, since both will have to be rebuilt.
10844 However it would be impossible to build the package in a
10845 cross-compilation, because building @file{foo.1} involves
10846 an @emph{execution} of @file{foo$(EXEEXT)}.
10848 Another context where such errors are common is when distributed files
10849 are built by tools that are built by the package. The pattern is
10853 distributed-file: built-tools distributed-sources
10858 should be changed to
10861 distributed-file: distributed-sources
10862 $(MAKE) $(AM_MAKEFLAGS) built-tools
10867 or you could choose not to distribute @file{distributed-file}, if
10868 cross-compilation does not matter.
10870 The points made through these examples are worth a summary:
10875 Distributed files should never depend upon non-distributed built
10878 Distributed files should be distributed with all their dependencies.
10880 If a file is @emph{intended} to be rebuilt by users, then there is no point
10881 in distributing it.
10885 @vrindex distcleancheck_listfiles
10886 For desperate cases, it's always possible to disable this check by
10887 setting @code{distcleancheck_listfiles} as documented in @ref{Checking
10889 Make sure you do understand the reason why @samp{make distcheck}
10890 complains before you do this. @code{distcleancheck_listfiles} is a
10891 way to @emph{hide} errors, not to fix them. You can always do better.
10893 @node Flag Variables Ordering
10894 @section Flag Variables Ordering
10895 @cindex Ordering flag variables
10896 @cindex Flag variables, ordering
10899 What is the difference between @code{AM_CFLAGS}, @code{CFLAGS}, and
10900 @code{mumble_CFLAGS}?
10904 Why does @command{automake} output @code{CPPFLAGS} after
10905 @code{AM_CPPFLAGS} on compile lines? Shouldn't it be the converse?
10909 My @file{configure} adds some warning flags into @code{CXXFLAGS}. In
10910 one @file{Makefile.am} I would like to append a new flag, however if I
10911 put the flag into @code{AM_CXXFLAGS} it is prepended to the other
10912 flags, not appended.
10915 @subheading Compile Flag Variables
10916 @cindex Flag Variables, Ordering
10917 @cindex Compile Flag Variables
10918 @cindex @code{AM_CCASFLAGS} and @code{CCASFLAGS}
10919 @cindex @code{AM_CFLAGS} and @code{CFLAGS}
10920 @cindex @code{AM_CPPFLAGS} and @code{CPPFLAGS}
10921 @cindex @code{AM_CXXFLAGS} and @code{CXXFLAGS}
10922 @cindex @code{AM_FCFLAGS} and @code{FCFLAGS}
10923 @cindex @code{AM_FFLAGS} and @code{FFLAGS}
10924 @cindex @code{AM_GCJFLAGS} and @code{GCJFLAGS}
10925 @cindex @code{AM_LDFLAGS} and @code{LDFLAGS}
10926 @cindex @code{AM_LFLAGS} and @code{LFLAGS}
10927 @cindex @code{AM_LIBTOOLFLAGS} and @code{LIBTOOLFLAGS}
10928 @cindex @code{AM_OBJCFLAGS} and @code{OBJCFLAGS}
10929 @cindex @code{AM_RFLAGS} and @code{RFLAGS}
10930 @cindex @code{AM_UPCFLAGS} and @code{UPCFLAGS}
10931 @cindex @code{AM_YFLAGS} and @code{YFLAGS}
10932 @cindex @code{CCASFLAGS} and @code{AM_CCASFLAGS}
10933 @cindex @code{CFLAGS} and @code{AM_CFLAGS}
10934 @cindex @code{CPPFLAGS} and @code{AM_CPPFLAGS}
10935 @cindex @code{CXXFLAGS} and @code{AM_CXXFLAGS}
10936 @cindex @code{FCFLAGS} and @code{AM_FCFLAGS}
10937 @cindex @code{FFLAGS} and @code{AM_FFLAGS}
10938 @cindex @code{GCJFLAGS} and @code{AM_GCJFLAGS}
10939 @cindex @code{LDFLAGS} and @code{AM_LDFLAGS}
10940 @cindex @code{LFLAGS} and @code{AM_LFLAGS}
10941 @cindex @code{LIBTOOLFLAGS} and @code{AM_LIBTOOLFLAGS}
10942 @cindex @code{OBJCFLAGS} and @code{AM_OBJCFLAGS}
10943 @cindex @code{RFLAGS} and @code{AM_RFLAGS}
10944 @cindex @code{UPCFLAGS} and @code{AM_UPCFLAGS}
10945 @cindex @code{YFLAGS} and @code{AM_YFLAGS}
10947 This section attempts to answer all the above questions. We will
10948 mostly discuss @code{CPPFLAGS} in our examples, but actually the
10949 answer holds for all the compile flags used in Automake:
10950 @code{CCASFLAGS}, @code{CFLAGS}, @code{CPPFLAGS}, @code{CXXFLAGS},
10951 @code{FCFLAGS}, @code{FFLAGS}, @code{GCJFLAGS}, @code{LDFLAGS},
10952 @code{LFLAGS}, @code{LIBTOOLFLAGS}, @code{OBJCFLAGS}, @code{RFLAGS},
10953 @code{UPCFLAGS}, and @code{YFLAGS}.
10955 @code{CPPFLAGS}, @code{AM_CPPFLAGS}, and @code{mumble_CPPFLAGS} are
10956 three variables that can be used to pass flags to the C preprocessor
10957 (actually these variables are also used for other languages like C++
10958 or preprocessed Fortran). @code{CPPFLAGS} is the user variable
10959 (@pxref{User Variables}), @code{AM_CPPFLAGS} is the Automake variable,
10960 and @code{mumble_CPPFLAGS} is the variable specific to the
10961 @code{mumble} target (we call this a per-target variable,
10962 @pxref{Program and Library Variables}).
10964 Automake always uses two of these variables when compiling C sources
10965 files. When compiling an object file for the @code{mumble} target,
10966 the first variable will be @code{mumble_CPPFLAGS} if it is defined, or
10967 @code{AM_CPPFLAGS} otherwise. The second variable is always
10970 In the following example,
10973 bin_PROGRAMS = foo bar
10974 foo_SOURCES = xyz.c
10975 bar_SOURCES = main.c
10976 foo_CPPFLAGS = -DFOO
10977 AM_CPPFLAGS = -DBAZ
10981 @file{xyz.o} will be compiled with @samp{$(foo_CPPFLAGS) $(CPPFLAGS)},
10982 (because @file{xyz.o} is part of the @code{foo} target), while
10983 @file{main.o} will be compiled with @samp{$(AM_CPPFLAGS) $(CPPFLAGS)}
10984 (because there is no per-target variable for target @code{bar}).
10986 The difference between @code{mumble_CPPFLAGS} and @code{AM_CPPFLAGS}
10987 being clear enough, let's focus on @code{CPPFLAGS}. @code{CPPFLAGS}
10988 is a user variable, i.e., a variable that users are entitled to modify
10989 in order to compile the package. This variable, like many others,
10990 is documented at the end of the output of @samp{configure --help}.
10992 For instance, someone who needs to add @file{/home/my/usr/include} to
10993 the C compiler's search path would configure a package with
10996 ./configure CPPFLAGS='-I /home/my/usr/include'
11000 and this flag would be propagated to the compile rules of all
11003 It is also not uncommon to override a user variable at
11004 @command{make}-time. Many installers do this with @code{prefix}, but
11005 this can be useful with compiler flags too. For instance, if, while
11006 debugging a C++ project, you need to disable optimization in one
11007 specific object file, you can run something like
11011 make CXXFLAGS=-O0 file.o
11015 The reason @samp{$(CPPFLAGS)} appears after @samp{$(AM_CPPFLAGS)} or
11016 @samp{$(mumble_CPPFLAGS)} in the compile command is that users
11017 should always have the last say. It probably makes more sense if you
11018 think about it while looking at the @samp{CXXFLAGS=-O0} above, which
11019 should supersede any other switch from @code{AM_CXXFLAGS} or
11020 @code{mumble_CXXFLAGS} (and this of course replaces the previous value
11021 of @code{CXXFLAGS}).
11023 You should never redefine a user variable such as @code{CPPFLAGS} in
11024 @file{Makefile.am}. Use @samp{automake -Woverride} to diagnose such
11025 mistakes. Even something like
11028 CPPFLAGS = -DDATADIR=\"$(datadir)\" @@CPPFLAGS@@
11032 is erroneous. Although this preserves @file{configure}'s value of
11033 @code{CPPFLAGS}, the definition of @code{DATADIR} will disappear if a
11034 user attempts to override @code{CPPFLAGS} from the @command{make}
11038 AM_CPPFLAGS = -DDATADIR=\"$(datadir)\"
11042 is all that is needed here if no per-target flags are used.
11044 You should not add options to these user variables within
11045 @file{configure} either, for the same reason. Occasionally you need
11046 to modify these variables to perform a test, but you should reset
11047 their values afterwards. In contrast, it is OK to modify the
11048 @samp{AM_} variables within @file{configure} if you @code{AC_SUBST}
11049 them, but it is rather rare that you need to do this, unless you
11050 really want to change the default definitions of the @samp{AM_}
11051 variables in all @file{Makefile}s.
11053 What we recommend is that you define extra flags in separate
11054 variables. For instance, you may write an Autoconf macro that computes
11055 a set of warning options for the C compiler, and @code{AC_SUBST} them
11056 in @code{WARNINGCFLAGS}; you may also have an Autoconf macro that
11057 determines which compiler and which linker flags should be used to
11058 link with library @file{libfoo}, and @code{AC_SUBST} these in
11059 @code{LIBFOOCFLAGS} and @code{LIBFOOLDFLAGS}. Then, a
11060 @file{Makefile.am} could use these variables as follows:
11063 AM_CFLAGS = $(WARNINGCFLAGS)
11064 bin_PROGRAMS = prog1 prog2
11065 prog1_SOURCES = @dots{}
11066 prog2_SOURCES = @dots{}
11067 prog2_CFLAGS = $(LIBFOOCFLAGS) $(AM_CFLAGS)
11068 prog2_LDFLAGS = $(LIBFOOLDFLAGS)
11071 In this example both programs will be compiled with the flags
11072 substituted into @samp{$(WARNINGCFLAGS)}, and @code{prog2} will
11073 additionally be compiled with the flags required to link with
11076 Note that listing @code{AM_CFLAGS} in a per-target @code{CFLAGS}
11077 variable is a common idiom to ensure that @code{AM_CFLAGS} applies to
11078 every target in a @file{Makefile.in}.
11080 Using variables like this gives you full control over the ordering of
11081 the flags. For instance, if there is a flag in $(WARNINGCFLAGS) that
11082 you want to negate for a particular target, you can use something like
11083 @samp{prog1_CFLAGS = $(AM_CFLAGS) -no-flag}. If all these flags had
11084 been forcefully appended to @code{CFLAGS}, there would be no way to
11085 disable one flag. Yet another reason to leave user variables to
11088 Finally, we have avoided naming the variable of the example
11089 @code{LIBFOO_LDFLAGS} (with an underscore) because that would cause
11090 Automake to think that this is actually a per-target variable (like
11091 @code{mumble_LDFLAGS}) for some non-declared @code{LIBFOO} target.
11093 @subheading Other Variables
11095 There are other variables in Automake that follow similar principles
11096 to allow user options. For instance, Texinfo rules (@pxref{Texinfo})
11097 use @code{MAKEINFOFLAGS} and @code{AM_MAKEINFOFLAGS}. Similarly,
11098 DejaGnu tests (@pxref{DejaGnu Tests}) use @code{RUNTESTDEFAULTFLAGS} and
11099 @code{AM_RUNTESTDEFAULTFLAGS}. The tags and ctags rules
11100 (@pxref{Tags}) use @code{ETAGSFLAGS}, @code{AM_ETAGSFLAGS},
11101 @code{CTAGSFLAGS}, and @code{AM_CTAGSFLAGS}. Java rules
11102 (@pxref{Java}) use @code{JAVACFLAGS} and @code{AM_JAVACFLAGS}. None
11103 of these rules support per-target flags (yet).
11105 To some extent, even @code{AM_MAKEFLAGS} (@pxref{Subdirectories})
11106 obeys this naming scheme. The slight difference is that
11107 @code{MAKEFLAGS} is passed to sub-@command{make}s implicitly by
11108 @command{make} itself.
11110 However you should not think that all variables ending with
11111 @code{FLAGS} follow this convention. For instance,
11112 @code{DISTCHECK_CONFIGURE_FLAGS} (@pxref{Checking the Distribution}) and
11113 @code{ACLOCAL_AMFLAGS} (see @ref{Rebuilding} and @ref{Local Macros}),
11114 are two variables that are only useful to the maintainer and have no
11117 @code{ARFLAGS} (@pxref{A Library}) is usually defined by Automake and
11118 has neither @code{AM_} nor per-target cousin.
11120 Finally you should not think that the existence of a per-target
11121 variable implies the existance of an @code{AM_} variable or of a user
11122 variable. For instance, the @code{mumble_LDADD} per-target variable
11123 overrides the makefile-wide @code{LDADD} variable (which is not a user
11124 variable), and @code{mumble_LIBADD} exists only as a per-target
11125 variable. @xref{Program and Library Variables}.
11128 @node Renamed Objects
11129 @section Why are object files sometimes renamed?
11131 This happens when per-target compilation flags are used. Object
11132 files need to be renamed just in case they would clash with object
11133 files compiled from the same sources, but with different flags.
11134 Consider the following example.
11137 bin_PROGRAMS = true false
11138 true_SOURCES = generic.c
11139 true_CPPFLAGS = -DEXIT_CODE=0
11140 false_SOURCES = generic.c
11141 false_CPPFLAGS = -DEXIT_CODE=1
11144 Obviously the two programs are built from the same source, but it
11145 would be bad if they shared the same object, because @file{generic.o}
11146 cannot be built with both @samp{-DEXIT_CODE=0} @emph{and}
11147 @samp{-DEXIT_CODE=1}. Therefore @command{automake} outputs rules to
11148 build two different objects: @file{true-generic.o} and
11149 @file{false-generic.o}.
11151 @command{automake} doesn't actually look whether source files are
11152 shared to decide if it must rename objects. It will just rename all
11153 objects of a target as soon as it sees per-target compilation flags
11156 It's OK to share object files when per-target compilation flags are not
11157 used. For instance, @file{true} and @file{false} will both use
11158 @file{version.o} in the following example.
11161 AM_CPPFLAGS = -DVERSION=1.0
11162 bin_PROGRAMS = true false
11163 true_SOURCES = true.c version.c
11164 false_SOURCES = false.c version.c
11167 Note that the renaming of objects is also affected by the
11168 @code{_SHORTNAME} variable (@pxref{Program and Library Variables}).
11171 @node Per-Object Flags
11172 @section Per-Object Flags Emulation
11173 @cindex Per-object flags, emulated
11176 One of my source files needs to be compiled with different flags. How
11180 Automake supports per-program and per-library compilation flags (see
11181 @ref{Program and Library Variables} and @ref{Flag Variables
11182 Ordering}). With this you can define compilation flags that apply to
11183 all files compiled for a target. For instance, in
11187 foo_SOURCES = foo.c foo.h bar.c bar.h main.c
11188 foo_CFLAGS = -some -flags
11192 @file{foo-foo.o}, @file{foo-bar.o}, and @file{foo-main.o} will all be
11193 compiled with @samp{-some -flags}. (If you wonder about the names of
11194 these object files, see @ref{Renamed Objects}.) Note that
11195 @code{foo_CFLAGS} gives the flags to use when compiling all the C
11196 sources of the @emph{program} @code{foo}, it has nothing to do with
11197 @file{foo.c} or @file{foo-foo.o} specifically.
11199 What if @file{foo.c} needs to be compiled into @file{foo.o} using some
11200 specific flags, that none of the other files requires? Obviously
11201 per-program flags are not directly applicable here. Something like
11202 per-object flags are expected, i.e., flags that would be used only
11203 when creating @file{foo-foo.o}. Automake does not support that,
11204 however this is easy to simulate using a library that contains only
11205 that object, and compiling this library with per-library flags.
11209 foo_SOURCES = bar.c bar.h main.c
11210 foo_CFLAGS = -some -flags
11211 foo_LDADD = libfoo.a
11212 noinst_LIBRARIES = libfoo.a
11213 libfoo_a_SOURCES = foo.c foo.h
11214 libfoo_a_CFLAGS = -some -other -flags
11217 Here @file{foo-bar.o} and @file{foo-main.o} will all be
11218 compiled with @samp{-some -flags}, while @file{libfoo_a-foo.o} will
11219 be compiled using @samp{-some -other -flags}. Eventually, all
11220 three objects will be linked to form @file{foo}.
11222 This trick can also be achieved using Libtool convenience libraries,
11223 for instance @samp{noinst_LTLIBRARIES = libfoo.la} (@pxref{Libtool
11224 Convenience Libraries}).
11226 Another tempting idea to implement per-object flags is to override the
11227 compile rules @command{automake} would output for these files.
11228 Automake will not define a rule for a target you have defined, so you
11229 could think about defining the @samp{foo-foo.o: foo.c} rule yourself.
11230 We recommend against this, because this is error prone. For instance,
11231 if you add such a rule to the first example, it will break the day you
11232 decide to remove @code{foo_CFLAGS} (because @file{foo.c} will then be
11233 compiled as @file{foo.o} instead of @file{foo-foo.o}, @pxref{Renamed
11234 Objects}). Also in order to support dependency tracking, the two
11235 @file{.o}/@file{.obj} extensions, and all the other flags variables
11236 involved in a compilation, you will end up modifying a copy of the
11237 rule previously output by @command{automake} for this file. If a new
11238 release of Automake generates a different rule, your copy will need to
11239 be updated by hand.
11241 @node Multiple Outputs
11242 @section Handling Tools that Produce Many Outputs
11243 @cindex multiple outputs, rules with
11244 @cindex many outputs, rules with
11245 @cindex rules with multiple outputs
11247 This section describes a @command{make} idiom that can be used when a
11248 tool produces multiple output files. It is not specific to Automake
11249 and can be used in ordinary @file{Makefile}s.
11251 Suppose we have a program called @command{foo} that will read one file
11252 called @file{data.foo} and produce two files named @file{data.c} and
11253 @file{data.h}. We want to write a @file{Makefile} rule that captures
11254 this one-to-two dependency.
11256 The naive rule is incorrect:
11259 # This is incorrect.
11260 data.c data.h: data.foo
11265 What the above rule really says is that @file{data.c} and
11266 @file{data.h} each depend on @file{data.foo}, and can each be built by
11267 running @samp{foo data.foo}. In other words it is equivalent to:
11270 # We do not want this.
11278 which means that @command{foo} can be run twice. Usually it will not
11279 be run twice, because @command{make} implementations are smart enough
11280 to check for the existence of the second file after the first one has
11281 been built; they will therefore detect that it already exists.
11282 However there are a few situations where it can run twice anyway:
11286 The most worrying case is when running a parallel @command{make}. If
11287 @file{data.c} and @file{data.h} are built in parallel, two @samp{foo
11288 data.foo} commands will run concurrently. This is harmful.
11290 Another case is when the dependency (here @file{data.foo}) is
11291 (or depends upon) a phony target.
11294 A solution that works with parallel @command{make} but not with
11295 phony dependencies is the following:
11298 data.c data.h: data.foo
11304 The above rules are equivalent to
11309 data.h: data.foo data.c
11313 therefore a parallel @command{make} will have to serialize the builds
11314 of @file{data.c} and @file{data.h}, and will detect that the second is
11315 no longer needed once the first is over.
11317 Using this pattern is probably enough for most cases. However it does
11318 not scale easily to more output files (in this scheme all output files
11319 must be totally ordered by the dependency relation), so we will
11320 explore a more complicated solution.
11322 Another idea is to write the following:
11325 # There is still a problem with this one.
11332 The idea is that @samp{foo data.foo} is run only when @file{data.c}
11333 needs to be updated, but we further state that @file{data.h} depends
11334 upon @file{data.c}. That way, if @file{data.h} is required and
11335 @file{data.foo} is out of date, the dependency on @file{data.c} will
11338 This is almost perfect, but suppose we have built @file{data.h} and
11339 @file{data.c}, and then we erase @file{data.h}. Then, running
11340 @samp{make data.h} will not rebuild @file{data.h}. The above rules
11341 just state that @file{data.c} must be up-to-date with respect to
11342 @file{data.foo}, and this is already the case.
11344 What we need is a rule that forces a rebuild when @file{data.h} is
11345 missing. Here it is:
11351 ## Recover from the removal of $@@
11352 @@if test -f $@@; then :; else \
11354 $(MAKE) $(AM_MAKEFLAGS) data.c; \
11358 The above scheme can be extended to handle more outputs and more
11359 inputs. One of the outputs is selected to serve as a witness to the
11360 successful completion of the command, it depends upon all inputs, and
11361 all other outputs depend upon it. For instance, if @command{foo}
11362 should additionally read @file{data.bar} and also produce
11363 @file{data.w} and @file{data.x}, we would write:
11366 data.c: data.foo data.bar
11367 foo data.foo data.bar
11368 data.h data.w data.x: data.c
11369 ## Recover from the removal of $@@
11370 @@if test -f $@@; then :; else \
11372 $(MAKE) $(AM_MAKEFLAGS) data.c; \
11376 However there are now two minor problems in this setup. One is related
11377 to the timestamp ordering of @file{data.h}, @file{data.w},
11378 @file{data.x}, and @file{data.c}. The other one is a race condition
11379 if a parallel @command{make} attempts to run multiple instances of the
11380 recover block at once.
11382 Let us deal with the first problem. @command{foo} outputs four files,
11383 but we do not know in which order these files are created. Suppose
11384 that @file{data.h} is created before @file{data.c}. Then we have a
11385 weird situation. The next time @command{make} is run, @file{data.h}
11386 will appear older than @file{data.c}, the second rule will be
11387 triggered, a shell will be started to execute the @samp{if@dots{}fi}
11388 command, but actually it will just execute the @code{then} branch,
11389 that is: nothing. In other words, because the witness we selected is
11390 not the first file created by @command{foo}, @command{make} will start
11391 a shell to do nothing each time it is run.
11393 A simple riposte is to fix the timestamps when this happens.
11396 data.c: data.foo data.bar
11397 foo data.foo data.bar
11398 data.h data.w data.x: data.c
11399 @@if test -f $@@; then \
11402 ## Recover from the removal of $@@
11404 $(MAKE) $(AM_MAKEFLAGS) data.c; \
11408 Another solution is to use a different and dedicated file as witness,
11409 rather than using any of @command{foo}'s outputs.
11412 data.stamp: data.foo data.bar
11415 foo data.foo data.bar
11416 @@mv -f data.tmp $@@
11417 data.c data.h data.w data.x: data.stamp
11418 ## Recover from the removal of $@@
11419 @@if test -f $@@; then :; else \
11420 rm -f data.stamp; \
11421 $(MAKE) $(AM_MAKEFLAGS) data.stamp; \
11425 @file{data.tmp} is created before @command{foo} is run, so it has a
11426 timestamp older than output files output by @command{foo}. It is then
11427 renamed to @file{data.stamp} after @command{foo} has run, because we
11428 do not want to update @file{data.stamp} if @command{foo} fails.
11430 This solution still suffers from the second problem: the race
11431 condition in the recover rule. If, after a successful build, a user
11432 erases @file{data.c} and @file{data.h}, and runs @samp{make -j}, then
11433 @command{make} may start both recover rules in parallel. If the two
11434 instances of the rule execute @samp{$(MAKE) $(AM_MAKEFLAGS)
11435 data.stamp} concurrently the build is likely to fail (for instance, the
11436 two rules will create @file{data.tmp}, but only one can rename it).
11438 Admittedly, such a weird situation does not arise during ordinary
11439 builds. It occurs only when the build tree is mutilated. Here
11440 @file{data.c} and @file{data.h} have been explicitly removed without
11441 also removing @file{data.stamp} and the other output files.
11442 @code{make clean; make} will always recover from these situations even
11443 with parallel makes, so you may decide that the recover rule is solely
11444 to help non-parallel make users and leave things as-is. Fixing this
11445 requires some locking mechanism to ensure only one instance of the
11446 recover rule rebuilds @file{data.stamp}. One could imagine something
11447 along the following lines.
11450 data.c data.h data.w data.x: data.stamp
11451 ## Recover from the removal of $@@
11452 @@if test -f $@@; then :; else \
11453 trap 'rm -rf data.lock data.stamp' 1 2 13 15; \
11454 ## mkdir is a portable test-and-set
11455 if mkdir data.lock 2>/dev/null; then \
11456 ## This code is being executed by the first process.
11457 rm -f data.stamp; \
11458 $(MAKE) $(AM_MAKEFLAGS) data.stamp; \
11459 result=$$?; rm -rf data.lock; exit $$result; \
11461 ## This code is being executed by the follower processes.
11462 ## Wait until the first process is done.
11463 while test -d data.lock; do sleep 1; done; \
11464 ## Succeed if and only if the first process succeeded.
11465 test -f data.stamp; \
11470 Using a dedicated witness, like @file{data.stamp}, is very handy when
11471 the list of output files is not known beforehand. As an illustration,
11472 consider the following rules to compile many @file{*.el} files into
11473 @file{*.elc} files in a single command. It does not matter how
11474 @code{ELFILES} is defined (as long as it is not empty: empty targets
11475 are not accepted by POSIX).
11478 ELFILES = one.el two.el three.el @dots{}
11479 ELCFILES = $(ELFILES:=c)
11481 elc-stamp: $(ELFILES)
11484 $(elisp_comp) $(ELFILES)
11485 @@mv -f elc-temp $@@
11487 $(ELCFILES): elc-stamp
11488 ## Recover from the removal of $@@
11489 @@if test -f $@@; then :; else \
11490 trap 'rm -rf elc-lock elc-stamp' 1 2 13 15; \
11491 if mkdir elc-lock 2>/dev/null; then \
11492 ## This code is being executed by the first process.
11494 $(MAKE) $(AM_MAKEFLAGS) elc-stamp; \
11497 ## This code is being executed by the follower processes.
11498 ## Wait until the first process is done.
11499 while test -d elc-lock; do sleep 1; done; \
11500 ## Succeed if and only if the first process succeeded.
11501 test -f elc-stamp; exit $$?; \
11507 For completeness it should be noted that GNU @command{make} is able to
11508 express rules with multiple output files using pattern rules
11509 (@pxref{Pattern Examples, , Pattern Rule Examples, make, The GNU Make
11510 Manual}). We do not discuss pattern rules here because they are not
11511 portable, but they can be convenient in packages that assume GNU
11515 @node Hard-Coded Install Paths
11516 @section Installing to Hard-Coded Locations
11519 My package needs to install some configuration file. I tried to use
11520 the following rule, but @samp{make distcheck} fails. Why?
11524 install-data-local:
11525 $(INSTALL_DATA) $(srcdir)/afile $(DESTDIR)/etc/afile
11530 My package needs to populate the installation directory of another
11531 package at install-time. I can easily compute that installation
11532 directory in @file{configure}, but if I install files therein,
11533 @samp{make distcheck} fails. How else should I do?
11536 These two setups share their symptoms: @samp{make distcheck} fails
11537 because they are installing files to hard-coded paths. In the later
11538 case the path is not really hard-coded in the package, but we can
11539 consider it to be hard-coded in the system (or in whichever tool that
11540 supplies the path). As long as the path does not use any of the
11541 standard directory variables (@samp{$(prefix)}, @samp{$(bindir)},
11542 @samp{$(datadir)}, etc.), the effect will be the same:
11543 user-installations are impossible.
11545 As a (non-root) user who wants to install a package, you usually have no
11546 right to install anything in @file{/usr} or @file{/usr/local}. So you
11547 do something like @samp{./configure --prefix ~/usr} to install a
11548 package in your own @file{~/usr} tree.
11550 If a package attempts to install something to some hard-coded path
11551 (e.g., @file{/etc/afile}), regardless of this @option{--prefix} setting,
11552 then the installation will fail. @samp{make distcheck} performs such
11553 a @option{--prefix} installation, hence it will fail too.
11555 Now, there are some easy solutions.
11557 The above @code{install-data-local} example for installing
11558 @file{/etc/afile} would be better replaced by
11561 sysconf_DATA = afile
11565 by default @code{sysconfdir} will be @samp{$(prefix)/etc}, because
11566 this is what the GNU Standards require. When such a package is
11567 installed on an FHS compliant system, the installer will have to set
11568 @samp{--sysconfdir=/etc}. As the maintainer of the package you
11569 should not be concerned by such site policies: use the appropriate
11570 standard directory variable to install your files so that the installer
11571 can easily redefine these variables to match their site conventions.
11573 Installing files that should be used by another package is slightly
11574 more involved. Let's take an example and assume you want to install
11575 a shared library that is a Python extension module. If you ask Python
11576 where to install the library, it will answer something like this:
11579 % @kbd{python -c 'from distutils import sysconfig;
11580 print sysconfig.get_python_lib(1,0)'}
11581 /usr/lib/python2.5/site-packages
11584 If you indeed use this absolute path to install your shared library,
11585 non-root users will not be able to install the package, hence
11588 Let's do better. The @samp{sysconfig.get_python_lib()} function
11589 actually accepts a third argument that will replace Python's
11590 installation prefix.
11593 % @kbd{python -c 'from distutils import sysconfig;
11594 print sysconfig.get_python_lib(1,0,"$@{exec_prefix@}")'}
11595 $@{exec_prefix@}/lib/python2.5/site-packages
11598 You can also use this new path. If you do
11601 root users can install your package with the same @option{--prefix}
11602 as Python (you get the behavior of the previous attempt)
11605 non-root users can install your package too, they will have the
11606 extension module in a place that is not searched by Python but they
11607 can work around this using environment variables (and if you installed
11608 scripts that use this shared library, it's easy to tell Python were to
11609 look in the beginning of your script, so the script works in both
11613 The @code{AM_PATH_PYTHON} macro uses similar commands to define
11614 @samp{$(pythondir)} and @samp{$(pyexecdir)} (@pxref{Python}).
11616 Of course not all tools are as advanced as Python regarding that
11617 substitution of @var{prefix}. So another strategy is to figure the
11618 part of the installation directory that must be preserved. For
11619 instance, here is how @code{AM_PATH_LISPDIR} (@pxref{Emacs Lisp})
11620 computes @samp{$(lispdir)}:
11623 $EMACS -batch -q -eval '(while load-path
11624 (princ (concat (car load-path) "\n"))
11625 (setq load-path (cdr load-path)))' >conftest.out
11628 -e '/.*\/lib\/x*emacs\/site-lisp$/@{
11629 s,.*/lib/\(x*emacs/site-lisp\)$,$@{libdir@}/\1,;p;q;
11631 -e '/.*\/share\/x*emacs\/site-lisp$/@{
11632 s,.*/share/\(x*emacs/site-lisp\),$@{datarootdir@}/\1,;p;q;
11637 I.e., it just picks the first directory that looks like
11638 @file{*/lib/*emacs/site-lisp} or @file{*/share/*emacs/site-lisp} in
11639 the search path of emacs, and then substitutes @samp{$@{libdir@}} or
11640 @samp{$@{datadir@}} appropriately.
11642 The emacs case looks complicated because it processes a list and
11643 expects two possible layouts, otherwise it's easy, and the benefits for
11644 non-root users are really worth the extra @command{sed} invocation.
11647 @node Debugging Make Rules
11648 @section Debugging Make Rules
11649 @cindex debugging rules
11650 @cindex rules, debugging
11652 The rules and dependency trees generated by @command{automake} can get
11653 rather complex, and leave the developer head-scratching when things
11654 don't work as expected. Besides the debug options provided by the
11655 @command{make} command (@pxref{Options Summary,,, make, The GNU Make
11656 Manual}), here's a couple of further hints for debugging makefiles
11657 generated by @command{automake} effectively:
11661 If less verbose output has been enabled in the package with the
11662 @samp{silent-rules} option (@pxref{Options}), you can use
11663 @code{make V=1} to see the commands being executed.
11665 @code{make -n} can help show what would be done without actually doing
11666 it. Note however, that this will @emph{still execute} commands prefixed
11667 with @samp{+}, and, when using GNU @command{make}, commands that contain
11668 the strings @samp{$(MAKE)} or @samp{$@{MAKE@}} (@pxref{Instead of
11669 Execution,,, make, The GNU Make Manual}).
11670 Typically, this is helpful to show what recursive rules would do, but it
11671 means that, in your own rules, you should not mix such recursion with
11672 actions that change any files.@footnote{Automake's @samp{dist} and
11673 @samp{distcheck} rules had a bug in this regard in that they created
11674 directories even with @option{-n}, but this has been fixed in Automake
11675 1.11.} Furthermore, note that GNU @command{make} will update
11676 prerequisites for the @file{Makefile} file itself even with @option{-n}
11677 (@pxref{Remaking Makefiles,,, make, The GNU Make Manual}).
11679 @code{make SHELL="/bin/bash -vx"} can help debug complex rules.
11680 @xref{The Make Macro SHELL,,, autoconf, The Autoconf Manual}, for some
11681 portability quirks associated with this construct.
11683 @code{echo 'print: ; @@echo "$(VAR)"' | make -f Makefile -f - print}
11684 can be handy to examine the expanded value of variables. You may need
11685 to use a target other than @samp{print} if that is already used or a
11686 file with that name exists.
11688 @url{http://bashdb.sourceforge.net/@/remake/} provides a modified
11689 GNU @command{make} command called @command{remake} that copes with
11690 complex GNU @command{make}-specific Makefiles and allows to trace
11691 execution, examine variables, and call rules interactively, much like
11697 @chapter History of Automake
11699 This chapter presents various aspects of the history of Automake. The
11700 exhausted reader can safely skip it; this will be more of interest to
11701 nostalgic people, or to those curious to learn about the evolution of
11705 * Timeline:: The Automake story.
11706 * Dependency Tracking Evolution:: Evolution of Automatic Dependency Tracking
11707 * Releases:: Statistics about Automake Releases
11714 @item 1994-09-19 First CVS commit.
11716 If we can trust the CVS repository, David J.@tie{}MacKenzie (djm) started
11717 working on Automake (or AutoMake, as it was spelt then) this Monday.
11719 The first version of the @command{automake} script looks as follows.
11728 if test ! -f $@{makefile@}.am; then
11729 echo "automake: $@{makefile@}.am: No such honkin' file"
11734 exec 4> $@{makefile@}.in
11739 From this you can already see that Automake will be about reading
11740 @file{*.am} file and producing @file{*.in} files. You cannot see
11741 anything else, but if you also know that David is the one who created
11742 Autoconf two years before you can guess the rest.
11744 Several commits follow, and by the end of the day Automake is
11745 reported to work for GNU fileutils and GNU m4.
11747 The modus operandi is the one that is still used today: variable
11748 assignments in @file{Makefile.am} files trigger injections of
11749 precanned @file{Makefile} fragments into the generated
11750 @file{Makefile.in}. The use of @file{Makefile} fragments was inspired
11751 by the 4.4BSD @command{make} and include files, however Automake aims
11752 to be portable and to conform to the GNU standards for @file{Makefile}
11753 variables and targets.
11755 At this point, the most recent release of Autoconf is version 1.11,
11756 and David is preparing to release Autoconf 2.0 in late October. As a
11757 matter of fact, he will barely touch Automake after September.
11759 @item 1994-11-05 David MacKenzie's last commit.
11761 At this point Automake is a 200 line portable shell script, plus 332
11762 lines of @file{Makefile} fragments. In the @file{README}, David
11763 states his ambivalence between ``portable shell'' and ``more
11764 appropriate language'':
11767 I wrote it keeping in mind the possibility of it becoming an Autoconf
11768 macro, so it would run at configure-time. That would slow
11769 configuration down a bit, but allow users to modify the Makefile.am
11770 without needing to fetch the AutoMake package. And, the Makefile.in
11771 files wouldn't need to be distributed. But all of AutoMake would. So
11772 I might reimplement AutoMake in Perl, m4, or some other more
11773 appropriate language.
11776 Automake is described as ``an experimental Makefile generator''.
11777 There is no documentation. Adventurous users are referred to the
11778 examples and patches needed to use Automake with GNU m4 1.3, fileutils
11779 3.9, time 1.6, and development versions of find and indent.
11781 These examples seem to have been lost. However at the time of writing
11782 (10 years later in September, 2004) the FSF still distributes a
11783 package that uses this version of Automake: check out GNU termutils
11786 @item 1995-11-12 Tom Tromey's first commit.
11788 After one year of inactivity, Tom Tromey takes over the package.
11789 Tom was working on GNU cpio back then, and doing this just for fun,
11790 having trouble finding a project to contribute to. So while hacking
11791 he wanted to bring the @file{Makefile.in} up to GNU standards. This
11792 was hard, and one day he saw Automake on @url{ftp://alpha.gnu.org/},
11793 grabbed it and tried it out.
11795 Tom didn't talk to djm about it until later, just to make sure he
11796 didn't mind if he made a release. He did a bunch of early releases to
11799 Gnits was (and still is) totally informal, just a few GNU friends who
11800 Fran@,cois Pinard knew, who were all interested in making a common
11801 infrastructure for GNU projects, and shared a similar outlook on how
11802 to do it. So they were able to make some progress. It came along
11803 with Autoconf and extensions thereof, and then Automake from David and
11804 Tom (who were both gnitsians). One of their ideas was to write a
11805 document paralleling the GNU standards, that was more strict in some
11806 ways and more detailed. They never finished the GNITS standards, but
11807 the ideas mostly made their way into Automake.
11809 @item 1995-11-23 Automake 0.20
11811 Besides introducing automatic dependency tracking (@pxref{Dependency
11812 Tracking Evolution}), this version also supplies a 9-page manual.
11814 At this time @command{aclocal} and @code{AM_INIT_AUTOMAKE} did not
11815 exist, so many things had to be done by hand. For instance, here is
11816 what a configure.in (this is the former name of the
11817 @file{configure.ac} we use today) must contain in order to use
11823 AC_DEFINE_UNQUOTED(PACKAGE, "$PACKAGE")
11824 AC_DEFINE_UNQUOTED(VERSION, "$VERSION")
11831 (Today all of the above is achieved by @code{AC_INIT} and
11832 @code{AM_INIT_AUTOMAKE}.)
11834 Here is how programs are specified in @file{Makefile.am}:
11838 hello_SOURCES = hello.c
11841 This looks pretty much like what we do today, except the
11842 @code{PROGRAMS} variable has no directory prefix specifying where
11843 @file{hello} should be installed: all programs are installed in
11844 @samp{$(bindir)}. @code{LIBPROGRAMS} can be used to specify programs
11845 that must be built but not installed (it is called
11846 @code{noinst_PROGRAMS} nowadays).
11848 Programs can be built conditionally using @code{AC_SUBST}itutions:
11851 PROGRAMS = @@progs@@
11852 AM_PROGRAMS = foo bar baz
11855 (@code{AM_PROGRAMS} has since then been renamed to
11856 @code{EXTRA_PROGRAMS}.)
11858 Similarly scripts, static libraries, and data can be built and installed
11859 using the @code{LIBRARIES}, @code{SCRIPTS}, and @code{DATA} variables.
11860 However @code{LIBRARIES} were treated a bit specially in that Automake
11861 did automatically supply the @file{lib} and @file{.a} prefixes.
11862 Therefore to build @file{libcpio.a}, one had to write
11869 Extra files to distribute must be listed in @code{DIST_OTHER} (the
11870 ancestor of @code{EXTRA_DIST}). Also extra directories that are to be
11871 distributed should appear in @code{DIST_SUBDIRS}, but the manual
11872 describes this as a temporary ugly hack (today extra directories should
11873 also be listed in @code{EXTRA_DIST}, and @code{DIST_SUBDIRS} is used
11874 for another purpose, @pxref{Conditional Subdirectories}).
11876 @item 1995-11-26 Automake 0.21
11878 In less time than it takes to cook a frozen pizza, Tom rewrites
11879 Automake using Perl. At this time Perl 5 is only one year old, and
11880 Perl 4.036 is in use at many sites. Supporting several Perl versions
11881 has been a source of problems through the whole history of Automake.
11883 If you never used Perl 4, imagine Perl 5 without objects, without
11884 @samp{my} variables (only dynamically scoped @samp{local} variables),
11885 without function prototypes, with function calls that needs to be
11886 prefixed with @samp{&}, etc. Traces of this old style can still be
11887 found in today's @command{automake}.
11889 @item 1995-11-28 Automake 0.22
11890 @itemx 1995-11-29 Automake 0.23
11894 @item 1995-12-08 Automake 0.24
11895 @itemx 1995-12-10 Automake 0.25
11897 Releases are raining. 0.24 introduces the uniform naming scheme we
11898 use today, i.e., @code{bin_PROGRAMS} instead of @code{PROGRAMS},
11899 @code{noinst_LIBRARIES} instead of @code{LIBLIBRARIES}, etc. (However
11900 @code{EXTRA_PROGRAMS} does not exist yet, @code{AM_PROGRAMS} is still
11901 in use; and @code{TEXINFOS} and @code{MANS} still have no directory
11902 prefixes.) Adding support for prefixes like that was one of the major
11903 ideas in @command{automake}; it has lasted pretty well.
11905 AutoMake is renamed to Automake (Tom seems to recall it was Fran@,cois
11908 0.25 fixes a Perl 4 portability bug.
11910 @item 1995-12-18 Jim Meyering starts using Automake in GNU Textutils.
11911 @item 1995-12-31 Fran@,cois Pinard starts using Automake in GNU tar.
11913 @item 1996-01-03 Automake 0.26
11914 @itemx 1996-01-03 Automake 0.27
11916 Of the many changes and suggestions sent by Fran@,cois Pinard and
11917 included in 0.26, perhaps the most important is the advice that to
11918 ease customization a user rule or variable definition should always
11919 override an Automake rule or definition.
11921 Gordon Matzigkeit and Jim Meyering are two other early contributors
11922 that have been sending fixes.
11924 0.27 fixes yet another Perl 4 portability bug.
11926 @item 1996-01-13 Automake 0.28
11928 Automake starts scanning @file{configure.in} for @code{LIBOBJS}
11929 support. This is an important step because until this version
11930 Automake only knew about the @file{Makefile.am}s it processed.
11931 @file{configure.in} was Autoconf's world and the link between Autoconf
11932 and Automake had to be done by the @file{Makefile.am} author. For
11933 instance, if @file{config.h} was generated by @file{configure}, it was the
11934 package maintainer's responsibility to define the @code{CONFIG_HEADER}
11935 variable in each @file{Makefile.am}.
11937 Succeeding releases will rely more and more on scanning
11938 @file{configure.in} to better automate the Autoconf integration.
11940 0.28 also introduces the @code{AUTOMAKE_OPTIONS} variable and the
11941 @option{--gnu} and @option{--gnits} options, the latter being stricter.
11943 @item 1996-02-07 Automake 0.29
11945 Thanks to @file{configure.in} scanning, @code{CONFIG_HEADER} is gone,
11946 and rebuild rules for @file{configure}-generated file are
11947 automatically output.
11949 @code{TEXINFOS} and @code{MANS} converted to the uniform naming
11952 @item 1996-02-24 Automake 0.30
11954 The test suite is born. It contains 9 tests. From now on test cases
11955 will be added pretty regularly (@pxref{Releases}), and this proved to
11956 be really helpful later on.
11958 @code{EXTRA_PROGRAMS} finally replaces @code{AM_PROGRAMS}.
11960 All the third-party Autoconf macros, written mostly by Fran@,cois
11961 Pinard (and later Jim Meyering), are distributed in Automake's
11962 hand-written @file{aclocal.m4} file. Package maintainers are expected
11963 to extract the necessary macros from this file. (In previous versions
11964 you had to copy and paste them from the manual...)
11966 @item 1996-03-11 Automake 0.31
11968 The test suite in 0.30 was run via a long @code{check-local} rule. Upon
11969 Ulrich Drepper's suggestion, 0.31 makes it an Automake rule output
11970 whenever the @code{TESTS} variable is defined.
11972 @code{DIST_OTHER} is renamed to @code{EXTRA_DIST}, and the @code{check_}
11973 prefix is introduced. The syntax is now the same as today.
11975 @item 1996-03-15 Gordon Matzigkeit starts writing libtool.
11977 @item 1996-04-27 Automake 0.32
11979 @code{-hook} targets are introduced; an idea from Dieter Baron.
11981 @file{*.info} files, which were output in the build directory are
11982 now built in the source directory, because they are distributed. It
11983 seems these files like to move back and forth as that will happen
11984 again in future versions.
11986 @item 1996-05-18 Automake 0.33
11988 Gord Matzigkeit's main two contributions:
11991 @item very preliminary libtool support
11992 @item the distcheck rule
11995 Although they were very basic at this point, these are probably
11996 among the top features for Automake today.
11998 Jim Meyering also provides the infamous @code{jm_MAINTAINER_MODE},
11999 since then renamed to @code{AM_MAINTAINER_MODE} and abandoned by its
12000 author (@pxref{maintainer-mode}).
12002 @item 1996-05-28 Automake 1.0
12004 After only six months of heavy development, the @command{automake} script is
12005 3134 lines long, plus 973 lines of @file{Makefile} fragments. The
12006 package has 30 pages of documentation, and 38 test cases.
12007 @file{aclocal.m4} contains 4 macros.
12009 From now on and until version 1.4, new releases will occur at a rate
12010 of about one a year. 1.1 did not exist, actually 1.1b to 1.1p have
12011 been the name of beta releases for 1.2. This is the first time
12012 Automake uses suffix letters to designate beta releases, a habit that
12015 @item 1996-10-10 Kevin Dalley packages Automake 1.0 for Debian GNU/Linux.
12017 @item 1996-11-26 David J.@tie{}MacKenzie releases Autoconf 2.12.
12019 Between June and October, the Autoconf development is almost stalled.
12020 Roland McGrath has been working at the beginning of the year. David
12021 comes back in November to release 2.12, but he won't touch Autoconf
12022 anymore after this year, and Autoconf then really stagnates. The
12023 desolate Autoconf @file{ChangeLog} for 1997 lists only 7 commits.
12025 @item 1997-02-28 @email{automake@@gnu.ai.mit.edu} list alive
12027 The mailing list is announced as follows:
12029 I've created the "automake" mailing list. It is
12030 "automake@@gnu.ai.mit.edu". Administrivia, as always, to
12031 automake-request@@gnu.ai.mit.edu.
12033 The charter of this list is discussion of automake, autoconf, and
12034 other configuration/portability tools (e.g., libtool). It is expected
12035 that discussion will range from pleas for help all the way up to
12038 This list is archived on the FSF machines. Offhand I don't know if
12039 you can get the archive without an account there.
12041 This list is open to anybody who wants to join. Tell all your
12046 Before that people were discussing Automake privately, on the Gnits
12047 mailing list (which is not public either), and less frequently on
12048 @code{gnu.misc.discuss}.
12050 @code{gnu.ai.mit.edu} is now @code{gnu.org}, in case you never
12051 noticed. The archives of the early years of the
12052 @code{automake@@gnu.org} list have been lost, so today it is almost
12053 impossible to find traces of discussions that occurred before 1999.
12054 This has been annoying more than once, as such discussions can be
12055 useful to understand the rationale behind a piece of uncommented code
12056 that was introduced back then.
12058 @item 1997-06-22 Automake 1.2
12060 Automake developments continues, and more and more new Autoconf macros
12061 are required. Distributing them in @file{aclocal.m4} and requiring
12062 people to browse this file to extract the relevant macros becomes
12063 uncomfortable. Ideally, some of them should be contributed to
12064 Autoconf so that they can be used directly, however Autoconf is
12065 currently inactive. Automake 1.2 consequently introduces
12066 @command{aclocal} (@command{aclocal} was actually started on
12067 1996-07-28), a tool that automatically constructs an @file{aclocal.m4}
12068 file from a repository of third-party macros. Because Autoconf has
12069 stalled, Automake also becomes a kind of repository for such
12070 third-party macros, even macros completely unrelated to Automake (for
12071 instance macros that fix broken Autoconf macros).
12073 The 1.2 release contains 20 macros, including the
12074 @code{AM_INIT_AUTOMAKE} macro that simplifies the creation of
12075 @file{configure.in}.
12077 Libtool is fully supported using @code{*_LTLIBRARIES}.
12079 The missing script is introduced by Fran@,cois Pinard; it is meant to be
12080 a better solution than @code{AM_MAINTAINER_MODE}
12081 (@pxref{maintainer-mode}).
12083 Conditionals support was implemented by Ian Lance Taylor. At the
12084 time, Tom and Ian were working on an internal project at Cygnus. They
12085 were using ILU, which is pretty similar to CORBA@. They wanted to
12086 integrate ILU into their build, which was all @file{configure}-based,
12087 and Ian thought that adding conditionals to @command{automake} was
12088 simpler than doing all the work in @file{configure} (which was the
12089 standard at the time). So this was actually funded by Cygnus.
12091 This very useful but tricky feature will take a lot of time to
12092 stabilize. (At the time this text is written, there are still
12093 primaries that have not been updated to support conditional
12094 definitions in Automake 1.9.)
12096 The @command{automake} script has almost doubled: 6089 lines of Perl,
12097 plus 1294 lines of @file{Makefile} fragments.
12099 @item 1997-07-08 Gordon Matzigkeit releases Libtool 1.0.
12101 @item 1998-04-05 Automake 1.3
12103 This is a small advance compared to 1.2.
12104 It adds support for assembly, and preliminary support for Java.
12106 Perl 5.004_04 is out, but fixes to support Perl 4 are still
12107 regularly submitted whenever Automake breaks it.
12109 @item 1998-09-06 @code{sourceware.cygnus.com} is on-line.
12111 Sourceware was setup by Jason Molenda to host open source projects.
12113 @item 1998-09-19 Automake CVS repository moved to @code{sourceware.cygnus.com}
12114 @itemx 1998-10-26 @code{sourceware.cygnus.com} announces it hosts Automake:
12115 Automake is now hosted on @code{sourceware.cygnus.com}. It has a
12116 publicly accessible CVS repository. This CVS repository is a copy of
12117 the one Tom was using on his machine, which in turn is based on
12118 a copy of the CVS repository of David MacKenzie. This is why we still
12119 have to full source history. (Automake was on Sourceware until 2007-10-29,
12120 when it moved to a git repository on @code{savannah.gnu.org},
12121 but the Sourceware host had been renamed to @code{sources.redhat.com}.)
12123 The oldest file in the administrative directory of the CVS repository
12124 that was created on Sourceware is dated 1998-09-19, while the
12125 announcement that @command{automake} and @command{autoconf} had joined
12126 @command{sourceware} was made on 1998-10-26. They were among the
12127 first projects to be hosted there.
12129 The heedful reader will have noticed Automake was exactly 4 years old
12132 @item 1999-01-05 Ben Elliston releases Autoconf 2.13.
12134 @item 1999-01-14 Automake 1.4
12136 This release adds support for Fortran 77 and for the @code{include}
12137 statement. Also, @samp{+=} assignments are introduced, but it is
12138 still quite easy to fool Automake when mixing this with conditionals.
12140 These two releases, Automake 1.4 and Autoconf 2.13 make a duo that
12141 will be used together for years.
12143 @command{automake} is 7228 lines, plus 1591 lines of Makefile
12144 fragment, 20 macros (some 1.3 macros were finally contributed back to
12145 Autoconf), 197 test cases, and 51 pages of documentation.
12147 @item 1999-03-27 The @code{user-dep-branch} is created on the CVS repository.
12149 This implements a new dependency tracking schemed that should be
12150 able to handle automatic dependency tracking using any compiler (not
12151 just gcc) and any make (not just GNU @command{make}). In addition,
12152 the new scheme should be more reliable than the old one, as
12153 dependencies are generated on the end user's machine. Alexandre Oliva
12154 creates depcomp for this purpose.
12156 @xref{Dependency Tracking Evolution}, for more details about the
12157 evolution of automatic dependency tracking in Automake.
12159 @item 1999-11-21 The @code{user-dep-branch} is merged into the main trunk.
12161 This was a huge problem since we also had patches going in on the
12162 trunk. The merge took a long time and was very painful.
12166 Since September 1999 and until 2003, Akim Demaille will be zealously
12167 revamping Autoconf.
12170 I think the next release should be called "3.0".@*
12171 Let's face it: you've basically rewritten autoconf.@*
12172 Every weekend there are 30 new patches.@*
12173 I don't see how we could call this "2.15" with a straight face.@*
12174 -- Tom Tromey on @email{autoconf@@gnu.org}
12177 Actually Akim works like a submarine: he will pile up patches while he
12178 works off-line during the weekend, and flush them in batch when he
12179 resurfaces on Monday.
12183 On this Wednesday, Autoconf 2.49c, the last beta before Autoconf 2.50
12184 is out, and Akim has to find something to do during his week-end :)
12188 Akim sends a batch of 14 patches to @email{automake@@gnu.org}.
12191 Aiieeee! I was dreading the day that the Demaillator turned his
12192 sights on automake@dots{} and now it has arrived! -- Tom Tromey
12195 It's only the beginning: in two months he will send 192 patches. Then
12196 he would slow down so Tom can catch up and review all this. Initially
12197 Tom actually read all these patches, then he probably trustingly
12198 answered OK to most of them, and finally gave up and let Akim apply
12199 whatever he wanted. There was no way to keep up with that patch rate.
12202 Anyway the patch below won't apply since it predates Akim's
12203 sourcequake; I have yet to figure where the relevant passage has
12204 been moved :) -- Alexandre Duret-Lutz
12207 All these patches were sent to and discussed on
12208 @email{automake@@gnu.org}, so subscribed users were literally drowning in
12209 technical mails. Eventually, the @email{automake-patches@@gnu.org}
12210 mailing list was created in May.
12212 Year after year, Automake had drifted away from its initial design:
12213 construct @file{Makefile.in} by assembling various @file{Makefile}
12214 fragments. In 1.4, lots of @file{Makefile} rules are being emitted at
12215 various places in the @command{automake} script itself; this does not
12216 help ensuring a consistent treatment of these rules (for instance
12217 making sure that user-defined rules override Automake's own rules).
12218 One of Akim's goal was moving all these hard-coded rules to separate
12219 @file{Makefile} fragments, so the logic could be centralized in a
12220 @file{Makefile} fragment processor.
12222 Another significant contribution of Akim is the interface with the
12223 ``trace'' feature of Autoconf. The way to scan @file{configure.in} at
12224 this time was to read the file and grep the various macro of interest
12225 to Automake. Doing so could break in many unexpected ways; @command{automake}
12226 could miss some definition (for instance @samp{AC_SUBST([$1], [$2])}
12227 where the arguments are known only when M4 is run), or conversely it
12228 could detect some macro that was not expanded (because it is called
12229 conditionally). In the CVS version of Autoconf, Akim had implemented
12230 the @option{--trace} option, which provides accurate information about
12231 where macros are actually called and with what arguments. Akim will
12232 equip Automake with a second @file{configure.in} scanner that uses
12233 this @option{--trace} interface. Since it was not sensible to drop the
12234 Autoconf 2.13 compatibility yet, this experimental scanner was only
12235 used when an environment variable was set, the traditional
12236 grep-scanner being still the default.
12238 @item 2001-04-25 Gary V.@tie{}Vaughan releases Libtool 1.4
12240 It has been more than two years since Automake 1.4, CVS Automake has
12241 suffered lot's of heavy changes and still is not ready for release.
12242 Libtool 1.4 had to be distributed with a patch against Automake 1.4.
12244 @item 2001-05-08 Automake 1.4-p1
12245 @itemx 2001-05-24 Automake 1.4-p2
12247 Gary V.@tie{}Vaughan, the principal Libtool maintainer, makes a ``patch
12248 release'' of Automake:
12251 The main purpose of this release is to have a stable automake
12252 which is compatible with the latest stable libtool.
12255 The release also contains obvious fixes for bugs in Automake 1.4,
12256 some of which were reported almost monthly.
12258 @item 2001-05-21 Akim Demaille releases Autoconf 2.50
12260 @item 2001-06-07 Automake 1.4-p3
12261 @itemx 2001-06-10 Automake 1.4-p4
12262 @itemx 2001-07-15 Automake 1.4-p5
12264 Gary continues his patch-release series. These also add support for
12265 some new Autoconf 2.50 idioms. Essentially, Autoconf now advocates
12266 @file{configure.ac} over @file{configure.in}, and it introduces a new
12267 syntax for @code{AC_OUTPUT}ing files.
12269 @item 2001-08-23 Automake 1.5
12271 A major and long-awaited release, that comes more than two years after
12272 1.4. It brings many changes, among which:
12274 @item The new dependency tracking scheme that uses @command{depcomp}.
12275 Aside from the improvement on the dependency tracking itself
12276 (@pxref{Dependency Tracking Evolution}), this also streamlines the use
12277 of @command{automake}-generated @file{Makefile.in}s as the @file{Makefile.in}s
12278 used during development are now the same as those used in
12279 distributions. Before that the @file{Makefile.in}s generated for
12280 maintainers required GNU @command{make} and GCC, they were different
12281 from the portable @file{Makefile} generated for distribution; this was
12282 causing some confusion.
12284 @item Support for per-target compilation flags.
12286 @item Support for reference to files in subdirectories in most
12287 @file{Makefile.am} variables.
12289 @item Introduction of the @code{dist_}, @code{nodist_}, and @code{nobase_}
12291 @item Perl 4 support is finally dropped.
12294 1.5 did break several packages that worked with 1.4. Enough so that
12295 Linux distributions could not easily install the new Automake version
12296 without breaking many of the packages for which they had to run
12297 @command{automake}.
12299 Some of these breakages were effectively bugs that would eventually be
12300 fixed in the next release. However, a lot of damage was caused by
12301 some changes made deliberately to render Automake stricter on some
12302 setup we did consider bogus. For instance, @samp{make distcheck} was
12303 improved to check that @samp{make uninstall} did remove all the files
12304 @samp{make install} installed, that @samp{make distclean} did not omit
12305 some file, and that a VPATH build would work even if the source
12306 directory was read-only. Similarly, Automake now rejects multiple
12307 definitions of the same variable (because that would mix very badly
12308 with conditionals), and @samp{+=} assignments with no previous
12309 definition. Because these changes all occurred suddenly after 1.4 had
12310 been established for more than two years, it hurt users.
12312 To make matter worse, meanwhile Autoconf (now at version 2.52) was
12313 facing similar troubles, for similar reasons.
12315 @item 2002-03-05 Automake 1.6
12317 This release introduced versioned installation (@pxref{API
12318 Versioning}). This was mainly pushed by Havoc Pennington, taking the
12319 GNOME source tree as motive: due to incompatibilities between the
12320 autotools it's impossible for the GNOME packages to switch to Autoconf
12321 2.53 and Automake 1.5 all at once, so they are currently stuck with
12322 Autoconf 2.13 and Automake 1.4.
12324 The idea was to call this version @file{automake-1.6}, call all its
12325 bug-fix versions identically, and switch to @file{automake-1.7} for
12326 the next release that adds new features or changes some rules. This
12327 scheme implies maintaining a bug-fix branch in addition to the
12328 development trunk, which means more work from the maintainer, but
12329 providing regular bug-fix releases proved to be really worthwhile.
12331 Like 1.5, 1.6 also introduced a bunch of incompatibilities, intentional or
12332 not. Perhaps the more annoying was the dependence on the newly
12333 released Autoconf 2.53. Autoconf seemed to have stabilized enough
12334 since its explosive 2.50 release and included changes required to fix
12335 some bugs in Automake. In order to upgrade to Automake 1.6, people
12336 now had to upgrade Autoconf too; for some packages it was no picnic.
12338 While versioned installation helped people to upgrade, it also
12339 unfortunately allowed people not to upgrade. At the time of writing,
12340 some Linux distributions are shipping packages for Automake 1.4, 1.5,
12341 1.6, 1.7, 1.8, and 1.9. Most of these still install 1.4 by default.
12342 Some distribution also call 1.4 the ``stable'' version, and present
12343 ``1.9'' as the development version; this does not really makes sense
12344 since 1.9 is way more solid than 1.4. All this does not help the
12347 @item 2002-04-11 Automake 1.6.1
12349 1.6, and the upcoming 1.4-p6 release were the last release by Tom.
12350 This one and those following will be handled by Alexandre
12351 Duret-Lutz. Tom is still around, and will be there until about 1.7,
12352 but his interest into Automake is drifting away towards projects like
12355 Alexandre has been using Automake since 2000, and started to
12356 contribute mostly on Akim's incitement (Akim and Alexandre have been
12357 working in the same room from 1999 to 2002). In 2001 and 2002 he had
12358 a lot of free time to enjoy hacking Automake.
12360 @item 2002-06-14 Automake 1.6.2
12362 @item 2002-07-28 Automake 1.6.3
12363 @itemx 2002-07-28 Automake 1.4-p6
12365 Two releases on the same day. 1.6.3 is a bug-fix release.
12367 Tom Tromey backported the versioned installation mechanism on the 1.4
12368 branch, so that Automake 1.6.x and Automake 1.4-p6 could be installed
12369 side by side. Another request from the GNOME folks.
12371 @item 2002-09-25 Automake 1.7
12373 This release switches to the new @file{configure.ac} scanner Akim
12374 was experimenting in 1.5.
12376 @item 2002-10-16 Automake 1.7.1
12377 @itemx 2002-12-06 Automake 1.7.2
12378 @itemx 2003-02-20 Automake 1.7.3
12379 @itemx 2003-04-23 Automake 1.7.4
12380 @itemx 2003-05-18 Automake 1.7.5
12381 @itemx 2003-07-10 Automake 1.7.6
12382 @itemx 2003-09-07 Automake 1.7.7
12383 @itemx 2003-10-07 Automake 1.7.8
12385 Many bug-fix releases. 1.7 lasted because the development version
12386 (upcoming 1.8) was suffering some major internal revamping.
12388 @item 2003-10-26 Automake on screen
12390 Episode 49, `Repercussions', in the third season of the `Alias' TV
12391 show is first aired.
12393 Marshall, one of the characters, is working on a computer virus that he
12394 has to modify before it gets into the wrong hands or something like
12395 that. The screenshots you see do not show any program code, they show
12396 a @file{Makefile.in} @code{generated by automake}...
12398 @item 2003-11-09 Automake 1.7.9
12400 @item 2003-12-10 Automake 1.8
12402 The most striking update is probably that of @command{aclocal}.
12404 @command{aclocal} now uses @code{m4_include} in the produced
12405 @file{aclocal.m4} when the included macros are already distributed
12406 with the package (an idiom used in many packages), which reduces code
12407 duplication. Many people liked that, but in fact this change was
12408 really introduced to fix a bug in rebuild rules: @file{Makefile.in}
12409 must be rebuilt whenever a dependency of @file{configure} changes, but
12410 all the @file{m4} files included in @file{aclocal.m4} where unknown
12411 from @command{automake}. Now @command{automake} can just trace the
12412 @code{m4_include}s to discover the dependencies.
12414 @command{aclocal} also starts using the @option{--trace} Autoconf option
12415 in order to discover used macros more accurately. This will turn out
12416 to be very tricky (later releases will improve this) as people had
12417 devised many ways to cope with the limitation of previous
12418 @command{aclocal} versions, notably using handwritten
12419 @code{m4_include}s: @command{aclocal} must make sure not to redefine a
12420 rule that is already included by such statement.
12422 Automake also has seen its guts rewritten. Although this rewriting
12423 took a lot of efforts, it is only apparent to the users in that some
12424 constructions previously disallowed by the implementation now work
12425 nicely. Conditionals, Locations, Variable and Rule definitions,
12426 Options: these items on which Automake works have been rewritten as
12427 separate Perl modules, and documented.
12429 @itemx 2004-01-11 Automake 1.8.1
12430 @itemx 2004-01-12 Automake 1.8.2
12431 @itemx 2004-03-07 Automake 1.8.3
12432 @itemx 2004-04-25 Automake 1.8.4
12433 @itemx 2004-05-16 Automake 1.8.5
12435 @item 2004-07-28 Automake 1.9
12437 This release tries to simplify the compilation rules it outputs to
12438 reduce the size of the Makefile. The complaint initially come from
12439 the libgcj developers. Their @file{Makefile.in} generated with
12440 Automake 1.4 and custom build rules (1.4 did not support compiled
12441 Java) is 250KB@. The one generated by 1.8 was over 9MB@! 1.9 gets it
12444 Aside from this it contains mainly minor changes and bug-fixes.
12446 @itemx 2004-08-11 Automake 1.9.1
12447 @itemx 2004-09-19 Automake 1.9.2
12449 Automake has ten years. This chapter of the manual was initially
12450 written for this occasion.
12452 @itemx 2007-10-29 Automake repository moves to @code{savannah.gnu.org} and uses
12453 git as primary repository.
12457 @node Dependency Tracking Evolution
12458 @section Dependency Tracking in Automake
12460 Over the years Automake has deployed three different dependency
12461 tracking methods. Each method, including the current one, has had
12462 flaws of various sorts. Here we lay out the different dependency
12463 tracking methods, their flaws, and their fixes. We conclude with
12464 recommendations for tool writers, and by indicating future directions
12465 for dependency tracking work in Automake.
12468 * First Take on Dependencies:: Precomputed dependency tracking
12469 * Dependencies As Side Effects:: Update at developer compile time
12470 * Dependencies for the User:: Update at user compile time
12471 * Techniques for Dependencies:: Alternative approaches
12472 * Recommendations for Tool Writers:: What tool writers can do to help
12473 * Future Directions for Dependencies:: Languages Automake does not know
12476 @node First Take on Dependencies
12477 @subsection First Take on Dependency Tracking
12478 @unnumberedsubsubsec Description
12480 Our first attempt at automatic dependency tracking was based on the
12481 method recommended by GNU @command{make}. (@pxref{Automatic
12482 Prerequisites, , Generating Prerequisites Automatically, make, The GNU
12485 This version worked by precomputing dependencies ahead of time. For
12486 each source file, it had a special @file{.P} file that held the
12487 dependencies. There was a rule to generate a @file{.P} file by
12488 invoking the compiler appropriately. All such @file{.P} files were
12489 included by the @file{Makefile}, thus implicitly becoming dependencies
12490 of @file{Makefile}.
12492 @unnumberedsubsubsec Bugs
12494 This approach had several critical bugs.
12498 The code to generate the @file{.P} file relied on @command{gcc}.
12499 (A limitation, not technically a bug.)
12501 The dependency tracking mechanism itself relied on GNU @command{make}.
12502 (A limitation, not technically a bug.)
12504 Because each @file{.P} file was a dependency of @file{Makefile}, this
12505 meant that dependency tracking was done eagerly by @command{make}.
12506 For instance, @samp{make clean} would cause all the dependency files
12507 to be updated, and then immediately removed. This eagerness also
12508 caused problems with some configurations; if a certain source file
12509 could not be compiled on a given architecture for some reason,
12510 dependency tracking would fail, aborting the entire build.
12512 As dependency tracking was done as a pre-pass, compile times were
12513 doubled--the compiler had to be run twice per source file.
12515 @samp{make dist} re-ran @command{automake} to generate a
12516 @file{Makefile} that did not have automatic dependency tracking (and
12517 that was thus portable to any version of @command{make}). In order to
12518 do this portably, Automake had to scan the dependency files and remove
12519 any reference that was to a source file not in the distribution.
12520 This process was error-prone. Also, if @samp{make dist} was run in an
12521 environment where some object file had a dependency on a source file
12522 that was only conditionally created, Automake would generate a
12523 @file{Makefile} that referred to a file that might not appear in the
12524 end user's build. A special, hacky mechanism was required to work
12528 @unnumberedsubsubsec Historical Note
12530 The code generated by Automake is often inspired by the
12531 @file{Makefile} style of a particular author. In the case of the first
12532 implementation of dependency tracking, I believe the impetus and
12533 inspiration was Jim Meyering. (I could be mistaken. If you know
12534 otherwise feel free to correct me.)
12536 @node Dependencies As Side Effects
12537 @subsection Dependencies As Side Effects
12538 @unnumberedsubsubsec Description
12540 The next refinement of Automake's automatic dependency tracking scheme
12541 was to implement dependencies as side effects of the compilation.
12542 This was aimed at solving the most commonly reported problems with the
12543 first approach. In particular we were most concerned with eliminating
12544 the weird rebuilding effect associated with make clean.
12546 In this approach, the @file{.P} files were included using the
12547 @code{-include} command, which let us create these files lazily. This
12548 avoided the @samp{make clean} problem.
12550 We only computed dependencies when a file was actually compiled. This
12551 avoided the performance penalty associated with scanning each file
12552 twice. It also let us avoid the other problems associated with the
12553 first, eager, implementation. For instance, dependencies would never
12554 be generated for a source file that was not compilable on a given
12555 architecture (because it in fact would never be compiled).
12557 @unnumberedsubsubsec Bugs
12561 This approach also relied on the existence of @command{gcc} and GNU
12562 @command{make}. (A limitation, not technically a bug.)
12564 Dependency tracking was still done by the developer, so the problems
12565 from the first implementation relating to massaging of dependencies by
12566 @samp{make dist} were still in effect.
12568 This implementation suffered from the ``deleted header file'' problem.
12569 Suppose a lazily-created @file{.P} file includes a dependency on a
12570 given header file, like this:
12573 maude.o: maude.c something.h
12576 Now suppose that you remove @file{something.h} and update @file{maude.c}
12577 so that this include is no longer needed. If you run @command{make},
12578 you will get an error because there is no way to create
12579 @file{something.h}.
12581 We fixed this problem in a later release by further massaging the
12582 output of @command{gcc} to include a dummy dependency for each header
12586 @node Dependencies for the User
12587 @subsection Dependencies for the User
12588 @unnumberedsubsubsec Description
12590 The bugs associated with @samp{make dist}, over time, became a real
12591 problem. Packages using Automake were being built on a large number
12592 of platforms, and were becoming increasingly complex. Broken
12593 dependencies were distributed in ``portable'' @file{Makefile.in}s,
12594 leading to user complaints. Also, the requirement for @command{gcc}
12595 and GNU @command{make} was a constant source of bug reports. The next
12596 implementation of dependency tracking aimed to remove these problems.
12598 We realized that the only truly reliable way to automatically track
12599 dependencies was to do it when the package itself was built. This
12600 meant discovering a method portable to any version of make and any
12601 compiler. Also, we wanted to preserve what we saw as the best point
12602 of the second implementation: dependency computation as a side effect
12605 In the end we found that most modern make implementations support some
12606 form of include directive. Also, we wrote a wrapper script that let
12607 us abstract away differences between dependency tracking methods for
12608 compilers. For instance, some compilers cannot generate dependencies
12609 as a side effect of compilation. In this case we simply have the
12610 script run the compiler twice. Currently our wrapper script
12611 (@command{depcomp}) knows about twelve different compilers (including
12612 a "compiler" that simply invokes @command{makedepend} and then the
12613 real compiler, which is assumed to be a standard Unix-like C compiler
12614 with no way to do dependency tracking).
12616 @unnumberedsubsubsec Bugs
12620 Running a wrapper script for each compilation slows down the build.
12622 Many users don't really care about precise dependencies.
12624 This implementation, like every other automatic dependency tracking
12625 scheme in common use today (indeed, every one we've ever heard of),
12626 suffers from the ``duplicated new header'' bug.
12628 This bug occurs because dependency tracking tools, such as the
12629 compiler, only generate dependencies on the successful opening of a
12630 file, and not on every probe.
12632 Suppose for instance that the compiler searches three directories for
12633 a given header, and that the header is found in the third directory.
12634 If the programmer erroneously adds a header file with the same name to
12635 the first directory, then a clean rebuild from scratch could fail
12636 (suppose the new header file is buggy), whereas an incremental rebuild
12639 What has happened here is that people have a misunderstanding of what
12640 a dependency is. Tool writers think a dependency encodes information
12641 about which files were read by the compiler. However, a dependency
12642 must actually encode information about what the compiler tried to do.
12644 This problem is not serious in practice. Programmers typically do not
12645 use the same name for a header file twice in a given project. (At
12646 least, not in C or C++. This problem may be more troublesome in
12647 Java.) This problem is easy to fix, by modifying dependency
12648 generators to record every probe, instead of every successful open.
12651 Since Automake generates dependencies as a side effect of compilation,
12652 there is a bootstrapping problem when header files are generated by
12653 running a program. The problem is that, the first time the build is
12654 done, there is no way by default to know that the headers are
12655 required, so make might try to run a compilation for which the headers
12656 have not yet been built.
12658 This was also a problem in the previous dependency tracking implementation.
12660 The current fix is to use @code{BUILT_SOURCES} to list built headers
12661 (@pxref{Sources}). This causes them to be built before any other
12662 build rules are run. This is unsatisfactory as a general solution,
12663 however in practice it seems sufficient for most actual programs.
12666 This code is used since Automake 1.5.
12668 In GCC 3.0, we managed to convince the maintainers to add special
12669 command-line options to help Automake more efficiently do its job. We
12670 hoped this would let us avoid the use of a wrapper script when
12671 Automake's automatic dependency tracking was used with @command{gcc}.
12673 Unfortunately, this code doesn't quite do what we want. In
12674 particular, it removes the dependency file if the compilation fails;
12675 we'd prefer that it instead only touch the file in any way if the
12676 compilation succeeds.
12678 Nevertheless, since Automake 1.7, when a recent @command{gcc} is
12679 detected at @command{configure} time, we inline the
12680 dependency-generation code and do not use the @command{depcomp}
12681 wrapper script. This makes compilations faster for those using this
12682 compiler (probably our primary user base). The counterpart is that
12683 because we have to encode two compilation rules in @file{Makefile}
12684 (with or without @command{depcomp}), the produced @file{Makefile}s are
12687 @node Techniques for Dependencies
12688 @subsection Techniques for Computing Dependencies
12690 There are actually several ways for a build tool like Automake to
12691 cause tools to generate dependencies.
12694 @item @command{makedepend}
12695 This was a commonly-used method in the past. The idea is to run a
12696 special program over the source and have it generate dependency
12697 information. Traditional implementations of @command{makedepend} are
12698 not completely precise; ordinarily they were conservative and
12699 discovered too many dependencies.
12701 An obvious way to generate dependencies is to simply write the tool so
12702 that it can generate the information needed by the build tool. This is
12703 also the most portable method. Many compilers have an option to
12704 generate dependencies. Unfortunately, not all tools provide such an
12706 @item The file system
12707 It is possible to write a special file system that tracks opens,
12708 reads, writes, etc, and then feed this information back to the build
12709 tool. @command{clearmake} does this. This is a very powerful
12710 technique, as it doesn't require cooperation from the
12711 tool. Unfortunately it is also very difficult to implement and also
12712 not practical in the general case.
12713 @item @code{LD_PRELOAD}
12714 Rather than use the file system, one could write a special library to
12715 intercept @code{open} and other syscalls. This technique is also quite
12716 powerful, but unfortunately it is not portable enough for use in
12717 @command{automake}.
12720 @node Recommendations for Tool Writers
12721 @subsection Recommendations for Tool Writers
12723 We think that every compilation tool ought to be able to generate
12724 dependencies as a side effect of compilation. Furthermore, at least
12725 while @command{make}-based tools are nearly universally in use (at
12726 least in the free software community), the tool itself should generate
12727 dummy dependencies for header files, to avoid the deleted header file
12728 bug. Finally, the tool should generate a dependency for each probe,
12729 instead of each successful file open, in order to avoid the duplicated
12732 @node Future Directions for Dependencies
12733 @subsection Future Directions for Dependencies
12735 Currently, only languages and compilers understood by Automake can
12736 have dependency tracking enabled. We would like to see if it is
12737 practical (and worthwhile) to let this support be extended by the user
12738 to languages unknown to Automake.
12741 @section Release Statistics
12743 The following table (inspired by @samp{perlhist(1)}) quantifies the
12744 evolution of Automake using these metrics:
12748 The date and version of the release.
12750 The number of lines of the @command{automake} script.
12752 The number of lines of the @command{aclocal} script.
12754 The number of lines of the @command{Perl} supporting modules.
12756 The number of lines of the @file{Makefile} fragments. The number in
12757 parentheses is the number of files.
12759 The number of lines (and files) of Autoconf macros.
12761 The number of pages of the documentation (the Postscript version).
12763 The number of test cases in the test suite. Of those, the number in
12764 parentheses is the number of generated test cases.
12767 @multitable {8888-88-88} {8.8-p8} {8888} {8888} {8888} {8888 (88)} {8888 (88)} {888} {888 (88)}
12768 @headitem Date @tab Rel @tab am @tab acl @tab pm @tab @file{*.am} @tab m4 @tab doc @tab t
12769 @item 1994-09-19 @tab CVS @tab 141 @tab @tab @tab 299 (24) @tab @tab @tab
12770 @item 1994-11-05 @tab CVS @tab 208 @tab @tab @tab 332 (28) @tab @tab @tab
12771 @item 1995-11-23 @tab 0.20 @tab 533 @tab @tab @tab 458 (35) @tab @tab 9 @tab
12772 @item 1995-11-26 @tab 0.21 @tab 613 @tab @tab @tab 480 (36) @tab @tab 11 @tab
12773 @item 1995-11-28 @tab 0.22 @tab 1116 @tab @tab @tab 539 (38) @tab @tab 12 @tab
12774 @item 1995-11-29 @tab 0.23 @tab 1240 @tab @tab @tab 541 (38) @tab @tab 12 @tab
12775 @item 1995-12-08 @tab 0.24 @tab 1462 @tab @tab @tab 504 (33) @tab @tab 14 @tab
12776 @item 1995-12-10 @tab 0.25 @tab 1513 @tab @tab @tab 511 (37) @tab @tab 15 @tab
12777 @item 1996-01-03 @tab 0.26 @tab 1706 @tab @tab @tab 438 (36) @tab @tab 16 @tab
12778 @item 1996-01-03 @tab 0.27 @tab 1706 @tab @tab @tab 438 (36) @tab @tab 16 @tab
12779 @item 1996-01-13 @tab 0.28 @tab 1964 @tab @tab @tab 934 (33) @tab @tab 16 @tab
12780 @item 1996-02-07 @tab 0.29 @tab 2299 @tab @tab @tab 936 (33) @tab @tab 17 @tab
12781 @item 1996-02-24 @tab 0.30 @tab 2544 @tab @tab @tab 919 (32) @tab 85 (1) @tab 20 @tab 9
12782 @item 1996-03-11 @tab 0.31 @tab 2877 @tab @tab @tab 919 (32) @tab 85 (1) @tab 29 @tab 17
12783 @item 1996-04-27 @tab 0.32 @tab 3058 @tab @tab @tab 921 (31) @tab 85 (1) @tab 30 @tab 26
12784 @item 1996-05-18 @tab 0.33 @tab 3110 @tab @tab @tab 926 (31) @tab 105 (1) @tab 30 @tab 35
12785 @item 1996-05-28 @tab 1.0 @tab 3134 @tab @tab @tab 973 (32) @tab 105 (1) @tab 30 @tab 38
12786 @item 1997-06-22 @tab 1.2 @tab 6089 @tab 385 @tab @tab 1294 (36) @tab 592 (20) @tab 37 @tab 126
12787 @item 1998-04-05 @tab 1.3 @tab 6415 @tab 422 @tab @tab 1470 (39) @tab 741 (23) @tab 39 @tab 156
12788 @item 1999-01-14 @tab 1.4 @tab 7240 @tab 426 @tab @tab 1591 (40) @tab 734 (20) @tab 51 @tab 197
12789 @item 2001-05-08 @tab 1.4-p1 @tab 7251 @tab 426 @tab @tab 1591 (40) @tab 734 (20) @tab 51 @tab 197
12790 @item 2001-05-24 @tab 1.4-p2 @tab 7268 @tab 439 @tab @tab 1591 (40) @tab 734 (20) @tab 49 @tab 197
12791 @item 2001-06-07 @tab 1.4-p3 @tab 7312 @tab 439 @tab @tab 1591 (40) @tab 734 (20) @tab 49 @tab 197
12792 @item 2001-06-10 @tab 1.4-p4 @tab 7321 @tab 439 @tab @tab 1591 (40) @tab 734 (20) @tab 49 @tab 198
12793 @item 2001-07-15 @tab 1.4-p5 @tab 7228 @tab 426 @tab @tab 1596 (40) @tab 734 (20) @tab 51 @tab 198
12794 @item 2001-08-23 @tab 1.5 @tab 8016 @tab 475 @tab 600 @tab 2654 (39) @tab 1166 (29) @tab 63 @tab 327
12795 @item 2002-03-05 @tab 1.6 @tab 8465 @tab 475 @tab 1136 @tab 2732 (39) @tab 1603 (27) @tab 66 @tab 365
12796 @item 2002-04-11 @tab 1.6.1 @tab 8544 @tab 475 @tab 1136 @tab 2741 (39) @tab 1603 (27) @tab 66 @tab 372
12797 @item 2002-06-14 @tab 1.6.2 @tab 8575 @tab 475 @tab 1136 @tab 2800 (39) @tab 1609 (27) @tab 67 @tab 386
12798 @item 2002-07-28 @tab 1.6.3 @tab 8600 @tab 475 @tab 1153 @tab 2809 (39) @tab 1609 (27) @tab 67 @tab 391
12799 @item 2002-07-28 @tab 1.4-p6 @tab 7332 @tab 455 @tab @tab 1596 (40) @tab 735 (20) @tab 49 @tab 197
12800 @item 2002-09-25 @tab 1.7 @tab 9189 @tab 471 @tab 1790 @tab 2965 (39) @tab 1606 (28) @tab 73 @tab 430
12801 @item 2002-10-16 @tab 1.7.1 @tab 9229 @tab 475 @tab 1790 @tab 2977 (39) @tab 1606 (28) @tab 73 @tab 437
12802 @item 2002-12-06 @tab 1.7.2 @tab 9334 @tab 475 @tab 1790 @tab 2988 (39) @tab 1606 (28) @tab 77 @tab 445
12803 @item 2003-02-20 @tab 1.7.3 @tab 9389 @tab 475 @tab 1790 @tab 3023 (39) @tab 1651 (29) @tab 84 @tab 448
12804 @item 2003-04-23 @tab 1.7.4 @tab 9429 @tab 475 @tab 1790 @tab 3031 (39) @tab 1644 (29) @tab 85 @tab 458
12805 @item 2003-05-18 @tab 1.7.5 @tab 9429 @tab 475 @tab 1790 @tab 3033 (39) @tab 1645 (29) @tab 85 @tab 459
12806 @item 2003-07-10 @tab 1.7.6 @tab 9442 @tab 475 @tab 1790 @tab 3033 (39) @tab 1660 (29) @tab 85 @tab 461
12807 @item 2003-09-07 @tab 1.7.7 @tab 9443 @tab 475 @tab 1790 @tab 3041 (39) @tab 1660 (29) @tab 90 @tab 467
12808 @item 2003-10-07 @tab 1.7.8 @tab 9444 @tab 475 @tab 1790 @tab 3041 (39) @tab 1660 (29) @tab 90 @tab 468
12809 @item 2003-11-09 @tab 1.7.9 @tab 9444 @tab 475 @tab 1790 @tab 3048 (39) @tab 1660 (29) @tab 90 @tab 468
12810 @item 2003-12-10 @tab 1.8 @tab 7171 @tab 585 @tab 7730 @tab 3236 (39) @tab 1666 (31) @tab 104 @tab 521
12811 @item 2004-01-11 @tab 1.8.1 @tab 7217 @tab 663 @tab 7726 @tab 3287 (39) @tab 1686 (31) @tab 104 @tab 525
12812 @item 2004-01-12 @tab 1.8.2 @tab 7217 @tab 663 @tab 7726 @tab 3288 (39) @tab 1686 (31) @tab 104 @tab 526
12813 @item 2004-03-07 @tab 1.8.3 @tab 7214 @tab 686 @tab 7735 @tab 3303 (39) @tab 1695 (31) @tab 111 @tab 530
12814 @item 2004-04-25 @tab 1.8.4 @tab 7214 @tab 686 @tab 7736 @tab 3310 (39) @tab 1701 (31) @tab 112 @tab 531
12815 @item 2004-05-16 @tab 1.8.5 @tab 7240 @tab 686 @tab 7736 @tab 3299 (39) @tab 1701 (31) @tab 112 @tab 533
12816 @item 2004-07-28 @tab 1.9 @tab 7508 @tab 715 @tab 7794 @tab 3352 (40) @tab 1812 (32) @tab 115 @tab 551
12817 @item 2004-08-11 @tab 1.9.1 @tab 7512 @tab 715 @tab 7794 @tab 3354 (40) @tab 1812 (32) @tab 115 @tab 552
12818 @item 2004-09-19 @tab 1.9.2 @tab 7512 @tab 715 @tab 7794 @tab 3354 (40) @tab 1812 (32) @tab 132 @tab 554
12819 @item 2004-11-01 @tab 1.9.3 @tab 7507 @tab 718 @tab 7804 @tab 3354 (40) @tab 1812 (32) @tab 134 @tab 556
12820 @item 2004-12-18 @tab 1.9.4 @tab 7508 @tab 718 @tab 7856 @tab 3361 (40) @tab 1811 (32) @tab 140 @tab 560
12821 @item 2005-02-13 @tab 1.9.5 @tab 7523 @tab 719 @tab 7859 @tab 3373 (40) @tab 1453 (32) @tab 142 @tab 562
12822 @item 2005-07-10 @tab 1.9.6 @tab 7539 @tab 699 @tab 7867 @tab 3400 (40) @tab 1453 (32) @tab 144 @tab 570
12823 @item 2006-10-15 @tab 1.10 @tab 7859 @tab 1072 @tab 8024 @tab 3512 (40) @tab 1496 (34) @tab 172 @tab 604
12824 @item 2008-01-19 @tab 1.10.1 @tab 7870 @tab 1089 @tab 8025 @tab 3520 (40) @tab 1499 (34) @tab 173 @tab 617
12825 @item 2008-11-23 @tab 1.10.2 @tab 7882 @tab 1089 @tab 8027 @tab 3540 (40) @tab 1509 (34) @tab 176 @tab 628
12826 @item 2009-05-17 @tab 1.11 @tab 8721 @tab 1092 @tab 8289 @tab 4164 (42) @tab 1714 (37) @tab 181 @tab 732 (20)
12830 @c ========================================================== Appendices
12833 @node Copying This Manual
12834 @appendix Copying This Manual
12837 * GNU Free Documentation License:: License for copying this manual
12840 @node GNU Free Documentation License
12841 @appendixsec GNU Free Documentation License
12849 * Macro Index:: Index of Autoconf macros
12850 * Variable Index:: Index of Makefile variables
12851 * General Index:: General index
12855 @appendixsec Macro Index
12859 @node Variable Index
12860 @appendixsec Variable Index
12864 @node General Index
12865 @appendixsec General Index
12874 @c LocalWords: texinfo setfilename settitle setchapternewpage texi direntry
12875 @c LocalWords: dircategory in's aclocal ifinfo titlepage Tromey vskip pt sp
12876 @c LocalWords: filll defcodeindex ov cv op tr syncodeindex fn cp vr ifnottex
12877 @c LocalWords: dir Automake's ac Dist Gnits gnits cygnus dfn Autoconf's pxref
12878 @c LocalWords: cindex Autoconf autoconf perl samp cvs dist trindex SUBST foo
12879 @c LocalWords: xs emph FIXME ref vindex pkglibdir pkgincludedir pkgdatadir mt
12880 @c LocalWords: pkg libdir cpio bindir sbindir rmt pax sbin zar zardir acindex
12881 @c LocalWords: HTML htmldir html noinst TEXINFOS nodist nobase strudel CFLAGS
12882 @c LocalWords: libmumble CC YFLAGS ansi knr itemx de fication config url comp
12883 @c LocalWords: depcomp elisp sh mdate mkinstalldirs mkdir py tex dvi ps pdf
12884 @c LocalWords: ylwrap zardoz INIT gettext acinclude mv FUNCS LIBOBJS LDADD fr
12885 @c LocalWords: uref featureful dnl src LINGUAS es ko nl pl sl sv PROG ISC doc
12886 @c LocalWords: POSIX STDC fcntl FUNC ALLOCA blksize struct stat intl po chmod
12887 @c LocalWords: ChangeLog SUBDIRS gettextize gpl testdata getopt INTLLIBS cpp
12888 @c LocalWords: localedir datadir DLOCALEDIR DEXIT CPPFLAGS autoreconf opindex
12889 @c LocalWords: AUX var symlink deps Wno Wnone package's aclocal's distclean
12890 @c LocalWords: ltmain xref LIBSOURCE LIBSOURCES LIBOBJ MEMCMP vs RANLIB CXX
12891 @c LocalWords: LDFLAGS LIBTOOL libtool XTRA LIBS gettext's acdir APIVERSION
12892 @c LocalWords: dirlist noindent usr MULTILIB multilib Multilibs TIOCGWINSZ sc
12893 @c LocalWords: GWINSZ termios SRCDIR tarball bzip LISPDIR lispdir XEmacs CCAS
12894 @c LocalWords: emacsen MicroEmacs CCASFLAGS UX GCJ gcj GCJFLAGS posix DMALLOC
12895 @c LocalWords: dmalloc ldmalloc REGEX regex rx DEPDIR DEP DEFUN aclocaldir fi
12896 @c LocalWords: mymacro myothermacro AMFLAGS autopoint autogen libtoolize yum
12897 @c LocalWords: autoheader README MAKEFLAGS subdir Inetutils sync COND endif
12898 @c LocalWords: Miller's installable includedir inc pkgdata EXEEXT libexec bsd
12899 @c LocalWords: pkglib libexecdir prog libcpio cpio's dlopen dlpreopen linux
12900 @c LocalWords: subsubsection OBJEXT esac lib LTLIBRARIES liblob LIBADD AR ar
12901 @c LocalWords: ARFLAGS cru ing maude libgettext lo LTLIBOBJS rpath SGI PRE yy
12902 @c LocalWords: libmaude CCLD CXXFLAGS FFLAGS LFLAGS OBJCFLAGS RFLAGS DEFS cc
12903 @c LocalWords: SHORTNAME vtable srcdir nostdinc basename yxx cxx ll lxx gdb
12904 @c LocalWords: lexers yymaxdepth maxdepth yyparse yylex yyerror yylval lval
12905 @c LocalWords: yychar yydebug yypact yyr yydef def yychk chk yypgo pgo yyact
12906 @c LocalWords: yyexca exca yyerrflag errflag yynerrs nerrs yyps yypv pv yys
12907 @c LocalWords: yystate yytmp tmp yyv yyval val yylloc lloc yyreds yytoks toks
12908 @c LocalWords: yylhs yylen yydefred yydgoto yysindex yyrindex yygindex yyname
12909 @c LocalWords: yytable yycheck yyrule byacc CXXCOMPILE CXXLINK FLINK cfortran
12910 @c LocalWords: Catalogue preprocessable FLIBS libfoo baz JAVACFLAGS java exe
12911 @c LocalWords: SunOS fying basenames exeext uninstalled oldinclude kr FSF's
12912 @c LocalWords: pkginclude oldincludedir sysconf sharedstate localstate gcc rm
12913 @c LocalWords: sysconfdir sharedstatedir localstatedir preexist CLEANFILES gz
12914 @c LocalWords: depfile tmpdepfile depmode const interoperate
12915 @c LocalWords: JAVAC javac JAVAROOT builddir CLASSPATH ENV pyc pyo pkgpython
12916 @c LocalWords: pyexecdir pkgpyexecdir Python's pythondir pkgpythondir txi ois
12917 @c LocalWords: installinfo vers MAKEINFO makeinfo MAKEINFOFLAGS noinstall rf
12918 @c LocalWords: mandir thesame alsothesame installman myexecbin DESTDIR Pinard
12919 @c LocalWords: uninstall installdirs uninstalls MOSTLYCLEANFILES mostlyclean
12920 @c LocalWords: DISTCLEANFILES MAINTAINERCLEANFILES GZIP gzip shar exp
12921 @c LocalWords: distdir distcheck distcleancheck listfiles distuninstallcheck
12922 @c LocalWords: VPATH tarfile stdout XFAIL DejaGnu dejagnu DEJATOOL runtest ln
12923 @c LocalWords: RUNTESTDEFAULTFLAGS toolchain RUNTESTFLAGS asis readme DVIPS
12924 @c LocalWords: installcheck gzipped tarZ std utils etags mkid multilibbing cd
12925 @c LocalWords: ARGS taggable ETAGSFLAGS lang ctags CTAGSFLAGS GTAGS gtags idl
12926 @c LocalWords: foocc doit idlC multilibs ABIs cmindex defmac ARG enableval FC
12927 @c LocalWords: MSG xtrue DBG pathchk CYGWIN afile proglink versioned CVS's TE
12928 @c LocalWords: wildcards Autoconfiscated subsubheading autotools Meyering API
12929 @c LocalWords: ois's wildcard Wportability cartouche vrindex printindex Duret
12930 @c LocalWords: DSOMEFLAG DVERSION automake Lutz insertcopying versioning FAQ
12931 @c LocalWords: LTLIBOBJ Libtool's libtool's libltdl dlopening itutions libbar
12932 @c LocalWords: WANTEDLIBS libhello sublibraries libtop libsub dlopened Ratfor
12933 @c LocalWords: mymodule timestamps timestamp underquoted MAKEINFOHTMLFLAGS te
12934 @c LocalWords: GNUmakefile Subpackages subpackage's subpackages aux
12935 @c LocalWords: detailmenu Timeline pwd reldir AUTOM autom PREREQ FOOBAR libc
12936 @c LocalWords: libhand subpackage moduleN libmain libmisc FCFLAGS FCCOMPILE
12937 @c LocalWords: FCLINK subst sed ELCFILES elc MAKEINFOHTML dvips esyscmd ustar
12938 @c LocalWords: tarballs Woverride vfi ELFILES djm AutoMake honkin FSF
12939 @c LocalWords: fileutils precanned MacKenzie's reimplement termutils Tromey's
12940 @c LocalWords: cois gnitsians LIBPROGRAMS progs LIBLIBRARIES Textutils Ulrich
12941 @c LocalWords: Matzigkeit Drepper's Gord Matzigkeit's jm Dalley Debian org
12942 @c LocalWords: Administrivia ILU CORBA Sourceware Molenda sourceware Elliston
12943 @c LocalWords: dep Oliva Akim Demaille Aiieeee Demaillator Akim's sourcequake
12944 @c LocalWords: grep backported screenshots libgcj KB unnumberedsubsubsec pre
12945 @c LocalWords: precomputing hacky makedepend inline clearmake LD PRELOAD Rel
12946 @c LocalWords: syscalls perlhist acl pm multitable headitem fdl appendixsec
12947 @c LocalWords: LTALLOCA MALLOC malloc memcmp strdup alloca libcompat xyz DFOO
12948 @c LocalWords: unprefixed buildable preprocessed DBAZ DDATADIR WARNINGCFLAGS
12949 @c LocalWords: LIBFOOCFLAGS LIBFOOLDFLAGS ftable testSubDir obj LIBTOOLFLAGS
12950 @c LocalWords: barexec Pinard's automatize initialize lzma xz