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 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 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 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 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 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}):
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 If your @file{configure.ac} has:
3959 AC_INIT([src/foo.c])
3960 AM_INIT_AUTOMAKE([mumble], [1.5])
3964 you should modernize it as follows:
3967 AC_INIT([mumble], [1.5])
3968 AC_CONFIG_SRCDIR([src/foo.c])
3972 Note that if you're upgrading your @file{configure.ac} from an earlier
3973 version of Automake, it is not always correct to simply move the
3974 package and version arguments from @code{AM_INIT_AUTOMAKE} directly to
3975 @code{AC_INIT}, as in the example above. The first argument to
3976 @code{AC_INIT} should be the name of your package (e.g., @samp{GNU
3977 Automake}), not the tarball name (e.g., @samp{automake}) that you used
3978 to pass to @code{AM_INIT_AUTOMAKE}. Autoconf tries to derive a
3979 tarball name from the package name, which should work for most but not
3980 all package names. (If it doesn't work for yours, you can use the
3981 four-argument form of @code{AC_INIT} to provide the tarball name
3984 @cindex @code{PACKAGE}, prevent definition
3985 @cindex @code{VERSION}, prevent definition
3987 By default this macro @code{AC_DEFINE}'s @code{PACKAGE} and
3988 @code{VERSION}. This can be avoided by passing the @option{no-define}
3991 AM_INIT_AUTOMAKE([gnits 1.5 no-define dist-bzip2])
3994 @item AM_PATH_LISPDIR
3995 @acindex AM_PATH_LISPDIR
3998 Searches for the program @command{emacs}, and, if found, sets the
3999 output variable @code{lispdir} to the full path to Emacs' site-lisp
4002 Note that this test assumes the @command{emacs} found to be a version
4003 that supports Emacs Lisp (such as GNU Emacs or XEmacs). Other
4004 emacsen can cause this test to hang (some, like old versions of
4005 MicroEmacs, start up in interactive mode, requiring @kbd{C-x C-c} to
4006 exit, which is hardly obvious for a non-emacs user). In most cases,
4007 however, you should be able to use @kbd{C-c} to kill the test. In
4008 order to avoid problems, you can set @env{EMACS} to ``no'' in the
4009 environment, or use the @option{--with-lispdir} option to
4010 @command{configure} to explicitly set the correct path (if you're sure
4011 you have an @command{emacs} that supports Emacs Lisp).
4013 @item AM_PROG_AR(@ovar{act-if-fail})
4016 You must use this macro when you use the archiver in your project, if
4017 you want support for unusual archivers such as Microsoft @command{lib}.
4018 The content of the optional argument is executed if the archiver
4019 interface is not recognized; the default action is to abort configure
4020 with an error message.
4026 Use this macro when you have assembly code in your project. This will
4027 choose the assembler for you (by default the C compiler) and set
4028 @code{CCAS}, and will also set @code{CCASFLAGS} if required.
4030 @item AM_PROG_CC_C_O
4031 @acindex AM_PROG_CC_C_O
4032 @acindex AC_PROG_CC_C_O
4033 This is like @code{AC_PROG_CC_C_O}, but it generates its results in
4034 the manner required by Automake. You must use this instead of
4035 @code{AC_PROG_CC_C_O} when you need this functionality, that is, when
4036 using per-target flags or subdir-objects with C sources.
4039 @acindex AM_PROG_LEX
4040 @acindex AC_PROG_LEX
4041 @cindex HP-UX 10, @command{lex} problems
4042 @cindex @command{lex} problems with HP-UX 10
4043 Like @code{AC_PROG_LEX} (@pxref{Particular Programs, , Particular
4044 Program Checks, autoconf, The Autoconf Manual}), but uses the
4045 @command{missing} script on systems that do not have @command{lex}.
4046 HP-UX 10 is one such system.
4049 @acindex AM_PROG_GCJ
4052 This macro finds the @command{gcj} program or causes an error. It sets
4053 @code{GCJ} and @code{GCJFLAGS}. @command{gcj} is the Java front-end to the
4054 GNU Compiler Collection.
4056 @item AM_PROG_UPC([@var{compiler-search-list}])
4057 @acindex AM_PROG_UPC
4059 Find a compiler for Unified Parallel C and define the @code{UPC}
4060 variable. The default @var{compiler-search-list} is @samp{upcc upc}.
4061 This macro will abort @command{configure} if no Unified Parallel C
4064 @item AM_SILENT_RULES
4065 @acindex AM_SILENT_RULES
4066 Enable the machinery for less verbose build output (@pxref{Options}).
4068 @item AM_WITH_DMALLOC
4069 @acindex AM_WITH_DMALLOC
4070 @cindex @command{dmalloc}, support for
4071 @vindex WITH_DMALLOC
4072 @opindex --with-dmalloc
4073 Add support for the @uref{http://dmalloc.com/, Dmalloc package}. If
4074 the user runs @command{configure} with @option{--with-dmalloc}, then
4075 define @code{WITH_DMALLOC} and add @option{-ldmalloc} to @code{LIBS}.
4080 @node Obsolete Macros
4081 @subsection Obsolete Macros
4082 @cindex obsolete macros
4085 Although using some of the following macros was required in past
4086 releases, you should not use any of them in new code. @emph{All
4087 these macros will be removed in the next major Automake version};
4088 if you are still using them, running @command{autoupdate} should
4089 adjust your @file{configure.ac} automatically (@pxref{autoupdate
4090 Invocation, , Using @command{autoupdate} to Modernize
4091 @file{configure.ac}, autoconf, The Autoconf Manual}).
4096 @item AM_CONFIG_HEADER
4097 @acindex AM_CONFIG_HEADER
4098 Automake will generate rules to automatically regenerate the config
4099 header. This obsolete macro is a synonym of @code{AC_CONFIG_HEADERS}
4100 today (@pxref{Optional}).
4102 @item AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
4103 @acindex AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
4104 If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
4105 define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be
4106 found in @file{<termios.h>}. This macro is obsolete, you should
4107 use Autoconf's @code{AC_HEADER_TIOCGWINSZ} instead.
4109 @item AM_PROG_MKDIR_P
4110 @acindex AM_PROG_MKDIR_P
4111 @cindex @code{mkdir -p}, macro check
4115 From Automake 1.8 to 1.9.6 this macro used to define the output
4116 variable @code{mkdir_p} to one of @code{mkdir -p}, @code{install-sh
4117 -d}, or @code{mkinstalldirs}.
4119 Nowadays Autoconf provides a similar functionality with
4120 @code{AC_PROG_MKDIR_P} (@pxref{Particular Programs, , Particular
4121 Program Checks, autoconf, The Autoconf Manual}), however this defines
4122 the output variable @code{MKDIR_P} instead. In case you are still
4123 using the @code{AM_PROG_MKDIR_P} macro in your @file{configure.ac},
4124 or its provided variable @code{$(mkdir_p)} in your @file{Makefile.am},
4125 you are advised to switch ASAP to the more modern Autoconf-provided
4126 interface instead; both the macro and the variable @emph{will be
4127 removed} in the next major Automake release.
4129 @item AM_SYS_POSIX_TERMIOS
4130 @acindex AM_SYS_POSIX_TERMIOS
4131 @cindex POSIX termios headers
4132 @cindex termios POSIX headers
4133 Check to see if POSIX termios headers and functions are available on the
4134 system. If so, set the shell variable @code{am_cv_sys_posix_termios} to
4135 @samp{yes}. If not, set the variable to @samp{no}. This macro is obsolete,
4136 you should use Autoconf's @code{AC_SYS_POSIX_TERMIOS} instead.
4141 @node Private Macros
4142 @subsection Private Macros
4144 The following macros are private macros you should not call directly.
4145 They are called by the other public macros when appropriate. Do not
4146 rely on them, as they might be changed in a future version. Consider
4147 them as implementation details; or better, do not consider them at all:
4151 @item _AM_DEPENDENCIES
4152 @itemx AM_SET_DEPDIR
4154 @itemx AM_OUTPUT_DEPENDENCY_COMMANDS
4155 These macros are used to implement Automake's automatic dependency
4156 tracking scheme. They are called automatically by Automake when
4157 required, and there should be no need to invoke them manually.
4159 @item AM_MAKE_INCLUDE
4160 This macro is used to discover how the user's @command{make} handles
4161 @code{include} statements. This macro is automatically invoked when
4162 needed; there should be no need to invoke it manually.
4164 @item AM_PROG_INSTALL_STRIP
4165 This is used to find a version of @code{install} that can be used to
4166 strip a program at installation time. This macro is automatically
4167 included when required.
4169 @item AM_SANITY_CHECK
4170 This checks to make sure that a file created in the build directory is
4171 newer than a file in the source directory. This can fail on systems
4172 where the clock is set incorrectly. This macro is automatically run
4173 from @code{AM_INIT_AUTOMAKE}.
4179 @chapter Directories
4181 For simple projects that distribute all files in the same directory
4182 it is enough to have a single @file{Makefile.am} that builds
4183 everything in place.
4185 In larger projects it is common to organize files in different
4186 directories, in a tree. For instance one directory per program, per
4187 library or per module. The traditional approach is to build these
4188 subdirectories recursively: each directory contains its @file{Makefile}
4189 (generated from @file{Makefile.am}), and when @command{make} is run
4190 from the top level directory it enters each subdirectory in turn to
4194 * Subdirectories:: Building subdirectories recursively
4195 * Conditional Subdirectories:: Conditionally not building directories
4196 * Alternative:: Subdirectories without recursion
4197 * Subpackages:: Nesting packages
4200 @node Subdirectories
4201 @section Recursing subdirectories
4203 @cindex @code{SUBDIRS}, explained
4205 In packages with subdirectories, the top level @file{Makefile.am} must
4206 tell Automake which subdirectories are to be built. This is done via
4207 the @code{SUBDIRS} variable.
4210 The @code{SUBDIRS} variable holds a list of subdirectories in which
4211 building of various sorts can occur. The rules for many targets
4212 (e.g., @code{all}) in the generated @file{Makefile} will run commands
4213 both locally and in all specified subdirectories. Note that the
4214 directories listed in @code{SUBDIRS} are not required to contain
4215 @file{Makefile.am}s; only @file{Makefile}s (after configuration).
4216 This allows inclusion of libraries from packages that do not use
4217 Automake (such as @code{gettext}; see also @ref{Third-Party
4220 In packages that use subdirectories, the top-level @file{Makefile.am} is
4221 often very short. For instance, here is the @file{Makefile.am} from the
4222 GNU Hello distribution:
4225 EXTRA_DIST = BUGS ChangeLog.O README-alpha
4226 SUBDIRS = doc intl po src tests
4229 When Automake invokes @command{make} in a subdirectory, it uses the value
4230 of the @code{MAKE} variable. It passes the value of the variable
4231 @code{AM_MAKEFLAGS} to the @command{make} invocation; this can be set in
4232 @file{Makefile.am} if there are flags you must always pass to
4235 @vindex AM_MAKEFLAGS
4237 The directories mentioned in @code{SUBDIRS} are usually direct
4238 children of the current directory, each subdirectory containing its
4239 own @file{Makefile.am} with a @code{SUBDIRS} pointing to deeper
4240 subdirectories. Automake can be used to construct packages of
4241 arbitrary depth this way.
4243 By default, Automake generates @file{Makefiles} that work depth-first
4244 in postfix order: the subdirectories are built before the current
4245 directory. However, it is possible to change this ordering. You can
4246 do this by putting @samp{.} into @code{SUBDIRS}. For instance,
4247 putting @samp{.} first will cause a prefix ordering of
4253 SUBDIRS = lib src . test
4257 will cause @file{lib/} to be built before @file{src/}, then the
4258 current directory will be built, finally the @file{test/} directory
4259 will be built. It is customary to arrange test directories to be
4260 built after everything else since they are meant to test what has
4263 All @code{clean} rules are run in reverse order of build rules.
4265 @node Conditional Subdirectories
4266 @section Conditional Subdirectories
4267 @cindex Subdirectories, building conditionally
4268 @cindex Conditional subdirectories
4269 @cindex @code{SUBDIRS}, conditional
4270 @cindex Conditional @code{SUBDIRS}
4272 It is possible to define the @code{SUBDIRS} variable conditionally if,
4273 like in the case of GNU Inetutils, you want to only build a subset of
4276 To illustrate how this works, let's assume we have two directories
4277 @file{src/} and @file{opt/}. @file{src/} should always be built, but we
4278 want to decide in @command{configure} whether @file{opt/} will be built
4279 or not. (For this example we will assume that @file{opt/} should be
4280 built when the variable @samp{$want_opt} was set to @samp{yes}.)
4282 Running @command{make} should thus recurse into @file{src/} always, and
4283 then maybe in @file{opt/}.
4285 However @samp{make dist} should always recurse into both @file{src/}
4286 and @file{opt/}. Because @file{opt/} should be distributed even if it
4287 is not needed in the current configuration. This means
4288 @file{opt/Makefile} should be created @emph{unconditionally}.
4290 There are two ways to setup a project like this. You can use Automake
4291 conditionals (@pxref{Conditionals}) or use Autoconf @code{AC_SUBST}
4292 variables (@pxref{Setting Output Variables, , Setting Output
4293 Variables, autoconf, The Autoconf Manual}). Using Automake
4294 conditionals is the preferred solution. Before we illustrate these
4295 two possibilities, let's introduce @code{DIST_SUBDIRS}.
4298 * SUBDIRS vs DIST_SUBDIRS:: Two sets of directories
4299 * Subdirectories with AM_CONDITIONAL:: Specifying conditional subdirectories
4300 * Subdirectories with AC_SUBST:: Another way for conditional recursion
4301 * Unconfigured Subdirectories:: Not even creating a @samp{Makefile}
4304 @node SUBDIRS vs DIST_SUBDIRS
4305 @subsection @code{SUBDIRS} vs.@: @code{DIST_SUBDIRS}
4306 @cindex @code{DIST_SUBDIRS}, explained
4308 Automake considers two sets of directories, defined by the variables
4309 @code{SUBDIRS} and @code{DIST_SUBDIRS}.
4311 @code{SUBDIRS} contains the subdirectories of the current directory
4312 that must be built (@pxref{Subdirectories}). It must be defined
4313 manually; Automake will never guess a directory is to be built. As we
4314 will see in the next two sections, it is possible to define it
4315 conditionally so that some directory will be omitted from the build.
4317 @code{DIST_SUBDIRS} is used in rules that need to recurse in all
4318 directories, even those that have been conditionally left out of the
4319 build. Recall our example where we may not want to build subdirectory
4320 @file{opt/}, but yet we want to distribute it? This is where
4321 @code{DIST_SUBDIRS} comes into play: @samp{opt} may not appear in
4322 @code{SUBDIRS}, but it must appear in @code{DIST_SUBDIRS}.
4324 Precisely, @code{DIST_SUBDIRS} is used by @samp{make
4325 maintainer-clean}, @samp{make distclean} and @samp{make dist}. All
4326 other recursive rules use @code{SUBDIRS}.
4328 If @code{SUBDIRS} is defined conditionally using Automake
4329 conditionals, Automake will define @code{DIST_SUBDIRS} automatically
4330 from the possible values of @code{SUBDIRS} in all conditions.
4332 If @code{SUBDIRS} contains @code{AC_SUBST} variables,
4333 @code{DIST_SUBDIRS} will not be defined correctly because Automake
4334 does not know the possible values of these variables. In this case
4335 @code{DIST_SUBDIRS} needs to be defined manually.
4337 @node Subdirectories with AM_CONDITIONAL
4338 @subsection Subdirectories with @code{AM_CONDITIONAL}
4339 @cindex @code{SUBDIRS} and @code{AM_CONDITIONAL}
4340 @cindex @code{AM_CONDITIONAL} and @code{SUBDIRS}
4342 @c Keep in sync with subcond2.sh
4344 @file{configure} should output the @file{Makefile} for each directory
4345 and define a condition into which @file{opt/} should be built.
4349 AM_CONDITIONAL([COND_OPT], [test "$want_opt" = yes])
4350 AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
4354 Then @code{SUBDIRS} can be defined in the top-level @file{Makefile.am}
4361 SUBDIRS = src $(MAYBE_OPT)
4364 As you can see, running @command{make} will rightly recurse into
4365 @file{src/} and maybe @file{opt/}.
4367 @vindex DIST_SUBDIRS
4368 As you can't see, running @samp{make dist} will recurse into both
4369 @file{src/} and @file{opt/} directories because @samp{make dist}, unlike
4370 @samp{make all}, doesn't use the @code{SUBDIRS} variable. It uses the
4371 @code{DIST_SUBDIRS} variable.
4373 In this case Automake will define @samp{DIST_SUBDIRS = src opt}
4374 automatically because it knows that @code{MAYBE_OPT} can contain
4375 @samp{opt} in some condition.
4377 @node Subdirectories with AC_SUBST
4378 @subsection Subdirectories with @code{AC_SUBST}
4379 @cindex @code{SUBDIRS} and @code{AC_SUBST}
4380 @cindex @code{AC_SUBST} and @code{SUBDIRS}
4382 @c Keep in sync with subcond3.sh
4384 Another possibility is to define @code{MAYBE_OPT} from
4385 @file{./configure} using @code{AC_SUBST}:
4389 if test "$want_opt" = yes; then
4394 AC_SUBST([MAYBE_OPT])
4395 AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
4399 In this case the top-level @file{Makefile.am} should look as follows.
4402 SUBDIRS = src $(MAYBE_OPT)
4403 DIST_SUBDIRS = src opt
4406 The drawback is that since Automake cannot guess what the possible
4407 values of @code{MAYBE_OPT} are, it is necessary to define
4408 @code{DIST_SUBDIRS}.
4410 @node Unconfigured Subdirectories
4411 @subsection Unconfigured Subdirectories
4412 @cindex Subdirectories, configured conditionally
4414 The semantics of @code{DIST_SUBDIRS} are often misunderstood by some
4415 users that try to @emph{configure and build} subdirectories
4416 conditionally. Here by configuring we mean creating the
4417 @file{Makefile} (it might also involve running a nested
4418 @command{configure} script: this is a costly operation that explains
4419 why people want to do it conditionally, but only the @file{Makefile}
4420 is relevant to the discussion).
4422 The above examples all assume that every @file{Makefile} is created,
4423 even in directories that are not going to be built. The simple reason
4424 is that we want @samp{make dist} to distribute even the directories
4425 that are not being built (e.g., platform-dependent code), hence
4426 @file{make dist} must recurse into the subdirectory, hence this
4427 directory must be configured and appear in @code{DIST_SUBDIRS}.
4429 Building packages that do not configure every subdirectory is a tricky
4430 business, and we do not recommend it to the novice as it is easy to
4431 produce an incomplete tarball by mistake. We will not discuss this
4432 topic in depth here, yet for the adventurous here are a few rules to
4437 @item @code{SUBDIRS} should always be a subset of @code{DIST_SUBDIRS}.
4439 It makes little sense to have a directory in @code{SUBDIRS} that
4440 is not in @code{DIST_SUBDIRS}. Think of the former as a way to tell
4441 which directories listed in the latter should be built.
4442 @item Any directory listed in @code{DIST_SUBDIRS} and @code{SUBDIRS}
4445 I.e., the @file{Makefile} must exists or the recursive @command{make}
4446 rules will not be able to process the directory.
4447 @item Any configured directory must be listed in @code{DIST_SUBDIRS}.
4449 So that the cleaning rules remove the generated @file{Makefile}s.
4450 It would be correct to see @code{DIST_SUBDIRS} as a variable that
4451 lists all the directories that have been configured.
4455 In order to prevent recursion in some unconfigured directory you
4456 must therefore ensure that this directory does not appear in
4457 @code{DIST_SUBDIRS} (and @code{SUBDIRS}). For instance, if you define
4458 @code{SUBDIRS} conditionally using @code{AC_SUBST} and do not define
4459 @code{DIST_SUBDIRS} explicitly, it will be default to
4460 @samp{$(SUBDIRS)}; another possibility is to force @code{DIST_SUBDIRS
4463 Of course, directories that are omitted from @code{DIST_SUBDIRS} will
4464 not be distributed unless you make other arrangements for this to
4465 happen (for instance, always running @samp{make dist} in a
4466 configuration where all directories are known to appear in
4467 @code{DIST_SUBDIRS}; or writing a @code{dist-hook} target to
4468 distribute these directories).
4470 @cindex Subdirectories, not distributed
4471 In few packages, unconfigured directories are not even expected to
4472 be distributed. Although these packages do not require the
4473 aforementioned extra arrangements, there is another pitfall. If the
4474 name of a directory appears in @code{SUBDIRS} or @code{DIST_SUBDIRS},
4475 @command{automake} will make sure the directory exists. Consequently
4476 @command{automake} cannot be run on such a distribution when one
4477 directory has been omitted. One way to avoid this check is to use the
4478 @code{AC_SUBST} method to declare conditional directories; since
4479 @command{automake} does not know the values of @code{AC_SUBST}
4480 variables it cannot ensure the corresponding directory exists.
4483 @section An Alternative Approach to Subdirectories
4485 If you've ever read Peter Miller's excellent paper,
4486 @uref{http://miller.emu.id.au/pmiller/books/rmch/,
4487 Recursive Make Considered Harmful}, the preceding sections on the use of
4488 subdirectories will probably come as unwelcome advice. For those who
4489 haven't read the paper, Miller's main thesis is that recursive
4490 @command{make} invocations are both slow and error-prone.
4492 Automake provides sufficient cross-directory support @footnote{We
4493 believe. This work is new and there are probably warts.
4494 @xref{Introduction}, for information on reporting bugs.} to enable you
4495 to write a single @file{Makefile.am} for a complex multi-directory
4499 By default an installable file specified in a subdirectory will have its
4500 directory name stripped before installation. For instance, in this
4501 example, the header file will be installed as
4502 @file{$(includedir)/stdio.h}:
4505 include_HEADERS = inc/stdio.h
4509 @cindex @code{nobase_} prefix
4510 @cindex Path stripping, avoiding
4511 @cindex Avoiding path stripping
4513 However, the @samp{nobase_} prefix can be used to circumvent this path
4514 stripping. In this example, the header file will be installed as
4515 @file{$(includedir)/sys/types.h}:
4518 nobase_include_HEADERS = sys/types.h
4521 @cindex @code{nobase_} and @code{dist_} or @code{nodist_}
4522 @cindex @code{dist_} and @code{nobase_}
4523 @cindex @code{nodist_} and @code{nobase_}
4527 @samp{nobase_} should be specified first when used in conjunction with
4528 either @samp{dist_} or @samp{nodist_} (@pxref{Fine-grained Distribution
4529 Control}). For instance:
4532 nobase_dist_pkgdata_DATA = images/vortex.pgm sounds/whirl.ogg
4535 Finally, note that a variable using the @samp{nobase_} prefix can
4536 often be replaced by several variables, one for each destination
4537 directory (@pxref{Uniform}). For instance, the last example could be
4538 rewritten as follows:
4540 @c Keep in sync with primary-prefix-couples-documented-valid.sh
4542 imagesdir = $(pkgdatadir)/images
4543 soundsdir = $(pkgdatadir)/sounds
4544 dist_images_DATA = images/vortex.pgm
4545 dist_sounds_DATA = sounds/whirl.ogg
4549 This latter syntax makes it possible to change one destination
4550 directory without changing the layout of the source tree.
4552 Currently, @samp{nobase_*_LTLIBRARIES} are the only exception to this
4553 rule, in that there is no particular installation order guarantee for
4554 an otherwise equivalent set of variables without @samp{nobase_} prefix.
4557 @section Nesting Packages
4558 @cindex Nesting packages
4560 @acindex AC_CONFIG_SUBDIRS
4561 @acindex AC_CONFIG_AUX_DIR
4564 In the GNU Build System, packages can be nested to arbitrary depth.
4565 This means that a package can embed other packages with their own
4566 @file{configure}, @file{Makefile}s, etc.
4568 These other packages should just appear as subdirectories of their
4569 parent package. They must be listed in @code{SUBDIRS} like other
4570 ordinary directories. However the subpackage's @file{Makefile}s
4571 should be output by its own @file{configure} script, not by the
4572 parent's @file{configure}. This is achieved using the
4573 @code{AC_CONFIG_SUBDIRS} Autoconf macro (@pxref{Subdirectories,
4574 AC_CONFIG_SUBDIRS, Configuring Other Packages in Subdirectories,
4575 autoconf, The Autoconf Manual}).
4577 Here is an example package for an @code{arm} program that links with
4578 a @code{hand} library that is a nested package in subdirectory
4581 @code{arm}'s @file{configure.ac}:
4584 AC_INIT([arm], [1.0])
4585 AC_CONFIG_AUX_DIR([.])
4588 AC_CONFIG_FILES([Makefile])
4589 # Call hand's ./configure script recursively.
4590 AC_CONFIG_SUBDIRS([hand])
4594 @code{arm}'s @file{Makefile.am}:
4597 # Build the library in the hand subdirectory first.
4600 # Include hand's header when compiling this directory.
4601 AM_CPPFLAGS = -I$(srcdir)/hand
4605 # link with the hand library.
4606 arm_LDADD = hand/libhand.a
4609 Now here is @code{hand}'s @file{hand/configure.ac}:
4612 AC_INIT([hand], [1.2])
4613 AC_CONFIG_AUX_DIR([.])
4618 AC_CONFIG_FILES([Makefile])
4623 and its @file{hand/Makefile.am}:
4626 lib_LIBRARIES = libhand.a
4627 libhand_a_SOURCES = hand.c
4630 When @samp{make dist} is run from the top-level directory it will
4631 create an archive @file{arm-1.0.tar.gz} that contains the @code{arm}
4632 code as well as the @file{hand} subdirectory. This package can be
4633 built and installed like any ordinary package, with the usual
4634 @samp{./configure && make && make install} sequence (the @code{hand}
4635 subpackage will be built and installed by the process).
4637 When @samp{make dist} is run from the hand directory, it will create a
4638 self-contained @file{hand-1.2.tar.gz} archive. So although it appears
4639 to be embedded in another package, it can still be used separately.
4641 The purpose of the @samp{AC_CONFIG_AUX_DIR([.])} instruction is to
4642 force Automake and Autoconf to search for auxiliary scripts in the
4643 current directory. For instance, this means that there will be two
4644 copies of @file{install-sh}: one in the top-level of the @code{arm}
4645 package, and another one in the @file{hand/} subdirectory for the
4646 @code{hand} package.
4648 The historical default is to search for these auxiliary scripts in
4649 the parent directory and the grandparent directory. So if the
4650 @samp{AC_CONFIG_AUX_DIR([.])} line was removed from
4651 @file{hand/configure.ac}, that subpackage would share the auxiliary
4652 script of the @code{arm} package. This may looks like a gain in size
4653 (a few kilobytes), but it is actually a loss of modularity as the
4654 @code{hand} subpackage is no longer self-contained (@samp{make dist}
4655 in the subdirectory will not work anymore).
4657 Packages that do not use Automake need more work to be integrated this
4658 way. @xref{Third-Party Makefiles}.
4661 @chapter Building Programs and Libraries
4663 A large part of Automake's functionality is dedicated to making it easy
4664 to build programs and libraries.
4667 * A Program:: Building a program
4668 * A Library:: Building a library
4669 * A Shared Library:: Building a Libtool library
4670 * Program and Library Variables:: Variables controlling program and
4672 * Default _SOURCES:: Default source files
4673 * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
4674 * Program Variables:: Variables used when building a program
4675 * Yacc and Lex:: Yacc and Lex support
4676 * C++ Support:: Compiling C++ sources
4677 * Objective C Support:: Compiling Objective C sources
4678 * Objective C++ Support:: Compiling Objective C++ sources
4679 * Unified Parallel C Support:: Compiling Unified Parallel C sources
4680 * Assembly Support:: Compiling assembly sources
4681 * Fortran 77 Support:: Compiling Fortran 77 sources
4682 * Fortran 9x Support:: Compiling Fortran 9x sources
4683 * Java Support with gcj:: Compiling Java sources using gcj
4684 * Vala Support:: Compiling Vala sources
4685 * Support for Other Languages:: Compiling other languages
4686 * Dependencies:: Automatic dependency tracking
4687 * EXEEXT:: Support for executable extensions
4692 @section Building a program
4694 In order to build a program, you need to tell Automake which sources
4695 are part of it, and which libraries it should be linked with.
4697 This section also covers conditional compilation of sources or
4698 programs. Most of the comments about these also apply to libraries
4699 (@pxref{A Library}) and libtool libraries (@pxref{A Shared Library}).
4702 * Program Sources:: Defining program sources
4703 * Linking:: Linking with libraries or extra objects
4704 * Conditional Sources:: Handling conditional sources
4705 * Conditional Programs:: Building a program conditionally
4708 @node Program Sources
4709 @subsection Defining program sources
4711 @cindex @code{PROGRAMS}, @code{bindir}
4713 @vindex bin_PROGRAMS
4714 @vindex sbin_PROGRAMS
4715 @vindex libexec_PROGRAMS
4716 @vindex pkglibexec_PROGRAMS
4717 @vindex noinst_PROGRAMS
4718 @vindex check_PROGRAMS
4720 In a directory containing source that gets built into a program (as
4721 opposed to a library or a script), the @code{PROGRAMS} primary is used.
4722 Programs can be installed in @code{bindir}, @code{sbindir},
4723 @code{libexecdir}, @code{pkglibexecdir}, or not at all
4724 (@code{noinst_}). They can also be built only for @samp{make check}, in
4725 which case the prefix is @samp{check_}.
4730 bin_PROGRAMS = hello
4733 In this simple case, the resulting @file{Makefile.in} will contain code
4734 to generate a program named @code{hello}.
4736 Associated with each program are several assisting variables that are
4737 named after the program. These variables are all optional, and have
4738 reasonable defaults. Each variable, its use, and default is spelled out
4739 below; we use the ``hello'' example throughout.
4741 The variable @code{hello_SOURCES} is used to specify which source files
4742 get built into an executable:
4745 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
4748 This causes each mentioned @file{.c} file to be compiled into the
4749 corresponding @file{.o}. Then all are linked to produce @file{hello}.
4751 @cindex @code{_SOURCES} primary, defined
4752 @cindex @code{SOURCES} primary, defined
4753 @cindex Primary variable, @code{SOURCES}
4756 If @code{hello_SOURCES} is not specified, then it defaults to the single
4757 file @file{hello.c} (@pxref{Default _SOURCES}).
4761 Multiple programs can be built in a single directory. Multiple programs
4762 can share a single source file, which must be listed in each
4763 @code{_SOURCES} definition.
4765 @cindex Header files in @code{_SOURCES}
4766 @cindex @code{_SOURCES} and header files
4768 Header files listed in a @code{_SOURCES} definition will be included in
4769 the distribution but otherwise ignored. In case it isn't obvious, you
4770 should not include the header file generated by @file{configure} in a
4771 @code{_SOURCES} variable; this file should not be distributed. Lex
4772 (@file{.l}) and Yacc (@file{.y}) files can also be listed; see @ref{Yacc
4777 @subsection Linking the program
4779 If you need to link against libraries that are not found by
4780 @command{configure}, you can use @code{LDADD} to do so. This variable is
4781 used to specify additional objects or libraries to link with; it is
4782 inappropriate for specifying specific linker flags, you should use
4783 @code{AM_LDFLAGS} for this purpose.
4787 @cindex @code{prog_LDADD}, defined
4789 Sometimes, multiple programs are built in one directory but do not share
4790 the same link-time requirements. In this case, you can use the
4791 @code{@var{prog}_LDADD} variable (where @var{prog} is the name of the
4792 program as it appears in some @code{_PROGRAMS} variable, and usually
4793 written in lowercase) to override @code{LDADD}. If this variable exists
4794 for a given program, then that program is not linked using @code{LDADD}.
4797 For instance, in GNU cpio, @code{pax}, @code{cpio} and @code{mt} are
4798 linked against the library @file{libcpio.a}. However, @code{rmt} is
4799 built in the same directory, and has no such link requirement. Also,
4800 @code{mt} and @code{rmt} are only built on certain architectures. Here
4801 is what cpio's @file{src/Makefile.am} looks like (abridged):
4804 bin_PROGRAMS = cpio pax $(MT)
4805 libexec_PROGRAMS = $(RMT)
4806 EXTRA_PROGRAMS = mt rmt
4808 LDADD = ../lib/libcpio.a $(INTLLIBS)
4811 cpio_SOURCES = @dots{}
4812 pax_SOURCES = @dots{}
4813 mt_SOURCES = @dots{}
4814 rmt_SOURCES = @dots{}
4817 @cindex @code{_LDFLAGS}, defined
4818 @vindex maude_LDFLAGS
4819 @code{@var{prog}_LDADD} is inappropriate for passing program-specific
4820 linker flags (except for @option{-l}, @option{-L}, @option{-dlopen} and
4821 @option{-dlpreopen}). So, use the @code{@var{prog}_LDFLAGS} variable for
4824 @cindex @code{_DEPENDENCIES}, defined
4825 @vindex maude_DEPENDENCIES
4826 @vindex EXTRA_maude_DEPENDENCIES
4827 It is also occasionally useful to have a program depend on some other
4828 target that is not actually part of that program. This can be done
4829 using either the @code{@var{prog}_DEPENDENCIES} or the
4830 @code{EXTRA_@var{prog}_DEPENDENCIES} variable. Each program depends on
4831 the contents both variables, but no further interpretation is done.
4833 Since these dependencies are associated to the link rule used to
4834 create the programs they should normally list files used by the link
4835 command. That is @file{*.$(OBJEXT)}, @file{*.a}, or @file{*.la}
4836 files. In rare cases you may need to add other kinds of files such as
4837 linker scripts, but @emph{listing a source file in
4838 @code{_DEPENDENCIES} is wrong}. If some source file needs to be built
4839 before all the components of a program are built, consider using the
4840 @code{BUILT_SOURCES} variable instead (@pxref{Sources}).
4842 If @code{@var{prog}_DEPENDENCIES} is not supplied, it is computed by
4843 Automake. The automatically-assigned value is the contents of
4844 @code{@var{prog}_LDADD}, with most configure substitutions, @option{-l},
4845 @option{-L}, @option{-dlopen} and @option{-dlpreopen} options removed. The
4846 configure substitutions that are left in are only @samp{$(LIBOBJS)} and
4847 @samp{$(ALLOCA)}; these are left because it is known that they will not
4848 cause an invalid value for @code{@var{prog}_DEPENDENCIES} to be
4851 @ref{Conditional Sources} shows a situation where @code{_DEPENDENCIES}
4854 The @code{EXTRA_@var{prog}_DEPENDENCIES} may be useful for cases where
4855 you merely want to augment the @command{automake}-generated
4856 @code{@var{prog}_DEPENDENCIES} rather than replacing it.
4858 @cindex @code{LDADD} and @option{-l}
4859 @cindex @option{-l} and @code{LDADD}
4860 We recommend that you avoid using @option{-l} options in @code{LDADD}
4861 or @code{@var{prog}_LDADD} when referring to libraries built by your
4862 package. Instead, write the file name of the library explicitly as in
4863 the above @code{cpio} example. Use @option{-l} only to list
4864 third-party libraries. If you follow this rule, the default value of
4865 @code{@var{prog}_DEPENDENCIES} will list all your local libraries and
4866 omit the other ones.
4869 @node Conditional Sources
4870 @subsection Conditional compilation of sources
4872 You can't put a configure substitution (e.g., @samp{@@FOO@@} or
4873 @samp{$(FOO)} where @code{FOO} is defined via @code{AC_SUBST}) into a
4874 @code{_SOURCES} variable. The reason for this is a bit hard to
4875 explain, but suffice to say that it simply won't work. Automake will
4876 give an error if you try to do this.
4878 Fortunately there are two other ways to achieve the same result. One is
4879 to use configure substitutions in @code{_LDADD} variables, the other is
4880 to use an Automake conditional.
4882 @subsubheading Conditional Compilation using @code{_LDADD} Substitutions
4884 @cindex @code{EXTRA_prog_SOURCES}, defined
4886 Automake must know all the source files that could possibly go into a
4887 program, even if not all the files are built in every circumstance. Any
4888 files that are only conditionally built should be listed in the
4889 appropriate @code{EXTRA_} variable. For instance, if
4890 @file{hello-linux.c} or @file{hello-generic.c} were conditionally included
4891 in @code{hello}, the @file{Makefile.am} would contain:
4894 bin_PROGRAMS = hello
4895 hello_SOURCES = hello-common.c
4896 EXTRA_hello_SOURCES = hello-linux.c hello-generic.c
4897 hello_LDADD = $(HELLO_SYSTEM)
4898 hello_DEPENDENCIES = $(HELLO_SYSTEM)
4902 You can then setup the @samp{$(HELLO_SYSTEM)} substitution from
4903 @file{configure.ac}:
4908 *linux*) HELLO_SYSTEM='hello-linux.$(OBJEXT)' ;;
4909 *) HELLO_SYSTEM='hello-generic.$(OBJEXT)' ;;
4911 AC_SUBST([HELLO_SYSTEM])
4915 In this case, the variable @code{HELLO_SYSTEM} should be replaced by
4916 either @file{hello-linux.o} or @file{hello-generic.o}, and added to
4917 both @code{hello_DEPENDENCIES} and @code{hello_LDADD} in order to be
4918 built and linked in.
4920 @subsubheading Conditional Compilation using Automake Conditionals
4922 An often simpler way to compile source files conditionally is to use
4923 Automake conditionals. For instance, you could use this
4924 @file{Makefile.am} construct to build the same @file{hello} example:
4927 bin_PROGRAMS = hello
4929 hello_SOURCES = hello-linux.c hello-common.c
4931 hello_SOURCES = hello-generic.c hello-common.c
4935 In this case, @file{configure.ac} should setup the @code{LINUX}
4936 conditional using @code{AM_CONDITIONAL} (@pxref{Conditionals}).
4938 When using conditionals like this you don't need to use the
4939 @code{EXTRA_} variable, because Automake will examine the contents of
4940 each variable to construct the complete list of source files.
4942 If your program uses a lot of files, you will probably prefer a
4943 conditional @samp{+=}.
4946 bin_PROGRAMS = hello
4947 hello_SOURCES = hello-common.c
4949 hello_SOURCES += hello-linux.c
4951 hello_SOURCES += hello-generic.c
4955 @node Conditional Programs
4956 @subsection Conditional compilation of programs
4957 @cindex Conditional programs
4958 @cindex Programs, conditional
4960 Sometimes it is useful to determine the programs that are to be built
4961 at configure time. For instance, GNU @code{cpio} only builds
4962 @code{mt} and @code{rmt} under special circumstances. The means to
4963 achieve conditional compilation of programs are the same you can use
4964 to compile source files conditionally: substitutions or conditionals.
4966 @subsubheading Conditional Programs using @command{configure} Substitutions
4968 @vindex EXTRA_PROGRAMS
4969 @cindex @code{EXTRA_PROGRAMS}, defined
4970 In this case, you must notify Automake of all the programs that can
4971 possibly be built, but at the same time cause the generated
4972 @file{Makefile.in} to use the programs specified by @command{configure}.
4973 This is done by having @command{configure} substitute values into each
4974 @code{_PROGRAMS} definition, while listing all optionally built programs
4975 in @code{EXTRA_PROGRAMS}.
4978 bin_PROGRAMS = cpio pax $(MT)
4979 libexec_PROGRAMS = $(RMT)
4980 EXTRA_PROGRAMS = mt rmt
4983 As explained in @ref{EXEEXT}, Automake will rewrite
4984 @code{bin_PROGRAMS}, @code{libexec_PROGRAMS}, and
4985 @code{EXTRA_PROGRAMS}, appending @samp{$(EXEEXT)} to each binary.
4986 Obviously it cannot rewrite values obtained at run-time through
4987 @command{configure} substitutions, therefore you should take care of
4988 appending @samp{$(EXEEXT)} yourself, as in @samp{AC_SUBST([MT],
4989 ['mt$@{EXEEXT@}'])}.
4991 @subsubheading Conditional Programs using Automake Conditionals
4993 You can also use Automake conditionals (@pxref{Conditionals}) to
4994 select programs to be built. In this case you don't have to worry
4995 about @samp{$(EXEEXT)} or @code{EXTRA_PROGRAMS}.
4997 @c Keep in sync with exeext.sh
4999 bin_PROGRAMS = cpio pax
5004 libexec_PROGRAMS = rmt
5010 @section Building a library
5012 @cindex @code{_LIBRARIES} primary, defined
5013 @cindex @code{LIBRARIES} primary, defined
5014 @cindex Primary variable, @code{LIBRARIES}
5017 @vindex lib_LIBRARIES
5018 @vindex pkglib_LIBRARIES
5019 @vindex noinst_LIBRARIES
5021 Building a library is much like building a program. In this case, the
5022 name of the primary is @code{LIBRARIES}. Libraries can be installed in
5023 @code{libdir} or @code{pkglibdir}.
5025 @xref{A Shared Library}, for information on how to build shared
5026 libraries using libtool and the @code{LTLIBRARIES} primary.
5028 Each @code{_LIBRARIES} variable is a list of the libraries to be built.
5029 For instance, to create a library named @file{libcpio.a}, but not install
5030 it, you would write:
5033 noinst_LIBRARIES = libcpio.a
5034 libcpio_a_SOURCES = @dots{}
5037 The sources that go into a library are determined exactly as they are
5038 for programs, via the @code{_SOURCES} variables. Note that the library
5039 name is canonicalized (@pxref{Canonicalization}), so the @code{_SOURCES}
5040 variable corresponding to @file{libcpio.a} is @samp{libcpio_a_SOURCES},
5041 not @samp{libcpio.a_SOURCES}.
5043 @vindex maude_LIBADD
5044 Extra objects can be added to a library using the
5045 @code{@var{library}_LIBADD} variable. This should be used for objects
5046 determined by @command{configure}. Again from @code{cpio}:
5048 @c Keep in sync with pr401c.sh
5050 libcpio_a_LIBADD = $(LIBOBJS) $(ALLOCA)
5053 In addition, sources for extra objects that will not exist until
5054 configure-time must be added to the @code{BUILT_SOURCES} variable
5057 Building a static library is done by compiling all object files, then
5058 by invoking @samp{$(AR) $(ARFLAGS)} followed by the name of the
5059 library and the list of objects, and finally by calling
5060 @samp{$(RANLIB)} on that library. You should call
5061 @code{AC_PROG_RANLIB} from your @file{configure.ac} to define
5062 @code{RANLIB} (Automake will complain otherwise). You should also
5063 call @code{AM_PROG_AR} to define @code{AR}, in order to support unusual
5064 archivers such as Microsoft lib. @code{ARFLAGS} will default to
5065 @code{cru}; you can override this variable by setting it in your
5066 @file{Makefile.am} or by @code{AC_SUBST}ing it from your
5067 @file{configure.ac}. You can override the @code{AR} variable by
5068 defining a per-library @code{maude_AR} variable (@pxref{Program and
5069 Library Variables}).
5071 @cindex Empty libraries
5072 Be careful when selecting library components conditionally. Because
5073 building an empty library is not portable, you should ensure that any
5074 library always contains at least one object.
5076 To use a static library when building a program, add it to
5077 @code{LDADD} for this program. In the following example, the program
5078 @file{cpio} is statically linked with the library @file{libcpio.a}.
5081 noinst_LIBRARIES = libcpio.a
5082 libcpio_a_SOURCES = @dots{}
5085 cpio_SOURCES = cpio.c @dots{}
5086 cpio_LDADD = libcpio.a
5090 @node A Shared Library
5091 @section Building a Shared Library
5093 @cindex Shared libraries, support for
5095 Building shared libraries portably is a relatively complex matter.
5096 For this reason, GNU Libtool (@pxref{Top, , Introduction, libtool, The
5097 Libtool Manual}) was created to help build shared libraries in a
5098 platform-independent way.
5101 * Libtool Concept:: Introducing Libtool
5102 * Libtool Libraries:: Declaring Libtool Libraries
5103 * Conditional Libtool Libraries:: Building Libtool Libraries Conditionally
5104 * Conditional Libtool Sources:: Choosing Library Sources Conditionally
5105 * Libtool Convenience Libraries:: Building Convenience Libtool Libraries
5106 * Libtool Modules:: Building Libtool Modules
5107 * Libtool Flags:: Using _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS
5108 * LTLIBOBJS:: Using $(LTLIBOBJS) and $(LTALLOCA)
5109 * Libtool Issues:: Common Issues Related to Libtool's Use
5112 @node Libtool Concept
5113 @subsection The Libtool Concept
5115 @cindex @command{libtool}, introduction
5116 @cindex libtool library, definition
5117 @cindex suffix @file{.la}, defined
5118 @cindex @file{.la} suffix, defined
5120 Libtool abstracts shared and static libraries into a unified concept
5121 henceforth called @dfn{libtool libraries}. Libtool libraries are
5122 files using the @file{.la} suffix, and can designate a static library,
5123 a shared library, or maybe both. Their exact nature cannot be
5124 determined until @file{./configure} is run: not all platforms support
5125 all kinds of libraries, and users can explicitly select which
5126 libraries should be built. (However the package's maintainers can
5127 tune the default, @pxref{AC_PROG_LIBTOOL, , The @code{AC_PROG_LIBTOOL}
5128 macro, libtool, The Libtool Manual}.)
5130 @cindex suffix @file{.lo}, defined
5131 Because object files for shared and static libraries must be compiled
5132 differently, libtool is also used during compilation. Object files
5133 built by libtool are called @dfn{libtool objects}: these are files
5134 using the @file{.lo} suffix. Libtool libraries are built from these
5137 You should not assume anything about the structure of @file{.la} or
5138 @file{.lo} files and how libtool constructs them: this is libtool's
5139 concern, and the last thing one wants is to learn about libtool's
5140 guts. However the existence of these files matters, because they are
5141 used as targets and dependencies in @file{Makefile}s rules when
5142 building libtool libraries. There are situations where you may have
5143 to refer to these, for instance when expressing dependencies for
5144 building source files conditionally (@pxref{Conditional Libtool
5147 @cindex @file{libltdl}, introduction
5149 People considering writing a plug-in system, with dynamically loaded
5150 modules, should look into @file{libltdl}: libtool's dlopening library
5151 (@pxref{Using libltdl, , Using libltdl, libtool, The Libtool Manual}).
5152 This offers a portable dlopening facility to load libtool libraries
5153 dynamically, and can also achieve static linking where unavoidable.
5155 Before we discuss how to use libtool with Automake in details, it
5156 should be noted that the libtool manual also has a section about how
5157 to use Automake with libtool (@pxref{Using Automake, , Using Automake
5158 with Libtool, libtool, The Libtool Manual}).
5160 @node Libtool Libraries
5161 @subsection Building Libtool Libraries
5163 @cindex @code{_LTLIBRARIES} primary, defined
5164 @cindex @code{LTLIBRARIES} primary, defined
5165 @cindex Primary variable, @code{LTLIBRARIES}
5166 @cindex Example of shared libraries
5167 @vindex lib_LTLIBRARIES
5168 @vindex pkglib_LTLIBRARIES
5169 @vindex _LTLIBRARIES
5171 Automake uses libtool to build libraries declared with the
5172 @code{LTLIBRARIES} primary. Each @code{_LTLIBRARIES} variable is a
5173 list of libtool libraries to build. For instance, to create a libtool
5174 library named @file{libgettext.la}, and install it in @code{libdir},
5178 lib_LTLIBRARIES = libgettext.la
5179 libgettext_la_SOURCES = gettext.c gettext.h @dots{}
5182 Automake predefines the variable @code{pkglibdir}, so you can use
5183 @code{pkglib_LTLIBRARIES} to install libraries in
5184 @samp{$(libdir)/@@PACKAGE@@/}.
5186 If @file{gettext.h} is a public header file that needs to be installed
5187 in order for people to use the library, it should be declared using a
5188 @code{_HEADERS} variable, not in @code{libgettext_la_SOURCES}.
5189 Headers listed in the latter should be internal headers that are not
5190 part of the public interface.
5193 lib_LTLIBRARIES = libgettext.la
5194 libgettext_la_SOURCES = gettext.c @dots{}
5195 include_HEADERS = gettext.h @dots{}
5198 A package can build and install such a library along with other
5199 programs that use it. This dependency should be specified using
5200 @code{LDADD}. The following example builds a program named
5201 @file{hello} that is linked with @file{libgettext.la}.
5204 lib_LTLIBRARIES = libgettext.la
5205 libgettext_la_SOURCES = gettext.c @dots{}
5207 bin_PROGRAMS = hello
5208 hello_SOURCES = hello.c @dots{}
5209 hello_LDADD = libgettext.la
5213 Whether @file{hello} is statically or dynamically linked with
5214 @file{libgettext.la} is not yet known: this will depend on the
5215 configuration of libtool and the capabilities of the host.
5218 @node Conditional Libtool Libraries
5219 @subsection Building Libtool Libraries Conditionally
5220 @cindex libtool libraries, conditional
5221 @cindex conditional libtool libraries
5223 Like conditional programs (@pxref{Conditional Programs}), there are
5224 two main ways to build conditional libraries: using Automake
5225 conditionals or using Autoconf @code{AC_SUBST}itutions.
5227 The important implementation detail you have to be aware of is that
5228 the place where a library will be installed matters to libtool: it
5229 needs to be indicated @emph{at link-time} using the @option{-rpath}
5232 For libraries whose destination directory is known when Automake runs,
5233 Automake will automatically supply the appropriate @option{-rpath}
5234 option to libtool. This is the case for libraries listed explicitly in
5235 some installable @code{_LTLIBRARIES} variables such as
5236 @code{lib_LTLIBRARIES}.
5238 However, for libraries determined at configure time (and thus
5239 mentioned in @code{EXTRA_LTLIBRARIES}), Automake does not know the
5240 final installation directory. For such libraries you must add the
5241 @option{-rpath} option to the appropriate @code{_LDFLAGS} variable by
5244 The examples below illustrate the differences between these two methods.
5246 Here is an example where @code{WANTEDLIBS} is an @code{AC_SUBST}ed
5247 variable set at @file{./configure}-time to either @file{libfoo.la},
5248 @file{libbar.la}, both, or none. Although @samp{$(WANTEDLIBS)}
5249 appears in the @code{lib_LTLIBRARIES}, Automake cannot guess it
5250 relates to @file{libfoo.la} or @file{libbar.la} at the time it creates
5251 the link rule for these two libraries. Therefore the @option{-rpath}
5252 argument must be explicitly supplied.
5254 @c Keep in sync with ltcond.sh
5256 EXTRA_LTLIBRARIES = libfoo.la libbar.la
5257 lib_LTLIBRARIES = $(WANTEDLIBS)
5258 libfoo_la_SOURCES = foo.c @dots{}
5259 libfoo_la_LDFLAGS = -rpath '$(libdir)'
5260 libbar_la_SOURCES = bar.c @dots{}
5261 libbar_la_LDFLAGS = -rpath '$(libdir)'
5264 Here is how the same @file{Makefile.am} would look using Automake
5265 conditionals named @code{WANT_LIBFOO} and @code{WANT_LIBBAR}. Now
5266 Automake is able to compute the @option{-rpath} setting itself, because
5267 it's clear that both libraries will end up in @samp{$(libdir)} if they
5270 @c Keep in sync with ltcond.sh
5274 lib_LTLIBRARIES += libfoo.la
5277 lib_LTLIBRARIES += libbar.la
5279 libfoo_la_SOURCES = foo.c @dots{}
5280 libbar_la_SOURCES = bar.c @dots{}
5283 @node Conditional Libtool Sources
5284 @subsection Libtool Libraries with Conditional Sources
5286 Conditional compilation of sources in a library can be achieved in the
5287 same way as conditional compilation of sources in a program
5288 (@pxref{Conditional Sources}). The only difference is that
5289 @code{_LIBADD} should be used instead of @code{_LDADD} and that it
5290 should mention libtool objects (@file{.lo} files).
5292 So, to mimic the @file{hello} example from @ref{Conditional Sources},
5293 we could build a @file{libhello.la} library using either
5294 @file{hello-linux.c} or @file{hello-generic.c} with the following
5297 @c Keep in sync with ltcond2.sh
5299 lib_LTLIBRARIES = libhello.la
5300 libhello_la_SOURCES = hello-common.c
5301 EXTRA_libhello_la_SOURCES = hello-linux.c hello-generic.c
5302 libhello_la_LIBADD = $(HELLO_SYSTEM)
5303 libhello_la_DEPENDENCIES = $(HELLO_SYSTEM)
5307 And make sure @command{configure} defines @code{HELLO_SYSTEM} as
5308 either @file{hello-linux.lo} or @file{hello-@-generic.lo}.
5310 Or we could simply use an Automake conditional as follows.
5312 @c Keep in sync with ltcond2.sh
5314 lib_LTLIBRARIES = libhello.la
5315 libhello_la_SOURCES = hello-common.c
5317 libhello_la_SOURCES += hello-linux.c
5319 libhello_la_SOURCES += hello-generic.c
5323 @node Libtool Convenience Libraries
5324 @subsection Libtool Convenience Libraries
5325 @cindex convenience libraries, libtool
5326 @cindex libtool convenience libraries
5327 @vindex noinst_LTLIBRARIES
5328 @vindex check_LTLIBRARIES
5330 Sometimes you want to build libtool libraries that should not be
5331 installed. These are called @dfn{libtool convenience libraries} and
5332 are typically used to encapsulate many sublibraries, later gathered
5333 into one big installed library.
5335 Libtool convenience libraries are declared by directory-less variables
5336 such as @code{noinst_LTLIBRARIES}, @code{check_LTLIBRARIES}, or even
5337 @code{EXTRA_LTLIBRARIES}. Unlike installed libtool libraries they do
5338 not need an @option{-rpath} flag at link time (actually this is the only
5341 Convenience libraries listed in @code{noinst_LTLIBRARIES} are always
5342 built. Those listed in @code{check_LTLIBRARIES} are built only upon
5343 @samp{make check}. Finally, libraries listed in
5344 @code{EXTRA_LTLIBRARIES} are never built explicitly: Automake outputs
5345 rules to build them, but if the library does not appear as a Makefile
5346 dependency anywhere it won't be built (this is why
5347 @code{EXTRA_LTLIBRARIES} is used for conditional compilation).
5349 Here is a sample setup merging libtool convenience libraries from
5350 subdirectories into one main @file{libtop.la} library.
5352 @c Keep in sync with ltconv.sh
5354 # -- Top-level Makefile.am --
5355 SUBDIRS = sub1 sub2 @dots{}
5356 lib_LTLIBRARIES = libtop.la
5358 libtop_la_LIBADD = \
5363 # -- sub1/Makefile.am --
5364 noinst_LTLIBRARIES = libsub1.la
5365 libsub1_la_SOURCES = @dots{}
5367 # -- sub2/Makefile.am --
5368 # showing nested convenience libraries
5369 SUBDIRS = sub2.1 sub2.2 @dots{}
5370 noinst_LTLIBRARIES = libsub2.la
5371 libsub2_la_SOURCES =
5372 libsub2_la_LIBADD = \
5378 When using such setup, beware that @command{automake} will assume
5379 @file{libtop.la} is to be linked with the C linker. This is because
5380 @code{libtop_la_SOURCES} is empty, so @command{automake} picks C as
5381 default language. If @code{libtop_la_SOURCES} was not empty,
5382 @command{automake} would select the linker as explained in @ref{How
5383 the Linker is Chosen}.
5385 If one of the sublibraries contains non-C source, it is important that
5386 the appropriate linker be chosen. One way to achieve this is to
5387 pretend that there is such a non-C file among the sources of the
5388 library, thus forcing @command{automake} to select the appropriate
5389 linker. Here is the top-level @file{Makefile} of our example updated
5390 to force C++ linking.
5393 SUBDIRS = sub1 sub2 @dots{}
5394 lib_LTLIBRARIES = libtop.la
5396 # Dummy C++ source to cause C++ linking.
5397 nodist_EXTRA_libtop_la_SOURCES = dummy.cxx
5398 libtop_la_LIBADD = \
5404 @samp{EXTRA_*_SOURCES} variables are used to keep track of source
5405 files that might be compiled (this is mostly useful when doing
5406 conditional compilation using @code{AC_SUBST}, @pxref{Conditional
5407 Libtool Sources}), and the @code{nodist_} prefix means the listed
5408 sources are not to be distributed (@pxref{Program and Library
5409 Variables}). In effect the file @file{dummy.cxx} does not need to
5410 exist in the source tree. Of course if you have some real source file
5411 to list in @code{libtop_la_SOURCES} there is no point in cheating with
5412 @code{nodist_EXTRA_libtop_la_SOURCES}.
5415 @node Libtool Modules
5416 @subsection Libtool Modules
5417 @cindex modules, libtool
5418 @cindex libtool modules
5419 @cindex @option{-module}, libtool
5421 These are libtool libraries meant to be dlopened. They are
5422 indicated to libtool by passing @option{-module} at link-time.
5425 pkglib_LTLIBRARIES = mymodule.la
5426 mymodule_la_SOURCES = doit.c
5427 mymodule_la_LDFLAGS = -module
5430 Ordinarily, Automake requires that a library's name start with
5431 @code{lib}. However, when building a dynamically loadable module you
5432 might wish to use a "nonstandard" name. Automake will not complain
5433 about such nonstandard names if it knows the library being built is a
5434 libtool module, i.e., if @option{-module} explicitly appears in the
5435 library's @code{_LDFLAGS} variable (or in the common @code{AM_LDFLAGS}
5436 variable when no per-library @code{_LDFLAGS} variable is defined).
5438 As always, @code{AC_SUBST} variables are black boxes to Automake since
5439 their values are not yet known when @command{automake} is run.
5440 Therefore if @option{-module} is set via such a variable, Automake
5441 cannot notice it and will proceed as if the library was an ordinary
5442 libtool library, with strict naming.
5444 If @code{mymodule_la_SOURCES} is not specified, then it defaults to
5445 the single file @file{mymodule.c} (@pxref{Default _SOURCES}).
5448 @subsection @code{_LIBADD}, @code{_LDFLAGS}, and @code{_LIBTOOLFLAGS}
5449 @cindex @code{_LIBADD}, libtool
5450 @cindex @code{_LDFLAGS}, libtool
5451 @cindex @code{_LIBTOOLFLAGS}, libtool
5452 @vindex AM_LIBTOOLFLAGS
5453 @vindex LIBTOOLFLAGS
5454 @vindex maude_LIBTOOLFLAGS
5456 As shown in previous sections, the @samp{@var{library}_LIBADD}
5457 variable should be used to list extra libtool objects (@file{.lo}
5458 files) or libtool libraries (@file{.la}) to add to @var{library}.
5460 The @samp{@var{library}_LDFLAGS} variable is the place to list
5461 additional libtool linking flags, such as @option{-version-info},
5462 @option{-static}, and a lot more. @xref{Link mode, , Link mode,
5463 libtool, The Libtool Manual}.
5465 The @command{libtool} command has two kinds of options: mode-specific
5466 options and generic options. Mode-specific options such as the
5467 aforementioned linking flags should be lumped with the other flags
5468 passed to the tool invoked by @command{libtool} (hence the use of
5469 @samp{@var{library}_LDFLAGS} for libtool linking flags). Generic
5470 options include @option{--tag=@var{tag}} and @option{--silent}
5471 (@pxref{Invoking libtool, , Invoking @command{libtool}, libtool, The
5472 Libtool Manual} for more options) should appear before the mode
5473 selection on the command line; in @file{Makefile.am}s they should
5474 be listed in the @samp{@var{library}_LIBTOOLFLAGS} variable.
5476 If @samp{@var{library}_LIBTOOLFLAGS} is not defined, then the variable
5477 @code{AM_LIBTOOLFLAGS} is used instead.
5479 These flags are passed to libtool after the @option{--tag=@var{tag}}
5480 option computed by Automake (if any), so
5481 @samp{@var{library}_LIBTOOLFLAGS} (or @code{AM_LIBTOOLFLAGS}) is a
5482 good place to override or supplement the @option{--tag=@var{tag}}
5485 The libtool rules also use a @code{LIBTOOLFLAGS} variable that should
5486 not be set in @file{Makefile.am}: this is a user variable (@pxref{Flag
5487 Variables Ordering}. It allows users to run @samp{make
5488 LIBTOOLFLAGS=--silent}, for instance. Note that the verbosity of
5489 @command{libtool} can also be influenced with the Automake
5490 @option{silent-rules} option (@pxref{Options}).
5493 @node LTLIBOBJS, Libtool Issues, Libtool Flags, A Shared Library
5494 @subsection @code{LTLIBOBJS} and @code{LTALLOCA}
5495 @cindex @code{LTLIBOBJS}, special handling
5496 @cindex @code{LIBOBJS}, and Libtool
5497 @cindex @code{LTALLOCA}, special handling
5498 @cindex @code{ALLOCA}, and Libtool
5505 Where an ordinary library might include @samp{$(LIBOBJS)} or
5506 @samp{$(ALLOCA)} (@pxref{LIBOBJS}), a libtool library must use
5507 @samp{$(LTLIBOBJS)} or @samp{$(LTALLOCA)}. This is required because
5508 the object files that libtool operates on do not necessarily end in
5511 Nowadays, the computation of @code{LTLIBOBJS} from @code{LIBOBJS} is
5512 performed automatically by Autoconf (@pxref{AC_LIBOBJ vs LIBOBJS, ,
5513 @code{AC_LIBOBJ} vs.@: @code{LIBOBJS}, autoconf, The Autoconf Manual}).
5515 @node Libtool Issues
5516 @subsection Common Issues Related to Libtool's Use
5519 * Error required file ltmain.sh not found:: The need to run libtoolize
5520 * Objects created both with libtool and without:: Avoid a specific build race
5523 @node Error required file ltmain.sh not found
5524 @subsubsection Error: @samp{required file `./ltmain.sh' not found}
5525 @cindex @file{ltmain.sh} not found
5526 @cindex @command{libtoolize}, no longer run by @command{automake}
5527 @cindex @command{libtoolize} and @command{autoreconf}
5528 @cindex @command{autoreconf} and @command{libtoolize}
5529 @cindex @file{bootstrap.sh} and @command{autoreconf}
5530 @cindex @file{autogen.sh} and @command{autoreconf}
5532 Libtool comes with a tool called @command{libtoolize} that will
5533 install libtool's supporting files into a package. Running this
5534 command will install @file{ltmain.sh}. You should execute it before
5535 @command{aclocal} and @command{automake}.
5537 People upgrading old packages to newer autotools are likely to face
5538 this issue because older Automake versions used to call
5539 @command{libtoolize}. Therefore old build scripts do not call
5540 @command{libtoolize}.
5542 Since Automake 1.6, it has been decided that running
5543 @command{libtoolize} was none of Automake's business. Instead, that
5544 functionality has been moved into the @command{autoreconf} command
5545 (@pxref{autoreconf Invocation, , Using @command{autoreconf}, autoconf,
5546 The Autoconf Manual}). If you do not want to remember what to run and
5547 when, just learn the @command{autoreconf} command. Hopefully,
5548 replacing existing @file{bootstrap.sh} or @file{autogen.sh} scripts by
5549 a call to @command{autoreconf} should also free you from any similar
5550 incompatible change in the future.
5552 @node Objects created both with libtool and without
5553 @subsubsection Objects @samp{created with both libtool and without}
5555 Sometimes, the same source file is used both to build a libtool
5556 library and to build another non-libtool target (be it a program or
5559 Let's consider the following @file{Makefile.am}.
5563 prog_SOURCES = prog.c foo.c @dots{}
5565 lib_LTLIBRARIES = libfoo.la
5566 libfoo_la_SOURCES = foo.c @dots{}
5570 (In this trivial case the issue could be avoided by linking
5571 @file{libfoo.la} with @file{prog} instead of listing @file{foo.c} in
5572 @code{prog_SOURCES}. But let's assume we really want to keep
5573 @file{prog} and @file{libfoo.la} separate.)
5575 Technically, it means that we should build @file{foo.$(OBJEXT)} for
5576 @file{prog}, and @file{foo.lo} for @file{libfoo.la}. The problem is
5577 that in the course of creating @file{foo.lo}, libtool may erase (or
5578 replace) @file{foo.$(OBJEXT)}, and this cannot be avoided.
5580 Therefore, when Automake detects this situation it will complain
5581 with a message such as
5583 object `foo.$(OBJEXT)' created both with libtool and without
5586 A workaround for this issue is to ensure that these two objects get
5587 different basenames. As explained in @ref{Renamed Objects}, this
5588 happens automatically when per-targets flags are used.
5592 prog_SOURCES = prog.c foo.c @dots{}
5593 prog_CFLAGS = $(AM_CFLAGS)
5595 lib_LTLIBRARIES = libfoo.la
5596 libfoo_la_SOURCES = foo.c @dots{}
5600 Adding @samp{prog_CFLAGS = $(AM_CFLAGS)} is almost a no-op, because
5601 when the @code{prog_CFLAGS} is defined, it is used instead of
5602 @code{AM_CFLAGS}. However as a side effect it will cause
5603 @file{prog.c} and @file{foo.c} to be compiled as
5604 @file{prog-prog.$(OBJEXT)} and @file{prog-foo.$(OBJEXT)}, which solves
5607 @node Program and Library Variables
5608 @section Program and Library Variables
5610 Associated with each program is a collection of variables that can be
5611 used to modify how that program is built. There is a similar list of
5612 such variables for each library. The canonical name of the program (or
5613 library) is used as a base for naming these variables.
5615 In the list below, we use the name ``maude'' to refer to the program or
5616 library. In your @file{Makefile.am} you would replace this with the
5617 canonical name of your program. This list also refers to ``maude'' as a
5618 program, but in general the same rules apply for both static and dynamic
5619 libraries; the documentation below notes situations where programs and
5624 This variable, if it exists, lists all the source files that are
5625 compiled to build the program. These files are added to the
5626 distribution by default. When building the program, Automake will cause
5627 each source file to be compiled to a single @file{.o} file (or
5628 @file{.lo} when using libtool). Normally these object files are named
5629 after the source file, but other factors can change this. If a file in
5630 the @code{_SOURCES} variable has an unrecognized extension, Automake
5631 will do one of two things with it. If a suffix rule exists for turning
5632 files with the unrecognized extension into @file{.o} files, then
5633 @command{automake} will treat this file as it will any other source file
5634 (@pxref{Support for Other Languages}). Otherwise, the file will be
5635 ignored as though it were a header file.
5637 The prefixes @code{dist_} and @code{nodist_} can be used to control
5638 whether files listed in a @code{_SOURCES} variable are distributed.
5639 @code{dist_} is redundant, as sources are distributed by default, but it
5640 can be specified for clarity if desired.
5642 It is possible to have both @code{dist_} and @code{nodist_} variants of
5643 a given @code{_SOURCES} variable at once; this lets you easily
5644 distribute some files and not others, for instance:
5647 nodist_maude_SOURCES = nodist.c
5648 dist_maude_SOURCES = dist-me.c
5651 By default the output file (on Unix systems, the @file{.o} file) will
5652 be put into the current build directory. However, if the option
5653 @option{subdir-objects} is in effect in the current directory then the
5654 @file{.o} file will be put into the subdirectory named after the
5655 source file. For instance, with @option{subdir-objects} enabled,
5656 @file{sub/dir/file.c} will be compiled to @file{sub/dir/file.o}. Some
5657 people prefer this mode of operation. You can specify
5658 @option{subdir-objects} in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
5659 @cindex Subdirectory, objects in
5660 @cindex Objects in subdirectory
5663 @item EXTRA_maude_SOURCES
5664 Automake needs to know the list of files you intend to compile
5665 @emph{statically}. For one thing, this is the only way Automake has of
5666 knowing what sort of language support a given @file{Makefile.in}
5667 requires. @footnote{There are other, more obscure reasons for
5668 this limitation as well.} This means that, for example, you can't put a
5669 configure substitution like @samp{@@my_sources@@} into a @samp{_SOURCES}
5670 variable. If you intend to conditionally compile source files and use
5671 @file{configure} to substitute the appropriate object names into, e.g.,
5672 @code{_LDADD} (see below), then you should list the corresponding source
5673 files in the @code{EXTRA_} variable.
5675 This variable also supports @code{dist_} and @code{nodist_} prefixes.
5676 For instance, @code{nodist_EXTRA_maude_SOURCES} would list extra
5677 sources that may need to be built, but should not be distributed.
5680 A static library is created by default by invoking @samp{$(AR)
5681 $(ARFLAGS)} followed by the name of the library and then the objects
5682 being put into the library. You can override this by setting the
5683 @code{_AR} variable. This is usually used with C++; some C++
5684 compilers require a special invocation in order to instantiate all the
5685 templates that should go into a library. For instance, the SGI C++
5686 compiler likes this variable set like so:
5688 libmaude_a_AR = $(CXX) -ar -o
5692 Extra objects can be added to a @emph{library} using the @code{_LIBADD}
5693 variable. For instance, this should be used for objects determined by
5694 @command{configure} (@pxref{A Library}).
5696 In the case of libtool libraries, @code{maude_LIBADD} can also refer
5697 to other libtool libraries.
5700 Extra objects (@file{*.$(OBJEXT)}) and libraries (@file{*.a},
5701 @file{*.la}) can be added to a @emph{program} by listing them in the
5702 @code{_LDADD} variable. For instance, this should be used for objects
5703 determined by @command{configure} (@pxref{Linking}).
5705 @code{_LDADD} and @code{_LIBADD} are inappropriate for passing
5706 program-specific linker flags (except for @option{-l}, @option{-L},
5707 @option{-dlopen} and @option{-dlpreopen}). Use the @code{_LDFLAGS} variable
5710 For instance, if your @file{configure.ac} uses @code{AC_PATH_XTRA}, you
5711 could link your program against the X libraries like so:
5714 maude_LDADD = $(X_PRE_LIBS) $(X_LIBS) $(X_EXTRA_LIBS)
5717 We recommend that you use @option{-l} and @option{-L} only when
5718 referring to third-party libraries, and give the explicit file names
5719 of any library built by your package. Doing so will ensure that
5720 @code{maude_DEPENDENCIES} (see below) is correctly defined by default.
5723 This variable is used to pass extra flags to the link step of a program
5724 or a shared library. It overrides the @code{AM_LDFLAGS} variable.
5726 @item maude_LIBTOOLFLAGS
5727 This variable is used to pass extra options to @command{libtool}.
5728 It overrides the @code{AM_LIBTOOLFLAGS} variable.
5729 These options are output before @command{libtool}'s @option{--mode=@var{mode}}
5730 option, so they should not be mode-specific options (those belong to
5731 the compiler or linker flags). @xref{Libtool Flags}.
5733 @item maude_DEPENDENCIES
5734 @itemx EXTRA_maude_DEPENDENCIES
5735 It is also occasionally useful to have a target (program or library)
5736 depend on some other file that is not actually part of that target.
5737 This can be done using the @code{_DEPENDENCIES} variable. Each
5738 target depends on the contents of such a variable, but no further
5739 interpretation is done.
5741 Since these dependencies are associated to the link rule used to
5742 create the programs they should normally list files used by the link
5743 command. That is @file{*.$(OBJEXT)}, @file{*.a}, or @file{*.la} files
5744 for programs; @file{*.lo} and @file{*.la} files for Libtool libraries;
5745 and @file{*.$(OBJEXT)} files for static libraries. In rare cases you
5746 may need to add other kinds of files such as linker scripts, but
5747 @emph{listing a source file in @code{_DEPENDENCIES} is wrong}. If
5748 some source file needs to be built before all the components of a
5749 program are built, consider using the @code{BUILT_SOURCES} variable
5752 If @code{_DEPENDENCIES} is not supplied, it is computed by Automake.
5753 The automatically-assigned value is the contents of @code{_LDADD} or
5754 @code{_LIBADD}, with most configure substitutions, @option{-l}, @option{-L},
5755 @option{-dlopen} and @option{-dlpreopen} options removed. The configure
5756 substitutions that are left in are only @samp{$(LIBOBJS)} and
5757 @samp{$(ALLOCA)}; these are left because it is known that they will not
5758 cause an invalid value for @code{_DEPENDENCIES} to be generated.
5760 @code{_DEPENDENCIES} is more likely used to perform conditional
5761 compilation using an @code{AC_SUBST} variable that contains a list of
5762 objects. @xref{Conditional Sources}, and @ref{Conditional Libtool
5765 The @code{EXTRA_*_DEPENDENCIES} variable may be useful for cases where
5766 you merely want to augment the @command{automake}-generated
5767 @code{_DEPENDENCIES} variable rather than replacing it.
5770 You can override the linker on a per-program basis. By default the
5771 linker is chosen according to the languages used by the program. For
5772 instance, a program that includes C++ source code would use the C++
5773 compiler to link. The @code{_LINK} variable must hold the name of a
5774 command that can be passed all the @file{.o} file names and libraries
5775 to link against as arguments. Note that the name of the underlying
5776 program is @emph{not} passed to @code{_LINK}; typically one uses
5780 maude_LINK = $(CCLD) -magic -o $@@
5783 If a @code{_LINK} variable is not supplied, it may still be generated
5784 and used by Automake due to the use of per-target link flags such as
5785 @code{_CFLAGS}, @code{_LDFLAGS} or @code{_LIBTOOLFLAGS}, in cases where
5788 @item maude_CCASFLAGS
5790 @itemx maude_CPPFLAGS
5791 @itemx maude_CXXFLAGS
5793 @itemx maude_GCJFLAGS
5795 @itemx maude_OBJCFLAGS
5796 @itemx maude_OBJCXXFLAGS
5798 @itemx maude_UPCFLAGS
5800 @cindex per-target compilation flags, defined
5801 Automake allows you to set compilation flags on a per-program (or
5802 per-library) basis. A single source file can be included in several
5803 programs, and it will potentially be compiled with different flags for
5804 each program. This works for any language directly supported by
5805 Automake. These @dfn{per-target compilation flags} are
5814 @samp{_OBJCXXFLAGS},
5816 @samp{_UPCFLAGS}, and
5819 When using a per-target compilation flag, Automake will choose a
5820 different name for the intermediate object files. Ordinarily a file
5821 like @file{sample.c} will be compiled to produce @file{sample.o}.
5822 However, if the program's @code{_CFLAGS} variable is set, then the
5823 object file will be named, for instance, @file{maude-sample.o}. (See
5824 also @ref{Renamed Objects}.) The use of per-target compilation flags
5825 with C sources requires that the macro @code{AM_PROG_CC_C_O} be called
5826 from @file{configure.ac}.
5828 In compilations with per-target flags, the ordinary @samp{AM_} form of
5829 the flags variable is @emph{not} automatically included in the
5830 compilation (however, the user form of the variable @emph{is} included).
5831 So for instance, if you want the hypothetical @file{maude} compilations
5832 to also use the value of @code{AM_CFLAGS}, you would need to write:
5835 maude_CFLAGS = @dots{} your flags @dots{} $(AM_CFLAGS)
5838 @xref{Flag Variables Ordering}, for more discussion about the
5839 interaction between user variables, @samp{AM_} shadow variables, and
5840 per-target variables.
5842 @item maude_SHORTNAME
5843 On some platforms the allowable file names are very short. In order to
5844 support these systems and per-target compilation flags at the same
5845 time, Automake allows you to set a ``short name'' that will influence
5846 how intermediate object files are named. For instance, in the following
5850 bin_PROGRAMS = maude
5851 maude_CPPFLAGS = -DSOMEFLAG
5853 maude_SOURCES = sample.c @dots{}
5857 the object file would be named @file{m-sample.o} rather than
5858 @file{maude-sample.o}.
5860 This facility is rarely needed in practice,
5861 and we recommend avoiding it until you find it is required.
5864 @node Default _SOURCES
5865 @section Default @code{_SOURCES}
5869 @cindex @code{_SOURCES}, default
5870 @cindex default @code{_SOURCES}
5871 @vindex AM_DEFAULT_SOURCE_EXT
5873 @code{_SOURCES} variables are used to specify source files of programs
5874 (@pxref{A Program}), libraries (@pxref{A Library}), and Libtool
5875 libraries (@pxref{A Shared Library}).
5877 When no such variable is specified for a target, Automake will define
5878 one itself. The default is to compile a single C file whose base name
5879 is the name of the target itself, with any extension replaced by
5880 @code{AM_DEFAULT_SOURCE_EXT}, which defaults to @file{.c}.
5882 For example if you have the following somewhere in your
5883 @file{Makefile.am} with no corresponding @code{libfoo_a_SOURCES}:
5886 lib_LIBRARIES = libfoo.a sub/libc++.a
5890 @file{libfoo.a} will be built using a default source file named
5891 @file{libfoo.c}, and @file{sub/libc++.a} will be built from
5892 @file{sub/libc++.c}. (In older versions @file{sub/libc++.a}
5893 would be built from @file{sub_libc___a.c}, i.e., the default source
5894 was the canonized name of the target, with @file{.c} appended.
5895 We believe the new behavior is more sensible, but for backward
5896 compatibility @command{automake} will use the old name if a file or a rule
5897 with that name exists and @code{AM_DEFAULT_SOURCE_EXT} is not used.)
5899 @cindex @code{check_PROGRAMS} example
5900 @vindex check_PROGRAMS
5901 Default sources are mainly useful in test suites, when building many
5902 test programs each from a single source. For instance, in
5905 check_PROGRAMS = test1 test2 test3
5906 AM_DEFAULT_SOURCE_EXT = .cpp
5910 @file{test1}, @file{test2}, and @file{test3} will be built
5911 from @file{test1.cpp}, @file{test2.cpp}, and @file{test3.cpp}.
5912 Without the last line, they will be built from @file{test1.c},
5913 @file{test2.c}, and @file{test3.c}.
5915 @cindex Libtool modules, default source example
5916 @cindex default source, Libtool modules example
5917 Another case where this is convenient is building many Libtool modules
5918 (@file{module@var{n}.la}), each defined in its own file
5919 (@file{module@var{n}.c}).
5922 AM_LDFLAGS = -module
5923 lib_LTLIBRARIES = module1.la module2.la module3.la
5926 @cindex empty @code{_SOURCES}
5927 @cindex @code{_SOURCES}, empty
5928 Finally, there is one situation where this default source computation
5929 needs to be avoided: when a target should not be built from sources.
5930 We already saw such an example in @ref{true}; this happens when all
5931 the constituents of a target have already been compiled and just need
5932 to be combined using a @code{_LDADD} variable. Then it is necessary
5933 to define an empty @code{_SOURCES} variable, so that @command{automake}
5934 does not compute a default.
5937 bin_PROGRAMS = target
5939 target_LDADD = libmain.a libmisc.a
5943 @section Special handling for @code{LIBOBJS} and @code{ALLOCA}
5945 @cindex @code{LIBOBJS}, example
5946 @cindex @code{ALLOCA}, example
5947 @cindex @code{LIBOBJS}, special handling
5948 @cindex @code{ALLOCA}, special handling
5954 The @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} variables list object
5955 files that should be compiled into the project to provide an
5956 implementation for functions that are missing or broken on the host
5957 system. They are substituted by @file{configure}.
5961 These variables are defined by Autoconf macros such as
5962 @code{AC_LIBOBJ}, @code{AC_REPLACE_FUNCS} (@pxref{Generic Functions, ,
5963 Generic Function Checks, autoconf, The Autoconf Manual}), or
5964 @code{AC_FUNC_ALLOCA} (@pxref{Particular Functions, , Particular
5965 Function Checks, autoconf, The Autoconf Manual}). Many other Autoconf
5966 macros call @code{AC_LIBOBJ} or @code{AC_REPLACE_FUNCS} to
5967 populate @samp{$(LIBOBJS)}.
5969 @acindex AC_LIBSOURCE
5971 Using these variables is very similar to doing conditional compilation
5972 using @code{AC_SUBST} variables, as described in @ref{Conditional
5973 Sources}. That is, when building a program, @samp{$(LIBOBJS)} and
5974 @samp{$(ALLOCA)} should be added to the associated @samp{*_LDADD}
5975 variable, or to the @samp{*_LIBADD} variable when building a library.
5976 However there is no need to list the corresponding sources in
5977 @samp{EXTRA_*_SOURCES} nor to define @samp{*_DEPENDENCIES}. Automake
5978 automatically adds @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} to the
5979 dependencies, and it will discover the list of corresponding source
5980 files automatically (by tracing the invocations of the
5981 @code{AC_LIBSOURCE} Autoconf macros). If you have already defined
5982 @samp{*_DEPENDENCIES} explicitly for an unrelated reason, then you
5983 either need to add these variables manually, or use
5984 @samp{EXTRA_*_DEPENDENCIES} instead of @samp{*_DEPENDENCIES}.
5986 These variables are usually used to build a portability library that
5987 is linked with all the programs of the project. We now review a
5988 sample setup. First, @file{configure.ac} contains some checks that
5989 affect either @code{LIBOBJS} or @code{ALLOCA}.
5994 AC_CONFIG_LIBOBJ_DIR([lib])
5996 AC_FUNC_MALLOC dnl May add malloc.$(OBJEXT) to LIBOBJS
5997 AC_FUNC_MEMCMP dnl May add memcmp.$(OBJEXT) to LIBOBJS
5998 AC_REPLACE_FUNCS([strdup]) dnl May add strdup.$(OBJEXT) to LIBOBJS
5999 AC_FUNC_ALLOCA dnl May add alloca.$(OBJEXT) to ALLOCA
6008 @acindex AC_CONFIG_LIBOBJ_DIR
6010 The @code{AC_CONFIG_LIBOBJ_DIR} tells Autoconf that the source files
6011 of these object files are to be found in the @file{lib/} directory.
6012 Automake can also use this information, otherwise it expects the
6013 source files are to be in the directory where the @samp{$(LIBOBJS)}
6014 and @samp{$(ALLOCA)} variables are used.
6016 The @file{lib/} directory should therefore contain @file{malloc.c},
6017 @file{memcmp.c}, @file{strdup.c}, @file{alloca.c}. Here is its
6023 noinst_LIBRARIES = libcompat.a
6024 libcompat_a_SOURCES =
6025 libcompat_a_LIBADD = $(LIBOBJS) $(ALLOCA)
6028 The library can have any name, of course, and anyway it is not going
6029 to be installed: it just holds the replacement versions of the missing
6030 or broken functions so we can later link them in. Many projects
6031 also include extra functions, specific to the project, in that
6032 library: they are simply added on the @code{_SOURCES} line.
6034 @cindex Empty libraries and @samp{$(LIBOBJS)}
6035 @cindex @samp{$(LIBOBJS)} and empty libraries
6036 There is a small trap here, though: @samp{$(LIBOBJS)} and
6037 @samp{$(ALLOCA)} might be empty, and building an empty library is not
6038 portable. You should ensure that there is always something to put in
6039 @file{libcompat.a}. Most projects will also add some utility
6040 functions in that directory, and list them in
6041 @code{libcompat_a_SOURCES}, so in practice @file{libcompat.a} cannot
6044 Finally here is how this library could be used from the @file{src/}
6050 # Link all programs in this directory with libcompat.a
6051 LDADD = ../lib/libcompat.a
6053 bin_PROGRAMS = tool1 tool2 @dots{}
6054 tool1_SOURCES = @dots{}
6055 tool2_SOURCES = @dots{}
6058 When option @option{subdir-objects} is not used, as in the above
6059 example, the variables @samp{$(LIBOBJS)} or @samp{$(ALLOCA)} can only
6060 be used in the directory where their sources lie. E.g., here it would
6061 be wrong to use @samp{$(LIBOBJS)} or @samp{$(ALLOCA)} in
6062 @file{src/Makefile.am}. However if both @option{subdir-objects} and
6063 @code{AC_CONFIG_LIBOBJ_DIR} are used, it is OK to use these variables
6064 in other directories. For instance @file{src/Makefile.am} could be
6070 AUTOMAKE_OPTIONS = subdir-objects
6071 LDADD = $(LIBOBJS) $(ALLOCA)
6073 bin_PROGRAMS = tool1 tool2 @dots{}
6074 tool1_SOURCES = @dots{}
6075 tool2_SOURCES = @dots{}
6078 Because @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} contain object
6079 file names that end with @samp{.$(OBJEXT)}, they are not suitable for
6080 Libtool libraries (where the expected object extension is @file{.lo}):
6081 @code{LTLIBOBJS} and @code{LTALLOCA} should be used instead.
6083 @code{LTLIBOBJS} is defined automatically by Autoconf and should not
6084 be defined by hand (as in the past), however at the time of writing
6085 @code{LTALLOCA} still needs to be defined from @code{ALLOCA} manually.
6086 @xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs.@: @code{LIBOBJS},
6087 autoconf, The Autoconf Manual}.
6090 @node Program Variables
6091 @section Variables used when building a program
6093 Occasionally it is useful to know which @file{Makefile} variables
6094 Automake uses for compilations, and in which order (@pxref{Flag
6095 Variables Ordering}); for instance, you might need to do your own
6096 compilation in some special cases.
6098 Some variables are inherited from Autoconf; these are @code{CC},
6099 @code{CFLAGS}, @code{CPPFLAGS}, @code{DEFS}, @code{LDFLAGS}, and
6108 There are some additional variables that Automake defines on its own:
6112 The contents of this variable are passed to every compilation that invokes
6113 the C preprocessor; it is a list of arguments to the preprocessor. For
6114 instance, @option{-I} and @option{-D} options should be listed here.
6116 Automake already provides some @option{-I} options automatically, in a
6117 separate variable that is also passed to every compilation that invokes
6118 the C preprocessor. In particular it generates @samp{-I.},
6119 @samp{-I$(srcdir)}, and a @option{-I} pointing to the directory holding
6120 @file{config.h} (if you've used @code{AC_CONFIG_HEADERS} or
6121 @code{AM_CONFIG_HEADER}). You can disable the default @option{-I}
6122 options using the @option{nostdinc} option.
6124 When a file to be included is generated during the build and not part
6125 of a distribution tarball, its location is under @code{$(builddir)},
6126 not under @code{$(srcdir)}. This matters especially for packages that
6127 use header files placed in sub-directories and want to allow builds
6128 outside the source tree (@pxref{VPATH Builds}). In that case we
6129 recommend to use a pair of @option{-I} options, such as, e.g.,
6130 @samp{-Isome/subdir -I$(srcdir)/some/subdir} or
6131 @samp{-I$(top_builddir)/some/subdir -I$(top_srcdir)/some/subdir}.
6132 Note that the reference to the build tree should come before the
6133 reference to the source tree, so that accidentally leftover generated
6134 files in the source directory are ignored.
6136 @code{AM_CPPFLAGS} is ignored in preference to a per-executable (or
6137 per-library) @code{_CPPFLAGS} variable if it is defined.
6140 This does the same job as @code{AM_CPPFLAGS} (or any per-target
6141 @code{_CPPFLAGS} variable if it is used). It is an older name for the
6142 same functionality. This variable is deprecated; we suggest using
6143 @code{AM_CPPFLAGS} and per-target @code{_CPPFLAGS} instead.
6146 This is the variable the @file{Makefile.am} author can use to pass
6147 in additional C compiler flags. It is more fully documented elsewhere.
6148 In some situations, this is not used, in preference to the
6149 per-executable (or per-library) @code{_CFLAGS}.
6152 This is the command used to actually compile a C source file. The
6153 file name is appended to form the complete command line.
6156 This is the variable the @file{Makefile.am} author can use to pass
6157 in additional linker flags. In some situations, this is not used, in
6158 preference to the per-executable (or per-library) @code{_LDFLAGS}.
6161 This is the command used to actually link a C program. It already
6162 includes @samp{-o $@@} and the usual variable references (for instance,
6163 @code{CFLAGS}); it takes as ``arguments'' the names of the object files
6164 and libraries to link in. This variable is not used when the linker is
6165 overridden with a per-target @code{_LINK} variable or per-target flags
6166 cause Automake to define such a @code{_LINK} variable.
6171 @section Yacc and Lex support
6173 Automake has somewhat idiosyncratic support for Yacc and Lex.
6175 Automake assumes that the @file{.c} file generated by @command{yacc}
6176 (or @command{lex}) should be named using the basename of the input
6177 file. That is, for a yacc source file @file{foo.y}, Automake will
6178 cause the intermediate file to be named @file{foo.c} (as opposed to
6179 @file{y.tab.c}, which is more traditional).
6181 The extension of a yacc source file is used to determine the extension
6182 of the resulting C or C++ source and header files. Note that header
6183 files are generated only when the @option{-d} Yacc option is used; see
6184 below for more information about this flag, and how to specify it.
6185 Files with the extension @file{.y} will thus be turned into @file{.c}
6186 sources and @file{.h} headers; likewise, @file{.yy} will become
6187 @file{.cc} and @file{.hh}, @file{.y++} will become @file{c++} and
6188 @file{h++}, @file{.yxx} will become @file{.cxx} and @file{.hxx},
6189 and @file{.ypp} will become @file{.cpp} and @file{.hpp}.
6191 Similarly, lex source files can be used to generate C or C++; the
6192 extensions @file{.l}, @file{.ll}, @file{.l++}, @file{.lxx}, and
6193 @file{.lpp} are recognized.
6195 You should never explicitly mention the intermediate (C or C++) file
6196 in any @code{SOURCES} variable; only list the source file.
6198 The intermediate files generated by @command{yacc} (or @command{lex})
6199 will be included in any distribution that is made. That way the user
6200 doesn't need to have @command{yacc} or @command{lex}.
6202 If a @command{yacc} source file is seen, then your @file{configure.ac} must
6203 define the variable @code{YACC}. This is most easily done by invoking
6204 the macro @code{AC_PROG_YACC} (@pxref{Particular Programs, , Particular
6205 Program Checks, autoconf, The Autoconf Manual}).
6209 When @code{yacc} is invoked, it is passed @code{AM_YFLAGS} and
6210 @code{YFLAGS}. The latter is a user variable and the former is
6211 intended for the @file{Makefile.am} author.
6213 @code{AM_YFLAGS} is usually used to pass the @option{-d} option to
6214 @command{yacc}. Automake knows what this means and will automatically
6215 adjust its rules to update and distribute the header file built by
6216 @samp{yacc -d}@footnote{Please note that @command{automake} recognizes
6217 @option{-d} in @code{AM_YFLAGS} only if it is not clustered with other
6218 options; for example, it won't be recognized if @code{AM_YFLAGS} is
6219 @option{-dt}, but it will be if @code{AM_YFLAGS} is @option{-d -t} or
6221 What Automake cannot guess, though, is where this
6222 header will be used: it is up to you to ensure the header gets built
6223 before it is first used. Typically this is necessary in order for
6224 dependency tracking to work when the header is included by another
6225 file. The common solution is listing the header file in
6226 @code{BUILT_SOURCES} (@pxref{Sources}) as follows.
6229 BUILT_SOURCES = parser.h
6232 foo_SOURCES = @dots{} parser.y @dots{}
6235 If a @command{lex} source file is seen, then your @file{configure.ac}
6236 must define the variable @code{LEX}. You can use @code{AC_PROG_LEX}
6237 to do this (@pxref{Particular Programs, , Particular Program Checks,
6238 autoconf, The Autoconf Manual}), but using @code{AM_PROG_LEX} macro
6239 (@pxref{Macros}) is recommended.
6243 When @command{lex} is invoked, it is passed @code{AM_LFLAGS} and
6244 @code{LFLAGS}. The latter is a user variable and the former is
6245 intended for the @file{Makefile.am} author.
6247 When @code{AM_MAINTAINER_MODE} (@pxref{maintainer-mode}) is used, the
6248 rebuild rule for distributed Yacc and Lex sources are only used when
6249 @code{maintainer-mode} is enabled, or when the files have been erased.
6251 @cindex @command{ylwrap}
6252 @cindex @command{yacc}, multiple parsers
6253 @cindex Multiple @command{yacc} parsers
6254 @cindex Multiple @command{lex} lexers
6255 @cindex @command{lex}, multiple lexers
6257 When @command{lex} or @command{yacc} sources are used, @code{automake
6258 -i} automatically installs an auxiliary program called
6259 @command{ylwrap} in your package (@pxref{Auxiliary Programs}). This
6260 program is used by the build rules to rename the output of these
6261 tools, and makes it possible to include multiple @command{yacc} (or
6262 @command{lex}) source files in a single directory. (This is necessary
6263 because yacc's output file name is fixed, and a parallel make could
6264 conceivably invoke more than one instance of @command{yacc}
6267 For @command{yacc}, simply managing locking is insufficient. The output of
6268 @command{yacc} always uses the same symbol names internally, so it isn't
6269 possible to link two @command{yacc} parsers into the same executable.
6271 We recommend using the following renaming hack used in @command{gdb}:
6273 #define yymaxdepth c_maxdepth
6274 #define yyparse c_parse
6276 #define yyerror c_error
6277 #define yylval c_lval
6278 #define yychar c_char
6279 #define yydebug c_debug
6280 #define yypact c_pact
6287 #define yyexca c_exca
6288 #define yyerrflag c_errflag
6289 #define yynerrs c_nerrs
6293 #define yy_yys c_yys
6294 #define yystate c_state
6297 #define yy_yyv c_yyv
6299 #define yylloc c_lloc
6300 #define yyreds c_reds
6301 #define yytoks c_toks
6302 #define yylhs c_yylhs
6303 #define yylen c_yylen
6304 #define yydefred c_yydefred
6305 #define yydgoto c_yydgoto
6306 #define yysindex c_yysindex
6307 #define yyrindex c_yyrindex
6308 #define yygindex c_yygindex
6309 #define yytable c_yytable
6310 #define yycheck c_yycheck
6311 #define yyname c_yyname
6312 #define yyrule c_yyrule
6315 For each define, replace the @samp{c_} prefix with whatever you like.
6316 These defines work for @command{bison}, @command{byacc}, and
6317 traditional @code{yacc}s. If you find a parser generator that uses a
6318 symbol not covered here, please report the new name so it can be added
6323 @section C++ Support
6326 @cindex Support for C++
6328 Automake includes full support for C++.
6330 Any package including C++ code must define the output variable
6331 @code{CXX} in @file{configure.ac}; the simplest way to do this is to use
6332 the @code{AC_PROG_CXX} macro (@pxref{Particular Programs, , Particular
6333 Program Checks, autoconf, The Autoconf Manual}).
6335 A few additional variables are defined when a C++ source file is seen:
6339 The name of the C++ compiler.
6342 Any flags to pass to the C++ compiler.
6345 The maintainer's variant of @code{CXXFLAGS}.
6348 The command used to actually compile a C++ source file. The file name
6349 is appended to form the complete command line.
6352 The command used to actually link a C++ program.
6356 @node Objective C Support
6357 @section Objective C Support
6359 @cindex Objective C support
6360 @cindex Support for Objective C
6362 Automake includes some support for Objective C.
6364 Any package including Objective C code must define the output variable
6365 @code{OBJC} in @file{configure.ac}; the simplest way to do this is to use
6366 the @code{AC_PROG_OBJC} macro (@pxref{Particular Programs, , Particular
6367 Program Checks, autoconf, The Autoconf Manual}).
6369 A few additional variables are defined when an Objective C source file
6374 The name of the Objective C compiler.
6377 Any flags to pass to the Objective C compiler.
6380 The maintainer's variant of @code{OBJCFLAGS}.
6383 The command used to actually compile an Objective C source file. The
6384 file name is appended to form the complete command line.
6387 The command used to actually link an Objective C program.
6391 @node Objective C++ Support
6392 @section Objective C++ Support
6394 @cindex Objective C++ support
6395 @cindex Support for Objective C++
6397 Automake includes some support for Objective C++.
6399 Any package including Objective C++ code must define the output variable
6400 @code{OBJCXX} in @file{configure.ac}; the simplest way to do this is to use
6401 the @code{AC_PROG_OBJCXX} macro (@pxref{Particular Programs, , Particular
6402 Program Checks, autoconf, The Autoconf Manual}).
6404 A few additional variables are defined when an Objective C++ source file
6409 The name of the Objective C++ compiler.
6412 Any flags to pass to the Objective C++ compiler.
6414 @item AM_OBJCXXFLAGS
6415 The maintainer's variant of @code{OBJCXXFLAGS}.
6418 The command used to actually compile an Objective C++ source file. The
6419 file name is appended to form the complete command line.
6422 The command used to actually link an Objective C++ program.
6426 @node Unified Parallel C Support
6427 @section Unified Parallel C Support
6429 @cindex Unified Parallel C support
6430 @cindex Support for Unified Parallel C
6432 Automake includes some support for Unified Parallel C.
6434 Any package including Unified Parallel C code must define the output
6435 variable @code{UPC} in @file{configure.ac}; the simplest way to do
6436 this is to use the @code{AM_PROG_UPC} macro (@pxref{Public Macros}).
6438 A few additional variables are defined when a Unified Parallel C
6439 source file is seen:
6443 The name of the Unified Parallel C compiler.
6446 Any flags to pass to the Unified Parallel C compiler.
6449 The maintainer's variant of @code{UPCFLAGS}.
6452 The command used to actually compile a Unified Parallel C source file.
6453 The file name is appended to form the complete command line.
6456 The command used to actually link a Unified Parallel C program.
6460 @node Assembly Support
6461 @section Assembly Support
6463 Automake includes some support for assembly code. There are two forms
6464 of assembler files: normal (@file{*.s}) and preprocessed by @code{CPP}
6465 (@file{*.S} or @file{*.sx}).
6470 @vindex AM_CCASFLAGS
6472 The variable @code{CCAS} holds the name of the compiler used to build
6473 assembly code. This compiler must work a bit like a C compiler; in
6474 particular it must accept @option{-c} and @option{-o}. The values of
6475 @code{CCASFLAGS} and @code{AM_CCASFLAGS} (or its per-target
6476 definition) is passed to the compilation. For preprocessed files,
6477 @code{DEFS}, @code{DEFAULT_INCLUDES}, @code{INCLUDES}, @code{CPPFLAGS}
6478 and @code{AM_CPPFLAGS} are also used.
6480 The autoconf macro @code{AM_PROG_AS} will define @code{CCAS} and
6481 @code{CCASFLAGS} for you (unless they are already set, it simply sets
6482 @code{CCAS} to the C compiler and @code{CCASFLAGS} to the C compiler
6483 flags), but you are free to define these variables by other means.
6485 Only the suffixes @file{.s}, @file{.S}, and @file{.sx} are recognized by
6486 @command{automake} as being files containing assembly code.
6489 @node Fortran 77 Support
6490 @comment node-name, next, previous, up
6491 @section Fortran 77 Support
6493 @cindex Fortran 77 support
6494 @cindex Support for Fortran 77
6496 Automake includes full support for Fortran 77.
6498 Any package including Fortran 77 code must define the output variable
6499 @code{F77} in @file{configure.ac}; the simplest way to do this is to use
6500 the @code{AC_PROG_F77} macro (@pxref{Particular Programs, , Particular
6501 Program Checks, autoconf, The Autoconf Manual}).
6503 A few additional variables are defined when a Fortran 77 source file is
6509 The name of the Fortran 77 compiler.
6512 Any flags to pass to the Fortran 77 compiler.
6515 The maintainer's variant of @code{FFLAGS}.
6518 Any flags to pass to the Ratfor compiler.
6521 The maintainer's variant of @code{RFLAGS}.
6524 The command used to actually compile a Fortran 77 source file. The file
6525 name is appended to form the complete command line.
6528 The command used to actually link a pure Fortran 77 program or shared
6533 Automake can handle preprocessing Fortran 77 and Ratfor source files in
6534 addition to compiling them@footnote{Much, if not most, of the
6535 information in the following sections pertaining to preprocessing
6536 Fortran 77 programs was taken almost verbatim from @ref{Catalogue of
6537 Rules, , Catalogue of Rules, make, The GNU Make Manual}.}. Automake
6538 also contains some support for creating programs and shared libraries
6539 that are a mixture of Fortran 77 and other languages (@pxref{Mixing
6540 Fortran 77 With C and C++}).
6542 These issues are covered in the following sections.
6545 * Preprocessing Fortran 77:: Preprocessing Fortran 77 sources
6546 * Compiling Fortran 77 Files:: Compiling Fortran 77 sources
6547 * Mixing Fortran 77 With C and C++:: Mixing Fortran 77 With C and C++
6551 @node Preprocessing Fortran 77
6552 @comment node-name, next, previous, up
6553 @subsection Preprocessing Fortran 77
6555 @cindex Preprocessing Fortran 77
6556 @cindex Fortran 77, Preprocessing
6557 @cindex Ratfor programs
6559 @file{N.f} is made automatically from @file{N.F} or @file{N.r}. This
6560 rule runs just the preprocessor to convert a preprocessable Fortran 77
6561 or Ratfor source file into a strict Fortran 77 source file. The precise
6562 command used is as follows:
6567 @code{$(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)@*
6568 $(AM_FFLAGS) $(FFLAGS)}
6571 @code{$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
6576 @node Compiling Fortran 77 Files
6577 @comment node-name, next, previous, up
6578 @subsection Compiling Fortran 77 Files
6580 @file{N.o} is made automatically from @file{N.f}, @file{N.F} or
6581 @file{N.r} by running the Fortran 77 compiler. The precise command used
6587 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS)}
6590 @code{$(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)@*
6591 $(AM_FFLAGS) $(FFLAGS)}
6594 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
6599 @node Mixing Fortran 77 With C and C++
6600 @comment node-name, next, previous, up
6601 @subsection Mixing Fortran 77 With C and C++
6603 @cindex Fortran 77, mixing with C and C++
6604 @cindex Mixing Fortran 77 with C and C++
6605 @cindex Linking Fortran 77 with C and C++
6607 @cindex Mixing Fortran 77 with C and/or C++
6609 Automake currently provides @emph{limited} support for creating programs
6610 and shared libraries that are a mixture of Fortran 77 and C and/or C++.
6611 However, there are many other issues related to mixing Fortran 77 with
6612 other languages that are @emph{not} (currently) handled by Automake, but
6613 that are handled by other packages@footnote{For example,
6614 @uref{http://www-zeus.desy.de/~burow/cfortran/, the cfortran package}
6615 addresses all of these inter-language issues, and runs under nearly all
6616 Fortran 77, C and C++ compilers on nearly all platforms. However,
6617 @command{cfortran} is not yet Free Software, but it will be in the next
6620 Automake can help in two ways:
6624 Automatic selection of the linker depending on which combinations of
6628 Automatic selection of the appropriate linker flags (e.g., @option{-L} and
6629 @option{-l}) to pass to the automatically selected linker in order to link
6630 in the appropriate Fortran 77 intrinsic and run-time libraries.
6632 @cindex @code{FLIBS}, defined
6634 These extra Fortran 77 linker flags are supplied in the output variable
6635 @code{FLIBS} by the @code{AC_F77_LIBRARY_LDFLAGS} Autoconf macro.
6636 @xref{Fortran Compiler, , Fortran Compiler Characteristics, autoconf,
6637 The Autoconf Manual}.
6640 If Automake detects that a program or shared library (as mentioned in
6641 some @code{_PROGRAMS} or @code{_LTLIBRARIES} primary) contains source
6642 code that is a mixture of Fortran 77 and C and/or C++, then it requires
6643 that the macro @code{AC_F77_LIBRARY_LDFLAGS} be called in
6644 @file{configure.ac}, and that either @code{$(FLIBS)}
6645 appear in the appropriate @code{_LDADD} (for programs) or @code{_LIBADD}
6646 (for shared libraries) variables. It is the responsibility of the
6647 person writing the @file{Makefile.am} to make sure that @samp{$(FLIBS)}
6648 appears in the appropriate @code{_LDADD} or
6649 @code{_LIBADD} variable.
6651 @cindex Mixed language example
6652 @cindex Example, mixed language
6654 For example, consider the following @file{Makefile.am}:
6658 foo_SOURCES = main.cc foo.f
6659 foo_LDADD = libfoo.la $(FLIBS)
6661 pkglib_LTLIBRARIES = libfoo.la
6662 libfoo_la_SOURCES = bar.f baz.c zardoz.cc
6663 libfoo_la_LIBADD = $(FLIBS)
6666 In this case, Automake will insist that @code{AC_F77_LIBRARY_LDFLAGS}
6667 is mentioned in @file{configure.ac}. Also, if @samp{$(FLIBS)} hadn't
6668 been mentioned in @code{foo_LDADD} and @code{libfoo_la_LIBADD}, then
6669 Automake would have issued a warning.
6672 * How the Linker is Chosen:: Automatic linker selection
6675 @node How the Linker is Chosen
6676 @comment node-name, next, previous, up
6677 @subsubsection How the Linker is Chosen
6679 @cindex Automatic linker selection
6680 @cindex Selecting the linker automatically
6682 When a program or library mixes several languages, Automake choose the
6683 linker according to the following priorities. (The names in
6684 parentheses are the variables containing the link command.)
6689 Native Java (@code{GCJLINK})
6692 Objective C++ (@code{OBJCXXLINK})
6695 C++ (@code{CXXLINK})
6698 Fortran 77 (@code{F77LINK})
6701 Fortran (@code{FCLINK})
6704 Objective C (@code{OBJCLINK})
6707 Unified Parallel C (@code{UPCLINK})
6713 For example, if Fortran 77, C and C++ source code is compiled
6714 into a program, then the C++ linker will be used. In this case, if the
6715 C or Fortran 77 linkers required any special libraries that weren't
6716 included by the C++ linker, then they must be manually added to an
6717 @code{_LDADD} or @code{_LIBADD} variable by the user writing the
6720 Automake only looks at the file names listed in @file{_SOURCES}
6721 variables to choose the linker, and defaults to the C linker.
6722 Sometimes this is inconvenient because you are linking against a
6723 library written in another language and would like to set the linker
6724 more appropriately. @xref{Libtool Convenience Libraries}, for a
6725 trick with @code{nodist_EXTRA_@dots{}_SOURCES}.
6727 A per-target @code{_LINK} variable will override the above selection.
6728 Per-target link flags will cause Automake to write a per-target
6729 @code{_LINK} variable according to the language chosen as above.
6732 @node Fortran 9x Support
6733 @comment node-name, next, previous, up
6734 @section Fortran 9x Support
6736 @cindex Fortran 9x support
6737 @cindex Support for Fortran 9x
6739 Automake includes support for Fortran 9x.
6741 Any package including Fortran 9x code must define the output variable
6742 @code{FC} in @file{configure.ac}; the simplest way to do this is to use
6743 the @code{AC_PROG_FC} macro (@pxref{Particular Programs, , Particular
6744 Program Checks, autoconf, The Autoconf Manual}).
6746 A few additional variables are defined when a Fortran 9x source file is
6752 The name of the Fortran 9x compiler.
6755 Any flags to pass to the Fortran 9x compiler.
6758 The maintainer's variant of @code{FCFLAGS}.
6761 The command used to actually compile a Fortran 9x source file. The file
6762 name is appended to form the complete command line.
6765 The command used to actually link a pure Fortran 9x program or shared
6771 * Compiling Fortran 9x Files:: Compiling Fortran 9x sources
6774 @node Compiling Fortran 9x Files
6775 @comment node-name, next, previous, up
6776 @subsection Compiling Fortran 9x Files
6778 @file{@var{file}.o} is made automatically from @file{@var{file}.f90},
6779 @file{@var{file}.f95}, @file{@var{file}.f03}, or @file{@var{file}.f08}
6780 by running the Fortran 9x compiler. The precise command used
6786 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f90) $<}
6789 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f95) $<}
6792 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f03) $<}
6795 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f08) $<}
6799 @node Java Support with gcj
6800 @comment node-name, next, previous, up
6801 @section Compiling Java sources using gcj
6803 @cindex Java support with gcj
6804 @cindex Support for Java with gcj
6805 @cindex Java to native code, compilation
6806 @cindex Compilation of Java to native code
6808 Automake includes support for natively compiled Java, using @command{gcj},
6809 the Java front end to the GNU Compiler Collection (rudimentary support
6810 for compiling Java to bytecode using the @command{javac} compiler is
6811 also present, @emph{albeit deprecated}; @pxref{Java}).
6813 Any package including Java code to be compiled must define the output
6814 variable @code{GCJ} in @file{configure.ac}; the variable @code{GCJFLAGS}
6815 must also be defined somehow (either in @file{configure.ac} or
6816 @file{Makefile.am}). The simplest way to do this is to use the
6817 @code{AM_PROG_GCJ} macro.
6821 By default, programs including Java source files are linked with
6824 As always, the contents of @code{AM_GCJFLAGS} are passed to every
6825 compilation invoking @command{gcj} (in its role as an ahead-of-time
6826 compiler, when invoking it to create @file{.class} files,
6827 @code{AM_JAVACFLAGS} is used instead). If it is necessary to pass
6828 options to @command{gcj} from @file{Makefile.am}, this variable, and not
6829 the user variable @code{GCJFLAGS}, should be used.
6833 @command{gcj} can be used to compile @file{.java}, @file{.class},
6834 @file{.zip}, or @file{.jar} files.
6836 When linking, @command{gcj} requires that the main class be specified
6837 using the @option{--main=} option. The easiest way to do this is to use
6838 the @code{_LDFLAGS} variable for the program.
6842 @comment node-name, next, previous, up
6843 @section Vala Support
6845 @cindex Vala Support
6846 @cindex Support for Vala
6848 Automake provides initial support for Vala
6849 (@uref{http://www.vala-project.org/}).
6850 This requires valac version 0.7.0 or later, and currently requires
6851 the user to use GNU @command{make}.
6854 foo_SOURCES = foo.vala bar.vala zardoc.c
6857 Any @file{.vala} file listed in a @code{_SOURCES} variable will be
6858 compiled into C code by the Vala compiler. The generated @file{.c} files are
6859 distributed. The end user does not need to have a Vala compiler installed.
6861 Automake ships with an Autoconf macro called @code{AM_PROG_VALAC}
6862 that will locate the Vala compiler and optionally check its version
6865 @defmac AM_PROG_VALAC (@ovar{minimum-version})
6866 Try to find a Vala compiler in @env{PATH}. If it is found, the variable
6867 @code{VALAC} is set. Optionally a minimum release number of the compiler
6871 AM_PROG_VALAC([0.7.0])
6875 There are a few variables that are used when compiling Vala sources:
6879 Path to the Vala compiler.
6882 Additional arguments for the Vala compiler.
6885 The maintainer's variant of @code{VALAFLAGS}.
6888 lib_LTLIBRARIES = libfoo.la
6889 libfoo_la_SOURCES = foo.vala
6893 Note that currently, you cannot use per-target @code{*_VALAFLAGS}
6894 (@pxref{Renamed Objects}) to produce different C files from one Vala
6898 @node Support for Other Languages
6899 @comment node-name, next, previous, up
6900 @section Support for Other Languages
6902 Automake currently only includes full support for C, C++ (@pxref{C++
6903 Support}), Objective C (@pxref{Objective C Support}),
6904 Objective C++ (@pxref{Objective C++ Support}),
6906 (@pxref{Fortran 77 Support}), Fortran 9x (@pxref{Fortran 9x Support}),
6907 and Java (@pxref{Java Support with gcj}). There is only rudimentary
6908 support for other languages, support for which will be improved based
6911 Some limited support for adding your own languages is available via the
6912 suffix rule handling (@pxref{Suffixes}).
6915 @section Automatic dependency tracking
6917 As a developer it is often painful to continually update the
6918 @file{Makefile.am} whenever the include-file dependencies change in a
6919 project. Automake supplies a way to automatically track dependency
6920 changes (@pxref{Dependency Tracking}).
6922 @cindex Dependency tracking
6923 @cindex Automatic dependency tracking
6925 Automake always uses complete dependencies for a compilation,
6926 including system headers. Automake's model is that dependency
6927 computation should be a side effect of the build. To this end,
6928 dependencies are computed by running all compilations through a
6929 special wrapper program called @command{depcomp}. @command{depcomp}
6930 understands how to coax many different C and C++ compilers into
6931 generating dependency information in the format it requires.
6932 @samp{automake -a} will install @command{depcomp} into your source
6933 tree for you. If @command{depcomp} can't figure out how to properly
6934 invoke your compiler, dependency tracking will simply be disabled for
6937 @cindex @command{depcomp}
6939 Experience with earlier versions of Automake (@pxref{Dependency Tracking
6940 Evolution, , Dependency Tracking Evolution, automake-history, Brief History
6941 of Automake}) taught us that it is not reliable to generate dependencies
6942 only on the maintainer's system, as configurations vary too much. So
6943 instead Automake implements dependency tracking at build time.
6945 Automatic dependency tracking can be suppressed by putting
6946 @option{no-dependencies} in the variable @code{AUTOMAKE_OPTIONS}, or
6947 passing @option{no-dependencies} as an argument to @code{AM_INIT_AUTOMAKE}
6948 (this should be the preferred way). Or, you can invoke @command{automake}
6949 with the @option{-i} option. Dependency tracking is enabled by default.
6951 @vindex AUTOMAKE_OPTIONS
6952 @opindex no-dependencies
6954 The person building your package also can choose to disable dependency
6955 tracking by configuring with @option{--disable-dependency-tracking}.
6957 @cindex Disabling dependency tracking
6958 @cindex Dependency tracking, disabling
6962 @section Support for executable extensions
6964 @cindex Executable extension
6965 @cindex Extension, executable
6968 On some platforms, such as Windows, executables are expected to have an
6969 extension such as @file{.exe}. On these platforms, some compilers (GCC
6970 among them) will automatically generate @file{foo.exe} when asked to
6971 generate @file{foo}.
6973 Automake provides mostly-transparent support for this. Unfortunately
6974 @emph{mostly} doesn't yet mean @emph{fully}. Until the English
6975 dictionary is revised, you will have to assist Automake if your package
6976 must support those platforms.
6978 One thing you must be aware of is that, internally, Automake rewrites
6979 something like this:
6982 bin_PROGRAMS = liver
6988 bin_PROGRAMS = liver$(EXEEXT)
6991 The targets Automake generates are likewise given the @samp{$(EXEEXT)}
6994 The variables @code{TESTS} and @code{XFAIL_TESTS} (@pxref{Simple Tests})
6995 are also rewritten if they contain filenames that have been declared as
6996 programs in the same @file{Makefile}. (This is mostly useful when some
6997 programs from @code{check_PROGRAMS} are listed in @code{TESTS}.)
6999 However, Automake cannot apply this rewriting to @command{configure}
7000 substitutions. This means that if you are conditionally building a
7001 program using such a substitution, then your @file{configure.ac} must
7002 take care to add @samp{$(EXEEXT)} when constructing the output variable.
7004 Sometimes maintainers like to write an explicit link rule for their
7005 program. Without executable extension support, this is easy---you
7006 simply write a rule whose target is the name of the program. However,
7007 when executable extension support is enabled, you must instead add the
7008 @samp{$(EXEEXT)} suffix.
7010 This might be a nuisance for maintainers who know their package will
7011 never run on a platform that has
7012 executable extensions. For those maintainers, the @option{no-exeext}
7013 option (@pxref{Options}) will disable this feature. This works in a
7014 fairly ugly way; if @option{no-exeext} is seen, then the presence of a
7015 rule for a target named @code{foo} in @file{Makefile.am} will override
7016 an @command{automake}-generated rule for @samp{foo$(EXEEXT)}. Without
7017 the @option{no-exeext} option, this use will give a diagnostic.
7021 @chapter Other Derived Objects
7023 Automake can handle derived objects that are not C programs. Sometimes
7024 the support for actually building such objects must be explicitly
7025 supplied, but Automake will still automatically handle installation and
7029 * Scripts:: Executable scripts
7030 * Headers:: Header files
7031 * Data:: Architecture-independent data files
7032 * Sources:: Derived sources
7037 @section Executable Scripts
7039 @cindex @code{_SCRIPTS} primary, defined
7040 @cindex @code{SCRIPTS} primary, defined
7041 @cindex Primary variable, @code{SCRIPTS}
7043 @cindex Installing scripts
7045 It is possible to define and install programs that are scripts. Such
7046 programs are listed using the @code{SCRIPTS} primary name. When the
7047 script is distributed in its final, installable form, the
7048 @file{Makefile} usually looks as follows:
7052 # Install my_script in $(bindir) and distribute it.
7053 dist_bin_SCRIPTS = my_script
7056 Scripts are not distributed by default; as we have just seen, those
7057 that should be distributed can be specified using a @code{dist_}
7058 prefix as with other primaries.
7060 @cindex @code{SCRIPTS}, installation directories
7062 @vindex sbin_SCRIPTS
7063 @vindex libexec_SCRIPTS
7064 @vindex pkgdata_SCRIPTS
7065 @vindex pkglibexec_SCRIPTS
7066 @vindex noinst_SCRIPTS
7067 @vindex check_SCRIPTS
7069 Scripts can be installed in @code{bindir}, @code{sbindir},
7070 @code{libexecdir}, @code{pkglibexecdir}, or @code{pkgdatadir}.
7072 Scripts that need not be installed can be listed in
7073 @code{noinst_SCRIPTS}, and among them, those which are needed only by
7074 @samp{make check} should go in @code{check_SCRIPTS}.
7076 When a script needs to be built, the @file{Makefile.am} should include
7077 the appropriate rules. For instance the @command{automake} program
7078 itself is a Perl script that is generated from @file{automake.in}.
7079 Here is how this is handled:
7082 bin_SCRIPTS = automake
7083 CLEANFILES = $(bin_SCRIPTS)
7084 EXTRA_DIST = automake.in
7086 do_subst = sed -e 's,[@@]datadir[@@],$(datadir),g' \
7087 -e 's,[@@]PERL[@@],$(PERL),g' \
7088 -e 's,[@@]PACKAGE[@@],$(PACKAGE),g' \
7089 -e 's,[@@]VERSION[@@],$(VERSION),g' \
7092 automake: automake.in Makefile
7093 $(do_subst) < $(srcdir)/automake.in > automake
7097 Such scripts for which a build rule has been supplied need to be
7098 deleted explicitly using @code{CLEANFILES} (@pxref{Clean}), and their
7099 sources have to be distributed, usually with @code{EXTRA_DIST}
7100 (@pxref{Basics of Distribution}).
7102 Another common way to build scripts is to process them from
7103 @file{configure} with @code{AC_CONFIG_FILES}. In this situation
7104 Automake knows which files should be cleaned and distributed, and what
7105 the rebuild rules should look like.
7107 For instance if @file{configure.ac} contains
7110 AC_CONFIG_FILES([src/my_script], [chmod +x src/my_script])
7114 to build @file{src/my_script} from @file{src/my_script.in}, then a
7115 @file{src/Makefile.am} to install this script in @code{$(bindir)} can
7119 bin_SCRIPTS = my_script
7120 CLEANFILES = $(bin_SCRIPTS)
7124 There is no need for @code{EXTRA_DIST} or any build rule: Automake
7125 infers them from @code{AC_CONFIG_FILES} (@pxref{Requirements}).
7126 @code{CLEANFILES} is still useful, because by default Automake will
7127 clean targets of @code{AC_CONFIG_FILES} in @code{distclean}, not
7130 Although this looks simpler, building scripts this way has one
7131 drawback: directory variables such as @code{$(datadir)} are not fully
7132 expanded and may refer to other directory variables.
7135 @section Header files
7137 @cindex @code{_HEADERS} primary, defined
7138 @cindex @code{HEADERS} primary, defined
7139 @cindex Primary variable, @code{HEADERS}
7141 @vindex noinst_HEADERS
7142 @cindex @code{HEADERS}, installation directories
7143 @cindex Installing headers
7144 @vindex include_HEADERS
7145 @vindex oldinclude_HEADERS
7146 @vindex pkginclude_HEADERS
7149 Header files that must be installed are specified by the
7150 @code{HEADERS} family of variables. Headers can be installed in
7151 @code{includedir}, @code{oldincludedir}, @code{pkgincludedir} or any
7152 other directory you may have defined (@pxref{Uniform}). For instance,
7155 include_HEADERS = foo.h bar/bar.h
7159 will install the two files as @file{$(includedir)/foo.h} and
7160 @file{$(includedir)/bar.h}.
7162 The @code{nobase_} prefix is also supported,
7165 nobase_include_HEADERS = foo.h bar/bar.h
7169 will install the two files as @file{$(includedir)/foo.h} and
7170 @file{$(includedir)/bar/bar.h} (@pxref{Alternative}).
7172 @vindex noinst_HEADERS
7173 Usually, only header files that accompany installed libraries need to
7174 be installed. Headers used by programs or convenience libraries are
7175 not installed. The @code{noinst_HEADERS} variable can be used for
7176 such headers. However when the header actually belongs to a single
7177 convenience library or program, we recommend listing it in the
7178 program's or library's @code{_SOURCES} variable (@pxref{Program
7179 Sources}) instead of in @code{noinst_HEADERS}. This is clearer for
7180 the @file{Makefile.am} reader. @code{noinst_HEADERS} would be the
7181 right variable to use in a directory containing only headers and no
7182 associated library or program.
7184 All header files must be listed somewhere; in a @code{_SOURCES}
7185 variable or in a @code{_HEADERS} variable. Missing ones will not
7186 appear in the distribution.
7188 For header files that are built and must not be distributed, use the
7189 @code{nodist_} prefix as in @code{nodist_include_HEADERS} or
7190 @code{nodist_prog_SOURCES}. If these generated headers are needed
7191 during the build, you must also ensure they exist before they are
7192 used (@pxref{Sources}).
7196 @section Architecture-independent data files
7198 @cindex @code{_DATA} primary, defined
7199 @cindex @code{DATA} primary, defined
7200 @cindex Primary variable, @code{DATA}
7203 Automake supports the installation of miscellaneous data files using the
7204 @code{DATA} family of variables.
7208 @vindex sysconf_DATA
7209 @vindex sharedstate_DATA
7210 @vindex localstate_DATA
7211 @vindex pkgdata_DATA
7213 Such data can be installed in the directories @code{datadir},
7214 @code{sysconfdir}, @code{sharedstatedir}, @code{localstatedir}, or
7217 By default, data files are @emph{not} included in a distribution. Of
7218 course, you can use the @code{dist_} prefix to change this on a
7221 Here is how Automake declares its auxiliary data files:
7224 dist_pkgdata_DATA = clean-kr.am clean.am @dots{}
7229 @section Built Sources
7231 Because Automake's automatic dependency tracking works as a side-effect
7232 of compilation (@pxref{Dependencies}) there is a bootstrap issue: a
7233 target should not be compiled before its dependencies are made, but
7234 these dependencies are unknown until the target is first compiled.
7236 Ordinarily this is not a problem, because dependencies are distributed
7237 sources: they preexist and do not need to be built. Suppose that
7238 @file{foo.c} includes @file{foo.h}. When it first compiles
7239 @file{foo.o}, @command{make} only knows that @file{foo.o} depends on
7240 @file{foo.c}. As a side-effect of this compilation @command{depcomp}
7241 records the @file{foo.h} dependency so that following invocations of
7242 @command{make} will honor it. In these conditions, it's clear there is
7243 no problem: either @file{foo.o} doesn't exist and has to be built
7244 (regardless of the dependencies), or accurate dependencies exist and
7245 they can be used to decide whether @file{foo.o} should be rebuilt.
7247 It's a different story if @file{foo.h} doesn't exist by the first
7248 @command{make} run. For instance, there might be a rule to build
7249 @file{foo.h}. This time @file{file.o}'s build will fail because the
7250 compiler can't find @file{foo.h}. @command{make} failed to trigger the
7251 rule to build @file{foo.h} first by lack of dependency information.
7253 @vindex BUILT_SOURCES
7254 @cindex @code{BUILT_SOURCES}, defined
7256 The @code{BUILT_SOURCES} variable is a workaround for this problem. A
7257 source file listed in @code{BUILT_SOURCES} is made on @samp{make all}
7258 or @samp{make check} (or even @samp{make install}) before other
7259 targets are processed. However, such a source file is not
7260 @emph{compiled} unless explicitly requested by mentioning it in some
7261 other @code{_SOURCES} variable.
7263 So, to conclude our introductory example, we could use
7264 @samp{BUILT_SOURCES = foo.h} to ensure @file{foo.h} gets built before
7265 any other target (including @file{foo.o}) during @samp{make all} or
7268 @code{BUILT_SOURCES} is actually a bit of a misnomer, as any file which
7269 must be created early in the build process can be listed in this
7270 variable. Moreover, all built sources do not necessarily have to be
7271 listed in @code{BUILT_SOURCES}. For instance, a generated @file{.c} file
7272 doesn't need to appear in @code{BUILT_SOURCES} (unless it is included by
7273 another source), because it's a known dependency of the associated
7276 It might be important to emphasize that @code{BUILT_SOURCES} is
7277 honored only by @samp{make all}, @samp{make check} and @samp{make
7278 install}. This means you cannot build a specific target (e.g.,
7279 @samp{make foo}) in a clean tree if it depends on a built source.
7280 However it will succeed if you have run @samp{make all} earlier,
7281 because accurate dependencies are already available.
7283 The next section illustrates and discusses the handling of built sources
7287 * Built Sources Example:: Several ways to handle built sources.
7290 @node Built Sources Example
7291 @subsection Built Sources Example
7293 Suppose that @file{foo.c} includes @file{bindir.h}, which is
7294 installation-dependent and not distributed: it needs to be built. Here
7295 @file{bindir.h} defines the preprocessor macro @code{bindir} to the
7296 value of the @command{make} variable @code{bindir} (inherited from
7299 We suggest several implementations below. It's not meant to be an
7300 exhaustive listing of all ways to handle built sources, but it will give
7301 you a few ideas if you encounter this issue.
7303 @subsubheading First Try
7305 This first implementation will illustrate the bootstrap issue mentioned
7306 in the previous section (@pxref{Sources}).
7308 Here is a tentative @file{Makefile.am}.
7314 nodist_foo_SOURCES = bindir.h
7315 CLEANFILES = bindir.h
7317 echo '#define bindir "$(bindir)"' >$@@
7320 This setup doesn't work, because Automake doesn't know that @file{foo.c}
7321 includes @file{bindir.h}. Remember, automatic dependency tracking works
7322 as a side-effect of compilation, so the dependencies of @file{foo.o} will
7323 be known only after @file{foo.o} has been compiled (@pxref{Dependencies}).
7324 The symptom is as follows.
7328 source='foo.c' object='foo.o' libtool=no \
7329 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
7330 depmode=gcc /bin/sh ./depcomp \
7331 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
7332 foo.c:2: bindir.h: No such file or directory
7333 make: *** [foo.o] Error 1
7336 In this example @file{bindir.h} is not distributed nor installed, and
7337 it is not even being built on-time. One may wonder if the
7338 @samp{nodist_foo_SOURCES = bindir.h} line has any use at all. This
7339 line simply states that @file{bindir.h} is a source of @code{foo}, so
7340 for instance, it should be inspected while generating tags
7341 (@pxref{Tags}). In other words, it does not help our present problem,
7342 and the build would fail identically without it.
7344 @subsubheading Using @code{BUILT_SOURCES}
7346 A solution is to require @file{bindir.h} to be built before anything
7347 else. This is what @code{BUILT_SOURCES} is meant for (@pxref{Sources}).
7352 nodist_foo_SOURCES = bindir.h
7353 BUILT_SOURCES = bindir.h
7354 CLEANFILES = bindir.h
7356 echo '#define bindir "$(bindir)"' >$@@
7359 See how @file{bindir.h} gets built first:
7363 echo '#define bindir "/usr/local/bin"' >bindir.h
7365 make[1]: Entering directory `/home/adl/tmp'
7366 source='foo.c' object='foo.o' libtool=no \
7367 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
7368 depmode=gcc /bin/sh ./depcomp \
7369 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
7370 gcc -g -O2 -o foo foo.o
7371 make[1]: Leaving directory `/home/adl/tmp'
7374 However, as said earlier, @code{BUILT_SOURCES} applies only to the
7375 @code{all}, @code{check}, and @code{install} targets. It still fails
7376 if you try to run @samp{make foo} explicitly:
7380 test -z "bindir.h" || rm -f bindir.h
7381 test -z "foo" || rm -f foo
7383 % : > .deps/foo.Po # Suppress previously recorded dependencies
7385 source='foo.c' object='foo.o' libtool=no \
7386 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
7387 depmode=gcc /bin/sh ./depcomp \
7388 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
7389 foo.c:2: bindir.h: No such file or directory
7390 make: *** [foo.o] Error 1
7393 @subsubheading Recording Dependencies manually
7395 Usually people are happy enough with @code{BUILT_SOURCES} because they
7396 never build targets such as @samp{make foo} before @samp{make all}, as
7397 in the previous example. However if this matters to you, you can
7398 avoid @code{BUILT_SOURCES} and record such dependencies explicitly in
7399 the @file{Makefile.am}.
7404 nodist_foo_SOURCES = bindir.h
7405 foo.$(OBJEXT): bindir.h
7406 CLEANFILES = bindir.h
7408 echo '#define bindir "$(bindir)"' >$@@
7411 You don't have to list @emph{all} the dependencies of @file{foo.o}
7412 explicitly, only those that might need to be built. If a dependency
7413 already exists, it will not hinder the first compilation and will be
7414 recorded by the normal dependency tracking code. (Note that after
7415 this first compilation the dependency tracking code will also have
7416 recorded the dependency between @file{foo.o} and
7417 @file{bindir.h}; so our explicit dependency is really useful to
7418 the first build only.)
7420 Adding explicit dependencies like this can be a bit dangerous if you are
7421 not careful enough. This is due to the way Automake tries not to
7422 overwrite your rules (it assumes you know better than it).
7423 @samp{foo.$(OBJEXT): bindir.h} supersedes any rule Automake may want to
7424 output to build @samp{foo.$(OBJEXT)}. It happens to work in this case
7425 because Automake doesn't have to output any @samp{foo.$(OBJEXT):}
7426 target: it relies on a suffix rule instead (i.e., @samp{.c.$(OBJEXT):}).
7427 Always check the generated @file{Makefile.in} if you do this.
7429 @subsubheading Build @file{bindir.h} from @file{configure}
7431 It's possible to define this preprocessor macro from @file{configure},
7432 either in @file{config.h} (@pxref{Defining Directories, , Defining
7433 Directories, autoconf, The Autoconf Manual}), or by processing a
7434 @file{bindir.h.in} file using @code{AC_CONFIG_FILES}
7435 (@pxref{Configuration Actions, ,Configuration Actions, autoconf, The
7438 At this point it should be clear that building @file{bindir.h} from
7439 @file{configure} works well for this example. @file{bindir.h} will exist
7440 before you build any target, hence will not cause any dependency issue.
7442 The Makefile can be shrunk as follows. We do not even have to mention
7450 However, it's not always possible to build sources from
7451 @file{configure}, especially when these sources are generated by a tool
7452 that needs to be built first.
7454 @subsubheading Build @file{bindir.c}, not @file{bindir.h}.
7456 Another attractive idea is to define @code{bindir} as a variable or
7457 function exported from @file{bindir.o}, and build @file{bindir.c}
7458 instead of @file{bindir.h}.
7461 noinst_PROGRAMS = foo
7462 foo_SOURCES = foo.c bindir.h
7463 nodist_foo_SOURCES = bindir.c
7464 CLEANFILES = bindir.c
7466 echo 'const char bindir[] = "$(bindir)";' >$@@
7469 @file{bindir.h} contains just the variable's declaration and doesn't
7470 need to be built, so it won't cause any trouble. @file{bindir.o} is
7471 always dependent on @file{bindir.c}, so @file{bindir.c} will get built
7474 @subsubheading Which is best?
7476 There is no panacea, of course. Each solution has its merits and
7479 You cannot use @code{BUILT_SOURCES} if the ability to run @samp{make
7480 foo} on a clean tree is important to you.
7482 You won't add explicit dependencies if you are leery of overriding
7483 an Automake rule by mistake.
7485 Building files from @file{./configure} is not always possible, neither
7486 is converting @file{.h} files into @file{.c} files.
7489 @node Other GNU Tools
7490 @chapter Other GNU Tools
7492 Since Automake is primarily intended to generate @file{Makefile.in}s for
7493 use in GNU programs, it tries hard to interoperate with other GNU tools.
7496 * Emacs Lisp:: Emacs Lisp
7499 * Java:: Java bytecode compilation (deprecated)
7507 @cindex @code{_LISP} primary, defined
7508 @cindex @code{LISP} primary, defined
7509 @cindex Primary variable, @code{LISP}
7515 Automake provides some support for Emacs Lisp. The @code{LISP} primary
7516 is used to hold a list of @file{.el} files. Possible prefixes for this
7517 primary are @code{lisp_} and @code{noinst_}. Note that if
7518 @code{lisp_LISP} is defined, then @file{configure.ac} must run
7519 @code{AM_PATH_LISPDIR} (@pxref{Macros}).
7521 @vindex dist_lisp_LISP
7522 @vindex dist_noinst_LISP
7523 Lisp sources are not distributed by default. You can prefix the
7524 @code{LISP} primary with @code{dist_}, as in @code{dist_lisp_LISP} or
7525 @code{dist_noinst_LISP}, to indicate that these files should be
7528 Automake will byte-compile all Emacs Lisp source files using the Emacs
7529 found by @code{AM_PATH_LISPDIR}, if any was found.
7531 Byte-compiled Emacs Lisp files are not portable among all versions of
7532 Emacs, so it makes sense to turn this off if you expect sites to have
7533 more than one version of Emacs installed. Furthermore, many packages
7534 don't actually benefit from byte-compilation. Still, we recommend
7535 that you byte-compile your Emacs Lisp sources. It is probably better
7536 for sites with strange setups to cope for themselves than to make the
7537 installation less nice for everybody else.
7539 There are two ways to avoid byte-compiling. Historically, we have
7540 recommended the following construct.
7543 lisp_LISP = file1.el file2.el
7548 @code{ELCFILES} is an internal Automake variable that normally lists
7549 all @file{.elc} files that must be byte-compiled. Automake defines
7550 @code{ELCFILES} automatically from @code{lisp_LISP}. Emptying this
7551 variable explicitly prevents byte-compilation.
7553 Since Automake 1.8, we now recommend using @code{lisp_DATA} instead:
7555 @c Keep in sync with primary-prefix-couples-documented-valid.sh
7557 lisp_DATA = file1.el file2.el
7560 Note that these two constructs are not equivalent. @code{_LISP} will
7561 not install a file if Emacs is not installed, while @code{_DATA} will
7562 always install its files.
7567 @cindex GNU Gettext support
7568 @cindex Gettext support
7569 @cindex Support for GNU Gettext
7571 If @code{AM_GNU_GETTEXT} is seen in @file{configure.ac}, then Automake
7572 turns on support for GNU gettext, a message catalog system for
7573 internationalization
7574 (@pxref{Top, , Introduction, gettext, GNU gettext utilities}).
7576 The @code{gettext} support in Automake requires the addition of one or
7577 two subdirectories to the package: @file{po} and possibly also @file{intl}.
7578 The latter is needed if @code{AM_GNU_GETTEXT} is not invoked with the
7579 @samp{external} argument, or if @code{AM_GNU_GETTEXT_INTL_SUBDIR} is used.
7580 Automake ensures that these directories exist and are mentioned in
7586 Automake provides support for GNU Libtool (@pxref{Top, , Introduction,
7587 libtool, The Libtool Manual}) with the @code{LTLIBRARIES} primary.
7588 @xref{A Shared Library}.
7592 @section Java bytecode compilation (deprecated)
7594 @cindex @code{_JAVA} primary, defined
7595 @cindex @code{JAVA} primary, defined
7596 @cindex Primary variable, @code{JAVA}
7597 @cindex Java to bytecode, compilation
7598 @cindex Compilation of Java to bytecode
7600 Automake provides some minimal support for Java bytecode compilation with
7601 the @code{JAVA} primary (in addition to the support for compiling Java to
7602 native machine code; @pxref{Java Support with gcj}). Note however that
7603 @emph{the interface and most features described here are deprecated}; the
7604 next automake release will strive to provide a better and cleaner
7605 interface, which however @emph{won't be backward-compatible}; the present
7606 interface will probably be removed altogether in future automake releases
7607 (1.13 or later), so don't use it in new code.
7609 Any @file{.java} files listed in a @code{_JAVA} variable will be
7610 compiled with @code{JAVAC} at build time. By default, @file{.java}
7611 files are not included in the distribution, you should use the
7612 @code{dist_} prefix to distribute them.
7614 Here is a typical setup for distributing @file{.java} files and
7615 installing the @file{.class} files resulting from their compilation.
7617 @c Keep in sync with primary-prefix-couples-documented-valid.sh
7619 javadir = $(datadir)/java
7620 dist_java_JAVA = a.java b.java @dots{}
7623 @cindex @code{JAVA} restrictions
7624 @cindex Restrictions for @code{JAVA}
7626 Currently Automake enforces the restriction that only one @code{_JAVA}
7627 primary can be used in a given @file{Makefile.am}. The reason for this
7628 restriction is that, in general, it isn't possible to know which
7629 @file{.class} files were generated from which @file{.java} files, so
7630 it would be impossible to know which files to install where. For
7631 instance, a @file{.java} file can define multiple classes; the resulting
7632 @file{.class} file names cannot be predicted without parsing the
7635 There are a few variables that are used when compiling Java sources:
7639 The name of the Java compiler. This defaults to @samp{javac}.
7642 The flags to pass to the compiler. This is considered to be a user
7643 variable (@pxref{User Variables}).
7646 More flags to pass to the Java compiler. This, and not
7647 @code{JAVACFLAGS}, should be used when it is necessary to put Java
7648 compiler flags into @file{Makefile.am}.
7651 The value of this variable is passed to the @option{-d} option to
7652 @code{javac}. It defaults to @samp{$(top_builddir)}.
7655 This variable is a shell expression that is used to set the
7656 @env{CLASSPATH} environment variable on the @code{javac} command line.
7657 (In the future we will probably handle class path setting differently.)
7664 @cindex @code{_PYTHON} primary, defined
7665 @cindex @code{PYTHON} primary, defined
7666 @cindex Primary variable, @code{PYTHON}
7669 Automake provides support for Python compilation with the
7670 @code{PYTHON} primary. A typical setup is to call
7671 @code{AM_PATH_PYTHON} in @file{configure.ac} and use a line like the
7672 following in @file{Makefile.am}:
7675 python_PYTHON = tree.py leave.py
7678 Any files listed in a @code{_PYTHON} variable will be byte-compiled
7679 with @command{py-compile} at install time. @command{py-compile}
7680 actually creates both standard (@file{.pyc}) and optimized
7681 (@file{.pyo}) byte-compiled versions of the source files. Note that
7682 because byte-compilation occurs at install time, any files listed in
7683 @code{noinst_PYTHON} will not be compiled. Python source files are
7684 included in the distribution by default, prepend @code{nodist_} (as in
7685 @code{nodist_python_PYTHON}) to omit them.
7687 Automake ships with an Autoconf macro called @code{AM_PATH_PYTHON}
7688 that will determine some Python-related directory variables (see
7689 below). If you have called @code{AM_PATH_PYTHON} from
7690 @file{configure.ac}, then you may use the variables
7691 @c Keep in sync with primary-prefix-couples-documented-valid.sh
7692 @code{python_PYTHON} or @code{pkgpython_PYTHON} to list Python source
7693 files in your @file{Makefile.am}, depending on where you want your files
7694 installed (see the definitions of @code{pythondir} and
7695 @code{pkgpythondir} below).
7697 @defmac AM_PATH_PYTHON (@ovar{version}, @ovar{action-if-found},
7698 @ovar{action-if-not-found})
7700 Search for a Python interpreter on the system. This macro takes three
7701 optional arguments. The first argument, if present, is the minimum
7702 version of Python required for this package: @code{AM_PATH_PYTHON}
7703 will skip any Python interpreter that is older than @var{version}.
7704 If an interpreter is found and satisfies @var{version}, then
7705 @var{action-if-found} is run. Otherwise, @var{action-if-not-found} is
7708 If @var{action-if-not-found} is not specified, as in the following
7709 example, the default is to abort @command{configure}.
7712 AM_PATH_PYTHON([2.2])
7716 This is fine when Python is an absolute requirement for the package.
7717 If Python >= 2.5 was only @emph{optional} to the package,
7718 @code{AM_PATH_PYTHON} could be called as follows.
7721 AM_PATH_PYTHON([2.5],, [:])
7724 If the @env{PYTHON} variable is set when @code{AM_PATH_PYTHON} is
7725 called, then that will be the only Python interpreter that is tried.
7727 @code{AM_PATH_PYTHON} creates the following output variables based on
7728 the Python installation found during configuration.
7733 The name of the Python executable, or @samp{:} if no suitable
7734 interpreter could be found.
7736 Assuming @var{action-if-not-found} is used (otherwise @file{./configure}
7737 will abort if Python is absent), the value of @code{PYTHON} can be used
7738 to setup a conditional in order to disable the relevant part of a build
7742 AM_PATH_PYTHON(,, [:])
7743 AM_CONDITIONAL([HAVE_PYTHON], [test "$PYTHON" != :])
7746 @item PYTHON_VERSION
7747 The Python version number, in the form @var{major}.@var{minor}
7748 (e.g., @samp{2.5}). This is currently the value of
7749 @samp{sys.version[:3]}.
7752 The string @samp{$@{prefix@}}. This term may be used in future work
7753 that needs the contents of Python's @samp{sys.prefix}, but general
7754 consensus is to always use the value from @command{configure}.
7756 @item PYTHON_EXEC_PREFIX
7757 The string @samp{$@{exec_prefix@}}. This term may be used in future work
7758 that needs the contents of Python's @samp{sys.exec_prefix}, but general
7759 consensus is to always use the value from @command{configure}.
7761 @item PYTHON_PLATFORM
7762 The canonical name used by Python to describe the operating system, as
7763 given by @samp{sys.platform}. This value is sometimes needed when
7764 building Python extensions.
7767 The directory name for the @file{site-packages} subdirectory of the
7768 standard Python install tree.
7771 This is the directory under @code{pythondir} that is named after the
7772 package. That is, it is @samp{$(pythondir)/$(PACKAGE)}. It is provided
7776 This is the directory where Python extension modules (shared libraries)
7777 should be installed. An extension module written in C could be declared
7778 as follows to Automake:
7780 @c Keep in sync with primary-prefix-couples-documented-valid.sh
7782 pyexec_LTLIBRARIES = quaternion.la
7783 quaternion_la_SOURCES = quaternion.c support.c support.h
7784 quaternion_la_LDFLAGS = -avoid-version -module
7788 This is a convenience variable that is defined as
7789 @samp{$(pyexecdir)/$(PACKAGE)}.
7792 All these directory variables have values that start with either
7793 @samp{$@{prefix@}} or @samp{$@{exec_prefix@}} unexpanded. This works
7794 fine in @file{Makefiles}, but it makes these variables hard to use in
7795 @file{configure}. This is mandated by the GNU coding standards, so
7796 that the user can run @samp{make prefix=/foo install}. The Autoconf
7797 manual has a section with more details on this topic
7798 (@pxref{Installation Directory Variables, , Installation Directory
7799 Variables, autoconf, The Autoconf Manual}). See also @ref{Hard-Coded
7804 @chapter Building documentation
7806 Currently Automake provides support for Texinfo and man pages.
7810 * Man Pages:: Man pages
7817 @cindex @code{_TEXINFOS} primary, defined
7818 @cindex @code{TEXINFOS} primary, defined
7819 @cindex Primary variable, @code{TEXINFOS}
7820 @cindex HTML output using Texinfo
7821 @cindex PDF output using Texinfo
7822 @cindex PS output using Texinfo
7823 @cindex DVI output using Texinfo
7825 @vindex info_TEXINFOS
7827 If the current directory contains Texinfo source, you must declare it
7828 with the @code{TEXINFOS} primary. Generally Texinfo files are converted
7829 into info, and thus the @code{info_TEXINFOS} variable is most commonly used
7830 here. Any Texinfo source file must end in the @file{.texi},
7831 @file{.txi}, or @file{.texinfo} extension. We recommend @file{.texi}
7834 Automake generates rules to build @file{.info}, @file{.dvi},
7835 @file{.ps}, @file{.pdf} and @file{.html} files from your Texinfo
7836 sources. Following the GNU Coding Standards, only the @file{.info}
7837 files are built by @samp{make all} and installed by @samp{make
7838 install} (unless you use @option{no-installinfo}, see below).
7839 Furthermore, @file{.info} files are automatically distributed so that
7840 Texinfo is not a prerequisite for installing your package.
7846 @trindex install-dvi
7847 @trindex install-html
7848 @trindex install-pdf
7850 Other documentation formats can be built on request by @samp{make
7851 dvi}, @samp{make ps}, @samp{make pdf} and @samp{make html}, and they
7852 can be installed with @samp{make install-dvi}, @samp{make install-ps},
7853 @samp{make install-pdf} and @samp{make install-html} explicitly.
7854 @samp{make uninstall} will remove everything: the Texinfo
7855 documentation installed by default as well as all the above optional
7858 All these targets can be extended using @samp{-local} rules
7859 (@pxref{Extending}).
7861 @cindex Texinfo flag, @code{VERSION}
7862 @cindex Texinfo flag, @code{UPDATED}
7863 @cindex Texinfo flag, @code{EDITION}
7864 @cindex Texinfo flag, @code{UPDATED-MONTH}
7866 @cindex @code{VERSION} Texinfo flag
7867 @cindex @code{UPDATED} Texinfo flag
7868 @cindex @code{EDITION} Texinfo flag
7869 @cindex @code{UPDATED-MONTH} Texinfo flag
7871 @cindex @file{mdate-sh}
7873 If the @file{.texi} file @code{@@include}s @file{version.texi}, then
7874 that file will be automatically generated. The file @file{version.texi}
7875 defines four Texinfo flag you can reference using
7876 @code{@@value@{EDITION@}}, @code{@@value@{VERSION@}},
7877 @code{@@value@{UPDATED@}}, and @code{@@value@{UPDATED-MONTH@}}.
7882 Both of these flags hold the version number of your program. They are
7883 kept separate for clarity.
7886 This holds the date the primary @file{.texi} file was last modified.
7889 This holds the name of the month in which the primary @file{.texi} file
7893 The @file{version.texi} support requires the @command{mdate-sh}
7894 script; this script is supplied with Automake and automatically
7895 included when @command{automake} is invoked with the
7896 @option{--add-missing} option.
7898 If you have multiple Texinfo files, and you want to use the
7899 @file{version.texi} feature, then you have to have a separate version
7900 file for each Texinfo file. Automake will treat any include in a
7901 Texinfo file that matches @file{vers*.texi} just as an automatically
7902 generated version file.
7904 Sometimes an info file actually depends on more than one @file{.texi}
7905 file. For instance, in GNU Hello, @file{hello.texi} includes the file
7906 @file{fdl.texi}. You can tell Automake about these dependencies using
7907 the @code{@var{texi}_TEXINFOS} variable. Here is how GNU Hello does it:
7912 info_TEXINFOS = hello.texi
7913 hello_TEXINFOS = fdl.texi
7916 @cindex @file{texinfo.tex}
7918 By default, Automake requires the file @file{texinfo.tex} to appear in
7919 the same directory as the @file{Makefile.am} file that lists the
7920 @file{.texi} files. If you used @code{AC_CONFIG_AUX_DIR} in
7921 @file{configure.ac} (@pxref{Input, , Finding `configure' Input,
7922 autoconf, The Autoconf Manual}), then @file{texinfo.tex} is looked for
7923 there. In both cases, @command{automake} then supplies @file{texinfo.tex} if
7924 @option{--add-missing} is given, and takes care of its distribution.
7925 However, if you set the @code{TEXINFO_TEX} variable (see below),
7926 it overrides the location of the file and turns off its installation
7927 into the source as well as its distribution.
7929 The option @option{no-texinfo.tex} can be used to eliminate the
7930 requirement for the file @file{texinfo.tex}. Use of the variable
7931 @code{TEXINFO_TEX} is preferable, however, because that allows the
7932 @code{dvi}, @code{ps}, and @code{pdf} targets to still work.
7934 @cindex Option, @code{no-installinfo}
7935 @cindex Target, @code{install-info}
7936 @cindex @code{install-info} target
7937 @cindex @code{no-installinfo} option
7939 @opindex no-installinfo
7940 @trindex install-info
7942 Automake generates an @code{install-info} rule; some people apparently
7943 use this. By default, info pages are installed by @samp{make
7944 install}, so running @code{make install-info} is pointless. This can
7945 be prevented via the @code{no-installinfo} option. In this case,
7946 @file{.info} files are not installed by default, and user must
7947 request this explicitly using @samp{make install-info}.
7949 @vindex AM_UPDATE_INFO_DIR
7950 By default, @code{make install-info} and @code{make install-info}
7951 will try to run the @command{install-info} program (if available)
7952 to update (or create) the @file{@code{$@{infodir@}}/dir} index.
7953 If this is undesired, it can be prevented by exporting the
7954 @code{AM_UPDATE_INFO_DIR} variable to "@code{no}".
7956 The following variables are used by the Texinfo build rules.
7960 The name of the program invoked to build @file{.info} files. This
7961 variable is defined by Automake. If the @command{makeinfo} program is
7962 found on the system then it will be used by default; otherwise
7963 @command{missing} will be used instead.
7966 The command invoked to build @file{.html} files. Automake
7967 defines this to @samp{$(MAKEINFO) --html}.
7970 User flags passed to each invocation of @samp{$(MAKEINFO)} and
7971 @samp{$(MAKEINFOHTML)}. This user variable (@pxref{User Variables}) is
7972 not expected to be defined in any @file{Makefile}; it can be used by
7973 users to pass extra flags to suit their needs.
7975 @item AM_MAKEINFOFLAGS
7976 @itemx AM_MAKEINFOHTMLFLAGS
7977 Maintainer flags passed to each @command{makeinfo} invocation. Unlike
7978 @code{MAKEINFOFLAGS}, these variables are meant to be defined by
7979 maintainers in @file{Makefile.am}. @samp{$(AM_MAKEINFOFLAGS)} is
7980 passed to @code{makeinfo} when building @file{.info} files; and
7981 @samp{$(AM_MAKEINFOHTMLFLAGS)} is used when building @file{.html}
7984 @c Keep in sync with txinfo21.sh
7985 For instance, the following setting can be used to obtain one single
7986 @file{.html} file per manual, without node separators.
7988 AM_MAKEINFOHTMLFLAGS = --no-headers --no-split
7991 @code{AM_MAKEINFOHTMLFLAGS} defaults to @samp{$(AM_MAKEINFOFLAGS)}.
7992 This means that defining @code{AM_MAKEINFOFLAGS} without defining
7993 @code{AM_MAKEINFOHTMLFLAGS} will impact builds of both @file{.info}
7994 and @file{.html} files.
7997 The name of the command that converts a @file{.texi} file into a
7998 @file{.dvi} file. This defaults to @samp{texi2dvi}, a script that ships
7999 with the Texinfo package.
8002 The name of the command that translates a @file{.texi} file into a
8003 @file{.pdf} file. This defaults to @samp{$(TEXI2DVI) --pdf --batch}.
8006 The name of the command that builds a @file{.ps} file out of a
8007 @file{.dvi} file. This defaults to @samp{dvips}.
8011 If your package has Texinfo files in many directories, you can use the
8012 variable @code{TEXINFO_TEX} to tell Automake where to find the canonical
8013 @file{texinfo.tex} for your package. The value of this variable should
8014 be the relative path from the current @file{Makefile.am} to
8018 TEXINFO_TEX = ../doc/texinfo.tex
8026 @cindex @code{_MANS} primary, defined
8027 @cindex @code{MANS} primary, defined
8028 @cindex Primary variable, @code{MANS}
8032 A package can also include man pages (but see the GNU standards on this
8033 matter, @ref{Man Pages, , , standards, The GNU Coding Standards}.) Man
8034 pages are declared using the @code{MANS} primary. Generally the
8035 @code{man_MANS} variable is used. Man pages are automatically installed in
8036 the correct subdirectory of @code{mandir}, based on the file extension.
8038 File extensions such as @file{.1c} are handled by looking for the valid
8039 part of the extension and using that to determine the correct
8040 subdirectory of @code{mandir}. Valid section names are the digits
8041 @samp{0} through @samp{9}, and the letters @samp{l} and @samp{n}.
8043 Sometimes developers prefer to name a man page something like
8044 @file{foo.man} in the source, and then rename it to have the correct
8045 suffix, for example @file{foo.1}, when installing the file. Automake
8046 also supports this mode. For a valid section named @var{section},
8047 there is a corresponding directory named @samp{man@var{section}dir},
8048 and a corresponding @code{_MANS} variable. Files listed in such a
8049 variable are installed in the indicated section. If the file already
8050 has a valid suffix, then it is installed as-is; otherwise the file
8051 suffix is changed to match the section.
8053 For instance, consider this example:
8055 man1_MANS = rename.man thesame.1 alsothesame.1c
8059 In this case, @file{rename.man} will be renamed to @file{rename.1} when
8060 installed, but the other files will keep their names.
8062 @cindex Target, @code{install-man}
8063 @cindex Option, @option{no-installman}
8064 @cindex @code{install-man} target
8065 @cindex @option{no-installman} option
8066 @opindex no-installman
8067 @trindex install-man
8069 By default, man pages are installed by @samp{make install}. However,
8070 since the GNU project does not require man pages, many maintainers do
8071 not expend effort to keep the man pages up to date. In these cases, the
8072 @option{no-installman} option will prevent the man pages from being
8073 installed by default. The user can still explicitly install them via
8074 @samp{make install-man}.
8076 For fast installation, with many files it is preferable to use
8077 @samp{man@var{section}_MANS} over @samp{man_MANS} as well as files that
8078 do not need to be renamed.
8080 Man pages are not currently considered to be source, because it is not
8081 uncommon for man pages to be automatically generated. Therefore they
8082 are not automatically included in the distribution. However, this can
8083 be changed by use of the @code{dist_} prefix. For instance here is
8084 how to distribute and install the two man pages of GNU @command{cpio}
8085 (which includes both Texinfo documentation and man pages):
8088 dist_man_MANS = cpio.1 mt.1
8091 The @code{nobase_} prefix is meaningless for man pages and is
8095 @cindex @code{notrans_} prefix
8096 @cindex Man page renaming, avoiding
8097 @cindex Avoiding man page renaming
8099 Executables and manpages may be renamed upon installation
8100 (@pxref{Renaming}). For manpages this can be avoided by use of the
8101 @code{notrans_} prefix. For instance, suppose an executable @samp{foo}
8102 allowing to access a library function @samp{foo} from the command line.
8103 The way to avoid renaming of the @file{foo.3} manpage is:
8107 notrans_man_MANS = foo.3
8110 @cindex @code{notrans_} and @code{dist_} or @code{nodist_}
8111 @cindex @code{dist_} and @code{notrans_}
8112 @cindex @code{nodist_} and @code{notrans_}
8114 @samp{notrans_} must be specified first when used in conjunction with
8115 either @samp{dist_} or @samp{nodist_} (@pxref{Fine-grained Distribution
8116 Control}). For instance:
8119 notrans_dist_man3_MANS = bar.3
8123 @chapter What Gets Installed
8125 @cindex Installation support
8126 @cindex @samp{make install} support
8128 Naturally, Automake handles the details of actually installing your
8129 program once it has been built. All files named by the various
8130 primaries are automatically installed in the appropriate places when the
8131 user runs @samp{make install}.
8134 * Basics of Installation:: What gets installed where
8135 * The Two Parts of Install:: Installing data and programs separately
8136 * Extending Installation:: Adding your own rules for installation
8137 * Staged Installs:: Installation in a temporary location
8138 * Install Rules for the User:: Useful additional rules
8141 @node Basics of Installation
8142 @section Basics of Installation
8144 A file named in a primary is installed by copying the built file into
8145 the appropriate directory. The base name of the file is used when
8149 bin_PROGRAMS = hello subdir/goodbye
8152 In this example, both @samp{hello} and @samp{goodbye} will be installed
8153 in @samp{$(bindir)}.
8155 Sometimes it is useful to avoid the basename step at install time. For
8156 instance, you might have a number of header files in subdirectories of
8157 the source tree that are laid out precisely how you want to install
8158 them. In this situation you can use the @code{nobase_} prefix to
8159 suppress the base name step. For example:
8162 nobase_include_HEADERS = stdio.h sys/types.h
8166 will install @file{stdio.h} in @samp{$(includedir)} and @file{types.h}
8167 in @samp{$(includedir)/sys}.
8169 For most file types, Automake will install multiple files at once, while
8170 avoiding command line length issues (@pxref{Length Limitations}). Since
8171 some @command{install} programs will not install the same file twice in
8172 one invocation, you may need to ensure that file lists are unique within
8173 one variable such as @samp{nobase_include_HEADERS} above.
8175 You should not rely on the order in which files listed in one variable
8176 are installed. Likewise, to cater for parallel make, you should not
8177 rely on any particular file installation order even among different
8178 file types (library dependencies are an exception here).
8181 @node The Two Parts of Install
8182 @section The Two Parts of Install
8184 Automake generates separate @code{install-data} and @code{install-exec}
8185 rules, in case the installer is installing on multiple machines that
8186 share directory structure---these targets allow the machine-independent
8187 parts to be installed only once. @code{install-exec} installs
8188 platform-dependent files, and @code{install-data} installs
8189 platform-independent files. The @code{install} target depends on both
8190 of these targets. While Automake tries to automatically segregate
8191 objects into the correct category, the @file{Makefile.am} author is, in
8192 the end, responsible for making sure this is done correctly.
8193 @trindex install-data
8194 @trindex install-exec
8196 @cindex Install, two parts of
8198 Variables using the standard directory prefixes @samp{data},
8199 @samp{info}, @samp{man}, @samp{include}, @samp{oldinclude},
8200 @samp{pkgdata}, or @samp{pkginclude} are installed by
8201 @code{install-data}.
8203 Variables using the standard directory prefixes @samp{bin},
8204 @samp{sbin}, @samp{libexec}, @samp{sysconf}, @samp{localstate},
8205 @samp{lib}, or @samp{pkglib} are installed by @code{install-exec}.
8207 For instance, @code{data_DATA} files are installed by @code{install-data},
8208 while @code{bin_PROGRAMS} files are installed by @code{install-exec}.
8210 Any variable using a user-defined directory prefix with
8211 @samp{exec} in the name (e.g.,
8212 @c Keep in sync with primary-prefix-couples-documented-valid.sh
8213 @code{myexecbin_PROGRAMS}) is installed by @code{install-exec}. All
8214 other user-defined prefixes are installed by @code{install-data}.
8216 @node Extending Installation
8217 @section Extending Installation
8219 It is possible to extend this mechanism by defining an
8220 @code{install-exec-local} or @code{install-data-local} rule. If these
8221 rules exist, they will be run at @samp{make install} time. These
8222 rules can do almost anything; care is required.
8223 @trindex install-exec-local
8224 @trindex install-data-local
8226 Automake also supports two install hooks, @code{install-exec-hook} and
8227 @code{install-data-hook}. These hooks are run after all other install
8228 rules of the appropriate type, exec or data, have completed. So, for
8229 instance, it is possible to perform post-installation modifications
8230 using an install hook. @xref{Extending}, for some examples.
8231 @cindex Install hook
8233 @node Staged Installs
8234 @section Staged Installs
8237 Automake generates support for the @code{DESTDIR} variable in all
8238 install rules. @code{DESTDIR} is used during the @samp{make install}
8239 step to relocate install objects into a staging area. Each object and
8240 path is prefixed with the value of @code{DESTDIR} before being copied
8241 into the install area. Here is an example of typical DESTDIR usage:
8244 mkdir /tmp/staging &&
8245 make DESTDIR=/tmp/staging install
8248 The @command{mkdir} command avoids a security problem if the attacker
8249 creates a symbolic link from @file{/tmp/staging} to a victim area;
8250 then @command{make} places install objects in a directory tree built under
8251 @file{/tmp/staging}. If @file{/gnu/bin/foo} and
8252 @file{/gnu/share/aclocal/foo.m4} are to be installed, the above command
8253 would install @file{/tmp/staging/gnu/bin/foo} and
8254 @file{/tmp/staging/gnu/share/aclocal/foo.m4}.
8256 This feature is commonly used to build install images and packages
8259 Support for @code{DESTDIR} is implemented by coding it directly into
8260 the install rules. If your @file{Makefile.am} uses a local install
8261 rule (e.g., @code{install-exec-local}) or an install hook, then you
8262 must write that code to respect @code{DESTDIR}.
8264 @xref{Makefile Conventions, , , standards, The GNU Coding Standards},
8265 for another usage example.
8267 @node Install Rules for the User
8268 @section Install Rules for the User
8270 Automake also generates rules for targets @code{uninstall},
8271 @code{installdirs}, and @code{install-strip}.
8273 @trindex installdirs
8274 @trindex install-strip
8276 Automake supports @code{uninstall-local} and @code{uninstall-hook}.
8277 There is no notion of separate uninstalls for ``exec'' and ``data'', as
8278 these features would not provide additional functionality.
8280 Note that @code{uninstall} is not meant as a replacement for a real
8285 @chapter What Gets Cleaned
8287 @cindex @samp{make clean} support
8289 The GNU Makefile Standards specify a number of different clean rules.
8290 @xref{Standard Targets, , Standard Targets for Users, standards,
8291 The GNU Coding Standards}.
8293 Generally the files that can be cleaned are determined automatically by
8294 Automake. Of course, Automake also recognizes some variables that can
8295 be defined to specify additional files to clean. These variables are
8296 @code{MOSTLYCLEANFILES}, @code{CLEANFILES}, @code{DISTCLEANFILES}, and
8297 @code{MAINTAINERCLEANFILES}.
8298 @vindex MOSTLYCLEANFILES
8300 @vindex DISTCLEANFILES
8301 @vindex MAINTAINERCLEANFILES
8303 @trindex mostlyclean-local
8304 @trindex clean-local
8305 @trindex distclean-local
8306 @trindex maintainer-clean-local
8307 When cleaning involves more than deleting some hard-coded list of
8308 files, it is also possible to supplement the cleaning rules with your
8309 own commands. Simply define a rule for any of the
8310 @code{mostlyclean-local}, @code{clean-local}, @code{distclean-local},
8311 or @code{maintainer-clean-local} targets (@pxref{Extending}). A common
8312 case is deleting a directory, for instance, a directory created by the
8320 Since @command{make} allows only one set of rules for a given target,
8321 a more extensible way of writing this is to use a separate target
8322 listed as a dependency:
8325 clean-local: clean-local-check
8326 .PHONY: clean-local-check
8331 As the GNU Standards aren't always explicit as to which files should
8332 be removed by which rule, we've adopted a heuristic that we believe
8333 was first formulated by Fran@,{c}ois Pinard:
8337 If @command{make} built it, and it is commonly something that one would
8338 want to rebuild (for instance, a @file{.o} file), then
8339 @code{mostlyclean} should delete it.
8342 Otherwise, if @command{make} built it, then @code{clean} should delete it.
8345 If @command{configure} built it, then @code{distclean} should delete it.
8348 If the maintainer built it (for instance, a @file{.info} file), then
8349 @code{maintainer-clean} should delete it. However
8350 @code{maintainer-clean} should not delete anything that needs to exist
8351 in order to run @samp{./configure && make}.
8354 We recommend that you follow this same set of heuristics in your
8359 @chapter What Goes in a Distribution
8362 * Basics of Distribution:: Files distributed by default
8363 * Fine-grained Distribution Control:: @code{dist_} and @code{nodist_} prefixes
8364 * The dist Hook:: A target for last-minute distribution changes
8365 * Checking the Distribution:: @samp{make distcheck} explained
8366 * The Types of Distributions:: A variety of formats and compression methods
8369 @node Basics of Distribution
8370 @section Basics of Distribution
8372 @cindex @samp{make dist}
8377 The @code{dist} rule in the generated @file{Makefile.in} can be used
8378 to generate a gzipped @code{tar} file and other flavors of archive for
8379 distribution. The file is named based on the @code{PACKAGE} and
8380 @code{VERSION} variables defined by @code{AM_INIT_AUTOMAKE}
8381 (@pxref{Macros}); more precisely the gzipped @code{tar} file is named
8382 @samp{@var{package}-@var{version}.tar.gz}.
8384 You can use the @command{make} variable @code{GZIP_ENV} to control how gzip
8385 is run. The default setting is @option{--best}.
8387 @cindex @code{m4_include}, distribution
8388 @cindex @code{include}, distribution
8391 For the most part, the files to distribute are automatically found by
8392 Automake: all source files are automatically included in a distribution,
8393 as are all @file{Makefile.am} and @file{Makefile.in} files. Automake also
8394 has a built-in list of commonly used files that are automatically
8395 included if they are found in the current directory (either physically,
8396 or as the target of a @file{Makefile.am} rule); this list is printed by
8397 @samp{automake --help}. Note that some files in this list are actually
8398 distributed only if other certain conditions hold (for example,
8399 @c Keep in sync with autodist-config-headers.sh
8400 the @file{config.h.top} and @file{config.h.bot} files are automatically
8401 distributed only if, e.g., @samp{AC_CONFIG_HEADERS([config.h])} is used
8402 in @file{configure.ac}). Also, files that are read by @command{configure}
8403 (i.e.@: the source files corresponding to the files specified in various
8404 Autoconf macros such as @code{AC_CONFIG_FILES} and siblings) are
8405 automatically distributed. Files included in a @file{Makefile.am} (using
8406 @code{include}) or in @file{configure.ac} (using @code{m4_include}), and
8407 helper scripts installed with @samp{automake --add-missing} are also
8411 Still, sometimes there are files that must be distributed, but which
8412 are not covered in the automatic rules. These files should be listed in
8413 the @code{EXTRA_DIST} variable. You can mention files from
8414 subdirectories in @code{EXTRA_DIST}.
8416 You can also mention a directory in @code{EXTRA_DIST}; in this case the
8417 entire directory will be recursively copied into the distribution.
8418 Please note that this will also copy @emph{everything} in the directory,
8419 including, e.g., Subversion's @file{.svn} private directories or CVS/RCS
8420 version control files. We recommend against using this feature.
8423 @vindex DIST_SUBDIRS
8424 If you define @code{SUBDIRS}, Automake will recursively include the
8425 subdirectories in the distribution. If @code{SUBDIRS} is defined
8426 conditionally (@pxref{Conditionals}), Automake will normally include
8427 all directories that could possibly appear in @code{SUBDIRS} in the
8428 distribution. If you need to specify the set of directories
8429 conditionally, you can set the variable @code{DIST_SUBDIRS} to the
8430 exact list of subdirectories to include in the distribution
8431 (@pxref{Conditional Subdirectories}).
8434 @node Fine-grained Distribution Control
8435 @section Fine-grained Distribution Control
8439 Sometimes you need tighter control over what does @emph{not} go into the
8440 distribution; for instance, you might have source files that are
8441 generated and that you do not want to distribute. In this case
8442 Automake gives fine-grained control using the @code{dist} and
8443 @code{nodist} prefixes. Any primary or @code{_SOURCES} variable can be
8444 prefixed with @code{dist_} to add the listed files to the distribution.
8445 Similarly, @code{nodist_} can be used to omit the files from the
8448 As an example, here is how you would cause some data to be distributed
8449 while leaving some source code out of the distribution:
8452 dist_data_DATA = distribute-this
8454 nodist_foo_SOURCES = do-not-distribute.c
8458 @section The dist Hook
8462 Occasionally it is useful to be able to change the distribution before
8463 it is packaged up. If the @code{dist-hook} rule exists, it is run
8464 after the distribution directory is filled, but before the actual
8465 distribution archives are created. One way to use this is for
8466 removing unnecessary files that get recursively included by specifying
8467 a directory in @code{EXTRA_DIST}:
8472 rm -rf `find $(distdir)/doc -type d -name .svn`
8475 @c The caveates described here should be documented in 'disthook.test'.
8477 Note that the @code{dist-hook} recipe shouldn't assume that the regular
8478 files in the distribution directory are writable; this might not be the
8479 case if one is packaging from a read-only source tree, or when a
8480 @code{make distcheck} is being done. For similar reasons, the recipe
8481 shouldn't assume that the subdirectories put into the distribution
8482 directory as effect of having them listed in @code{EXTRA_DIST} are
8483 writable. So, if the @code{dist-hook} recipe wants to modify the
8484 content of an existing file (or @code{EXTRA_DIST} subdirectory) in the
8485 distribution directory, it should explicitly to make it writable first:
8488 EXTRA_DIST = README doc
8490 chmod u+w $(distdir)/README $(distdir)/doc
8491 echo "Distribution date: `date`" >> README
8492 rm -f $(distdir)/doc/HACKING
8497 Two variables that come handy when writing @code{dist-hook} rules are
8498 @samp{$(distdir)} and @samp{$(top_distdir)}.
8500 @samp{$(distdir)} points to the directory where the @code{dist} rule
8501 will copy files from the current directory before creating the
8502 tarball. If you are at the top-level directory, then @samp{distdir =
8503 $(PACKAGE)-$(VERSION)}. When used from subdirectory named
8504 @file{foo/}, then @samp{distdir = ../$(PACKAGE)-$(VERSION)/foo}.
8505 @samp{$(distdir)} can be a relative or absolute path, do not assume
8508 @samp{$(top_distdir)} always points to the root directory of the
8509 distributed tree. At the top-level it's equal to @samp{$(distdir)}.
8510 In the @file{foo/} subdirectory
8511 @samp{top_distdir = ../$(PACKAGE)-$(VERSION)}.
8512 @samp{$(top_distdir)} too can be a relative or absolute path.
8514 Note that when packages are nested using @code{AC_CONFIG_SUBDIRS}
8515 (@pxref{Subpackages}), then @samp{$(distdir)} and
8516 @samp{$(top_distdir)} are relative to the package where @samp{make
8517 dist} was run, not to any sub-packages involved.
8519 @node Checking the Distribution
8520 @section Checking the Distribution
8522 @cindex @samp{make distcheck}
8524 Automake also generates a @code{distcheck} rule that can be of help
8525 to ensure that a given distribution will actually work. Simplifying
8526 a bit, we can say this rule first makes a distribution, and then,
8527 @emph{operating from it}, takes the following steps:
8530 tries to do a @code{VPATH} build (@pxref{VPATH Builds}), with the
8531 @code{srcdir} and all its content made @emph{read-only};
8533 runs the test suite (with @command{make check}) on this fresh build;
8535 installs the package in a temporary directory (with @command{make
8536 install}), and tries runs the test suite on the resulting installation
8537 (with @command{make installcheck});
8539 checks that the package can be correctly uninstalled (by @command{make
8540 uninstall}) and cleaned (by @code{make distclean});
8542 finally, makes another tarball to ensure the distribution is
8546 @vindex AM_DISTCHECK_CONFIGURE_FLAGS
8547 @vindex DISTCHECK_CONFIGURE_FLAGS
8548 @subheading DISTCHECK_CONFIGURE_FLAGS
8549 Building the package involves running @samp{./configure}. If you need
8550 to supply additional flags to @command{configure}, define them in the
8551 @code{AM_DISTCHECK_CONFIGURE_FLAGS} variable in your top-level
8552 @file{Makefile.am}. The user can still extend or override the flags
8553 provided there by defining the @code{DISTCHECK_CONFIGURE_FLAGS} variable,
8554 on the command line when invoking @command{make}.
8556 Still, developers are encouraged to strive to make their code buildable
8557 without requiring any special configure option; thus, in general, you
8558 shouldn't define @code{AM_DISTCHECK_CONFIGURE_FLAGS}. However, there
8559 might be few scenarios in which the use of this variable is justified.
8560 GNU @command{m4} offers an example. GNU @command{m4} configures by
8561 default with its experimental and seldom used "changeword" feature
8562 disabled; so in its case it is useful to have @command{make distcheck}
8563 run configure with the @option{--with-changeword} option, to ensure that
8564 the code for changeword support still compiles correctly.
8565 GNU @command{m4} also employs the @code{AM_DISTCHECK_CONFIGURE_FLAGS}
8566 variable to stress-test the use of @option{--program-prefix=g}, since at
8567 one point the @command{m4} build system had a bug where @command{make
8568 installcheck} was wrongly assuming it could blindly test "@command{m4}",
8569 rather than the just-installed "@command{gm4}".
8571 @trindex distcheck-hook
8572 @subheading distcheck-hook
8573 If the @code{distcheck-hook} rule is defined in your top-level
8574 @file{Makefile.am}, then it will be invoked by @code{distcheck} after
8575 the new distribution has been unpacked, but before the unpacked copy
8576 is configured and built. Your @code{distcheck-hook} can do almost
8577 anything, though as always caution is advised. Generally this hook is
8578 used to check for potential distribution errors not caught by the
8579 standard mechanism. Note that @code{distcheck-hook} as well as
8580 @code{AM_DISTCHECK_CONFIGURE_FLAGS} and @code{DISTCHECK_CONFIGURE_FLAGS}
8581 are not honored in a subpackage @file{Makefile.am}, but the flags from
8582 @code{AM_DISTCHECK_CONFIGURE_FLAGS} and @code{DISTCHECK_CONFIGURE_FLAGS}
8583 are passed down to the @command{configure} script of the subpackage.
8585 @cindex @samp{make distcleancheck}
8586 @trindex distcleancheck
8587 @vindex DISTCLEANFILES
8588 @vindex distcleancheck_listfiles
8590 @subheading distcleancheck
8591 Speaking of potential distribution errors, @code{distcheck} also
8592 ensures that the @code{distclean} rule actually removes all built
8593 files. This is done by running @samp{make distcleancheck} at the end of
8594 the @code{VPATH} build. By default, @code{distcleancheck} will run
8595 @code{distclean} and then make sure the build tree has been emptied by
8596 running @samp{$(distcleancheck_listfiles)}. Usually this check will
8597 find generated files that you forgot to add to the @code{DISTCLEANFILES}
8598 variable (@pxref{Clean}).
8600 The @code{distcleancheck} behavior should be OK for most packages,
8601 otherwise you have the possibility to override the definition of
8602 either the @code{distcleancheck} rule, or the
8603 @samp{$(distcleancheck_listfiles)} variable. For instance, to disable
8604 @code{distcleancheck} completely, add the following rule to your
8605 top-level @file{Makefile.am}:
8612 If you want @code{distcleancheck} to ignore built files that have not
8613 been cleaned because they are also part of the distribution, add the
8614 following definition instead:
8616 @c Keep in sync with distcleancheck.sh
8618 distcleancheck_listfiles = \
8619 find . -type f -exec sh -c 'test -f $(srcdir)/$$1 || echo $$1' \
8623 The above definition is not the default because it's usually an error if
8624 your Makefiles cause some distributed files to be rebuilt when the user
8625 build the package. (Think about the user missing the tool required to
8626 build the file; or if the required tool is built by your package,
8627 consider the cross-compilation case where it can't be run.) There is
8628 an entry in the FAQ about this (@pxref{Errors with distclean}), make
8629 sure you read it before playing with @code{distcleancheck_listfiles}.
8631 @cindex @samp{make distuninstallcheck}
8632 @trindex distuninstallcheck
8633 @vindex distuninstallcheck_listfiles
8635 @subheading distuninstallcheck
8636 @code{distcheck} also checks that the @code{uninstall} rule works
8637 properly, both for ordinary and @code{DESTDIR} builds. It does this
8638 by invoking @samp{make uninstall}, and then it checks the install tree
8639 to see if any files are left over. This check will make sure that you
8640 correctly coded your @code{uninstall}-related rules.
8642 By default, the checking is done by the @code{distuninstallcheck} rule,
8643 and the list of files in the install tree is generated by
8644 @samp{$(distuninstallcheck_listfiles)} (this is a variable whose value is
8645 a shell command to run that prints the list of files to stdout).
8647 Either of these can be overridden to modify the behavior of
8648 @code{distcheck}. For instance, to disable this check completely, you
8656 @node The Types of Distributions
8657 @section The Types of Distributions
8659 Automake generates rules to provide archives of the project for
8660 distributions in various formats. Their targets are:
8664 @item @code{dist-bzip2}
8665 Generate a bzip2 tar archive of the distribution. bzip2 archives are
8666 frequently smaller than gzipped archives.
8667 By default, this rule makes @samp{bzip2} use a compression option of @option{-9}.
8668 To make it use a different one, set the @env{BZIP2} environment variable.
8669 For example, @samp{make dist-bzip2 BZIP2=-7}.
8672 @item @code{dist-gzip}
8673 Generate a gzip tar archive of the distribution.
8676 @item @code{dist-lzip}
8677 Generate an @samp{lzip} tar archive of the distribution. @command{lzip}
8678 archives are frequently smaller than @command{bzip2}-compressed archives.
8681 @item @code{dist-shar}
8682 Generate a shar archive of the distribution.
8686 @item @code{dist-xz}
8687 Generate an @samp{xz} tar archive of the distribution. @command{xz}
8688 archives are frequently smaller than @command{bzip2}-compressed archives.
8689 By default, this rule makes @samp{xz} use a compression option of
8690 @option{-e}. To make it use a different one, set the @env{XZ_OPT}
8691 environment variable. For example, run this command to use the
8692 default compression ratio, but with a progress indicator:
8693 @samp{make dist-xz XZ_OPT=-7e}.
8696 @item @code{dist-zip}
8697 Generate a zip archive of the distribution.
8700 @item @code{dist-tarZ}
8701 Generate a compressed tar archive of
8706 The rule @code{dist} (and its historical synonym @code{dist-all}) will
8707 create archives in all the enabled formats, @ref{Options}. By
8708 default, only the @code{dist-gzip} target is hooked to @code{dist}.
8712 @chapter Support for test suites
8715 @cindex @code{make check}
8718 Automake can generate code to handle two kinds of test suites. One is
8719 based on integration with the @command{dejagnu} framework. The other
8720 (and most used) form is based on the use of generic test scripts, and
8721 its activation is triggered by the definition of the special @code{TESTS}
8722 variable. This second form allows for various degrees of sophistication
8723 and customization; in particular, it allows for concurrent execution
8724 of test scripts, use of established test protocols such as TAP, and
8725 definition of custom test drivers and test runners.
8728 In either case, the testsuite is invoked via @samp{make check}.
8731 * Generalities about Testing:: Concepts and terminology about testing
8732 * Simple Tests:: Listing test scripts in @code{TESTS}
8733 * Custom Test Drivers:: Writing and using custom test drivers
8734 * Using the TAP test protocol:: Integrating test scripts that use the TAP protocol
8735 * DejaGnu Tests:: Interfacing with the @command{dejagnu} testing framework
8736 * Install Tests:: Running tests on installed packages
8739 @node Generalities about Testing
8740 @section Generalities about Testing
8742 The purpose of testing is to determine whether a program or system behaves
8743 as expected (e.g., known inputs produce the expected outputs, error
8744 conditions are correctly handled or reported, and older bugs do not
8748 The minimal unit of testing is usually called @emph{test case}, or simply
8749 @emph{test}. How a test case is defined or delimited, and even what
8750 exactly @emph{constitutes} a test case, depends heavily on the testing
8751 paradigm and/or framework in use, so we won't attempt any more precise
8752 definition. The set of the test cases for a given program or system
8753 constitutes its @emph{testsuite}.
8755 @cindex test harness
8756 @cindex testsuite harness
8757 A @emph{test harness} (also @emph{testsuite harness}) is a program or
8758 software component that executes all (or part of) the defined test cases,
8759 analyzes their outcomes, and report or register these outcomes
8760 appropriately. Again, the details of how this is accomplished (and how
8761 the developer and user can influence it or interface with it) varies
8762 wildly, and we'll attempt no precise definition.
8765 @cindex test failure
8766 A test is said to @emph{pass} when it can determine that the condition or
8767 behaviour it means to verify holds, and is said to @emph{fail} when it can
8768 determine that such condition of behaviour does @emph{not} hold.
8771 Sometimes, tests can rely on non-portable tools or prerequisites, or
8772 simply make no sense on a given system (for example, a test checking a
8773 Windows-specific feature makes no sense on a GNU/Linux system). In this
8774 case, accordingly to the definition above, the tests can neither be
8775 considered passed nor failed; instead, they are @emph{skipped} -- i.e.,
8776 they are not run, or their result is anyway ignored for what concerns
8777 the count of failures an successes. Skips are usually explicitly
8778 reported though, so that the user will be aware that not all of the
8779 testsuite has really run.
8782 @cindex expected failure
8783 @cindex expected test failure
8785 @cindex unexpected pass
8786 @cindex unexpected test pass
8787 It's not uncommon, especially during early development stages, that some
8788 tests fail for known reasons, and that the developer doesn't want to
8789 tackle these failures immediately (this is especially true when the
8790 failing tests deal with corner cases). In this situation, the better
8791 policy is to declare that each of those failures is an @emph{expected
8792 failure} (or @emph{xfail}). In case a test that is expected to fail ends
8793 up passing instead, many testing environments will flag the result as a
8794 special kind of failure called @emph{unexpected pass} (or @emph{xpass}).
8797 @cindex Distinction between errors and failures in testsuites
8798 Many testing environments and frameworks distinguish between test failures
8799 and hard errors. As we've seen, a test failure happens when some invariant
8800 or expected behaviour of the software under test is not met. An @emph{hard
8801 error} happens when e.g., the set-up of a test case scenario fails, or when
8802 some other unexpected or highly undesirable condition is encountered (for
8803 example, the program under test experiences a segmentation fault).
8805 @emph{TODO}: Links to other test harnesses (esp. those sharing our
8809 @section Simple Tests
8812 * Scripts-based Testsuites:: Automake-specific concepts and terminology
8813 * Serial Test Harness:: Older (and obsolescent) serial test harness
8814 * Parallel Test Harness:: Generic concurrent test harness
8817 @node Scripts-based Testsuites
8818 @subsection Scripts-based Testsuites
8820 If the special variable @code{TESTS} is defined, its value is taken to be
8821 a list of programs or scripts to run in order to do the testing. Under
8822 the appropriate circumstances, it's possible for @code{TESTS} to list
8823 also data files to be passed to one or more test scripts defined by
8824 different means (the so-called ``log compilers'', @pxref{Parallel Test
8827 Test scripts can be executed serially or concurrently. Automake
8828 supports both these kinds of test execution, with the serial test harness
8829 being the default (for backward-compatibility reasons only, as its use
8830 is nowadays discouraged). The concurrent test harness relies on the
8831 concurrence capabilities (if any) offered by the underlying @command{make}
8832 implementation, and can thus only be as good as those are.
8834 By default, only the exit statuses of the test scripts are considered when
8835 determining the testsuite outcome. But Automake allows also the use of
8836 more complex test protocols, either standard (@pxref{Using the TAP test
8837 protocol}) or custom (@pxref{Custom Test Drivers}). Note that you can
8838 enable such protocols only when the parallel harness is used: they won't
8839 work with the serial test harness. In the rest of this section we are
8840 going to concentrate mostly on protocol-less tests, since we'll have later
8841 a whole section devoted to the use of test protocols (again, @pxref{Custom
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 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 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 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 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 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{tests/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