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-2012 Free Software Foundation, Inc.
29 Permission is granted to copy, distribute and/or modify this document
30 under the terms of the GNU Free Documentation License,
31 Version 1.3 or any later version published by the Free Software
32 Foundation; with no Invariant Sections, with no Front-Cover texts,
33 and with no Back-Cover Texts. A copy of the license is included in the
34 section entitled ``GNU Free Documentation License.''
39 @dircategory Software development
41 * Automake: (automake). Making GNU standards-compliant Makefiles.
44 @dircategory Individual utilities
46 * aclocal-invocation: (automake)aclocal Invocation. Generating aclocal.m4.
47 * automake-invocation: (automake)automake Invocation. Generating Makefile.in.
52 @subtitle For version @value{VERSION}, @value{UPDATED}
53 @author David MacKenzie
55 @author Alexandre Duret-Lutz
57 @vskip 0pt plus 1filll
63 @c We use the following macros to define indices:
64 @c @cindex concepts, and anything that does not fit elsewhere
65 @c @vindex Makefile variables
67 @c @acindex Autoconf/Automake/Libtool/M4/... macros
68 @c @opindex tool options
70 @c Define an index of configure macros.
72 @c Define an index of options.
74 @c Define an index of targets.
76 @c Define an index of commands.
79 @c Put the macros in the function index.
82 @c Put everything else into one index (arbitrarily chosen to be the
90 @comment node-name, next, previous, up
96 * Introduction:: Automake's purpose
97 * Autotools Introduction:: An Introduction to the Autotools
98 * Generalities:: General ideas
99 * Examples:: Some example packages
100 * automake Invocation:: Creating a Makefile.in
101 * configure:: Scanning configure.ac, using aclocal
102 * Directories:: Declaring subdirectories
103 * Programs:: Building programs and libraries
104 * Other Objects:: Other derived objects
105 * Other GNU Tools:: Other GNU Tools
106 * Documentation:: Building documentation
107 * Install:: What gets installed
108 * Clean:: What gets cleaned
109 * Dist:: What goes in a distribution
110 * Tests:: Support for test suites
111 * Rebuilding:: Automatic rebuilding of Makefile
112 * Options:: Changing Automake's behavior
113 * Miscellaneous:: Miscellaneous rules
114 * Include:: Including extra files in an Automake template
115 * Conditionals:: Conditionals
116 * Silencing Make:: Obtain less verbose output from @command{make}
117 * Gnits:: The effect of @option{--gnu} and @option{--gnits}
118 * Cygnus:: The effect of @option{--cygnus} (deprecated, soon to be removed)
119 * Not Enough:: When Automake is not Enough
120 * Distributing:: Distributing the Makefile.in
121 * API Versioning:: About compatibility between Automake versions
122 * Upgrading:: Upgrading to a Newer Automake Version
123 * FAQ:: Frequently Asked Questions
124 * Copying This Manual:: How to make copies of this manual
125 * Indices:: Indices of variables, macros, and concepts
128 --- The Detailed Node Listing ---
130 An Introduction to the Autotools
132 * GNU Build System:: Introducing the GNU Build System
133 * Use Cases:: Use Cases for the GNU Build System
134 * Why Autotools:: How Autotools Help
135 * Hello World:: A Small Hello World Package
137 Use Cases for the GNU Build System
139 * Basic Installation:: Common installation procedure
140 * Standard Targets:: A list of standard Makefile targets
141 * Standard Directory Variables:: A list of standard directory variables
142 * Standard Configuration Variables:: Using configuration variables
143 * config.site:: Using a config.site file
144 * VPATH Builds:: Parallel build trees
145 * Two-Part Install:: Installing data and programs separately
146 * Cross-Compilation:: Building for other architectures
147 * Renaming:: Renaming programs at install time
148 * DESTDIR:: Building binary packages with DESTDIR
149 * Preparing Distributions:: Rolling out tarballs
150 * Dependency Tracking:: Automatic dependency tracking
151 * Nested Packages:: The GNU Build Systems can be nested
155 * Creating amhello:: Create @file{amhello-1.0.tar.gz} from scratch
156 * amhello's configure.ac Setup Explained::
157 * amhello's Makefile.am Setup Explained::
161 * General Operation:: General operation of Automake
162 * Strictness:: Standards conformance checking
163 * Uniform:: The Uniform Naming Scheme
164 * Length Limitations:: Staying below the command line length limit
165 * Canonicalization:: How derived variables are named
166 * User Variables:: Variables reserved for the user
167 * Auxiliary Programs:: Programs automake might require
169 Some example packages
171 * Complete:: A simple example, start to finish
172 * true:: Building true and false
174 Scanning @file{configure.ac}, using @command{aclocal}
176 * Requirements:: Configuration requirements
177 * Optional:: Other things Automake recognizes
178 * aclocal Invocation:: Auto-generating aclocal.m4
179 * Macros:: Autoconf macros supplied with Automake
181 Auto-generating aclocal.m4
183 * aclocal Options:: Options supported by aclocal
184 * Macro Search Path:: How aclocal finds .m4 files
185 * Extending aclocal:: Writing your own aclocal macros
186 * Local Macros:: Organizing local macros
187 * Serials:: Serial lines in Autoconf macros
188 * Future of aclocal:: aclocal's scheduled death
190 Autoconf macros supplied with Automake
192 * Public Macros:: Macros that you can use.
193 * Obsolete Macros:: Macros that will soon be removed.
194 * Private Macros:: Macros that you should not use.
198 * Subdirectories:: Building subdirectories recursively
199 * Conditional Subdirectories:: Conditionally not building directories
200 * Alternative:: Subdirectories without recursion
201 * Subpackages:: Nesting packages
203 Conditional Subdirectories
205 * SUBDIRS vs DIST_SUBDIRS:: Two sets of directories
206 * Subdirectories with AM_CONDITIONAL:: Specifying conditional subdirectories
207 * Subdirectories with AC_SUBST:: Another way for conditional recursion
208 * Unconfigured Subdirectories:: Not even creating a @samp{Makefile}
210 Building Programs and Libraries
212 * A Program:: Building a program
213 * A Library:: Building a library
214 * A Shared Library:: Building a Libtool library
215 * Program and Library Variables:: Variables controlling program and
217 * Default _SOURCES:: Default source files
218 * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
219 * Program Variables:: Variables used when building a program
220 * Yacc and Lex:: Yacc and Lex support
221 * C++ Support:: Compiling C++ sources
222 * Objective C Support:: Compiling Objective C sources
223 * Objective C++ Support:: Compiling Objective C++ sources
224 * Unified Parallel C Support:: Compiling Unified Parallel C sources
225 * Assembly Support:: Compiling assembly sources
226 * Fortran 77 Support:: Compiling Fortran 77 sources
227 * Fortran 9x Support:: Compiling Fortran 9x sources
228 * Java Support with gcj:: Compiling Java sources using gcj
229 * Vala Support:: Compiling Vala sources
230 * Support for Other Languages:: Compiling other languages
231 * Dependencies:: Automatic dependency tracking
232 * EXEEXT:: Support for executable extensions
236 * Program Sources:: Defining program sources
237 * Linking:: Linking with libraries or extra objects
238 * Conditional Sources:: Handling conditional sources
239 * Conditional Programs:: Building a program conditionally
241 Building a Shared Library
243 * Libtool Concept:: Introducing Libtool
244 * Libtool Libraries:: Declaring Libtool Libraries
245 * Conditional Libtool Libraries:: Building Libtool Libraries Conditionally
246 * Conditional Libtool Sources:: Choosing Library Sources Conditionally
247 * Libtool Convenience Libraries:: Building Convenience Libtool Libraries
248 * Libtool Modules:: Building Libtool Modules
249 * Libtool Flags:: Using _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS
250 * LTLIBOBJS:: Using $(LTLIBOBJS) and $(LTALLOCA)
251 * Libtool Issues:: Common Issues Related to Libtool's Use
253 Common Issues Related to Libtool's Use
255 * Error required file ltmain.sh not found:: The need to run libtoolize
256 * Objects created both with libtool and without:: Avoid a specific build race
260 * Preprocessing Fortran 77:: Preprocessing Fortran 77 sources
261 * Compiling Fortran 77 Files:: Compiling Fortran 77 sources
262 * Mixing Fortran 77 With C and C++:: Mixing Fortran 77 With C and C++
264 Mixing Fortran 77 With C and C++
266 * How the Linker is Chosen:: Automatic linker selection
270 * Compiling Fortran 9x Files:: Compiling Fortran 9x sources
272 Other Derived Objects
274 * Scripts:: Executable scripts
275 * Headers:: Header files
276 * Data:: Architecture-independent data files
277 * Sources:: Derived sources
281 * Built Sources Example:: Several ways to handle built sources.
285 * Emacs Lisp:: Emacs Lisp
288 * Java:: Java bytecode compilation (deprecated)
291 Building documentation
294 * Man Pages:: Man pages
298 * Basics of Installation:: What gets installed where
299 * The Two Parts of Install:: Installing data and programs separately
300 * Extending Installation:: Adding your own rules for installation
301 * Staged Installs:: Installation in a temporary location
302 * Install Rules for the User:: Useful additional rules
304 What Goes in a Distribution
306 * Basics of Distribution:: Files distributed by default
307 * Fine-grained Distribution Control:: @code{dist_} and @code{nodist_} prefixes
308 * The dist Hook:: A target for last-minute distribution changes
309 * Checking the Distribution:: @samp{make distcheck} explained
310 * The Types of Distributions:: A variety of formats and compression methods
312 Support for test suites
314 * Generalities about Testing:: Generic concepts and terminology about testing
315 * Simple Tests:: Listing test scripts in @code{TESTS}
316 * Custom Test Drivers:: Writing and using custom test drivers
317 * Using the TAP test protocol:: Integrating test scripts that use the TAP protocol
318 * DejaGnu Tests:: Interfacing with the @command{dejagnu} testing framework
319 * Install Tests:: Running tests on installed packages
323 * Scripts-based Testsuites:: Automake-specific concepts and terminology
324 * Serial Test Harness:: Older (and obsolescent) serial test harness
325 * Parallel Test Harness:: Generic concurrent test harness
327 Using the TAP test protocol
329 * Introduction to TAP::
330 * Use TAP with the Automake test harness::
331 * Incompatibilities with other TAP parsers and drivers::
332 * Links and external resources on TAP::
336 * Overview of Custom Test Drivers Support::
337 * Declaring Custom Test Drivers::
338 * API for Custom Test Drivers::
340 API for Custom Test Drivers
342 * Command-line arguments for test drivers::
343 * Log files generation and test results recording::
344 * Testsuite progress output::
346 Changing Automake's Behavior
348 * Options generalities:: Semantics of Automake option
349 * List of Automake options:: A comprehensive list of Automake options
353 * Tags:: Interfacing to cscope, etags and mkid
354 * Suffixes:: Handling new file extensions
358 * Usage of Conditionals:: Declaring conditional content
359 * Limits of Conditionals:: Enclosing complete statements
363 * Make verbosity:: Make is verbose by default
364 * Tricks For Silencing Make:: Standard and generic ways to silence make
365 * Automake silent-rules Option:: How Automake can help in silencing make
367 When Automake Isn't Enough
369 * Extending:: Adding new rules or overriding existing ones.
370 * Third-Party Makefiles:: Integrating Non-Automake @file{Makefile}s.
372 Frequently Asked Questions about Automake
374 * CVS:: CVS and generated files
375 * maintainer-mode:: missing and AM_MAINTAINER_MODE
376 * Wildcards:: Why doesn't Automake support wildcards?
377 * Limitations on File Names:: Limitations on source and installed file names
378 * Errors with distclean:: Files left in build directory after distclean
379 * Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS
380 * Renamed Objects:: Why are object files sometimes renamed?
381 * Per-Object Flags:: How to simulate per-object flags?
382 * Multiple Outputs:: Writing rules for tools with many output files
383 * Hard-Coded Install Paths:: Installing to hard-coded locations
384 * Debugging Make Rules:: Strategies when things don't work as expected
385 * Reporting Bugs:: Feedback on bugs and feature requests
389 * GNU Free Documentation License:: License for copying this manual
393 * Macro Index:: Index of Autoconf macros
394 * Variable Index:: Index of Makefile variables
395 * General Index:: General index
404 @chapter Introduction
406 Automake is a tool for automatically generating @file{Makefile.in}s
407 from files called @file{Makefile.am}. Each @file{Makefile.am} is
408 basically a series of @command{make} variable
409 definitions@footnote{These variables are also called @dfn{make macros}
410 in Make terminology, however in this manual we reserve the term
411 @dfn{macro} for Autoconf's macros.}, with rules being thrown in
412 occasionally. The generated @file{Makefile.in}s are compliant with
413 the GNU Makefile standards.
415 @cindex GNU Makefile standards
417 The GNU Makefile Standards Document
418 (@pxref{Makefile Conventions, , , standards, The GNU Coding Standards})
419 is long, complicated, and subject to change. The goal of Automake is to
420 remove the burden of Makefile maintenance from the back of the
421 individual GNU maintainer (and put it on the back of the Automake
424 The typical Automake input file is simply a series of variable definitions.
425 Each such file is processed to create a @file{Makefile.in}. There
426 should generally be one @file{Makefile.am} per directory of a project.
428 @cindex Constraints of Automake
429 @cindex Automake constraints
431 Automake does constrain a project in certain ways; for instance, it
432 assumes that the project uses Autoconf (@pxref{Top, , Introduction,
433 autoconf, The Autoconf Manual}), and enforces certain restrictions on
434 the @file{configure.ac} contents.
436 @cindex Automake requirements
437 @cindex Requirements, Automake
439 Automake requires @command{perl} in order to generate the
440 @file{Makefile.in}s. However, the distributions created by Automake are
441 fully GNU standards-compliant, and do not require @command{perl} in order
444 @cindex Bugs, reporting
445 @cindex Reporting bugs
446 @cindex E-mail, bug reports
448 For more information on bug reports, @xref{Reporting Bugs}.
450 @node Autotools Introduction
451 @chapter An Introduction to the Autotools
453 If you are new to Automake, maybe you know that it is part of a set of
454 tools called @emph{The Autotools}. Maybe you've already delved into a
455 package full of files named @file{configure}, @file{configure.ac},
456 @file{Makefile.in}, @file{Makefile.am}, @file{aclocal.m4}, @dots{},
457 some of them claiming to be @emph{generated by} Autoconf or Automake.
458 But the exact purpose of these files and their relations is probably
459 fuzzy. The goal of this chapter is to introduce you to this machinery,
460 to show you how it works and how powerful it is. If you've never
461 installed or seen such a package, do not worry: this chapter will walk
464 If you need some teaching material, more illustrations, or a less
465 @command{automake}-centered continuation, some slides for this
466 introduction are available in Alexandre Duret-Lutz's
467 @uref{http://www.lrde.epita.fr/@/~adl/@/autotools.html,
469 This chapter is the written version of the first part of his tutorial.
472 * GNU Build System:: Introducing the GNU Build System
473 * Use Cases:: Use Cases for the GNU Build System
474 * Why Autotools:: How Autotools Help
475 * Hello World:: A Small Hello World Package
478 @node GNU Build System
479 @section Introducing the GNU Build System
480 @cindex GNU Build System, introduction
482 It is a truth universally acknowledged, that as a developer in
483 possession of a new package, you must be in want of a build system.
485 In the Unix world, such a build system is traditionally achieved using
486 the command @command{make} (@pxref{Top, , Overview, make, The GNU Make
487 Manual}). You express the recipe to build your package in a
488 @file{Makefile}. This file is a set of rules to build the files in
489 the package. For instance the program @file{prog} may be built by
490 running the linker on the files @file{main.o}, @file{foo.o}, and
491 @file{bar.o}; the file @file{main.o} may be built by running the
492 compiler on @file{main.c}; etc. Each time @command{make} is run, it
493 reads @file{Makefile}, checks the existence and modification time of
494 the files mentioned, decides what files need to be built (or rebuilt),
495 and runs the associated commands.
497 When a package needs to be built on a different platform than the one
498 it was developed on, its @file{Makefile} usually needs to be adjusted.
499 For instance the compiler may have another name or require more
500 options. In 1991, David J. MacKenzie got tired of customizing
501 @file{Makefile} for the 20 platforms he had to deal with. Instead, he
502 handcrafted a little shell script called @file{configure} to
503 automatically adjust the @file{Makefile} (@pxref{Genesis, , Genesis,
504 autoconf, The Autoconf Manual}). Compiling his package was now
505 as simple as running @code{./configure && make}.
507 @cindex GNU Coding Standards
509 Today this process has been standardized in the GNU project. The GNU
510 Coding Standards (@pxref{Managing Releases, The Release Process, ,
511 standards, The GNU Coding Standards}) explains how each package of the
512 GNU project should have a @file{configure} script, and the minimal
513 interface it should have. The @file{Makefile} too should follow some
514 established conventions. The result? A unified build system that
515 makes all packages almost indistinguishable by the installer. In its
516 simplest scenario, all the installer has to do is to unpack the
517 package, run @code{./configure && make && make install}, and repeat
518 with the next package to install.
520 We call this build system the @dfn{GNU Build System}, since it was
521 grown out of the GNU project. However it is used by a vast number of
522 other packages: following any existing convention has its advantages.
524 @cindex Autotools, introduction
526 The Autotools are tools that will create a GNU Build System for your
527 package. Autoconf mostly focuses on @file{configure} and Automake on
528 @file{Makefile}s. It is entirely possible to create a GNU Build
529 System without the help of these tools. However it is rather
530 burdensome and error-prone. We will discuss this again after some
531 illustration of the GNU Build System in action.
534 @section Use Cases for the GNU Build System
535 @cindex GNU Build System, use cases
536 @cindex GNU Build System, features
537 @cindex Features of the GNU Build System
538 @cindex Use Cases for the GNU Build System
539 @cindex @file{amhello-1.0.tar.gz}, location
540 @cindex @file{amhello-1.0.tar.gz}, use cases
542 In this section we explore several use cases for the GNU Build System.
543 You can replay all of these examples on the @file{amhello-1.0.tar.gz}
544 package distributed with Automake. If Automake is installed on your
545 system, you should find a copy of this file in
546 @file{@var{prefix}/share/doc/automake/amhello-1.0.tar.gz}, where
547 @var{prefix} is the installation prefix specified during configuration
548 (@var{prefix} defaults to @file{/usr/local}, however if Automake was
549 installed by some GNU/Linux distribution it most likely has been set
550 to @file{/usr}). If you do not have a copy of Automake installed,
551 you can find a copy of this file inside the @file{doc/} directory of
552 the Automake package.
554 Some of the following use cases present features that are in fact
555 extensions to the GNU Build System. Read: they are not specified by
556 the GNU Coding Standards, but they are nonetheless part of the build
557 system created by the Autotools. To keep things simple, we do not
558 point out the difference. Our objective is to show you many of the
559 features that the build system created by the Autotools will offer to
563 * Basic Installation:: Common installation procedure
564 * Standard Targets:: A list of standard Makefile targets
565 * Standard Directory Variables:: A list of standard directory variables
566 * Standard Configuration Variables:: Using configuration variables
567 * config.site:: Using a config.site file
568 * VPATH Builds:: Parallel build trees
569 * Two-Part Install:: Installing data and programs separately
570 * Cross-Compilation:: Building for other architectures
571 * Renaming:: Renaming programs at install time
572 * DESTDIR:: Building binary packages with DESTDIR
573 * Preparing Distributions:: Rolling out tarballs
574 * Dependency Tracking:: Automatic dependency tracking
575 * Nested Packages:: The GNU Build Systems can be nested
578 @node Basic Installation
579 @subsection Basic Installation
580 @cindex Configuration, basics
581 @cindex Installation, basics
582 @cindex GNU Build System, basics
584 The most common installation procedure looks as follows.
587 ~ % @kbd{tar zxf amhello-1.0.tar.gz}
588 ~ % @kbd{cd amhello-1.0}
589 ~/amhello-1.0 % @kbd{./configure}
591 config.status: creating Makefile
592 config.status: creating src/Makefile
594 ~/amhello-1.0 % @kbd{make}
596 ~/amhello-1.0 % @kbd{make check}
598 ~/amhello-1.0 % @kbd{su}
600 /home/adl/amhello-1.0 # @kbd{make install}
602 /home/adl/amhello-1.0 # @kbd{exit}
603 ~/amhello-1.0 % @kbd{make installcheck}
609 The user first unpacks the package. Here, and in the following
610 examples, we will use the non-portable @code{tar zxf} command for
611 simplicity. On a system without GNU @command{tar} installed, this
612 command should read @code{gunzip -c amhello-1.0.tar.gz | tar xf -}.
614 The user then enters the newly created directory to run the
615 @file{configure} script. This script probes the system for various
616 features, and finally creates the @file{Makefile}s. In this toy
617 example there are only two @file{Makefile}s, but in real-world projects,
618 there may be many more, usually one @file{Makefile} per directory.
620 It is now possible to run @code{make}. This will construct all the
621 programs, libraries, and scripts that need to be constructed for the
622 package. In our example, this compiles the @file{hello} program.
623 All files are constructed in place, in the source tree; we will see
624 later how this can be changed.
626 @code{make check} causes the package's tests to be run. This step is
627 not mandatory, but it is often good to make sure the programs that
628 have been built behave as they should, before you decide to install
629 them. Our example does not contain any tests, so running @code{make
632 @cindex su, before @code{make install}
633 After everything has been built, and maybe tested, it is time to
634 install it on the system. That means copying the programs,
635 libraries, header files, scripts, and other data files from the
636 source directory to their final destination on the system. The
637 command @code{make install} will do that. However, by default
638 everything will be installed in subdirectories of @file{/usr/local}:
639 binaries will go into @file{/usr/local/bin}, libraries will end up in
640 @file{/usr/local/lib}, etc. This destination is usually not writable
641 by any user, so we assume that we have to become root before we can
642 run @code{make install}. In our example, running @code{make install}
643 will copy the program @file{hello} into @file{/usr/local/bin}
644 and @file{README} into @file{/usr/local/share/doc/amhello}.
646 A last and optional step is to run @code{make installcheck}. This
647 command may run tests on the installed files. @code{make check} tests
648 the files in the source tree, while @code{make installcheck} tests
649 their installed copies. The tests run by the latter can be different
650 from those run by the former. For instance, there are tests that
651 cannot be run in the source tree. Conversely, some packages are set
652 up so that @code{make installcheck} will run the very same tests as
653 @code{make check}, only on different files (non-installed
654 vs.@: installed). It can make a difference, for instance when the
655 source tree's layout is different from that of the installation.
656 Furthermore it may help to diagnose an incomplete installation.
658 Presently most packages do not have any @code{installcheck} tests
659 because the existence of @code{installcheck} is little known, and its
660 usefulness is neglected. Our little toy package is no better: @code{make
661 installcheck} does nothing.
663 @node Standard Targets
664 @subsection Standard @file{Makefile} Targets
666 So far we have come across four ways to run @command{make} in the GNU
667 Build System: @code{make}, @code{make check}, @code{make install}, and
668 @code{make installcheck}. The words @code{check}, @code{install}, and
669 @code{installcheck}, passed as arguments to @command{make}, are called
670 @dfn{targets}. @code{make} is a shorthand for @code{make all},
671 @code{all} being the default target in the GNU Build System.
673 Here is a list of the most useful targets that the GNU Coding Standards
679 Build programs, libraries, documentation, etc.@: (same as @code{make}).
682 Install what needs to be installed, copying the files from the
683 package's tree to system-wide directories.
684 @item make install-strip
685 @trindex install-strip
686 Same as @code{make install}, then strip debugging symbols. Some
687 users like to trade space for useful bug reports@enddots{}
690 The opposite of @code{make install}: erase the installed files.
691 (This needs to be run from the same build tree that was installed.)
694 Erase from the build tree the files built by @code{make all}.
697 Additionally erase anything @code{./configure} created.
700 Run the test suite, if any.
701 @item make installcheck
702 @trindex installcheck
703 Check the installed programs or libraries, if supported.
706 Recreate @file{@var{package}-@var{version}.tar.gz} from all the source
710 @node Standard Directory Variables
711 @subsection Standard Directory Variables
712 @cindex directory variables
714 The GNU Coding Standards also specify a hierarchy of variables to
715 denote installation directories. Some of these are:
717 @multitable {Directory variable} {@code{$@{datarootdir@}/doc/$@{PACKAGE@}}}
718 @headitem Directory variable @tab Default value
719 @item @code{prefix} @tab @code{/usr/local}
720 @item @w{@ @ @code{exec_prefix}} @tab @code{$@{prefix@}}
721 @item @w{@ @ @ @ @code{bindir}} @tab @code{$@{exec_prefix@}/bin}
722 @item @w{@ @ @ @ @code{libdir}} @tab @code{$@{exec_prefix@}/lib}
723 @item @w{@ @ @ @ @dots{}}
724 @item @w{@ @ @code{includedir}} @tab @code{$@{prefix@}/include}
725 @item @w{@ @ @code{datarootdir}} @tab @code{$@{prefix@}/share}
726 @item @w{@ @ @ @ @code{datadir}} @tab @code{$@{datarootdir@}}
727 @item @w{@ @ @ @ @code{mandir}} @tab @code{$@{datarootdir@}/man}
728 @item @w{@ @ @ @ @code{infodir}} @tab @code{$@{datarootdir@}/info}
729 @item @w{@ @ @ @ @code{docdir}} @tab @code{$@{datarootdir@}/doc/$@{PACKAGE@}}
730 @item @w{@ @ @dots{}}
733 @c We should provide a complete table somewhere, but not here. The
734 @c complete list of directory variables it too confusing as-is. It
735 @c requires some explanations that are too complicated for this
736 @c introduction. Besides listing directories like localstatedir
737 @c would make the explanations in ``Two-Part Install'' harder.
739 Each of these directories has a role which is often obvious from its
740 name. In a package, any installable file will be installed in one of
741 these directories. For instance in @code{amhello-1.0}, the program
742 @file{hello} is to be installed in @var{bindir}, the directory for
743 binaries. The default value for this directory is
744 @file{/usr/local/bin}, but the user can supply a different value when
745 calling @command{configure}. Also the file @file{README} will be
746 installed into @var{docdir}, which defaults to
747 @file{/usr/local/share/doc/amhello}.
751 As a user, if you wish to install a package on your own account, you
752 could proceed as follows:
755 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr}
757 ~/amhello-1.0 % @kbd{make}
759 ~/amhello-1.0 % @kbd{make install}
763 This would install @file{~/usr/bin/hello} and
764 @file{~/usr/share/doc/amhello/README}.
766 The list of all such directory options is shown by
767 @code{./configure --help}.
769 @node Standard Configuration Variables
770 @subsection Standard Configuration Variables
771 @cindex configuration variables, overriding
773 The GNU Coding Standards also define a set of standard configuration
774 variables used during the build. Here are some:
783 @item @code{CXXFLAGS}
787 @item @code{CPPFLAGS}
788 C/C++ preprocessor flags
792 @command{configure} usually does a good job at setting appropriate
793 values for these variables, but there are cases where you may want to
794 override them. For instance you may have several versions of a
795 compiler installed and would like to use another one, you may have
796 header files installed outside the default search path of the
797 compiler, or even libraries out of the way of the linker.
799 Here is how one would call @command{configure} to force it to use
800 @command{gcc-3} as C compiler, use header files from
801 @file{~/usr/include} when compiling, and libraries from
802 @file{~/usr/lib} when linking.
805 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr CC=gcc-3 \
806 CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib}
809 Again, a full list of these variables appears in the output of
810 @code{./configure --help}.
813 @subsection Overriding Default Configuration Setting with @file{config.site}
814 @cindex @file{config.site} example
816 When installing several packages using the same setup, it can be
817 convenient to create a file to capture common settings.
818 If a file named @file{@var{prefix}/share/config.site} exists,
819 @command{configure} will source it at the beginning of its execution.
821 Recall the command from the previous section:
824 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr CC=gcc-3 \
825 CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib}
828 Assuming we are installing many package in @file{~/usr}, and will
829 always want to use these definitions of @code{CC}, @code{CPPFLAGS}, and
830 @code{LDFLAGS}, we can automate this by creating the following
831 @file{~/usr/share/config.site} file:
834 test -z "$CC" && CC=gcc-3
835 test -z "$CPPFLAGS" && CPPFLAGS=-I$HOME/usr/include
836 test -z "$LDFLAGS" && LDFLAGS=-L$HOME/usr/lib
839 Now, any time a @file{configure} script is using the @file{~/usr}
840 prefix, it will execute the above @file{config.site} and define
841 these three variables.
844 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr}
845 configure: loading site script /home/adl/usr/share/config.site
849 @xref{Site Defaults, , Setting Site Defaults, autoconf, The Autoconf
850 Manual}, for more information about this feature.
854 @subsection Parallel Build Trees (a.k.a.@: VPATH Builds)
855 @cindex Parallel build trees
857 @cindex source tree and build tree
858 @cindex build tree and source tree
859 @cindex trees, source vs.@: build
861 The GNU Build System distinguishes two trees: the source tree, and
864 The source tree is rooted in the directory containing
865 @file{configure}. It contains all the sources files (those that are
866 distributed), and may be arranged using several subdirectories.
868 The build tree is rooted in the directory in which @file{configure}
869 was run, and is populated with all object files, programs, libraries,
870 and other derived files built from the sources (and hence not
871 distributed). The build tree usually has the same subdirectory layout
872 as the source tree; its subdirectories are created automatically by
875 If @file{configure} is executed in its own directory, the source and
876 build trees are combined: derived files are constructed in the same
877 directories as their sources. This was the case in our first
878 installation example (@pxref{Basic Installation}).
880 A common request from users is that they want to confine all derived
881 files to a single directory, to keep their source directories
882 uncluttered. Here is how we could run @file{configure} to build
883 everything in a subdirectory called @file{build/}.
886 ~ % @kbd{tar zxf ~/amhello-1.0.tar.gz}
887 ~ % @kbd{cd amhello-1.0}
888 ~/amhello-1.0 % @kbd{mkdir build && cd build}
889 ~/amhello-1.0/build % @kbd{../configure}
891 ~/amhello-1.0/build % @kbd{make}
895 These setups, where source and build trees are different, are often
896 called @dfn{parallel builds} or @dfn{VPATH builds}. The expression
897 @emph{parallel build} is misleading: the word @emph{parallel} is a
898 reference to the way the build tree shadows the source tree, it is not
899 about some concurrency in the way build commands are run. For this
900 reason we refer to such setups using the name @emph{VPATH builds} in
901 the following. @emph{VPATH} is the name of the @command{make} feature
902 used by the @file{Makefile}s to allow these builds (@pxref{General
903 Search, , @code{VPATH} Search Path for All Prerequisites, make, The
906 @cindex multiple configurations, example
907 @cindex debug build, example
908 @cindex optimized build, example
910 VPATH builds have other interesting uses. One is to build the same
911 sources with multiple configurations. For instance:
913 @c Keep in sync with amhello-cflags.sh
915 ~ % @kbd{tar zxf ~/amhello-1.0.tar.gz}
916 ~ % @kbd{cd amhello-1.0}
917 ~/amhello-1.0 % @kbd{mkdir debug optim && cd debug}
918 ~/amhello-1.0/debug % @kbd{../configure CFLAGS='-g -O0'}
920 ~/amhello-1.0/debug % @kbd{make}
922 ~/amhello-1.0/debug % cd ../optim
923 ~/amhello-1.0/optim % @kbd{../configure CFLAGS='-O3 -fomit-frame-pointer'}
925 ~/amhello-1.0/optim % @kbd{make}
929 With network file systems, a similar approach can be used to build the
930 same sources on different machines. For instance, suppose that the
931 sources are installed on a directory shared by two hosts: @code{HOST1}
932 and @code{HOST2}, which may be different platforms.
935 ~ % @kbd{cd /nfs/src}
936 /nfs/src % @kbd{tar zxf ~/amhello-1.0.tar.gz}
939 On the first host, you could create a local build directory:
941 [HOST1] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
942 [HOST1] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure}
944 [HOST1] /tmp/amh % @kbd{make && sudo make install}
949 (Here we assume that the installer has configured @command{sudo} so it
950 can execute @code{make install} with root privileges; it is more convenient
951 than using @command{su} like in @ref{Basic Installation}).
953 On the second host, you would do exactly the same, possibly at
956 [HOST2] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
957 [HOST2] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure}
959 [HOST2] /tmp/amh % @kbd{make && sudo make install}
963 @cindex read-only source tree
964 @cindex source tree, read-only
966 In this scenario, nothing forbids the @file{/nfs/src/amhello-1.0}
967 directory from being read-only. In fact VPATH builds are also a means
968 of building packages from a read-only medium such as a CD-ROM. (The
969 FSF used to sell CD-ROM with unpacked source code, before the GNU
970 project grew so big.)
972 @node Two-Part Install
973 @subsection Two-Part Installation
975 In our last example (@pxref{VPATH Builds}), a source tree was shared
976 by two hosts, but compilation and installation were done separately on
979 The GNU Build System also supports networked setups where part of the
980 installed files should be shared amongst multiple hosts. It does so
981 by distinguishing architecture-dependent files from
982 architecture-independent files, and providing two @file{Makefile}
983 targets to install each of these classes of files.
985 @trindex install-exec
986 @trindex install-data
988 These targets are @code{install-exec} for architecture-dependent files
989 and @code{install-data} for architecture-independent files.
990 The command we used up to now, @code{make install}, can be thought of
991 as a shorthand for @code{make install-exec install-data}.
993 From the GNU Build System point of view, the distinction between
994 architecture-dependent files and architecture-independent files is
995 based exclusively on the directory variable used to specify their
996 installation destination. In the list of directory variables we
997 provided earlier (@pxref{Standard Directory Variables}), all the
998 variables based on @var{exec-prefix} designate architecture-dependent
999 directories whose files will be installed by @code{make install-exec}.
1000 The others designate architecture-independent directories and will
1001 serve files installed by @code{make install-data}. @xref{The Two Parts
1002 of Install}, for more details.
1004 Here is how we could revisit our two-host installation example,
1005 assuming that (1) we want to install the package directly in
1006 @file{/usr}, and (2) the directory @file{/usr/share} is shared by the
1009 On the first host we would run
1011 [HOST1] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
1012 [HOST1] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure --prefix /usr}
1014 [HOST1] /tmp/amh % @kbd{make && sudo make install}
1018 On the second host, however, we need only install the
1019 architecture-specific files.
1021 [HOST2] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
1022 [HOST2] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure --prefix /usr}
1024 [HOST2] /tmp/amh % @kbd{make && sudo make install-exec}
1028 In packages that have installation checks, it would make sense to run
1029 @code{make installcheck} (@pxref{Basic Installation}) to verify that
1030 the package works correctly despite the apparent partial installation.
1032 @node Cross-Compilation
1033 @subsection Cross-Compilation
1034 @cindex cross-compilation
1036 To @dfn{cross-compile} is to build on one platform a binary that will
1037 run on another platform. When speaking of cross-compilation, it is
1038 important to distinguish between the @dfn{build platform} on which
1039 the compilation is performed, and the @dfn{host platform} on which the
1040 resulting executable is expected to run. The following
1041 @command{configure} options are used to specify each of them:
1044 @item --build=@var{build}
1045 @opindex --build=@var{build}
1046 The system on which the package is built.
1047 @item --host=@var{host}
1048 @opindex --host=@var{host}
1049 The system where built programs and libraries will run.
1052 When the @option{--host} is used, @command{configure} will search for
1053 the cross-compiling suite for this platform. Cross-compilation tools
1054 commonly have their target architecture as prefix of their name. For
1055 instance my cross-compiler for MinGW32 has its binaries called
1056 @code{i586-mingw32msvc-gcc}, @code{i586-mingw32msvc-ld},
1057 @code{i586-mingw32msvc-as}, etc.
1059 @cindex MinGW cross-compilation example
1060 @cindex cross-compilation example
1062 Here is how we could build @code{amhello-1.0} for
1063 @code{i586-mingw32msvc} on a GNU/Linux PC.
1065 @c Keep in sync with amhello-cross-compile.sh
1067 ~/amhello-1.0 % @kbd{./configure --build i686-pc-linux-gnu --host i586-mingw32msvc}
1068 checking for a BSD-compatible install... /usr/bin/install -c
1069 checking whether build environment is sane... yes
1070 checking for gawk... gawk
1071 checking whether make sets $(MAKE)... yes
1072 checking for i586-mingw32msvc-strip... i586-mingw32msvc-strip
1073 checking for i586-mingw32msvc-gcc... i586-mingw32msvc-gcc
1074 checking for C compiler default output file name... a.exe
1075 checking whether the C compiler works... yes
1076 checking whether we are cross compiling... yes
1077 checking for suffix of executables... .exe
1078 checking for suffix of object files... o
1079 checking whether we are using the GNU C compiler... yes
1080 checking whether i586-mingw32msvc-gcc accepts -g... yes
1081 checking for i586-mingw32msvc-gcc option to accept ANSI C...
1083 ~/amhello-1.0 % @kbd{make}
1085 ~/amhello-1.0 % @kbd{cd src; file hello.exe}
1086 hello.exe: MS Windows PE 32-bit Intel 80386 console executable not relocatable
1089 The @option{--host} and @option{--build} options are usually all we
1090 need for cross-compiling. The only exception is if the package being
1091 built is itself a cross-compiler: we need a third option to specify
1092 its target architecture.
1095 @item --target=@var{target}
1096 @opindex --target=@var{target}
1097 When building compiler tools: the system for which the tools will
1101 For instance when installing GCC, the GNU Compiler Collection, we can
1102 use @option{--target=@/@var{target}} to specify that we want to build
1103 GCC as a cross-compiler for @var{target}. Mixing @option{--build} and
1104 @option{--target}, we can actually cross-compile a cross-compiler;
1105 such a three-way cross-compilation is known as a @dfn{Canadian cross}.
1107 @xref{Specifying Names, , Specifying the System Type, autoconf, The
1108 Autoconf Manual}, for more information about these @command{configure}
1112 @subsection Renaming Programs at Install Time
1113 @cindex Renaming programs
1114 @cindex Transforming program names
1115 @cindex Programs, renaming during installation
1117 The GNU Build System provides means to automatically rename
1118 executables and manpages before they are installed (@pxref{Man Pages}).
1119 This is especially convenient
1120 when installing a GNU package on a system that already has a
1121 proprietary implementation you do not want to overwrite. For instance,
1122 you may want to install GNU @command{tar} as @command{gtar} so you can
1123 distinguish it from your vendor's @command{tar}.
1125 This can be done using one of these three @command{configure} options.
1128 @item --program-prefix=@var{prefix}
1129 @opindex --program-prefix=@var{prefix}
1130 Prepend @var{prefix} to installed program names.
1131 @item --program-suffix=@var{suffix}
1132 @opindex --program-suffix=@var{suffix}
1133 Append @var{suffix} to installed program names.
1134 @item --program-transform-name=@var{program}
1135 @opindex --program-transform-name=@var{program}
1136 Run @code{sed @var{program}} on installed program names.
1139 The following commands would install @file{hello}
1140 as @file{/usr/local/bin/test-hello}, for instance.
1143 ~/amhello-1.0 % @kbd{./configure --program-prefix test-}
1145 ~/amhello-1.0 % @kbd{make}
1147 ~/amhello-1.0 % @kbd{sudo make install}
1152 @subsection Building Binary Packages Using DESTDIR
1155 The GNU Build System's @code{make install} and @code{make uninstall}
1156 interface does not exactly fit the needs of a system administrator
1157 who has to deploy and upgrade packages on lots of hosts. In other
1158 words, the GNU Build System does not replace a package manager.
1160 Such package managers usually need to know which files have been
1161 installed by a package, so a mere @code{make install} is
1164 @cindex Staged installation
1166 The @code{DESTDIR} variable can be used to perform a staged
1167 installation. The package should be configured as if it was going to
1168 be installed in its final location (e.g., @code{--prefix /usr}), but
1169 when running @code{make install}, the @code{DESTDIR} should be set to
1170 the absolute name of a directory into which the installation will be
1171 diverted. From this directory it is easy to review which files are
1172 being installed where, and finally copy them to their final location
1175 @cindex Binary package
1177 For instance here is how we could create a binary package containing a
1178 snapshot of all the files to be installed.
1180 @c Keep in sync with amhello-binpkg.sh
1182 ~/amhello-1.0 % @kbd{./configure --prefix /usr}
1184 ~/amhello-1.0 % @kbd{make}
1186 ~/amhello-1.0 % @kbd{make DESTDIR=$HOME/inst install}
1188 ~/amhello-1.0 % @kbd{cd ~/inst}
1189 ~/inst % @kbd{find . -type f -print > ../files.lst}
1190 ~/inst % @kbd{tar zcvf ~/amhello-1.0-i686.tar.gz `cat ../files.lst`}
1192 ./usr/share/doc/amhello/README
1195 After this example, @code{amhello-1.0-i686.tar.gz} is ready to be
1196 uncompressed in @file{/} on many hosts. (Using @code{`cat ../files.lst`}
1197 instead of @samp{.} as argument for @command{tar} avoids entries for
1198 each subdirectory in the archive: we would not like @command{tar} to
1199 restore the modification time of @file{/}, @file{/usr/}, etc.)
1201 Note that when building packages for several architectures, it might
1202 be convenient to use @code{make install-data} and @code{make
1203 install-exec} (@pxref{Two-Part Install}) to gather
1204 architecture-independent files in a single package.
1206 @xref{Install}, for more information.
1208 @c We should document PRE_INSTALL/POST_INSTALL/NORMAL_INSTALL and their
1209 @c UNINSTALL counterparts.
1211 @node Preparing Distributions
1212 @subsection Preparing Distributions
1213 @cindex Preparing distributions
1214 @cindex Packages, preparation
1215 @cindex Distributions, preparation
1217 We have already mentioned @code{make dist}. This target collects all
1218 your source files and the necessary parts of the build system to
1219 create a tarball named @file{@var{package}-@var{version}.tar.gz}.
1221 @cindex @code{distcheck} better than @code{dist}
1223 Another, more useful command is @code{make distcheck}. The
1224 @code{distcheck} target constructs
1225 @file{@var{package}-@var{version}.tar.gz} just as well as @code{dist},
1226 but it additionally ensures most of the use cases presented so far
1231 It attempts a full compilation of the package (@pxref{Basic
1232 Installation}), unpacking the newly constructed tarball, running
1233 @code{make}, @code{make check}, @code{make install}, as well as
1234 @code{make installcheck}, and even @code{make dist},
1236 it tests VPATH builds with read-only source tree (@pxref{VPATH Builds}),
1238 it makes sure @code{make clean}, @code{make distclean}, and @code{make
1239 uninstall} do not omit any file (@pxref{Standard Targets}),
1241 and it checks that @code{DESTDIR} installations work (@pxref{DESTDIR}).
1244 All of these actions are performed in a temporary subdirectory, so
1245 that no root privileges are required.
1247 Releasing a package that fails @code{make distcheck} means that one of
1248 the scenarios we presented will not work and some users will be
1249 disappointed. Therefore it is a good practice to release a package
1250 only after a successful @code{make distcheck}. This of course does
1251 not imply that the package will be flawless, but at least it will
1252 prevent some of the embarrassing errors you may find in packages
1253 released by people who have never heard about @code{distcheck} (like
1254 @code{DESTDIR} not working because of a typo, or a distributed file
1255 being erased by @code{make clean}, or even @code{VPATH} builds not
1258 @xref{Creating amhello}, to recreate @file{amhello-1.0.tar.gz} using
1259 @code{make distcheck}. @xref{Checking the Distribution}, for more
1260 information about @code{distcheck}.
1262 @node Dependency Tracking
1263 @subsection Automatic Dependency Tracking
1264 @cindex Dependency tracking
1266 Dependency tracking is performed as a side-effect of compilation.
1267 Each time the build system compiles a source file, it computes its
1268 list of dependencies (in C these are the header files included by the
1269 source being compiled). Later, any time @command{make} is run and a
1270 dependency appears to have changed, the dependent files will be
1273 Automake generates code for automatic dependency tracking by default,
1274 unless the developer chooses to override it; for more information,
1275 @pxref{Dependencies}.
1277 When @command{configure} is executed, you can see it probing each
1278 compiler for the dependency mechanism it supports (several mechanisms
1282 ~/amhello-1.0 % @kbd{./configure --prefix /usr}
1284 checking dependency style of gcc... gcc3
1288 Because dependencies are only computed as a side-effect of the
1289 compilation, no dependency information exists the first time a package
1290 is built. This is OK because all the files need to be built anyway:
1291 @code{make} does not have to decide which files need to be rebuilt.
1292 In fact, dependency tracking is completely useless for one-time builds
1293 and there is a @command{configure} option to disable this:
1296 @item --disable-dependency-tracking
1297 @opindex --disable-dependency-tracking
1298 Speed up one-time builds.
1301 Some compilers do not offer any practical way to derive the list of
1302 dependencies as a side-effect of the compilation, requiring a separate
1303 run (maybe of another tool) to compute these dependencies. The
1304 performance penalty implied by these methods is important enough to
1305 disable them by default. The option @option{--enable-dependency-tracking}
1306 must be passed to @command{configure} to activate them.
1309 @item --enable-dependency-tracking
1310 @opindex --enable-dependency-tracking
1311 Do not reject slow dependency extractors.
1314 @xref{Dependency Tracking Evolution, , Dependency Tracking Evolution,
1315 automake-history, Brief History of Automake}, for some discussion about
1316 the different dependency tracking schemes used by Automake over the years.
1318 @node Nested Packages
1319 @subsection Nested Packages
1320 @cindex Nested packages
1321 @cindex Packages, nested
1324 Although nesting packages isn't something we would recommend to
1325 someone who is discovering the Autotools, it is a nice feature worthy
1326 of mention in this small advertising tour.
1328 Autoconfiscated packages (that means packages whose build system have
1329 been created by Autoconf and friends) can be nested to arbitrary
1332 A typical setup is that package A will distribute one of the libraries
1333 it needs in a subdirectory. This library B is a complete package with
1334 its own GNU Build System. The @command{configure} script of A will
1335 run the @command{configure} script of B as part of its execution,
1336 building and installing A will also build and install B. Generating a
1337 distribution for A will also include B.
1339 It is possible to gather several packages like this. GCC is a heavy
1340 user of this feature. This gives installers a single package to
1341 configure, build and install, while it allows developers to work on
1342 subpackages independently.
1344 When configuring nested packages, the @command{configure} options
1345 given to the top-level @command{configure} are passed recursively to
1346 nested @command{configure}s. A package that does not understand an
1347 option will ignore it, assuming it is meaningful to some other
1350 @opindex --help=recursive
1352 The command @code{configure --help=recursive} can be used to display
1353 the options supported by all the included packages.
1355 @xref{Subpackages}, for an example setup.
1358 @section How Autotools Help
1359 @cindex Autotools, purpose
1361 There are several reasons why you may not want to implement the GNU
1362 Build System yourself (read: write a @file{configure} script and
1363 @file{Makefile}s yourself).
1367 As we have seen, the GNU Build System has a lot of
1368 features (@pxref{Use Cases}).
1369 Some users may expect features you have not implemented because
1370 you did not need them.
1372 Implementing these features portably is difficult and exhausting.
1373 Think of writing portable shell scripts, and portable
1374 @file{Makefile}s, for systems you may not have handy. @xref{Portable
1375 Shell, , Portable Shell Programming, autoconf, The Autoconf Manual}, to
1378 You will have to upgrade your setup to follow changes to the GNU
1382 The GNU Autotools take all this burden off your back and provide:
1386 Tools to create a portable, complete, and self-contained GNU Build
1387 System, from simple instructions.
1388 @emph{Self-contained} meaning the resulting build system does not
1389 require the GNU Autotools.
1391 A central place where fixes and improvements are made:
1392 a bug-fix for a portability issue will benefit every package.
1395 Yet there also exist reasons why you may want NOT to use the
1396 Autotools@enddots{} For instance you may be already using (or used to)
1397 another incompatible build system. Autotools will only be useful if
1398 you do accept the concepts of the GNU Build System. People who have their
1399 own idea of how a build system should work will feel frustrated by the
1403 @section A Small Hello World
1404 @cindex Example Hello World
1405 @cindex Hello World example
1406 @cindex @file{amhello-1.0.tar.gz}, creation
1408 In this section we recreate the @file{amhello-1.0} package from
1409 scratch. The first subsection shows how to call the Autotools to
1410 instantiate the GNU Build System, while the second explains the
1411 meaning of the @file{configure.ac} and @file{Makefile.am} files read
1414 @anchor{amhello Explained}
1416 * Creating amhello:: Create @file{amhello-1.0.tar.gz} from scratch
1417 * amhello's configure.ac Setup Explained::
1418 * amhello's Makefile.am Setup Explained::
1421 @node Creating amhello
1422 @subsection Creating @file{amhello-1.0.tar.gz}
1424 Here is how we can recreate @file{amhello-1.0.tar.gz} from scratch.
1425 The package is simple enough so that we will only need to write 5
1426 files. (You may copy them from the final @file{amhello-1.0.tar.gz}
1427 that is distributed with Automake if you do not want to write them.)
1429 Create the following files in an empty directory.
1434 @file{src/main.c} is the source file for the @file{hello} program. We
1435 store it in the @file{src/} subdirectory, because later, when the package
1436 evolves, it will ease the addition of a @file{man/} directory for man
1437 pages, a @file{data/} directory for data files, etc.
1439 ~/amhello % @kbd{cat src/main.c}
1446 puts ("Hello World!");
1447 puts ("This is " PACKAGE_STRING ".");
1453 @file{README} contains some very limited documentation for our little
1456 ~/amhello % @kbd{cat README}
1457 This is a demonstration package for GNU Automake.
1458 Type `info Automake' to read the Automake manual.
1462 @file{Makefile.am} and @file{src/Makefile.am} contain Automake
1463 instructions for these two directories.
1466 ~/amhello % @kbd{cat src/Makefile.am}
1467 bin_PROGRAMS = hello
1468 hello_SOURCES = main.c
1469 ~/amhello % @kbd{cat Makefile.am}
1471 dist_doc_DATA = README
1475 Finally, @file{configure.ac} contains Autoconf instructions to
1476 create the @command{configure} script.
1479 ~/amhello % @kbd{cat configure.ac}
1480 AC_INIT([amhello], [1.0], [@value{PACKAGE_BUGREPORT}])
1481 AM_INIT_AUTOMAKE([-Wall -Werror foreign])
1483 AC_CONFIG_HEADERS([config.h])
1492 @cindex @command{autoreconf}, example
1494 Once you have these five files, it is time to run the Autotools to
1495 instantiate the build system. Do this using the @command{autoreconf}
1499 ~/amhello % @kbd{autoreconf --install}
1500 configure.ac: installing `./install-sh'
1501 configure.ac: installing `./missing'
1502 src/Makefile.am: installing `./depcomp'
1505 At this point the build system is complete.
1507 In addition to the three scripts mentioned in its output, you can see
1508 that @command{autoreconf} created four other files: @file{configure},
1509 @file{config.h.in}, @file{Makefile.in}, and @file{src/Makefile.in}.
1510 The latter three files are templates that will be adapted to the
1511 system by @command{configure} under the names @file{config.h},
1512 @file{Makefile}, and @file{src/Makefile}. Let's do this:
1515 ~/amhello % @kbd{./configure}
1516 checking for a BSD-compatible install... /usr/bin/install -c
1517 checking whether build environment is sane... yes
1518 checking for gawk... no
1519 checking for mawk... mawk
1520 checking whether make sets $(MAKE)... yes
1521 checking for gcc... gcc
1522 checking for C compiler default output file name... a.out
1523 checking whether the C compiler works... yes
1524 checking whether we are cross compiling... no
1525 checking for suffix of executables...
1526 checking for suffix of object files... o
1527 checking whether we are using the GNU C compiler... yes
1528 checking whether gcc accepts -g... yes
1529 checking for gcc option to accept ISO C89... none needed
1530 checking for style of include used by make... GNU
1531 checking dependency style of gcc... gcc3
1532 configure: creating ./config.status
1533 config.status: creating Makefile
1534 config.status: creating src/Makefile
1535 config.status: creating config.h
1536 config.status: executing depfiles commands
1540 @cindex @code{distcheck} example
1542 You can see @file{Makefile}, @file{src/Makefile}, and @file{config.h}
1543 being created at the end after @command{configure} has probed the
1544 system. It is now possible to run all the targets we wish
1545 (@pxref{Standard Targets}). For instance:
1548 ~/amhello % @kbd{make}
1550 ~/amhello % @kbd{src/hello}
1552 This is amhello 1.0.
1553 ~/amhello % @kbd{make distcheck}
1555 =============================================
1556 amhello-1.0 archives ready for distribution:
1558 =============================================
1561 Note that running @command{autoreconf} is only needed initially when
1562 the GNU Build System does not exist. When you later change some
1563 instructions in a @file{Makefile.am} or @file{configure.ac}, the
1564 relevant part of the build system will be regenerated automatically
1565 when you execute @command{make}.
1567 @command{autoreconf} is a script that calls @command{autoconf},
1568 @command{automake}, and a bunch of other commands in the right order.
1569 If you are beginning with these tools, it is not important to figure
1570 out in which order all of these tools should be invoked and why. However,
1571 because Autoconf and Automake have separate manuals, the important
1572 point to understand is that @command{autoconf} is in charge of
1573 creating @file{configure} from @file{configure.ac}, while
1574 @command{automake} is in charge of creating @file{Makefile.in}s from
1575 @file{Makefile.am}s and @file{configure.ac}. This should at least
1576 direct you to the right manual when seeking answers.
1579 @node amhello's configure.ac Setup Explained
1580 @subsection @code{amhello}'s @file{configure.ac} Setup Explained
1582 @cindex @file{configure.ac}, Hello World
1584 Let us begin with the contents of @file{configure.ac}.
1587 AC_INIT([amhello], [1.0], [@value{PACKAGE_BUGREPORT}])
1588 AM_INIT_AUTOMAKE([-Wall -Werror foreign])
1590 AC_CONFIG_HEADERS([config.h])
1598 This file is read by both @command{autoconf} (to create
1599 @file{configure}) and @command{automake} (to create the various
1600 @file{Makefile.in}s). It contains a series of M4 macros that will be
1601 expanded as shell code to finally form the @file{configure} script.
1602 We will not elaborate on the syntax of this file, because the Autoconf
1603 manual has a whole section about it (@pxref{Writing Autoconf Input, ,
1604 Writing @file{configure.ac}, autoconf, The Autoconf Manual}).
1606 The macros prefixed with @code{AC_} are Autoconf macros, documented
1607 in the Autoconf manual (@pxref{Autoconf Macro Index, , Autoconf Macro
1608 Index, autoconf, The Autoconf Manual}). The macros that start with
1609 @code{AM_} are Automake macros, documented later in this manual
1610 (@pxref{Macro Index}).
1612 The first two lines of @file{configure.ac} initialize Autoconf and
1613 Automake. @code{AC_INIT} takes in as parameters the name of the package,
1614 its version number, and a contact address for bug-reports about the
1615 package (this address is output at the end of @code{./configure
1616 --help}, for instance). When adapting this setup to your own package,
1617 by all means please do not blindly copy Automake's address: use the
1618 mailing list of your package, or your own mail address.
1624 The argument to @code{AM_INIT_AUTOMAKE} is a list of options for
1625 @command{automake} (@pxref{Options}). @option{-Wall} and
1626 @option{-Werror} ask @command{automake} to turn on all warnings and
1627 report them as errors. We are speaking of @strong{Automake} warnings
1628 here, such as dubious instructions in @file{Makefile.am}. This has
1629 absolutely nothing to do with how the compiler will be called, even
1630 though it may support options with similar names. Using @option{-Wall
1631 -Werror} is a safe setting when starting to work on a package: you do
1632 not want to miss any issues. Later you may decide to relax things a
1633 bit. The @option{foreign} option tells Automake that this package
1634 will not follow the GNU Standards. GNU packages should always
1635 distribute additional files such as @file{ChangeLog}, @file{AUTHORS},
1636 etc. We do not want @command{automake} to complain about these
1637 missing files in our small example.
1639 The @code{AC_PROG_CC} line causes the @command{configure} script to
1640 search for a C compiler and define the variable @code{CC} with its
1641 name. The @file{src/Makefile.in} file generated by Automake uses the
1642 variable @code{CC} to build @file{hello}, so when @command{configure}
1643 creates @file{src/Makefile} from @file{src/Makefile.in}, it will define
1644 @code{CC} with the value it has found. If Automake is asked to create
1645 a @file{Makefile.in} that uses @code{CC} but @file{configure.ac} does
1646 not define it, it will suggest you add a call to @code{AC_PROG_CC}.
1648 The @code{AC_CONFIG_HEADERS([config.h])} invocation causes the
1649 @command{configure} script to create a @file{config.h} file gathering
1650 @samp{#define}s defined by other macros in @file{configure.ac}. In our
1651 case, the @code{AC_INIT} macro already defined a few of them. Here
1652 is an excerpt of @file{config.h} after @command{configure} has run:
1656 /* Define to the address where bug reports for this package should be sent. */
1657 #define PACKAGE_BUGREPORT "@value{PACKAGE_BUGREPORT}"
1659 /* Define to the full name and version of this package. */
1660 #define PACKAGE_STRING "amhello 1.0"
1664 As you probably noticed, @file{src/main.c} includes @file{config.h} so
1665 it can use @code{PACKAGE_STRING}. In a real-world project,
1666 @file{config.h} can grow really big, with one @samp{#define} per
1667 feature probed on the system.
1669 The @code{AC_CONFIG_FILES} macro declares the list of files that
1670 @command{configure} should create from their @file{*.in} templates.
1671 Automake also scans this list to find the @file{Makefile.am} files it must
1672 process. (This is important to remember: when adding a new directory
1673 to your project, you should add its @file{Makefile} to this list,
1674 otherwise Automake will never process the new @file{Makefile.am} you
1675 wrote in that directory.)
1677 Finally, the @code{AC_OUTPUT} line is a closing command that actually
1678 produces the part of the script in charge of creating the files
1679 registered with @code{AC_CONFIG_HEADERS} and @code{AC_CONFIG_FILES}.
1681 @cindex @command{autoscan}
1683 When starting a new project, we suggest you start with such a simple
1684 @file{configure.ac}, and gradually add the other tests it requires.
1685 The command @command{autoscan} can also suggest a few of the tests
1686 your package may need (@pxref{autoscan Invocation, , Using
1687 @command{autoscan} to Create @file{configure.ac}, autoconf, The
1691 @node amhello's Makefile.am Setup Explained
1692 @subsection @code{amhello}'s @file{Makefile.am} Setup Explained
1694 @cindex @file{Makefile.am}, Hello World
1696 We now turn to @file{src/Makefile.am}. This file contains
1697 Automake instructions to build and install @file{hello}.
1700 bin_PROGRAMS = hello
1701 hello_SOURCES = main.c
1704 A @file{Makefile.am} has the same syntax as an ordinary
1705 @file{Makefile}. When @command{automake} processes a
1706 @file{Makefile.am} it copies the entire file into the output
1707 @file{Makefile.in} (that will be later turned into @file{Makefile} by
1708 @command{configure}) but will react to certain variable definitions
1709 by generating some build rules and other variables.
1710 Often @file{Makefile.am}s contain only a list of variable definitions as
1711 above, but they can also contain other variable and rule definitions that
1712 @command{automake} will pass along without interpretation.
1714 Variables that end with @code{_PROGRAMS} are special variables
1715 that list programs that the resulting @file{Makefile} should build.
1716 In Automake speak, this @code{_PROGRAMS} suffix is called a
1717 @dfn{primary}; Automake recognizes other primaries such as
1718 @code{_SCRIPTS}, @code{_DATA}, @code{_LIBRARIES}, etc.@: corresponding
1719 to different types of files.
1721 The @samp{bin} part of the @code{bin_PROGRAMS} tells
1722 @command{automake} that the resulting programs should be installed in
1723 @var{bindir}. Recall that the GNU Build System uses a set of variables
1724 to denote destination directories and allow users to customize these
1725 locations (@pxref{Standard Directory Variables}). Any such directory
1726 variable can be put in front of a primary (omitting the @code{dir}
1727 suffix) to tell @command{automake} where to install the listed files.
1729 Programs need to be built from source files, so for each program
1730 @code{@var{prog}} listed in a @code{@w{_PROGRAMS}} variable,
1731 @command{automake} will look for another variable named
1732 @code{@var{prog}_SOURCES} listing its source files. There may be more
1733 than one source file: they will all be compiled and linked together.
1735 Automake also knows that source files need to be distributed when
1736 creating a tarball (unlike built programs). So a side-effect of this
1737 @code{hello_SOURCES} declaration is that @file{main.c} will be
1738 part of the tarball created by @code{make dist}.
1740 Finally here are some explanations regarding the top-level
1745 dist_doc_DATA = README
1748 @code{SUBDIRS} is a special variable listing all directories that
1749 @command{make} should recurse into before processing the current
1750 directory. So this line is responsible for @command{make} building
1751 @file{src/hello} even though we run it from the top-level. This line
1752 also causes @code{make install} to install @file{src/hello} before
1753 installing @file{README} (not that this order matters).
1755 The line @code{dist_doc_DATA = README} causes @file{README} to be
1756 distributed and installed in @var{docdir}. Files listed with the
1757 @code{_DATA} primary are not automatically part of the tarball built
1758 with @code{make dist}, so we add the @code{dist_} prefix so they get
1759 distributed. However, for @file{README} it would not have been
1760 necessary: @command{automake} automatically distributes any
1761 @file{README} file it encounters (the list of other files
1762 automatically distributed is presented by @code{automake --help}).
1763 The only important effect of this second line is therefore to install
1764 @file{README} during @code{make install}.
1766 One thing not covered in this example is accessing the installation
1767 directory values (@pxref{Standard Directory Variables}) from your
1768 program code, that is, converting them into defined macros. For this,
1769 @pxref{Defining Directories,,, autoconf, The Autoconf Manual}.
1773 @chapter General ideas
1775 The following sections cover a few basic ideas that will help you
1776 understand how Automake works.
1779 * General Operation:: General operation of Automake
1780 * Strictness:: Standards conformance checking
1781 * Uniform:: The Uniform Naming Scheme
1782 * Length Limitations:: Staying below the command line length limit
1783 * Canonicalization:: How derived variables are named
1784 * User Variables:: Variables reserved for the user
1785 * Auxiliary Programs:: Programs automake might require
1789 @node General Operation
1790 @section General Operation
1792 Automake works by reading a @file{Makefile.am} and generating a
1793 @file{Makefile.in}. Certain variables and rules defined in the
1794 @file{Makefile.am} instruct Automake to generate more specialized code;
1795 for instance, a @code{bin_PROGRAMS} variable definition will cause rules
1796 for compiling and linking programs to be generated.
1798 @cindex Non-standard targets
1799 @cindex @code{git-dist}, non-standard example
1802 The variable definitions and rules in the @file{Makefile.am} are
1803 copied mostly verbatim into the generated file, with all variable
1804 definitions preceding all rules. This allows you to add almost
1805 arbitrary code into the generated @file{Makefile.in}. For instance,
1806 the Automake distribution includes a non-standard rule for the
1807 @code{git-dist} target, which the Automake maintainer uses to make
1808 distributions from the source control system.
1810 @cindex GNU make extensions
1812 Note that most GNU make extensions are not recognized by Automake. Using
1813 such extensions in a @file{Makefile.am} will lead to errors or confusing
1816 @cindex Append operator
1818 A special exception is that the GNU make append operator, @samp{+=}, is
1819 supported. This operator appends its right hand argument to the variable
1820 specified on the left. Automake will translate the operator into
1821 an ordinary @samp{=} operator; @samp{+=} will thus work with any make program.
1823 Automake tries to keep comments grouped with any adjoining rules or
1824 variable definitions.
1826 @cindex Limitations of automake parser
1827 @cindex Automake parser, limitations of
1828 @cindex indentation in Makefile.am
1829 Generally, Automake is not particularly smart in the parsing of unusual
1830 Makefile constructs, so you're advised to avoid fancy constructs or
1831 ``creative'' use of whitespaces.
1832 @c Keep this in sync with doc-parsing-buglets-tabs.sh
1833 For example, @key{TAB} characters cannot be used between a target name
1834 and the following ``@code{:}'' character, and variable assignments
1835 shouldn't be indented with @key{TAB} characters.
1836 @c Keep this in sync with doc-parsing-buglets-colneq-subst.sh
1837 Also, using more complex macro in target names can cause trouble:
1840 % @kbd{cat Makefile.am}
1843 Makefile.am:1: bad characters in variable name `$(FOO'
1844 Makefile.am:1: `:='-style assignments are not portable
1847 @cindex Make targets, overriding
1848 @cindex Make rules, overriding
1849 @cindex Overriding make rules
1850 @cindex Overriding make targets
1852 A rule defined in @file{Makefile.am} generally overrides any such
1853 rule of a similar name that would be automatically generated by
1854 @command{automake}. Although this is a supported feature, it is generally
1855 best to avoid making use of it, as sometimes the generated rules are
1858 @cindex Variables, overriding
1859 @cindex Overriding make variables
1861 Similarly, a variable defined in @file{Makefile.am} or
1862 @code{AC_SUBST}ed from @file{configure.ac} will override any
1863 definition of the variable that @command{automake} would ordinarily
1864 create. This feature is more often useful than the ability to
1865 override a rule. Be warned that many of the variables generated by
1866 @command{automake} are considered to be for internal use only, and their
1867 names might change in future releases.
1869 @cindex Recursive operation of Automake
1870 @cindex Automake, recursive operation
1871 @cindex Example of recursive operation
1873 When examining a variable definition, Automake will recursively examine
1874 variables referenced in the definition. For example, if Automake is
1875 looking at the content of @code{foo_SOURCES} in this snippet
1877 @c Keep in sync with interp.sh
1880 foo_SOURCES = c.c $(xs)
1883 it would use the files @file{a.c}, @file{b.c}, and @file{c.c} as the
1884 contents of @code{foo_SOURCES}.
1886 @cindex @code{##} (special Automake comment)
1887 @cindex Special Automake comment
1888 @cindex Comment, special to Automake
1890 Automake also allows a form of comment that is @emph{not} copied into
1891 the output; all lines beginning with @samp{##} (leading spaces allowed)
1892 are completely ignored by Automake.
1894 It is customary to make the first line of @file{Makefile.am} read:
1896 @cindex Makefile.am, first line
1897 @cindex First line of Makefile.am
1900 ## Process this file with automake to produce Makefile.in
1903 @c FIXME discuss putting a copyright into Makefile.am here? I would but
1904 @c I don't know quite what to say.
1906 @c FIXME document customary ordering of Makefile.am here!
1912 @cindex Non-GNU packages
1914 While Automake is intended to be used by maintainers of GNU packages, it
1915 does make some effort to accommodate those who wish to use it, but do
1916 not want to use all the GNU conventions.
1918 @cindex Strictness, defined
1919 @cindex Strictness, @option{foreign}
1920 @cindex @option{foreign} strictness
1921 @cindex Strictness, @option{gnu}
1922 @cindex @option{gnu} strictness
1923 @cindex Strictness, @option{gnits}
1924 @cindex @option{gnits} strictness
1926 To this end, Automake supports three levels of @dfn{strictness}---the
1927 strictness indicating how stringently Automake should check standards
1930 The valid strictness levels are:
1934 Automake will check for only those things that are absolutely
1935 required for proper operations. For instance, whereas GNU standards
1936 dictate the existence of a @file{NEWS} file, it will not be required in
1937 this mode. This strictness will also turn off some warnings by default
1938 (among them, portability warnings).
1939 The name comes from the fact that Automake is intended to be
1940 used for GNU programs; these relaxed rules are not the standard mode of
1944 Automake will check---as much as possible---for compliance to the GNU
1945 standards for packages. This is the default.
1948 Automake will check for compliance to the as-yet-unwritten @dfn{Gnits
1949 standards}. These are based on the GNU standards, but are even more
1950 detailed. Unless you are a Gnits standards contributor, it is
1951 recommended that you avoid this option until such time as the Gnits
1952 standard is actually published (which may never happen).
1955 @xref{Gnits}, for more information on the precise implications of the
1958 Automake also has a special (and @emph{today deprecated}) ``cygnus'' mode
1959 that is similar to strictness but handled differently. This mode is
1960 useful for packages that are put into a ``Cygnus'' style tree (e.g., older
1961 versions of the GCC and gdb trees). @xref{Cygnus}, for more information
1962 on this mode. Please note that this mode @emph{is deprecated and will be
1963 removed in the next major Automake release (1.13)}; you must avoid its use
1964 in new packages, and should stop using it in existing packages as well.
1968 @section The Uniform Naming Scheme
1970 @cindex Uniform naming scheme
1972 Automake variables generally follow a @dfn{uniform naming scheme} that
1973 makes it easy to decide how programs (and other derived objects) are
1974 built, and how they are installed. This scheme also supports
1975 @command{configure} time determination of what should be built.
1977 @cindex @code{_PROGRAMS} primary variable
1978 @cindex @code{PROGRAMS} primary variable
1979 @cindex Primary variable, @code{PROGRAMS}
1980 @cindex Primary variable, defined
1983 At @command{make} time, certain variables are used to determine which
1984 objects are to be built. The variable names are made of several pieces
1985 that are concatenated together.
1987 The piece that tells @command{automake} what is being built is commonly called
1988 the @dfn{primary}. For instance, the primary @code{PROGRAMS} holds a
1989 list of programs that are to be compiled and linked.
1992 @cindex @code{pkgdatadir}, defined
1993 @cindex @code{pkgincludedir}, defined
1994 @cindex @code{pkglibdir}, defined
1995 @cindex @code{pkglibexecdir}, defined
1998 @vindex pkgincludedir
2000 @vindex pkglibexecdir
2002 @cindex @code{PACKAGE}, directory
2003 A different set of names is used to decide where the built objects
2004 should be installed. These names are prefixes to the primary, and they
2005 indicate which standard directory should be used as the installation
2006 directory. The standard directory names are given in the GNU standards
2007 (@pxref{Directory Variables, , , standards, The GNU Coding Standards}).
2008 Automake extends this list with @code{pkgdatadir}, @code{pkgincludedir},
2009 @code{pkglibdir}, and @code{pkglibexecdir}; these are the same as the
2010 non-@samp{pkg} versions, but with @samp{$(PACKAGE)} appended. For instance,
2011 @code{pkglibdir} is defined as @samp{$(libdir)/$(PACKAGE)}.
2013 @cindex @code{EXTRA_}, prepending
2014 For each primary, there is one additional variable named by prepending
2015 @samp{EXTRA_} to the primary name. This variable is used to list
2016 objects that may or may not be built, depending on what
2017 @command{configure} decides. This variable is required because Automake
2018 must statically know the entire list of objects that may be built in
2019 order to generate a @file{Makefile.in} that will work in all cases.
2021 @cindex @code{EXTRA_PROGRAMS}, defined
2022 @cindex Example, @code{EXTRA_PROGRAMS}
2023 @cindex @command{cpio} example
2025 For instance, @command{cpio} decides at configure time which programs
2026 should be built. Some of the programs are installed in @code{bindir},
2027 and some are installed in @code{sbindir}:
2030 EXTRA_PROGRAMS = mt rmt
2031 bin_PROGRAMS = cpio pax
2032 sbin_PROGRAMS = $(MORE_PROGRAMS)
2035 Defining a primary without a prefix as a variable, e.g.,
2036 @samp{PROGRAMS}, is an error.
2038 Note that the common @samp{dir} suffix is left off when constructing the
2039 variable names; thus one writes @samp{bin_PROGRAMS} and not
2040 @samp{bindir_PROGRAMS}.
2042 Not every sort of object can be installed in every directory. Automake
2043 will flag those attempts it finds in error (but see below how to override
2044 the check if you really need to).
2045 Automake will also diagnose obvious misspellings in directory names.
2047 @cindex Extending list of installation directories
2048 @cindex Installation directories, extending list
2050 Sometimes the standard directories---even as augmented by
2051 Automake---are not enough. In particular it is sometimes useful, for
2052 clarity, to install objects in a subdirectory of some predefined
2053 directory. To this end, Automake allows you to extend the list of
2054 possible installation directories. A given prefix (e.g., @samp{zar})
2055 is valid if a variable of the same name with @samp{dir} appended is
2056 defined (e.g., @samp{zardir}).
2058 For instance, the following snippet will install @file{file.xml} into
2059 @samp{$(datadir)/xml}.
2061 @c Keep in sync with primary-prefix-couples-documented-valid.sh
2063 xmldir = $(datadir)/xml
2067 This feature can also be used to override the sanity checks Automake
2068 performs to diagnose suspicious directory/primary couples (in the
2069 unlikely case these checks are undesirable, and you really know what
2070 you're doing). For example, Automake would error out on this input:
2072 @c Should be tested in primary-prefix-invalid-couples.sh
2074 # Forbidden directory combinations, automake will error out on this.
2075 pkglib_PROGRAMS = foo
2076 doc_LIBRARIES = libquux.a
2080 but it will succeed with this:
2082 @c Keep in sync with primary-prefix-couples-documented-valid.sh
2084 # Work around forbidden directory combinations. Do not use this
2085 # without a very good reason!
2086 my_execbindir = $(pkglibdir)
2087 my_doclibdir = $(docdir)
2088 my_execbin_PROGRAMS = foo
2089 my_doclib_LIBRARIES = libquux.a
2092 The @samp{exec} substring of the @samp{my_execbindir} variable lets
2093 the files be installed at the right time (@pxref{The Two Parts of
2096 @cindex @samp{noinst_} primary prefix, definition
2099 The special prefix @samp{noinst_} indicates that the objects in question
2100 should be built but not installed at all. This is usually used for
2101 objects required to build the rest of your package, for instance static
2102 libraries (@pxref{A Library}), or helper scripts.
2104 @cindex @samp{check_} primary prefix, definition
2107 The special prefix @samp{check_} indicates that the objects in question
2108 should not be built until the @samp{make check} command is run. Those
2109 objects are not installed either.
2111 The current primary names are @samp{PROGRAMS}, @samp{LIBRARIES},
2112 @samp{LTLIBRARIES}, @samp{LISP}, @samp{PYTHON}, @samp{JAVA},
2113 @samp{SCRIPTS}, @samp{DATA}, @samp{HEADERS}, @samp{MANS}, and
2127 Some primaries also allow additional prefixes that control other
2128 aspects of @command{automake}'s behavior. The currently defined prefixes
2129 are @samp{dist_}, @samp{nodist_}, @samp{nobase_}, and @samp{notrans_}.
2130 These prefixes are explained later (@pxref{Program and Library Variables})
2131 (@pxref{Man Pages}).
2134 @node Length Limitations
2135 @section Staying below the command line length limit
2137 @cindex command line length limit
2140 Traditionally, most unix-like systems have a length limitation for the
2141 command line arguments and environment contents when creating new
2142 processes (see for example
2143 @uref{http://www.in-ulm.de/@/~mascheck/@/various/@/argmax/} for an
2144 overview on this issue),
2145 which of course also applies to commands spawned by @command{make}.
2146 POSIX requires this limit to be at least 4096 bytes, and most modern
2147 systems have quite high limits (or are unlimited).
2149 In order to create portable Makefiles that do not trip over these
2150 limits, it is necessary to keep the length of file lists bounded.
2151 Unfortunately, it is not possible to do so fully transparently within
2152 Automake, so your help may be needed. Typically, you can split long
2153 file lists manually and use different installation directory names for
2154 each list. For example,
2157 data_DATA = file1 @dots{} file@var{N} file@var{N+1} @dots{} file@var{2N}
2161 may also be written as
2163 @c Keep in sync with primary-prefix-couples-documented-valid.sh
2165 data_DATA = file1 @dots{} file@var{N}
2166 data2dir = $(datadir)
2167 data2_DATA = file@var{N+1} @dots{} file@var{2N}
2171 and will cause Automake to treat the two lists separately during
2172 @code{make install}. See @ref{The Two Parts of Install} for choosing
2173 directory names that will keep the ordering of the two parts of
2174 installation Note that @code{make dist} may still only work on a host
2175 with a higher length limit in this example.
2177 Automake itself employs a couple of strategies to avoid long command
2178 lines. For example, when @samp{$@{srcdir@}/} is prepended to file
2179 names, as can happen with above @code{$(data_DATA)} lists, it limits
2180 the amount of arguments passed to external commands.
2182 Unfortunately, some system's @command{make} commands may prepend
2183 @code{VPATH} prefixes like @samp{$@{srcdir@}/} to file names from the
2184 source tree automatically (@pxref{Automatic Rule Rewriting, , Automatic
2185 Rule Rewriting, autoconf, The Autoconf Manual}). In this case, the user
2186 may have to switch to use GNU Make, or refrain from using VPATH builds,
2187 in order to stay below the length limit.
2189 For libraries and programs built from many sources, convenience archives
2190 may be used as intermediates in order to limit the object list length
2191 (@pxref{Libtool Convenience Libraries}).
2194 @node Canonicalization
2195 @section How derived variables are named
2197 @cindex canonicalizing Automake variables
2199 Sometimes a Makefile variable name is derived from some text the
2200 maintainer supplies. For instance, a program name listed in
2201 @samp{_PROGRAMS} is rewritten into the name of a @samp{_SOURCES}
2202 variable. In cases like this, Automake canonicalizes the text, so that
2203 program names and the like do not have to follow Makefile variable naming
2204 rules. All characters in the name except for letters, numbers, the
2205 strudel (@@), and the underscore are turned into underscores when making
2206 variable references.
2208 For example, if your program is named @file{sniff-glue}, the derived
2209 variable name would be @samp{sniff_glue_SOURCES}, not
2210 @samp{sniff-glue_SOURCES}. Similarly the sources for a library named
2211 @file{libmumble++.a} should be listed in the
2212 @samp{libmumble___a_SOURCES} variable.
2214 The strudel is an addition, to make the use of Autoconf substitutions in
2215 variable names less obfuscating.
2218 @node User Variables
2219 @section Variables reserved for the user
2221 @cindex variables, reserved for the user
2222 @cindex user variables
2224 Some @file{Makefile} variables are reserved by the GNU Coding Standards
2225 for the use of the ``user''---the person building the package. For
2226 instance, @code{CFLAGS} is one such variable.
2228 Sometimes package developers are tempted to set user variables such as
2229 @code{CFLAGS} because it appears to make their job easier. However,
2230 the package itself should never set a user variable, particularly not
2231 to include switches that are required for proper compilation of the
2232 package. Since these variables are documented as being for the
2233 package builder, that person rightfully expects to be able to override
2234 any of these variables at build time.
2236 To get around this problem, Automake introduces an automake-specific
2237 shadow variable for each user flag variable. (Shadow variables are
2238 not introduced for variables like @code{CC}, where they would make no
2239 sense.) The shadow variable is named by prepending @samp{AM_} to the
2240 user variable's name. For instance, the shadow variable for
2241 @code{YFLAGS} is @code{AM_YFLAGS}. The package maintainer---that is,
2242 the author(s) of the @file{Makefile.am} and @file{configure.ac}
2243 files---may adjust these shadow variables however necessary.
2245 @xref{Flag Variables Ordering}, for more discussion about these
2246 variables and how they interact with per-target variables.
2248 @node Auxiliary Programs
2249 @section Programs automake might require
2251 @cindex Programs, auxiliary
2252 @cindex Auxiliary programs
2254 Automake sometimes requires helper programs so that the generated
2255 @file{Makefile} can do its work properly. There are a fairly large
2256 number of them, and we list them here.
2258 Although all of these files are distributed and installed with
2259 Automake, a couple of them are maintained separately. The Automake
2260 copies are updated before each release, but we mention the original
2261 source in case you need more recent versions.
2265 This is a wrapper primarily for the Microsoft lib archiver, to make
2269 This is a wrapper for compilers that do not accept options @option{-c}
2270 and @option{-o} at the same time. It is only used when absolutely
2271 required. Such compilers are rare, with the Microsoft C/C++ Compiler
2272 as the most notable exception. This wrapper also makes the following
2273 common options available for that compiler, while performing file name
2274 translation where needed: @option{-I}, @option{-L}, @option{-l},
2275 @option{-Wl,} and @option{-Xlinker}.
2279 These two programs compute the canonical triplets for the given build,
2280 host, or target architecture. These programs are updated regularly to
2281 support new architectures and fix probes broken by changes in new
2282 kernel versions. Each new release of Automake comes with up-to-date
2283 copies of these programs. If your copy of Automake is getting old,
2284 you are encouraged to fetch the latest versions of these files from
2285 @url{http://savannah.gnu.org/git/?group=config} before making a
2289 This program understands how to run a compiler so that it will
2290 generate not only the desired output but also dependency information
2291 that is then used by the automatic dependency tracking feature
2292 (@pxref{Dependencies}).
2295 This program is used to byte-compile Emacs Lisp code.
2298 This is a replacement for the @command{install} program that works on
2299 platforms where @command{install} is unavailable or unusable.
2302 This script is used to generate a @file{version.texi} file. It examines
2303 a file and prints some date information about it.
2306 This wraps a number of programs that are typically only required by
2307 maintainers. If the program in question doesn't exist,
2308 @command{missing} prints an informative warning and attempts to fix
2309 things so that the build can continue.
2312 This script used to be a wrapper around @samp{mkdir -p}, which is not
2313 portable. Now we prefer to use @samp{install-sh -d} when @command{configure}
2314 finds that @samp{mkdir -p} does not work, this makes one less script to
2317 For backward compatibility @file{mkinstalldirs} is still used and
2318 distributed when @command{automake} finds it in a package. But it is no
2319 longer installed automatically, and it should be safe to remove it.
2322 This is used to byte-compile Python scripts.
2325 This implements the default test driver offered by the parallel
2329 Not a program, this file is required for @samp{make dvi}, @samp{make
2330 ps} and @samp{make pdf} to work when Texinfo sources are in the
2331 package. The latest version can be downloaded from
2332 @url{http://www.gnu.org/software/texinfo/}.
2335 This program wraps @command{lex} and @command{yacc} to rename their
2336 output files. It also ensures that, for instance, multiple
2337 @command{yacc} instances can be invoked in a single directory in
2344 @chapter Some example packages
2346 This section contains two small examples.
2348 The first example (@pxref{Complete}) assumes you have an existing
2349 project already using Autoconf, with handcrafted @file{Makefile}s, and
2350 that you want to convert it to using Automake. If you are discovering
2351 both tools, it is probably better that you look at the Hello World
2352 example presented earlier (@pxref{Hello World}).
2354 The second example (@pxref{true}) shows how two programs can be built
2355 from the same file, using different compilation parameters. It
2356 contains some technical digressions that are probably best skipped on
2360 * Complete:: A simple example, start to finish
2361 * true:: Building true and false
2366 @section A simple example, start to finish
2368 @cindex Complete example
2370 Let's suppose you just finished writing @code{zardoz}, a program to make
2371 your head float from vortex to vortex. You've been using Autoconf to
2372 provide a portability framework, but your @file{Makefile.in}s have been
2373 ad-hoc. You want to make them bulletproof, so you turn to Automake.
2375 @cindex @code{AM_INIT_AUTOMAKE}, example use
2377 The first step is to update your @file{configure.ac} to include the
2378 commands that @command{automake} needs. The way to do this is to add an
2379 @code{AM_INIT_AUTOMAKE} call just after @code{AC_INIT}:
2382 AC_INIT([zardoz], [1.0])
2387 Since your program doesn't have any complicating factors (e.g., it
2388 doesn't use @code{gettext}, it doesn't want to build a shared library),
2389 you're done with this part. That was easy!
2391 @cindex @command{aclocal} program, introduction
2392 @cindex @file{aclocal.m4}, preexisting
2393 @cindex @file{acinclude.m4}, defined
2395 Now you must regenerate @file{configure}. But to do that, you'll need
2396 to tell @command{autoconf} how to find the new macro you've used. The
2397 easiest way to do this is to use the @command{aclocal} program to
2398 generate your @file{aclocal.m4} for you. But wait@dots{} maybe you
2399 already have an @file{aclocal.m4}, because you had to write some hairy
2400 macros for your program. The @command{aclocal} program lets you put
2401 your own macros into @file{acinclude.m4}, so simply rename and then
2405 mv aclocal.m4 acinclude.m4
2410 @cindex @command{zardoz} example
2412 Now it is time to write your @file{Makefile.am} for @code{zardoz}.
2413 Since @code{zardoz} is a user program, you want to install it where the
2414 rest of the user programs go: @code{bindir}. Additionally,
2415 @code{zardoz} has some Texinfo documentation. Your @file{configure.ac}
2416 script uses @code{AC_REPLACE_FUNCS}, so you need to link against
2417 @samp{$(LIBOBJS)}. So here's what you'd write:
2420 bin_PROGRAMS = zardoz
2421 zardoz_SOURCES = main.c head.c float.c vortex9.c gun.c
2422 zardoz_LDADD = $(LIBOBJS)
2424 info_TEXINFOS = zardoz.texi
2427 Now you can run @samp{automake --add-missing} to generate your
2428 @file{Makefile.in} and grab any auxiliary files you might need, and
2433 @section Building true and false
2435 @cindex Example, @command{false} and @command{true}
2436 @cindex @command{false} Example
2437 @cindex @command{true} Example
2439 Here is another, trickier example. It shows how to generate two
2440 programs (@code{true} and @code{false}) from the same source file
2441 (@file{true.c}). The difficult part is that each compilation of
2442 @file{true.c} requires different @code{cpp} flags.
2445 bin_PROGRAMS = true false
2447 false_LDADD = false.o
2450 $(COMPILE) -DEXIT_CODE=0 -c true.c
2453 $(COMPILE) -DEXIT_CODE=1 -o false.o -c true.c
2456 Note that there is no @code{true_SOURCES} definition. Automake will
2457 implicitly assume that there is a source file named @file{true.c}
2458 (@pxref{Default _SOURCES}), and
2459 define rules to compile @file{true.o} and link @file{true}. The
2460 @samp{true.o: true.c} rule supplied by the above @file{Makefile.am},
2461 will override the Automake generated rule to build @file{true.o}.
2463 @code{false_SOURCES} is defined to be empty---that way no implicit value
2464 is substituted. Because we have not listed the source of
2465 @file{false}, we have to tell Automake how to link the program. This is
2466 the purpose of the @code{false_LDADD} line. A @code{false_DEPENDENCIES}
2467 variable, holding the dependencies of the @file{false} target will be
2468 automatically generated by Automake from the content of
2471 The above rules won't work if your compiler doesn't accept both
2472 @option{-c} and @option{-o}. The simplest fix for this is to introduce a
2473 bogus dependency (to avoid problems with a parallel @command{make}):
2476 true.o: true.c false.o
2477 $(COMPILE) -DEXIT_CODE=0 -c true.c
2480 $(COMPILE) -DEXIT_CODE=1 -c true.c && mv true.o false.o
2483 As it turns out, there is also a much easier way to do this same task.
2484 Some of the above technique is useful enough that we've kept the
2485 example in the manual. However if you were to build @code{true} and
2486 @code{false} in real life, you would probably use per-program
2487 compilation flags, like so:
2489 @c Keep in sync with specflg7.sh and specflg8.sh
2491 bin_PROGRAMS = false true
2493 false_SOURCES = true.c
2494 false_CPPFLAGS = -DEXIT_CODE=1
2496 true_SOURCES = true.c
2497 true_CPPFLAGS = -DEXIT_CODE=0
2500 In this case Automake will cause @file{true.c} to be compiled twice,
2501 with different flags. In this instance, the names of the object files
2502 would be chosen by automake; they would be @file{false-true.o} and
2503 @file{true-true.o}. (The name of the object files rarely matters.)
2505 @node automake Invocation
2506 @chapter Creating a @file{Makefile.in}
2507 @c This node used to be named "Invoking automake". This @anchor
2508 @c allows old links to still work.
2509 @anchor{Invoking automake}
2511 @cindex Multiple @file{configure.ac} files
2512 @cindex Invoking @command{automake}
2513 @cindex @command{automake}, invoking
2514 @cindex Invocation of @command{automake}
2515 @cindex @command{automake}, invocation
2517 To create all the @file{Makefile.in}s for a package, run the
2518 @command{automake} program in the top level directory, with no
2519 arguments. @command{automake} will automatically find each
2520 appropriate @file{Makefile.am} (by scanning @file{configure.ac};
2521 @pxref{configure}) and generate the corresponding @file{Makefile.in}.
2522 Note that @command{automake} has a rather simplistic view of what
2523 constitutes a package; it assumes that a package has only one
2524 @file{configure.ac}, at the top. If your package has multiple
2525 @file{configure.ac}s, then you must run @command{automake} in each
2526 directory holding a @file{configure.ac}. (Alternatively, you may rely
2527 on Autoconf's @command{autoreconf}, which is able to recurse your
2528 package tree and run @command{automake} where appropriate.)
2530 You can optionally give @command{automake} an argument; @file{.am} is
2531 appended to the argument and the result is used as the name of the
2532 input file. This feature is generally only used to automatically
2533 rebuild an out-of-date @file{Makefile.in}. Note that
2534 @command{automake} must always be run from the topmost directory of a
2535 project, even if being used to regenerate the @file{Makefile.in} in
2536 some subdirectory. This is necessary because @command{automake} must
2537 scan @file{configure.ac}, and because @command{automake} uses the
2538 knowledge that a @file{Makefile.in} is in a subdirectory to change its
2539 behavior in some cases.
2542 Automake will run @command{autoconf} to scan @file{configure.ac} and
2543 its dependencies (i.e., @file{aclocal.m4} and any included file),
2544 therefore @command{autoconf} must be in your @env{PATH}. If there is
2545 an @env{AUTOCONF} variable in your environment it will be used
2546 instead of @command{autoconf}, this allows you to select a particular
2547 version of Autoconf. By the way, don't misunderstand this paragraph:
2548 @command{automake} runs @command{autoconf} to @strong{scan} your
2549 @file{configure.ac}, this won't build @file{configure} and you still
2550 have to run @command{autoconf} yourself for this purpose.
2552 @cindex @command{automake} options
2553 @cindex Options, @command{automake}
2554 @cindex Strictness, command line
2556 @command{automake} accepts the following options:
2558 @cindex Extra files distributed with Automake
2559 @cindex Files distributed with Automake
2560 @cindex @file{config.guess}
2564 @itemx --add-missing
2566 @opindex --add-missing
2567 Automake requires certain common files to exist in certain situations;
2568 for instance, @file{config.guess} is required if @file{configure.ac} invokes
2569 @code{AC_CANONICAL_HOST}. Automake is distributed with several of these
2570 files (@pxref{Auxiliary Programs}); this option will cause the missing
2571 ones to be automatically added to the package, whenever possible. In
2572 general if Automake tells you a file is missing, try using this option.
2573 By default Automake tries to make a symbolic link pointing to its own
2574 copy of the missing file; this can be changed with @option{--copy}.
2576 Many of the potentially-missing files are common scripts whose
2577 location may be specified via the @code{AC_CONFIG_AUX_DIR} macro.
2578 Therefore, @code{AC_CONFIG_AUX_DIR}'s setting affects whether a
2579 file is considered missing, and where the missing file is added
2582 In some strictness modes, additional files are installed, see @ref{Gnits}
2583 for more information.
2585 @item --libdir=@var{dir}
2587 Look for Automake data files in directory @var{dir} instead of in the
2588 installation directory. This is typically used for debugging.
2590 @item --print-libdir
2591 @opindex --print-libdir
2592 Print the path of the installation directory containing Automake-provided
2593 scripts and data files (like e.g., @file{texinfo.texi} and
2600 When used with @option{--add-missing}, causes installed files to be
2601 copied. The default is to make a symbolic link.
2605 Causes the generated @file{Makefile.in}s to follow Cygnus rules, instead
2606 of GNU or Gnits rules. For more information, see @ref{Cygnus}.
2607 Note that @emph{this mode of operation is deprecated, and will be removed}
2608 in the next major Automake release (1.13).
2612 @itemx --force-missing
2613 @opindex --force-missing
2614 When used with @option{--add-missing}, causes standard files to be reinstalled
2615 even if they already exist in the source tree. This involves removing
2616 the file from the source tree before creating the new symlink (or, with
2617 @option{--copy}, copying the new file).
2621 Set the global strictness to @option{foreign}. For more information, see
2626 Set the global strictness to @option{gnits}. For more information, see
2631 Set the global strictness to @option{gnu}. For more information, see
2632 @ref{Gnits}. This is the default strictness.
2636 Print a summary of the command line options and exit.
2639 @itemx --ignore-deps
2641 This disables the dependency tracking feature in generated
2642 @file{Makefile}s; see @ref{Dependencies}.
2644 @item --include-deps
2645 @opindex --include-deps
2646 This enables the dependency tracking feature. This feature is enabled
2647 by default. This option is provided for historical reasons only and
2648 probably should not be used.
2652 Ordinarily @command{automake} creates all @file{Makefile.in}s mentioned in
2653 @file{configure.ac}. This option causes it to only update those
2654 @file{Makefile.in}s that are out of date with respect to one of their
2658 @itemx --output-dir=@var{dir}
2660 @opindex --output-dir
2661 Put the generated @file{Makefile.in} in the directory @var{dir}.
2662 Ordinarily each @file{Makefile.in} is created in the directory of the
2663 corresponding @file{Makefile.am}. This option is deprecated and will be
2664 removed in a future release.
2670 Cause Automake to print information about which files are being read or
2675 Print the version number of Automake and exit.
2678 @itemx --warnings=@var{category}
2681 Output warnings falling in @var{category}. @var{category} can be
2685 warnings related to the GNU Coding Standards
2686 (@pxref{Top, , , standards, The GNU Coding Standards}).
2688 obsolete features or constructions
2690 user redefinitions of Automake rules or variables
2692 portability issues (e.g., use of @command{make} features that are
2693 known to be not portable)
2694 @item extra-portability
2695 extra portability issues related to obscure tools. One example of such
2696 a tool is the Microsoft @command{lib} archiver.
2698 weird syntax, unused variables, typos
2700 unsupported or incomplete features
2704 turn off all the warnings
2706 treat warnings as errors
2709 A category can be turned off by prefixing its name with @samp{no-}. For
2710 instance, @option{-Wno-syntax} will hide the warnings about unused
2713 The categories output by default are @samp{syntax} and
2714 @samp{unsupported}. Additionally, @samp{gnu} and @samp{portability}
2715 are enabled in @option{--gnu} and @option{--gnits} strictness.
2716 On the other hand, the @option{silent-rules} options (@pxref{Options})
2717 turns off portability warnings about recursive variable expansions.
2719 @c Checked by extra-portability.sh
2720 Turning off @samp{portability} will also turn off @samp{extra-portability},
2721 and similarly turning on @samp{extra-portability} will also turn on
2722 @samp{portability}. However, turning on @samp{portability} or turning
2723 off @samp{extra-portability} will not affect the other category.
2726 The environment variable @env{WARNINGS} can contain a comma separated
2727 list of categories to enable. It will be taken into account before the
2728 command-line switches, this way @option{-Wnone} will also ignore any
2729 warning category enabled by @env{WARNINGS}. This variable is also used
2730 by other tools like @command{autoconf}; unknown categories are ignored
2735 @vindex AUTOMAKE_JOBS
2736 If the environment variable @env{AUTOMAKE_JOBS} contains a positive
2737 number, it is taken as the maximum number of Perl threads to use in
2738 @command{automake} for generating multiple @file{Makefile.in} files
2739 concurrently. This is an experimental feature.
2743 @chapter Scanning @file{configure.ac}, using @command{aclocal}
2745 @cindex @file{configure.ac}, scanning
2746 @cindex Scanning @file{configure.ac}
2747 @cindex Using @command{aclocal}
2748 @cindex @command{aclocal}, using
2750 Automake scans the package's @file{configure.ac} to determine certain
2751 information about the package. Some @command{autoconf} macros are required
2752 and some variables must be defined in @file{configure.ac}. Automake
2753 will also use information from @file{configure.ac} to further tailor its
2756 Automake also supplies some Autoconf macros to make the maintenance
2757 easier. These macros can automatically be put into your
2758 @file{aclocal.m4} using the @command{aclocal} program.
2761 * Requirements:: Configuration requirements
2762 * Optional:: Other things Automake recognizes
2763 * aclocal Invocation:: Auto-generating aclocal.m4
2764 * Macros:: Autoconf macros supplied with Automake
2769 @section Configuration requirements
2771 @cindex Automake requirements
2772 @cindex Requirements of Automake
2774 @acindex AM_INIT_AUTOMAKE
2775 The one real requirement of Automake is that your @file{configure.ac}
2776 call @code{AM_INIT_AUTOMAKE}. This macro does several things that are
2777 required for proper Automake operation (@pxref{Macros}).
2779 Here are the other macros that Automake requires but which are not run
2780 by @code{AM_INIT_AUTOMAKE}:
2783 @item AC_CONFIG_FILES
2785 @acindex AC_CONFIG_FILES
2787 These two macros are usually invoked as follows near the end of
2788 @file{configure.ac}.
2802 Automake uses these to determine which files to create (@pxref{Output, ,
2803 Creating Output Files, autoconf, The Autoconf Manual}). A listed file
2804 is considered to be an Automake generated @file{Makefile} if there
2805 exists a file with the same name and the @file{.am} extension appended.
2806 Typically, @samp{AC_CONFIG_FILES([foo/Makefile])} will cause Automake to
2807 generate @file{foo/Makefile.in} if @file{foo/Makefile.am} exists.
2809 When using @code{AC_CONFIG_FILES} with multiple input files, as in
2812 AC_CONFIG_FILES([Makefile:top.in:Makefile.in:bot.in])
2816 @command{automake} will generate the first @file{.in} input file for
2817 which a @file{.am} file exists. If no such file exists the output
2818 file is not considered to be generated by Automake.
2820 Files created by @code{AC_CONFIG_FILES}, be they Automake
2821 @file{Makefile}s or not, are all removed by @samp{make distclean}.
2822 Their inputs are automatically distributed, unless they
2823 are the output of prior @code{AC_CONFIG_FILES} commands.
2824 Finally, rebuild rules are generated in the Automake @file{Makefile}
2825 existing in the subdirectory of the output file, if there is one, or
2826 in the top-level @file{Makefile} otherwise.
2828 The above machinery (cleaning, distributing, and rebuilding) works
2829 fine if the @code{AC_CONFIG_FILES} specifications contain only
2830 literals. If part of the specification uses shell variables,
2831 @command{automake} will not be able to fulfill this setup, and you will
2832 have to complete the missing bits by hand. For instance, on
2834 @c Keep in sync with output11.sh
2838 AC_CONFIG_FILES([output:$file],, [file=$file])
2842 @command{automake} will output rules to clean @file{output}, and
2843 rebuild it. However the rebuild rule will not depend on @file{input},
2844 and this file will not be distributed either. (You must add
2845 @samp{EXTRA_DIST = input} to your @file{Makefile.am} if @file{input} is a
2850 @c Keep in sync with output11.sh
2855 AC_CONFIG_FILES([$file:input],, [file=$file])
2856 AC_CONFIG_FILES([$file2],, [file2=$file2])
2860 will only cause @file{input} to be distributed. No file will be
2861 cleaned automatically (add @samp{DISTCLEANFILES = output out}
2862 yourself), and no rebuild rule will be output.
2864 Obviously @command{automake} cannot guess what value @samp{$file} is
2865 going to hold later when @file{configure} is run, and it cannot use
2866 the shell variable @samp{$file} in a @file{Makefile}. However, if you
2867 make reference to @samp{$file} as @samp{$@{file@}} (i.e., in a way
2868 that is compatible with @command{make}'s syntax) and furthermore use
2869 @code{AC_SUBST} to ensure that @samp{$@{file@}} is meaningful in a
2870 @file{Makefile}, then @command{automake} will be able to use
2871 @samp{$@{file@}} to generate all of these rules. For instance, here is
2872 how the Automake package itself generates versioned scripts for its
2876 AC_SUBST([APIVERSION], @dots{})
2879 [tests/aclocal-$@{APIVERSION@}:tests/aclocal.in],
2880 [chmod +x tests/aclocal-$@{APIVERSION@}],
2881 [APIVERSION=$APIVERSION])
2883 [tests/automake-$@{APIVERSION@}:tests/automake.in],
2884 [chmod +x tests/automake-$@{APIVERSION@}])
2888 Here cleaning, distributing, and rebuilding are done automatically,
2889 because @samp{$@{APIVERSION@}} is known at @command{make}-time.
2891 Note that you should not use shell variables to declare
2892 @file{Makefile} files for which @command{automake} must create
2893 @file{Makefile.in}. Even @code{AC_SUBST} does not help here, because
2894 @command{automake} needs to know the file name when it runs in order
2895 to check whether @file{Makefile.am} exists. (In the very hairy case
2896 that your setup requires such use of variables, you will have to tell
2897 Automake which @file{Makefile.in}s to generate on the command-line.)
2899 It is possible to let @command{automake} emit conditional rules for
2900 @code{AC_CONFIG_FILES} with the help of @code{AM_COND_IF}
2906 Use literals for @file{Makefile}s, and for other files whenever possible.
2908 Use @samp{$file} (or @samp{$@{file@}} without @samp{AC_SUBST([file])})
2909 for files that @command{automake} should ignore.
2911 Use @samp{$@{file@}} and @samp{AC_SUBST([file])} for files
2912 that @command{automake} should not ignore.
2919 @section Other things Automake recognizes
2921 @cindex Macros Automake recognizes
2922 @cindex Recognized macros by Automake
2924 Every time Automake is run it calls Autoconf to trace
2925 @file{configure.ac}. This way it can recognize the use of certain
2926 macros and tailor the generated @file{Makefile.in} appropriately.
2927 Currently recognized macros and their effects are:
2930 @item AC_CANONICAL_BUILD
2931 @itemx AC_CANONICAL_HOST
2932 @itemx AC_CANONICAL_TARGET
2933 @vindex build_triplet
2934 @vindex host_triplet
2935 @vindex target_triplet
2936 Automake will ensure that @file{config.guess} and @file{config.sub}
2937 exist. Also, the @file{Makefile} variables @code{build_triplet},
2938 @code{host_triplet} and @code{target_triplet} are introduced. See
2939 @ref{Canonicalizing, , Getting the Canonical System Type, autoconf,
2940 The Autoconf Manual}.
2942 @item AC_CONFIG_AUX_DIR
2943 Automake will look for various helper scripts, such as
2944 @file{install-sh}, in the directory named in this macro invocation.
2945 @c This list is accurate relative to version 1.11
2946 (The full list of scripts is:
2948 @file{config.guess},
2957 @file{mkinstalldirs},
2962 Not all scripts are always searched for; some scripts
2963 will only be sought if the generated @file{Makefile.in} requires them.
2965 If @code{AC_CONFIG_AUX_DIR} is not given, the scripts are looked for in
2966 their standard locations. For @file{mdate-sh},
2967 @file{texinfo.tex}, and @file{ylwrap}, the standard location is the
2968 source directory corresponding to the current @file{Makefile.am}. For
2969 the rest, the standard location is the first one of @file{.}, @file{..},
2970 or @file{../..} (relative to the top source directory) that provides any
2971 one of the helper scripts. @xref{Input, , Finding `configure' Input,
2972 autoconf, The Autoconf Manual}.
2974 Required files from @code{AC_CONFIG_AUX_DIR} are automatically
2975 distributed, even if there is no @file{Makefile.am} in this directory.
2977 @item AC_CONFIG_LIBOBJ_DIR
2978 Automake will require the sources file declared with
2979 @code{AC_LIBSOURCE} (see below) in the directory specified by this
2982 @item AC_CONFIG_HEADERS
2983 Automake will generate rules to rebuild these headers. Older versions
2984 of Automake required the use of @code{AM_CONFIG_HEADER}
2985 (@pxref{Macros}); this is no longer the case.
2987 As with @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the
2988 specification using shell variables will be ignored as far as
2989 cleaning, distributing, and rebuilding is concerned.
2991 @item AC_CONFIG_LINKS
2992 Automake will generate rules to remove @file{configure} generated
2993 links on @samp{make distclean} and to distribute named source files as
2994 part of @samp{make dist}.
2996 As for @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the
2997 specification using shell variables will be ignored as far as cleaning
2998 and distributing is concerned. (There are no rebuild rules for links.)
3002 @itemx AC_LIBSOURCES
3004 Automake will automatically distribute any file listed in
3005 @code{AC_LIBSOURCE} or @code{AC_LIBSOURCES}.
3007 Note that the @code{AC_LIBOBJ} macro calls @code{AC_LIBSOURCE}. So if
3008 an Autoconf macro is documented to call @samp{AC_LIBOBJ([file])}, then
3009 @file{file.c} will be distributed automatically by Automake. This
3010 encompasses many macros like @code{AC_FUNC_ALLOCA},
3011 @code{AC_FUNC_MEMCMP}, @code{AC_REPLACE_FUNCS}, and others.
3013 By the way, direct assignments to @code{LIBOBJS} are no longer
3014 supported. You should always use @code{AC_LIBOBJ} for this purpose.
3015 @xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs.@: @code{LIBOBJS},
3016 autoconf, The Autoconf Manual}.
3018 @item AC_PROG_RANLIB
3019 This is required if any libraries are built in the package.
3020 @xref{Particular Programs, , Particular Program Checks, autoconf, The
3024 This is required if any C++ source is included. @xref{Particular
3025 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
3028 This is required if any Objective C source is included. @xref{Particular
3029 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
3031 @item AC_PROG_OBJCXX
3032 This is required if any Objective C++ source is included. @xref{Particular
3033 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
3036 This is required if any Fortran 77 source is included. @xref{Particular
3037 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
3039 @item AC_F77_LIBRARY_LDFLAGS
3040 This is required for programs and shared libraries that are a mixture of
3041 languages that include Fortran 77 (@pxref{Mixing Fortran 77 With C and
3042 C++}). @xref{Macros, , Autoconf macros supplied with Automake}.
3045 Automake will add the flags computed by @code{AC_FC_SRCEXT} to compilation
3046 of files with the respective source extension (@pxref{Fortran Compiler, ,
3047 Fortran Compiler Characteristics, autoconf, The Autoconf Manual}).
3050 This is required if any Fortran 90/95 source is included. This macro is
3051 distributed with Autoconf version 2.58 and later. @xref{Particular
3052 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
3054 @item AC_PROG_LIBTOOL
3055 Automake will turn on processing for @command{libtool} (@pxref{Top, ,
3056 Introduction, libtool, The Libtool Manual}).
3060 If a Yacc source file is seen, then you must either use this macro or
3061 define the variable @code{YACC} in @file{configure.ac}. The former is
3062 preferred (@pxref{Particular Programs, , Particular Program Checks,
3063 autoconf, The Autoconf Manual}).
3066 If a Lex source file is seen, then this macro must be used.
3067 @xref{Particular Programs, , Particular Program Checks, autoconf, The
3070 @item AC_REQUIRE_AUX_FILE
3071 For each @code{AC_REQUIRE_AUX_FILE([@var{file}])},
3072 @command{automake} will ensure that @file{@var{file}} exists in the
3073 aux directory, and will complain otherwise. It
3074 will also automatically distribute the file. This macro should be
3075 used by third-party Autoconf macros that require some supporting
3076 files in the aux directory specified with @code{AC_CONFIG_AUX_DIR}
3077 above. @xref{Input, , Finding @command{configure} Input, autoconf,
3078 The Autoconf Manual}.
3081 The first argument is automatically defined as a variable in each
3082 generated @file{Makefile.in}, unless @code{AM_SUBST_NOTMAKE} is also
3083 used for this variable. @xref{Setting Output Variables, , Setting
3084 Output Variables, autoconf, The Autoconf Manual}.
3086 For every substituted variable @var{var}, @command{automake} will add
3087 a line @code{@var{var} = @var{value}} to each @file{Makefile.in} file.
3088 Many Autoconf macros invoke @code{AC_SUBST} to set output variables
3089 this way, e.g., @code{AC_PATH_XTRA} defines @code{X_CFLAGS} and
3090 @code{X_LIBS}. Thus, you can access these variables as
3091 @code{$(X_CFLAGS)} and @code{$(X_LIBS)} in any @file{Makefile.am}
3092 if @code{AC_PATH_XTRA} is called.
3094 @item AM_CONDITIONAL
3095 This introduces an Automake conditional (@pxref{Conditionals}).
3098 This macro allows @code{automake} to detect subsequent access within
3099 @file{configure.ac} to a conditional previously introduced with
3100 @code{AM_CONDITIONAL}, thus enabling conditional @code{AC_CONFIG_FILES}
3101 (@pxref{Usage of Conditionals}).
3103 @item AM_GNU_GETTEXT
3104 This macro is required for packages that use GNU gettext
3105 (@pxref{gettext}). It is distributed with gettext. If Automake sees
3106 this macro it ensures that the package meets some of gettext's
3109 @item AM_GNU_GETTEXT_INTL_SUBDIR
3110 This macro specifies that the @file{intl/} subdirectory is to be built,
3111 even if the @code{AM_GNU_GETTEXT} macro was invoked with a first argument
3114 @item AM_MAINTAINER_MODE(@ovar{default-mode})
3115 @opindex --enable-maintainer-mode
3116 @opindex --disable-maintainer-mode
3117 This macro adds an @option{--enable-maintainer-mode} option to
3118 @command{configure}. If this is used, @command{automake} will cause
3119 ``maintainer-only'' rules to be turned off by default in the
3120 generated @file{Makefile.in}s, unless @var{default-mode} is
3121 @samp{enable}. This macro defines the @code{MAINTAINER_MODE}
3122 conditional, which you can use in your own @file{Makefile.am}.
3123 @xref{maintainer-mode}.
3125 @item AM_SUBST_NOTMAKE(@var{var})
3126 Prevent Automake from defining a variable @var{var}, even if it is
3127 substituted by @command{config.status}. Normally, Automake defines a
3128 @command{make} variable for each @command{configure} substitution,
3129 i.e., for each @code{AC_SUBST([@var{var}])}. This macro prevents that
3130 definition from Automake. If @code{AC_SUBST} has not been called
3131 for this variable, then @code{AM_SUBST_NOTMAKE} has no effects.
3132 Preventing variable definitions may be useful for substitution of
3133 multi-line values, where @code{@var{var} = @@@var{value}@@} might yield
3137 Files included by @file{configure.ac} using this macro will be
3138 detected by Automake and automatically distributed. They will also
3139 appear as dependencies in @file{Makefile} rules.
3141 @code{m4_include} is seldom used by @file{configure.ac} authors, but
3142 can appear in @file{aclocal.m4} when @command{aclocal} detects that
3143 some required macros come from files local to your package (as opposed to
3144 macros installed in a system-wide directory, @pxref{aclocal Invocation}).
3148 @node aclocal Invocation
3149 @section Auto-generating aclocal.m4
3150 @c This node used to be named "Invoking automake". This @anchor
3151 @c allows old links to still work.
3152 @anchor{Invoking aclocal}
3154 @cindex Invocation of @command{aclocal}
3155 @cindex @command{aclocal}, Invocation
3156 @cindex Invoking @command{aclocal}
3157 @cindex @command{aclocal}, Invoking
3159 Automake includes a number of Autoconf macros that can be used in
3160 your package (@pxref{Macros}); some of them are actually required by
3161 Automake in certain situations. These macros must be defined in your
3162 @file{aclocal.m4}; otherwise they will not be seen by
3165 The @command{aclocal} program will automatically generate
3166 @file{aclocal.m4} files based on the contents of @file{configure.ac}.
3167 This provides a convenient way to get Automake-provided macros,
3168 without having to search around. The @command{aclocal} mechanism
3169 allows other packages to supply their own macros (@pxref{Extending
3170 aclocal}). You can also use it to maintain your own set of custom
3171 macros (@pxref{Local Macros}).
3173 At startup, @command{aclocal} scans all the @file{.m4} files it can
3174 find, looking for macro definitions (@pxref{Macro Search Path}). Then
3175 it scans @file{configure.ac}. Any mention of one of the macros found
3176 in the first step causes that macro, and any macros it in turn
3177 requires, to be put into @file{aclocal.m4}.
3179 @emph{Putting} the file that contains the macro definition into
3180 @file{aclocal.m4} is usually done by copying the entire text of this
3181 file, including unused macro definitions as well as both @samp{#} and
3182 @samp{dnl} comments. If you want to make a comment that will be
3183 completely ignored by @command{aclocal}, use @samp{##} as the comment
3186 When a file selected by @command{aclocal} is located in a subdirectory
3187 specified as a relative search path with @command{aclocal}'s @option{-I}
3188 argument, @command{aclocal} assumes the file belongs to the package
3189 and uses @code{m4_include} instead of copying it into
3190 @file{aclocal.m4}. This makes the package smaller, eases dependency
3191 tracking, and cause the file to be distributed automatically.
3192 (@xref{Local Macros}, for an example.) Any macro that is found in a
3193 system-wide directory, or via an absolute search path will be copied.
3194 So use @samp{-I `pwd`/reldir} instead of @samp{-I reldir} whenever
3195 some relative directory should be considered outside the package.
3197 The contents of @file{acinclude.m4}, if this file exists, are also
3198 automatically included in @file{aclocal.m4}. We recommend against
3199 using @file{acinclude.m4} in new packages (@pxref{Local Macros}).
3203 While computing @file{aclocal.m4}, @command{aclocal} runs
3204 @command{autom4te} (@pxref{Using autom4te, , Using @command{Autom4te},
3205 autoconf, The Autoconf Manual}) in order to trace the macros that are
3206 really used, and omit from @file{aclocal.m4} all macros that are
3207 mentioned but otherwise unexpanded (this can happen when a macro is
3208 called conditionally). @command{autom4te} is expected to be in the
3209 @env{PATH}, just as @command{autoconf}. Its location can be
3210 overridden using the @env{AUTOM4TE} environment variable.
3213 * aclocal Options:: Options supported by aclocal
3214 * Macro Search Path:: How aclocal finds .m4 files
3215 * Extending aclocal:: Writing your own aclocal macros
3216 * Local Macros:: Organizing local macros
3217 * Serials:: Serial lines in Autoconf macros
3218 * Future of aclocal:: aclocal's scheduled death
3221 @node aclocal Options
3222 @subsection aclocal Options
3224 @cindex @command{aclocal}, Options
3225 @cindex Options, @command{aclocal}
3227 @command{aclocal} accepts the following options:
3230 @item --automake-acdir=@var{dir}
3231 @opindex --automake-acdir
3232 Look for the automake-provided macro files in @var{dir} instead of
3233 in the installation directory. This is typically used for debugging.
3235 @item --system-acdir=@var{dir}
3236 @opindex --system-acdir
3237 Look for the system-wide third-party macro files (and the special
3238 @file{dirlist} file) in @var{dir} instead of in the installation
3239 directory. This is typically used for debugging.
3241 @item --diff[=@var{command}]
3243 Run @var{command} on M4 file that would be installed or overwritten
3244 by @option{--install}. The default @var{command} is @samp{diff -u}.
3245 This option implies @option{--install} and @option{--dry-run}.
3249 Do not actually overwrite (or create) @file{aclocal.m4} and M4
3250 files installed by @option{--install}.
3254 Print a summary of the command line options and exit.
3258 Add the directory @var{dir} to the list of directories searched for
3263 Install system-wide third-party macros into the first directory
3264 specified with @samp{-I @var{dir}} instead of copying them in the
3266 @c Keep in sync with aclocal-install-absdir.sh
3267 Note that this will happen also if @var{dir} is an absolute path.
3269 @cindex serial number and @option{--install}
3270 When this option is used, and only when this option is used,
3271 @command{aclocal} will also honor @samp{#serial @var{number}} lines
3272 that appear in macros: an M4 file is ignored if there exists another
3273 M4 file with the same basename and a greater serial number in the
3274 search path (@pxref{Serials}).
3278 Always overwrite the output file. The default is to overwrite the output
3279 file only when really needed, i.e., when its contents changes or if one
3280 of its dependencies is younger.
3282 This option forces the update of @file{aclocal.m4} (or the file
3283 specified with @file{--output} below) and only this file, it has
3284 absolutely no influence on files that may need to be installed by
3287 @item --output=@var{file}
3289 Cause the output to be put into @var{file} instead of @file{aclocal.m4}.
3291 @item --print-ac-dir
3292 @opindex --print-ac-dir
3293 Prints the name of the directory that @command{aclocal} will search to
3294 find third-party @file{.m4} files. When this option is given, normal
3295 processing is suppressed. This option was used @emph{in the past} by
3296 third-party packages to determine where to install @file{.m4} macro
3297 files, but @emph{this usage is today discouraged}, since it causes
3298 @samp{$(prefix)} not to be thoroughly honoured (which violates the
3299 GNU Coding Standards), and a similar semantics can be better obtained
3300 with the @env{ACLOCAL_PATH} environment variable; @pxref{Extending aclocal}.
3304 Print the names of the files it examines.
3308 Print the version number of Automake and exit.
3311 @item --warnings=@var{category}
3314 Output warnings falling in @var{category}. @var{category} can be
3318 dubious syntactic constructs, underquoted macros, unused macros, etc.
3322 all the warnings, this is the default
3324 turn off all the warnings
3326 treat warnings as errors
3329 All warnings are output by default.
3332 The environment variable @env{WARNINGS} is honored in the same
3333 way as it is for @command{automake} (@pxref{automake Invocation}).
3337 @node Macro Search Path
3338 @subsection Macro Search Path
3340 @cindex Macro search path
3341 @cindex @command{aclocal} search path
3343 By default, @command{aclocal} searches for @file{.m4} files in the following
3344 directories, in this order:
3347 @item @var{acdir-APIVERSION}
3348 This is where the @file{.m4} macros distributed with Automake itself
3349 are stored. @var{APIVERSION} depends on the Automake release used;
3350 for example, for Automake 1.11.x, @var{APIVERSION} = @code{1.11}.
3353 This directory is intended for third party @file{.m4} files, and is
3354 configured when @command{automake} itself is built. This is
3355 @file{@@datadir@@/aclocal/}, which typically
3356 expands to @file{$@{prefix@}/share/aclocal/}. To find the compiled-in
3357 value of @var{acdir}, use the @option{--print-ac-dir} option
3358 (@pxref{aclocal Options}).
3361 As an example, suppose that @command{automake-1.11.2} was configured with
3362 @option{--prefix=@-/usr/local}. Then, the search path would be:
3365 @item @file{/usr/local/share/aclocal-1.11.2/}
3366 @item @file{/usr/local/share/aclocal/}
3369 The paths for the @var{acdir} and @var{acdir-APIVERSION} directories can
3370 be changed respectively through aclocal options @option{--system-acdir}
3371 and @option{--automake-acdir} (@pxref{aclocal Options}). Note however
3372 that these options are only intended for use by the internal Automake
3373 test suite, or for debugging under highly unusual situations; they are
3374 not ordinarily needed by end-users.
3376 As explained in (@pxref{aclocal Options}), there are several options that
3377 can be used to change or extend this search path.
3379 @subsubheading Modifying the Macro Search Path: @samp{-I @var{dir}}
3381 Any extra directories specified using @option{-I} options
3382 (@pxref{aclocal Options}) are @emph{prepended} to this search list. Thus,
3383 @samp{aclocal -I /foo -I /bar} results in the following search path:
3388 @item @var{acdir}-@var{APIVERSION}
3392 @subsubheading Modifying the Macro Search Path: @file{dirlist}
3393 @cindex @file{dirlist}
3395 There is a third mechanism for customizing the search path. If a
3396 @file{dirlist} file exists in @var{acdir}, then that file is assumed to
3397 contain a list of directory patterns, one per line. @command{aclocal}
3398 expands these patterns to directory names, and adds them to the search
3399 list @emph{after} all other directories. @file{dirlist} entries may
3400 use shell wildcards such as @samp{*}, @samp{?}, or @code{[...]}.
3402 For example, suppose
3403 @file{@var{acdir}/dirlist} contains the following:
3412 and that @command{aclocal} was called with the @samp{-I /foo -I /bar} options.
3413 Then, the search path would be
3415 @c @code looks better than @file here
3419 @item @var{acdir}-@var{APIVERSION}
3426 and all directories with path names starting with @code{/test3}.
3428 If the @option{--system-acdir=@var{dir}} option is used, then
3429 @command{aclocal} will search for the @file{dirlist} file in
3430 @var{dir}; but remember the warnings above against the use of
3431 @option{--system-acdir}.
3433 @file{dirlist} is useful in the following situation: suppose that
3434 @command{automake} version @code{1.11.2} is installed with
3435 @samp{--prefix=/usr} by the system vendor. Thus, the default search
3438 @c @code looks better than @file here
3440 @item @code{/usr/share/aclocal-1.11/}
3441 @item @code{/usr/share/aclocal/}
3444 However, suppose further that many packages have been manually
3445 installed on the system, with $prefix=/usr/local, as is typical. In
3446 that case, many of these ``extra'' @file{.m4} files are in
3447 @file{/usr/local/share/aclocal}. The only way to force
3448 @file{/usr/bin/aclocal} to find these ``extra'' @file{.m4} files is to
3449 always call @samp{aclocal -I /usr/local/share/aclocal}. This is
3450 inconvenient. With @file{dirlist}, one may create a file
3451 @file{/usr/share/aclocal/dirlist} containing only the single line
3454 /usr/local/share/aclocal
3457 Now, the ``default'' search path on the affected system is
3459 @c @code looks better than @file here
3461 @item @code{/usr/share/aclocal-1.11/}
3462 @item @code{/usr/share/aclocal/}
3463 @item @code{/usr/local/share/aclocal/}
3466 without the need for @option{-I} options; @option{-I} options can be reserved
3467 for project-specific needs (@file{my-source-dir/m4/}), rather than
3468 using it to work around local system-dependent tool installation
3471 Similarly, @file{dirlist} can be handy if you have installed a local
3472 copy of Automake in your account and want @command{aclocal} to look for
3473 macros installed at other places on the system.
3475 @anchor{ACLOCAL_PATH}
3476 @subsubheading Modifying the Macro Search Path: @file{ACLOCAL_PATH}
3477 @cindex @env{ACLOCAL_PATH}
3479 The fourth and last mechanism to customize the macro search path is
3480 also the simplest. Any directory included in the colon-separated
3481 environment variable @env{ACLOCAL_PATH} is added to the search path
3482 @c Keep in sync with aclocal-path-precedence.sh
3483 and takes precedence over system directories (including those found via
3484 @file{dirlist}), with the exception of the versioned directory
3485 @var{acdir-APIVERSION} (@pxref{Macro Search Path}). However, directories
3486 passed via @option{-I} will take precedence over directories in
3489 @c Keep in sync with aclocal-path-installed.sh
3490 Also note that, if the @option{--install} option is used, any @file{.m4}
3491 file containing a required macro that is found in a directory listed in
3492 @env{ACLOCAL_PATH} will be installed locally.
3493 @c Keep in sync with aclocal-path-installed-serial.sh
3494 In this case, serial numbers in @file{.m4} are honoured too,
3497 Conversely to @file{dirlist}, @env{ACLOCAL_PATH} is useful if you are
3498 using a global copy of Automake and want @command{aclocal} to look for
3499 macros somewhere under your home directory.
3501 @subsubheading Planned future incompatibilities
3503 The order in which the directories in the macro search path are currently
3504 looked up is confusing and/or suboptimal in various aspects, and is
3505 probably going to be changed in the future Automake release. In
3506 particular, directories in @env{ACLOCAL_PATH} and @file{@var{acdir}}
3507 might end up taking precedence over @file{@var{acdir-APIVERSION}}, and
3508 directories in @file{@var{acdir}/dirlist} might end up taking precedence
3509 over @file{@var{acdir}}. @emph{This is a possible future incompatibility!}
3511 @node Extending aclocal
3512 @subsection Writing your own aclocal macros
3514 @cindex @command{aclocal}, extending
3515 @cindex Extending @command{aclocal}
3517 The @command{aclocal} program doesn't have any built-in knowledge of any
3518 macros, so it is easy to extend it with your own macros.
3520 This can be used by libraries that want to supply their own Autoconf
3521 macros for use by other programs. For instance, the @command{gettext}
3522 library supplies a macro @code{AM_GNU_GETTEXT} that should be used by
3523 any package using @command{gettext}. When the library is installed, it
3524 installs this macro so that @command{aclocal} will find it.
3526 A macro file's name should end in @file{.m4}. Such files should be
3527 installed in @file{$(datadir)/aclocal}. This is as simple as writing:
3529 @c Keep in sync with primary-prefix-couples-documented-valid.sh
3531 aclocaldir = $(datadir)/aclocal
3532 aclocal_DATA = mymacro.m4 myothermacro.m4
3536 Please do use @file{$(datadir)/aclocal}, and not something based on
3537 the result of @samp{aclocal --print-ac-dir} (@pxref{Hard-Coded Install
3538 Paths}, for arguments). It might also be helpful to suggest to
3539 the user to add the @file{$(datadir)/aclocal} directory to his
3540 @env{ACLOCAL_PATH} variable (@pxref{ACLOCAL_PATH}) so that
3541 @command{aclocal} will find the @file{.m4} files installed by your
3542 package automatically.
3544 A file of macros should be a series of properly quoted
3545 @code{AC_DEFUN}'s (@pxref{Macro Definitions, , , autoconf, The
3546 Autoconf Manual}). The @command{aclocal} programs also understands
3547 @code{AC_REQUIRE} (@pxref{Prerequisite Macros, , , autoconf, The
3548 Autoconf Manual}), so it is safe to put each macro in a separate file.
3549 Each file should have no side effects but macro definitions.
3550 Especially, any call to @code{AC_PREREQ} should be done inside the
3551 defined macro, not at the beginning of the file.
3553 @cindex underquoted @code{AC_DEFUN}
3557 Starting with Automake 1.8, @command{aclocal} will warn about all
3558 underquoted calls to @code{AC_DEFUN}. We realize this will annoy a
3559 lot of people, because @command{aclocal} was not so strict in the past
3560 and many third party macros are underquoted; and we have to apologize
3561 for this temporary inconvenience. The reason we have to be stricter
3562 is that a future implementation of @command{aclocal} (@pxref{Future of
3563 aclocal}) will have to temporarily include all of these third party
3564 @file{.m4} files, maybe several times, including even files that are
3565 not actually needed. Doing so should alleviate many problems of the
3566 current implementation, however it requires a stricter style from the
3567 macro authors. Hopefully it is easy to revise the existing macros.
3574 [AC_REQUIRE([AX_SOMETHING])dnl
3581 should be rewritten as
3584 AC_DEFUN([AX_FOOBAR],
3585 [AC_PREREQ([2.68])dnl
3586 AC_REQUIRE([AX_SOMETHING])dnl
3592 Wrapping the @code{AC_PREREQ} call inside the macro ensures that
3593 Autoconf 2.68 will not be required if @code{AX_FOOBAR} is not actually
3594 used. Most importantly, quoting the first argument of @code{AC_DEFUN}
3595 allows the macro to be redefined or included twice (otherwise this
3596 first argument would be expanded during the second definition). For
3597 consistency we like to quote even arguments such as @code{2.68} that
3600 If you have been directed here by the @command{aclocal} diagnostic but
3601 are not the maintainer of the implicated macro, you will want to
3602 contact the maintainer of that macro. Please make sure you have the
3603 latest version of the macro and that the problem hasn't already been
3604 reported before doing so: people tend to work faster when they aren't
3607 Another situation where @command{aclocal} is commonly used is to
3608 manage macros that are used locally by the package, @ref{Local
3612 @subsection Handling Local Macros
3614 Feature tests offered by Autoconf do not cover all needs. People
3615 often have to supplement existing tests with their own macros, or
3616 with third-party macros.
3618 There are two ways to organize custom macros in a package.
3620 The first possibility (the historical practice) is to list all your
3621 macros in @file{acinclude.m4}. This file will be included in
3622 @file{aclocal.m4} when you run @command{aclocal}, and its macro(s) will
3623 henceforth be visible to @command{autoconf}. However if it contains
3624 numerous macros, it will rapidly become difficult to maintain, and it
3625 will be almost impossible to share macros between packages.
3627 @vindex ACLOCAL_AMFLAGS
3628 The second possibility, which we do recommend, is to write each macro
3629 in its own file and gather all of these files in a directory. This
3630 directory is usually called @file{m4/}. To build @file{aclocal.m4},
3631 one should therefore instruct @command{aclocal} to scan @file{m4/}.
3632 From the command line, this is done with @samp{aclocal -I m4}. The
3633 top-level @file{Makefile.am} should also be updated to define
3636 ACLOCAL_AMFLAGS = -I m4
3639 @code{ACLOCAL_AMFLAGS} contains options to pass to @command{aclocal}
3640 when @file{aclocal.m4} is to be rebuilt by @command{make}. This line is
3641 also used by @command{autoreconf} (@pxref{autoreconf Invocation, ,
3642 Using @command{autoreconf} to Update @file{configure} Scripts,
3643 autoconf, The Autoconf Manual}) to run @command{aclocal} with suitable
3644 options, or by @command{autopoint} (@pxref{autopoint Invocation, ,
3645 Invoking the @command{autopoint} Program, gettext, GNU gettext tools})
3646 and @command{gettextize} (@pxref{gettextize Invocation, , Invoking the
3647 @command{gettextize} Program, gettext, GNU gettext tools}) to locate
3648 the place where Gettext's macros should be installed. So even if you
3649 do not really care about the rebuild rules, you should define
3650 @code{ACLOCAL_AMFLAGS}.
3652 When @samp{aclocal -I m4} is run, it will build an @file{aclocal.m4}
3653 that @code{m4_include}s any file from @file{m4/} that defines a
3654 required macro. Macros not found locally will still be searched in
3655 system-wide directories, as explained in @ref{Macro Search Path}.
3657 Custom macros should be distributed for the same reason that
3658 @file{configure.ac} is: so that other people have all the sources of
3659 your package if they want to work on it. Actually, this distribution
3660 happens automatically because all @code{m4_include}d files are
3663 However there is no consensus on the distribution of third-party
3664 macros that your package may use. Many libraries install their own
3665 macro in the system-wide @command{aclocal} directory (@pxref{Extending
3666 aclocal}). For instance, Guile ships with a file called
3667 @file{guile.m4} that contains the macro @code{GUILE_FLAGS} that can
3668 be used to define setup compiler and linker flags appropriate for
3669 using Guile. Using @code{GUILE_FLAGS} in @file{configure.ac} will
3670 cause @command{aclocal} to copy @file{guile.m4} into
3671 @file{aclocal.m4}, but as @file{guile.m4} is not part of the project,
3672 it will not be distributed. Technically, that means a user who
3673 needs to rebuild @file{aclocal.m4} will have to install Guile first.
3674 This is probably OK, if Guile already is a requirement to build the
3675 package. However, if Guile is only an optional feature, or if your
3676 package might run on architectures where Guile cannot be installed,
3677 this requirement will hinder development. An easy solution is to copy
3678 such third-party macros in your local @file{m4/} directory so they get
3681 Since Automake 1.10, @command{aclocal} offers an option to copy these
3682 system-wide third-party macros in your local macro directory, solving
3683 the above problem. Simply use:
3686 ACLOCAL_AMFLAGS = -I m4 --install
3690 With this setup, system-wide macros will be copied to @file{m4/}
3691 the first time you run @command{autoreconf}. Then the locally
3692 installed macros will have precedence over the system-wide installed
3693 macros each time @command{aclocal} is run again.
3695 One reason why you should keep @option{--install} in the flags even
3696 after the first run is that when you later edit @file{configure.ac}
3697 and depend on a new macro, this macro will be installed in your
3698 @file{m4/} automatically. Another one is that serial numbers
3699 (@pxref{Serials}) can be used to update the macros in your source tree
3700 automatically when new system-wide versions are installed. A serial
3701 number should be a single line of the form
3708 where @var{nnn} contains only digits and dots. It should appear in
3709 the M4 file before any macro definition. It is a good practice to
3710 maintain a serial number for each macro you distribute, even if you do
3711 not use the @option{--install} option of @command{aclocal}: this allows
3712 other people to use it.
3716 @subsection Serial Numbers
3717 @cindex serial numbers in macros
3718 @cindex macro serial numbers
3719 @cindex @code{#serial} syntax
3720 @cindex @command{aclocal} and serial numbers
3722 Because third-party macros defined in @file{*.m4} files are naturally
3723 shared between multiple projects, some people like to version them.
3724 This makes it easier to tell which of two M4 files is newer. Since at
3725 least 1996, the tradition is to use a @samp{#serial} line for this.
3727 A serial number should be a single line of the form
3730 # serial @var{version}
3734 where @var{version} is a version number containing only digits and
3735 dots. Usually people use a single integer, and they increment it each
3736 time they change the macro (hence the name of ``serial''). Such a
3737 line should appear in the M4 file before any macro definition.
3739 The @samp{#} must be the first character on the line,
3740 and it is OK to have extra words after the version, as in
3743 #serial @var{version} @var{garbage}
3746 Normally these serial numbers are completely ignored by
3747 @command{aclocal} and @command{autoconf}, like any genuine comment.
3748 However when using @command{aclocal}'s @option{--install} feature, these
3749 serial numbers will modify the way @command{aclocal} selects the
3750 macros to install in the package: if two files with the same basename
3751 exist in your search path, and if at least one of them uses a
3752 @samp{#serial} line, @command{aclocal} will ignore the file that has
3753 the older @samp{#serial} line (or the file that has none).
3755 Note that a serial number applies to a whole M4 file, not to any macro
3756 it contains. A file can contains multiple macros, but only one
3759 Here is a use case that illustrates the use of @option{--install} and
3760 its interaction with serial numbers. Let's assume we maintain a
3761 package called MyPackage, the @file{configure.ac} of which requires a
3762 third-party macro @code{AX_THIRD_PARTY} defined in
3763 @file{/usr/share/aclocal/thirdparty.m4} as follows:
3767 AC_DEFUN([AX_THIRD_PARTY], [...])
3770 MyPackage uses an @file{m4/} directory to store local macros as
3771 explained in @ref{Local Macros}, and has
3774 ACLOCAL_AMFLAGS = -I m4 --install
3778 in its top-level @file{Makefile.am}.
3780 Initially the @file{m4/} directory is empty. The first time we run
3781 @command{autoreconf}, it will fetch the options to pass to
3782 @command{aclocal} in @file{Makefile.am}, and run @samp{aclocal -I m4
3783 --install}. @command{aclocal} will notice that
3787 @file{configure.ac} uses @code{AX_THIRD_PARTY}
3789 No local macros define @code{AX_THIRD_PARTY}
3791 @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3796 Because @file{/usr/share/aclocal/thirdparty.m4} is a system-wide macro
3797 and @command{aclocal} was given the @option{--install} option, it will
3798 copy this file in @file{m4/thirdparty.m4}, and output an
3799 @file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}.
3801 The next time @samp{aclocal -I m4 --install} is run (either via
3802 @command{autoreconf}, by hand, or from the @file{Makefile} rebuild
3803 rules) something different happens. @command{aclocal} notices that
3807 @file{configure.ac} uses @code{AX_THIRD_PARTY}
3809 @file{m4/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3812 @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3817 Because both files have the same serial number, @command{aclocal} uses
3818 the first it found in its search path order (@pxref{Macro Search
3819 Path}). @command{aclocal} therefore ignores
3820 @file{/usr/share/aclocal/thirdparty.m4} and outputs an
3821 @file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}.
3823 Local directories specified with @option{-I} are always searched before
3824 system-wide directories, so a local file will always be preferred to
3825 the system-wide file in case of equal serial numbers.
3827 Now suppose the system-wide third-party macro is changed. This can
3828 happen if the package installing this macro is updated. Let's suppose
3829 the new macro has serial number 2. The next time @samp{aclocal -I m4
3830 --install} is run the situation is the following:
3834 @file{configure.ac} uses @code{AX_THIRD_PARTY}
3836 @file{m4/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3839 @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3844 When @command{aclocal} sees a greater serial number, it immediately
3845 forgets anything it knows from files that have the same basename and a
3846 smaller serial number. So after it has found
3847 @file{/usr/share/aclocal/thirdparty.m4} with serial 2,
3848 @command{aclocal} will proceed as if it had never seen
3849 @file{m4/thirdparty.m4}. This brings us back to a situation similar
3850 to that at the beginning of our example, where no local file defined
3851 the macro. @command{aclocal} will install the new version of the
3852 macro in @file{m4/thirdparty.m4}, in this case overriding the old
3853 version. MyPackage just had its macro updated as a side effect of
3854 running @command{aclocal}.
3856 If you are leery of letting @command{aclocal} update your local macro,
3857 you can run @samp{aclocal -I m4 --diff} to review the changes
3858 @samp{aclocal -I m4 --install} would perform on these macros.
3860 Finally, note that the @option{--force} option of @command{aclocal} has
3861 absolutely no effect on the files installed by @option{--install}. For
3862 instance, if you have modified your local macros, do not expect
3863 @option{--install --force} to replace the local macros by their
3864 system-wide versions. If you want to do so, simply erase the local
3865 macros you want to revert, and run @samp{aclocal -I m4 --install}.
3868 @node Future of aclocal
3869 @subsection The Future of @command{aclocal}
3870 @cindex @command{aclocal}'s scheduled death
3872 @command{aclocal} is expected to disappear. This feature really
3873 should not be offered by Automake. Automake should focus on
3874 generating @file{Makefile}s; dealing with M4 macros really is
3875 Autoconf's job. The fact that some people install Automake just to use
3876 @command{aclocal}, but do not use @command{automake} otherwise is an
3877 indication of how that feature is misplaced.
3879 The new implementation will probably be done slightly differently.
3880 For instance, it could enforce the @file{m4/}-style layout discussed in
3883 We have no idea when and how this will happen. This has been
3884 discussed several times in the past, but someone still has to commit
3885 to that non-trivial task.
3887 From the user point of view, @command{aclocal}'s removal might turn
3888 out to be painful. There is a simple precaution that you may take to
3889 make that switch more seamless: never call @command{aclocal} yourself.
3890 Keep this guy under the exclusive control of @command{autoreconf} and
3891 Automake's rebuild rules. Hopefully you won't need to worry about
3892 things breaking, when @command{aclocal} disappears, because everything
3893 will have been taken care of. If otherwise you used to call
3894 @command{aclocal} directly yourself or from some script, you will
3895 quickly notice the change.
3897 Many packages come with a script called @file{bootstrap.sh} or
3898 @file{autogen.sh}, that will just call @command{aclocal},
3899 @command{libtoolize}, @command{gettextize} or @command{autopoint},
3900 @command{autoconf}, @command{autoheader}, and @command{automake} in
3901 the right order. Actually this is precisely what @command{autoreconf}
3902 can do for you. If your package has such a @file{bootstrap.sh} or
3903 @file{autogen.sh} script, consider using @command{autoreconf}. That
3904 should simplify its logic a lot (less things to maintain, yum!), it's
3905 even likely you will not need the script anymore, and more to the point
3906 you will not call @command{aclocal} directly anymore.
3908 For the time being, third-party packages should continue to install
3909 public macros into @file{/usr/share/aclocal/}. If @command{aclocal}
3910 is replaced by another tool it might make sense to rename the
3911 directory, but supporting @file{/usr/share/aclocal/} for backward
3912 compatibility should be really easy provided all macros are properly
3913 written (@pxref{Extending aclocal}).
3918 @section Autoconf macros supplied with Automake
3920 Automake ships with several Autoconf macros that you can use from your
3921 @file{configure.ac}. When you use one of them it will be included by
3922 @command{aclocal} in @file{aclocal.m4}.
3925 * Public Macros:: Macros that you can use.
3926 * Obsolete Macros:: Macros that will soon be removed.
3927 * Private Macros:: Macros that you should not use.
3930 @c consider generating the following subsections automatically from m4 files.
3933 @subsection Public Macros
3937 @item AM_INIT_AUTOMAKE([OPTIONS])
3938 @acindex AM_INIT_AUTOMAKE
3939 Runs many macros required for proper operation of the generated Makefiles.
3941 @vindex AUTOMAKE_OPTIONS
3942 Today, @code{AM_INIT_AUTOMAKE} is called with a single argument: a
3943 space-separated list of Automake options that should
3944 be applied to every @file{Makefile.am} in the tree. The effect is as if
3945 each option were listed in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
3948 This macro can also be called in @emph{another, deprecated form} (support
3949 for which will be @emph{removed in the next major Automake release (1.13)}):
3950 @code{AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])}. In this form,
3951 there are two required arguments: the package and the version number.
3952 This form is obsolete because the @var{package} and @var{version} can
3953 be obtained from Autoconf's @code{AC_INIT} macro (which itself has an
3954 old and a new form).
3956 @anchor{Modernize AM_INIT_AUTOMAKE invocation}
3957 If your @file{configure.ac} has:
3960 AC_INIT([src/foo.c])
3961 AM_INIT_AUTOMAKE([mumble], [1.5])
3965 you should modernize it as follows:
3968 AC_INIT([mumble], [1.5])
3969 AC_CONFIG_SRCDIR([src/foo.c])
3973 Note that if you're upgrading your @file{configure.ac} from an earlier
3974 version of Automake, it is not always correct to simply move the
3975 package and version arguments from @code{AM_INIT_AUTOMAKE} directly to
3976 @code{AC_INIT}, as in the example above. The first argument to
3977 @code{AC_INIT} should be the name of your package (e.g., @samp{GNU
3978 Automake}), not the tarball name (e.g., @samp{automake}) that you used
3979 to pass to @code{AM_INIT_AUTOMAKE}. Autoconf tries to derive a
3980 tarball name from the package name, which should work for most but not
3981 all package names. (If it doesn't work for yours, you can use the
3982 four-argument form of @code{AC_INIT} to provide the tarball name
3985 @cindex @code{PACKAGE}, prevent definition
3986 @cindex @code{VERSION}, prevent definition
3988 By default this macro @code{AC_DEFINE}'s @code{PACKAGE} and
3989 @code{VERSION}. This can be avoided by passing the @option{no-define}
3992 AM_INIT_AUTOMAKE([gnits 1.5 no-define dist-bzip2])
3995 @item AM_PATH_LISPDIR
3996 @acindex AM_PATH_LISPDIR
3999 Searches for the program @command{emacs}, and, if found, sets the
4000 output variable @code{lispdir} to the full path to Emacs' site-lisp
4003 Note that this test assumes the @command{emacs} found to be a version
4004 that supports Emacs Lisp (such as GNU Emacs or XEmacs). Other
4005 emacsen can cause this test to hang (some, like old versions of
4006 MicroEmacs, start up in interactive mode, requiring @kbd{C-x C-c} to
4007 exit, which is hardly obvious for a non-emacs user). In most cases,
4008 however, you should be able to use @kbd{C-c} to kill the test. In
4009 order to avoid problems, you can set @env{EMACS} to ``no'' in the
4010 environment, or use the @option{--with-lispdir} option to
4011 @command{configure} to explicitly set the correct path (if you're sure
4012 you have an @command{emacs} that supports Emacs Lisp).
4014 @item AM_PROG_AR(@ovar{act-if-fail})
4017 You must use this macro when you use the archiver in your project, if
4018 you want support for unusual archivers such as Microsoft @command{lib}.
4019 The content of the optional argument is executed if the archiver
4020 interface is not recognized; the default action is to abort configure
4021 with an error message.
4027 Use this macro when you have assembly code in your project. This will
4028 choose the assembler for you (by default the C compiler) and set
4029 @code{CCAS}, and will also set @code{CCASFLAGS} if required.
4031 @item AM_PROG_CC_C_O
4032 @acindex AM_PROG_CC_C_O
4033 @acindex AC_PROG_CC_C_O
4034 This is like @code{AC_PROG_CC_C_O}, but it generates its results in
4035 the manner required by Automake. You must use this instead of
4036 @code{AC_PROG_CC_C_O} when you need this functionality, that is, when
4037 using per-target flags or subdir-objects with C sources.
4040 @acindex AM_PROG_LEX
4041 @acindex AC_PROG_LEX
4042 @cindex HP-UX 10, @command{lex} problems
4043 @cindex @command{lex} problems with HP-UX 10
4044 Like @code{AC_PROG_LEX} (@pxref{Particular Programs, , Particular
4045 Program Checks, autoconf, The Autoconf Manual}), but uses the
4046 @command{missing} script on systems that do not have @command{lex}.
4047 HP-UX 10 is one such system.
4050 @acindex AM_PROG_GCJ
4053 This macro finds the @command{gcj} program or causes an error. It sets
4054 @code{GCJ} and @code{GCJFLAGS}. @command{gcj} is the Java front-end to the
4055 GNU Compiler Collection.
4057 @item AM_PROG_UPC([@var{compiler-search-list}])
4058 @acindex AM_PROG_UPC
4060 Find a compiler for Unified Parallel C and define the @code{UPC}
4061 variable. The default @var{compiler-search-list} is @samp{upcc upc}.
4062 This macro will abort @command{configure} if no Unified Parallel C
4065 @item AM_SILENT_RULES
4066 @acindex AM_SILENT_RULES
4067 Enable the machinery for less verbose build output (@pxref{Options}).
4069 @item AM_WITH_DMALLOC
4070 @acindex AM_WITH_DMALLOC
4071 @cindex @command{dmalloc}, support for
4072 @vindex WITH_DMALLOC
4073 @opindex --with-dmalloc
4074 Add support for the @uref{http://dmalloc.com/, Dmalloc package}. If
4075 the user runs @command{configure} with @option{--with-dmalloc}, then
4076 define @code{WITH_DMALLOC} and add @option{-ldmalloc} to @code{LIBS}.
4081 @node Obsolete Macros
4082 @subsection Obsolete Macros
4083 @cindex obsolete macros
4086 Although using some of the following macros was required in past
4087 releases, you should not use any of them in new code. @emph{All
4088 these macros will be removed in the next major Automake version};
4089 if you are still using them, running @command{autoupdate} should
4090 adjust your @file{configure.ac} automatically (@pxref{autoupdate
4091 Invocation, , Using @command{autoupdate} to Modernize
4092 @file{configure.ac}, autoconf, The Autoconf Manual}).
4097 @item AM_CONFIG_HEADER
4098 @acindex AM_CONFIG_HEADER
4099 Automake will generate rules to automatically regenerate the config
4100 header. This obsolete macro is a synonym of @code{AC_CONFIG_HEADERS}
4101 today (@pxref{Optional}).
4103 @item AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
4104 @acindex AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
4105 If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
4106 define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be
4107 found in @file{<termios.h>}. This macro is obsolete, you should
4108 use Autoconf's @code{AC_HEADER_TIOCGWINSZ} instead.
4110 @item AM_PROG_MKDIR_P
4111 @acindex AM_PROG_MKDIR_P
4112 @cindex @code{mkdir -p}, macro check
4116 From Automake 1.8 to 1.9.6 this macro used to define the output
4117 variable @code{mkdir_p} to one of @code{mkdir -p}, @code{install-sh
4118 -d}, or @code{mkinstalldirs}.
4120 Nowadays Autoconf provides a similar functionality with
4121 @code{AC_PROG_MKDIR_P} (@pxref{Particular Programs, , Particular
4122 Program Checks, autoconf, The Autoconf Manual}), however this defines
4123 the output variable @code{MKDIR_P} instead. In case you are still
4124 using the @code{AM_PROG_MKDIR_P} macro in your @file{configure.ac},
4125 or its provided variable @code{$(mkdir_p)} in your @file{Makefile.am},
4126 you are advised to switch ASAP to the more modern Autoconf-provided
4127 interface instead; both the macro and the variable @emph{will be
4128 removed} in the next major Automake release.
4130 @item AM_SYS_POSIX_TERMIOS
4131 @acindex AM_SYS_POSIX_TERMIOS
4132 @cindex POSIX termios headers
4133 @cindex termios POSIX headers
4134 Check to see if POSIX termios headers and functions are available on the
4135 system. If so, set the shell variable @code{am_cv_sys_posix_termios} to
4136 @samp{yes}. If not, set the variable to @samp{no}. This macro is obsolete,
4137 you should use Autoconf's @code{AC_SYS_POSIX_TERMIOS} instead.
4142 @node Private Macros
4143 @subsection Private Macros
4145 The following macros are private macros you should not call directly.
4146 They are called by the other public macros when appropriate. Do not
4147 rely on them, as they might be changed in a future version. Consider
4148 them as implementation details; or better, do not consider them at all:
4152 @item _AM_DEPENDENCIES
4153 @itemx AM_SET_DEPDIR
4155 @itemx AM_OUTPUT_DEPENDENCY_COMMANDS
4156 These macros are used to implement Automake's automatic dependency
4157 tracking scheme. They are called automatically by Automake when
4158 required, and there should be no need to invoke them manually.
4160 @item AM_MAKE_INCLUDE
4161 This macro is used to discover how the user's @command{make} handles
4162 @code{include} statements. This macro is automatically invoked when
4163 needed; there should be no need to invoke it manually.
4165 @item AM_PROG_INSTALL_STRIP
4166 This is used to find a version of @code{install} that can be used to
4167 strip a program at installation time. This macro is automatically
4168 included when required.
4170 @item AM_SANITY_CHECK
4171 This checks to make sure that a file created in the build directory is
4172 newer than a file in the source directory. This can fail on systems
4173 where the clock is set incorrectly. This macro is automatically run
4174 from @code{AM_INIT_AUTOMAKE}.
4180 @chapter Directories
4182 For simple projects that distribute all files in the same directory
4183 it is enough to have a single @file{Makefile.am} that builds
4184 everything in place.
4186 In larger projects it is common to organize files in different
4187 directories, in a tree. For instance one directory per program, per
4188 library or per module. The traditional approach is to build these
4189 subdirectories recursively: each directory contains its @file{Makefile}
4190 (generated from @file{Makefile.am}), and when @command{make} is run
4191 from the top level directory it enters each subdirectory in turn to
4195 * Subdirectories:: Building subdirectories recursively
4196 * Conditional Subdirectories:: Conditionally not building directories
4197 * Alternative:: Subdirectories without recursion
4198 * Subpackages:: Nesting packages
4201 @node Subdirectories
4202 @section Recursing subdirectories
4204 @cindex @code{SUBDIRS}, explained
4206 In packages with subdirectories, the top level @file{Makefile.am} must
4207 tell Automake which subdirectories are to be built. This is done via
4208 the @code{SUBDIRS} variable.
4211 The @code{SUBDIRS} variable holds a list of subdirectories in which
4212 building of various sorts can occur. The rules for many targets
4213 (e.g., @code{all}) in the generated @file{Makefile} will run commands
4214 both locally and in all specified subdirectories. Note that the
4215 directories listed in @code{SUBDIRS} are not required to contain
4216 @file{Makefile.am}s; only @file{Makefile}s (after configuration).
4217 This allows inclusion of libraries from packages that do not use
4218 Automake (such as @code{gettext}; see also @ref{Third-Party
4221 In packages that use subdirectories, the top-level @file{Makefile.am} is
4222 often very short. For instance, here is the @file{Makefile.am} from the
4223 GNU Hello distribution:
4226 EXTRA_DIST = BUGS ChangeLog.O README-alpha
4227 SUBDIRS = doc intl po src tests
4230 When Automake invokes @command{make} in a subdirectory, it uses the value
4231 of the @code{MAKE} variable. It passes the value of the variable
4232 @code{AM_MAKEFLAGS} to the @command{make} invocation; this can be set in
4233 @file{Makefile.am} if there are flags you must always pass to
4236 @vindex AM_MAKEFLAGS
4238 The directories mentioned in @code{SUBDIRS} are usually direct
4239 children of the current directory, each subdirectory containing its
4240 own @file{Makefile.am} with a @code{SUBDIRS} pointing to deeper
4241 subdirectories. Automake can be used to construct packages of
4242 arbitrary depth this way.
4244 By default, Automake generates @file{Makefiles} that work depth-first
4245 in postfix order: the subdirectories are built before the current
4246 directory. However, it is possible to change this ordering. You can
4247 do this by putting @samp{.} into @code{SUBDIRS}. For instance,
4248 putting @samp{.} first will cause a prefix ordering of
4254 SUBDIRS = lib src . test
4258 will cause @file{lib/} to be built before @file{src/}, then the
4259 current directory will be built, finally the @file{test/} directory
4260 will be built. It is customary to arrange test directories to be
4261 built after everything else since they are meant to test what has
4264 All @code{clean} rules are run in reverse order of build rules.
4266 @node Conditional Subdirectories
4267 @section Conditional Subdirectories
4268 @cindex Subdirectories, building conditionally
4269 @cindex Conditional subdirectories
4270 @cindex @code{SUBDIRS}, conditional
4271 @cindex Conditional @code{SUBDIRS}
4273 It is possible to define the @code{SUBDIRS} variable conditionally if,
4274 like in the case of GNU Inetutils, you want to only build a subset of
4277 To illustrate how this works, let's assume we have two directories
4278 @file{src/} and @file{opt/}. @file{src/} should always be built, but we
4279 want to decide in @command{configure} whether @file{opt/} will be built
4280 or not. (For this example we will assume that @file{opt/} should be
4281 built when the variable @samp{$want_opt} was set to @samp{yes}.)
4283 Running @command{make} should thus recurse into @file{src/} always, and
4284 then maybe in @file{opt/}.
4286 However @samp{make dist} should always recurse into both @file{src/}
4287 and @file{opt/}. Because @file{opt/} should be distributed even if it
4288 is not needed in the current configuration. This means
4289 @file{opt/Makefile} should be created @emph{unconditionally}.
4291 There are two ways to setup a project like this. You can use Automake
4292 conditionals (@pxref{Conditionals}) or use Autoconf @code{AC_SUBST}
4293 variables (@pxref{Setting Output Variables, , Setting Output
4294 Variables, autoconf, The Autoconf Manual}). Using Automake
4295 conditionals is the preferred solution. Before we illustrate these
4296 two possibilities, let's introduce @code{DIST_SUBDIRS}.
4299 * SUBDIRS vs DIST_SUBDIRS:: Two sets of directories
4300 * Subdirectories with AM_CONDITIONAL:: Specifying conditional subdirectories
4301 * Subdirectories with AC_SUBST:: Another way for conditional recursion
4302 * Unconfigured Subdirectories:: Not even creating a @samp{Makefile}
4305 @node SUBDIRS vs DIST_SUBDIRS
4306 @subsection @code{SUBDIRS} vs.@: @code{DIST_SUBDIRS}
4307 @cindex @code{DIST_SUBDIRS}, explained
4309 Automake considers two sets of directories, defined by the variables
4310 @code{SUBDIRS} and @code{DIST_SUBDIRS}.
4312 @code{SUBDIRS} contains the subdirectories of the current directory
4313 that must be built (@pxref{Subdirectories}). It must be defined
4314 manually; Automake will never guess a directory is to be built. As we
4315 will see in the next two sections, it is possible to define it
4316 conditionally so that some directory will be omitted from the build.
4318 @code{DIST_SUBDIRS} is used in rules that need to recurse in all
4319 directories, even those that have been conditionally left out of the
4320 build. Recall our example where we may not want to build subdirectory
4321 @file{opt/}, but yet we want to distribute it? This is where
4322 @code{DIST_SUBDIRS} comes into play: @samp{opt} may not appear in
4323 @code{SUBDIRS}, but it must appear in @code{DIST_SUBDIRS}.
4325 Precisely, @code{DIST_SUBDIRS} is used by @samp{make
4326 maintainer-clean}, @samp{make distclean} and @samp{make dist}. All
4327 other recursive rules use @code{SUBDIRS}.
4329 If @code{SUBDIRS} is defined conditionally using Automake
4330 conditionals, Automake will define @code{DIST_SUBDIRS} automatically
4331 from the possible values of @code{SUBDIRS} in all conditions.
4333 If @code{SUBDIRS} contains @code{AC_SUBST} variables,
4334 @code{DIST_SUBDIRS} will not be defined correctly because Automake
4335 does not know the possible values of these variables. In this case
4336 @code{DIST_SUBDIRS} needs to be defined manually.
4338 @node Subdirectories with AM_CONDITIONAL
4339 @subsection Subdirectories with @code{AM_CONDITIONAL}
4340 @cindex @code{SUBDIRS} and @code{AM_CONDITIONAL}
4341 @cindex @code{AM_CONDITIONAL} and @code{SUBDIRS}
4343 @c Keep in sync with subcond2.sh
4345 @file{configure} should output the @file{Makefile} for each directory
4346 and define a condition into which @file{opt/} should be built.
4350 AM_CONDITIONAL([COND_OPT], [test "$want_opt" = yes])
4351 AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
4355 Then @code{SUBDIRS} can be defined in the top-level @file{Makefile.am}
4362 SUBDIRS = src $(MAYBE_OPT)
4365 As you can see, running @command{make} will rightly recurse into
4366 @file{src/} and maybe @file{opt/}.
4368 @vindex DIST_SUBDIRS
4369 As you can't see, running @samp{make dist} will recurse into both
4370 @file{src/} and @file{opt/} directories because @samp{make dist}, unlike
4371 @samp{make all}, doesn't use the @code{SUBDIRS} variable. It uses the
4372 @code{DIST_SUBDIRS} variable.
4374 In this case Automake will define @samp{DIST_SUBDIRS = src opt}
4375 automatically because it knows that @code{MAYBE_OPT} can contain
4376 @samp{opt} in some condition.
4378 @node Subdirectories with AC_SUBST
4379 @subsection Subdirectories with @code{AC_SUBST}
4380 @cindex @code{SUBDIRS} and @code{AC_SUBST}
4381 @cindex @code{AC_SUBST} and @code{SUBDIRS}
4383 @c Keep in sync with subcond3.sh
4385 Another possibility is to define @code{MAYBE_OPT} from
4386 @file{./configure} using @code{AC_SUBST}:
4390 if test "$want_opt" = yes; then
4395 AC_SUBST([MAYBE_OPT])
4396 AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
4400 In this case the top-level @file{Makefile.am} should look as follows.
4403 SUBDIRS = src $(MAYBE_OPT)
4404 DIST_SUBDIRS = src opt
4407 The drawback is that since Automake cannot guess what the possible
4408 values of @code{MAYBE_OPT} are, it is necessary to define
4409 @code{DIST_SUBDIRS}.
4411 @node Unconfigured Subdirectories
4412 @subsection Unconfigured Subdirectories
4413 @cindex Subdirectories, configured conditionally
4415 The semantics of @code{DIST_SUBDIRS} are often misunderstood by some
4416 users that try to @emph{configure and build} subdirectories
4417 conditionally. Here by configuring we mean creating the
4418 @file{Makefile} (it might also involve running a nested
4419 @command{configure} script: this is a costly operation that explains
4420 why people want to do it conditionally, but only the @file{Makefile}
4421 is relevant to the discussion).
4423 The above examples all assume that every @file{Makefile} is created,
4424 even in directories that are not going to be built. The simple reason
4425 is that we want @samp{make dist} to distribute even the directories
4426 that are not being built (e.g., platform-dependent code), hence
4427 @file{make dist} must recurse into the subdirectory, hence this
4428 directory must be configured and appear in @code{DIST_SUBDIRS}.
4430 Building packages that do not configure every subdirectory is a tricky
4431 business, and we do not recommend it to the novice as it is easy to
4432 produce an incomplete tarball by mistake. We will not discuss this
4433 topic in depth here, yet for the adventurous here are a few rules to
4438 @item @code{SUBDIRS} should always be a subset of @code{DIST_SUBDIRS}.
4440 It makes little sense to have a directory in @code{SUBDIRS} that
4441 is not in @code{DIST_SUBDIRS}. Think of the former as a way to tell
4442 which directories listed in the latter should be built.
4443 @item Any directory listed in @code{DIST_SUBDIRS} and @code{SUBDIRS}
4446 I.e., the @file{Makefile} must exists or the recursive @command{make}
4447 rules will not be able to process the directory.
4448 @item Any configured directory must be listed in @code{DIST_SUBDIRS}.
4450 So that the cleaning rules remove the generated @file{Makefile}s.
4451 It would be correct to see @code{DIST_SUBDIRS} as a variable that
4452 lists all the directories that have been configured.
4456 In order to prevent recursion in some unconfigured directory you
4457 must therefore ensure that this directory does not appear in
4458 @code{DIST_SUBDIRS} (and @code{SUBDIRS}). For instance, if you define
4459 @code{SUBDIRS} conditionally using @code{AC_SUBST} and do not define
4460 @code{DIST_SUBDIRS} explicitly, it will be default to
4461 @samp{$(SUBDIRS)}; another possibility is to force @code{DIST_SUBDIRS
4464 Of course, directories that are omitted from @code{DIST_SUBDIRS} will
4465 not be distributed unless you make other arrangements for this to
4466 happen (for instance, always running @samp{make dist} in a
4467 configuration where all directories are known to appear in
4468 @code{DIST_SUBDIRS}; or writing a @code{dist-hook} target to
4469 distribute these directories).
4471 @cindex Subdirectories, not distributed
4472 In few packages, unconfigured directories are not even expected to
4473 be distributed. Although these packages do not require the
4474 aforementioned extra arrangements, there is another pitfall. If the
4475 name of a directory appears in @code{SUBDIRS} or @code{DIST_SUBDIRS},
4476 @command{automake} will make sure the directory exists. Consequently
4477 @command{automake} cannot be run on such a distribution when one
4478 directory has been omitted. One way to avoid this check is to use the
4479 @code{AC_SUBST} method to declare conditional directories; since
4480 @command{automake} does not know the values of @code{AC_SUBST}
4481 variables it cannot ensure the corresponding directory exists.
4484 @section An Alternative Approach to Subdirectories
4486 If you've ever read Peter Miller's excellent paper,
4487 @uref{http://miller.emu.id.au/pmiller/books/rmch/,
4488 Recursive Make Considered Harmful}, the preceding sections on the use of
4489 subdirectories will probably come as unwelcome advice. For those who
4490 haven't read the paper, Miller's main thesis is that recursive
4491 @command{make} invocations are both slow and error-prone.
4493 Automake provides sufficient cross-directory support @footnote{We
4494 believe. This work is new and there are probably warts.
4495 @xref{Introduction}, for information on reporting bugs.} to enable you
4496 to write a single @file{Makefile.am} for a complex multi-directory
4500 By default an installable file specified in a subdirectory will have its
4501 directory name stripped before installation. For instance, in this
4502 example, the header file will be installed as
4503 @file{$(includedir)/stdio.h}:
4506 include_HEADERS = inc/stdio.h
4510 @cindex @code{nobase_} prefix
4511 @cindex Path stripping, avoiding
4512 @cindex Avoiding path stripping
4514 However, the @samp{nobase_} prefix can be used to circumvent this path
4515 stripping. In this example, the header file will be installed as
4516 @file{$(includedir)/sys/types.h}:
4519 nobase_include_HEADERS = sys/types.h
4522 @cindex @code{nobase_} and @code{dist_} or @code{nodist_}
4523 @cindex @code{dist_} and @code{nobase_}
4524 @cindex @code{nodist_} and @code{nobase_}
4528 @samp{nobase_} should be specified first when used in conjunction with
4529 either @samp{dist_} or @samp{nodist_} (@pxref{Fine-grained Distribution
4530 Control}). For instance:
4533 nobase_dist_pkgdata_DATA = images/vortex.pgm sounds/whirl.ogg
4536 Finally, note that a variable using the @samp{nobase_} prefix can
4537 often be replaced by several variables, one for each destination
4538 directory (@pxref{Uniform}). For instance, the last example could be
4539 rewritten as follows:
4541 @c Keep in sync with primary-prefix-couples-documented-valid.sh
4543 imagesdir = $(pkgdatadir)/images
4544 soundsdir = $(pkgdatadir)/sounds
4545 dist_images_DATA = images/vortex.pgm
4546 dist_sounds_DATA = sounds/whirl.ogg
4550 This latter syntax makes it possible to change one destination
4551 directory without changing the layout of the source tree.
4553 Currently, @samp{nobase_*_LTLIBRARIES} are the only exception to this
4554 rule, in that there is no particular installation order guarantee for
4555 an otherwise equivalent set of variables without @samp{nobase_} prefix.
4558 @section Nesting Packages
4559 @cindex Nesting packages
4561 @acindex AC_CONFIG_SUBDIRS
4562 @acindex AC_CONFIG_AUX_DIR
4565 In the GNU Build System, packages can be nested to arbitrary depth.
4566 This means that a package can embed other packages with their own
4567 @file{configure}, @file{Makefile}s, etc.
4569 These other packages should just appear as subdirectories of their
4570 parent package. They must be listed in @code{SUBDIRS} like other
4571 ordinary directories. However the subpackage's @file{Makefile}s
4572 should be output by its own @file{configure} script, not by the
4573 parent's @file{configure}. This is achieved using the
4574 @code{AC_CONFIG_SUBDIRS} Autoconf macro (@pxref{Subdirectories,
4575 AC_CONFIG_SUBDIRS, Configuring Other Packages in Subdirectories,
4576 autoconf, The Autoconf Manual}).
4578 Here is an example package for an @code{arm} program that links with
4579 a @code{hand} library that is a nested package in subdirectory
4582 @code{arm}'s @file{configure.ac}:
4585 AC_INIT([arm], [1.0])
4586 AC_CONFIG_AUX_DIR([.])
4589 AC_CONFIG_FILES([Makefile])
4590 # Call hand's ./configure script recursively.
4591 AC_CONFIG_SUBDIRS([hand])
4595 @code{arm}'s @file{Makefile.am}:
4598 # Build the library in the hand subdirectory first.
4601 # Include hand's header when compiling this directory.
4602 AM_CPPFLAGS = -I$(srcdir)/hand
4606 # link with the hand library.
4607 arm_LDADD = hand/libhand.a
4610 Now here is @code{hand}'s @file{hand/configure.ac}:
4613 AC_INIT([hand], [1.2])
4614 AC_CONFIG_AUX_DIR([.])
4619 AC_CONFIG_FILES([Makefile])
4624 and its @file{hand/Makefile.am}:
4627 lib_LIBRARIES = libhand.a
4628 libhand_a_SOURCES = hand.c
4631 When @samp{make dist} is run from the top-level directory it will
4632 create an archive @file{arm-1.0.tar.gz} that contains the @code{arm}
4633 code as well as the @file{hand} subdirectory. This package can be
4634 built and installed like any ordinary package, with the usual
4635 @samp{./configure && make && make install} sequence (the @code{hand}
4636 subpackage will be built and installed by the process).
4638 When @samp{make dist} is run from the hand directory, it will create a
4639 self-contained @file{hand-1.2.tar.gz} archive. So although it appears
4640 to be embedded in another package, it can still be used separately.
4642 The purpose of the @samp{AC_CONFIG_AUX_DIR([.])} instruction is to
4643 force Automake and Autoconf to search for auxiliary scripts in the
4644 current directory. For instance, this means that there will be two
4645 copies of @file{install-sh}: one in the top-level of the @code{arm}
4646 package, and another one in the @file{hand/} subdirectory for the
4647 @code{hand} package.
4649 The historical default is to search for these auxiliary scripts in
4650 the parent directory and the grandparent directory. So if the
4651 @samp{AC_CONFIG_AUX_DIR([.])} line was removed from
4652 @file{hand/configure.ac}, that subpackage would share the auxiliary
4653 script of the @code{arm} package. This may looks like a gain in size
4654 (a few kilobytes), but it is actually a loss of modularity as the
4655 @code{hand} subpackage is no longer self-contained (@samp{make dist}
4656 in the subdirectory will not work anymore).
4658 Packages that do not use Automake need more work to be integrated this
4659 way. @xref{Third-Party Makefiles}.
4662 @chapter Building Programs and Libraries
4664 A large part of Automake's functionality is dedicated to making it easy
4665 to build programs and libraries.
4668 * A Program:: Building a program
4669 * A Library:: Building a library
4670 * A Shared Library:: Building a Libtool library
4671 * Program and Library Variables:: Variables controlling program and
4673 * Default _SOURCES:: Default source files
4674 * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
4675 * Program Variables:: Variables used when building a program
4676 * Yacc and Lex:: Yacc and Lex support
4677 * C++ Support:: Compiling C++ sources
4678 * Objective C Support:: Compiling Objective C sources
4679 * Objective C++ Support:: Compiling Objective C++ sources
4680 * Unified Parallel C Support:: Compiling Unified Parallel C sources
4681 * Assembly Support:: Compiling assembly sources
4682 * Fortran 77 Support:: Compiling Fortran 77 sources
4683 * Fortran 9x Support:: Compiling Fortran 9x sources
4684 * Java Support with gcj:: Compiling Java sources using gcj
4685 * Vala Support:: Compiling Vala sources
4686 * Support for Other Languages:: Compiling other languages
4687 * Dependencies:: Automatic dependency tracking
4688 * EXEEXT:: Support for executable extensions
4693 @section Building a program
4695 In order to build a program, you need to tell Automake which sources
4696 are part of it, and which libraries it should be linked with.
4698 This section also covers conditional compilation of sources or
4699 programs. Most of the comments about these also apply to libraries
4700 (@pxref{A Library}) and libtool libraries (@pxref{A Shared Library}).
4703 * Program Sources:: Defining program sources
4704 * Linking:: Linking with libraries or extra objects
4705 * Conditional Sources:: Handling conditional sources
4706 * Conditional Programs:: Building a program conditionally
4709 @node Program Sources
4710 @subsection Defining program sources
4712 @cindex @code{PROGRAMS}, @code{bindir}
4714 @vindex bin_PROGRAMS
4715 @vindex sbin_PROGRAMS
4716 @vindex libexec_PROGRAMS
4717 @vindex pkglibexec_PROGRAMS
4718 @vindex noinst_PROGRAMS
4719 @vindex check_PROGRAMS
4721 In a directory containing source that gets built into a program (as
4722 opposed to a library or a script), the @code{PROGRAMS} primary is used.
4723 Programs can be installed in @code{bindir}, @code{sbindir},
4724 @code{libexecdir}, @code{pkglibexecdir}, or not at all
4725 (@code{noinst_}). They can also be built only for @samp{make check}, in
4726 which case the prefix is @samp{check_}.
4731 bin_PROGRAMS = hello
4734 In this simple case, the resulting @file{Makefile.in} will contain code
4735 to generate a program named @code{hello}.
4737 Associated with each program are several assisting variables that are
4738 named after the program. These variables are all optional, and have
4739 reasonable defaults. Each variable, its use, and default is spelled out
4740 below; we use the ``hello'' example throughout.
4742 The variable @code{hello_SOURCES} is used to specify which source files
4743 get built into an executable:
4746 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
4749 This causes each mentioned @file{.c} file to be compiled into the
4750 corresponding @file{.o}. Then all are linked to produce @file{hello}.
4752 @cindex @code{_SOURCES} primary, defined
4753 @cindex @code{SOURCES} primary, defined
4754 @cindex Primary variable, @code{SOURCES}
4757 If @code{hello_SOURCES} is not specified, then it defaults to the single
4758 file @file{hello.c} (@pxref{Default _SOURCES}).
4762 Multiple programs can be built in a single directory. Multiple programs
4763 can share a single source file, which must be listed in each
4764 @code{_SOURCES} definition.
4766 @cindex Header files in @code{_SOURCES}
4767 @cindex @code{_SOURCES} and header files
4769 Header files listed in a @code{_SOURCES} definition will be included in
4770 the distribution but otherwise ignored. In case it isn't obvious, you
4771 should not include the header file generated by @file{configure} in a
4772 @code{_SOURCES} variable; this file should not be distributed. Lex
4773 (@file{.l}) and Yacc (@file{.y}) files can also be listed; see @ref{Yacc
4778 @subsection Linking the program
4780 If you need to link against libraries that are not found by
4781 @command{configure}, you can use @code{LDADD} to do so. This variable is
4782 used to specify additional objects or libraries to link with; it is
4783 inappropriate for specifying specific linker flags, you should use
4784 @code{AM_LDFLAGS} for this purpose.
4788 @cindex @code{prog_LDADD}, defined
4790 Sometimes, multiple programs are built in one directory but do not share
4791 the same link-time requirements. In this case, you can use the
4792 @code{@var{prog}_LDADD} variable (where @var{prog} is the name of the
4793 program as it appears in some @code{_PROGRAMS} variable, and usually
4794 written in lowercase) to override @code{LDADD}. If this variable exists
4795 for a given program, then that program is not linked using @code{LDADD}.
4798 For instance, in GNU cpio, @code{pax}, @code{cpio} and @code{mt} are
4799 linked against the library @file{libcpio.a}. However, @code{rmt} is
4800 built in the same directory, and has no such link requirement. Also,
4801 @code{mt} and @code{rmt} are only built on certain architectures. Here
4802 is what cpio's @file{src/Makefile.am} looks like (abridged):
4805 bin_PROGRAMS = cpio pax $(MT)
4806 libexec_PROGRAMS = $(RMT)
4807 EXTRA_PROGRAMS = mt rmt
4809 LDADD = ../lib/libcpio.a $(INTLLIBS)
4812 cpio_SOURCES = @dots{}
4813 pax_SOURCES = @dots{}
4814 mt_SOURCES = @dots{}
4815 rmt_SOURCES = @dots{}
4818 @cindex @code{_LDFLAGS}, defined
4819 @vindex maude_LDFLAGS
4820 @code{@var{prog}_LDADD} is inappropriate for passing program-specific
4821 linker flags (except for @option{-l}, @option{-L}, @option{-dlopen} and
4822 @option{-dlpreopen}). So, use the @code{@var{prog}_LDFLAGS} variable for
4825 @cindex @code{_DEPENDENCIES}, defined
4826 @vindex maude_DEPENDENCIES
4827 @vindex EXTRA_maude_DEPENDENCIES
4828 It is also occasionally useful to have a program depend on some other
4829 target that is not actually part of that program. This can be done
4830 using either the @code{@var{prog}_DEPENDENCIES} or the
4831 @code{EXTRA_@var{prog}_DEPENDENCIES} variable. Each program depends on
4832 the contents both variables, but no further interpretation is done.
4834 Since these dependencies are associated to the link rule used to
4835 create the programs they should normally list files used by the link
4836 command. That is @file{*.$(OBJEXT)}, @file{*.a}, or @file{*.la}
4837 files. In rare cases you may need to add other kinds of files such as
4838 linker scripts, but @emph{listing a source file in
4839 @code{_DEPENDENCIES} is wrong}. If some source file needs to be built
4840 before all the components of a program are built, consider using the
4841 @code{BUILT_SOURCES} variable instead (@pxref{Sources}).
4843 If @code{@var{prog}_DEPENDENCIES} is not supplied, it is computed by
4844 Automake. The automatically-assigned value is the contents of
4845 @code{@var{prog}_LDADD}, with most configure substitutions, @option{-l},
4846 @option{-L}, @option{-dlopen} and @option{-dlpreopen} options removed. The
4847 configure substitutions that are left in are only @samp{$(LIBOBJS)} and
4848 @samp{$(ALLOCA)}; these are left because it is known that they will not
4849 cause an invalid value for @code{@var{prog}_DEPENDENCIES} to be
4852 @ref{Conditional Sources} shows a situation where @code{_DEPENDENCIES}
4855 The @code{EXTRA_@var{prog}_DEPENDENCIES} may be useful for cases where
4856 you merely want to augment the @command{automake}-generated
4857 @code{@var{prog}_DEPENDENCIES} rather than replacing it.
4859 @cindex @code{LDADD} and @option{-l}
4860 @cindex @option{-l} and @code{LDADD}
4861 We recommend that you avoid using @option{-l} options in @code{LDADD}
4862 or @code{@var{prog}_LDADD} when referring to libraries built by your
4863 package. Instead, write the file name of the library explicitly as in
4864 the above @code{cpio} example. Use @option{-l} only to list
4865 third-party libraries. If you follow this rule, the default value of
4866 @code{@var{prog}_DEPENDENCIES} will list all your local libraries and
4867 omit the other ones.
4870 @node Conditional Sources
4871 @subsection Conditional compilation of sources
4873 You can't put a configure substitution (e.g., @samp{@@FOO@@} or
4874 @samp{$(FOO)} where @code{FOO} is defined via @code{AC_SUBST}) into a
4875 @code{_SOURCES} variable. The reason for this is a bit hard to
4876 explain, but suffice to say that it simply won't work. Automake will
4877 give an error if you try to do this.
4879 Fortunately there are two other ways to achieve the same result. One is
4880 to use configure substitutions in @code{_LDADD} variables, the other is
4881 to use an Automake conditional.
4883 @subsubheading Conditional Compilation using @code{_LDADD} Substitutions
4885 @cindex @code{EXTRA_prog_SOURCES}, defined
4887 Automake must know all the source files that could possibly go into a
4888 program, even if not all the files are built in every circumstance. Any
4889 files that are only conditionally built should be listed in the
4890 appropriate @code{EXTRA_} variable. For instance, if
4891 @file{hello-linux.c} or @file{hello-generic.c} were conditionally included
4892 in @code{hello}, the @file{Makefile.am} would contain:
4895 bin_PROGRAMS = hello
4896 hello_SOURCES = hello-common.c
4897 EXTRA_hello_SOURCES = hello-linux.c hello-generic.c
4898 hello_LDADD = $(HELLO_SYSTEM)
4899 hello_DEPENDENCIES = $(HELLO_SYSTEM)
4903 You can then setup the @samp{$(HELLO_SYSTEM)} substitution from
4904 @file{configure.ac}:
4909 *linux*) HELLO_SYSTEM='hello-linux.$(OBJEXT)' ;;
4910 *) HELLO_SYSTEM='hello-generic.$(OBJEXT)' ;;
4912 AC_SUBST([HELLO_SYSTEM])
4916 In this case, the variable @code{HELLO_SYSTEM} should be replaced by
4917 either @file{hello-linux.o} or @file{hello-generic.o}, and added to
4918 both @code{hello_DEPENDENCIES} and @code{hello_LDADD} in order to be
4919 built and linked in.
4921 @subsubheading Conditional Compilation using Automake Conditionals
4923 An often simpler way to compile source files conditionally is to use
4924 Automake conditionals. For instance, you could use this
4925 @file{Makefile.am} construct to build the same @file{hello} example:
4928 bin_PROGRAMS = hello
4930 hello_SOURCES = hello-linux.c hello-common.c
4932 hello_SOURCES = hello-generic.c hello-common.c
4936 In this case, @file{configure.ac} should setup the @code{LINUX}
4937 conditional using @code{AM_CONDITIONAL} (@pxref{Conditionals}).
4939 When using conditionals like this you don't need to use the
4940 @code{EXTRA_} variable, because Automake will examine the contents of
4941 each variable to construct the complete list of source files.
4943 If your program uses a lot of files, you will probably prefer a
4944 conditional @samp{+=}.
4947 bin_PROGRAMS = hello
4948 hello_SOURCES = hello-common.c
4950 hello_SOURCES += hello-linux.c
4952 hello_SOURCES += hello-generic.c
4956 @node Conditional Programs
4957 @subsection Conditional compilation of programs
4958 @cindex Conditional programs
4959 @cindex Programs, conditional
4961 Sometimes it is useful to determine the programs that are to be built
4962 at configure time. For instance, GNU @code{cpio} only builds
4963 @code{mt} and @code{rmt} under special circumstances. The means to
4964 achieve conditional compilation of programs are the same you can use
4965 to compile source files conditionally: substitutions or conditionals.
4967 @subsubheading Conditional Programs using @command{configure} Substitutions
4969 @vindex EXTRA_PROGRAMS
4970 @cindex @code{EXTRA_PROGRAMS}, defined
4971 In this case, you must notify Automake of all the programs that can
4972 possibly be built, but at the same time cause the generated
4973 @file{Makefile.in} to use the programs specified by @command{configure}.
4974 This is done by having @command{configure} substitute values into each
4975 @code{_PROGRAMS} definition, while listing all optionally built programs
4976 in @code{EXTRA_PROGRAMS}.
4979 bin_PROGRAMS = cpio pax $(MT)
4980 libexec_PROGRAMS = $(RMT)
4981 EXTRA_PROGRAMS = mt rmt
4984 As explained in @ref{EXEEXT}, Automake will rewrite
4985 @code{bin_PROGRAMS}, @code{libexec_PROGRAMS}, and
4986 @code{EXTRA_PROGRAMS}, appending @samp{$(EXEEXT)} to each binary.
4987 Obviously it cannot rewrite values obtained at run-time through
4988 @command{configure} substitutions, therefore you should take care of
4989 appending @samp{$(EXEEXT)} yourself, as in @samp{AC_SUBST([MT],
4990 ['mt$@{EXEEXT@}'])}.
4992 @subsubheading Conditional Programs using Automake Conditionals
4994 You can also use Automake conditionals (@pxref{Conditionals}) to
4995 select programs to be built. In this case you don't have to worry
4996 about @samp{$(EXEEXT)} or @code{EXTRA_PROGRAMS}.
4998 @c Keep in sync with exeext.sh
5000 bin_PROGRAMS = cpio pax
5005 libexec_PROGRAMS = rmt
5011 @section Building a library
5013 @cindex @code{_LIBRARIES} primary, defined
5014 @cindex @code{LIBRARIES} primary, defined
5015 @cindex Primary variable, @code{LIBRARIES}
5018 @vindex lib_LIBRARIES
5019 @vindex pkglib_LIBRARIES
5020 @vindex noinst_LIBRARIES
5022 Building a library is much like building a program. In this case, the
5023 name of the primary is @code{LIBRARIES}. Libraries can be installed in
5024 @code{libdir} or @code{pkglibdir}.
5026 @xref{A Shared Library}, for information on how to build shared
5027 libraries using libtool and the @code{LTLIBRARIES} primary.
5029 Each @code{_LIBRARIES} variable is a list of the libraries to be built.
5030 For instance, to create a library named @file{libcpio.a}, but not install
5031 it, you would write:
5034 noinst_LIBRARIES = libcpio.a
5035 libcpio_a_SOURCES = @dots{}
5038 The sources that go into a library are determined exactly as they are
5039 for programs, via the @code{_SOURCES} variables. Note that the library
5040 name is canonicalized (@pxref{Canonicalization}), so the @code{_SOURCES}
5041 variable corresponding to @file{libcpio.a} is @samp{libcpio_a_SOURCES},
5042 not @samp{libcpio.a_SOURCES}.
5044 @vindex maude_LIBADD
5045 Extra objects can be added to a library using the
5046 @code{@var{library}_LIBADD} variable. This should be used for objects
5047 determined by @command{configure}. Again from @code{cpio}:
5049 @c Keep in sync with pr401c.sh
5051 libcpio_a_LIBADD = $(LIBOBJS) $(ALLOCA)
5054 In addition, sources for extra objects that will not exist until
5055 configure-time must be added to the @code{BUILT_SOURCES} variable
5058 Building a static library is done by compiling all object files, then
5059 by invoking @samp{$(AR) $(ARFLAGS)} followed by the name of the
5060 library and the list of objects, and finally by calling
5061 @samp{$(RANLIB)} on that library. You should call
5062 @code{AC_PROG_RANLIB} from your @file{configure.ac} to define
5063 @code{RANLIB} (Automake will complain otherwise). You should also
5064 call @code{AM_PROG_AR} to define @code{AR}, in order to support unusual
5065 archivers such as Microsoft lib. @code{ARFLAGS} will default to
5066 @code{cru}; you can override this variable by setting it in your
5067 @file{Makefile.am} or by @code{AC_SUBST}ing it from your
5068 @file{configure.ac}. You can override the @code{AR} variable by
5069 defining a per-library @code{maude_AR} variable (@pxref{Program and
5070 Library Variables}).
5072 @cindex Empty libraries
5073 Be careful when selecting library components conditionally. Because
5074 building an empty library is not portable, you should ensure that any
5075 library always contains at least one object.
5077 To use a static library when building a program, add it to
5078 @code{LDADD} for this program. In the following example, the program
5079 @file{cpio} is statically linked with the library @file{libcpio.a}.
5082 noinst_LIBRARIES = libcpio.a
5083 libcpio_a_SOURCES = @dots{}
5086 cpio_SOURCES = cpio.c @dots{}
5087 cpio_LDADD = libcpio.a
5091 @node A Shared Library
5092 @section Building a Shared Library
5094 @cindex Shared libraries, support for
5096 Building shared libraries portably is a relatively complex matter.
5097 For this reason, GNU Libtool (@pxref{Top, , Introduction, libtool, The
5098 Libtool Manual}) was created to help build shared libraries in a
5099 platform-independent way.
5102 * Libtool Concept:: Introducing Libtool
5103 * Libtool Libraries:: Declaring Libtool Libraries
5104 * Conditional Libtool Libraries:: Building Libtool Libraries Conditionally
5105 * Conditional Libtool Sources:: Choosing Library Sources Conditionally
5106 * Libtool Convenience Libraries:: Building Convenience Libtool Libraries
5107 * Libtool Modules:: Building Libtool Modules
5108 * Libtool Flags:: Using _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS
5109 * LTLIBOBJS:: Using $(LTLIBOBJS) and $(LTALLOCA)
5110 * Libtool Issues:: Common Issues Related to Libtool's Use
5113 @node Libtool Concept
5114 @subsection The Libtool Concept
5116 @cindex @command{libtool}, introduction
5117 @cindex libtool library, definition
5118 @cindex suffix @file{.la}, defined
5119 @cindex @file{.la} suffix, defined
5121 Libtool abstracts shared and static libraries into a unified concept
5122 henceforth called @dfn{libtool libraries}. Libtool libraries are
5123 files using the @file{.la} suffix, and can designate a static library,
5124 a shared library, or maybe both. Their exact nature cannot be
5125 determined until @file{./configure} is run: not all platforms support
5126 all kinds of libraries, and users can explicitly select which
5127 libraries should be built. (However the package's maintainers can
5128 tune the default, @pxref{AC_PROG_LIBTOOL, , The @code{AC_PROG_LIBTOOL}
5129 macro, libtool, The Libtool Manual}.)
5131 @cindex suffix @file{.lo}, defined
5132 Because object files for shared and static libraries must be compiled
5133 differently, libtool is also used during compilation. Object files
5134 built by libtool are called @dfn{libtool objects}: these are files
5135 using the @file{.lo} suffix. Libtool libraries are built from these
5138 You should not assume anything about the structure of @file{.la} or
5139 @file{.lo} files and how libtool constructs them: this is libtool's
5140 concern, and the last thing one wants is to learn about libtool's
5141 guts. However the existence of these files matters, because they are
5142 used as targets and dependencies in @file{Makefile}s rules when
5143 building libtool libraries. There are situations where you may have
5144 to refer to these, for instance when expressing dependencies for
5145 building source files conditionally (@pxref{Conditional Libtool
5148 @cindex @file{libltdl}, introduction
5150 People considering writing a plug-in system, with dynamically loaded
5151 modules, should look into @file{libltdl}: libtool's dlopening library
5152 (@pxref{Using libltdl, , Using libltdl, libtool, The Libtool Manual}).
5153 This offers a portable dlopening facility to load libtool libraries
5154 dynamically, and can also achieve static linking where unavoidable.
5156 Before we discuss how to use libtool with Automake in details, it
5157 should be noted that the libtool manual also has a section about how
5158 to use Automake with libtool (@pxref{Using Automake, , Using Automake
5159 with Libtool, libtool, The Libtool Manual}).
5161 @node Libtool Libraries
5162 @subsection Building Libtool Libraries
5164 @cindex @code{_LTLIBRARIES} primary, defined
5165 @cindex @code{LTLIBRARIES} primary, defined
5166 @cindex Primary variable, @code{LTLIBRARIES}
5167 @cindex Example of shared libraries
5168 @vindex lib_LTLIBRARIES
5169 @vindex pkglib_LTLIBRARIES
5170 @vindex _LTLIBRARIES
5172 Automake uses libtool to build libraries declared with the
5173 @code{LTLIBRARIES} primary. Each @code{_LTLIBRARIES} variable is a
5174 list of libtool libraries to build. For instance, to create a libtool
5175 library named @file{libgettext.la}, and install it in @code{libdir},
5179 lib_LTLIBRARIES = libgettext.la
5180 libgettext_la_SOURCES = gettext.c gettext.h @dots{}
5183 Automake predefines the variable @code{pkglibdir}, so you can use
5184 @code{pkglib_LTLIBRARIES} to install libraries in
5185 @samp{$(libdir)/@@PACKAGE@@/}.
5187 If @file{gettext.h} is a public header file that needs to be installed
5188 in order for people to use the library, it should be declared using a
5189 @code{_HEADERS} variable, not in @code{libgettext_la_SOURCES}.
5190 Headers listed in the latter should be internal headers that are not
5191 part of the public interface.
5194 lib_LTLIBRARIES = libgettext.la
5195 libgettext_la_SOURCES = gettext.c @dots{}
5196 include_HEADERS = gettext.h @dots{}
5199 A package can build and install such a library along with other
5200 programs that use it. This dependency should be specified using
5201 @code{LDADD}. The following example builds a program named
5202 @file{hello} that is linked with @file{libgettext.la}.
5205 lib_LTLIBRARIES = libgettext.la
5206 libgettext_la_SOURCES = gettext.c @dots{}
5208 bin_PROGRAMS = hello
5209 hello_SOURCES = hello.c @dots{}
5210 hello_LDADD = libgettext.la
5214 Whether @file{hello} is statically or dynamically linked with
5215 @file{libgettext.la} is not yet known: this will depend on the
5216 configuration of libtool and the capabilities of the host.
5219 @node Conditional Libtool Libraries
5220 @subsection Building Libtool Libraries Conditionally
5221 @cindex libtool libraries, conditional
5222 @cindex conditional libtool libraries
5224 Like conditional programs (@pxref{Conditional Programs}), there are
5225 two main ways to build conditional libraries: using Automake
5226 conditionals or using Autoconf @code{AC_SUBST}itutions.
5228 The important implementation detail you have to be aware of is that
5229 the place where a library will be installed matters to libtool: it
5230 needs to be indicated @emph{at link-time} using the @option{-rpath}
5233 For libraries whose destination directory is known when Automake runs,
5234 Automake will automatically supply the appropriate @option{-rpath}
5235 option to libtool. This is the case for libraries listed explicitly in
5236 some installable @code{_LTLIBRARIES} variables such as
5237 @code{lib_LTLIBRARIES}.
5239 However, for libraries determined at configure time (and thus
5240 mentioned in @code{EXTRA_LTLIBRARIES}), Automake does not know the
5241 final installation directory. For such libraries you must add the
5242 @option{-rpath} option to the appropriate @code{_LDFLAGS} variable by
5245 The examples below illustrate the differences between these two methods.
5247 Here is an example where @code{WANTEDLIBS} is an @code{AC_SUBST}ed
5248 variable set at @file{./configure}-time to either @file{libfoo.la},
5249 @file{libbar.la}, both, or none. Although @samp{$(WANTEDLIBS)}
5250 appears in the @code{lib_LTLIBRARIES}, Automake cannot guess it
5251 relates to @file{libfoo.la} or @file{libbar.la} at the time it creates
5252 the link rule for these two libraries. Therefore the @option{-rpath}
5253 argument must be explicitly supplied.
5255 @c Keep in sync with ltcond.sh
5257 EXTRA_LTLIBRARIES = libfoo.la libbar.la
5258 lib_LTLIBRARIES = $(WANTEDLIBS)
5259 libfoo_la_SOURCES = foo.c @dots{}
5260 libfoo_la_LDFLAGS = -rpath '$(libdir)'
5261 libbar_la_SOURCES = bar.c @dots{}
5262 libbar_la_LDFLAGS = -rpath '$(libdir)'
5265 Here is how the same @file{Makefile.am} would look using Automake
5266 conditionals named @code{WANT_LIBFOO} and @code{WANT_LIBBAR}. Now
5267 Automake is able to compute the @option{-rpath} setting itself, because
5268 it's clear that both libraries will end up in @samp{$(libdir)} if they
5271 @c Keep in sync with ltcond.sh
5275 lib_LTLIBRARIES += libfoo.la
5278 lib_LTLIBRARIES += libbar.la
5280 libfoo_la_SOURCES = foo.c @dots{}
5281 libbar_la_SOURCES = bar.c @dots{}
5284 @node Conditional Libtool Sources
5285 @subsection Libtool Libraries with Conditional Sources
5287 Conditional compilation of sources in a library can be achieved in the
5288 same way as conditional compilation of sources in a program
5289 (@pxref{Conditional Sources}). The only difference is that
5290 @code{_LIBADD} should be used instead of @code{_LDADD} and that it
5291 should mention libtool objects (@file{.lo} files).
5293 So, to mimic the @file{hello} example from @ref{Conditional Sources},
5294 we could build a @file{libhello.la} library using either
5295 @file{hello-linux.c} or @file{hello-generic.c} with the following
5298 @c Keep in sync with ltcond2.sh
5300 lib_LTLIBRARIES = libhello.la
5301 libhello_la_SOURCES = hello-common.c
5302 EXTRA_libhello_la_SOURCES = hello-linux.c hello-generic.c
5303 libhello_la_LIBADD = $(HELLO_SYSTEM)
5304 libhello_la_DEPENDENCIES = $(HELLO_SYSTEM)
5308 And make sure @command{configure} defines @code{HELLO_SYSTEM} as
5309 either @file{hello-linux.lo} or @file{hello-@-generic.lo}.
5311 Or we could simply use an Automake conditional as follows.
5313 @c Keep in sync with ltcond2.sh
5315 lib_LTLIBRARIES = libhello.la
5316 libhello_la_SOURCES = hello-common.c
5318 libhello_la_SOURCES += hello-linux.c
5320 libhello_la_SOURCES += hello-generic.c
5324 @node Libtool Convenience Libraries
5325 @subsection Libtool Convenience Libraries
5326 @cindex convenience libraries, libtool
5327 @cindex libtool convenience libraries
5328 @vindex noinst_LTLIBRARIES
5329 @vindex check_LTLIBRARIES
5331 Sometimes you want to build libtool libraries that should not be
5332 installed. These are called @dfn{libtool convenience libraries} and
5333 are typically used to encapsulate many sublibraries, later gathered
5334 into one big installed library.
5336 Libtool convenience libraries are declared by directory-less variables
5337 such as @code{noinst_LTLIBRARIES}, @code{check_LTLIBRARIES}, or even
5338 @code{EXTRA_LTLIBRARIES}. Unlike installed libtool libraries they do
5339 not need an @option{-rpath} flag at link time (actually this is the only
5342 Convenience libraries listed in @code{noinst_LTLIBRARIES} are always
5343 built. Those listed in @code{check_LTLIBRARIES} are built only upon
5344 @samp{make check}. Finally, libraries listed in
5345 @code{EXTRA_LTLIBRARIES} are never built explicitly: Automake outputs
5346 rules to build them, but if the library does not appear as a Makefile
5347 dependency anywhere it won't be built (this is why
5348 @code{EXTRA_LTLIBRARIES} is used for conditional compilation).
5350 Here is a sample setup merging libtool convenience libraries from
5351 subdirectories into one main @file{libtop.la} library.
5353 @c Keep in sync with ltconv.sh
5355 # -- Top-level Makefile.am --
5356 SUBDIRS = sub1 sub2 @dots{}
5357 lib_LTLIBRARIES = libtop.la
5359 libtop_la_LIBADD = \
5364 # -- sub1/Makefile.am --
5365 noinst_LTLIBRARIES = libsub1.la
5366 libsub1_la_SOURCES = @dots{}
5368 # -- sub2/Makefile.am --
5369 # showing nested convenience libraries
5370 SUBDIRS = sub2.1 sub2.2 @dots{}
5371 noinst_LTLIBRARIES = libsub2.la
5372 libsub2_la_SOURCES =
5373 libsub2_la_LIBADD = \
5379 When using such setup, beware that @command{automake} will assume
5380 @file{libtop.la} is to be linked with the C linker. This is because
5381 @code{libtop_la_SOURCES} is empty, so @command{automake} picks C as
5382 default language. If @code{libtop_la_SOURCES} was not empty,
5383 @command{automake} would select the linker as explained in @ref{How
5384 the Linker is Chosen}.
5386 If one of the sublibraries contains non-C source, it is important that
5387 the appropriate linker be chosen. One way to achieve this is to
5388 pretend that there is such a non-C file among the sources of the
5389 library, thus forcing @command{automake} to select the appropriate
5390 linker. Here is the top-level @file{Makefile} of our example updated
5391 to force C++ linking.
5394 SUBDIRS = sub1 sub2 @dots{}
5395 lib_LTLIBRARIES = libtop.la
5397 # Dummy C++ source to cause C++ linking.
5398 nodist_EXTRA_libtop_la_SOURCES = dummy.cxx
5399 libtop_la_LIBADD = \
5405 @samp{EXTRA_*_SOURCES} variables are used to keep track of source
5406 files that might be compiled (this is mostly useful when doing
5407 conditional compilation using @code{AC_SUBST}, @pxref{Conditional
5408 Libtool Sources}), and the @code{nodist_} prefix means the listed
5409 sources are not to be distributed (@pxref{Program and Library
5410 Variables}). In effect the file @file{dummy.cxx} does not need to
5411 exist in the source tree. Of course if you have some real source file
5412 to list in @code{libtop_la_SOURCES} there is no point in cheating with
5413 @code{nodist_EXTRA_libtop_la_SOURCES}.
5416 @node Libtool Modules
5417 @subsection Libtool Modules
5418 @cindex modules, libtool
5419 @cindex libtool modules
5420 @cindex @option{-module}, libtool
5422 These are libtool libraries meant to be dlopened. They are
5423 indicated to libtool by passing @option{-module} at link-time.
5426 pkglib_LTLIBRARIES = mymodule.la
5427 mymodule_la_SOURCES = doit.c
5428 mymodule_la_LDFLAGS = -module
5431 Ordinarily, Automake requires that a library's name start with
5432 @code{lib}. However, when building a dynamically loadable module you
5433 might wish to use a "nonstandard" name. Automake will not complain
5434 about such nonstandard names if it knows the library being built is a
5435 libtool module, i.e., if @option{-module} explicitly appears in the
5436 library's @code{_LDFLAGS} variable (or in the common @code{AM_LDFLAGS}
5437 variable when no per-library @code{_LDFLAGS} variable is defined).
5439 As always, @code{AC_SUBST} variables are black boxes to Automake since
5440 their values are not yet known when @command{automake} is run.
5441 Therefore if @option{-module} is set via such a variable, Automake
5442 cannot notice it and will proceed as if the library was an ordinary
5443 libtool library, with strict naming.
5445 If @code{mymodule_la_SOURCES} is not specified, then it defaults to
5446 the single file @file{mymodule.c} (@pxref{Default _SOURCES}).
5449 @subsection @code{_LIBADD}, @code{_LDFLAGS}, and @code{_LIBTOOLFLAGS}
5450 @cindex @code{_LIBADD}, libtool
5451 @cindex @code{_LDFLAGS}, libtool
5452 @cindex @code{_LIBTOOLFLAGS}, libtool
5453 @vindex AM_LIBTOOLFLAGS
5454 @vindex LIBTOOLFLAGS
5455 @vindex maude_LIBTOOLFLAGS
5457 As shown in previous sections, the @samp{@var{library}_LIBADD}
5458 variable should be used to list extra libtool objects (@file{.lo}
5459 files) or libtool libraries (@file{.la}) to add to @var{library}.
5461 The @samp{@var{library}_LDFLAGS} variable is the place to list
5462 additional libtool linking flags, such as @option{-version-info},
5463 @option{-static}, and a lot more. @xref{Link mode, , Link mode,
5464 libtool, The Libtool Manual}.
5466 The @command{libtool} command has two kinds of options: mode-specific
5467 options and generic options. Mode-specific options such as the
5468 aforementioned linking flags should be lumped with the other flags
5469 passed to the tool invoked by @command{libtool} (hence the use of
5470 @samp{@var{library}_LDFLAGS} for libtool linking flags). Generic
5471 options include @option{--tag=@var{tag}} and @option{--silent}
5472 (@pxref{Invoking libtool, , Invoking @command{libtool}, libtool, The
5473 Libtool Manual} for more options) should appear before the mode
5474 selection on the command line; in @file{Makefile.am}s they should
5475 be listed in the @samp{@var{library}_LIBTOOLFLAGS} variable.
5477 If @samp{@var{library}_LIBTOOLFLAGS} is not defined, then the variable
5478 @code{AM_LIBTOOLFLAGS} is used instead.
5480 These flags are passed to libtool after the @option{--tag=@var{tag}}
5481 option computed by Automake (if any), so
5482 @samp{@var{library}_LIBTOOLFLAGS} (or @code{AM_LIBTOOLFLAGS}) is a
5483 good place to override or supplement the @option{--tag=@var{tag}}
5486 The libtool rules also use a @code{LIBTOOLFLAGS} variable that should
5487 not be set in @file{Makefile.am}: this is a user variable (@pxref{Flag
5488 Variables Ordering}. It allows users to run @samp{make
5489 LIBTOOLFLAGS=--silent}, for instance. Note that the verbosity of
5490 @command{libtool} can also be influenced with the Automake
5491 @option{silent-rules} option (@pxref{Options}).
5494 @node LTLIBOBJS, Libtool Issues, Libtool Flags, A Shared Library
5495 @subsection @code{LTLIBOBJS} and @code{LTALLOCA}
5496 @cindex @code{LTLIBOBJS}, special handling
5497 @cindex @code{LIBOBJS}, and Libtool
5498 @cindex @code{LTALLOCA}, special handling
5499 @cindex @code{ALLOCA}, and Libtool
5506 Where an ordinary library might include @samp{$(LIBOBJS)} or
5507 @samp{$(ALLOCA)} (@pxref{LIBOBJS}), a libtool library must use
5508 @samp{$(LTLIBOBJS)} or @samp{$(LTALLOCA)}. This is required because
5509 the object files that libtool operates on do not necessarily end in
5512 Nowadays, the computation of @code{LTLIBOBJS} from @code{LIBOBJS} is
5513 performed automatically by Autoconf (@pxref{AC_LIBOBJ vs LIBOBJS, ,
5514 @code{AC_LIBOBJ} vs.@: @code{LIBOBJS}, autoconf, The Autoconf Manual}).
5516 @node Libtool Issues
5517 @subsection Common Issues Related to Libtool's Use
5520 * Error required file ltmain.sh not found:: The need to run libtoolize
5521 * Objects created both with libtool and without:: Avoid a specific build race
5524 @node Error required file ltmain.sh not found
5525 @subsubsection Error: @samp{required file `./ltmain.sh' not found}
5526 @cindex @file{ltmain.sh} not found
5527 @cindex @command{libtoolize}, no longer run by @command{automake}
5528 @cindex @command{libtoolize} and @command{autoreconf}
5529 @cindex @command{autoreconf} and @command{libtoolize}
5530 @cindex @file{bootstrap.sh} and @command{autoreconf}
5531 @cindex @file{autogen.sh} and @command{autoreconf}
5533 Libtool comes with a tool called @command{libtoolize} that will
5534 install libtool's supporting files into a package. Running this
5535 command will install @file{ltmain.sh}. You should execute it before
5536 @command{aclocal} and @command{automake}.
5538 People upgrading old packages to newer autotools are likely to face
5539 this issue because older Automake versions used to call
5540 @command{libtoolize}. Therefore old build scripts do not call
5541 @command{libtoolize}.
5543 Since Automake 1.6, it has been decided that running
5544 @command{libtoolize} was none of Automake's business. Instead, that
5545 functionality has been moved into the @command{autoreconf} command
5546 (@pxref{autoreconf Invocation, , Using @command{autoreconf}, autoconf,
5547 The Autoconf Manual}). If you do not want to remember what to run and
5548 when, just learn the @command{autoreconf} command. Hopefully,
5549 replacing existing @file{bootstrap.sh} or @file{autogen.sh} scripts by
5550 a call to @command{autoreconf} should also free you from any similar
5551 incompatible change in the future.
5553 @node Objects created both with libtool and without
5554 @subsubsection Objects @samp{created with both libtool and without}
5556 Sometimes, the same source file is used both to build a libtool
5557 library and to build another non-libtool target (be it a program or
5560 Let's consider the following @file{Makefile.am}.
5564 prog_SOURCES = prog.c foo.c @dots{}
5566 lib_LTLIBRARIES = libfoo.la
5567 libfoo_la_SOURCES = foo.c @dots{}
5571 (In this trivial case the issue could be avoided by linking
5572 @file{libfoo.la} with @file{prog} instead of listing @file{foo.c} in
5573 @code{prog_SOURCES}. But let's assume we really want to keep
5574 @file{prog} and @file{libfoo.la} separate.)
5576 Technically, it means that we should build @file{foo.$(OBJEXT)} for
5577 @file{prog}, and @file{foo.lo} for @file{libfoo.la}. The problem is
5578 that in the course of creating @file{foo.lo}, libtool may erase (or
5579 replace) @file{foo.$(OBJEXT)}, and this cannot be avoided.
5581 Therefore, when Automake detects this situation it will complain
5582 with a message such as
5584 object `foo.$(OBJEXT)' created both with libtool and without
5587 A workaround for this issue is to ensure that these two objects get
5588 different basenames. As explained in @ref{Renamed Objects}, this
5589 happens automatically when per-targets flags are used.
5593 prog_SOURCES = prog.c foo.c @dots{}
5594 prog_CFLAGS = $(AM_CFLAGS)
5596 lib_LTLIBRARIES = libfoo.la
5597 libfoo_la_SOURCES = foo.c @dots{}
5601 Adding @samp{prog_CFLAGS = $(AM_CFLAGS)} is almost a no-op, because
5602 when the @code{prog_CFLAGS} is defined, it is used instead of
5603 @code{AM_CFLAGS}. However as a side effect it will cause
5604 @file{prog.c} and @file{foo.c} to be compiled as
5605 @file{prog-prog.$(OBJEXT)} and @file{prog-foo.$(OBJEXT)}, which solves
5608 @node Program and Library Variables
5609 @section Program and Library Variables
5611 Associated with each program is a collection of variables that can be
5612 used to modify how that program is built. There is a similar list of
5613 such variables for each library. The canonical name of the program (or
5614 library) is used as a base for naming these variables.
5616 In the list below, we use the name ``maude'' to refer to the program or
5617 library. In your @file{Makefile.am} you would replace this with the
5618 canonical name of your program. This list also refers to ``maude'' as a
5619 program, but in general the same rules apply for both static and dynamic
5620 libraries; the documentation below notes situations where programs and
5625 This variable, if it exists, lists all the source files that are
5626 compiled to build the program. These files are added to the
5627 distribution by default. When building the program, Automake will cause
5628 each source file to be compiled to a single @file{.o} file (or
5629 @file{.lo} when using libtool). Normally these object files are named
5630 after the source file, but other factors can change this. If a file in
5631 the @code{_SOURCES} variable has an unrecognized extension, Automake
5632 will do one of two things with it. If a suffix rule exists for turning
5633 files with the unrecognized extension into @file{.o} files, then
5634 @command{automake} will treat this file as it will any other source file
5635 (@pxref{Support for Other Languages}). Otherwise, the file will be
5636 ignored as though it were a header file.
5638 The prefixes @code{dist_} and @code{nodist_} can be used to control
5639 whether files listed in a @code{_SOURCES} variable are distributed.
5640 @code{dist_} is redundant, as sources are distributed by default, but it
5641 can be specified for clarity if desired.
5643 It is possible to have both @code{dist_} and @code{nodist_} variants of
5644 a given @code{_SOURCES} variable at once; this lets you easily
5645 distribute some files and not others, for instance:
5648 nodist_maude_SOURCES = nodist.c
5649 dist_maude_SOURCES = dist-me.c
5652 By default the output file (on Unix systems, the @file{.o} file) will
5653 be put into the current build directory. However, if the option
5654 @option{subdir-objects} is in effect in the current directory then the
5655 @file{.o} file will be put into the subdirectory named after the
5656 source file. For instance, with @option{subdir-objects} enabled,
5657 @file{sub/dir/file.c} will be compiled to @file{sub/dir/file.o}. Some
5658 people prefer this mode of operation. You can specify
5659 @option{subdir-objects} in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
5660 @cindex Subdirectory, objects in
5661 @cindex Objects in subdirectory
5664 @item EXTRA_maude_SOURCES
5665 Automake needs to know the list of files you intend to compile
5666 @emph{statically}. For one thing, this is the only way Automake has of
5667 knowing what sort of language support a given @file{Makefile.in}
5668 requires. @footnote{There are other, more obscure reasons for
5669 this limitation as well.} This means that, for example, you can't put a
5670 configure substitution like @samp{@@my_sources@@} into a @samp{_SOURCES}
5671 variable. If you intend to conditionally compile source files and use
5672 @file{configure} to substitute the appropriate object names into, e.g.,
5673 @code{_LDADD} (see below), then you should list the corresponding source
5674 files in the @code{EXTRA_} variable.
5676 This variable also supports @code{dist_} and @code{nodist_} prefixes.
5677 For instance, @code{nodist_EXTRA_maude_SOURCES} would list extra
5678 sources that may need to be built, but should not be distributed.
5681 A static library is created by default by invoking @samp{$(AR)
5682 $(ARFLAGS)} followed by the name of the library and then the objects
5683 being put into the library. You can override this by setting the
5684 @code{_AR} variable. This is usually used with C++; some C++
5685 compilers require a special invocation in order to instantiate all the
5686 templates that should go into a library. For instance, the SGI C++
5687 compiler likes this variable set like so:
5689 libmaude_a_AR = $(CXX) -ar -o
5693 Extra objects can be added to a @emph{library} using the @code{_LIBADD}
5694 variable. For instance, this should be used for objects determined by
5695 @command{configure} (@pxref{A Library}).
5697 In the case of libtool libraries, @code{maude_LIBADD} can also refer
5698 to other libtool libraries.
5701 Extra objects (@file{*.$(OBJEXT)}) and libraries (@file{*.a},
5702 @file{*.la}) can be added to a @emph{program} by listing them in the
5703 @code{_LDADD} variable. For instance, this should be used for objects
5704 determined by @command{configure} (@pxref{Linking}).
5706 @code{_LDADD} and @code{_LIBADD} are inappropriate for passing
5707 program-specific linker flags (except for @option{-l}, @option{-L},
5708 @option{-dlopen} and @option{-dlpreopen}). Use the @code{_LDFLAGS} variable
5711 For instance, if your @file{configure.ac} uses @code{AC_PATH_XTRA}, you
5712 could link your program against the X libraries like so:
5715 maude_LDADD = $(X_PRE_LIBS) $(X_LIBS) $(X_EXTRA_LIBS)
5718 We recommend that you use @option{-l} and @option{-L} only when
5719 referring to third-party libraries, and give the explicit file names
5720 of any library built by your package. Doing so will ensure that
5721 @code{maude_DEPENDENCIES} (see below) is correctly defined by default.
5724 This variable is used to pass extra flags to the link step of a program
5725 or a shared library. It overrides the @code{AM_LDFLAGS} variable.
5727 @item maude_LIBTOOLFLAGS
5728 This variable is used to pass extra options to @command{libtool}.
5729 It overrides the @code{AM_LIBTOOLFLAGS} variable.
5730 These options are output before @command{libtool}'s @option{--mode=@var{mode}}
5731 option, so they should not be mode-specific options (those belong to
5732 the compiler or linker flags). @xref{Libtool Flags}.
5734 @item maude_DEPENDENCIES
5735 @itemx EXTRA_maude_DEPENDENCIES
5736 It is also occasionally useful to have a target (program or library)
5737 depend on some other file that is not actually part of that target.
5738 This can be done using the @code{_DEPENDENCIES} variable. Each
5739 target depends on the contents of such a variable, but no further
5740 interpretation is done.
5742 Since these dependencies are associated to the link rule used to
5743 create the programs they should normally list files used by the link
5744 command. That is @file{*.$(OBJEXT)}, @file{*.a}, or @file{*.la} files
5745 for programs; @file{*.lo} and @file{*.la} files for Libtool libraries;
5746 and @file{*.$(OBJEXT)} files for static libraries. In rare cases you
5747 may need to add other kinds of files such as linker scripts, but
5748 @emph{listing a source file in @code{_DEPENDENCIES} is wrong}. If
5749 some source file needs to be built before all the components of a
5750 program are built, consider using the @code{BUILT_SOURCES} variable
5753 If @code{_DEPENDENCIES} is not supplied, it is computed by Automake.
5754 The automatically-assigned value is the contents of @code{_LDADD} or
5755 @code{_LIBADD}, with most configure substitutions, @option{-l}, @option{-L},
5756 @option{-dlopen} and @option{-dlpreopen} options removed. The configure
5757 substitutions that are left in are only @samp{$(LIBOBJS)} and
5758 @samp{$(ALLOCA)}; these are left because it is known that they will not
5759 cause an invalid value for @code{_DEPENDENCIES} to be generated.
5761 @code{_DEPENDENCIES} is more likely used to perform conditional
5762 compilation using an @code{AC_SUBST} variable that contains a list of
5763 objects. @xref{Conditional Sources}, and @ref{Conditional Libtool
5766 The @code{EXTRA_*_DEPENDENCIES} variable may be useful for cases where
5767 you merely want to augment the @command{automake}-generated
5768 @code{_DEPENDENCIES} variable rather than replacing it.
5771 You can override the linker on a per-program basis. By default the
5772 linker is chosen according to the languages used by the program. For
5773 instance, a program that includes C++ source code would use the C++
5774 compiler to link. The @code{_LINK} variable must hold the name of a
5775 command that can be passed all the @file{.o} file names and libraries
5776 to link against as arguments. Note that the name of the underlying
5777 program is @emph{not} passed to @code{_LINK}; typically one uses
5781 maude_LINK = $(CCLD) -magic -o $@@
5784 If a @code{_LINK} variable is not supplied, it may still be generated
5785 and used by Automake due to the use of per-target link flags such as
5786 @code{_CFLAGS}, @code{_LDFLAGS} or @code{_LIBTOOLFLAGS}, in cases where
5789 @item maude_CCASFLAGS
5791 @itemx maude_CPPFLAGS
5792 @itemx maude_CXXFLAGS
5794 @itemx maude_GCJFLAGS
5796 @itemx maude_OBJCFLAGS
5797 @itemx maude_OBJCXXFLAGS
5799 @itemx maude_UPCFLAGS
5801 @cindex per-target compilation flags, defined
5802 Automake allows you to set compilation flags on a per-program (or
5803 per-library) basis. A single source file can be included in several
5804 programs, and it will potentially be compiled with different flags for
5805 each program. This works for any language directly supported by
5806 Automake. These @dfn{per-target compilation flags} are
5815 @samp{_OBJCXXFLAGS},
5817 @samp{_UPCFLAGS}, and
5820 When using a per-target compilation flag, Automake will choose a
5821 different name for the intermediate object files. Ordinarily a file
5822 like @file{sample.c} will be compiled to produce @file{sample.o}.
5823 However, if the program's @code{_CFLAGS} variable is set, then the
5824 object file will be named, for instance, @file{maude-sample.o}. (See
5825 also @ref{Renamed Objects}.) The use of per-target compilation flags
5826 with C sources requires that the macro @code{AM_PROG_CC_C_O} be called
5827 from @file{configure.ac}.
5829 In compilations with per-target flags, the ordinary @samp{AM_} form of
5830 the flags variable is @emph{not} automatically included in the
5831 compilation (however, the user form of the variable @emph{is} included).
5832 So for instance, if you want the hypothetical @file{maude} compilations
5833 to also use the value of @code{AM_CFLAGS}, you would need to write:
5836 maude_CFLAGS = @dots{} your flags @dots{} $(AM_CFLAGS)
5839 @xref{Flag Variables Ordering}, for more discussion about the
5840 interaction between user variables, @samp{AM_} shadow variables, and
5841 per-target variables.
5843 @item maude_SHORTNAME
5844 On some platforms the allowable file names are very short. In order to
5845 support these systems and per-target compilation flags at the same
5846 time, Automake allows you to set a ``short name'' that will influence
5847 how intermediate object files are named. For instance, in the following
5851 bin_PROGRAMS = maude
5852 maude_CPPFLAGS = -DSOMEFLAG
5854 maude_SOURCES = sample.c @dots{}
5858 the object file would be named @file{m-sample.o} rather than
5859 @file{maude-sample.o}.
5861 This facility is rarely needed in practice,
5862 and we recommend avoiding it until you find it is required.
5865 @node Default _SOURCES
5866 @section Default @code{_SOURCES}
5870 @cindex @code{_SOURCES}, default
5871 @cindex default @code{_SOURCES}
5872 @vindex AM_DEFAULT_SOURCE_EXT
5874 @code{_SOURCES} variables are used to specify source files of programs
5875 (@pxref{A Program}), libraries (@pxref{A Library}), and Libtool
5876 libraries (@pxref{A Shared Library}).
5878 When no such variable is specified for a target, Automake will define
5879 one itself. The default is to compile a single C file whose base name
5880 is the name of the target itself, with any extension replaced by
5881 @code{AM_DEFAULT_SOURCE_EXT}, which defaults to @file{.c}.
5883 For example if you have the following somewhere in your
5884 @file{Makefile.am} with no corresponding @code{libfoo_a_SOURCES}:
5887 lib_LIBRARIES = libfoo.a sub/libc++.a
5891 @file{libfoo.a} will be built using a default source file named
5892 @file{libfoo.c}, and @file{sub/libc++.a} will be built from
5893 @file{sub/libc++.c}. (In older versions @file{sub/libc++.a}
5894 would be built from @file{sub_libc___a.c}, i.e., the default source
5895 was the canonized name of the target, with @file{.c} appended.
5896 We believe the new behavior is more sensible, but for backward
5897 compatibility @command{automake} will use the old name if a file or a rule
5898 with that name exists and @code{AM_DEFAULT_SOURCE_EXT} is not used.)
5900 @cindex @code{check_PROGRAMS} example
5901 @vindex check_PROGRAMS
5902 Default sources are mainly useful in test suites, when building many
5903 test programs each from a single source. For instance, in
5906 check_PROGRAMS = test1 test2 test3
5907 AM_DEFAULT_SOURCE_EXT = .cpp
5911 @file{test1}, @file{test2}, and @file{test3} will be built
5912 from @file{test1.cpp}, @file{test2.cpp}, and @file{test3.cpp}.
5913 Without the last line, they will be built from @file{test1.c},
5914 @file{test2.c}, and @file{test3.c}.
5916 @cindex Libtool modules, default source example
5917 @cindex default source, Libtool modules example
5918 Another case where this is convenient is building many Libtool modules
5919 (@file{module@var{n}.la}), each defined in its own file
5920 (@file{module@var{n}.c}).
5923 AM_LDFLAGS = -module
5924 lib_LTLIBRARIES = module1.la module2.la module3.la
5927 @cindex empty @code{_SOURCES}
5928 @cindex @code{_SOURCES}, empty
5929 Finally, there is one situation where this default source computation
5930 needs to be avoided: when a target should not be built from sources.
5931 We already saw such an example in @ref{true}; this happens when all
5932 the constituents of a target have already been compiled and just need
5933 to be combined using a @code{_LDADD} variable. Then it is necessary
5934 to define an empty @code{_SOURCES} variable, so that @command{automake}
5935 does not compute a default.
5938 bin_PROGRAMS = target
5940 target_LDADD = libmain.a libmisc.a
5944 @section Special handling for @code{LIBOBJS} and @code{ALLOCA}
5946 @cindex @code{LIBOBJS}, example
5947 @cindex @code{ALLOCA}, example
5948 @cindex @code{LIBOBJS}, special handling
5949 @cindex @code{ALLOCA}, special handling
5955 The @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} variables list object
5956 files that should be compiled into the project to provide an
5957 implementation for functions that are missing or broken on the host
5958 system. They are substituted by @file{configure}.
5962 These variables are defined by Autoconf macros such as
5963 @code{AC_LIBOBJ}, @code{AC_REPLACE_FUNCS} (@pxref{Generic Functions, ,
5964 Generic Function Checks, autoconf, The Autoconf Manual}), or
5965 @code{AC_FUNC_ALLOCA} (@pxref{Particular Functions, , Particular
5966 Function Checks, autoconf, The Autoconf Manual}). Many other Autoconf
5967 macros call @code{AC_LIBOBJ} or @code{AC_REPLACE_FUNCS} to
5968 populate @samp{$(LIBOBJS)}.
5970 @acindex AC_LIBSOURCE
5972 Using these variables is very similar to doing conditional compilation
5973 using @code{AC_SUBST} variables, as described in @ref{Conditional
5974 Sources}. That is, when building a program, @samp{$(LIBOBJS)} and
5975 @samp{$(ALLOCA)} should be added to the associated @samp{*_LDADD}
5976 variable, or to the @samp{*_LIBADD} variable when building a library.
5977 However there is no need to list the corresponding sources in
5978 @samp{EXTRA_*_SOURCES} nor to define @samp{*_DEPENDENCIES}. Automake
5979 automatically adds @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} to the
5980 dependencies, and it will discover the list of corresponding source
5981 files automatically (by tracing the invocations of the
5982 @code{AC_LIBSOURCE} Autoconf macros). If you have already defined
5983 @samp{*_DEPENDENCIES} explicitly for an unrelated reason, then you
5984 either need to add these variables manually, or use
5985 @samp{EXTRA_*_DEPENDENCIES} instead of @samp{*_DEPENDENCIES}.
5987 These variables are usually used to build a portability library that
5988 is linked with all the programs of the project. We now review a
5989 sample setup. First, @file{configure.ac} contains some checks that
5990 affect either @code{LIBOBJS} or @code{ALLOCA}.
5995 AC_CONFIG_LIBOBJ_DIR([lib])
5997 AC_FUNC_MALLOC dnl May add malloc.$(OBJEXT) to LIBOBJS
5998 AC_FUNC_MEMCMP dnl May add memcmp.$(OBJEXT) to LIBOBJS
5999 AC_REPLACE_FUNCS([strdup]) dnl May add strdup.$(OBJEXT) to LIBOBJS
6000 AC_FUNC_ALLOCA dnl May add alloca.$(OBJEXT) to ALLOCA
6009 @acindex AC_CONFIG_LIBOBJ_DIR
6011 The @code{AC_CONFIG_LIBOBJ_DIR} tells Autoconf that the source files
6012 of these object files are to be found in the @file{lib/} directory.
6013 Automake can also use this information, otherwise it expects the
6014 source files are to be in the directory where the @samp{$(LIBOBJS)}
6015 and @samp{$(ALLOCA)} variables are used.
6017 The @file{lib/} directory should therefore contain @file{malloc.c},
6018 @file{memcmp.c}, @file{strdup.c}, @file{alloca.c}. Here is its
6024 noinst_LIBRARIES = libcompat.a
6025 libcompat_a_SOURCES =
6026 libcompat_a_LIBADD = $(LIBOBJS) $(ALLOCA)
6029 The library can have any name, of course, and anyway it is not going
6030 to be installed: it just holds the replacement versions of the missing
6031 or broken functions so we can later link them in. Many projects
6032 also include extra functions, specific to the project, in that
6033 library: they are simply added on the @code{_SOURCES} line.
6035 @cindex Empty libraries and @samp{$(LIBOBJS)}
6036 @cindex @samp{$(LIBOBJS)} and empty libraries
6037 There is a small trap here, though: @samp{$(LIBOBJS)} and
6038 @samp{$(ALLOCA)} might be empty, and building an empty library is not
6039 portable. You should ensure that there is always something to put in
6040 @file{libcompat.a}. Most projects will also add some utility
6041 functions in that directory, and list them in
6042 @code{libcompat_a_SOURCES}, so in practice @file{libcompat.a} cannot
6045 Finally here is how this library could be used from the @file{src/}
6051 # Link all programs in this directory with libcompat.a
6052 LDADD = ../lib/libcompat.a
6054 bin_PROGRAMS = tool1 tool2 @dots{}
6055 tool1_SOURCES = @dots{}
6056 tool2_SOURCES = @dots{}
6059 When option @option{subdir-objects} is not used, as in the above
6060 example, the variables @samp{$(LIBOBJS)} or @samp{$(ALLOCA)} can only
6061 be used in the directory where their sources lie. E.g., here it would
6062 be wrong to use @samp{$(LIBOBJS)} or @samp{$(ALLOCA)} in
6063 @file{src/Makefile.am}. However if both @option{subdir-objects} and
6064 @code{AC_CONFIG_LIBOBJ_DIR} are used, it is OK to use these variables
6065 in other directories. For instance @file{src/Makefile.am} could be
6071 AUTOMAKE_OPTIONS = subdir-objects
6072 LDADD = $(LIBOBJS) $(ALLOCA)
6074 bin_PROGRAMS = tool1 tool2 @dots{}
6075 tool1_SOURCES = @dots{}
6076 tool2_SOURCES = @dots{}
6079 Because @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} contain object
6080 file names that end with @samp{.$(OBJEXT)}, they are not suitable for
6081 Libtool libraries (where the expected object extension is @file{.lo}):
6082 @code{LTLIBOBJS} and @code{LTALLOCA} should be used instead.
6084 @code{LTLIBOBJS} is defined automatically by Autoconf and should not
6085 be defined by hand (as in the past), however at the time of writing
6086 @code{LTALLOCA} still needs to be defined from @code{ALLOCA} manually.
6087 @xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs.@: @code{LIBOBJS},
6088 autoconf, The Autoconf Manual}.
6091 @node Program Variables
6092 @section Variables used when building a program
6094 Occasionally it is useful to know which @file{Makefile} variables
6095 Automake uses for compilations, and in which order (@pxref{Flag
6096 Variables Ordering}); for instance, you might need to do your own
6097 compilation in some special cases.
6099 Some variables are inherited from Autoconf; these are @code{CC},
6100 @code{CFLAGS}, @code{CPPFLAGS}, @code{DEFS}, @code{LDFLAGS}, and
6109 There are some additional variables that Automake defines on its own:
6113 The contents of this variable are passed to every compilation that invokes
6114 the C preprocessor; it is a list of arguments to the preprocessor. For
6115 instance, @option{-I} and @option{-D} options should be listed here.
6117 Automake already provides some @option{-I} options automatically, in a
6118 separate variable that is also passed to every compilation that invokes
6119 the C preprocessor. In particular it generates @samp{-I.},
6120 @samp{-I$(srcdir)}, and a @option{-I} pointing to the directory holding
6121 @file{config.h} (if you've used @code{AC_CONFIG_HEADERS} or
6122 @code{AM_CONFIG_HEADER}). You can disable the default @option{-I}
6123 options using the @option{nostdinc} option.
6125 When a file to be included is generated during the build and not part
6126 of a distribution tarball, its location is under @code{$(builddir)},
6127 not under @code{$(srcdir)}. This matters especially for packages that
6128 use header files placed in sub-directories and want to allow builds
6129 outside the source tree (@pxref{VPATH Builds}). In that case we
6130 recommend to use a pair of @option{-I} options, such as, e.g.,
6131 @samp{-Isome/subdir -I$(srcdir)/some/subdir} or
6132 @samp{-I$(top_builddir)/some/subdir -I$(top_srcdir)/some/subdir}.
6133 Note that the reference to the build tree should come before the
6134 reference to the source tree, so that accidentally leftover generated
6135 files in the source directory are ignored.
6137 @code{AM_CPPFLAGS} is ignored in preference to a per-executable (or
6138 per-library) @code{_CPPFLAGS} variable if it is defined.
6141 This does the same job as @code{AM_CPPFLAGS} (or any per-target
6142 @code{_CPPFLAGS} variable if it is used). It is an older name for the
6143 same functionality. This variable is deprecated; we suggest using
6144 @code{AM_CPPFLAGS} and per-target @code{_CPPFLAGS} instead.
6147 This is the variable the @file{Makefile.am} author can use to pass
6148 in additional C compiler flags. It is more fully documented elsewhere.
6149 In some situations, this is not used, in preference to the
6150 per-executable (or per-library) @code{_CFLAGS}.
6153 This is the command used to actually compile a C source file. The
6154 file name is appended to form the complete command line.
6157 This is the variable the @file{Makefile.am} author can use to pass
6158 in additional linker flags. In some situations, this is not used, in
6159 preference to the per-executable (or per-library) @code{_LDFLAGS}.
6162 This is the command used to actually link a C program. It already
6163 includes @samp{-o $@@} and the usual variable references (for instance,
6164 @code{CFLAGS}); it takes as ``arguments'' the names of the object files
6165 and libraries to link in. This variable is not used when the linker is
6166 overridden with a per-target @code{_LINK} variable or per-target flags
6167 cause Automake to define such a @code{_LINK} variable.
6172 @section Yacc and Lex support
6174 Automake has somewhat idiosyncratic support for Yacc and Lex.
6176 Automake assumes that the @file{.c} file generated by @command{yacc}
6177 (or @command{lex}) should be named using the basename of the input
6178 file. That is, for a yacc source file @file{foo.y}, Automake will
6179 cause the intermediate file to be named @file{foo.c} (as opposed to
6180 @file{y.tab.c}, which is more traditional).
6182 The extension of a yacc source file is used to determine the extension
6183 of the resulting C or C++ source and header files. Note that header
6184 files are generated only when the @option{-d} Yacc option is used; see
6185 below for more information about this flag, and how to specify it.
6186 Files with the extension @file{.y} will thus be turned into @file{.c}
6187 sources and @file{.h} headers; likewise, @file{.yy} will become
6188 @file{.cc} and @file{.hh}, @file{.y++} will become @file{c++} and
6189 @file{h++}, @file{.yxx} will become @file{.cxx} and @file{.hxx},
6190 and @file{.ypp} will become @file{.cpp} and @file{.hpp}.
6192 Similarly, lex source files can be used to generate C or C++; the
6193 extensions @file{.l}, @file{.ll}, @file{.l++}, @file{.lxx}, and
6194 @file{.lpp} are recognized.
6196 You should never explicitly mention the intermediate (C or C++) file
6197 in any @code{SOURCES} variable; only list the source file.
6199 The intermediate files generated by @command{yacc} (or @command{lex})
6200 will be included in any distribution that is made. That way the user
6201 doesn't need to have @command{yacc} or @command{lex}.
6203 If a @command{yacc} source file is seen, then your @file{configure.ac} must
6204 define the variable @code{YACC}. This is most easily done by invoking
6205 the macro @code{AC_PROG_YACC} (@pxref{Particular Programs, , Particular
6206 Program Checks, autoconf, The Autoconf Manual}).
6210 When @code{yacc} is invoked, it is passed @code{AM_YFLAGS} and
6211 @code{YFLAGS}. The latter is a user variable and the former is
6212 intended for the @file{Makefile.am} author.
6214 @code{AM_YFLAGS} is usually used to pass the @option{-d} option to
6215 @command{yacc}. Automake knows what this means and will automatically
6216 adjust its rules to update and distribute the header file built by
6217 @samp{yacc -d}@footnote{Please note that @command{automake} recognizes
6218 @option{-d} in @code{AM_YFLAGS} only if it is not clustered with other
6219 options; for example, it won't be recognized if @code{AM_YFLAGS} is
6220 @option{-dt}, but it will be if @code{AM_YFLAGS} is @option{-d -t} or
6222 What Automake cannot guess, though, is where this
6223 header will be used: it is up to you to ensure the header gets built
6224 before it is first used. Typically this is necessary in order for
6225 dependency tracking to work when the header is included by another
6226 file. The common solution is listing the header file in
6227 @code{BUILT_SOURCES} (@pxref{Sources}) as follows.
6230 BUILT_SOURCES = parser.h
6233 foo_SOURCES = @dots{} parser.y @dots{}
6236 If a @command{lex} source file is seen, then your @file{configure.ac}
6237 must define the variable @code{LEX}. You can use @code{AC_PROG_LEX}
6238 to do this (@pxref{Particular Programs, , Particular Program Checks,
6239 autoconf, The Autoconf Manual}), but using @code{AM_PROG_LEX} macro
6240 (@pxref{Macros}) is recommended.
6244 When @command{lex} is invoked, it is passed @code{AM_LFLAGS} and
6245 @code{LFLAGS}. The latter is a user variable and the former is
6246 intended for the @file{Makefile.am} author.
6248 When @code{AM_MAINTAINER_MODE} (@pxref{maintainer-mode}) is used, the
6249 rebuild rule for distributed Yacc and Lex sources are only used when
6250 @code{maintainer-mode} is enabled, or when the files have been erased.
6252 @cindex @command{ylwrap}
6253 @cindex @command{yacc}, multiple parsers
6254 @cindex Multiple @command{yacc} parsers
6255 @cindex Multiple @command{lex} lexers
6256 @cindex @command{lex}, multiple lexers
6258 When @command{lex} or @command{yacc} sources are used, @code{automake
6259 -i} automatically installs an auxiliary program called
6260 @command{ylwrap} in your package (@pxref{Auxiliary Programs}). This
6261 program is used by the build rules to rename the output of these
6262 tools, and makes it possible to include multiple @command{yacc} (or
6263 @command{lex}) source files in a single directory. (This is necessary
6264 because yacc's output file name is fixed, and a parallel make could
6265 conceivably invoke more than one instance of @command{yacc}
6268 For @command{yacc}, simply managing locking is insufficient. The output of
6269 @command{yacc} always uses the same symbol names internally, so it isn't
6270 possible to link two @command{yacc} parsers into the same executable.
6272 We recommend using the following renaming hack used in @command{gdb}:
6274 #define yymaxdepth c_maxdepth
6275 #define yyparse c_parse
6277 #define yyerror c_error
6278 #define yylval c_lval
6279 #define yychar c_char
6280 #define yydebug c_debug
6281 #define yypact c_pact
6288 #define yyexca c_exca
6289 #define yyerrflag c_errflag
6290 #define yynerrs c_nerrs
6294 #define yy_yys c_yys
6295 #define yystate c_state
6298 #define yy_yyv c_yyv
6300 #define yylloc c_lloc
6301 #define yyreds c_reds
6302 #define yytoks c_toks
6303 #define yylhs c_yylhs
6304 #define yylen c_yylen
6305 #define yydefred c_yydefred
6306 #define yydgoto c_yydgoto
6307 #define yysindex c_yysindex
6308 #define yyrindex c_yyrindex
6309 #define yygindex c_yygindex
6310 #define yytable c_yytable
6311 #define yycheck c_yycheck
6312 #define yyname c_yyname
6313 #define yyrule c_yyrule
6316 For each define, replace the @samp{c_} prefix with whatever you like.
6317 These defines work for @command{bison}, @command{byacc}, and
6318 traditional @code{yacc}s. If you find a parser generator that uses a
6319 symbol not covered here, please report the new name so it can be added
6324 @section C++ Support
6327 @cindex Support for C++
6329 Automake includes full support for C++.
6331 Any package including C++ code must define the output variable
6332 @code{CXX} in @file{configure.ac}; the simplest way to do this is to use
6333 the @code{AC_PROG_CXX} macro (@pxref{Particular Programs, , Particular
6334 Program Checks, autoconf, The Autoconf Manual}).
6336 A few additional variables are defined when a C++ source file is seen:
6340 The name of the C++ compiler.
6343 Any flags to pass to the C++ compiler.
6346 The maintainer's variant of @code{CXXFLAGS}.
6349 The command used to actually compile a C++ source file. The file name
6350 is appended to form the complete command line.
6353 The command used to actually link a C++ program.
6357 @node Objective C Support
6358 @section Objective C Support
6360 @cindex Objective C support
6361 @cindex Support for Objective C
6363 Automake includes some support for Objective C.
6365 Any package including Objective C code must define the output variable
6366 @code{OBJC} in @file{configure.ac}; the simplest way to do this is to use
6367 the @code{AC_PROG_OBJC} macro (@pxref{Particular Programs, , Particular
6368 Program Checks, autoconf, The Autoconf Manual}).
6370 A few additional variables are defined when an Objective C source file
6375 The name of the Objective C compiler.
6378 Any flags to pass to the Objective C compiler.
6381 The maintainer's variant of @code{OBJCFLAGS}.
6384 The command used to actually compile an Objective C source file. The
6385 file name is appended to form the complete command line.
6388 The command used to actually link an Objective C program.
6392 @node Objective C++ Support
6393 @section Objective C++ Support
6395 @cindex Objective C++ support
6396 @cindex Support for Objective C++
6398 Automake includes some support for Objective C++.
6400 Any package including Objective C++ code must define the output variable
6401 @code{OBJCXX} in @file{configure.ac}; the simplest way to do this is to use
6402 the @code{AC_PROG_OBJCXX} macro (@pxref{Particular Programs, , Particular
6403 Program Checks, autoconf, The Autoconf Manual}).
6405 A few additional variables are defined when an Objective C++ source file
6410 The name of the Objective C++ compiler.
6413 Any flags to pass to the Objective C++ compiler.
6415 @item AM_OBJCXXFLAGS
6416 The maintainer's variant of @code{OBJCXXFLAGS}.
6419 The command used to actually compile an Objective C++ source file. The
6420 file name is appended to form the complete command line.
6423 The command used to actually link an Objective C++ program.
6427 @node Unified Parallel C Support
6428 @section Unified Parallel C Support
6430 @cindex Unified Parallel C support
6431 @cindex Support for Unified Parallel C
6433 Automake includes some support for Unified Parallel C.
6435 Any package including Unified Parallel C code must define the output
6436 variable @code{UPC} in @file{configure.ac}; the simplest way to do
6437 this is to use the @code{AM_PROG_UPC} macro (@pxref{Public Macros}).
6439 A few additional variables are defined when a Unified Parallel C
6440 source file is seen:
6444 The name of the Unified Parallel C compiler.
6447 Any flags to pass to the Unified Parallel C compiler.
6450 The maintainer's variant of @code{UPCFLAGS}.
6453 The command used to actually compile a Unified Parallel C source file.
6454 The file name is appended to form the complete command line.
6457 The command used to actually link a Unified Parallel C program.
6461 @node Assembly Support
6462 @section Assembly Support
6464 Automake includes some support for assembly code. There are two forms
6465 of assembler files: normal (@file{*.s}) and preprocessed by @code{CPP}
6466 (@file{*.S} or @file{*.sx}).
6471 @vindex AM_CCASFLAGS
6473 The variable @code{CCAS} holds the name of the compiler used to build
6474 assembly code. This compiler must work a bit like a C compiler; in
6475 particular it must accept @option{-c} and @option{-o}. The values of
6476 @code{CCASFLAGS} and @code{AM_CCASFLAGS} (or its per-target
6477 definition) is passed to the compilation. For preprocessed files,
6478 @code{DEFS}, @code{DEFAULT_INCLUDES}, @code{INCLUDES}, @code{CPPFLAGS}
6479 and @code{AM_CPPFLAGS} are also used.
6481 The autoconf macro @code{AM_PROG_AS} will define @code{CCAS} and
6482 @code{CCASFLAGS} for you (unless they are already set, it simply sets
6483 @code{CCAS} to the C compiler and @code{CCASFLAGS} to the C compiler
6484 flags), but you are free to define these variables by other means.
6486 Only the suffixes @file{.s}, @file{.S}, and @file{.sx} are recognized by
6487 @command{automake} as being files containing assembly code.
6490 @node Fortran 77 Support
6491 @comment node-name, next, previous, up
6492 @section Fortran 77 Support
6494 @cindex Fortran 77 support
6495 @cindex Support for Fortran 77
6497 Automake includes full support for Fortran 77.
6499 Any package including Fortran 77 code must define the output variable
6500 @code{F77} in @file{configure.ac}; the simplest way to do this is to use
6501 the @code{AC_PROG_F77} macro (@pxref{Particular Programs, , Particular
6502 Program Checks, autoconf, The Autoconf Manual}).
6504 A few additional variables are defined when a Fortran 77 source file is
6510 The name of the Fortran 77 compiler.
6513 Any flags to pass to the Fortran 77 compiler.
6516 The maintainer's variant of @code{FFLAGS}.
6519 Any flags to pass to the Ratfor compiler.
6522 The maintainer's variant of @code{RFLAGS}.
6525 The command used to actually compile a Fortran 77 source file. The file
6526 name is appended to form the complete command line.
6529 The command used to actually link a pure Fortran 77 program or shared
6534 Automake can handle preprocessing Fortran 77 and Ratfor source files in
6535 addition to compiling them@footnote{Much, if not most, of the
6536 information in the following sections pertaining to preprocessing
6537 Fortran 77 programs was taken almost verbatim from @ref{Catalogue of
6538 Rules, , Catalogue of Rules, make, The GNU Make Manual}.}. Automake
6539 also contains some support for creating programs and shared libraries
6540 that are a mixture of Fortran 77 and other languages (@pxref{Mixing
6541 Fortran 77 With C and C++}).
6543 These issues are covered in the following sections.
6546 * Preprocessing Fortran 77:: Preprocessing Fortran 77 sources
6547 * Compiling Fortran 77 Files:: Compiling Fortran 77 sources
6548 * Mixing Fortran 77 With C and C++:: Mixing Fortran 77 With C and C++
6552 @node Preprocessing Fortran 77
6553 @comment node-name, next, previous, up
6554 @subsection Preprocessing Fortran 77
6556 @cindex Preprocessing Fortran 77
6557 @cindex Fortran 77, Preprocessing
6558 @cindex Ratfor programs
6560 @file{N.f} is made automatically from @file{N.F} or @file{N.r}. This
6561 rule runs just the preprocessor to convert a preprocessable Fortran 77
6562 or Ratfor source file into a strict Fortran 77 source file. The precise
6563 command used is as follows:
6568 @code{$(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)@*
6569 $(AM_FFLAGS) $(FFLAGS)}
6572 @code{$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
6577 @node Compiling Fortran 77 Files
6578 @comment node-name, next, previous, up
6579 @subsection Compiling Fortran 77 Files
6581 @file{N.o} is made automatically from @file{N.f}, @file{N.F} or
6582 @file{N.r} by running the Fortran 77 compiler. The precise command used
6588 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS)}
6591 @code{$(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)@*
6592 $(AM_FFLAGS) $(FFLAGS)}
6595 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
6600 @node Mixing Fortran 77 With C and C++
6601 @comment node-name, next, previous, up
6602 @subsection Mixing Fortran 77 With C and C++
6604 @cindex Fortran 77, mixing with C and C++
6605 @cindex Mixing Fortran 77 with C and C++
6606 @cindex Linking Fortran 77 with C and C++
6608 @cindex Mixing Fortran 77 with C and/or C++
6610 Automake currently provides @emph{limited} support for creating programs
6611 and shared libraries that are a mixture of Fortran 77 and C and/or C++.
6612 However, there are many other issues related to mixing Fortran 77 with
6613 other languages that are @emph{not} (currently) handled by Automake, but
6614 that are handled by other packages@footnote{For example,
6615 @uref{http://www-zeus.desy.de/~burow/cfortran/, the cfortran package}
6616 addresses all of these inter-language issues, and runs under nearly all
6617 Fortran 77, C and C++ compilers on nearly all platforms. However,
6618 @command{cfortran} is not yet Free Software, but it will be in the next
6621 Automake can help in two ways:
6625 Automatic selection of the linker depending on which combinations of
6629 Automatic selection of the appropriate linker flags (e.g., @option{-L} and
6630 @option{-l}) to pass to the automatically selected linker in order to link
6631 in the appropriate Fortran 77 intrinsic and run-time libraries.
6633 @cindex @code{FLIBS}, defined
6635 These extra Fortran 77 linker flags are supplied in the output variable
6636 @code{FLIBS} by the @code{AC_F77_LIBRARY_LDFLAGS} Autoconf macro.
6637 @xref{Fortran Compiler, , Fortran Compiler Characteristics, autoconf,
6638 The Autoconf Manual}.
6641 If Automake detects that a program or shared library (as mentioned in
6642 some @code{_PROGRAMS} or @code{_LTLIBRARIES} primary) contains source
6643 code that is a mixture of Fortran 77 and C and/or C++, then it requires
6644 that the macro @code{AC_F77_LIBRARY_LDFLAGS} be called in
6645 @file{configure.ac}, and that either @code{$(FLIBS)}
6646 appear in the appropriate @code{_LDADD} (for programs) or @code{_LIBADD}
6647 (for shared libraries) variables. It is the responsibility of the
6648 person writing the @file{Makefile.am} to make sure that @samp{$(FLIBS)}
6649 appears in the appropriate @code{_LDADD} or
6650 @code{_LIBADD} variable.
6652 @cindex Mixed language example
6653 @cindex Example, mixed language
6655 For example, consider the following @file{Makefile.am}:
6659 foo_SOURCES = main.cc foo.f
6660 foo_LDADD = libfoo.la $(FLIBS)
6662 pkglib_LTLIBRARIES = libfoo.la
6663 libfoo_la_SOURCES = bar.f baz.c zardoz.cc
6664 libfoo_la_LIBADD = $(FLIBS)
6667 In this case, Automake will insist that @code{AC_F77_LIBRARY_LDFLAGS}
6668 is mentioned in @file{configure.ac}. Also, if @samp{$(FLIBS)} hadn't
6669 been mentioned in @code{foo_LDADD} and @code{libfoo_la_LIBADD}, then
6670 Automake would have issued a warning.
6673 * How the Linker is Chosen:: Automatic linker selection
6676 @node How the Linker is Chosen
6677 @comment node-name, next, previous, up
6678 @subsubsection How the Linker is Chosen
6680 @cindex Automatic linker selection
6681 @cindex Selecting the linker automatically
6683 When a program or library mixes several languages, Automake choose the
6684 linker according to the following priorities. (The names in
6685 parentheses are the variables containing the link command.)
6690 Native Java (@code{GCJLINK})
6693 Objective C++ (@code{OBJCXXLINK})
6696 C++ (@code{CXXLINK})
6699 Fortran 77 (@code{F77LINK})
6702 Fortran (@code{FCLINK})
6705 Objective C (@code{OBJCLINK})
6708 Unified Parallel C (@code{UPCLINK})
6714 For example, if Fortran 77, C and C++ source code is compiled
6715 into a program, then the C++ linker will be used. In this case, if the
6716 C or Fortran 77 linkers required any special libraries that weren't
6717 included by the C++ linker, then they must be manually added to an
6718 @code{_LDADD} or @code{_LIBADD} variable by the user writing the
6721 Automake only looks at the file names listed in @file{_SOURCES}
6722 variables to choose the linker, and defaults to the C linker.
6723 Sometimes this is inconvenient because you are linking against a
6724 library written in another language and would like to set the linker
6725 more appropriately. @xref{Libtool Convenience Libraries}, for a
6726 trick with @code{nodist_EXTRA_@dots{}_SOURCES}.
6728 A per-target @code{_LINK} variable will override the above selection.
6729 Per-target link flags will cause Automake to write a per-target
6730 @code{_LINK} variable according to the language chosen as above.
6733 @node Fortran 9x Support
6734 @comment node-name, next, previous, up
6735 @section Fortran 9x Support
6737 @cindex Fortran 9x support
6738 @cindex Support for Fortran 9x
6740 Automake includes support for Fortran 9x.
6742 Any package including Fortran 9x code must define the output variable
6743 @code{FC} in @file{configure.ac}; the simplest way to do this is to use
6744 the @code{AC_PROG_FC} macro (@pxref{Particular Programs, , Particular
6745 Program Checks, autoconf, The Autoconf Manual}).
6747 A few additional variables are defined when a Fortran 9x source file is
6753 The name of the Fortran 9x compiler.
6756 Any flags to pass to the Fortran 9x compiler.
6759 The maintainer's variant of @code{FCFLAGS}.
6762 The command used to actually compile a Fortran 9x source file. The file
6763 name is appended to form the complete command line.
6766 The command used to actually link a pure Fortran 9x program or shared
6772 * Compiling Fortran 9x Files:: Compiling Fortran 9x sources
6775 @node Compiling Fortran 9x Files
6776 @comment node-name, next, previous, up
6777 @subsection Compiling Fortran 9x Files
6779 @file{@var{file}.o} is made automatically from @file{@var{file}.f90},
6780 @file{@var{file}.f95}, @file{@var{file}.f03}, or @file{@var{file}.f08}
6781 by running the Fortran 9x compiler. The precise command used
6787 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f90) $<}
6790 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f95) $<}
6793 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f03) $<}
6796 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f08) $<}
6800 @node Java Support with gcj
6801 @comment node-name, next, previous, up
6802 @section Compiling Java sources using gcj
6804 @cindex Java support with gcj
6805 @cindex Support for Java with gcj
6806 @cindex Java to native code, compilation
6807 @cindex Compilation of Java to native code
6809 Automake includes support for natively compiled Java, using @command{gcj},
6810 the Java front end to the GNU Compiler Collection (rudimentary support
6811 for compiling Java to bytecode using the @command{javac} compiler is
6812 also present, @emph{albeit deprecated}; @pxref{Java}).
6814 Any package including Java code to be compiled must define the output
6815 variable @code{GCJ} in @file{configure.ac}; the variable @code{GCJFLAGS}
6816 must also be defined somehow (either in @file{configure.ac} or
6817 @file{Makefile.am}). The simplest way to do this is to use the
6818 @code{AM_PROG_GCJ} macro.
6822 By default, programs including Java source files are linked with
6825 As always, the contents of @code{AM_GCJFLAGS} are passed to every
6826 compilation invoking @command{gcj} (in its role as an ahead-of-time
6827 compiler, when invoking it to create @file{.class} files,
6828 @code{AM_JAVACFLAGS} is used instead). If it is necessary to pass
6829 options to @command{gcj} from @file{Makefile.am}, this variable, and not
6830 the user variable @code{GCJFLAGS}, should be used.
6834 @command{gcj} can be used to compile @file{.java}, @file{.class},
6835 @file{.zip}, or @file{.jar} files.
6837 When linking, @command{gcj} requires that the main class be specified
6838 using the @option{--main=} option. The easiest way to do this is to use
6839 the @code{_LDFLAGS} variable for the program.
6843 @comment node-name, next, previous, up
6844 @section Vala Support
6846 @cindex Vala Support
6847 @cindex Support for Vala
6849 Automake provides initial support for Vala
6850 (@uref{http://www.vala-project.org/}).
6851 This requires valac version 0.7.0 or later, and currently requires
6852 the user to use GNU @command{make}.
6855 foo_SOURCES = foo.vala bar.vala zardoc.c
6858 Any @file{.vala} file listed in a @code{_SOURCES} variable will be
6859 compiled into C code by the Vala compiler. The generated @file{.c} files are
6860 distributed. The end user does not need to have a Vala compiler installed.
6862 Automake ships with an Autoconf macro called @code{AM_PROG_VALAC}
6863 that will locate the Vala compiler and optionally check its version
6866 @defmac AM_PROG_VALAC (@ovar{minimum-version})
6867 Try to find a Vala compiler in @env{PATH}. If it is found, the variable
6868 @code{VALAC} is set. Optionally a minimum release number of the compiler
6872 AM_PROG_VALAC([0.7.0])
6876 There are a few variables that are used when compiling Vala sources:
6880 Path to the Vala compiler.
6883 Additional arguments for the Vala compiler.
6886 The maintainer's variant of @code{VALAFLAGS}.
6889 lib_LTLIBRARIES = libfoo.la
6890 libfoo_la_SOURCES = foo.vala
6894 Note that currently, you cannot use per-target @code{*_VALAFLAGS}
6895 (@pxref{Renamed Objects}) to produce different C files from one Vala
6899 @node Support for Other Languages
6900 @comment node-name, next, previous, up
6901 @section Support for Other Languages
6903 Automake currently only includes full support for C, C++ (@pxref{C++
6904 Support}), Objective C (@pxref{Objective C Support}),
6905 Objective C++ (@pxref{Objective C++ Support}),
6907 (@pxref{Fortran 77 Support}), Fortran 9x (@pxref{Fortran 9x Support}),
6908 and Java (@pxref{Java Support with gcj}). There is only rudimentary
6909 support for other languages, support for which will be improved based
6912 Some limited support for adding your own languages is available via the
6913 suffix rule handling (@pxref{Suffixes}).
6916 @section Automatic dependency tracking
6918 As a developer it is often painful to continually update the
6919 @file{Makefile.am} whenever the include-file dependencies change in a
6920 project. Automake supplies a way to automatically track dependency
6921 changes (@pxref{Dependency Tracking}).
6923 @cindex Dependency tracking
6924 @cindex Automatic dependency tracking
6926 Automake always uses complete dependencies for a compilation,
6927 including system headers. Automake's model is that dependency
6928 computation should be a side effect of the build. To this end,
6929 dependencies are computed by running all compilations through a
6930 special wrapper program called @command{depcomp}. @command{depcomp}
6931 understands how to coax many different C and C++ compilers into
6932 generating dependency information in the format it requires.
6933 @samp{automake -a} will install @command{depcomp} into your source
6934 tree for you. If @command{depcomp} can't figure out how to properly
6935 invoke your compiler, dependency tracking will simply be disabled for
6938 @cindex @command{depcomp}
6940 Experience with earlier versions of Automake (@pxref{Dependency Tracking
6941 Evolution, , Dependency Tracking Evolution, automake-history, Brief History
6942 of Automake}) taught us that it is not reliable to generate dependencies
6943 only on the maintainer's system, as configurations vary too much. So
6944 instead Automake implements dependency tracking at build time.
6946 Automatic dependency tracking can be suppressed by putting
6947 @option{no-dependencies} in the variable @code{AUTOMAKE_OPTIONS}, or
6948 passing @option{no-dependencies} as an argument to @code{AM_INIT_AUTOMAKE}
6949 (this should be the preferred way). Or, you can invoke @command{automake}
6950 with the @option{-i} option. Dependency tracking is enabled by default.
6952 @vindex AUTOMAKE_OPTIONS
6953 @opindex no-dependencies
6955 The person building your package also can choose to disable dependency
6956 tracking by configuring with @option{--disable-dependency-tracking}.
6958 @cindex Disabling dependency tracking
6959 @cindex Dependency tracking, disabling
6963 @section Support for executable extensions
6965 @cindex Executable extension
6966 @cindex Extension, executable
6969 On some platforms, such as Windows, executables are expected to have an
6970 extension such as @file{.exe}. On these platforms, some compilers (GCC
6971 among them) will automatically generate @file{foo.exe} when asked to
6972 generate @file{foo}.
6974 Automake provides mostly-transparent support for this. Unfortunately
6975 @emph{mostly} doesn't yet mean @emph{fully}. Until the English
6976 dictionary is revised, you will have to assist Automake if your package
6977 must support those platforms.
6979 One thing you must be aware of is that, internally, Automake rewrites
6980 something like this:
6983 bin_PROGRAMS = liver
6989 bin_PROGRAMS = liver$(EXEEXT)
6992 The targets Automake generates are likewise given the @samp{$(EXEEXT)}
6995 The variables @code{TESTS} and @code{XFAIL_TESTS} (@pxref{Simple Tests})
6996 are also rewritten if they contain filenames that have been declared as
6997 programs in the same @file{Makefile}. (This is mostly useful when some
6998 programs from @code{check_PROGRAMS} are listed in @code{TESTS}.)
7000 However, Automake cannot apply this rewriting to @command{configure}
7001 substitutions. This means that if you are conditionally building a
7002 program using such a substitution, then your @file{configure.ac} must
7003 take care to add @samp{$(EXEEXT)} when constructing the output variable.
7005 Sometimes maintainers like to write an explicit link rule for their
7006 program. Without executable extension support, this is easy---you
7007 simply write a rule whose target is the name of the program. However,
7008 when executable extension support is enabled, you must instead add the
7009 @samp{$(EXEEXT)} suffix.
7011 This might be a nuisance for maintainers who know their package will
7012 never run on a platform that has
7013 executable extensions. For those maintainers, the @option{no-exeext}
7014 option (@pxref{Options}) will disable this feature. This works in a
7015 fairly ugly way; if @option{no-exeext} is seen, then the presence of a
7016 rule for a target named @code{foo} in @file{Makefile.am} will override
7017 an @command{automake}-generated rule for @samp{foo$(EXEEXT)}. Without
7018 the @option{no-exeext} option, this use will give a diagnostic.
7022 @chapter Other Derived Objects
7024 Automake can handle derived objects that are not C programs. Sometimes
7025 the support for actually building such objects must be explicitly
7026 supplied, but Automake will still automatically handle installation and
7030 * Scripts:: Executable scripts
7031 * Headers:: Header files
7032 * Data:: Architecture-independent data files
7033 * Sources:: Derived sources
7038 @section Executable Scripts
7040 @cindex @code{_SCRIPTS} primary, defined
7041 @cindex @code{SCRIPTS} primary, defined
7042 @cindex Primary variable, @code{SCRIPTS}
7044 @cindex Installing scripts
7046 It is possible to define and install programs that are scripts. Such
7047 programs are listed using the @code{SCRIPTS} primary name. When the
7048 script is distributed in its final, installable form, the
7049 @file{Makefile} usually looks as follows:
7053 # Install my_script in $(bindir) and distribute it.
7054 dist_bin_SCRIPTS = my_script
7057 Scripts are not distributed by default; as we have just seen, those
7058 that should be distributed can be specified using a @code{dist_}
7059 prefix as with other primaries.
7061 @cindex @code{SCRIPTS}, installation directories
7063 @vindex sbin_SCRIPTS
7064 @vindex libexec_SCRIPTS
7065 @vindex pkgdata_SCRIPTS
7066 @vindex pkglibexec_SCRIPTS
7067 @vindex noinst_SCRIPTS
7068 @vindex check_SCRIPTS
7070 Scripts can be installed in @code{bindir}, @code{sbindir},
7071 @code{libexecdir}, @code{pkglibexecdir}, or @code{pkgdatadir}.
7073 Scripts that need not be installed can be listed in
7074 @code{noinst_SCRIPTS}, and among them, those which are needed only by
7075 @samp{make check} should go in @code{check_SCRIPTS}.
7077 When a script needs to be built, the @file{Makefile.am} should include
7078 the appropriate rules. For instance the @command{automake} program
7079 itself is a Perl script that is generated from @file{automake.in}.
7080 Here is how this is handled:
7083 bin_SCRIPTS = automake
7084 CLEANFILES = $(bin_SCRIPTS)
7085 EXTRA_DIST = automake.in
7087 do_subst = sed -e 's,[@@]datadir[@@],$(datadir),g' \
7088 -e 's,[@@]PERL[@@],$(PERL),g' \
7089 -e 's,[@@]PACKAGE[@@],$(PACKAGE),g' \
7090 -e 's,[@@]VERSION[@@],$(VERSION),g' \
7093 automake: automake.in Makefile
7094 $(do_subst) < $(srcdir)/automake.in > automake
7098 Such scripts for which a build rule has been supplied need to be
7099 deleted explicitly using @code{CLEANFILES} (@pxref{Clean}), and their
7100 sources have to be distributed, usually with @code{EXTRA_DIST}
7101 (@pxref{Basics of Distribution}).
7103 Another common way to build scripts is to process them from
7104 @file{configure} with @code{AC_CONFIG_FILES}. In this situation
7105 Automake knows which files should be cleaned and distributed, and what
7106 the rebuild rules should look like.
7108 For instance if @file{configure.ac} contains
7111 AC_CONFIG_FILES([src/my_script], [chmod +x src/my_script])
7115 to build @file{src/my_script} from @file{src/my_script.in}, then a
7116 @file{src/Makefile.am} to install this script in @code{$(bindir)} can
7120 bin_SCRIPTS = my_script
7121 CLEANFILES = $(bin_SCRIPTS)
7125 There is no need for @code{EXTRA_DIST} or any build rule: Automake
7126 infers them from @code{AC_CONFIG_FILES} (@pxref{Requirements}).
7127 @code{CLEANFILES} is still useful, because by default Automake will
7128 clean targets of @code{AC_CONFIG_FILES} in @code{distclean}, not
7131 Although this looks simpler, building scripts this way has one
7132 drawback: directory variables such as @code{$(datadir)} are not fully
7133 expanded and may refer to other directory variables.
7136 @section Header files
7138 @cindex @code{_HEADERS} primary, defined
7139 @cindex @code{HEADERS} primary, defined
7140 @cindex Primary variable, @code{HEADERS}
7142 @vindex noinst_HEADERS
7143 @cindex @code{HEADERS}, installation directories
7144 @cindex Installing headers
7145 @vindex include_HEADERS
7146 @vindex oldinclude_HEADERS
7147 @vindex pkginclude_HEADERS
7150 Header files that must be installed are specified by the
7151 @code{HEADERS} family of variables. Headers can be installed in
7152 @code{includedir}, @code{oldincludedir}, @code{pkgincludedir} or any
7153 other directory you may have defined (@pxref{Uniform}). For instance,
7156 include_HEADERS = foo.h bar/bar.h
7160 will install the two files as @file{$(includedir)/foo.h} and
7161 @file{$(includedir)/bar.h}.
7163 The @code{nobase_} prefix is also supported,
7166 nobase_include_HEADERS = foo.h bar/bar.h
7170 will install the two files as @file{$(includedir)/foo.h} and
7171 @file{$(includedir)/bar/bar.h} (@pxref{Alternative}).
7173 @vindex noinst_HEADERS
7174 Usually, only header files that accompany installed libraries need to
7175 be installed. Headers used by programs or convenience libraries are
7176 not installed. The @code{noinst_HEADERS} variable can be used for
7177 such headers. However when the header actually belongs to a single
7178 convenience library or program, we recommend listing it in the
7179 program's or library's @code{_SOURCES} variable (@pxref{Program
7180 Sources}) instead of in @code{noinst_HEADERS}. This is clearer for
7181 the @file{Makefile.am} reader. @code{noinst_HEADERS} would be the
7182 right variable to use in a directory containing only headers and no
7183 associated library or program.
7185 All header files must be listed somewhere; in a @code{_SOURCES}
7186 variable or in a @code{_HEADERS} variable. Missing ones will not
7187 appear in the distribution.
7189 For header files that are built and must not be distributed, use the
7190 @code{nodist_} prefix as in @code{nodist_include_HEADERS} or
7191 @code{nodist_prog_SOURCES}. If these generated headers are needed
7192 during the build, you must also ensure they exist before they are
7193 used (@pxref{Sources}).
7197 @section Architecture-independent data files
7199 @cindex @code{_DATA} primary, defined
7200 @cindex @code{DATA} primary, defined
7201 @cindex Primary variable, @code{DATA}
7204 Automake supports the installation of miscellaneous data files using the
7205 @code{DATA} family of variables.
7209 @vindex sysconf_DATA
7210 @vindex sharedstate_DATA
7211 @vindex localstate_DATA
7212 @vindex pkgdata_DATA
7214 Such data can be installed in the directories @code{datadir},
7215 @code{sysconfdir}, @code{sharedstatedir}, @code{localstatedir}, or
7218 By default, data files are @emph{not} included in a distribution. Of
7219 course, you can use the @code{dist_} prefix to change this on a
7222 Here is how Automake declares its auxiliary data files:
7225 dist_pkgdata_DATA = clean-kr.am clean.am @dots{}
7230 @section Built Sources
7232 Because Automake's automatic dependency tracking works as a side-effect
7233 of compilation (@pxref{Dependencies}) there is a bootstrap issue: a
7234 target should not be compiled before its dependencies are made, but
7235 these dependencies are unknown until the target is first compiled.
7237 Ordinarily this is not a problem, because dependencies are distributed
7238 sources: they preexist and do not need to be built. Suppose that
7239 @file{foo.c} includes @file{foo.h}. When it first compiles
7240 @file{foo.o}, @command{make} only knows that @file{foo.o} depends on
7241 @file{foo.c}. As a side-effect of this compilation @command{depcomp}
7242 records the @file{foo.h} dependency so that following invocations of
7243 @command{make} will honor it. In these conditions, it's clear there is
7244 no problem: either @file{foo.o} doesn't exist and has to be built
7245 (regardless of the dependencies), or accurate dependencies exist and
7246 they can be used to decide whether @file{foo.o} should be rebuilt.
7248 It's a different story if @file{foo.h} doesn't exist by the first
7249 @command{make} run. For instance, there might be a rule to build
7250 @file{foo.h}. This time @file{file.o}'s build will fail because the
7251 compiler can't find @file{foo.h}. @command{make} failed to trigger the
7252 rule to build @file{foo.h} first by lack of dependency information.
7254 @vindex BUILT_SOURCES
7255 @cindex @code{BUILT_SOURCES}, defined
7257 The @code{BUILT_SOURCES} variable is a workaround for this problem. A
7258 source file listed in @code{BUILT_SOURCES} is made on @samp{make all}
7259 or @samp{make check} (or even @samp{make install}) before other
7260 targets are processed. However, such a source file is not
7261 @emph{compiled} unless explicitly requested by mentioning it in some
7262 other @code{_SOURCES} variable.
7264 So, to conclude our introductory example, we could use
7265 @samp{BUILT_SOURCES = foo.h} to ensure @file{foo.h} gets built before
7266 any other target (including @file{foo.o}) during @samp{make all} or
7269 @code{BUILT_SOURCES} is actually a bit of a misnomer, as any file which
7270 must be created early in the build process can be listed in this
7271 variable. Moreover, all built sources do not necessarily have to be
7272 listed in @code{BUILT_SOURCES}. For instance, a generated @file{.c} file
7273 doesn't need to appear in @code{BUILT_SOURCES} (unless it is included by
7274 another source), because it's a known dependency of the associated
7277 It might be important to emphasize that @code{BUILT_SOURCES} is
7278 honored only by @samp{make all}, @samp{make check} and @samp{make
7279 install}. This means you cannot build a specific target (e.g.,
7280 @samp{make foo}) in a clean tree if it depends on a built source.
7281 However it will succeed if you have run @samp{make all} earlier,
7282 because accurate dependencies are already available.
7284 The next section illustrates and discusses the handling of built sources
7288 * Built Sources Example:: Several ways to handle built sources.
7291 @node Built Sources Example
7292 @subsection Built Sources Example
7294 Suppose that @file{foo.c} includes @file{bindir.h}, which is
7295 installation-dependent and not distributed: it needs to be built. Here
7296 @file{bindir.h} defines the preprocessor macro @code{bindir} to the
7297 value of the @command{make} variable @code{bindir} (inherited from
7300 We suggest several implementations below. It's not meant to be an
7301 exhaustive listing of all ways to handle built sources, but it will give
7302 you a few ideas if you encounter this issue.
7304 @subsubheading First Try
7306 This first implementation will illustrate the bootstrap issue mentioned
7307 in the previous section (@pxref{Sources}).
7309 Here is a tentative @file{Makefile.am}.
7315 nodist_foo_SOURCES = bindir.h
7316 CLEANFILES = bindir.h
7318 echo '#define bindir "$(bindir)"' >$@@
7321 This setup doesn't work, because Automake doesn't know that @file{foo.c}
7322 includes @file{bindir.h}. Remember, automatic dependency tracking works
7323 as a side-effect of compilation, so the dependencies of @file{foo.o} will
7324 be known only after @file{foo.o} has been compiled (@pxref{Dependencies}).
7325 The symptom is as follows.
7329 source='foo.c' object='foo.o' libtool=no \
7330 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
7331 depmode=gcc /bin/sh ./depcomp \
7332 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
7333 foo.c:2: bindir.h: No such file or directory
7334 make: *** [foo.o] Error 1
7337 In this example @file{bindir.h} is not distributed nor installed, and
7338 it is not even being built on-time. One may wonder if the
7339 @samp{nodist_foo_SOURCES = bindir.h} line has any use at all. This
7340 line simply states that @file{bindir.h} is a source of @code{foo}, so
7341 for instance, it should be inspected while generating tags
7342 (@pxref{Tags}). In other words, it does not help our present problem,
7343 and the build would fail identically without it.
7345 @subsubheading Using @code{BUILT_SOURCES}
7347 A solution is to require @file{bindir.h} to be built before anything
7348 else. This is what @code{BUILT_SOURCES} is meant for (@pxref{Sources}).
7353 nodist_foo_SOURCES = bindir.h
7354 BUILT_SOURCES = bindir.h
7355 CLEANFILES = bindir.h
7357 echo '#define bindir "$(bindir)"' >$@@
7360 See how @file{bindir.h} gets built first:
7364 echo '#define bindir "/usr/local/bin"' >bindir.h
7366 make[1]: Entering directory `/home/adl/tmp'
7367 source='foo.c' object='foo.o' libtool=no \
7368 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
7369 depmode=gcc /bin/sh ./depcomp \
7370 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
7371 gcc -g -O2 -o foo foo.o
7372 make[1]: Leaving directory `/home/adl/tmp'
7375 However, as said earlier, @code{BUILT_SOURCES} applies only to the
7376 @code{all}, @code{check}, and @code{install} targets. It still fails
7377 if you try to run @samp{make foo} explicitly:
7381 test -z "bindir.h" || rm -f bindir.h
7382 test -z "foo" || rm -f foo
7384 % : > .deps/foo.Po # Suppress previously recorded dependencies
7386 source='foo.c' object='foo.o' libtool=no \
7387 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
7388 depmode=gcc /bin/sh ./depcomp \
7389 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
7390 foo.c:2: bindir.h: No such file or directory
7391 make: *** [foo.o] Error 1
7394 @subsubheading Recording Dependencies manually
7396 Usually people are happy enough with @code{BUILT_SOURCES} because they
7397 never build targets such as @samp{make foo} before @samp{make all}, as
7398 in the previous example. However if this matters to you, you can
7399 avoid @code{BUILT_SOURCES} and record such dependencies explicitly in
7400 the @file{Makefile.am}.
7405 nodist_foo_SOURCES = bindir.h
7406 foo.$(OBJEXT): bindir.h
7407 CLEANFILES = bindir.h
7409 echo '#define bindir "$(bindir)"' >$@@
7412 You don't have to list @emph{all} the dependencies of @file{foo.o}
7413 explicitly, only those that might need to be built. If a dependency
7414 already exists, it will not hinder the first compilation and will be
7415 recorded by the normal dependency tracking code. (Note that after
7416 this first compilation the dependency tracking code will also have
7417 recorded the dependency between @file{foo.o} and
7418 @file{bindir.h}; so our explicit dependency is really useful to
7419 the first build only.)
7421 Adding explicit dependencies like this can be a bit dangerous if you are
7422 not careful enough. This is due to the way Automake tries not to
7423 overwrite your rules (it assumes you know better than it).
7424 @samp{foo.$(OBJEXT): bindir.h} supersedes any rule Automake may want to
7425 output to build @samp{foo.$(OBJEXT)}. It happens to work in this case
7426 because Automake doesn't have to output any @samp{foo.$(OBJEXT):}
7427 target: it relies on a suffix rule instead (i.e., @samp{.c.$(OBJEXT):}).
7428 Always check the generated @file{Makefile.in} if you do this.
7430 @subsubheading Build @file{bindir.h} from @file{configure}
7432 It's possible to define this preprocessor macro from @file{configure},
7433 either in @file{config.h} (@pxref{Defining Directories, , Defining
7434 Directories, autoconf, The Autoconf Manual}), or by processing a
7435 @file{bindir.h.in} file using @code{AC_CONFIG_FILES}
7436 (@pxref{Configuration Actions, ,Configuration Actions, autoconf, The
7439 At this point it should be clear that building @file{bindir.h} from
7440 @file{configure} works well for this example. @file{bindir.h} will exist
7441 before you build any target, hence will not cause any dependency issue.
7443 The Makefile can be shrunk as follows. We do not even have to mention
7451 However, it's not always possible to build sources from
7452 @file{configure}, especially when these sources are generated by a tool
7453 that needs to be built first.
7455 @subsubheading Build @file{bindir.c}, not @file{bindir.h}.
7457 Another attractive idea is to define @code{bindir} as a variable or
7458 function exported from @file{bindir.o}, and build @file{bindir.c}
7459 instead of @file{bindir.h}.
7462 noinst_PROGRAMS = foo
7463 foo_SOURCES = foo.c bindir.h
7464 nodist_foo_SOURCES = bindir.c
7465 CLEANFILES = bindir.c
7467 echo 'const char bindir[] = "$(bindir)";' >$@@
7470 @file{bindir.h} contains just the variable's declaration and doesn't
7471 need to be built, so it won't cause any trouble. @file{bindir.o} is
7472 always dependent on @file{bindir.c}, so @file{bindir.c} will get built
7475 @subsubheading Which is best?
7477 There is no panacea, of course. Each solution has its merits and
7480 You cannot use @code{BUILT_SOURCES} if the ability to run @samp{make
7481 foo} on a clean tree is important to you.
7483 You won't add explicit dependencies if you are leery of overriding
7484 an Automake rule by mistake.
7486 Building files from @file{./configure} is not always possible, neither
7487 is converting @file{.h} files into @file{.c} files.
7490 @node Other GNU Tools
7491 @chapter Other GNU Tools
7493 Since Automake is primarily intended to generate @file{Makefile.in}s for
7494 use in GNU programs, it tries hard to interoperate with other GNU tools.
7497 * Emacs Lisp:: Emacs Lisp
7500 * Java:: Java bytecode compilation (deprecated)
7508 @cindex @code{_LISP} primary, defined
7509 @cindex @code{LISP} primary, defined
7510 @cindex Primary variable, @code{LISP}
7516 Automake provides some support for Emacs Lisp. The @code{LISP} primary
7517 is used to hold a list of @file{.el} files. Possible prefixes for this
7518 primary are @code{lisp_} and @code{noinst_}. Note that if
7519 @code{lisp_LISP} is defined, then @file{configure.ac} must run
7520 @code{AM_PATH_LISPDIR} (@pxref{Macros}).
7522 @vindex dist_lisp_LISP
7523 @vindex dist_noinst_LISP
7524 Lisp sources are not distributed by default. You can prefix the
7525 @code{LISP} primary with @code{dist_}, as in @code{dist_lisp_LISP} or
7526 @code{dist_noinst_LISP}, to indicate that these files should be
7529 Automake will byte-compile all Emacs Lisp source files using the Emacs
7530 found by @code{AM_PATH_LISPDIR}, if any was found.
7532 Byte-compiled Emacs Lisp files are not portable among all versions of
7533 Emacs, so it makes sense to turn this off if you expect sites to have
7534 more than one version of Emacs installed. Furthermore, many packages
7535 don't actually benefit from byte-compilation. Still, we recommend
7536 that you byte-compile your Emacs Lisp sources. It is probably better
7537 for sites with strange setups to cope for themselves than to make the
7538 installation less nice for everybody else.
7540 There are two ways to avoid byte-compiling. Historically, we have
7541 recommended the following construct.
7544 lisp_LISP = file1.el file2.el
7549 @code{ELCFILES} is an internal Automake variable that normally lists
7550 all @file{.elc} files that must be byte-compiled. Automake defines
7551 @code{ELCFILES} automatically from @code{lisp_LISP}. Emptying this
7552 variable explicitly prevents byte-compilation.
7554 Since Automake 1.8, we now recommend using @code{lisp_DATA} instead:
7556 @c Keep in sync with primary-prefix-couples-documented-valid.sh
7558 lisp_DATA = file1.el file2.el
7561 Note that these two constructs are not equivalent. @code{_LISP} will
7562 not install a file if Emacs is not installed, while @code{_DATA} will
7563 always install its files.
7568 @cindex GNU Gettext support
7569 @cindex Gettext support
7570 @cindex Support for GNU Gettext
7572 If @code{AM_GNU_GETTEXT} is seen in @file{configure.ac}, then Automake
7573 turns on support for GNU gettext, a message catalog system for
7574 internationalization
7575 (@pxref{Top, , Introduction, gettext, GNU gettext utilities}).
7577 The @code{gettext} support in Automake requires the addition of one or
7578 two subdirectories to the package: @file{po} and possibly also @file{intl}.
7579 The latter is needed if @code{AM_GNU_GETTEXT} is not invoked with the
7580 @samp{external} argument, or if @code{AM_GNU_GETTEXT_INTL_SUBDIR} is used.
7581 Automake ensures that these directories exist and are mentioned in
7587 Automake provides support for GNU Libtool (@pxref{Top, , Introduction,
7588 libtool, The Libtool Manual}) with the @code{LTLIBRARIES} primary.
7589 @xref{A Shared Library}.
7593 @section Java bytecode compilation (deprecated)
7595 @cindex @code{_JAVA} primary, defined
7596 @cindex @code{JAVA} primary, defined
7597 @cindex Primary variable, @code{JAVA}
7598 @cindex Java to bytecode, compilation
7599 @cindex Compilation of Java to bytecode
7601 Automake provides some minimal support for Java bytecode compilation with
7602 the @code{JAVA} primary (in addition to the support for compiling Java to
7603 native machine code; @pxref{Java Support with gcj}). Note however that
7604 @emph{the interface and most features described here are deprecated}; the
7605 next automake release will strive to provide a better and cleaner
7606 interface, which however @emph{won't be backward-compatible}; the present
7607 interface will probably be removed altogether in future automake releases
7608 (1.13 or later), so don't use it in new code.
7610 Any @file{.java} files listed in a @code{_JAVA} variable will be
7611 compiled with @code{JAVAC} at build time. By default, @file{.java}
7612 files are not included in the distribution, you should use the
7613 @code{dist_} prefix to distribute them.
7615 Here is a typical setup for distributing @file{.java} files and
7616 installing the @file{.class} files resulting from their compilation.
7618 @c Keep in sync with primary-prefix-couples-documented-valid.sh
7620 javadir = $(datadir)/java
7621 dist_java_JAVA = a.java b.java @dots{}
7624 @cindex @code{JAVA} restrictions
7625 @cindex Restrictions for @code{JAVA}
7627 Currently Automake enforces the restriction that only one @code{_JAVA}
7628 primary can be used in a given @file{Makefile.am}. The reason for this
7629 restriction is that, in general, it isn't possible to know which
7630 @file{.class} files were generated from which @file{.java} files, so
7631 it would be impossible to know which files to install where. For
7632 instance, a @file{.java} file can define multiple classes; the resulting
7633 @file{.class} file names cannot be predicted without parsing the
7636 There are a few variables that are used when compiling Java sources:
7640 The name of the Java compiler. This defaults to @samp{javac}.
7643 The flags to pass to the compiler. This is considered to be a user
7644 variable (@pxref{User Variables}).
7647 More flags to pass to the Java compiler. This, and not
7648 @code{JAVACFLAGS}, should be used when it is necessary to put Java
7649 compiler flags into @file{Makefile.am}.
7652 The value of this variable is passed to the @option{-d} option to
7653 @code{javac}. It defaults to @samp{$(top_builddir)}.
7656 This variable is a shell expression that is used to set the
7657 @env{CLASSPATH} environment variable on the @code{javac} command line.
7658 (In the future we will probably handle class path setting differently.)
7665 @cindex @code{_PYTHON} primary, defined
7666 @cindex @code{PYTHON} primary, defined
7667 @cindex Primary variable, @code{PYTHON}
7670 Automake provides support for Python compilation with the
7671 @code{PYTHON} primary. A typical setup is to call
7672 @code{AM_PATH_PYTHON} in @file{configure.ac} and use a line like the
7673 following in @file{Makefile.am}:
7676 python_PYTHON = tree.py leave.py
7679 Any files listed in a @code{_PYTHON} variable will be byte-compiled
7680 with @command{py-compile} at install time. @command{py-compile}
7681 actually creates both standard (@file{.pyc}) and optimized
7682 (@file{.pyo}) byte-compiled versions of the source files. Note that
7683 because byte-compilation occurs at install time, any files listed in
7684 @code{noinst_PYTHON} will not be compiled. Python source files are
7685 included in the distribution by default, prepend @code{nodist_} (as in
7686 @code{nodist_python_PYTHON}) to omit them.
7688 Automake ships with an Autoconf macro called @code{AM_PATH_PYTHON}
7689 that will determine some Python-related directory variables (see
7690 below). If you have called @code{AM_PATH_PYTHON} from
7691 @file{configure.ac}, then you may use the variables
7692 @c Keep in sync with primary-prefix-couples-documented-valid.sh
7693 @code{python_PYTHON} or @code{pkgpython_PYTHON} to list Python source
7694 files in your @file{Makefile.am}, depending on where you want your files
7695 installed (see the definitions of @code{pythondir} and
7696 @code{pkgpythondir} below).
7698 @defmac AM_PATH_PYTHON (@ovar{version}, @ovar{action-if-found},
7699 @ovar{action-if-not-found})
7701 Search for a Python interpreter on the system. This macro takes three
7702 optional arguments. The first argument, if present, is the minimum
7703 version of Python required for this package: @code{AM_PATH_PYTHON}
7704 will skip any Python interpreter that is older than @var{version}.
7705 If an interpreter is found and satisfies @var{version}, then
7706 @var{action-if-found} is run. Otherwise, @var{action-if-not-found} is
7709 If @var{action-if-not-found} is not specified, as in the following
7710 example, the default is to abort @command{configure}.
7713 AM_PATH_PYTHON([2.2])
7717 This is fine when Python is an absolute requirement for the package.
7718 If Python >= 2.5 was only @emph{optional} to the package,
7719 @code{AM_PATH_PYTHON} could be called as follows.
7722 AM_PATH_PYTHON([2.5],, [:])
7725 If the @env{PYTHON} variable is set when @code{AM_PATH_PYTHON} is
7726 called, then that will be the only Python interpreter that is tried.
7728 @code{AM_PATH_PYTHON} creates the following output variables based on
7729 the Python installation found during configuration.
7734 The name of the Python executable, or @samp{:} if no suitable
7735 interpreter could be found.
7737 Assuming @var{action-if-not-found} is used (otherwise @file{./configure}
7738 will abort if Python is absent), the value of @code{PYTHON} can be used
7739 to setup a conditional in order to disable the relevant part of a build
7743 AM_PATH_PYTHON(,, [:])
7744 AM_CONDITIONAL([HAVE_PYTHON], [test "$PYTHON" != :])
7747 @item PYTHON_VERSION
7748 The Python version number, in the form @var{major}.@var{minor}
7749 (e.g., @samp{2.5}). This is currently the value of
7750 @samp{sys.version[:3]}.
7753 The string @samp{$@{prefix@}}. This term may be used in future work
7754 that needs the contents of Python's @samp{sys.prefix}, but general
7755 consensus is to always use the value from @command{configure}.
7757 @item PYTHON_EXEC_PREFIX
7758 The string @samp{$@{exec_prefix@}}. This term may be used in future work
7759 that needs the contents of Python's @samp{sys.exec_prefix}, but general
7760 consensus is to always use the value from @command{configure}.
7762 @item PYTHON_PLATFORM
7763 The canonical name used by Python to describe the operating system, as
7764 given by @samp{sys.platform}. This value is sometimes needed when
7765 building Python extensions.
7768 The directory name for the @file{site-packages} subdirectory of the
7769 standard Python install tree.
7772 This is the directory under @code{pythondir} that is named after the
7773 package. That is, it is @samp{$(pythondir)/$(PACKAGE)}. It is provided
7777 This is the directory where Python extension modules (shared libraries)
7778 should be installed. An extension module written in C could be declared
7779 as follows to Automake:
7781 @c Keep in sync with primary-prefix-couples-documented-valid.sh
7783 pyexec_LTLIBRARIES = quaternion.la
7784 quaternion_la_SOURCES = quaternion.c support.c support.h
7785 quaternion_la_LDFLAGS = -avoid-version -module
7789 This is a convenience variable that is defined as
7790 @samp{$(pyexecdir)/$(PACKAGE)}.
7793 All of these directory variables have values that start with either
7794 @samp{$@{prefix@}} or @samp{$@{exec_prefix@}} unexpanded. This works
7795 fine in @file{Makefiles}, but it makes these variables hard to use in
7796 @file{configure}. This is mandated by the GNU coding standards, so
7797 that the user can run @samp{make prefix=/foo install}. The Autoconf
7798 manual has a section with more details on this topic
7799 (@pxref{Installation Directory Variables, , Installation Directory
7800 Variables, autoconf, The Autoconf Manual}). See also @ref{Hard-Coded
7805 @chapter Building documentation
7807 Currently Automake provides support for Texinfo and man pages.
7811 * Man Pages:: Man pages
7818 @cindex @code{_TEXINFOS} primary, defined
7819 @cindex @code{TEXINFOS} primary, defined
7820 @cindex Primary variable, @code{TEXINFOS}
7821 @cindex HTML output using Texinfo
7822 @cindex PDF output using Texinfo
7823 @cindex PS output using Texinfo
7824 @cindex DVI output using Texinfo
7826 @vindex info_TEXINFOS
7828 If the current directory contains Texinfo source, you must declare it
7829 with the @code{TEXINFOS} primary. Generally Texinfo files are converted
7830 into info, and thus the @code{info_TEXINFOS} variable is most commonly used
7831 here. Any Texinfo source file must end in the @file{.texi},
7832 @file{.txi}, or @file{.texinfo} extension. We recommend @file{.texi}
7835 Automake generates rules to build @file{.info}, @file{.dvi},
7836 @file{.ps}, @file{.pdf} and @file{.html} files from your Texinfo
7837 sources. Following the GNU Coding Standards, only the @file{.info}
7838 files are built by @samp{make all} and installed by @samp{make
7839 install} (unless you use @option{no-installinfo}, see below).
7840 Furthermore, @file{.info} files are automatically distributed so that
7841 Texinfo is not a prerequisite for installing your package.
7847 @trindex install-dvi
7848 @trindex install-html
7849 @trindex install-pdf
7851 Other documentation formats can be built on request by @samp{make
7852 dvi}, @samp{make ps}, @samp{make pdf} and @samp{make html}, and they
7853 can be installed with @samp{make install-dvi}, @samp{make install-ps},
7854 @samp{make install-pdf} and @samp{make install-html} explicitly.
7855 @samp{make uninstall} will remove everything: the Texinfo
7856 documentation installed by default as well as all the above optional
7859 All of these targets can be extended using @samp{-local} rules
7860 (@pxref{Extending}).
7862 @cindex Texinfo flag, @code{VERSION}
7863 @cindex Texinfo flag, @code{UPDATED}
7864 @cindex Texinfo flag, @code{EDITION}
7865 @cindex Texinfo flag, @code{UPDATED-MONTH}
7867 @cindex @code{VERSION} Texinfo flag
7868 @cindex @code{UPDATED} Texinfo flag
7869 @cindex @code{EDITION} Texinfo flag
7870 @cindex @code{UPDATED-MONTH} Texinfo flag
7872 @cindex @file{mdate-sh}
7874 If the @file{.texi} file @code{@@include}s @file{version.texi}, then
7875 that file will be automatically generated. The file @file{version.texi}
7876 defines four Texinfo flag you can reference using
7877 @code{@@value@{EDITION@}}, @code{@@value@{VERSION@}},
7878 @code{@@value@{UPDATED@}}, and @code{@@value@{UPDATED-MONTH@}}.
7883 Both of these flags hold the version number of your program. They are
7884 kept separate for clarity.
7887 This holds the date the primary @file{.texi} file was last modified.
7890 This holds the name of the month in which the primary @file{.texi} file
7894 The @file{version.texi} support requires the @command{mdate-sh}
7895 script; this script is supplied with Automake and automatically
7896 included when @command{automake} is invoked with the
7897 @option{--add-missing} option.
7899 If you have multiple Texinfo files, and you want to use the
7900 @file{version.texi} feature, then you have to have a separate version
7901 file for each Texinfo file. Automake will treat any include in a
7902 Texinfo file that matches @file{vers*.texi} just as an automatically
7903 generated version file.
7905 Sometimes an info file actually depends on more than one @file{.texi}
7906 file. For instance, in GNU Hello, @file{hello.texi} includes the file
7907 @file{fdl.texi}. You can tell Automake about these dependencies using
7908 the @code{@var{texi}_TEXINFOS} variable. Here is how GNU Hello does it:
7913 info_TEXINFOS = hello.texi
7914 hello_TEXINFOS = fdl.texi
7917 @cindex @file{texinfo.tex}
7919 By default, Automake requires the file @file{texinfo.tex} to appear in
7920 the same directory as the @file{Makefile.am} file that lists the
7921 @file{.texi} files. If you used @code{AC_CONFIG_AUX_DIR} in
7922 @file{configure.ac} (@pxref{Input, , Finding `configure' Input,
7923 autoconf, The Autoconf Manual}), then @file{texinfo.tex} is looked for
7924 there. In both cases, @command{automake} then supplies @file{texinfo.tex} if
7925 @option{--add-missing} is given, and takes care of its distribution.
7926 However, if you set the @code{TEXINFO_TEX} variable (see below),
7927 it overrides the location of the file and turns off its installation
7928 into the source as well as its distribution.
7930 The option @option{no-texinfo.tex} can be used to eliminate the
7931 requirement for the file @file{texinfo.tex}. Use of the variable
7932 @code{TEXINFO_TEX} is preferable, however, because that allows the
7933 @code{dvi}, @code{ps}, and @code{pdf} targets to still work.
7935 @cindex Option, @code{no-installinfo}
7936 @cindex Target, @code{install-info}
7937 @cindex @code{install-info} target
7938 @cindex @code{no-installinfo} option
7940 @opindex no-installinfo
7941 @trindex install-info
7943 Automake generates an @code{install-info} rule; some people apparently
7944 use this. By default, info pages are installed by @samp{make
7945 install}, so running @code{make install-info} is pointless. This can
7946 be prevented via the @code{no-installinfo} option. In this case,
7947 @file{.info} files are not installed by default, and user must
7948 request this explicitly using @samp{make install-info}.
7950 @vindex AM_UPDATE_INFO_DIR
7951 By default, @code{make install-info} and @code{make install-info}
7952 will try to run the @command{install-info} program (if available)
7953 to update (or create) the @file{@code{$@{infodir@}}/dir} index.
7954 If this is undesired, it can be prevented by exporting the
7955 @code{AM_UPDATE_INFO_DIR} variable to "@code{no}".
7957 The following variables are used by the Texinfo build rules.
7961 The name of the program invoked to build @file{.info} files. This
7962 variable is defined by Automake. If the @command{makeinfo} program is
7963 found on the system then it will be used by default; otherwise
7964 @command{missing} will be used instead.
7967 The command invoked to build @file{.html} files. Automake
7968 defines this to @samp{$(MAKEINFO) --html}.
7971 User flags passed to each invocation of @samp{$(MAKEINFO)} and
7972 @samp{$(MAKEINFOHTML)}. This user variable (@pxref{User Variables}) is
7973 not expected to be defined in any @file{Makefile}; it can be used by
7974 users to pass extra flags to suit their needs.
7976 @item AM_MAKEINFOFLAGS
7977 @itemx AM_MAKEINFOHTMLFLAGS
7978 Maintainer flags passed to each @command{makeinfo} invocation. Unlike
7979 @code{MAKEINFOFLAGS}, these variables are meant to be defined by
7980 maintainers in @file{Makefile.am}. @samp{$(AM_MAKEINFOFLAGS)} is
7981 passed to @code{makeinfo} when building @file{.info} files; and
7982 @samp{$(AM_MAKEINFOHTMLFLAGS)} is used when building @file{.html}
7985 @c Keep in sync with txinfo21.sh
7986 For instance, the following setting can be used to obtain one single
7987 @file{.html} file per manual, without node separators.
7989 AM_MAKEINFOHTMLFLAGS = --no-headers --no-split
7992 @code{AM_MAKEINFOHTMLFLAGS} defaults to @samp{$(AM_MAKEINFOFLAGS)}.
7993 This means that defining @code{AM_MAKEINFOFLAGS} without defining
7994 @code{AM_MAKEINFOHTMLFLAGS} will impact builds of both @file{.info}
7995 and @file{.html} files.
7998 The name of the command that converts a @file{.texi} file into a
7999 @file{.dvi} file. This defaults to @samp{texi2dvi}, a script that ships
8000 with the Texinfo package.
8003 The name of the command that translates a @file{.texi} file into a
8004 @file{.pdf} file. This defaults to @samp{$(TEXI2DVI) --pdf --batch}.
8007 The name of the command that builds a @file{.ps} file out of a
8008 @file{.dvi} file. This defaults to @samp{dvips}.
8012 If your package has Texinfo files in many directories, you can use the
8013 variable @code{TEXINFO_TEX} to tell Automake where to find the canonical
8014 @file{texinfo.tex} for your package. The value of this variable should
8015 be the relative path from the current @file{Makefile.am} to
8019 TEXINFO_TEX = ../doc/texinfo.tex
8027 @cindex @code{_MANS} primary, defined
8028 @cindex @code{MANS} primary, defined
8029 @cindex Primary variable, @code{MANS}
8033 A package can also include man pages (but see the GNU standards on this
8034 matter, @ref{Man Pages, , , standards, The GNU Coding Standards}.) Man
8035 pages are declared using the @code{MANS} primary. Generally the
8036 @code{man_MANS} variable is used. Man pages are automatically installed in
8037 the correct subdirectory of @code{mandir}, based on the file extension.
8039 File extensions such as @file{.1c} are handled by looking for the valid
8040 part of the extension and using that to determine the correct
8041 subdirectory of @code{mandir}. Valid section names are the digits
8042 @samp{0} through @samp{9}, and the letters @samp{l} and @samp{n}.
8044 Sometimes developers prefer to name a man page something like
8045 @file{foo.man} in the source, and then rename it to have the correct
8046 suffix, for example @file{foo.1}, when installing the file. Automake
8047 also supports this mode. For a valid section named @var{section},
8048 there is a corresponding directory named @samp{man@var{section}dir},
8049 and a corresponding @code{_MANS} variable. Files listed in such a
8050 variable are installed in the indicated section. If the file already
8051 has a valid suffix, then it is installed as-is; otherwise the file
8052 suffix is changed to match the section.
8054 For instance, consider this example:
8056 man1_MANS = rename.man thesame.1 alsothesame.1c
8060 In this case, @file{rename.man} will be renamed to @file{rename.1} when
8061 installed, but the other files will keep their names.
8063 @cindex Target, @code{install-man}
8064 @cindex Option, @option{no-installman}
8065 @cindex @code{install-man} target
8066 @cindex @option{no-installman} option
8067 @opindex no-installman
8068 @trindex install-man
8070 By default, man pages are installed by @samp{make install}. However,
8071 since the GNU project does not require man pages, many maintainers do
8072 not expend effort to keep the man pages up to date. In these cases, the
8073 @option{no-installman} option will prevent the man pages from being
8074 installed by default. The user can still explicitly install them via
8075 @samp{make install-man}.
8077 For fast installation, with many files it is preferable to use
8078 @samp{man@var{section}_MANS} over @samp{man_MANS} as well as files that
8079 do not need to be renamed.
8081 Man pages are not currently considered to be source, because it is not
8082 uncommon for man pages to be automatically generated. Therefore they
8083 are not automatically included in the distribution. However, this can
8084 be changed by use of the @code{dist_} prefix. For instance here is
8085 how to distribute and install the two man pages of GNU @command{cpio}
8086 (which includes both Texinfo documentation and man pages):
8089 dist_man_MANS = cpio.1 mt.1
8092 The @code{nobase_} prefix is meaningless for man pages and is
8096 @cindex @code{notrans_} prefix
8097 @cindex Man page renaming, avoiding
8098 @cindex Avoiding man page renaming
8100 Executables and manpages may be renamed upon installation
8101 (@pxref{Renaming}). For manpages this can be avoided by use of the
8102 @code{notrans_} prefix. For instance, suppose an executable @samp{foo}
8103 allowing to access a library function @samp{foo} from the command line.
8104 The way to avoid renaming of the @file{foo.3} manpage is:
8108 notrans_man_MANS = foo.3
8111 @cindex @code{notrans_} and @code{dist_} or @code{nodist_}
8112 @cindex @code{dist_} and @code{notrans_}
8113 @cindex @code{nodist_} and @code{notrans_}
8115 @samp{notrans_} must be specified first when used in conjunction with
8116 either @samp{dist_} or @samp{nodist_} (@pxref{Fine-grained Distribution
8117 Control}). For instance:
8120 notrans_dist_man3_MANS = bar.3
8124 @chapter What Gets Installed
8126 @cindex Installation support
8127 @cindex @samp{make install} support
8129 Naturally, Automake handles the details of actually installing your
8130 program once it has been built. All files named by the various
8131 primaries are automatically installed in the appropriate places when the
8132 user runs @samp{make install}.
8135 * Basics of Installation:: What gets installed where
8136 * The Two Parts of Install:: Installing data and programs separately
8137 * Extending Installation:: Adding your own rules for installation
8138 * Staged Installs:: Installation in a temporary location
8139 * Install Rules for the User:: Useful additional rules
8142 @node Basics of Installation
8143 @section Basics of Installation
8145 A file named in a primary is installed by copying the built file into
8146 the appropriate directory. The base name of the file is used when
8150 bin_PROGRAMS = hello subdir/goodbye
8153 In this example, both @samp{hello} and @samp{goodbye} will be installed
8154 in @samp{$(bindir)}.
8156 Sometimes it is useful to avoid the basename step at install time. For
8157 instance, you might have a number of header files in subdirectories of
8158 the source tree that are laid out precisely how you want to install
8159 them. In this situation you can use the @code{nobase_} prefix to
8160 suppress the base name step. For example:
8163 nobase_include_HEADERS = stdio.h sys/types.h
8167 will install @file{stdio.h} in @samp{$(includedir)} and @file{types.h}
8168 in @samp{$(includedir)/sys}.
8170 For most file types, Automake will install multiple files at once, while
8171 avoiding command line length issues (@pxref{Length Limitations}). Since
8172 some @command{install} programs will not install the same file twice in
8173 one invocation, you may need to ensure that file lists are unique within
8174 one variable such as @samp{nobase_include_HEADERS} above.
8176 You should not rely on the order in which files listed in one variable
8177 are installed. Likewise, to cater for parallel make, you should not
8178 rely on any particular file installation order even among different
8179 file types (library dependencies are an exception here).
8182 @node The Two Parts of Install
8183 @section The Two Parts of Install
8185 Automake generates separate @code{install-data} and @code{install-exec}
8186 rules, in case the installer is installing on multiple machines that
8187 share directory structure---these targets allow the machine-independent
8188 parts to be installed only once. @code{install-exec} installs
8189 platform-dependent files, and @code{install-data} installs
8190 platform-independent files. The @code{install} target depends on both
8191 of these targets. While Automake tries to automatically segregate
8192 objects into the correct category, the @file{Makefile.am} author is, in
8193 the end, responsible for making sure this is done correctly.
8194 @trindex install-data
8195 @trindex install-exec
8197 @cindex Install, two parts of
8199 Variables using the standard directory prefixes @samp{data},
8200 @samp{info}, @samp{man}, @samp{include}, @samp{oldinclude},
8201 @samp{pkgdata}, or @samp{pkginclude} are installed by
8202 @code{install-data}.
8204 Variables using the standard directory prefixes @samp{bin},
8205 @samp{sbin}, @samp{libexec}, @samp{sysconf}, @samp{localstate},
8206 @samp{lib}, or @samp{pkglib} are installed by @code{install-exec}.
8208 For instance, @code{data_DATA} files are installed by @code{install-data},
8209 while @code{bin_PROGRAMS} files are installed by @code{install-exec}.
8211 Any variable using a user-defined directory prefix with
8212 @samp{exec} in the name (e.g.,
8213 @c Keep in sync with primary-prefix-couples-documented-valid.sh
8214 @code{myexecbin_PROGRAMS}) is installed by @code{install-exec}. All
8215 other user-defined prefixes are installed by @code{install-data}.
8217 @node Extending Installation
8218 @section Extending Installation
8220 It is possible to extend this mechanism by defining an
8221 @code{install-exec-local} or @code{install-data-local} rule. If these
8222 rules exist, they will be run at @samp{make install} time. These
8223 rules can do almost anything; care is required.
8224 @trindex install-exec-local
8225 @trindex install-data-local
8227 Automake also supports two install hooks, @code{install-exec-hook} and
8228 @code{install-data-hook}. These hooks are run after all other install
8229 rules of the appropriate type, exec or data, have completed. So, for
8230 instance, it is possible to perform post-installation modifications
8231 using an install hook. @xref{Extending}, for some examples.
8232 @cindex Install hook
8234 @node Staged Installs
8235 @section Staged Installs
8238 Automake generates support for the @code{DESTDIR} variable in all
8239 install rules. @code{DESTDIR} is used during the @samp{make install}
8240 step to relocate install objects into a staging area. Each object and
8241 path is prefixed with the value of @code{DESTDIR} before being copied
8242 into the install area. Here is an example of typical DESTDIR usage:
8245 mkdir /tmp/staging &&
8246 make DESTDIR=/tmp/staging install
8249 The @command{mkdir} command avoids a security problem if the attacker
8250 creates a symbolic link from @file{/tmp/staging} to a victim area;
8251 then @command{make} places install objects in a directory tree built under
8252 @file{/tmp/staging}. If @file{/gnu/bin/foo} and
8253 @file{/gnu/share/aclocal/foo.m4} are to be installed, the above command
8254 would install @file{/tmp/staging/gnu/bin/foo} and
8255 @file{/tmp/staging/gnu/share/aclocal/foo.m4}.
8257 This feature is commonly used to build install images and packages
8260 Support for @code{DESTDIR} is implemented by coding it directly into
8261 the install rules. If your @file{Makefile.am} uses a local install
8262 rule (e.g., @code{install-exec-local}) or an install hook, then you
8263 must write that code to respect @code{DESTDIR}.
8265 @xref{Makefile Conventions, , , standards, The GNU Coding Standards},
8266 for another usage example.
8268 @node Install Rules for the User
8269 @section Install Rules for the User
8271 Automake also generates rules for targets @code{uninstall},
8272 @code{installdirs}, and @code{install-strip}.
8274 @trindex installdirs
8275 @trindex install-strip
8277 Automake supports @code{uninstall-local} and @code{uninstall-hook}.
8278 There is no notion of separate uninstalls for ``exec'' and ``data'', as
8279 these features would not provide additional functionality.
8281 Note that @code{uninstall} is not meant as a replacement for a real
8286 @chapter What Gets Cleaned
8288 @cindex @samp{make clean} support
8290 The GNU Makefile Standards specify a number of different clean rules.
8291 @xref{Standard Targets, , Standard Targets for Users, standards,
8292 The GNU Coding Standards}.
8294 Generally the files that can be cleaned are determined automatically by
8295 Automake. Of course, Automake also recognizes some variables that can
8296 be defined to specify additional files to clean. These variables are
8297 @code{MOSTLYCLEANFILES}, @code{CLEANFILES}, @code{DISTCLEANFILES}, and
8298 @code{MAINTAINERCLEANFILES}.
8299 @vindex MOSTLYCLEANFILES
8301 @vindex DISTCLEANFILES
8302 @vindex MAINTAINERCLEANFILES
8304 @trindex mostlyclean-local
8305 @trindex clean-local
8306 @trindex distclean-local
8307 @trindex maintainer-clean-local
8308 When cleaning involves more than deleting some hard-coded list of
8309 files, it is also possible to supplement the cleaning rules with your
8310 own commands. Simply define a rule for any of the
8311 @code{mostlyclean-local}, @code{clean-local}, @code{distclean-local},
8312 or @code{maintainer-clean-local} targets (@pxref{Extending}). A common
8313 case is deleting a directory, for instance, a directory created by the
8321 Since @command{make} allows only one set of rules for a given target,
8322 a more extensible way of writing this is to use a separate target
8323 listed as a dependency:
8326 clean-local: clean-local-check
8327 .PHONY: clean-local-check
8332 As the GNU Standards aren't always explicit as to which files should
8333 be removed by which rule, we've adopted a heuristic that we believe
8334 was first formulated by Fran@,{c}ois Pinard:
8338 If @command{make} built it, and it is commonly something that one would
8339 want to rebuild (for instance, a @file{.o} file), then
8340 @code{mostlyclean} should delete it.
8343 Otherwise, if @command{make} built it, then @code{clean} should delete it.
8346 If @command{configure} built it, then @code{distclean} should delete it.
8349 If the maintainer built it (for instance, a @file{.info} file), then
8350 @code{maintainer-clean} should delete it. However
8351 @code{maintainer-clean} should not delete anything that needs to exist
8352 in order to run @samp{./configure && make}.
8355 We recommend that you follow this same set of heuristics in your
8360 @chapter What Goes in a Distribution
8363 * Basics of Distribution:: Files distributed by default
8364 * Fine-grained Distribution Control:: @code{dist_} and @code{nodist_} prefixes
8365 * The dist Hook:: A target for last-minute distribution changes
8366 * Checking the Distribution:: @samp{make distcheck} explained
8367 * The Types of Distributions:: A variety of formats and compression methods
8370 @node Basics of Distribution
8371 @section Basics of Distribution
8373 @cindex @samp{make dist}
8378 The @code{dist} rule in the generated @file{Makefile.in} can be used
8379 to generate a gzipped @code{tar} file and other flavors of archive for
8380 distribution. The file is named based on the @code{PACKAGE} and
8381 @code{VERSION} variables defined by @code{AM_INIT_AUTOMAKE}
8382 (@pxref{Macros}); more precisely the gzipped @code{tar} file is named
8383 @samp{@var{package}-@var{version}.tar.gz}.
8385 You can use the @command{make} variable @code{GZIP_ENV} to control how gzip
8386 is run. The default setting is @option{--best}.
8388 @cindex @code{m4_include}, distribution
8389 @cindex @code{include}, distribution
8392 For the most part, the files to distribute are automatically found by
8393 Automake: all source files are automatically included in a distribution,
8394 as are all @file{Makefile.am} and @file{Makefile.in} files. Automake also
8395 has a built-in list of commonly used files that are automatically
8396 included if they are found in the current directory (either physically,
8397 or as the target of a @file{Makefile.am} rule); this list is printed by
8398 @samp{automake --help}. Note that some files in this list are actually
8399 distributed only if other certain conditions hold (for example,
8400 @c Keep in sync with autodist-config-headers.sh
8401 the @file{config.h.top} and @file{config.h.bot} files are automatically
8402 distributed only if, e.g., @samp{AC_CONFIG_HEADERS([config.h])} is used
8403 in @file{configure.ac}). Also, files that are read by @command{configure}
8404 (i.e.@: the source files corresponding to the files specified in various
8405 Autoconf macros such as @code{AC_CONFIG_FILES} and siblings) are
8406 automatically distributed. Files included in a @file{Makefile.am} (using
8407 @code{include}) or in @file{configure.ac} (using @code{m4_include}), and
8408 helper scripts installed with @samp{automake --add-missing} are also
8412 Still, sometimes there are files that must be distributed, but which
8413 are not covered in the automatic rules. These files should be listed in
8414 the @code{EXTRA_DIST} variable. You can mention files from
8415 subdirectories in @code{EXTRA_DIST}.
8417 You can also mention a directory in @code{EXTRA_DIST}; in this case the
8418 entire directory will be recursively copied into the distribution.
8419 Please note that this will also copy @emph{everything} in the directory,
8420 including, e.g., Subversion's @file{.svn} private directories or CVS/RCS
8421 version control files. We recommend against using this feature.
8424 @vindex DIST_SUBDIRS
8425 If you define @code{SUBDIRS}, Automake will recursively include the
8426 subdirectories in the distribution. If @code{SUBDIRS} is defined
8427 conditionally (@pxref{Conditionals}), Automake will normally include
8428 all directories that could possibly appear in @code{SUBDIRS} in the
8429 distribution. If you need to specify the set of directories
8430 conditionally, you can set the variable @code{DIST_SUBDIRS} to the
8431 exact list of subdirectories to include in the distribution
8432 (@pxref{Conditional Subdirectories}).
8435 @node Fine-grained Distribution Control
8436 @section Fine-grained Distribution Control
8440 Sometimes you need tighter control over what does @emph{not} go into the
8441 distribution; for instance, you might have source files that are
8442 generated and that you do not want to distribute. In this case
8443 Automake gives fine-grained control using the @code{dist} and
8444 @code{nodist} prefixes. Any primary or @code{_SOURCES} variable can be
8445 prefixed with @code{dist_} to add the listed files to the distribution.
8446 Similarly, @code{nodist_} can be used to omit the files from the
8449 As an example, here is how you would cause some data to be distributed
8450 while leaving some source code out of the distribution:
8453 dist_data_DATA = distribute-this
8455 nodist_foo_SOURCES = do-not-distribute.c
8459 @section The dist Hook
8463 Occasionally it is useful to be able to change the distribution before
8464 it is packaged up. If the @code{dist-hook} rule exists, it is run
8465 after the distribution directory is filled, but before the actual
8466 distribution archives are created. One way to use this is for
8467 removing unnecessary files that get recursively included by specifying
8468 a directory in @code{EXTRA_DIST}:
8473 rm -rf `find $(distdir)/doc -type d -name .svn`
8476 @c The caveates described here should be documented in 'disthook.test'.
8478 Note that the @code{dist-hook} recipe shouldn't assume that the regular
8479 files in the distribution directory are writable; this might not be the
8480 case if one is packaging from a read-only source tree, or when a
8481 @code{make distcheck} is being done. For similar reasons, the recipe
8482 shouldn't assume that the subdirectories put into the distribution
8483 directory as effect of having them listed in @code{EXTRA_DIST} are
8484 writable. So, if the @code{dist-hook} recipe wants to modify the
8485 content of an existing file (or @code{EXTRA_DIST} subdirectory) in the
8486 distribution directory, it should explicitly to make it writable first:
8489 EXTRA_DIST = README doc
8491 chmod u+w $(distdir)/README $(distdir)/doc
8492 echo "Distribution date: `date`" >> README
8493 rm -f $(distdir)/doc/HACKING
8498 Two variables that come handy when writing @code{dist-hook} rules are
8499 @samp{$(distdir)} and @samp{$(top_distdir)}.
8501 @samp{$(distdir)} points to the directory where the @code{dist} rule
8502 will copy files from the current directory before creating the
8503 tarball. If you are at the top-level directory, then @samp{distdir =
8504 $(PACKAGE)-$(VERSION)}. When used from subdirectory named
8505 @file{foo/}, then @samp{distdir = ../$(PACKAGE)-$(VERSION)/foo}.
8506 @samp{$(distdir)} can be a relative or absolute path, do not assume
8509 @samp{$(top_distdir)} always points to the root directory of the
8510 distributed tree. At the top-level it's equal to @samp{$(distdir)}.
8511 In the @file{foo/} subdirectory
8512 @samp{top_distdir = ../$(PACKAGE)-$(VERSION)}.
8513 @samp{$(top_distdir)} too can be a relative or absolute path.
8515 Note that when packages are nested using @code{AC_CONFIG_SUBDIRS}
8516 (@pxref{Subpackages}), then @samp{$(distdir)} and
8517 @samp{$(top_distdir)} are relative to the package where @samp{make
8518 dist} was run, not to any sub-packages involved.
8520 @node Checking the Distribution
8521 @section Checking the Distribution
8523 @cindex @samp{make distcheck}
8525 Automake also generates a @code{distcheck} rule that can be of help
8526 to ensure that a given distribution will actually work. Simplifying
8527 a bit, we can say this rule first makes a distribution, and then,
8528 @emph{operating from it}, takes the following steps:
8531 tries to do a @code{VPATH} build (@pxref{VPATH Builds}), with the
8532 @code{srcdir} and all its content made @emph{read-only};
8534 runs the test suite (with @command{make check}) on this fresh build;
8536 installs the package in a temporary directory (with @command{make
8537 install}), and tries runs the test suite on the resulting installation
8538 (with @command{make installcheck});
8540 checks that the package can be correctly uninstalled (by @command{make
8541 uninstall}) and cleaned (by @code{make distclean});
8543 finally, makes another tarball to ensure the distribution is
8547 @vindex AM_DISTCHECK_CONFIGURE_FLAGS
8548 @vindex DISTCHECK_CONFIGURE_FLAGS
8549 @subheading DISTCHECK_CONFIGURE_FLAGS
8550 Building the package involves running @samp{./configure}. If you need
8551 to supply additional flags to @command{configure}, define them in the
8552 @code{AM_DISTCHECK_CONFIGURE_FLAGS} variable in your top-level
8553 @file{Makefile.am}. The user can still extend or override the flags
8554 provided there by defining the @code{DISTCHECK_CONFIGURE_FLAGS} variable,
8555 on the command line when invoking @command{make}.
8557 Still, developers are encouraged to strive to make their code buildable
8558 without requiring any special configure option; thus, in general, you
8559 shouldn't define @code{AM_DISTCHECK_CONFIGURE_FLAGS}. However, there
8560 might be few scenarios in which the use of this variable is justified.
8561 GNU @command{m4} offers an example. GNU @command{m4} configures by
8562 default with its experimental and seldom used "changeword" feature
8563 disabled; so in its case it is useful to have @command{make distcheck}
8564 run configure with the @option{--with-changeword} option, to ensure that
8565 the code for changeword support still compiles correctly.
8566 GNU @command{m4} also employs the @code{AM_DISTCHECK_CONFIGURE_FLAGS}
8567 variable to stress-test the use of @option{--program-prefix=g}, since at
8568 one point the @command{m4} build system had a bug where @command{make
8569 installcheck} was wrongly assuming it could blindly test "@command{m4}",
8570 rather than the just-installed "@command{gm4}".
8572 @trindex distcheck-hook
8573 @subheading distcheck-hook
8574 If the @code{distcheck-hook} rule is defined in your top-level
8575 @file{Makefile.am}, then it will be invoked by @code{distcheck} after
8576 the new distribution has been unpacked, but before the unpacked copy
8577 is configured and built. Your @code{distcheck-hook} can do almost
8578 anything, though as always caution is advised. Generally this hook is
8579 used to check for potential distribution errors not caught by the
8580 standard mechanism. Note that @code{distcheck-hook} as well as
8581 @code{AM_DISTCHECK_CONFIGURE_FLAGS} and @code{DISTCHECK_CONFIGURE_FLAGS}
8582 are not honored in a subpackage @file{Makefile.am}, but the flags from
8583 @code{AM_DISTCHECK_CONFIGURE_FLAGS} and @code{DISTCHECK_CONFIGURE_FLAGS}
8584 are passed down to the @command{configure} script of the subpackage.
8586 @cindex @samp{make distcleancheck}
8587 @trindex distcleancheck
8588 @vindex DISTCLEANFILES
8589 @vindex distcleancheck_listfiles
8591 @subheading distcleancheck
8592 Speaking of potential distribution errors, @code{distcheck} also
8593 ensures that the @code{distclean} rule actually removes all built
8594 files. This is done by running @samp{make distcleancheck} at the end of
8595 the @code{VPATH} build. By default, @code{distcleancheck} will run
8596 @code{distclean} and then make sure the build tree has been emptied by
8597 running @samp{$(distcleancheck_listfiles)}. Usually this check will
8598 find generated files that you forgot to add to the @code{DISTCLEANFILES}
8599 variable (@pxref{Clean}).
8601 The @code{distcleancheck} behavior should be OK for most packages,
8602 otherwise you have the possibility to override the definition of
8603 either the @code{distcleancheck} rule, or the
8604 @samp{$(distcleancheck_listfiles)} variable. For instance, to disable
8605 @code{distcleancheck} completely, add the following rule to your
8606 top-level @file{Makefile.am}:
8613 If you want @code{distcleancheck} to ignore built files that have not
8614 been cleaned because they are also part of the distribution, add the
8615 following definition instead:
8617 @c Keep in sync with distcleancheck.sh
8619 distcleancheck_listfiles = \
8620 find . -type f -exec sh -c 'test -f $(srcdir)/$$1 || echo $$1' \
8624 The above definition is not the default because it's usually an error if
8625 your Makefiles cause some distributed files to be rebuilt when the user
8626 build the package. (Think about the user missing the tool required to
8627 build the file; or if the required tool is built by your package,
8628 consider the cross-compilation case where it can't be run.) There is
8629 an entry in the FAQ about this (@pxref{Errors with distclean}), make
8630 sure you read it before playing with @code{distcleancheck_listfiles}.
8632 @cindex @samp{make distuninstallcheck}
8633 @trindex distuninstallcheck
8634 @vindex distuninstallcheck_listfiles
8636 @subheading distuninstallcheck
8637 @code{distcheck} also checks that the @code{uninstall} rule works
8638 properly, both for ordinary and @code{DESTDIR} builds. It does this
8639 by invoking @samp{make uninstall}, and then it checks the install tree
8640 to see if any files are left over. This check will make sure that you
8641 correctly coded your @code{uninstall}-related rules.
8643 By default, the checking is done by the @code{distuninstallcheck} rule,
8644 and the list of files in the install tree is generated by
8645 @samp{$(distuninstallcheck_listfiles)} (this is a variable whose value is
8646 a shell command to run that prints the list of files to stdout).
8648 Either of these can be overridden to modify the behavior of
8649 @code{distcheck}. For instance, to disable this check completely, you
8657 @node The Types of Distributions
8658 @section The Types of Distributions
8660 Automake generates rules to provide archives of the project for
8661 distributions in various formats. Their targets are:
8665 @item @code{dist-bzip2}
8666 Generate a bzip2 tar archive of the distribution. bzip2 archives are
8667 frequently smaller than gzipped archives.
8668 By default, this rule makes @samp{bzip2} use a compression option of @option{-9}.
8669 To make it use a different one, set the @env{BZIP2} environment variable.
8670 For example, @samp{make dist-bzip2 BZIP2=-7}.
8673 @item @code{dist-gzip}
8674 Generate a gzip tar archive of the distribution.
8677 @item @code{dist-lzip}
8678 Generate an @samp{lzip} tar archive of the distribution. @command{lzip}
8679 archives are frequently smaller than @command{bzip2}-compressed archives.
8682 @item @code{dist-shar}
8683 Generate a shar archive of the distribution.
8687 @item @code{dist-xz}
8688 Generate an @samp{xz} tar archive of the distribution. @command{xz}
8689 archives are frequently smaller than @command{bzip2}-compressed archives.
8690 By default, this rule makes @samp{xz} use a compression option of
8691 @option{-e}. To make it use a different one, set the @env{XZ_OPT}
8692 environment variable. For example, run this command to use the
8693 default compression ratio, but with a progress indicator:
8694 @samp{make dist-xz XZ_OPT=-7e}.
8697 @item @code{dist-zip}
8698 Generate a zip archive of the distribution.
8701 @item @code{dist-tarZ}
8702 Generate a compressed tar archive of
8707 The rule @code{dist} (and its historical synonym @code{dist-all}) will
8708 create archives in all the enabled formats, @ref{Options}. By
8709 default, only the @code{dist-gzip} target is hooked to @code{dist}.
8713 @chapter Support for test suites
8716 @cindex @code{make check}
8719 Automake can generate code to handle two kinds of test suites. One is
8720 based on integration with the @command{dejagnu} framework. The other
8721 (and most used) form is based on the use of generic test scripts, and
8722 its activation is triggered by the definition of the special @code{TESTS}
8723 variable. This second form allows for various degrees of sophistication
8724 and customization; in particular, it allows for concurrent execution
8725 of test scripts, use of established test protocols such as TAP, and
8726 definition of custom test drivers and test runners.
8729 In either case, the testsuite is invoked via @samp{make check}.
8732 * Generalities about Testing:: Concepts and terminology about testing
8733 * Simple Tests:: Listing test scripts in @code{TESTS}
8734 * Custom Test Drivers:: Writing and using custom test drivers
8735 * Using the TAP test protocol:: Integrating test scripts that use the TAP protocol
8736 * DejaGnu Tests:: Interfacing with the @command{dejagnu} testing framework
8737 * Install Tests:: Running tests on installed packages
8740 @node Generalities about Testing
8741 @section Generalities about Testing
8743 The purpose of testing is to determine whether a program or system behaves
8744 as expected (e.g., known inputs produce the expected outputs, error
8745 conditions are correctly handled or reported, and older bugs do not
8749 The minimal unit of testing is usually called @emph{test case}, or simply
8750 @emph{test}. How a test case is defined or delimited, and even what
8751 exactly @emph{constitutes} a test case, depends heavily on the testing
8752 paradigm and/or framework in use, so we won't attempt any more precise
8753 definition. The set of the test cases for a given program or system
8754 constitutes its @emph{testsuite}.
8756 @cindex test harness
8757 @cindex testsuite harness
8758 A @emph{test harness} (also @emph{testsuite harness}) is a program or
8759 software component that executes all (or part of) the defined test cases,
8760 analyzes their outcomes, and report or register these outcomes
8761 appropriately. Again, the details of how this is accomplished (and how
8762 the developer and user can influence it or interface with it) varies
8763 wildly, and we'll attempt no precise definition.
8766 @cindex test failure
8767 A test is said to @emph{pass} when it can determine that the condition or
8768 behaviour it means to verify holds, and is said to @emph{fail} when it can
8769 determine that such condition of behaviour does @emph{not} hold.
8772 Sometimes, tests can rely on non-portable tools or prerequisites, or
8773 simply make no sense on a given system (for example, a test checking a
8774 Windows-specific feature makes no sense on a GNU/Linux system). In this
8775 case, accordingly to the definition above, the tests can neither be
8776 considered passed nor failed; instead, they are @emph{skipped} -- i.e.,
8777 they are not run, or their result is anyway ignored for what concerns
8778 the count of failures an successes. Skips are usually explicitly
8779 reported though, so that the user will be aware that not all of the
8780 testsuite has really run.
8783 @cindex expected failure
8784 @cindex expected test failure
8786 @cindex unexpected pass
8787 @cindex unexpected test pass
8788 It's not uncommon, especially during early development stages, that some
8789 tests fail for known reasons, and that the developer doesn't want to
8790 tackle these failures immediately (this is especially true when the
8791 failing tests deal with corner cases). In this situation, the better
8792 policy is to declare that each of those failures is an @emph{expected
8793 failure} (or @emph{xfail}). In case a test that is expected to fail ends
8794 up passing instead, many testing environments will flag the result as a
8795 special kind of failure called @emph{unexpected pass} (or @emph{xpass}).
8798 @cindex Distinction between errors and failures in testsuites
8799 Many testing environments and frameworks distinguish between test failures
8800 and hard errors. As we've seen, a test failure happens when some invariant
8801 or expected behaviour of the software under test is not met. An @emph{hard
8802 error} happens when e.g., the set-up of a test case scenario fails, or when
8803 some other unexpected or highly undesirable condition is encountered (for
8804 example, the program under test experiences a segmentation fault).
8806 @emph{TODO}: Links to other test harnesses (esp. those sharing our
8810 @section Simple Tests
8813 * Scripts-based Testsuites:: Automake-specific concepts and terminology
8814 * Serial Test Harness:: Older (and obsolescent) serial test harness
8815 * Parallel Test Harness:: Generic concurrent test harness
8818 @node Scripts-based Testsuites
8819 @subsection Scripts-based Testsuites
8821 If the special variable @code{TESTS} is defined, its value is taken to be
8822 a list of programs or scripts to run in order to do the testing. Under
8823 the appropriate circumstances, it's possible for @code{TESTS} to list
8824 also data files to be passed to one or more test scripts defined by
8825 different means (the so-called ``log compilers'', @pxref{Parallel Test
8828 Test scripts can be executed serially or concurrently. Automake
8829 supports both these kinds of test execution, with the serial test harness
8830 being the default (for backward-compatibility reasons only, as its use
8831 is nowadays discouraged). The concurrent test harness relies on the
8832 concurrence capabilities (if any) offered by the underlying @command{make}
8833 implementation, and can thus only be as good as those are.
8835 By default, only the exit statuses of the test scripts are considered when
8836 determining the testsuite outcome. But Automake allows also the use of
8837 more complex test protocols, either standard (@pxref{Using the TAP test
8838 protocol}) or custom (@pxref{Custom Test Drivers}). Note that you can
8839 enable such protocols only when the parallel harness is used: they won't
8840 work with the serial test harness. In the rest of this section we are
8841 going to concentrate mostly on protocol-less tests, since we cover
8842 test protocols in a later section (again, @pxref{Custom Test Drivers}).
8844 @cindex Exit status 77, special interpretation
8845 @cindex Exit status 99, special interpretation
8846 When no test protocol is in use, an exit status of 0 from a test script will
8847 denote a success, an exit status of 77 a skipped test, an exit status of 99
8848 an hard error, and any other exit status will denote a failure.
8850 @cindex Tests, expected failure
8851 @cindex Expected test failure
8853 @vindex DISABLE_HARD_ERRORS
8854 @cindex Disabling hard errors
8855 You may define the variable @code{XFAIL_TESTS} to a list of tests
8856 (usually a subset of @code{TESTS}) that are expected to fail; this will
8857 effectively reverse the result of those tests (with the provision that
8858 skips and hard errors remain untouched). You may also instruct the
8859 testsuite harness to treat hard errors like simple failures, by defining
8860 the @code{DISABLE_HARD_ERRORS} make variable to a nonempty value.
8862 Note however that, for tests based on more complex test protocols,
8863 the exact effects of @code{XFAIL_TESTS} and @code{DISABLE_HARD_ERRORS}
8864 might change, or they might even have no effect at all (for example,
8865 @c Keep this in sync with tap-no-disable-hard-errors.sh
8866 in tests using TAP, there is not way to disable hard errors, and the
8867 @code{DISABLE_HARD_ERRORS} variable has no effect on them).
8869 @anchor{Testsuite progress on console}
8870 @cindex Testsuite progress on console
8871 The result of each test case run by the scripts in @code{TESTS} will be
8872 printed on standard output, along with the test name. For test protocols
8873 that allow more test cases per test script (such as TAP), a number,
8874 identifier and/or brief description specific for the single test case is
8875 expected to be printed in addition to the name of the test script. The
8876 possible results (whose meanings should be clear from the previous
8877 @ref{Generalities about Testing}) are @code{PASS}, @code{FAIL},
8878 @code{SKIP}, @code{XFAIL}, @code{XPASS} and @code{ERROR}. Here is an
8879 example of output from an hypothetical testsuite that uses both plain
8881 @c Keep in sync with tap-doc.sh
8884 PASS: zardoz.tap 1 - Daemon started
8885 PASS: zardoz.tap 2 - Daemon responding
8886 SKIP: zardoz.tap 3 - Daemon uses /proc # SKIP /proc is not mounted
8887 PASS: zardoz.tap 4 - Daemon stopped
8890 XFAIL: mu.tap 2 # TODO frobnication not yet implemented
8894 A testsuite summary (expected to report at least the number of run,
8895 skipped and failed tests) will be printed at the end of the testsuite
8898 @anchor{Simple tests and color-tests}
8899 @vindex AM_COLOR_TESTS
8900 @cindex Colorized testsuite output
8901 If the Automake option @code{color-tests} is used (@pxref{Options})
8902 and standard output is connected to a capable terminal, then the test
8903 results and the summary are colored appropriately. The user can disable
8904 colored output by setting the @command{make} variable
8905 @samp{AM_COLOR_TESTS=no}, or force colored output even without a connecting
8906 terminal with @samp{AM_COLOR_TESTS=always}. It's also worth noting that
8907 some @command{make} implementations, when used in parallel mode, have
8908 slightly different semantics (@pxref{Parallel make,,, autoconf,
8909 The Autoconf Manual}), which can break the automatic detection of a
8910 connection to a capable terminal. If this is the case, you'll have to
8911 resort to the use of @samp{AM_COLOR_TESTS=always} in order to have the
8912 testsuite output colorized.
8914 Test programs that need data files should look for them in @code{srcdir}
8915 (which is both a make variable and an environment variable made available
8916 to the tests), so that they work when building in a separate directory
8917 (@pxref{Build Directories, , Build Directories , autoconf,
8918 The Autoconf Manual}), and in particular for the @code{distcheck} rule
8919 (@pxref{Checking the Distribution}).
8922 @vindex TESTS_ENVIRONMENT
8923 @vindex AM_TESTS_ENVIRONMENT
8924 The @code{AM_TESTS_ENVIRONMENT} and @code{TESTS_ENVIRONMENT} variables can
8925 be used to run initialization code and set environment variables for the
8926 test scripts. The former variable is developer-reserved, and can be
8927 defined in the @file{Makefile.am}, while the latter is reserved for the
8928 user, which can employ it to extend or override the settings in the
8929 former; for this to work portably, however, the contents of a non-empty
8930 @code{AM_TESTS_ENVIRONMENT} @emph{must} be terminated by a semicolon.
8932 @vindex AM_TESTS_FD_REDIRECT
8933 The @code{AM_TESTS_FD_REDIRECT} variable can be used to define file
8934 descriptor redirections for the test scripts. One might think that
8935 @code{AM_TESTS_ENVIRONMENT} could be used for this purpose, but experience
8936 has shown that doing so portably is practically impossible. The main
8937 hurdle is constituted by Korn shells, which usually set the close-on-exec
8938 flag on file descriptors opened with the @command{exec} builtin, thus
8939 rendering an idiom like @code{AM_TESTS_ENVIRONMENT = exec 9>&2;}
8940 ineffectual. This issue also affects some Bourne shells, such as the
8941 HP-UX's @command{/bin/sh},
8942 @c FIXME: should we offer a link to the relevant discussions on the
8943 @c bug-autoconf list?
8945 @c Keep in sync with tests-environment-backcompat.sh
8947 AM_TESTS_ENVIRONMENT = \
8948 ## Some environment initializations are kept in a separate shell
8949 ## file `tests-env.sh', which can make it easier to also run tests
8950 ## from the command line.
8951 . $(srcdir)/tests-env.sh; \
8952 ## On Solaris, prefer more POSIX-compliant versions of the standard
8953 ## tools by default.
8954 if test -d /usr/xpg4/bin; then \
8955 PATH=/usr/xpg4/bin:$$PATH; export PATH; \
8957 @c $$ restore font-lock
8958 ## With this, the test scripts will be able to print diagnostic
8959 ## messages to the original standard error stream, even if the test
8960 ## driver redirects the stderr of the test scripts to a log file
8961 ## before executing them.
8962 AM_TESTS_FD_REDIRECT = 9>&2
8966 Note however that @code{AM_TESTS_ENVIRONMENT} is, for historical and
8967 implementation reasons, @emph{not} supported by the serial harness
8968 (@pxref{Serial Test Harness}).
8970 Automake ensures that each file listed in @code{TESTS} is built before
8971 it is run; you can list both source and derived programs (or scripts)
8972 in @code{TESTS}; the generated rule will look both in @code{srcdir} and
8973 @file{.}. For instance, you might want to run a C program as a test.
8974 To do this you would list its name in @code{TESTS} and also in
8975 @code{check_PROGRAMS}, and then specify it as you would any other
8978 Programs listed in @code{check_PROGRAMS} (and @code{check_LIBRARIES},
8979 @code{check_LTLIBRARIES}...) are only built during @code{make check},
8980 not during @code{make all}. You should list there any program needed
8981 by your tests that does not need to be built by @code{make all}. Note
8982 that @code{check_PROGRAMS} are @emph{not} automatically added to
8983 @code{TESTS} because @code{check_PROGRAMS} usually lists programs used
8984 by the tests, not the tests themselves. Of course you can set
8985 @code{TESTS = $(check_PROGRAMS)} if all your programs are test cases.
8987 @node Serial Test Harness
8988 @subsection Serial Test Harness
8989 @cindex @option{serial-tests}, Using
8991 @emph{NOTE:} This harness, while still being the default one, is
8992 obsolescent, and kept mostly for backward-compatibility reasons. The user
8993 is advised to use the parallel test harness instead (@pxref{Parallel Test
8994 Harness}). Be warned that future Automake versions might switch to use
8995 that more modern and feature-rich harness by default.
8997 The serial test harness is enabled by the Automake option
8998 @option{serial-tests}. It operates by simply running the tests serially,
8999 one at the time, without any I/O redirection. It's up to the user to
9000 implement logging of tests' output, if that's requited or desired.
9001 @c TODO: give an example of how this can be done.
9003 For historical and implementation reasons, the @code{AM_TESTS_ENVIRONMENT}
9004 variable is @emph{not} supported by this harness (it will be silently
9005 ignored if defined); only @code{TESTS_ENVIRONMENT} is, and it is to be
9006 considered a developer-reserved variable. This is done so that, when
9007 using the serial harness, @code{TESTS_ENVIRONMENT} can be defined to an
9008 invocation of an interpreter through which the tests are to be run.
9009 For instance, the following setup may be used to run tests with Perl:
9012 TESTS_ENVIRONMENT = $(PERL) -Mstrict -w
9013 TESTS = foo.pl bar.pl baz.pl
9017 It's important to note that the use of @code{TESTS_ENVIRONMENT} endorsed
9018 here would be @emph{invalid} with the parallel harness. That harness
9019 provides a more elegant way to achieve the same effect, with the further
9020 benefit of freeing the @code{TESTS_ENVIRONMENT} variable for the user
9021 (@pxref{Parallel Test Harness}).
9023 Another, less serious limit of the serial harness is that it doesn't
9024 really distinguish between simple failures and hard errors; this is
9025 due to historical reasons only, and might be fixed in future Automake
9028 @node Parallel Test Harness
9029 @subsection Parallel Test Harness
9030 @cindex @option{parallel-tests}, Using
9032 The parallel (or concurrent) test harness is enabled by the Automake option
9033 @option{parallel-tests}. It features automatic collection of the test
9034 scripts output in @file{.log} files, concurrent execution of tests with
9035 @code{make -j}, specification of inter-test dependencies, lazy reruns of
9036 tests that have not completed in a prior run, and hard errors for exceptional
9039 This harness is still somewhat experimental and may undergo changes in
9040 order to satisfy additional portability requirements.
9042 @anchor{Basics of test metadata}
9043 @vindex TEST_SUITE_LOG
9045 @cindex @file{.log} files
9046 @cindex @file{.trs} files
9047 @cindex test metadata
9048 The parallel test harness operates by defining a set of @command{make}
9049 rules that run the test scripts listed in @code{TESTS}, and, for each
9050 such script, save its output in a corresponding @file{.log} file and
9051 its results (and other ``metadata'', @pxref{API for Custom Test Drivers})
9052 in a corresponding @file{.trs} (as in @b{T}est @b{R}e@b{S}ults) file.
9053 @c We choose the `.trs' extension also because, at the time of writing,
9054 @c it isn't already used for other significant purposes; see e.g.:
9055 @c - http://filext.com/file-extension/trs
9056 @c - http://www.file-extensions.org/search/?searchstring=trs
9057 The @file{.log} file will contain all the output emitted by the test on
9058 its standard output and its standard error. The @file{.trs} file will
9059 contain, among the other things, the results of the test cases run by
9062 The parallel test harness will also create a summary log file,
9063 @code{TEST_SUITE_LOG}, which defaults to @file{test-suite.log} and requires
9064 a @file{.log} suffix. This file depends upon all the @file{.log} and
9065 @file{.trs} files created for the test scripts listed in @code{TESTS}.
9068 As with the serial harness above, by default one status line is printed
9069 per completed test, and a short summary after the suite has completed.
9070 However, standard output and standard error of the test are redirected
9071 to a per-test log file, so that parallel execution does not produce
9072 intermingled output. The output from failed tests is collected in the
9073 @file{test-suite.log} file. If the variable @samp{VERBOSE} is set, this
9074 file is output after the summary.
9075 @c FIXME: we should be clearer about what we mean exactly here ...
9076 For best results, the tests should be verbose by default now.
9078 @vindex TEST_EXTENSIONS
9080 Each couple of @file{.log} and @file{.trs} files is created when the
9081 corresponding test has completed. The set of log files is listed in
9082 the read-only variable @code{TEST_LOGS}, and defaults to @code{TESTS},
9083 with the executable extension if any (@pxref{EXEEXT}), as well as any
9084 suffix listed in @code{TEST_EXTENSIONS} removed, and @file{.log} appended.
9085 Results are undefined if a test file name ends in several concatenated
9086 suffixes. @code{TEST_EXTENSIONS} defaults to @file{.test}; it can be
9087 overridden by the user, in which case any extension listed in it must be
9088 constituted by a dot, followed by a non-digit alphabetic character,
9089 followed by any number of alphabetic characters.
9090 @c Keep in sync with test-extensions.sh
9091 For example, @samp{.sh}, @samp{.T} and @samp{.t1} are valid extensions,
9092 while @samp{.x-y}, @samp{.6c} and @samp{.t.1} are not.
9094 @vindex _LOG_COMPILE
9095 @vindex _LOG_COMPILER
9098 @vindex LOG_COMPILER
9100 @vindex @var{ext}_LOG_COMPILE
9101 @vindex @var{ext}_LOG_COMPILER
9102 @vindex @var{ext}_LOG_FLAGS
9103 @vindex AM_@var{ext}_LOG_FLAGS
9104 @vindex AM_LOG_FLAGS
9105 For tests that match an extension @code{.@var{ext}} listed in
9106 @code{TEST_EXTENSIONS}, you can provide a custom ``test runner'' using
9107 the variable @code{@var{ext}_LOG_COMPILER} (note the upper-case
9108 extension) and pass options in @code{AM_@var{ext}_LOG_FLAGS} and allow
9109 the user to pass options in @code{@var{ext}_LOG_FLAGS}. It will cause
9110 all tests with this extension to be called with this runner. For all
9111 tests without a registered extension, the variables @code{LOG_COMPILER},
9112 @code{AM_LOG_FLAGS}, and @code{LOG_FLAGS} may be used. For example,
9114 @c Keep in sync with parallel-tests-log-compiler-example.sh
9116 TESTS = foo.pl bar.py baz
9117 TEST_EXTENSIONS = .pl .py
9118 PL_LOG_COMPILER = $(PERL)
9119 AM_PL_LOG_FLAGS = -w
9120 PY_LOG_COMPILER = $(PYTHON)
9121 AM_PY_LOG_FLAGS = -v
9122 LOG_COMPILER = ./wrapper-script
9127 will invoke @samp{$(PERL) -w foo.pl}, @samp{$(PYTHON) -v bar.py},
9128 and @samp{./wrapper-script -d baz} to produce @file{foo.log},
9129 @file{bar.log}, and @file{baz.log}, respectively. The @file{foo.trs},
9130 @file{bar.trs} and @file{baz.trs} files will be automatically produced
9133 It's important to note that, differently from what we've seen for the
9134 serial test harness (@pxref{Parallel Test Harness}), the
9135 @code{AM_TESTS_ENVIRONMENT} and @code{TESTS_ENVIRONMENT} variables
9136 @emph{cannot} be use to define a custom test runner; the
9137 @code{LOG_COMPILER} and @code{LOG_FLAGS} (or their extension-specific
9138 counterparts) should be used instead:
9142 AM_TESTS_ENVIRONMENT = PERL5LIB='$(srcdir)/lib' $(PERL) -Mstrict -w
9147 AM_TESTS_ENVIRONMENT = PERL5LIB='$(srcdir)/lib'; export PERL5LIB;
9148 LOG_COMPILER = $(PERL)
9149 AM_LOG_FLAGS = -Mstrict -w
9152 By default, the test suite harness will run all tests, but there are
9153 several ways to limit the set of tests that are run:
9157 You can set the @code{TESTS} variable. For example, you can use a
9158 command like this to run only a subset of the tests:
9161 env TESTS="foo.test bar.test" make -e check
9164 Note however that the command above will unconditionally overwrite the
9165 @file{test-suite.log} file, thus clobbering the recorded results
9166 of any previous testsuite run. This might be undesirable for packages
9167 whose testsuite takes long time to execute. Luckily, this problem can
9168 easily be avoided by overriding also @code{TEST_SUITE_LOG} at runtime;
9171 @c Keep in sync with parallel-tests-log-override-2.sh
9173 env TEST_SUITE_LOG=partial.log TESTS="..." make -e check
9176 will write the result of the partial testsuite runs to the
9177 @file{partial.log}, without touching @file{test-suite.log}.
9180 You can set the @code{TEST_LOGS} variable. By default, this variable is
9181 computed at @command{make} run time from the value of @code{TESTS} as
9182 described above. For example, you can use the following:
9185 set x subset*.log; shift
9186 env TEST_LOGS="foo.log $*" make -e check
9189 The comments made above about @code{TEST_SUITE_LOG} overriding applies
9193 @vindex RECHECK_LOGS
9194 @cindex lazy test execution
9195 By default, the test harness removes all old per-test @file{.log} and
9196 @file{.trs} files before it starts running tests to regenerate them. The
9197 variable @code{RECHECK_LOGS} contains the set of @file{.log} (and, by
9198 implication, @file{.trs}) files which are removed. @code{RECHECK_LOGS}
9199 defaults to @code{TEST_LOGS}, which means all tests need to be rechecked.
9200 By overriding this variable, you can choose which tests need to be
9201 reconsidered. For example, you can lazily rerun only those tests which
9202 are outdated, i.e., older than their prerequisite test files, by setting
9203 this variable to the empty value:
9206 env RECHECK_LOGS= make -e check
9211 You can ensure that all tests are rerun which have failed or passed
9212 unexpectedly, by running @code{make recheck} in the test directory.
9213 This convenience target will set @code{RECHECK_LOGS} appropriately
9214 before invoking the main test harness.
9218 In order to guarantee an ordering between tests even with @code{make
9219 -j@var{N}}, dependencies between the corresponding @file{.log} files
9220 may be specified through usual @command{make} dependencies. For example,
9221 the following snippet lets the test named @file{foo-execute.test} depend
9222 upon completion of the test @file{foo-compile.test}:
9225 TESTS = foo-compile.test foo-execute.test
9226 foo-execute.log: foo-compile.log
9230 Please note that this ordering ignores the @emph{results} of required
9231 tests, thus the test @file{foo-execute.test} is run even if the test
9232 @file{foo-compile.test} failed or was skipped beforehand. Further,
9233 please note that specifying such dependencies currently works only for
9234 tests that end in one of the suffixes listed in @code{TEST_EXTENSIONS}.
9236 Tests without such specified dependencies may be run concurrently with
9237 parallel @command{make -j@var{N}}, so be sure they are prepared for
9238 concurrent execution.
9241 @c Keep in sync with 'parallel-tests-extra-programs.test'.
9242 The combination of lazy test execution and correct dependencies between
9243 tests and their sources may be exploited for efficient unit testing
9244 during development. To further speed up the edit-compile-test cycle, it
9245 may even be useful to specify compiled programs in @code{EXTRA_PROGRAMS}
9246 instead of with @code{check_PROGRAMS}, as the former allows intertwined
9247 compilation and test execution (but note that @code{EXTRA_PROGRAMS} are
9248 not cleaned automatically, @pxref{Uniform}).
9250 The variables @code{TESTS} and @code{XFAIL_TESTS} may contain
9251 conditional parts as well as configure substitutions. In the latter
9252 case, however, certain restrictions apply: substituted test names
9253 must end with a nonempty test suffix like @file{.test}, so that one of
9254 the inference rules generated by @command{automake} can apply. For
9255 literal test names, @command{automake} can generate per-target rules
9256 to avoid this limitation.
9258 Please note that it is currently not possible to use @code{$(srcdir)/}
9259 or @code{$(top_srcdir)/} in the @code{TESTS} variable. This technical
9260 limitation is necessary to avoid generating test logs in the source tree
9261 and has the unfortunate consequence that it is not possible to specify
9262 distributed tests that are themselves generated by means of explicit
9263 rules, in a way that is portable to all @command{make} implementations
9264 (@pxref{Make Target Lookup,,, autoconf, The Autoconf Manual}, the
9265 semantics of FreeBSD and OpenBSD @command{make} conflict with this).
9266 In case of doubt you may want to require to use GNU @command{make},
9267 or work around the issue with inference rules to generate the tests.
9269 @node Custom Test Drivers
9270 @section Custom Test Drivers
9273 * Overview of Custom Test Drivers Support::
9274 * Declaring Custom Test Drivers::
9275 * API for Custom Test Drivers::
9278 @node Overview of Custom Test Drivers Support
9279 @subsection Overview of Custom Test Drivers Support
9281 Starting from Automake version 1.12, the parallel test harness allows
9282 the package authors to use third-party custom test drivers, in case the
9283 default ones are inadequate for their purposes, or do not support their
9284 testing protocol of choice.
9286 A custom test driver is expected to properly run the test programs passed
9287 to it (including the command-line arguments passed to those programs, if
9288 any), to analyze their execution and outcome, to create the @file{.log}
9289 and @file{.trs} files associated to these test runs, and to display the test
9290 results on the console. It is responsibility of the author of the test
9291 driver to ensure that it implements all the above steps meaningfully and
9292 correctly; Automake isn't and can't be of any help here. On the other
9293 hand, the Automake-provided code for testsuite summary generation offers
9294 support for test drivers allowing several test results per test script,
9295 if they take care to register such results properly (@pxref{Log files
9296 generation and test results recording}).
9298 The exact details of how test scripts' results are to be determined and
9299 analyzed is left to the individual drivers. Some drivers might only
9300 consider the test script exit status (this is done for example by the
9301 default test driver used by the parallel test harness, described
9302 in the previous section). Other drivers might implement more complex and
9303 advanced test protocols, which might require them to parse and interpreter
9304 the output emitted by the test script they're running (examples of such
9305 protocols are TAP and SubUnit).
9307 It's very important to note that, even when using custom test drivers,
9308 most of the infrastructure described in the previous section about the
9309 parallel harness remains in place; this includes:
9313 list of test scripts defined in @code{TESTS}, and overridable at
9314 runtime through the redefinition of @code{TESTS} or @code{TEST_LOGS};
9316 concurrency through the use of @command{make}'s option @option{-j};
9318 per-test @file{.log} and @file{.trs} files, and generation of a summary
9319 @file{.log} file from them;
9321 @code{recheck} target, @code{RECHECK_LOGS} variable, and lazy reruns
9324 inter-test dependencies;
9326 support for @code{check_*} variables (@code{check_PROGRAMS},
9327 @code{check_LIBRARIES}, ...);
9329 use of @code{VERBOSE} environment variable to get verbose output on
9332 definition and honoring of @code{TESTS_ENVIRONMENT},
9333 @code{AM_TESTS_ENVIRONMENT} and @code{AM_TESTS_FD_REDIRECT}
9336 definition of generic and extension-specific @code{LOG_COMPILER} and
9337 @code{LOG_FLAGS} variables.
9341 On the other hand, the exact semantics of how (and if)
9342 @option{color-tests}, @code{XFAIL_TESTS}, and hard errors are supported
9343 and handled is left to the individual test drivers.
9345 @c TODO: We should really add a working example in the doc/ directory,
9346 @c TODO: and reference if from here.
9348 @node Declaring Custom Test Drivers
9349 @subsection Declaring Custom Test Drivers
9352 @vindex _LOG_DRIVER_FLAGS
9354 @vindex LOG_DRIVER_FLAGS
9355 @vindex @var{ext}_LOG_DRIVER
9356 @vindex @var{ext}_LOG_DRIVER_FLAGS
9357 @vindex AM_@var{ext}_LOG_DRIVER_FLAGS
9358 @vindex AM_LOG_DRIVER_FLAGS
9359 Custom testsuite drivers are declared by defining the make variables
9360 @code{LOG_DRIVER} or @code{@var{ext}_LOG_DRIVER} (where @var{ext} must
9361 be declared in @code{TEST_EXTENSIONS}). They must be defined to
9362 programs or scripts that will be used to drive the execution, logging,
9363 and outcome report of the tests with corresponding extensions (or of
9364 those with no registered extension in the case of @code{LOG_DRIVER}).
9365 Clearly, multiple distinct test drivers can be declared in the same
9366 @file{Makefile.am}. Note moreover that the @code{LOG_DRIVER} variables
9367 are @emph{not} a substitute for the @code{LOG_COMPILER} variables: the
9368 two sets of variables can, and often do, usefully and legitimately
9371 @c TODO: We should really be able to point to a clarifying example here!
9373 The developer-reserved variable @code{AM_LOG_DRIVER_FLAGS} and the
9374 user-reserved variable @code{LOG_DRIVER_FLAGS} can be used to define
9375 flags that will be passed to each invocation of @code{LOG_DRIVER},
9376 with the user-defined flags obviously taking precedence over the
9377 developer-reserved ones. Similarly, for each extension @var{ext}
9378 declared in @code{TEST_EXTENSIONS}, flags listed in
9379 @code{AM_@var{ext}_LOG_DRIVER_FLAGS} and
9380 @code{@var{ext}_LOG_DRIVER_FLAGS} will be passed to
9381 invocations of @code{@var{ext}_LOG_DRIVER}.
9383 @node API for Custom Test Drivers
9384 @subsection API for Custom Test Drivers
9386 Note that @emph{the APIs described here are still highly experimental},
9387 and will very likely undergo tightenings and likely also extensive changes
9388 in the future, to accommodate for new features or to satisfy additional
9389 portability requirements.
9391 The main characteristic of these APIs is that they are designed to share
9392 as much infrastructure, semantics, and implementation details as possible
9393 with the parallel test harness and its default driver.
9396 * Command-line arguments for test drivers::
9397 * Log files generation and test results recording::
9398 * Testsuite progress output::
9401 @node Command-line arguments for test drivers
9402 @subsubsection Command-line arguments for test drivers
9404 A custom driver can rely on various command-line options and arguments
9405 being passed to it automatically by the Automake's @option{parallel-tests}
9406 harness. It is @emph{mandatory} that it understands all of them (even
9407 if the exact interpretation of the associated semantics can legitimately
9408 change between a test driver and another, and even be a no-op in some
9412 Here is the list of options:
9415 @item --test-name=@var{NAME}
9416 The name of the test, with VPATH prefix (if any) removed. This can have a
9417 suffix and a directory component (as in e.g., @file{sub/foo.test}), and is
9418 mostly meant to be used in console reports about testsuite advancements and
9419 results (@pxref{Testsuite progress output}).
9420 @item --log-file=@file{@var{PATH}.log}
9421 The @file{.log} file the test driver must create (@pxref{Basics of
9422 test metadata}). If it has a directory component (as in e.g.,
9423 @file{sub/foo.log}), the test harness will ensure that such directory
9424 exists @emph{before} the test driver is called.
9425 @item --trs-file=@file{@var{PATH}.trs}
9426 The @file{.trs} file the test driver must create (@pxref{Basics of
9427 test metadata}). If it has a directory component (as in e.g.,
9428 @file{sub/foo.trs}), the test harness will ensure that such directory
9429 exists @emph{before} the test driver is called.
9430 @item --color-tests=@{yes|no@}
9431 Whether the console output should be colorized or not (@pxref{Simple
9432 tests and color-tests}, to learn when this option gets activated and
9434 @item --expect-failure=@{yes|no@}
9435 Whether the tested program is expected to fail.
9436 @item --enable-hard-errors=@{yes|no@}
9437 Whether ``hard errors'' in the tested program should be treated differently
9438 from normal failures or not (the default should be @code{yes}). The exact
9439 meaning of ``hard error'' is highly dependent from the test protocols or
9442 Explicitly terminate the list of options.
9446 The first non-option argument passed to the test driver is the program to
9447 be run, and all the following ones are command-line options and arguments
9450 Note that the exact semantics attached to the @option{--color-tests},
9451 @option{--expect-failure} and @option{--enable-hard-errors} options are
9452 left up to the individual test drivers. Still, having a behaviour
9453 compatible or at least similar to that provided by the default
9454 @option{parallel-tests} driver is advised, as that would offer a better
9455 consistency and a more pleasant user experience.
9457 @node Log files generation and test results recording
9458 @subsubsection Log files generation and test results recording
9460 The test driver must correctly generate the files specified by the
9461 @option{--log-file} and @option{--trs-file} option (even when the tested
9462 program fails or crashes).
9464 The @file{.log} file should ideally contain all the output produced by the
9465 tested program, plus optionally other information that might facilitate
9466 debugging or analysis of bug reports. Apart from that, its format is
9469 The @file{.trs} file is used to register some metadata through the use
9470 of custom reStructuredText fields. This metadata is expected to be
9471 employed in various ways by the parallel test harness; for example, to
9472 count the test results when printing the testsuite summary, or to decide
9473 which tests to re-run upon @command{make reheck}. Unrecognized metadata
9474 in a @file{.trs} file is currently ignored by the harness, but this might
9475 change in the future. The list of currently recognized metadata follows.
9480 @cindex Register test result
9481 @cindex Register test case result
9482 @cindex Test result, registering
9483 @cindex Test case result, registering
9484 @cindex @code{:test-result:}
9485 @cindex reStructuredText field, @code{:test-result:}
9486 The test driver must use this field to register the results of @emph{each}
9487 test case run by a test script file. Several @code{:test-result:} fields
9488 can be present in the same @file{.trs} file; this is done in order to
9489 support test protocols that allow a single test script to run more test
9492 @c Keep this in sync with lib/am/check-am:$(TEST_SUITE_LOG).
9493 The only recognized test results are currently @code{PASS}, @code{XFAIL},
9494 @code{SKIP}, @code{FAIL}, @code{XPASS} and @code{ERROR}. These results,
9495 when declared with @code{:test-result:}, can be optionally followed by
9496 text holding the name and/or a brief description of the corresponding
9497 test; the @option{parallel-tests} harness will ignore such extra text when
9498 generating @file{test-suite.log} and preparing the testsuite summary.
9500 @c Keep in sync with 'test-metadata-recheck.test'.
9501 @item @code{:recheck:}
9503 @cindex reStructuredText field, @code{:recheck:}
9504 If this field is present and defined to @code{no}, then the corresponding
9505 test script will @emph{not} be run upon a @command{make recheck}. What
9506 happens when two or more @code{:recheck:} fields are present in the same
9507 @file{.trs} file is undefined behaviour.
9509 @c Keep in sync with 'test-metadata-global-log.test'.
9510 @item @code{:copy-in-global-log:}
9511 @cindex :copy-in-global-log:
9512 @cindex reStructuredText field, @code{:copy-in-global-log:}
9513 If this field is present and defined to @code{no}, then the content
9514 of the @file{.log} file will @emph{not} be copied into the global
9515 @file{test-suite.log}. We allow to forsake such copying because, while
9516 it can be useful in debugging and analysis of bug report, it can also be
9517 just a waste of space in normal situations, e.g., when a test script is
9518 successful. What happens when two or more @code{:copy-in-global-log:}
9519 fields are present in the same @file{.trs} file is undefined behaviour.
9521 @c Keep in sync with 'test-metadata-global-result.test'.
9522 @item @code{:test-global-result:}
9523 @cindex :test-global-result:
9524 @cindex reStructuredText field, @code{:test-global-result:}
9525 This is used to declare the "global result" of the script. Currently,
9526 the value of this field is needed only to be reported (more or less
9527 verbatim) in the generated global log file @code{$(TEST_SUITE_LOG)},
9528 so it's quite free-form. For example, a test script which run 10 test
9529 cases, 6 of which pass and 4 of which are skipped, could reasonably have
9530 a @code{PASS/SKIP} value for this field, while a test script which run
9531 19 successful tests and one failed test could have an @code{ALMOST
9532 PASSED} value. What happens when two or more @code{:test-global-result:}
9533 fields are present in the same @file{.trs} file is undefined behaviour.
9537 Let's see a small example. Assume a @file{.trs} file contains the
9541 :test-result: PASS server starts
9542 :global-log-copy: no
9543 :test-result: PASS HTTP/1.1 request
9544 :test-result: FAIL HTTP/1.0 request
9546 :test-result: SKIP HTTPS request (TLS library wasn't available)
9547 :test-result: PASS server stops
9551 Then the corresponding test script will be re-run by @command{make check},
9552 will contribute with @emph{five} test results to the testsuite summary
9553 (three of these tests being successful, one failed, and one skipped), and
9554 the content of the corresponding @file{.log} file will @emph{not} be
9555 copied in the global log file @file{test-suite.log}.
9557 @node Testsuite progress output
9558 @subsubsection Testsuite progress output
9560 A custom test driver also has the task of displaying, on the standard
9561 output, the test results as soon as they become available. Depending on
9562 the protocol in use, it can also display the reasons for failures and
9563 skips, and, more generally, any useful diagnostic output (but remember
9564 that each line on the screen is precious, so that cluttering the screen
9565 with overly verbose information is bad idea). The exact format of this
9566 progress output is left up to the test driver; in fact, a custom test
9567 driver might @emph{theoretically} even decide not to do any such report,
9568 leaving it all to the testsuite summary (that would be a very lousy idea,
9569 of course, and serves only to illustrate the flexibility that is
9572 Remember that consistency is good; so, if possible, try to be consistent
9573 with the output of the built-in Automake test drivers, providing a similar
9574 ``look & feel''. In particular, the testsuite progress output should be
9575 colorized when the @option{--color-tests} is passed to the driver. On the
9576 other end, if you are using a known and widespread test protocol with
9577 well-established implementations, being consistent with those
9578 implementations' output might be a good idea too.
9580 @c TODO: Give an example, maybe inspired to py.test-style output.
9581 @c TODO: That is a good idea because it shows a test driver that allows
9582 @c TODO: for different levels of verbosity in the progress output (could
9583 @c TODO: be implemented either using a driver cmdline flag, or an
9584 @c TODO: environment variable, or both).
9586 @node Using the TAP test protocol
9587 @section Using the TAP test protocol
9590 * Introduction to TAP::
9591 * Use TAP with the Automake test harness::
9592 * Incompatibilities with other TAP parsers and drivers::
9593 * Links and external resources on TAP::
9596 @node Introduction to TAP
9597 @subsection Introduction to TAP
9599 TAP, the Test Anything Protocol, is a simple text-based interface between
9600 testing modules or programs and a test harness. The tests (also called
9601 ``TAP producers'' in this context) write test results in a simple format
9602 on standard output; a test harness (also called ``TAP consumer'') will
9603 parse and interpret these results, and properly present them to the user,
9604 and/or register them for later analysis. The exact details of how this
9605 is accomplished can vary among different test harnesses. The Automake
9606 parallel harness will present the results on the console in the usual
9607 fashion (@pxref{Testsuite progress on console}), and will use the
9608 @file{.trs} files (@pxref{Basics of test metadata}) to store the test
9609 results and related metadata. Apart from that, it will try to remain
9610 as much compatible as possible with pre-existing and widespread utilities,
9611 such as the @uref{http://search.cpan.org/~andya/Test-Harness/bin/prove,
9612 @command{prove} utility}, at least for the simpler usages.
9614 TAP started its life as part of the test harness for Perl, but today
9615 it has been (mostly) standardized, and has various independent
9616 implementations in different languages; among them, C, C++, Perl,
9617 Python, PHP, and Java. For a semi-official specification of the
9618 TAP protocol, please refer to the documentation of
9619 @uref{http://search.cpan.org/~petdance/Test-Harness/lib/Test/Harness/TAP.pod,
9620 @samp{Test::Harness::TAP}}.
9622 The most relevant real-world usages of TAP are obviously in the testsuites
9623 of @command{perl} and of many perl modules. Still, also other important
9624 third-party packages, such as @uref{http://git-scm.com/, @command{git}},
9625 use TAP in their testsuite.
9627 @node Use TAP with the Automake test harness
9628 @subsection Use TAP with the Automake test harness
9630 Currently, the TAP driver that comes with Automake requires some by-hand
9631 steps on the developer's part (this situation should hopefully be improved
9632 in future Automake versions). You'll have to grab the @file{tap-driver.sh}
9633 script from the Automake distribution by hand, copy it in your source tree,
9634 add a call to @code{AC_PROG_AWK} in @file{configure.ac} to search for a
9635 proper awk program, and use the Automake support for third-party test
9636 drivers to instruct the harness to use the @file{tap-driver.sh} script
9637 and that awk program to run your TAP-producing tests. See the example
9638 below for clarification.
9640 Apart from the options common to all the Automake test drivers
9641 (@pxref{Command-line arguments for test drivers}), the @file{tap-driver.sh}
9642 supports the following options, whose names are chosen for enhanced
9643 compatibility with the @command{prove} utility.
9646 @c Keep in sync with 'tap-exit.test' and 'tap-signal.tap'.
9648 Causes the test driver to ignore the exit status of the test scripts;
9649 by default, the driver will report an error if the script exits with a
9650 non-zero status. This option has effect also on non-zero exit statuses
9651 due to termination by a signal.
9653 Instruct the test driver to display TAP diagnostic (i.e., lines beginning
9654 with the @samp{#} character) in the testsuite progress output too; by
9655 default, TAP diagnostic is only copied to the @file{.log} file.
9657 Revert the effects of @option{--comments}.
9659 Instruct the test driver to merge the test scripts' standard error into
9660 their standard output. This is necessary if you want to ensure that
9661 diagnostics from the test scripts are displayed in the correct order
9662 relative to test results; this can be of great help in debugging
9663 (especially if your test scripts are shell scripts run with shell
9664 tracing active). As a downside, this option might cause the test
9665 harness to get confused if anything that appears on standard error
9666 looks like a test result.
9668 Revert the effects of @option{--merge}.
9669 @item --diagnostic-string=@var{STRING}
9670 Change the string that introduces TAP diagnostic from the default value
9671 of ``@code{#}'' to @code{@var{STRING}}. This can be useful if your
9672 TAP-based test scripts produce verbose output on which they have limited
9673 control (because, say, the output comes from other tools invoked in the
9674 scripts), and it might contain text that gets spuriously interpreted as
9675 TAP diagnostic: such an issue can be solved by redefining the string that
9676 activates TAP diagnostic to a value you know won't appear by chance in
9677 the tests' output. Note however that this feature is non-standard, as
9678 the ``official'' TAP protocol does not allow for such a customization; so
9679 don't use it if you can avoid it.
9683 Here is an example of how the TAP driver can be set up and used.
9685 @c Keep in sync with tap-doc2.sh
9687 % @kbd{cat configure.ac}
9688 AC_INIT([GNU Try Tap], [1.0], [bug-automake@@gnu.org])
9689 AC_CONFIG_AUX_DIR([build-aux])
9690 AM_INIT_AUTOMAKE([foreign parallel-tests -Wall -Werror])
9691 AC_CONFIG_FILES([Makefile])
9692 AC_REQUIRE_AUX_FILE([tap-driver.sh])
9696 % @kbd{cat Makefile.am}
9697 TEST_LOG_DRIVER = env AM_TAP_AWK='$(AWK)' $(SHELL) \
9698 $(top_srcdir)/build-aux/tap-driver.sh
9699 TESTS = foo.test bar.test baz.test
9700 EXTRA_DIST = $(TESTS)
9702 % @kbd{cat foo.test}
9704 echo 1..4 # Number of tests to be executed.
9705 echo 'ok 1 - Swallows fly'
9706 echo 'not ok 2 - Caterpillars fly # TODO metamorphosis in progress'
9707 echo 'ok 3 - Pigs fly # SKIP not enough acid'
9708 echo '# I just love word plays ...'
9709 echo 'ok 4 - Flies fly too :-)'
9711 % @kbd{cat bar.test}
9714 echo 'not ok 1 - Bummer, this test has failed.'
9715 echo 'ok 2 - This passed though.'
9716 echo 'Bail out! Ennui kicking in, sorry...'
9717 echo 'ok 3 - This will not be seen.'
9719 % @kbd{cat baz.test}
9723 # Exit with error, even if all the tests have been successful.
9726 % @kbd{cp @var{PREFIX}/share/automake-@var{APIVERSION}/tap-driver.pl .}
9727 % @kbd{autoreconf -vi && ./configure && make check}
9729 PASS: foo.test 1 - Swallows fly
9730 XFAIL: foo.test 2 - Caterpillars fly # TODO metamorphosis in progress
9731 SKIP: foo.test 3 - Pigs fly # SKIP not enough acid
9732 PASS: foo.test 4 - Flies fly too :-)
9733 FAIL: bar.test 1 - Bummer, this test has failed.
9734 PASS: bar.test 2 - This passed though.
9735 ERROR: bar.test - Bail out! Ennui kicking in, sorry...
9737 ERROR: baz.test - exited with status 7
9739 Please report to bug-automake@@gnu.org
9741 % @kbd{echo exit status: $?}
9744 @c Keep the "skewed" indentation below, it produces pretty PDF output.
9745 % @kbd{env TEST_LOG_DRIVER_FLAGS='--comments --ignore-exit' \
9746 TESTS='foo.test baz.test' make -e check}
9748 PASS: foo.test 1 - Swallows fly
9749 XFAIL: foo.test 2 - Caterpillars fly # TODO metamorphosis in progress
9750 SKIP: foo.test 3 - Pigs fly # SKIP not enough acid
9751 # foo.test: I just love word plays...
9752 PASS: foo.test 4 - Flies fly too :-)
9755 % @kbd{echo exit status: $?}
9759 @node Incompatibilities with other TAP parsers and drivers
9760 @subsection Incompatibilities with other TAP parsers and drivers
9762 For implementation or historical reasons, the TAP driver and harness as
9763 implemented by Automake have some minors incompatibilities with the
9764 mainstream versions, which you should be aware of.
9768 A @code{Bail out!} directive doesn't stop the whole testsuite, but only
9769 the test script it occurs in. This doesn't follow TAP specifications,
9770 but on the other hand it maximizes compatibility (and code sharing) with
9771 the ``hard error'' concept of the default @option{parallel-tests} driver.
9773 The @code{version} and @code{pragma} directives are not supported.
9775 The @option{--diagnostic-string} option of our driver allows to modify
9776 the string that introduces TAP diagnostic from the default value
9777 of ``@code{#}''. The standard TAP protocol has currently no way to
9778 allow this, so if you use it your diagnostic will be lost to more
9779 compliant tools like @command{prove} and @code{Test::Harness}
9781 And there are probably some other small and yet undiscovered
9782 incompatibilities, especially in corner cases or with rare usages.
9785 @node Links and external resources on TAP
9786 @subsection Links and external resources on TAP
9789 Here are some links to more extensive official or third-party
9790 documentation and resources about the TAP protocol and related
9791 tools and libraries.
9794 @uref{http://search.cpan.org/~petdance/Test-Harness/lib/Test/Harness/TAP.pod,
9795 @samp{Test::Harness::TAP}},
9796 the (mostly) official documentation about the TAP format and protocol.
9798 @uref{http://search.cpan.org/~andya/Test-Harness/bin/prove,
9800 the most famous command-line TAP test driver, included in the distribution
9801 of @command{perl} and
9802 @uref{http://search.cpan.org/~andya/Test-Harness/lib/Test/Harness.pm,
9803 @samp{Test::Harness}}.
9805 The @uref{http://testanything.org/wiki/index.php/Main_Page,TAP wiki}.
9807 A ``gentle introduction'' to testing for perl coders:
9808 @uref{http://search.cpan.org/dist/Test-Simple/lib/Test/Tutorial.pod,
9809 @samp{Test::Tutorial}}.
9811 @uref{http://search.cpan.org/~mschwern/Test-Simple/lib/Test/Simple.pm,
9812 @samp{Test::Simple}}
9814 @uref{http://search.cpan.org/~mschwern/Test-Simple/lib/Test/More.pm,
9816 the standard perl testing libraries, which are based on TAP.
9818 @uref{http://www.eyrie.org/~eagle/software/c-tap-harness/,C TAP Harness},
9819 a C-based project implementing both a TAP producer and a TAP consumer.
9821 @uref{http://www.tap4j.org/,tap4j},
9822 a Java-based project implementing both a TAP producer and a TAP consumer.
9826 @section DejaGnu Tests
9828 If @uref{ftp://ftp.gnu.org/gnu/dejagnu/, @command{dejagnu}} appears in
9829 @code{AUTOMAKE_OPTIONS}, then a @command{dejagnu}-based test suite is
9830 assumed. The variable @code{DEJATOOL} is a list of names that are
9831 passed, one at a time, as the @option{--tool} argument to
9832 @command{runtest} invocations; it defaults to the name of the package.
9834 The variable @code{RUNTESTDEFAULTFLAGS} holds the @option{--tool} and
9835 @option{--srcdir} flags that are passed to dejagnu by default; this can be
9836 overridden if necessary.
9837 @vindex RUNTESTDEFAULTFLAGS
9839 The variables @code{EXPECT} and @code{RUNTEST} can
9840 also be overridden to provide project-specific values. For instance,
9841 you will need to do this if you are testing a compiler toolchain,
9842 because the default values do not take into account host and target
9849 The contents of the variable @code{RUNTESTFLAGS} are passed to the
9850 @code{runtest} invocation. This is considered a ``user variable''
9851 (@pxref{User Variables}). If you need to set @command{runtest} flags in
9852 @file{Makefile.am}, you can use @code{AM_RUNTESTFLAGS} instead.
9853 @vindex RUNTESTFLAGS
9854 @vindex AM_RUNTESTFLAGS
9856 @cindex @file{site.exp}
9857 Automake will generate rules to create a local @file{site.exp} file,
9858 defining various variables detected by @command{configure}. This file
9859 is automatically read by DejaGnu. It is OK for the user of a package
9860 to edit this file in order to tune the test suite. However this is
9861 not the place where the test suite author should define new variables:
9862 this should be done elsewhere in the real test suite code.
9863 Especially, @file{site.exp} should not be distributed.
9865 Still, if the package author has legitimate reasons to extend
9866 @file{site.exp} at @command{make} time, he can do so by defining
9867 the variable @code{EXTRA_DEJAGNU_SITE_CONFIG}; the files listed
9868 there will be considered @file{site.exp} prerequisites, and their
9869 content will be appended to it (in the same order in which they
9870 appear in @code{EXTRA_DEJAGNU_SITE_CONFIG}). Note that files are
9871 @emph{not} distributed by default.
9873 For more information regarding DejaGnu test suites, see @ref{Top, , ,
9874 dejagnu, The DejaGnu Manual}.
9877 @section Install Tests
9879 The @code{installcheck} target is available to the user as a way to
9880 run any tests after the package has been installed. You can add tests
9881 to this by writing an @code{installcheck-local} rule.
9885 @chapter Rebuilding Makefiles
9886 @cindex rebuild rules
9888 Automake generates rules to automatically rebuild @file{Makefile}s,
9889 @file{configure}, and other derived files like @file{Makefile.in}.
9891 @acindex AM_MAINTAINER_MODE
9892 If you are using @code{AM_MAINTAINER_MODE} in @file{configure.ac}, then
9893 these automatic rebuilding rules are only enabled in maintainer mode.
9895 @vindex ACLOCAL_AMFLAGS
9896 Sometimes you need to run @command{aclocal} with an argument like
9897 @option{-I} to tell it where to find @file{.m4} files. Since
9898 sometimes @command{make} will automatically run @command{aclocal}, you
9899 need a way to specify these arguments. You can do this by defining
9900 @code{ACLOCAL_AMFLAGS}; this holds arguments that are passed verbatim
9901 to @command{aclocal}. This variable is only useful in the top-level
9904 @vindex CONFIG_STATUS_DEPENDENCIES
9905 @vindex CONFIGURE_DEPENDENCIES
9906 @cindex @file{version.sh}, example
9907 @cindex @file{version.m4}, example
9909 Sometimes it is convenient to supplement the rebuild rules for
9910 @file{configure} or @file{config.status} with additional dependencies.
9911 The variables @code{CONFIGURE_DEPENDENCIES} and
9912 @code{CONFIG_STATUS_DEPENDENCIES} can be used to list these extra
9913 dependencies. These variables should be defined in all
9914 @file{Makefile}s of the tree (because these two rebuild rules are
9915 output in all them), so it is safer and easier to @code{AC_SUBST} them
9916 from @file{configure.ac}. For instance, the following statement will
9917 cause @file{configure} to be rerun each time @file{version.sh} is
9921 AC_SUBST([CONFIG_STATUS_DEPENDENCIES], ['$(top_srcdir)/version.sh'])
9925 Note the @samp{$(top_srcdir)/} in the file name. Since this variable
9926 is to be used in all @file{Makefile}s, its value must be sensible at
9927 any level in the build hierarchy.
9929 Beware not to mistake @code{CONFIGURE_DEPENDENCIES} for
9930 @code{CONFIG_STATUS_DEPENDENCIES}.
9932 @code{CONFIGURE_DEPENDENCIES} adds dependencies to the
9933 @file{configure} rule, whose effect is to run @command{autoconf}. This
9934 variable should be seldom used, because @command{automake} already tracks
9935 @code{m4_include}d files. However it can be useful when playing
9936 tricky games with @code{m4_esyscmd} or similar non-recommendable
9937 macros with side effects.
9939 @code{CONFIG_STATUS_DEPENDENCIES} adds dependencies to the
9940 @file{config.status} rule, whose effect is to run @file{configure}.
9941 This variable should therefore carry any non-standard source that may
9942 be read as a side effect of running @command{configure}, like @file{version.sh}
9943 in the example above.
9945 Speaking of @file{version.sh} scripts, we recommend against them
9946 today. They are mainly used when the version of a package is updated
9947 automatically by a script (e.g., in daily builds). Here is what some
9948 old-style @file{configure.ac}s may look like:
9952 . $srcdir/version.sh
9953 AM_INIT_AUTOMAKE([name], $VERSION_NUMBER)
9958 Here, @file{version.sh} is a shell fragment that sets
9959 @code{VERSION_NUMBER}. The problem with this example is that
9960 @command{automake} cannot track dependencies (listing @file{version.sh}
9961 in @command{CONFIG_STATUS_DEPENDENCIES}, and distributing this file is up
9962 to the user), and that it uses the obsolete form of @code{AC_INIT} and
9963 @code{AM_INIT_AUTOMAKE}. Upgrading to the new syntax is not
9964 straightforward, because shell variables are not allowed in
9965 @code{AC_INIT}'s arguments. We recommend that @file{version.sh} be
9966 replaced by an M4 file that is included by @file{configure.ac}:
9969 m4_include([version.m4])
9970 AC_INIT([name], VERSION_NUMBER)
9976 Here @file{version.m4} could contain something like
9977 @samp{m4_define([VERSION_NUMBER], [1.2])}. The advantage of this
9978 second form is that @command{automake} will take care of the
9979 dependencies when defining the rebuild rule, and will also distribute
9980 the file automatically. An inconvenience is that @command{autoconf}
9981 will now be rerun each time the version number is bumped, when only
9982 @file{configure} had to be rerun in the previous setup.
9986 @chapter Changing Automake's Behavior
9989 * Options generalities:: Semantics of Automake option
9990 * List of Automake options:: A comprehensive list of Automake options
9993 @node Options generalities
9994 @section Options generalities
9996 Various features of Automake can be controlled by options. Except where
9997 noted otherwise, options can be specified in one of several ways. Most
9998 options can be applied on a per-@file{Makefile} basis when listed in a
9999 special @file{Makefile} variable named @code{AUTOMAKE_OPTIONS}. Some
10000 of these options only make sense when specified in the toplevel
10001 @file{Makefile.am} file. Options are applied globally to all processed
10002 @file{Makefile} files when listed in the first argument of
10003 @code{AM_INIT_AUTOMAKE} in @file{configure.ac}, and some options which
10004 require changes to the @command{configure} script can only be specified
10005 there. These are annotated below.
10007 As a general rule, options specified in @code{AUTOMAKE_OPTIONS} take
10008 precedence over those specified in @code{AM_INIT_AUTOMAKE}, which in
10009 turn take precedence over those specified on the command line.
10011 Also, some care must be taken about the interactions among strictness
10012 level and warning categories. As a general rule, strictness-implied
10013 warnings are overridden by those specified by explicit options. For
10014 example, even if @samp{portability} warnings are disabled by default
10015 in @option{foreign} strictness, an usage like this will end up enabling
10019 AUTOMAKE_OPTIONS = -Wportability foreign
10022 However, a strictness level specified in a higher-priority context
10023 will override all the explicit warnings specified in a lower-priority
10024 context. For example, if @file{configure.ac} contains:
10027 AM_INIT_AUTOMAKE([-Wportability])
10031 and @file{Makefile.am} contains:
10034 AUTOMAKE_OPTIONS = foreign
10038 then @samp{portability} warnings will be @emph{disabled} in
10039 @file{Makefile.am}.
10041 @node List of Automake options
10042 @section List of Automake options
10044 @vindex AUTOMAKE_OPTIONS
10047 @item @option{gnits}
10048 @itemx @option{gnu}
10049 @itemx @option{foreign}
10050 @itemx @option{cygnus}
10051 @cindex Option, @option{gnits}
10052 @cindex Option, @option{gnu}
10053 @cindex Option, @option{foreign}
10054 @cindex Option, @option{cygnus}
10060 Set the strictness as appropriate. The @option{gnits} option also
10061 implies options @option{readme-alpha} and @option{check-news}.
10063 @item @option{check-news}
10064 @cindex Option, @option{check-news}
10065 @opindex check-news
10066 Cause @samp{make dist} to fail unless the current version number appears
10067 in the first few lines of the @file{NEWS} file.
10069 @item @option{color-tests}
10070 @cindex Option, @option{color-tests}
10071 @opindex color-tests
10072 Cause output of the serial and parallel test harnesses (see @ref{Simple
10073 Tests}) and of properly-written custom test drivers (@pxref{Custom Test
10074 Drivers}) to be colorized on capable terminals.
10076 @item @option{dejagnu}
10077 @cindex Option, @option{dejagnu}
10079 Cause @command{dejagnu}-specific rules to be generated. @xref{DejaGnu Tests}.
10081 @item @option{dist-bzip2}
10082 @cindex Option, @option{dist-bzip2}
10083 @opindex dist-bzip2
10084 Hook @code{dist-bzip2} to @code{dist}.
10085 @trindex dist-bzip2
10087 @item @option{dist-lzip}
10088 @cindex Option, @option{dist-lzip}
10090 Hook @code{dist-lzip} to @code{dist}.
10093 @item @option{dist-shar}
10094 @cindex Option, @option{dist-shar}
10096 Hook @code{dist-shar} to @code{dist}.
10099 @item @option{dist-zip}
10100 @cindex Option, @option{dist-zip}
10102 Hook @code{dist-zip} to @code{dist}.
10105 @item @option{dist-tarZ}
10106 @cindex Option, @option{dist-tarZ}
10108 Hook @code{dist-tarZ} to @code{dist}.
10111 @item @option{filename-length-max=99}
10112 @cindex Option, @option{filename-length-max=99}
10113 @opindex filename-length-max=99
10114 Abort if file names longer than 99 characters are found during
10115 @samp{make dist}. Such long file names are generally considered not to
10116 be portable in tarballs. See the @option{tar-v7} and @option{tar-ustar}
10117 options below. This option should be used in the top-level
10118 @file{Makefile.am} or as an argument of @code{AM_INIT_AUTOMAKE} in
10119 @file{configure.ac}, it will be ignored otherwise. It will also be
10120 ignored in sub-packages of nested packages (@pxref{Subpackages}).
10122 @item @option{no-define}
10123 @cindex Option, @option{no-define}
10125 This option is meaningful only when passed as an argument to
10126 @code{AM_INIT_AUTOMAKE}. It will prevent the @code{PACKAGE} and
10127 @code{VERSION} variables from being @code{AC_DEFINE}d.
10129 @item @option{no-dependencies}
10130 @cindex Option, @option{no-dependencies}
10131 @opindex no-dependencies
10132 This is similar to using @option{--ignore-deps} on the command line,
10133 but is useful for those situations where you don't have the necessary
10134 bits to make automatic dependency tracking work
10135 (@pxref{Dependencies}). In this case the effect is to effectively
10136 disable automatic dependency tracking.
10138 @item @option{no-dist}
10139 @cindex Option, @option{no-dist}
10141 Don't emit any code related to @code{dist} target. This is useful
10142 when a package has its own method for making distributions.
10144 @item @option{no-dist-gzip}
10145 @cindex Option, @option{no-dist-gzip}
10146 @opindex no-dist-gzip
10147 Do not hook @code{dist-gzip} to @code{dist}.
10148 @trindex no-dist-gzip
10150 @item @option{no-exeext}
10151 @cindex Option, @option{no-exeext}
10153 If your @file{Makefile.am} defines a rule for target @code{foo}, it
10154 will override a rule for a target named @samp{foo$(EXEEXT)}. This is
10155 necessary when @code{EXEEXT} is found to be empty. However, by
10156 default @command{automake} will generate an error for this use. The
10157 @option{no-exeext} option will disable this error. This is intended for
10158 use only where it is known in advance that the package will not be
10159 ported to Windows, or any other operating system using extensions on
10162 @item @option{no-installinfo}
10163 @cindex Option, @option{no-installinfo}
10164 @opindex no-installinfo
10165 The generated @file{Makefile.in} will not cause info pages to be built
10166 or installed by default. However, @code{info} and @code{install-info}
10167 targets will still be available. This option is disallowed at
10168 @option{gnu} strictness and above.
10170 @trindex install-info
10172 @item @option{no-installman}
10173 @cindex Option, @option{no-installman}
10174 @opindex no-installman
10175 The generated @file{Makefile.in} will not cause man pages to be
10176 installed by default. However, an @code{install-man} target will still
10177 be available for optional installation. This option is disallowed at
10178 @option{gnu} strictness and above.
10179 @trindex install-man
10181 @item @option{nostdinc}
10182 @cindex Option, @option{nostdinc}
10184 This option can be used to disable the standard @option{-I} options that
10185 are ordinarily automatically provided by Automake.
10187 @item @option{no-texinfo.tex}
10188 @cindex Option, @option{no-texinfo.tex}
10189 @opindex no-texinfo.tex
10190 Don't require @file{texinfo.tex}, even if there are texinfo files in
10193 @item @option{parallel-tests}
10194 @cindex Option, @option{parallel-tests}
10195 @opindex parallel-tests
10196 Enable test suite harness for @code{TESTS} that can run tests in parallel
10197 (@pxref{Parallel Test Harness}, for more information).
10199 @item @option{serial-tests}
10200 @cindex Option, @option{serial-tests}
10201 @opindex serial-tests
10202 Enable the older serial test suite harness for @code{TESTS} (@pxref{Serial
10203 Test Harness}, for more information). This is still the default for the
10206 @item @option{readme-alpha}
10207 @cindex Option, @option{readme-alpha}
10208 @opindex readme-alpha
10209 If this release is an alpha release, and the file @file{README-alpha}
10210 exists, then it will be added to the distribution. If this option is
10211 given, version numbers are expected to follow one of two forms. The
10212 first form is @samp{@var{major}.@var{minor}.@var{alpha}}, where each
10213 element is a number; the final period and number should be left off for
10214 non-alpha releases. The second form is
10215 @samp{@var{major}.@var{minor}@var{alpha}}, where @var{alpha} is a
10216 letter; it should be omitted for non-alpha releases.
10218 @item @option{silent-rules}
10219 @cindex Option, @option{silent-rules}
10220 @opindex silent-rules
10221 Enable less verbose build rules. This can be used to let build rules
10222 output status lines of the form:
10224 GEN @var{output-file}
10225 CC @var{object-file}
10228 instead of printing the command that will be executed to update
10229 @var{output-file} or to compile @var{object-file}. It can also
10230 silence @command{libtool} output.
10232 For more information about how to use, enable, or disable silent
10233 rules, @pxref{Automake silent-rules Option}.
10235 @item @option{std-options}
10236 @cindex Options, @option{std-options}
10237 @cindex @samp{make installcheck}, testing @option{--help} and @option{--version}
10238 @cindex @option{--help} check
10239 @cindex @option{--version} check
10240 @opindex std-options
10242 Make the @code{installcheck} rule check that installed scripts and
10243 programs support the @option{--help} and @option{--version} options.
10244 This also provides a basic check that the program's
10245 run-time dependencies are satisfied after installation.
10247 @vindex AM_INSTALLCHECK_STD_OPTIONS_EXEMPT
10248 In a few situations, programs (or scripts) have to be exempted from this
10249 test. For instance, @command{false} (from GNU coreutils) is never
10250 successful, even for @option{--help} or @option{--version}. You can list
10251 such programs in the variable @code{AM_INSTALLCHECK_STD_OPTIONS_EXEMPT}.
10252 Programs (not scripts) listed in this variable should be suffixed by
10253 @samp{$(EXEEXT)} for the sake of Windows or OS/2. For instance, suppose we
10254 build @file{false} as a program but @file{true.sh} as a script, and that
10255 neither of them support @option{--help} or @option{--version}:
10258 AUTOMAKE_OPTIONS = std-options
10259 bin_PROGRAMS = false ...
10260 bin_SCRIPTS = true.sh ...
10261 AM_INSTALLCHECK_STD_OPTIONS_EXEMPT = false$(EXEEXT) true.sh
10264 @item @option{subdir-objects}
10265 @cindex Options, @option{subdir-objects}
10266 @opindex subdir-objects
10267 If this option is specified, then objects are placed into the
10268 subdirectory of the build directory corresponding to the subdirectory of
10269 the source file. For instance, if the source file is
10270 @file{subdir/file.cxx}, then the output file would be
10271 @file{subdir/file.o}.
10273 In order to use this option with C sources, you should add
10274 @code{AM_PROG_CC_C_O} to @file{configure.ac}.
10276 @anchor{tar-formats}
10277 @item @option{tar-v7}
10278 @itemx @option{tar-ustar}
10279 @itemx @option{tar-pax}
10280 @cindex Option, @option{tar-v7}
10281 @cindex Option, @option{tar-ustar}
10282 @cindex Option, @option{tar-pax}
10283 @cindex @command{tar} formats
10284 @cindex v7 @command{tar} format
10285 @cindex ustar format
10291 These three mutually exclusive options select the tar format to use
10292 when generating tarballs with @samp{make dist}. (The tar file created
10293 is then compressed according to the set of @option{no-dist-gzip},
10294 @option{dist-bzip2}, @option{dist-lzip}, @option{dist-xz} and
10295 @option{dist-tarZ} options in use.)
10297 These options must be passed as arguments to @code{AM_INIT_AUTOMAKE}
10298 (@pxref{Macros}) because they can require additional configure checks.
10299 Automake will complain if it sees such options in an
10300 @code{AUTOMAKE_OPTIONS} variable.
10302 @option{tar-v7} selects the old V7 tar format. This is the historical
10303 default. This antiquated format is understood by all tar
10304 implementations and supports file names with up to 99 characters. When
10305 given longer file names some tar implementations will diagnose the
10306 problem while other will generate broken tarballs or use non-portable
10307 extensions. Furthermore, the V7 format cannot store empty
10308 directories. When using this format, consider using the
10309 @option{filename-length-max=99} option to catch file names too long.
10311 @option{tar-ustar} selects the ustar format defined by POSIX
10312 1003.1-1988. This format is believed to be old enough to be portable.
10313 It fully supports empty directories. It can store file names with up
10314 to 256 characters, provided that the file name can be split at
10315 directory separator in two parts, first of them being at most 155
10316 bytes long. So, in most cases the maximum file name length will be
10317 shorter than 256 characters. However you may run against broken tar
10318 implementations that incorrectly handle file names longer than 99
10319 characters (please report them to @email{@value{PACKAGE_BUGREPORT}} so we
10320 can document this accurately).
10322 @option{tar-pax} selects the new pax interchange format defined by POSIX
10323 1003.1-2001. It does not limit the length of file names. However,
10324 this format is very young and should probably be restricted to
10325 packages that target only very modern platforms. There are moves to
10326 change the pax format in an upward-compatible way, so this option may
10327 refer to a more recent version in the future.
10329 @xref{Formats, , Controlling the Archive Format, tar, GNU Tar}, for
10330 further discussion about tar formats.
10332 @command{configure} knows several ways to construct these formats. It
10333 will not abort if it cannot find a tool up to the task (so that the
10334 package can still be built), but @samp{make dist} will fail.
10336 @item @var{version}
10337 @cindex Option, @var{version}
10338 A version number (e.g., @samp{0.30}) can be specified. If Automake is not
10339 newer than the version specified, creation of the @file{Makefile.in}
10340 will be suppressed.
10342 @item @option{-W@var{category}} or @option{--warnings=@var{category}}
10343 @cindex Option, warnings
10344 @cindex Option, @option{-W@var{category}}
10345 @cindex Option, @option{--warnings=@var{category}}
10346 These options behave exactly like their command-line counterpart
10347 (@pxref{automake Invocation}). This allows you to enable or disable some
10348 warning categories on a per-file basis. You can also setup some warnings
10349 for your entire project; for instance, try @samp{AM_INIT_AUTOMAKE([-Wall])}
10350 in your @file{configure.ac}.
10354 Unrecognized options are diagnosed by @command{automake}.
10356 If you want an option to apply to all the files in the tree, you can use
10357 the @code{AM_INIT_AUTOMAKE} macro in @file{configure.ac}.
10361 @node Miscellaneous
10362 @chapter Miscellaneous Rules
10364 There are a few rules and variables that didn't fit anywhere else.
10367 * Tags:: Interfacing to cscope, etags and mkid
10368 * Suffixes:: Handling new file extensions
10373 @section Interfacing to @command{etags}
10375 @cindex @file{TAGS} support
10377 Automake will generate rules to generate @file{TAGS} files for use with
10378 GNU Emacs under some circumstances.
10381 If any C, C++ or Fortran 77 source code or headers are present, then
10382 @code{tags} and @code{TAGS} rules will be generated for the directory.
10383 All files listed using the @code{_SOURCES}, @code{_HEADERS}, and
10384 @code{_LISP} primaries will be used to generate tags. Note that
10385 generated source files that are not distributed must be declared in
10386 variables like @code{nodist_noinst_HEADERS} or
10387 @code{nodist_@var{prog}_SOURCES} or they will be ignored.
10389 A @code{tags} rule will be output at the topmost directory of a
10390 multi-directory package. When run from this topmost directory,
10391 @samp{make tags} will generate a @file{TAGS} file that includes by
10392 reference all @file{TAGS} files from subdirectories.
10394 The @code{tags} rule will also be generated if the variable
10395 @code{ETAGS_ARGS} is defined. This variable is intended for use in
10396 directories that contain taggable source that @command{etags} does
10397 not understand. The user can use the @code{ETAGSFLAGS} to pass
10398 additional flags to @command{etags}; @code{AM_ETAGSFLAGS} is also
10399 available for use in @file{Makefile.am}.
10402 @vindex AM_ETAGSFLAGS
10404 Here is how Automake generates tags for its source, and for nodes in its
10408 ETAGS_ARGS = automake.in --lang=none \
10409 --regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi
10412 If you add file names to @code{ETAGS_ARGS}, you will probably also
10413 want to define @code{TAGS_DEPENDENCIES}. The contents of this variable
10414 are added directly to the dependencies for the @code{tags} rule.
10415 @vindex TAGS_DEPENDENCIES
10417 Automake also generates a @code{ctags} rule that can be used to
10418 build @command{vi}-style @file{tags} files. The variable @code{CTAGS}
10419 is the name of the program to invoke (by default @command{ctags});
10420 @code{CTAGSFLAGS} can be used by the user to pass additional flags,
10421 and @code{AM_CTAGSFLAGS} can be used by the @file{Makefile.am}.
10424 Automake will also generate an @code{ID} rule that will run
10425 @command{mkid} on the source. This is only supported on a
10426 directory-by-directory basis.
10428 Similarly, the @code{cscope} rule will create a list of all the source
10429 files in the tree and run @command{cscope} to build an inverted index
10430 database. The variable @code{CSCOPE} is the name of the program to invoke
10431 (by default @command{cscope}); @code{CSCOPEFLAGS} and
10432 @code{CSCOPE_ARGS} can be used by the user to pass additional flags and
10433 file names respectively, while @code{AM_CSCOPEFLAGS} can be used by the
10434 @file{Makefile.am}. Note that, currently, the Automake-provided
10435 @code{cscope} support, when used in a VPATH build, might not work well
10436 with non-GNU make implementations (especially with make implementations
10437 performing @ref{Automatic Rule Rewriting, , VPATH rewrites, autoconf,
10438 The Autoconf Manual}).
10440 Finally, Automake also emits rules to support the
10441 @uref{http://www.gnu.org/software/global/, GNU Global Tags program}.
10442 The @code{GTAGS} rule runs Global Tags and puts the
10443 result in the top build directory. The variable @code{GTAGS_ARGS}
10444 holds arguments that are passed to @command{gtags}.
10449 @section Handling new file extensions
10451 @cindex Adding new @code{SUFFIXES}
10452 @cindex @code{SUFFIXES}, adding
10455 It is sometimes useful to introduce a new implicit rule to handle a file
10456 type that Automake does not know about.
10458 For instance, suppose you had a compiler that could compile @file{.foo}
10459 files to @file{.o} files. You would simply define a suffix rule for
10467 Then you could directly use a @file{.foo} file in a @code{_SOURCES}
10468 variable and expect the correct results:
10471 bin_PROGRAMS = doit
10472 doit_SOURCES = doit.foo
10475 This was the simpler and more common case. In other cases, you will
10476 have to help Automake to figure out which extensions you are defining your
10477 suffix rule for. This usually happens when your extension does not
10478 start with a dot. Then, all you have to do is to put a list of new
10479 suffixes in the @code{SUFFIXES} variable @strong{before} you define your
10482 For instance, the following definition prevents Automake from misinterpreting
10483 the @samp{.idlC.cpp:} rule as an attempt to transform @file{.idlC} files into
10486 @c Keep in sync with suffix7.sh
10488 SUFFIXES = .idl C.cpp
10493 As you may have noted, the @code{SUFFIXES} variable behaves like the
10494 @code{.SUFFIXES} special target of @command{make}. You should not touch
10495 @code{.SUFFIXES} yourself, but use @code{SUFFIXES} instead and let
10496 Automake generate the suffix list for @code{.SUFFIXES}. Any given
10497 @code{SUFFIXES} go at the start of the generated suffixes list, followed
10498 by Automake generated suffixes not already in the list.
10504 @cindex Including @file{Makefile} fragment
10505 @cindex @file{Makefile} fragment, including
10507 Automake supports an @code{include} directive that can be used to
10508 include other @file{Makefile} fragments when @command{automake} is run.
10509 Note that these fragments are read and interpreted by @command{automake},
10510 not by @command{make}. As with conditionals, @command{make} has no idea that
10511 @code{include} is in use.
10513 There are two forms of @code{include}:
10516 @item include $(srcdir)/file
10517 Include a fragment that is found relative to the current source
10520 @item include $(top_srcdir)/file
10521 Include a fragment that is found relative to the top source directory.
10524 Note that if a fragment is included inside a conditional, then the
10525 condition applies to the entire contents of that fragment.
10527 Makefile fragments included this way are always distributed because
10528 they are needed to rebuild @file{Makefile.in}.
10531 @chapter Conditionals
10533 @cindex Conditionals
10535 Automake supports a simple type of conditionals.
10537 These conditionals are not the same as conditionals in
10538 GNU Make. Automake conditionals are checked at configure time by the
10539 @file{configure} script, and affect the translation from
10540 @file{Makefile.in} to @file{Makefile}. They are based on options passed
10541 to @file{configure} and on results that @file{configure} has discovered
10542 about the host system. GNU Make conditionals are checked at @command{make}
10543 time, and are based on variables passed to the make program or defined
10544 in the @file{Makefile}.
10546 Automake conditionals will work with any make program.
10549 * Usage of Conditionals:: Declaring conditional content
10550 * Limits of Conditionals:: Enclosing complete statements
10553 @node Usage of Conditionals
10554 @section Usage of Conditionals
10556 @acindex AM_CONDITIONAL
10557 Before using a conditional, you must define it by using
10558 @code{AM_CONDITIONAL} in the @file{configure.ac} file (@pxref{Macros}).
10560 @defmac AM_CONDITIONAL (@var{conditional}, @var{condition})
10561 The conditional name, @var{conditional}, should be a simple string
10562 starting with a letter and containing only letters, digits, and
10563 underscores. It must be different from @samp{TRUE} and @samp{FALSE}
10564 that are reserved by Automake.
10566 The shell @var{condition} (suitable for use in a shell @code{if}
10567 statement) is evaluated when @command{configure} is run. Note that you
10568 must arrange for @emph{every} @code{AM_CONDITIONAL} to be invoked every
10569 time @command{configure} is run. If @code{AM_CONDITIONAL} is run
10570 conditionally (e.g., in a shell @code{if} statement), then the result
10571 will confuse @command{automake}.
10574 @cindex @option{--enable-debug}, example
10575 @cindex Example conditional @option{--enable-debug}
10576 @cindex Conditional example, @option{--enable-debug}
10578 Conditionals typically depend upon options that the user provides to
10579 the @command{configure} script. Here is an example of how to write a
10580 conditional that is true if the user uses the @option{--enable-debug}
10584 AC_ARG_ENABLE([debug],
10585 [ --enable-debug Turn on debugging],
10586 [case "$@{enableval@}" in
10589 *) AC_MSG_ERROR([bad value $@{enableval@} for --enable-debug]) ;;
10590 esac],[debug=false])
10591 AM_CONDITIONAL([DEBUG], [test x$debug = xtrue])
10594 Here is an example of how to use that conditional in @file{Makefile.am}:
10606 noinst_PROGRAMS = $(DBG)
10609 This trivial example could also be handled using @code{EXTRA_PROGRAMS}
10610 (@pxref{Conditional Programs}).
10612 You may only test a single variable in an @code{if} statement, possibly
10613 negated using @samp{!}. The @code{else} statement may be omitted.
10614 Conditionals may be nested to any depth. You may specify an argument to
10615 @code{else} in which case it must be the negation of the condition used
10616 for the current @code{if}. Similarly you may specify the condition
10617 that is closed on the @code{endif} line:
10628 Unbalanced conditions are errors. The @code{if}, @code{else}, and
10629 @code{endif} statements should not be indented, i.e., start on column
10632 The @code{else} branch of the above two examples could be omitted,
10633 since assigning the empty string to an otherwise undefined variable
10634 makes no difference.
10636 @acindex AM_COND_IF
10637 In order to allow access to the condition registered by
10638 @code{AM_CONDITIONAL} inside @file{configure.ac}, and to allow
10639 conditional @code{AC_CONFIG_FILES}, @code{AM_COND_IF} may be used:
10641 @defmac AM_COND_IF (@var{conditional}, @ovar{if-true}, @ovar{if-false})
10642 If @var{conditional} is fulfilled, execute @var{if-true}, otherwise
10643 execute @var{if-false}. If either branch contains @code{AC_CONFIG_FILES},
10644 it will cause @command{automake} to output the rules for the respective
10645 files only for the given condition.
10648 @code{AM_COND_IF} macros may be nested when m4 quotation is used
10649 properly (@pxref{M4 Quotation, ,, autoconf, The Autoconf Manual}).
10651 @cindex Example conditional @code{AC_CONFIG_FILES}
10652 @cindex @code{AC_CONFIG_FILES}, conditional
10654 Here is an example of how to define a conditional config file:
10657 AM_CONDITIONAL([SHELL_WRAPPER], [test "x$with_wrapper" = xtrue])
10658 AM_COND_IF([SHELL_WRAPPER],
10659 [AC_CONFIG_FILES([wrapper:wrapper.in])])
10662 @node Limits of Conditionals
10663 @section Limits of Conditionals
10665 Conditionals should enclose complete statements like variables or
10666 rules definitions. Automake cannot deal with conditionals used inside
10667 a variable definition, for instance, and is not even able to diagnose
10668 this situation. The following example would not work:
10671 # This syntax is not understood by Automake
10680 However the intended definition of @code{AM_CPPFLAGS} can be achieved
10685 DEBUGFLAGS = -DDEBUG
10687 AM_CPPFLAGS = -DFEATURE_A $(DEBUGFLAGS) -DFEATURE_B
10694 AM_CPPFLAGS = -DFEATURE_A
10696 AM_CPPFLAGS += -DDEBUG
10698 AM_CPPFLAGS += -DFEATURE_B
10701 More details and examples of conditionals are described alongside
10702 various Automake features in this manual (@pxref{Conditional
10703 Subdirectories}, @pxref{Conditional Sources}, @pxref{Conditional
10704 Programs}, @pxref{Conditional Libtool Libraries}, @pxref{Conditional
10707 @node Silencing Make
10708 @chapter Silencing @command{make}
10710 @cindex Silent @command{make}
10711 @cindex Silencing @command{make}
10712 @cindex Silent rules
10713 @cindex Silent @command{make} rules
10716 * Make verbosity:: Make is verbose by default
10717 * Tricks For Silencing Make:: Standard and generic ways to silence make
10718 * Automake silent-rules Option:: How Automake can help in silencing make
10721 @node Make verbosity
10722 @section Make is verbose by default
10724 Normally, when executing the set of rules associated with a target,
10725 @command{make} prints each rule before it is executed. This behaviour,
10726 while having been in place for a long time, and being even mandated by
10727 the POSIX standard, starkly violates the ``silence is golden'' UNIX
10728 principle@footnote{See also
10729 @uref{http://catb.org/~esr/writings/taoup/html/ch11s09.html}.}:
10732 When a program has nothing interesting or surprising to say, it should
10733 say nothing. Well-behaved Unix programs do their jobs unobtrusively,
10734 with a minimum of fuss and bother. Silence is golden.
10737 In fact, while such verbosity of @command{make} can theoretically be
10738 useful to track bugs and understand reasons of failures right away, it
10739 can also hide warning and error messages from @command{make}-invoked
10740 tools, drowning them in a flood of uninteresting and seldom useful
10741 messages, and thus allowing them to go easily undetected.
10743 This problem can be very annoying, especially for developers, who usually
10744 know quite well what's going on behind the scenes, and for whom the
10745 verbose output from @command{make} ends up being mostly noise that hampers
10746 the easy detection of potentially important warning messages.
10748 @node Tricks For Silencing Make
10749 @section Standard and generic ways to silence make
10751 Here we describe some common idioms/tricks to obtain a quieter make
10752 output, with their relative advantages and drawbacks. In the next
10753 section (@ref{Automake silent-rules Option}) we'll see how Automake
10754 can help in this respect.
10758 @item @command{make -s}
10760 This simply causes @command{make} not to print @emph{any} rule before
10763 The @option{-s} flag is mandated by POSIX, universally supported, and
10764 its purpose and function are easy to understand.
10766 But it also has its serious limitations too. First of all, it embodies
10767 an ``all or nothing'' strategy, i.e., either everything is silenced, or
10768 nothing is; this lack of granularity can sometimes be a fatal flaw.
10769 Moreover, when the @option{-s} flag is used, the @command{make} output
10770 might turn out to be too much terse; in case of errors, the user won't
10771 be able to easily see what rule or command have caused them, or even,
10772 in case of tools with poor error reporting, what the errors were!
10774 @item @command{make >/dev/null || make}
10776 Apparently, this perfectly obeys the ``silence is golden'' rule: warnings
10777 from stderr are passed through, output reporting is done only in case of
10778 error, and in that case it should provide a verbose-enough report to allow
10779 an easy determination of the error location and causes.
10781 However, calling @command{make} two times in a row might hide errors
10782 (especially intermittent ones), or subtly change the expected semantic
10783 of the @command{make} calls --- things these which can clearly make
10784 debugging and error assessment very difficult.
10786 @item @command{make --no-print-directory}
10788 This is GNU @command{make} specific. When called with the
10789 @option{--no-print-directory} option, GNU @command{make} will disable
10790 printing of the working directory by invoked sub-@command{make}s (the
10791 well-known ``@i{Entering/Leaving directory ...}'' messages). This helps
10792 to decrease the verbosity of the output, but experience has shown that
10793 it can also often render debugging considerably harder in projects using
10794 deeply-nested @command{make} recursion.
10796 As an aside, notice that the @option{--no-print-directory} option is
10797 automatically activated if the @option{-s} flag is used.
10799 @c TODO: Other tricks?
10800 @c TODO: Maybe speak about the @code{.SILENT} target?
10801 @c TODO: - Pros: More granularity on what to silence.
10802 @c TODO: - Cons: No easy way to temporarily override.
10806 @node Automake silent-rules Option
10807 @section How Automake can help in silencing make
10809 The tricks and idioms for silencing @command{make} described in the
10810 previous section can be useful from time to time, but we've seen that
10811 they all have their serious drawbacks and limitations. That's why
10812 automake provides support for a more advanced and flexible way of
10813 obtaining quieter output from @command{make}: the @option{silent-rules}
10816 @c TODO: Maybe describe in brief the precedent set by the build system
10817 @c of the Linux Kernel, from which Automake took inspiration ... Links?
10819 To give the gist of what @option{silent-rules} can do, here is a simple
10820 comparison between a typical @command{make} output (where silent rules
10821 are disabled) and one with silent rules enabled:
10824 % @kbd{cat Makefile.am}
10826 foo_SOURCES = main.c func.c
10828 int main (void) @{ return func (); @} /* func used undeclared */
10830 int func (void) @{ int i; return i; @} /* i used uninitialized */
10832 @i{The make output is by default very verbose. This causes warnings
10833 from the compiler to be somewhat hidden, and not immediate to spot.}
10834 % @kbd{make CFLAGS=-Wall}
10835 gcc -DPACKAGE_NAME=\"foo\" -DPACKAGE_TARNAME=\"foo\" ...
10836 -DPACKAGE_STRING=\"foo\ 1.0\" -DPACKAGE_BUGREPORT=\"\" ...
10837 -DPACKAGE=\"foo\" -DVERSION=\"1.0\" -I. -Wall -MT main.o
10838 -MD -MP -MF .deps/main.Tpo -c -o main.o main.c
10839 main.c: In function ‘main’:
10840 main.c:3:3: warning: implicit declaration of function ‘func’
10841 mv -f .deps/main.Tpo .deps/main.Po
10842 gcc -DPACKAGE_NAME=\"foo\" -DPACKAGE_TARNAME=\"foo\" ...
10843 -DPACKAGE_STRING=\"foo\ 1.0\" -DPACKAGE_BUGREPORT=\"\" ...
10844 -DPACKAGE=\"foo\" -DVERSION=\"1.0\" -I. -Wall -MT func.o
10845 -MD -MP -MF .deps/func.Tpo -c -o func.o func.c
10846 func.c: In function ‘func’:
10847 func.c:4:3: warning: ‘i’ used uninitialized in this function
10848 mv -f .deps/func.Tpo .deps/func.Po
10849 gcc -Wall -o foo main.o func.o
10851 @i{Clean up, so that we we can rebuild everything from scratch.}
10853 test -z "foo" || rm -f foo
10856 @i{Silent rules enabled: the output is minimal but informative. In
10857 particular, the warnings from the compiler stick out very clearly.}
10858 % @kbd{make V=0 CFLAGS=-Wall}
10860 main.c: In function ‘main’:
10861 main.c:3:3: warning: implicit declaration of function ‘func’
10863 func.c: In function ‘func’:
10864 func.c:4:3: warning: ‘i’ used uninitialized in this function
10868 @cindex silent-rules and libtool
10869 Also, in projects using @command{libtool}, the use of silent rules can
10870 automatically enable the @command{libtool}'s @option{--silent} option:
10873 % @kbd{cat Makefile.am}
10874 lib_LTLIBRARIES = libx.la
10876 % @kbd{make # Both make and libtool are verbose by default.}
10878 libtool: compile: gcc -DPACKAGE_NAME=\"foo\" ... -DLT_OBJDIR=\".libs/\"
10879 -I. -g -O2 -MT libx.lo -MD -MP -MF .deps/libx.Tpo -c libx.c -fPIC
10880 -DPIC -o .libs/libx.o
10881 mv -f .deps/libx.Tpo .deps/libx.Plo
10882 /bin/sh ./libtool --tag=CC --mode=link gcc -g -O2 -o libx.la -rpath
10883 /usr/local/lib libx.lo
10884 libtool: link: gcc -shared .libs/libx.o -Wl,-soname -Wl,libx.so.0
10885 -o .libs/libx.so.0.0.0
10886 libtool: link: cd .libs && rm -f libx.so && ln -s libx.so.0.0.0 libx.so
10894 Let's now see how the @option{silent-rules} mode interfaces with the
10895 package developer and the package user.
10897 To enable the use of @option{silent-rules} in his package, a developer
10898 needs to do either of the following:
10902 Add the @option{silent-rules} option as argument to @code{AM_INIT_AUTOMAKE}.
10904 Call the @code{AM_SILENT_RULES} macro from within the @file{configure.ac}
10908 It is not possible to instead specify @option{silent-rules} in a
10909 @file{Makefile.am} file.
10911 If the developer has done either of the above, then the user of the
10912 package may influence the verbosity at @command{configure} run time as
10913 well as at @command{make} run time:
10917 @opindex --enable-silent-rules
10918 @opindex --disable-silent-rules
10919 Passing @option{--enable-silent-rules} to @command{configure} will cause
10920 build rules to be less verbose; the option @option{--disable-silent-rules}
10921 will cause normal verbose output.
10924 At @command{make} run time, the default chosen at @command{configure}
10925 time may be overridden: @code{make V=1} will produce verbose output,
10926 @code{make V=0} less verbose output.
10929 @cindex default verbosity for silent-rules
10930 Note that silent rules are @emph{disabled} by default; the user must
10931 enable them explicitly at either @command{configure} run time or at
10932 @command{make} run time. We think that this is a good policy, since
10933 it provides the casual user with enough information to prepare a good
10934 bug report in case anything breaks.
10936 Still, notwithstanding the rationales above, a developer who wants to
10937 make silent rules enabled by default in his own package can do so by
10938 adding a @samp{yes} argument to the @code{AM_SILENT_RULES} call in
10939 @file{configure.ac}. We advise against this approach, though.
10941 @c Keep in sync with silent-configsite.sh
10942 Users who prefer to have silent rules enabled by default can edit their
10943 @file{config.site} file to make the variable @code{enable_silent_rules}
10944 default to @samp{yes}. This should still allow disabling silent rules
10945 at @command{configure} time and at @command{make} time.
10947 @c FIXME: there's really a need to specify this explicitly?
10948 For portability to different @command{make} implementations, package authors
10949 are advised to not set the variable @code{V} inside the @file{Makefile.am}
10950 file, to allow the user to override the value for subdirectories as well.
10952 The current implementation of this feature normally uses nested
10953 variable expansion @samp{$(@var{var1}$(V))}, a @file{Makefile} feature
10954 that is not required by POSIX 2008 but is widely supported in
10955 practice. The @option{silent-rules} option thus turns off warnings
10956 about recursive variable expansion, which are in turn enabled by
10957 @option{-Wportability} (@pxref{automake Invocation}). On the rare
10958 @command{make} implementations that do not support nested variable
10959 expansion, whether rules are silent is always determined at configure
10960 time, and cannot be overridden at make time. Future versions of POSIX
10961 are likely to require nested variable expansion, so this minor
10962 limitation should go away with time.
10964 @vindex @code{AM_V_GEN}
10965 @vindex @code{AM_V_at}
10966 @vindex @code{AM_DEFAULT_VERBOSITY}
10967 @vindex @code{AM_V}
10968 @vindex @code{AM_DEFAULT_V}
10969 To extend the silent mode to your own rules, you have two choices:
10973 You can use the predefined variable @code{AM_V_GEN} as a prefix to
10974 commands that should output a status line in silent mode, and
10975 @code{AM_V_at} as a prefix to commands that should not output anything
10976 in silent mode. When output is to be verbose, both of these variables
10977 will expand to the empty string.
10979 You can add your own variables, so strings of your own choice are shown.
10980 The following snippet shows how you would define your own equivalent of
10984 pkg_verbose = $(pkg_verbose_@@AM_V@@)
10985 pkg_verbose_ = $(pkg_verbose_@@AM_DEFAULT_V@@)
10986 pkg_verbose_0 = @@echo PKG-GEN $@@;
10989 $(pkg_verbose)cp $(srcdir)/foo.in $@@
10994 As a final note, observe that, even when silent rules are enabled,
10995 the @option{--no-print-directory} option is still required with GNU
10996 @command{make} if the ``@i{Entering/Leaving directory ...}'' messages
10997 are to be disabled.
11000 @chapter The effect of @option{--gnu} and @option{--gnits}
11002 @cindex @option{--gnu}, required files
11003 @cindex @option{--gnu}, complete description
11005 The @option{--gnu} option (or @option{gnu} in the
11006 @code{AUTOMAKE_OPTIONS} variable) causes @command{automake} to check
11011 The files @file{INSTALL}, @file{NEWS}, @file{README}, @file{AUTHORS},
11012 and @file{ChangeLog}, plus one of @file{COPYING.LIB}, @file{COPYING.LESSER}
11013 or @file{COPYING}, are required at the topmost directory of the package.
11015 If the @option{--add-missing} option is given, @command{automake} will
11016 add a generic version of the @file{INSTALL} file as well as the
11017 @file{COPYING} file containing the text of the current version of the
11018 GNU General Public License existing at the time of this Automake release
11019 (version 3 as this is written, @uref{http://www.gnu.org/@/copyleft/@/gpl.html}).
11020 However, an existing @file{COPYING} file will never be overwritten by
11021 @command{automake}.
11024 The options @option{no-installman} and @option{no-installinfo} are
11028 Note that this option will be extended in the future to do even more
11029 checking; it is advisable to be familiar with the precise requirements
11030 of the GNU standards. Also, @option{--gnu} can require certain
11031 non-standard GNU programs to exist for use by various maintainer-only
11032 rules; for instance, in the future @command{pathchk} might be required for
11035 @cindex @option{--gnits}, complete description
11037 The @option{--gnits} option does everything that @option{--gnu} does, and
11038 checks the following as well:
11042 @samp{make installcheck} will check to make sure that the @option{--help}
11043 and @option{--version} really print a usage message and a version string,
11044 respectively. This is the @option{std-options} option (@pxref{Options}).
11047 @samp{make dist} will check to make sure the @file{NEWS} file has been
11048 updated to the current version.
11051 @code{VERSION} is checked to make sure its format complies with Gnits
11053 @c FIXME xref when standards are finished
11056 @cindex @file{README-alpha}
11057 If @code{VERSION} indicates that this is an alpha release, and the file
11058 @file{README-alpha} appears in the topmost directory of a package, then
11059 it is included in the distribution. This is done in @option{--gnits}
11060 mode, and no other, because this mode is the only one where version
11061 number formats are constrained, and hence the only mode where Automake
11062 can automatically determine whether @file{README-alpha} should be
11066 The file @file{THANKS} is required.
11071 @chapter The effect of @option{--cygnus}
11073 @cindex @option{cygnus} strictness
11075 @emph{The features described in this section are deprecated; you must
11076 not use any of them in new code, and should remove their use from older
11077 but still maintained code: they will be withdrawn the next major Automake
11080 Some packages, notably GNU GCC and GNU gdb, used to have a build
11081 environment originally written at Cygnus Support (subsequently renamed
11082 Cygnus Solutions, and then later purchased by Red Hat). Packages with
11083 this ancestry are sometimes referred to as ``Cygnus'' trees.
11085 A Cygnus tree has slightly different rules for how a
11086 @file{Makefile.in} is to be constructed. Passing @option{--cygnus} to
11087 @command{automake} will cause any generated @file{Makefile.in} to
11088 comply with Cygnus rules.
11090 Here are the precise effects of @option{--cygnus}:
11095 The @option{foreign} strictness is implied.
11098 The options @option{no-installinfo}, @option{no-dependencies} and
11099 @option{no-dist} are implied (@pxref{Options}).
11102 The macro @code{AM_MAINTAINER_MODE} is required.
11105 Info files are always created in the build directory, and not in the
11106 source directory. Packages that don't use the @option{cygnus} option
11107 can emulate this effect by using the @option{no-installinfo} option
11108 and listing the generated info files in the @code{CLEANFILES} variable.
11111 @file{texinfo.tex} is not required if a Texinfo source file is
11112 specified. The assumption is that the file will be supplied, but in a
11113 place that Automake cannot find -- it is an artifact of how Cygnus
11114 packages are typically bundled. This effect can be emulated in
11115 packages not using the @option{cygnus} option with a proper definition
11116 of the @code{TEXINFO_TEX} variable (@pxref{Texinfo}).
11119 Certain tools will be searched for in the build tree as well as in the
11120 user's @env{PATH}. These tools are @command{runtest}, @command{expect},
11121 @command{makeinfo} and @command{texi2dvi}.
11124 The @code{check} target doesn't depend on @code{all}.
11129 @chapter When Automake Isn't Enough
11131 In some situations, where Automake is not up to one task, one has to
11132 resort to handwritten rules or even handwritten @file{Makefile}s.
11135 * Extending:: Adding new rules or overriding existing ones.
11136 * Third-Party Makefiles:: Integrating Non-Automake @file{Makefile}s.
11140 @section Extending Automake Rules
11142 With some minor exceptions (for example @code{_PROGRAMS} variables,
11143 @code{TESTS}, or @code{XFAIL_TESTS}) being rewritten to append
11144 @samp{$(EXEEXT)}), the contents of a @file{Makefile.am} is copied to
11145 @file{Makefile.in} verbatim.
11147 @cindex copying semantics
11149 These copying semantics mean that many problems can be worked around
11150 by simply adding some @command{make} variables and rules to
11151 @file{Makefile.am}. Automake will ignore these additions.
11153 @cindex conflicting definitions
11154 @cindex rules, conflicting
11155 @cindex variables, conflicting
11156 @cindex definitions, conflicts
11158 Since a @file{Makefile.in} is built from data gathered from three
11159 different places (@file{Makefile.am}, @file{configure.ac}, and
11160 @command{automake} itself), it is possible to have conflicting
11161 definitions of rules or variables. When building @file{Makefile.in}
11162 the following priorities are respected by @command{automake} to ensure
11163 the user always has the last word:
11167 User defined variables in @file{Makefile.am} have priority over
11168 variables @code{AC_SUBST}ed from @file{configure.ac}, and
11169 @code{AC_SUBST}ed variables have priority over
11170 @command{automake}-defined variables.
11172 As far as rules are concerned, a user-defined rule overrides any
11173 @command{automake}-defined rule for the same target.
11176 @cindex overriding rules
11177 @cindex overriding semantics
11178 @cindex rules, overriding
11180 These overriding semantics make it possible to fine tune some default
11181 settings of Automake, or replace some of its rules. Overriding
11182 Automake rules is often inadvisable, particularly in the topmost
11183 directory of a package with subdirectories. The @option{-Woverride}
11184 option (@pxref{automake Invocation}) comes in handy to catch overridden
11187 Note that Automake does not make any distinction between rules with
11188 commands and rules that only specify dependencies. So it is not
11189 possible to append new dependencies to an @command{automake}-defined
11190 target without redefining the entire rule.
11192 @cindex @option{-local} targets
11193 @cindex local targets
11195 However, various useful targets have a @samp{-local} version you can
11196 specify in your @file{Makefile.am}. Automake will supplement the
11197 standard target with these user-supplied targets.
11202 @trindex info-local
11210 @trindex html-local
11212 @trindex check-local
11214 @trindex install-data
11215 @trindex install-data-local
11216 @trindex install-dvi
11217 @trindex install-dvi-local
11218 @trindex install-exec
11219 @trindex install-exec-local
11220 @trindex install-html
11221 @trindex install-html-local
11222 @trindex install-info
11223 @trindex install-info-local
11224 @trindex install-pdf
11225 @trindex install-pdf-local
11226 @trindex install-ps
11227 @trindex install-ps-local
11229 @trindex uninstall-local
11230 @trindex mostlyclean
11231 @trindex mostlyclean-local
11233 @trindex clean-local
11235 @trindex distclean-local
11236 @trindex installdirs
11237 @trindex installdirs-local
11238 @trindex installcheck
11239 @trindex installcheck-local
11241 The targets that support a local version are @code{all}, @code{info},
11242 @code{dvi}, @code{ps}, @code{pdf}, @code{html}, @code{check},
11243 @code{install-data}, @code{install-dvi}, @code{install-exec},
11244 @code{install-html}, @code{install-info}, @code{install-pdf},
11245 @code{install-ps}, @code{uninstall}, @code{installdirs},
11246 @code{installcheck} and the various @code{clean} targets
11247 (@code{mostlyclean}, @code{clean}, @code{distclean}, and
11248 @code{maintainer-clean}).
11250 Note that there are no @code{uninstall-exec-local} or
11251 @code{uninstall-data-local} targets; just use @code{uninstall-local}.
11252 It doesn't make sense to uninstall just data or just executables.
11254 For instance, here is one way to erase a subdirectory during
11255 @samp{make clean} (@pxref{Clean}).
11262 You may be tempted to use @code{install-data-local} to install a file
11263 to some hard-coded location, but you should avoid this
11264 (@pxref{Hard-Coded Install Paths}).
11266 With the @code{-local} targets, there is no particular guarantee of
11267 execution order; typically, they are run early, but with parallel
11268 make, there is no way to be sure of that.
11270 @cindex @option{-hook} targets
11271 @cindex hook targets
11272 @trindex install-data-hook
11273 @trindex install-exec-hook
11274 @trindex uninstall-hook
11277 In contrast, some rules also have a way to run another rule, called a
11278 @dfn{hook}; hooks are always executed after the main rule's work is done.
11279 The hook is named after the principal target, with @samp{-hook} appended.
11280 The targets allowing hooks are @code{install-data},
11281 @code{install-exec}, @code{uninstall}, @code{dist}, and
11284 For instance, here is how to create a hard link to an installed program:
11288 ln $(DESTDIR)$(bindir)/program$(EXEEXT) \
11289 $(DESTDIR)$(bindir)/proglink$(EXEEXT)
11292 Although cheaper and more portable than symbolic links, hard links
11293 will not work everywhere (for instance, OS/2 does not have
11294 @command{ln}). Ideally you should fall back to @samp{cp -p} when
11295 @command{ln} does not work. An easy way, if symbolic links are
11296 acceptable to you, is to add @code{AC_PROG_LN_S} to
11297 @file{configure.ac} (@pxref{Particular Programs, , Particular Program
11298 Checks, autoconf, The Autoconf Manual}) and use @samp{$(LN_S)} in
11299 @file{Makefile.am}.
11301 @cindex versioned binaries, installing
11302 @cindex installing versioned binaries
11303 @cindex @code{LN_S} example
11304 For instance, here is how you could install a versioned copy of a
11305 program using @samp{$(LN_S)}:
11307 @c Keep in sync with insthook.sh
11310 cd $(DESTDIR)$(bindir) && \
11311 mv -f prog$(EXEEXT) prog-$(VERSION)$(EXEEXT) && \
11312 $(LN_S) prog-$(VERSION)$(EXEEXT) prog$(EXEEXT)
11315 Note that we rename the program so that a new version will erase the
11316 symbolic link, not the real binary. Also we @command{cd} into the
11317 destination directory in order to create relative links.
11319 When writing @code{install-exec-hook} or @code{install-data-hook},
11320 please bear in mind that the exec/data distinction is based on the
11321 installation directory, not on the primary used (@pxref{The Two Parts of
11323 @c Keep in sync with primary-prefix-couples-documented-valid.sh
11324 So a @code{foo_SCRIPTS} will be installed by
11325 @code{install-data}, and a @code{barexec_SCRIPTS} will be installed by
11326 @code{install-exec}. You should define your hooks consequently.
11328 @c FIXME should include discussion of variables you can use in these
11331 @node Third-Party Makefiles
11332 @section Third-Party @file{Makefile}s
11334 @cindex Third-party packages, interfacing with
11335 @cindex Interfacing with third-party packages
11337 In most projects all @file{Makefile}s are generated by Automake. In
11338 some cases, however, projects need to embed subdirectories with
11339 handwritten @file{Makefile}s. For instance, one subdirectory could be
11340 a third-party project with its own build system, not using Automake.
11342 It is possible to list arbitrary directories in @code{SUBDIRS} or
11343 @code{DIST_SUBDIRS} provided each of these directories has a
11344 @file{Makefile} that recognizes all the following recursive targets.
11346 @cindex recursive targets and third-party @file{Makefile}s
11347 When a user runs one of these targets, that target is run recursively
11348 in all subdirectories. This is why it is important that even
11349 third-party @file{Makefile}s support them.
11353 Compile the entire package. This is the default target in
11354 Automake-generated @file{Makefile}s, but it does not need to be the
11355 default in third-party @file{Makefile}s.
11360 @vindex top_distdir
11361 Copy files to distribute into @samp{$(distdir)}, before a tarball is
11362 constructed. Of course this target is not required if the
11363 @option{no-dist} option (@pxref{Options}) is used.
11365 The variables @samp{$(top_distdir)} and @samp{$(distdir)}
11366 (@pxref{The dist Hook}) will be passed from the outer package to the subpackage
11367 when the @code{distdir} target is invoked. These two variables have
11368 been adjusted for the directory that is being recursed into, so they
11372 @itemx install-data
11373 @itemx install-exec
11375 Install or uninstall files (@pxref{Install}).
11378 @itemx install-html
11379 @itemx install-info
11382 Install only some specific documentation format (@pxref{Texinfo}).
11385 Create install directories, but do not install any files.
11388 @itemx installcheck
11389 Check the package (@pxref{Tests}).
11394 @itemx maintainer-clean
11395 Cleaning rules (@pxref{Clean}).
11402 Build the documentation in various formats (@pxref{Texinfo}).
11406 Build @file{TAGS} and @file{CTAGS} (@pxref{Tags}).
11409 If you have ever used Gettext in a project, this is a good example of
11410 how third-party @file{Makefile}s can be used with Automake. The
11411 @file{Makefile}s @command{gettextize} puts in the @file{po/} and
11412 @file{intl/} directories are handwritten @file{Makefile}s that
11413 implement all of these targets. That way they can be added to
11414 @code{SUBDIRS} in Automake packages.
11416 Directories that are only listed in @code{DIST_SUBDIRS} but not in
11417 @code{SUBDIRS} need only the @code{distclean},
11418 @code{maintainer-clean}, and @code{distdir} rules (@pxref{Conditional
11421 Usually, many of these rules are irrelevant to the third-party
11422 subproject, but they are required for the whole package to work. It's
11423 OK to have a rule that does nothing, so if you are integrating a
11424 third-party project with no documentation or tag support, you could
11425 simply augment its @file{Makefile} as follows:
11428 EMPTY_AUTOMAKE_TARGETS = dvi pdf ps info html tags ctags
11429 .PHONY: $(EMPTY_AUTOMAKE_TARGETS)
11430 $(EMPTY_AUTOMAKE_TARGETS):
11433 Another aspect of integrating third-party build systems is whether
11434 they support VPATH builds (@pxref{VPATH Builds}). Obviously if the
11435 subpackage does not support VPATH builds the whole package will not
11436 support VPATH builds. This in turns means that @samp{make distcheck}
11437 will not work, because it relies on VPATH builds. Some people can
11438 live without this (actually, many Automake users have never heard of
11439 @samp{make distcheck}). Other people may prefer to revamp the
11440 existing @file{Makefile}s to support VPATH@. Doing so does not
11441 necessarily require Automake, only Autoconf is needed (@pxref{Build
11442 Directories, , Build Directories, autoconf, The Autoconf Manual}).
11443 The necessary substitutions: @samp{@@srcdir@@}, @samp{@@top_srcdir@@},
11444 and @samp{@@top_builddir@@} are defined by @file{configure} when it
11445 processes a @file{Makefile} (@pxref{Preset Output Variables, , Preset
11446 Output Variables, autoconf, The Autoconf Manual}), they are not
11447 computed by the Makefile like the aforementioned @samp{$(distdir)} and
11448 @samp{$(top_distdir)} variables.
11450 It is sometimes inconvenient to modify a third-party @file{Makefile}
11451 to introduce the above required targets. For instance, one may want to
11452 keep the third-party sources untouched to ease upgrades to new
11455 @cindex @file{GNUmakefile} including @file{Makefile}
11456 Here are two other ideas. If GNU make is assumed, one possibility is
11457 to add to that subdirectory a @file{GNUmakefile} that defines the
11458 required targets and includes the third-party @file{Makefile}. For
11459 this to work in VPATH builds, @file{GNUmakefile} must lie in the build
11460 directory; the easiest way to do this is to write a
11461 @file{GNUmakefile.in} instead, and have it processed with
11462 @code{AC_CONFIG_FILES} from the outer package. For example if we
11463 assume @file{Makefile} defines all targets except the documentation
11464 targets, and that the @code{check} target is actually called
11465 @code{test}, we could write @file{GNUmakefile} (or
11466 @file{GNUmakefile.in}) like this:
11469 # First, include the real Makefile
11471 # Then, define the other targets needed by Automake Makefiles.
11472 .PHONY: dvi pdf ps info html check
11473 dvi pdf ps info html:
11477 @cindex Proxy @file{Makefile} for third-party packages
11478 A similar idea that does not use @code{include} is to write a proxy
11479 @file{Makefile} that dispatches rules to the real @file{Makefile},
11480 either with @samp{$(MAKE) -f Makefile.real $(AM_MAKEFLAGS) target} (if
11481 it's OK to rename the original @file{Makefile}) or with @samp{cd
11482 subdir && $(MAKE) $(AM_MAKEFLAGS) target} (if it's OK to store the
11483 subdirectory project one directory deeper). The good news is that
11484 this proxy @file{Makefile} can be generated with Automake. All we
11485 need are @option{-local} targets (@pxref{Extending}) that perform the
11486 dispatch. Of course the other Automake features are available, so you
11487 could decide to let Automake perform distribution or installation.
11488 Here is a possible @file{Makefile.am}:
11492 cd subdir && $(MAKE) $(AM_MAKEFLAGS) all
11494 cd subdir && $(MAKE) $(AM_MAKEFLAGS) test
11496 cd subdir && $(MAKE) $(AM_MAKEFLAGS) clean
11498 # Assuming the package knows how to install itself
11499 install-data-local:
11500 cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-data
11501 install-exec-local:
11502 cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-exec
11504 cd subdir && $(MAKE) $(AM_MAKEFLAGS) uninstall
11506 # Distribute files from here.
11507 EXTRA_DIST = subdir/Makefile subdir/program.c ...
11510 Pushing this idea to the extreme, it is also possible to ignore the
11511 subproject build system and build everything from this proxy
11512 @file{Makefile.am}. This might sound very sensible if you need VPATH
11513 builds but the subproject does not support them.
11516 @chapter Distributing @file{Makefile.in}s
11518 Automake places no restrictions on the distribution of the resulting
11519 @file{Makefile.in}s. We still encourage software authors to
11520 distribute their work under terms like those of the GPL, but doing so
11521 is not required to use Automake.
11523 Some of the files that can be automatically installed via the
11524 @option{--add-missing} switch do fall under the GPL@. However, these also
11525 have a special exception allowing you to distribute them with your
11526 package, regardless of the licensing you choose.
11529 @node API Versioning
11530 @chapter Automake API Versioning
11532 New Automake releases usually include bug fixes and new features.
11533 Unfortunately they may also introduce new bugs and incompatibilities.
11534 This makes four reasons why a package may require a particular Automake
11537 Things get worse when maintaining a large tree of packages, each one
11538 requiring a different version of Automake. In the past, this meant that
11539 any developer (and sometimes users) had to install several versions of
11540 Automake in different places, and switch @samp{$PATH} appropriately for
11543 Starting with version 1.6, Automake installs versioned binaries. This
11544 means you can install several versions of Automake in the same
11545 @samp{$prefix}, and can select an arbitrary Automake version by running
11546 @command{automake-1.6} or @command{automake-1.7} without juggling with
11547 @samp{$PATH}. Furthermore, @file{Makefile}'s generated by Automake 1.6
11548 will use @command{automake-1.6} explicitly in their rebuild rules.
11550 The number @samp{1.6} in @command{automake-1.6} is Automake's API version,
11551 not Automake's version. If a bug fix release is made, for instance
11552 Automake 1.6.1, the API version will remain 1.6. This means that a
11553 package that works with Automake 1.6 should also work with 1.6.1; after
11554 all, this is what people expect from bug fix releases.
11556 If your package relies on a feature or a bug fix introduced in
11557 a release, you can pass this version as an option to Automake to ensure
11558 older releases will not be used. For instance, use this in your
11559 @file{configure.ac}:
11562 AM_INIT_AUTOMAKE([1.6.1]) dnl Require Automake 1.6.1 or better.
11566 or, in a particular @file{Makefile.am}:
11569 AUTOMAKE_OPTIONS = 1.6.1 # Require Automake 1.6.1 or better.
11573 Automake will print an error message if its version is
11574 older than the requested version.
11577 @heading What is in the API
11579 Automake's programming interface is not easy to define. Basically it
11580 should include at least all @strong{documented} variables and targets
11581 that a @file{Makefile.am} author can use, any behavior associated with
11582 them (e.g., the places where @samp{-hook}'s are run), the command line
11583 interface of @command{automake} and @command{aclocal}, @dots{}
11585 @heading What is not in the API
11587 Every undocumented variable, target, or command line option, is not part
11588 of the API@. You should avoid using them, as they could change from one
11589 version to the other (even in bug fix releases, if this helps to fix a
11592 If it turns out you need to use such an undocumented feature, contact
11593 @email{automake@@gnu.org} and try to get it documented and exercised by
11597 @chapter Upgrading a Package to a Newer Automake Version
11599 Automake maintains three kind of files in a package.
11602 @item @file{aclocal.m4}
11603 @item @file{Makefile.in}s
11604 @item auxiliary tools like @file{install-sh} or @file{py-compile}
11607 @file{aclocal.m4} is generated by @command{aclocal} and contains some
11608 Automake-supplied M4 macros. Auxiliary tools are installed by
11609 @samp{automake --add-missing} when needed. @file{Makefile.in}s are
11610 built from @file{Makefile.am} by @command{automake}, and rely on the
11611 definitions of the M4 macros put in @file{aclocal.m4} as well as the
11612 behavior of the auxiliary tools installed.
11614 Because all of these files are closely related, it is important to
11615 regenerate all of them when upgrading to a newer Automake release.
11616 The usual way to do that is
11619 aclocal # with any option needed (such a -I m4)
11621 automake --add-missing --force-missing
11625 or more conveniently:
11631 The use of @option{--force-missing} ensures that auxiliary tools will be
11632 overridden by new versions (@pxref{automake Invocation}).
11634 It is important to regenerate all of these files each time Automake is
11635 upgraded, even between bug fixes releases. For instance, it is not
11636 unusual for a bug fix to involve changes to both the rules generated
11637 in @file{Makefile.in} and the supporting M4 macros copied to
11640 Presently @command{automake} is able to diagnose situations where
11641 @file{aclocal.m4} has been generated with another version of
11642 @command{aclocal}. However it never checks whether auxiliary scripts
11643 are up-to-date. In other words, @command{automake} will tell you when
11644 @command{aclocal} needs to be rerun, but it will never diagnose a
11645 missing @option{--force-missing}.
11647 Before upgrading to a new major release, it is a good idea to read the
11648 file @file{NEWS}. This file lists all changes between releases: new
11649 features, obsolete constructs, known incompatibilities, and
11653 @chapter Frequently Asked Questions about Automake
11655 This chapter covers some questions that often come up on the mailing
11659 * CVS:: CVS and generated files
11660 * maintainer-mode:: missing and AM_MAINTAINER_MODE
11661 * Wildcards:: Why doesn't Automake support wildcards?
11662 * Limitations on File Names:: Limitations on source and installed file names
11663 * Errors with distclean:: Files left in build directory after distclean
11664 * Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS
11665 * Renamed Objects:: Why are object files sometimes renamed?
11666 * Per-Object Flags:: How to simulate per-object flags?
11667 * Multiple Outputs:: Writing rules for tools with many output files
11668 * Hard-Coded Install Paths:: Installing to hard-coded locations
11669 * Debugging Make Rules:: Strategies when things don't work as expected
11670 * Reporting Bugs:: Feedback on bugs and feature requests
11674 @section CVS and generated files
11676 @subheading Background: distributed generated Files
11677 @cindex generated files, distributed
11678 @cindex rebuild rules
11680 Packages made with Autoconf and Automake ship with some generated
11681 files like @file{configure} or @file{Makefile.in}. These files were
11682 generated on the developer's host and are distributed so that
11683 end-users do not have to install the maintainer tools required to
11684 rebuild them. Other generated files like Lex scanners, Yacc parsers,
11685 or Info documentation, are usually distributed on similar grounds.
11687 Automake outputs rules in @file{Makefile}s to rebuild these files. For
11688 instance, @command{make} will run @command{autoconf} to rebuild
11689 @file{configure} whenever @file{configure.ac} is changed. This makes
11690 development safer by ensuring a @file{configure} is never out-of-date
11691 with respect to @file{configure.ac}.
11693 As generated files shipped in packages are up-to-date, and because
11694 @command{tar} preserves times-tamps, these rebuild rules are not
11695 triggered when a user unpacks and builds a package.
11697 @subheading Background: CVS and Timestamps
11698 @cindex timestamps and CVS
11699 @cindex CVS and timestamps
11701 Unless you use CVS keywords (in which case files must be updated at
11702 commit time), CVS preserves timestamp during @samp{cvs commit} and
11703 @samp{cvs import -d} operations.
11705 When you check out a file using @samp{cvs checkout} its timestamp is
11706 set to that of the revision that is being checked out.
11708 However, during @command{cvs update}, files will have the date of the
11709 update, not the original timestamp of this revision. This is meant to
11710 make sure that @command{make} notices sources files have been updated.
11712 This timestamp shift is troublesome when both sources and generated
11713 files are kept under CVS@. Because CVS processes files in lexical
11714 order, @file{configure.ac} will appear newer than @file{configure}
11715 after a @command{cvs update} that updates both files, even if
11716 @file{configure} was newer than @file{configure.ac} when it was
11717 checked in. Calling @command{make} will then trigger a spurious rebuild
11718 of @file{configure}.
11720 @subheading Living with CVS in Autoconfiscated Projects
11721 @cindex CVS and generated files
11722 @cindex generated files and CVS
11724 There are basically two clans amongst maintainers: those who keep all
11725 distributed files under CVS, including generated files, and those who
11726 keep generated files @emph{out} of CVS.
11728 @subsubheading All Files in CVS
11732 The CVS repository contains all distributed files so you know exactly
11733 what is distributed, and you can checkout any prior version entirely.
11736 Maintainers can see how generated files evolve (for instance, you can
11737 see what happens to your @file{Makefile.in}s when you upgrade Automake
11738 and make sure they look OK).
11741 Users do not need the autotools to build a checkout of the project, it
11742 works just like a released tarball.
11745 If users use @command{cvs update} to update their copy, instead of
11746 @command{cvs checkout} to fetch a fresh one, timestamps will be
11747 inaccurate. Some rebuild rules will be triggered and attempt to
11748 run developer tools such as @command{autoconf} or @command{automake}.
11750 Actually, calls to such tools are all wrapped into a call to the
11751 @command{missing} script discussed later (@pxref{maintainer-mode}).
11752 @command{missing} will take care of fixing the timestamps when these
11753 tools are not installed, so that the build can continue.
11756 In distributed development, developers are likely to have different
11757 version of the maintainer tools installed. In this case rebuilds
11758 triggered by timestamp lossage will lead to spurious changes
11759 to generated files. There are several solutions to this:
11763 All developers should use the same versions, so that the rebuilt files
11764 are identical to files in CVS@. (This starts to be difficult when each
11765 project you work on uses different versions.)
11767 Or people use a script to fix the timestamp after a checkout (the GCC
11768 folks have such a script).
11770 Or @file{configure.ac} uses @code{AM_MAINTAINER_MODE}, which will
11771 disable all of these rebuild rules by default. This is further discussed
11772 in @ref{maintainer-mode}.
11776 Although we focused on spurious rebuilds, the converse can also
11777 happen. CVS's timestamp handling can also let you think an
11778 out-of-date file is up-to-date.
11780 For instance, suppose a developer has modified @file{Makefile.am} and
11781 has rebuilt @file{Makefile.in}, and then decides to do a last-minute
11782 change to @file{Makefile.am} right before checking in both files
11783 (without rebuilding @file{Makefile.in} to account for the change).
11785 This last change to @file{Makefile.am} makes the copy of
11786 @file{Makefile.in} out-of-date. Since CVS processes files
11787 alphabetically, when another developer @samp{cvs update}s his or her
11788 tree, @file{Makefile.in} will happen to be newer than
11789 @file{Makefile.am}. This other developer will not see that
11790 @file{Makefile.in} is out-of-date.
11794 @subsubheading Generated Files out of CVS
11796 One way to get CVS and @command{make} working peacefully is to never
11797 store generated files in CVS, i.e., do not CVS-control files that
11798 are @file{Makefile} targets (also called @emph{derived} files).
11800 This way developers are not annoyed by changes to generated files. It
11801 does not matter if they all have different versions (assuming they are
11802 compatible, of course). And finally, timestamps are not lost, changes
11803 to sources files can't be missed as in the
11804 @file{Makefile.am}/@file{Makefile.in} example discussed earlier.
11806 The drawback is that the CVS repository is not an exact copy of what
11807 is distributed and that users now need to install various development
11808 tools (maybe even specific versions) before they can build a checkout.
11809 But, after all, CVS's job is versioning, not distribution.
11811 Allowing developers to use different versions of their tools can also
11812 hide bugs during distributed development. Indeed, developers will be
11813 using (hence testing) their own generated files, instead of the
11814 generated files that will be released actually. The developer who
11815 prepares the tarball might be using a version of the tool that
11816 produces bogus output (for instance a non-portable C file), something
11817 other developers could have noticed if they weren't using their own
11818 versions of this tool.
11820 @subheading Third-party Files
11821 @cindex CVS and third-party files
11822 @cindex third-party files and CVS
11824 Another class of files not discussed here (because they do not cause
11825 timestamp issues) are files that are shipped with a package, but
11826 maintained elsewhere. For instance, tools like @command{gettextize}
11827 and @command{autopoint} (from Gettext) or @command{libtoolize} (from
11828 Libtool), will install or update files in your package.
11830 These files, whether they are kept under CVS or not, raise similar
11831 concerns about version mismatch between developers' tools. The
11832 Gettext manual has a section about this, see @ref{CVS Issues, CVS
11833 Issues, Integrating with CVS, gettext, GNU gettext tools}.
11835 @node maintainer-mode
11836 @section @command{missing} and @code{AM_MAINTAINER_MODE}
11838 @subheading @command{missing}
11839 @cindex @command{missing}, purpose
11841 The @command{missing} script is a wrapper around several maintainer
11842 tools, designed to warn users if a maintainer tool is required but
11843 missing. Typical maintainer tools are @command{autoconf},
11844 @command{automake}, @command{bison}, etc. Because file generated by
11845 these tools are shipped with the other sources of a package, these
11846 tools shouldn't be required during a user build and they are not
11847 checked for in @file{configure}.
11849 However, if for some reason a rebuild rule is triggered and involves a
11850 missing tool, @command{missing} will notice it and warn the user.
11851 Besides the warning, when a tool is missing, @command{missing} will
11852 attempt to fix timestamps in a way that allows the build to continue.
11853 For instance, @command{missing} will touch @file{configure} if
11854 @command{autoconf} is not installed. When all distributed files are
11855 kept under version control, this feature of @command{missing} allows a
11856 user @emph{with no maintainer tools} to build a package off its version
11857 control repository, bypassing any timestamp inconsistency (implied by
11858 e.g.@: @samp{cvs update} or @samp{git clone}).
11860 If the required tool is installed, @command{missing} will run it and
11861 won't attempt to continue after failures. This is correct during
11862 development: developers love fixing failures. However, users with
11863 wrong versions of maintainer tools may get an error when the rebuild
11864 rule is spuriously triggered, halting the build. This failure to let
11865 the build continue is one of the arguments of the
11866 @code{AM_MAINTAINER_MODE} advocates.
11868 @subheading @code{AM_MAINTAINER_MODE}
11869 @cindex @code{AM_MAINTAINER_MODE}, purpose
11870 @acindex AM_MAINTAINER_MODE
11872 @code{AM_MAINTAINER_MODE} allows you to choose whether the so called
11873 "rebuild rules" should be enabled or disabled. With
11874 @code{AM_MAINTAINER_MODE([enable])}, they are enabled by default,
11875 otherwise they are disabled by default. In the latter case, if
11876 you have @code{AM_MAINTAINER_MODE} in @file{configure.ac}, and run
11877 @samp{./configure && make}, then @command{make} will *never* attempt to
11878 rebuild @file{configure}, @file{Makefile.in}s, Lex or Yacc outputs, etc.
11879 I.e., this disables build rules for files that are usually distributed
11880 and that users should normally not have to update.
11882 The user can override the default setting by passing either
11883 @samp{--enable-maintainer-mode} or @samp{--disable-maintainer-mode}
11884 to @command{configure}.
11886 People use @code{AM_MAINTAINER_MODE} either because they do not want their
11887 users (or themselves) annoyed by timestamps lossage (@pxref{CVS}), or
11888 because they simply can't stand the rebuild rules and prefer running
11889 maintainer tools explicitly.
11891 @code{AM_MAINTAINER_MODE} also allows you to disable some custom build
11892 rules conditionally. Some developers use this feature to disable
11893 rules that need exotic tools that users may not have available.
11895 Several years ago Fran@,{c}ois Pinard pointed out several arguments
11896 against this @code{AM_MAINTAINER_MODE} macro. Most of them relate to
11897 insecurity. By removing dependencies you get non-dependable builds:
11898 changes to sources files can have no effect on generated files and this
11899 can be very confusing when unnoticed. He adds that security shouldn't
11900 be reserved to maintainers (what @option{--enable-maintainer-mode}
11901 suggests), on the contrary. If one user has to modify a
11902 @file{Makefile.am}, then either @file{Makefile.in} should be updated
11903 or a warning should be output (this is what Automake uses
11904 @command{missing} for) but the last thing you want is that nothing
11905 happens and the user doesn't notice it (this is what happens when
11906 rebuild rules are disabled by @code{AM_MAINTAINER_MODE}).
11908 Jim Meyering, the inventor of the @code{AM_MAINTAINER_MODE} macro was
11909 swayed by Fran@,{c}ois's arguments, and got rid of
11910 @code{AM_MAINTAINER_MODE} in all of his packages.
11912 Still many people continue to use @code{AM_MAINTAINER_MODE}, because
11913 it helps them working on projects where all files are kept under version
11914 control, and because @command{missing} isn't enough if you have the
11915 wrong version of the tools.
11919 @section Why doesn't Automake support wildcards?
11922 Developers are lazy. They would often like to use wildcards in
11923 @file{Makefile.am}s, so that they would not need to remember to
11924 update @file{Makefile.am}s every time they add, delete, or rename
11927 There are several objections to this:
11930 When using CVS (or similar) developers need to remember they have to
11931 run @samp{cvs add} or @samp{cvs rm} anyway. Updating
11932 @file{Makefile.am} accordingly quickly becomes a reflex.
11934 Conversely, if your application doesn't compile
11935 because you forgot to add a file in @file{Makefile.am}, it will help
11936 you remember to @samp{cvs add} it.
11939 Using wildcards makes it easy to distribute files by mistake. For
11940 instance, some code a developer is experimenting with (a test case,
11941 say) that should not be part of the distribution.
11944 Using wildcards it's easy to omit some files by mistake. For
11945 instance, one developer creates a new file, uses it in many places,
11946 but forgets to commit it. Another developer then checks out the
11947 incomplete project and is able to run @samp{make dist} successfully,
11948 even though a file is missing. By listing files, @samp{make dist}
11949 @emph{will} complain.
11952 Wildcards are not portable to some non-GNU @command{make} implementations,
11953 e.g., NetBSD @command{make} will not expand globs such as @samp{*} in
11954 prerequisites of a target.
11957 Finally, it's really hard to @emph{forget} to add a file to
11958 @file{Makefile.am}: files that are not listed in @file{Makefile.am} are
11959 not compiled or installed, so you can't even test them.
11962 Still, these are philosophical objections, and as such you may disagree,
11963 or find enough value in wildcards to dismiss all of them. Before you
11964 start writing a patch against Automake to teach it about wildcards,
11965 let's see the main technical issue: portability.
11967 Although @samp{$(wildcard ...)} works with GNU @command{make}, it is
11968 not portable to other @command{make} implementations.
11970 The only way Automake could support @command{$(wildcard ...)} is by
11971 expending @command{$(wildcard ...)} when @command{automake} is run.
11972 The resulting @file{Makefile.in}s would be portable since they would
11973 list all files and not use @samp{$(wildcard ...)}. However that
11974 means developers would need to remember to run @command{automake} each
11975 time they add, delete, or rename files.
11977 Compared to editing @file{Makefile.am}, this is a very small gain. Sure,
11978 it's easier and faster to type @samp{automake; make} than to type
11979 @samp{emacs Makefile.am; make}. But nobody bothered enough to write a
11980 patch to add support for this syntax. Some people use scripts to
11981 generate file lists in @file{Makefile.am} or in separate
11982 @file{Makefile} fragments.
11984 Even if you don't care about portability, and are tempted to use
11985 @samp{$(wildcard ...)} anyway because you target only GNU Make, you
11986 should know there are many places where Automake needs to know exactly
11987 which files should be processed. As Automake doesn't know how to
11988 expand @samp{$(wildcard ...)}, you cannot use it in these places.
11989 @samp{$(wildcard ...)} is a black box comparable to @code{AC_SUBST}ed
11990 variables as far Automake is concerned.
11992 You can get warnings about @samp{$(wildcard ...}) constructs using the
11993 @option{-Wportability} flag.
11995 @node Limitations on File Names
11996 @section Limitations on File Names
11997 @cindex file names, limitations on
11999 Automake attempts to support all kinds of file names, even those that
12000 contain unusual characters or are unusually long. However, some
12001 limitations are imposed by the underlying operating system and tools.
12003 Most operating systems prohibit the use of the null byte in file
12004 names, and reserve @samp{/} as a directory separator. Also, they
12005 require that file names are properly encoded for the user's locale.
12006 Automake is subject to these limits.
12008 Portable packages should limit themselves to POSIX file
12009 names. These can contain ASCII letters and digits,
12010 @samp{_}, @samp{.}, and @samp{-}. File names consist of components
12011 separated by @samp{/}. File name components cannot begin with
12014 Portable POSIX file names cannot contain components that exceed a
12015 14-byte limit, but nowadays it's normally safe to assume the
12016 more-generous XOPEN limit of 255 bytes. POSIX
12017 limits file names to 255 bytes (XOPEN allows 1023 bytes),
12018 but you may want to limit a source tarball to file names of 99 bytes
12019 to avoid interoperability problems with old versions of @command{tar}.
12021 If you depart from these rules (e.g., by using non-ASCII
12022 characters in file names, or by using lengthy file names), your
12023 installers may have problems for reasons unrelated to Automake.
12024 However, if this does not concern you, you should know about the
12025 limitations imposed by Automake itself. These limitations are
12026 undesirable, but some of them seem to be inherent to underlying tools
12027 like Autoconf, Make, M4, and the shell. They fall into three
12028 categories: install directories, build directories, and file names.
12030 The following characters:
12033 @r{newline} " # $ ' `
12036 should not appear in the names of install directories. For example,
12037 the operand of @command{configure}'s @option{--prefix} option should
12038 not contain these characters.
12040 Build directories suffer the same limitations as install directories,
12041 and in addition should not contain the following characters:
12047 For example, the full name of the directory containing the source
12048 files should not contain these characters.
12050 Source and installation file names like @file{main.c} are limited even
12051 further: they should conform to the POSIX/XOPEN
12052 rules described above. In addition, if you plan to port to
12053 non-POSIX environments, you should avoid file names that
12054 differ only in case (e.g., @file{makefile} and @file{Makefile}).
12055 Nowadays it is no longer worth worrying about the 8.3 limits of
12058 @c FIXME This should probably be moved in the "Checking the Distribution"
12059 @c FIXME section...
12060 @node Errors with distclean
12061 @section Errors with distclean
12062 @cindex @code{distclean}, diagnostic
12063 @cindex @samp{make distclean}, diagnostic
12064 @cindex dependencies and distributed files
12067 This is a diagnostic you might encounter while running @samp{make
12070 As explained in @ref{Checking the Distribution}, @samp{make distcheck}
12071 attempts to build and check your package for errors like this one.
12073 @samp{make distcheck} will perform a @code{VPATH} build of your
12074 package (@pxref{VPATH Builds}), and then call @samp{make distclean}.
12075 Files left in the build directory after @samp{make distclean} has run
12076 are listed after this error.
12078 This diagnostic really covers two kinds of errors:
12082 files that are forgotten by distclean;
12084 distributed files that are erroneously rebuilt.
12087 The former left-over files are not distributed, so the fix is to mark
12088 them for cleaning (@pxref{Clean}), this is obvious and doesn't deserve
12091 The latter bug is not always easy to understand and fix, so let's
12092 proceed with an example. Suppose our package contains a program for
12093 which we want to build a man page using @command{help2man}. GNU
12094 @command{help2man} produces simple manual pages from the @option{--help}
12095 and @option{--version} output of other commands (@pxref{Top, , Overview,
12096 help2man, The Help2man Manual}). Because we don't want to force our
12097 users to install @command{help2man}, we decide to distribute the
12098 generated man page using the following setup.
12101 # This Makefile.am is bogus.
12103 foo_SOURCES = foo.c
12104 dist_man_MANS = foo.1
12106 foo.1: foo$(EXEEXT)
12107 help2man --output=foo.1 ./foo$(EXEEXT)
12110 This will effectively distribute the man page. However,
12111 @samp{make distcheck} will fail with:
12114 ERROR: files left in build directory after distclean:
12118 Why was @file{foo.1} rebuilt? Because although distributed,
12119 @file{foo.1} depends on a non-distributed built file:
12120 @file{foo$(EXEEXT)}. @file{foo$(EXEEXT)} is built by the user, so it
12121 will always appear to be newer than the distributed @file{foo.1}.
12123 @samp{make distcheck} caught an inconsistency in our package. Our
12124 intent was to distribute @file{foo.1} so users do not need to install
12125 @command{help2man}, however since this rule causes this file to be
12126 always rebuilt, users @emph{do} need @command{help2man}. Either we
12127 should ensure that @file{foo.1} is not rebuilt by users, or there is
12128 no point in distributing @file{foo.1}.
12130 More generally, the rule is that distributed files should never depend
12131 on non-distributed built files. If you distribute something
12132 generated, distribute its sources.
12134 One way to fix the above example, while still distributing
12135 @file{foo.1} is to not depend on @file{foo$(EXEEXT)}. For instance,
12136 assuming @command{foo --version} and @command{foo --help} do not
12137 change unless @file{foo.c} or @file{configure.ac} change, we could
12138 write the following @file{Makefile.am}:
12142 foo_SOURCES = foo.c
12143 dist_man_MANS = foo.1
12145 foo.1: foo.c $(top_srcdir)/configure.ac
12146 $(MAKE) $(AM_MAKEFLAGS) foo$(EXEEXT)
12147 help2man --output=foo.1 ./foo$(EXEEXT)
12150 This way, @file{foo.1} will not get rebuilt every time
12151 @file{foo$(EXEEXT)} changes. The @command{make} call makes sure
12152 @file{foo$(EXEEXT)} is up-to-date before @command{help2man}. Another
12153 way to ensure this would be to use separate directories for binaries
12154 and man pages, and set @code{SUBDIRS} so that binaries are built
12157 We could also decide not to distribute @file{foo.1}. In
12158 this case it's fine to have @file{foo.1} dependent upon
12159 @file{foo$(EXEEXT)}, since both will have to be rebuilt.
12160 However it would be impossible to build the package in a
12161 cross-compilation, because building @file{foo.1} involves
12162 an @emph{execution} of @file{foo$(EXEEXT)}.
12164 Another context where such errors are common is when distributed files
12165 are built by tools that are built by the package. The pattern is
12169 distributed-file: built-tools distributed-sources
12174 should be changed to
12177 distributed-file: distributed-sources
12178 $(MAKE) $(AM_MAKEFLAGS) built-tools
12183 or you could choose not to distribute @file{distributed-file}, if
12184 cross-compilation does not matter.
12186 The points made through these examples are worth a summary:
12191 Distributed files should never depend upon non-distributed built
12194 Distributed files should be distributed with all their dependencies.
12196 If a file is @emph{intended} to be rebuilt by users, then there is no point
12197 in distributing it.
12201 @vrindex distcleancheck_listfiles
12202 For desperate cases, it's always possible to disable this check by
12203 setting @code{distcleancheck_listfiles} as documented in @ref{Checking
12205 Make sure you do understand the reason why @samp{make distcheck}
12206 complains before you do this. @code{distcleancheck_listfiles} is a
12207 way to @emph{hide} errors, not to fix them. You can always do better.
12209 @node Flag Variables Ordering
12210 @section Flag Variables Ordering
12211 @cindex Ordering flag variables
12212 @cindex Flag variables, ordering
12215 What is the difference between @code{AM_CFLAGS}, @code{CFLAGS}, and
12216 @code{mumble_CFLAGS}?
12220 Why does @command{automake} output @code{CPPFLAGS} after
12221 @code{AM_CPPFLAGS} on compile lines? Shouldn't it be the converse?
12225 My @file{configure} adds some warning flags into @code{CXXFLAGS}. In
12226 one @file{Makefile.am} I would like to append a new flag, however if I
12227 put the flag into @code{AM_CXXFLAGS} it is prepended to the other
12228 flags, not appended.
12231 @subheading Compile Flag Variables
12232 @cindex Flag Variables, Ordering
12233 @cindex Compile Flag Variables
12234 @cindex @code{AM_CCASFLAGS} and @code{CCASFLAGS}
12235 @cindex @code{AM_CFLAGS} and @code{CFLAGS}
12236 @cindex @code{AM_CPPFLAGS} and @code{CPPFLAGS}
12237 @cindex @code{AM_CXXFLAGS} and @code{CXXFLAGS}
12238 @cindex @code{AM_FCFLAGS} and @code{FCFLAGS}
12239 @cindex @code{AM_FFLAGS} and @code{FFLAGS}
12240 @cindex @code{AM_GCJFLAGS} and @code{GCJFLAGS}
12241 @cindex @code{AM_LDFLAGS} and @code{LDFLAGS}
12242 @cindex @code{AM_LFLAGS} and @code{LFLAGS}
12243 @cindex @code{AM_LIBTOOLFLAGS} and @code{LIBTOOLFLAGS}
12244 @cindex @code{AM_OBJCFLAGS} and @code{OBJCFLAGS}
12245 @cindex @code{AM_OBJCXXFLAGS} and @code{OBJXXCFLAGS}
12246 @cindex @code{AM_RFLAGS} and @code{RFLAGS}
12247 @cindex @code{AM_UPCFLAGS} and @code{UPCFLAGS}
12248 @cindex @code{AM_YFLAGS} and @code{YFLAGS}
12249 @cindex @code{CCASFLAGS} and @code{AM_CCASFLAGS}
12250 @cindex @code{CFLAGS} and @code{AM_CFLAGS}
12251 @cindex @code{CPPFLAGS} and @code{AM_CPPFLAGS}
12252 @cindex @code{CXXFLAGS} and @code{AM_CXXFLAGS}
12253 @cindex @code{FCFLAGS} and @code{AM_FCFLAGS}
12254 @cindex @code{FFLAGS} and @code{AM_FFLAGS}
12255 @cindex @code{GCJFLAGS} and @code{AM_GCJFLAGS}
12256 @cindex @code{LDFLAGS} and @code{AM_LDFLAGS}
12257 @cindex @code{LFLAGS} and @code{AM_LFLAGS}
12258 @cindex @code{LIBTOOLFLAGS} and @code{AM_LIBTOOLFLAGS}
12259 @cindex @code{OBJCFLAGS} and @code{AM_OBJCFLAGS}
12260 @cindex @code{OBJCXXFLAGS} and @code{AM_OBJCXXFLAGS}
12261 @cindex @code{RFLAGS} and @code{AM_RFLAGS}
12262 @cindex @code{UPCFLAGS} and @code{AM_UPCFLAGS}
12263 @cindex @code{YFLAGS} and @code{AM_YFLAGS}
12265 This section attempts to answer all the above questions. We will
12266 mostly discuss @code{CPPFLAGS} in our examples, but actually the
12267 answer holds for all the compile flags used in Automake:
12268 @code{CCASFLAGS}, @code{CFLAGS}, @code{CPPFLAGS}, @code{CXXFLAGS},
12269 @code{FCFLAGS}, @code{FFLAGS}, @code{GCJFLAGS}, @code{LDFLAGS},
12270 @code{LFLAGS}, @code{LIBTOOLFLAGS}, @code{OBJCFLAGS}, @code{OBJCXXFLAGS},
12271 @code{RFLAGS}, @code{UPCFLAGS}, and @code{YFLAGS}.
12273 @code{CPPFLAGS}, @code{AM_CPPFLAGS}, and @code{mumble_CPPFLAGS} are
12274 three variables that can be used to pass flags to the C preprocessor
12275 (actually these variables are also used for other languages like C++
12276 or preprocessed Fortran). @code{CPPFLAGS} is the user variable
12277 (@pxref{User Variables}), @code{AM_CPPFLAGS} is the Automake variable,
12278 and @code{mumble_CPPFLAGS} is the variable specific to the
12279 @code{mumble} target (we call this a per-target variable,
12280 @pxref{Program and Library Variables}).
12282 Automake always uses two of these variables when compiling C sources
12283 files. When compiling an object file for the @code{mumble} target,
12284 the first variable will be @code{mumble_CPPFLAGS} if it is defined, or
12285 @code{AM_CPPFLAGS} otherwise. The second variable is always
12288 In the following example,
12291 bin_PROGRAMS = foo bar
12292 foo_SOURCES = xyz.c
12293 bar_SOURCES = main.c
12294 foo_CPPFLAGS = -DFOO
12295 AM_CPPFLAGS = -DBAZ
12299 @file{xyz.o} will be compiled with @samp{$(foo_CPPFLAGS) $(CPPFLAGS)},
12300 (because @file{xyz.o} is part of the @code{foo} target), while
12301 @file{main.o} will be compiled with @samp{$(AM_CPPFLAGS) $(CPPFLAGS)}
12302 (because there is no per-target variable for target @code{bar}).
12304 The difference between @code{mumble_CPPFLAGS} and @code{AM_CPPFLAGS}
12305 being clear enough, let's focus on @code{CPPFLAGS}. @code{CPPFLAGS}
12306 is a user variable, i.e., a variable that users are entitled to modify
12307 in order to compile the package. This variable, like many others,
12308 is documented at the end of the output of @samp{configure --help}.
12310 For instance, someone who needs to add @file{/home/my/usr/include} to
12311 the C compiler's search path would configure a package with
12314 ./configure CPPFLAGS='-I /home/my/usr/include'
12318 and this flag would be propagated to the compile rules of all
12321 It is also not uncommon to override a user variable at
12322 @command{make}-time. Many installers do this with @code{prefix}, but
12323 this can be useful with compiler flags too. For instance, if, while
12324 debugging a C++ project, you need to disable optimization in one
12325 specific object file, you can run something like
12329 make CXXFLAGS=-O0 file.o
12333 The reason @samp{$(CPPFLAGS)} appears after @samp{$(AM_CPPFLAGS)} or
12334 @samp{$(mumble_CPPFLAGS)} in the compile command is that users
12335 should always have the last say. It probably makes more sense if you
12336 think about it while looking at the @samp{CXXFLAGS=-O0} above, which
12337 should supersede any other switch from @code{AM_CXXFLAGS} or
12338 @code{mumble_CXXFLAGS} (and this of course replaces the previous value
12339 of @code{CXXFLAGS}).
12341 You should never redefine a user variable such as @code{CPPFLAGS} in
12342 @file{Makefile.am}. Use @samp{automake -Woverride} to diagnose such
12343 mistakes. Even something like
12346 CPPFLAGS = -DDATADIR=\"$(datadir)\" @@CPPFLAGS@@
12350 is erroneous. Although this preserves @file{configure}'s value of
12351 @code{CPPFLAGS}, the definition of @code{DATADIR} will disappear if a
12352 user attempts to override @code{CPPFLAGS} from the @command{make}
12356 AM_CPPFLAGS = -DDATADIR=\"$(datadir)\"
12360 is all that is needed here if no per-target flags are used.
12362 You should not add options to these user variables within
12363 @file{configure} either, for the same reason. Occasionally you need
12364 to modify these variables to perform a test, but you should reset
12365 their values afterwards. In contrast, it is OK to modify the
12366 @samp{AM_} variables within @file{configure} if you @code{AC_SUBST}
12367 them, but it is rather rare that you need to do this, unless you
12368 really want to change the default definitions of the @samp{AM_}
12369 variables in all @file{Makefile}s.
12371 What we recommend is that you define extra flags in separate
12372 variables. For instance, you may write an Autoconf macro that computes
12373 a set of warning options for the C compiler, and @code{AC_SUBST} them
12374 in @code{WARNINGCFLAGS}; you may also have an Autoconf macro that
12375 determines which compiler and which linker flags should be used to
12376 link with library @file{libfoo}, and @code{AC_SUBST} these in
12377 @code{LIBFOOCFLAGS} and @code{LIBFOOLDFLAGS}. Then, a
12378 @file{Makefile.am} could use these variables as follows:
12381 AM_CFLAGS = $(WARNINGCFLAGS)
12382 bin_PROGRAMS = prog1 prog2
12383 prog1_SOURCES = @dots{}
12384 prog2_SOURCES = @dots{}
12385 prog2_CFLAGS = $(LIBFOOCFLAGS) $(AM_CFLAGS)
12386 prog2_LDFLAGS = $(LIBFOOLDFLAGS)
12389 In this example both programs will be compiled with the flags
12390 substituted into @samp{$(WARNINGCFLAGS)}, and @code{prog2} will
12391 additionally be compiled with the flags required to link with
12394 Note that listing @code{AM_CFLAGS} in a per-target @code{CFLAGS}
12395 variable is a common idiom to ensure that @code{AM_CFLAGS} applies to
12396 every target in a @file{Makefile.in}.
12398 Using variables like this gives you full control over the ordering of
12399 the flags. For instance, if there is a flag in $(WARNINGCFLAGS) that
12400 you want to negate for a particular target, you can use something like
12401 @samp{prog1_CFLAGS = $(AM_CFLAGS) -no-flag}. If all of these flags had
12402 been forcefully appended to @code{CFLAGS}, there would be no way to
12403 disable one flag. Yet another reason to leave user variables to
12406 Finally, we have avoided naming the variable of the example
12407 @code{LIBFOO_LDFLAGS} (with an underscore) because that would cause
12408 Automake to think that this is actually a per-target variable (like
12409 @code{mumble_LDFLAGS}) for some non-declared @code{LIBFOO} target.
12411 @subheading Other Variables
12413 There are other variables in Automake that follow similar principles
12414 to allow user options. For instance, Texinfo rules (@pxref{Texinfo})
12415 use @code{MAKEINFOFLAGS} and @code{AM_MAKEINFOFLAGS}. Similarly,
12416 DejaGnu tests (@pxref{DejaGnu Tests}) use @code{RUNTESTDEFAULTFLAGS} and
12417 @code{AM_RUNTESTDEFAULTFLAGS}. The tags and ctags rules
12418 (@pxref{Tags}) use @code{ETAGSFLAGS}, @code{AM_ETAGSFLAGS},
12419 @code{CTAGSFLAGS}, and @code{AM_CTAGSFLAGS}. Java rules
12420 (@pxref{Java}) use @code{JAVACFLAGS} and @code{AM_JAVACFLAGS}. None
12421 of these rules support per-target flags (yet).
12423 To some extent, even @code{AM_MAKEFLAGS} (@pxref{Subdirectories})
12424 obeys this naming scheme. The slight difference is that
12425 @code{MAKEFLAGS} is passed to sub-@command{make}s implicitly by
12426 @command{make} itself.
12428 However you should not think that all variables ending with
12429 @code{FLAGS} follow this convention. For instance,
12430 @code{DISTCHECK_CONFIGURE_FLAGS} (@pxref{Checking the Distribution}) and
12431 @code{ACLOCAL_AMFLAGS} (see @ref{Rebuilding} and @ref{Local Macros}),
12432 are two variables that are only useful to the maintainer and have no
12435 @code{ARFLAGS} (@pxref{A Library}) is usually defined by Automake and
12436 has neither @code{AM_} nor per-target cousin.
12438 Finally you should not think that the existence of a per-target
12439 variable implies the existence of an @code{AM_} variable or of a user
12440 variable. For instance, the @code{mumble_LDADD} per-target variable
12441 overrides the makefile-wide @code{LDADD} variable (which is not a user
12442 variable), and @code{mumble_LIBADD} exists only as a per-target
12443 variable. @xref{Program and Library Variables}.
12446 @node Renamed Objects
12447 @section Why are object files sometimes renamed?
12449 This happens when per-target compilation flags are used. Object
12450 files need to be renamed just in case they would clash with object
12451 files compiled from the same sources, but with different flags.
12452 Consider the following example.
12455 bin_PROGRAMS = true false
12456 true_SOURCES = generic.c
12457 true_CPPFLAGS = -DEXIT_CODE=0
12458 false_SOURCES = generic.c
12459 false_CPPFLAGS = -DEXIT_CODE=1
12463 Obviously the two programs are built from the same source, but it
12464 would be bad if they shared the same object, because @file{generic.o}
12465 cannot be built with both @samp{-DEXIT_CODE=0} @emph{and}
12466 @samp{-DEXIT_CODE=1}. Therefore @command{automake} outputs rules to
12467 build two different objects: @file{true-generic.o} and
12468 @file{false-generic.o}.
12470 @command{automake} doesn't actually look whether source files are
12471 shared to decide if it must rename objects. It will just rename all
12472 objects of a target as soon as it sees per-target compilation flags
12475 It's OK to share object files when per-target compilation flags are not
12476 used. For instance, @file{true} and @file{false} will both use
12477 @file{version.o} in the following example.
12480 AM_CPPFLAGS = -DVERSION=1.0
12481 bin_PROGRAMS = true false
12482 true_SOURCES = true.c version.c
12483 false_SOURCES = false.c version.c
12486 Note that the renaming of objects is also affected by the
12487 @code{_SHORTNAME} variable (@pxref{Program and Library Variables}).
12490 @node Per-Object Flags
12491 @section Per-Object Flags Emulation
12492 @cindex Per-object flags, emulated
12495 One of my source files needs to be compiled with different flags. How
12499 Automake supports per-program and per-library compilation flags (see
12500 @ref{Program and Library Variables} and @ref{Flag Variables
12501 Ordering}). With this you can define compilation flags that apply to
12502 all files compiled for a target. For instance, in
12506 foo_SOURCES = foo.c foo.h bar.c bar.h main.c
12507 foo_CFLAGS = -some -flags
12511 @file{foo-foo.o}, @file{foo-bar.o}, and @file{foo-main.o} will all be
12512 compiled with @samp{-some -flags}. (If you wonder about the names of
12513 these object files, see @ref{Renamed Objects}.) Note that
12514 @code{foo_CFLAGS} gives the flags to use when compiling all the C
12515 sources of the @emph{program} @code{foo}, it has nothing to do with
12516 @file{foo.c} or @file{foo-foo.o} specifically.
12518 What if @file{foo.c} needs to be compiled into @file{foo.o} using some
12519 specific flags, that none of the other files requires? Obviously
12520 per-program flags are not directly applicable here. Something like
12521 per-object flags are expected, i.e., flags that would be used only
12522 when creating @file{foo-foo.o}. Automake does not support that,
12523 however this is easy to simulate using a library that contains only
12524 that object, and compiling this library with per-library flags.
12528 foo_SOURCES = bar.c bar.h main.c
12529 foo_CFLAGS = -some -flags
12530 foo_LDADD = libfoo.a
12531 noinst_LIBRARIES = libfoo.a
12532 libfoo_a_SOURCES = foo.c foo.h
12533 libfoo_a_CFLAGS = -some -other -flags
12536 Here @file{foo-bar.o} and @file{foo-main.o} will all be
12537 compiled with @samp{-some -flags}, while @file{libfoo_a-foo.o} will
12538 be compiled using @samp{-some -other -flags}. Eventually, all
12539 three objects will be linked to form @file{foo}.
12541 This trick can also be achieved using Libtool convenience libraries,
12542 for instance @samp{noinst_LTLIBRARIES = libfoo.la} (@pxref{Libtool
12543 Convenience Libraries}).
12545 Another tempting idea to implement per-object flags is to override the
12546 compile rules @command{automake} would output for these files.
12547 Automake will not define a rule for a target you have defined, so you
12548 could think about defining the @samp{foo-foo.o: foo.c} rule yourself.
12549 We recommend against this, because this is error prone. For instance,
12550 if you add such a rule to the first example, it will break the day you
12551 decide to remove @code{foo_CFLAGS} (because @file{foo.c} will then be
12552 compiled as @file{foo.o} instead of @file{foo-foo.o}, @pxref{Renamed
12553 Objects}). Also in order to support dependency tracking, the two
12554 @file{.o}/@file{.obj} extensions, and all the other flags variables
12555 involved in a compilation, you will end up modifying a copy of the
12556 rule previously output by @command{automake} for this file. If a new
12557 release of Automake generates a different rule, your copy will need to
12558 be updated by hand.
12560 @node Multiple Outputs
12561 @section Handling Tools that Produce Many Outputs
12562 @cindex multiple outputs, rules with
12563 @cindex many outputs, rules with
12564 @cindex rules with multiple outputs
12566 This section describes a @command{make} idiom that can be used when a
12567 tool produces multiple output files. It is not specific to Automake
12568 and can be used in ordinary @file{Makefile}s.
12570 Suppose we have a program called @command{foo} that will read one file
12571 called @file{data.foo} and produce two files named @file{data.c} and
12572 @file{data.h}. We want to write a @file{Makefile} rule that captures
12573 this one-to-two dependency.
12575 The naive rule is incorrect:
12578 # This is incorrect.
12579 data.c data.h: data.foo
12584 What the above rule really says is that @file{data.c} and
12585 @file{data.h} each depend on @file{data.foo}, and can each be built by
12586 running @samp{foo data.foo}. In other words it is equivalent to:
12589 # We do not want this.
12597 which means that @command{foo} can be run twice. Usually it will not
12598 be run twice, because @command{make} implementations are smart enough
12599 to check for the existence of the second file after the first one has
12600 been built; they will therefore detect that it already exists.
12601 However there are a few situations where it can run twice anyway:
12605 The most worrying case is when running a parallel @command{make}. If
12606 @file{data.c} and @file{data.h} are built in parallel, two @samp{foo
12607 data.foo} commands will run concurrently. This is harmful.
12609 Another case is when the dependency (here @file{data.foo}) is
12610 (or depends upon) a phony target.
12613 A solution that works with parallel @command{make} but not with
12614 phony dependencies is the following:
12617 data.c data.h: data.foo
12623 The above rules are equivalent to
12628 data.h: data.foo data.c
12633 therefore a parallel @command{make} will have to serialize the builds
12634 of @file{data.c} and @file{data.h}, and will detect that the second is
12635 no longer needed once the first is over.
12637 Using this pattern is probably enough for most cases. However it does
12638 not scale easily to more output files (in this scheme all output files
12639 must be totally ordered by the dependency relation), so we will
12640 explore a more complicated solution.
12642 Another idea is to write the following:
12645 # There is still a problem with this one.
12652 The idea is that @samp{foo data.foo} is run only when @file{data.c}
12653 needs to be updated, but we further state that @file{data.h} depends
12654 upon @file{data.c}. That way, if @file{data.h} is required and
12655 @file{data.foo} is out of date, the dependency on @file{data.c} will
12658 This is almost perfect, but suppose we have built @file{data.h} and
12659 @file{data.c}, and then we erase @file{data.h}. Then, running
12660 @samp{make data.h} will not rebuild @file{data.h}. The above rules
12661 just state that @file{data.c} must be up-to-date with respect to
12662 @file{data.foo}, and this is already the case.
12664 What we need is a rule that forces a rebuild when @file{data.h} is
12665 missing. Here it is:
12671 ## Recover from the removal of $@@
12672 @@if test -f $@@; then :; else \
12674 $(MAKE) $(AM_MAKEFLAGS) data.c; \
12678 The above scheme can be extended to handle more outputs and more
12679 inputs. One of the outputs is selected to serve as a witness to the
12680 successful completion of the command, it depends upon all inputs, and
12681 all other outputs depend upon it. For instance, if @command{foo}
12682 should additionally read @file{data.bar} and also produce
12683 @file{data.w} and @file{data.x}, we would write:
12686 data.c: data.foo data.bar
12687 foo data.foo data.bar
12688 data.h data.w data.x: data.c
12689 ## Recover from the removal of $@@
12690 @@if test -f $@@; then :; else \
12692 $(MAKE) $(AM_MAKEFLAGS) data.c; \
12696 However there are now three minor problems in this setup. One is related
12697 to the timestamp ordering of @file{data.h}, @file{data.w},
12698 @file{data.x}, and @file{data.c}. Another one is a race condition
12699 if a parallel @command{make} attempts to run multiple instances of the
12700 recover block at once. Finally, the recursive rule breaks @samp{make -n}
12701 when run with GNU @command{make} (as well as some other @command{make}
12702 implementations), as it may remove @file{data.h} even when it should not
12703 (@pxref{MAKE Variable, , How the @code{MAKE} Variable Works, make,
12704 The GNU Make Manual}).
12706 Let us deal with the first problem. @command{foo} outputs four files,
12707 but we do not know in which order these files are created. Suppose
12708 that @file{data.h} is created before @file{data.c}. Then we have a
12709 weird situation. The next time @command{make} is run, @file{data.h}
12710 will appear older than @file{data.c}, the second rule will be
12711 triggered, a shell will be started to execute the @samp{if@dots{}fi}
12712 command, but actually it will just execute the @code{then} branch,
12713 that is: nothing. In other words, because the witness we selected is
12714 not the first file created by @command{foo}, @command{make} will start
12715 a shell to do nothing each time it is run.
12717 A simple riposte is to fix the timestamps when this happens.
12720 data.c: data.foo data.bar
12721 foo data.foo data.bar
12722 data.h data.w data.x: data.c
12723 @@if test -f $@@; then \
12726 ## Recover from the removal of $@@
12728 $(MAKE) $(AM_MAKEFLAGS) data.c; \
12732 Another solution is to use a different and dedicated file as witness,
12733 rather than using any of @command{foo}'s outputs.
12736 data.stamp: data.foo data.bar
12739 foo data.foo data.bar
12740 @@mv -f data.tmp $@@
12741 data.c data.h data.w data.x: data.stamp
12742 ## Recover from the removal of $@@
12743 @@if test -f $@@; then :; else \
12744 rm -f data.stamp; \
12745 $(MAKE) $(AM_MAKEFLAGS) data.stamp; \
12749 @file{data.tmp} is created before @command{foo} is run, so it has a
12750 timestamp older than output files output by @command{foo}. It is then
12751 renamed to @file{data.stamp} after @command{foo} has run, because we
12752 do not want to update @file{data.stamp} if @command{foo} fails.
12754 This solution still suffers from the second problem: the race
12755 condition in the recover rule. If, after a successful build, a user
12756 erases @file{data.c} and @file{data.h}, and runs @samp{make -j}, then
12757 @command{make} may start both recover rules in parallel. If the two
12758 instances of the rule execute @samp{$(MAKE) $(AM_MAKEFLAGS)
12759 data.stamp} concurrently the build is likely to fail (for instance, the
12760 two rules will create @file{data.tmp}, but only one can rename it).
12762 Admittedly, such a weird situation does not arise during ordinary
12763 builds. It occurs only when the build tree is mutilated. Here
12764 @file{data.c} and @file{data.h} have been explicitly removed without
12765 also removing @file{data.stamp} and the other output files.
12766 @code{make clean; make} will always recover from these situations even
12767 with parallel makes, so you may decide that the recover rule is solely
12768 to help non-parallel make users and leave things as-is. Fixing this
12769 requires some locking mechanism to ensure only one instance of the
12770 recover rule rebuilds @file{data.stamp}. One could imagine something
12771 along the following lines.
12774 data.c data.h data.w data.x: data.stamp
12775 ## Recover from the removal of $@@
12776 @@if test -f $@@; then :; else \
12777 trap 'rm -rf data.lock data.stamp' 1 2 13 15; \
12778 ## mkdir is a portable test-and-set
12779 if mkdir data.lock 2>/dev/null; then \
12780 ## This code is being executed by the first process.
12781 rm -f data.stamp; \
12782 $(MAKE) $(AM_MAKEFLAGS) data.stamp; \
12783 result=$$?; rm -rf data.lock; exit $$result; \
12785 ## This code is being executed by the follower processes.
12786 ## Wait until the first process is done.
12787 while test -d data.lock; do sleep 1; done; \
12788 ## Succeed if and only if the first process succeeded.
12789 test -f data.stamp; \
12794 Using a dedicated witness, like @file{data.stamp}, is very handy when
12795 the list of output files is not known beforehand. As an illustration,
12796 consider the following rules to compile many @file{*.el} files into
12797 @file{*.elc} files in a single command. It does not matter how
12798 @code{ELFILES} is defined (as long as it is not empty: empty targets
12799 are not accepted by POSIX).
12802 ELFILES = one.el two.el three.el @dots{}
12803 ELCFILES = $(ELFILES:=c)
12805 elc-stamp: $(ELFILES)
12808 $(elisp_comp) $(ELFILES)
12809 @@mv -f elc-temp $@@
12811 $(ELCFILES): elc-stamp
12812 @@if test -f $@@; then :; else \
12813 ## Recover from the removal of $@@
12814 trap 'rm -rf elc-lock elc-stamp' 1 2 13 15; \
12815 if mkdir elc-lock 2>/dev/null; then \
12816 ## This code is being executed by the first process.
12818 $(MAKE) $(AM_MAKEFLAGS) elc-stamp; \
12821 ## This code is being executed by the follower processes.
12822 ## Wait until the first process is done.
12823 while test -d elc-lock; do sleep 1; done; \
12824 ## Succeed if and only if the first process succeeded.
12825 test -f elc-stamp; exit $$?; \
12831 These solutions all still suffer from the third problem, namely that
12832 they break the promise that @samp{make -n} should not cause any actual
12833 changes to the tree. For those solutions that do not create lock files,
12834 it is possible to split the recover rules into two separate recipe
12835 commands, one of which does all work but the recursion, and the
12836 other invokes the recursive @samp{$(MAKE)}. The solutions involving
12837 locking could act upon the contents of the @samp{MAKEFLAGS} variable,
12838 but parsing that portably is not easy (@pxref{The Make Macro MAKEFLAGS,,,
12839 autoconf, The Autoconf Manual}). Here is an example:
12842 ELFILES = one.el two.el three.el @dots{}
12843 ELCFILES = $(ELFILES:=c)
12845 elc-stamp: $(ELFILES)
12848 $(elisp_comp) $(ELFILES)
12849 @@mv -f elc-temp $@@
12851 $(ELCFILES): elc-stamp
12852 ## Recover from the removal of $@@
12853 @@dry=; for f in x $$MAKEFLAGS; do \
12859 if test -f $@@; then :; else \
12860 $$dry trap 'rm -rf elc-lock elc-stamp' 1 2 13 15; \
12861 if $$dry mkdir elc-lock 2>/dev/null; then \
12862 ## This code is being executed by the first process.
12863 $$dry rm -f elc-stamp; \
12864 $(MAKE) $(AM_MAKEFLAGS) elc-stamp; \
12865 $$dry rmdir elc-lock; \
12867 ## This code is being executed by the follower processes.
12868 ## Wait until the first process is done.
12869 while test -d elc-lock && test -z "$$dry"; do \
12873 ## Succeed if and only if the first process succeeded.
12874 $$dry test -f elc-stamp; exit $$?; \
12879 For completeness it should be noted that GNU @command{make} is able to
12880 express rules with multiple output files using pattern rules
12881 (@pxref{Pattern Examples, , Pattern Rule Examples, make, The GNU Make
12882 Manual}). We do not discuss pattern rules here because they are not
12883 portable, but they can be convenient in packages that assume GNU
12887 @node Hard-Coded Install Paths
12888 @section Installing to Hard-Coded Locations
12891 My package needs to install some configuration file. I tried to use
12892 the following rule, but @samp{make distcheck} fails. Why?
12896 install-data-local:
12897 $(INSTALL_DATA) $(srcdir)/afile $(DESTDIR)/etc/afile
12902 My package needs to populate the installation directory of another
12903 package at install-time. I can easily compute that installation
12904 directory in @file{configure}, but if I install files therein,
12905 @samp{make distcheck} fails. How else should I do?
12908 These two setups share their symptoms: @samp{make distcheck} fails
12909 because they are installing files to hard-coded paths. In the later
12910 case the path is not really hard-coded in the package, but we can
12911 consider it to be hard-coded in the system (or in whichever tool that
12912 supplies the path). As long as the path does not use any of the
12913 standard directory variables (@samp{$(prefix)}, @samp{$(bindir)},
12914 @samp{$(datadir)}, etc.), the effect will be the same:
12915 user-installations are impossible.
12917 As a (non-root) user who wants to install a package, you usually have no
12918 right to install anything in @file{/usr} or @file{/usr/local}. So you
12919 do something like @samp{./configure --prefix ~/usr} to install a
12920 package in your own @file{~/usr} tree.
12922 If a package attempts to install something to some hard-coded path
12923 (e.g., @file{/etc/afile}), regardless of this @option{--prefix} setting,
12924 then the installation will fail. @samp{make distcheck} performs such
12925 a @option{--prefix} installation, hence it will fail too.
12927 Now, there are some easy solutions.
12929 The above @code{install-data-local} example for installing
12930 @file{/etc/afile} would be better replaced by
12933 sysconf_DATA = afile
12937 by default @code{sysconfdir} will be @samp{$(prefix)/etc}, because
12938 this is what the GNU Standards require. When such a package is
12939 installed on an FHS compliant system, the installer will have to set
12940 @samp{--sysconfdir=/etc}. As the maintainer of the package you
12941 should not be concerned by such site policies: use the appropriate
12942 standard directory variable to install your files so that the installer
12943 can easily redefine these variables to match their site conventions.
12945 Installing files that should be used by another package is slightly
12946 more involved. Let's take an example and assume you want to install
12947 a shared library that is a Python extension module. If you ask Python
12948 where to install the library, it will answer something like this:
12951 % @kbd{python -c 'from distutils import sysconfig;
12952 print sysconfig.get_python_lib(1,0)'}
12953 /usr/lib/python2.5/site-packages
12956 If you indeed use this absolute path to install your shared library,
12957 non-root users will not be able to install the package, hence
12960 Let's do better. The @samp{sysconfig.get_python_lib()} function
12961 actually accepts a third argument that will replace Python's
12962 installation prefix.
12965 % @kbd{python -c 'from distutils import sysconfig;
12966 print sysconfig.get_python_lib(1,0,"$@{exec_prefix@}")'}
12967 $@{exec_prefix@}/lib/python2.5/site-packages
12970 You can also use this new path. If you do
12973 root users can install your package with the same @option{--prefix}
12974 as Python (you get the behavior of the previous attempt)
12977 non-root users can install your package too, they will have the
12978 extension module in a place that is not searched by Python but they
12979 can work around this using environment variables (and if you installed
12980 scripts that use this shared library, it's easy to tell Python were to
12981 look in the beginning of your script, so the script works in both
12985 The @code{AM_PATH_PYTHON} macro uses similar commands to define
12986 @samp{$(pythondir)} and @samp{$(pyexecdir)} (@pxref{Python}).
12988 Of course not all tools are as advanced as Python regarding that
12989 substitution of @var{prefix}. So another strategy is to figure the
12990 part of the installation directory that must be preserved. For
12991 instance, here is how @code{AM_PATH_LISPDIR} (@pxref{Emacs Lisp})
12992 computes @samp{$(lispdir)}:
12995 $EMACS -batch -q -eval '(while load-path
12996 (princ (concat (car load-path) "\n"))
12997 (setq load-path (cdr load-path)))' >conftest.out
13000 -e '/.*\/lib\/x*emacs\/site-lisp$/@{
13001 s,.*/lib/\(x*emacs/site-lisp\)$,$@{libdir@}/\1,;p;q;
13003 -e '/.*\/share\/x*emacs\/site-lisp$/@{
13004 s,.*/share/\(x*emacs/site-lisp\),$@{datarootdir@}/\1,;p;q;
13009 I.e., it just picks the first directory that looks like
13010 @file{*/lib/*emacs/site-lisp} or @file{*/share/*emacs/site-lisp} in
13011 the search path of emacs, and then substitutes @samp{$@{libdir@}} or
13012 @samp{$@{datadir@}} appropriately.
13014 The emacs case looks complicated because it processes a list and
13015 expects two possible layouts, otherwise it's easy, and the benefits for
13016 non-root users are really worth the extra @command{sed} invocation.
13019 @node Debugging Make Rules
13020 @section Debugging Make Rules
13021 @cindex debugging rules
13022 @cindex rules, debugging
13024 The rules and dependency trees generated by @command{automake} can get
13025 rather complex, and leave the developer head-scratching when things
13026 don't work as expected. Besides the debug options provided by the
13027 @command{make} command (@pxref{Options Summary,,, make, The GNU Make
13028 Manual}), here's a couple of further hints for debugging makefiles
13029 generated by @command{automake} effectively:
13033 If less verbose output has been enabled in the package with the
13034 @samp{silent-rules} option (@pxref{Options}), you can use
13035 @code{make V=1} to see the commands being executed.
13037 @code{make -n} can help show what would be done without actually doing
13038 it. Note however, that this will @emph{still execute} commands prefixed
13039 with @samp{+}, and, when using GNU @command{make}, commands that contain
13040 the strings @samp{$(MAKE)} or @samp{$@{MAKE@}} (@pxref{Instead of
13041 Execution,,, make, The GNU Make Manual}).
13042 Typically, this is helpful to show what recursive rules would do, but it
13043 means that, in your own rules, you should not mix such recursion with
13044 actions that change any files.@footnote{Automake's @samp{dist} and
13045 @samp{distcheck} rules had a bug in this regard in that they created
13046 directories even with @option{-n}, but this has been fixed in Automake
13047 1.11.} Furthermore, note that GNU @command{make} will update
13048 prerequisites for the @file{Makefile} file itself even with @option{-n}
13049 (@pxref{Remaking Makefiles,,, make, The GNU Make Manual}).
13051 @code{make SHELL="/bin/bash -vx"} can help debug complex rules.
13052 @xref{The Make Macro SHELL,,, autoconf, The Autoconf Manual}, for some
13053 portability quirks associated with this construct.
13055 @code{echo 'print: ; @@echo "$(VAR)"' | make -f Makefile -f - print}
13056 can be handy to examine the expanded value of variables. You may need
13057 to use a target other than @samp{print} if that is already used or a
13058 file with that name exists.
13060 @url{http://bashdb.sourceforge.net/@/remake/} provides a modified
13061 GNU @command{make} command called @command{remake} that copes with
13062 complex GNU @command{make}-specific Makefiles and allows to trace
13063 execution, examine variables, and call rules interactively, much like
13068 @node Reporting Bugs
13069 @section Reporting Bugs
13071 Most nontrivial software has bugs. Automake is no exception. Although
13072 we cannot promise we can or will fix a bug, and we might not even agree
13073 that it is a bug, we want to hear about problems you encounter. Often we
13074 agree they are bugs and want to fix them.
13076 To make it possible for us to fix a bug, please report it. In order to
13077 do so effectively, it helps to know when and how to do it.
13079 Before reporting a bug, it is a good idea to see if it is already known.
13080 You can look at the @uref{http://debbugs.gnu.org/, GNU Bug Tracker}
13081 and the @uref{http://lists.gnu.org/@/archive/@/html/@/bug-automake/,
13082 bug-automake mailing list archives} for previous bug reports. We
13084 @uref{http://sourceware.org/@/cgi-bin/@/gnatsweb.pl?database=automake,
13085 Gnats database} for bug tracking, so some bugs might have been reported
13086 there already. Please do not use it for new bug reports, however.
13088 If the bug is not already known, it should be reported. It is very
13089 important to report bugs in a way that is useful and efficient. For
13090 this, please familiarize yourself with
13091 @uref{http://www.chiark.greenend.org.uk/@/~sgtatham/@/bugs.html, How to
13092 Report Bugs Effectively} and
13093 @uref{http://catb.org/@/~esr/@/faqs/@/smart-questions.html, How to Ask
13094 Questions the Smart Way}. This helps you and developers to save time
13095 which can then be spent on fixing more bugs and implementing more
13098 For a bug report, a feature request or other suggestions, please send
13099 email to @email{@value{PACKAGE_BUGREPORT}}. This will then open a new
13100 bug in the @uref{http://debbugs.gnu.org/@/automake, bug tracker}. Be
13101 sure to include the versions of Autoconf and Automake that you use.
13102 Ideally, post a minimal @file{Makefile.am} and @file{configure.ac} that
13103 reproduces the problem you encounter. If you have encountered test
13104 suite failures, please attach the @file{test-suite.log} file.
13106 @c ========================================================== Appendices
13109 @node Copying This Manual
13110 @appendix Copying This Manual
13113 * GNU Free Documentation License:: License for copying this manual
13116 @node GNU Free Documentation License
13117 @appendixsec GNU Free Documentation License
13125 * Macro Index:: Index of Autoconf macros
13126 * Variable Index:: Index of Makefile variables
13127 * General Index:: General index
13131 @appendixsec Macro Index
13135 @node Variable Index
13136 @appendixsec Variable Index
13140 @node General Index
13141 @appendixsec General Index
13148 @c LocalWords: texinfo setfilename settitle setchapternewpage texi direntry
13149 @c LocalWords: dircategory in's aclocal ifinfo titlepage Tromey vskip pt sp
13150 @c LocalWords: filll defcodeindex ov cv op tr syncodeindex fn cp vr ifnottex
13151 @c LocalWords: dir Automake's ac Dist Gnits gnits cygnus dfn Autoconf's pxref
13152 @c LocalWords: cindex Autoconf autoconf perl samp cvs dist trindex SUBST foo
13153 @c LocalWords: xs emph FIXME ref vindex pkglibdir pkgincludedir pkgdatadir mt
13154 @c LocalWords: pkg libdir cpio bindir sbindir rmt pax sbin zar zardir acindex
13155 @c LocalWords: HTML htmldir html noinst TEXINFOS nodist nobase strudel CFLAGS
13156 @c LocalWords: libmumble CC YFLAGS itemx de fication config url comp
13157 @c LocalWords: depcomp elisp sh mdate mkinstalldirs mkdir py tex dvi ps pdf
13158 @c LocalWords: ylwrap zardoz INIT gettext acinclude mv FUNCS LIBOBJS LDADD fr
13159 @c LocalWords: uref featureful dnl src LINGUAS es ko nl pl sl sv PROG ISC doc
13160 @c LocalWords: POSIX STDC fcntl FUNC ALLOCA blksize struct stat intl po chmod
13161 @c LocalWords: ChangeLog SUBDIRS gettextize gpl testdata getopt INTLLIBS cpp
13162 @c LocalWords: localedir datadir DLOCALEDIR DEXIT CPPFLAGS autoreconf opindex
13163 @c LocalWords: AUX var symlink deps Wno Wnone package's aclocal's distclean
13164 @c LocalWords: ltmain xref LIBSOURCE LIBSOURCES LIBOBJ MEMCMP vs RANLIB CXX
13165 @c LocalWords: LDFLAGS LIBTOOL libtool XTRA LIBS gettext's acdir APIVERSION
13166 @c LocalWords: dirlist noindent usr TIOCGWINSZ sc
13167 @c LocalWords: GWINSZ termios SRCDIR tarball bzip LISPDIR lispdir XEmacs CCAS
13168 @c LocalWords: emacsen MicroEmacs CCASFLAGS UX GCJ gcj GCJFLAGS posix DMALLOC
13169 @c LocalWords: dmalloc ldmalloc REGEX regex DEPDIR DEP DEFUN aclocaldir fi
13170 @c LocalWords: mymacro myothermacro AMFLAGS autopoint autogen libtoolize yum
13171 @c LocalWords: autoheader README MAKEFLAGS subdir Inetutils sync COND endif
13172 @c LocalWords: Miller's installable includedir inc pkgdata EXEEXT libexec bsd
13173 @c LocalWords: pkglib libexecdir prog libcpio cpio's dlopen dlpreopen linux
13174 @c LocalWords: subsubsection OBJEXT esac lib LTLIBRARIES liblob LIBADD AR ar
13175 @c LocalWords: ARFLAGS cru ing maude libgettext lo LTLIBOBJS rpath SGI PRE yy
13176 @c LocalWords: libmaude CCLD CXXFLAGS FFLAGS LFLAGS OBJCFLAGS RFLAGS DEFS cc
13177 @c LocalWords: OBJCXXFLAGS
13178 @c LocalWords: SHORTNAME vtable srcdir nostdinc basename yxx cxx ll lxx gdb
13179 @c LocalWords: lexers yymaxdepth maxdepth yyparse yylex yyerror yylval lval
13180 @c LocalWords: yychar yydebug yypact yyr yydef def yychk chk yypgo pgo yyact
13181 @c LocalWords: yyexca exca yyerrflag errflag yynerrs nerrs yyps yypv pv yys
13182 @c LocalWords: yystate yytmp tmp yyv yyval val yylloc lloc yyreds yytoks toks
13183 @c LocalWords: yylhs yylen yydefred yydgoto yysindex yyrindex yygindex yyname
13184 @c LocalWords: yytable yycheck yyrule byacc CXXCOMPILE CXXLINK FLINK cfortran
13185 @c LocalWords: Catalogue preprocessable FLIBS libfoo baz JAVACFLAGS java exe
13186 @c LocalWords: SunOS fying basenames exeext uninstalled oldinclude kr FSF's
13187 @c LocalWords: pkginclude oldincludedir sysconf sharedstate localstate gcc rm
13188 @c LocalWords: sysconfdir sharedstatedir localstatedir preexist CLEANFILES gz
13189 @c LocalWords: depfile tmpdepfile depmode const interoperate
13190 @c LocalWords: JAVAC javac JAVAROOT builddir CLASSPATH ENV pyc pyo pkgpython
13191 @c LocalWords: pyexecdir pkgpyexecdir Python's pythondir pkgpythondir txi ois
13192 @c LocalWords: installinfo vers MAKEINFO makeinfo MAKEINFOFLAGS noinstall rf
13193 @c LocalWords: mandir thesame alsothesame installman myexecbin DESTDIR Pinard
13194 @c LocalWords: uninstall installdirs uninstalls MOSTLYCLEANFILES mostlyclean
13195 @c LocalWords: DISTCLEANFILES MAINTAINERCLEANFILES GZIP gzip shar exp
13196 @c LocalWords: distdir distcheck distcleancheck listfiles distuninstallcheck
13197 @c LocalWords: VPATH tarfile stdout XFAIL DejaGnu dejagnu DEJATOOL runtest ln
13198 @c LocalWords: RUNTESTDEFAULTFLAGS toolchain RUNTESTFLAGS asis readme DVIPS
13199 @c LocalWords: installcheck gzipped tarZ std utils etags mkid cd
13200 @c LocalWords: ARGS taggable ETAGSFLAGS lang ctags CTAGSFLAGS GTAGS gtags idl
13201 @c LocalWords: foocc doit idlC multilibs ABIs cmindex defmac ARG enableval FC
13202 @c LocalWords: MSG xtrue DBG pathchk CYGWIN afile proglink versioned CVS's TE
13203 @c LocalWords: wildcards Autoconfiscated subsubheading autotools Meyering API
13204 @c LocalWords: ois's wildcard Wportability cartouche vrindex printindex Duret
13205 @c LocalWords: DSOMEFLAG DVERSION automake Lutz insertcopying versioning FAQ
13206 @c LocalWords: LTLIBOBJ Libtool's libtool's libltdl dlopening itutions libbar
13207 @c LocalWords: WANTEDLIBS libhello sublibraries libtop libsub dlopened Ratfor
13208 @c LocalWords: mymodule timestamps timestamp underquoted MAKEINFOHTMLFLAGS te
13209 @c LocalWords: GNUmakefile Subpackages subpackage's subpackages aux
13210 @c LocalWords: detailmenu Timeline pwd reldir AUTOM autom PREREQ FOOBAR libc
13211 @c LocalWords: libhand subpackage moduleN libmain libmisc FCFLAGS FCCOMPILE
13212 @c LocalWords: FCLINK subst sed ELCFILES elc MAKEINFOHTML dvips esyscmd ustar
13213 @c LocalWords: tarballs Woverride vfi ELFILES djm AutoMake honkin FSF
13214 @c LocalWords: fileutils precanned MacKenzie's reimplement termutils Tromey's
13215 @c LocalWords: cois gnitsians LIBPROGRAMS progs LIBLIBRARIES Textutils Ulrich
13216 @c LocalWords: Matzigkeit Drepper's Gord Matzigkeit's jm Dalley Debian org
13217 @c LocalWords: Administrivia ILU CORBA Sourceware Molenda sourceware Elliston
13218 @c LocalWords: dep Oliva Akim Demaille Aiieeee Demaillator Akim's sourcequake
13219 @c LocalWords: grep backported screenshots libgcj KB unnumberedsubsubsec pre
13220 @c LocalWords: precomputing hacky makedepend inline clearmake LD PRELOAD Rel
13221 @c LocalWords: syscalls perlhist acl pm multitable headitem fdl appendixsec
13222 @c LocalWords: LTALLOCA MALLOC malloc memcmp strdup alloca libcompat xyz DFOO
13223 @c LocalWords: unprefixed buildable preprocessed DBAZ DDATADIR WARNINGCFLAGS
13224 @c LocalWords: LIBFOOCFLAGS LIBFOOLDFLAGS ftable testSubDir obj LIBTOOLFLAGS
13225 @c LocalWords: barexec Pinard's automatize initialize lzip xz cscope