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}
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 * Unified Parallel C Support:: Compiling Unified Parallel C sources
224 * Assembly Support:: Compiling assembly sources
225 * Fortran 77 Support:: Compiling Fortran 77 sources
226 * Fortran 9x Support:: Compiling Fortran 9x sources
227 * Java Support with gcj:: Compiling Java sources using gcj
228 * Vala Support:: Compiling Vala sources
229 * Support for Other Languages:: Compiling other languages
230 * Dependencies:: Automatic dependency tracking
231 * EXEEXT:: Support for executable extensions
235 * Program Sources:: Defining program sources
236 * Linking:: Linking with libraries or extra objects
237 * Conditional Sources:: Handling conditional sources
238 * Conditional Programs:: Building a program conditionally
240 Building a Shared Library
242 * Libtool Concept:: Introducing Libtool
243 * Libtool Libraries:: Declaring Libtool Libraries
244 * Conditional Libtool Libraries:: Building Libtool Libraries Conditionally
245 * Conditional Libtool Sources:: Choosing Library Sources Conditionally
246 * Libtool Convenience Libraries:: Building Convenience Libtool Libraries
247 * Libtool Modules:: Building Libtool Modules
248 * Libtool Flags:: Using _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS
249 * LTLIBOBJS:: Using $(LTLIBOBJS) and $(LTALLOCA)
250 * Libtool Issues:: Common Issues Related to Libtool's Use
252 Common Issues Related to Libtool's Use
254 * Error required file ltmain.sh not found:: The need to run libtoolize
255 * Objects created both with libtool and without:: Avoid a specific build race
259 * Preprocessing Fortran 77:: Preprocessing Fortran 77 sources
260 * Compiling Fortran 77 Files:: Compiling Fortran 77 sources
261 * Mixing Fortran 77 With C and C++:: Mixing Fortran 77 With C and C++
263 Mixing Fortran 77 With C and C++
265 * How the Linker is Chosen:: Automatic linker selection
269 * Compiling Fortran 9x Files:: Compiling Fortran 9x sources
271 Other Derived Objects
273 * Scripts:: Executable scripts
274 * Headers:: Header files
275 * Data:: Architecture-independent data files
276 * Sources:: Derived sources
280 * Built Sources Example:: Several ways to handle built sources.
284 * Emacs Lisp:: Emacs Lisp
287 * Java:: Java bytecode compilation (deprecated)
290 Building documentation
293 * Man Pages:: Man pages
297 * Basics of Installation:: What gets installed where
298 * The Two Parts of Install:: Installing data and programs separately
299 * Extending Installation:: Adding your own rules for installation
300 * Staged Installs:: Installation in a temporary location
301 * Install Rules for the User:: Useful additional rules
303 What Goes in a Distribution
305 * Basics of Distribution:: Files distributed by default
306 * Fine-grained Distribution Control:: @code{dist_} and @code{nodist_} prefixes
307 * The dist Hook:: A target for last-minute distribution changes
308 * Checking the Distribution:: @samp{make distcheck} explained
309 * The Types of Distributions:: A variety of formats and compression methods
311 Support for test suites
313 * Generalities about Testing:: Generic concepts and terminology about testing
314 * Simple Tests:: Listing test scripts in @code{TESTS}
315 * Custom Test Drivers:: Writing and using custom test drivers
316 * Using the TAP test protocol:: Integrating test scripts that use the TAP protocol
317 * DejaGnu Tests:: Interfacing with the @command{dejagnu} testing framework
318 * Install Tests:: Running tests on installed packages
322 * Scripts-based Testsuites:: Automake-specific concepts and terminology
323 * Serial Test Harness:: Older (and obsolescent) serial test harness
324 * Parallel Test Harness:: Generic concurrent test harness
326 Using the TAP test protocol
328 * Introduction to TAP::
329 * Use TAP with the Automake test harness::
330 * Incompatibilities with other TAP parsers and drivers::
331 * Links and external resources on TAP::
335 * Overview of Custom Test Drivers Support::
336 * Declaring Custom Test Drivers::
337 * API for Custom Test Drivers::
339 API for Custom Test Drivers
341 * Command-line arguments for test drivers::
342 * Log files generation and test results recording::
343 * Testsuite progress output::
345 Changing Automake's Behavior
347 * Options generalities:: Semantics of Automake option
348 * List of Automake options:: A comprehensive list of Automake options
352 * Tags:: Interfacing to cscope, etags and mkid
353 * Suffixes:: Handling new file extensions
357 * Usage of Conditionals:: Declaring conditional content
358 * Limits of Conditionals:: Enclosing complete statements
362 * Make verbosity:: Make is verbose by default
363 * Tricks For Silencing Make:: Standard and generic ways to silence make
364 * Automake silent-rules Option:: How Automake can help in silencing make
366 When Automake Isn't Enough
368 * Extending:: Adding new rules or overriding existing ones.
369 * Third-Party Makefiles:: Integrating Non-Automake @file{Makefile}s.
371 Frequently Asked Questions about Automake
373 * CVS:: CVS and generated files
374 * maintainer-mode:: missing and AM_MAINTAINER_MODE
375 * Wildcards:: Why doesn't Automake support wildcards?
376 * Limitations on File Names:: Limitations on source and installed file names
377 * Errors with distclean:: Files left in build directory after distclean
378 * Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS
379 * Renamed Objects:: Why are object files sometimes renamed?
380 * Per-Object Flags:: How to simulate per-object flags?
381 * Multiple Outputs:: Writing rules for tools with many output files
382 * Hard-Coded Install Paths:: Installing to hard-coded locations
383 * Debugging Make Rules:: Strategies when things don't work as expected
384 * Reporting Bugs:: Feedback on bugs and feature requests
388 * GNU Free Documentation License:: License for copying this manual
392 * Macro Index:: Index of Autoconf macros
393 * Variable Index:: Index of Makefile variables
394 * General Index:: General index
403 @chapter Introduction
405 Automake is a tool for automatically generating @file{Makefile.in}s
406 from files called @file{Makefile.am}. Each @file{Makefile.am} is
407 basically a series of @command{make} variable
408 definitions@footnote{These variables are also called @dfn{make macros}
409 in Make terminology, however in this manual we reserve the term
410 @dfn{macro} for Autoconf's macros.}, with rules being thrown in
411 occasionally. The generated @file{Makefile.in}s are compliant with
412 the GNU Makefile standards.
414 @cindex GNU Makefile standards
416 The GNU Makefile Standards Document
417 (@pxref{Makefile Conventions, , , standards, The GNU Coding Standards})
418 is long, complicated, and subject to change. The goal of Automake is to
419 remove the burden of Makefile maintenance from the back of the
420 individual GNU maintainer (and put it on the back of the Automake
423 The typical Automake input file is simply a series of variable definitions.
424 Each such file is processed to create a @file{Makefile.in}. There
425 should generally be one @file{Makefile.am} per directory of a project.
427 @cindex Constraints of Automake
428 @cindex Automake constraints
430 Automake does constrain a project in certain ways; for instance, it
431 assumes that the project uses Autoconf (@pxref{Top, , Introduction,
432 autoconf, The Autoconf Manual}), and enforces certain restrictions on
433 the @file{configure.ac} contents@footnote{Older Autoconf versions used
434 @file{configure.in}. Autoconf 2.50 and greater promotes
435 @file{configure.ac} over @file{configure.in}. The rest of this
436 documentation will refer to @file{configure.ac}, but Automake also
437 supports @file{configure.in} for backward compatibility.}.
439 @cindex Automake requirements
440 @cindex Requirements, Automake
442 Automake requires @command{perl} in order to generate the
443 @file{Makefile.in}s. However, the distributions created by Automake are
444 fully GNU standards-compliant, and do not require @command{perl} in order
447 @cindex Bugs, reporting
448 @cindex Reporting bugs
449 @cindex E-mail, bug reports
451 For more information on bug reports, @xref{Reporting Bugs}.
453 @node Autotools Introduction
454 @chapter An Introduction to the Autotools
456 If you are new to Automake, maybe you know that it is part of a set of
457 tools called @emph{The Autotools}. Maybe you've already delved into a
458 package full of files named @file{configure}, @file{configure.ac},
459 @file{Makefile.in}, @file{Makefile.am}, @file{aclocal.m4}, @dots{},
460 some of them claiming to be @emph{generated by} Autoconf or Automake.
461 But the exact purpose of these files and their relations is probably
462 fuzzy. The goal of this chapter is to introduce you to this machinery,
463 to show you how it works and how powerful it is. If you've never
464 installed or seen such a package, do not worry: this chapter will walk
467 If you need some teaching material, more illustrations, or a less
468 @command{automake}-centered continuation, some slides for this
469 introduction are available in Alexandre Duret-Lutz's
470 @uref{http://www.lrde.epita.fr/@/~adl/@/autotools.html,
472 This chapter is the written version of the first part of his tutorial.
475 * GNU Build System:: Introducing the GNU Build System
476 * Use Cases:: Use Cases for the GNU Build System
477 * Why Autotools:: How Autotools Help
478 * Hello World:: A Small Hello World Package
481 @node GNU Build System
482 @section Introducing the GNU Build System
483 @cindex GNU Build System, introduction
485 It is a truth universally acknowledged, that as a developer in
486 possession of a new package, you must be in want of a build system.
488 In the Unix world, such a build system is traditionally achieved using
489 the command @command{make} (@pxref{Top, , Overview, make, The GNU Make
490 Manual}). You express the recipe to build your package in a
491 @file{Makefile}. This file is a set of rules to build the files in
492 the package. For instance the program @file{prog} may be built by
493 running the linker on the files @file{main.o}, @file{foo.o}, and
494 @file{bar.o}; the file @file{main.o} may be built by running the
495 compiler on @file{main.c}; etc. Each time @command{make} is run, it
496 reads @file{Makefile}, checks the existence and modification time of
497 the files mentioned, decides what files need to be built (or rebuilt),
498 and runs the associated commands.
500 When a package needs to be built on a different platform than the one
501 it was developed on, its @file{Makefile} usually needs to be adjusted.
502 For instance the compiler may have another name or require more
503 options. In 1991, David J. MacKenzie got tired of customizing
504 @file{Makefile} for the 20 platforms he had to deal with. Instead, he
505 handcrafted a little shell script called @file{configure} to
506 automatically adjust the @file{Makefile} (@pxref{Genesis, , Genesis,
507 autoconf, The Autoconf Manual}). Compiling his package was now
508 as simple as running @code{./configure && make}.
510 @cindex GNU Coding Standards
512 Today this process has been standardized in the GNU project. The GNU
513 Coding Standards (@pxref{Managing Releases, The Release Process, ,
514 standards, The GNU Coding Standards}) explains how each package of the
515 GNU project should have a @file{configure} script, and the minimal
516 interface it should have. The @file{Makefile} too should follow some
517 established conventions. The result? A unified build system that
518 makes all packages almost indistinguishable by the installer. In its
519 simplest scenario, all the installer has to do is to unpack the
520 package, run @code{./configure && make && make install}, and repeat
521 with the next package to install.
523 We call this build system the @dfn{GNU Build System}, since it was
524 grown out of the GNU project. However it is used by a vast number of
525 other packages: following any existing convention has its advantages.
527 @cindex Autotools, introduction
529 The Autotools are tools that will create a GNU Build System for your
530 package. Autoconf mostly focuses on @file{configure} and Automake on
531 @file{Makefile}s. It is entirely possible to create a GNU Build
532 System without the help of these tools. However it is rather
533 burdensome and error-prone. We will discuss this again after some
534 illustration of the GNU Build System in action.
537 @section Use Cases for the GNU Build System
538 @cindex GNU Build System, use cases
539 @cindex GNU Build System, features
540 @cindex Features of the GNU Build System
541 @cindex Use Cases for the GNU Build System
542 @cindex @file{amhello-1.0.tar.gz}, location
543 @cindex @file{amhello-1.0.tar.gz}, use cases
545 In this section we explore several use cases for the GNU Build System.
546 You can replay all these examples on the @file{amhello-1.0.tar.gz}
547 package distributed with Automake. If Automake is installed on your
548 system, you should find a copy of this file in
549 @file{@var{prefix}/share/doc/automake/amhello-1.0.tar.gz}, where
550 @var{prefix} is the installation prefix specified during configuration
551 (@var{prefix} defaults to @file{/usr/local}, however if Automake was
552 installed by some GNU/Linux distribution it most likely has been set
553 to @file{/usr}). If you do not have a copy of Automake installed,
554 you can find a copy of this file inside the @file{doc/} directory of
555 the Automake package.
557 Some of the following use cases present features that are in fact
558 extensions to the GNU Build System. Read: they are not specified by
559 the GNU Coding Standards, but they are nonetheless part of the build
560 system created by the Autotools. To keep things simple, we do not
561 point out the difference. Our objective is to show you many of the
562 features that the build system created by the Autotools will offer to
566 * Basic Installation:: Common installation procedure
567 * Standard Targets:: A list of standard Makefile targets
568 * Standard Directory Variables:: A list of standard directory variables
569 * Standard Configuration Variables:: Using configuration variables
570 * config.site:: Using a config.site file
571 * VPATH Builds:: Parallel build trees
572 * Two-Part Install:: Installing data and programs separately
573 * Cross-Compilation:: Building for other architectures
574 * Renaming:: Renaming programs at install time
575 * DESTDIR:: Building binary packages with DESTDIR
576 * Preparing Distributions:: Rolling out tarballs
577 * Dependency Tracking:: Automatic dependency tracking
578 * Nested Packages:: The GNU Build Systems can be nested
581 @node Basic Installation
582 @subsection Basic Installation
583 @cindex Configuration, basics
584 @cindex Installation, basics
585 @cindex GNU Build System, basics
587 The most common installation procedure looks as follows.
590 ~ % @kbd{tar zxf amhello-1.0.tar.gz}
591 ~ % @kbd{cd amhello-1.0}
592 ~/amhello-1.0 % @kbd{./configure}
594 config.status: creating Makefile
595 config.status: creating src/Makefile
597 ~/amhello-1.0 % @kbd{make}
599 ~/amhello-1.0 % @kbd{make check}
601 ~/amhello-1.0 % @kbd{su}
603 /home/adl/amhello-1.0 # @kbd{make install}
605 /home/adl/amhello-1.0 # @kbd{exit}
606 ~/amhello-1.0 % @kbd{make installcheck}
612 The user first unpacks the package. Here, and in the following
613 examples, we will use the non-portable @code{tar zxf} command for
614 simplicity. On a system without GNU @command{tar} installed, this
615 command should read @code{gunzip -c amhello-1.0.tar.gz | tar xf -}.
617 The user then enters the newly created directory to run the
618 @file{configure} script. This script probes the system for various
619 features, and finally creates the @file{Makefile}s. In this toy
620 example there are only two @file{Makefile}s, but in real-world projects,
621 there may be many more, usually one @file{Makefile} per directory.
623 It is now possible to run @code{make}. This will construct all the
624 programs, libraries, and scripts that need to be constructed for the
625 package. In our example, this compiles the @file{hello} program.
626 All files are constructed in place, in the source tree; we will see
627 later how this can be changed.
629 @code{make check} causes the package's tests to be run. This step is
630 not mandatory, but it is often good to make sure the programs that
631 have been built behave as they should, before you decide to install
632 them. Our example does not contain any tests, so running @code{make
635 @cindex su, before @code{make install}
636 After everything has been built, and maybe tested, it is time to
637 install it on the system. That means copying the programs,
638 libraries, header files, scripts, and other data files from the
639 source directory to their final destination on the system. The
640 command @code{make install} will do that. However, by default
641 everything will be installed in subdirectories of @file{/usr/local}:
642 binaries will go into @file{/usr/local/bin}, libraries will end up in
643 @file{/usr/local/lib}, etc. This destination is usually not writable
644 by any user, so we assume that we have to become root before we can
645 run @code{make install}. In our example, running @code{make install}
646 will copy the program @file{hello} into @file{/usr/local/bin}
647 and @file{README} into @file{/usr/local/share/doc/amhello}.
649 A last and optional step is to run @code{make installcheck}. This
650 command may run tests on the installed files. @code{make check} tests
651 the files in the source tree, while @code{make installcheck} tests
652 their installed copies. The tests run by the latter can be different
653 from those run by the former. For instance, there are tests that
654 cannot be run in the source tree. Conversely, some packages are set
655 up so that @code{make installcheck} will run the very same tests as
656 @code{make check}, only on different files (non-installed
657 vs.@: installed). It can make a difference, for instance when the
658 source tree's layout is different from that of the installation.
659 Furthermore it may help to diagnose an incomplete installation.
661 Presently most packages do not have any @code{installcheck} tests
662 because the existence of @code{installcheck} is little known, and its
663 usefulness is neglected. Our little toy package is no better: @code{make
664 installcheck} does nothing.
666 @node Standard Targets
667 @subsection Standard @file{Makefile} Targets
669 So far we have come across four ways to run @command{make} in the GNU
670 Build System: @code{make}, @code{make check}, @code{make install}, and
671 @code{make installcheck}. The words @code{check}, @code{install}, and
672 @code{installcheck}, passed as arguments to @command{make}, are called
673 @dfn{targets}. @code{make} is a shorthand for @code{make all},
674 @code{all} being the default target in the GNU Build System.
676 Here is a list of the most useful targets that the GNU Coding Standards
682 Build programs, libraries, documentation, etc.@: (same as @code{make}).
685 Install what needs to be installed, copying the files from the
686 package's tree to system-wide directories.
687 @item make install-strip
688 @trindex install-strip
689 Same as @code{make install}, then strip debugging symbols. Some
690 users like to trade space for useful bug reports@enddots{}
693 The opposite of @code{make install}: erase the installed files.
694 (This needs to be run from the same build tree that was installed.)
697 Erase from the build tree the files built by @code{make all}.
700 Additionally erase anything @code{./configure} created.
703 Run the test suite, if any.
704 @item make installcheck
705 @trindex installcheck
706 Check the installed programs or libraries, if supported.
709 Recreate @file{@var{package}-@var{version}.tar.gz} from all the source
713 @node Standard Directory Variables
714 @subsection Standard Directory Variables
715 @cindex directory variables
717 The GNU Coding Standards also specify a hierarchy of variables to
718 denote installation directories. Some of these are:
720 @multitable {Directory variable} {@code{$@{datarootdir@}/doc/$@{PACKAGE@}}}
721 @headitem Directory variable @tab Default value
722 @item @code{prefix} @tab @code{/usr/local}
723 @item @w{@ @ @code{exec_prefix}} @tab @code{$@{prefix@}}
724 @item @w{@ @ @ @ @code{bindir}} @tab @code{$@{exec_prefix@}/bin}
725 @item @w{@ @ @ @ @code{libdir}} @tab @code{$@{exec_prefix@}/lib}
726 @item @w{@ @ @ @ @dots{}}
727 @item @w{@ @ @code{includedir}} @tab @code{$@{prefix@}/include}
728 @item @w{@ @ @code{datarootdir}} @tab @code{$@{prefix@}/share}
729 @item @w{@ @ @ @ @code{datadir}} @tab @code{$@{datarootdir@}}
730 @item @w{@ @ @ @ @code{mandir}} @tab @code{$@{datarootdir@}/man}
731 @item @w{@ @ @ @ @code{infodir}} @tab @code{$@{datarootdir@}/info}
732 @item @w{@ @ @ @ @code{docdir}} @tab @code{$@{datarootdir@}/doc/$@{PACKAGE@}}
733 @item @w{@ @ @dots{}}
736 @c We should provide a complete table somewhere, but not here. The
737 @c complete list of directory variables it too confusing as-is. It
738 @c requires some explanations that are too complicated for this
739 @c introduction. Besides listing directories like localstatedir
740 @c would make the explanations in ``Two-Part Install'' harder.
742 Each of these directories has a role which is often obvious from its
743 name. In a package, any installable file will be installed in one of
744 these directories. For instance in @code{amhello-1.0}, the program
745 @file{hello} is to be installed in @var{bindir}, the directory for
746 binaries. The default value for this directory is
747 @file{/usr/local/bin}, but the user can supply a different value when
748 calling @command{configure}. Also the file @file{README} will be
749 installed into @var{docdir}, which defaults to
750 @file{/usr/local/share/doc/amhello}.
754 As a user, if you wish to install a package on your own account, you
755 could proceed as follows:
758 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr}
760 ~/amhello-1.0 % @kbd{make}
762 ~/amhello-1.0 % @kbd{make install}
766 This would install @file{~/usr/bin/hello} and
767 @file{~/usr/share/doc/amhello/README}.
769 The list of all such directory options is shown by
770 @code{./configure --help}.
772 @node Standard Configuration Variables
773 @subsection Standard Configuration Variables
774 @cindex configuration variables, overriding
776 The GNU Coding Standards also define a set of standard configuration
777 variables used during the build. Here are some:
786 @item @code{CXXFLAGS}
790 @item @code{CPPFLAGS}
791 C/C++ preprocessor flags
795 @command{configure} usually does a good job at setting appropriate
796 values for these variables, but there are cases where you may want to
797 override them. For instance you may have several versions of a
798 compiler installed and would like to use another one, you may have
799 header files installed outside the default search path of the
800 compiler, or even libraries out of the way of the linker.
802 Here is how one would call @command{configure} to force it to use
803 @command{gcc-3} as C compiler, use header files from
804 @file{~/usr/include} when compiling, and libraries from
805 @file{~/usr/lib} when linking.
808 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr CC=gcc-3 \
809 CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib}
812 Again, a full list of these variables appears in the output of
813 @code{./configure --help}.
816 @subsection Overriding Default Configuration Setting with @file{config.site}
817 @cindex @file{config.site} example
819 When installing several packages using the same setup, it can be
820 convenient to create a file to capture common settings.
821 If a file named @file{@var{prefix}/share/config.site} exists,
822 @command{configure} will source it at the beginning of its execution.
824 Recall the command from the previous section:
827 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr CC=gcc-3 \
828 CPPFLAGS=-I$HOME/usr/include LDFLAGS=-L$HOME/usr/lib}
831 Assuming we are installing many package in @file{~/usr}, and will
832 always want to use these definitions of @code{CC}, @code{CPPFLAGS}, and
833 @code{LDFLAGS}, we can automate this by creating the following
834 @file{~/usr/share/config.site} file:
837 test -z "$CC" && CC=gcc-3
838 test -z "$CPPFLAGS" && CPPFLAGS=-I$HOME/usr/include
839 test -z "$LDFLAGS" && LDFLAGS=-L$HOME/usr/lib
842 Now, any time a @file{configure} script is using the @file{~/usr}
843 prefix, it will execute the above @file{config.site} and define
844 these three variables.
847 ~/amhello-1.0 % @kbd{./configure --prefix ~/usr}
848 configure: loading site script /home/adl/usr/share/config.site
852 @xref{Site Defaults, , Setting Site Defaults, autoconf, The Autoconf
853 Manual}, for more information about this feature.
857 @subsection Parallel Build Trees (a.k.a.@: VPATH Builds)
858 @cindex Parallel build trees
860 @cindex source tree and build tree
861 @cindex build tree and source tree
862 @cindex trees, source vs.@: build
864 The GNU Build System distinguishes two trees: the source tree, and
867 The source tree is rooted in the directory containing
868 @file{configure}. It contains all the sources files (those that are
869 distributed), and may be arranged using several subdirectories.
871 The build tree is rooted in the directory in which @file{configure}
872 was run, and is populated with all object files, programs, libraries,
873 and other derived files built from the sources (and hence not
874 distributed). The build tree usually has the same subdirectory layout
875 as the source tree; its subdirectories are created automatically by
878 If @file{configure} is executed in its own directory, the source and
879 build trees are combined: derived files are constructed in the same
880 directories as their sources. This was the case in our first
881 installation example (@pxref{Basic Installation}).
883 A common request from users is that they want to confine all derived
884 files to a single directory, to keep their source directories
885 uncluttered. Here is how we could run @file{configure} to build
886 everything in a subdirectory called @file{build/}.
889 ~ % @kbd{tar zxf ~/amhello-1.0.tar.gz}
890 ~ % @kbd{cd amhello-1.0}
891 ~/amhello-1.0 % @kbd{mkdir build && cd build}
892 ~/amhello-1.0/build % @kbd{../configure}
894 ~/amhello-1.0/build % @kbd{make}
898 These setups, where source and build trees are different, are often
899 called @dfn{parallel builds} or @dfn{VPATH builds}. The expression
900 @emph{parallel build} is misleading: the word @emph{parallel} is a
901 reference to the way the build tree shadows the source tree, it is not
902 about some concurrency in the way build commands are run. For this
903 reason we refer to such setups using the name @emph{VPATH builds} in
904 the following. @emph{VPATH} is the name of the @command{make} feature
905 used by the @file{Makefile}s to allow these builds (@pxref{General
906 Search, , @code{VPATH} Search Path for All Prerequisites, make, The
909 @cindex multiple configurations, example
910 @cindex debug build, example
911 @cindex optimized build, example
913 VPATH builds have other interesting uses. One is to build the same
914 sources with multiple configurations. For instance:
916 @c Keep in sync with amhello-cflags.test.
918 ~ % @kbd{tar zxf ~/amhello-1.0.tar.gz}
919 ~ % @kbd{cd amhello-1.0}
920 ~/amhello-1.0 % @kbd{mkdir debug optim && cd debug}
921 ~/amhello-1.0/debug % @kbd{../configure CFLAGS='-g -O0'}
923 ~/amhello-1.0/debug % @kbd{make}
925 ~/amhello-1.0/debug % cd ../optim
926 ~/amhello-1.0/optim % @kbd{../configure CFLAGS='-O3 -fomit-frame-pointer'}
928 ~/amhello-1.0/optim % @kbd{make}
932 With network file systems, a similar approach can be used to build the
933 same sources on different machines. For instance, suppose that the
934 sources are installed on a directory shared by two hosts: @code{HOST1}
935 and @code{HOST2}, which may be different platforms.
938 ~ % @kbd{cd /nfs/src}
939 /nfs/src % @kbd{tar zxf ~/amhello-1.0.tar.gz}
942 On the first host, you could create a local build directory:
944 [HOST1] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
945 [HOST1] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure}
947 [HOST1] /tmp/amh % @kbd{make && sudo make install}
952 (Here we assume that the installer has configured @command{sudo} so it
953 can execute @code{make install} with root privileges; it is more convenient
954 than using @command{su} like in @ref{Basic Installation}).
956 On the second host, you would do exactly the same, possibly at
959 [HOST2] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
960 [HOST2] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure}
962 [HOST2] /tmp/amh % @kbd{make && sudo make install}
966 @cindex read-only source tree
967 @cindex source tree, read-only
969 In this scenario, nothing forbids the @file{/nfs/src/amhello-1.0}
970 directory from being read-only. In fact VPATH builds are also a means
971 of building packages from a read-only medium such as a CD-ROM. (The
972 FSF used to sell CD-ROM with unpacked source code, before the GNU
973 project grew so big.)
975 @node Two-Part Install
976 @subsection Two-Part Installation
978 In our last example (@pxref{VPATH Builds}), a source tree was shared
979 by two hosts, but compilation and installation were done separately on
982 The GNU Build System also supports networked setups where part of the
983 installed files should be shared amongst multiple hosts. It does so
984 by distinguishing architecture-dependent files from
985 architecture-independent files, and providing two @file{Makefile}
986 targets to install each of these classes of files.
988 @trindex install-exec
989 @trindex install-data
991 These targets are @code{install-exec} for architecture-dependent files
992 and @code{install-data} for architecture-independent files.
993 The command we used up to now, @code{make install}, can be thought of
994 as a shorthand for @code{make install-exec install-data}.
996 From the GNU Build System point of view, the distinction between
997 architecture-dependent files and architecture-independent files is
998 based exclusively on the directory variable used to specify their
999 installation destination. In the list of directory variables we
1000 provided earlier (@pxref{Standard Directory Variables}), all the
1001 variables based on @var{exec-prefix} designate architecture-dependent
1002 directories whose files will be installed by @code{make install-exec}.
1003 The others designate architecture-independent directories and will
1004 serve files installed by @code{make install-data}. @xref{The Two Parts
1005 of Install}, for more details.
1007 Here is how we could revisit our two-host installation example,
1008 assuming that (1) we want to install the package directly in
1009 @file{/usr}, and (2) the directory @file{/usr/share} is shared by the
1012 On the first host we would run
1014 [HOST1] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
1015 [HOST1] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure --prefix /usr}
1017 [HOST1] /tmp/amh % @kbd{make && sudo make install}
1021 On the second host, however, we need only install the
1022 architecture-specific files.
1024 [HOST2] ~ % @kbd{mkdir /tmp/amh && cd /tmp/amh}
1025 [HOST2] /tmp/amh % @kbd{/nfs/src/amhello-1.0/configure --prefix /usr}
1027 [HOST2] /tmp/amh % @kbd{make && sudo make install-exec}
1031 In packages that have installation checks, it would make sense to run
1032 @code{make installcheck} (@pxref{Basic Installation}) to verify that
1033 the package works correctly despite the apparent partial installation.
1035 @node Cross-Compilation
1036 @subsection Cross-Compilation
1037 @cindex cross-compilation
1039 To @dfn{cross-compile} is to build on one platform a binary that will
1040 run on another platform. When speaking of cross-compilation, it is
1041 important to distinguish between the @dfn{build platform} on which
1042 the compilation is performed, and the @dfn{host platform} on which the
1043 resulting executable is expected to run. The following
1044 @command{configure} options are used to specify each of them:
1047 @item --build=@var{build}
1048 @opindex --build=@var{build}
1049 The system on which the package is built.
1050 @item --host=@var{host}
1051 @opindex --host=@var{host}
1052 The system where built programs and libraries will run.
1055 When the @option{--host} is used, @command{configure} will search for
1056 the cross-compiling suite for this platform. Cross-compilation tools
1057 commonly have their target architecture as prefix of their name. For
1058 instance my cross-compiler for MinGW32 has its binaries called
1059 @code{i586-mingw32msvc-gcc}, @code{i586-mingw32msvc-ld},
1060 @code{i586-mingw32msvc-as}, etc.
1062 @cindex MinGW cross-compilation example
1063 @cindex cross-compilation example
1065 Here is how we could build @code{amhello-1.0} for
1066 @code{i586-mingw32msvc} on a GNU/Linux PC.
1068 @c Keep in sync with amhello-cross-compile.test.
1070 ~/amhello-1.0 % @kbd{./configure --build i686-pc-linux-gnu --host i586-mingw32msvc}
1071 checking for a BSD-compatible install... /usr/bin/install -c
1072 checking whether build environment is sane... yes
1073 checking for gawk... gawk
1074 checking whether make sets $(MAKE)... yes
1075 checking for i586-mingw32msvc-strip... i586-mingw32msvc-strip
1076 checking for i586-mingw32msvc-gcc... i586-mingw32msvc-gcc
1077 checking for C compiler default output file name... a.exe
1078 checking whether the C compiler works... yes
1079 checking whether we are cross compiling... yes
1080 checking for suffix of executables... .exe
1081 checking for suffix of object files... o
1082 checking whether we are using the GNU C compiler... yes
1083 checking whether i586-mingw32msvc-gcc accepts -g... yes
1084 checking for i586-mingw32msvc-gcc option to accept ANSI C...
1086 ~/amhello-1.0 % @kbd{make}
1088 ~/amhello-1.0 % @kbd{cd src; file hello.exe}
1089 hello.exe: MS Windows PE 32-bit Intel 80386 console executable not relocatable
1092 The @option{--host} and @option{--build} options are usually all we
1093 need for cross-compiling. The only exception is if the package being
1094 built is itself a cross-compiler: we need a third option to specify
1095 its target architecture.
1098 @item --target=@var{target}
1099 @opindex --target=@var{target}
1100 When building compiler tools: the system for which the tools will
1104 For instance when installing GCC, the GNU Compiler Collection, we can
1105 use @option{--target=@/@var{target}} to specify that we want to build
1106 GCC as a cross-compiler for @var{target}. Mixing @option{--build} and
1107 @option{--target}, we can actually cross-compile a cross-compiler;
1108 such a three-way cross-compilation is known as a @dfn{Canadian cross}.
1110 @xref{Specifying Names, , Specifying the System Type, autoconf, The
1111 Autoconf Manual}, for more information about these @command{configure}
1115 @subsection Renaming Programs at Install Time
1116 @cindex Renaming programs
1117 @cindex Transforming program names
1118 @cindex Programs, renaming during installation
1120 The GNU Build System provides means to automatically rename
1121 executables and manpages before they are installed (@pxref{Man Pages}).
1122 This is especially convenient
1123 when installing a GNU package on a system that already has a
1124 proprietary implementation you do not want to overwrite. For instance,
1125 you may want to install GNU @command{tar} as @command{gtar} so you can
1126 distinguish it from your vendor's @command{tar}.
1128 This can be done using one of these three @command{configure} options.
1131 @item --program-prefix=@var{prefix}
1132 @opindex --program-prefix=@var{prefix}
1133 Prepend @var{prefix} to installed program names.
1134 @item --program-suffix=@var{suffix}
1135 @opindex --program-suffix=@var{suffix}
1136 Append @var{suffix} to installed program names.
1137 @item --program-transform-name=@var{program}
1138 @opindex --program-transform-name=@var{program}
1139 Run @code{sed @var{program}} on installed program names.
1142 The following commands would install @file{hello}
1143 as @file{/usr/local/bin/test-hello}, for instance.
1146 ~/amhello-1.0 % @kbd{./configure --program-prefix test-}
1148 ~/amhello-1.0 % @kbd{make}
1150 ~/amhello-1.0 % @kbd{sudo make install}
1155 @subsection Building Binary Packages Using DESTDIR
1158 The GNU Build System's @code{make install} and @code{make uninstall}
1159 interface does not exactly fit the needs of a system administrator
1160 who has to deploy and upgrade packages on lots of hosts. In other
1161 words, the GNU Build System does not replace a package manager.
1163 Such package managers usually need to know which files have been
1164 installed by a package, so a mere @code{make install} is
1167 @cindex Staged installation
1169 The @code{DESTDIR} variable can be used to perform a staged
1170 installation. The package should be configured as if it was going to
1171 be installed in its final location (e.g., @code{--prefix /usr}), but
1172 when running @code{make install}, the @code{DESTDIR} should be set to
1173 the absolute name of a directory into which the installation will be
1174 diverted. From this directory it is easy to review which files are
1175 being installed where, and finally copy them to their final location
1178 @cindex Binary package
1180 For instance here is how we could create a binary package containing a
1181 snapshot of all the files to be installed.
1183 @c Keep in sync with amhello-binpkg.test.
1185 ~/amhello-1.0 % @kbd{./configure --prefix /usr}
1187 ~/amhello-1.0 % @kbd{make}
1189 ~/amhello-1.0 % @kbd{make DESTDIR=$HOME/inst install}
1191 ~/amhello-1.0 % @kbd{cd ~/inst}
1192 ~/inst % @kbd{find . -type f -print > ../files.lst}
1193 ~/inst % @kbd{tar zcvf ~/amhello-1.0-i686.tar.gz `cat ../files.lst`}
1195 ./usr/share/doc/amhello/README
1198 After this example, @code{amhello-1.0-i686.tar.gz} is ready to be
1199 uncompressed in @file{/} on many hosts. (Using @code{`cat ../files.lst`}
1200 instead of @samp{.} as argument for @command{tar} avoids entries for
1201 each subdirectory in the archive: we would not like @command{tar} to
1202 restore the modification time of @file{/}, @file{/usr/}, etc.)
1204 Note that when building packages for several architectures, it might
1205 be convenient to use @code{make install-data} and @code{make
1206 install-exec} (@pxref{Two-Part Install}) to gather
1207 architecture-independent files in a single package.
1209 @xref{Install}, for more information.
1211 @c We should document PRE_INSTALL/POST_INSTALL/NORMAL_INSTALL and their
1212 @c UNINSTALL counterparts.
1214 @node Preparing Distributions
1215 @subsection Preparing Distributions
1216 @cindex Preparing distributions
1217 @cindex Packages, preparation
1218 @cindex Distributions, preparation
1220 We have already mentioned @code{make dist}. This target collects all
1221 your source files and the necessary parts of the build system to
1222 create a tarball named @file{@var{package}-@var{version}.tar.gz}.
1224 @cindex @code{distcheck} better than @code{dist}
1226 Another, more useful command is @code{make distcheck}. The
1227 @code{distcheck} target constructs
1228 @file{@var{package}-@var{version}.tar.gz} just as well as @code{dist},
1229 but it additionally ensures most of the use cases presented so far
1234 It attempts a full compilation of the package (@pxref{Basic
1235 Installation}), unpacking the newly constructed tarball, running
1236 @code{make}, @code{make check}, @code{make install}, as well as
1237 @code{make installcheck}, and even @code{make dist},
1239 it tests VPATH builds with read-only source tree (@pxref{VPATH Builds}),
1241 it makes sure @code{make clean}, @code{make distclean}, and @code{make
1242 uninstall} do not omit any file (@pxref{Standard Targets}),
1244 and it checks that @code{DESTDIR} installations work (@pxref{DESTDIR}).
1247 All of these actions are performed in a temporary subdirectory, so
1248 that no root privileges are required.
1250 Releasing a package that fails @code{make distcheck} means that one of
1251 the scenarios we presented will not work and some users will be
1252 disappointed. Therefore it is a good practice to release a package
1253 only after a successful @code{make distcheck}. This of course does
1254 not imply that the package will be flawless, but at least it will
1255 prevent some of the embarrassing errors you may find in packages
1256 released by people who have never heard about @code{distcheck} (like
1257 @code{DESTDIR} not working because of a typo, or a distributed file
1258 being erased by @code{make clean}, or even @code{VPATH} builds not
1261 @xref{Creating amhello}, to recreate @file{amhello-1.0.tar.gz} using
1262 @code{make distcheck}. @xref{Checking the Distribution}, for more
1263 information about @code{distcheck}.
1265 @node Dependency Tracking
1266 @subsection Automatic Dependency Tracking
1267 @cindex Dependency tracking
1269 Dependency tracking is performed as a side-effect of compilation.
1270 Each time the build system compiles a source file, it computes its
1271 list of dependencies (in C these are the header files included by the
1272 source being compiled). Later, any time @command{make} is run and a
1273 dependency appears to have changed, the dependent files will be
1276 Automake generates code for automatic dependency tracking by default,
1277 unless the developer chooses to override it; for more information,
1278 @pxref{Dependencies}.
1280 When @command{configure} is executed, you can see it probing each
1281 compiler for the dependency mechanism it supports (several mechanisms
1285 ~/amhello-1.0 % @kbd{./configure --prefix /usr}
1287 checking dependency style of gcc... gcc3
1291 Because dependencies are only computed as a side-effect of the
1292 compilation, no dependency information exists the first time a package
1293 is built. This is OK because all the files need to be built anyway:
1294 @code{make} does not have to decide which files need to be rebuilt.
1295 In fact, dependency tracking is completely useless for one-time builds
1296 and there is a @command{configure} option to disable this:
1299 @item --disable-dependency-tracking
1300 @opindex --disable-dependency-tracking
1301 Speed up one-time builds.
1304 Some compilers do not offer any practical way to derive the list of
1305 dependencies as a side-effect of the compilation, requiring a separate
1306 run (maybe of another tool) to compute these dependencies. The
1307 performance penalty implied by these methods is important enough to
1308 disable them by default. The option @option{--enable-dependency-tracking}
1309 must be passed to @command{configure} to activate them.
1312 @item --enable-dependency-tracking
1313 @opindex --enable-dependency-tracking
1314 Do not reject slow dependency extractors.
1317 @xref{Dependency Tracking Evolution, , Dependency Tracking Evolution,
1318 automake-history, Brief History of Automake}, for some discussion about
1319 the different dependency tracking schemes used by Automake over the years.
1321 @node Nested Packages
1322 @subsection Nested Packages
1323 @cindex Nested packages
1324 @cindex Packages, nested
1327 Although nesting packages isn't something we would recommend to
1328 someone who is discovering the Autotools, it is a nice feature worthy
1329 of mention in this small advertising tour.
1331 Autoconfiscated packages (that means packages whose build system have
1332 been created by Autoconf and friends) can be nested to arbitrary
1335 A typical setup is that package A will distribute one of the libraries
1336 it needs in a subdirectory. This library B is a complete package with
1337 its own GNU Build System. The @command{configure} script of A will
1338 run the @command{configure} script of B as part of its execution,
1339 building and installing A will also build and install B. Generating a
1340 distribution for A will also include B.
1342 It is possible to gather several packages like this. GCC is a heavy
1343 user of this feature. This gives installers a single package to
1344 configure, build and install, while it allows developers to work on
1345 subpackages independently.
1347 When configuring nested packages, the @command{configure} options
1348 given to the top-level @command{configure} are passed recursively to
1349 nested @command{configure}s. A package that does not understand an
1350 option will ignore it, assuming it is meaningful to some other
1353 @opindex --help=recursive
1355 The command @code{configure --help=recursive} can be used to display
1356 the options supported by all the included packages.
1358 @xref{Subpackages}, for an example setup.
1361 @section How Autotools Help
1362 @cindex Autotools, purpose
1364 There are several reasons why you may not want to implement the GNU
1365 Build System yourself (read: write a @file{configure} script and
1366 @file{Makefile}s yourself).
1370 As we have seen, the GNU Build System has a lot of
1371 features (@pxref{Use Cases}).
1372 Some users may expect features you have not implemented because
1373 you did not need them.
1375 Implementing these features portably is difficult and exhausting.
1376 Think of writing portable shell scripts, and portable
1377 @file{Makefile}s, for systems you may not have handy. @xref{Portable
1378 Shell, , Portable Shell Programming, autoconf, The Autoconf Manual}, to
1381 You will have to upgrade your setup to follow changes to the GNU
1385 The GNU Autotools take all this burden off your back and provide:
1389 Tools to create a portable, complete, and self-contained GNU Build
1390 System, from simple instructions.
1391 @emph{Self-contained} meaning the resulting build system does not
1392 require the GNU Autotools.
1394 A central place where fixes and improvements are made:
1395 a bug-fix for a portability issue will benefit every package.
1398 Yet there also exist reasons why you may want NOT to use the
1399 Autotools@enddots{} For instance you may be already using (or used to)
1400 another incompatible build system. Autotools will only be useful if
1401 you do accept the concepts of the GNU Build System. People who have their
1402 own idea of how a build system should work will feel frustrated by the
1406 @section A Small Hello World
1407 @cindex Example Hello World
1408 @cindex Hello World example
1409 @cindex @file{amhello-1.0.tar.gz}, creation
1411 In this section we recreate the @file{amhello-1.0} package from
1412 scratch. The first subsection shows how to call the Autotools to
1413 instantiate the GNU Build System, while the second explains the
1414 meaning of the @file{configure.ac} and @file{Makefile.am} files read
1417 @anchor{amhello Explained}
1419 * Creating amhello:: Create @file{amhello-1.0.tar.gz} from scratch
1420 * amhello's configure.ac Setup Explained::
1421 * amhello's Makefile.am Setup Explained::
1424 @node Creating amhello
1425 @subsection Creating @file{amhello-1.0.tar.gz}
1427 Here is how we can recreate @file{amhello-1.0.tar.gz} from scratch.
1428 The package is simple enough so that we will only need to write 5
1429 files. (You may copy them from the final @file{amhello-1.0.tar.gz}
1430 that is distributed with Automake if you do not want to write them.)
1432 Create the following files in an empty directory.
1437 @file{src/main.c} is the source file for the @file{hello} program. We
1438 store it in the @file{src/} subdirectory, because later, when the package
1439 evolves, it will ease the addition of a @file{man/} directory for man
1440 pages, a @file{data/} directory for data files, etc.
1442 ~/amhello % @kbd{cat src/main.c}
1449 puts ("Hello World!");
1450 puts ("This is " PACKAGE_STRING ".");
1456 @file{README} contains some very limited documentation for our little
1459 ~/amhello % @kbd{cat README}
1460 This is a demonstration package for GNU Automake.
1461 Type `info Automake' to read the Automake manual.
1465 @file{Makefile.am} and @file{src/Makefile.am} contain Automake
1466 instructions for these two directories.
1469 ~/amhello % @kbd{cat src/Makefile.am}
1470 bin_PROGRAMS = hello
1471 hello_SOURCES = main.c
1472 ~/amhello % @kbd{cat Makefile.am}
1474 dist_doc_DATA = README
1478 Finally, @file{configure.ac} contains Autoconf instructions to
1479 create the @command{configure} script.
1482 ~/amhello % @kbd{cat configure.ac}
1483 AC_INIT([amhello], [1.0], [@value{PACKAGE_BUGREPORT}])
1484 AM_INIT_AUTOMAKE([-Wall -Werror foreign])
1486 AC_CONFIG_HEADERS([config.h])
1495 @cindex @command{autoreconf}, example
1497 Once you have these five files, it is time to run the Autotools to
1498 instantiate the build system. Do this using the @command{autoreconf}
1502 ~/amhello % @kbd{autoreconf --install}
1503 configure.ac: installing `./install-sh'
1504 configure.ac: installing `./missing'
1505 src/Makefile.am: installing `./depcomp'
1508 At this point the build system is complete.
1510 In addition to the three scripts mentioned in its output, you can see
1511 that @command{autoreconf} created four other files: @file{configure},
1512 @file{config.h.in}, @file{Makefile.in}, and @file{src/Makefile.in}.
1513 The latter three files are templates that will be adapted to the
1514 system by @command{configure} under the names @file{config.h},
1515 @file{Makefile}, and @file{src/Makefile}. Let's do this:
1518 ~/amhello % @kbd{./configure}
1519 checking for a BSD-compatible install... /usr/bin/install -c
1520 checking whether build environment is sane... yes
1521 checking for gawk... no
1522 checking for mawk... mawk
1523 checking whether make sets $(MAKE)... yes
1524 checking for gcc... gcc
1525 checking for C compiler default output file name... a.out
1526 checking whether the C compiler works... yes
1527 checking whether we are cross compiling... no
1528 checking for suffix of executables...
1529 checking for suffix of object files... o
1530 checking whether we are using the GNU C compiler... yes
1531 checking whether gcc accepts -g... yes
1532 checking for gcc option to accept ISO C89... none needed
1533 checking for style of include used by make... GNU
1534 checking dependency style of gcc... gcc3
1535 configure: creating ./config.status
1536 config.status: creating Makefile
1537 config.status: creating src/Makefile
1538 config.status: creating config.h
1539 config.status: executing depfiles commands
1543 @cindex @code{distcheck} example
1545 You can see @file{Makefile}, @file{src/Makefile}, and @file{config.h}
1546 being created at the end after @command{configure} has probed the
1547 system. It is now possible to run all the targets we wish
1548 (@pxref{Standard Targets}). For instance:
1551 ~/amhello % @kbd{make}
1553 ~/amhello % @kbd{src/hello}
1555 This is amhello 1.0.
1556 ~/amhello % @kbd{make distcheck}
1558 =============================================
1559 amhello-1.0 archives ready for distribution:
1561 =============================================
1564 Note that running @command{autoreconf} is only needed initially when
1565 the GNU Build System does not exist. When you later change some
1566 instructions in a @file{Makefile.am} or @file{configure.ac}, the
1567 relevant part of the build system will be regenerated automatically
1568 when you execute @command{make}.
1570 @command{autoreconf} is a script that calls @command{autoconf},
1571 @command{automake}, and a bunch of other commands in the right order.
1572 If you are beginning with these tools, it is not important to figure
1573 out in which order all these tools should be invoked and why. However,
1574 because Autoconf and Automake have separate manuals, the important
1575 point to understand is that @command{autoconf} is in charge of
1576 creating @file{configure} from @file{configure.ac}, while
1577 @command{automake} is in charge of creating @file{Makefile.in}s from
1578 @file{Makefile.am}s and @file{configure.ac}. This should at least
1579 direct you to the right manual when seeking answers.
1582 @node amhello's configure.ac Setup Explained
1583 @subsection @code{amhello}'s @file{configure.ac} Setup Explained
1585 @cindex @file{configure.ac}, Hello World
1587 Let us begin with the contents of @file{configure.ac}.
1590 AC_INIT([amhello], [1.0], [@value{PACKAGE_BUGREPORT}])
1591 AM_INIT_AUTOMAKE([-Wall -Werror foreign])
1593 AC_CONFIG_HEADERS([config.h])
1601 This file is read by both @command{autoconf} (to create
1602 @file{configure}) and @command{automake} (to create the various
1603 @file{Makefile.in}s). It contains a series of M4 macros that will be
1604 expanded as shell code to finally form the @file{configure} script.
1605 We will not elaborate on the syntax of this file, because the Autoconf
1606 manual has a whole section about it (@pxref{Writing Autoconf Input, ,
1607 Writing @file{configure.ac}, autoconf, The Autoconf Manual}).
1609 The macros prefixed with @code{AC_} are Autoconf macros, documented
1610 in the Autoconf manual (@pxref{Autoconf Macro Index, , Autoconf Macro
1611 Index, autoconf, The Autoconf Manual}). The macros that start with
1612 @code{AM_} are Automake macros, documented later in this manual
1613 (@pxref{Macro Index}).
1615 The first two lines of @file{configure.ac} initialize Autoconf and
1616 Automake. @code{AC_INIT} takes in as parameters the name of the package,
1617 its version number, and a contact address for bug-reports about the
1618 package (this address is output at the end of @code{./configure
1619 --help}, for instance). When adapting this setup to your own package,
1620 by all means please do not blindly copy Automake's address: use the
1621 mailing list of your package, or your own mail address.
1627 The argument to @code{AM_INIT_AUTOMAKE} is a list of options for
1628 @command{automake} (@pxref{Options}). @option{-Wall} and
1629 @option{-Werror} ask @command{automake} to turn on all warnings and
1630 report them as errors. We are speaking of @strong{Automake} warnings
1631 here, such as dubious instructions in @file{Makefile.am}. This has
1632 absolutely nothing to do with how the compiler will be called, even
1633 though it may support options with similar names. Using @option{-Wall
1634 -Werror} is a safe setting when starting to work on a package: you do
1635 not want to miss any issues. Later you may decide to relax things a
1636 bit. The @option{foreign} option tells Automake that this package
1637 will not follow the GNU Standards. GNU packages should always
1638 distribute additional files such as @file{ChangeLog}, @file{AUTHORS},
1639 etc. We do not want @command{automake} to complain about these
1640 missing files in our small example.
1642 The @code{AC_PROG_CC} line causes the @command{configure} script to
1643 search for a C compiler and define the variable @code{CC} with its
1644 name. The @file{src/Makefile.in} file generated by Automake uses the
1645 variable @code{CC} to build @file{hello}, so when @command{configure}
1646 creates @file{src/Makefile} from @file{src/Makefile.in}, it will define
1647 @code{CC} with the value it has found. If Automake is asked to create
1648 a @file{Makefile.in} that uses @code{CC} but @file{configure.ac} does
1649 not define it, it will suggest you add a call to @code{AC_PROG_CC}.
1651 The @code{AC_CONFIG_HEADERS([config.h])} invocation causes the
1652 @command{configure} script to create a @file{config.h} file gathering
1653 @samp{#define}s defined by other macros in @file{configure.ac}. In our
1654 case, the @code{AC_INIT} macro already defined a few of them. Here
1655 is an excerpt of @file{config.h} after @command{configure} has run:
1659 /* Define to the address where bug reports for this package should be sent. */
1660 #define PACKAGE_BUGREPORT "@value{PACKAGE_BUGREPORT}"
1662 /* Define to the full name and version of this package. */
1663 #define PACKAGE_STRING "amhello 1.0"
1667 As you probably noticed, @file{src/main.c} includes @file{config.h} so
1668 it can use @code{PACKAGE_STRING}. In a real-world project,
1669 @file{config.h} can grow really big, with one @samp{#define} per
1670 feature probed on the system.
1672 The @code{AC_CONFIG_FILES} macro declares the list of files that
1673 @command{configure} should create from their @file{*.in} templates.
1674 Automake also scans this list to find the @file{Makefile.am} files it must
1675 process. (This is important to remember: when adding a new directory
1676 to your project, you should add its @file{Makefile} to this list,
1677 otherwise Automake will never process the new @file{Makefile.am} you
1678 wrote in that directory.)
1680 Finally, the @code{AC_OUTPUT} line is a closing command that actually
1681 produces the part of the script in charge of creating the files
1682 registered with @code{AC_CONFIG_HEADERS} and @code{AC_CONFIG_FILES}.
1684 @cindex @command{autoscan}
1686 When starting a new project, we suggest you start with such a simple
1687 @file{configure.ac}, and gradually add the other tests it requires.
1688 The command @command{autoscan} can also suggest a few of the tests
1689 your package may need (@pxref{autoscan Invocation, , Using
1690 @command{autoscan} to Create @file{configure.ac}, autoconf, The
1694 @node amhello's Makefile.am Setup Explained
1695 @subsection @code{amhello}'s @file{Makefile.am} Setup Explained
1697 @cindex @file{Makefile.am}, Hello World
1699 We now turn to @file{src/Makefile.am}. This file contains
1700 Automake instructions to build and install @file{hello}.
1703 bin_PROGRAMS = hello
1704 hello_SOURCES = main.c
1707 A @file{Makefile.am} has the same syntax as an ordinary
1708 @file{Makefile}. When @command{automake} processes a
1709 @file{Makefile.am} it copies the entire file into the output
1710 @file{Makefile.in} (that will be later turned into @file{Makefile} by
1711 @command{configure}) but will react to certain variable definitions
1712 by generating some build rules and other variables.
1713 Often @file{Makefile.am}s contain only a list of variable definitions as
1714 above, but they can also contain other variable and rule definitions that
1715 @command{automake} will pass along without interpretation.
1717 Variables that end with @code{_PROGRAMS} are special variables
1718 that list programs that the resulting @file{Makefile} should build.
1719 In Automake speak, this @code{_PROGRAMS} suffix is called a
1720 @dfn{primary}; Automake recognizes other primaries such as
1721 @code{_SCRIPTS}, @code{_DATA}, @code{_LIBRARIES}, etc.@: corresponding
1722 to different types of files.
1724 The @samp{bin} part of the @code{bin_PROGRAMS} tells
1725 @command{automake} that the resulting programs should be installed in
1726 @var{bindir}. Recall that the GNU Build System uses a set of variables
1727 to denote destination directories and allow users to customize these
1728 locations (@pxref{Standard Directory Variables}). Any such directory
1729 variable can be put in front of a primary (omitting the @code{dir}
1730 suffix) to tell @command{automake} where to install the listed files.
1732 Programs need to be built from source files, so for each program
1733 @code{@var{prog}} listed in a @code{@w{_PROGRAMS}} variable,
1734 @command{automake} will look for another variable named
1735 @code{@var{prog}_SOURCES} listing its source files. There may be more
1736 than one source file: they will all be compiled and linked together.
1738 Automake also knows that source files need to be distributed when
1739 creating a tarball (unlike built programs). So a side-effect of this
1740 @code{hello_SOURCES} declaration is that @file{main.c} will be
1741 part of the tarball created by @code{make dist}.
1743 Finally here are some explanations regarding the top-level
1748 dist_doc_DATA = README
1751 @code{SUBDIRS} is a special variable listing all directories that
1752 @command{make} should recurse into before processing the current
1753 directory. So this line is responsible for @command{make} building
1754 @file{src/hello} even though we run it from the top-level. This line
1755 also causes @code{make install} to install @file{src/hello} before
1756 installing @file{README} (not that this order matters).
1758 The line @code{dist_doc_DATA = README} causes @file{README} to be
1759 distributed and installed in @var{docdir}. Files listed with the
1760 @code{_DATA} primary are not automatically part of the tarball built
1761 with @code{make dist}, so we add the @code{dist_} prefix so they get
1762 distributed. However, for @file{README} it would not have been
1763 necessary: @command{automake} automatically distributes any
1764 @file{README} file it encounters (the list of other files
1765 automatically distributed is presented by @code{automake --help}).
1766 The only important effect of this second line is therefore to install
1767 @file{README} during @code{make install}.
1769 One thing not covered in this example is accessing the installation
1770 directory values (@pxref{Standard Directory Variables}) from your
1771 program code, that is, converting them into defined macros. For this,
1772 @pxref{Defining Directories,,, autoconf, The Autoconf Manual}.
1776 @chapter General ideas
1778 The following sections cover a few basic ideas that will help you
1779 understand how Automake works.
1782 * General Operation:: General operation of Automake
1783 * Strictness:: Standards conformance checking
1784 * Uniform:: The Uniform Naming Scheme
1785 * Length Limitations:: Staying below the command line length limit
1786 * Canonicalization:: How derived variables are named
1787 * User Variables:: Variables reserved for the user
1788 * Auxiliary Programs:: Programs automake might require
1792 @node General Operation
1793 @section General Operation
1795 Automake works by reading a @file{Makefile.am} and generating a
1796 @file{Makefile.in}. Certain variables and rules defined in the
1797 @file{Makefile.am} instruct Automake to generate more specialized code;
1798 for instance, a @code{bin_PROGRAMS} variable definition will cause rules
1799 for compiling and linking programs to be generated.
1801 @cindex Non-standard targets
1802 @cindex @code{git-dist}, non-standard example
1805 The variable definitions and rules in the @file{Makefile.am} are
1806 copied mostly verbatim into the generated file, with all variable
1807 definitions preceding all rules. This allows you to add almost
1808 arbitrary code into the generated @file{Makefile.in}. For instance,
1809 the Automake distribution includes a non-standard rule for the
1810 @code{git-dist} target, which the Automake maintainer uses to make
1811 distributions from the source control system.
1813 @cindex GNU make extensions
1815 Note that most GNU make extensions are not recognized by Automake. Using
1816 such extensions in a @file{Makefile.am} will lead to errors or confusing
1819 @cindex Append operator
1821 A special exception is that the GNU make append operator, @samp{+=}, is
1822 supported. This operator appends its right hand argument to the variable
1823 specified on the left. Automake will translate the operator into
1824 an ordinary @samp{=} operator; @samp{+=} will thus work with any make program.
1826 Automake tries to keep comments grouped with any adjoining rules or
1827 variable definitions.
1829 @cindex Limitations of automake parser
1830 @cindex Automake parser, limitations of
1831 @cindex indentation in Makefile.am
1832 Generally, Automake is not particularly smart in the parsing of unusual
1833 Makefile constructs, so you're advised to avoid fancy constructs or
1834 ``creative'' use of whitespaces.
1835 @c Keep this in sync with doc-parsing-buglets-tabs.test.
1836 For example, @key{TAB} characters cannot be used between a target name
1837 and the following ``@code{:}'' character, and variable assignments
1838 shouldn't be indented with @key{TAB} characters.
1839 @c Keep this in sync with doc-parsing-buglets-colneq-subst.test.
1840 Also, using more complex macro in target names can cause trouble:
1843 % @kbd{cat Makefile.am}
1846 Makefile.am:1: bad characters in variable name `$(FOO'
1847 Makefile.am:1: `:='-style assignments are not portable
1850 @cindex Make targets, overriding
1851 @cindex Make rules, overriding
1852 @cindex Overriding make rules
1853 @cindex Overriding make targets
1855 A rule defined in @file{Makefile.am} generally overrides any such
1856 rule of a similar name that would be automatically generated by
1857 @command{automake}. Although this is a supported feature, it is generally
1858 best to avoid making use of it, as sometimes the generated rules are
1861 @cindex Variables, overriding
1862 @cindex Overriding make variables
1864 Similarly, a variable defined in @file{Makefile.am} or
1865 @code{AC_SUBST}ed from @file{configure.ac} will override any
1866 definition of the variable that @command{automake} would ordinarily
1867 create. This feature is more often useful than the ability to
1868 override a rule. Be warned that many of the variables generated by
1869 @command{automake} are considered to be for internal use only, and their
1870 names might change in future releases.
1872 @cindex Recursive operation of Automake
1873 @cindex Automake, recursive operation
1874 @cindex Example of recursive operation
1876 When examining a variable definition, Automake will recursively examine
1877 variables referenced in the definition. For example, if Automake is
1878 looking at the content of @code{foo_SOURCES} in this snippet
1880 @c Keep in sync with interp.test.
1883 foo_SOURCES = c.c $(xs)
1886 it would use the files @file{a.c}, @file{b.c}, and @file{c.c} as the
1887 contents of @code{foo_SOURCES}.
1889 @cindex @code{##} (special Automake comment)
1890 @cindex Special Automake comment
1891 @cindex Comment, special to Automake
1893 Automake also allows a form of comment that is @emph{not} copied into
1894 the output; all lines beginning with @samp{##} (leading spaces allowed)
1895 are completely ignored by Automake.
1897 It is customary to make the first line of @file{Makefile.am} read:
1899 @cindex Makefile.am, first line
1900 @cindex First line of Makefile.am
1903 ## Process this file with automake to produce Makefile.in
1906 @c FIXME discuss putting a copyright into Makefile.am here? I would but
1907 @c I don't know quite what to say.
1909 @c FIXME document customary ordering of Makefile.am here!
1915 @cindex Non-GNU packages
1917 While Automake is intended to be used by maintainers of GNU packages, it
1918 does make some effort to accommodate those who wish to use it, but do
1919 not want to use all the GNU conventions.
1921 @cindex Strictness, defined
1922 @cindex Strictness, @option{foreign}
1923 @cindex @option{foreign} strictness
1924 @cindex Strictness, @option{gnu}
1925 @cindex @option{gnu} strictness
1926 @cindex Strictness, @option{gnits}
1927 @cindex @option{gnits} strictness
1929 To this end, Automake supports three levels of @dfn{strictness}---the
1930 strictness indicating how stringently Automake should check standards
1933 The valid strictness levels are:
1937 Automake will check for only those things that are absolutely
1938 required for proper operations. For instance, whereas GNU standards
1939 dictate the existence of a @file{NEWS} file, it will not be required in
1940 this mode. This strictness will also turn off some warnings by default
1941 (among them, portability warnings).
1942 The name comes from the fact that Automake is intended to be
1943 used for GNU programs; these relaxed rules are not the standard mode of
1947 Automake will check---as much as possible---for compliance to the GNU
1948 standards for packages. This is the default.
1951 Automake will check for compliance to the as-yet-unwritten @dfn{Gnits
1952 standards}. These are based on the GNU standards, but are even more
1953 detailed. Unless you are a Gnits standards contributor, it is
1954 recommended that you avoid this option until such time as the Gnits
1955 standard is actually published (which may never happen).
1958 @xref{Gnits}, for more information on the precise implications of the
1961 Automake also has a special ``cygnus'' mode that is similar to
1962 strictness but handled differently. This mode is useful for packages
1963 that are put into a ``Cygnus'' style tree (e.g., the GCC tree).
1964 @xref{Cygnus}, for more information on this mode.
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.test.
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.test.
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.test.
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.test.
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.test and specflg8.test.
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}.
2610 @itemx --force-missing
2611 @opindex --force-missing
2612 When used with @option{--add-missing}, causes standard files to be reinstalled
2613 even if they already exist in the source tree. This involves removing
2614 the file from the source tree before creating the new symlink (or, with
2615 @option{--copy}, copying the new file).
2619 Set the global strictness to @option{foreign}. For more information, see
2624 Set the global strictness to @option{gnits}. For more information, see
2629 Set the global strictness to @option{gnu}. For more information, see
2630 @ref{Gnits}. This is the default strictness.
2634 Print a summary of the command line options and exit.
2637 @itemx --ignore-deps
2639 This disables the dependency tracking feature in generated
2640 @file{Makefile}s; see @ref{Dependencies}.
2642 @item --include-deps
2643 @opindex --include-deps
2644 This enables the dependency tracking feature. This feature is enabled
2645 by default. This option is provided for historical reasons only and
2646 probably should not be used.
2650 Ordinarily @command{automake} creates all @file{Makefile.in}s mentioned in
2651 @file{configure.ac}. This option causes it to only update those
2652 @file{Makefile.in}s that are out of date with respect to one of their
2656 @itemx --output-dir=@var{dir}
2658 @opindex --output-dir
2659 Put the generated @file{Makefile.in} in the directory @var{dir}.
2660 Ordinarily each @file{Makefile.in} is created in the directory of the
2661 corresponding @file{Makefile.am}. This option is deprecated and will be
2662 removed in a future release.
2668 Cause Automake to print information about which files are being read or
2673 Print the version number of Automake and exit.
2676 @itemx --warnings=@var{category}
2679 Output warnings falling in @var{category}. @var{category} can be
2683 warnings related to the GNU Coding Standards
2684 (@pxref{Top, , , standards, The GNU Coding Standards}).
2686 obsolete features or constructions
2688 user redefinitions of Automake rules or variables
2690 portability issues (e.g., use of @command{make} features that are
2691 known to be not portable)
2692 @item extra-portability
2693 extra portability issues related to obscure tools. One example of such
2694 a tool is the Microsoft @command{lib} archiver.
2696 weird syntax, unused variables, typos
2698 unsupported or incomplete features
2702 turn off all the warnings
2704 treat warnings as errors
2707 A category can be turned off by prefixing its name with @samp{no-}. For
2708 instance, @option{-Wno-syntax} will hide the warnings about unused
2711 The categories output by default are @samp{syntax} and
2712 @samp{unsupported}. Additionally, @samp{gnu} and @samp{portability}
2713 are enabled in @option{--gnu} and @option{--gnits} strictness.
2714 On the other hand, the @option{silent-rules} options (@pxref{Options})
2715 turns off portability warnings about recursive variable expansions.
2717 @c Checked by extra-portability.test
2718 Turning off @samp{portability} will also turn off @samp{extra-portability},
2719 and similarly turning on @samp{extra-portability} will also turn on
2720 @samp{portability}. However, turning on @samp{portability} or turning
2721 off @samp{extra-portability} will not affect the other category.
2724 The environment variable @env{WARNINGS} can contain a comma separated
2725 list of categories to enable. It will be taken into account before the
2726 command-line switches, this way @option{-Wnone} will also ignore any
2727 warning category enabled by @env{WARNINGS}. This variable is also used
2728 by other tools like @command{autoconf}; unknown categories are ignored
2733 @vindex AUTOMAKE_JOBS
2734 If the environment variable @env{AUTOMAKE_JOBS} contains a positive
2735 number, it is taken as the maximum number of Perl threads to use in
2736 @command{automake} for generating multiple @file{Makefile.in} files
2737 concurrently. This is an experimental feature.
2741 @chapter Scanning @file{configure.ac}, using @command{aclocal}
2743 @cindex @file{configure.ac}, scanning
2744 @cindex Scanning @file{configure.ac}
2745 @cindex Using @command{aclocal}
2746 @cindex @command{aclocal}, using
2748 Automake scans the package's @file{configure.ac} to determine certain
2749 information about the package. Some @command{autoconf} macros are required
2750 and some variables must be defined in @file{configure.ac}. Automake
2751 will also use information from @file{configure.ac} to further tailor its
2754 Automake also supplies some Autoconf macros to make the maintenance
2755 easier. These macros can automatically be put into your
2756 @file{aclocal.m4} using the @command{aclocal} program.
2759 * Requirements:: Configuration requirements
2760 * Optional:: Other things Automake recognizes
2761 * aclocal Invocation:: Auto-generating aclocal.m4
2762 * Macros:: Autoconf macros supplied with Automake
2767 @section Configuration requirements
2769 @cindex Automake requirements
2770 @cindex Requirements of Automake
2772 @acindex AM_INIT_AUTOMAKE
2773 The one real requirement of Automake is that your @file{configure.ac}
2774 call @code{AM_INIT_AUTOMAKE}. This macro does several things that are
2775 required for proper Automake operation (@pxref{Macros}).
2777 Here are the other macros that Automake requires but which are not run
2778 by @code{AM_INIT_AUTOMAKE}:
2781 @item AC_CONFIG_FILES
2783 @acindex AC_CONFIG_FILES
2785 These two macros are usually invoked as follows near the end of
2786 @file{configure.ac}.
2800 Automake uses these to determine which files to create (@pxref{Output, ,
2801 Creating Output Files, autoconf, The Autoconf Manual}). A listed file
2802 is considered to be an Automake generated @file{Makefile} if there
2803 exists a file with the same name and the @file{.am} extension appended.
2804 Typically, @samp{AC_CONFIG_FILES([foo/Makefile])} will cause Automake to
2805 generate @file{foo/Makefile.in} if @file{foo/Makefile.am} exists.
2807 When using @code{AC_CONFIG_FILES} with multiple input files, as in
2810 AC_CONFIG_FILES([Makefile:top.in:Makefile.in:bot.in])
2814 @command{automake} will generate the first @file{.in} input file for
2815 which a @file{.am} file exists. If no such file exists the output
2816 file is not considered to be generated by Automake.
2818 Files created by @code{AC_CONFIG_FILES}, be they Automake
2819 @file{Makefile}s or not, are all removed by @samp{make distclean}.
2820 Their inputs are automatically distributed, unless they
2821 are the output of prior @code{AC_CONFIG_FILES} commands.
2822 Finally, rebuild rules are generated in the Automake @file{Makefile}
2823 existing in the subdirectory of the output file, if there is one, or
2824 in the top-level @file{Makefile} otherwise.
2826 The above machinery (cleaning, distributing, and rebuilding) works
2827 fine if the @code{AC_CONFIG_FILES} specifications contain only
2828 literals. If part of the specification uses shell variables,
2829 @command{automake} will not be able to fulfill this setup, and you will
2830 have to complete the missing bits by hand. For instance, on
2832 @c Keep in sync with output11.test.
2836 AC_CONFIG_FILES([output:$file],, [file=$file])
2840 @command{automake} will output rules to clean @file{output}, and
2841 rebuild it. However the rebuild rule will not depend on @file{input},
2842 and this file will not be distributed either. (You must add
2843 @samp{EXTRA_DIST = input} to your @file{Makefile.am} if @file{input} is a
2848 @c Keep in sync with output11.test.
2853 AC_CONFIG_FILES([$file:input],, [file=$file])
2854 AC_CONFIG_FILES([$file2],, [file2=$file2])
2858 will only cause @file{input} to be distributed. No file will be
2859 cleaned automatically (add @samp{DISTCLEANFILES = output out}
2860 yourself), and no rebuild rule will be output.
2862 Obviously @command{automake} cannot guess what value @samp{$file} is
2863 going to hold later when @file{configure} is run, and it cannot use
2864 the shell variable @samp{$file} in a @file{Makefile}. However, if you
2865 make reference to @samp{$file} as @samp{$@{file@}} (i.e., in a way
2866 that is compatible with @command{make}'s syntax) and furthermore use
2867 @code{AC_SUBST} to ensure that @samp{$@{file@}} is meaningful in a
2868 @file{Makefile}, then @command{automake} will be able to use
2869 @samp{$@{file@}} to generate all these rules. For instance, here is
2870 how the Automake package itself generates versioned scripts for its
2874 AC_SUBST([APIVERSION], @dots{})
2877 [tests/aclocal-$@{APIVERSION@}:tests/aclocal.in],
2878 [chmod +x tests/aclocal-$@{APIVERSION@}],
2879 [APIVERSION=$APIVERSION])
2881 [tests/automake-$@{APIVERSION@}:tests/automake.in],
2882 [chmod +x tests/automake-$@{APIVERSION@}])
2886 Here cleaning, distributing, and rebuilding are done automatically,
2887 because @samp{$@{APIVERSION@}} is known at @command{make}-time.
2889 Note that you should not use shell variables to declare
2890 @file{Makefile} files for which @command{automake} must create
2891 @file{Makefile.in}. Even @code{AC_SUBST} does not help here, because
2892 @command{automake} needs to know the file name when it runs in order
2893 to check whether @file{Makefile.am} exists. (In the very hairy case
2894 that your setup requires such use of variables, you will have to tell
2895 Automake which @file{Makefile.in}s to generate on the command-line.)
2897 It is possible to let @command{automake} emit conditional rules for
2898 @code{AC_CONFIG_FILES} with the help of @code{AM_COND_IF}
2904 Use literals for @file{Makefile}s, and for other files whenever possible.
2906 Use @samp{$file} (or @samp{$@{file@}} without @samp{AC_SUBST([file])})
2907 for files that @command{automake} should ignore.
2909 Use @samp{$@{file@}} and @samp{AC_SUBST([file])} for files
2910 that @command{automake} should not ignore.
2917 @section Other things Automake recognizes
2919 @cindex Macros Automake recognizes
2920 @cindex Recognized macros by Automake
2922 Every time Automake is run it calls Autoconf to trace
2923 @file{configure.ac}. This way it can recognize the use of certain
2924 macros and tailor the generated @file{Makefile.in} appropriately.
2925 Currently recognized macros and their effects are:
2928 @item AC_CANONICAL_BUILD
2929 @itemx AC_CANONICAL_HOST
2930 @itemx AC_CANONICAL_TARGET
2931 @vindex build_triplet
2932 @vindex host_triplet
2933 @vindex target_triplet
2934 Automake will ensure that @file{config.guess} and @file{config.sub}
2935 exist. Also, the @file{Makefile} variables @code{build_triplet},
2936 @code{host_triplet} and @code{target_triplet} are introduced. See
2937 @ref{Canonicalizing, , Getting the Canonical System Type, autoconf,
2938 The Autoconf Manual}.
2940 @item AC_CONFIG_AUX_DIR
2941 Automake will look for various helper scripts, such as
2942 @file{install-sh}, in the directory named in this macro invocation.
2943 @c This list is accurate relative to version 1.11
2944 (The full list of scripts is:
2946 @file{config.guess},
2955 @file{mkinstalldirs},
2960 Not all scripts are always searched for; some scripts
2961 will only be sought if the generated @file{Makefile.in} requires them.
2963 If @code{AC_CONFIG_AUX_DIR} is not given, the scripts are looked for in
2964 their standard locations. For @file{mdate-sh},
2965 @file{texinfo.tex}, and @file{ylwrap}, the standard location is the
2966 source directory corresponding to the current @file{Makefile.am}. For
2967 the rest, the standard location is the first one of @file{.}, @file{..},
2968 or @file{../..} (relative to the top source directory) that provides any
2969 one of the helper scripts. @xref{Input, , Finding `configure' Input,
2970 autoconf, The Autoconf Manual}.
2972 Required files from @code{AC_CONFIG_AUX_DIR} are automatically
2973 distributed, even if there is no @file{Makefile.am} in this directory.
2975 @item AC_CONFIG_LIBOBJ_DIR
2976 Automake will require the sources file declared with
2977 @code{AC_LIBSOURCE} (see below) in the directory specified by this
2980 @item AC_CONFIG_HEADERS
2981 Automake will generate rules to rebuild these headers. Older versions
2982 of Automake required the use of @code{AM_CONFIG_HEADER}
2983 (@pxref{Macros}); this is no longer the case.
2985 As with @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the
2986 specification using shell variables will be ignored as far as
2987 cleaning, distributing, and rebuilding is concerned.
2989 @item AC_CONFIG_LINKS
2990 Automake will generate rules to remove @file{configure} generated
2991 links on @samp{make distclean} and to distribute named source files as
2992 part of @samp{make dist}.
2994 As for @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the
2995 specification using shell variables will be ignored as far as cleaning
2996 and distributing is concerned. (There are no rebuild rules for links.)
3000 @itemx AC_LIBSOURCES
3002 Automake will automatically distribute any file listed in
3003 @code{AC_LIBSOURCE} or @code{AC_LIBSOURCES}.
3005 Note that the @code{AC_LIBOBJ} macro calls @code{AC_LIBSOURCE}. So if
3006 an Autoconf macro is documented to call @samp{AC_LIBOBJ([file])}, then
3007 @file{file.c} will be distributed automatically by Automake. This
3008 encompasses many macros like @code{AC_FUNC_ALLOCA},
3009 @code{AC_FUNC_MEMCMP}, @code{AC_REPLACE_FUNCS}, and others.
3011 By the way, direct assignments to @code{LIBOBJS} are no longer
3012 supported. You should always use @code{AC_LIBOBJ} for this purpose.
3013 @xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs.@: @code{LIBOBJS},
3014 autoconf, The Autoconf Manual}.
3016 @item AC_PROG_RANLIB
3017 This is required if any libraries are built in the package.
3018 @xref{Particular Programs, , Particular Program Checks, autoconf, The
3022 This is required if any C++ source is included. @xref{Particular
3023 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
3026 This is required if any Objective C source is included. @xref{Particular
3027 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
3030 This is required if any Fortran 77 source is included. This macro is
3031 distributed with Autoconf version 2.13 and later. @xref{Particular
3032 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
3034 @item AC_F77_LIBRARY_LDFLAGS
3035 This is required for programs and shared libraries that are a mixture of
3036 languages that include Fortran 77 (@pxref{Mixing Fortran 77 With C and
3037 C++}). @xref{Macros, , Autoconf macros supplied with Automake}.
3040 Automake will add the flags computed by @code{AC_FC_SRCEXT} to compilation
3041 of files with the respective source extension (@pxref{Fortran Compiler, ,
3042 Fortran Compiler Characteristics, autoconf, The Autoconf Manual}).
3045 This is required if any Fortran 90/95 source is included. This macro is
3046 distributed with Autoconf version 2.58 and later. @xref{Particular
3047 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
3049 @item AC_PROG_LIBTOOL
3050 Automake will turn on processing for @command{libtool} (@pxref{Top, ,
3051 Introduction, libtool, The Libtool Manual}).
3055 If a Yacc source file is seen, then you must either use this macro or
3056 define the variable @code{YACC} in @file{configure.ac}. The former is
3057 preferred (@pxref{Particular Programs, , Particular Program Checks,
3058 autoconf, The Autoconf Manual}).
3061 If a Lex source file is seen, then this macro must be used.
3062 @xref{Particular Programs, , Particular Program Checks, autoconf, The
3065 @item AC_REQUIRE_AUX_FILE
3066 For each @code{AC_REQUIRE_AUX_FILE([@var{file}])},
3067 @command{automake} will ensure that @file{@var{file}} exists in the
3068 aux directory, and will complain otherwise. It
3069 will also automatically distribute the file. This macro should be
3070 used by third-party Autoconf macros that require some supporting
3071 files in the aux directory specified with @code{AC_CONFIG_AUX_DIR}
3072 above. @xref{Input, , Finding @command{configure} Input, autoconf,
3073 The Autoconf Manual}.
3076 The first argument is automatically defined as a variable in each
3077 generated @file{Makefile.in}, unless @code{AM_SUBST_NOTMAKE} is also
3078 used for this variable. @xref{Setting Output Variables, , Setting
3079 Output Variables, autoconf, The Autoconf Manual}.
3081 For every substituted variable @var{var}, @command{automake} will add
3082 a line @code{@var{var} = @var{value}} to each @file{Makefile.in} file.
3083 Many Autoconf macros invoke @code{AC_SUBST} to set output variables
3084 this way, e.g., @code{AC_PATH_XTRA} defines @code{X_CFLAGS} and
3085 @code{X_LIBS}. Thus, you can access these variables as
3086 @code{$(X_CFLAGS)} and @code{$(X_LIBS)} in any @file{Makefile.am}
3087 if @code{AC_PATH_XTRA} is called.
3089 @item AM_CONDITIONAL
3090 This introduces an Automake conditional (@pxref{Conditionals}).
3093 This macro allows @code{automake} to detect subsequent access within
3094 @file{configure.ac} to a conditional previously introduced with
3095 @code{AM_CONDITIONAL}, thus enabling conditional @code{AC_CONFIG_FILES}
3096 (@pxref{Usage of Conditionals}).
3098 @item AM_GNU_GETTEXT
3099 This macro is required for packages that use GNU gettext
3100 (@pxref{gettext}). It is distributed with gettext. If Automake sees
3101 this macro it ensures that the package meets some of gettext's
3104 @item AM_GNU_GETTEXT_INTL_SUBDIR
3105 This macro specifies that the @file{intl/} subdirectory is to be built,
3106 even if the @code{AM_GNU_GETTEXT} macro was invoked with a first argument
3109 @item AM_MAINTAINER_MODE(@ovar{default-mode})
3110 @opindex --enable-maintainer-mode
3111 @opindex --disable-maintainer-mode
3112 This macro adds an @option{--enable-maintainer-mode} option to
3113 @command{configure}. If this is used, @command{automake} will cause
3114 ``maintainer-only'' rules to be turned off by default in the
3115 generated @file{Makefile.in}s, unless @var{default-mode} is
3116 @samp{enable}. This macro defines the @code{MAINTAINER_MODE}
3117 conditional, which you can use in your own @file{Makefile.am}.
3118 @xref{maintainer-mode}.
3120 @item AM_SUBST_NOTMAKE(@var{var})
3121 Prevent Automake from defining a variable @var{var}, even if it is
3122 substituted by @command{config.status}. Normally, Automake defines a
3123 @command{make} variable for each @command{configure} substitution,
3124 i.e., for each @code{AC_SUBST([@var{var}])}. This macro prevents that
3125 definition from Automake. If @code{AC_SUBST} has not been called
3126 for this variable, then @code{AM_SUBST_NOTMAKE} has no effects.
3127 Preventing variable definitions may be useful for substitution of
3128 multi-line values, where @code{@var{var} = @@@var{value}@@} might yield
3132 Files included by @file{configure.ac} using this macro will be
3133 detected by Automake and automatically distributed. They will also
3134 appear as dependencies in @file{Makefile} rules.
3136 @code{m4_include} is seldom used by @file{configure.ac} authors, but
3137 can appear in @file{aclocal.m4} when @command{aclocal} detects that
3138 some required macros come from files local to your package (as opposed to
3139 macros installed in a system-wide directory, @pxref{aclocal Invocation}).
3143 @node aclocal Invocation
3144 @section Auto-generating aclocal.m4
3145 @c This node used to be named "Invoking automake". This @anchor
3146 @c allows old links to still work.
3147 @anchor{Invoking aclocal}
3149 @cindex Invocation of @command{aclocal}
3150 @cindex @command{aclocal}, Invocation
3151 @cindex Invoking @command{aclocal}
3152 @cindex @command{aclocal}, Invoking
3154 Automake includes a number of Autoconf macros that can be used in
3155 your package (@pxref{Macros}); some of them are actually required by
3156 Automake in certain situations. These macros must be defined in your
3157 @file{aclocal.m4}; otherwise they will not be seen by
3160 The @command{aclocal} program will automatically generate
3161 @file{aclocal.m4} files based on the contents of @file{configure.ac}.
3162 This provides a convenient way to get Automake-provided macros,
3163 without having to search around. The @command{aclocal} mechanism
3164 allows other packages to supply their own macros (@pxref{Extending
3165 aclocal}). You can also use it to maintain your own set of custom
3166 macros (@pxref{Local Macros}).
3168 At startup, @command{aclocal} scans all the @file{.m4} files it can
3169 find, looking for macro definitions (@pxref{Macro Search Path}). Then
3170 it scans @file{configure.ac}. Any mention of one of the macros found
3171 in the first step causes that macro, and any macros it in turn
3172 requires, to be put into @file{aclocal.m4}.
3174 @emph{Putting} the file that contains the macro definition into
3175 @file{aclocal.m4} is usually done by copying the entire text of this
3176 file, including unused macro definitions as well as both @samp{#} and
3177 @samp{dnl} comments. If you want to make a comment that will be
3178 completely ignored by @command{aclocal}, use @samp{##} as the comment
3181 When a file selected by @command{aclocal} is located in a subdirectory
3182 specified as a relative search path with @command{aclocal}'s @option{-I}
3183 argument, @command{aclocal} assumes the file belongs to the package
3184 and uses @code{m4_include} instead of copying it into
3185 @file{aclocal.m4}. This makes the package smaller, eases dependency
3186 tracking, and cause the file to be distributed automatically.
3187 (@xref{Local Macros}, for an example.) Any macro that is found in a
3188 system-wide directory, or via an absolute search path will be copied.
3189 So use @samp{-I `pwd`/reldir} instead of @samp{-I reldir} whenever
3190 some relative directory should be considered outside the package.
3192 The contents of @file{acinclude.m4}, if this file exists, are also
3193 automatically included in @file{aclocal.m4}. We recommend against
3194 using @file{acinclude.m4} in new packages (@pxref{Local Macros}).
3198 While computing @file{aclocal.m4}, @command{aclocal} runs
3199 @command{autom4te} (@pxref{Using autom4te, , Using @command{Autom4te},
3200 autoconf, The Autoconf Manual}) in order to trace the macros that are
3201 really used, and omit from @file{aclocal.m4} all macros that are
3202 mentioned but otherwise unexpanded (this can happen when a macro is
3203 called conditionally). @command{autom4te} is expected to be in the
3204 @env{PATH}, just as @command{autoconf}. Its location can be
3205 overridden using the @env{AUTOM4TE} environment variable.
3208 * aclocal Options:: Options supported by aclocal
3209 * Macro Search Path:: How aclocal finds .m4 files
3210 * Extending aclocal:: Writing your own aclocal macros
3211 * Local Macros:: Organizing local macros
3212 * Serials:: Serial lines in Autoconf macros
3213 * Future of aclocal:: aclocal's scheduled death
3216 @node aclocal Options
3217 @subsection aclocal Options
3219 @cindex @command{aclocal}, Options
3220 @cindex Options, @command{aclocal}
3222 @command{aclocal} accepts the following options:
3225 @item --automake-acdir=@var{dir}
3226 @opindex --automake-acdir
3227 Look for the automake-provided macro files in @var{dir} instead of
3228 in the installation directory. This is typically used for debugging.
3230 @item --system-acdir=@var{dir}
3231 @opindex --system-acdir
3232 Look for the system-wide third-party macro files (and the special
3233 @file{dirlist} file) in @var{dir} instead of in the installation
3234 directory. This is typically used for debugging.
3236 @item --diff[=@var{command}]
3238 Run @var{command} on M4 file that would be installed or overwritten
3239 by @option{--install}. The default @var{command} is @samp{diff -u}.
3240 This option implies @option{--install} and @option{--dry-run}.
3244 Do not actually overwrite (or create) @file{aclocal.m4} and M4
3245 files installed by @option{--install}.
3249 Print a summary of the command line options and exit.
3253 Add the directory @var{dir} to the list of directories searched for
3258 Install system-wide third-party macros into the first directory
3259 specified with @samp{-I @var{dir}} instead of copying them in the
3261 @c The following semantics is checked by `aclocal-install-absdir.test'.
3262 Note that this will happen also if @var{dir} is an absolute path.
3264 @cindex serial number and @option{--install}
3265 When this option is used, and only when this option is used,
3266 @command{aclocal} will also honor @samp{#serial @var{number}} lines
3267 that appear in macros: an M4 file is ignored if there exists another
3268 M4 file with the same basename and a greater serial number in the
3269 search path (@pxref{Serials}).
3273 Always overwrite the output file. The default is to overwrite the output
3274 file only when really needed, i.e., when its contents changes or if one
3275 of its dependencies is younger.
3277 This option forces the update of @file{aclocal.m4} (or the file
3278 specified with @file{--output} below) and only this file, it has
3279 absolutely no influence on files that may need to be installed by
3282 @item --output=@var{file}
3284 Cause the output to be put into @var{file} instead of @file{aclocal.m4}.
3286 @item --print-ac-dir
3287 @opindex --print-ac-dir
3288 Prints the name of the directory that @command{aclocal} will search to
3289 find third-party @file{.m4} files. When this option is given, normal
3290 processing is suppressed. This option was used @emph{in the past} by
3291 third-party packages to determine where to install @file{.m4} macro
3292 files, but @emph{this usage is today discouraged}, since it causes
3293 @samp{$(prefix)} not to be thoroughly honoured (which violates the
3294 GNU Coding Standards), and a similar semantics can be better obtained
3295 with the @env{ACLOCAL_PATH} environment variable; @pxref{Extending aclocal}.
3299 Print the names of the files it examines.
3303 Print the version number of Automake and exit.
3306 @item --warnings=@var{category}
3309 Output warnings falling in @var{category}. @var{category} can be
3313 dubious syntactic constructs, underquoted macros, unused macros, etc.
3317 all the warnings, this is the default
3319 turn off all the warnings
3321 treat warnings as errors
3324 All warnings are output by default.
3327 The environment variable @env{WARNINGS} is honored in the same
3328 way as it is for @command{automake} (@pxref{automake Invocation}).
3332 @node Macro Search Path
3333 @subsection Macro Search Path
3335 @cindex Macro search path
3336 @cindex @command{aclocal} search path
3338 By default, @command{aclocal} searches for @file{.m4} files in the following
3339 directories, in this order:
3342 @item @var{acdir-APIVERSION}
3343 This is where the @file{.m4} macros distributed with Automake itself
3344 are stored. @var{APIVERSION} depends on the Automake release used;
3345 for example, for Automake 1.11.x, @var{APIVERSION} = @code{1.11}.
3348 This directory is intended for third party @file{.m4} files, and is
3349 configured when @command{automake} itself is built. This is
3350 @file{@@datadir@@/aclocal/}, which typically
3351 expands to @file{$@{prefix@}/share/aclocal/}. To find the compiled-in
3352 value of @var{acdir}, use the @option{--print-ac-dir} option
3353 (@pxref{aclocal Options}).
3356 As an example, suppose that @command{automake-1.11.2} was configured with
3357 @option{--prefix=@-/usr/local}. Then, the search path would be:
3360 @item @file{/usr/local/share/aclocal-1.11.2/}
3361 @item @file{/usr/local/share/aclocal/}
3364 The paths for the @var{acdir} and @var{acdir-APIVERSION} directories can
3365 be changed respectively through aclocal options @option{--system-acdir}
3366 and @option{--automake-acdir} (@pxref{aclocal Options}). Note however
3367 that these options are only intended for use by the internal Automake
3368 test suite, or for debugging under highly unusual situations; they are
3369 not ordinarily needed by end-users.
3371 As explained in (@pxref{aclocal Options}), there are several options that
3372 can be used to change or extend this search path.
3374 @subsubheading Modifying the Macro Search Path: @samp{-I @var{dir}}
3376 Any extra directories specified using @option{-I} options
3377 (@pxref{aclocal Options}) are @emph{prepended} to this search list. Thus,
3378 @samp{aclocal -I /foo -I /bar} results in the following search path:
3383 @item @var{acdir}-@var{APIVERSION}
3387 @subsubheading Modifying the Macro Search Path: @file{dirlist}
3388 @cindex @file{dirlist}
3390 There is a third mechanism for customizing the search path. If a
3391 @file{dirlist} file exists in @var{acdir}, then that file is assumed to
3392 contain a list of directory patterns, one per line. @command{aclocal}
3393 expands these patterns to directory names, and adds them to the search
3394 list @emph{after} all other directories. @file{dirlist} entries may
3395 use shell wildcards such as @samp{*}, @samp{?}, or @code{[...]}.
3397 For example, suppose
3398 @file{@var{acdir}/dirlist} contains the following:
3407 and that @command{aclocal} was called with the @samp{-I /foo -I /bar} options.
3408 Then, the search path would be
3410 @c @code looks better than @file here
3414 @item @var{acdir}-@var{APIVERSION}
3421 and all directories with path names starting with @code{/test3}.
3423 If the @option{--system-acdir=@var{dir}} option is used, then
3424 @command{aclocal} will search for the @file{dirlist} file in
3425 @var{dir}; but remember the warnings above against the use of
3426 @option{--system-acdir}.
3428 @file{dirlist} is useful in the following situation: suppose that
3429 @command{automake} version @code{1.11.2} is installed with
3430 @samp{--prefix=/usr} by the system vendor. Thus, the default search
3433 @c @code looks better than @file here
3435 @item @code{/usr/share/aclocal-1.11/}
3436 @item @code{/usr/share/aclocal/}
3439 However, suppose further that many packages have been manually
3440 installed on the system, with $prefix=/usr/local, as is typical. In
3441 that case, many of these ``extra'' @file{.m4} files are in
3442 @file{/usr/local/share/aclocal}. The only way to force
3443 @file{/usr/bin/aclocal} to find these ``extra'' @file{.m4} files is to
3444 always call @samp{aclocal -I /usr/local/share/aclocal}. This is
3445 inconvenient. With @file{dirlist}, one may create a file
3446 @file{/usr/share/aclocal/dirlist} containing only the single line
3449 /usr/local/share/aclocal
3452 Now, the ``default'' search path on the affected system is
3454 @c @code looks better than @file here
3456 @item @code{/usr/share/aclocal-1.11/}
3457 @item @code{/usr/share/aclocal/}
3458 @item @code{/usr/local/share/aclocal/}
3461 without the need for @option{-I} options; @option{-I} options can be reserved
3462 for project-specific needs (@file{my-source-dir/m4/}), rather than
3463 using it to work around local system-dependent tool installation
3466 Similarly, @file{dirlist} can be handy if you have installed a local
3467 copy of Automake in your account and want @command{aclocal} to look for
3468 macros installed at other places on the system.
3470 @anchor{ACLOCAL_PATH}
3471 @subsubheading Modifying the Macro Search Path: @file{ACLOCAL_PATH}
3472 @cindex @env{ACLOCAL_PATH}
3474 The fourth and last mechanism to customize the macro search path is
3475 also the simplest. Any directory included in the colon-separated
3476 environment variable @env{ACLOCAL_PATH} is added to the search path
3477 @c Keep in sync with aclocal-path-precedence.test.
3478 and takes precedence over system directories (including those found via
3479 @file{dirlist}), with the exception of the versioned directory
3480 @var{acdir-APIVERSION} (@pxref{Macro Search Path}). However, directories
3481 passed via @option{-I} will take precedence over directories in
3484 @c Keep in sync with aclocal-path-installed.test.
3485 Also note that, if the @option{--install} option is used, any @file{.m4}
3486 file containing a required macro that is found in a directory listed in
3487 @env{ACLOCAL_PATH} will be installed locally.
3488 @c Keep in sync with aclocal-path-installed-serial.test.
3489 In this case, serial numbers in @file{.m4} are honoured too,
3492 Conversely to @file{dirlist}, @env{ACLOCAL_PATH} is useful if you are
3493 using a global copy of Automake and want @command{aclocal} to look for
3494 macros somewhere under your home directory.
3496 @subsubheading Planned future incompatibilities
3498 The order in which the directories in the macro search path are currently
3499 looked up is confusing and/or suboptimal in various aspects, and is
3500 probably going to be changed in the future Automake release. In
3501 particular, directories in @env{ACLOCAL_PATH} and @file{@var{acdir}}
3502 might end up taking precedence over @file{@var{acdir-APIVERSION}}, and
3503 directories in @file{@var{acdir}/dirlist} might end up taking precedence
3504 over @file{@var{acdir}}. @emph{This is a possible future incompatibility!}
3506 @node Extending aclocal
3507 @subsection Writing your own aclocal macros
3509 @cindex @command{aclocal}, extending
3510 @cindex Extending @command{aclocal}
3512 The @command{aclocal} program doesn't have any built-in knowledge of any
3513 macros, so it is easy to extend it with your own macros.
3515 This can be used by libraries that want to supply their own Autoconf
3516 macros for use by other programs. For instance, the @command{gettext}
3517 library supplies a macro @code{AM_GNU_GETTEXT} that should be used by
3518 any package using @command{gettext}. When the library is installed, it
3519 installs this macro so that @command{aclocal} will find it.
3521 A macro file's name should end in @file{.m4}. Such files should be
3522 installed in @file{$(datadir)/aclocal}. This is as simple as writing:
3524 @c Keep in sync with primary-prefix-couples-documented-valid.test.
3526 aclocaldir = $(datadir)/aclocal
3527 aclocal_DATA = mymacro.m4 myothermacro.m4
3531 Please do use @file{$(datadir)/aclocal}, and not something based on
3532 the result of @samp{aclocal --print-ac-dir} (@pxref{Hard-Coded Install
3533 Paths}, for arguments). It might also be helpful to suggest to
3534 the user to add the @file{$(datadir)/aclocal} directory to his
3535 @env{ACLOCAL_PATH} variable (@pxref{ACLOCAL_PATH}) so that
3536 @command{aclocal} will find the @file{.m4} files installed by your
3537 package automatically.
3539 A file of macros should be a series of properly quoted
3540 @code{AC_DEFUN}'s (@pxref{Macro Definitions, , , autoconf, The
3541 Autoconf Manual}). The @command{aclocal} programs also understands
3542 @code{AC_REQUIRE} (@pxref{Prerequisite Macros, , , autoconf, The
3543 Autoconf Manual}), so it is safe to put each macro in a separate file.
3544 Each file should have no side effects but macro definitions.
3545 Especially, any call to @code{AC_PREREQ} should be done inside the
3546 defined macro, not at the beginning of the file.
3548 @cindex underquoted @code{AC_DEFUN}
3552 Starting with Automake 1.8, @command{aclocal} will warn about all
3553 underquoted calls to @code{AC_DEFUN}. We realize this will annoy a
3554 lot of people, because @command{aclocal} was not so strict in the past
3555 and many third party macros are underquoted; and we have to apologize
3556 for this temporary inconvenience. The reason we have to be stricter
3557 is that a future implementation of @command{aclocal} (@pxref{Future of
3558 aclocal}) will have to temporarily include all these third party
3559 @file{.m4} files, maybe several times, including even files that are
3560 not actually needed. Doing so should alleviate many problems of the
3561 current implementation, however it requires a stricter style from the
3562 macro authors. Hopefully it is easy to revise the existing macros.
3569 [AC_REQUIRE([AX_SOMETHING])dnl
3576 should be rewritten as
3579 AC_DEFUN([AX_FOOBAR],
3580 [AC_PREREQ([2.57])dnl
3581 AC_REQUIRE([AX_SOMETHING])dnl
3587 Wrapping the @code{AC_PREREQ} call inside the macro ensures that
3588 Autoconf 2.57 will not be required if @code{AX_FOOBAR} is not actually
3589 used. Most importantly, quoting the first argument of @code{AC_DEFUN}
3590 allows the macro to be redefined or included twice (otherwise this
3591 first argument would be expanded during the second definition). For
3592 consistency we like to quote even arguments such as @code{2.57} that
3595 If you have been directed here by the @command{aclocal} diagnostic but
3596 are not the maintainer of the implicated macro, you will want to
3597 contact the maintainer of that macro. Please make sure you have the
3598 latest version of the macro and that the problem hasn't already been
3599 reported before doing so: people tend to work faster when they aren't
3602 Another situation where @command{aclocal} is commonly used is to
3603 manage macros that are used locally by the package, @ref{Local
3607 @subsection Handling Local Macros
3609 Feature tests offered by Autoconf do not cover all needs. People
3610 often have to supplement existing tests with their own macros, or
3611 with third-party macros.
3613 There are two ways to organize custom macros in a package.
3615 The first possibility (the historical practice) is to list all your
3616 macros in @file{acinclude.m4}. This file will be included in
3617 @file{aclocal.m4} when you run @command{aclocal}, and its macro(s) will
3618 henceforth be visible to @command{autoconf}. However if it contains
3619 numerous macros, it will rapidly become difficult to maintain, and it
3620 will be almost impossible to share macros between packages.
3622 @vindex ACLOCAL_AMFLAGS
3623 The second possibility, which we do recommend, is to write each macro
3624 in its own file and gather all these files in a directory. This
3625 directory is usually called @file{m4/}. To build @file{aclocal.m4},
3626 one should therefore instruct @command{aclocal} to scan @file{m4/}.
3627 From the command line, this is done with @samp{aclocal -I m4}. The
3628 top-level @file{Makefile.am} should also be updated to define
3631 ACLOCAL_AMFLAGS = -I m4
3634 @code{ACLOCAL_AMFLAGS} contains options to pass to @command{aclocal}
3635 when @file{aclocal.m4} is to be rebuilt by @command{make}. This line is
3636 also used by @command{autoreconf} (@pxref{autoreconf Invocation, ,
3637 Using @command{autoreconf} to Update @file{configure} Scripts,
3638 autoconf, The Autoconf Manual}) to run @command{aclocal} with suitable
3639 options, or by @command{autopoint} (@pxref{autopoint Invocation, ,
3640 Invoking the @command{autopoint} Program, gettext, GNU gettext tools})
3641 and @command{gettextize} (@pxref{gettextize Invocation, , Invoking the
3642 @command{gettextize} Program, gettext, GNU gettext tools}) to locate
3643 the place where Gettext's macros should be installed. So even if you
3644 do not really care about the rebuild rules, you should define
3645 @code{ACLOCAL_AMFLAGS}.
3647 When @samp{aclocal -I m4} is run, it will build an @file{aclocal.m4}
3648 that @code{m4_include}s any file from @file{m4/} that defines a
3649 required macro. Macros not found locally will still be searched in
3650 system-wide directories, as explained in @ref{Macro Search Path}.
3652 Custom macros should be distributed for the same reason that
3653 @file{configure.ac} is: so that other people have all the sources of
3654 your package if they want to work on it. Actually, this distribution
3655 happens automatically because all @code{m4_include}d files are
3658 However there is no consensus on the distribution of third-party
3659 macros that your package may use. Many libraries install their own
3660 macro in the system-wide @command{aclocal} directory (@pxref{Extending
3661 aclocal}). For instance, Guile ships with a file called
3662 @file{guile.m4} that contains the macro @code{GUILE_FLAGS} that can
3663 be used to define setup compiler and linker flags appropriate for
3664 using Guile. Using @code{GUILE_FLAGS} in @file{configure.ac} will
3665 cause @command{aclocal} to copy @file{guile.m4} into
3666 @file{aclocal.m4}, but as @file{guile.m4} is not part of the project,
3667 it will not be distributed. Technically, that means a user who
3668 needs to rebuild @file{aclocal.m4} will have to install Guile first.
3669 This is probably OK, if Guile already is a requirement to build the
3670 package. However, if Guile is only an optional feature, or if your
3671 package might run on architectures where Guile cannot be installed,
3672 this requirement will hinder development. An easy solution is to copy
3673 such third-party macros in your local @file{m4/} directory so they get
3676 Since Automake 1.10, @command{aclocal} offers an option to copy these
3677 system-wide third-party macros in your local macro directory, solving
3678 the above problem. Simply use:
3681 ACLOCAL_AMFLAGS = -I m4 --install
3685 With this setup, system-wide macros will be copied to @file{m4/}
3686 the first time you run @command{autoreconf}. Then the locally
3687 installed macros will have precedence over the system-wide installed
3688 macros each time @command{aclocal} is run again.
3690 One reason why you should keep @option{--install} in the flags even
3691 after the first run is that when you later edit @file{configure.ac}
3692 and depend on a new macro, this macro will be installed in your
3693 @file{m4/} automatically. Another one is that serial numbers
3694 (@pxref{Serials}) can be used to update the macros in your source tree
3695 automatically when new system-wide versions are installed. A serial
3696 number should be a single line of the form
3703 where @var{nnn} contains only digits and dots. It should appear in
3704 the M4 file before any macro definition. It is a good practice to
3705 maintain a serial number for each macro you distribute, even if you do
3706 not use the @option{--install} option of @command{aclocal}: this allows
3707 other people to use it.
3711 @subsection Serial Numbers
3712 @cindex serial numbers in macros
3713 @cindex macro serial numbers
3714 @cindex @code{#serial} syntax
3715 @cindex @command{aclocal} and serial numbers
3717 Because third-party macros defined in @file{*.m4} files are naturally
3718 shared between multiple projects, some people like to version them.
3719 This makes it easier to tell which of two M4 files is newer. Since at
3720 least 1996, the tradition is to use a @samp{#serial} line for this.
3722 A serial number should be a single line of the form
3725 # serial @var{version}
3729 where @var{version} is a version number containing only digits and
3730 dots. Usually people use a single integer, and they increment it each
3731 time they change the macro (hence the name of ``serial''). Such a
3732 line should appear in the M4 file before any macro definition.
3734 The @samp{#} must be the first character on the line,
3735 and it is OK to have extra words after the version, as in
3738 #serial @var{version} @var{garbage}
3741 Normally these serial numbers are completely ignored by
3742 @command{aclocal} and @command{autoconf}, like any genuine comment.
3743 However when using @command{aclocal}'s @option{--install} feature, these
3744 serial numbers will modify the way @command{aclocal} selects the
3745 macros to install in the package: if two files with the same basename
3746 exist in your search path, and if at least one of them uses a
3747 @samp{#serial} line, @command{aclocal} will ignore the file that has
3748 the older @samp{#serial} line (or the file that has none).
3750 Note that a serial number applies to a whole M4 file, not to any macro
3751 it contains. A file can contains multiple macros, but only one
3754 Here is a use case that illustrates the use of @option{--install} and
3755 its interaction with serial numbers. Let's assume we maintain a
3756 package called MyPackage, the @file{configure.ac} of which requires a
3757 third-party macro @code{AX_THIRD_PARTY} defined in
3758 @file{/usr/share/aclocal/thirdparty.m4} as follows:
3762 AC_DEFUN([AX_THIRD_PARTY], [...])
3765 MyPackage uses an @file{m4/} directory to store local macros as
3766 explained in @ref{Local Macros}, and has
3769 ACLOCAL_AMFLAGS = -I m4 --install
3773 in its top-level @file{Makefile.am}.
3775 Initially the @file{m4/} directory is empty. The first time we run
3776 @command{autoreconf}, it will fetch the options to pass to
3777 @command{aclocal} in @file{Makefile.am}, and run @samp{aclocal -I m4
3778 --install}. @command{aclocal} will notice that
3782 @file{configure.ac} uses @code{AX_THIRD_PARTY}
3784 No local macros define @code{AX_THIRD_PARTY}
3786 @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3791 Because @file{/usr/share/aclocal/thirdparty.m4} is a system-wide macro
3792 and @command{aclocal} was given the @option{--install} option, it will
3793 copy this file in @file{m4/thirdparty.m4}, and output an
3794 @file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}.
3796 The next time @samp{aclocal -I m4 --install} is run (either via
3797 @command{autoreconf}, by hand, or from the @file{Makefile} rebuild
3798 rules) something different happens. @command{aclocal} notices that
3802 @file{configure.ac} uses @code{AX_THIRD_PARTY}
3804 @file{m4/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3807 @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3812 Because both files have the same serial number, @command{aclocal} uses
3813 the first it found in its search path order (@pxref{Macro Search
3814 Path}). @command{aclocal} therefore ignores
3815 @file{/usr/share/aclocal/thirdparty.m4} and outputs an
3816 @file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}.
3818 Local directories specified with @option{-I} are always searched before
3819 system-wide directories, so a local file will always be preferred to
3820 the system-wide file in case of equal serial numbers.
3822 Now suppose the system-wide third-party macro is changed. This can
3823 happen if the package installing this macro is updated. Let's suppose
3824 the new macro has serial number 2. The next time @samp{aclocal -I m4
3825 --install} is run the situation is the following:
3829 @file{configure.ac} uses @code{AX_THIRD_PARTY}
3831 @file{m4/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3834 @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
3839 When @command{aclocal} sees a greater serial number, it immediately
3840 forgets anything it knows from files that have the same basename and a
3841 smaller serial number. So after it has found
3842 @file{/usr/share/aclocal/thirdparty.m4} with serial 2,
3843 @command{aclocal} will proceed as if it had never seen
3844 @file{m4/thirdparty.m4}. This brings us back to a situation similar
3845 to that at the beginning of our example, where no local file defined
3846 the macro. @command{aclocal} will install the new version of the
3847 macro in @file{m4/thirdparty.m4}, in this case overriding the old
3848 version. MyPackage just had its macro updated as a side effect of
3849 running @command{aclocal}.
3851 If you are leery of letting @command{aclocal} update your local macro,
3852 you can run @samp{aclocal -I m4 --diff} to review the changes
3853 @samp{aclocal -I m4 --install} would perform on these macros.
3855 Finally, note that the @option{--force} option of @command{aclocal} has
3856 absolutely no effect on the files installed by @option{--install}. For
3857 instance, if you have modified your local macros, do not expect
3858 @option{--install --force} to replace the local macros by their
3859 system-wide versions. If you want to do so, simply erase the local
3860 macros you want to revert, and run @samp{aclocal -I m4 --install}.
3863 @node Future of aclocal
3864 @subsection The Future of @command{aclocal}
3865 @cindex @command{aclocal}'s scheduled death
3867 @command{aclocal} is expected to disappear. This feature really
3868 should not be offered by Automake. Automake should focus on
3869 generating @file{Makefile}s; dealing with M4 macros really is
3870 Autoconf's job. The fact that some people install Automake just to use
3871 @command{aclocal}, but do not use @command{automake} otherwise is an
3872 indication of how that feature is misplaced.
3874 The new implementation will probably be done slightly differently.
3875 For instance, it could enforce the @file{m4/}-style layout discussed in
3878 We have no idea when and how this will happen. This has been
3879 discussed several times in the past, but someone still has to commit
3880 to that non-trivial task.
3882 From the user point of view, @command{aclocal}'s removal might turn
3883 out to be painful. There is a simple precaution that you may take to
3884 make that switch more seamless: never call @command{aclocal} yourself.
3885 Keep this guy under the exclusive control of @command{autoreconf} and
3886 Automake's rebuild rules. Hopefully you won't need to worry about
3887 things breaking, when @command{aclocal} disappears, because everything
3888 will have been taken care of. If otherwise you used to call
3889 @command{aclocal} directly yourself or from some script, you will
3890 quickly notice the change.
3892 Many packages come with a script called @file{bootstrap.sh} or
3893 @file{autogen.sh}, that will just call @command{aclocal},
3894 @command{libtoolize}, @command{gettextize} or @command{autopoint},
3895 @command{autoconf}, @command{autoheader}, and @command{automake} in
3896 the right order. Actually this is precisely what @command{autoreconf}
3897 can do for you. If your package has such a @file{bootstrap.sh} or
3898 @file{autogen.sh} script, consider using @command{autoreconf}. That
3899 should simplify its logic a lot (less things to maintain, yum!), it's
3900 even likely you will not need the script anymore, and more to the point
3901 you will not call @command{aclocal} directly anymore.
3903 For the time being, third-party packages should continue to install
3904 public macros into @file{/usr/share/aclocal/}. If @command{aclocal}
3905 is replaced by another tool it might make sense to rename the
3906 directory, but supporting @file{/usr/share/aclocal/} for backward
3907 compatibility should be really easy provided all macros are properly
3908 written (@pxref{Extending aclocal}).
3913 @section Autoconf macros supplied with Automake
3915 Automake ships with several Autoconf macros that you can use from your
3916 @file{configure.ac}. When you use one of them it will be included by
3917 @command{aclocal} in @file{aclocal.m4}.
3920 * Public Macros:: Macros that you can use.
3921 * Obsolete Macros:: Macros that will soon be removed.
3922 * Private Macros:: Macros that you should not use.
3925 @c consider generating the following subsections automatically from m4 files.
3928 @subsection Public Macros
3932 @item AM_INIT_AUTOMAKE([OPTIONS])
3933 @acindex AM_INIT_AUTOMAKE
3934 Runs many macros required for proper operation of the generated Makefiles.
3936 @vindex AUTOMAKE_OPTIONS
3937 Today, @code{AM_INIT_AUTOMAKE} is called with a single argument: a
3938 space-separated list of Automake options that should
3939 be applied to every @file{Makefile.am} in the tree. The effect is as if
3940 each option were listed in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
3943 This macro can also be called in @emph{another, deprecated form} (support
3944 for which will be @emph{removed in the next major Automake release}):
3945 @code{AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])}. In this form,
3946 there are two required arguments: the package and the version number.
3947 This form is obsolete because the @var{package} and @var{version} can
3948 be obtained from Autoconf's @code{AC_INIT} macro (which itself has an
3949 old and a new form).
3951 If your @file{configure.ac} has:
3954 AC_INIT([src/foo.c])
3955 AM_INIT_AUTOMAKE([mumble], [1.5])
3959 you should modernize it as follows:
3962 AC_INIT([mumble], [1.5])
3963 AC_CONFIG_SRCDIR([src/foo.c])
3967 Note that if you're upgrading your @file{configure.ac} from an earlier
3968 version of Automake, it is not always correct to simply move the
3969 package and version arguments from @code{AM_INIT_AUTOMAKE} directly to
3970 @code{AC_INIT}, as in the example above. The first argument to
3971 @code{AC_INIT} should be the name of your package (e.g., @samp{GNU
3972 Automake}), not the tarball name (e.g., @samp{automake}) that you used
3973 to pass to @code{AM_INIT_AUTOMAKE}. Autoconf tries to derive a
3974 tarball name from the package name, which should work for most but not
3975 all package names. (If it doesn't work for yours, you can use the
3976 four-argument form of @code{AC_INIT} to provide the tarball name
3979 @cindex @code{PACKAGE}, prevent definition
3980 @cindex @code{VERSION}, prevent definition
3982 By default this macro @code{AC_DEFINE}'s @code{PACKAGE} and
3983 @code{VERSION}. This can be avoided by passing the @option{no-define}
3986 AM_INIT_AUTOMAKE([gnits 1.5 no-define dist-bzip2])
3989 @item AM_PATH_LISPDIR
3990 @acindex AM_PATH_LISPDIR
3993 Searches for the program @command{emacs}, and, if found, sets the
3994 output variable @code{lispdir} to the full path to Emacs' site-lisp
3997 Note that this test assumes the @command{emacs} found to be a version
3998 that supports Emacs Lisp (such as GNU Emacs or XEmacs). Other
3999 emacsen can cause this test to hang (some, like old versions of
4000 MicroEmacs, start up in interactive mode, requiring @kbd{C-x C-c} to
4001 exit, which is hardly obvious for a non-emacs user). In most cases,
4002 however, you should be able to use @kbd{C-c} to kill the test. In
4003 order to avoid problems, you can set @env{EMACS} to ``no'' in the
4004 environment, or use the @option{--with-lispdir} option to
4005 @command{configure} to explicitly set the correct path (if you're sure
4006 you have an @command{emacs} that supports Emacs Lisp).
4008 @item AM_PROG_AR(@ovar{act-if-fail})
4011 You must use this macro when you use the archiver in your project, if
4012 you want support for unusual archivers such as Microsoft @command{lib}.
4013 The content of the optional argument is executed if the archiver
4014 interface is not recognized; the default action is to abort configure
4015 with an error message.
4021 Use this macro when you have assembly code in your project. This will
4022 choose the assembler for you (by default the C compiler) and set
4023 @code{CCAS}, and will also set @code{CCASFLAGS} if required.
4025 @item AM_PROG_CC_C_O
4026 @acindex AM_PROG_CC_C_O
4027 @acindex AC_PROG_CC_C_O
4028 This is like @code{AC_PROG_CC_C_O}, but it generates its results in
4029 the manner required by Automake. You must use this instead of
4030 @code{AC_PROG_CC_C_O} when you need this functionality, that is, when
4031 using per-target flags or subdir-objects with C sources.
4034 @acindex AM_PROG_LEX
4035 @acindex AC_PROG_LEX
4036 @cindex HP-UX 10, @command{lex} problems
4037 @cindex @command{lex} problems with HP-UX 10
4038 Like @code{AC_PROG_LEX} (@pxref{Particular Programs, , Particular
4039 Program Checks, autoconf, The Autoconf Manual}), but uses the
4040 @command{missing} script on systems that do not have @command{lex}.
4041 HP-UX 10 is one such system.
4044 @acindex AM_PROG_GCJ
4047 This macro finds the @command{gcj} program or causes an error. It sets
4048 @code{GCJ} and @code{GCJFLAGS}. @command{gcj} is the Java front-end to the
4049 GNU Compiler Collection.
4051 @item AM_PROG_UPC([@var{compiler-search-list}])
4052 @acindex AM_PROG_UPC
4054 Find a compiler for Unified Parallel C and define the @code{UPC}
4055 variable. The default @var{compiler-search-list} is @samp{upcc upc}.
4056 This macro will abort @command{configure} if no Unified Parallel C
4059 @item AM_SILENT_RULES
4060 @acindex AM_SILENT_RULES
4061 Enable the machinery for less verbose build output (@pxref{Options}).
4063 @item AM_WITH_DMALLOC
4064 @acindex AM_WITH_DMALLOC
4065 @cindex @command{dmalloc}, support for
4066 @vindex WITH_DMALLOC
4067 @opindex --with-dmalloc
4068 Add support for the @uref{http://dmalloc.com/, Dmalloc package}. If
4069 the user runs @command{configure} with @option{--with-dmalloc}, then
4070 define @code{WITH_DMALLOC} and add @option{-ldmalloc} to @code{LIBS}.
4075 @node Obsolete Macros
4076 @subsection Obsolete Macros
4077 @cindex obsolete macros
4080 Although using some of the following macros was required in past
4081 releases, you should not use any of them in new code. @emph{All
4082 these macros will be removed in the next major Automake version};
4083 if you are still using them, running @command{autoupdate} should
4084 adjust your @file{configure.ac} automatically (@pxref{autoupdate
4085 Invocation, , Using @command{autoupdate} to Modernize
4086 @file{configure.ac}, autoconf, The Autoconf Manual}).
4091 @item AM_CONFIG_HEADER
4092 @acindex AM_CONFIG_HEADER
4093 Automake will generate rules to automatically regenerate the config
4094 header. This obsolete macro is a synonym of @code{AC_CONFIG_HEADERS}
4095 today (@pxref{Optional}).
4097 @item AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
4098 @acindex AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
4099 If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
4100 define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be
4101 found in @file{<termios.h>}. This macro is obsolete, you should
4102 use Autoconf's @code{AC_HEADER_TIOCGWINSZ} instead.
4104 @item AM_PROG_MKDIR_P
4105 @acindex AM_PROG_MKDIR_P
4106 @cindex @code{mkdir -p}, macro check
4110 From Automake 1.8 to 1.9.6 this macro used to define the output
4111 variable @code{mkdir_p} to one of @code{mkdir -p}, @code{install-sh
4112 -d}, or @code{mkinstalldirs}.
4114 Nowadays Autoconf provides a similar functionality with
4115 @code{AC_PROG_MKDIR_P} (@pxref{Particular Programs, , Particular
4116 Program Checks, autoconf, The Autoconf Manual}), however this defines
4117 the output variable @code{MKDIR_P} instead. In case you are still
4118 using the @code{AM_PROG_MKDIR_P} macro in your @file{configure.ac},
4119 or its provided variable @code{$(mkdir_p)} in your @file{Makefile.am},
4120 you are advised to switch ASAP to the more modern Autoconf-provided
4121 interface instead; both the macro and the variable @emph{will be
4122 removed} in the next major Automake release.
4124 @item AM_SYS_POSIX_TERMIOS
4125 @acindex AM_SYS_POSIX_TERMIOS
4126 @cindex POSIX termios headers
4127 @cindex termios POSIX headers
4128 Check to see if POSIX termios headers and functions are available on the
4129 system. If so, set the shell variable @code{am_cv_sys_posix_termios} to
4130 @samp{yes}. If not, set the variable to @samp{no}. This macro is obsolete,
4131 you should use Autoconf's @code{AC_SYS_POSIX_TERMIOS} instead.
4136 @node Private Macros
4137 @subsection Private Macros
4139 The following macros are private macros you should not call directly.
4140 They are called by the other public macros when appropriate. Do not
4141 rely on them, as they might be changed in a future version. Consider
4142 them as implementation details; or better, do not consider them at all:
4146 @item _AM_DEPENDENCIES
4147 @itemx AM_SET_DEPDIR
4149 @itemx AM_OUTPUT_DEPENDENCY_COMMANDS
4150 These macros are used to implement Automake's automatic dependency
4151 tracking scheme. They are called automatically by Automake when
4152 required, and there should be no need to invoke them manually.
4154 @item AM_MAKE_INCLUDE
4155 This macro is used to discover how the user's @command{make} handles
4156 @code{include} statements. This macro is automatically invoked when
4157 needed; there should be no need to invoke it manually.
4159 @item AM_PROG_INSTALL_STRIP
4160 This is used to find a version of @code{install} that can be used to
4161 strip a program at installation time. This macro is automatically
4162 included when required.
4164 @item AM_SANITY_CHECK
4165 This checks to make sure that a file created in the build directory is
4166 newer than a file in the source directory. This can fail on systems
4167 where the clock is set incorrectly. This macro is automatically run
4168 from @code{AM_INIT_AUTOMAKE}.
4174 @chapter Directories
4176 For simple projects that distribute all files in the same directory
4177 it is enough to have a single @file{Makefile.am} that builds
4178 everything in place.
4180 In larger projects it is common to organize files in different
4181 directories, in a tree. For instance one directory per program, per
4182 library or per module. The traditional approach is to build these
4183 subdirectories recursively: each directory contains its @file{Makefile}
4184 (generated from @file{Makefile.am}), and when @command{make} is run
4185 from the top level directory it enters each subdirectory in turn to
4189 * Subdirectories:: Building subdirectories recursively
4190 * Conditional Subdirectories:: Conditionally not building directories
4191 * Alternative:: Subdirectories without recursion
4192 * Subpackages:: Nesting packages
4195 @node Subdirectories
4196 @section Recursing subdirectories
4198 @cindex @code{SUBDIRS}, explained
4200 In packages with subdirectories, the top level @file{Makefile.am} must
4201 tell Automake which subdirectories are to be built. This is done via
4202 the @code{SUBDIRS} variable.
4205 The @code{SUBDIRS} variable holds a list of subdirectories in which
4206 building of various sorts can occur. The rules for many targets
4207 (e.g., @code{all}) in the generated @file{Makefile} will run commands
4208 both locally and in all specified subdirectories. Note that the
4209 directories listed in @code{SUBDIRS} are not required to contain
4210 @file{Makefile.am}s; only @file{Makefile}s (after configuration).
4211 This allows inclusion of libraries from packages that do not use
4212 Automake (such as @code{gettext}; see also @ref{Third-Party
4215 In packages that use subdirectories, the top-level @file{Makefile.am} is
4216 often very short. For instance, here is the @file{Makefile.am} from the
4217 GNU Hello distribution:
4220 EXTRA_DIST = BUGS ChangeLog.O README-alpha
4221 SUBDIRS = doc intl po src tests
4224 When Automake invokes @command{make} in a subdirectory, it uses the value
4225 of the @code{MAKE} variable. It passes the value of the variable
4226 @code{AM_MAKEFLAGS} to the @command{make} invocation; this can be set in
4227 @file{Makefile.am} if there are flags you must always pass to
4230 @vindex AM_MAKEFLAGS
4232 The directories mentioned in @code{SUBDIRS} are usually direct
4233 children of the current directory, each subdirectory containing its
4234 own @file{Makefile.am} with a @code{SUBDIRS} pointing to deeper
4235 subdirectories. Automake can be used to construct packages of
4236 arbitrary depth this way.
4238 By default, Automake generates @file{Makefiles} that work depth-first
4239 in postfix order: the subdirectories are built before the current
4240 directory. However, it is possible to change this ordering. You can
4241 do this by putting @samp{.} into @code{SUBDIRS}. For instance,
4242 putting @samp{.} first will cause a prefix ordering of
4248 SUBDIRS = lib src . test
4252 will cause @file{lib/} to be built before @file{src/}, then the
4253 current directory will be built, finally the @file{test/} directory
4254 will be built. It is customary to arrange test directories to be
4255 built after everything else since they are meant to test what has
4258 All @code{clean} rules are run in reverse order of build rules.
4260 @node Conditional Subdirectories
4261 @section Conditional Subdirectories
4262 @cindex Subdirectories, building conditionally
4263 @cindex Conditional subdirectories
4264 @cindex @code{SUBDIRS}, conditional
4265 @cindex Conditional @code{SUBDIRS}
4267 It is possible to define the @code{SUBDIRS} variable conditionally if,
4268 like in the case of GNU Inetutils, you want to only build a subset of
4271 To illustrate how this works, let's assume we have two directories
4272 @file{src/} and @file{opt/}. @file{src/} should always be built, but we
4273 want to decide in @command{configure} whether @file{opt/} will be built
4274 or not. (For this example we will assume that @file{opt/} should be
4275 built when the variable @samp{$want_opt} was set to @samp{yes}.)
4277 Running @command{make} should thus recurse into @file{src/} always, and
4278 then maybe in @file{opt/}.
4280 However @samp{make dist} should always recurse into both @file{src/}
4281 and @file{opt/}. Because @file{opt/} should be distributed even if it
4282 is not needed in the current configuration. This means
4283 @file{opt/Makefile} should be created @emph{unconditionally}.
4285 There are two ways to setup a project like this. You can use Automake
4286 conditionals (@pxref{Conditionals}) or use Autoconf @code{AC_SUBST}
4287 variables (@pxref{Setting Output Variables, , Setting Output
4288 Variables, autoconf, The Autoconf Manual}). Using Automake
4289 conditionals is the preferred solution. Before we illustrate these
4290 two possibilities, let's introduce @code{DIST_SUBDIRS}.
4293 * SUBDIRS vs DIST_SUBDIRS:: Two sets of directories
4294 * Subdirectories with AM_CONDITIONAL:: Specifying conditional subdirectories
4295 * Subdirectories with AC_SUBST:: Another way for conditional recursion
4296 * Unconfigured Subdirectories:: Not even creating a @samp{Makefile}
4299 @node SUBDIRS vs DIST_SUBDIRS
4300 @subsection @code{SUBDIRS} vs.@: @code{DIST_SUBDIRS}
4301 @cindex @code{DIST_SUBDIRS}, explained
4303 Automake considers two sets of directories, defined by the variables
4304 @code{SUBDIRS} and @code{DIST_SUBDIRS}.
4306 @code{SUBDIRS} contains the subdirectories of the current directory
4307 that must be built (@pxref{Subdirectories}). It must be defined
4308 manually; Automake will never guess a directory is to be built. As we
4309 will see in the next two sections, it is possible to define it
4310 conditionally so that some directory will be omitted from the build.
4312 @code{DIST_SUBDIRS} is used in rules that need to recurse in all
4313 directories, even those that have been conditionally left out of the
4314 build. Recall our example where we may not want to build subdirectory
4315 @file{opt/}, but yet we want to distribute it? This is where
4316 @code{DIST_SUBDIRS} comes into play: @samp{opt} may not appear in
4317 @code{SUBDIRS}, but it must appear in @code{DIST_SUBDIRS}.
4319 Precisely, @code{DIST_SUBDIRS} is used by @samp{make
4320 maintainer-clean}, @samp{make distclean} and @samp{make dist}. All
4321 other recursive rules use @code{SUBDIRS}.
4323 If @code{SUBDIRS} is defined conditionally using Automake
4324 conditionals, Automake will define @code{DIST_SUBDIRS} automatically
4325 from the possible values of @code{SUBDIRS} in all conditions.
4327 If @code{SUBDIRS} contains @code{AC_SUBST} variables,
4328 @code{DIST_SUBDIRS} will not be defined correctly because Automake
4329 does not know the possible values of these variables. In this case
4330 @code{DIST_SUBDIRS} needs to be defined manually.
4332 @node Subdirectories with AM_CONDITIONAL
4333 @subsection Subdirectories with @code{AM_CONDITIONAL}
4334 @cindex @code{SUBDIRS} and @code{AM_CONDITIONAL}
4335 @cindex @code{AM_CONDITIONAL} and @code{SUBDIRS}
4337 @c Keep in sync with subcond2.test.
4339 @file{configure} should output the @file{Makefile} for each directory
4340 and define a condition into which @file{opt/} should be built.
4344 AM_CONDITIONAL([COND_OPT], [test "$want_opt" = yes])
4345 AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
4349 Then @code{SUBDIRS} can be defined in the top-level @file{Makefile.am}
4356 SUBDIRS = src $(MAYBE_OPT)
4359 As you can see, running @command{make} will rightly recurse into
4360 @file{src/} and maybe @file{opt/}.
4362 @vindex DIST_SUBDIRS
4363 As you can't see, running @samp{make dist} will recurse into both
4364 @file{src/} and @file{opt/} directories because @samp{make dist}, unlike
4365 @samp{make all}, doesn't use the @code{SUBDIRS} variable. It uses the
4366 @code{DIST_SUBDIRS} variable.
4368 In this case Automake will define @samp{DIST_SUBDIRS = src opt}
4369 automatically because it knows that @code{MAYBE_OPT} can contain
4370 @samp{opt} in some condition.
4372 @node Subdirectories with AC_SUBST
4373 @subsection Subdirectories with @code{AC_SUBST}
4374 @cindex @code{SUBDIRS} and @code{AC_SUBST}
4375 @cindex @code{AC_SUBST} and @code{SUBDIRS}
4377 @c Keep in sync with subcond3.test.
4379 Another possibility is to define @code{MAYBE_OPT} from
4380 @file{./configure} using @code{AC_SUBST}:
4384 if test "$want_opt" = yes; then
4389 AC_SUBST([MAYBE_OPT])
4390 AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
4394 In this case the top-level @file{Makefile.am} should look as follows.
4397 SUBDIRS = src $(MAYBE_OPT)
4398 DIST_SUBDIRS = src opt
4401 The drawback is that since Automake cannot guess what the possible
4402 values of @code{MAYBE_OPT} are, it is necessary to define
4403 @code{DIST_SUBDIRS}.
4405 @node Unconfigured Subdirectories
4406 @subsection Unconfigured Subdirectories
4407 @cindex Subdirectories, configured conditionally
4409 The semantics of @code{DIST_SUBDIRS} are often misunderstood by some
4410 users that try to @emph{configure and build} subdirectories
4411 conditionally. Here by configuring we mean creating the
4412 @file{Makefile} (it might also involve running a nested
4413 @command{configure} script: this is a costly operation that explains
4414 why people want to do it conditionally, but only the @file{Makefile}
4415 is relevant to the discussion).
4417 The above examples all assume that every @file{Makefile} is created,
4418 even in directories that are not going to be built. The simple reason
4419 is that we want @samp{make dist} to distribute even the directories
4420 that are not being built (e.g., platform-dependent code), hence
4421 @file{make dist} must recurse into the subdirectory, hence this
4422 directory must be configured and appear in @code{DIST_SUBDIRS}.
4424 Building packages that do not configure every subdirectory is a tricky
4425 business, and we do not recommend it to the novice as it is easy to
4426 produce an incomplete tarball by mistake. We will not discuss this
4427 topic in depth here, yet for the adventurous here are a few rules to
4432 @item @code{SUBDIRS} should always be a subset of @code{DIST_SUBDIRS}.
4434 It makes little sense to have a directory in @code{SUBDIRS} that
4435 is not in @code{DIST_SUBDIRS}. Think of the former as a way to tell
4436 which directories listed in the latter should be built.
4437 @item Any directory listed in @code{DIST_SUBDIRS} and @code{SUBDIRS}
4440 I.e., the @file{Makefile} must exists or the recursive @command{make}
4441 rules will not be able to process the directory.
4442 @item Any configured directory must be listed in @code{DIST_SUBDIRS}.
4444 So that the cleaning rules remove the generated @file{Makefile}s.
4445 It would be correct to see @code{DIST_SUBDIRS} as a variable that
4446 lists all the directories that have been configured.
4450 In order to prevent recursion in some unconfigured directory you
4451 must therefore ensure that this directory does not appear in
4452 @code{DIST_SUBDIRS} (and @code{SUBDIRS}). For instance, if you define
4453 @code{SUBDIRS} conditionally using @code{AC_SUBST} and do not define
4454 @code{DIST_SUBDIRS} explicitly, it will be default to
4455 @samp{$(SUBDIRS)}; another possibility is to force @code{DIST_SUBDIRS
4458 Of course, directories that are omitted from @code{DIST_SUBDIRS} will
4459 not be distributed unless you make other arrangements for this to
4460 happen (for instance, always running @samp{make dist} in a
4461 configuration where all directories are known to appear in
4462 @code{DIST_SUBDIRS}; or writing a @code{dist-hook} target to
4463 distribute these directories).
4465 @cindex Subdirectories, not distributed
4466 In few packages, unconfigured directories are not even expected to
4467 be distributed. Although these packages do not require the
4468 aforementioned extra arrangements, there is another pitfall. If the
4469 name of a directory appears in @code{SUBDIRS} or @code{DIST_SUBDIRS},
4470 @command{automake} will make sure the directory exists. Consequently
4471 @command{automake} cannot be run on such a distribution when one
4472 directory has been omitted. One way to avoid this check is to use the
4473 @code{AC_SUBST} method to declare conditional directories; since
4474 @command{automake} does not know the values of @code{AC_SUBST}
4475 variables it cannot ensure the corresponding directory exists.
4478 @section An Alternative Approach to Subdirectories
4480 If you've ever read Peter Miller's excellent paper,
4481 @uref{http://miller.emu.id.au/pmiller/books/rmch/,
4482 Recursive Make Considered Harmful}, the preceding sections on the use of
4483 subdirectories will probably come as unwelcome advice. For those who
4484 haven't read the paper, Miller's main thesis is that recursive
4485 @command{make} invocations are both slow and error-prone.
4487 Automake provides sufficient cross-directory support @footnote{We
4488 believe. This work is new and there are probably warts.
4489 @xref{Introduction}, for information on reporting bugs.} to enable you
4490 to write a single @file{Makefile.am} for a complex multi-directory
4494 By default an installable file specified in a subdirectory will have its
4495 directory name stripped before installation. For instance, in this
4496 example, the header file will be installed as
4497 @file{$(includedir)/stdio.h}:
4500 include_HEADERS = inc/stdio.h
4504 @cindex @code{nobase_} prefix
4505 @cindex Path stripping, avoiding
4506 @cindex Avoiding path stripping
4508 However, the @samp{nobase_} prefix can be used to circumvent this path
4509 stripping. In this example, the header file will be installed as
4510 @file{$(includedir)/sys/types.h}:
4513 nobase_include_HEADERS = sys/types.h
4516 @cindex @code{nobase_} and @code{dist_} or @code{nodist_}
4517 @cindex @code{dist_} and @code{nobase_}
4518 @cindex @code{nodist_} and @code{nobase_}
4522 @samp{nobase_} should be specified first when used in conjunction with
4523 either @samp{dist_} or @samp{nodist_} (@pxref{Fine-grained Distribution
4524 Control}). For instance:
4527 nobase_dist_pkgdata_DATA = images/vortex.pgm sounds/whirl.ogg
4530 Finally, note that a variable using the @samp{nobase_} prefix can
4531 often be replaced by several variables, one for each destination
4532 directory (@pxref{Uniform}). For instance, the last example could be
4533 rewritten as follows:
4535 @c Keep in sync with primary-prefix-couples-documented-valid.test.
4537 imagesdir = $(pkgdatadir)/images
4538 soundsdir = $(pkgdatadir)/sounds
4539 dist_images_DATA = images/vortex.pgm
4540 dist_sounds_DATA = sounds/whirl.ogg
4544 This latter syntax makes it possible to change one destination
4545 directory without changing the layout of the source tree.
4547 Currently, @samp{nobase_*_LTLIBRARIES} are the only exception to this
4548 rule, in that there is no particular installation order guarantee for
4549 an otherwise equivalent set of variables without @samp{nobase_} prefix.
4552 @section Nesting Packages
4553 @cindex Nesting packages
4555 @acindex AC_CONFIG_SUBDIRS
4556 @acindex AC_CONFIG_AUX_DIR
4559 In the GNU Build System, packages can be nested to arbitrary depth.
4560 This means that a package can embed other packages with their own
4561 @file{configure}, @file{Makefile}s, etc.
4563 These other packages should just appear as subdirectories of their
4564 parent package. They must be listed in @code{SUBDIRS} like other
4565 ordinary directories. However the subpackage's @file{Makefile}s
4566 should be output by its own @file{configure} script, not by the
4567 parent's @file{configure}. This is achieved using the
4568 @code{AC_CONFIG_SUBDIRS} Autoconf macro (@pxref{Subdirectories,
4569 AC_CONFIG_SUBDIRS, Configuring Other Packages in Subdirectories,
4570 autoconf, The Autoconf Manual}).
4572 Here is an example package for an @code{arm} program that links with
4573 a @code{hand} library that is a nested package in subdirectory
4576 @code{arm}'s @file{configure.ac}:
4579 AC_INIT([arm], [1.0])
4580 AC_CONFIG_AUX_DIR([.])
4583 AC_CONFIG_FILES([Makefile])
4584 # Call hand's ./configure script recursively.
4585 AC_CONFIG_SUBDIRS([hand])
4589 @code{arm}'s @file{Makefile.am}:
4592 # Build the library in the hand subdirectory first.
4595 # Include hand's header when compiling this directory.
4596 AM_CPPFLAGS = -I$(srcdir)/hand
4600 # link with the hand library.
4601 arm_LDADD = hand/libhand.a
4604 Now here is @code{hand}'s @file{hand/configure.ac}:
4607 AC_INIT([hand], [1.2])
4608 AC_CONFIG_AUX_DIR([.])
4613 AC_CONFIG_FILES([Makefile])
4618 and its @file{hand/Makefile.am}:
4621 lib_LIBRARIES = libhand.a
4622 libhand_a_SOURCES = hand.c
4625 When @samp{make dist} is run from the top-level directory it will
4626 create an archive @file{arm-1.0.tar.gz} that contains the @code{arm}
4627 code as well as the @file{hand} subdirectory. This package can be
4628 built and installed like any ordinary package, with the usual
4629 @samp{./configure && make && make install} sequence (the @code{hand}
4630 subpackage will be built and installed by the process).
4632 When @samp{make dist} is run from the hand directory, it will create a
4633 self-contained @file{hand-1.2.tar.gz} archive. So although it appears
4634 to be embedded in another package, it can still be used separately.
4636 The purpose of the @samp{AC_CONFIG_AUX_DIR([.])} instruction is to
4637 force Automake and Autoconf to search for auxiliary scripts in the
4638 current directory. For instance, this means that there will be two
4639 copies of @file{install-sh}: one in the top-level of the @code{arm}
4640 package, and another one in the @file{hand/} subdirectory for the
4641 @code{hand} package.
4643 The historical default is to search for these auxiliary scripts in
4644 the parent directory and the grandparent directory. So if the
4645 @samp{AC_CONFIG_AUX_DIR([.])} line was removed from
4646 @file{hand/configure.ac}, that subpackage would share the auxiliary
4647 script of the @code{arm} package. This may looks like a gain in size
4648 (a few kilobytes), but it is actually a loss of modularity as the
4649 @code{hand} subpackage is no longer self-contained (@samp{make dist}
4650 in the subdirectory will not work anymore).
4652 Packages that do not use Automake need more work to be integrated this
4653 way. @xref{Third-Party Makefiles}.
4656 @chapter Building Programs and Libraries
4658 A large part of Automake's functionality is dedicated to making it easy
4659 to build programs and libraries.
4662 * A Program:: Building a program
4663 * A Library:: Building a library
4664 * A Shared Library:: Building a Libtool library
4665 * Program and Library Variables:: Variables controlling program and
4667 * Default _SOURCES:: Default source files
4668 * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
4669 * Program Variables:: Variables used when building a program
4670 * Yacc and Lex:: Yacc and Lex support
4671 * C++ Support:: Compiling C++ sources
4672 * Objective C Support:: Compiling Objective C sources
4673 * Unified Parallel C Support:: Compiling Unified Parallel C sources
4674 * Assembly Support:: Compiling assembly sources
4675 * Fortran 77 Support:: Compiling Fortran 77 sources
4676 * Fortran 9x Support:: Compiling Fortran 9x sources
4677 * Java Support with gcj:: Compiling Java sources using gcj
4678 * Vala Support:: Compiling Vala sources
4679 * Support for Other Languages:: Compiling other languages
4680 * Dependencies:: Automatic dependency tracking
4681 * EXEEXT:: Support for executable extensions
4686 @section Building a program
4688 In order to build a program, you need to tell Automake which sources
4689 are part of it, and which libraries it should be linked with.
4691 This section also covers conditional compilation of sources or
4692 programs. Most of the comments about these also apply to libraries
4693 (@pxref{A Library}) and libtool libraries (@pxref{A Shared Library}).
4696 * Program Sources:: Defining program sources
4697 * Linking:: Linking with libraries or extra objects
4698 * Conditional Sources:: Handling conditional sources
4699 * Conditional Programs:: Building a program conditionally
4702 @node Program Sources
4703 @subsection Defining program sources
4705 @cindex @code{PROGRAMS}, @code{bindir}
4707 @vindex bin_PROGRAMS
4708 @vindex sbin_PROGRAMS
4709 @vindex libexec_PROGRAMS
4710 @vindex pkglibexec_PROGRAMS
4711 @vindex noinst_PROGRAMS
4712 @vindex check_PROGRAMS
4714 In a directory containing source that gets built into a program (as
4715 opposed to a library or a script), the @code{PROGRAMS} primary is used.
4716 Programs can be installed in @code{bindir}, @code{sbindir},
4717 @code{libexecdir}, @code{pkglibexecdir}, or not at all
4718 (@code{noinst_}). They can also be built only for @samp{make check}, in
4719 which case the prefix is @samp{check_}.
4724 bin_PROGRAMS = hello
4727 In this simple case, the resulting @file{Makefile.in} will contain code
4728 to generate a program named @code{hello}.
4730 Associated with each program are several assisting variables that are
4731 named after the program. These variables are all optional, and have
4732 reasonable defaults. Each variable, its use, and default is spelled out
4733 below; we use the ``hello'' example throughout.
4735 The variable @code{hello_SOURCES} is used to specify which source files
4736 get built into an executable:
4739 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
4742 This causes each mentioned @file{.c} file to be compiled into the
4743 corresponding @file{.o}. Then all are linked to produce @file{hello}.
4745 @cindex @code{_SOURCES} primary, defined
4746 @cindex @code{SOURCES} primary, defined
4747 @cindex Primary variable, @code{SOURCES}
4750 If @code{hello_SOURCES} is not specified, then it defaults to the single
4751 file @file{hello.c} (@pxref{Default _SOURCES}).
4755 Multiple programs can be built in a single directory. Multiple programs
4756 can share a single source file, which must be listed in each
4757 @code{_SOURCES} definition.
4759 @cindex Header files in @code{_SOURCES}
4760 @cindex @code{_SOURCES} and header files
4762 Header files listed in a @code{_SOURCES} definition will be included in
4763 the distribution but otherwise ignored. In case it isn't obvious, you
4764 should not include the header file generated by @file{configure} in a
4765 @code{_SOURCES} variable; this file should not be distributed. Lex
4766 (@file{.l}) and Yacc (@file{.y}) files can also be listed; see @ref{Yacc
4771 @subsection Linking the program
4773 If you need to link against libraries that are not found by
4774 @command{configure}, you can use @code{LDADD} to do so. This variable is
4775 used to specify additional objects or libraries to link with; it is
4776 inappropriate for specifying specific linker flags, you should use
4777 @code{AM_LDFLAGS} for this purpose.
4781 @cindex @code{prog_LDADD}, defined
4783 Sometimes, multiple programs are built in one directory but do not share
4784 the same link-time requirements. In this case, you can use the
4785 @code{@var{prog}_LDADD} variable (where @var{prog} is the name of the
4786 program as it appears in some @code{_PROGRAMS} variable, and usually
4787 written in lowercase) to override @code{LDADD}. If this variable exists
4788 for a given program, then that program is not linked using @code{LDADD}.
4791 For instance, in GNU cpio, @code{pax}, @code{cpio} and @code{mt} are
4792 linked against the library @file{libcpio.a}. However, @code{rmt} is
4793 built in the same directory, and has no such link requirement. Also,
4794 @code{mt} and @code{rmt} are only built on certain architectures. Here
4795 is what cpio's @file{src/Makefile.am} looks like (abridged):
4798 bin_PROGRAMS = cpio pax $(MT)
4799 libexec_PROGRAMS = $(RMT)
4800 EXTRA_PROGRAMS = mt rmt
4802 LDADD = ../lib/libcpio.a $(INTLLIBS)
4805 cpio_SOURCES = @dots{}
4806 pax_SOURCES = @dots{}
4807 mt_SOURCES = @dots{}
4808 rmt_SOURCES = @dots{}
4811 @cindex @code{_LDFLAGS}, defined
4812 @vindex maude_LDFLAGS
4813 @code{@var{prog}_LDADD} is inappropriate for passing program-specific
4814 linker flags (except for @option{-l}, @option{-L}, @option{-dlopen} and
4815 @option{-dlpreopen}). So, use the @code{@var{prog}_LDFLAGS} variable for
4818 @cindex @code{_DEPENDENCIES}, defined
4819 @vindex maude_DEPENDENCIES
4820 @vindex EXTRA_maude_DEPENDENCIES
4821 It is also occasionally useful to have a program depend on some other
4822 target that is not actually part of that program. This can be done
4823 using either the @code{@var{prog}_DEPENDENCIES} or the
4824 @code{EXTRA_@var{prog}_DEPENDENCIES} variable. Each program depends on
4825 the contents both variables, but no further interpretation is done.
4827 Since these dependencies are associated to the link rule used to
4828 create the programs they should normally list files used by the link
4829 command. That is @file{*.$(OBJEXT)}, @file{*.a}, or @file{*.la}
4830 files. In rare cases you may need to add other kinds of files such as
4831 linker scripts, but @emph{listing a source file in
4832 @code{_DEPENDENCIES} is wrong}. If some source file needs to be built
4833 before all the components of a program are built, consider using the
4834 @code{BUILT_SOURCES} variable instead (@pxref{Sources}).
4836 If @code{@var{prog}_DEPENDENCIES} is not supplied, it is computed by
4837 Automake. The automatically-assigned value is the contents of
4838 @code{@var{prog}_LDADD}, with most configure substitutions, @option{-l},
4839 @option{-L}, @option{-dlopen} and @option{-dlpreopen} options removed. The
4840 configure substitutions that are left in are only @samp{$(LIBOBJS)} and
4841 @samp{$(ALLOCA)}; these are left because it is known that they will not
4842 cause an invalid value for @code{@var{prog}_DEPENDENCIES} to be
4845 @ref{Conditional Sources} shows a situation where @code{_DEPENDENCIES}
4848 The @code{EXTRA_@var{prog}_DEPENDENCIES} may be useful for cases where
4849 you merely want to augment the @command{automake}-generated
4850 @code{@var{prog}_DEPENDENCIES} rather than replacing it.
4852 @cindex @code{LDADD} and @option{-l}
4853 @cindex @option{-l} and @code{LDADD}
4854 We recommend that you avoid using @option{-l} options in @code{LDADD}
4855 or @code{@var{prog}_LDADD} when referring to libraries built by your
4856 package. Instead, write the file name of the library explicitly as in
4857 the above @code{cpio} example. Use @option{-l} only to list
4858 third-party libraries. If you follow this rule, the default value of
4859 @code{@var{prog}_DEPENDENCIES} will list all your local libraries and
4860 omit the other ones.
4863 @node Conditional Sources
4864 @subsection Conditional compilation of sources
4866 You can't put a configure substitution (e.g., @samp{@@FOO@@} or
4867 @samp{$(FOO)} where @code{FOO} is defined via @code{AC_SUBST}) into a
4868 @code{_SOURCES} variable. The reason for this is a bit hard to
4869 explain, but suffice to say that it simply won't work. Automake will
4870 give an error if you try to do this.
4872 Fortunately there are two other ways to achieve the same result. One is
4873 to use configure substitutions in @code{_LDADD} variables, the other is
4874 to use an Automake conditional.
4876 @subsubheading Conditional Compilation using @code{_LDADD} Substitutions
4878 @cindex @code{EXTRA_prog_SOURCES}, defined
4880 Automake must know all the source files that could possibly go into a
4881 program, even if not all the files are built in every circumstance. Any
4882 files that are only conditionally built should be listed in the
4883 appropriate @code{EXTRA_} variable. For instance, if
4884 @file{hello-linux.c} or @file{hello-generic.c} were conditionally included
4885 in @code{hello}, the @file{Makefile.am} would contain:
4888 bin_PROGRAMS = hello
4889 hello_SOURCES = hello-common.c
4890 EXTRA_hello_SOURCES = hello-linux.c hello-generic.c
4891 hello_LDADD = $(HELLO_SYSTEM)
4892 hello_DEPENDENCIES = $(HELLO_SYSTEM)
4896 You can then setup the @samp{$(HELLO_SYSTEM)} substitution from
4897 @file{configure.ac}:
4902 *linux*) HELLO_SYSTEM='hello-linux.$(OBJEXT)' ;;
4903 *) HELLO_SYSTEM='hello-generic.$(OBJEXT)' ;;
4905 AC_SUBST([HELLO_SYSTEM])
4909 In this case, the variable @code{HELLO_SYSTEM} should be replaced by
4910 either @file{hello-linux.o} or @file{hello-generic.o}, and added to
4911 both @code{hello_DEPENDENCIES} and @code{hello_LDADD} in order to be
4912 built and linked in.
4914 @subsubheading Conditional Compilation using Automake Conditionals
4916 An often simpler way to compile source files conditionally is to use
4917 Automake conditionals. For instance, you could use this
4918 @file{Makefile.am} construct to build the same @file{hello} example:
4921 bin_PROGRAMS = hello
4923 hello_SOURCES = hello-linux.c hello-common.c
4925 hello_SOURCES = hello-generic.c hello-common.c
4929 In this case, @file{configure.ac} should setup the @code{LINUX}
4930 conditional using @code{AM_CONDITIONAL} (@pxref{Conditionals}).
4932 When using conditionals like this you don't need to use the
4933 @code{EXTRA_} variable, because Automake will examine the contents of
4934 each variable to construct the complete list of source files.
4936 If your program uses a lot of files, you will probably prefer a
4937 conditional @samp{+=}.
4940 bin_PROGRAMS = hello
4941 hello_SOURCES = hello-common.c
4943 hello_SOURCES += hello-linux.c
4945 hello_SOURCES += hello-generic.c
4949 @node Conditional Programs
4950 @subsection Conditional compilation of programs
4951 @cindex Conditional programs
4952 @cindex Programs, conditional
4954 Sometimes it is useful to determine the programs that are to be built
4955 at configure time. For instance, GNU @code{cpio} only builds
4956 @code{mt} and @code{rmt} under special circumstances. The means to
4957 achieve conditional compilation of programs are the same you can use
4958 to compile source files conditionally: substitutions or conditionals.
4960 @subsubheading Conditional Programs using @command{configure} Substitutions
4962 @vindex EXTRA_PROGRAMS
4963 @cindex @code{EXTRA_PROGRAMS}, defined
4964 In this case, you must notify Automake of all the programs that can
4965 possibly be built, but at the same time cause the generated
4966 @file{Makefile.in} to use the programs specified by @command{configure}.
4967 This is done by having @command{configure} substitute values into each
4968 @code{_PROGRAMS} definition, while listing all optionally built programs
4969 in @code{EXTRA_PROGRAMS}.
4972 bin_PROGRAMS = cpio pax $(MT)
4973 libexec_PROGRAMS = $(RMT)
4974 EXTRA_PROGRAMS = mt rmt
4977 As explained in @ref{EXEEXT}, Automake will rewrite
4978 @code{bin_PROGRAMS}, @code{libexec_PROGRAMS}, and
4979 @code{EXTRA_PROGRAMS}, appending @samp{$(EXEEXT)} to each binary.
4980 Obviously it cannot rewrite values obtained at run-time through
4981 @command{configure} substitutions, therefore you should take care of
4982 appending @samp{$(EXEEXT)} yourself, as in @samp{AC_SUBST([MT],
4983 ['mt$@{EXEEXT@}'])}.
4985 @subsubheading Conditional Programs using Automake Conditionals
4987 You can also use Automake conditionals (@pxref{Conditionals}) to
4988 select programs to be built. In this case you don't have to worry
4989 about @samp{$(EXEEXT)} or @code{EXTRA_PROGRAMS}.
4991 @c Keep in sync with exeext.test.
4993 bin_PROGRAMS = cpio pax
4998 libexec_PROGRAMS = rmt
5004 @section Building a library
5006 @cindex @code{_LIBRARIES} primary, defined
5007 @cindex @code{LIBRARIES} primary, defined
5008 @cindex Primary variable, @code{LIBRARIES}
5011 @vindex lib_LIBRARIES
5012 @vindex pkglib_LIBRARIES
5013 @vindex noinst_LIBRARIES
5015 Building a library is much like building a program. In this case, the
5016 name of the primary is @code{LIBRARIES}. Libraries can be installed in
5017 @code{libdir} or @code{pkglibdir}.
5019 @xref{A Shared Library}, for information on how to build shared
5020 libraries using libtool and the @code{LTLIBRARIES} primary.
5022 Each @code{_LIBRARIES} variable is a list of the libraries to be built.
5023 For instance, to create a library named @file{libcpio.a}, but not install
5024 it, you would write:
5027 noinst_LIBRARIES = libcpio.a
5028 libcpio_a_SOURCES = @dots{}
5031 The sources that go into a library are determined exactly as they are
5032 for programs, via the @code{_SOURCES} variables. Note that the library
5033 name is canonicalized (@pxref{Canonicalization}), so the @code{_SOURCES}
5034 variable corresponding to @file{libcpio.a} is @samp{libcpio_a_SOURCES},
5035 not @samp{libcpio.a_SOURCES}.
5037 @vindex maude_LIBADD
5038 Extra objects can be added to a library using the
5039 @code{@var{library}_LIBADD} variable. This should be used for objects
5040 determined by @command{configure}. Again from @code{cpio}:
5042 @c Keep in sync with pr401c.test.
5044 libcpio_a_LIBADD = $(LIBOBJS) $(ALLOCA)
5047 In addition, sources for extra objects that will not exist until
5048 configure-time must be added to the @code{BUILT_SOURCES} variable
5051 Building a static library is done by compiling all object files, then
5052 by invoking @samp{$(AR) $(ARFLAGS)} followed by the name of the
5053 library and the list of objects, and finally by calling
5054 @samp{$(RANLIB)} on that library. You should call
5055 @code{AC_PROG_RANLIB} from your @file{configure.ac} to define
5056 @code{RANLIB} (Automake will complain otherwise). You should also
5057 call @code{AM_PROG_AR} to define @code{AR}, in order to support unusual
5058 archivers such as Microsoft lib. @code{ARFLAGS} will default to
5059 @code{cru}; you can override this variable by setting it in your
5060 @file{Makefile.am} or by @code{AC_SUBST}ing it from your
5061 @file{configure.ac}. You can override the @code{AR} variable by
5062 defining a per-library @code{maude_AR} variable (@pxref{Program and
5063 Library Variables}).
5065 @cindex Empty libraries
5066 Be careful when selecting library components conditionally. Because
5067 building an empty library is not portable, you should ensure that any
5068 library always contains at least one object.
5070 To use a static library when building a program, add it to
5071 @code{LDADD} for this program. In the following example, the program
5072 @file{cpio} is statically linked with the library @file{libcpio.a}.
5075 noinst_LIBRARIES = libcpio.a
5076 libcpio_a_SOURCES = @dots{}
5079 cpio_SOURCES = cpio.c @dots{}
5080 cpio_LDADD = libcpio.a
5084 @node A Shared Library
5085 @section Building a Shared Library
5087 @cindex Shared libraries, support for
5089 Building shared libraries portably is a relatively complex matter.
5090 For this reason, GNU Libtool (@pxref{Top, , Introduction, libtool, The
5091 Libtool Manual}) was created to help build shared libraries in a
5092 platform-independent way.
5095 * Libtool Concept:: Introducing Libtool
5096 * Libtool Libraries:: Declaring Libtool Libraries
5097 * Conditional Libtool Libraries:: Building Libtool Libraries Conditionally
5098 * Conditional Libtool Sources:: Choosing Library Sources Conditionally
5099 * Libtool Convenience Libraries:: Building Convenience Libtool Libraries
5100 * Libtool Modules:: Building Libtool Modules
5101 * Libtool Flags:: Using _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS
5102 * LTLIBOBJS:: Using $(LTLIBOBJS) and $(LTALLOCA)
5103 * Libtool Issues:: Common Issues Related to Libtool's Use
5106 @node Libtool Concept
5107 @subsection The Libtool Concept
5109 @cindex @command{libtool}, introduction
5110 @cindex libtool library, definition
5111 @cindex suffix @file{.la}, defined
5112 @cindex @file{.la} suffix, defined
5114 Libtool abstracts shared and static libraries into a unified concept
5115 henceforth called @dfn{libtool libraries}. Libtool libraries are
5116 files using the @file{.la} suffix, and can designate a static library,
5117 a shared library, or maybe both. Their exact nature cannot be
5118 determined until @file{./configure} is run: not all platforms support
5119 all kinds of libraries, and users can explicitly select which
5120 libraries should be built. (However the package's maintainers can
5121 tune the default, @pxref{AC_PROG_LIBTOOL, , The @code{AC_PROG_LIBTOOL}
5122 macro, libtool, The Libtool Manual}.)
5124 @cindex suffix @file{.lo}, defined
5125 Because object files for shared and static libraries must be compiled
5126 differently, libtool is also used during compilation. Object files
5127 built by libtool are called @dfn{libtool objects}: these are files
5128 using the @file{.lo} suffix. Libtool libraries are built from these
5131 You should not assume anything about the structure of @file{.la} or
5132 @file{.lo} files and how libtool constructs them: this is libtool's
5133 concern, and the last thing one wants is to learn about libtool's
5134 guts. However the existence of these files matters, because they are
5135 used as targets and dependencies in @file{Makefile}s rules when
5136 building libtool libraries. There are situations where you may have
5137 to refer to these, for instance when expressing dependencies for
5138 building source files conditionally (@pxref{Conditional Libtool
5141 @cindex @file{libltdl}, introduction
5143 People considering writing a plug-in system, with dynamically loaded
5144 modules, should look into @file{libltdl}: libtool's dlopening library
5145 (@pxref{Using libltdl, , Using libltdl, libtool, The Libtool Manual}).
5146 This offers a portable dlopening facility to load libtool libraries
5147 dynamically, and can also achieve static linking where unavoidable.
5149 Before we discuss how to use libtool with Automake in details, it
5150 should be noted that the libtool manual also has a section about how
5151 to use Automake with libtool (@pxref{Using Automake, , Using Automake
5152 with Libtool, libtool, The Libtool Manual}).
5154 @node Libtool Libraries
5155 @subsection Building Libtool Libraries
5157 @cindex @code{_LTLIBRARIES} primary, defined
5158 @cindex @code{LTLIBRARIES} primary, defined
5159 @cindex Primary variable, @code{LTLIBRARIES}
5160 @cindex Example of shared libraries
5161 @vindex lib_LTLIBRARIES
5162 @vindex pkglib_LTLIBRARIES
5163 @vindex _LTLIBRARIES
5165 Automake uses libtool to build libraries declared with the
5166 @code{LTLIBRARIES} primary. Each @code{_LTLIBRARIES} variable is a
5167 list of libtool libraries to build. For instance, to create a libtool
5168 library named @file{libgettext.la}, and install it in @code{libdir},
5172 lib_LTLIBRARIES = libgettext.la
5173 libgettext_la_SOURCES = gettext.c gettext.h @dots{}
5176 Automake predefines the variable @code{pkglibdir}, so you can use
5177 @code{pkglib_LTLIBRARIES} to install libraries in
5178 @samp{$(libdir)/@@PACKAGE@@/}.
5180 If @file{gettext.h} is a public header file that needs to be installed
5181 in order for people to use the library, it should be declared using a
5182 @code{_HEADERS} variable, not in @code{libgettext_la_SOURCES}.
5183 Headers listed in the latter should be internal headers that are not
5184 part of the public interface.
5187 lib_LTLIBRARIES = libgettext.la
5188 libgettext_la_SOURCES = gettext.c @dots{}
5189 include_HEADERS = gettext.h @dots{}
5192 A package can build and install such a library along with other
5193 programs that use it. This dependency should be specified using
5194 @code{LDADD}. The following example builds a program named
5195 @file{hello} that is linked with @file{libgettext.la}.
5198 lib_LTLIBRARIES = libgettext.la
5199 libgettext_la_SOURCES = gettext.c @dots{}
5201 bin_PROGRAMS = hello
5202 hello_SOURCES = hello.c @dots{}
5203 hello_LDADD = libgettext.la
5207 Whether @file{hello} is statically or dynamically linked with
5208 @file{libgettext.la} is not yet known: this will depend on the
5209 configuration of libtool and the capabilities of the host.
5212 @node Conditional Libtool Libraries
5213 @subsection Building Libtool Libraries Conditionally
5214 @cindex libtool libraries, conditional
5215 @cindex conditional libtool libraries
5217 Like conditional programs (@pxref{Conditional Programs}), there are
5218 two main ways to build conditional libraries: using Automake
5219 conditionals or using Autoconf @code{AC_SUBST}itutions.
5221 The important implementation detail you have to be aware of is that
5222 the place where a library will be installed matters to libtool: it
5223 needs to be indicated @emph{at link-time} using the @option{-rpath}
5226 For libraries whose destination directory is known when Automake runs,
5227 Automake will automatically supply the appropriate @option{-rpath}
5228 option to libtool. This is the case for libraries listed explicitly in
5229 some installable @code{_LTLIBRARIES} variables such as
5230 @code{lib_LTLIBRARIES}.
5232 However, for libraries determined at configure time (and thus
5233 mentioned in @code{EXTRA_LTLIBRARIES}), Automake does not know the
5234 final installation directory. For such libraries you must add the
5235 @option{-rpath} option to the appropriate @code{_LDFLAGS} variable by
5238 The examples below illustrate the differences between these two methods.
5240 Here is an example where @code{WANTEDLIBS} is an @code{AC_SUBST}ed
5241 variable set at @file{./configure}-time to either @file{libfoo.la},
5242 @file{libbar.la}, both, or none. Although @samp{$(WANTEDLIBS)}
5243 appears in the @code{lib_LTLIBRARIES}, Automake cannot guess it
5244 relates to @file{libfoo.la} or @file{libbar.la} at the time it creates
5245 the link rule for these two libraries. Therefore the @option{-rpath}
5246 argument must be explicitly supplied.
5248 @c Keep in sync with ltcond.test.
5250 EXTRA_LTLIBRARIES = libfoo.la libbar.la
5251 lib_LTLIBRARIES = $(WANTEDLIBS)
5252 libfoo_la_SOURCES = foo.c @dots{}
5253 libfoo_la_LDFLAGS = -rpath '$(libdir)'
5254 libbar_la_SOURCES = bar.c @dots{}
5255 libbar_la_LDFLAGS = -rpath '$(libdir)'
5258 Here is how the same @file{Makefile.am} would look using Automake
5259 conditionals named @code{WANT_LIBFOO} and @code{WANT_LIBBAR}. Now
5260 Automake is able to compute the @option{-rpath} setting itself, because
5261 it's clear that both libraries will end up in @samp{$(libdir)} if they
5264 @c Keep in sync with ltcond.test.
5268 lib_LTLIBRARIES += libfoo.la
5271 lib_LTLIBRARIES += libbar.la
5273 libfoo_la_SOURCES = foo.c @dots{}
5274 libbar_la_SOURCES = bar.c @dots{}
5277 @node Conditional Libtool Sources
5278 @subsection Libtool Libraries with Conditional Sources
5280 Conditional compilation of sources in a library can be achieved in the
5281 same way as conditional compilation of sources in a program
5282 (@pxref{Conditional Sources}). The only difference is that
5283 @code{_LIBADD} should be used instead of @code{_LDADD} and that it
5284 should mention libtool objects (@file{.lo} files).
5286 So, to mimic the @file{hello} example from @ref{Conditional Sources},
5287 we could build a @file{libhello.la} library using either
5288 @file{hello-linux.c} or @file{hello-generic.c} with the following
5291 @c Keep in sync with ltcond2.test.
5293 lib_LTLIBRARIES = libhello.la
5294 libhello_la_SOURCES = hello-common.c
5295 EXTRA_libhello_la_SOURCES = hello-linux.c hello-generic.c
5296 libhello_la_LIBADD = $(HELLO_SYSTEM)
5297 libhello_la_DEPENDENCIES = $(HELLO_SYSTEM)
5301 And make sure @command{configure} defines @code{HELLO_SYSTEM} as
5302 either @file{hello-linux.lo} or @file{hello-@-generic.lo}.
5304 Or we could simply use an Automake conditional as follows.
5306 @c Keep in sync with ltcond2.test.
5308 lib_LTLIBRARIES = libhello.la
5309 libhello_la_SOURCES = hello-common.c
5311 libhello_la_SOURCES += hello-linux.c
5313 libhello_la_SOURCES += hello-generic.c
5317 @node Libtool Convenience Libraries
5318 @subsection Libtool Convenience Libraries
5319 @cindex convenience libraries, libtool
5320 @cindex libtool convenience libraries
5321 @vindex noinst_LTLIBRARIES
5322 @vindex check_LTLIBRARIES
5324 Sometimes you want to build libtool libraries that should not be
5325 installed. These are called @dfn{libtool convenience libraries} and
5326 are typically used to encapsulate many sublibraries, later gathered
5327 into one big installed library.
5329 Libtool convenience libraries are declared by directory-less variables
5330 such as @code{noinst_LTLIBRARIES}, @code{check_LTLIBRARIES}, or even
5331 @code{EXTRA_LTLIBRARIES}. Unlike installed libtool libraries they do
5332 not need an @option{-rpath} flag at link time (actually this is the only
5335 Convenience libraries listed in @code{noinst_LTLIBRARIES} are always
5336 built. Those listed in @code{check_LTLIBRARIES} are built only upon
5337 @samp{make check}. Finally, libraries listed in
5338 @code{EXTRA_LTLIBRARIES} are never built explicitly: Automake outputs
5339 rules to build them, but if the library does not appear as a Makefile
5340 dependency anywhere it won't be built (this is why
5341 @code{EXTRA_LTLIBRARIES} is used for conditional compilation).
5343 Here is a sample setup merging libtool convenience libraries from
5344 subdirectories into one main @file{libtop.la} library.
5346 @c Keep in sync with ltconv.test.
5348 # -- Top-level Makefile.am --
5349 SUBDIRS = sub1 sub2 @dots{}
5350 lib_LTLIBRARIES = libtop.la
5352 libtop_la_LIBADD = \
5357 # -- sub1/Makefile.am --
5358 noinst_LTLIBRARIES = libsub1.la
5359 libsub1_la_SOURCES = @dots{}
5361 # -- sub2/Makefile.am --
5362 # showing nested convenience libraries
5363 SUBDIRS = sub2.1 sub2.2 @dots{}
5364 noinst_LTLIBRARIES = libsub2.la
5365 libsub2_la_SOURCES =
5366 libsub2_la_LIBADD = \
5372 When using such setup, beware that @command{automake} will assume
5373 @file{libtop.la} is to be linked with the C linker. This is because
5374 @code{libtop_la_SOURCES} is empty, so @command{automake} picks C as
5375 default language. If @code{libtop_la_SOURCES} was not empty,
5376 @command{automake} would select the linker as explained in @ref{How
5377 the Linker is Chosen}.
5379 If one of the sublibraries contains non-C source, it is important that
5380 the appropriate linker be chosen. One way to achieve this is to
5381 pretend that there is such a non-C file among the sources of the
5382 library, thus forcing @command{automake} to select the appropriate
5383 linker. Here is the top-level @file{Makefile} of our example updated
5384 to force C++ linking.
5387 SUBDIRS = sub1 sub2 @dots{}
5388 lib_LTLIBRARIES = libtop.la
5390 # Dummy C++ source to cause C++ linking.
5391 nodist_EXTRA_libtop_la_SOURCES = dummy.cxx
5392 libtop_la_LIBADD = \
5398 @samp{EXTRA_*_SOURCES} variables are used to keep track of source
5399 files that might be compiled (this is mostly useful when doing
5400 conditional compilation using @code{AC_SUBST}, @pxref{Conditional
5401 Libtool Sources}), and the @code{nodist_} prefix means the listed
5402 sources are not to be distributed (@pxref{Program and Library
5403 Variables}). In effect the file @file{dummy.cxx} does not need to
5404 exist in the source tree. Of course if you have some real source file
5405 to list in @code{libtop_la_SOURCES} there is no point in cheating with
5406 @code{nodist_EXTRA_libtop_la_SOURCES}.
5409 @node Libtool Modules
5410 @subsection Libtool Modules
5411 @cindex modules, libtool
5412 @cindex libtool modules
5413 @cindex @option{-module}, libtool
5415 These are libtool libraries meant to be dlopened. They are
5416 indicated to libtool by passing @option{-module} at link-time.
5419 pkglib_LTLIBRARIES = mymodule.la
5420 mymodule_la_SOURCES = doit.c
5421 mymodule_la_LDFLAGS = -module
5424 Ordinarily, Automake requires that a library's name start with
5425 @code{lib}. However, when building a dynamically loadable module you
5426 might wish to use a "nonstandard" name. Automake will not complain
5427 about such nonstandard names if it knows the library being built is a
5428 libtool module, i.e., if @option{-module} explicitly appears in the
5429 library's @code{_LDFLAGS} variable (or in the common @code{AM_LDFLAGS}
5430 variable when no per-library @code{_LDFLAGS} variable is defined).
5432 As always, @code{AC_SUBST} variables are black boxes to Automake since
5433 their values are not yet known when @command{automake} is run.
5434 Therefore if @option{-module} is set via such a variable, Automake
5435 cannot notice it and will proceed as if the library was an ordinary
5436 libtool library, with strict naming.
5438 If @code{mymodule_la_SOURCES} is not specified, then it defaults to
5439 the single file @file{mymodule.c} (@pxref{Default _SOURCES}).
5442 @subsection @code{_LIBADD}, @code{_LDFLAGS}, and @code{_LIBTOOLFLAGS}
5443 @cindex @code{_LIBADD}, libtool
5444 @cindex @code{_LDFLAGS}, libtool
5445 @cindex @code{_LIBTOOLFLAGS}, libtool
5446 @vindex AM_LIBTOOLFLAGS
5447 @vindex LIBTOOLFLAGS
5448 @vindex maude_LIBTOOLFLAGS
5450 As shown in previous sections, the @samp{@var{library}_LIBADD}
5451 variable should be used to list extra libtool objects (@file{.lo}
5452 files) or libtool libraries (@file{.la}) to add to @var{library}.
5454 The @samp{@var{library}_LDFLAGS} variable is the place to list
5455 additional libtool linking flags, such as @option{-version-info},
5456 @option{-static}, and a lot more. @xref{Link mode, , Link mode,
5457 libtool, The Libtool Manual}.
5459 The @command{libtool} command has two kinds of options: mode-specific
5460 options and generic options. Mode-specific options such as the
5461 aforementioned linking flags should be lumped with the other flags
5462 passed to the tool invoked by @command{libtool} (hence the use of
5463 @samp{@var{library}_LDFLAGS} for libtool linking flags). Generic
5464 options include @option{--tag=@var{tag}} and @option{--silent}
5465 (@pxref{Invoking libtool, , Invoking @command{libtool}, libtool, The
5466 Libtool Manual} for more options) should appear before the mode
5467 selection on the command line; in @file{Makefile.am}s they should
5468 be listed in the @samp{@var{library}_LIBTOOLFLAGS} variable.
5470 If @samp{@var{library}_LIBTOOLFLAGS} is not defined, then the variable
5471 @code{AM_LIBTOOLFLAGS} is used instead.
5473 These flags are passed to libtool after the @option{--tag=@var{tag}}
5474 option computed by Automake (if any), so
5475 @samp{@var{library}_LIBTOOLFLAGS} (or @code{AM_LIBTOOLFLAGS}) is a
5476 good place to override or supplement the @option{--tag=@var{tag}}
5479 The libtool rules also use a @code{LIBTOOLFLAGS} variable that should
5480 not be set in @file{Makefile.am}: this is a user variable (@pxref{Flag
5481 Variables Ordering}. It allows users to run @samp{make
5482 LIBTOOLFLAGS=--silent}, for instance. Note that the verbosity of
5483 @command{libtool} can also be influenced with the Automake
5484 @option{silent-rules} option (@pxref{Options}).
5487 @node LTLIBOBJS, Libtool Issues, Libtool Flags, A Shared Library
5488 @subsection @code{LTLIBOBJS} and @code{LTALLOCA}
5489 @cindex @code{LTLIBOBJS}, special handling
5490 @cindex @code{LIBOBJS}, and Libtool
5491 @cindex @code{LTALLOCA}, special handling
5492 @cindex @code{ALLOCA}, and Libtool
5499 Where an ordinary library might include @samp{$(LIBOBJS)} or
5500 @samp{$(ALLOCA)} (@pxref{LIBOBJS}), a libtool library must use
5501 @samp{$(LTLIBOBJS)} or @samp{$(LTALLOCA)}. This is required because
5502 the object files that libtool operates on do not necessarily end in
5505 Nowadays, the computation of @code{LTLIBOBJS} from @code{LIBOBJS} is
5506 performed automatically by Autoconf (@pxref{AC_LIBOBJ vs LIBOBJS, ,
5507 @code{AC_LIBOBJ} vs.@: @code{LIBOBJS}, autoconf, The Autoconf Manual}).
5509 @node Libtool Issues
5510 @subsection Common Issues Related to Libtool's Use
5513 * Error required file ltmain.sh not found:: The need to run libtoolize
5514 * Objects created both with libtool and without:: Avoid a specific build race
5517 @node Error required file ltmain.sh not found
5518 @subsubsection Error: @samp{required file `./ltmain.sh' not found}
5519 @cindex @file{ltmain.sh} not found
5520 @cindex @command{libtoolize}, no longer run by @command{automake}
5521 @cindex @command{libtoolize} and @command{autoreconf}
5522 @cindex @command{autoreconf} and @command{libtoolize}
5523 @cindex @file{bootstrap.sh} and @command{autoreconf}
5524 @cindex @file{autogen.sh} and @command{autoreconf}
5526 Libtool comes with a tool called @command{libtoolize} that will
5527 install libtool's supporting files into a package. Running this
5528 command will install @file{ltmain.sh}. You should execute it before
5529 @command{aclocal} and @command{automake}.
5531 People upgrading old packages to newer autotools are likely to face
5532 this issue because older Automake versions used to call
5533 @command{libtoolize}. Therefore old build scripts do not call
5534 @command{libtoolize}.
5536 Since Automake 1.6, it has been decided that running
5537 @command{libtoolize} was none of Automake's business. Instead, that
5538 functionality has been moved into the @command{autoreconf} command
5539 (@pxref{autoreconf Invocation, , Using @command{autoreconf}, autoconf,
5540 The Autoconf Manual}). If you do not want to remember what to run and
5541 when, just learn the @command{autoreconf} command. Hopefully,
5542 replacing existing @file{bootstrap.sh} or @file{autogen.sh} scripts by
5543 a call to @command{autoreconf} should also free you from any similar
5544 incompatible change in the future.
5546 @node Objects created both with libtool and without
5547 @subsubsection Objects @samp{created with both libtool and without}
5549 Sometimes, the same source file is used both to build a libtool
5550 library and to build another non-libtool target (be it a program or
5553 Let's consider the following @file{Makefile.am}.
5557 prog_SOURCES = prog.c foo.c @dots{}
5559 lib_LTLIBRARIES = libfoo.la
5560 libfoo_la_SOURCES = foo.c @dots{}
5564 (In this trivial case the issue could be avoided by linking
5565 @file{libfoo.la} with @file{prog} instead of listing @file{foo.c} in
5566 @code{prog_SOURCES}. But let's assume we really want to keep
5567 @file{prog} and @file{libfoo.la} separate.)
5569 Technically, it means that we should build @file{foo.$(OBJEXT)} for
5570 @file{prog}, and @file{foo.lo} for @file{libfoo.la}. The problem is
5571 that in the course of creating @file{foo.lo}, libtool may erase (or
5572 replace) @file{foo.$(OBJEXT)}, and this cannot be avoided.
5574 Therefore, when Automake detects this situation it will complain
5575 with a message such as
5577 object `foo.$(OBJEXT)' created both with libtool and without
5580 A workaround for this issue is to ensure that these two objects get
5581 different basenames. As explained in @ref{Renamed Objects}, this
5582 happens automatically when per-targets flags are used.
5586 prog_SOURCES = prog.c foo.c @dots{}
5587 prog_CFLAGS = $(AM_CFLAGS)
5589 lib_LTLIBRARIES = libfoo.la
5590 libfoo_la_SOURCES = foo.c @dots{}
5594 Adding @samp{prog_CFLAGS = $(AM_CFLAGS)} is almost a no-op, because
5595 when the @code{prog_CFLAGS} is defined, it is used instead of
5596 @code{AM_CFLAGS}. However as a side effect it will cause
5597 @file{prog.c} and @file{foo.c} to be compiled as
5598 @file{prog-prog.$(OBJEXT)} and @file{prog-foo.$(OBJEXT)}, which solves
5601 @node Program and Library Variables
5602 @section Program and Library Variables
5604 Associated with each program is a collection of variables that can be
5605 used to modify how that program is built. There is a similar list of
5606 such variables for each library. The canonical name of the program (or
5607 library) is used as a base for naming these variables.
5609 In the list below, we use the name ``maude'' to refer to the program or
5610 library. In your @file{Makefile.am} you would replace this with the
5611 canonical name of your program. This list also refers to ``maude'' as a
5612 program, but in general the same rules apply for both static and dynamic
5613 libraries; the documentation below notes situations where programs and
5618 This variable, if it exists, lists all the source files that are
5619 compiled to build the program. These files are added to the
5620 distribution by default. When building the program, Automake will cause
5621 each source file to be compiled to a single @file{.o} file (or
5622 @file{.lo} when using libtool). Normally these object files are named
5623 after the source file, but other factors can change this. If a file in
5624 the @code{_SOURCES} variable has an unrecognized extension, Automake
5625 will do one of two things with it. If a suffix rule exists for turning
5626 files with the unrecognized extension into @file{.o} files, then
5627 @command{automake} will treat this file as it will any other source file
5628 (@pxref{Support for Other Languages}). Otherwise, the file will be
5629 ignored as though it were a header file.
5631 The prefixes @code{dist_} and @code{nodist_} can be used to control
5632 whether files listed in a @code{_SOURCES} variable are distributed.
5633 @code{dist_} is redundant, as sources are distributed by default, but it
5634 can be specified for clarity if desired.
5636 It is possible to have both @code{dist_} and @code{nodist_} variants of
5637 a given @code{_SOURCES} variable at once; this lets you easily
5638 distribute some files and not others, for instance:
5641 nodist_maude_SOURCES = nodist.c
5642 dist_maude_SOURCES = dist-me.c
5645 By default the output file (on Unix systems, the @file{.o} file) will
5646 be put into the current build directory. However, if the option
5647 @option{subdir-objects} is in effect in the current directory then the
5648 @file{.o} file will be put into the subdirectory named after the
5649 source file. For instance, with @option{subdir-objects} enabled,
5650 @file{sub/dir/file.c} will be compiled to @file{sub/dir/file.o}. Some
5651 people prefer this mode of operation. You can specify
5652 @option{subdir-objects} in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
5653 @cindex Subdirectory, objects in
5654 @cindex Objects in subdirectory
5657 @item EXTRA_maude_SOURCES
5658 Automake needs to know the list of files you intend to compile
5659 @emph{statically}. For one thing, this is the only way Automake has of
5660 knowing what sort of language support a given @file{Makefile.in}
5661 requires. @footnote{There are other, more obscure reasons for
5662 this limitation as well.} This means that, for example, you can't put a
5663 configure substitution like @samp{@@my_sources@@} into a @samp{_SOURCES}
5664 variable. If you intend to conditionally compile source files and use
5665 @file{configure} to substitute the appropriate object names into, e.g.,
5666 @code{_LDADD} (see below), then you should list the corresponding source
5667 files in the @code{EXTRA_} variable.
5669 This variable also supports @code{dist_} and @code{nodist_} prefixes.
5670 For instance, @code{nodist_EXTRA_maude_SOURCES} would list extra
5671 sources that may need to be built, but should not be distributed.
5674 A static library is created by default by invoking @samp{$(AR)
5675 $(ARFLAGS)} followed by the name of the library and then the objects
5676 being put into the library. You can override this by setting the
5677 @code{_AR} variable. This is usually used with C++; some C++
5678 compilers require a special invocation in order to instantiate all the
5679 templates that should go into a library. For instance, the SGI C++
5680 compiler likes this variable set like so:
5682 libmaude_a_AR = $(CXX) -ar -o
5686 Extra objects can be added to a @emph{library} using the @code{_LIBADD}
5687 variable. For instance, this should be used for objects determined by
5688 @command{configure} (@pxref{A Library}).
5690 In the case of libtool libraries, @code{maude_LIBADD} can also refer
5691 to other libtool libraries.
5694 Extra objects (@file{*.$(OBJEXT)}) and libraries (@file{*.a},
5695 @file{*.la}) can be added to a @emph{program} by listing them in the
5696 @code{_LDADD} variable. For instance, this should be used for objects
5697 determined by @command{configure} (@pxref{Linking}).
5699 @code{_LDADD} and @code{_LIBADD} are inappropriate for passing
5700 program-specific linker flags (except for @option{-l}, @option{-L},
5701 @option{-dlopen} and @option{-dlpreopen}). Use the @code{_LDFLAGS} variable
5704 For instance, if your @file{configure.ac} uses @code{AC_PATH_XTRA}, you
5705 could link your program against the X libraries like so:
5708 maude_LDADD = $(X_PRE_LIBS) $(X_LIBS) $(X_EXTRA_LIBS)
5711 We recommend that you use @option{-l} and @option{-L} only when
5712 referring to third-party libraries, and give the explicit file names
5713 of any library built by your package. Doing so will ensure that
5714 @code{maude_DEPENDENCIES} (see below) is correctly defined by default.
5717 This variable is used to pass extra flags to the link step of a program
5718 or a shared library. It overrides the @code{AM_LDFLAGS} variable.
5720 @item maude_LIBTOOLFLAGS
5721 This variable is used to pass extra options to @command{libtool}.
5722 It overrides the @code{AM_LIBTOOLFLAGS} variable.
5723 These options are output before @command{libtool}'s @option{--mode=@var{mode}}
5724 option, so they should not be mode-specific options (those belong to
5725 the compiler or linker flags). @xref{Libtool Flags}.
5727 @item maude_DEPENDENCIES
5728 @itemx EXTRA_maude_DEPENDENCIES
5729 It is also occasionally useful to have a target (program or library)
5730 depend on some other file that is not actually part of that target.
5731 This can be done using the @code{_DEPENDENCIES} variable. Each
5732 target depends on the contents of such a variable, but no further
5733 interpretation is done.
5735 Since these dependencies are associated to the link rule used to
5736 create the programs they should normally list files used by the link
5737 command. That is @file{*.$(OBJEXT)}, @file{*.a}, or @file{*.la} files
5738 for programs; @file{*.lo} and @file{*.la} files for Libtool libraries;
5739 and @file{*.$(OBJEXT)} files for static libraries. In rare cases you
5740 may need to add other kinds of files such as linker scripts, but
5741 @emph{listing a source file in @code{_DEPENDENCIES} is wrong}. If
5742 some source file needs to be built before all the components of a
5743 program are built, consider using the @code{BUILT_SOURCES} variable
5746 If @code{_DEPENDENCIES} is not supplied, it is computed by Automake.
5747 The automatically-assigned value is the contents of @code{_LDADD} or
5748 @code{_LIBADD}, with most configure substitutions, @option{-l}, @option{-L},
5749 @option{-dlopen} and @option{-dlpreopen} options removed. The configure
5750 substitutions that are left in are only @samp{$(LIBOBJS)} and
5751 @samp{$(ALLOCA)}; these are left because it is known that they will not
5752 cause an invalid value for @code{_DEPENDENCIES} to be generated.
5754 @code{_DEPENDENCIES} is more likely used to perform conditional
5755 compilation using an @code{AC_SUBST} variable that contains a list of
5756 objects. @xref{Conditional Sources}, and @ref{Conditional Libtool
5759 The @code{EXTRA_*_DEPENDENCIES} variable may be useful for cases where
5760 you merely want to augment the @command{automake}-generated
5761 @code{_DEPENDENCIES} variable rather than replacing it.
5764 You can override the linker on a per-program basis. By default the
5765 linker is chosen according to the languages used by the program. For
5766 instance, a program that includes C++ source code would use the C++
5767 compiler to link. The @code{_LINK} variable must hold the name of a
5768 command that can be passed all the @file{.o} file names and libraries
5769 to link against as arguments. Note that the name of the underlying
5770 program is @emph{not} passed to @code{_LINK}; typically one uses
5774 maude_LINK = $(CCLD) -magic -o $@@
5777 If a @code{_LINK} variable is not supplied, it may still be generated
5778 and used by Automake due to the use of per-target link flags such as
5779 @code{_CFLAGS}, @code{_LDFLAGS} or @code{_LIBTOOLFLAGS}, in cases where
5782 @item maude_CCASFLAGS
5784 @itemx maude_CPPFLAGS
5785 @itemx maude_CXXFLAGS
5787 @itemx maude_GCJFLAGS
5789 @itemx maude_OBJCFLAGS
5791 @itemx maude_UPCFLAGS
5793 @cindex per-target compilation flags, defined
5794 Automake allows you to set compilation flags on a per-program (or
5795 per-library) basis. A single source file can be included in several
5796 programs, and it will potentially be compiled with different flags for
5797 each program. This works for any language directly supported by
5798 Automake. These @dfn{per-target compilation flags} are
5808 @samp{_UPCFLAGS}, and
5811 When using a per-target compilation flag, Automake will choose a
5812 different name for the intermediate object files. Ordinarily a file
5813 like @file{sample.c} will be compiled to produce @file{sample.o}.
5814 However, if the program's @code{_CFLAGS} variable is set, then the
5815 object file will be named, for instance, @file{maude-sample.o}. (See
5816 also @ref{Renamed Objects}.) The use of per-target compilation flags
5817 with C sources requires that the macro @code{AM_PROG_CC_C_O} be called
5818 from @file{configure.ac}.
5820 In compilations with per-target flags, the ordinary @samp{AM_} form of
5821 the flags variable is @emph{not} automatically included in the
5822 compilation (however, the user form of the variable @emph{is} included).
5823 So for instance, if you want the hypothetical @file{maude} compilations
5824 to also use the value of @code{AM_CFLAGS}, you would need to write:
5827 maude_CFLAGS = @dots{} your flags @dots{} $(AM_CFLAGS)
5830 @xref{Flag Variables Ordering}, for more discussion about the
5831 interaction between user variables, @samp{AM_} shadow variables, and
5832 per-target variables.
5834 @item maude_SHORTNAME
5835 On some platforms the allowable file names are very short. In order to
5836 support these systems and per-target compilation flags at the same
5837 time, Automake allows you to set a ``short name'' that will influence
5838 how intermediate object files are named. For instance, in the following
5842 bin_PROGRAMS = maude
5843 maude_CPPFLAGS = -DSOMEFLAG
5845 maude_SOURCES = sample.c @dots{}
5849 the object file would be named @file{m-sample.o} rather than
5850 @file{maude-sample.o}.
5852 This facility is rarely needed in practice,
5853 and we recommend avoiding it until you find it is required.
5856 @node Default _SOURCES
5857 @section Default @code{_SOURCES}
5861 @cindex @code{_SOURCES}, default
5862 @cindex default @code{_SOURCES}
5863 @vindex AM_DEFAULT_SOURCE_EXT
5865 @code{_SOURCES} variables are used to specify source files of programs
5866 (@pxref{A Program}), libraries (@pxref{A Library}), and Libtool
5867 libraries (@pxref{A Shared Library}).
5869 When no such variable is specified for a target, Automake will define
5870 one itself. The default is to compile a single C file whose base name
5871 is the name of the target itself, with any extension replaced by
5872 @code{AM_DEFAULT_SOURCE_EXT}, which defaults to @file{.c}.
5874 For example if you have the following somewhere in your
5875 @file{Makefile.am} with no corresponding @code{libfoo_a_SOURCES}:
5878 lib_LIBRARIES = libfoo.a sub/libc++.a
5882 @file{libfoo.a} will be built using a default source file named
5883 @file{libfoo.c}, and @file{sub/libc++.a} will be built from
5884 @file{sub/libc++.c}. (In older versions @file{sub/libc++.a}
5885 would be built from @file{sub_libc___a.c}, i.e., the default source
5886 was the canonized name of the target, with @file{.c} appended.
5887 We believe the new behavior is more sensible, but for backward
5888 compatibility @command{automake} will use the old name if a file or a rule
5889 with that name exists and @code{AM_DEFAULT_SOURCE_EXT} is not used.)
5891 @cindex @code{check_PROGRAMS} example
5892 @vindex check_PROGRAMS
5893 Default sources are mainly useful in test suites, when building many
5894 test programs each from a single source. For instance, in
5897 check_PROGRAMS = test1 test2 test3
5898 AM_DEFAULT_SOURCE_EXT = .cpp
5902 @file{test1}, @file{test2}, and @file{test3} will be built
5903 from @file{test1.cpp}, @file{test2.cpp}, and @file{test3.cpp}.
5904 Without the last line, they will be built from @file{test1.c},
5905 @file{test2.c}, and @file{test3.c}.
5907 @cindex Libtool modules, default source example
5908 @cindex default source, Libtool modules example
5909 Another case where this is convenient is building many Libtool modules
5910 (@file{module@var{n}.la}), each defined in its own file
5911 (@file{module@var{n}.c}).
5914 AM_LDFLAGS = -module
5915 lib_LTLIBRARIES = module1.la module2.la module3.la
5918 @cindex empty @code{_SOURCES}
5919 @cindex @code{_SOURCES}, empty
5920 Finally, there is one situation where this default source computation
5921 needs to be avoided: when a target should not be built from sources.
5922 We already saw such an example in @ref{true}; this happens when all
5923 the constituents of a target have already been compiled and just need
5924 to be combined using a @code{_LDADD} variable. Then it is necessary
5925 to define an empty @code{_SOURCES} variable, so that @command{automake}
5926 does not compute a default.
5929 bin_PROGRAMS = target
5931 target_LDADD = libmain.a libmisc.a
5935 @section Special handling for @code{LIBOBJS} and @code{ALLOCA}
5937 @cindex @code{LIBOBJS}, example
5938 @cindex @code{ALLOCA}, example
5939 @cindex @code{LIBOBJS}, special handling
5940 @cindex @code{ALLOCA}, special handling
5946 The @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} variables list object
5947 files that should be compiled into the project to provide an
5948 implementation for functions that are missing or broken on the host
5949 system. They are substituted by @file{configure}.
5953 These variables are defined by Autoconf macros such as
5954 @code{AC_LIBOBJ}, @code{AC_REPLACE_FUNCS} (@pxref{Generic Functions, ,
5955 Generic Function Checks, autoconf, The Autoconf Manual}), or
5956 @code{AC_FUNC_ALLOCA} (@pxref{Particular Functions, , Particular
5957 Function Checks, autoconf, The Autoconf Manual}). Many other Autoconf
5958 macros call @code{AC_LIBOBJ} or @code{AC_REPLACE_FUNCS} to
5959 populate @samp{$(LIBOBJS)}.
5961 @acindex AC_LIBSOURCE
5963 Using these variables is very similar to doing conditional compilation
5964 using @code{AC_SUBST} variables, as described in @ref{Conditional
5965 Sources}. That is, when building a program, @samp{$(LIBOBJS)} and
5966 @samp{$(ALLOCA)} should be added to the associated @samp{*_LDADD}
5967 variable, or to the @samp{*_LIBADD} variable when building a library.
5968 However there is no need to list the corresponding sources in
5969 @samp{EXTRA_*_SOURCES} nor to define @samp{*_DEPENDENCIES}. Automake
5970 automatically adds @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} to the
5971 dependencies, and it will discover the list of corresponding source
5972 files automatically (by tracing the invocations of the
5973 @code{AC_LIBSOURCE} Autoconf macros). If you have already defined
5974 @samp{*_DEPENDENCIES} explicitly for an unrelated reason, then you
5975 either need to add these variables manually, or use
5976 @samp{EXTRA_*_DEPENDENCIES} instead of @samp{*_DEPENDENCIES}.
5978 These variables are usually used to build a portability library that
5979 is linked with all the programs of the project. We now review a
5980 sample setup. First, @file{configure.ac} contains some checks that
5981 affect either @code{LIBOBJS} or @code{ALLOCA}.
5986 AC_CONFIG_LIBOBJ_DIR([lib])
5988 AC_FUNC_MALLOC dnl May add malloc.$(OBJEXT) to LIBOBJS
5989 AC_FUNC_MEMCMP dnl May add memcmp.$(OBJEXT) to LIBOBJS
5990 AC_REPLACE_FUNCS([strdup]) dnl May add strdup.$(OBJEXT) to LIBOBJS
5991 AC_FUNC_ALLOCA dnl May add alloca.$(OBJEXT) to ALLOCA
6000 @acindex AC_CONFIG_LIBOBJ_DIR
6002 The @code{AC_CONFIG_LIBOBJ_DIR} tells Autoconf that the source files
6003 of these object files are to be found in the @file{lib/} directory.
6004 Automake can also use this information, otherwise it expects the
6005 source files are to be in the directory where the @samp{$(LIBOBJS)}
6006 and @samp{$(ALLOCA)} variables are used.
6008 The @file{lib/} directory should therefore contain @file{malloc.c},
6009 @file{memcmp.c}, @file{strdup.c}, @file{alloca.c}. Here is its
6015 noinst_LIBRARIES = libcompat.a
6016 libcompat_a_SOURCES =
6017 libcompat_a_LIBADD = $(LIBOBJS) $(ALLOCA)
6020 The library can have any name, of course, and anyway it is not going
6021 to be installed: it just holds the replacement versions of the missing
6022 or broken functions so we can later link them in. Many projects
6023 also include extra functions, specific to the project, in that
6024 library: they are simply added on the @code{_SOURCES} line.
6026 @cindex Empty libraries and @samp{$(LIBOBJS)}
6027 @cindex @samp{$(LIBOBJS)} and empty libraries
6028 There is a small trap here, though: @samp{$(LIBOBJS)} and
6029 @samp{$(ALLOCA)} might be empty, and building an empty library is not
6030 portable. You should ensure that there is always something to put in
6031 @file{libcompat.a}. Most projects will also add some utility
6032 functions in that directory, and list them in
6033 @code{libcompat_a_SOURCES}, so in practice @file{libcompat.a} cannot
6036 Finally here is how this library could be used from the @file{src/}
6042 # Link all programs in this directory with libcompat.a
6043 LDADD = ../lib/libcompat.a
6045 bin_PROGRAMS = tool1 tool2 @dots{}
6046 tool1_SOURCES = @dots{}
6047 tool2_SOURCES = @dots{}
6050 When option @option{subdir-objects} is not used, as in the above
6051 example, the variables @samp{$(LIBOBJS)} or @samp{$(ALLOCA)} can only
6052 be used in the directory where their sources lie. E.g., here it would
6053 be wrong to use @samp{$(LIBOBJS)} or @samp{$(ALLOCA)} in
6054 @file{src/Makefile.am}. However if both @option{subdir-objects} and
6055 @code{AC_CONFIG_LIBOBJ_DIR} are used, it is OK to use these variables
6056 in other directories. For instance @file{src/Makefile.am} could be
6062 AUTOMAKE_OPTIONS = subdir-objects
6063 LDADD = $(LIBOBJS) $(ALLOCA)
6065 bin_PROGRAMS = tool1 tool2 @dots{}
6066 tool1_SOURCES = @dots{}
6067 tool2_SOURCES = @dots{}
6070 Because @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} contain object
6071 file names that end with @samp{.$(OBJEXT)}, they are not suitable for
6072 Libtool libraries (where the expected object extension is @file{.lo}):
6073 @code{LTLIBOBJS} and @code{LTALLOCA} should be used instead.
6075 @code{LTLIBOBJS} is defined automatically by Autoconf and should not
6076 be defined by hand (as in the past), however at the time of writing
6077 @code{LTALLOCA} still needs to be defined from @code{ALLOCA} manually.
6078 @xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs.@: @code{LIBOBJS},
6079 autoconf, The Autoconf Manual}.
6082 @node Program Variables
6083 @section Variables used when building a program
6085 Occasionally it is useful to know which @file{Makefile} variables
6086 Automake uses for compilations, and in which order (@pxref{Flag
6087 Variables Ordering}); for instance, you might need to do your own
6088 compilation in some special cases.
6090 Some variables are inherited from Autoconf; these are @code{CC},
6091 @code{CFLAGS}, @code{CPPFLAGS}, @code{DEFS}, @code{LDFLAGS}, and
6100 There are some additional variables that Automake defines on its own:
6104 The contents of this variable are passed to every compilation that invokes
6105 the C preprocessor; it is a list of arguments to the preprocessor. For
6106 instance, @option{-I} and @option{-D} options should be listed here.
6108 Automake already provides some @option{-I} options automatically, in a
6109 separate variable that is also passed to every compilation that invokes
6110 the C preprocessor. In particular it generates @samp{-I.},
6111 @samp{-I$(srcdir)}, and a @option{-I} pointing to the directory holding
6112 @file{config.h} (if you've used @code{AC_CONFIG_HEADERS} or
6113 @code{AM_CONFIG_HEADER}). You can disable the default @option{-I}
6114 options using the @option{nostdinc} option.
6116 When a file to be included is generated during the build and not part
6117 of a distribution tarball, its location is under @code{$(builddir)},
6118 not under @code{$(srcdir)}. This matters especially for packages that
6119 use header files placed in sub-directories and want to allow builds
6120 outside the source tree (@pxref{VPATH Builds}). In that case we
6121 recommend to use a pair of @option{-I} options, such as, e.g.,
6122 @samp{-Isome/subdir -I$(srcdir)/some/subdir} or
6123 @samp{-I$(top_builddir)/some/subdir -I$(top_srcdir)/some/subdir}.
6124 Note that the reference to the build tree should come before the
6125 reference to the source tree, so that accidentally leftover generated
6126 files in the source directory are ignored.
6128 @code{AM_CPPFLAGS} is ignored in preference to a per-executable (or
6129 per-library) @code{_CPPFLAGS} variable if it is defined.
6132 This does the same job as @code{AM_CPPFLAGS} (or any per-target
6133 @code{_CPPFLAGS} variable if it is used). It is an older name for the
6134 same functionality. This variable is deprecated; we suggest using
6135 @code{AM_CPPFLAGS} and per-target @code{_CPPFLAGS} instead.
6138 This is the variable the @file{Makefile.am} author can use to pass
6139 in additional C compiler flags. It is more fully documented elsewhere.
6140 In some situations, this is not used, in preference to the
6141 per-executable (or per-library) @code{_CFLAGS}.
6144 This is the command used to actually compile a C source file. The
6145 file name is appended to form the complete command line.
6148 This is the variable the @file{Makefile.am} author can use to pass
6149 in additional linker flags. In some situations, this is not used, in
6150 preference to the per-executable (or per-library) @code{_LDFLAGS}.
6153 This is the command used to actually link a C program. It already
6154 includes @samp{-o $@@} and the usual variable references (for instance,
6155 @code{CFLAGS}); it takes as ``arguments'' the names of the object files
6156 and libraries to link in. This variable is not used when the linker is
6157 overridden with a per-target @code{_LINK} variable or per-target flags
6158 cause Automake to define such a @code{_LINK} variable.
6163 @section Yacc and Lex support
6165 Automake has somewhat idiosyncratic support for Yacc and Lex.
6167 Automake assumes that the @file{.c} file generated by @command{yacc}
6168 (or @command{lex}) should be named using the basename of the input
6169 file. That is, for a yacc source file @file{foo.y}, Automake will
6170 cause the intermediate file to be named @file{foo.c} (as opposed to
6171 @file{y.tab.c}, which is more traditional).
6173 The extension of a yacc source file is used to determine the extension
6174 of the resulting C or C++ source and header files. Note that header
6175 files are generated only when the @option{-d} Yacc option is used; see
6176 below for more information about this flag, and how to specify it.
6177 Files with the extension @file{.y} will thus be turned into @file{.c}
6178 sources and @file{.h} headers; likewise, @file{.yy} will become
6179 @file{.cc} and @file{.hh}, @file{.y++} will become @file{c++} and
6180 @file{h++}, @file{.yxx} will become @file{.cxx} and @file{.hxx},
6181 and @file{.ypp} will become @file{.cpp} and @file{.hpp}.
6183 Similarly, lex source files can be used to generate C or C++; the
6184 extensions @file{.l}, @file{.ll}, @file{.l++}, @file{.lxx}, and
6185 @file{.lpp} are recognized.
6187 You should never explicitly mention the intermediate (C or C++) file
6188 in any @code{SOURCES} variable; only list the source file.
6190 The intermediate files generated by @command{yacc} (or @command{lex})
6191 will be included in any distribution that is made. That way the user
6192 doesn't need to have @command{yacc} or @command{lex}.
6194 If a @command{yacc} source file is seen, then your @file{configure.ac} must
6195 define the variable @code{YACC}. This is most easily done by invoking
6196 the macro @code{AC_PROG_YACC} (@pxref{Particular Programs, , Particular
6197 Program Checks, autoconf, The Autoconf Manual}).
6201 When @code{yacc} is invoked, it is passed @code{AM_YFLAGS} and
6202 @code{YFLAGS}. The latter is a user variable and the former is
6203 intended for the @file{Makefile.am} author.
6205 @code{AM_YFLAGS} is usually used to pass the @option{-d} option to
6206 @command{yacc}. Automake knows what this means and will automatically
6207 adjust its rules to update and distribute the header file built by
6208 @samp{yacc -d}@footnote{Please note that @command{automake} recognizes
6209 @option{-d} in @code{AM_YFLAGS} only if it is not clustered with other
6210 options; for example, it won't be recognized if @code{AM_YFLAGS} is
6211 @option{-dt}, but it will be if @code{AM_YFLAGS} is @option{-d -t} or
6213 What Automake cannot guess, though, is where this
6214 header will be used: it is up to you to ensure the header gets built
6215 before it is first used. Typically this is necessary in order for
6216 dependency tracking to work when the header is included by another
6217 file. The common solution is listing the header file in
6218 @code{BUILT_SOURCES} (@pxref{Sources}) as follows.
6221 BUILT_SOURCES = parser.h
6224 foo_SOURCES = @dots{} parser.y @dots{}
6227 If a @command{lex} source file is seen, then your @file{configure.ac}
6228 must define the variable @code{LEX}. You can use @code{AC_PROG_LEX}
6229 to do this (@pxref{Particular Programs, , Particular Program Checks,
6230 autoconf, The Autoconf Manual}), but using @code{AM_PROG_LEX} macro
6231 (@pxref{Macros}) is recommended.
6235 When @command{lex} is invoked, it is passed @code{AM_LFLAGS} and
6236 @code{LFLAGS}. The latter is a user variable and the former is
6237 intended for the @file{Makefile.am} author.
6239 When @code{AM_MAINTAINER_MODE} (@pxref{maintainer-mode}) is used, the
6240 rebuild rule for distributed Yacc and Lex sources are only used when
6241 @code{maintainer-mode} is enabled, or when the files have been erased.
6243 @cindex @command{ylwrap}
6244 @cindex @command{yacc}, multiple parsers
6245 @cindex Multiple @command{yacc} parsers
6246 @cindex Multiple @command{lex} lexers
6247 @cindex @command{lex}, multiple lexers
6249 When @command{lex} or @command{yacc} sources are used, @code{automake
6250 -i} automatically installs an auxiliary program called
6251 @command{ylwrap} in your package (@pxref{Auxiliary Programs}). This
6252 program is used by the build rules to rename the output of these
6253 tools, and makes it possible to include multiple @command{yacc} (or
6254 @command{lex}) source files in a single directory. (This is necessary
6255 because yacc's output file name is fixed, and a parallel make could
6256 conceivably invoke more than one instance of @command{yacc}
6259 For @command{yacc}, simply managing locking is insufficient. The output of
6260 @command{yacc} always uses the same symbol names internally, so it isn't
6261 possible to link two @command{yacc} parsers into the same executable.
6263 We recommend using the following renaming hack used in @command{gdb}:
6265 #define yymaxdepth c_maxdepth
6266 #define yyparse c_parse
6268 #define yyerror c_error
6269 #define yylval c_lval
6270 #define yychar c_char
6271 #define yydebug c_debug
6272 #define yypact c_pact
6279 #define yyexca c_exca
6280 #define yyerrflag c_errflag
6281 #define yynerrs c_nerrs
6285 #define yy_yys c_yys
6286 #define yystate c_state
6289 #define yy_yyv c_yyv
6291 #define yylloc c_lloc
6292 #define yyreds c_reds
6293 #define yytoks c_toks
6294 #define yylhs c_yylhs
6295 #define yylen c_yylen
6296 #define yydefred c_yydefred
6297 #define yydgoto c_yydgoto
6298 #define yysindex c_yysindex
6299 #define yyrindex c_yyrindex
6300 #define yygindex c_yygindex
6301 #define yytable c_yytable
6302 #define yycheck c_yycheck
6303 #define yyname c_yyname
6304 #define yyrule c_yyrule
6307 For each define, replace the @samp{c_} prefix with whatever you like.
6308 These defines work for @command{bison}, @command{byacc}, and
6309 traditional @code{yacc}s. If you find a parser generator that uses a
6310 symbol not covered here, please report the new name so it can be added
6315 @section C++ Support
6318 @cindex Support for C++
6320 Automake includes full support for C++.
6322 Any package including C++ code must define the output variable
6323 @code{CXX} in @file{configure.ac}; the simplest way to do this is to use
6324 the @code{AC_PROG_CXX} macro (@pxref{Particular Programs, , Particular
6325 Program Checks, autoconf, The Autoconf Manual}).
6327 A few additional variables are defined when a C++ source file is seen:
6331 The name of the C++ compiler.
6334 Any flags to pass to the C++ compiler.
6337 The maintainer's variant of @code{CXXFLAGS}.
6340 The command used to actually compile a C++ source file. The file name
6341 is appended to form the complete command line.
6344 The command used to actually link a C++ program.
6348 @node Objective C Support
6349 @section Objective C Support
6351 @cindex Objective C support
6352 @cindex Support for Objective C
6354 Automake includes some support for Objective C.
6356 Any package including Objective C code must define the output variable
6357 @code{OBJC} in @file{configure.ac}; the simplest way to do this is to use
6358 the @code{AC_PROG_OBJC} macro (@pxref{Particular Programs, , Particular
6359 Program Checks, autoconf, The Autoconf Manual}).
6361 A few additional variables are defined when an Objective C source file
6366 The name of the Objective C compiler.
6369 Any flags to pass to the Objective C compiler.
6372 The maintainer's variant of @code{OBJCFLAGS}.
6375 The command used to actually compile an Objective C source file. The
6376 file name is appended to form the complete command line.
6379 The command used to actually link an Objective C program.
6383 @node Unified Parallel C Support
6384 @section Unified Parallel C Support
6386 @cindex Unified Parallel C support
6387 @cindex Support for Unified Parallel C
6389 Automake includes some support for Unified Parallel C.
6391 Any package including Unified Parallel C code must define the output
6392 variable @code{UPC} in @file{configure.ac}; the simplest way to do
6393 this is to use the @code{AM_PROG_UPC} macro (@pxref{Public Macros}).
6395 A few additional variables are defined when a Unified Parallel C
6396 source file is seen:
6400 The name of the Unified Parallel C compiler.
6403 Any flags to pass to the Unified Parallel C compiler.
6406 The maintainer's variant of @code{UPCFLAGS}.
6409 The command used to actually compile a Unified Parallel C source file.
6410 The file name is appended to form the complete command line.
6413 The command used to actually link a Unified Parallel C program.
6417 @node Assembly Support
6418 @section Assembly Support
6420 Automake includes some support for assembly code. There are two forms
6421 of assembler files: normal (@file{*.s}) and preprocessed by @code{CPP}
6422 (@file{*.S} or @file{*.sx}).
6427 @vindex AM_CCASFLAGS
6429 The variable @code{CCAS} holds the name of the compiler used to build
6430 assembly code. This compiler must work a bit like a C compiler; in
6431 particular it must accept @option{-c} and @option{-o}. The values of
6432 @code{CCASFLAGS} and @code{AM_CCASFLAGS} (or its per-target
6433 definition) is passed to the compilation. For preprocessed files,
6434 @code{DEFS}, @code{DEFAULT_INCLUDES}, @code{INCLUDES}, @code{CPPFLAGS}
6435 and @code{AM_CPPFLAGS} are also used.
6437 The autoconf macro @code{AM_PROG_AS} will define @code{CCAS} and
6438 @code{CCASFLAGS} for you (unless they are already set, it simply sets
6439 @code{CCAS} to the C compiler and @code{CCASFLAGS} to the C compiler
6440 flags), but you are free to define these variables by other means.
6442 Only the suffixes @file{.s}, @file{.S}, and @file{.sx} are recognized by
6443 @command{automake} as being files containing assembly code.
6446 @node Fortran 77 Support
6447 @comment node-name, next, previous, up
6448 @section Fortran 77 Support
6450 @cindex Fortran 77 support
6451 @cindex Support for Fortran 77
6453 Automake includes full support for Fortran 77.
6455 Any package including Fortran 77 code must define the output variable
6456 @code{F77} in @file{configure.ac}; the simplest way to do this is to use
6457 the @code{AC_PROG_F77} macro (@pxref{Particular Programs, , Particular
6458 Program Checks, autoconf, The Autoconf Manual}).
6460 A few additional variables are defined when a Fortran 77 source file is
6466 The name of the Fortran 77 compiler.
6469 Any flags to pass to the Fortran 77 compiler.
6472 The maintainer's variant of @code{FFLAGS}.
6475 Any flags to pass to the Ratfor compiler.
6478 The maintainer's variant of @code{RFLAGS}.
6481 The command used to actually compile a Fortran 77 source file. The file
6482 name is appended to form the complete command line.
6485 The command used to actually link a pure Fortran 77 program or shared
6490 Automake can handle preprocessing Fortran 77 and Ratfor source files in
6491 addition to compiling them@footnote{Much, if not most, of the
6492 information in the following sections pertaining to preprocessing
6493 Fortran 77 programs was taken almost verbatim from @ref{Catalogue of
6494 Rules, , Catalogue of Rules, make, The GNU Make Manual}.}. Automake
6495 also contains some support for creating programs and shared libraries
6496 that are a mixture of Fortran 77 and other languages (@pxref{Mixing
6497 Fortran 77 With C and C++}).
6499 These issues are covered in the following sections.
6502 * Preprocessing Fortran 77:: Preprocessing Fortran 77 sources
6503 * Compiling Fortran 77 Files:: Compiling Fortran 77 sources
6504 * Mixing Fortran 77 With C and C++:: Mixing Fortran 77 With C and C++
6508 @node Preprocessing Fortran 77
6509 @comment node-name, next, previous, up
6510 @subsection Preprocessing Fortran 77
6512 @cindex Preprocessing Fortran 77
6513 @cindex Fortran 77, Preprocessing
6514 @cindex Ratfor programs
6516 @file{N.f} is made automatically from @file{N.F} or @file{N.r}. This
6517 rule runs just the preprocessor to convert a preprocessable Fortran 77
6518 or Ratfor source file into a strict Fortran 77 source file. The precise
6519 command used is as follows:
6524 @code{$(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)@*
6525 $(AM_FFLAGS) $(FFLAGS)}
6528 @code{$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
6533 @node Compiling Fortran 77 Files
6534 @comment node-name, next, previous, up
6535 @subsection Compiling Fortran 77 Files
6537 @file{N.o} is made automatically from @file{N.f}, @file{N.F} or
6538 @file{N.r} by running the Fortran 77 compiler. The precise command used
6544 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS)}
6547 @code{$(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)@*
6548 $(AM_FFLAGS) $(FFLAGS)}
6551 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
6556 @node Mixing Fortran 77 With C and C++
6557 @comment node-name, next, previous, up
6558 @subsection Mixing Fortran 77 With C and C++
6560 @cindex Fortran 77, mixing with C and C++
6561 @cindex Mixing Fortran 77 with C and C++
6562 @cindex Linking Fortran 77 with C and C++
6564 @cindex Mixing Fortran 77 with C and/or C++
6566 Automake currently provides @emph{limited} support for creating programs
6567 and shared libraries that are a mixture of Fortran 77 and C and/or C++.
6568 However, there are many other issues related to mixing Fortran 77 with
6569 other languages that are @emph{not} (currently) handled by Automake, but
6570 that are handled by other packages@footnote{For example,
6571 @uref{http://www-zeus.desy.de/~burow/cfortran/, the cfortran package}
6572 addresses all of these inter-language issues, and runs under nearly all
6573 Fortran 77, C and C++ compilers on nearly all platforms. However,
6574 @command{cfortran} is not yet Free Software, but it will be in the next
6577 Automake can help in two ways:
6581 Automatic selection of the linker depending on which combinations of
6585 Automatic selection of the appropriate linker flags (e.g., @option{-L} and
6586 @option{-l}) to pass to the automatically selected linker in order to link
6587 in the appropriate Fortran 77 intrinsic and run-time libraries.
6589 @cindex @code{FLIBS}, defined
6591 These extra Fortran 77 linker flags are supplied in the output variable
6592 @code{FLIBS} by the @code{AC_F77_LIBRARY_LDFLAGS} Autoconf macro
6593 supplied with newer versions of Autoconf (Autoconf version 2.13 and
6594 later). @xref{Fortran Compiler, , Fortran Compiler Characteristics,
6595 autoconf, The Autoconf Manual}.
6598 If Automake detects that a program or shared library (as mentioned in
6599 some @code{_PROGRAMS} or @code{_LTLIBRARIES} primary) contains source
6600 code that is a mixture of Fortran 77 and C and/or C++, then it requires
6601 that the macro @code{AC_F77_LIBRARY_LDFLAGS} be called in
6602 @file{configure.ac}, and that either @code{$(FLIBS)}
6603 appear in the appropriate @code{_LDADD} (for programs) or @code{_LIBADD}
6604 (for shared libraries) variables. It is the responsibility of the
6605 person writing the @file{Makefile.am} to make sure that @samp{$(FLIBS)}
6606 appears in the appropriate @code{_LDADD} or
6607 @code{_LIBADD} variable.
6609 @cindex Mixed language example
6610 @cindex Example, mixed language
6612 For example, consider the following @file{Makefile.am}:
6616 foo_SOURCES = main.cc foo.f
6617 foo_LDADD = libfoo.la $(FLIBS)
6619 pkglib_LTLIBRARIES = libfoo.la
6620 libfoo_la_SOURCES = bar.f baz.c zardoz.cc
6621 libfoo_la_LIBADD = $(FLIBS)
6624 In this case, Automake will insist that @code{AC_F77_LIBRARY_LDFLAGS}
6625 is mentioned in @file{configure.ac}. Also, if @samp{$(FLIBS)} hadn't
6626 been mentioned in @code{foo_LDADD} and @code{libfoo_la_LIBADD}, then
6627 Automake would have issued a warning.
6630 * How the Linker is Chosen:: Automatic linker selection
6633 @node How the Linker is Chosen
6634 @comment node-name, next, previous, up
6635 @subsubsection How the Linker is Chosen
6637 @cindex Automatic linker selection
6638 @cindex Selecting the linker automatically
6640 When a program or library mixes several languages, Automake choose the
6641 linker according to the following priorities. (The names in
6642 parentheses are the variables containing the link command.)
6647 Native Java (@code{GCJLINK})
6650 C++ (@code{CXXLINK})
6653 Fortran 77 (@code{F77LINK})
6656 Fortran (@code{FCLINK})
6659 Objective C (@code{OBJCLINK})
6662 Unified Parallel C (@code{UPCLINK})
6668 For example, if Fortran 77, C and C++ source code is compiled
6669 into a program, then the C++ linker will be used. In this case, if the
6670 C or Fortran 77 linkers required any special libraries that weren't
6671 included by the C++ linker, then they must be manually added to an
6672 @code{_LDADD} or @code{_LIBADD} variable by the user writing the
6675 Automake only looks at the file names listed in @file{_SOURCES}
6676 variables to choose the linker, and defaults to the C linker.
6677 Sometimes this is inconvenient because you are linking against a
6678 library written in another language and would like to set the linker
6679 more appropriately. @xref{Libtool Convenience Libraries}, for a
6680 trick with @code{nodist_EXTRA_@dots{}_SOURCES}.
6682 A per-target @code{_LINK} variable will override the above selection.
6683 Per-target link flags will cause Automake to write a per-target
6684 @code{_LINK} variable according to the language chosen as above.
6687 @node Fortran 9x Support
6688 @comment node-name, next, previous, up
6689 @section Fortran 9x Support
6691 @cindex Fortran 9x support
6692 @cindex Support for Fortran 9x
6694 Automake includes support for Fortran 9x.
6696 Any package including Fortran 9x code must define the output variable
6697 @code{FC} in @file{configure.ac}; the simplest way to do this is to use
6698 the @code{AC_PROG_FC} macro (@pxref{Particular Programs, , Particular
6699 Program Checks, autoconf, The Autoconf Manual}).
6701 A few additional variables are defined when a Fortran 9x source file is
6707 The name of the Fortran 9x compiler.
6710 Any flags to pass to the Fortran 9x compiler.
6713 The maintainer's variant of @code{FCFLAGS}.
6716 The command used to actually compile a Fortran 9x source file. The file
6717 name is appended to form the complete command line.
6720 The command used to actually link a pure Fortran 9x program or shared
6726 * Compiling Fortran 9x Files:: Compiling Fortran 9x sources
6729 @node Compiling Fortran 9x Files
6730 @comment node-name, next, previous, up
6731 @subsection Compiling Fortran 9x Files
6733 @file{@var{file}.o} is made automatically from @file{@var{file}.f90},
6734 @file{@var{file}.f95}, @file{@var{file}.f03}, or @file{@var{file}.f08}
6735 by running the Fortran 9x compiler. The precise command used
6741 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f90) $<}
6744 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f95) $<}
6747 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f03) $<}
6750 @code{$(FC) $(AM_FCFLAGS) $(FCFLAGS) -c $(FCFLAGS_f08) $<}
6754 @node Java Support with gcj
6755 @comment node-name, next, previous, up
6756 @section Compiling Java sources using gcj
6758 @cindex Java support with gcj
6759 @cindex Support for Java with gcj
6760 @cindex Java to native code, compilation
6761 @cindex Compilation of Java to native code
6763 Automake includes support for natively compiled Java, using @command{gcj},
6764 the Java front end to the GNU Compiler Collection (rudimentary support
6765 for compiling Java to bytecode using the @command{javac} compiler is
6766 also present, @emph{albeit deprecated}; @pxref{Java}).
6768 Any package including Java code to be compiled must define the output
6769 variable @code{GCJ} in @file{configure.ac}; the variable @code{GCJFLAGS}
6770 must also be defined somehow (either in @file{configure.ac} or
6771 @file{Makefile.am}). The simplest way to do this is to use the
6772 @code{AM_PROG_GCJ} macro.
6776 By default, programs including Java source files are linked with
6779 As always, the contents of @code{AM_GCJFLAGS} are passed to every
6780 compilation invoking @command{gcj} (in its role as an ahead-of-time
6781 compiler, when invoking it to create @file{.class} files,
6782 @code{AM_JAVACFLAGS} is used instead). If it is necessary to pass
6783 options to @command{gcj} from @file{Makefile.am}, this variable, and not
6784 the user variable @code{GCJFLAGS}, should be used.
6788 @command{gcj} can be used to compile @file{.java}, @file{.class},
6789 @file{.zip}, or @file{.jar} files.
6791 When linking, @command{gcj} requires that the main class be specified
6792 using the @option{--main=} option. The easiest way to do this is to use
6793 the @code{_LDFLAGS} variable for the program.
6797 @comment node-name, next, previous, up
6798 @section Vala Support
6800 @cindex Vala Support
6801 @cindex Support for Vala
6803 Automake provides initial support for Vala
6804 (@uref{http://www.vala-project.org/}).
6805 This requires valac version 0.7.0 or later, and currently requires
6806 the user to use GNU @command{make}.
6809 foo_SOURCES = foo.vala bar.vala zardoc.c
6812 Any @file{.vala} file listed in a @code{_SOURCES} variable will be
6813 compiled into C code by the Vala compiler. The generated @file{.c} files are
6814 distributed. The end user does not need to have a Vala compiler installed.
6816 Automake ships with an Autoconf macro called @code{AM_PROG_VALAC}
6817 that will locate the Vala compiler and optionally check its version
6820 @defmac AM_PROG_VALAC (@ovar{minimum-version})
6821 Try to find a Vala compiler in @env{PATH}. If it is found, the variable
6822 @code{VALAC} is set. Optionally a minimum release number of the compiler
6826 AM_PROG_VALAC([0.7.0])
6830 There are a few variables that are used when compiling Vala sources:
6834 Path to the Vala compiler.
6837 Additional arguments for the Vala compiler.
6840 The maintainer's variant of @code{VALAFLAGS}.
6843 lib_LTLIBRARIES = libfoo.la
6844 libfoo_la_SOURCES = foo.vala
6848 Note that currently, you cannot use per-target @code{*_VALAFLAGS}
6849 (@pxref{Renamed Objects}) to produce different C files from one Vala
6853 @node Support for Other Languages
6854 @comment node-name, next, previous, up
6855 @section Support for Other Languages
6857 Automake currently only includes full support for C, C++ (@pxref{C++
6858 Support}), Objective C (@pxref{Objective C Support}), Fortran 77
6859 (@pxref{Fortran 77 Support}), Fortran 9x (@pxref{Fortran 9x Support}),
6860 and Java (@pxref{Java Support with gcj}). There is only rudimentary
6861 support for other languages, support for which will be improved based
6864 Some limited support for adding your own languages is available via the
6865 suffix rule handling (@pxref{Suffixes}).
6868 @section Automatic dependency tracking
6870 As a developer it is often painful to continually update the
6871 @file{Makefile.am} whenever the include-file dependencies change in a
6872 project. Automake supplies a way to automatically track dependency
6873 changes (@pxref{Dependency Tracking}).
6875 @cindex Dependency tracking
6876 @cindex Automatic dependency tracking
6878 Automake always uses complete dependencies for a compilation,
6879 including system headers. Automake's model is that dependency
6880 computation should be a side effect of the build. To this end,
6881 dependencies are computed by running all compilations through a
6882 special wrapper program called @command{depcomp}. @command{depcomp}
6883 understands how to coax many different C and C++ compilers into
6884 generating dependency information in the format it requires.
6885 @samp{automake -a} will install @command{depcomp} into your source
6886 tree for you. If @command{depcomp} can't figure out how to properly
6887 invoke your compiler, dependency tracking will simply be disabled for
6890 @cindex @command{depcomp}
6892 Experience with earlier versions of Automake (@pxref{Dependency Tracking
6893 Evolution, , Dependency Tracking Evolution, automake-history, Brief History
6894 of Automake}) taught us that it is not reliable to generate dependencies
6895 only on the maintainer's system, as configurations vary too much. So
6896 instead Automake implements dependency tracking at build time.
6898 Automatic dependency tracking can be suppressed by putting
6899 @option{no-dependencies} in the variable @code{AUTOMAKE_OPTIONS}, or
6900 passing @option{no-dependencies} as an argument to @code{AM_INIT_AUTOMAKE}
6901 (this should be the preferred way). Or, you can invoke @command{automake}
6902 with the @option{-i} option. Dependency tracking is enabled by default.
6904 @vindex AUTOMAKE_OPTIONS
6905 @opindex no-dependencies
6907 The person building your package also can choose to disable dependency
6908 tracking by configuring with @option{--disable-dependency-tracking}.
6910 @cindex Disabling dependency tracking
6911 @cindex Dependency tracking, disabling
6915 @section Support for executable extensions
6917 @cindex Executable extension
6918 @cindex Extension, executable
6921 On some platforms, such as Windows, executables are expected to have an
6922 extension such as @file{.exe}. On these platforms, some compilers (GCC
6923 among them) will automatically generate @file{foo.exe} when asked to
6924 generate @file{foo}.
6926 Automake provides mostly-transparent support for this. Unfortunately
6927 @emph{mostly} doesn't yet mean @emph{fully}. Until the English
6928 dictionary is revised, you will have to assist Automake if your package
6929 must support those platforms.
6931 One thing you must be aware of is that, internally, Automake rewrites
6932 something like this:
6935 bin_PROGRAMS = liver
6941 bin_PROGRAMS = liver$(EXEEXT)
6944 The targets Automake generates are likewise given the @samp{$(EXEEXT)}
6947 The variables @code{TESTS} and @code{XFAIL_TESTS} (@pxref{Simple Tests})
6948 are also rewritten if they contain filenames that have been declared as
6949 programs in the same @file{Makefile}. (This is mostly useful when some
6950 programs from @code{check_PROGRAMS} are listed in @code{TESTS}.)
6952 However, Automake cannot apply this rewriting to @command{configure}
6953 substitutions. This means that if you are conditionally building a
6954 program using such a substitution, then your @file{configure.ac} must
6955 take care to add @samp{$(EXEEXT)} when constructing the output variable.
6957 With Autoconf 2.13 and earlier, you must explicitly use @code{AC_EXEEXT}
6958 to get this support. With Autoconf 2.50, @code{AC_EXEEXT} is run
6959 automatically if you configure a compiler (say, through
6962 Sometimes maintainers like to write an explicit link rule for their
6963 program. Without executable extension support, this is easy---you
6964 simply write a rule whose target is the name of the program. However,
6965 when executable extension support is enabled, you must instead add the
6966 @samp{$(EXEEXT)} suffix.
6968 Unfortunately, due to the change in Autoconf 2.50, this means you must
6969 always add this extension. However, this is a problem for maintainers
6970 who know their package will never run on a platform that has
6971 executable extensions. For those maintainers, the @option{no-exeext}
6972 option (@pxref{Options}) will disable this feature. This works in a
6973 fairly ugly way; if @option{no-exeext} is seen, then the presence of a
6974 rule for a target named @code{foo} in @file{Makefile.am} will override
6975 an @command{automake}-generated rule for @samp{foo$(EXEEXT)}. Without
6976 the @option{no-exeext} option, this use will give a diagnostic.
6980 @chapter Other Derived Objects
6982 Automake can handle derived objects that are not C programs. Sometimes
6983 the support for actually building such objects must be explicitly
6984 supplied, but Automake will still automatically handle installation and
6988 * Scripts:: Executable scripts
6989 * Headers:: Header files
6990 * Data:: Architecture-independent data files
6991 * Sources:: Derived sources
6996 @section Executable Scripts
6998 @cindex @code{_SCRIPTS} primary, defined
6999 @cindex @code{SCRIPTS} primary, defined
7000 @cindex Primary variable, @code{SCRIPTS}
7002 @cindex Installing scripts
7004 It is possible to define and install programs that are scripts. Such
7005 programs are listed using the @code{SCRIPTS} primary name. When the
7006 script is distributed in its final, installable form, the
7007 @file{Makefile} usually looks as follows:
7011 # Install my_script in $(bindir) and distribute it.
7012 dist_bin_SCRIPTS = my_script
7015 Scripts are not distributed by default; as we have just seen, those
7016 that should be distributed can be specified using a @code{dist_}
7017 prefix as with other primaries.
7019 @cindex @code{SCRIPTS}, installation directories
7021 @vindex sbin_SCRIPTS
7022 @vindex libexec_SCRIPTS
7023 @vindex pkgdata_SCRIPTS
7024 @vindex pkglibexec_SCRIPTS
7025 @vindex noinst_SCRIPTS
7026 @vindex check_SCRIPTS
7028 Scripts can be installed in @code{bindir}, @code{sbindir},
7029 @code{libexecdir}, @code{pkglibexecdir}, or @code{pkgdatadir}.
7031 Scripts that need not be installed can be listed in
7032 @code{noinst_SCRIPTS}, and among them, those which are needed only by
7033 @samp{make check} should go in @code{check_SCRIPTS}.
7035 When a script needs to be built, the @file{Makefile.am} should include
7036 the appropriate rules. For instance the @command{automake} program
7037 itself is a Perl script that is generated from @file{automake.in}.
7038 Here is how this is handled:
7041 bin_SCRIPTS = automake
7042 CLEANFILES = $(bin_SCRIPTS)
7043 EXTRA_DIST = automake.in
7045 do_subst = sed -e 's,[@@]datadir[@@],$(datadir),g' \
7046 -e 's,[@@]PERL[@@],$(PERL),g' \
7047 -e 's,[@@]PACKAGE[@@],$(PACKAGE),g' \
7048 -e 's,[@@]VERSION[@@],$(VERSION),g' \
7051 automake: automake.in Makefile
7052 $(do_subst) < $(srcdir)/automake.in > automake
7056 Such scripts for which a build rule has been supplied need to be
7057 deleted explicitly using @code{CLEANFILES} (@pxref{Clean}), and their
7058 sources have to be distributed, usually with @code{EXTRA_DIST}
7059 (@pxref{Basics of Distribution}).
7061 Another common way to build scripts is to process them from
7062 @file{configure} with @code{AC_CONFIG_FILES}. In this situation
7063 Automake knows which files should be cleaned and distributed, and what
7064 the rebuild rules should look like.
7066 For instance if @file{configure.ac} contains
7069 AC_CONFIG_FILES([src/my_script], [chmod +x src/my_script])
7073 to build @file{src/my_script} from @file{src/my_script.in}, then a
7074 @file{src/Makefile.am} to install this script in @code{$(bindir)} can
7078 bin_SCRIPTS = my_script
7079 CLEANFILES = $(bin_SCRIPTS)
7083 There is no need for @code{EXTRA_DIST} or any build rule: Automake
7084 infers them from @code{AC_CONFIG_FILES} (@pxref{Requirements}).
7085 @code{CLEANFILES} is still useful, because by default Automake will
7086 clean targets of @code{AC_CONFIG_FILES} in @code{distclean}, not
7089 Although this looks simpler, building scripts this way has one
7090 drawback: directory variables such as @code{$(datadir)} are not fully
7091 expanded and may refer to other directory variables.
7094 @section Header files
7096 @cindex @code{_HEADERS} primary, defined
7097 @cindex @code{HEADERS} primary, defined
7098 @cindex Primary variable, @code{HEADERS}
7100 @vindex noinst_HEADERS
7101 @cindex @code{HEADERS}, installation directories
7102 @cindex Installing headers
7103 @vindex include_HEADERS
7104 @vindex oldinclude_HEADERS
7105 @vindex pkginclude_HEADERS
7108 Header files that must be installed are specified by the
7109 @code{HEADERS} family of variables. Headers can be installed in
7110 @code{includedir}, @code{oldincludedir}, @code{pkgincludedir} or any
7111 other directory you may have defined (@pxref{Uniform}). For instance,
7114 include_HEADERS = foo.h bar/bar.h
7118 will install the two files as @file{$(includedir)/foo.h} and
7119 @file{$(includedir)/bar.h}.
7121 The @code{nobase_} prefix is also supported,
7124 nobase_include_HEADERS = foo.h bar/bar.h
7128 will install the two files as @file{$(includedir)/foo.h} and
7129 @file{$(includedir)/bar/bar.h} (@pxref{Alternative}).
7131 @vindex noinst_HEADERS
7132 Usually, only header files that accompany installed libraries need to
7133 be installed. Headers used by programs or convenience libraries are
7134 not installed. The @code{noinst_HEADERS} variable can be used for
7135 such headers. However when the header actually belongs to a single
7136 convenience library or program, we recommend listing it in the
7137 program's or library's @code{_SOURCES} variable (@pxref{Program
7138 Sources}) instead of in @code{noinst_HEADERS}. This is clearer for
7139 the @file{Makefile.am} reader. @code{noinst_HEADERS} would be the
7140 right variable to use in a directory containing only headers and no
7141 associated library or program.
7143 All header files must be listed somewhere; in a @code{_SOURCES}
7144 variable or in a @code{_HEADERS} variable. Missing ones will not
7145 appear in the distribution.
7147 For header files that are built and must not be distributed, use the
7148 @code{nodist_} prefix as in @code{nodist_include_HEADERS} or
7149 @code{nodist_prog_SOURCES}. If these generated headers are needed
7150 during the build, you must also ensure they exist before they are
7151 used (@pxref{Sources}).
7155 @section Architecture-independent data files
7157 @cindex @code{_DATA} primary, defined
7158 @cindex @code{DATA} primary, defined
7159 @cindex Primary variable, @code{DATA}
7162 Automake supports the installation of miscellaneous data files using the
7163 @code{DATA} family of variables.
7167 @vindex sysconf_DATA
7168 @vindex sharedstate_DATA
7169 @vindex localstate_DATA
7170 @vindex pkgdata_DATA
7172 Such data can be installed in the directories @code{datadir},
7173 @code{sysconfdir}, @code{sharedstatedir}, @code{localstatedir}, or
7176 By default, data files are @emph{not} included in a distribution. Of
7177 course, you can use the @code{dist_} prefix to change this on a
7180 Here is how Automake declares its auxiliary data files:
7183 dist_pkgdata_DATA = clean-kr.am clean.am @dots{}
7188 @section Built Sources
7190 Because Automake's automatic dependency tracking works as a side-effect
7191 of compilation (@pxref{Dependencies}) there is a bootstrap issue: a
7192 target should not be compiled before its dependencies are made, but
7193 these dependencies are unknown until the target is first compiled.
7195 Ordinarily this is not a problem, because dependencies are distributed
7196 sources: they preexist and do not need to be built. Suppose that
7197 @file{foo.c} includes @file{foo.h}. When it first compiles
7198 @file{foo.o}, @command{make} only knows that @file{foo.o} depends on
7199 @file{foo.c}. As a side-effect of this compilation @command{depcomp}
7200 records the @file{foo.h} dependency so that following invocations of
7201 @command{make} will honor it. In these conditions, it's clear there is
7202 no problem: either @file{foo.o} doesn't exist and has to be built
7203 (regardless of the dependencies), or accurate dependencies exist and
7204 they can be used to decide whether @file{foo.o} should be rebuilt.
7206 It's a different story if @file{foo.h} doesn't exist by the first
7207 @command{make} run. For instance, there might be a rule to build
7208 @file{foo.h}. This time @file{file.o}'s build will fail because the
7209 compiler can't find @file{foo.h}. @command{make} failed to trigger the
7210 rule to build @file{foo.h} first by lack of dependency information.
7212 @vindex BUILT_SOURCES
7213 @cindex @code{BUILT_SOURCES}, defined
7215 The @code{BUILT_SOURCES} variable is a workaround for this problem. A
7216 source file listed in @code{BUILT_SOURCES} is made on @samp{make all}
7217 or @samp{make check} (or even @samp{make install}) before other
7218 targets are processed. However, such a source file is not
7219 @emph{compiled} unless explicitly requested by mentioning it in some
7220 other @code{_SOURCES} variable.
7222 So, to conclude our introductory example, we could use
7223 @samp{BUILT_SOURCES = foo.h} to ensure @file{foo.h} gets built before
7224 any other target (including @file{foo.o}) during @samp{make all} or
7227 @code{BUILT_SOURCES} is actually a bit of a misnomer, as any file which
7228 must be created early in the build process can be listed in this
7229 variable. Moreover, all built sources do not necessarily have to be
7230 listed in @code{BUILT_SOURCES}. For instance, a generated @file{.c} file
7231 doesn't need to appear in @code{BUILT_SOURCES} (unless it is included by
7232 another source), because it's a known dependency of the associated
7235 It might be important to emphasize that @code{BUILT_SOURCES} is
7236 honored only by @samp{make all}, @samp{make check} and @samp{make
7237 install}. This means you cannot build a specific target (e.g.,
7238 @samp{make foo}) in a clean tree if it depends on a built source.
7239 However it will succeed if you have run @samp{make all} earlier,
7240 because accurate dependencies are already available.
7242 The next section illustrates and discusses the handling of built sources
7246 * Built Sources Example:: Several ways to handle built sources.
7249 @node Built Sources Example
7250 @subsection Built Sources Example
7252 Suppose that @file{foo.c} includes @file{bindir.h}, which is
7253 installation-dependent and not distributed: it needs to be built. Here
7254 @file{bindir.h} defines the preprocessor macro @code{bindir} to the
7255 value of the @command{make} variable @code{bindir} (inherited from
7258 We suggest several implementations below. It's not meant to be an
7259 exhaustive listing of all ways to handle built sources, but it will give
7260 you a few ideas if you encounter this issue.
7262 @subsubheading First Try
7264 This first implementation will illustrate the bootstrap issue mentioned
7265 in the previous section (@pxref{Sources}).
7267 Here is a tentative @file{Makefile.am}.
7273 nodist_foo_SOURCES = bindir.h
7274 CLEANFILES = bindir.h
7276 echo '#define bindir "$(bindir)"' >$@@
7279 This setup doesn't work, because Automake doesn't know that @file{foo.c}
7280 includes @file{bindir.h}. Remember, automatic dependency tracking works
7281 as a side-effect of compilation, so the dependencies of @file{foo.o} will
7282 be known only after @file{foo.o} has been compiled (@pxref{Dependencies}).
7283 The symptom is as follows.
7287 source='foo.c' object='foo.o' libtool=no \
7288 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
7289 depmode=gcc /bin/sh ./depcomp \
7290 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
7291 foo.c:2: bindir.h: No such file or directory
7292 make: *** [foo.o] Error 1
7295 In this example @file{bindir.h} is not distributed nor installed, and
7296 it is not even being built on-time. One may wonder if the
7297 @samp{nodist_foo_SOURCES = bindir.h} line has any use at all. This
7298 line simply states that @file{bindir.h} is a source of @code{foo}, so
7299 for instance, it should be inspected while generating tags
7300 (@pxref{Tags}). In other words, it does not help our present problem,
7301 and the build would fail identically without it.
7303 @subsubheading Using @code{BUILT_SOURCES}
7305 A solution is to require @file{bindir.h} to be built before anything
7306 else. This is what @code{BUILT_SOURCES} is meant for (@pxref{Sources}).
7311 nodist_foo_SOURCES = bindir.h
7312 BUILT_SOURCES = bindir.h
7313 CLEANFILES = bindir.h
7315 echo '#define bindir "$(bindir)"' >$@@
7318 See how @file{bindir.h} gets built first:
7322 echo '#define bindir "/usr/local/bin"' >bindir.h
7324 make[1]: Entering directory `/home/adl/tmp'
7325 source='foo.c' object='foo.o' libtool=no \
7326 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
7327 depmode=gcc /bin/sh ./depcomp \
7328 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
7329 gcc -g -O2 -o foo foo.o
7330 make[1]: Leaving directory `/home/adl/tmp'
7333 However, as said earlier, @code{BUILT_SOURCES} applies only to the
7334 @code{all}, @code{check}, and @code{install} targets. It still fails
7335 if you try to run @samp{make foo} explicitly:
7339 test -z "bindir.h" || rm -f bindir.h
7340 test -z "foo" || rm -f foo
7342 % : > .deps/foo.Po # Suppress previously recorded dependencies
7344 source='foo.c' object='foo.o' libtool=no \
7345 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
7346 depmode=gcc /bin/sh ./depcomp \
7347 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
7348 foo.c:2: bindir.h: No such file or directory
7349 make: *** [foo.o] Error 1
7352 @subsubheading Recording Dependencies manually
7354 Usually people are happy enough with @code{BUILT_SOURCES} because they
7355 never build targets such as @samp{make foo} before @samp{make all}, as
7356 in the previous example. However if this matters to you, you can
7357 avoid @code{BUILT_SOURCES} and record such dependencies explicitly in
7358 the @file{Makefile.am}.
7363 nodist_foo_SOURCES = bindir.h
7364 foo.$(OBJEXT): bindir.h
7365 CLEANFILES = bindir.h
7367 echo '#define bindir "$(bindir)"' >$@@
7370 You don't have to list @emph{all} the dependencies of @file{foo.o}
7371 explicitly, only those that might need to be built. If a dependency
7372 already exists, it will not hinder the first compilation and will be
7373 recorded by the normal dependency tracking code. (Note that after
7374 this first compilation the dependency tracking code will also have
7375 recorded the dependency between @file{foo.o} and
7376 @file{bindir.h}; so our explicit dependency is really useful to
7377 the first build only.)
7379 Adding explicit dependencies like this can be a bit dangerous if you are
7380 not careful enough. This is due to the way Automake tries not to
7381 overwrite your rules (it assumes you know better than it).
7382 @samp{foo.$(OBJEXT): bindir.h} supersedes any rule Automake may want to
7383 output to build @samp{foo.$(OBJEXT)}. It happens to work in this case
7384 because Automake doesn't have to output any @samp{foo.$(OBJEXT):}
7385 target: it relies on a suffix rule instead (i.e., @samp{.c.$(OBJEXT):}).
7386 Always check the generated @file{Makefile.in} if you do this.
7388 @subsubheading Build @file{bindir.h} from @file{configure}
7390 It's possible to define this preprocessor macro from @file{configure},
7391 either in @file{config.h} (@pxref{Defining Directories, , Defining
7392 Directories, autoconf, The Autoconf Manual}), or by processing a
7393 @file{bindir.h.in} file using @code{AC_CONFIG_FILES}
7394 (@pxref{Configuration Actions, ,Configuration Actions, autoconf, The
7397 At this point it should be clear that building @file{bindir.h} from
7398 @file{configure} works well for this example. @file{bindir.h} will exist
7399 before you build any target, hence will not cause any dependency issue.
7401 The Makefile can be shrunk as follows. We do not even have to mention
7409 However, it's not always possible to build sources from
7410 @file{configure}, especially when these sources are generated by a tool
7411 that needs to be built first.
7413 @subsubheading Build @file{bindir.c}, not @file{bindir.h}.
7415 Another attractive idea is to define @code{bindir} as a variable or
7416 function exported from @file{bindir.o}, and build @file{bindir.c}
7417 instead of @file{bindir.h}.
7420 noinst_PROGRAMS = foo
7421 foo_SOURCES = foo.c bindir.h
7422 nodist_foo_SOURCES = bindir.c
7423 CLEANFILES = bindir.c
7425 echo 'const char bindir[] = "$(bindir)";' >$@@
7428 @file{bindir.h} contains just the variable's declaration and doesn't
7429 need to be built, so it won't cause any trouble. @file{bindir.o} is
7430 always dependent on @file{bindir.c}, so @file{bindir.c} will get built
7433 @subsubheading Which is best?
7435 There is no panacea, of course. Each solution has its merits and
7438 You cannot use @code{BUILT_SOURCES} if the ability to run @samp{make
7439 foo} on a clean tree is important to you.
7441 You won't add explicit dependencies if you are leery of overriding
7442 an Automake rule by mistake.
7444 Building files from @file{./configure} is not always possible, neither
7445 is converting @file{.h} files into @file{.c} files.
7448 @node Other GNU Tools
7449 @chapter Other GNU Tools
7451 Since Automake is primarily intended to generate @file{Makefile.in}s for
7452 use in GNU programs, it tries hard to interoperate with other GNU tools.
7455 * Emacs Lisp:: Emacs Lisp
7458 * Java:: Java bytecode compilation (deprecated)
7466 @cindex @code{_LISP} primary, defined
7467 @cindex @code{LISP} primary, defined
7468 @cindex Primary variable, @code{LISP}
7474 Automake provides some support for Emacs Lisp. The @code{LISP} primary
7475 is used to hold a list of @file{.el} files. Possible prefixes for this
7476 primary are @code{lisp_} and @code{noinst_}. Note that if
7477 @code{lisp_LISP} is defined, then @file{configure.ac} must run
7478 @code{AM_PATH_LISPDIR} (@pxref{Macros}).
7480 @vindex dist_lisp_LISP
7481 @vindex dist_noinst_LISP
7482 Lisp sources are not distributed by default. You can prefix the
7483 @code{LISP} primary with @code{dist_}, as in @code{dist_lisp_LISP} or
7484 @code{dist_noinst_LISP}, to indicate that these files should be
7487 Automake will byte-compile all Emacs Lisp source files using the Emacs
7488 found by @code{AM_PATH_LISPDIR}, if any was found.
7490 Byte-compiled Emacs Lisp files are not portable among all versions of
7491 Emacs, so it makes sense to turn this off if you expect sites to have
7492 more than one version of Emacs installed. Furthermore, many packages
7493 don't actually benefit from byte-compilation. Still, we recommend
7494 that you byte-compile your Emacs Lisp sources. It is probably better
7495 for sites with strange setups to cope for themselves than to make the
7496 installation less nice for everybody else.
7498 There are two ways to avoid byte-compiling. Historically, we have
7499 recommended the following construct.
7502 lisp_LISP = file1.el file2.el
7507 @code{ELCFILES} is an internal Automake variable that normally lists
7508 all @file{.elc} files that must be byte-compiled. Automake defines
7509 @code{ELCFILES} automatically from @code{lisp_LISP}. Emptying this
7510 variable explicitly prevents byte-compilation.
7512 Since Automake 1.8, we now recommend using @code{lisp_DATA} instead:
7514 @c Keep in sync with primary-prefix-couples-documented-valid.test.
7516 lisp_DATA = file1.el file2.el
7519 Note that these two constructs are not equivalent. @code{_LISP} will
7520 not install a file if Emacs is not installed, while @code{_DATA} will
7521 always install its files.
7526 @cindex GNU Gettext support
7527 @cindex Gettext support
7528 @cindex Support for GNU Gettext
7530 If @code{AM_GNU_GETTEXT} is seen in @file{configure.ac}, then Automake
7531 turns on support for GNU gettext, a message catalog system for
7532 internationalization
7533 (@pxref{Top, , Introduction, gettext, GNU gettext utilities}).
7535 The @code{gettext} support in Automake requires the addition of one or
7536 two subdirectories to the package: @file{po} and possibly also @file{intl}.
7537 The latter is needed if @code{AM_GNU_GETTEXT} is not invoked with the
7538 @samp{external} argument, or if @code{AM_GNU_GETTEXT_INTL_SUBDIR} is used.
7539 Automake ensures that these directories exist and are mentioned in
7545 Automake provides support for GNU Libtool (@pxref{Top, , Introduction,
7546 libtool, The Libtool Manual}) with the @code{LTLIBRARIES} primary.
7547 @xref{A Shared Library}.
7551 @section Java bytecode compilation (deprecated)
7553 @cindex @code{_JAVA} primary, defined
7554 @cindex @code{JAVA} primary, defined
7555 @cindex Primary variable, @code{JAVA}
7556 @cindex Java to bytecode, compilation
7557 @cindex Compilation of Java to bytecode
7559 Automake provides some minimal support for Java bytecode compilation with
7560 the @code{JAVA} primary (in addition to the support for compiling Java to
7561 native machine code; @pxref{Java Support with gcj}). Note however that
7562 @emph{the interface and most features described here are deprecated}; the
7563 next automake release will strive to provide a better and cleaner
7564 interface, which however @emph{won't be backward-compatible}; the present
7565 interface will probably be removed altogether in future automake releases
7566 (1.13 or later), so don't use it in new code.
7568 Any @file{.java} files listed in a @code{_JAVA} variable will be
7569 compiled with @code{JAVAC} at build time. By default, @file{.java}
7570 files are not included in the distribution, you should use the
7571 @code{dist_} prefix to distribute them.
7573 Here is a typical setup for distributing @file{.java} files and
7574 installing the @file{.class} files resulting from their compilation.
7576 @c Keep in sync with primary-prefix-couples-documented-valid.test.
7578 javadir = $(datadir)/java
7579 dist_java_JAVA = a.java b.java @dots{}
7582 @cindex @code{JAVA} restrictions
7583 @cindex Restrictions for @code{JAVA}
7585 Currently Automake enforces the restriction that only one @code{_JAVA}
7586 primary can be used in a given @file{Makefile.am}. The reason for this
7587 restriction is that, in general, it isn't possible to know which
7588 @file{.class} files were generated from which @file{.java} files, so
7589 it would be impossible to know which files to install where. For
7590 instance, a @file{.java} file can define multiple classes; the resulting
7591 @file{.class} file names cannot be predicted without parsing the
7594 There are a few variables that are used when compiling Java sources:
7598 The name of the Java compiler. This defaults to @samp{javac}.
7601 The flags to pass to the compiler. This is considered to be a user
7602 variable (@pxref{User Variables}).
7605 More flags to pass to the Java compiler. This, and not
7606 @code{JAVACFLAGS}, should be used when it is necessary to put Java
7607 compiler flags into @file{Makefile.am}.
7610 The value of this variable is passed to the @option{-d} option to
7611 @code{javac}. It defaults to @samp{$(top_builddir)}.
7614 This variable is a shell expression that is used to set the
7615 @env{CLASSPATH} environment variable on the @code{javac} command line.
7616 (In the future we will probably handle class path setting differently.)
7623 @cindex @code{_PYTHON} primary, defined
7624 @cindex @code{PYTHON} primary, defined
7625 @cindex Primary variable, @code{PYTHON}
7628 Automake provides support for Python compilation with the
7629 @code{PYTHON} primary. A typical setup is to call
7630 @code{AM_PATH_PYTHON} in @file{configure.ac} and use a line like the
7631 following in @file{Makefile.am}:
7634 python_PYTHON = tree.py leave.py
7637 Any files listed in a @code{_PYTHON} variable will be byte-compiled
7638 with @command{py-compile} at install time. @command{py-compile}
7639 actually creates both standard (@file{.pyc}) and optimized
7640 (@file{.pyo}) byte-compiled versions of the source files. Note that
7641 because byte-compilation occurs at install time, any files listed in
7642 @code{noinst_PYTHON} will not be compiled. Python source files are
7643 included in the distribution by default, prepend @code{nodist_} (as in
7644 @code{nodist_python_PYTHON}) to omit them.
7646 Automake ships with an Autoconf macro called @code{AM_PATH_PYTHON}
7647 that will determine some Python-related directory variables (see
7648 below). If you have called @code{AM_PATH_PYTHON} from
7649 @file{configure.ac}, then you may use the variables
7650 @c Keep in sync with primary-prefix-couples-documented-valid.test.
7651 @code{python_PYTHON} or @code{pkgpython_PYTHON} to list Python source
7652 files in your @file{Makefile.am}, depending on where you want your files
7653 installed (see the definitions of @code{pythondir} and
7654 @code{pkgpythondir} below).
7656 @defmac AM_PATH_PYTHON (@ovar{version}, @ovar{action-if-found},
7657 @ovar{action-if-not-found})
7659 Search for a Python interpreter on the system. This macro takes three
7660 optional arguments. The first argument, if present, is the minimum
7661 version of Python required for this package: @code{AM_PATH_PYTHON}
7662 will skip any Python interpreter that is older than @var{version}.
7663 If an interpreter is found and satisfies @var{version}, then
7664 @var{action-if-found} is run. Otherwise, @var{action-if-not-found} is
7667 If @var{action-if-not-found} is not specified, as in the following
7668 example, the default is to abort @command{configure}.
7671 AM_PATH_PYTHON([2.2])
7675 This is fine when Python is an absolute requirement for the package.
7676 If Python >= 2.5 was only @emph{optional} to the package,
7677 @code{AM_PATH_PYTHON} could be called as follows.
7680 AM_PATH_PYTHON([2.5],, [:])
7683 If the @env{PYTHON} variable is set when @code{AM_PATH_PYTHON} is
7684 called, then that will be the only Python interpreter that is tried.
7686 @code{AM_PATH_PYTHON} creates the following output variables based on
7687 the Python installation found during configuration.
7692 The name of the Python executable, or @samp{:} if no suitable
7693 interpreter could be found.
7695 Assuming @var{action-if-not-found} is used (otherwise @file{./configure}
7696 will abort if Python is absent), the value of @code{PYTHON} can be used
7697 to setup a conditional in order to disable the relevant part of a build
7701 AM_PATH_PYTHON(,, [:])
7702 AM_CONDITIONAL([HAVE_PYTHON], [test "$PYTHON" != :])
7705 @item PYTHON_VERSION
7706 The Python version number, in the form @var{major}.@var{minor}
7707 (e.g., @samp{2.5}). This is currently the value of
7708 @samp{sys.version[:3]}.
7711 The string @samp{$@{prefix@}}. This term may be used in future work
7712 that needs the contents of Python's @samp{sys.prefix}, but general
7713 consensus is to always use the value from @command{configure}.
7715 @item PYTHON_EXEC_PREFIX
7716 The string @samp{$@{exec_prefix@}}. This term may be used in future work
7717 that needs the contents of Python's @samp{sys.exec_prefix}, but general
7718 consensus is to always use the value from @command{configure}.
7720 @item PYTHON_PLATFORM
7721 The canonical name used by Python to describe the operating system, as
7722 given by @samp{sys.platform}. This value is sometimes needed when
7723 building Python extensions.
7726 The directory name for the @file{site-packages} subdirectory of the
7727 standard Python install tree.
7730 This is the directory under @code{pythondir} that is named after the
7731 package. That is, it is @samp{$(pythondir)/$(PACKAGE)}. It is provided
7735 This is the directory where Python extension modules (shared libraries)
7736 should be installed. An extension module written in C could be declared
7737 as follows to Automake:
7739 @c Keep in sync with primary-prefix-couples-documented-valid.test.
7741 pyexec_LTLIBRARIES = quaternion.la
7742 quaternion_la_SOURCES = quaternion.c support.c support.h
7743 quaternion_la_LDFLAGS = -avoid-version -module
7747 This is a convenience variable that is defined as
7748 @samp{$(pyexecdir)/$(PACKAGE)}.
7751 All these directory variables have values that start with either
7752 @samp{$@{prefix@}} or @samp{$@{exec_prefix@}} unexpanded. This works
7753 fine in @file{Makefiles}, but it makes these variables hard to use in
7754 @file{configure}. This is mandated by the GNU coding standards, so
7755 that the user can run @samp{make prefix=/foo install}. The Autoconf
7756 manual has a section with more details on this topic
7757 (@pxref{Installation Directory Variables, , Installation Directory
7758 Variables, autoconf, The Autoconf Manual}). See also @ref{Hard-Coded
7763 @chapter Building documentation
7765 Currently Automake provides support for Texinfo and man pages.
7769 * Man Pages:: Man pages
7776 @cindex @code{_TEXINFOS} primary, defined
7777 @cindex @code{TEXINFOS} primary, defined
7778 @cindex Primary variable, @code{TEXINFOS}
7779 @cindex HTML output using Texinfo
7780 @cindex PDF output using Texinfo
7781 @cindex PS output using Texinfo
7782 @cindex DVI output using Texinfo
7784 @vindex info_TEXINFOS
7786 If the current directory contains Texinfo source, you must declare it
7787 with the @code{TEXINFOS} primary. Generally Texinfo files are converted
7788 into info, and thus the @code{info_TEXINFOS} variable is most commonly used
7789 here. Any Texinfo source file must end in the @file{.texi},
7790 @file{.txi}, or @file{.texinfo} extension. We recommend @file{.texi}
7793 Automake generates rules to build @file{.info}, @file{.dvi},
7794 @file{.ps}, @file{.pdf} and @file{.html} files from your Texinfo
7795 sources. Following the GNU Coding Standards, only the @file{.info}
7796 files are built by @samp{make all} and installed by @samp{make
7797 install} (unless you use @option{no-installinfo}, see below).
7798 Furthermore, @file{.info} files are automatically distributed so that
7799 Texinfo is not a prerequisite for installing your package.
7805 @trindex install-dvi
7806 @trindex install-html
7807 @trindex install-pdf
7809 Other documentation formats can be built on request by @samp{make
7810 dvi}, @samp{make ps}, @samp{make pdf} and @samp{make html}, and they
7811 can be installed with @samp{make install-dvi}, @samp{make install-ps},
7812 @samp{make install-pdf} and @samp{make install-html} explicitly.
7813 @samp{make uninstall} will remove everything: the Texinfo
7814 documentation installed by default as well as all the above optional
7817 All these targets can be extended using @samp{-local} rules
7818 (@pxref{Extending}).
7820 @cindex Texinfo flag, @code{VERSION}
7821 @cindex Texinfo flag, @code{UPDATED}
7822 @cindex Texinfo flag, @code{EDITION}
7823 @cindex Texinfo flag, @code{UPDATED-MONTH}
7825 @cindex @code{VERSION} Texinfo flag
7826 @cindex @code{UPDATED} Texinfo flag
7827 @cindex @code{EDITION} Texinfo flag
7828 @cindex @code{UPDATED-MONTH} Texinfo flag
7830 @cindex @file{mdate-sh}
7832 If the @file{.texi} file @code{@@include}s @file{version.texi}, then
7833 that file will be automatically generated. The file @file{version.texi}
7834 defines four Texinfo flag you can reference using
7835 @code{@@value@{EDITION@}}, @code{@@value@{VERSION@}},
7836 @code{@@value@{UPDATED@}}, and @code{@@value@{UPDATED-MONTH@}}.
7841 Both of these flags hold the version number of your program. They are
7842 kept separate for clarity.
7845 This holds the date the primary @file{.texi} file was last modified.
7848 This holds the name of the month in which the primary @file{.texi} file
7852 The @file{version.texi} support requires the @command{mdate-sh}
7853 script; this script is supplied with Automake and automatically
7854 included when @command{automake} is invoked with the
7855 @option{--add-missing} option.
7857 If you have multiple Texinfo files, and you want to use the
7858 @file{version.texi} feature, then you have to have a separate version
7859 file for each Texinfo file. Automake will treat any include in a
7860 Texinfo file that matches @file{vers*.texi} just as an automatically
7861 generated version file.
7863 Sometimes an info file actually depends on more than one @file{.texi}
7864 file. For instance, in GNU Hello, @file{hello.texi} includes the file
7865 @file{fdl.texi}. You can tell Automake about these dependencies using
7866 the @code{@var{texi}_TEXINFOS} variable. Here is how GNU Hello does it:
7871 info_TEXINFOS = hello.texi
7872 hello_TEXINFOS = fdl.texi
7875 @cindex @file{texinfo.tex}
7877 By default, Automake requires the file @file{texinfo.tex} to appear in
7878 the same directory as the @file{Makefile.am} file that lists the
7879 @file{.texi} files. If you used @code{AC_CONFIG_AUX_DIR} in
7880 @file{configure.ac} (@pxref{Input, , Finding `configure' Input,
7881 autoconf, The Autoconf Manual}), then @file{texinfo.tex} is looked for
7882 there. In both cases, @command{automake} then supplies @file{texinfo.tex} if
7883 @option{--add-missing} is given, and takes care of its distribution.
7884 However, if you set the @code{TEXINFO_TEX} variable (see below),
7885 it overrides the location of the file and turns off its installation
7886 into the source as well as its distribution.
7888 The option @option{no-texinfo.tex} can be used to eliminate the
7889 requirement for the file @file{texinfo.tex}. Use of the variable
7890 @code{TEXINFO_TEX} is preferable, however, because that allows the
7891 @code{dvi}, @code{ps}, and @code{pdf} targets to still work.
7893 @cindex Option, @code{no-installinfo}
7894 @cindex Target, @code{install-info}
7895 @cindex @code{install-info} target
7896 @cindex @code{no-installinfo} option
7898 @opindex no-installinfo
7899 @trindex install-info
7901 Automake generates an @code{install-info} rule; some people apparently
7902 use this. By default, info pages are installed by @samp{make
7903 install}, so running @code{make install-info} is pointless. This can
7904 be prevented via the @code{no-installinfo} option. In this case,
7905 @file{.info} files are not installed by default, and user must
7906 request this explicitly using @samp{make install-info}.
7908 @vindex AM_UPDATE_INFO_DIR
7909 By default, @code{make install-info} will try to run the
7910 @command{install-info} program (if available) to update (or create)
7911 the @file{@code{$@{infodir@}}/dir} index. If this is undesired, it
7912 can be prevented by exporting the @code{AM_UPDATE_INFO_DIR} variable
7915 The following variables are used by the Texinfo build rules.
7919 The name of the program invoked to build @file{.info} files. This
7920 variable is defined by Automake. If the @command{makeinfo} program is
7921 found on the system then it will be used by default; otherwise
7922 @command{missing} will be used instead.
7925 The command invoked to build @file{.html} files. Automake
7926 defines this to @samp{$(MAKEINFO) --html}.
7929 User flags passed to each invocation of @samp{$(MAKEINFO)} and
7930 @samp{$(MAKEINFOHTML)}. This user variable (@pxref{User Variables}) is
7931 not expected to be defined in any @file{Makefile}; it can be used by
7932 users to pass extra flags to suit their needs.
7934 @item AM_MAKEINFOFLAGS
7935 @itemx AM_MAKEINFOHTMLFLAGS
7936 Maintainer flags passed to each @command{makeinfo} invocation. Unlike
7937 @code{MAKEINFOFLAGS}, these variables are meant to be defined by
7938 maintainers in @file{Makefile.am}. @samp{$(AM_MAKEINFOFLAGS)} is
7939 passed to @code{makeinfo} when building @file{.info} files; and
7940 @samp{$(AM_MAKEINFOHTMLFLAGS)} is used when building @file{.html}
7943 @c Keep in sync with txinfo21.test.
7944 For instance, the following setting can be used to obtain one single
7945 @file{.html} file per manual, without node separators.
7947 AM_MAKEINFOHTMLFLAGS = --no-headers --no-split
7950 @code{AM_MAKEINFOHTMLFLAGS} defaults to @samp{$(AM_MAKEINFOFLAGS)}.
7951 This means that defining @code{AM_MAKEINFOFLAGS} without defining
7952 @code{AM_MAKEINFOHTMLFLAGS} will impact builds of both @file{.info}
7953 and @file{.html} files.
7956 The name of the command that converts a @file{.texi} file into a
7957 @file{.dvi} file. This defaults to @samp{texi2dvi}, a script that ships
7958 with the Texinfo package.
7961 The name of the command that translates a @file{.texi} file into a
7962 @file{.pdf} file. This defaults to @samp{$(TEXI2DVI) --pdf --batch}.
7965 The name of the command that builds a @file{.ps} file out of a
7966 @file{.dvi} file. This defaults to @samp{dvips}.
7970 If your package has Texinfo files in many directories, you can use the
7971 variable @code{TEXINFO_TEX} to tell Automake where to find the canonical
7972 @file{texinfo.tex} for your package. The value of this variable should
7973 be the relative path from the current @file{Makefile.am} to
7977 TEXINFO_TEX = ../doc/texinfo.tex
7985 @cindex @code{_MANS} primary, defined
7986 @cindex @code{MANS} primary, defined
7987 @cindex Primary variable, @code{MANS}
7991 A package can also include man pages (but see the GNU standards on this
7992 matter, @ref{Man Pages, , , standards, The GNU Coding Standards}.) Man
7993 pages are declared using the @code{MANS} primary. Generally the
7994 @code{man_MANS} variable is used. Man pages are automatically installed in
7995 the correct subdirectory of @code{mandir}, based on the file extension.
7997 File extensions such as @file{.1c} are handled by looking for the valid
7998 part of the extension and using that to determine the correct
7999 subdirectory of @code{mandir}. Valid section names are the digits
8000 @samp{0} through @samp{9}, and the letters @samp{l} and @samp{n}.
8002 Sometimes developers prefer to name a man page something like
8003 @file{foo.man} in the source, and then rename it to have the correct
8004 suffix, for example @file{foo.1}, when installing the file. Automake
8005 also supports this mode. For a valid section named @var{section},
8006 there is a corresponding directory named @samp{man@var{section}dir},
8007 and a corresponding @code{_MANS} variable. Files listed in such a
8008 variable are installed in the indicated section. If the file already
8009 has a valid suffix, then it is installed as-is; otherwise the file
8010 suffix is changed to match the section.
8012 For instance, consider this example:
8014 man1_MANS = rename.man thesame.1 alsothesame.1c
8018 In this case, @file{rename.man} will be renamed to @file{rename.1} when
8019 installed, but the other files will keep their names.
8021 @cindex Target, @code{install-man}
8022 @cindex Option, @option{no-installman}
8023 @cindex @code{install-man} target
8024 @cindex @option{no-installman} option
8025 @opindex no-installman
8026 @trindex install-man
8028 By default, man pages are installed by @samp{make install}. However,
8029 since the GNU project does not require man pages, many maintainers do
8030 not expend effort to keep the man pages up to date. In these cases, the
8031 @option{no-installman} option will prevent the man pages from being
8032 installed by default. The user can still explicitly install them via
8033 @samp{make install-man}.
8035 For fast installation, with many files it is preferable to use
8036 @samp{man@var{section}_MANS} over @samp{man_MANS} as well as files that
8037 do not need to be renamed.
8039 Man pages are not currently considered to be source, because it is not
8040 uncommon for man pages to be automatically generated. Therefore they
8041 are not automatically included in the distribution. However, this can
8042 be changed by use of the @code{dist_} prefix. For instance here is
8043 how to distribute and install the two man pages of GNU @command{cpio}
8044 (which includes both Texinfo documentation and man pages):
8047 dist_man_MANS = cpio.1 mt.1
8050 The @code{nobase_} prefix is meaningless for man pages and is
8054 @cindex @code{notrans_} prefix
8055 @cindex Man page renaming, avoiding
8056 @cindex Avoiding man page renaming
8058 Executables and manpages may be renamed upon installation
8059 (@pxref{Renaming}). For manpages this can be avoided by use of the
8060 @code{notrans_} prefix. For instance, suppose an executable @samp{foo}
8061 allowing to access a library function @samp{foo} from the command line.
8062 The way to avoid renaming of the @file{foo.3} manpage is:
8066 notrans_man_MANS = foo.3
8069 @cindex @code{notrans_} and @code{dist_} or @code{nodist_}
8070 @cindex @code{dist_} and @code{notrans_}
8071 @cindex @code{nodist_} and @code{notrans_}
8073 @samp{notrans_} must be specified first when used in conjunction with
8074 either @samp{dist_} or @samp{nodist_} (@pxref{Fine-grained Distribution
8075 Control}). For instance:
8078 notrans_dist_man3_MANS = bar.3
8082 @chapter What Gets Installed
8084 @cindex Installation support
8085 @cindex @samp{make install} support
8087 Naturally, Automake handles the details of actually installing your
8088 program once it has been built. All files named by the various
8089 primaries are automatically installed in the appropriate places when the
8090 user runs @samp{make install}.
8093 * Basics of Installation:: What gets installed where
8094 * The Two Parts of Install:: Installing data and programs separately
8095 * Extending Installation:: Adding your own rules for installation
8096 * Staged Installs:: Installation in a temporary location
8097 * Install Rules for the User:: Useful additional rules
8100 @node Basics of Installation
8101 @section Basics of Installation
8103 A file named in a primary is installed by copying the built file into
8104 the appropriate directory. The base name of the file is used when
8108 bin_PROGRAMS = hello subdir/goodbye
8111 In this example, both @samp{hello} and @samp{goodbye} will be installed
8112 in @samp{$(bindir)}.
8114 Sometimes it is useful to avoid the basename step at install time. For
8115 instance, you might have a number of header files in subdirectories of
8116 the source tree that are laid out precisely how you want to install
8117 them. In this situation you can use the @code{nobase_} prefix to
8118 suppress the base name step. For example:
8121 nobase_include_HEADERS = stdio.h sys/types.h
8125 will install @file{stdio.h} in @samp{$(includedir)} and @file{types.h}
8126 in @samp{$(includedir)/sys}.
8128 For most file types, Automake will install multiple files at once, while
8129 avoiding command line length issues (@pxref{Length Limitations}). Since
8130 some @command{install} programs will not install the same file twice in
8131 one invocation, you may need to ensure that file lists are unique within
8132 one variable such as @samp{nobase_include_HEADERS} above.
8134 You should not rely on the order in which files listed in one variable
8135 are installed. Likewise, to cater for parallel make, you should not
8136 rely on any particular file installation order even among different
8137 file types (library dependencies are an exception here).
8140 @node The Two Parts of Install
8141 @section The Two Parts of Install
8143 Automake generates separate @code{install-data} and @code{install-exec}
8144 rules, in case the installer is installing on multiple machines that
8145 share directory structure---these targets allow the machine-independent
8146 parts to be installed only once. @code{install-exec} installs
8147 platform-dependent files, and @code{install-data} installs
8148 platform-independent files. The @code{install} target depends on both
8149 of these targets. While Automake tries to automatically segregate
8150 objects into the correct category, the @file{Makefile.am} author is, in
8151 the end, responsible for making sure this is done correctly.
8152 @trindex install-data
8153 @trindex install-exec
8155 @cindex Install, two parts of
8157 Variables using the standard directory prefixes @samp{data},
8158 @samp{info}, @samp{man}, @samp{include}, @samp{oldinclude},
8159 @samp{pkgdata}, or @samp{pkginclude} are installed by
8160 @code{install-data}.
8162 Variables using the standard directory prefixes @samp{bin},
8163 @samp{sbin}, @samp{libexec}, @samp{sysconf}, @samp{localstate},
8164 @samp{lib}, or @samp{pkglib} are installed by @code{install-exec}.
8166 For instance, @code{data_DATA} files are installed by @code{install-data},
8167 while @code{bin_PROGRAMS} files are installed by @code{install-exec}.
8169 Any variable using a user-defined directory prefix with
8170 @samp{exec} in the name (e.g.,
8171 @c Keep in sync with primary-prefix-couples-documented-valid.test.
8172 @code{myexecbin_PROGRAMS}) is installed by @code{install-exec}. All
8173 other user-defined prefixes are installed by @code{install-data}.
8175 @node Extending Installation
8176 @section Extending Installation
8178 It is possible to extend this mechanism by defining an
8179 @code{install-exec-local} or @code{install-data-local} rule. If these
8180 rules exist, they will be run at @samp{make install} time. These
8181 rules can do almost anything; care is required.
8182 @trindex install-exec-local
8183 @trindex install-data-local
8185 Automake also supports two install hooks, @code{install-exec-hook} and
8186 @code{install-data-hook}. These hooks are run after all other install
8187 rules of the appropriate type, exec or data, have completed. So, for
8188 instance, it is possible to perform post-installation modifications
8189 using an install hook. @xref{Extending}, for some examples.
8190 @cindex Install hook
8192 @node Staged Installs
8193 @section Staged Installs
8196 Automake generates support for the @code{DESTDIR} variable in all
8197 install rules. @code{DESTDIR} is used during the @samp{make install}
8198 step to relocate install objects into a staging area. Each object and
8199 path is prefixed with the value of @code{DESTDIR} before being copied
8200 into the install area. Here is an example of typical DESTDIR usage:
8203 mkdir /tmp/staging &&
8204 make DESTDIR=/tmp/staging install
8207 The @command{mkdir} command avoids a security problem if the attacker
8208 creates a symbolic link from @file{/tmp/staging} to a victim area;
8209 then @command{make} places install objects in a directory tree built under
8210 @file{/tmp/staging}. If @file{/gnu/bin/foo} and
8211 @file{/gnu/share/aclocal/foo.m4} are to be installed, the above command
8212 would install @file{/tmp/staging/gnu/bin/foo} and
8213 @file{/tmp/staging/gnu/share/aclocal/foo.m4}.
8215 This feature is commonly used to build install images and packages
8218 Support for @code{DESTDIR} is implemented by coding it directly into
8219 the install rules. If your @file{Makefile.am} uses a local install
8220 rule (e.g., @code{install-exec-local}) or an install hook, then you
8221 must write that code to respect @code{DESTDIR}.
8223 @xref{Makefile Conventions, , , standards, The GNU Coding Standards},
8224 for another usage example.
8226 @node Install Rules for the User
8227 @section Install Rules for the User
8229 Automake also generates rules for targets @code{uninstall},
8230 @code{installdirs}, and @code{install-strip}.
8232 @trindex installdirs
8233 @trindex install-strip
8235 Automake supports @code{uninstall-local} and @code{uninstall-hook}.
8236 There is no notion of separate uninstalls for ``exec'' and ``data'', as
8237 these features would not provide additional functionality.
8239 Note that @code{uninstall} is not meant as a replacement for a real
8244 @chapter What Gets Cleaned
8246 @cindex @samp{make clean} support
8248 The GNU Makefile Standards specify a number of different clean rules.
8249 @xref{Standard Targets, , Standard Targets for Users, standards,
8250 The GNU Coding Standards}.
8252 Generally the files that can be cleaned are determined automatically by
8253 Automake. Of course, Automake also recognizes some variables that can
8254 be defined to specify additional files to clean. These variables are
8255 @code{MOSTLYCLEANFILES}, @code{CLEANFILES}, @code{DISTCLEANFILES}, and
8256 @code{MAINTAINERCLEANFILES}.
8257 @vindex MOSTLYCLEANFILES
8259 @vindex DISTCLEANFILES
8260 @vindex MAINTAINERCLEANFILES
8262 @trindex mostlyclean-local
8263 @trindex clean-local
8264 @trindex distclean-local
8265 @trindex maintainer-clean-local
8266 When cleaning involves more than deleting some hard-coded list of
8267 files, it is also possible to supplement the cleaning rules with your
8268 own commands. Simply define a rule for any of the
8269 @code{mostlyclean-local}, @code{clean-local}, @code{distclean-local},
8270 or @code{maintainer-clean-local} targets (@pxref{Extending}). A common
8271 case is deleting a directory, for instance, a directory created by the
8279 Since @command{make} allows only one set of rules for a given target,
8280 a more extensible way of writing this is to use a separate target
8281 listed as a dependency:
8284 clean-local: clean-local-check
8285 .PHONY: clean-local-check
8290 As the GNU Standards aren't always explicit as to which files should
8291 be removed by which rule, we've adopted a heuristic that we believe
8292 was first formulated by Fran@,{c}ois Pinard:
8296 If @command{make} built it, and it is commonly something that one would
8297 want to rebuild (for instance, a @file{.o} file), then
8298 @code{mostlyclean} should delete it.
8301 Otherwise, if @command{make} built it, then @code{clean} should delete it.
8304 If @command{configure} built it, then @code{distclean} should delete it.
8307 If the maintainer built it (for instance, a @file{.info} file), then
8308 @code{maintainer-clean} should delete it. However
8309 @code{maintainer-clean} should not delete anything that needs to exist
8310 in order to run @samp{./configure && make}.
8313 We recommend that you follow this same set of heuristics in your
8318 @chapter What Goes in a Distribution
8321 * Basics of Distribution:: Files distributed by default
8322 * Fine-grained Distribution Control:: @code{dist_} and @code{nodist_} prefixes
8323 * The dist Hook:: A target for last-minute distribution changes
8324 * Checking the Distribution:: @samp{make distcheck} explained
8325 * The Types of Distributions:: A variety of formats and compression methods
8328 @node Basics of Distribution
8329 @section Basics of Distribution
8331 @cindex @samp{make dist}
8336 The @code{dist} rule in the generated @file{Makefile.in} can be used
8337 to generate a gzipped @code{tar} file and other flavors of archive for
8338 distribution. The file is named based on the @code{PACKAGE} and
8339 @code{VERSION} variables defined by @code{AM_INIT_AUTOMAKE}
8340 (@pxref{Macros}); more precisely the gzipped @code{tar} file is named
8341 @samp{@var{package}-@var{version}.tar.gz}.
8343 You can use the @command{make} variable @code{GZIP_ENV} to control how gzip
8344 is run. The default setting is @option{--best}.
8346 @cindex @code{m4_include}, distribution
8347 @cindex @code{include}, distribution
8350 For the most part, the files to distribute are automatically found by
8351 Automake: all source files are automatically included in a distribution,
8352 as are all @file{Makefile.am} and @file{Makefile.in} files. Automake also
8353 has a built-in list of commonly used files that are automatically
8354 included if they are found in the current directory (either physically,
8355 or as the target of a @file{Makefile.am} rule); this list is printed by
8356 @samp{automake --help}. Note that some files in this list are actually
8357 distributed only if other certain conditions hold (for example,
8358 @c Keep in sync with autodist-config-headers.test.
8359 the @file{config.h.top} and @file{config.h.bot} files are automatically
8360 distributed only if, e.g., @samp{AC_CONFIG_HEADERS([config.h])} is used
8361 in @file{configure.ac}). Also, files that are read by @command{configure}
8362 (i.e.@: the source files corresponding to the files specified in various
8363 Autoconf macros such as @code{AC_CONFIG_FILES} and siblings) are
8364 automatically distributed. Files included in a @file{Makefile.am} (using
8365 @code{include}) or in @file{configure.ac} (using @code{m4_include}), and
8366 helper scripts installed with @samp{automake --add-missing} are also
8370 Still, sometimes there are files that must be distributed, but which
8371 are not covered in the automatic rules. These files should be listed in
8372 the @code{EXTRA_DIST} variable. You can mention files from
8373 subdirectories in @code{EXTRA_DIST}.
8375 You can also mention a directory in @code{EXTRA_DIST}; in this case the
8376 entire directory will be recursively copied into the distribution.
8377 Please note that this will also copy @emph{everything} in the directory,
8378 including, e.g., Subversion's @file{.svn} private directories or CVS/RCS
8379 version control files. We recommend against using this feature.
8382 @vindex DIST_SUBDIRS
8383 If you define @code{SUBDIRS}, Automake will recursively include the
8384 subdirectories in the distribution. If @code{SUBDIRS} is defined
8385 conditionally (@pxref{Conditionals}), Automake will normally include
8386 all directories that could possibly appear in @code{SUBDIRS} in the
8387 distribution. If you need to specify the set of directories
8388 conditionally, you can set the variable @code{DIST_SUBDIRS} to the
8389 exact list of subdirectories to include in the distribution
8390 (@pxref{Conditional Subdirectories}).
8393 @node Fine-grained Distribution Control
8394 @section Fine-grained Distribution Control
8398 Sometimes you need tighter control over what does @emph{not} go into the
8399 distribution; for instance, you might have source files that are
8400 generated and that you do not want to distribute. In this case
8401 Automake gives fine-grained control using the @code{dist} and
8402 @code{nodist} prefixes. Any primary or @code{_SOURCES} variable can be
8403 prefixed with @code{dist_} to add the listed files to the distribution.
8404 Similarly, @code{nodist_} can be used to omit the files from the
8407 As an example, here is how you would cause some data to be distributed
8408 while leaving some source code out of the distribution:
8411 dist_data_DATA = distribute-this
8413 nodist_foo_SOURCES = do-not-distribute.c
8417 @section The dist Hook
8421 Occasionally it is useful to be able to change the distribution before
8422 it is packaged up. If the @code{dist-hook} rule exists, it is run
8423 after the distribution directory is filled, but before the actual
8424 distribution archives are created. One way to use this is for
8425 removing unnecessary files that get recursively included by specifying
8426 a directory in @code{EXTRA_DIST}:
8431 rm -rf `find $(distdir)/doc -type d -name .svn`
8434 @c The caveates described here should be documented in 'disthook.test'.
8436 Note that the @code{dist-hook} recipe shouldn't assume that the regular
8437 files in the distribution directory are writable; this might not be the
8438 case if one is packaging from a read-only source tree, or when a
8439 @code{make distcheck} is being done. For similar reasons, the recipe
8440 shouldn't assume that the subdirectories put into the distribution
8441 directory as effect of having them listed in @code{EXTRA_DIST} are
8442 writable. So, if the @code{dist-hook} recipe wants to modify the
8443 content of an existing file (or @code{EXTRA_DIST} subdirectory) in the
8444 distribution directory, it should explicitly to make it writable first:
8447 EXTRA_DIST = README doc
8449 chmod u+w $(distdir)/README $(distdir)/doc
8450 echo "Distribution date: `date`" >> README
8451 rm -f $(distdir)/doc/HACKING
8456 Two variables that come handy when writing @code{dist-hook} rules are
8457 @samp{$(distdir)} and @samp{$(top_distdir)}.
8459 @samp{$(distdir)} points to the directory where the @code{dist} rule
8460 will copy files from the current directory before creating the
8461 tarball. If you are at the top-level directory, then @samp{distdir =
8462 $(PACKAGE)-$(VERSION)}. When used from subdirectory named
8463 @file{foo/}, then @samp{distdir = ../$(PACKAGE)-$(VERSION)/foo}.
8464 @samp{$(distdir)} can be a relative or absolute path, do not assume
8467 @samp{$(top_distdir)} always points to the root directory of the
8468 distributed tree. At the top-level it's equal to @samp{$(distdir)}.
8469 In the @file{foo/} subdirectory
8470 @samp{top_distdir = ../$(PACKAGE)-$(VERSION)}.
8471 @samp{$(top_distdir)} too can be a relative or absolute path.
8473 Note that when packages are nested using @code{AC_CONFIG_SUBDIRS}
8474 (@pxref{Subpackages}), then @samp{$(distdir)} and
8475 @samp{$(top_distdir)} are relative to the package where @samp{make
8476 dist} was run, not to any sub-packages involved.
8478 @node Checking the Distribution
8479 @section Checking the Distribution
8481 @cindex @samp{make distcheck}
8483 Automake also generates a @code{distcheck} rule that can be of help
8484 to ensure that a given distribution will actually work. Simplifying
8485 a bit, we can say this rule first makes a distribution, and then,
8486 @emph{operating from it}, takes the following steps:
8489 tries to do a @code{VPATH} build (@pxref{VPATH Builds}), with the
8490 @code{srcdir} and all its content made @emph{read-only};
8492 runs the test suite (with @command{make check}) on this fresh build;
8494 installs the package in a temporary directory (with @command{make
8495 install}), and tries runs the test suite on the resulting installation
8496 (with @command{make installcheck});
8498 checks that the package can be correctly uninstalled (by @command{make
8499 uninstall}) and cleaned (by @code{make distclean});
8501 finally, makes another tarball to ensure the distribution is
8505 @vindex AM_DISTCHECK_CONFIGURE_FLAGS
8506 @vindex DISTCHECK_CONFIGURE_FLAGS
8507 @subheading DISTCHECK_CONFIGURE_FLAGS
8508 Building the package involves running @samp{./configure}. If you need
8509 to supply additional flags to @command{configure}, define them in the
8510 @code{AM_DISTCHECK_CONFIGURE_FLAGS} variable in your top-level
8511 @file{Makefile.am}. The user can still extend or override the flags
8512 provided there by defining the @code{DISTCHECK_CONFIGURE_FLAGS} variable,
8513 on the command line when invoking @command{make}.
8515 Still, developers are encouraged to strive to make their code buildable
8516 without requiring any special configure option; thus, in general, you
8517 shouldn't define @code{AM_DISTCHECK_CONFIGURE_FLAGS}. However, there
8518 might be few scenarios in which the use of this variable is justified.
8519 GNU @command{m4} offers an example. GNU @command{m4} configures by
8520 default with its experimental and seldom used "changeword" feature
8521 disabled; so in its case it is useful to have @command{make distcheck}
8522 run configure with the @option{--with-changeword} option, to ensure that
8523 the code for changeword support still compiles correctly.
8524 GNU @command{m4} also employs the @code{AM_DISTCHECK_CONFIGURE_FLAGS}
8525 variable to stress-test the use of @option{--program-prefix=g}, since at
8526 one point the @command{m4} build system had a bug where @command{make
8527 installcheck} was wrongly assuming it could blindly test "@command{m4}",
8528 rather than the just-installed "@command{gm4}".
8530 @trindex distcheck-hook
8531 @subheading distcheck-hook
8532 If the @code{distcheck-hook} rule is defined in your top-level
8533 @file{Makefile.am}, then it will be invoked by @code{distcheck} after
8534 the new distribution has been unpacked, but before the unpacked copy
8535 is configured and built. Your @code{distcheck-hook} can do almost
8536 anything, though as always caution is advised. Generally this hook is
8537 used to check for potential distribution errors not caught by the
8538 standard mechanism. Note that @code{distcheck-hook} as well as
8539 @code{AM_DISTCHECK_CONFIGURE_FLAGS} and @code{DISTCHECK_CONFIGURE_FLAGS}
8540 are not honored in a subpackage @file{Makefile.am}, but the flags from
8541 @code{AM_DISTCHECK_CONFIGURE_FLAGS} and @code{DISTCHECK_CONFIGURE_FLAGS}
8542 are passed down to the @command{configure} script of the subpackage.
8544 @cindex @samp{make distcleancheck}
8545 @trindex distcleancheck
8546 @vindex DISTCLEANFILES
8547 @vindex distcleancheck_listfiles
8549 @subheading distcleancheck
8550 Speaking of potential distribution errors, @code{distcheck} also
8551 ensures that the @code{distclean} rule actually removes all built
8552 files. This is done by running @samp{make distcleancheck} at the end of
8553 the @code{VPATH} build. By default, @code{distcleancheck} will run
8554 @code{distclean} and then make sure the build tree has been emptied by
8555 running @samp{$(distcleancheck_listfiles)}. Usually this check will
8556 find generated files that you forgot to add to the @code{DISTCLEANFILES}
8557 variable (@pxref{Clean}).
8559 The @code{distcleancheck} behavior should be OK for most packages,
8560 otherwise you have the possibility to override the definition of
8561 either the @code{distcleancheck} rule, or the
8562 @samp{$(distcleancheck_listfiles)} variable. For instance, to disable
8563 @code{distcleancheck} completely, add the following rule to your
8564 top-level @file{Makefile.am}:
8571 If you want @code{distcleancheck} to ignore built files that have not
8572 been cleaned because they are also part of the distribution, add the
8573 following definition instead:
8575 @c Keep in sync with distcleancheck.test.
8577 distcleancheck_listfiles = \
8578 find . -type f -exec sh -c 'test -f $(srcdir)/$$1 || echo $$1' \
8582 The above definition is not the default because it's usually an error if
8583 your Makefiles cause some distributed files to be rebuilt when the user
8584 build the package. (Think about the user missing the tool required to
8585 build the file; or if the required tool is built by your package,
8586 consider the cross-compilation case where it can't be run.) There is
8587 an entry in the FAQ about this (@pxref{Errors with distclean}), make
8588 sure you read it before playing with @code{distcleancheck_listfiles}.
8590 @cindex @samp{make distuninstallcheck}
8591 @trindex distuninstallcheck
8592 @vindex distuninstallcheck_listfiles
8594 @subheading distuninstallcheck
8595 @code{distcheck} also checks that the @code{uninstall} rule works
8596 properly, both for ordinary and @code{DESTDIR} builds. It does this
8597 by invoking @samp{make uninstall}, and then it checks the install tree
8598 to see if any files are left over. This check will make sure that you
8599 correctly coded your @code{uninstall}-related rules.
8601 By default, the checking is done by the @code{distuninstallcheck} rule,
8602 and the list of files in the install tree is generated by
8603 @samp{$(distuninstallcheck_listfiles)} (this is a variable whose value is
8604 a shell command to run that prints the list of files to stdout).
8606 Either of these can be overridden to modify the behavior of
8607 @code{distcheck}. For instance, to disable this check completely, you
8615 @node The Types of Distributions
8616 @section The Types of Distributions
8618 Automake generates rules to provide archives of the project for
8619 distributions in various formats. Their targets are:
8623 @item @code{dist-bzip2}
8624 Generate a bzip2 tar archive of the distribution. bzip2 archives are
8625 frequently smaller than gzipped archives.
8626 By default, this rule makes @samp{bzip2} use a compression option of @option{-9}.
8627 To make it use a different one, set the @env{BZIP2} environment variable.
8628 For example, @samp{make dist-bzip2 BZIP2=-7}.
8631 @item @code{dist-gzip}
8632 Generate a gzip tar archive of the distribution.
8635 @item @code{dist-lzip}
8636 Generate an @samp{lzip} tar archive of the distribution. @command{lzip}
8637 archives are frequently smaller than @command{bzip2}-compressed archives.
8640 @item @code{dist-shar}
8641 Generate a shar archive of the distribution.
8645 @item @code{dist-xz}
8646 Generate an @samp{xz} tar archive of the distribution. @command{xz}
8647 archives are frequently smaller than @command{bzip2}-compressed archives.
8648 By default, this rule makes @samp{xz} use a compression option of
8649 @option{-e}. To make it use a different one, set the @env{XZ_OPT}
8650 environment variable. For example, run this command to use the
8651 default compression ratio, but with a progress indicator:
8652 @samp{make dist-xz XZ_OPT=-7e}.
8655 @item @code{dist-zip}
8656 Generate a zip archive of the distribution.
8659 @item @code{dist-tarZ}
8660 Generate a compressed tar archive of
8665 The rule @code{dist} (and its historical synonym @code{dist-all}) will
8666 create archives in all the enabled formats, @ref{Options}. By
8667 default, only the @code{dist-gzip} target is hooked to @code{dist}.
8671 @chapter Support for test suites
8674 @cindex @code{make check}
8677 Automake can generate code to handle two kinds of test suites. One is
8678 based on integration with the @command{dejagnu} framework. The other
8679 (and most used) form is based on the use of generic test scripts, and
8680 its activation is triggered by the definition of the special @code{TESTS}
8681 variable. This second form allows for various degrees of sophistication
8682 and customization; in particular, it allows for concurrent execution
8683 of test scripts, use of established test protocols such as TAP, and
8684 definition of custom test drivers and test runners.
8687 In either case, the testsuite is invoked via @samp{make check}.
8690 * Generalities about Testing:: Concepts and terminology about testing
8691 * Simple Tests:: Listing test scripts in @code{TESTS}
8692 * Custom Test Drivers:: Writing and using custom test drivers
8693 * Using the TAP test protocol:: Integrating test scripts that use the TAP protocol
8694 * DejaGnu Tests:: Interfacing with the @command{dejagnu} testing framework
8695 * Install Tests:: Running tests on installed packages
8698 @node Generalities about Testing
8699 @section Generalities about Testing
8701 The purpose of testing is to determine whether a program or system behaves
8702 as expected (e.g., known inputs produce the expected outputs, error
8703 conditions are correctly handled or reported, and older bugs do not
8707 The minimal unit of testing is usually called @emph{test case}, or simply
8708 @emph{test}. How a test case is defined or delimited, and even what
8709 exactly @emph{constitutes} a test case, depends heavily on the testing
8710 paradigm and/or framework in use, so we won't attempt any more precise
8711 definition. The set of the test cases for a given program or system
8712 constitutes its @emph{testsuite}.
8714 @cindex test harness
8715 @cindex testsuite harness
8716 A @emph{test harness} (also @emph{testsuite harness}) is a program or
8717 software component that executes all (or part of) the defined test cases,
8718 analyzes their outcomes, and report or register these outcomes
8719 appropriately. Again, the details of how this is accomplished (and how
8720 the developer and user can influence it or interface with it) varies
8721 wildly, and we'll attempt no precise definition.
8724 @cindex test failure
8725 A test is said to @emph{pass} when it can determine that the condition or
8726 behaviour it means to verify holds, and is said to @emph{fail} when it can
8727 determine that such condition of behaviour does @emph{not} hold.
8730 Sometimes, tests can rely on non-portable tools or prerequisites, or
8731 simply make no sense on a given system (for example, a test checking a
8732 Windows-specific feature makes no sense on a GNU/Linux system). In this
8733 case, accordingly to the definition above, the tests can neither be
8734 considered passed nor failed; instead, they are @emph{skipped} -- i.e.,
8735 they are not run, or their result is anyway ignored for what concerns
8736 the count of failures an successes. Skips are usually explicitly
8737 reported though, so that the user will be aware that not all of the
8738 testsuite has really run.
8741 @cindex expected failure
8742 @cindex expected test failure
8744 @cindex unexpected pass
8745 @cindex unexpected test pass
8746 It's not uncommon, especially during early development stages, that some
8747 tests fail for known reasons, and that the developer doesn't want to
8748 tackle these failures immediately (this is especially true when the
8749 failing tests deal with corner cases). In this situation, the better
8750 policy is to declare that each of those failures is an @emph{expected
8751 failure} (or @emph{xfail}). In case a test that is expected to fail ends
8752 up passing instead, many testing environments will flag the result as a
8753 special kind of failure called @emph{unexpected pass} (or @emph{xpass}).
8756 @cindex Distinction between errors and failures in testsuites
8757 Many testing environments and frameworks distinguish between test failures
8758 and hard errors. As we've seen, a test failure happens when some invariant
8759 or expected behaviour of the software under test is not met. An @emph{hard
8760 error} happens when e.g., the set-up of a test case scenario fails, or when
8761 some other unexpected or highly undesirable condition is encountered (for
8762 example, the program under test experiences a segmentation fault).
8764 @emph{TODO}: Links to other test harnesses (esp. those sharing our
8768 @section Simple Tests
8771 * Scripts-based Testsuites:: Automake-specific concepts and terminology
8772 * Serial Test Harness:: Older (and obsolescent) serial test harness
8773 * Parallel Test Harness:: Generic concurrent test harness
8776 @node Scripts-based Testsuites
8777 @subsection Scripts-based Testsuites
8779 If the special variable @code{TESTS} is defined, its value is taken to be
8780 a list of programs or scripts to run in order to do the testing. Under
8781 the appropriate circumstances, it's possible for @code{TESTS} to list
8782 also data files to be passed to one or more test scripts defined by
8783 different means (the so-called ``log compilers'', @pxref{Parallel Test
8786 Test scripts can be executed serially or concurrently. Automake
8787 supports both these kinds of test execution, with the serial test harness
8788 being the default (for backward-compatibility reasons only, as its use
8789 is nowadays discouraged). The concurrent test harness relies on the
8790 concurrence capabilities (if any) offered by the underlying @command{make}
8791 implementation, and can thus only be as good as those are.
8793 By default, only the exit statuses of the test scripts are considered when
8794 determining the testsuite outcome. But Automake allows also the use of
8795 more complex test protocols, either standard (@pxref{Using the TAP test
8796 protocol}) or custom (@pxref{Custom Test Drivers}). Note that you can
8797 enable such protocols only when the parallel harness is used: they won't
8798 work with the serial test harness. In the rest of this section we are
8799 going to concentrate mostly on protocol-less tests, since we'll have later
8800 a whole section devoted to the use of test protocols (again, @pxref{Custom
8803 @cindex Exit status 77, special interpretation
8804 @cindex Exit status 99, special interpretation
8805 When no test protocol is in use, an exit status of 0 from a test script will
8806 denote a success, an exit status of 77 a skipped test, an exit status of 99
8807 an hard error, and any other exit status will denote a failure.
8809 @cindex Tests, expected failure
8810 @cindex Expected test failure
8812 @vindex DISABLE_HARD_ERRORS
8813 @cindex Disabling hard errors
8814 You may define the variable @code{XFAIL_TESTS} to a list of tests
8815 (usually a subset of @code{TESTS}) that are expected to fail; this will
8816 effectively reverse the result of those tests (with the provision that
8817 skips and hard errors remain untouched). You may also instruct the
8818 testsuite harness to treat hard errors like simple failures, by defining
8819 the @code{DISABLE_HARD_ERRORS} make variable to a nonempty value.
8821 Note however that, for tests based on more complex test protocols,
8822 the exact effects of @code{XFAIL_TESTS} and @code{DISABLE_HARD_ERRORS}
8823 might change, or they might even have no effect at all (for example,
8824 @c Keep this in sync with tap-no-disable-hard-errors.test.
8825 in tests using TAP, there is not way to disable hard errors, and the
8826 @code{DISABLE_HARD_ERRORS} variable has no effect on them).
8828 @anchor{Testsuite progress on console}
8829 @cindex Testsuite progress on console
8830 The result of each test case run by the scripts in @code{TESTS} will be
8831 printed on standard output, along with the test name. For test protocols
8832 that allow more test cases per test script (such as TAP), a number,
8833 identifier and/or brief description specific for the single test case is
8834 expected to be printed in addition to the name of the test script. The
8835 possible results (whose meanings should be clear from the previous
8836 @ref{Generalities about Testing}) are @code{PASS}, @code{FAIL},
8837 @code{SKIP}, @code{XFAIL}, @code{XPASS} and @code{ERROR}. Here is an
8838 example of output from an hypothetical testsuite that uses both plain
8840 @c Keep in sync with tap-doc.test.
8843 PASS: zardoz.tap 1 - Daemon started
8844 PASS: zardoz.tap 2 - Daemon responding
8845 SKIP: zardoz.tap 3 - Daemon uses /proc # SKIP /proc is not mounted
8846 PASS: zardoz.tap 4 - Daemon stopped
8849 XFAIL: mu.tap 2 # TODO frobnication not yet implemented
8853 A testsuite summary (expected to report at least the number of run,
8854 skipped and failed tests) will be printed at the end of the testsuite
8857 @anchor{Simple tests and color-tests}
8858 @vindex AM_COLOR_TESTS
8859 @cindex Colorized testsuite output
8860 If the Automake option @code{color-tests} is used (@pxref{Options})
8861 and standard output is connected to a capable terminal, then the test
8862 results and the summary are colored appropriately. The user can disable
8863 colored output by setting the @command{make} variable
8864 @samp{AM_COLOR_TESTS=no}, or force colored output even without a connecting
8865 terminal with @samp{AM_COLOR_TESTS=always}. It's also worth noting that
8866 some @command{make} implementations, when used in parallel mode, have
8867 slightly different semantics (@pxref{Parallel make,,, autoconf,
8868 The Autoconf Manual}), which can break the automatic detection of a
8869 connection to a capable terminal. If this is the case, you'll have to
8870 resort to the use of @samp{AM_COLOR_TESTS=always} in order to have the
8871 testsuite output colorized.
8873 Test programs that need data files should look for them in @code{srcdir}
8874 (which is both a make variable and an environment variable made available
8875 to the tests), so that they work when building in a separate directory
8876 (@pxref{Build Directories, , Build Directories , autoconf,
8877 The Autoconf Manual}), and in particular for the @code{distcheck} rule
8878 (@pxref{Checking the Distribution}).
8881 @vindex TESTS_ENVIRONMENT
8882 @vindex AM_TESTS_ENVIRONMENT
8883 The @code{AM_TESTS_ENVIRONMENT} and @code{TESTS_ENVIRONMENT} variables can
8884 be used to run initialization code and set environment variables for the
8885 test scripts. The former variable is developer-reserved, and can be
8886 defined in the @file{Makefile.am}, while the latter is reserved for the
8887 user, which can employ it to extend or override the settings in the
8888 former; for this to work portably, however, the contents of a non-empty
8889 @code{AM_TESTS_ENVIRONMENT} @emph{must} be terminated by a semicolon.
8891 @vindex AM_TESTS_FD_REDIRECT
8892 The @code{AM_TESTS_FD_REDIRECT} variable can be used to define file
8893 descriptor redirections for the test scripts. One might think that
8894 @code{AM_TESTS_ENVIRONMENT} could be used for this purpose, but experience
8895 has shown that doing so portably is practically impossible. The main
8896 hurdle is constituted by Korn shells, which usually set the close-on-exec
8897 flag on file descriptors opened with the @command{exec} builtin, thus
8898 rendering an idiom like @code{AM_TESTS_ENVIRONMENT = exec 9>&2;}
8899 ineffectual. This issue also affects some Bourne shells, such as the
8900 HP-UX's @command{/bin/sh},
8901 @c FIXME: should we offer a link to the relevant discussions on the
8902 @c bug-autoconf list?
8904 @c Keep in sync with tests-environment-backcompat.test.
8906 AM_TESTS_ENVIRONMENT = \
8907 ## Some environment initializations are kept in a separate shell
8908 ## file `tests-env.sh', which can make it easier to also run tests
8909 ## from the command line.
8910 . $(srcdir)/tests-env.sh; \
8911 ## On Solaris, prefer more POSIX-compliant versions of the standard
8912 ## tools by default.
8913 if test -d /usr/xpg4/bin; then \
8914 PATH=/usr/xpg4/bin:$$PATH; export PATH; \
8916 @c $$ restore font-lock
8917 ## With this, the test scripts will be able to print diagnostic
8918 ## messages to the original standard error stream, even if the test
8919 ## driver redirects the stderr of the test scripts to a log file
8920 ## before executing them.
8921 AM_TESTS_FD_REDIRECT = 9>&2
8925 Note however that @code{AM_TESTS_ENVIRONMENT} is, for historical and
8926 implementation reasons, @emph{not} supported by the serial harness
8927 (@pxref{Serial Test Harness}).
8929 Automake ensures that each file listed in @code{TESTS} is built before
8930 it is run; you can list both source and derived programs (or scripts)
8931 in @code{TESTS}; the generated rule will look both in @code{srcdir} and
8932 @file{.}. For instance, you might want to run a C program as a test.
8933 To do this you would list its name in @code{TESTS} and also in
8934 @code{check_PROGRAMS}, and then specify it as you would any other
8937 Programs listed in @code{check_PROGRAMS} (and @code{check_LIBRARIES},
8938 @code{check_LTLIBRARIES}...) are only built during @code{make check},
8939 not during @code{make all}. You should list there any program needed
8940 by your tests that does not need to be built by @code{make all}. Note
8941 that @code{check_PROGRAMS} are @emph{not} automatically added to
8942 @code{TESTS} because @code{check_PROGRAMS} usually lists programs used
8943 by the tests, not the tests themselves. Of course you can set
8944 @code{TESTS = $(check_PROGRAMS)} if all your programs are test cases.
8946 @node Serial Test Harness
8947 @subsection Serial Test Harness
8948 @cindex @option{serial-tests}, Using
8950 @emph{NOTE:} This harness, while still being the default one, is
8951 obsolescent, and kept mostly for backward-compatibility reasons. The user
8952 is advised to use the parallel test harness instead (@pxref{Parallel Test
8953 Harness}). Be warned that future Automake versions might switch to use
8954 that more modern and feature-rich harness by default.
8956 The serial test harness is enabled by the Automake option
8957 @option{serial-tests}. It operates by simply running the tests serially,
8958 one at the time, without any I/O redirection. It's up to the user to
8959 implement logging of tests' output, if that's requited or desired.
8960 @c TODO: give an example of how this can be done.
8962 For historical and implementation reasons, the @code{AM_TESTS_ENVIRONMENT}
8963 variable is @emph{not} supported by this harness (it will be silently
8964 ignored if defined); only @code{TESTS_ENVIRONMENT} is, and it is to be
8965 considered a developer-reserved variable. This is done so that, when
8966 using the serial harness, @code{TESTS_ENVIRONMENT} can be defined to an
8967 invocation of an interpreter through which the tests are to be run.
8968 For instance, the following setup may be used to run tests with Perl:
8971 TESTS_ENVIRONMENT = $(PERL) -Mstrict -w
8972 TESTS = foo.pl bar.pl baz.pl
8976 It's important to note that the use of @code{TESTS_ENVIRONMENT} endorsed
8977 here would be @emph{invalid} with the parallel harness. That harness
8978 provides a more elegant way to achieve the same effect, with the further
8979 benefit of freeing the @code{TESTS_ENVIRONMENT} variable for the user
8980 (@pxref{Parallel Test Harness}).
8982 Another, less serious limit of the serial harness is that it doesn't
8983 really distinguish between simple failures and hard errors; this is
8984 due to historical reasons only, and might be fixed in future Automake
8987 @node Parallel Test Harness
8988 @subsection Parallel Test Harness
8989 @cindex @option{parallel-tests}, Using
8991 The parallel (or concurrent) test harness is enabled by the Automake option
8992 @option{parallel-tests}. It features automatic collection of the test
8993 scripts output in @file{.log} files, concurrent execution of tests with
8994 @code{make -j}, specification of inter-test dependencies, lazy reruns of
8995 tests that have not completed in a prior run, and hard errors for exceptional
8998 This harness is still somewhat experimental and may undergo changes in
8999 order to satisfy additional portability requirements.
9001 @anchor{Basics of test metadata}
9002 @vindex TEST_SUITE_LOG
9004 @cindex @file{.log} files
9005 @cindex @file{.trs} files
9006 @cindex test metadata
9007 The parallel test harness operates by defining a set of @command{make}
9008 rules that run the test scripts listed in @code{TESTS}, and, for each
9009 such script, save its output in a corresponding @file{.log} file and
9010 its results (and other ``metadata'', @pxref{API for Custom Test Drivers})
9011 in a corresponding @file{.trs} (as in @b{T}est @b{R}e@b{S}ults) file.
9012 @c We choose the `.trs' extension also because, at the time of writing,
9013 @c it isn't already used for other significant purposes; see e.g.:
9014 @c - http://filext.com/file-extension/trs
9015 @c - http://www.file-extensions.org/search/?searchstring=trs
9016 The @file{.log} file will contain all the output emitted by the test on
9017 its standard output and its standard error. The @file{.trs} file will
9018 contain, among the other things, the results of the test cases run by
9021 The parallel test harness will also create a summary log file,
9022 @code{TEST_SUITE_LOG}, which defaults to @file{test-suite.log} and requires
9023 a @file{.log} suffix. This file depends upon all the @file{.log} and
9024 @file{.trs} files created for the test scripts listed in @code{TESTS}.
9027 As with the serial harness above, by default one status line is printed
9028 per completed test, and a short summary after the suite has completed.
9029 However, standard output and standard error of the test are redirected
9030 to a per-test log file, so that parallel execution does not produce
9031 intermingled output. The output from failed tests is collected in the
9032 @file{test-suite.log} file. If the variable @samp{VERBOSE} is set, this
9033 file is output after the summary.
9034 @c FIXME: we should be clearer about what we mean exactly here ...
9035 For best results, the tests should be verbose by default now.
9037 @vindex TEST_EXTENSIONS
9039 Each couple of @file{.log} and @file{.trs} files is created when the
9040 corresponding test has completed. The set of log files is listed in
9041 the read-only variable @code{TEST_LOGS}, and defaults to @code{TESTS},
9042 with the executable extension if any (@pxref{EXEEXT}), as well as any
9043 suffix listed in @code{TEST_EXTENSIONS} removed, and @file{.log} appended.
9044 Results are undefined if a test file name ends in several concatenated
9045 suffixes. @code{TEST_EXTENSIONS} defaults to @file{.test}; it can be
9046 overridden by the user, in which case any extension listed in it must be
9047 constituted by a dot, followed by a non-digit alphabetic character,
9048 followed by any number of alphabetic characters.
9049 @c Keep in sync with test-extensions.test.
9050 For example, @samp{.sh}, @samp{.T} and @samp{.t1} are valid extensions,
9051 while @samp{.x-y}, @samp{.6c} and @samp{.t.1} are not.
9053 @vindex _LOG_COMPILE
9054 @vindex _LOG_COMPILER
9057 @vindex LOG_COMPILER
9059 @vindex @var{ext}_LOG_COMPILE
9060 @vindex @var{ext}_LOG_COMPILER
9061 @vindex @var{ext}_LOG_FLAGS
9062 @vindex AM_@var{ext}_LOG_FLAGS
9063 @vindex AM_LOG_FLAGS
9064 For tests that match an extension @code{.@var{ext}} listed in
9065 @code{TEST_EXTENSIONS}, you can provide a custom ``test runner'' using
9066 the variable @code{@var{ext}_LOG_COMPILER} (note the upper-case
9067 extension) and pass options in @code{AM_@var{ext}_LOG_FLAGS} and allow
9068 the user to pass options in @code{@var{ext}_LOG_FLAGS}. It will cause
9069 all tests with this extension to be called with this runner. For all
9070 tests without a registered extension, the variables @code{LOG_COMPILER},
9071 @code{AM_LOG_FLAGS}, and @code{LOG_FLAGS} may be used. For example,
9073 @c Keep in sync with parallel-tests-log-compiler-example.test.
9075 TESTS = foo.pl bar.py baz
9076 TEST_EXTENSIONS = .pl .py
9077 PL_LOG_COMPILER = $(PERL)
9078 AM_PL_LOG_FLAGS = -w
9079 PY_LOG_COMPILER = $(PYTHON)
9080 AM_PY_LOG_FLAGS = -v
9081 LOG_COMPILER = ./wrapper-script
9086 will invoke @samp{$(PERL) -w foo.pl}, @samp{$(PYTHON) -v bar.py},
9087 and @samp{./wrapper-script -d baz} to produce @file{foo.log},
9088 @file{bar.log}, and @file{baz.log}, respectively. The @file{foo.trs},
9089 @file{bar.trs} and @file{baz.trs} files will be automatically produced
9092 It's important to note that, differently from what we've seen for the
9093 serial test harness (@pxref{Parallel Test Harness}), the
9094 @code{AM_TESTS_ENVIRONMENT} and @code{TESTS_ENVIRONMENT} variables
9095 @emph{cannot} be use to define a custom test runner; the
9096 @code{LOG_COMPILER} and @code{LOG_FLAGS} (or their extension-specific
9097 counterparts) should be used instead:
9101 AM_TESTS_ENVIRONMENT = PERL5LIB='$(srcdir)/lib' $(PERL) -Mstrict -w
9106 AM_TESTS_ENVIRONMENT = PERL5LIB='$(srcdir)/lib'; export PERL5LIB;
9107 LOG_COMPILER = $(PERL)
9108 AM_LOG_FLAGS = -Mstrict -w
9111 By default, the test suite harness will run all tests, but there are
9112 several ways to limit the set of tests that are run:
9116 You can set the @code{TESTS} variable. For example, you can use a
9117 command like this to run only a subset of the tests:
9120 env TESTS="foo.test bar.test" make -e check
9123 Note however that the command above will unconditionally overwrite the
9124 @file{test-suite.log} file, thus clobbering the recorded results
9125 of any previous testsuite run. This might be undesirable for packages
9126 whose testsuite takes long time to execute. Luckily, this problem can
9127 easily be avoided by overriding also @code{TEST_SUITE_LOG} at runtime;
9130 @c Keep in sync with parallel-tests-log-override-2.test.
9132 env TEST_SUITE_LOG=partial.log TESTS="..." make -e check
9135 will write the result of the partial testsuite runs to the
9136 @file{partial.log}, without touching @file{test-suite.log}.
9139 You can set the @code{TEST_LOGS} variable. By default, this variable is
9140 computed at @command{make} run time from the value of @code{TESTS} as
9141 described above. For example, you can use the following:
9144 set x subset*.log; shift
9145 env TEST_LOGS="foo.log $*" make -e check
9148 The comments made above about @code{TEST_SUITE_LOG} overriding applies
9152 @vindex RECHECK_LOGS
9153 @cindex lazy test execution
9154 By default, the test harness removes all old per-test @file{.log} and
9155 @file{.trs} files before it starts running tests to regenerate them. The
9156 variable @code{RECHECK_LOGS} contains the set of @file{.log} (and, by
9157 implication, @file{.trs}) files which are removed. @code{RECHECK_LOGS}
9158 defaults to @code{TEST_LOGS}, which means all tests need to be rechecked.
9159 By overriding this variable, you can choose which tests need to be
9160 reconsidered. For example, you can lazily rerun only those tests which
9161 are outdated, i.e., older than their prerequisite test files, by setting
9162 this variable to the empty value:
9165 env RECHECK_LOGS= make -e check
9170 You can ensure that all tests are rerun which have failed or passed
9171 unexpectedly, by running @code{make recheck} in the test directory.
9172 This convenience target will set @code{RECHECK_LOGS} appropriately
9173 before invoking the main test harness.
9177 In order to guarantee an ordering between tests even with @code{make
9178 -j@var{N}}, dependencies between the corresponding @file{.log} files
9179 may be specified through usual @command{make} dependencies. For example,
9180 the following snippet lets the test named @file{foo-execute.test} depend
9181 upon completion of the test @file{foo-compile.test}:
9184 TESTS = foo-compile.test foo-execute.test
9185 foo-execute.log: foo-compile.log
9189 Please note that this ordering ignores the @emph{results} of required
9190 tests, thus the test @file{foo-execute.test} is run even if the test
9191 @file{foo-compile.test} failed or was skipped beforehand. Further,
9192 please note that specifying such dependencies currently works only for
9193 tests that end in one of the suffixes listed in @code{TEST_EXTENSIONS}.
9195 Tests without such specified dependencies may be run concurrently with
9196 parallel @command{make -j@var{N}}, so be sure they are prepared for
9197 concurrent execution.
9200 @c Keep in sync with 'parallel-tests-extra-programs.test'.
9201 The combination of lazy test execution and correct dependencies between
9202 tests and their sources may be exploited for efficient unit testing
9203 during development. To further speed up the edit-compile-test cycle, it
9204 may even be useful to specify compiled programs in @code{EXTRA_PROGRAMS}
9205 instead of with @code{check_PROGRAMS}, as the former allows intertwined
9206 compilation and test execution (but note that @code{EXTRA_PROGRAMS} are
9207 not cleaned automatically, @pxref{Uniform}).
9209 The variables @code{TESTS} and @code{XFAIL_TESTS} may contain
9210 conditional parts as well as configure substitutions. In the latter
9211 case, however, certain restrictions apply: substituted test names
9212 must end with a nonempty test suffix like @file{.test}, so that one of
9213 the inference rules generated by @command{automake} can apply. For
9214 literal test names, @command{automake} can generate per-target rules
9215 to avoid this limitation.
9217 Please note that it is currently not possible to use @code{$(srcdir)/}
9218 or @code{$(top_srcdir)/} in the @code{TESTS} variable. This technical
9219 limitation is necessary to avoid generating test logs in the source tree
9220 and has the unfortunate consequence that it is not possible to specify
9221 distributed tests that are themselves generated by means of explicit
9222 rules, in a way that is portable to all @command{make} implementations
9223 (@pxref{Make Target Lookup,,, autoconf, The Autoconf Manual}, the
9224 semantics of FreeBSD and OpenBSD @command{make} conflict with this).
9225 In case of doubt you may want to require to use GNU @command{make},
9226 or work around the issue with inference rules to generate the tests.
9228 @node Custom Test Drivers
9229 @section Custom Test Drivers
9232 * Overview of Custom Test Drivers Support::
9233 * Declaring Custom Test Drivers::
9234 * API for Custom Test Drivers::
9237 @node Overview of Custom Test Drivers Support
9238 @subsection Overview of Custom Test Drivers Support
9240 Starting from Automake version 1.12, the parallel test harness allows
9241 the package authors to use third-party custom test drivers, in case the
9242 default ones are inadequate for their purposes, or do not support their
9243 testing protocol of choice.
9245 A custom test driver is expected to properly run the test programs passed
9246 to it (including the command-line arguments passed to those programs, if
9247 any), to analyze their execution and outcome, to create the @file{.log}
9248 and @file{.trs} files associated to these test runs, and to display the test
9249 results on the console. It is responsibility of the author of the test
9250 driver to ensure that it implements all the above steps meaningfully and
9251 correctly; Automake isn't and can't be of any help here. On the other
9252 hand, the Automake-provided code for testsuite summary generation offers
9253 support for test drivers allowing several test results per test script,
9254 if they take care to register such results properly (@pxref{Log files
9255 generation and test results recording}).
9257 The exact details of how test scripts' results are to be determined and
9258 analyzed is left to the individual drivers. Some drivers might only
9259 consider the test script exit status (this is done for example by the
9260 default test driver used by the parallel test harness, described
9261 in the previous section). Other drivers might implement more complex and
9262 advanced test protocols, which might require them to parse and interpreter
9263 the output emitted by the test script they're running (examples of such
9264 protocols are TAP and SubUnit).
9266 It's very important to note that, even when using custom test drivers,
9267 most of the infrastructure described in the previous section about the
9268 parallel harness remains in place; this includes:
9272 list of test scripts defined in @code{TESTS}, and overridable at
9273 runtime through the redefinition of @code{TESTS} or @code{TEST_LOGS};
9275 concurrency through the use of @command{make}'s option @option{-j};
9277 per-test @file{.log} and @file{.trs} files, and generation of a summary
9278 @file{.log} file from them;
9280 @code{recheck} target, @code{RECHECK_LOGS} variable, and lazy reruns
9283 inter-test dependencies;
9285 support for @code{check_*} variables (@code{check_PROGRAMS},
9286 @code{check_LIBRARIES}, ...);
9288 use of @code{VERBOSE} environment variable to get verbose output on
9291 definition and honoring of @code{TESTS_ENVIRONMENT},
9292 @code{AM_TESTS_ENVIRONMENT} and @code{AM_TESTS_FD_REDIRECT}
9295 definition of generic and extension-specific @code{LOG_COMPILER} and
9296 @code{LOG_FLAGS} variables.
9300 On the other hand, the exact semantics of how (and if)
9301 @option{color-tests}, @code{XFAIL_TESTS}, and hard errors are supported
9302 and handled is left to the individual test drivers.
9304 @c TODO: We should really add a working example in the doc/ directory,
9305 @c TODO: and reference if from here.
9307 @node Declaring Custom Test Drivers
9308 @subsection Declaring Custom Test Drivers
9311 @vindex _LOG_DRIVER_FLAGS
9313 @vindex LOG_DRIVER_FLAGS
9314 @vindex @var{ext}_LOG_DRIVER
9315 @vindex @var{ext}_LOG_DRIVER_FLAGS
9316 @vindex AM_@var{ext}_LOG_DRIVER_FLAGS
9317 @vindex AM_LOG_DRIVER_FLAGS
9318 Custom testsuite drivers are declared by defining the make variables
9319 @code{LOG_DRIVER} or @code{@var{ext}_LOG_DRIVER} (where @var{ext} must
9320 be declared in @code{TEST_EXTENSIONS}). They must be defined to
9321 programs or scripts that will be used to drive the execution, logging,
9322 and outcome report of the tests with corresponding extensions (or of
9323 those with no registered extension in the case of @code{LOG_DRIVER}).
9324 Clearly, multiple distinct test drivers can be declared in the same
9325 @file{Makefile.am}. Note moreover that the @code{LOG_DRIVER} variables
9326 are @emph{not} a substitute for the @code{LOG_COMPILER} variables: the
9327 two sets of variables can, and often do, usefully and legitimately
9330 @c TODO: We should really be able to point to a clarifying example here!
9332 The developer-reserved variable @code{AM_LOG_DRIVER_FLAGS} and the
9333 user-reserved variable @code{LOG_DRIVER_FLAGS} can be used to define
9334 flags that will be passed to each invocation of @code{LOG_DRIVER},
9335 with the user-defined flags obviously taking precedence over the
9336 developer-reserved ones. Similarly, for each extension @var{ext}
9337 declared in @code{TEST_EXTENSIONS}, flags listed in
9338 @code{AM_@var{ext}_LOG_DRIVER_FLAGS} and
9339 @code{@var{ext}_LOG_DRIVER_FLAGS} will be passed to
9340 invocations of @code{@var{ext}_LOG_DRIVER}.
9342 @node API for Custom Test Drivers
9343 @subsection API for Custom Test Drivers
9345 Note that @emph{the APIs described here are still highly experimental},
9346 and will very likely undergo tightenings and likely also extensive changes
9347 in the future, to accommodate for new features or to satisfy additional
9348 portability requirements.
9350 The main characteristic of these APIs is that they are designed to share
9351 as much infrastructure, semantics, and implementation details as possible
9352 with the parallel test harness and its default driver.
9355 * Command-line arguments for test drivers::
9356 * Log files generation and test results recording::
9357 * Testsuite progress output::
9360 @node Command-line arguments for test drivers
9361 @subsubsection Command-line arguments for test drivers
9363 A custom driver can rely on various command-line options and arguments
9364 being passed to it automatically by the Automake's @option{parallel-tests}
9365 harness. It is @emph{mandatory} that it understands all of them (even
9366 if the exact interpretation of the associated semantics can legitimately
9367 change between a test driver and another, and even be a no-op in some
9371 Here is the list of options:
9374 @item --test-name=@var{NAME}
9375 The name of the test, with VPATH prefix (if any) removed. This can have a
9376 suffix and a directory component (as in e.g., @file{sub/foo.test}), and is
9377 mostly meant to be used in console reports about testsuite advancements and
9378 results (@pxref{Testsuite progress output}).
9379 @item --log-file=@file{@var{PATH}.log}
9380 The @file{.log} file the test driver must create (@pxref{Basics of
9381 test metadata}). If it has a directory component (as in e.g.,
9382 @file{sub/foo.log}), the test harness will ensure that such directory
9383 exists @emph{before} the test driver is called.
9384 @item --trs-file=@file{@var{PATH}.trs}
9385 The @file{.trs} file the test driver must create (@pxref{Basics of
9386 test metadata}). If it has a directory component (as in e.g.,
9387 @file{sub/foo.trs}), the test harness will ensure that such directory
9388 exists @emph{before} the test driver is called.
9389 @item --color-tests=@{yes|no@}
9390 Whether the console output should be colorized or not (@pxref{Simple
9391 tests and color-tests}, to learn when this option gets activated and
9393 @item --expect-failure=@{yes|no@}
9394 Whether the tested program is expected to fail.
9395 @item --enable-hard-errors=@{yes|no@}
9396 Whether ``hard errors'' in the tested program should be treated differently
9397 from normal failures or not (the default should be @code{yes}). The exact
9398 meaning of ``hard error'' is highly dependent from the test protocols or
9401 Explicitly terminate the list of options.
9405 The first non-option argument passed to the test driver is the program to
9406 be run, and all the following ones are command-line options and arguments
9409 Note that the exact semantics attached to the @option{--color-tests},
9410 @option{--expect-failure} and @option{--enable-hard-errors} options are
9411 left up to the individual test drivers. Still, having a behaviour
9412 compatible or at least similar to that provided by the default
9413 @option{parallel-tests} driver is advised, as that would offer a better
9414 consistency and a more pleasant user experience.
9416 @node Log files generation and test results recording
9417 @subsubsection Log files generation and test results recording
9419 The test driver must correctly generate the files specified by the
9420 @option{--log-file} and @option{--trs-file} option (even when the tested
9421 program fails or crashes).
9423 The @file{.log} file should ideally contain all the output produced by the
9424 tested program, plus optionally other information that might facilitate
9425 debugging or analysis of bug reports. Apart from that, its format is
9428 The @file{.trs} file is used to register some metadata through the use
9429 of custom reStructuredText fields. This metadata is expected to be
9430 employed in various ways by the parallel test harness; for example, to
9431 count the test results when printing the testsuite summary, or to decide
9432 which tests to re-run upon @command{make reheck}. Unrecognized metadata
9433 in a @file{.trs} file is currently ignored by the harness, but this might
9434 change in the future. The list of currently recognized metadata follows.
9439 @cindex Register test result
9440 @cindex Register test case result
9441 @cindex Test result, registering
9442 @cindex Test case result, registering
9443 @cindex @code{:test-result:}
9444 @cindex reStructuredText field, @code{:test-result:}
9445 The test driver must use this field to register the results of @emph{each}
9446 test case run by a test script file. Several @code{:test-result:} fields
9447 can be present in the same @file{.trs} file; this is done in order to
9448 support test protocols that allow a single test script to run more test
9451 @c Keep this in sync with lib/am/check-am:$(TEST_SUITE_LOG).
9452 The only recognized test results are currently @code{PASS}, @code{XFAIL},
9453 @code{SKIP}, @code{FAIL}, @code{XPASS} and @code{ERROR}. These results,
9454 when declared with @code{:test-result:}, can be optionally followed by
9455 text holding the name and/or a brief description of the corresponding
9456 test; the @option{parallel-tests} harness will ignore such extra text when
9457 generating @file{test-suite.log} and preparing the testsuite summary.
9459 @c Keep in sync with 'test-metadata-recheck.test'.
9460 @item @code{:recheck:}
9462 @cindex reStructuredText field, @code{:recheck:}
9463 If this field is present and defined to @code{no}, then the corresponding
9464 test script will @emph{not} be run upon a @command{make recheck}. What
9465 happens when two or more @code{:recheck:} fields are present in the same
9466 @file{.trs} file is undefined behaviour.
9468 @c Keep in sync with 'test-metadata-global-log.test'.
9469 @item @code{:copy-in-global-log:}
9470 @cindex :copy-in-global-log:
9471 @cindex reStructuredText field, @code{:copy-in-global-log:}
9472 If this field is present and defined to @code{no}, then the content
9473 of the @file{.log} file will @emph{not} be copied into the global
9474 @file{test-suite.log}. We allow to forsake such copying because, while
9475 it can be useful in debugging and analysis of bug report, it can also be
9476 just a waste of space in normal situations, e.g., when a test script is
9477 successful. What happens when two or more @code{:copy-in-global-log:}
9478 fields are present in the same @file{.trs} file is undefined behaviour.
9480 @c Keep in sync with 'test-metadata-global-result.test'.
9481 @item @code{:test-global-result:}
9482 @cindex :test-global-result:
9483 @cindex reStructuredText field, @code{:test-global-result:}
9484 This is used to declare the "global result" of the script. Currently,
9485 the value of this field is needed only to be reported (more or less
9486 verbatim) in the generated global log file @code{$(TEST_SUITE_LOG)},
9487 so it's quite free-form. For example, a test script which run 10 test
9488 cases, 6 of which pass and 4 of which are skipped, could reasonably have
9489 a @code{PASS/SKIP} value for this field, while a test script which run
9490 19 successful tests and one failed test could have an @code{ALMOST
9491 PASSED} value. What happens when two or more @code{:test-global-result:}
9492 fields are present in the same @file{.trs} file is undefined behaviour.
9496 Let's see a small example. Assume a @file{.trs} file contains the
9500 :test-result: PASS server starts
9501 :global-log-copy: no
9502 :test-result: PASS HTTP/1.1 request
9503 :test-result: FAIL HTTP/1.0 request
9505 :test-result: SKIP HTTPS request (TLS library wasn't available)
9506 :test-result: PASS server stops
9510 Then the corresponding test script will be re-run by @command{make check},
9511 will contribute with @emph{five} test results to the testsuite summary
9512 (three of these tests being successful, one failed, and one skipped), and
9513 the content of the corresponding @file{.log} file will @emph{not} be
9514 copied in the global log file @file{test-suite.log}.
9516 @node Testsuite progress output
9517 @subsubsection Testsuite progress output
9519 A custom test driver also has the task of displaying, on the standard
9520 output, the test results as soon as they become available. Depending on
9521 the protocol in use, it can also display the reasons for failures and
9522 skips, and, more generally, any useful diagnostic output (but remember
9523 that each line on the screen is precious, so that cluttering the screen
9524 with overly verbose information is bad idea). The exact format of this
9525 progress output is left up to the test driver; in fact, a custom test
9526 driver might @emph{theoretically} even decide not to do any such report,
9527 leaving it all to the testsuite summary (that would be a very lousy idea,
9528 of course, and serves only to illustrate the flexibility that is
9531 Remember that consistency is good; so, if possible, try to be consistent
9532 with the output of the built-in Automake test drivers, providing a similar
9533 ``look & feel''. In particular, the testsuite progress output should be
9534 colorized when the @option{--color-tests} is passed to the driver. On the
9535 other end, if you are using a known and widespread test protocol with
9536 well-established implementations, being consistent with those
9537 implementations' output might be a good idea too.
9539 @c TODO: Give an example, maybe inspired to py.test-style output.
9540 @c TODO: That is a good idea because it shows a test driver that allows
9541 @c TODO: for different levels of verbosity in the progress output (could
9542 @c TODO: be implemented either using a driver cmdline flag, or an
9543 @c TODO: environment variable, or both).
9545 @node Using the TAP test protocol
9546 @section Using the TAP test protocol
9549 * Introduction to TAP::
9550 * Use TAP with the Automake test harness::
9551 * Incompatibilities with other TAP parsers and drivers::
9552 * Links and external resources on TAP::
9555 @node Introduction to TAP
9556 @subsection Introduction to TAP
9558 TAP, the Test Anything Protocol, is a simple text-based interface between
9559 testing modules or programs and a test harness. The tests (also called
9560 ``TAP producers'' in this context) write test results in a simple format
9561 on standard output; a test harness (also called ``TAP consumer'') will
9562 parse and interpret these results, and properly present them to the user,
9563 and/or register them for later analysis. The exact details of how this
9564 is accomplished can vary among different test harnesses. The Automake
9565 parallel harness will present the results on the console in the usual
9566 fashion (@pxref{Testsuite progress on console}), and will use the
9567 @file{.trs} files (@pxref{Basics of test metadata}) to store the test
9568 results and related metadata. Apart from that, it will try to remain
9569 as much compatible as possible with pre-existing and widespread utilities,
9570 such as the @uref{http://search.cpan.org/~andya/Test-Harness/bin/prove,
9571 @command{prove} utility}, at least for the simpler usages.
9573 TAP started its life as part of the test harness for Perl, but today
9574 it has been (mostly) standardized, and has various independent
9575 implementations in different languages; among them, C, C++, Perl,
9576 Python, PHP, and Java. For a semi-official specification of the
9577 TAP protocol, please refer to the documentation of
9578 @uref{http://search.cpan.org/~petdance/Test-Harness/lib/Test/Harness/TAP.pod,
9579 @samp{Test::Harness::TAP}}.
9581 The most relevant real-world usages of TAP are obviously in the testsuites
9582 of @command{perl} and of many perl modules. Still, also other important
9583 third-party packages, such as @uref{http://git-scm.com/, @command{git}},
9584 use TAP in their testsuite.
9586 @node Use TAP with the Automake test harness
9587 @subsection Use TAP with the Automake test harness
9589 Currently, the TAP driver that comes with Automake requires some by-hand
9590 steps on the developer's part (this situation should hopefully be improved
9591 in future Automake versions). You'll have grab the @file{tap-driver.sh}
9592 script from the Automake distribution by hand, copy it in your source tree,
9593 add a call to @code{AC_PROG_AWK} in @file{configure.ac} to search for a
9594 proper awk program, and use the Automake support for third-party test
9595 drivers to instruct the harness to use the @file{tap-driver.sh} script
9596 and that awk program to run your TAP-producing tests. See the example
9597 below for clarification.
9599 Apart from the options common to all the Automake test drivers
9600 (@pxref{Command-line arguments for test drivers}), the @file{tap-driver.sh}
9601 supports the following options, whose names are chosen for enhanced
9602 compatibility with the @command{prove} utility.
9605 @c Keep in sync with 'tap-exit.test' and 'tap-signal.test'.
9607 Causes the test driver to ignore the exit status of the test scripts;
9608 by default, the driver will report an error if the script exit with a
9609 non-zero status. This option has effect also
9611 Instruct the test driver to display TAP diagnostic (i.e., lines beginning
9612 with the @samp{#} character) in the testsuite progress output too; by
9613 default, TAP diagnostic is only copied in the @file{.log} file.
9615 Revert the effects of @option{--comments}.
9617 Instruct the test driver to merge the test scripts' standard error into
9618 their standard output. This is necessary if you want to ensure that
9619 diagnostics from the test scripts are displayed in the correct order
9620 relative to test results; this can be of great help in debugging
9621 (especially if your test scripts are shell scripts run with shell
9622 tracing active). As a downside, this option might cause the test
9623 harness to get confused if anything that appears on standard error
9624 looks like a test result.
9626 Revert the effects of @option{--merge}.
9627 @item --diagnostic-string=@var{STRING}
9628 Change the string that introduces TAP diagnostic from the default value
9629 of ``@code{#}'' to @code{@var{STRING}}. This can be useful if your
9630 TAP-based test scripts produce verbose output on which they have limited
9631 control (because, say, the output comes by other tools invoked in the
9632 scripts), and it might contain text that gets spuriously interpreted as
9633 TAP diagnostic: such an issue can be solved by redefining the string that
9634 activates TAP diagnostic to a value you know won't appear by chance in
9635 the tests' output. Note however that this feature is non-standard, as
9636 the ``official'' TAP protocol does not allow for such a customization; so
9637 don't use it if you can avoid it.
9641 Here is an example of how the TAP driver can be set up and used.
9643 @c Keep in sync with tap-doc2.test.
9645 % @kbd{cat configure.ac}
9646 AC_INIT([GNU Try Tap], [1.0], [bug-automake@@gnu.org])
9647 AC_CONFIG_AUX_DIR([build-aux])
9648 AM_INIT_AUTOMAKE([foreign parallel-tests -Wall -Werror])
9649 AC_CONFIG_FILES([Makefile])
9650 AC_REQUIRE_AUX_FILE([tap-driver.sh])
9654 % @kbd{cat Makefile.am}
9655 TEST_LOG_DRIVER = env AM_TAP_AWK='$(AWK)' $(SHELL) \
9656 $(top_srcdir)/build-aux/tap-driver.sh
9657 TESTS = foo.test bar.test baz.test
9658 EXTRA_DIST = $(TESTS)
9660 % @kbd{cat foo.test}
9662 echo 1..4 # Number of tests to be executed.
9663 echo 'ok 1 - Swallows fly'
9664 echo 'not ok 2 - Caterpillars fly # TODO metamorphosis in progress'
9665 echo 'ok 3 - Pigs fly # SKIP not enough acid'
9666 echo '# I just love word plays ...'
9667 echo 'ok 4 - Flies fly too :-)'
9669 % @kbd{cat bar.test}
9672 echo 'not ok 1 - Bummer, this test has failed.'
9673 echo 'ok 2 - This passed though.'
9674 echo 'Bail out! Ennui kicking in, sorry...'
9675 echo 'ok 3 - This will not be seen.'
9677 % @kbd{cat baz.test}
9681 # Exit with error, even if all the test case has been successful.
9684 % @kbd{cp @var{PREFIX}/share/automake-@var{APIVERSION}/tap-driver.pl .}
9685 % @kbd{autoreconf -vi && ./configure && make check}
9687 PASS: foo.test 1 - Swallows fly
9688 XFAIL: foo.test 2 - Caterpillars fly # TODO metamorphosis in progress
9689 SKIP: foo.test 3 - Pigs fly # SKIP not enough acid
9690 PASS: foo.test 4 - Flies fly too :-)
9691 FAIL: bar.test 1 - Bummer, this test has failed.
9692 PASS: bar.test 2 - This passed though.
9693 ERROR: bar.test - Bail out! Ennui kicking in, sorry...
9695 ERROR: baz.test - exited with status 7
9697 Please report to bug-automake@@gnu.org
9699 % @kbd{echo exit status: $?}
9702 @c Keep the "skewed" indentation below, it produces pretty PDF output.
9703 % @kbd{env TEST_LOG_DRIVER_FLAGS='--comments --ignore-exit' \
9704 TESTS='foo.test baz.test' make -e check}
9706 PASS: foo.test 1 - Swallows fly
9707 XFAIL: foo.test 2 - Caterpillars fly # TODO metamorphosis in progress
9708 SKIP: foo.test 3 - Pigs fly # SKIP not enough acid
9709 # foo.test: I just love word plays...
9710 PASS: foo.test 4 - Flies fly too :-)
9713 % @kbd{echo exit status: $?}
9717 @node Incompatibilities with other TAP parsers and drivers
9718 @subsection Incompatibilities with other TAP parsers and drivers
9720 For implementation or historical reasons, the TAP driver and harness as
9721 implemented by Automake have some minors incompatibilities with the
9722 mainstream versions, which you should be aware of.
9726 A @code{Bail out!} directive doesn't stop the whole testsuite, but only
9727 the test script it occurs into. This doesn't follows TAP specifications,
9728 but on the other hand it maximizes compatibility (and code sharing) with
9729 the ``hard error'' concept of the default @option{parallel-tests} driver.
9731 The @code{version} and @code{pragma} directives are not supported.
9733 The @option{--diagnostic-string} option of out driver allows to modify
9734 the string that introduces TAP diagnostic from the default value
9735 of ``@code{#}''. The standard TAP protocol has currently no way to
9736 allow this, so if you use it your diagnostic will be lost to more
9737 compliant tools like @command{prove} and @code{Test::Harness}
9739 And there are probably some other small and yet undiscovered
9740 incompatibilities, especially in corner cases or with rare usages.
9743 @node Links and external resources on TAP
9744 @subsection Links and external resources on TAP
9747 Here are some links to more extensive official or third-party
9748 documentation and resources about the TAP protocol and related
9749 tools and libraries.
9752 @uref{http://search.cpan.org/~petdance/Test-Harness/lib/Test/Harness/TAP.pod,
9753 @samp{Test::Harness::TAP}},
9754 the (mostly) official documentation about the TAP format and protocol.
9756 @uref{http://search.cpan.org/~andya/Test-Harness/bin/prove,
9758 the most famous command-line TAP test driver, included in the distribution
9759 of @command{perl} and
9760 @uref{http://search.cpan.org/~andya/Test-Harness/lib/Test/Harness.pm,
9761 @samp{Test::Harness}}.
9763 The @uref{http://testanything.org/wiki/index.php/Main_Page,TAP wiki}.
9765 A ``gentle introduction'' to testing for perl coders:
9766 @uref{http://search.cpan.org/dist/Test-Simple/lib/Test/Tutorial.pod,
9767 @samp{Test::Tutorial}}.
9769 @uref{http://search.cpan.org/~mschwern/Test-Simple/lib/Test/Simple.pm,
9770 @samp{Test::Simple}}
9772 @uref{http://search.cpan.org/~mschwern/Test-Simple/lib/Test/More.pm,
9774 the standard perl testing libraries, which are based on TAP.
9776 @uref{http://www.eyrie.org/~eagle/software/c-tap-harness/,C TAP Harness},
9777 a C-based project implementing both a TAP producer and a TAP consumer.
9779 @uref{http://www.tap4j.org/,tap4j},
9780 a Java-based project implementing both a TAP producer and a TAP consumer.
9784 @section DejaGnu Tests
9786 If @uref{ftp://ftp.gnu.org/gnu/dejagnu/, @command{dejagnu}} appears in
9787 @code{AUTOMAKE_OPTIONS}, then a @command{dejagnu}-based test suite is
9788 assumed. The variable @code{DEJATOOL} is a list of names that are
9789 passed, one at a time, as the @option{--tool} argument to
9790 @command{runtest} invocations; it defaults to the name of the package.
9792 The variable @code{RUNTESTDEFAULTFLAGS} holds the @option{--tool} and
9793 @option{--srcdir} flags that are passed to dejagnu by default; this can be
9794 overridden if necessary.
9795 @vindex RUNTESTDEFAULTFLAGS
9797 The variables @code{EXPECT} and @code{RUNTEST} can
9798 also be overridden to provide project-specific values. For instance,
9799 you will need to do this if you are testing a compiler toolchain,
9800 because the default values do not take into account host and target
9807 The contents of the variable @code{RUNTESTFLAGS} are passed to the
9808 @code{runtest} invocation. This is considered a ``user variable''
9809 (@pxref{User Variables}). If you need to set @command{runtest} flags in
9810 @file{Makefile.am}, you can use @code{AM_RUNTESTFLAGS} instead.
9811 @vindex RUNTESTFLAGS
9812 @vindex AM_RUNTESTFLAGS
9814 @cindex @file{site.exp}
9815 Automake will generate rules to create a local @file{site.exp} file,
9816 defining various variables detected by @command{configure}. This file
9817 is automatically read by DejaGnu. It is OK for the user of a package
9818 to edit this file in order to tune the test suite. However this is
9819 not the place where the test suite author should define new variables:
9820 this should be done elsewhere in the real test suite code.
9821 Especially, @file{site.exp} should not be distributed.
9823 Still, if the package author has legitimate reasons to extend
9824 @file{site.exp} at @command{make} time, he can do so by defining
9825 the variable @code{EXTRA_DEJAGNU_SITE_CONFIG}; the files listed
9826 there will be considered @file{site.exp} prerequisites, and their
9827 content will be appended to it (in the same order in which they
9828 appear in @code{EXTRA_DEJAGNU_SITE_CONFIG}). Note that files are
9829 @emph{not} distributed by default.
9831 For more information regarding DejaGnu test suites, see @ref{Top, , ,
9832 dejagnu, The DejaGnu Manual}.
9835 @section Install Tests
9837 The @code{installcheck} target is available to the user as a way to
9838 run any tests after the package has been installed. You can add tests
9839 to this by writing an @code{installcheck-local} rule.
9843 @chapter Rebuilding Makefiles
9844 @cindex rebuild rules
9846 Automake generates rules to automatically rebuild @file{Makefile}s,
9847 @file{configure}, and other derived files like @file{Makefile.in}.
9849 @acindex AM_MAINTAINER_MODE
9850 If you are using @code{AM_MAINTAINER_MODE} in @file{configure.ac}, then
9851 these automatic rebuilding rules are only enabled in maintainer mode.
9853 @vindex ACLOCAL_AMFLAGS
9854 Sometimes you need to run @command{aclocal} with an argument like
9855 @option{-I} to tell it where to find @file{.m4} files. Since
9856 sometimes @command{make} will automatically run @command{aclocal}, you
9857 need a way to specify these arguments. You can do this by defining
9858 @code{ACLOCAL_AMFLAGS}; this holds arguments that are passed verbatim
9859 to @command{aclocal}. This variable is only useful in the top-level
9862 @vindex CONFIG_STATUS_DEPENDENCIES
9863 @vindex CONFIGURE_DEPENDENCIES
9864 @cindex @file{version.sh}, example
9865 @cindex @file{version.m4}, example
9867 Sometimes it is convenient to supplement the rebuild rules for
9868 @file{configure} or @file{config.status} with additional dependencies.
9869 The variables @code{CONFIGURE_DEPENDENCIES} and
9870 @code{CONFIG_STATUS_DEPENDENCIES} can be used to list these extra
9871 dependencies. These variables should be defined in all
9872 @file{Makefile}s of the tree (because these two rebuild rules are
9873 output in all them), so it is safer and easier to @code{AC_SUBST} them
9874 from @file{configure.ac}. For instance, the following statement will
9875 cause @file{configure} to be rerun each time @file{version.sh} is
9879 AC_SUBST([CONFIG_STATUS_DEPENDENCIES], ['$(top_srcdir)/version.sh'])
9883 Note the @samp{$(top_srcdir)/} in the file name. Since this variable
9884 is to be used in all @file{Makefile}s, its value must be sensible at
9885 any level in the build hierarchy.
9887 Beware not to mistake @code{CONFIGURE_DEPENDENCIES} for
9888 @code{CONFIG_STATUS_DEPENDENCIES}.
9890 @code{CONFIGURE_DEPENDENCIES} adds dependencies to the
9891 @file{configure} rule, whose effect is to run @command{autoconf}. This
9892 variable should be seldom used, because @command{automake} already tracks
9893 @code{m4_include}d files. However it can be useful when playing
9894 tricky games with @code{m4_esyscmd} or similar non-recommendable
9895 macros with side effects.
9897 @code{CONFIG_STATUS_DEPENDENCIES} adds dependencies to the
9898 @file{config.status} rule, whose effect is to run @file{configure}.
9899 This variable should therefore carry any non-standard source that may
9900 be read as a side effect of running @command{configure}, like @file{version.sh}
9901 in the example above.
9903 Speaking of @file{version.sh} scripts, we recommend against them
9904 today. They are mainly used when the version of a package is updated
9905 automatically by a script (e.g., in daily builds). Here is what some
9906 old-style @file{configure.ac}s may look like:
9910 . $srcdir/version.sh
9911 AM_INIT_AUTOMAKE([name], $VERSION_NUMBER)
9916 Here, @file{version.sh} is a shell fragment that sets
9917 @code{VERSION_NUMBER}. The problem with this example is that
9918 @command{automake} cannot track dependencies (listing @file{version.sh}
9919 in @command{CONFIG_STATUS_DEPENDENCIES}, and distributing this file is up
9920 to the user), and that it uses the obsolete form of @code{AC_INIT} and
9921 @code{AM_INIT_AUTOMAKE}. Upgrading to the new syntax is not
9922 straightforward, because shell variables are not allowed in
9923 @code{AC_INIT}'s arguments. We recommend that @file{version.sh} be
9924 replaced by an M4 file that is included by @file{configure.ac}:
9927 m4_include([version.m4])
9928 AC_INIT([name], VERSION_NUMBER)
9934 Here @file{version.m4} could contain something like
9935 @samp{m4_define([VERSION_NUMBER], [1.2])}. The advantage of this
9936 second form is that @command{automake} will take care of the
9937 dependencies when defining the rebuild rule, and will also distribute
9938 the file automatically. An inconvenience is that @command{autoconf}
9939 will now be rerun each time the version number is bumped, when only
9940 @file{configure} had to be rerun in the previous setup.
9944 @chapter Changing Automake's Behavior
9947 * Options generalities:: Semantics of Automake option
9948 * List of Automake options:: A comprehensive list of Automake options
9951 @node Options generalities
9952 @section Options generalities
9954 Various features of Automake can be controlled by options. Except where
9955 noted otherwise, options can be specified in one of several ways. Most
9956 options can be applied on a per-@file{Makefile} basis when listed in a
9957 special @file{Makefile} variable named @code{AUTOMAKE_OPTIONS}. Some
9958 of these options only make sense when specified in the toplevel
9959 @file{Makefile.am} file. Options are applied globally to all processed
9960 @file{Makefile} files when listed in the first argument of
9961 @code{AM_INIT_AUTOMAKE} in @file{configure.ac}, and some options which
9962 require changes to the @command{configure} script can only be specified
9963 there. These are annotated below.
9965 As a general rule, options specified in @code{AUTOMAKE_OPTIONS} take
9966 precedence over those specified in @code{AM_INIT_AUTOMAKE}, which in
9967 turn take precedence over those specified on the command line.
9969 Also, some care must be taken about the interactions among strictness
9970 level and warning categories. As a general rule, strictness-implied
9971 warnings are overridden by those specified by explicit options. For
9972 example, even if @samp{portability} warnings are disabled by default
9973 in @option{foreign} strictness, an usage like this will end up enabling
9977 AUTOMAKE_OPTIONS = -Wportability foreign
9980 However, a strictness level specified in a higher-priority context
9981 will override all the explicit warnings specified in a lower-priority
9982 context. For example, if @file{configure.ac} contains:
9985 AM_INIT_AUTOMAKE([-Wportability])
9989 and @file{Makefile.am} contains:
9992 AUTOMAKE_OPTIONS = foreign
9996 then @samp{portability} warnings will be @emph{disabled} in
9999 @node List of Automake options
10000 @section List of Automake options
10002 @vindex AUTOMAKE_OPTIONS
10005 @item @option{gnits}
10006 @itemx @option{gnu}
10007 @itemx @option{foreign}
10008 @itemx @option{cygnus}
10009 @cindex Option, @option{gnits}
10010 @cindex Option, @option{gnu}
10011 @cindex Option, @option{foreign}
10012 @cindex Option, @option{cygnus}
10018 Set the strictness as appropriate. The @option{gnits} option also
10019 implies options @option{readme-alpha} and @option{check-news}.
10021 @item @option{check-news}
10022 @cindex Option, @option{check-news}
10023 @opindex check-news
10024 Cause @samp{make dist} to fail unless the current version number appears
10025 in the first few lines of the @file{NEWS} file.
10027 @item @option{color-tests}
10028 @cindex Option, @option{color-tests}
10029 @opindex color-tests
10030 Cause output of the serial and parallel test harnesses (see @ref{Simple
10031 Tests}) and of properly-written custom test drivers (@pxref{Custom Test
10032 Drivers}) to be colorized on capable terminals.
10034 @item @option{dejagnu}
10035 @cindex Option, @option{dejagnu}
10037 Cause @command{dejagnu}-specific rules to be generated. @xref{DejaGnu Tests}.
10039 @item @option{dist-bzip2}
10040 @cindex Option, @option{dist-bzip2}
10041 @opindex dist-bzip2
10042 Hook @code{dist-bzip2} to @code{dist}.
10043 @trindex dist-bzip2
10045 @item @option{dist-lzip}
10046 @cindex Option, @option{dist-lzip}
10048 Hook @code{dist-lzip} to @code{dist}.
10051 @item @option{dist-shar}
10052 @cindex Option, @option{dist-shar}
10054 Hook @code{dist-shar} to @code{dist}.
10057 @item @option{dist-zip}
10058 @cindex Option, @option{dist-zip}
10060 Hook @code{dist-zip} to @code{dist}.
10063 @item @option{dist-tarZ}
10064 @cindex Option, @option{dist-tarZ}
10066 Hook @code{dist-tarZ} to @code{dist}.
10069 @item @option{filename-length-max=99}
10070 @cindex Option, @option{filename-length-max=99}
10071 @opindex filename-length-max=99
10072 Abort if file names longer than 99 characters are found during
10073 @samp{make dist}. Such long file names are generally considered not to
10074 be portable in tarballs. See the @option{tar-v7} and @option{tar-ustar}
10075 options below. This option should be used in the top-level
10076 @file{Makefile.am} or as an argument of @code{AM_INIT_AUTOMAKE} in
10077 @file{configure.ac}, it will be ignored otherwise. It will also be
10078 ignored in sub-packages of nested packages (@pxref{Subpackages}).
10080 @item @option{no-define}
10081 @cindex Option, @option{no-define}
10083 This option is meaningful only when passed as an argument to
10084 @code{AM_INIT_AUTOMAKE}. It will prevent the @code{PACKAGE} and
10085 @code{VERSION} variables from being @code{AC_DEFINE}d.
10087 @item @option{no-dependencies}
10088 @cindex Option, @option{no-dependencies}
10089 @opindex no-dependencies
10090 This is similar to using @option{--ignore-deps} on the command line,
10091 but is useful for those situations where you don't have the necessary
10092 bits to make automatic dependency tracking work
10093 (@pxref{Dependencies}). In this case the effect is to effectively
10094 disable automatic dependency tracking.
10096 @item @option{no-dist}
10097 @cindex Option, @option{no-dist}
10099 Don't emit any code related to @code{dist} target. This is useful
10100 when a package has its own method for making distributions.
10102 @item @option{no-dist-gzip}
10103 @cindex Option, @option{no-dist-gzip}
10104 @opindex no-dist-gzip
10105 Do not hook @code{dist-gzip} to @code{dist}.
10106 @trindex no-dist-gzip
10108 @item @option{no-exeext}
10109 @cindex Option, @option{no-exeext}
10111 If your @file{Makefile.am} defines a rule for target @code{foo}, it
10112 will override a rule for a target named @samp{foo$(EXEEXT)}. This is
10113 necessary when @code{EXEEXT} is found to be empty. However, by
10114 default @command{automake} will generate an error for this use. The
10115 @option{no-exeext} option will disable this error. This is intended for
10116 use only where it is known in advance that the package will not be
10117 ported to Windows, or any other operating system using extensions on
10120 @item @option{no-installinfo}
10121 @cindex Option, @option{no-installinfo}
10122 @opindex no-installinfo
10123 The generated @file{Makefile.in} will not cause info pages to be built
10124 or installed by default. However, @code{info} and @code{install-info}
10125 targets will still be available. This option is disallowed at
10126 @option{gnu} strictness and above.
10128 @trindex install-info
10130 @item @option{no-installman}
10131 @cindex Option, @option{no-installman}
10132 @opindex no-installman
10133 The generated @file{Makefile.in} will not cause man pages to be
10134 installed by default. However, an @code{install-man} target will still
10135 be available for optional installation. This option is disallowed at
10136 @option{gnu} strictness and above.
10137 @trindex install-man
10139 @item @option{nostdinc}
10140 @cindex Option, @option{nostdinc}
10142 This option can be used to disable the standard @option{-I} options that
10143 are ordinarily automatically provided by Automake.
10145 @item @option{no-texinfo.tex}
10146 @cindex Option, @option{no-texinfo.tex}
10147 @opindex no-texinfo.tex
10148 Don't require @file{texinfo.tex}, even if there are texinfo files in
10151 @item @option{parallel-tests}
10152 @cindex Option, @option{parallel-tests}
10153 @opindex parallel-tests
10154 Enable test suite harness for @code{TESTS} that can run tests in parallel
10155 (@pxref{Parallel Test Harness}, for more information).
10157 @item @option{serial-tests}
10158 @cindex Option, @option{serial-tests}
10159 @opindex serial-tests
10160 Enable the older serial test suite harness for @code{TESTS} (@pxref{Serial
10161 Test Harness}, for more information). This is still the default for the
10164 @item @option{readme-alpha}
10165 @cindex Option, @option{readme-alpha}
10166 @opindex readme-alpha
10167 If this release is an alpha release, and the file @file{README-alpha}
10168 exists, then it will be added to the distribution. If this option is
10169 given, version numbers are expected to follow one of two forms. The
10170 first form is @samp{@var{major}.@var{minor}.@var{alpha}}, where each
10171 element is a number; the final period and number should be left off for
10172 non-alpha releases. The second form is
10173 @samp{@var{major}.@var{minor}@var{alpha}}, where @var{alpha} is a
10174 letter; it should be omitted for non-alpha releases.
10176 @item @option{silent-rules}
10177 @cindex Option, @option{silent-rules}
10178 @opindex silent-rules
10179 Enable less verbose build rules. This can be used to let build rules
10180 output status lines of the form:
10182 GEN @var{output-file}
10183 CC @var{object-file}
10186 instead of printing the command that will be executed to update
10187 @var{output-file} or to compile @var{object-file}. It can also
10188 silence @command{libtool} output.
10190 For more information about how to use, enable, or disable silent
10191 rules, @pxref{Automake silent-rules Option}.
10193 @item @option{std-options}
10194 @cindex Options, @option{std-options}
10195 @cindex @samp{make installcheck}, testing @option{--help} and @option{--version}
10196 @cindex @option{--help} check
10197 @cindex @option{--version} check
10198 @opindex std-options
10200 Make the @code{installcheck} rule check that installed scripts and
10201 programs support the @option{--help} and @option{--version} options.
10202 This also provides a basic check that the program's
10203 run-time dependencies are satisfied after installation.
10205 @vindex AM_INSTALLCHECK_STD_OPTIONS_EXEMPT
10206 In a few situations, programs (or scripts) have to be exempted from this
10207 test. For instance, @command{false} (from GNU coreutils) is never
10208 successful, even for @option{--help} or @option{--version}. You can list
10209 such programs in the variable @code{AM_INSTALLCHECK_STD_OPTIONS_EXEMPT}.
10210 Programs (not scripts) listed in this variable should be suffixed by
10211 @samp{$(EXEEXT)} for the sake of Windows or OS/2. For instance, suppose we
10212 build @file{false} as a program but @file{true.sh} as a script, and that
10213 neither of them support @option{--help} or @option{--version}:
10216 AUTOMAKE_OPTIONS = std-options
10217 bin_PROGRAMS = false ...
10218 bin_SCRIPTS = true.sh ...
10219 AM_INSTALLCHECK_STD_OPTIONS_EXEMPT = false$(EXEEXT) true.sh
10222 @item @option{subdir-objects}
10223 @cindex Options, @option{subdir-objects}
10224 @opindex subdir-objects
10225 If this option is specified, then objects are placed into the
10226 subdirectory of the build directory corresponding to the subdirectory of
10227 the source file. For instance, if the source file is
10228 @file{subdir/file.cxx}, then the output file would be
10229 @file{subdir/file.o}.
10231 In order to use this option with C sources, you should add
10232 @code{AM_PROG_CC_C_O} to @file{configure.ac}.
10234 @anchor{tar-formats}
10235 @item @option{tar-v7}
10236 @itemx @option{tar-ustar}
10237 @itemx @option{tar-pax}
10238 @cindex Option, @option{tar-v7}
10239 @cindex Option, @option{tar-ustar}
10240 @cindex Option, @option{tar-pax}
10241 @cindex @command{tar} formats
10242 @cindex v7 @command{tar} format
10243 @cindex ustar format
10249 These three mutually exclusive options select the tar format to use
10250 when generating tarballs with @samp{make dist}. (The tar file created
10251 is then compressed according to the set of @option{no-dist-gzip},
10252 @option{dist-bzip2}, @option{dist-lzip}, @option{dist-xz} and
10253 @option{dist-tarZ} options in use.)
10255 These options must be passed as arguments to @code{AM_INIT_AUTOMAKE}
10256 (@pxref{Macros}) because they can require additional configure checks.
10257 Automake will complain if it sees such options in an
10258 @code{AUTOMAKE_OPTIONS} variable.
10260 @option{tar-v7} selects the old V7 tar format. This is the historical
10261 default. This antiquated format is understood by all tar
10262 implementations and supports file names with up to 99 characters. When
10263 given longer file names some tar implementations will diagnose the
10264 problem while other will generate broken tarballs or use non-portable
10265 extensions. Furthermore, the V7 format cannot store empty
10266 directories. When using this format, consider using the
10267 @option{filename-length-max=99} option to catch file names too long.
10269 @option{tar-ustar} selects the ustar format defined by POSIX
10270 1003.1-1988. This format is believed to be old enough to be portable.
10271 It fully supports empty directories. It can store file names with up
10272 to 256 characters, provided that the file name can be split at
10273 directory separator in two parts, first of them being at most 155
10274 bytes long. So, in most cases the maximum file name length will be
10275 shorter than 256 characters. However you may run against broken tar
10276 implementations that incorrectly handle file names longer than 99
10277 characters (please report them to @email{@value{PACKAGE_BUGREPORT}} so we
10278 can document this accurately).
10280 @option{tar-pax} selects the new pax interchange format defined by POSIX
10281 1003.1-2001. It does not limit the length of file names. However,
10282 this format is very young and should probably be restricted to
10283 packages that target only very modern platforms. There are moves to
10284 change the pax format in an upward-compatible way, so this option may
10285 refer to a more recent version in the future.
10287 @xref{Formats, , Controlling the Archive Format, tar, GNU Tar}, for
10288 further discussion about tar formats.
10290 @command{configure} knows several ways to construct these formats. It
10291 will not abort if it cannot find a tool up to the task (so that the
10292 package can still be built), but @samp{make dist} will fail.
10294 @item @var{version}
10295 @cindex Option, @var{version}
10296 A version number (e.g., @samp{0.30}) can be specified. If Automake is not
10297 newer than the version specified, creation of the @file{Makefile.in}
10298 will be suppressed.
10300 @item @option{-W@var{category}} or @option{--warnings=@var{category}}
10301 @cindex Option, warnings
10302 @cindex Option, @option{-W@var{category}}
10303 @cindex Option, @option{--warnings=@var{category}}
10304 These options behave exactly like their command-line counterpart
10305 (@pxref{automake Invocation}). This allows you to enable or disable some
10306 warning categories on a per-file basis. You can also setup some warnings
10307 for your entire project; for instance, try @samp{AM_INIT_AUTOMAKE([-Wall])}
10308 in your @file{configure.ac}.
10312 Unrecognized options are diagnosed by @command{automake}.
10314 If you want an option to apply to all the files in the tree, you can use
10315 the @code{AM_INIT_AUTOMAKE} macro in @file{configure.ac}.
10319 @node Miscellaneous
10320 @chapter Miscellaneous Rules
10322 There are a few rules and variables that didn't fit anywhere else.
10325 * Tags:: Interfacing to cscope, etags and mkid
10326 * Suffixes:: Handling new file extensions
10331 @section Interfacing to @command{etags}
10333 @cindex @file{TAGS} support
10335 Automake will generate rules to generate @file{TAGS} files for use with
10336 GNU Emacs under some circumstances.
10339 If any C, C++ or Fortran 77 source code or headers are present, then
10340 @code{tags} and @code{TAGS} rules will be generated for the directory.
10341 All files listed using the @code{_SOURCES}, @code{_HEADERS}, and
10342 @code{_LISP} primaries will be used to generate tags. Note that
10343 generated source files that are not distributed must be declared in
10344 variables like @code{nodist_noinst_HEADERS} or
10345 @code{nodist_@var{prog}_SOURCES} or they will be ignored.
10347 A @code{tags} rule will be output at the topmost directory of a
10348 multi-directory package. When run from this topmost directory,
10349 @samp{make tags} will generate a @file{TAGS} file that includes by
10350 reference all @file{TAGS} files from subdirectories.
10352 The @code{tags} rule will also be generated if the variable
10353 @code{ETAGS_ARGS} is defined. This variable is intended for use in
10354 directories that contain taggable source that @command{etags} does
10355 not understand. The user can use the @code{ETAGSFLAGS} to pass
10356 additional flags to @command{etags}; @code{AM_ETAGSFLAGS} is also
10357 available for use in @file{Makefile.am}.
10360 @vindex AM_ETAGSFLAGS
10362 Here is how Automake generates tags for its source, and for nodes in its
10366 ETAGS_ARGS = automake.in --lang=none \
10367 --regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi
10370 If you add file names to @code{ETAGS_ARGS}, you will probably also
10371 want to define @code{TAGS_DEPENDENCIES}. The contents of this variable
10372 are added directly to the dependencies for the @code{tags} rule.
10373 @vindex TAGS_DEPENDENCIES
10375 Automake also generates a @code{ctags} rule that can be used to
10376 build @command{vi}-style @file{tags} files. The variable @code{CTAGS}
10377 is the name of the program to invoke (by default @command{ctags});
10378 @code{CTAGSFLAGS} can be used by the user to pass additional flags,
10379 and @code{AM_CTAGSFLAGS} can be used by the @file{Makefile.am}.
10382 Automake will also generate an @code{ID} rule that will run
10383 @command{mkid} on the source. This is only supported on a
10384 directory-by-directory basis.
10386 Similarly, the @code{cscope} rule will create a list of all the source
10387 files in the tree and run @command{cscope} to build an inverted index
10388 database. The variable @code{CSCOPE} is the name of the program to invoke
10389 (by default @command{cscope}); @code{CSCOPEFLAGS} and
10390 @code{CSCOPE_ARGS} can be used by the user to pass additional flags and
10391 file names respectively, while @code{AM_CSCOPEFLAGS} can be used by the
10392 @file{Makefile.am}. Note that, currently, the Automake-provided
10393 @code{cscope} support, when used in a VPATH build, might not work well
10394 with non-GNU make implementations (especially with make implementations
10395 performing @ref{Automatic Rule Rewriting, , VPATH rewrites, autoconf,
10396 The Autoconf Manual}).
10398 Finally, Automake also emits rules to support the
10399 @uref{http://www.gnu.org/software/global/, GNU Global Tags program}.
10400 The @code{GTAGS} rule runs Global Tags and puts the
10401 result in the top build directory. The variable @code{GTAGS_ARGS}
10402 holds arguments that are passed to @command{gtags}.
10407 @section Handling new file extensions
10409 @cindex Adding new @code{SUFFIXES}
10410 @cindex @code{SUFFIXES}, adding
10413 It is sometimes useful to introduce a new implicit rule to handle a file
10414 type that Automake does not know about.
10416 For instance, suppose you had a compiler that could compile @file{.foo}
10417 files to @file{.o} files. You would simply define a suffix rule for
10425 Then you could directly use a @file{.foo} file in a @code{_SOURCES}
10426 variable and expect the correct results:
10429 bin_PROGRAMS = doit
10430 doit_SOURCES = doit.foo
10433 This was the simpler and more common case. In other cases, you will
10434 have to help Automake to figure out which extensions you are defining your
10435 suffix rule for. This usually happens when your extension does not
10436 start with a dot. Then, all you have to do is to put a list of new
10437 suffixes in the @code{SUFFIXES} variable @strong{before} you define your
10440 For instance, the following definition prevents Automake from misinterpreting
10441 the @samp{.idlC.cpp:} rule as an attempt to transform @file{.idlC} files into
10444 @c Keep in sync with suffix7.test.
10446 SUFFIXES = .idl C.cpp
10451 As you may have noted, the @code{SUFFIXES} variable behaves like the
10452 @code{.SUFFIXES} special target of @command{make}. You should not touch
10453 @code{.SUFFIXES} yourself, but use @code{SUFFIXES} instead and let
10454 Automake generate the suffix list for @code{.SUFFIXES}. Any given
10455 @code{SUFFIXES} go at the start of the generated suffixes list, followed
10456 by Automake generated suffixes not already in the list.
10462 @cindex Including @file{Makefile} fragment
10463 @cindex @file{Makefile} fragment, including
10465 Automake supports an @code{include} directive that can be used to
10466 include other @file{Makefile} fragments when @command{automake} is run.
10467 Note that these fragments are read and interpreted by @command{automake},
10468 not by @command{make}. As with conditionals, @command{make} has no idea that
10469 @code{include} is in use.
10471 There are two forms of @code{include}:
10474 @item include $(srcdir)/file
10475 Include a fragment that is found relative to the current source
10478 @item include $(top_srcdir)/file
10479 Include a fragment that is found relative to the top source directory.
10482 Note that if a fragment is included inside a conditional, then the
10483 condition applies to the entire contents of that fragment.
10485 Makefile fragments included this way are always distributed because
10486 they are needed to rebuild @file{Makefile.in}.
10489 @chapter Conditionals
10491 @cindex Conditionals
10493 Automake supports a simple type of conditionals.
10495 These conditionals are not the same as conditionals in
10496 GNU Make. Automake conditionals are checked at configure time by the
10497 @file{configure} script, and affect the translation from
10498 @file{Makefile.in} to @file{Makefile}. They are based on options passed
10499 to @file{configure} and on results that @file{configure} has discovered
10500 about the host system. GNU Make conditionals are checked at @command{make}
10501 time, and are based on variables passed to the make program or defined
10502 in the @file{Makefile}.
10504 Automake conditionals will work with any make program.
10507 * Usage of Conditionals:: Declaring conditional content
10508 * Limits of Conditionals:: Enclosing complete statements
10511 @node Usage of Conditionals
10512 @section Usage of Conditionals
10514 @acindex AM_CONDITIONAL
10515 Before using a conditional, you must define it by using
10516 @code{AM_CONDITIONAL} in the @file{configure.ac} file (@pxref{Macros}).
10518 @defmac AM_CONDITIONAL (@var{conditional}, @var{condition})
10519 The conditional name, @var{conditional}, should be a simple string
10520 starting with a letter and containing only letters, digits, and
10521 underscores. It must be different from @samp{TRUE} and @samp{FALSE}
10522 that are reserved by Automake.
10524 The shell @var{condition} (suitable for use in a shell @code{if}
10525 statement) is evaluated when @command{configure} is run. Note that you
10526 must arrange for @emph{every} @code{AM_CONDITIONAL} to be invoked every
10527 time @command{configure} is run. If @code{AM_CONDITIONAL} is run
10528 conditionally (e.g., in a shell @code{if} statement), then the result
10529 will confuse @command{automake}.
10532 @cindex @option{--enable-debug}, example
10533 @cindex Example conditional @option{--enable-debug}
10534 @cindex Conditional example, @option{--enable-debug}
10536 Conditionals typically depend upon options that the user provides to
10537 the @command{configure} script. Here is an example of how to write a
10538 conditional that is true if the user uses the @option{--enable-debug}
10542 AC_ARG_ENABLE([debug],
10543 [ --enable-debug Turn on debugging],
10544 [case "$@{enableval@}" in
10547 *) AC_MSG_ERROR([bad value $@{enableval@} for --enable-debug]) ;;
10548 esac],[debug=false])
10549 AM_CONDITIONAL([DEBUG], [test x$debug = xtrue])
10552 Here is an example of how to use that conditional in @file{Makefile.am}:
10564 noinst_PROGRAMS = $(DBG)
10567 This trivial example could also be handled using @code{EXTRA_PROGRAMS}
10568 (@pxref{Conditional Programs}).
10570 You may only test a single variable in an @code{if} statement, possibly
10571 negated using @samp{!}. The @code{else} statement may be omitted.
10572 Conditionals may be nested to any depth. You may specify an argument to
10573 @code{else} in which case it must be the negation of the condition used
10574 for the current @code{if}. Similarly you may specify the condition
10575 that is closed on the @code{endif} line:
10586 Unbalanced conditions are errors. The @code{if}, @code{else}, and
10587 @code{endif} statements should not be indented, i.e., start on column
10590 The @code{else} branch of the above two examples could be omitted,
10591 since assigning the empty string to an otherwise undefined variable
10592 makes no difference.
10594 @acindex AM_COND_IF
10595 In order to allow access to the condition registered by
10596 @code{AM_CONDITIONAL} inside @file{configure.ac}, and to allow
10597 conditional @code{AC_CONFIG_FILES}, @code{AM_COND_IF} may be used:
10599 @defmac AM_COND_IF (@var{conditional}, @ovar{if-true}, @ovar{if-false})
10600 If @var{conditional} is fulfilled, execute @var{if-true}, otherwise
10601 execute @var{if-false}. If either branch contains @code{AC_CONFIG_FILES},
10602 it will cause @command{automake} to output the rules for the respective
10603 files only for the given condition.
10606 @code{AM_COND_IF} macros may be nested when m4 quotation is used
10607 properly (@pxref{M4 Quotation, ,, autoconf, The Autoconf Manual}).
10609 @cindex Example conditional @code{AC_CONFIG_FILES}
10610 @cindex @code{AC_CONFIG_FILES}, conditional
10612 Here is an example of how to define a conditional config file:
10615 AM_CONDITIONAL([SHELL_WRAPPER], [test "x$with_wrapper" = xtrue])
10616 AM_COND_IF([SHELL_WRAPPER],
10617 [AC_CONFIG_FILES([wrapper:wrapper.in])])
10620 @node Limits of Conditionals
10621 @section Limits of Conditionals
10623 Conditionals should enclose complete statements like variables or
10624 rules definitions. Automake cannot deal with conditionals used inside
10625 a variable definition, for instance, and is not even able to diagnose
10626 this situation. The following example would not work:
10629 # This syntax is not understood by Automake
10638 However the intended definition of @code{AM_CPPFLAGS} can be achieved
10643 DEBUGFLAGS = -DDEBUG
10645 AM_CPPFLAGS = -DFEATURE_A $(DEBUGFLAGS) -DFEATURE_B
10652 AM_CPPFLAGS = -DFEATURE_A
10654 AM_CPPFLAGS += -DDEBUG
10656 AM_CPPFLAGS += -DFEATURE_B
10659 More details and examples of conditionals are described alongside
10660 various Automake features in this manual (@pxref{Conditional
10661 Subdirectories}, @pxref{Conditional Sources}, @pxref{Conditional
10662 Programs}, @pxref{Conditional Libtool Libraries}, @pxref{Conditional
10665 @node Silencing Make
10666 @chapter Silencing @command{make}
10668 @cindex Silent @command{make}
10669 @cindex Silencing @command{make}
10670 @cindex Silent rules
10671 @cindex Silent @command{make} rules
10674 * Make verbosity:: Make is verbose by default
10675 * Tricks For Silencing Make:: Standard and generic ways to silence make
10676 * Automake silent-rules Option:: How Automake can help in silencing make
10679 @node Make verbosity
10680 @section Make is verbose by default
10682 Normally, when executing the set of rules associated with a target,
10683 @command{make} prints each rule before it is executed. This behaviour,
10684 while having been in place for a long time, and being even mandated by
10685 the POSIX standard, starkly violates the ``silence is golden'' UNIX
10686 principle@footnote{See also
10687 @uref{http://catb.org/~esr/writings/taoup/html/ch11s09.html}.}:
10690 When a program has nothing interesting or surprising to say, it should
10691 say nothing. Well-behaved Unix programs do their jobs unobtrusively,
10692 with a minimum of fuss and bother. Silence is golden.
10695 In fact, while such verbosity of @command{make} can theoretically be
10696 useful to track bugs and understand reasons of failures right away, it
10697 can also hide warning and error messages from @command{make}-invoked
10698 tools, drowning them in a flood of uninteresting and seldom useful
10699 messages, and thus allowing them to go easily undetected.
10701 This problem can be very annoying, especially for developers, who usually
10702 know quite well what's going on behind the scenes, and for whom the
10703 verbose output from @command{make} ends up being mostly noise that hampers
10704 the easy detection of potentially important warning messages.
10706 @node Tricks For Silencing Make
10707 @section Standard and generic ways to silence make
10709 Here we describe some common idioms/tricks to obtain a quieter make
10710 output, with their relative advantages and drawbacks. In the next
10711 section (@ref{Automake silent-rules Option}) we'll see how Automake
10712 can help in this respect.
10716 @item @command{make -s}
10718 This simply causes @command{make} not to print @emph{any} rule before
10721 The @option{-s} flag is mandated by POSIX, universally supported, and
10722 its purpose and function are easy to understand.
10724 But it also has its serious limitations too. First of all, it embodies
10725 an ``all or nothing'' strategy, i.e., either everything is silenced, or
10726 nothing is; this lack of granularity can sometimes be a fatal flaw.
10727 Moreover, when the @option{-s} flag is used, the @command{make} output
10728 might turn out to be too much terse; in case of errors, the user won't
10729 be able to easily see what rule or command have caused them, or even,
10730 in case of tools with poor error reporting, what the errors were!
10732 @item @command{make >/dev/null || make}
10734 Apparently, this perfectly obeys the ``silence is golden'' rule: warnings
10735 from stderr are passed through, output reporting is done only in case of
10736 error, and in that case it should provide a verbose-enough report to allow
10737 an easy determination of the error location and causes.
10739 However, calling @command{make} two times in a row might hide errors
10740 (especially intermittent ones), or subtly change the expected semantic
10741 of the @command{make} calls --- things these which can clearly make
10742 debugging and error assessment very difficult.
10744 @item @command{make --no-print-directory}
10746 This is GNU @command{make} specific. When called with the
10747 @option{--no-print-directory} option, GNU @command{make} will disable
10748 printing of the working directory by invoked sub-@command{make}s (the
10749 well-known ``@i{Entering/Leaving directory ...}'' messages). This helps
10750 to decrease the verbosity of the output, but experience has shown that
10751 it can also often render debugging considerably harder in projects using
10752 deeply-nested @command{make} recursion.
10754 As an aside, notice that the @option{--no-print-directory} option is
10755 automatically activated if the @option{-s} flag is used.
10757 @c TODO: Other tricks?
10758 @c TODO: Maybe speak about the @code{.SILENT} target?
10759 @c TODO: - Pros: More granularity on what to silence.
10760 @c TODO: - Cons: No easy way to temporarily override.
10764 @node Automake silent-rules Option
10765 @section How Automake can help in silencing make
10767 The tricks and idioms for silencing @command{make} described in the
10768 previous section can be useful from time to time, but we've seen that
10769 they all have their serious drawbacks and limitations. That's why
10770 automake provides support for a more advanced and flexible way of
10771 obtaining quieter output from @command{make}: the @option{silent-rules}
10774 @c TODO: Maybe describe in brief the precedent set by the build system
10775 @c of the Linux Kernel, from which Automake took inspiration ... Links?
10777 To give the gist of what @option{silent-rules} can do, here is a simple
10778 comparison between a typical @command{make} output (where silent rules
10779 are disabled) and one with silent rules enabled:
10782 % @kbd{cat Makefile.am}
10784 foo_SOURCES = main.c func.c
10786 int main (void) @{ return func (); @} /* func used undeclared */
10788 int func (void) @{ int i; return i; @} /* i used uninitialized */
10790 @i{The make output is by default very verbose. This causes warnings
10791 from the compiler to be somewhat hidden, and not immediate to spot.}
10792 % @kbd{make CFLAGS=-Wall}
10793 gcc -DPACKAGE_NAME=\"foo\" -DPACKAGE_TARNAME=\"foo\" ...
10794 -DPACKAGE_STRING=\"foo\ 1.0\" -DPACKAGE_BUGREPORT=\"\" ...
10795 -DPACKAGE=\"foo\" -DVERSION=\"1.0\" -I. -Wall -MT main.o
10796 -MD -MP -MF .deps/main.Tpo -c -o main.o main.c
10797 main.c: In function ‘main’:
10798 main.c:3:3: warning: implicit declaration of function ‘func’
10799 mv -f .deps/main.Tpo .deps/main.Po
10800 gcc -DPACKAGE_NAME=\"foo\" -DPACKAGE_TARNAME=\"foo\" ...
10801 -DPACKAGE_STRING=\"foo\ 1.0\" -DPACKAGE_BUGREPORT=\"\" ...
10802 -DPACKAGE=\"foo\" -DVERSION=\"1.0\" -I. -Wall -MT func.o
10803 -MD -MP -MF .deps/func.Tpo -c -o func.o func.c
10804 func.c: In function ‘func’:
10805 func.c:4:3: warning: ‘i’ used uninitialized in this function
10806 mv -f .deps/func.Tpo .deps/func.Po
10807 gcc -Wall -o foo main.o func.o
10809 @i{Clean up, so that we we can rebuild everything from scratch.}
10811 test -z "foo" || rm -f foo
10814 @i{Silent rules enabled: the output is minimal but informative. In
10815 particular, the warnings from the compiler stick out very clearly.}
10816 % @kbd{make V=0 CFLAGS=-Wall}
10818 main.c: In function ‘main’:
10819 main.c:3:3: warning: implicit declaration of function ‘func’
10821 func.c: In function ‘func’:
10822 func.c:4:3: warning: ‘i’ used uninitialized in this function
10826 @cindex silent-rules and libtool
10827 Also, in projects using @command{libtool}, the use of silent rules can
10828 automatically enable the @command{libtool}'s @option{--silent} option:
10831 % @kbd{cat Makefile.am}
10832 lib_LTLIBRARIES = libx.la
10834 % @kbd{make # Both make and libtool are verbose by default.}
10836 libtool: compile: gcc -DPACKAGE_NAME=\"foo\" ... -DLT_OBJDIR=\".libs/\"
10837 -I. -g -O2 -MT libx.lo -MD -MP -MF .deps/libx.Tpo -c libx.c -fPIC
10838 -DPIC -o .libs/libx.o
10839 mv -f .deps/libx.Tpo .deps/libx.Plo
10840 /bin/sh ./libtool --tag=CC --mode=link gcc -g -O2 -o libx.la -rpath
10841 /usr/local/lib libx.lo
10842 libtool: link: gcc -shared .libs/libx.o -Wl,-soname -Wl,libx.so.0
10843 -o .libs/libx.so.0.0.0
10844 libtool: link: cd .libs && rm -f libx.so && ln -s libx.so.0.0.0 libx.so
10852 Let's now see how the @option{silent-rules} mode interfaces with the
10853 package developer and the package user.
10855 To enable the use of @option{silent-rules} in his package, a developer
10856 needs to do either of the following:
10860 Add the @option{silent-rules} option as argument to @code{AM_INIT_AUTOMAKE}.
10862 Call the @code{AM_SILENT_RULES} macro from within the @file{configure.ac}
10866 It is not possible to instead specify @option{silent-rules} in a
10867 @file{Makefile.am} file.
10869 If the developer has done either of the above, then the user of the
10870 package may influence the verbosity at @command{configure} run time as
10871 well as at @command{make} run time:
10875 @opindex --enable-silent-rules
10876 @opindex --disable-silent-rules
10877 Passing @option{--enable-silent-rules} to @command{configure} will cause
10878 build rules to be less verbose; the option @option{--disable-silent-rules}
10879 will cause normal verbose output.
10882 At @command{make} run time, the default chosen at @command{configure}
10883 time may be overridden: @code{make V=1} will produce verbose output,
10884 @code{make V=0} less verbose output.
10887 @cindex default verbosity for silent-rules
10888 Note that silent rules are @emph{disabled} by default; the user must
10889 enable them explicitly at either @command{configure} run time or at
10890 @command{make} run time. We think that this is a good policy, since
10891 it provides the casual user with enough information to prepare a good
10892 bug report in case anything breaks.
10894 Still, notwithstanding the rationales above, a developer who wants to
10895 make silent rules enabled by default in his own package can do so by
10896 adding a @samp{yes} argument to the @code{AM_SILENT_RULES} call in
10897 @file{configure.ac}. We advise against this approach, though.
10899 @c Keep in sync with silent-configsite.test
10900 Users who prefer to have silent rules enabled by default can edit their
10901 @file{config.site} file to make the variable @code{enable_silent_rules}
10902 default to @samp{yes}. This should still allow disabling silent rules
10903 at @command{configure} time and at @command{make} time.
10905 @c FIXME: there's really a need to specify this explicitly?
10906 For portability to different @command{make} implementations, package authors
10907 are advised to not set the variable @code{V} inside the @file{Makefile.am}
10908 file, to allow the user to override the value for subdirectories as well.
10910 The current implementation of this feature normally uses nested
10911 variable expansion @samp{$(@var{var1}$(V))}, a @file{Makefile} feature
10912 that is not required by POSIX 2008 but is widely supported in
10913 practice. The @option{silent-rules} option thus turns off warnings
10914 about recursive variable expansion, which are in turn enabled by
10915 @option{-Wportability} (@pxref{automake Invocation}). On the rare
10916 @command{make} implementations that do not support nested variable
10917 expansion, whether rules are silent is always determined at configure
10918 time, and cannot be overridden at make time. Future versions of POSIX
10919 are likely to require nested variable expansion, so this minor
10920 limitation should go away with time.
10922 @vindex @code{AM_V_GEN}
10923 @vindex @code{AM_V_at}
10924 @vindex @code{AM_DEFAULT_VERBOSITY}
10925 @vindex @code{AM_V}
10926 @vindex @code{AM_DEFAULT_V}
10927 To extend the silent mode to your own rules, you have two choices:
10931 You can use the predefined variable @code{AM_V_GEN} as a prefix to
10932 commands that should output a status line in silent mode, and
10933 @code{AM_V_at} as a prefix to commands that should not output anything
10934 in silent mode. When output is to be verbose, both of these variables
10935 will expand to the empty string.
10937 You can add your own variables, so strings of your own choice are shown.
10938 The following snippet shows how you would define your own equivalent of
10942 pkg_verbose = $(pkg_verbose_@@AM_V@@)
10943 pkg_verbose_ = $(pkg_verbose_@@AM_DEFAULT_V@@)
10944 pkg_verbose_0 = @@echo PKG-GEN $@@;
10947 $(pkg_verbose)cp $(srcdir)/foo.in $@@
10952 As a final note, observe that, even when silent rules are enabled,
10953 the @option{--no-print-directory} option is still required with GNU
10954 @command{make} if the ``@i{Entering/Leaving directory ...}'' messages
10955 are to be disabled.
10958 @chapter The effect of @option{--gnu} and @option{--gnits}
10960 @cindex @option{--gnu}, required files
10961 @cindex @option{--gnu}, complete description
10963 The @option{--gnu} option (or @option{gnu} in the
10964 @code{AUTOMAKE_OPTIONS} variable) causes @command{automake} to check
10969 The files @file{INSTALL}, @file{NEWS}, @file{README}, @file{AUTHORS},
10970 and @file{ChangeLog}, plus one of @file{COPYING.LIB}, @file{COPYING.LESSER}
10971 or @file{COPYING}, are required at the topmost directory of the package.
10973 If the @option{--add-missing} option is given, @command{automake} will
10974 add a generic version of the @file{INSTALL} file as well as the
10975 @file{COPYING} file containing the text of the current version of the
10976 GNU General Public License existing at the time of this Automake release
10977 (version 3 as this is written, @uref{http://www.gnu.org/@/copyleft/@/gpl.html}).
10978 However, an existing @file{COPYING} file will never be overwritten by
10979 @command{automake}.
10982 The options @option{no-installman} and @option{no-installinfo} are
10986 Note that this option will be extended in the future to do even more
10987 checking; it is advisable to be familiar with the precise requirements
10988 of the GNU standards. Also, @option{--gnu} can require certain
10989 non-standard GNU programs to exist for use by various maintainer-only
10990 rules; for instance, in the future @command{pathchk} might be required for
10993 @cindex @option{--gnits}, complete description
10995 The @option{--gnits} option does everything that @option{--gnu} does, and
10996 checks the following as well:
11000 @samp{make installcheck} will check to make sure that the @option{--help}
11001 and @option{--version} really print a usage message and a version string,
11002 respectively. This is the @option{std-options} option (@pxref{Options}).
11005 @samp{make dist} will check to make sure the @file{NEWS} file has been
11006 updated to the current version.
11009 @code{VERSION} is checked to make sure its format complies with Gnits
11011 @c FIXME xref when standards are finished
11014 @cindex @file{README-alpha}
11015 If @code{VERSION} indicates that this is an alpha release, and the file
11016 @file{README-alpha} appears in the topmost directory of a package, then
11017 it is included in the distribution. This is done in @option{--gnits}
11018 mode, and no other, because this mode is the only one where version
11019 number formats are constrained, and hence the only mode where Automake
11020 can automatically determine whether @file{README-alpha} should be
11024 The file @file{THANKS} is required.
11029 @chapter The effect of @option{--cygnus}
11031 @cindex @option{cygnus} strictness
11033 Some packages, notably GNU GCC and GNU gdb, have a build environment
11034 originally written at Cygnus Support (subsequently renamed Cygnus
11035 Solutions, and then later purchased by Red Hat). Packages with this
11036 ancestry are sometimes referred to as ``Cygnus'' trees.
11038 A Cygnus tree has slightly different rules for how a
11039 @file{Makefile.in} is to be constructed. Passing @option{--cygnus} to
11040 @command{automake} will cause any generated @file{Makefile.in} to
11041 comply with Cygnus rules.
11043 Here are the precise effects of @option{--cygnus}:
11047 Info files are always created in the build directory, and not in the
11051 @file{texinfo.tex} is not required if a Texinfo source file is
11052 specified. The assumption is that the file will be supplied, but in a
11053 place that Automake cannot find. This assumption is an artifact of how
11054 Cygnus packages are typically bundled.
11057 @samp{make dist} is not supported, and the rules for it are not
11058 generated. Cygnus-style trees use their own distribution mechanism.
11061 Certain tools will be searched for in the build tree as well as in the
11062 user's @env{PATH}. These tools are @command{runtest}, @command{expect},
11063 @command{makeinfo} and @command{texi2dvi}.
11066 @option{--foreign} is implied.
11069 The options @option{no-installinfo} and @option{no-dependencies} are
11073 The macro @code{AM_MAINTAINER_MODE} is required.
11076 The @code{check} target doesn't depend on @code{all}.
11079 GNU maintainers are advised to use @option{gnu} strictness in preference
11080 to the special Cygnus mode. Some day, perhaps, the differences between
11081 Cygnus trees and GNU trees will disappear (for instance, as GCC is made
11082 more standards compliant). At that time the special Cygnus mode will be
11087 @chapter When Automake Isn't Enough
11089 In some situations, where Automake is not up to one task, one has to
11090 resort to handwritten rules or even handwritten @file{Makefile}s.
11093 * Extending:: Adding new rules or overriding existing ones.
11094 * Third-Party Makefiles:: Integrating Non-Automake @file{Makefile}s.
11098 @section Extending Automake Rules
11100 With some minor exceptions (for example @code{_PROGRAMS} variables,
11101 @code{TESTS}, or @code{XFAIL_TESTS}) being rewritten to append
11102 @samp{$(EXEEXT)}), the contents of a @file{Makefile.am} is copied to
11103 @file{Makefile.in} verbatim.
11105 @cindex copying semantics
11107 These copying semantics mean that many problems can be worked around
11108 by simply adding some @command{make} variables and rules to
11109 @file{Makefile.am}. Automake will ignore these additions.
11111 @cindex conflicting definitions
11112 @cindex rules, conflicting
11113 @cindex variables, conflicting
11114 @cindex definitions, conflicts
11116 Since a @file{Makefile.in} is built from data gathered from three
11117 different places (@file{Makefile.am}, @file{configure.ac}, and
11118 @command{automake} itself), it is possible to have conflicting
11119 definitions of rules or variables. When building @file{Makefile.in}
11120 the following priorities are respected by @command{automake} to ensure
11121 the user always has the last word:
11125 User defined variables in @file{Makefile.am} have priority over
11126 variables @code{AC_SUBST}ed from @file{configure.ac}, and
11127 @code{AC_SUBST}ed variables have priority over
11128 @command{automake}-defined variables.
11130 As far as rules are concerned, a user-defined rule overrides any
11131 @command{automake}-defined rule for the same target.
11134 @cindex overriding rules
11135 @cindex overriding semantics
11136 @cindex rules, overriding
11138 These overriding semantics make it possible to fine tune some default
11139 settings of Automake, or replace some of its rules. Overriding
11140 Automake rules is often inadvisable, particularly in the topmost
11141 directory of a package with subdirectories. The @option{-Woverride}
11142 option (@pxref{automake Invocation}) comes in handy to catch overridden
11145 Note that Automake does not make any distinction between rules with
11146 commands and rules that only specify dependencies. So it is not
11147 possible to append new dependencies to an @command{automake}-defined
11148 target without redefining the entire rule.
11150 @cindex @option{-local} targets
11151 @cindex local targets
11153 However, various useful targets have a @samp{-local} version you can
11154 specify in your @file{Makefile.am}. Automake will supplement the
11155 standard target with these user-supplied targets.
11160 @trindex info-local
11168 @trindex html-local
11170 @trindex check-local
11172 @trindex install-data
11173 @trindex install-data-local
11174 @trindex install-dvi
11175 @trindex install-dvi-local
11176 @trindex install-exec
11177 @trindex install-exec-local
11178 @trindex install-html
11179 @trindex install-html-local
11180 @trindex install-info
11181 @trindex install-info-local
11182 @trindex install-pdf
11183 @trindex install-pdf-local
11184 @trindex install-ps
11185 @trindex install-ps-local
11187 @trindex uninstall-local
11188 @trindex mostlyclean
11189 @trindex mostlyclean-local
11191 @trindex clean-local
11193 @trindex distclean-local
11194 @trindex installdirs
11195 @trindex installdirs-local
11196 @trindex installcheck
11197 @trindex installcheck-local
11199 The targets that support a local version are @code{all}, @code{info},
11200 @code{dvi}, @code{ps}, @code{pdf}, @code{html}, @code{check},
11201 @code{install-data}, @code{install-dvi}, @code{install-exec},
11202 @code{install-html}, @code{install-info}, @code{install-pdf},
11203 @code{install-ps}, @code{uninstall}, @code{installdirs},
11204 @code{installcheck} and the various @code{clean} targets
11205 (@code{mostlyclean}, @code{clean}, @code{distclean}, and
11206 @code{maintainer-clean}).
11208 Note that there are no @code{uninstall-exec-local} or
11209 @code{uninstall-data-local} targets; just use @code{uninstall-local}.
11210 It doesn't make sense to uninstall just data or just executables.
11212 For instance, here is one way to erase a subdirectory during
11213 @samp{make clean} (@pxref{Clean}).
11220 You may be tempted to use @code{install-data-local} to install a file
11221 to some hard-coded location, but you should avoid this
11222 (@pxref{Hard-Coded Install Paths}).
11224 With the @code{-local} targets, there is no particular guarantee of
11225 execution order; typically, they are run early, but with parallel
11226 make, there is no way to be sure of that.
11228 @cindex @option{-hook} targets
11229 @cindex hook targets
11230 @trindex install-data-hook
11231 @trindex install-exec-hook
11232 @trindex uninstall-hook
11235 In contrast, some rules also have a way to run another rule, called a
11236 @dfn{hook}; hooks are always executed after the main rule's work is done.
11237 The hook is named after the principal target, with @samp{-hook} appended.
11238 The targets allowing hooks are @code{install-data},
11239 @code{install-exec}, @code{uninstall}, @code{dist}, and
11242 For instance, here is how to create a hard link to an installed program:
11246 ln $(DESTDIR)$(bindir)/program$(EXEEXT) \
11247 $(DESTDIR)$(bindir)/proglink$(EXEEXT)
11250 Although cheaper and more portable than symbolic links, hard links
11251 will not work everywhere (for instance, OS/2 does not have
11252 @command{ln}). Ideally you should fall back to @samp{cp -p} when
11253 @command{ln} does not work. An easy way, if symbolic links are
11254 acceptable to you, is to add @code{AC_PROG_LN_S} to
11255 @file{configure.ac} (@pxref{Particular Programs, , Particular Program
11256 Checks, autoconf, The Autoconf Manual}) and use @samp{$(LN_S)} in
11257 @file{Makefile.am}.
11259 @cindex versioned binaries, installing
11260 @cindex installing versioned binaries
11261 @cindex @code{LN_S} example
11262 For instance, here is how you could install a versioned copy of a
11263 program using @samp{$(LN_S)}:
11265 @c Keep in sync with insthook.test
11268 cd $(DESTDIR)$(bindir) && \
11269 mv -f prog$(EXEEXT) prog-$(VERSION)$(EXEEXT) && \
11270 $(LN_S) prog-$(VERSION)$(EXEEXT) prog$(EXEEXT)
11273 Note that we rename the program so that a new version will erase the
11274 symbolic link, not the real binary. Also we @command{cd} into the
11275 destination directory in order to create relative links.
11277 When writing @code{install-exec-hook} or @code{install-data-hook},
11278 please bear in mind that the exec/data distinction is based on the
11279 installation directory, not on the primary used (@pxref{The Two Parts of
11281 @c Keep in sync with primary-prefix-couples-documented-valid.test.
11282 So a @code{foo_SCRIPTS} will be installed by
11283 @code{install-data}, and a @code{barexec_SCRIPTS} will be installed by
11284 @code{install-exec}. You should define your hooks consequently.
11286 @c FIXME should include discussion of variables you can use in these
11289 @node Third-Party Makefiles
11290 @section Third-Party @file{Makefile}s
11292 @cindex Third-party packages, interfacing with
11293 @cindex Interfacing with third-party packages
11295 In most projects all @file{Makefile}s are generated by Automake. In
11296 some cases, however, projects need to embed subdirectories with
11297 handwritten @file{Makefile}s. For instance, one subdirectory could be
11298 a third-party project with its own build system, not using Automake.
11300 It is possible to list arbitrary directories in @code{SUBDIRS} or
11301 @code{DIST_SUBDIRS} provided each of these directories has a
11302 @file{Makefile} that recognizes all the following recursive targets.
11304 @cindex recursive targets and third-party @file{Makefile}s
11305 When a user runs one of these targets, that target is run recursively
11306 in all subdirectories. This is why it is important that even
11307 third-party @file{Makefile}s support them.
11311 Compile the entire package. This is the default target in
11312 Automake-generated @file{Makefile}s, but it does not need to be the
11313 default in third-party @file{Makefile}s.
11318 @vindex top_distdir
11319 Copy files to distribute into @samp{$(distdir)}, before a tarball is
11320 constructed. Of course this target is not required if the
11321 @option{no-dist} option (@pxref{Options}) is used.
11323 The variables @samp{$(top_distdir)} and @samp{$(distdir)}
11324 (@pxref{The dist Hook}) will be passed from the outer package to the subpackage
11325 when the @code{distdir} target is invoked. These two variables have
11326 been adjusted for the directory that is being recursed into, so they
11330 @itemx install-data
11331 @itemx install-exec
11333 Install or uninstall files (@pxref{Install}).
11336 @itemx install-html
11337 @itemx install-info
11340 Install only some specific documentation format (@pxref{Texinfo}).
11343 Create install directories, but do not install any files.
11346 @itemx installcheck
11347 Check the package (@pxref{Tests}).
11352 @itemx maintainer-clean
11353 Cleaning rules (@pxref{Clean}).
11360 Build the documentation in various formats (@pxref{Texinfo}).
11364 Build @file{TAGS} and @file{CTAGS} (@pxref{Tags}).
11367 If you have ever used Gettext in a project, this is a good example of
11368 how third-party @file{Makefile}s can be used with Automake. The
11369 @file{Makefile}s @command{gettextize} puts in the @file{po/} and
11370 @file{intl/} directories are handwritten @file{Makefile}s that
11371 implement all these targets. That way they can be added to
11372 @code{SUBDIRS} in Automake packages.
11374 Directories that are only listed in @code{DIST_SUBDIRS} but not in
11375 @code{SUBDIRS} need only the @code{distclean},
11376 @code{maintainer-clean}, and @code{distdir} rules (@pxref{Conditional
11379 Usually, many of these rules are irrelevant to the third-party
11380 subproject, but they are required for the whole package to work. It's
11381 OK to have a rule that does nothing, so if you are integrating a
11382 third-party project with no documentation or tag support, you could
11383 simply augment its @file{Makefile} as follows:
11386 EMPTY_AUTOMAKE_TARGETS = dvi pdf ps info html tags ctags
11387 .PHONY: $(EMPTY_AUTOMAKE_TARGETS)
11388 $(EMPTY_AUTOMAKE_TARGETS):
11391 Another aspect of integrating third-party build systems is whether
11392 they support VPATH builds (@pxref{VPATH Builds}). Obviously if the
11393 subpackage does not support VPATH builds the whole package will not
11394 support VPATH builds. This in turns means that @samp{make distcheck}
11395 will not work, because it relies on VPATH builds. Some people can
11396 live without this (actually, many Automake users have never heard of
11397 @samp{make distcheck}). Other people may prefer to revamp the
11398 existing @file{Makefile}s to support VPATH@. Doing so does not
11399 necessarily require Automake, only Autoconf is needed (@pxref{Build
11400 Directories, , Build Directories, autoconf, The Autoconf Manual}).
11401 The necessary substitutions: @samp{@@srcdir@@}, @samp{@@top_srcdir@@},
11402 and @samp{@@top_builddir@@} are defined by @file{configure} when it
11403 processes a @file{Makefile} (@pxref{Preset Output Variables, , Preset
11404 Output Variables, autoconf, The Autoconf Manual}), they are not
11405 computed by the Makefile like the aforementioned @samp{$(distdir)} and
11406 @samp{$(top_distdir)} variables.
11408 It is sometimes inconvenient to modify a third-party @file{Makefile}
11409 to introduce the above required targets. For instance, one may want to
11410 keep the third-party sources untouched to ease upgrades to new
11413 @cindex @file{GNUmakefile} including @file{Makefile}
11414 Here are two other ideas. If GNU make is assumed, one possibility is
11415 to add to that subdirectory a @file{GNUmakefile} that defines the
11416 required targets and includes the third-party @file{Makefile}. For
11417 this to work in VPATH builds, @file{GNUmakefile} must lie in the build
11418 directory; the easiest way to do this is to write a
11419 @file{GNUmakefile.in} instead, and have it processed with
11420 @code{AC_CONFIG_FILES} from the outer package. For example if we
11421 assume @file{Makefile} defines all targets except the documentation
11422 targets, and that the @code{check} target is actually called
11423 @code{test}, we could write @file{GNUmakefile} (or
11424 @file{GNUmakefile.in}) like this:
11427 # First, include the real Makefile
11429 # Then, define the other targets needed by Automake Makefiles.
11430 .PHONY: dvi pdf ps info html check
11431 dvi pdf ps info html:
11435 @cindex Proxy @file{Makefile} for third-party packages
11436 A similar idea that does not use @code{include} is to write a proxy
11437 @file{Makefile} that dispatches rules to the real @file{Makefile},
11438 either with @samp{$(MAKE) -f Makefile.real $(AM_MAKEFLAGS) target} (if
11439 it's OK to rename the original @file{Makefile}) or with @samp{cd
11440 subdir && $(MAKE) $(AM_MAKEFLAGS) target} (if it's OK to store the
11441 subdirectory project one directory deeper). The good news is that
11442 this proxy @file{Makefile} can be generated with Automake. All we
11443 need are @option{-local} targets (@pxref{Extending}) that perform the
11444 dispatch. Of course the other Automake features are available, so you
11445 could decide to let Automake perform distribution or installation.
11446 Here is a possible @file{Makefile.am}:
11450 cd subdir && $(MAKE) $(AM_MAKEFLAGS) all
11452 cd subdir && $(MAKE) $(AM_MAKEFLAGS) test
11454 cd subdir && $(MAKE) $(AM_MAKEFLAGS) clean
11456 # Assuming the package knows how to install itself
11457 install-data-local:
11458 cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-data
11459 install-exec-local:
11460 cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-exec
11462 cd subdir && $(MAKE) $(AM_MAKEFLAGS) uninstall
11464 # Distribute files from here.
11465 EXTRA_DIST = subdir/Makefile subdir/program.c ...
11468 Pushing this idea to the extreme, it is also possible to ignore the
11469 subproject build system and build everything from this proxy
11470 @file{Makefile.am}. This might sound very sensible if you need VPATH
11471 builds but the subproject does not support them.
11474 @chapter Distributing @file{Makefile.in}s
11476 Automake places no restrictions on the distribution of the resulting
11477 @file{Makefile.in}s. We still encourage software authors to
11478 distribute their work under terms like those of the GPL, but doing so
11479 is not required to use Automake.
11481 Some of the files that can be automatically installed via the
11482 @option{--add-missing} switch do fall under the GPL@. However, these also
11483 have a special exception allowing you to distribute them with your
11484 package, regardless of the licensing you choose.
11487 @node API Versioning
11488 @chapter Automake API Versioning
11490 New Automake releases usually include bug fixes and new features.
11491 Unfortunately they may also introduce new bugs and incompatibilities.
11492 This makes four reasons why a package may require a particular Automake
11495 Things get worse when maintaining a large tree of packages, each one
11496 requiring a different version of Automake. In the past, this meant that
11497 any developer (and sometimes users) had to install several versions of
11498 Automake in different places, and switch @samp{$PATH} appropriately for
11501 Starting with version 1.6, Automake installs versioned binaries. This
11502 means you can install several versions of Automake in the same
11503 @samp{$prefix}, and can select an arbitrary Automake version by running
11504 @command{automake-1.6} or @command{automake-1.7} without juggling with
11505 @samp{$PATH}. Furthermore, @file{Makefile}'s generated by Automake 1.6
11506 will use @command{automake-1.6} explicitly in their rebuild rules.
11508 The number @samp{1.6} in @command{automake-1.6} is Automake's API version,
11509 not Automake's version. If a bug fix release is made, for instance
11510 Automake 1.6.1, the API version will remain 1.6. This means that a
11511 package that works with Automake 1.6 should also work with 1.6.1; after
11512 all, this is what people expect from bug fix releases.
11514 If your package relies on a feature or a bug fix introduced in
11515 a release, you can pass this version as an option to Automake to ensure
11516 older releases will not be used. For instance, use this in your
11517 @file{configure.ac}:
11520 AM_INIT_AUTOMAKE([1.6.1]) dnl Require Automake 1.6.1 or better.
11524 or, in a particular @file{Makefile.am}:
11527 AUTOMAKE_OPTIONS = 1.6.1 # Require Automake 1.6.1 or better.
11531 Automake will print an error message if its version is
11532 older than the requested version.
11535 @heading What is in the API
11537 Automake's programming interface is not easy to define. Basically it
11538 should include at least all @strong{documented} variables and targets
11539 that a @file{Makefile.am} author can use, any behavior associated with
11540 them (e.g., the places where @samp{-hook}'s are run), the command line
11541 interface of @command{automake} and @command{aclocal}, @dots{}
11543 @heading What is not in the API
11545 Every undocumented variable, target, or command line option, is not part
11546 of the API@. You should avoid using them, as they could change from one
11547 version to the other (even in bug fix releases, if this helps to fix a
11550 If it turns out you need to use such an undocumented feature, contact
11551 @email{automake@@gnu.org} and try to get it documented and exercised by
11555 @chapter Upgrading a Package to a Newer Automake Version
11557 Automake maintains three kind of files in a package.
11560 @item @file{aclocal.m4}
11561 @item @file{Makefile.in}s
11562 @item auxiliary tools like @file{install-sh} or @file{py-compile}
11565 @file{aclocal.m4} is generated by @command{aclocal} and contains some
11566 Automake-supplied M4 macros. Auxiliary tools are installed by
11567 @samp{automake --add-missing} when needed. @file{Makefile.in}s are
11568 built from @file{Makefile.am} by @command{automake}, and rely on the
11569 definitions of the M4 macros put in @file{aclocal.m4} as well as the
11570 behavior of the auxiliary tools installed.
11572 Because all these files are closely related, it is important to
11573 regenerate all of them when upgrading to a newer Automake release.
11574 The usual way to do that is
11577 aclocal # with any option needed (such a -I m4)
11579 automake --add-missing --force-missing
11583 or more conveniently:
11589 The use of @option{--force-missing} ensures that auxiliary tools will be
11590 overridden by new versions (@pxref{automake Invocation}).
11592 It is important to regenerate all these files each time Automake is
11593 upgraded, even between bug fixes releases. For instance, it is not
11594 unusual for a bug fix to involve changes to both the rules generated
11595 in @file{Makefile.in} and the supporting M4 macros copied to
11598 Presently @command{automake} is able to diagnose situations where
11599 @file{aclocal.m4} has been generated with another version of
11600 @command{aclocal}. However it never checks whether auxiliary scripts
11601 are up-to-date. In other words, @command{automake} will tell you when
11602 @command{aclocal} needs to be rerun, but it will never diagnose a
11603 missing @option{--force-missing}.
11605 Before upgrading to a new major release, it is a good idea to read the
11606 file @file{NEWS}. This file lists all changes between releases: new
11607 features, obsolete constructs, known incompatibilities, and
11611 @chapter Frequently Asked Questions about Automake
11613 This chapter covers some questions that often come up on the mailing
11617 * CVS:: CVS and generated files
11618 * maintainer-mode:: missing and AM_MAINTAINER_MODE
11619 * Wildcards:: Why doesn't Automake support wildcards?
11620 * Limitations on File Names:: Limitations on source and installed file names
11621 * Errors with distclean:: Files left in build directory after distclean
11622 * Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS
11623 * Renamed Objects:: Why are object files sometimes renamed?
11624 * Per-Object Flags:: How to simulate per-object flags?
11625 * Multiple Outputs:: Writing rules for tools with many output files
11626 * Hard-Coded Install Paths:: Installing to hard-coded locations
11627 * Debugging Make Rules:: Strategies when things don't work as expected
11628 * Reporting Bugs:: Feedback on bugs and feature requests
11632 @section CVS and generated files
11634 @subheading Background: distributed generated Files
11635 @cindex generated files, distributed
11636 @cindex rebuild rules
11638 Packages made with Autoconf and Automake ship with some generated
11639 files like @file{configure} or @file{Makefile.in}. These files were
11640 generated on the developer's host and are distributed so that
11641 end-users do not have to install the maintainer tools required to
11642 rebuild them. Other generated files like Lex scanners, Yacc parsers,
11643 or Info documentation, are usually distributed on similar grounds.
11645 Automake outputs rules in @file{Makefile}s to rebuild these files. For
11646 instance, @command{make} will run @command{autoconf} to rebuild
11647 @file{configure} whenever @file{configure.ac} is changed. This makes
11648 development safer by ensuring a @file{configure} is never out-of-date
11649 with respect to @file{configure.ac}.
11651 As generated files shipped in packages are up-to-date, and because
11652 @command{tar} preserves times-tamps, these rebuild rules are not
11653 triggered when a user unpacks and builds a package.
11655 @subheading Background: CVS and Timestamps
11656 @cindex timestamps and CVS
11657 @cindex CVS and timestamps
11659 Unless you use CVS keywords (in which case files must be updated at
11660 commit time), CVS preserves timestamp during @samp{cvs commit} and
11661 @samp{cvs import -d} operations.
11663 When you check out a file using @samp{cvs checkout} its timestamp is
11664 set to that of the revision that is being checked out.
11666 However, during @command{cvs update}, files will have the date of the
11667 update, not the original timestamp of this revision. This is meant to
11668 make sure that @command{make} notices sources files have been updated.
11670 This timestamp shift is troublesome when both sources and generated
11671 files are kept under CVS@. Because CVS processes files in lexical
11672 order, @file{configure.ac} will appear newer than @file{configure}
11673 after a @command{cvs update} that updates both files, even if
11674 @file{configure} was newer than @file{configure.ac} when it was
11675 checked in. Calling @command{make} will then trigger a spurious rebuild
11676 of @file{configure}.
11678 @subheading Living with CVS in Autoconfiscated Projects
11679 @cindex CVS and generated files
11680 @cindex generated files and CVS
11682 There are basically two clans amongst maintainers: those who keep all
11683 distributed files under CVS, including generated files, and those who
11684 keep generated files @emph{out} of CVS.
11686 @subsubheading All Files in CVS
11690 The CVS repository contains all distributed files so you know exactly
11691 what is distributed, and you can checkout any prior version entirely.
11694 Maintainers can see how generated files evolve (for instance, you can
11695 see what happens to your @file{Makefile.in}s when you upgrade Automake
11696 and make sure they look OK).
11699 Users do not need the autotools to build a checkout of the project, it
11700 works just like a released tarball.
11703 If users use @command{cvs update} to update their copy, instead of
11704 @command{cvs checkout} to fetch a fresh one, timestamps will be
11705 inaccurate. Some rebuild rules will be triggered and attempt to
11706 run developer tools such as @command{autoconf} or @command{automake}.
11708 Actually, calls to such tools are all wrapped into a call to the
11709 @command{missing} script discussed later (@pxref{maintainer-mode}).
11710 @command{missing} will take care of fixing the timestamps when these
11711 tools are not installed, so that the build can continue.
11714 In distributed development, developers are likely to have different
11715 version of the maintainer tools installed. In this case rebuilds
11716 triggered by timestamp lossage will lead to spurious changes
11717 to generated files. There are several solutions to this:
11721 All developers should use the same versions, so that the rebuilt files
11722 are identical to files in CVS@. (This starts to be difficult when each
11723 project you work on uses different versions.)
11725 Or people use a script to fix the timestamp after a checkout (the GCC
11726 folks have such a script).
11728 Or @file{configure.ac} uses @code{AM_MAINTAINER_MODE}, which will
11729 disable all these rebuild rules by default. This is further discussed
11730 in @ref{maintainer-mode}.
11734 Although we focused on spurious rebuilds, the converse can also
11735 happen. CVS's timestamp handling can also let you think an
11736 out-of-date file is up-to-date.
11738 For instance, suppose a developer has modified @file{Makefile.am} and
11739 has rebuilt @file{Makefile.in}, and then decides to do a last-minute
11740 change to @file{Makefile.am} right before checking in both files
11741 (without rebuilding @file{Makefile.in} to account for the change).
11743 This last change to @file{Makefile.am} makes the copy of
11744 @file{Makefile.in} out-of-date. Since CVS processes files
11745 alphabetically, when another developer @samp{cvs update}s his or her
11746 tree, @file{Makefile.in} will happen to be newer than
11747 @file{Makefile.am}. This other developer will not see that
11748 @file{Makefile.in} is out-of-date.
11752 @subsubheading Generated Files out of CVS
11754 One way to get CVS and @command{make} working peacefully is to never
11755 store generated files in CVS, i.e., do not CVS-control files that
11756 are @file{Makefile} targets (also called @emph{derived} files).
11758 This way developers are not annoyed by changes to generated files. It
11759 does not matter if they all have different versions (assuming they are
11760 compatible, of course). And finally, timestamps are not lost, changes
11761 to sources files can't be missed as in the
11762 @file{Makefile.am}/@file{Makefile.in} example discussed earlier.
11764 The drawback is that the CVS repository is not an exact copy of what
11765 is distributed and that users now need to install various development
11766 tools (maybe even specific versions) before they can build a checkout.
11767 But, after all, CVS's job is versioning, not distribution.
11769 Allowing developers to use different versions of their tools can also
11770 hide bugs during distributed development. Indeed, developers will be
11771 using (hence testing) their own generated files, instead of the
11772 generated files that will be released actually. The developer who
11773 prepares the tarball might be using a version of the tool that
11774 produces bogus output (for instance a non-portable C file), something
11775 other developers could have noticed if they weren't using their own
11776 versions of this tool.
11778 @subheading Third-party Files
11779 @cindex CVS and third-party files
11780 @cindex third-party files and CVS
11782 Another class of files not discussed here (because they do not cause
11783 timestamp issues) are files that are shipped with a package, but
11784 maintained elsewhere. For instance, tools like @command{gettextize}
11785 and @command{autopoint} (from Gettext) or @command{libtoolize} (from
11786 Libtool), will install or update files in your package.
11788 These files, whether they are kept under CVS or not, raise similar
11789 concerns about version mismatch between developers' tools. The
11790 Gettext manual has a section about this, see @ref{CVS Issues, CVS
11791 Issues, Integrating with CVS, gettext, GNU gettext tools}.
11793 @node maintainer-mode
11794 @section @command{missing} and @code{AM_MAINTAINER_MODE}
11796 @subheading @command{missing}
11797 @cindex @command{missing}, purpose
11799 The @command{missing} script is a wrapper around several maintainer
11800 tools, designed to warn users if a maintainer tool is required but
11801 missing. Typical maintainer tools are @command{autoconf},
11802 @command{automake}, @command{bison}, etc. Because file generated by
11803 these tools are shipped with the other sources of a package, these
11804 tools shouldn't be required during a user build and they are not
11805 checked for in @file{configure}.
11807 However, if for some reason a rebuild rule is triggered and involves a
11808 missing tool, @command{missing} will notice it and warn the user.
11809 Besides the warning, when a tool is missing, @command{missing} will
11810 attempt to fix timestamps in a way that allows the build to continue.
11811 For instance, @command{missing} will touch @file{configure} if
11812 @command{autoconf} is not installed. When all distributed files are
11813 kept under version control, this feature of @command{missing} allows a
11814 user @emph{with no maintainer tools} to build a package off its version
11815 control repository, bypassing any timestamp inconsistency (implied by
11816 e.g.@: @samp{cvs update} or @samp{git clone}).
11818 If the required tool is installed, @command{missing} will run it and
11819 won't attempt to continue after failures. This is correct during
11820 development: developers love fixing failures. However, users with
11821 wrong versions of maintainer tools may get an error when the rebuild
11822 rule is spuriously triggered, halting the build. This failure to let
11823 the build continue is one of the arguments of the
11824 @code{AM_MAINTAINER_MODE} advocates.
11826 @subheading @code{AM_MAINTAINER_MODE}
11827 @cindex @code{AM_MAINTAINER_MODE}, purpose
11828 @acindex AM_MAINTAINER_MODE
11830 @code{AM_MAINTAINER_MODE} allows you to choose whether the so called
11831 "rebuild rules" should be enabled or disabled. With
11832 @code{AM_MAINTAINER_MODE([enable])}, they are enabled by default,
11833 otherwise they are disabled by default. In the latter case, if
11834 you have @code{AM_MAINTAINER_MODE} in @file{configure.ac}, and run
11835 @samp{./configure && make}, then @command{make} will *never* attempt to
11836 rebuild @file{configure}, @file{Makefile.in}s, Lex or Yacc outputs, etc.
11837 I.e., this disables build rules for files that are usually distributed
11838 and that users should normally not have to update.
11840 The user can override the default setting by passing either
11841 @samp{--enable-maintainer-mode} or @samp{--disable-maintainer-mode}
11842 to @command{configure}.
11844 People use @code{AM_MAINTAINER_MODE} either because they do not want their
11845 users (or themselves) annoyed by timestamps lossage (@pxref{CVS}), or
11846 because they simply can't stand the rebuild rules and prefer running
11847 maintainer tools explicitly.
11849 @code{AM_MAINTAINER_MODE} also allows you to disable some custom build
11850 rules conditionally. Some developers use this feature to disable
11851 rules that need exotic tools that users may not have available.
11853 Several years ago Fran@,{c}ois Pinard pointed out several arguments
11854 against this @code{AM_MAINTAINER_MODE} macro. Most of them relate to
11855 insecurity. By removing dependencies you get non-dependable builds:
11856 changes to sources files can have no effect on generated files and this
11857 can be very confusing when unnoticed. He adds that security shouldn't
11858 be reserved to maintainers (what @option{--enable-maintainer-mode}
11859 suggests), on the contrary. If one user has to modify a
11860 @file{Makefile.am}, then either @file{Makefile.in} should be updated
11861 or a warning should be output (this is what Automake uses
11862 @command{missing} for) but the last thing you want is that nothing
11863 happens and the user doesn't notice it (this is what happens when
11864 rebuild rules are disabled by @code{AM_MAINTAINER_MODE}).
11866 Jim Meyering, the inventor of the @code{AM_MAINTAINER_MODE} macro was
11867 swayed by Fran@,{c}ois's arguments, and got rid of
11868 @code{AM_MAINTAINER_MODE} in all of his packages.
11870 Still many people continue to use @code{AM_MAINTAINER_MODE}, because
11871 it helps them working on projects where all files are kept under version
11872 control, and because @command{missing} isn't enough if you have the
11873 wrong version of the tools.
11877 @section Why doesn't Automake support wildcards?
11880 Developers are lazy. They would often like to use wildcards in
11881 @file{Makefile.am}s, so that they would not need to remember to
11882 update @file{Makefile.am}s every time they add, delete, or rename
11885 There are several objections to this:
11888 When using CVS (or similar) developers need to remember they have to
11889 run @samp{cvs add} or @samp{cvs rm} anyway. Updating
11890 @file{Makefile.am} accordingly quickly becomes a reflex.
11892 Conversely, if your application doesn't compile
11893 because you forgot to add a file in @file{Makefile.am}, it will help
11894 you remember to @samp{cvs add} it.
11897 Using wildcards makes it easy to distribute files by mistake. For
11898 instance, some code a developer is experimenting with (a test case,
11899 say) that should not be part of the distribution.
11902 Using wildcards it's easy to omit some files by mistake. For
11903 instance, one developer creates a new file, uses it in many places,
11904 but forgets to commit it. Another developer then checks out the
11905 incomplete project and is able to run @samp{make dist} successfully,
11906 even though a file is missing. By listing files, @samp{make dist}
11907 @emph{will} complain.
11910 Wildcards are not portable to some non-GNU @command{make} implementations,
11911 e.g., NetBSD @command{make} will not expand globs such as @samp{*} in
11912 prerequisites of a target.
11915 Finally, it's really hard to @emph{forget} to add a file to
11916 @file{Makefile.am}: files that are not listed in @file{Makefile.am} are
11917 not compiled or installed, so you can't even test them.
11920 Still, these are philosophical objections, and as such you may disagree,
11921 or find enough value in wildcards to dismiss all of them. Before you
11922 start writing a patch against Automake to teach it about wildcards,
11923 let's see the main technical issue: portability.
11925 Although @samp{$(wildcard ...)} works with GNU @command{make}, it is
11926 not portable to other @command{make} implementations.
11928 The only way Automake could support @command{$(wildcard ...)} is by
11929 expending @command{$(wildcard ...)} when @command{automake} is run.
11930 The resulting @file{Makefile.in}s would be portable since they would
11931 list all files and not use @samp{$(wildcard ...)}. However that
11932 means developers would need to remember to run @command{automake} each
11933 time they add, delete, or rename files.
11935 Compared to editing @file{Makefile.am}, this is a very small gain. Sure,
11936 it's easier and faster to type @samp{automake; make} than to type
11937 @samp{emacs Makefile.am; make}. But nobody bothered enough to write a
11938 patch to add support for this syntax. Some people use scripts to
11939 generate file lists in @file{Makefile.am} or in separate
11940 @file{Makefile} fragments.
11942 Even if you don't care about portability, and are tempted to use
11943 @samp{$(wildcard ...)} anyway because you target only GNU Make, you
11944 should know there are many places where Automake needs to know exactly
11945 which files should be processed. As Automake doesn't know how to
11946 expand @samp{$(wildcard ...)}, you cannot use it in these places.
11947 @samp{$(wildcard ...)} is a black box comparable to @code{AC_SUBST}ed
11948 variables as far Automake is concerned.
11950 You can get warnings about @samp{$(wildcard ...}) constructs using the
11951 @option{-Wportability} flag.
11953 @node Limitations on File Names
11954 @section Limitations on File Names
11955 @cindex file names, limitations on
11957 Automake attempts to support all kinds of file names, even those that
11958 contain unusual characters or are unusually long. However, some
11959 limitations are imposed by the underlying operating system and tools.
11961 Most operating systems prohibit the use of the null byte in file
11962 names, and reserve @samp{/} as a directory separator. Also, they
11963 require that file names are properly encoded for the user's locale.
11964 Automake is subject to these limits.
11966 Portable packages should limit themselves to POSIX file
11967 names. These can contain ASCII letters and digits,
11968 @samp{_}, @samp{.}, and @samp{-}. File names consist of components
11969 separated by @samp{/}. File name components cannot begin with
11972 Portable POSIX file names cannot contain components that exceed a
11973 14-byte limit, but nowadays it's normally safe to assume the
11974 more-generous XOPEN limit of 255 bytes. POSIX
11975 limits file names to 255 bytes (XOPEN allows 1023 bytes),
11976 but you may want to limit a source tarball to file names of 99 bytes
11977 to avoid interoperability problems with old versions of @command{tar}.
11979 If you depart from these rules (e.g., by using non-ASCII
11980 characters in file names, or by using lengthy file names), your
11981 installers may have problems for reasons unrelated to Automake.
11982 However, if this does not concern you, you should know about the
11983 limitations imposed by Automake itself. These limitations are
11984 undesirable, but some of them seem to be inherent to underlying tools
11985 like Autoconf, Make, M4, and the shell. They fall into three
11986 categories: install directories, build directories, and file names.
11988 The following characters:
11991 @r{newline} " # $ ' `
11994 should not appear in the names of install directories. For example,
11995 the operand of @command{configure}'s @option{--prefix} option should
11996 not contain these characters.
11998 Build directories suffer the same limitations as install directories,
11999 and in addition should not contain the following characters:
12005 For example, the full name of the directory containing the source
12006 files should not contain these characters.
12008 Source and installation file names like @file{main.c} are limited even
12009 further: they should conform to the POSIX/XOPEN
12010 rules described above. In addition, if you plan to port to
12011 non-POSIX environments, you should avoid file names that
12012 differ only in case (e.g., @file{makefile} and @file{Makefile}).
12013 Nowadays it is no longer worth worrying about the 8.3 limits of
12016 @c FIXME This should probably be moved in the "Checking the Distribution"
12017 @c FIXME section...
12018 @node Errors with distclean
12019 @section Errors with distclean
12020 @cindex @code{distclean}, diagnostic
12021 @cindex @samp{make distclean}, diagnostic
12022 @cindex dependencies and distributed files
12025 This is a diagnostic you might encounter while running @samp{make
12028 As explained in @ref{Checking the Distribution}, @samp{make distcheck}
12029 attempts to build and check your package for errors like this one.
12031 @samp{make distcheck} will perform a @code{VPATH} build of your
12032 package (@pxref{VPATH Builds}), and then call @samp{make distclean}.
12033 Files left in the build directory after @samp{make distclean} has run
12034 are listed after this error.
12036 This diagnostic really covers two kinds of errors:
12040 files that are forgotten by distclean;
12042 distributed files that are erroneously rebuilt.
12045 The former left-over files are not distributed, so the fix is to mark
12046 them for cleaning (@pxref{Clean}), this is obvious and doesn't deserve
12049 The latter bug is not always easy to understand and fix, so let's
12050 proceed with an example. Suppose our package contains a program for
12051 which we want to build a man page using @command{help2man}. GNU
12052 @command{help2man} produces simple manual pages from the @option{--help}
12053 and @option{--version} output of other commands (@pxref{Top, , Overview,
12054 help2man, The Help2man Manual}). Because we don't want to force our
12055 users to install @command{help2man}, we decide to distribute the
12056 generated man page using the following setup.
12059 # This Makefile.am is bogus.
12061 foo_SOURCES = foo.c
12062 dist_man_MANS = foo.1
12064 foo.1: foo$(EXEEXT)
12065 help2man --output=foo.1 ./foo$(EXEEXT)
12068 This will effectively distribute the man page. However,
12069 @samp{make distcheck} will fail with:
12072 ERROR: files left in build directory after distclean:
12076 Why was @file{foo.1} rebuilt? Because although distributed,
12077 @file{foo.1} depends on a non-distributed built file:
12078 @file{foo$(EXEEXT)}. @file{foo$(EXEEXT)} is built by the user, so it
12079 will always appear to be newer than the distributed @file{foo.1}.
12081 @samp{make distcheck} caught an inconsistency in our package. Our
12082 intent was to distribute @file{foo.1} so users do not need to install
12083 @command{help2man}, however since this rule causes this file to be
12084 always rebuilt, users @emph{do} need @command{help2man}. Either we
12085 should ensure that @file{foo.1} is not rebuilt by users, or there is
12086 no point in distributing @file{foo.1}.
12088 More generally, the rule is that distributed files should never depend
12089 on non-distributed built files. If you distribute something
12090 generated, distribute its sources.
12092 One way to fix the above example, while still distributing
12093 @file{foo.1} is to not depend on @file{foo$(EXEEXT)}. For instance,
12094 assuming @command{foo --version} and @command{foo --help} do not
12095 change unless @file{foo.c} or @file{configure.ac} change, we could
12096 write the following @file{Makefile.am}:
12100 foo_SOURCES = foo.c
12101 dist_man_MANS = foo.1
12103 foo.1: foo.c $(top_srcdir)/configure.ac
12104 $(MAKE) $(AM_MAKEFLAGS) foo$(EXEEXT)
12105 help2man --output=foo.1 ./foo$(EXEEXT)
12108 This way, @file{foo.1} will not get rebuilt every time
12109 @file{foo$(EXEEXT)} changes. The @command{make} call makes sure
12110 @file{foo$(EXEEXT)} is up-to-date before @command{help2man}. Another
12111 way to ensure this would be to use separate directories for binaries
12112 and man pages, and set @code{SUBDIRS} so that binaries are built
12115 We could also decide not to distribute @file{foo.1}. In
12116 this case it's fine to have @file{foo.1} dependent upon
12117 @file{foo$(EXEEXT)}, since both will have to be rebuilt.
12118 However it would be impossible to build the package in a
12119 cross-compilation, because building @file{foo.1} involves
12120 an @emph{execution} of @file{foo$(EXEEXT)}.
12122 Another context where such errors are common is when distributed files
12123 are built by tools that are built by the package. The pattern is
12127 distributed-file: built-tools distributed-sources
12132 should be changed to
12135 distributed-file: distributed-sources
12136 $(MAKE) $(AM_MAKEFLAGS) built-tools
12141 or you could choose not to distribute @file{distributed-file}, if
12142 cross-compilation does not matter.
12144 The points made through these examples are worth a summary:
12149 Distributed files should never depend upon non-distributed built
12152 Distributed files should be distributed with all their dependencies.
12154 If a file is @emph{intended} to be rebuilt by users, then there is no point
12155 in distributing it.
12159 @vrindex distcleancheck_listfiles
12160 For desperate cases, it's always possible to disable this check by
12161 setting @code{distcleancheck_listfiles} as documented in @ref{Checking
12163 Make sure you do understand the reason why @samp{make distcheck}
12164 complains before you do this. @code{distcleancheck_listfiles} is a
12165 way to @emph{hide} errors, not to fix them. You can always do better.
12167 @node Flag Variables Ordering
12168 @section Flag Variables Ordering
12169 @cindex Ordering flag variables
12170 @cindex Flag variables, ordering
12173 What is the difference between @code{AM_CFLAGS}, @code{CFLAGS}, and
12174 @code{mumble_CFLAGS}?
12178 Why does @command{automake} output @code{CPPFLAGS} after
12179 @code{AM_CPPFLAGS} on compile lines? Shouldn't it be the converse?
12183 My @file{configure} adds some warning flags into @code{CXXFLAGS}. In
12184 one @file{Makefile.am} I would like to append a new flag, however if I
12185 put the flag into @code{AM_CXXFLAGS} it is prepended to the other
12186 flags, not appended.
12189 @subheading Compile Flag Variables
12190 @cindex Flag Variables, Ordering
12191 @cindex Compile Flag Variables
12192 @cindex @code{AM_CCASFLAGS} and @code{CCASFLAGS}
12193 @cindex @code{AM_CFLAGS} and @code{CFLAGS}
12194 @cindex @code{AM_CPPFLAGS} and @code{CPPFLAGS}
12195 @cindex @code{AM_CXXFLAGS} and @code{CXXFLAGS}
12196 @cindex @code{AM_FCFLAGS} and @code{FCFLAGS}
12197 @cindex @code{AM_FFLAGS} and @code{FFLAGS}
12198 @cindex @code{AM_GCJFLAGS} and @code{GCJFLAGS}
12199 @cindex @code{AM_LDFLAGS} and @code{LDFLAGS}
12200 @cindex @code{AM_LFLAGS} and @code{LFLAGS}
12201 @cindex @code{AM_LIBTOOLFLAGS} and @code{LIBTOOLFLAGS}
12202 @cindex @code{AM_OBJCFLAGS} and @code{OBJCFLAGS}
12203 @cindex @code{AM_RFLAGS} and @code{RFLAGS}
12204 @cindex @code{AM_UPCFLAGS} and @code{UPCFLAGS}
12205 @cindex @code{AM_YFLAGS} and @code{YFLAGS}
12206 @cindex @code{CCASFLAGS} and @code{AM_CCASFLAGS}
12207 @cindex @code{CFLAGS} and @code{AM_CFLAGS}
12208 @cindex @code{CPPFLAGS} and @code{AM_CPPFLAGS}
12209 @cindex @code{CXXFLAGS} and @code{AM_CXXFLAGS}
12210 @cindex @code{FCFLAGS} and @code{AM_FCFLAGS}
12211 @cindex @code{FFLAGS} and @code{AM_FFLAGS}
12212 @cindex @code{GCJFLAGS} and @code{AM_GCJFLAGS}
12213 @cindex @code{LDFLAGS} and @code{AM_LDFLAGS}
12214 @cindex @code{LFLAGS} and @code{AM_LFLAGS}
12215 @cindex @code{LIBTOOLFLAGS} and @code{AM_LIBTOOLFLAGS}
12216 @cindex @code{OBJCFLAGS} and @code{AM_OBJCFLAGS}
12217 @cindex @code{RFLAGS} and @code{AM_RFLAGS}
12218 @cindex @code{UPCFLAGS} and @code{AM_UPCFLAGS}
12219 @cindex @code{YFLAGS} and @code{AM_YFLAGS}
12221 This section attempts to answer all the above questions. We will
12222 mostly discuss @code{CPPFLAGS} in our examples, but actually the
12223 answer holds for all the compile flags used in Automake:
12224 @code{CCASFLAGS}, @code{CFLAGS}, @code{CPPFLAGS}, @code{CXXFLAGS},
12225 @code{FCFLAGS}, @code{FFLAGS}, @code{GCJFLAGS}, @code{LDFLAGS},
12226 @code{LFLAGS}, @code{LIBTOOLFLAGS}, @code{OBJCFLAGS}, @code{RFLAGS},
12227 @code{UPCFLAGS}, and @code{YFLAGS}.
12229 @code{CPPFLAGS}, @code{AM_CPPFLAGS}, and @code{mumble_CPPFLAGS} are
12230 three variables that can be used to pass flags to the C preprocessor
12231 (actually these variables are also used for other languages like C++
12232 or preprocessed Fortran). @code{CPPFLAGS} is the user variable
12233 (@pxref{User Variables}), @code{AM_CPPFLAGS} is the Automake variable,
12234 and @code{mumble_CPPFLAGS} is the variable specific to the
12235 @code{mumble} target (we call this a per-target variable,
12236 @pxref{Program and Library Variables}).
12238 Automake always uses two of these variables when compiling C sources
12239 files. When compiling an object file for the @code{mumble} target,
12240 the first variable will be @code{mumble_CPPFLAGS} if it is defined, or
12241 @code{AM_CPPFLAGS} otherwise. The second variable is always
12244 In the following example,
12247 bin_PROGRAMS = foo bar
12248 foo_SOURCES = xyz.c
12249 bar_SOURCES = main.c
12250 foo_CPPFLAGS = -DFOO
12251 AM_CPPFLAGS = -DBAZ
12255 @file{xyz.o} will be compiled with @samp{$(foo_CPPFLAGS) $(CPPFLAGS)},
12256 (because @file{xyz.o} is part of the @code{foo} target), while
12257 @file{main.o} will be compiled with @samp{$(AM_CPPFLAGS) $(CPPFLAGS)}
12258 (because there is no per-target variable for target @code{bar}).
12260 The difference between @code{mumble_CPPFLAGS} and @code{AM_CPPFLAGS}
12261 being clear enough, let's focus on @code{CPPFLAGS}. @code{CPPFLAGS}
12262 is a user variable, i.e., a variable that users are entitled to modify
12263 in order to compile the package. This variable, like many others,
12264 is documented at the end of the output of @samp{configure --help}.
12266 For instance, someone who needs to add @file{/home/my/usr/include} to
12267 the C compiler's search path would configure a package with
12270 ./configure CPPFLAGS='-I /home/my/usr/include'
12274 and this flag would be propagated to the compile rules of all
12277 It is also not uncommon to override a user variable at
12278 @command{make}-time. Many installers do this with @code{prefix}, but
12279 this can be useful with compiler flags too. For instance, if, while
12280 debugging a C++ project, you need to disable optimization in one
12281 specific object file, you can run something like
12285 make CXXFLAGS=-O0 file.o
12289 The reason @samp{$(CPPFLAGS)} appears after @samp{$(AM_CPPFLAGS)} or
12290 @samp{$(mumble_CPPFLAGS)} in the compile command is that users
12291 should always have the last say. It probably makes more sense if you
12292 think about it while looking at the @samp{CXXFLAGS=-O0} above, which
12293 should supersede any other switch from @code{AM_CXXFLAGS} or
12294 @code{mumble_CXXFLAGS} (and this of course replaces the previous value
12295 of @code{CXXFLAGS}).
12297 You should never redefine a user variable such as @code{CPPFLAGS} in
12298 @file{Makefile.am}. Use @samp{automake -Woverride} to diagnose such
12299 mistakes. Even something like
12302 CPPFLAGS = -DDATADIR=\"$(datadir)\" @@CPPFLAGS@@
12306 is erroneous. Although this preserves @file{configure}'s value of
12307 @code{CPPFLAGS}, the definition of @code{DATADIR} will disappear if a
12308 user attempts to override @code{CPPFLAGS} from the @command{make}
12312 AM_CPPFLAGS = -DDATADIR=\"$(datadir)\"
12316 is all that is needed here if no per-target flags are used.
12318 You should not add options to these user variables within
12319 @file{configure} either, for the same reason. Occasionally you need
12320 to modify these variables to perform a test, but you should reset
12321 their values afterwards. In contrast, it is OK to modify the
12322 @samp{AM_} variables within @file{configure} if you @code{AC_SUBST}
12323 them, but it is rather rare that you need to do this, unless you
12324 really want to change the default definitions of the @samp{AM_}
12325 variables in all @file{Makefile}s.
12327 What we recommend is that you define extra flags in separate
12328 variables. For instance, you may write an Autoconf macro that computes
12329 a set of warning options for the C compiler, and @code{AC_SUBST} them
12330 in @code{WARNINGCFLAGS}; you may also have an Autoconf macro that
12331 determines which compiler and which linker flags should be used to
12332 link with library @file{libfoo}, and @code{AC_SUBST} these in
12333 @code{LIBFOOCFLAGS} and @code{LIBFOOLDFLAGS}. Then, a
12334 @file{Makefile.am} could use these variables as follows:
12337 AM_CFLAGS = $(WARNINGCFLAGS)
12338 bin_PROGRAMS = prog1 prog2
12339 prog1_SOURCES = @dots{}
12340 prog2_SOURCES = @dots{}
12341 prog2_CFLAGS = $(LIBFOOCFLAGS) $(AM_CFLAGS)
12342 prog2_LDFLAGS = $(LIBFOOLDFLAGS)
12345 In this example both programs will be compiled with the flags
12346 substituted into @samp{$(WARNINGCFLAGS)}, and @code{prog2} will
12347 additionally be compiled with the flags required to link with
12350 Note that listing @code{AM_CFLAGS} in a per-target @code{CFLAGS}
12351 variable is a common idiom to ensure that @code{AM_CFLAGS} applies to
12352 every target in a @file{Makefile.in}.
12354 Using variables like this gives you full control over the ordering of
12355 the flags. For instance, if there is a flag in $(WARNINGCFLAGS) that
12356 you want to negate for a particular target, you can use something like
12357 @samp{prog1_CFLAGS = $(AM_CFLAGS) -no-flag}. If all these flags had
12358 been forcefully appended to @code{CFLAGS}, there would be no way to
12359 disable one flag. Yet another reason to leave user variables to
12362 Finally, we have avoided naming the variable of the example
12363 @code{LIBFOO_LDFLAGS} (with an underscore) because that would cause
12364 Automake to think that this is actually a per-target variable (like
12365 @code{mumble_LDFLAGS}) for some non-declared @code{LIBFOO} target.
12367 @subheading Other Variables
12369 There are other variables in Automake that follow similar principles
12370 to allow user options. For instance, Texinfo rules (@pxref{Texinfo})
12371 use @code{MAKEINFOFLAGS} and @code{AM_MAKEINFOFLAGS}. Similarly,
12372 DejaGnu tests (@pxref{DejaGnu Tests}) use @code{RUNTESTDEFAULTFLAGS} and
12373 @code{AM_RUNTESTDEFAULTFLAGS}. The tags and ctags rules
12374 (@pxref{Tags}) use @code{ETAGSFLAGS}, @code{AM_ETAGSFLAGS},
12375 @code{CTAGSFLAGS}, and @code{AM_CTAGSFLAGS}. Java rules
12376 (@pxref{Java}) use @code{JAVACFLAGS} and @code{AM_JAVACFLAGS}. None
12377 of these rules support per-target flags (yet).
12379 To some extent, even @code{AM_MAKEFLAGS} (@pxref{Subdirectories})
12380 obeys this naming scheme. The slight difference is that
12381 @code{MAKEFLAGS} is passed to sub-@command{make}s implicitly by
12382 @command{make} itself.
12384 However you should not think that all variables ending with
12385 @code{FLAGS} follow this convention. For instance,
12386 @code{DISTCHECK_CONFIGURE_FLAGS} (@pxref{Checking the Distribution}) and
12387 @code{ACLOCAL_AMFLAGS} (see @ref{Rebuilding} and @ref{Local Macros}),
12388 are two variables that are only useful to the maintainer and have no
12391 @code{ARFLAGS} (@pxref{A Library}) is usually defined by Automake and
12392 has neither @code{AM_} nor per-target cousin.
12394 Finally you should not think that the existence of a per-target
12395 variable implies the existence of an @code{AM_} variable or of a user
12396 variable. For instance, the @code{mumble_LDADD} per-target variable
12397 overrides the makefile-wide @code{LDADD} variable (which is not a user
12398 variable), and @code{mumble_LIBADD} exists only as a per-target
12399 variable. @xref{Program and Library Variables}.
12402 @node Renamed Objects
12403 @section Why are object files sometimes renamed?
12405 This happens when per-target compilation flags are used. Object
12406 files need to be renamed just in case they would clash with object
12407 files compiled from the same sources, but with different flags.
12408 Consider the following example.
12411 bin_PROGRAMS = true false
12412 true_SOURCES = generic.c
12413 true_CPPFLAGS = -DEXIT_CODE=0
12414 false_SOURCES = generic.c
12415 false_CPPFLAGS = -DEXIT_CODE=1
12419 Obviously the two programs are built from the same source, but it
12420 would be bad if they shared the same object, because @file{generic.o}
12421 cannot be built with both @samp{-DEXIT_CODE=0} @emph{and}
12422 @samp{-DEXIT_CODE=1}. Therefore @command{automake} outputs rules to
12423 build two different objects: @file{true-generic.o} and
12424 @file{false-generic.o}.
12426 @command{automake} doesn't actually look whether source files are
12427 shared to decide if it must rename objects. It will just rename all
12428 objects of a target as soon as it sees per-target compilation flags
12431 It's OK to share object files when per-target compilation flags are not
12432 used. For instance, @file{true} and @file{false} will both use
12433 @file{version.o} in the following example.
12436 AM_CPPFLAGS = -DVERSION=1.0
12437 bin_PROGRAMS = true false
12438 true_SOURCES = true.c version.c
12439 false_SOURCES = false.c version.c
12442 Note that the renaming of objects is also affected by the
12443 @code{_SHORTNAME} variable (@pxref{Program and Library Variables}).
12446 @node Per-Object Flags
12447 @section Per-Object Flags Emulation
12448 @cindex Per-object flags, emulated
12451 One of my source files needs to be compiled with different flags. How
12455 Automake supports per-program and per-library compilation flags (see
12456 @ref{Program and Library Variables} and @ref{Flag Variables
12457 Ordering}). With this you can define compilation flags that apply to
12458 all files compiled for a target. For instance, in
12462 foo_SOURCES = foo.c foo.h bar.c bar.h main.c
12463 foo_CFLAGS = -some -flags
12467 @file{foo-foo.o}, @file{foo-bar.o}, and @file{foo-main.o} will all be
12468 compiled with @samp{-some -flags}. (If you wonder about the names of
12469 these object files, see @ref{Renamed Objects}.) Note that
12470 @code{foo_CFLAGS} gives the flags to use when compiling all the C
12471 sources of the @emph{program} @code{foo}, it has nothing to do with
12472 @file{foo.c} or @file{foo-foo.o} specifically.
12474 What if @file{foo.c} needs to be compiled into @file{foo.o} using some
12475 specific flags, that none of the other files requires? Obviously
12476 per-program flags are not directly applicable here. Something like
12477 per-object flags are expected, i.e., flags that would be used only
12478 when creating @file{foo-foo.o}. Automake does not support that,
12479 however this is easy to simulate using a library that contains only
12480 that object, and compiling this library with per-library flags.
12484 foo_SOURCES = bar.c bar.h main.c
12485 foo_CFLAGS = -some -flags
12486 foo_LDADD = libfoo.a
12487 noinst_LIBRARIES = libfoo.a
12488 libfoo_a_SOURCES = foo.c foo.h
12489 libfoo_a_CFLAGS = -some -other -flags
12492 Here @file{foo-bar.o} and @file{foo-main.o} will all be
12493 compiled with @samp{-some -flags}, while @file{libfoo_a-foo.o} will
12494 be compiled using @samp{-some -other -flags}. Eventually, all
12495 three objects will be linked to form @file{foo}.
12497 This trick can also be achieved using Libtool convenience libraries,
12498 for instance @samp{noinst_LTLIBRARIES = libfoo.la} (@pxref{Libtool
12499 Convenience Libraries}).
12501 Another tempting idea to implement per-object flags is to override the
12502 compile rules @command{automake} would output for these files.
12503 Automake will not define a rule for a target you have defined, so you
12504 could think about defining the @samp{foo-foo.o: foo.c} rule yourself.
12505 We recommend against this, because this is error prone. For instance,
12506 if you add such a rule to the first example, it will break the day you
12507 decide to remove @code{foo_CFLAGS} (because @file{foo.c} will then be
12508 compiled as @file{foo.o} instead of @file{foo-foo.o}, @pxref{Renamed
12509 Objects}). Also in order to support dependency tracking, the two
12510 @file{.o}/@file{.obj} extensions, and all the other flags variables
12511 involved in a compilation, you will end up modifying a copy of the
12512 rule previously output by @command{automake} for this file. If a new
12513 release of Automake generates a different rule, your copy will need to
12514 be updated by hand.
12516 @node Multiple Outputs
12517 @section Handling Tools that Produce Many Outputs
12518 @cindex multiple outputs, rules with
12519 @cindex many outputs, rules with
12520 @cindex rules with multiple outputs
12522 This section describes a @command{make} idiom that can be used when a
12523 tool produces multiple output files. It is not specific to Automake
12524 and can be used in ordinary @file{Makefile}s.
12526 Suppose we have a program called @command{foo} that will read one file
12527 called @file{data.foo} and produce two files named @file{data.c} and
12528 @file{data.h}. We want to write a @file{Makefile} rule that captures
12529 this one-to-two dependency.
12531 The naive rule is incorrect:
12534 # This is incorrect.
12535 data.c data.h: data.foo
12540 What the above rule really says is that @file{data.c} and
12541 @file{data.h} each depend on @file{data.foo}, and can each be built by
12542 running @samp{foo data.foo}. In other words it is equivalent to:
12545 # We do not want this.
12553 which means that @command{foo} can be run twice. Usually it will not
12554 be run twice, because @command{make} implementations are smart enough
12555 to check for the existence of the second file after the first one has
12556 been built; they will therefore detect that it already exists.
12557 However there are a few situations where it can run twice anyway:
12561 The most worrying case is when running a parallel @command{make}. If
12562 @file{data.c} and @file{data.h} are built in parallel, two @samp{foo
12563 data.foo} commands will run concurrently. This is harmful.
12565 Another case is when the dependency (here @file{data.foo}) is
12566 (or depends upon) a phony target.
12569 A solution that works with parallel @command{make} but not with
12570 phony dependencies is the following:
12573 data.c data.h: data.foo
12579 The above rules are equivalent to
12584 data.h: data.foo data.c
12589 therefore a parallel @command{make} will have to serialize the builds
12590 of @file{data.c} and @file{data.h}, and will detect that the second is
12591 no longer needed once the first is over.
12593 Using this pattern is probably enough for most cases. However it does
12594 not scale easily to more output files (in this scheme all output files
12595 must be totally ordered by the dependency relation), so we will
12596 explore a more complicated solution.
12598 Another idea is to write the following:
12601 # There is still a problem with this one.
12608 The idea is that @samp{foo data.foo} is run only when @file{data.c}
12609 needs to be updated, but we further state that @file{data.h} depends
12610 upon @file{data.c}. That way, if @file{data.h} is required and
12611 @file{data.foo} is out of date, the dependency on @file{data.c} will
12614 This is almost perfect, but suppose we have built @file{data.h} and
12615 @file{data.c}, and then we erase @file{data.h}. Then, running
12616 @samp{make data.h} will not rebuild @file{data.h}. The above rules
12617 just state that @file{data.c} must be up-to-date with respect to
12618 @file{data.foo}, and this is already the case.
12620 What we need is a rule that forces a rebuild when @file{data.h} is
12621 missing. Here it is:
12627 ## Recover from the removal of $@@
12628 @@if test -f $@@; then :; else \
12630 $(MAKE) $(AM_MAKEFLAGS) data.c; \
12634 The above scheme can be extended to handle more outputs and more
12635 inputs. One of the outputs is selected to serve as a witness to the
12636 successful completion of the command, it depends upon all inputs, and
12637 all other outputs depend upon it. For instance, if @command{foo}
12638 should additionally read @file{data.bar} and also produce
12639 @file{data.w} and @file{data.x}, we would write:
12642 data.c: data.foo data.bar
12643 foo data.foo data.bar
12644 data.h data.w data.x: data.c
12645 ## Recover from the removal of $@@
12646 @@if test -f $@@; then :; else \
12648 $(MAKE) $(AM_MAKEFLAGS) data.c; \
12652 However there are now three minor problems in this setup. One is related
12653 to the timestamp ordering of @file{data.h}, @file{data.w},
12654 @file{data.x}, and @file{data.c}. Another one is a race condition
12655 if a parallel @command{make} attempts to run multiple instances of the
12656 recover block at once. Finally, the recursive rule breaks @samp{make -n}
12657 when run with GNU @command{make} (as well as some other @command{make}
12658 implementations), as it may remove @file{data.h} even when it should not
12659 (@pxref{MAKE Variable, , How the @code{MAKE} Variable Works, make,
12660 The GNU Make Manual}).
12662 Let us deal with the first problem. @command{foo} outputs four files,
12663 but we do not know in which order these files are created. Suppose
12664 that @file{data.h} is created before @file{data.c}. Then we have a
12665 weird situation. The next time @command{make} is run, @file{data.h}
12666 will appear older than @file{data.c}, the second rule will be
12667 triggered, a shell will be started to execute the @samp{if@dots{}fi}
12668 command, but actually it will just execute the @code{then} branch,
12669 that is: nothing. In other words, because the witness we selected is
12670 not the first file created by @command{foo}, @command{make} will start
12671 a shell to do nothing each time it is run.
12673 A simple riposte is to fix the timestamps when this happens.
12676 data.c: data.foo data.bar
12677 foo data.foo data.bar
12678 data.h data.w data.x: data.c
12679 @@if test -f $@@; then \
12682 ## Recover from the removal of $@@
12684 $(MAKE) $(AM_MAKEFLAGS) data.c; \
12688 Another solution is to use a different and dedicated file as witness,
12689 rather than using any of @command{foo}'s outputs.
12692 data.stamp: data.foo data.bar
12695 foo data.foo data.bar
12696 @@mv -f data.tmp $@@
12697 data.c data.h data.w data.x: data.stamp
12698 ## Recover from the removal of $@@
12699 @@if test -f $@@; then :; else \
12700 rm -f data.stamp; \
12701 $(MAKE) $(AM_MAKEFLAGS) data.stamp; \
12705 @file{data.tmp} is created before @command{foo} is run, so it has a
12706 timestamp older than output files output by @command{foo}. It is then
12707 renamed to @file{data.stamp} after @command{foo} has run, because we
12708 do not want to update @file{data.stamp} if @command{foo} fails.
12710 This solution still suffers from the second problem: the race
12711 condition in the recover rule. If, after a successful build, a user
12712 erases @file{data.c} and @file{data.h}, and runs @samp{make -j}, then
12713 @command{make} may start both recover rules in parallel. If the two
12714 instances of the rule execute @samp{$(MAKE) $(AM_MAKEFLAGS)
12715 data.stamp} concurrently the build is likely to fail (for instance, the
12716 two rules will create @file{data.tmp}, but only one can rename it).
12718 Admittedly, such a weird situation does not arise during ordinary
12719 builds. It occurs only when the build tree is mutilated. Here
12720 @file{data.c} and @file{data.h} have been explicitly removed without
12721 also removing @file{data.stamp} and the other output files.
12722 @code{make clean; make} will always recover from these situations even
12723 with parallel makes, so you may decide that the recover rule is solely
12724 to help non-parallel make users and leave things as-is. Fixing this
12725 requires some locking mechanism to ensure only one instance of the
12726 recover rule rebuilds @file{data.stamp}. One could imagine something
12727 along the following lines.
12730 data.c data.h data.w data.x: data.stamp
12731 ## Recover from the removal of $@@
12732 @@if test -f $@@; then :; else \
12733 trap 'rm -rf data.lock data.stamp' 1 2 13 15; \
12734 ## mkdir is a portable test-and-set
12735 if mkdir data.lock 2>/dev/null; then \
12736 ## This code is being executed by the first process.
12737 rm -f data.stamp; \
12738 $(MAKE) $(AM_MAKEFLAGS) data.stamp; \
12739 result=$$?; rm -rf data.lock; exit $$result; \
12741 ## This code is being executed by the follower processes.
12742 ## Wait until the first process is done.
12743 while test -d data.lock; do sleep 1; done; \
12744 ## Succeed if and only if the first process succeeded.
12745 test -f data.stamp; \
12750 Using a dedicated witness, like @file{data.stamp}, is very handy when
12751 the list of output files is not known beforehand. As an illustration,
12752 consider the following rules to compile many @file{*.el} files into
12753 @file{*.elc} files in a single command. It does not matter how
12754 @code{ELFILES} is defined (as long as it is not empty: empty targets
12755 are not accepted by POSIX).
12758 ELFILES = one.el two.el three.el @dots{}
12759 ELCFILES = $(ELFILES:=c)
12761 elc-stamp: $(ELFILES)
12764 $(elisp_comp) $(ELFILES)
12765 @@mv -f elc-temp $@@
12767 $(ELCFILES): elc-stamp
12768 @@if test -f $@@; then :; else \
12769 ## Recover from the removal of $@@
12770 trap 'rm -rf elc-lock elc-stamp' 1 2 13 15; \
12771 if mkdir elc-lock 2>/dev/null; then \
12772 ## This code is being executed by the first process.
12774 $(MAKE) $(AM_MAKEFLAGS) elc-stamp; \
12777 ## This code is being executed by the follower processes.
12778 ## Wait until the first process is done.
12779 while test -d elc-lock; do sleep 1; done; \
12780 ## Succeed if and only if the first process succeeded.
12781 test -f elc-stamp; exit $$?; \
12787 These solutions all still suffer from the third problem, namely that
12788 they break the promise that @samp{make -n} should not cause any actual
12789 changes to the tree. For those solutions that do not create lock files,
12790 it is possible to split the recover rules into two separate recipe
12791 commands, one of which does all work but the recursion, and the
12792 other invokes the recursive @samp{$(MAKE)}. The solutions involving
12793 locking could act upon the contents of the @samp{MAKEFLAGS} variable,
12794 but parsing that portably is not easy (@pxref{The Make Macro MAKEFLAGS,,,
12795 autoconf, The Autoconf Manual}). Here is an example:
12798 ELFILES = one.el two.el three.el @dots{}
12799 ELCFILES = $(ELFILES:=c)
12801 elc-stamp: $(ELFILES)
12804 $(elisp_comp) $(ELFILES)
12805 @@mv -f elc-temp $@@
12807 $(ELCFILES): elc-stamp
12808 ## Recover from the removal of $@@
12809 @@dry=; for f in x $$MAKEFLAGS; do \
12815 if test -f $@@; then :; else \
12816 $$dry trap 'rm -rf elc-lock elc-stamp' 1 2 13 15; \
12817 if $$dry mkdir elc-lock 2>/dev/null; then \
12818 ## This code is being executed by the first process.
12819 $$dry rm -f elc-stamp; \
12820 $(MAKE) $(AM_MAKEFLAGS) elc-stamp; \
12821 $$dry rmdir elc-lock; \
12823 ## This code is being executed by the follower processes.
12824 ## Wait until the first process is done.
12825 while test -d elc-lock && test -z "$$dry"; do \
12829 ## Succeed if and only if the first process succeeded.
12830 $$dry test -f elc-stamp; exit $$?; \
12835 For completeness it should be noted that GNU @command{make} is able to
12836 express rules with multiple output files using pattern rules
12837 (@pxref{Pattern Examples, , Pattern Rule Examples, make, The GNU Make
12838 Manual}). We do not discuss pattern rules here because they are not
12839 portable, but they can be convenient in packages that assume GNU
12843 @node Hard-Coded Install Paths
12844 @section Installing to Hard-Coded Locations
12847 My package needs to install some configuration file. I tried to use
12848 the following rule, but @samp{make distcheck} fails. Why?
12852 install-data-local:
12853 $(INSTALL_DATA) $(srcdir)/afile $(DESTDIR)/etc/afile
12858 My package needs to populate the installation directory of another
12859 package at install-time. I can easily compute that installation
12860 directory in @file{configure}, but if I install files therein,
12861 @samp{make distcheck} fails. How else should I do?
12864 These two setups share their symptoms: @samp{make distcheck} fails
12865 because they are installing files to hard-coded paths. In the later
12866 case the path is not really hard-coded in the package, but we can
12867 consider it to be hard-coded in the system (or in whichever tool that
12868 supplies the path). As long as the path does not use any of the
12869 standard directory variables (@samp{$(prefix)}, @samp{$(bindir)},
12870 @samp{$(datadir)}, etc.), the effect will be the same:
12871 user-installations are impossible.
12873 As a (non-root) user who wants to install a package, you usually have no
12874 right to install anything in @file{/usr} or @file{/usr/local}. So you
12875 do something like @samp{./configure --prefix ~/usr} to install a
12876 package in your own @file{~/usr} tree.
12878 If a package attempts to install something to some hard-coded path
12879 (e.g., @file{/etc/afile}), regardless of this @option{--prefix} setting,
12880 then the installation will fail. @samp{make distcheck} performs such
12881 a @option{--prefix} installation, hence it will fail too.
12883 Now, there are some easy solutions.
12885 The above @code{install-data-local} example for installing
12886 @file{/etc/afile} would be better replaced by
12889 sysconf_DATA = afile
12893 by default @code{sysconfdir} will be @samp{$(prefix)/etc}, because
12894 this is what the GNU Standards require. When such a package is
12895 installed on an FHS compliant system, the installer will have to set
12896 @samp{--sysconfdir=/etc}. As the maintainer of the package you
12897 should not be concerned by such site policies: use the appropriate
12898 standard directory variable to install your files so that the installer
12899 can easily redefine these variables to match their site conventions.
12901 Installing files that should be used by another package is slightly
12902 more involved. Let's take an example and assume you want to install
12903 a shared library that is a Python extension module. If you ask Python
12904 where to install the library, it will answer something like this:
12907 % @kbd{python -c 'from distutils import sysconfig;
12908 print sysconfig.get_python_lib(1,0)'}
12909 /usr/lib/python2.5/site-packages
12912 If you indeed use this absolute path to install your shared library,
12913 non-root users will not be able to install the package, hence
12916 Let's do better. The @samp{sysconfig.get_python_lib()} function
12917 actually accepts a third argument that will replace Python's
12918 installation prefix.
12921 % @kbd{python -c 'from distutils import sysconfig;
12922 print sysconfig.get_python_lib(1,0,"$@{exec_prefix@}")'}
12923 $@{exec_prefix@}/lib/python2.5/site-packages
12926 You can also use this new path. If you do
12929 root users can install your package with the same @option{--prefix}
12930 as Python (you get the behavior of the previous attempt)
12933 non-root users can install your package too, they will have the
12934 extension module in a place that is not searched by Python but they
12935 can work around this using environment variables (and if you installed
12936 scripts that use this shared library, it's easy to tell Python were to
12937 look in the beginning of your script, so the script works in both
12941 The @code{AM_PATH_PYTHON} macro uses similar commands to define
12942 @samp{$(pythondir)} and @samp{$(pyexecdir)} (@pxref{Python}).
12944 Of course not all tools are as advanced as Python regarding that
12945 substitution of @var{prefix}. So another strategy is to figure the
12946 part of the installation directory that must be preserved. For
12947 instance, here is how @code{AM_PATH_LISPDIR} (@pxref{Emacs Lisp})
12948 computes @samp{$(lispdir)}:
12951 $EMACS -batch -q -eval '(while load-path
12952 (princ (concat (car load-path) "\n"))
12953 (setq load-path (cdr load-path)))' >conftest.out
12956 -e '/.*\/lib\/x*emacs\/site-lisp$/@{
12957 s,.*/lib/\(x*emacs/site-lisp\)$,$@{libdir@}/\1,;p;q;
12959 -e '/.*\/share\/x*emacs\/site-lisp$/@{
12960 s,.*/share/\(x*emacs/site-lisp\),$@{datarootdir@}/\1,;p;q;
12965 I.e., it just picks the first directory that looks like
12966 @file{*/lib/*emacs/site-lisp} or @file{*/share/*emacs/site-lisp} in
12967 the search path of emacs, and then substitutes @samp{$@{libdir@}} or
12968 @samp{$@{datadir@}} appropriately.
12970 The emacs case looks complicated because it processes a list and
12971 expects two possible layouts, otherwise it's easy, and the benefits for
12972 non-root users are really worth the extra @command{sed} invocation.
12975 @node Debugging Make Rules
12976 @section Debugging Make Rules
12977 @cindex debugging rules
12978 @cindex rules, debugging
12980 The rules and dependency trees generated by @command{automake} can get
12981 rather complex, and leave the developer head-scratching when things
12982 don't work as expected. Besides the debug options provided by the
12983 @command{make} command (@pxref{Options Summary,,, make, The GNU Make
12984 Manual}), here's a couple of further hints for debugging makefiles
12985 generated by @command{automake} effectively:
12989 If less verbose output has been enabled in the package with the
12990 @samp{silent-rules} option (@pxref{Options}), you can use
12991 @code{make V=1} to see the commands being executed.
12993 @code{make -n} can help show what would be done without actually doing
12994 it. Note however, that this will @emph{still execute} commands prefixed
12995 with @samp{+}, and, when using GNU @command{make}, commands that contain
12996 the strings @samp{$(MAKE)} or @samp{$@{MAKE@}} (@pxref{Instead of
12997 Execution,,, make, The GNU Make Manual}).
12998 Typically, this is helpful to show what recursive rules would do, but it
12999 means that, in your own rules, you should not mix such recursion with
13000 actions that change any files.@footnote{Automake's @samp{dist} and
13001 @samp{distcheck} rules had a bug in this regard in that they created
13002 directories even with @option{-n}, but this has been fixed in Automake
13003 1.11.} Furthermore, note that GNU @command{make} will update
13004 prerequisites for the @file{Makefile} file itself even with @option{-n}
13005 (@pxref{Remaking Makefiles,,, make, The GNU Make Manual}).
13007 @code{make SHELL="/bin/bash -vx"} can help debug complex rules.
13008 @xref{The Make Macro SHELL,,, autoconf, The Autoconf Manual}, for some
13009 portability quirks associated with this construct.
13011 @code{echo 'print: ; @@echo "$(VAR)"' | make -f Makefile -f - print}
13012 can be handy to examine the expanded value of variables. You may need
13013 to use a target other than @samp{print} if that is already used or a
13014 file with that name exists.
13016 @url{http://bashdb.sourceforge.net/@/remake/} provides a modified
13017 GNU @command{make} command called @command{remake} that copes with
13018 complex GNU @command{make}-specific Makefiles and allows to trace
13019 execution, examine variables, and call rules interactively, much like
13024 @node Reporting Bugs
13025 @section Reporting Bugs
13027 Most nontrivial software has bugs. Automake is no exception. Although
13028 we cannot promise we can or will fix a bug, and we might not even agree
13029 that it is a bug, we want to hear about problems you encounter. Often we
13030 agree they are bugs and want to fix them.
13032 To make it possible for us to fix a bug, please report it. In order to
13033 do so effectively, it helps to know when and how to do it.
13035 Before reporting a bug, it is a good idea to see if it is already known.
13036 You can look at the @uref{http://debbugs.gnu.org/, GNU Bug Tracker}
13037 and the @uref{http://lists.gnu.org/@/archive/@/html/@/bug-automake/,
13038 bug-automake mailing list archives} for previous bug reports. We
13040 @uref{http://sourceware.org/@/cgi-bin/@/gnatsweb.pl?database=automake,
13041 Gnats database} for bug tracking, so some bugs might have been reported
13042 there already. Please do not use it for new bug reports, however.
13044 If the bug is not already known, it should be reported. It is very
13045 important to report bugs in a way that is useful and efficient. For
13046 this, please familiarize yourself with
13047 @uref{http://www.chiark.greenend.org.uk/@/~sgtatham/@/bugs.html, How to
13048 Report Bugs Effectively} and
13049 @uref{http://catb.org/@/~esr/@/faqs/@/smart-questions.html, How to Ask
13050 Questions the Smart Way}. This helps you and developers to save time
13051 which can then be spent on fixing more bugs and implementing more
13054 For a bug report, a feature request or other suggestions, please send
13055 email to @email{@value{PACKAGE_BUGREPORT}}. This will then open a new
13056 bug in the @uref{http://debbugs.gnu.org/@/automake, bug tracker}. Be
13057 sure to include the versions of Autoconf and Automake that you use.
13058 Ideally, post a minimal @file{Makefile.am} and @file{configure.ac} that
13059 reproduces the problem you encounter. If you have encountered test
13060 suite failures, please attach the @file{tests/test-suite.log} file.
13062 @c ========================================================== Appendices
13065 @node Copying This Manual
13066 @appendix Copying This Manual
13069 * GNU Free Documentation License:: License for copying this manual
13072 @node GNU Free Documentation License
13073 @appendixsec GNU Free Documentation License
13081 * Macro Index:: Index of Autoconf macros
13082 * Variable Index:: Index of Makefile variables
13083 * General Index:: General index
13087 @appendixsec Macro Index
13091 @node Variable Index
13092 @appendixsec Variable Index
13096 @node General Index
13097 @appendixsec General Index
13104 @c LocalWords: texinfo setfilename settitle setchapternewpage texi direntry
13105 @c LocalWords: dircategory in's aclocal ifinfo titlepage Tromey vskip pt sp
13106 @c LocalWords: filll defcodeindex ov cv op tr syncodeindex fn cp vr ifnottex
13107 @c LocalWords: dir Automake's ac Dist Gnits gnits cygnus dfn Autoconf's pxref
13108 @c LocalWords: cindex Autoconf autoconf perl samp cvs dist trindex SUBST foo
13109 @c LocalWords: xs emph FIXME ref vindex pkglibdir pkgincludedir pkgdatadir mt
13110 @c LocalWords: pkg libdir cpio bindir sbindir rmt pax sbin zar zardir acindex
13111 @c LocalWords: HTML htmldir html noinst TEXINFOS nodist nobase strudel CFLAGS
13112 @c LocalWords: libmumble CC YFLAGS itemx de fication config url comp
13113 @c LocalWords: depcomp elisp sh mdate mkinstalldirs mkdir py tex dvi ps pdf
13114 @c LocalWords: ylwrap zardoz INIT gettext acinclude mv FUNCS LIBOBJS LDADD fr
13115 @c LocalWords: uref featureful dnl src LINGUAS es ko nl pl sl sv PROG ISC doc
13116 @c LocalWords: POSIX STDC fcntl FUNC ALLOCA blksize struct stat intl po chmod
13117 @c LocalWords: ChangeLog SUBDIRS gettextize gpl testdata getopt INTLLIBS cpp
13118 @c LocalWords: localedir datadir DLOCALEDIR DEXIT CPPFLAGS autoreconf opindex
13119 @c LocalWords: AUX var symlink deps Wno Wnone package's aclocal's distclean
13120 @c LocalWords: ltmain xref LIBSOURCE LIBSOURCES LIBOBJ MEMCMP vs RANLIB CXX
13121 @c LocalWords: LDFLAGS LIBTOOL libtool XTRA LIBS gettext's acdir APIVERSION
13122 @c LocalWords: dirlist noindent usr TIOCGWINSZ sc
13123 @c LocalWords: GWINSZ termios SRCDIR tarball bzip LISPDIR lispdir XEmacs CCAS
13124 @c LocalWords: emacsen MicroEmacs CCASFLAGS UX GCJ gcj GCJFLAGS posix DMALLOC
13125 @c LocalWords: dmalloc ldmalloc REGEX regex DEPDIR DEP DEFUN aclocaldir fi
13126 @c LocalWords: mymacro myothermacro AMFLAGS autopoint autogen libtoolize yum
13127 @c LocalWords: autoheader README MAKEFLAGS subdir Inetutils sync COND endif
13128 @c LocalWords: Miller's installable includedir inc pkgdata EXEEXT libexec bsd
13129 @c LocalWords: pkglib libexecdir prog libcpio cpio's dlopen dlpreopen linux
13130 @c LocalWords: subsubsection OBJEXT esac lib LTLIBRARIES liblob LIBADD AR ar
13131 @c LocalWords: ARFLAGS cru ing maude libgettext lo LTLIBOBJS rpath SGI PRE yy
13132 @c LocalWords: libmaude CCLD CXXFLAGS FFLAGS LFLAGS OBJCFLAGS RFLAGS DEFS cc
13133 @c LocalWords: SHORTNAME vtable srcdir nostdinc basename yxx cxx ll lxx gdb
13134 @c LocalWords: lexers yymaxdepth maxdepth yyparse yylex yyerror yylval lval
13135 @c LocalWords: yychar yydebug yypact yyr yydef def yychk chk yypgo pgo yyact
13136 @c LocalWords: yyexca exca yyerrflag errflag yynerrs nerrs yyps yypv pv yys
13137 @c LocalWords: yystate yytmp tmp yyv yyval val yylloc lloc yyreds yytoks toks
13138 @c LocalWords: yylhs yylen yydefred yydgoto yysindex yyrindex yygindex yyname
13139 @c LocalWords: yytable yycheck yyrule byacc CXXCOMPILE CXXLINK FLINK cfortran
13140 @c LocalWords: Catalogue preprocessable FLIBS libfoo baz JAVACFLAGS java exe
13141 @c LocalWords: SunOS fying basenames exeext uninstalled oldinclude kr FSF's
13142 @c LocalWords: pkginclude oldincludedir sysconf sharedstate localstate gcc rm
13143 @c LocalWords: sysconfdir sharedstatedir localstatedir preexist CLEANFILES gz
13144 @c LocalWords: depfile tmpdepfile depmode const interoperate
13145 @c LocalWords: JAVAC javac JAVAROOT builddir CLASSPATH ENV pyc pyo pkgpython
13146 @c LocalWords: pyexecdir pkgpyexecdir Python's pythondir pkgpythondir txi ois
13147 @c LocalWords: installinfo vers MAKEINFO makeinfo MAKEINFOFLAGS noinstall rf
13148 @c LocalWords: mandir thesame alsothesame installman myexecbin DESTDIR Pinard
13149 @c LocalWords: uninstall installdirs uninstalls MOSTLYCLEANFILES mostlyclean
13150 @c LocalWords: DISTCLEANFILES MAINTAINERCLEANFILES GZIP gzip shar exp
13151 @c LocalWords: distdir distcheck distcleancheck listfiles distuninstallcheck
13152 @c LocalWords: VPATH tarfile stdout XFAIL DejaGnu dejagnu DEJATOOL runtest ln
13153 @c LocalWords: RUNTESTDEFAULTFLAGS toolchain RUNTESTFLAGS asis readme DVIPS
13154 @c LocalWords: installcheck gzipped tarZ std utils etags mkid cd
13155 @c LocalWords: ARGS taggable ETAGSFLAGS lang ctags CTAGSFLAGS GTAGS gtags idl
13156 @c LocalWords: foocc doit idlC multilibs ABIs cmindex defmac ARG enableval FC
13157 @c LocalWords: MSG xtrue DBG pathchk CYGWIN afile proglink versioned CVS's TE
13158 @c LocalWords: wildcards Autoconfiscated subsubheading autotools Meyering API
13159 @c LocalWords: ois's wildcard Wportability cartouche vrindex printindex Duret
13160 @c LocalWords: DSOMEFLAG DVERSION automake Lutz insertcopying versioning FAQ
13161 @c LocalWords: LTLIBOBJ Libtool's libtool's libltdl dlopening itutions libbar
13162 @c LocalWords: WANTEDLIBS libhello sublibraries libtop libsub dlopened Ratfor
13163 @c LocalWords: mymodule timestamps timestamp underquoted MAKEINFOHTMLFLAGS te
13164 @c LocalWords: GNUmakefile Subpackages subpackage's subpackages aux
13165 @c LocalWords: detailmenu Timeline pwd reldir AUTOM autom PREREQ FOOBAR libc
13166 @c LocalWords: libhand subpackage moduleN libmain libmisc FCFLAGS FCCOMPILE
13167 @c LocalWords: FCLINK subst sed ELCFILES elc MAKEINFOHTML dvips esyscmd ustar
13168 @c LocalWords: tarballs Woverride vfi ELFILES djm AutoMake honkin FSF
13169 @c LocalWords: fileutils precanned MacKenzie's reimplement termutils Tromey's
13170 @c LocalWords: cois gnitsians LIBPROGRAMS progs LIBLIBRARIES Textutils Ulrich
13171 @c LocalWords: Matzigkeit Drepper's Gord Matzigkeit's jm Dalley Debian org
13172 @c LocalWords: Administrivia ILU CORBA Sourceware Molenda sourceware Elliston
13173 @c LocalWords: dep Oliva Akim Demaille Aiieeee Demaillator Akim's sourcequake
13174 @c LocalWords: grep backported screenshots libgcj KB unnumberedsubsubsec pre
13175 @c LocalWords: precomputing hacky makedepend inline clearmake LD PRELOAD Rel
13176 @c LocalWords: syscalls perlhist acl pm multitable headitem fdl appendixsec
13177 @c LocalWords: LTALLOCA MALLOC malloc memcmp strdup alloca libcompat xyz DFOO
13178 @c LocalWords: unprefixed buildable preprocessed DBAZ DDATADIR WARNINGCFLAGS
13179 @c LocalWords: LIBFOOCFLAGS LIBFOOLDFLAGS ftable testSubDir obj LIBTOOLFLAGS
13180 @c LocalWords: barexec Pinard's automatize initialize lzip xz cscope