1 \input texinfo @c -*-texinfo-*-
3 @setfilename automake.info
12 This manual is for @acronym{GNU} Automake (version @value{VERSION},
13 @value{UPDATED}), a program that creates GNU standards-compliant
14 Makefiles from template files.
16 Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
17 2003, 2004, 2005 Free Software Foundation, Inc.
20 Permission is granted to copy, distribute and/or modify this document
21 under the terms of the @acronym{GNU} Free Documentation License,
22 Version 1.2 or any later version published by the Free Software
23 Foundation; with no Invariant Sections, with the Front-Cover texts
24 being ``A @acronym{GNU} Manual,'' and with the Back-Cover Texts as in
25 (a) below. A copy of the license is included in the section entitled
26 ``@acronym{GNU} Free Documentation License.''
28 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and
29 modify this @acronym{GNU} Manual, like @acronym{GNU} software. Copies
30 published by the Free Software Foundation raise funds for
31 @acronym{GNU} development.''
35 @c info Automake points to the Automake package's documentation
36 @c info automake points to the automake script's documentation
37 @c (Autoconf has a similar setup.)
38 @dircategory Software development
40 * Automake: (automake). Making GNU standards-compliant Makefiles.
43 @dircategory Individual utilities
45 * aclocal: (automake)Invoking aclocal. Generating aclocal.m4.
46 * automake: (automake)Invoking automake. Generating Makefile.in.
51 @subtitle For version @value{VERSION}, @value{UPDATED}
52 @author David MacKenzie
54 @author Alexandre Duret-Lutz
56 @vskip 0pt plus 1filll
60 @c Define an index of configure macros.
62 @c Define an index of options.
64 @c Define an index of targets.
66 @c Define an index of commands.
69 @c Put the macros in the function index.
72 @c Put everything else into one index (arbitrarily chosen to be the concept index).
79 @comment node-name, next, previous, up
85 * Introduction:: Automake's purpose
86 * Generalities:: General ideas
87 * Examples:: Some example packages
88 * Invoking Automake:: Creating a Makefile.in
89 * configure:: Scanning configure.ac or configure.in
90 * Directories:: Declaring subdirectories
91 * Programs:: Building programs and libraries
92 * Other objects:: Other derived objects
93 * Other GNU Tools:: Other GNU Tools
94 * Documentation:: Building documentation
95 * Install:: What gets installed
96 * Clean:: What gets cleaned
97 * Dist:: What goes in a distribution
98 * Tests:: Support for test suites
99 * Rebuilding:: Automatic rebuilding of Makefile
100 * Options:: Changing Automake's behavior
101 * Miscellaneous:: Miscellaneous rules
102 * Include:: Including extra files in an Automake template.
103 * Conditionals:: Conditionals
104 * Gnits:: The effect of @option{--gnu} and @option{--gnits}
105 * Cygnus:: The effect of @option{--cygnus}
106 * Not Enough:: When Automake is not Enough
107 * Distributing:: Distributing the Makefile.in
108 * API versioning:: About compatibility between Automake versions
109 * Upgrading:: Upgrading to a Newer Automake Version
110 * FAQ:: Frequently Asked Questions
111 * History:: Notes about the history of Automake
112 * Copying This Manual:: How to make copies of this manual
113 * Indices:: Indices of variables, macros, and concepts
116 --- The Detailed Node Listing ---
120 * General Operation:: General operation of Automake
121 * Strictness:: Standards conformance checking
122 * Uniform:: The Uniform Naming Scheme
123 * Canonicalization:: How derived variables are named
124 * User Variables:: Variables reserved for the user
125 * Auxiliary Programs:: Programs automake might require
127 Some example packages
129 * Complete:: A simple example, start to finish
130 * Hello:: A classic program
131 * true:: Building true and false
133 Scanning @file{configure.ac}
135 * Requirements:: Configuration requirements
136 * Optional:: Other things Automake recognizes
137 * Invoking aclocal:: Auto-generating aclocal.m4
138 * Macros:: Autoconf macros supplied with Automake
140 Auto-generating aclocal.m4
142 * aclocal options:: Options supported by aclocal
143 * Macro search path:: How aclocal finds .m4 files
144 * Extending aclocal:: Writing your own aclocal macros
145 * Local Macros:: Organizing local macros
146 * Serials:: Serial lines in Autoconf macros
147 * Future of aclocal:: aclocal's scheduled death
149 Autoconf macros supplied with Automake
151 * Public macros:: Macros that you can use.
152 * Obsolete macros:: Macros that you should stop using.
153 * Private macros:: Macros that you should not use.
157 * Subdirectories:: Building subdirectories recursively
158 * Conditional Subdirectories:: Conditionally not building directories
159 * Alternative:: Subdirectories without recursion
160 * Subpackages:: Nesting packages
162 Building Programs and Libraries
164 * A Program:: Building a program
165 * A Library:: Building a library
166 * A Shared Library:: Building a Libtool library
167 * Program and Library Variables:: Variables controlling program and
169 * Default _SOURCES:: Default source files
170 * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
171 * Program variables:: Variables used when building a program
172 * Yacc and Lex:: Yacc and Lex support
173 * C++ Support:: Compiling C++ sources
174 * Assembly Support:: Compiling assembly sources
175 * Fortran 77 Support:: Compiling Fortran 77 sources
176 * Fortran 9x Support:: Compiling Fortran 9x sources
177 * Java Support:: Compiling Java sources
178 * Support for Other Languages:: Compiling other languages
179 * ANSI:: Automatic de-ANSI-fication
180 * Dependencies:: Automatic dependency tracking
181 * EXEEXT:: Support for executable extensions
185 * Program Sources:: Defining program sources
186 * Linking:: Linking with libraries or extra objects
187 * Conditional Sources:: Handling conditional sources
188 * Conditional Programs:: Building program conditionally
190 Building a Shared Library
192 * Libtool Concept:: Introducing Libtool
193 * Libtool Libraries:: Declaring Libtool Libraries
194 * Conditional Libtool Libraries:: Building Libtool Libraries Conditionally
195 * Conditional Libtool Sources:: Choosing Library Sources Conditionally
196 * Libtool Convenience Libraries:: Building Convenience Libtool Libraries
197 * Libtool Modules:: Building Libtool Modules
198 * Libtool Flags:: Using _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS
199 * LTLIBOBJS:: Using $(LTLIBOBJS) and $(LTALLOCA)
200 * Libtool Issues:: Common Issues Related to Libtool's Use
204 * Preprocessing Fortran 77:: Preprocessing Fortran 77 sources
205 * Compiling Fortran 77 Files:: Compiling Fortran 77 sources
206 * Mixing Fortran 77 With C and C++:: Mixing Fortran 77 With C and C++
208 Mixing Fortran 77 With C and C++
210 * How the Linker is Chosen:: Automatic linker selection
214 * Compiling Fortran 9x Files:: Compiling Fortran 9x sources
216 Other Derived Objects
218 * Scripts:: Executable scripts
219 * Headers:: Header files
220 * Data:: Architecture-independent data files
221 * Sources:: Derived sources
225 * Built sources example:: Several ways to handle built sources.
229 * Emacs Lisp:: Emacs Lisp
235 Building documentation
238 * Man pages:: Man pages
242 * Tags:: Interfacing to etags and mkid
243 * Suffixes:: Handling new file extensions
244 * Multilibs:: Support for multilibs.
246 When Automake Isn't Enough
248 * Extending:: Adding new rules or overriding existing ones.
249 * Third-Party Makefiles:: Integrating Non-Automake @file{Makefile}s.
251 Frequently Asked Questions about Automake
253 * CVS:: CVS and generated files
254 * maintainer-mode:: missing and AM_MAINTAINER_MODE
255 * wildcards:: Why doesn't Automake support wildcards?
256 * limitations on file names:: Limitations on source and installed file names
257 * distcleancheck:: Files left in build directory after distclean
258 * Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS
259 * renamed objects:: Why are object files sometimes renamed?
260 * Per-Object Flags:: How to simulate per-object flags?
261 * Multiple Outputs:: Writing rules for tools with many output files
262 * Hard-Coded Install Paths:: Installing to Hard-Coded Locations
266 * Timeline:: The Automake story.
267 * Dependency Tracking Evolution:: Evolution of Automatic Dependency Tracking
268 * Releases:: Statistics about Automake Releases
272 * GNU Free Documentation License:: License for copying this manual
276 * Macro Index:: Index of Autoconf macros
277 * Variable Index:: Index of Makefile variables
278 * General Index:: General index
287 @chapter Introduction
289 Automake is a tool for automatically generating @file{Makefile.in}s from
290 files called @file{Makefile.am}. Each @file{Makefile.am} is basically a
291 series of @command{make} variable definitions@footnote{These variables are
292 also called @dfn{make macros} in Make terminology, however in this
293 manual we reserve the term @dfn{macro} for Autoconf's macros.}, with
294 rules being thrown in occasionally. The generated @file{Makefile.in}s
295 are compliant with the GNU Makefile standards.
297 @cindex GNU Makefile standards
299 The GNU Makefile Standards Document
300 (@pxref{Makefile Conventions, , , standards, The GNU Coding Standards})
301 is long, complicated, and subject to change. The goal of Automake is to
302 remove the burden of Makefile maintenance from the back of the
303 individual GNU maintainer (and put it on the back of the Automake
306 The typical Automake input file is simply a series of variable definitions.
307 Each such file is processed to create a @file{Makefile.in}. There
308 should generally be one @file{Makefile.am} per directory of a project.
310 @cindex Constraints of Automake
311 @cindex Automake constraints
313 Automake does constrain a project in certain ways; for instance, it
314 assumes that the project uses Autoconf (@pxref{Top, , Introduction,
315 autoconf, The Autoconf Manual}), and enforces certain restrictions on
316 the @file{configure.ac} contents@footnote{Older Autoconf versions used
317 @file{configure.in}. Autoconf 2.50 and greater promotes
318 @file{configure.ac} over @file{configure.in}. The rest of this
319 documentation will refer to @file{configure.ac}, but Automake also
320 supports @file{configure.in} for backward compatibility.}.
322 @cindex Automake requirements
323 @cindex Requirements, Automake
325 Automake requires @command{perl} in order to generate the
326 @file{Makefile.in}s. However, the distributions created by Automake are
327 fully GNU standards-compliant, and do not require @command{perl} in order
330 @cindex Bugs, reporting
331 @cindex Reporting bugs
332 @cindex E-mail, bug reports
334 Mail suggestions and bug reports for Automake to
335 @email{bug-automake@@gnu.org}.
339 @chapter General ideas
341 The following sections cover a few basic ideas that will help you
342 understand how Automake works.
345 * General Operation:: General operation of Automake
346 * Strictness:: Standards conformance checking
347 * Uniform:: The Uniform Naming Scheme
348 * Canonicalization:: How derived variables are named
349 * User Variables:: Variables reserved for the user
350 * Auxiliary Programs:: Programs automake might require
354 @node General Operation
355 @section General Operation
357 Automake works by reading a @file{Makefile.am} and generating a
358 @file{Makefile.in}. Certain variables and rules defined in the
359 @file{Makefile.am} instruct Automake to generate more specialized code;
360 for instance, a @code{bin_PROGRAMS} variable definition will cause rules
361 for compiling and linking programs to be generated.
363 @cindex Non-standard targets
364 @cindex @code{cvs-dist}, non-standard example
367 The variable definitions and rules in the @file{Makefile.am} are
368 copied verbatim into the generated file. This allows you to add
369 arbitrary code into the generated @file{Makefile.in}. For instance,
370 the Automake distribution includes a non-standard rule for the
371 @code{cvs-dist} target, which the Automake maintainer uses to make
372 distributions from his source control system.
374 @cindex GNU make extensions
376 Note that most GNU make extensions are not recognized by Automake. Using
377 such extensions in a @file{Makefile.am} will lead to errors or confusing
380 @cindex Append operator
382 A special exception is that the GNU make append operator, @samp{+=}, is
383 supported. This operator appends its right hand argument to the variable
384 specified on the left. Automake will translate the operator into
385 an ordinary @samp{=} operator; @samp{+=} will thus work with any make program.
387 Automake tries to keep comments grouped with any adjoining rules or
388 variable definitions.
390 @cindex Make targets, overriding
391 @cindex Make rules, overriding
392 @cindex Overriding make rules
393 @cindex Overriding make targets
395 A rule defined in @file{Makefile.am} generally overrides any such
396 rule of a similar name that would be automatically generated by
397 @command{automake}. Although this is a supported feature, it is generally
398 best to avoid making use of it, as sometimes the generated rules are
401 @cindex Variables, overriding
402 @cindex Overriding make variables
404 Similarly, a variable defined in @file{Makefile.am} or
405 @code{AC_SUBST}ed from @file{configure.ac} will override any
406 definition of the variable that @command{automake} would ordinarily
407 create. This feature is more often useful than the ability to
408 override a rule. Be warned that many of the variables generated by
409 @command{automake} are considered to be for internal use only, and their
410 names might change in future releases.
412 @cindex Recursive operation of Automake
413 @cindex Automake, recursive operation
414 @cindex Example of recursive operation
416 When examining a variable definition, Automake will recursively examine
417 variables referenced in the definition. For example, if Automake is
418 looking at the content of @code{foo_SOURCES} in this snippet
422 foo_SOURCES = c.c $(xs)
425 it would use the files @file{a.c}, @file{b.c}, and @file{c.c} as the
426 contents of @code{foo_SOURCES}.
428 @cindex @code{##} (special Automake comment)
429 @cindex Special Automake comment
430 @cindex Comment, special to Automake
432 Automake also allows a form of comment that is @emph{not} copied into
433 the output; all lines beginning with @samp{##} (leading spaces allowed)
434 are completely ignored by Automake.
436 It is customary to make the first line of @file{Makefile.am} read:
438 @cindex Makefile.am, first line
439 @cindex First line of Makefile.am
442 ## Process this file with automake to produce Makefile.in
445 @c FIXME discuss putting a copyright into Makefile.am here? I would but
446 @c I don't know quite what to say.
448 @c FIXME document customary ordering of Makefile.am here!
454 @cindex Non-GNU packages
456 While Automake is intended to be used by maintainers of GNU packages, it
457 does make some effort to accommodate those who wish to use it, but do
458 not want to use all the GNU conventions.
460 @cindex Strictness, defined
461 @cindex Strictness, @option{foreign}
462 @cindex @option{foreign} strictness
463 @cindex Strictness, @option{gnu}
464 @cindex @option{gnu} strictness
465 @cindex Strictness, @option{gnits}
466 @cindex @option{gnits} strictness
468 To this end, Automake supports three levels of @dfn{strictness}---the
469 strictness indicating how stringently Automake should check standards
472 The valid strictness levels are:
476 Automake will check for only those things that are absolutely
477 required for proper operations. For instance, whereas GNU standards
478 dictate the existence of a @file{NEWS} file, it will not be required in
479 this mode. The name comes from the fact that Automake is intended to be
480 used for GNU programs; these relaxed rules are not the standard mode of
484 Automake will check---as much as possible---for compliance to the GNU
485 standards for packages. This is the default.
488 Automake will check for compliance to the as-yet-unwritten @dfn{Gnits
489 standards}. These are based on the GNU standards, but are even more
490 detailed. Unless you are a Gnits standards contributor, it is
491 recommended that you avoid this option until such time as the Gnits
492 standard is actually published (which may never happen).
495 @xref{Gnits}, for more information on the precise implications of the
498 Automake also has a special ``cygnus'' mode that is similar to
499 strictness but handled differently. This mode is useful for packages
500 that are put into a ``Cygnus'' style tree (e.g., the GCC tree).
501 @xref{Cygnus}, for more information on this mode.
505 @section The Uniform Naming Scheme
507 @cindex Uniform naming scheme
509 Automake variables generally follow a @dfn{uniform naming scheme} that
510 makes it easy to decide how programs (and other derived objects) are
511 built, and how they are installed. This scheme also supports
512 @command{configure} time determination of what should be built.
514 @cindex @code{_PROGRAMS} primary variable
515 @cindex @code{PROGRAMS} primary variable
516 @cindex Primary variable, @code{PROGRAMS}
517 @cindex Primary variable, defined
520 At @command{make} time, certain variables are used to determine which
521 objects are to be built. The variable names are made of several pieces
522 that are concatenated together.
524 The piece that tells automake what is being built is commonly called
525 the @dfn{primary}. For instance, the primary @code{PROGRAMS} holds a
526 list of programs that are to be compiled and linked.
529 @cindex @code{pkglibdir}, defined
530 @cindex @code{pkgincludedir}, defined
531 @cindex @code{pkgdatadir}, defined
534 @vindex pkgincludedir
537 @cindex @code{PACKAGE}, directory
538 A different set of names is used to decide where the built objects
539 should be installed. These names are prefixes to the primary, and they
540 indicate which standard directory should be used as the installation
541 directory. The standard directory names are given in the GNU standards
542 (@pxref{Directory Variables, , , standards, The GNU Coding Standards}).
543 Automake extends this list with @code{pkglibdir}, @code{pkgincludedir},
544 and @code{pkgdatadir}; these are the same as the non-@samp{pkg}
545 versions, but with @samp{$(PACKAGE)} appended. For instance,
546 @code{pkglibdir} is defined as @samp{$(libdir)/$(PACKAGE)}.
548 @cindex @code{EXTRA_}, prepending
549 For each primary, there is one additional variable named by prepending
550 @samp{EXTRA_} to the primary name. This variable is used to list
551 objects that may or may not be built, depending on what
552 @command{configure} decides. This variable is required because Automake
553 must statically know the entire list of objects that may be built in
554 order to generate a @file{Makefile.in} that will work in all cases.
556 @cindex @code{EXTRA_PROGRAMS}, defined
557 @cindex Example, @code{EXTRA_PROGRAMS}
558 @cindex @command{cpio} example
560 For instance, @command{cpio} decides at configure time which programs
561 should be built. Some of the programs are installed in @code{bindir},
562 and some are installed in @code{sbindir}:
565 EXTRA_PROGRAMS = mt rmt
566 bin_PROGRAMS = cpio pax
567 sbin_PROGRAMS = $(MORE_PROGRAMS)
570 Defining a primary without a prefix as a variable, e.g.,
571 @samp{PROGRAMS}, is an error.
573 Note that the common @samp{dir} suffix is left off when constructing the
574 variable names; thus one writes @samp{bin_PROGRAMS} and not
575 @samp{bindir_PROGRAMS}.
577 Not every sort of object can be installed in every directory. Automake
578 will flag those attempts it finds in error.
579 Automake will also diagnose obvious misspellings in directory names.
581 @cindex Extending list of installation directories
582 @cindex Installation directories, extending list
584 Sometimes the standard directories---even as augmented by
585 Automake---are not enough. In particular it is sometimes useful, for
586 clarity, to install objects in a subdirectory of some predefined
587 directory. To this end, Automake allows you to extend the list of
588 possible installation directories. A given prefix (e.g., @samp{zar})
589 is valid if a variable of the same name with @samp{dir} appended is
590 defined (e.g., @samp{zardir}).
592 For instance, the following snippet will install @file{file.xml} into
593 @samp{$(datadir)/xml}.
596 xmldir = $(datadir)/xml
600 @cindex @samp{noinst_} primary prefix, definition
603 The special prefix @samp{noinst_} indicates that the objects in question
604 should be built but not installed at all. This is usually used for
605 objects required to build the rest of your package, for instance static
606 libraries (@pxref{A Library}), or helper scripts.
608 @cindex @samp{check_} primary prefix, definition
611 The special prefix @samp{check_} indicates that the objects in question
612 should not be built until the @samp{make check} command is run. Those
613 objects are not installed either.
615 The current primary names are @samp{PROGRAMS}, @samp{LIBRARIES},
616 @samp{LISP}, @samp{PYTHON}, @samp{JAVA}, @samp{SCRIPTS}, @samp{DATA},
617 @samp{HEADERS}, @samp{MANS}, and @samp{TEXINFOS}.
629 Some primaries also allow additional prefixes that control other
630 aspects of @command{automake}'s behavior. The currently defined prefixes
631 are @samp{dist_}, @samp{nodist_}, and @samp{nobase_}. These prefixes
632 are explained later (@pxref{Program and Library Variables}).
635 @node Canonicalization
636 @section How derived variables are named
638 @cindex canonicalizing Automake variables
640 Sometimes a Makefile variable name is derived from some text the
641 maintainer supplies. For instance, a program name listed in
642 @samp{_PROGRAMS} is rewritten into the name of a @samp{_SOURCES}
643 variable. In cases like this, Automake canonicalizes the text, so that
644 program names and the like do not have to follow Makefile variable naming
645 rules. All characters in the name except for letters, numbers, the
646 strudel (@@), and the underscore are turned into underscores when making
649 For example, if your program is named @file{sniff-glue}, the derived
650 variable name would be @samp{sniff_glue_SOURCES}, not
651 @samp{sniff-glue_SOURCES}. Similarly the sources for a library named
652 @file{libmumble++.a} should be listed in the
653 @samp{libmumble___a_SOURCES} variable.
655 The strudel is an addition, to make the use of Autoconf substitutions in
656 variable names less obfuscating.
660 @section Variables reserved for the user
662 @cindex variables, reserved for the user
663 @cindex user variables
665 Some @file{Makefile} variables are reserved by the GNU Coding Standards
666 for the use of the ``user''---the person building the package. For
667 instance, @code{CFLAGS} is one such variable.
669 Sometimes package developers are tempted to set user variables such as
670 @code{CFLAGS} because it appears to make their job easier. However,
671 the package itself should never set a user variable, particularly not
672 to include switches that are required for proper compilation of the
673 package. Since these variables are documented as being for the
674 package builder, that person rightfully expects to be able to override
675 any of these variables at build time.
677 To get around this problem, Automake introduces an automake-specific
678 shadow variable for each user flag variable. (Shadow variables are
679 not introduced for variables like @code{CC}, where they would make no
680 sense.) The shadow variable is named by prepending @samp{AM_} to the
681 user variable's name. For instance, the shadow variable for
682 @code{YFLAGS} is @code{AM_YFLAGS}. The package maintainer---that is,
683 the author(s) of the @file{Makefile.am} and @file{configure.ac}
684 files---may adjust these shadow variables however necessary.
686 @xref{Flag Variables Ordering}, for more discussion about these
687 variables and how they interact with per-target variables.
689 @node Auxiliary Programs
690 @section Programs automake might require
692 @cindex Programs, auxiliary
693 @cindex Auxiliary programs
695 Automake sometimes requires helper programs so that the generated
696 @file{Makefile} can do its work properly. There are a fairly large
697 number of them, and we list them here.
699 Although all of these files are distributed and installed with
700 Automake, a couple of them are maintained separately. The Automake
701 copies are updated before each release, but we mention the original
702 source in case you need more recent versions.
707 These two files are used by the automatic de-ANSI-fication support
711 This is a wrapper for compilers that do not accept options @option{-c}
712 and @option{-o} at the same time. It is only used when absolutely
713 required. Such compilers are rare.
717 These two programs compute the canonical triplets for the given build,
718 host, or target architecture. These programs are updated regularly to
719 support new architectures and fix probes broken by changes in new
720 kernel versions. Each new release of Automake comes with up-to-date
721 copies of these programs. If your copy of Automake is getting old,
722 you are encouraged to fetch the latest versions of these files from
723 @url{http://savannah.gnu.org/cvs/?group=config} before making a
727 This file is not a program, it is a @file{configure} fragment used for
728 multilib support (@pxref{Multilibs}). This file is maintained in the
729 GCC tree at @url{http://gcc.gnu.org/cvs.html}.
732 This program understands how to run a compiler so that it will
733 generate not only the desired output but also dependency information
734 that is then used by the automatic dependency tracking feature.
737 This program is used to byte-compile Emacs Lisp code.
740 This is a replacement for the @command{install} program that works on
741 platforms where @command{install} is unavailable or unusable.
744 This script is used to generate a @file{version.texi} file. It examines
745 a file and prints some date information about it.
748 This wraps a number of programs that are typically only required by
749 maintainers. If the program in question doesn't exist,
750 @command{missing} prints an informative warning and attempts to fix
751 things so that the build can continue.
754 This script used to be a wrapper around @samp{mkdir -p}, which is not
755 portable. Now we prefer to use @samp{install-sh -d} when configure
756 finds that @samp{mkdir -p} does not work, this makes one less script to
759 For backward compatibility @file{mkinstalldirs} is still used and
760 distributed when @command{automake} finds it in a package. But it is no
761 longer installed automatically, and it should be safe to remove it.
764 This is used to byte-compile Python scripts.
767 This program duplicates a tree of directories, using symbolic links
768 instead of copying files. Such operation is performed when building
769 multilibs (@pxref{Multilibs}). This file is maintained in the GCC
770 tree at @url{http://gcc.gnu.org/cvs.html}.
773 Not a program, this file is required for @samp{make dvi}, @samp{make
774 ps} and @samp{make pdf} to work when Texinfo sources are in the
775 package. The latest version can be downloaded from
776 @url{http://www.gnu.org/software/texinfo/}.
779 This program wraps @command{lex} and @command{yacc} and ensures that,
780 for instance, multiple @command{yacc} instances can be invoked in a
781 single directory in parallel.
787 @chapter Some example packages
790 * Complete:: A simple example, start to finish
791 * Hello:: A classic program
792 * true:: Building true and false
797 @section A simple example, start to finish
799 @cindex Complete example
801 Let's suppose you just finished writing @code{zardoz}, a program to make
802 your head float from vortex to vortex. You've been using Autoconf to
803 provide a portability framework, but your @file{Makefile.in}s have been
804 ad-hoc. You want to make them bulletproof, so you turn to Automake.
806 @cindex @code{AM_INIT_AUTOMAKE}, example use
808 The first step is to update your @file{configure.ac} to include the
809 commands that @command{automake} needs. The way to do this is to add an
810 @code{AM_INIT_AUTOMAKE} call just after @code{AC_INIT}:
818 Since your program doesn't have any complicating factors (e.g., it
819 doesn't use @code{gettext}, it doesn't want to build a shared library),
820 you're done with this part. That was easy!
822 @cindex @command{aclocal} program, introduction
823 @cindex @file{aclocal.m4}, preexisting
824 @cindex @file{acinclude.m4}, defined
826 Now you must regenerate @file{configure}. But to do that, you'll need
827 to tell @command{autoconf} how to find the new macro you've used. The
828 easiest way to do this is to use the @command{aclocal} program to
829 generate your @file{aclocal.m4} for you. But wait@dots{} maybe you
830 already have an @file{aclocal.m4}, because you had to write some hairy
831 macros for your program. The @command{aclocal} program lets you put
832 your own macros into @file{acinclude.m4}, so simply rename and then
836 mv aclocal.m4 acinclude.m4
841 @cindex @command{zardoz} example
843 Now it is time to write your @file{Makefile.am} for @code{zardoz}.
844 Since @code{zardoz} is a user program, you want to install it where the
845 rest of the user programs go: @code{bindir}. Additionally,
846 @code{zardoz} has some Texinfo documentation. Your @file{configure.ac}
847 script uses @code{AC_REPLACE_FUNCS}, so you need to link against
848 @samp{$(LIBOBJS)}. So here's what you'd write:
851 bin_PROGRAMS = zardoz
852 zardoz_SOURCES = main.c head.c float.c vortex9.c gun.c
853 zardoz_LDADD = $(LIBOBJS)
855 info_TEXINFOS = zardoz.texi
858 Now you can run @samp{automake --add-missing} to generate your
859 @file{Makefile.in} and grab any auxiliary files you might need, and
864 @section A classic program
866 @cindex Example, GNU Hello
867 @cindex Hello example
868 @cindex GNU Hello, example
870 @uref{ftp://prep.ai.mit.edu/pub/gnu/hello-1.3.tar.gz, GNU hello} is
871 renowned for its classic simplicity and versatility. This section shows
872 how Automake could be used with the GNU Hello package. The examples
873 below are from the latest beta version of GNU Hello, but with all of the
874 maintainer-only code stripped out, as well as all copyright comments.
876 Of course, GNU Hello is somewhat more featureful than your traditional
877 two-liner. GNU Hello is internationalized, does option processing, and
878 has a manual and a test suite.
880 @cindex @file{configure.ac}, from GNU Hello
881 @cindex GNU Hello, @file{configure.ac}
882 @cindex Hello, @file{configure.ac}
884 Here is the @file{configure.ac} from GNU Hello.
885 @strong{Please note:} The calls to @code{AC_INIT} and @code{AM_INIT_AUTOMAKE}
886 in this example use a deprecated syntax. For the current approach,
887 see the description of @code{AM_INIT_AUTOMAKE} in @ref{Public macros}.
889 @c FIXME: This definitely requires an update, e.g., to GNU Hello 2.1.1.
892 dnl Process this file with autoconf to produce a configure script.
894 AM_INIT_AUTOMAKE(hello, 1.3.11)
895 AM_CONFIG_HEADER(config.h)
897 dnl Set of available languages.
898 ALL_LINGUAS="de fr es ko nl no pl pt sl sv"
900 dnl Checks for programs.
904 dnl Checks for libraries.
906 dnl Checks for header files.
908 AC_HAVE_HEADERS(string.h fcntl.h sys/file.h sys/param.h)
910 dnl Checks for library functions.
913 dnl Check for st_blksize in struct stat
916 dnl internationalization macros
918 AC_OUTPUT([Makefile doc/Makefile intl/Makefile po/Makefile.in \
919 src/Makefile tests/Makefile tests/hello],
920 [chmod +x tests/hello])
923 The @samp{AM_} macros are provided by Automake (or the Gettext library);
924 the rest are standard Autoconf macros.
927 The top-level @file{Makefile.am}:
930 EXTRA_DIST = BUGS ChangeLog.O
931 SUBDIRS = doc intl po src tests
934 As you can see, all the work here is really done in subdirectories.
936 The @file{po} and @file{intl} directories are automatically generated
937 using @command{gettextize}; they will not be discussed here.
939 @cindex Texinfo file handling example
940 @cindex Example, handling Texinfo files
942 In @file{doc/Makefile.am} we see:
945 info_TEXINFOS = hello.texi
946 hello_TEXINFOS = gpl.texi
949 This is sufficient to build, install, and distribute the GNU Hello
952 @cindex Regression test example
953 @cindex Example, regression test
955 Here is @file{tests/Makefile.am}:
959 EXTRA_DIST = hello.in testdata
962 The script @file{hello} is generated by @command{configure}, and is the
963 only test case. @samp{make check} will run this test.
965 @cindex @code{INCLUDES}, example usage
968 Last we have @file{src/Makefile.am}, where all the real work is done:
969 @c FIXME: As all the Hello World excerpts in this manual, this
970 @c shows deprecated features (here: $(INCLUDES)).
974 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
975 hello_LDADD = $(INTLLIBS) $(ALLOCA)
976 localedir = $(datadir)/locale
977 INCLUDES = -I../intl -DLOCALEDIR=\"$(localedir)\"
982 @section Building true and false
984 @cindex Example, @command{false} and @command{true}
985 @cindex @command{false} Example
986 @cindex @command{true} Example
988 Here is another, trickier example. It shows how to generate two
989 programs (@code{true} and @code{false}) from the same source file
990 (@file{true.c}). The difficult part is that each compilation of
991 @file{true.c} requires different @code{cpp} flags.
994 bin_PROGRAMS = true false
996 false_LDADD = false.o
999 $(COMPILE) -DEXIT_CODE=0 -c true.c
1002 $(COMPILE) -DEXIT_CODE=1 -o false.o -c true.c
1005 Note that there is no @code{true_SOURCES} definition. Automake will
1006 implicitly assume that there is a source file named @file{true.c}, and
1007 define rules to compile @file{true.o} and link @file{true}. The
1008 @samp{true.o: true.c} rule supplied by the above @file{Makefile.am},
1009 will override the Automake generated rule to build @file{true.o}.
1011 @code{false_SOURCES} is defined to be empty---that way no implicit value
1012 is substituted. Because we have not listed the source of
1013 @file{false}, we have to tell Automake how to link the program. This is
1014 the purpose of the @code{false_LDADD} line. A @code{false_DEPENDENCIES}
1015 variable, holding the dependencies of the @file{false} target will be
1016 automatically generated by Automake from the content of
1019 The above rules won't work if your compiler doesn't accept both
1020 @option{-c} and @option{-o}. The simplest fix for this is to introduce a
1021 bogus dependency (to avoid problems with a parallel @command{make}):
1024 true.o: true.c false.o
1025 $(COMPILE) -DEXIT_CODE=0 -c true.c
1028 $(COMPILE) -DEXIT_CODE=1 -c true.c && mv true.o false.o
1031 Also, these explicit rules do not work if the de-ANSI-fication feature
1032 is used (@pxref{ANSI}). Supporting de-ANSI-fication requires a little
1036 true_.o: true_.c false_.o
1037 $(COMPILE) -DEXIT_CODE=0 -c true_.c
1040 $(COMPILE) -DEXIT_CODE=1 -c true_.c && mv true_.o false_.o
1043 As it turns out, there is also a much easier way to do this same task.
1044 Some of the above techniques are useful enough that we've kept the
1045 example in the manual. However if you were to build @code{true} and
1046 @code{false} in real life, you would probably use per-program
1047 compilation flags, like so:
1050 bin_PROGRAMS = false true
1052 false_SOURCES = true.c
1053 false_CPPFLAGS = -DEXIT_CODE=1
1055 true_SOURCES = true.c
1056 true_CPPFLAGS = -DEXIT_CODE=0
1059 In this case Automake will cause @file{true.c} to be compiled twice,
1060 with different flags. De-ANSI-fication will work automatically. In
1061 this instance, the names of the object files would be chosen by
1062 automake; they would be @file{false-true.o} and @file{true-true.o}.
1063 (The name of the object files rarely matters.)
1066 @node Invoking Automake
1067 @chapter Creating a @file{Makefile.in}
1069 @cindex Multiple @file{configure.ac} files
1070 @cindex Invoking @command{automake}
1071 @cindex @command{automake}, invoking
1073 To create all the @file{Makefile.in}s for a package, run the
1074 @command{automake} program in the top level directory, with no
1075 arguments. @command{automake} will automatically find each
1076 appropriate @file{Makefile.am} (by scanning @file{configure.ac};
1077 @pxref{configure}) and generate the corresponding @file{Makefile.in}.
1078 Note that @command{automake} has a rather simplistic view of what
1079 constitutes a package; it assumes that a package has only one
1080 @file{configure.ac}, at the top. If your package has multiple
1081 @file{configure.ac}s, then you must run @command{automake} in each
1082 directory holding a @file{configure.ac}. (Alternatively, you may rely
1083 on Autoconf's @command{autoreconf}, which is able to recurse your
1084 package tree and run @command{automake} where appropriate.)
1086 You can optionally give @command{automake} an argument; @file{.am} is
1087 appended to the argument and the result is used as the name of the
1088 input file. This feature is generally only used to automatically
1089 rebuild an out-of-date @file{Makefile.in}. Note that
1090 @command{automake} must always be run from the topmost directory of a
1091 project, even if being used to regenerate the @file{Makefile.in} in
1092 some subdirectory. This is necessary because @command{automake} must
1093 scan @file{configure.ac}, and because @command{automake} uses the
1094 knowledge that a @file{Makefile.in} is in a subdirectory to change its
1095 behavior in some cases.
1098 Automake will run @command{autoconf} to scan @file{configure.ac} and
1099 its dependencies (i.e., @file{aclocal.m4} and any included file),
1100 therefore @command{autoconf} must be in your @env{PATH}. If there is
1101 an @env{AUTOCONF} variable in your environment it will be used
1102 instead of @command{autoconf}, this allows you to select a particular
1103 version of Autoconf. By the way, don't misunderstand this paragraph:
1104 @command{automake} runs @command{autoconf} to @strong{scan} your
1105 @file{configure.ac}, this won't build @file{configure} and you still
1106 have to run @command{autoconf} yourself for this purpose.
1108 @cindex @command{automake} options
1109 @cindex Options, @command{automake}
1110 @cindex Strictness, command line
1112 @command{automake} accepts the following options:
1114 @cindex Extra files distributed with Automake
1115 @cindex Files distributed with Automake
1116 @cindex @file{config.guess}
1120 @itemx --add-missing
1122 @opindex --add-missing
1123 Automake requires certain common files to exist in certain situations;
1124 for instance, @file{config.guess} is required if @file{configure.ac} runs
1125 @code{AC_CANONICAL_HOST}. Automake is distributed with several of these
1126 files (@pxref{Auxiliary Programs}); this option will cause the missing
1127 ones to be automatically added to the package, whenever possible. In
1128 general if Automake tells you a file is missing, try using this option.
1129 By default Automake tries to make a symbolic link pointing to its own
1130 copy of the missing file; this can be changed with @option{--copy}.
1132 Many of the potentially-missing files are common scripts whose
1133 location may be specified via the @code{AC_CONFIG_AUX_DIR} macro.
1134 Therefore, @code{AC_CONFIG_AUX_DIR}'s setting affects whether a
1135 file is considered missing, and where the missing file is added
1138 @item --libdir=@var{dir}
1140 Look for Automake data files in directory @var{dir} instead of in the
1141 installation directory. This is typically used for debugging.
1147 When used with @option{--add-missing}, causes installed files to be
1148 copied. The default is to make a symbolic link.
1152 Causes the generated @file{Makefile.in}s to follow Cygnus rules, instead
1153 of GNU or Gnits rules. For more information, see @ref{Cygnus}.
1157 @itemx --force-missing
1158 @opindex --force-missing
1159 When used with @option{--add-missing}, causes standard files to be reinstalled
1160 even if they already exist in the source tree. This involves removing
1161 the file from the source tree before creating the new symlink (or, with
1162 @option{--copy}, copying the new file).
1166 Set the global strictness to @option{foreign}. For more information, see
1171 Set the global strictness to @option{gnits}. For more information, see
1176 Set the global strictness to @option{gnu}. For more information, see
1177 @ref{Gnits}. This is the default strictness.
1181 Print a summary of the command line options and exit.
1184 @itemx --ignore-deps
1186 This disables the dependency tracking feature in generated
1187 @file{Makefile}s; see @ref{Dependencies}.
1189 @item --include-deps
1190 @opindex --include-deps
1191 This enables the dependency tracking feature. This feature is enabled
1192 by default. This option is provided for historical reasons only and
1193 probably should not be used.
1197 Ordinarily @command{automake} creates all @file{Makefile.in}s mentioned in
1198 @file{configure.ac}. This option causes it to only update those
1199 @file{Makefile.in}s that are out of date with respect to one of their
1203 @itemx --output-dir=@var{dir}
1205 @opindex --output-dir
1206 Put the generated @file{Makefile.in} in the directory @var{dir}.
1207 Ordinarily each @file{Makefile.in} is created in the directory of the
1208 corresponding @file{Makefile.am}. This option is deprecated and will be
1209 removed in a future release.
1215 Cause Automake to print information about which files are being read or
1220 Print the version number of Automake and exit.
1223 @item --warnings=@var{category}
1226 Output warnings falling in @var{category}. @var{category} can be
1230 warnings related to the GNU Coding Standards
1231 (@pxref{Top, , , standards, The GNU Coding Standards}).
1233 obsolete features or constructions
1235 user redefinitions of Automake rules or variables
1237 portability issues (e.g., use of @command{make} features that are
1238 known to be not portable)
1240 weird syntax, unused variables, typos
1242 unsupported or incomplete features
1246 turn off all the warnings
1248 treat warnings as errors
1251 A category can be turned off by prefixing its name with @samp{no-}. For
1252 instance, @option{-Wno-syntax} will hide the warnings about unused
1255 The categories output by default are @samp{syntax} and
1256 @samp{unsupported}. Additionally, @samp{gnu} is enabled in @option{--gnu} and
1257 @option{--gnits} strictness.
1259 @samp{portability} warnings are currently disabled by default, but they
1260 will be enabled in @option{--gnu} and @option{--gnits} strictness in a
1264 The environment variable @env{WARNINGS} can contain a comma separated
1265 list of categories to enable. It will be taken into account before the
1266 command-line switches, this way @option{-Wnone} will also ignore any
1267 warning category enabled by @env{WARNINGS}. This variable is also used
1268 by other tools like @command{autoconf}; unknown categories are ignored
1275 @chapter Scanning @file{configure.ac}
1277 @cindex @file{configure.ac}, scanning
1278 @cindex Scanning @file{configure.ac}
1280 Automake scans the package's @file{configure.ac} to determine certain
1281 information about the package. Some @command{autoconf} macros are required
1282 and some variables must be defined in @file{configure.ac}. Automake
1283 will also use information from @file{configure.ac} to further tailor its
1286 Automake also supplies some Autoconf macros to make the maintenance
1287 easier. These macros can automatically be put into your
1288 @file{aclocal.m4} using the @command{aclocal} program.
1291 * Requirements:: Configuration requirements
1292 * Optional:: Other things Automake recognizes
1293 * Invoking aclocal:: Auto-generating aclocal.m4
1294 * Macros:: Autoconf macros supplied with Automake
1299 @section Configuration requirements
1301 @cindex Automake requirements
1302 @cindex Requirements of Automake
1304 @acindex AM_INIT_AUTOMAKE
1305 The one real requirement of Automake is that your @file{configure.ac}
1306 call @code{AM_INIT_AUTOMAKE}. This macro does several things that are
1307 required for proper Automake operation (@pxref{Macros}).
1309 Here are the other macros that Automake requires but which are not run
1310 by @code{AM_INIT_AUTOMAKE}:
1313 @item AC_CONFIG_FILES
1315 @acindex AC_CONFIG_FILES
1317 These two macros are usually invoked as follows near the end of
1318 @file{configure.ac}.
1332 Automake uses these to determine which files to create (@pxref{Output, ,
1333 Creating Output Files, autoconf, The Autoconf Manual}). A listed file
1334 is considered to be an Automake generated @file{Makefile} if there
1335 exists a file with the same name and the @file{.am} extension appended.
1336 Typically, @samp{AC_CONFIG_FILES([foo/Makefile])} will cause Automake to
1337 generate @file{foo/Makefile.in} if @file{foo/Makefile.am} exists.
1339 When using @code{AC_CONFIG_FILES} with multiple input files, as in
1342 AC_CONFIG_FILES([Makefile:top.in:Makefile.in:bot.in])
1346 @command{automake} will generate the first @file{.in} input file for
1347 which a @file{.am} file exists. If no such file exists the output
1348 file is not considered to be Automake generated.
1350 Files created by @code{AC_CONFIG_FILES}, be they Automake
1351 @file{Makefile}s or not, are all removed by @samp{make distclean}.
1352 Their inputs are automatically distributed, except for inputs that
1353 turn out the be outputs of prior @code{AC_CONFIG_FILES} commands.
1354 Finally, rebuild rules are generated in the Automake @file{Makefile}
1355 existing in the subdirectory of the output file, if there is one, or
1356 in the top-level @file{Makefile} otherwise.
1358 The above machinery (cleaning, distributing, and rebuilding) works
1359 fine if the @code{AC_CONFIG_FILES} specifications contain only
1360 literals. If part of the specification uses shell variables,
1361 @command{automake} will not be able to fulfil this setup, and you will
1362 have to complete the missing bits by hand. For instance, on
1367 AC_CONFIG_FILES([output:$file],, [file=$file])
1371 @command{automake} will output rules to clean @file{output}, and
1372 rebuild it. However the rebuild rule will not depend on @file{input},
1373 and this file will not be distributed either. (You must add
1374 @samp{EXTRA_DIST = input} to your @file{Makefile} if @file{input} is a
1383 AC_CONFIG_FILES([$file:input],, [file=$file])
1384 AC_CONFIG_FILES([$file2],, [file2=$file2])
1388 will only cause @file{input} to be distributed. No file will be
1389 cleaned automatically (add @samp{DISTCLEANFILES = output out}
1390 yourself), and no rebuild rule will be output.
1392 Obviously @command{automake} cannot guess what value @samp{$file} is
1393 going to hold later when @file{configure} is run, and it cannot use
1394 the shell variable @samp{$file} in a @file{Makefile}. However, if you
1395 make reference to @samp{$file} as @samp{$@{file@}} (i.e., in a way
1396 that is compatible with @command{make}'s syntax) and furthermore use
1397 @code{AC_SUBST} to ensure that @samp{$@{file@}} is meaningful in a
1398 @file{Makefile}, then @command{automake} will be able to use
1399 @samp{$@{file@}} to generate all these rules. For instance, here is
1400 how the Automake package itself generates versioned scripts for its
1404 AC_SUBST([APIVERSION], @dots{})
1407 [tests/aclocal-$@{APIVERSION@}:tests/aclocal.in],
1408 [chmod +x tests/aclocal-$@{APIVERSION@}],
1409 [APIVERSION=$APIVERSION])
1411 [tests/automake-$@{APIVERSION@}:tests/automake.in],
1412 [chmod +x tests/automake-$@{APIVERSION@}])
1416 Here cleaning, distributing, and rebuilding are done automatically,
1417 because @samp{$@{APIVERSION@}} is known at @command{make}-time.
1419 Note that you should not use shell variables to declare
1420 @file{Makefile} files for which @command{automake} must create
1421 @file{Makefile.in}. Even @code{AC_SUBST} does not help here, because
1422 @command{automake} needs to know the file name when it runs in order
1423 to check whether @file{Makefile.am} exists. (In the very hairy case
1424 that your setup requires such use of variables, you will have to tell
1425 Automake which @file{Makefile.in}s to generate on the command-line.)
1430 Use literals for @file{Makefile}s, and for other files whenever possible.
1432 Use @samp{$file} (or @samp{$@{file@}} without @samp{AC_SUBST([file])})
1433 for files that @command{automake} should ignore.
1435 Use @samp{$@{file@}} and @samp{AC_SUBST([file])} for files
1436 that @command{automake} should not ignore.
1443 @section Other things Automake recognizes
1445 @cindex Macros Automake recognizes
1446 @cindex Recognized macros by Automake
1448 Every time Automake is run it calls Autoconf to trace
1449 @file{configure.ac}. This way it can recognize the use of certain
1450 macros and tailor the generated @file{Makefile.in} appropriately.
1451 Currently recognized macros and their effects are:
1454 @item AC_CANONICAL_BUILD
1455 @itemx AC_CANONICAL_HOST
1456 @itemx AC_CANONICAL_TARGET
1457 @vindex build_triplet
1458 @vindex host_triplet
1459 @vindex target_triplet
1460 Automake will ensure that @file{config.guess} and @file{config.sub}
1461 exist. Also, the @file{Makefile} variables @code{build_triplet},
1462 @code{host_triplet} and @code{target_triplet} are introduced. See
1463 @ref{Canonicalizing, , Getting the Canonical System Type, autoconf,
1464 The Autoconf Manual}.
1466 @item AC_CONFIG_AUX_DIR
1467 Automake will look for various helper scripts, such as
1468 @file{install-sh}, in the directory named in this macro invocation.
1469 @c This list is accurate relative to version 1.8
1470 (The full list of scripts is: @file{config.guess}, @file{config.sub},
1471 @file{depcomp}, @file{elisp-comp}, @file{compile}, @file{install-sh},
1472 @file{ltmain.sh}, @file{mdate-sh}, @file{missing}, @file{mkinstalldirs},
1473 @file{py-compile}, @file{texinfo.tex}, and @file{ylwrap}.) Not all
1474 scripts are always searched for; some scripts will only be sought if the
1475 generated @file{Makefile.in} requires them.
1477 If @code{AC_CONFIG_AUX_DIR} is not given, the scripts are looked for in
1478 their standard locations. For @file{mdate-sh},
1479 @file{texinfo.tex}, and @file{ylwrap}, the standard location is the
1480 source directory corresponding to the current @file{Makefile.am}. For
1481 the rest, the standard location is the first one of @file{.}, @file{..},
1482 or @file{../..} (relative to the top source directory) that provides any
1483 one of the helper scripts. @xref{Input, , Finding `configure' Input,
1484 autoconf, The Autoconf Manual}.
1486 Required files from @code{AC_CONFIG_AUX_DIR} are automatically
1487 distributed, even if there is no @file{Makefile.am} in this directory.
1489 @item AC_CONFIG_LIBOBJ_DIR
1490 Automake will require the sources file declared with
1491 @code{AC_LIBSOURCE} (see below) in the directory specified by this
1494 @item AC_CONFIG_HEADERS
1495 Automake will generate rules to rebuild these headers. Older versions
1496 of Automake required the use of @code{AM_CONFIG_HEADER}
1497 (@pxref{Macros}); this is no longer the case today.
1499 As for @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the
1500 specification using shell variables will be ignored as far as
1501 cleaning, distributing, and rebuilding is concerned.
1503 @item AC_CONFIG_LINKS
1504 Automake will generate rules to remove @file{configure} generated
1505 links on @samp{make distclean} and to distribute named source files as
1506 part of @samp{make dist}.
1508 As for @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the
1509 specification using shell variables will be ignored as far as cleaning
1510 and distributing is concerned. (There is no rebuild rules for links.)
1514 @itemx AC_LIBSOURCES
1516 Automake will automatically distribute any file listed in
1517 @code{AC_LIBSOURCE} or @code{AC_LIBSOURCES}.
1519 Note that the @code{AC_LIBOBJ} macro calls @code{AC_LIBSOURCE}. So if
1520 an Autoconf macro is documented to call @samp{AC_LIBOBJ([file])}, then
1521 @file{file.c} will be distributed automatically by Automake. This
1522 encompasses many macros like @code{AC_FUNC_ALLOCA},
1523 @code{AC_FUNC_MEMCMP}, @code{AC_REPLACE_FUNCS}, and others.
1525 By the way, direct assignments to @code{LIBOBJS} are no longer
1526 supported. You should always use @code{AC_LIBOBJ} for this purpose.
1527 @xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs.@: @code{LIBOBJS},
1528 autoconf, The Autoconf Manual}.
1530 @item AC_PROG_RANLIB
1531 This is required if any libraries are built in the package.
1532 @xref{Particular Programs, , Particular Program Checks, autoconf, The
1536 This is required if any C++ source is included. @xref{Particular
1537 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
1540 This is required if any Fortran 77 source is included. This macro is
1541 distributed with Autoconf version 2.13 and later. @xref{Particular
1542 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
1544 @item AC_F77_LIBRARY_LDFLAGS
1545 This is required for programs and shared libraries that are a mixture of
1546 languages that include Fortran 77 (@pxref{Mixing Fortran 77 With C and
1547 C++}). @xref{Macros, , Autoconf macros supplied with Automake}.
1550 This is required if any Fortran 90/95 source is included. This macro is
1551 distributed with Autoconf version 2.58 and later. @xref{Particular
1552 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
1554 @item AC_PROG_LIBTOOL
1555 Automake will turn on processing for @command{libtool} (@pxref{Top, ,
1556 Introduction, libtool, The Libtool Manual}).
1560 If a Yacc source file is seen, then you must either use this macro or
1561 define the variable @code{YACC} in @file{configure.ac}. The former is
1562 preferred (@pxref{Particular Programs, , Particular Program Checks,
1563 autoconf, The Autoconf Manual}).
1566 If a Lex source file is seen, then this macro must be used.
1567 @xref{Particular Programs, , Particular Program Checks, autoconf, The
1570 @item AC_REQUIRE_AUX_FILE
1571 @command{automake} will ensure each file for which this macro is
1572 called exists in the aux directory, and will complain otherwise. It
1573 will also automatically distribute the file. This macro should be
1574 used by third-party Autoconf macros that requires some supporting
1575 files in the aux directory specified with @code{AC_CONFIG_AUX_DIR}
1576 above. @xref{Input, , Finding @command{configure} Input, autoconf,
1577 The Autoconf Manual}.
1580 The first argument is automatically defined as a variable in each
1581 generated @file{Makefile.in}. @xref{Setting Output Variables, , Setting
1582 Output Variables, autoconf, The Autoconf Manual}.
1584 If the Autoconf manual says that a macro calls @code{AC_SUBST} for
1585 @var{var}, or defines the output variable @var{var} then @var{var} will
1586 be defined in each @file{Makefile.in} generated by Automake.
1587 E.g.@: @code{AC_PATH_XTRA} defines @code{X_CFLAGS} and @code{X_LIBS}, so
1588 you can use these variables in any @file{Makefile.am} if
1589 @code{AC_PATH_XTRA} is called.
1591 @item AM_C_PROTOTYPES
1592 This is required when using automatic de-ANSI-fication; see @ref{ANSI}.
1594 @item AM_GNU_GETTEXT
1595 This macro is required for packages that use GNU gettext
1596 (@pxref{gettext}). It is distributed with gettext. If Automake sees
1597 this macro it ensures that the package meets some of gettext's
1600 @item AM_MAINTAINER_MODE
1601 @opindex --enable-maintainer-mode
1602 This macro adds a @option{--enable-maintainer-mode} option to
1603 @command{configure}. If this is used, @command{automake} will cause
1604 ``maintainer-only'' rules to be turned off by default in the
1605 generated @file{Makefile.in}s. This macro defines the
1606 @code{MAINTAINER_MODE} conditional, which you can use in your own
1607 @file{Makefile.am}. @xref{maintainer-mode}.
1610 Files included by @file{configure.ac} using this macro will be
1611 detected by Automake and automatically distributed. They will also
1612 appear as dependencies in @file{Makefile} rules.
1614 @code{m4_include} is seldom used by @file{configure.ac} authors, but
1615 can appear in @file{aclocal.m4} when @command{aclocal} detects that
1616 some required macros come from files local to your package (as opposed
1617 to macros installed in a system-wide directory, @pxref{Invoking
1623 @node Invoking aclocal
1624 @section Auto-generating aclocal.m4
1626 @cindex Invoking @command{aclocal}
1627 @cindex @command{aclocal}, Invoking
1629 Automake includes a number of Autoconf macros that can be used in
1630 your package (@pxref{Macros}); some of them are actually required by
1631 Automake in certain situations. These macros must be defined in your
1632 @file{aclocal.m4}; otherwise they will not be seen by
1635 The @command{aclocal} program will automatically generate
1636 @file{aclocal.m4} files based on the contents of @file{configure.ac}.
1637 This provides a convenient way to get Automake-provided macros,
1638 without having to search around. The @command{aclocal} mechanism
1639 allows other packages to supply their own macros (@pxref{Extending
1640 aclocal}). You can also use it to maintain your own set of custom
1641 macros (@pxref{Local Macros}).
1643 At startup, @command{aclocal} scans all the @file{.m4} files it can
1644 find, looking for macro definitions (@pxref{Macro search path}). Then
1645 it scans @file{configure.ac}. Any mention of one of the macros found
1646 in the first step causes that macro, and any macros it in turn
1647 requires, to be put into @file{aclocal.m4}.
1649 @emph{Putting} the file that contains the macro definition into
1650 @file{aclocal.m4} is usually done by copying the entire text of this
1651 file, including unused macro definitions as well as both @samp{#} and
1652 @samp{dnl} comments. If you want to make a comment that will be
1653 completely ignored by @command{aclocal}, use @samp{##} as the comment
1656 When a file selected by @command{aclocal} is located in a subdirectory
1657 specified as a relative search path with @command{aclocal}'s @option{-I}
1658 argument, @command{aclocal} assumes the file belongs to the package
1659 and uses @code{m4_include} instead of copying it into
1660 @file{aclocal.m4}. This makes the package smaller, eases dependency
1661 tracking, and cause the file to be distributed automatically.
1662 (@xref{Local Macros}, for an example.) Any macro that is found in a
1663 system-wide directory, or via an absolute search path will be copied.
1664 So use @samp{-I `pwd`/reldir} instead of @samp{-I reldir} whenever
1665 some relative directory need to be considered outside the package.
1667 The contents of @file{acinclude.m4}, if this file exists, are also
1668 automatically included in @file{aclocal.m4}. We recommend against
1669 using @file{acinclude.m4} in new packages (@pxref{Local Macros}).
1673 While computing @file{aclocal.m4}, @command{aclocal} runs
1674 @command{autom4te} (@pxref{Using autom4te, , Using @command{Autom4te},
1675 autoconf, The Autoconf Manual}) in order to trace the macros that are
1676 really used, and omit from @file{aclocal.m4} all macros that are
1677 mentioned but otherwise unexpanded (this can happen when a macro is
1678 called conditionally). @command{autom4te} is expected to be in the
1679 @env{PATH}, just as @command{autoconf}. Its location can be
1680 overridden using the @env{AUTOM4TE} environment variable.
1683 * aclocal options:: Options supported by aclocal
1684 * Macro search path:: How aclocal finds .m4 files
1685 * Extending aclocal:: Writing your own aclocal macros
1686 * Local Macros:: Organizing local macros
1687 * Serials:: Serial lines in Autoconf macros
1688 * Future of aclocal:: aclocal's scheduled death
1691 @node aclocal options
1692 @subsection aclocal options
1694 @cindex @command{aclocal}, Options
1695 @cindex Options, @command{aclocal}
1697 @command{aclocal} accepts the following options:
1700 @item --acdir=@var{dir}
1702 Look for the macro files in @var{dir} instead of the installation
1703 directory. This is typically used for debugging.
1705 @item --diff[=@var{command}]
1707 Run @var{command} on M4 file that would be installed or overwritten
1708 by @option{--install}. The default @var{command} is @samp{diff -u}.
1709 This option implies @option{--install} and @option{--dry-run}.
1713 Do not actually overwrite (or create) @file{aclocal.m4} and M4
1714 files installed by @option{--install}.
1718 Print a summary of the command line options and exit.
1722 Add the directory @var{dir} to the list of directories searched for
1727 Install system-wide third-party macros into the first directory
1728 specified with @samp{-I @var{dir}} instead of copying them in the
1731 @cindex serial number and @option{--install}
1732 When this option is used, and only when this option is used,
1733 @command{aclocal} will also honor @samp{#serial @var{NUMBER}} lines
1734 that appear in macros: an M4 file is ignored if there exists another
1735 M4 file with the same basename and a greater serial number in the
1736 search path (@pxref{Serials}).
1740 Always overwrite the output file. The default is to overwrite the output
1741 file only when really needed, i.e., when its contents changes or if one
1742 of its dependencies is younger.
1744 This option forces the update of @file{aclocal.m4} (or the file
1745 specified with @file{--output} below) and only this file, it has
1746 absolutely no influence on files that may need to be installed by
1749 @item --output=@var{file}
1751 Cause the output to be put into @var{file} instead of @file{aclocal.m4}.
1753 @item --print-ac-dir
1754 @opindex --print-ac-dir
1755 Prints the name of the directory that @command{aclocal} will search to
1756 find third-party @file{.m4} files. When this option is given, normal
1757 processing is suppressed. This option can be used by a package to
1758 determine where to install a macro file.
1762 Print the names of the files it examines.
1766 Print the version number of Automake and exit.
1769 @item --warnings=@var{category}
1772 Output warnings falling in @var{category}. @var{category} can be
1776 dubious syntactic constructs, underquoted macros, unused macros, etc.
1780 all the warnings, this is the default
1782 turn off all the warnings
1784 treat warnings as errors
1787 All warnings are output by default.
1790 The environment variable @env{WARNINGS} is honored in the same
1791 way as it is for @command{automake} (@pxref{Invoking Automake}).
1795 @node Macro search path
1796 @subsection Macro search path
1798 @cindex Macro search path
1799 @cindex @command{aclocal} search path
1801 By default, @command{aclocal} searches for @file{.m4} files in the following
1802 directories, in this order:
1805 @item @var{acdir-APIVERSION}
1806 This is where the @file{.m4} macros distributed with automake itself
1807 are stored. @var{APIVERSION} depends on the automake release used;
1808 for automake 1.6.x, @var{APIVERSION} = @code{1.6}.
1811 This directory is intended for third party @file{.m4} files, and is
1812 configured when @command{automake} itself is built. This is
1813 @file{@@datadir@@/aclocal/}, which typically
1814 expands to @file{$@{prefix@}/share/aclocal/}. To find the compiled-in
1815 value of @var{acdir}, use the @option{--print-ac-dir} option
1816 (@pxref{aclocal options}).
1819 As an example, suppose that @command{automake-1.6.2} was configured with
1820 @option{--prefix=@-/usr/local}. Then, the search path would be:
1823 @item @file{/usr/local/share/aclocal-1.6/}
1824 @item @file{/usr/local/share/aclocal/}
1827 As explained in (@pxref{aclocal options}), there are several options that
1828 can be used to change or extend this search path.
1830 @subsubsection Modifying the macro search path: @option{--acdir}
1832 The most erroneous option to modify the search path is
1833 @option{--acdir=@var{dir}}, which changes default directory and
1834 drops the @var{APIVERSION} directory. For example, if one specifies
1835 @samp{--acdir=/opt/private/}, then the search path becomes:
1838 @item @file{/opt/private/}
1841 This option, @option{--acdir}, is intended for use by the internal
1842 automake test suite only; it is not ordinarily needed by end-users.
1844 @subsubsection Modifying the macro search path: @samp{-I @var{dir}}
1846 Any extra directories specified using @option{-I} options
1847 (@pxref{aclocal options}) are @emph{prepended} to this search list. Thus,
1848 @samp{aclocal -I /foo -I /bar} results in the following search path:
1853 @item @var{acdir}-@var{APIVERSION}
1857 @subsubsection Modifying the macro search path: @file{dirlist}
1858 @cindex @file{dirlist}
1860 There is a third mechanism for customizing the search path. If a
1861 @file{dirlist} file exists in @var{acdir}, then that file is assumed to
1862 contain a list of directories, one per line, to be added to the search
1863 list. These directories are searched @emph{after} all other
1866 For example, suppose
1867 @file{@var{acdir}/dirlist} contains the following:
1875 and that @command{aclocal} was called with the @samp{-I /foo -I /bar} options.
1876 Then, the search path would be
1878 @c @code looks better than @file here
1882 @item @var{acdir}-@var{APIVERSION}
1888 If the @option{--acdir=@var{dir}} option is used, then @command{aclocal}
1889 will search for the @file{dirlist} file in @var{dir}. In the
1890 @samp{--acdir=/opt/private/} example above, @command{aclocal} would look
1891 for @file{/opt/private/dirlist}. Again, however, the @option{--acdir}
1892 option is intended for use by the internal automake test suite only;
1893 @option{--acdir} is not ordinarily needed by end-users.
1895 @file{dirlist} is useful in the following situation: suppose that
1896 @command{automake} version @code{1.6.2} is installed with
1897 @samp{--prefix=/usr} by the system vendor. Thus, the default search
1900 @c @code looks better than @file here
1902 @item @code{/usr/share/aclocal-1.6/}
1903 @item @code{/usr/share/aclocal/}
1906 However, suppose further that many packages have been manually
1907 installed on the system, with $prefix=/usr/local, as is typical. In
1908 that case, many of these ``extra'' @file{.m4} files are in
1909 @file{/usr/local/share/aclocal}. The only way to force
1910 @file{/usr/bin/aclocal} to find these ``extra'' @file{.m4} files is to
1911 always call @samp{aclocal -I /usr/local/share/aclocal}. This is
1912 inconvenient. With @file{dirlist}, one may create a file
1913 @file{/usr/share/aclocal/dirlist} containing only the single line
1916 /usr/local/share/aclocal
1919 Now, the ``default'' search path on the affected system is
1921 @c @code looks better than @file here
1923 @item @code{/usr/share/aclocal-1.6/}
1924 @item @code{/usr/share/aclocal/}
1925 @item @code{/usr/local/share/aclocal/}
1928 without the need for @option{-I} options; @option{-I} options can be reserved
1929 for project-specific needs (@file{my-source-dir/m4/}), rather than
1930 using it to work around local system-dependent tool installation
1933 Similarly, @file{dirlist} can be handy if you have installed a local
1934 copy Automake on your account and want @command{aclocal} to look for
1935 macros installed at other places on the system.
1938 @node Extending aclocal
1939 @subsection Writing your own aclocal macros
1941 @cindex @command{aclocal}, extending
1942 @cindex Extending @command{aclocal}
1944 The @command{aclocal} program doesn't have any built-in knowledge of any
1945 macros, so it is easy to extend it with your own macros.
1947 This can be used by libraries that want to supply their own Autoconf
1948 macros for use by other programs. For instance, the @command{gettext}
1949 library supplies a macro @code{AM_GNU_GETTEXT} that should be used by
1950 any package using @command{gettext}. When the library is installed, it
1951 installs this macro so that @command{aclocal} will find it.
1953 A macro file's name should end in @file{.m4}. Such files should be
1954 installed in @file{$(datadir)/aclocal}. This is as simple as writing:
1957 aclocaldir = $(datadir)/aclocal
1958 aclocal_DATA = mymacro.m4 myothermacro.m4
1962 Please do use @file{$(datadir)/aclocal}, and not something based on
1963 the result of @samp{aclocal --print-ac-dir}. @xref{Hard-Coded Install
1964 Paths}, for arguments.
1966 A file of macros should be a series of properly quoted
1967 @code{AC_DEFUN}'s (@pxref{Macro Definitions, , , autoconf, The
1968 Autoconf Manual}). The @command{aclocal} programs also understands
1969 @code{AC_REQUIRE} (@pxref{Prerequisite Macros, , , autoconf, The
1970 Autoconf Manual}), so it is safe to put each macro in a separate file.
1971 Each file should have no side effects but macro definitions.
1972 Especially, any call to @code{AC_PREREQ} should be done inside the
1973 defined macro, not at the beginning of the file.
1975 @cindex underquoted @code{AC_DEFUN}
1979 Starting with Automake 1.8, @command{aclocal} will warn about all
1980 underquoted calls to @code{AC_DEFUN}. We realize this will annoy a
1981 lot of people, because @command{aclocal} was not so strict in the past
1982 and many third party macros are underquoted; and we have to apologize
1983 for this temporary inconvenience. The reason we have to be stricter
1984 is that a future implementation of @command{aclocal} (@pxref{Future of
1985 aclocal}) will have to temporarily include all these third party
1986 @file{.m4} files, maybe several times, including even files that are
1987 not actually needed. Doing so should alleviate many problems of the
1988 current implementation, however it requires a stricter style from the
1989 macro authors. Hopefully it is easy to revise the existing macros.
1995 [AC_REQUIRE([AX_SOMETHING])dnl
2001 should be rewritten as
2003 AC_DEFUN([AX_FOOBAR],
2005 AC_REQUIRE([AX_SOMETHING])dnl
2011 Wrapping the @code{AC_PREREQ} call inside the macro ensures that
2012 Autoconf 2.57 will not be required if @code{AX_FOOBAR} is not actually
2013 used. Most importantly, quoting the first argument of @code{AC_DEFUN}
2014 allows the macro to be redefined or included twice (otherwise this
2015 first argument would be expanded during the second definition).
2017 If you have been directed here by the @command{aclocal} diagnostic but
2018 are not the maintainer of the implicated macro, you will want to
2019 contact the maintainer of that macro. Please make sure you have the
2020 last version of the macro and that the problem already hasn't been
2021 reported before doing so: people tend to work faster when they aren't
2024 Another situation where @command{aclocal} is commonly used is to
2025 manage macros that are used locally by the package, @ref{Local
2029 @subsection Handling Local Macros
2031 Feature tests offered by Autoconf do not cover all needs. People
2032 often have to supplement existing tests with their own macros, or
2033 with third-party macros.
2035 There are two ways to organize custom macros in a package.
2037 The first possibility (the historical practice) is to list all your
2038 macros in @file{acinclude.m4}. This file will be included in
2039 @file{aclocal.m4} when you run @command{aclocal}, and its macro(s) will
2040 henceforth be visible to @command{autoconf}. However if it contains
2041 numerous macros, it will rapidly become difficult to maintain, and it
2042 will be almost impossible to share macros between packages.
2044 @vindex ACLOCAL_AMFLAGS
2045 The second possibility, which we do recommend, is to write each macro
2046 in its own file and gather all these files in a directory. This
2047 directory is usually called @file{m4/}. To build @file{aclocal.m4},
2048 one should therefore instruct @command{aclocal} to scan @file{m4/}.
2049 From the command line, this is done with @samp{aclocal -I m4}. The
2050 top-level @file{Makefile.am} should also be updated to define
2053 ACLOCAL_AMFLAGS = -I m4
2056 @code{ACLOCAL_AMFLAGS} contains options to pass to @command{aclocal}
2057 when @file{aclocal.m4} is to be rebuilt by @command{make}. This line is
2058 also used by @command{autoreconf} (@pxref{autoreconf Invocation, ,
2059 Using @command{autoreconf} to Update @file{configure} Scripts,
2060 autoconf, The Autoconf Manual}) to run @command{aclocal} with suitable
2061 options, or by @command{autopoint} (@pxref{autopoint Invocation, ,
2062 Invoking the @command{autopoint} Program, gettext, GNU gettext tools})
2063 and @command{gettextize} (@pxref{gettextize Invocation, , Invoking the
2064 @command{gettextize} Program, gettext, GNU gettext tools}) to locate
2065 the place where Gettext's macros should be installed. So even if you
2066 do not really care about the rebuild rules, you should define
2067 @code{ACLOCAL_AMFLAGS}.
2069 When @samp{aclocal -I m4} is run, it will build a @file{aclocal.m4}
2070 that @code{m4_include}s any file from @file{m4/} that defines a
2071 required macro. Macros not found locally will still be searched in
2072 system-wide directories, as explained in @ref{Macro search path}.
2074 Custom macros should be distributed for the same reason that
2075 @file{configure.ac} is: so that other people have all the sources of
2076 your package if they want to work on it. Actually, this distribution
2077 happens automatically because all @code{m4_include}d files are
2080 However there is no consensus on the distribution of third-party
2081 macros that your package may use. Many libraries install their own
2082 macro in the system-wide @command{aclocal} directory (@pxref{Extending
2083 aclocal}). For instance, Guile ships with a file called
2084 @file{guile.m4} that contains the macro @code{GUILE_FLAGS} that can
2085 be used to define setup compiler and linker flags appropriate for
2086 using Guile. Using @code{GUILE_FLAGS} in @file{configure.ac} will
2087 cause @command{aclocal} to copy @file{guile.m4} into
2088 @file{aclocal.m4}, but as @file{guile.m4} is not part of the project,
2089 it will not be distributed. Technically, that means a user who
2090 needs to rebuild @file{aclocal.m4} will have to install Guile first.
2091 This is probably OK, if Guile already is a requirement to build the
2092 package. However, if Guile is only an optional feature, or if your
2093 package might run on architectures where Guile cannot be installed,
2094 this requirement will hinder development. An easy solution is to copy
2095 such third-party macros in your local @file{m4/} directory so they get
2098 Since Automake 1.10, @command{aclocal} offers an option to copy these
2099 system-wide third-party macros in your local macro directory, solving
2100 the above problem. Simply use:
2103 ACLOCAL_AMFLAGS = -I m4 --install
2107 With this setup, system-wide macros will be copied to @file{m4/}
2108 the first time you run @command{autoreconf}. Then the locally
2109 installed macros will have precedence over the system-wide installed
2110 macros each time @command{aclocal} is run again.
2112 One reason why you should keep @option{--install} in the flags even
2113 after the first run is that when you later edit @file{configure.ac}
2114 and depend on a new macro, this macro will be installed in your
2115 @file{m4/} automatically. Another one is that serial numbers
2116 (@pxref{Serials}) can be used to update the macros in your source tree
2117 automatically when new system-wide versions are installed. A serial
2118 number should be a single line of the form
2125 where @var{NNN} contains only digits and dots. It should appear in
2126 the M4 file before any macro definition. It is a good practice to
2127 maintain a serial number for each macro you distribute, even if you do
2128 not use the @option{--install} option of @command{aclocal}: this allows
2129 other people to use it.
2133 @subsection Serial Numbers
2134 @cindex serial numbers in macros
2135 @cindex macro serial numbers
2136 @cindex @code{#serial} syntax
2137 @cindex @command{aclocal} and serial numbers
2139 Because third-party macros defined in @file{*.m4} files are naturally
2140 shared between multiple projects, some people like to version them.
2141 This makes it easier to tell which of two M4 files is newer. Since at
2142 least 1996, the tradition is to use a @samp{#serial} line for this.
2144 A serial number should be a single line of the form
2147 # serial @var{version}
2151 where @var{version} is a version number containing only digits and
2152 dots. Usually people use a single integer, and they increment it each
2153 time they change the macro (hence the name of ``serial''). Such a
2154 line should appear in the M4 file before any macro definition.
2156 The @samp{#} must be the first character on the line,
2157 and it is OK to have extra words after the version, as in
2160 #serial @var{version} @var{garbage}
2163 Normally these serial numbers are completely ignored by
2164 @command{aclocal} and @command{autoconf}, like any genuine comment.
2165 However when using @command{aclocal}'s @option{--install} feature, these
2166 serial numbers will modify the way @command{aclocal} selects the
2167 macros to install in the package: if two files with the same basename
2168 exists in your search path, and if at least one of them use a
2169 @samp{#serial} line, @command{aclocal} will ignore the file that has
2170 the older @samp{#serial} line (or the file that has none).
2172 Note that a serial number applies to a whole M4 file, not to any macro
2173 it contains. A file can contains multiple macros, but only one
2176 Here is a use case that illustrate the use of @option{--install} and
2177 its interaction with serial numbers. Let's assume we maintain a
2178 package called MyPackage, the @file{configure.ac} of which requires a
2179 third-party macro @code{AX_THIRD_PARTY} defined in
2180 @file{/usr/share/aclocal/thirdparty.m4} as follows:
2184 AC_DEFUN([AX_THIRD_PARTY], [...])
2187 MyPackage uses an @file{m4/} directory to store local macros as
2188 explained in @ref{Local Macros}, and has
2191 ACLOCAL_AMFLAGS = -I m4 --install
2195 in its top-level @file{Makefile.am}.
2197 Initially the @file{m4/} directory is empty. The first time we run
2198 @command{autoreconf}, it will fetch the options to pass to
2199 @command{aclocal} in @file{Makefile.am}, and run @samp{aclocal -I m4
2200 --install}. @command{aclocal} will notice that
2204 @file{configure.ac} uses @code{AX_THIRD_PARTY}
2206 No local macros define @code{AX_THIRD_PARTY}
2208 @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
2213 Because @file{/usr/share/aclocal/thirdparty.m4} is a system-wide macro
2214 and @command{aclocal} was given the @option{--install} option, it will
2215 copy this file in @file{m4/thirdparty.m4}, and output an
2216 @file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}.
2218 The next time @samp{aclocal -I m4 --install} is run (either via
2219 @command{autoreconf}, by hand, or from the @file{Makefile} rebuild
2220 rules) something different happens. @command{aclocal} notices that
2224 @file{configure.ac} uses @code{AX_THIRD_PARTY}
2226 @file{m4/thirdparty.m4} defines @code{AX_THIRD_PARTY}
2229 @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
2234 Because both files have the same serial number, @command{aclocal} uses
2235 the first it found in its search path order (@pxref{Macro search
2236 path}). @command{aclocal} therefore ignores
2237 @file{/usr/share/aclocal/thirdparty.m4} and outputs an
2238 @file{aclocal.m4} that contains @samp{m4_include([m4/thirdparty.m4])}.
2240 Local directories specified with @option{-I} are always searched before
2241 system-wide directories, so a local file will always be preferred to
2242 the system-wide file in case of equal serial numbers.
2244 Now suppose the system-wide third-party macro is changed. This can
2245 happen if the package installing this macro is updated. Let's suppose
2246 the new macro has serial number 2. The next time @samp{aclocal -I m4
2247 --install} is run the situation is the following:
2251 @file{configure.ac} uses @code{AX_THIRD_PARTY}
2253 @file{m4/thirdparty.m4} defines @code{AX_THIRD_PARTY}
2256 @file{/usr/share/aclocal/thirdparty.m4} defines @code{AX_THIRD_PARTY}
2261 When @command{aclocal} sees a greater serial number, it immediately
2262 forgets anything it knows from files that have the same basename and a
2263 smaller serial number. So after it has found
2264 @file{/usr/share/aclocal/thirdparty.m4} with serial 2,
2265 @command{aclocal} will proceed as if it had never seen
2266 @file{m4/thirdparty.m4}. This brings us back to a situation similar
2267 to that at the beginning of our example, where no local file defined
2268 the macro. @command{aclocal} will install the new version of the
2269 macro in @file{m4/thirdparty.m4}, in this case overriding the old
2270 version. MyPackage just had its macro updated as a side effect of
2271 running @command{aclocal}.
2273 If you are leery of letting @command{aclocal} update your local macro,
2274 you can run @samp{aclocal -I m4 --diff} to review the changes
2275 @samp{aclocal -I m4 --install} would perform on these macros.
2277 Finally, note that the @option{--force} option of @command{aclocal} has
2278 absolutely no effect on the files installed by @option{--install}. For
2279 instance, if you have modified your local macros, do not expect
2280 @option{--install --force} to replace the local macros by their
2281 system-wide versions. If you want to do so, simply erase the local
2282 macros you want to revert, and run @samp{aclocal -I m4 --install}.
2285 @node Future of aclocal
2286 @subsection The Future of @command{aclocal}
2287 @cindex @command{aclocal}'s scheduled death
2289 @command{aclocal} is expected to disappear. This feature really
2290 should not be offered by Automake. Automake should focus on
2291 generating @file{Makefile}s; dealing with M4 macros really is
2292 Autoconf's job. That some people install Automake just to use
2293 @command{aclocal}, but do not use @command{automake} otherwise is an
2294 indication of how that feature is misplaced.
2296 The new implementation will probably be done slightly differently.
2297 For instance, it could enforce the @file{m4/}-style layout discussed in
2300 We have no idea when and how this will happen. This has been
2301 discussed several times in the past, but someone still has to commit
2302 itself to that non-trivial task.
2304 From the user point of view, @command{aclocal}'s removal might turn
2305 out to be painful. There is a simple precaution that you may take to
2306 make that switch more seamless: never call @command{aclocal} yourself.
2307 Keep this guy under the exclusive control of @command{autoreconf} and
2308 Automake's rebuild rules. Hopefully you won't need to worry about
2309 things breaking, when @command{aclocal} disappears, because everything
2310 will have been taken care of. If otherwise you used to call
2311 @command{aclocal} directly yourself or from some script, you will
2312 quickly notice the change.
2314 Many packages come with a script called @file{bootstrap.sh} or
2315 @file{autogen.sh}, that will just call @command{aclocal},
2316 @command{libtoolize}, @command{gettextize} or @command{autopoint},
2317 @command{autoconf}, @command{autoheader}, and @command{automake} in
2318 the right order. Actually this is precisely what @command{autoreconf}
2319 can do for you. If your package has such a @file{bootstrap.sh} or
2320 @file{autogen.sh} script, consider using @command{autoreconf}. That
2321 should simplify its logic a lot (less things to maintain, yum!), it's
2322 even likely you will not need the script anymore, and more to the point
2323 you will not call @command{aclocal} directly anymore.
2325 For the time being, third-party packages should continue to install
2326 public macros into @file{/usr/share/aclocal/}. If @command{aclocal}
2327 is replaced by another tool it might make sense to rename the
2328 directory, but supporting @file{/usr/share/aclocal/} for backward
2329 compatibility should be really easy provided all macros are properly
2330 written (@pxref{Extending aclocal}).
2335 @section Autoconf macros supplied with Automake
2337 Automake ships with several Autoconf macros that you can use from your
2338 @file{configure.ac}. When you use one of them it will be included by
2339 @command{aclocal} in @file{aclocal.m4}.
2342 * Public macros:: Macros that you can use.
2343 * Obsolete macros:: Macros that you should stop using.
2344 * Private macros:: Macros that you should not use.
2347 @c consider generating the following subsections automatically from m4 files.
2350 @subsection Public macros
2353 @item AM_C_PROTOTYPES
2354 @acindex AM_C_PROTOTYPES
2357 Check to see if function prototypes are understood by the compiler. If
2358 so, define @samp{PROTOTYPES} and set the output variables @code{U} and
2359 @code{ANSI2KNR} to the empty string. Otherwise, set @code{U} to
2360 @samp{_} and @code{ANSI2KNR} to @samp{./ansi2knr}. Automake uses these
2361 values to implement automatic de-ANSI-fication.
2363 @item AM_ENABLE_MULTILIB
2364 @acindex AM_ENABLE_MULTILIB
2365 This is used when a ``multilib'' library is being built. The first
2366 optional argument is the name of the @file{Makefile} being generated; it
2367 defaults to @samp{Makefile}. The second option argument is used to find
2368 the top source directory; it defaults to the empty string (generally
2369 this should not be used unless you are familiar with the internals).
2372 @item AM_INIT_AUTOMAKE([OPTIONS])
2373 @itemx AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])
2374 @acindex AM_INIT_AUTOMAKE
2375 Runs many macros required for proper operation of the generated Makefiles.
2377 @vindex AUTOMAKE_OPTIONS
2378 This macro has two forms, the first of which is preferred.
2379 In this form, @code{AM_INIT_AUTOMAKE} is called with a
2380 single argument: a space-separated list of Automake options that should
2381 be applied to every @file{Makefile.am} in the tree. The effect is as if
2382 each option were listed in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
2385 The second, deprecated, form of @code{AM_INIT_AUTOMAKE} has two required
2386 arguments: the package and the version number. This form is
2387 obsolete because the @var{package} and @var{version} can be obtained
2388 from Autoconf's @code{AC_INIT} macro (which itself has an old and a new
2391 If your @file{configure.ac} has:
2395 AM_INIT_AUTOMAKE(mumble, 1.5)
2399 you can modernize it as follows:
2402 AC_INIT(mumble, 1.5)
2403 AC_CONFIG_SRCDIR(src/foo.c)
2407 Note that if you're upgrading your @file{configure.ac} from an earlier
2408 version of Automake, it is not always correct to simply move the
2409 package and version arguments from @code{AM_INIT_AUTOMAKE} directly to
2410 @code{AC_INIT}, as in the example above. The first argument to
2411 @code{AC_INIT} should be the name of your package (e.g., @samp{GNU
2412 Automake}), not the tarball name (e.g., @samp{automake}) that you used
2413 to pass to @code{AM_INIT_AUTOMAKE}. Autoconf tries to derive a
2414 tarball name from the package name, which should work for most but not
2415 all package names. (If it doesn't work for yours, you can use the
2416 four-argument form of @code{AC_INIT} to provide the tarball name
2419 @cindex @code{PACKAGE}, prevent definition
2420 @cindex @code{VERSION}, prevent definition
2422 By default this macro @code{AC_DEFINE}'s @code{PACKAGE} and
2423 @code{VERSION}. This can be avoided by passing the @option{no-define}
2426 AM_INIT_AUTOMAKE([gnits 1.5 no-define dist-bzip2])
2428 or by passing a third non-empty argument to the obsolete form.
2430 @item AM_PATH_LISPDIR
2431 @acindex AM_PATH_LISPDIR
2434 Searches for the program @command{emacs}, and, if found, sets the
2435 output variable @code{lispdir} to the full path to Emacs' site-lisp
2438 Note that this test assumes the @command{emacs} found to be a version
2439 that supports Emacs Lisp (such as @sc{gnu} Emacs or XEmacs). Other
2440 emacsen can cause this test to hang (some, like old versions of
2441 MicroEmacs, start up in interactive mode, requiring @kbd{C-x C-c} to
2442 exit, which is hardly obvious for a non-emacs user). In most cases,
2443 however, you should be able to use @kbd{C-c} to kill the test. In
2444 order to avoid problems, you can set @env{EMACS} to ``no'' in the
2445 environment, or use the @option{--with-lispdir} option to
2446 @command{configure} to explicitly set the correct path (if you're sure
2447 you have an @command{emacs} that supports Emacs Lisp.
2453 Use this macro when you have assembly code in your project. This will
2454 choose the assembler for you (by default the C compiler) and set
2455 @code{CCAS}, and will also set @code{CCASFLAGS} if required.
2457 @item AM_PROG_CC_C_O
2458 @acindex AM_PROG_CC_C_O
2459 @acindex AC_PROG_CC_C_O
2460 This is like @code{AC_PROG_CC_C_O}, but it generates its results in
2461 the manner required by automake. You must use this instead of
2462 @code{AC_PROG_CC_C_O} when you need this functionality, that is, when
2463 using per-target flags or subdir-objects with C sources.
2466 @acindex AM_PROG_LEX
2467 @acindex AC_PROG_LEX
2468 @cindex HP-UX 10, @command{lex} problems
2469 @cindex @command{lex} problems with HP-UX 10
2470 Like @code{AC_PROG_LEX} (@pxref{Particular Programs, , Particular
2471 Program Checks, autoconf, The Autoconf Manual}), but uses the
2472 @command{missing} script on systems that do not have @command{lex}.
2473 HP-UX 10 is one such system.
2476 @acindex AM_PROG_GCJ
2479 This macro finds the @command{gcj} program or causes an error. It sets
2480 @code{GCJ} and @code{GCJFLAGS}. @command{gcj} is the Java front-end to the
2481 GNU Compiler Collection.
2483 @item AM_WITH_DMALLOC
2484 @acindex AM_WITH_DMALLOC
2485 @cindex @command{dmalloc}, support for
2486 @vindex WITH_DMALLOC
2487 @opindex --with-dmalloc
2488 Add support for the @uref{http://dmalloc.com/, Dmalloc package}. If
2489 the user runs @command{configure} with @option{--with-dmalloc}, then
2490 define @code{WITH_DMALLOC} and add @option{-ldmalloc} to @code{LIBS}.
2493 @acindex AM_WITH_REGEX
2495 @opindex --with-regex
2496 @cindex regex package
2498 Adds @option{--with-regex} to the @command{configure} command line. If
2499 specified (the default), then the @samp{regex} regular expression
2500 library is used, @file{regex.o} is put into @code{LIBOBJS}, and
2501 @code{WITH_REGEX} is defined. If @option{--without-regex} is given, then
2502 the @code{rx} regular expression library is used, and @file{rx.o} is put
2503 into @code{LIBOBJS}.
2508 @node Obsolete macros
2509 @subsection Obsolete macros
2510 @cindex obsolete macros
2513 Although using some of the following macros was required in past
2514 releases, you should not used any of them in new code. Running
2515 @command{autoupdate} should adjust your @file{configure.ac}
2516 automatically (@pxref{autoupdate Invocation, , Using
2517 @command{autoupdate} to Modernize @file{configure.ac}, autoconf, The
2521 @item AM_CONFIG_HEADER
2522 @acindex AM_CONFIG_HEADER
2523 Automake will generate rules to automatically regenerate the config
2524 header. This obsolete macro is a synonym of @code{AC_CONFIG_HEADERS}
2525 today (@pxref{Optional}).
2527 @item AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
2528 @acindex AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
2529 If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
2530 define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be
2531 found in @file{<termios.h>}. This macro is obsolete, you should
2532 use Autoconf's @code{AC_HEADER_TIOCGWINSZ} instead.
2534 @item AM_SYS_POSIX_TERMIOS
2535 @acindex AM_SYS_POSIX_TERMIOS
2536 @cindex POSIX termios headers
2537 @cindex termios POSIX headers
2538 Check to see if POSIX termios headers and functions are available on the
2539 system. If so, set the shell variable @code{am_cv_sys_posix_termios} to
2540 @samp{yes}. If not, set the variable to @samp{no}. This macro is obsolete,
2541 you should use Autoconf's @code{AC_SYS_POSIX_TERMIOS} instead.
2546 @node Private macros
2547 @subsection Private macros
2549 The following macros are private macros you should not call directly.
2550 They are called by the other public macros when appropriate. Do not
2551 rely on them, as they might be changed in a future version. Consider
2552 them as implementation details; or better, do not consider them at all:
2556 @item _AM_DEPENDENCIES
2557 @itemx AM_SET_DEPDIR
2559 @itemx AM_OUTPUT_DEPENDENCY_COMMANDS
2560 These macros are used to implement Automake's automatic dependency
2561 tracking scheme. They are called automatically by automake when
2562 required, and there should be no need to invoke them manually.
2564 @item AM_MAKE_INCLUDE
2565 This macro is used to discover how the user's @command{make} handles
2566 @code{include} statements. This macro is automatically invoked when
2567 needed; there should be no need to invoke it manually.
2569 @item AM_PROG_INSTALL_STRIP
2570 This is used to find a version of @code{install} that can be used to
2571 strip a program at installation time. This macro is automatically
2572 included when required.
2574 @item AM_SANITY_CHECK
2575 This checks to make sure that a file created in the build directory is
2576 newer than a file in the source directory. This can fail on systems
2577 where the clock is set incorrectly. This macro is automatically run
2578 from @code{AM_INIT_AUTOMAKE}.
2584 @chapter Directories
2586 For simple projects that distributes all files in the same directory
2587 it is enough to have a single @file{Makefile.am} that builds
2588 everything in place.
2590 In larger projects it is common to organize files in different
2591 directories, in a tree. For instance one directory per program, per
2592 library or per module. The traditional approach is to build these
2593 subdirectory recursively: each directory contains its @file{Makefile}
2594 (generated from @file{Makefile.am}), and when @command{make} is run
2595 from the top level directory it enters each subdirectory in turn to
2599 * Subdirectories:: Building subdirectories recursively
2600 * Conditional Subdirectories:: Conditionally not building directories
2601 * Alternative:: Subdirectories without recursion
2602 * Subpackages:: Nesting packages
2605 @node Subdirectories
2606 @section Recursing subdirectories
2608 @cindex @code{SUBDIRS}, explained
2610 In packages with subdirectories, the top level @file{Makefile.am} must
2611 tell Automake which subdirectories are to be built. This is done via
2612 the @code{SUBDIRS} variable.
2615 The @code{SUBDIRS} variable holds a list of subdirectories in which
2616 building of various sorts can occur. The rules for many targets
2617 (e.g., @code{all}) in the generated @file{Makefile} will run commands
2618 both locally and in all specified subdirectories. Note that the
2619 directories listed in @code{SUBDIRS} are not required to contain
2620 @file{Makefile.am}s; only @file{Makefile}s (after configuration).
2621 This allows inclusion of libraries from packages that do not use
2622 Automake (such as @code{gettext}; see also @ref{Third-Party
2625 In packages that use subdirectories, the top-level @file{Makefile.am} is
2626 often very short. For instance, here is the @file{Makefile.am} from the
2627 GNU Hello distribution:
2630 EXTRA_DIST = BUGS ChangeLog.O README-alpha
2631 SUBDIRS = doc intl po src tests
2634 When Automake invokes @command{make} in a subdirectory, it uses the value
2635 of the @code{MAKE} variable. It passes the value of the variable
2636 @code{AM_MAKEFLAGS} to the @command{make} invocation; this can be set in
2637 @file{Makefile.am} if there are flags you must always pass to
2640 @vindex AM_MAKEFLAGS
2642 The directories mentioned in @code{SUBDIRS} are usually direct
2643 children of the current directory, each subdirectory containing its
2644 own @file{Makefile.am} with a @code{SUBDIRS} pointing to deeper
2645 subdirectories. Automake can be used to construct packages of
2646 arbitrary depth this way.
2648 By default, Automake generates @file{Makefiles} that work depth-first
2649 in postfix order: the subdirectories are built before the current
2650 directory. However, it is possible to change this ordering. You can
2651 do this by putting @samp{.} into @code{SUBDIRS}. For instance,
2652 putting @samp{.} first will cause a prefix ordering of
2658 SUBDIRS = lib src . test
2662 will cause @file{lib/} to be built before @file{src/}, then the
2663 current directory will be built, finally the @file{test/} directory
2664 will be built. It is customary to arrange test directories to be
2665 built after everything else since they are meant to test what has
2668 All @code{clean} rules are run in reverse order of build rules.
2670 @node Conditional Subdirectories
2671 @section Conditional Subdirectories
2672 @cindex Subdirectories, building conditionally
2673 @cindex Conditional subdirectories
2674 @cindex @code{SUBDIRS}, conditional
2675 @cindex Conditional @code{SUBDIRS}
2677 It is possible to define the @code{SUBDIRS} variable conditionally if,
2678 like in the case of GNU Inetutils, you want to only build a subset of
2681 To illustrate how this works, let's assume we have two directories
2682 @file{src/} and @file{opt/}. @file{src/} should always be built, but we
2683 want to decide in @command{configure} whether @file{opt/} will be built
2684 or not. (For this example we will assume that @file{opt/} should be
2685 built when the variable @samp{$want_opt} was set to @samp{yes}.)
2687 Running @command{make} should thus recurse into @file{src/} always, and
2688 then maybe in @file{opt/}.
2690 However @samp{make dist} should always recurse into both @file{src/}
2691 and @file{opt/}. Because @file{opt/} should be distributed even if it
2692 is not needed in the current configuration. This means
2693 @file{opt/Makefile} should be created @emph{unconditionally}.
2695 There are two ways to setup a project like this. You can use Automake
2696 conditionals (@pxref{Conditionals}) or use Autoconf @code{AC_SUBST}
2697 variables (@pxref{Setting Output Variables, , Setting Output
2698 Variables, autoconf, The Autoconf Manual}). Using Automake
2699 conditionals is the preferred solution. Before we illustrate these
2700 two possibility, let's introduce @code{DIST_SUBDIRS}.
2702 @subsection @code{SUBDIRS} vs.@: @code{DIST_SUBDIRS}
2703 @cindex @code{DIST_SUBDIRS}, explained
2705 Automake considers two sets of directories, defined by the variables
2706 @code{SUBDIRS} and @code{DIST_SUBDIRS}.
2708 @code{SUBDIRS} contains the subdirectories of the current directory
2709 that must be built (@pxref{Subdirectories}). It must be defined
2710 manually; Automake will never guess a directory is to be built. As we
2711 will see in the next two sections, it is possible to define it
2712 conditionally so that some directory will be omitted from the build.
2714 @code{DIST_SUBDIRS} is used in rules that need to recurse in all
2715 directories, even those that have been conditionally left out of the
2716 build. Recall our example where we may not want to build subdirectory
2717 @file{opt/}, but yet we want to distribute it? This is where
2718 @code{DIST_SUBDIRS} come into play: @samp{opt} may not appear in
2719 @code{SUBDIRS}, but it must appear in @code{DIST_SUBDIRS}.
2721 Precisely, @code{DIST_SUBDIRS} is used by @samp{make
2722 maintainer-clean}, @samp{make distclean} and @samp{make dist}. All
2723 other recursive rules use @code{SUBDIRS}.
2725 If @code{SUBDIRS} is defined conditionally using Automake
2726 conditionals, Automake will define @code{DIST_SUBDIRS} automatically
2727 from the possibles values of @code{SUBDIRS} in all conditions.
2729 If @code{SUBDIRS} contains @code{AC_SUBST} variables,
2730 @code{DIST_SUBDIRS} will not be defined correctly because Automake
2731 does not know the possible values of these variables. In this case
2732 @code{DIST_SUBDIRS} needs to be defined manually.
2734 @subsection Conditional subdirectories with @code{AM_CONDITIONAL}
2735 @cindex @code{SUBDIRS} and @code{AM_CONDITIONAL}
2736 @cindex @code{AM_CONDITIONAL} and @code{SUBDIRS}
2738 @c The test case for the setup described here is
2739 @c test/subdircond2.test
2740 @c Try to keep it in sync.
2742 @file{configure} should output the @file{Makefile} for each directory
2743 and define a condition into which @file{opt/} should be built.
2747 AM_CONDITIONAL([COND_OPT], [test "$want_opt" = yes])
2748 AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
2752 Then @code{SUBDIRS} can be defined in the top-level @file{Makefile.am}
2759 SUBDIRS = src $(MAYBE_OPT)
2762 As you can see, running @command{make} will rightly recurse into
2763 @file{src/} and maybe @file{opt/}.
2765 @vindex DIST_SUBDIRS
2766 As you can't see, running @samp{make dist} will recurse into both
2767 @file{src/} and @file{opt/} directories because @samp{make dist}, unlike
2768 @samp{make all}, doesn't use the @code{SUBDIRS} variable. It uses the
2769 @code{DIST_SUBDIRS} variable.
2771 In this case Automake will define @samp{DIST_SUBDIRS = src opt}
2772 automatically because it knows that @code{MAYBE_OPT} can contain
2773 @samp{opt} in some condition.
2775 @subsection Conditional Subdirectories with @code{AC_SUBST}
2776 @cindex @code{SUBDIRS} and @code{AC_SUBST}
2777 @cindex @code{AC_SUBST} and @code{SUBDIRS}
2779 @c The test case for the setup described here is
2780 @c test/subdircond3.test
2781 @c Try to keep it in sync.
2783 Another possibility is to define @code{MAYBE_OPT} from
2784 @file{./configure} using @code{AC_SUBST}:
2788 if test "$want_opt" = yes; then
2793 AC_SUBST([MAYBE_OPT])
2794 AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
2798 In this case the top-level @file{Makefile.am} should look as follows.
2801 SUBDIRS = src $(MAYBE_OPT)
2802 DIST_SUBDIRS = src opt
2805 The drawback is that since Automake cannot guess what the possible
2806 values of @code{MAYBE_OPT} are, it is necessary to define
2807 @code{DIST_SUBDIRS}.
2809 @subsection Non-configured Subdirectories
2810 @cindex Subdirectories, configured conditionally
2812 The semantic of @code{DIST_SUBDIRS} is often misunderstood by some
2813 users that try to @emph{configure and build} subdirectories
2814 conditionally. Here by configuring we mean creating the
2815 @file{Makefile} (it might also involve running a nested
2816 @command{configure} script: this is a costly operation that explains
2817 why people want to do it conditionally, but only the @file{Makefile}
2818 is relevant to the discussion).
2820 The above examples all assume that every @file{Makefile} is created,
2821 even in directories that are not going to be built. The simple reason
2822 is that we want @samp{make dist} to distribute even the directories
2823 that are not being built (e.g., platform-dependent code), hence
2824 @file{make dist} must recurse into the subdirectory, hence this
2825 directory must be configured and appear in @code{DIST_SUBDIRS}.
2827 Building packages that do not configure every subdirectory is a tricky
2828 business, and we do not recommend it to the novice as it is easy to
2829 produce an incomplete tarball by mistake. We will not discuss this
2830 topic in depth here, yet for the adventurous here are a few rules to
2835 @item @code{SUBDIRS} should always be a subset of @code{DIST_SUBDIRS}.
2837 It makes little sense to have a directory in @code{SUBDIRS} that
2838 is not in @code{DIST_SUBDIRS}. Think of the former as a way to tell
2839 which directories listed in the latter should be built.
2840 @item Any directory listed in @code{DIST_SUBDIRS} and @code{SUBDIRS}
2843 I.e., the @file{Makefile} must exists or the recursive @command{make}
2844 rules will not be able to process the directory.
2845 @item Any configured directory must be listed in @code{DIST_SUBDIRS}.
2847 So that the cleaning rule remove the generated @file{Makefile}s.
2848 It would be correct to see @code{DIST_SUBDIRS} as a variable that
2849 lists all the directories that have been configured.
2853 In order to prevent recursion in some non-configured directory you
2854 must therefore ensure that this directory does not appear in
2855 @code{DIST_SUBDIRS} (and @code{SUBDIRS}). For instance, if you define
2856 @code{SUBDIRS} conditionally using @code{AC_SUBST} and do not define
2857 @code{DIST_SUBDIRS} explicitly, it will be default to
2858 @samp{$(SUBDIRS)}; another possibility is to force @code{DIST_SUBDIRS
2861 Of course, directories that are omitted from @code{DIST_SUBDIRS} will
2862 not be distributed unless you make other arrangements for this to
2863 happen (for instance, always running @samp{make dist} in a
2864 configuration where all directories are known to appear in
2865 @code{DIST_SUBDIRS}; or writing a @code{dist-hook} target to
2866 distribute these directories).
2868 @cindex Subdirectories, not distributed
2869 In few packages, non-configured directories are not even expected to
2870 be distributed. Although these packages do not require the
2871 aforementioned extra arrangements, there is another pitfall. If the
2872 name of a directory appears in @code{SUBDIRS} or @code{DIST_SUBDIRS},
2873 @command{automake} will make sure the directory exists. Consequently
2874 @command{automake} cannot be run on such a distribution when one
2875 directory has been omitted. One way to avoid this check is to use the
2876 @code{AC_SUBST} method to declare conditional directories; since
2877 @command{automake} does not know the values of @code{AC_SUBST}
2878 variables it cannot ensure the corresponding directory exist.
2881 @section An Alternative Approach to Subdirectories
2883 If you've ever read Peter Miller's excellent paper,
2884 @uref{http://www.pcug.org.au/~millerp/rmch/recu-make-cons-harm.html,
2885 Recursive Make Considered Harmful}, the preceding sections on the use of
2886 subdirectories will probably come as unwelcome advice. For those who
2887 haven't read the paper, Miller's main thesis is that recursive
2888 @command{make} invocations are both slow and error-prone.
2890 Automake provides sufficient cross-directory support @footnote{We
2891 believe. This work is new and there are probably warts.
2892 @xref{Introduction}, for information on reporting bugs.} to enable you
2893 to write a single @file{Makefile.am} for a complex multi-directory
2897 By default an installable file specified in a subdirectory will have its
2898 directory name stripped before installation. For instance, in this
2899 example, the header file will be installed as
2900 @file{$(includedir)/stdio.h}:
2903 include_HEADERS = inc/stdio.h
2907 @cindex @code{nobase_} prefix
2908 @cindex Path stripping, avoiding
2909 @cindex Avoiding path stripping
2911 However, the @samp{nobase_} prefix can be used to circumvent this path
2912 stripping. In this example, the header file will be installed as
2913 @file{$(includedir)/sys/types.h}:
2916 nobase_include_HEADERS = sys/types.h
2919 @cindex @code{nobase_} and @code{dist_} or @code{nodist_}
2920 @cindex @code{dist_} and @code{nobase_}
2921 @cindex @code{nodist_} and @code{nobase_}
2925 @samp{nobase_} should be specified first when used in conjunction with
2926 either @samp{dist_} or @samp{nodist_} (@pxref{Dist}). For instance:
2929 nobase_dist_pkgdata_DATA = images/vortex.pgm sounds/whirl.ogg
2932 Finally, note that a variable using the @samp{nobase_} prefix can
2933 always be replaced by several variables, one for each destination
2934 directory (@pxref{Uniform}). For instance, the last example could be
2935 rewritten as follows:
2938 imagesdir = $(pkgdatadir)/images
2939 soundsdir = $(pkgdatadir)/sounds
2940 dist_images_DATA = images/vortex.pgm
2941 dist_sounds_DATA = sounds/whirl.ogg
2945 This latter syntax makes it possible to change one destination
2946 directory without changing the layout of the source tree.
2949 @section Nesting Packages
2950 @cindex Nesting packages
2952 @acindex AC_CONFIG_SUBDIRS
2953 @acindex AC_CONFIG_AUX_DIR
2956 In the GNU Build System, packages can be nested to arbitrary depth.
2957 This means that a package can embedded other packages with their own
2958 @file{configure}, @file{Makefile}s, etc.
2960 These other packages should just appear as subdirectories of their
2961 parent package. They must be listed in @code{SUBDIRS} like other
2962 ordinary directories. However the subpackage's @file{Makefile}s
2963 should be output by its own @file{configure} script, not by the
2964 parent's @file{configure}. This is achieved using the
2965 @code{AC_CONFIG_SUBDIRS} Autoconf macro (@pxref{Subdirectories,
2966 AC_CONFIG_SUBDIRS, Configuring Other Packages in Subdirectories,
2967 autoconf, The Autoconf Manual}).
2969 Here is an example package for an @code{arm} program that links with
2970 an @code{hand} library that is a nested package in subdirectory
2973 @code{arm}'s @file{configure.ac}:
2976 AC_INIT([arm], [1.0])
2977 AC_CONFIG_AUX_DIR([.])
2980 AC_CONFIG_FILES([Makefile])
2981 # Call hand's ./configure script recursively.
2982 AC_CONFIG_SUBDIRS([hand])
2986 @code{arm}'s @file{Makefile.am}:
2989 # Build the library in the hand subdirectory first.
2992 # Include hand's header when compiling this directory.
2993 AM_CPPFLAGS = -I$(srcdir)/hand
2997 # link with the hand library.
2998 arm_LDADD = hand/libhand.a
3001 Now here is @code{hand}'s @file{hand/configure.ac}:
3004 AC_INIT([hand], [1.2])
3005 AC_CONFIG_AUX_DIR([.])
3009 AC_CONFIG_FILES([Makefile])
3014 and its @file{hand/Makefile.am}:
3017 lib_LIBRARIES = libhand.a
3018 libhand_a_SOURCES = hand.c
3021 When @samp{make dist} is run from the top-level directory it will
3022 create an archive @file{arm-1.0.tar.gz} that contains the @code{arm}
3023 code as well as the @file{hand} subdirectory. This package can be
3024 built and installed like any ordinary package, with the usual
3025 @samp{./configure && make && make install} sequence (the @code{hand}
3026 subpackage will be built and installed by the process).
3028 When @samp{make dist} is run from the hand directory, it will create a
3029 self-contained @file{hand-1.2.tar.gz} archive. So although it appears
3030 to be embedded in another package, it can still be used separately.
3032 The purpose of the @samp{AC_CONFIG_AUX_DIR([.])} instruction is to
3033 force Automake and Autoconf into search auxiliary script in the
3034 current directory. For instance, this means that there will be two
3035 copies of @file{install-sh}: one in the top-level of the @code{arm}
3036 package, and another one in the @file{hand/} subdirectory for the
3037 @code{hand} package.
3039 The historical default is to search these auxiliary scripts in the
3040 immediate parent and grand-parent directories. So if the
3041 @samp{AC_CONFIG_AUX_DIR([.])} line was removed from
3042 @file{hand/configure.ac}, that subpackage would share the auxiliary
3043 script of the @code{arm} package. This may looks like a gain in size
3044 (a few kilobytes), but it is actually a loss of modularity as the
3045 @code{hand} subpackage is no longer self-contained (@samp{make dist}
3046 in the subdirectory will not work anymore).
3048 Packages that do not use Automake need more work to be integrated this
3049 way. @xref{Third-Party Makefiles}.
3052 @chapter Building Programs and Libraries
3054 A large part of Automake's functionality is dedicated to making it easy
3055 to build programs and libraries.
3058 * A Program:: Building a program
3059 * A Library:: Building a library
3060 * A Shared Library:: Building a Libtool library
3061 * Program and Library Variables:: Variables controlling program and
3063 * Default _SOURCES:: Default source files
3064 * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
3065 * Program variables:: Variables used when building a program
3066 * Yacc and Lex:: Yacc and Lex support
3067 * C++ Support:: Compiling C++ sources
3068 * Assembly Support:: Compiling assembly sources
3069 * Fortran 77 Support:: Compiling Fortran 77 sources
3070 * Fortran 9x Support:: Compiling Fortran 9x sources
3071 * Java Support:: Compiling Java sources
3072 * Support for Other Languages:: Compiling other languages
3073 * ANSI:: Automatic de-ANSI-fication
3074 * Dependencies:: Automatic dependency tracking
3075 * EXEEXT:: Support for executable extensions
3080 @section Building a program
3082 In order to build a program, you need to tell Automake which sources
3083 are part of it, and which libraries it should be linked with.
3085 This section also covers conditional compilation of sources or
3086 programs. Most of the comments about these also apply to libraries
3087 (@pxref{A Library}) and libtool libraries (@pxref{A Shared Library}).
3090 * Program Sources:: Defining program sources
3091 * Linking:: Linking with libraries or extra objects
3092 * Conditional Sources:: Handling conditional sources
3093 * Conditional Programs:: Building program conditionally
3096 @node Program Sources
3097 @subsection Defining program sources
3099 @cindex @code{PROGRAMS}, @code{bindir}
3101 @vindex bin_PROGRAMS
3102 @vindex sbin_PROGRAMS
3103 @vindex libexec_PROGRAMS
3104 @vindex pkglib_PROGRAMS
3105 @vindex noinst_PROGRAMS
3106 @vindex check_PROGRAMS
3108 In a directory containing source that gets built into a program (as
3109 opposed to a library or a script), the @code{PROGRAMS} primary is used.
3110 Programs can be installed in @code{bindir}, @code{sbindir},
3111 @code{libexecdir}, @code{pkglibdir}, or not at all (@code{noinst_}).
3112 They can also be built only for @samp{make check}, in which case the
3113 prefix is @samp{check_}.
3118 bin_PROGRAMS = hello
3121 In this simple case, the resulting @file{Makefile.in} will contain code
3122 to generate a program named @code{hello}.
3124 Associated with each program are several assisting variables that are
3125 named after the program. These variables are all optional, and have
3126 reasonable defaults. Each variable, its use, and default is spelled out
3127 below; we use the ``hello'' example throughout.
3129 The variable @code{hello_SOURCES} is used to specify which source files
3130 get built into an executable:
3133 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
3136 This causes each mentioned @file{.c} file to be compiled into the
3137 corresponding @file{.o}. Then all are linked to produce @file{hello}.
3139 @cindex @code{_SOURCES} primary, defined
3140 @cindex @code{SOURCES} primary, defined
3141 @cindex Primary variable, @code{SOURCES}
3144 If @code{hello_SOURCES} is not specified, then it defaults to the single
3145 file @file{hello.c} (@pxref{Default _SOURCES}).
3149 Multiple programs can be built in a single directory. Multiple programs
3150 can share a single source file, which must be listed in each
3151 @code{_SOURCES} definition.
3153 @cindex Header files in @code{_SOURCES}
3154 @cindex @code{_SOURCES} and header files
3156 Header files listed in a @code{_SOURCES} definition will be included in
3157 the distribution but otherwise ignored. In case it isn't obvious, you
3158 should not include the header file generated by @file{configure} in a
3159 @code{_SOURCES} variable; this file should not be distributed. Lex
3160 (@file{.l}) and Yacc (@file{.y}) files can also be listed; see @ref{Yacc
3165 @subsection Linking the program
3167 If you need to link against libraries that are not found by
3168 @command{configure}, you can use @code{LDADD} to do so. This variable is
3169 used to specify additional objects or libraries to link with; it is
3170 inappropriate for specifying specific linker flags, you should use
3171 @code{AM_LDFLAGS} for this purpose.
3175 @cindex @code{prog_LDADD}, defined
3177 Sometimes, multiple programs are built in one directory but do not share
3178 the same link-time requirements. In this case, you can use the
3179 @code{@var{prog}_LDADD} variable (where @var{prog} is the name of the
3180 program as it appears in some @code{_PROGRAMS} variable, and usually
3181 written in lowercase) to override the global @code{LDADD}. If this
3182 variable exists for a given program, then that program is not linked
3186 For instance, in GNU cpio, @code{pax}, @code{cpio} and @code{mt} are
3187 linked against the library @file{libcpio.a}. However, @code{rmt} is
3188 built in the same directory, and has no such link requirement. Also,
3189 @code{mt} and @code{rmt} are only built on certain architectures. Here
3190 is what cpio's @file{src/Makefile.am} looks like (abridged):
3193 bin_PROGRAMS = cpio pax $(MT)
3194 libexec_PROGRAMS = $(RMT)
3195 EXTRA_PROGRAMS = mt rmt
3197 LDADD = ../lib/libcpio.a $(INTLLIBS)
3200 cpio_SOURCES = @dots{}
3201 pax_SOURCES = @dots{}
3202 mt_SOURCES = @dots{}
3203 rmt_SOURCES = @dots{}
3206 @cindex @code{_LDFLAGS}, defined
3207 @vindex maude_LDFLAGS
3208 @code{@var{prog}_LDADD} is inappropriate for passing program-specific
3209 linker flags (except for @option{-l}, @option{-L}, @option{-dlopen} and
3210 @option{-dlpreopen}). So, use the @code{@var{prog}_LDFLAGS} variable for
3213 @cindex @code{_DEPENDENCIES}, defined
3214 @vindex maude_DEPENDENCIES
3215 It is also occasionally useful to have a program depend on some other
3216 target that is not actually part of that program. This can be done
3217 using the @code{@var{prog}_DEPENDENCIES} variable. Each program depends
3218 on the contents of such a variable, but no further interpretation is
3221 If @code{@var{prog}_DEPENDENCIES} is not supplied, it is computed by
3222 Automake. The automatically-assigned value is the contents of
3223 @code{@var{prog}_LDADD}, with most configure substitutions, @option{-l},
3224 @option{-L}, @option{-dlopen} and @option{-dlpreopen} options removed. The
3225 configure substitutions that are left in are only @samp{$(LIBOBJS)} and
3226 @samp{$(ALLOCA)}; these are left because it is known that they will not
3227 cause an invalid value for @code{@var{prog}_DEPENDENCIES} to be
3230 @cindex @code{LDADD} and @option{-l}
3231 @cindex @option{-l} and @code{LDADD}
3232 We recommend that you avoid using @option{-l} options in @code{LDADD}
3233 or @code{@var{prog}_LDADD} when referring to libraries built by your
3234 package. Instead, write the file name of the library explicitly as in
3235 the above @code{cpio} example. Use @option{-l} only to list
3236 third-party libraries. If you follow this rule, the default value of
3237 @code{@var{prog}_DEPENDENCIES} will list all your local libraries and
3238 omit the other ones.
3241 @node Conditional Sources
3242 @subsection Conditional compilation of sources
3244 You can't put a configure substitution (e.g., @samp{@@FOO@@} or
3245 @samp{$(FOO)} where @code{FOO} is defined via @code{AC_SUBST}) into a
3246 @code{_SOURCES} variable. The reason for this is a bit hard to
3247 explain, but suffice to say that it simply won't work. Automake will
3248 give an error if you try to do this.
3250 Fortunately there are two other ways to achieve the same result. One is
3251 to use configure substitutions in @code{_LDADD} variables, the other is
3252 to use an Automake conditional.
3254 @subsubsection Conditional compilation using @code{_LDADD} substitutions
3256 @cindex @code{EXTRA_prog_SOURCES}, defined
3258 Automake must know all the source files that could possibly go into a
3259 program, even if not all the files are built in every circumstance. Any
3260 files that are only conditionally built should be listed in the
3261 appropriate @code{EXTRA_} variable. For instance, if
3262 @file{hello-linux.c} or @file{hello-generic.c} were conditionally included
3263 in @code{hello}, the @file{Makefile.am} would contain:
3266 bin_PROGRAMS = hello
3267 hello_SOURCES = hello-common.c
3268 EXTRA_hello_SOURCES = hello-linux.c hello-generic.c
3269 hello_LDADD = $(HELLO_SYSTEM)
3270 hello_DEPENDENCIES = $(HELLO_SYSTEM)
3274 You can then setup the @samp{$(HELLO_SYSTEM)} substitution from
3275 @file{configure.ac}:
3280 *linux*) HELLO_SYSTEM='hello-linux.$(OBJEXT)' ;;
3281 *) HELLO_SYSTEM='hello-generic.$(OBJEXT)' ;;
3283 AC_SUBST([HELLO_SYSTEM])
3287 In this case, the variable @code{HELLO_SYSTEM} should be replaced by
3288 either @file{hello-linux.o} or @file{hello-generic.o}, and added to
3289 both @code{hello_DEPENDENCIES} and @code{hello_LDADD} in order to be
3290 built and linked in.
3292 @subsubsection Conditional compilation using Automake conditionals
3294 An often simpler way to compile source files conditionally is to use
3295 Automake conditionals. For instance, you could use this
3296 @file{Makefile.am} construct to build the same @file{hello} example:
3299 bin_PROGRAMS = hello
3301 hello_SOURCES = hello-linux.c hello-common.c
3303 hello_SOURCES = hello-generic.c hello-common.c
3307 In this case, @file{configure.ac} should setup the @code{LINUX}
3308 conditional using @code{AM_CONDITIONAL} (@pxref{Conditionals}).
3310 When using conditionals like this you don't need to use the
3311 @code{EXTRA_} variable, because Automake will examine the contents of
3312 each variable to construct the complete list of source files.
3314 If your program uses a lot of files, you will probably prefer a
3315 conditional @samp{+=}.
3318 bin_PROGRAMS = hello
3319 hello_SOURCES = hello-common.c
3321 hello_SOURCES += hello-linux.c
3323 hello_SOURCES += hello-generic.c
3327 @node Conditional Programs
3328 @subsection Conditional compilation of programs
3329 @cindex Conditional programs
3330 @cindex Programs, conditional
3332 Sometimes it is useful to determine the programs that are to be built
3333 at configure time. For instance, GNU @code{cpio} only builds
3334 @code{mt} and @code{rmt} under special circumstances. The means to
3335 achieve conditional compilation of programs are the same you can use
3336 to compile source files conditionally: substitutions or conditionals.
3338 @subsubsection Conditional programs using @command{configure} substitutions
3340 @vindex EXTRA_PROGRAMS
3341 @cindex @code{EXTRA_PROGRAMS}, defined
3342 In this case, you must notify Automake of all the programs that can
3343 possibly be built, but at the same time cause the generated
3344 @file{Makefile.in} to use the programs specified by @command{configure}.
3345 This is done by having @command{configure} substitute values into each
3346 @code{_PROGRAMS} definition, while listing all optionally built programs
3347 in @code{EXTRA_PROGRAMS}.
3350 bin_PROGRAMS = cpio pax $(MT)
3351 libexec_PROGRAMS = $(RMT)
3352 EXTRA_PROGRAMS = mt rmt
3355 As explained in @ref{EXEEXT}, Automake will rewrite
3356 @code{bin_PROGRAMS}, @code{libexec_PROGRAMS}, and
3357 @code{EXTRA_PROGRAMS}, appending @samp{$(EXEEXT)} to each binary.
3358 Obviously it cannot rewrite values obtained at run-time through
3359 @command{configure} substitutions, therefore you should take care of
3360 appending @samp{$(EXEEXT)} yourself, as in @samp{AC_SUBST([MT],
3361 ['mt$@{EXEEXT@}'])}.
3363 @subsubsection Conditional programs using Automake conditionals
3365 You can also use Automake conditionals (@pxref{Conditionals}) to
3366 select programs to be built. In this case you don't have to worry
3367 about @samp{$(EXEEXT)} or @code{EXTRA_PROGRAMS}.
3370 bin_PROGRAMS = cpio pax
3375 libexec_PROGRAMS = rmt
3381 @section Building a library
3383 @cindex @code{_LIBRARIES} primary, defined
3384 @cindex @code{LIBRARIES} primary, defined
3385 @cindex Primary variable, @code{LIBRARIES}
3388 @vindex lib_LIBRARIES
3389 @vindex pkglib_LIBRARIES
3390 @vindex noinst_LIBRARIES
3392 Building a library is much like building a program. In this case, the
3393 name of the primary is @code{LIBRARIES}. Libraries can be installed in
3394 @code{libdir} or @code{pkglibdir}.
3396 @xref{A Shared Library}, for information on how to build shared
3397 libraries using libtool and the @code{LTLIBRARIES} primary.
3399 Each @code{_LIBRARIES} variable is a list of the libraries to be built.
3400 For instance, to create a library named @file{libcpio.a}, but not install
3401 it, you would write:
3404 noinst_LIBRARIES = libcpio.a
3405 libcpio_a_SOURCES = @dots{}
3408 The sources that go into a library are determined exactly as they are
3409 for programs, via the @code{_SOURCES} variables. Note that the library
3410 name is canonicalized (@pxref{Canonicalization}), so the @code{_SOURCES}
3411 variable corresponding to @file{libcpio.a} is @samp{libcpio_a_SOURCES},
3412 not @samp{libcpio.a_SOURCES}.
3414 @vindex maude_LIBADD
3415 Extra objects can be added to a library using the
3416 @code{@var{library}_LIBADD} variable. This should be used for objects
3417 determined by @command{configure}. Again from @code{cpio}:
3420 libcpio_a_LIBADD = $(LIBOBJS) $(ALLOCA)
3423 In addition, sources for extra objects that will not exist until
3424 configure-time must be added to the @code{BUILT_SOURCES} variable
3427 Building a static library is done by compiling all object files, then
3428 by invoking @samp{$(AR) $(ARFLAGS)} followed by the name of the
3429 library and the list of objects, and finally by calling
3430 @samp{$(RANLIB)} on that library. You should call
3431 @code{AC_PROG_RANLIB} from your @file{configure.ac} to define
3432 @code{RANLIB} (Automake will complain otherwise). @code{AR} and
3433 @code{ARFLAGS} default to @code{ar} and @code{cru} respectively; you
3434 can override these two variables my setting them in your
3435 @file{Makefile.am}, by @code{AC_SUBST}ing them from your
3436 @file{configure.ac}, or by defining a per-library @code{maude_AR}
3437 variable (@pxref{Program and Library Variables}).
3439 @cindex Empty libraries
3440 Be careful when selecting library components conditionally. Because
3441 building an empty library is not portable, you should ensure that any
3442 library contains always at least one object.
3444 To use a static library when building a program, add it to
3445 @code{LDADD} for this program. In the following example, the program
3446 @file{cpio} is statically linked with the library @file{libcpio.a}.
3449 noinst_LIBRARIES = libcpio.a
3450 libcpio_a_SOURCES = @dots{}
3453 cpio_SOURCES = cpio.c @dots{}
3454 cpio_LDADD = libcpio.a
3458 @node A Shared Library
3459 @section Building a Shared Library
3461 @cindex Shared libraries, support for
3463 Building shared libraries portably is a relatively complex matter.
3464 For this reason, GNU Libtool (@pxref{Top, , Introduction, libtool, The
3465 Libtool Manual}) was created to help build shared libraries in a
3466 platform-independent way.
3469 * Libtool Concept:: Introducing Libtool
3470 * Libtool Libraries:: Declaring Libtool Libraries
3471 * Conditional Libtool Libraries:: Building Libtool Libraries Conditionally
3472 * Conditional Libtool Sources:: Choosing Library Sources Conditionally
3473 * Libtool Convenience Libraries:: Building Convenience Libtool Libraries
3474 * Libtool Modules:: Building Libtool Modules
3475 * Libtool Flags:: Using _LIBADD, _LDFLAGS, and _LIBTOOLFLAGS
3476 * LTLIBOBJS:: Using $(LTLIBOBJS) and $(LTALLOCA)
3477 * Libtool Issues:: Common Issues Related to Libtool's Use
3480 @node Libtool Concept
3481 @subsection The Libtool Concept
3483 @cindex @command{libtool}, introduction
3484 @cindex libtool library, definition
3485 @cindex suffix @file{.la}, defined
3486 @cindex @file{.la} suffix, defined
3488 Libtool abstracts shared and static libraries into a unified concept
3489 henceforth called @dfn{libtool libraries}. Libtool libraries are
3490 files using the @file{.la} suffix, and can designate a static library,
3491 a shared library, or maybe both. Their exact nature cannot be
3492 determined until @file{./configure} is run: not all platforms support
3493 all kinds of libraries, and users can explicitly select which
3494 libraries should be built. (However the package's maintainers can
3495 tune the default, @pxref{AC_PROG_LIBTOOL, , The @code{AC_PROG_LIBTOOL}
3496 macro, libtool, The Libtool Manual}.)
3498 @cindex suffix @file{.lo}, defined
3499 Because object files for shared and static libraries must be compiled
3500 differently, libtool is also used during compilation. Object files
3501 built by libtool are called @dfn{libtool objects}: these are files
3502 using the @file{.lo} suffix. Libtool libraries are built from these
3505 You should not assume anything about the structure of @file{.la} or
3506 @file{.lo} files and how libtool constructs them: this is libtool's
3507 concern, and the last thing one wants is to learn about libtool's
3508 guts. However the existence of these files matters, because they are
3509 used as targets and dependencies in @file{Makefile}s rules when
3510 building libtool libraries. There are situations where you may have
3511 to refer to these, for instance when expressing dependencies for
3512 building source files conditionally (@pxref{Conditional Libtool
3515 @cindex @file{libltdl}, introduction
3517 People considering writing a plug-in system, with dynamically loaded
3518 modules, should look into @file{libltdl}: libtool's dlopening library
3519 (@pxref{Using libltdl, , Using libltdl, libtool, The Libtool Manual}).
3520 This offers a portable dlopening facility to load libtool libraries
3521 dynamically, and can also achieve static linking where unavoidable.
3523 Before we discuss how to use libtool with Automake in details, it
3524 should be noted that the libtool manual also has a section about how
3525 to use Automake with libtool (@pxref{Using Automake, , Using Automake
3526 with Libtool, libtool, The Libtool Manual}).
3528 @node Libtool Libraries
3529 @subsection Building Libtool Libraries
3531 @cindex @code{_LTLIBRARIES} primary, defined
3532 @cindex @code{LTLIBRARIES} primary, defined
3533 @cindex Primary variable, @code{LTLIBRARIES}
3534 @cindex Example of shared libraries
3535 @vindex lib_LTLIBRARIES
3536 @vindex pkglib_LTLIBRARIES
3537 @vindex _LTLIBRARIES
3539 Automake uses libtool to build libraries declared with the
3540 @code{LTLIBRARIES} primary. Each @code{_LTLIBRARIES} variable is a
3541 list of libtool libraries to build. For instance, to create a libtool
3542 library named @file{libgettext.la}, and install it in @code{libdir},
3546 lib_LTLIBRARIES = libgettext.la
3547 libgettext_la_SOURCES = gettext.c gettext.h @dots{}
3550 Automake predefines the variable @code{pkglibdir}, so you can use
3551 @code{pkglib_LTLIBRARIES} to install libraries in
3552 @samp{$(libdir)/@@PACKAGE@@/}.
3554 If @file{gettext.h} is a public header file that needs to be installed
3555 in order for people to use the library, it should be declared using a
3556 @code{_HEADERS} variable, not in @code{libgettext_la_SOURCES}.
3557 Headers listed in the latter should be internal headers that are not
3558 part of the public interface.
3561 lib_LTLIBRARIES = libgettext.la
3562 libgettext_la_SOURCES = gettext.c @dots{}
3563 include_HEADERS = gettext.h @dots{}
3566 A package can build and install such a library along with other
3567 programs that use it. This dependency should be specified using
3568 @code{LDADD}. The following example builds a program named
3569 @file{hello} that is linked with @file{libgettext.la}.
3572 lib_LTLIBRARIES = libgettext.la
3573 libgettext_la_SOURCES = gettext.c @dots{}
3575 bin_PROGRAMS = hello
3576 hello_SOURCES = hello.c @dots{}
3577 hello_LDADD = libgettext.la
3581 Whether @file{hello} is statically or dynamically linked with
3582 @file{libgettext.la} is not yet known: this will depend on the
3583 configuration of libtool and the capabilities of the host.
3586 @node Conditional Libtool Libraries
3587 @subsection Building Libtool Libraries Conditionally
3588 @cindex libtool libraries, conditional
3589 @cindex conditional libtool libraries
3591 Like conditional programs (@pxref{Conditional Programs}), there are
3592 two main ways to build conditional libraries: using Automake
3593 conditionals or using Autoconf @code{AC_SUBST}itutions.
3595 The important implementation detail you have to be aware of is that
3596 the place where a library will be installed matters to libtool: it
3597 needs to be indicated @emph{at link-time} using the @option{-rpath}
3600 For libraries whose destination directory is known when Automake runs,
3601 Automake will automatically supply the appropriate @option{-rpath}
3602 option to libtool. This is the case for libraries listed explicitly in
3603 some installable @code{_LTLIBRARIES} variables such as
3604 @code{lib_LTLIBRARIES}.
3606 However, for libraries determined at configure time (and thus
3607 mentioned in @code{EXTRA_LTLIBRARIES}), Automake does not know the
3608 final installation directory. For such libraries you must add the
3609 @option{-rpath} option to the appropriate @code{_LDFLAGS} variable by
3612 The examples below illustrate the differences between these two methods.
3614 Here is an example where @code{WANTEDLIBS} is an @code{AC_SUBST}ed
3615 variable set at @file{./configure}-time to either @file{libfoo.la},
3616 @file{libbar.la}, both, or none. Although @samp{$(WANTEDLIBS)}
3617 appears in the @code{lib_LTLIBRARIES}, Automake cannot guess it
3618 relates to @file{libfoo.la} or @file{libbar.la} by the time it creates
3619 the link rule for these two libraries. Therefore the @option{-rpath}
3620 argument must be explicitly supplied.
3623 EXTRA_LTLIBRARIES = libfoo.la libbar.la
3624 lib_LTLIBRARIES = $(WANTEDLIBS)
3625 libfoo_la_SOURCES = foo.c @dots{}
3626 libfoo_la_LDFLAGS = -rpath '$(libdir)'
3627 libbar_la_SOURCES = bar.c @dots{}
3628 libbar_la_LDFLAGS = -rpath '$(libdir)'
3631 Here is how the same @file{Makefile.am} would look using Automake
3632 conditionals named @code{WANT_LIBFOO} and @code{WANT_LIBBAR}. Now
3633 Automake is able to compute the @option{-rpath} setting itself, because
3634 it's clear that both libraries will end up in @samp{$(libdir)} if they
3640 lib_LTLIBRARIES += libfoo.la
3643 lib_LTLIBRARIES += libbar.la
3645 libfoo_la_SOURCES = foo.c @dots{}
3646 libbar_la_SOURCES = bar.c @dots{}
3649 @node Conditional Libtool Sources
3650 @subsection Libtool Libraries with Conditional Sources
3652 Conditional compilation of sources in a library can be achieved in the
3653 same way as conditional compilation of sources in a program
3654 (@pxref{Conditional Sources}). The only difference is that
3655 @code{_LIBADD} should be used instead of @code{_LDADD} and that it
3656 should mention libtool objects (@file{.lo} files).
3658 So, to mimic the @file{hello} example from @ref{Conditional Sources},
3659 we could build a @file{libhello.la} library using either
3660 @file{hello-linux.c} or @file{hello-generic.c} with the following
3664 lib_LTLIBRARIES = libhello.la
3665 libhello_la_SOURCES = hello-common.c
3666 EXTRA_libhello_la_SOURCES = hello-linux.c hello-generic.c
3667 libhello_la_LIBADD = $(HELLO_SYSTEM)
3668 libhello_la_DEPENDENCIES = $(HELLO_SYSTEM)
3672 And make sure @command{configure} defines @code{HELLO_SYSTEM} as
3673 either @file{hello-linux.lo} or @file{hello-@-generic.lo}.
3675 Or we could simply use an Automake conditional as follows.
3678 lib_LTLIBRARIES = libhello.la
3679 libhello_la_SOURCES = hello-common.c
3681 libhello_la_SOURCES += hello-linux.c
3683 libhello_la_SOURCES += hello-generic.c
3687 @node Libtool Convenience Libraries
3688 @subsection Libtool Convenience Libraries
3689 @cindex convenience libraries, libtool
3690 @cindex libtool convenience libraries
3691 @vindex noinst_LTLIBRARIES
3692 @vindex check_LTLIBRARIES
3694 Sometimes you want to build libtool libraries that should not be
3695 installed. These are called @dfn{libtool convenience libraries} and
3696 are typically used to encapsulate many sublibraries, later gathered
3697 into one big installed library.
3699 Libtool convenience libraries are declared by directory-less variables
3700 such as @code{noinst_LTLIBRARIES}, @code{check_LTLIBRARIES}, or even
3701 @code{EXTRA_LTLIBRARIES}. Unlike installed libtool libraries they do
3702 not need an @option{-rpath} flag at link time (actually this is the only
3705 Convenience libraries listed in @code{noinst_LTLIBRARIES} are always
3706 built. Those listed in @code{check_LTLIBRARIES} are built only upon
3707 @samp{make check}. Finally, libraries listed in
3708 @code{EXTRA_LTLIBRARIES} are never built explicitly: Automake outputs
3709 rules to build them, but if the library does not appear as a Makefile
3710 dependency anywhere it won't be built (this is why
3711 @code{EXTRA_LTLIBRARIES} is used for conditional compilation).
3713 Here is a sample setup merging libtool convenience libraries from
3714 subdirectories into one main @file{libtop.la} library.
3717 # -- Top-level Makefile.am --
3718 SUBDIRS = sub1 sub2 @dots{}
3719 lib_LTLIBRARIES = libtop.la
3721 libtop_la_LIBADD = \
3726 # -- sub1/Makefile.am --
3727 noinst_LTLIBRARIES = libsub1.la
3728 libsub1_la_SOURCES = @dots{}
3730 # -- sub2/Makefile.am --
3731 # showing nested convenience libraries
3732 SUBDIRS = sub2.1 sub2.2 @dots{}
3733 noinst_LTLIBRARIES = libsub2.la
3734 libsub2_la_SOURCES =
3735 libsub2_la_LIBADD = \
3741 When using such setup, beware that @command{automake} will assume
3742 @file{libtop.la} is to be linked with the C linker. This is because
3743 @code{libtop_la_SOURCES} is empty, so @command{automake} picks C as
3744 default language. If @code{libtop_la_SOURCES} was not empty,
3745 @command{automake} would select the linker as explained in @ref{How
3746 the Linker is Chosen}.
3748 If one of the sublibraries contains non-C source, it is important that
3749 the appropriate linker be chosen. One way to achieve this is to
3750 pretend that there is such a non-C file among the sources of the
3751 library, thus forcing @command{automake} to select the appropriate
3752 linker. Here is the top-level @file{Makefile} of our example updated
3753 to force C++ linking.
3756 SUBDIRS = sub1 sub2 @dots{}
3757 lib_LTLIBRARIES = libtop.la
3759 # Dummy C++ source to cause C++ linking.
3760 nodist_EXTRA_libtop_la_SOURCES = dummy.cxx
3761 libtop_la_LIBADD = \
3767 @samp{EXTRA_*_SOURCES} variables are used to keep track of source
3768 files that might be compiled (this is mostly useful when doing
3769 conditional compilation using @code{AC_SUBST}, @pxref{Conditional
3770 Libtool Sources}), and the @code{nodist_} prefix means the listed
3771 sources are not to be distributed (@pxref{Program and Library
3772 Variables}). In effect the file @file{dummy.cxx} does not need to
3773 exist in the source tree. Of course if you have some real source file
3774 to list in @code{libtop_la_SOURCES} there is no point in cheating with
3775 @code{nodist_EXTRA_libtop_la_SOURCES}.
3778 @node Libtool Modules
3779 @subsection Libtool Modules
3780 @cindex modules, libtool
3781 @cindex libtool modules
3782 @cindex @option{-module}, libtool
3784 These are libtool libraries meant to be dlopened. They are
3785 indicated to libtool by passing @option{-module} at link-time.
3788 pkglib_LTLIBRARIES = mymodule.la
3789 mymodule_la_SOURCES = doit.c
3790 mymodule_la_LDFLAGS = -module
3793 Ordinarily, Automake requires that a library's name starts with
3794 @code{lib}. However, when building a dynamically loadable module you
3795 might wish to use a "nonstandard" name. Automake will not complain
3796 about such nonstandard name if it knows the library being built is a
3797 libtool module, i.e., if @option{-module} explicitly appears in the
3798 library's @code{_LDFLAGS} variable (or in the common @code{AM_LDFLAGS}
3799 variable when no per-library @code{_LDFLAGS} variable is defined).
3801 As always, @code{AC_SUBST} variables are black boxes to Automake since
3802 their values are not yet known when @command{automake} is run.
3803 Therefore if @option{-module} is set via such a variable, Automake
3804 cannot notice it and will proceed as if the library was an ordinary
3805 libtool library, with strict naming.
3807 If @code{mymodule_la_SOURCES} is not specified, then it defaults to
3808 the single file @file{mymodule.c} (@pxref{Default _SOURCES}).
3811 @subsection @code{_LIBADD}, @code{_LDFLAGS}, and @code{_LIBTOOLFLAGS}
3812 @cindex @code{_LIBADD}, libtool
3813 @cindex @code{_LDFLAGS}, libtool
3814 @cindex @code{_LIBTOOLFLAGS}, libtool
3815 @vindex AM_LIBTOOLFLAGS
3816 @vindex LIBTOOLFLAGS
3817 @vindex maude_LIBTOOLFLAGS
3819 As shown in previous sections, the @samp{@var{library}_LIBADD}
3820 variable should be used to list extra libtool objects (@file{.lo}
3821 files) or libtool libraries (@file{.la}) to add to @var{library}.
3823 The @samp{@var{library}_LDFLAGS} variable is the place to list
3824 additional libtool linking flags, such as @option{-version-info},
3825 @option{-static}, and a lot more. @xref{Link mode, , Link mode,
3826 libtool, The Libtool Manual}.
3828 The @command{libtool} command has two kinds of options: mode-specific
3829 options and generic options. Mode-specific options such as the
3830 aforementioned linking flags should be lumped with the other flags
3831 passed to the tool invoked by @command{libtool} (hence the use of
3832 @samp{@var{library}_LDFLAGS} for libtool linking flags). Generic
3833 options include @option{--tag=@var{TAG}} and @option{--silent}
3834 (@pxref{Invoking libtool, , Invoking @command{libtool}, libtool, The
3835 Libtool Manual} for more options) should appear before the mode
3836 selection on the command line; in @file{Makefile.am}s they should
3837 be listed in the @samp{@var{library}_LIBTOOLFLAGS} variable.
3839 If @samp{@var{library}_LIBTOOLFLAGS} is not defined, the global
3840 @code{AM_LIBTOOLFLAGS} variable is used instead.
3842 These flags are passed to libtool after the @option{--tag=@var{TAG}}
3843 option computed by Automake (if any), so
3844 @samp{@var{library}_LIBTOOLFLAGS} (or @code{AM_LIBTOOLFLAGS}) is the
3845 good place to override or supplement the @option{--tag=@var{TAG}}
3848 The libtool rules also use a @code{LIBTOOLFLAGS} variable that should
3849 not be set in @file{Makefile.am}: this is a user variable (@pxref{Flag
3850 Variables Ordering}. It allows users to run @samp{make
3851 LIBTOOLFLAGS=--silent}, for instance.
3854 @node LTLIBOBJS, Libtool Issues, Libtool Flags, A Shared Library
3855 @subsection @code{LTLIBOBJS} and @code{LTALLOCA}
3856 @cindex @code{LTLIBOBJS}, special handling
3857 @cindex @code{LIBOBJS}, and Libtool
3858 @cindex @code{LTALLOCA}, special handling
3859 @cindex @code{ALLOCA}, and Libtool
3866 Where an ordinary library might include @samp{$(LIBOBJS)} or
3867 @samp{$(ALLOCA)} (@pxref{LIBOBJS}), a libtool library must use
3868 @samp{$(LTLIBOBJS)} or @samp{$(LTALLOCA)}. This is required because
3869 the object files that libtool operates on do not necessarily end in
3872 Nowadays, the computation of @code{LTLIBOBJS} from @code{LIBOBJS} is
3873 performed automatically by Autoconf (@pxref{AC_LIBOBJ vs LIBOBJS, ,
3874 @code{AC_LIBOBJ} vs.@: @code{LIBOBJS}, autoconf, The Autoconf Manual}).
3876 @node Libtool Issues
3877 @subsection Common Issues Related to Libtool's Use
3879 @subsubsection @samp{required file `./ltmain.sh' not found}
3880 @cindex @file{ltmain.sh} not found
3881 @cindex @command{libtoolize}, no longer run by @command{automake}
3882 @cindex @command{libtoolize} and @command{autoreconf}
3883 @cindex @command{autoreconf} and @command{libtoolize}
3884 @cindex @file{bootstrap.sh} and @command{autoreconf}
3885 @cindex @file{autogen.sh} and @command{autoreconf}
3887 Libtool comes with a tool called @command{libtoolize} that will
3888 install libtool's supporting files into a package. Running this
3889 command will install @file{ltmain.sh}. You should execute it before
3890 @command{aclocal} and @command{automake}.
3892 People upgrading old packages to newer autotools are likely to face
3893 this issue because older Automake versions used to call
3894 @command{libtoolize}. Therefore old build scripts do not call
3895 @command{libtoolize}.
3897 Since Automake 1.6, it has been decided that running
3898 @command{libtoolize} was none of Automake's business. Instead, that
3899 functionality has been moved into the @command{autoreconf} command
3900 (@pxref{autoreconf Invocation, , Using @command{autoreconf}, autoconf,
3901 The Autoconf Manual}). If you do not want to remember what to run and
3902 when, just learn the @command{autoreconf} command. Hopefully,
3903 replacing existing @file{bootstrap.sh} or @file{autogen.sh} scripts by
3904 a call to @command{autoreconf} should also free you from any similar
3905 incompatible change in the future.
3907 @subsubsection Objects @samp{created with both libtool and without}
3909 Sometimes, the same source file is used both to build a libtool
3910 library and to build another non-libtool target (be it a program or
3913 Let's consider the following @file{Makefile.am}.
3917 prog_SOURCES = prog.c foo.c @dots{}
3919 lib_LTLIBRARIES = libfoo.la
3920 libfoo_la_SOURCES = foo.c @dots{}
3924 (In this trivial case the issue could be avoided by linking
3925 @file{libfoo.la} with @file{prog} instead of listing @file{foo.c} in
3926 @code{prog_SOURCES}. But let's assume we really want to keep
3927 @file{prog} and @file{libfoo.la} separate.)
3929 Technically, it means that we should build @file{foo.$(OBJEXT)} for
3930 @file{prog}, and @file{foo.lo} for @file{libfoo.la}. The problem is
3931 that in the course of creating @file{foo.lo}, libtool may erase (or
3932 replace) @file{foo.$(OBJEXT)}, and this cannot be avoided.
3934 Therefore, when Automake detects this situation it will complain
3935 with a message such as
3937 object `foo.$(OBJEXT)' created both with libtool and without
3940 A workaround for this issue is to ensure that these two objects get
3941 different basenames. As explained in @ref{renamed objects}, this
3942 happens automatically when per-targets flags are used.
3946 prog_SOURCES = prog.c foo.c @dots{}
3947 prog_CFLAGS = $(AM_CFLAGS)
3949 lib_LTLIBRARIES = libfoo.la
3950 libfoo_la_SOURCES = foo.c @dots{}
3954 Adding @samp{prog_CFLAGS = $(AM_CFLAGS)} is almost a no-op, because
3955 when the @code{prog_CFLAGS} is defined, it is used instead of
3956 @code{AM_CFLAGS}. However as a side effect it will cause
3957 @file{prog.c} and @file{foo.c} to be compiled as
3958 @file{prog-prog.$(OBJEXT)} and @file{prog-foo.$(OBJEXT)}, which solves
3961 @node Program and Library Variables
3962 @section Program and Library Variables
3964 Associated with each program are a collection of variables that can be
3965 used to modify how that program is built. There is a similar list of
3966 such variables for each library. The canonical name of the program (or
3967 library) is used as a base for naming these variables.
3969 In the list below, we use the name ``maude'' to refer to the program or
3970 library. In your @file{Makefile.am} you would replace this with the
3971 canonical name of your program. This list also refers to ``maude'' as a
3972 program, but in general the same rules apply for both static and dynamic
3973 libraries; the documentation below notes situations where programs and
3978 This variable, if it exists, lists all the source files that are
3979 compiled to build the program. These files are added to the
3980 distribution by default. When building the program, Automake will cause
3981 each source file to be compiled to a single @file{.o} file (or
3982 @file{.lo} when using libtool). Normally these object files are named
3983 after the source file, but other factors can change this. If a file in
3984 the @code{_SOURCES} variable has an unrecognized extension, Automake
3985 will do one of two things with it. If a suffix rule exists for turning
3986 files with the unrecognized extension into @file{.o} files, then
3987 automake will treat this file as it will any other source file
3988 (@pxref{Support for Other Languages}). Otherwise, the file will be
3989 ignored as though it were a header file.
3991 The prefixes @code{dist_} and @code{nodist_} can be used to control
3992 whether files listed in a @code{_SOURCES} variable are distributed.
3993 @code{dist_} is redundant, as sources are distributed by default, but it
3994 can be specified for clarity if desired.
3996 It is possible to have both @code{dist_} and @code{nodist_} variants of
3997 a given @code{_SOURCES} variable at once; this lets you easily
3998 distribute some files and not others, for instance:
4001 nodist_maude_SOURCES = nodist.c
4002 dist_maude_SOURCES = dist-me.c
4005 By default the output file (on Unix systems, the @file{.o} file) will
4006 be put into the current build directory. However, if the option
4007 @option{subdir-objects} is in effect in the current directory then the
4008 @file{.o} file will be put into the subdirectory named after the
4009 source file. For instance, with @option{subdir-objects} enabled,
4010 @file{sub/dir/file.c} will be compiled to @file{sub/dir/file.o}. Some
4011 people prefer this mode of operation. You can specify
4012 @option{subdir-objects} in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
4013 @cindex Subdirectory, objects in
4014 @cindex Objects in subdirectory
4017 @item EXTRA_maude_SOURCES
4018 Automake needs to know the list of files you intend to compile
4019 @emph{statically}. For one thing, this is the only way Automake has of
4020 knowing what sort of language support a given @file{Makefile.in}
4021 requires. @footnote{There are other, more obscure reasons for
4022 this limitation as well.} This means that, for example, you can't put a
4023 configure substitution like @samp{@@my_sources@@} into a @samp{_SOURCES}
4024 variable. If you intend to conditionally compile source files and use
4025 @file{configure} to substitute the appropriate object names into, e.g.,
4026 @code{_LDADD} (see below), then you should list the corresponding source
4027 files in the @code{EXTRA_} variable.
4029 This variable also supports @code{dist_} and @code{nodist_} prefixes.
4030 For instance, @code{nodist_EXTRA_maude_SOURCES} would list extra
4031 sources that may need to be built, but should not be distributed.
4034 A static library is created by default by invoking @samp{$(AR)
4035 $(ARFLAGS)} followed by the name of the library and then the objects
4036 being put into the library. You can override this by setting the
4037 @code{_AR} variable. This is usually used with C++; some C++
4038 compilers require a special invocation in order to instantiate all the
4039 templates that should go into a library. For instance, the SGI C++
4040 compiler likes this variable set like so:
4042 libmaude_a_AR = $(CXX) -ar -o
4046 Extra objects can be added to a @emph{library} using the @code{_LIBADD}
4047 variable. For instance, this should be used for objects determined by
4048 @command{configure} (@pxref{A Library}).
4050 In the case of libtool libraries, @code{maude_LIBADD} can also refer
4051 to other libtool libraries.
4054 Extra objects (@file{*.$(OBJEXT)}) and libraries (@file{*.a},
4055 @file{*.la}) can be added to a @emph{program} by listing them in the
4056 @code{_LDADD} variable. For instance, this should be used for objects
4057 determined by @command{configure} (@pxref{Linking}).
4059 @code{_LDADD} and @code{_LIBADD} are inappropriate for passing
4060 program-specific linker flags (except for @option{-l}, @option{-L},
4061 @option{-dlopen} and @option{-dlpreopen}). Use the @code{_LDFLAGS} variable
4064 For instance, if your @file{configure.ac} uses @code{AC_PATH_XTRA}, you
4065 could link your program against the X libraries like so:
4068 maude_LDADD = $(X_PRE_LIBS) $(X_LIBS) $(X_EXTRA_LIBS)
4071 We recommend that you use @option{-l} and @option{-L} only when
4072 referring to third-party libraries, and give the explicit file names
4073 of any library built by your package. Doing so will ensure that
4074 @code{maude_DEPENDENCIES} (see below) is correctly defined by default.
4077 This variable is used to pass extra flags to the link step of a program
4078 or a shared library. It overrides the global @code{AM_LDFLAGS} variable.
4080 @item maude_LIBTOOLFLAGS
4081 This variable is used to pass extra options to @command{libtool}.
4082 It overrides the global @code{AM_LIBTOOLFLAGS} variable.
4083 These options are output before @command{libtool}'s @option{--mode=@var{MODE}}
4084 option, so they should not be mode-specific options (those belong to
4085 the compiler or linker flags). @xref{Libtool Flags}.
4087 @item maude_DEPENDENCIES
4088 It is also occasionally useful to have a program depend on some other
4089 target that is not actually part of that program. This can be done
4090 using the @code{_DEPENDENCIES} variable. Each program depends on the
4091 contents of such a variable, but no further interpretation is done.
4093 If @code{_DEPENDENCIES} is not supplied, it is computed by Automake.
4094 The automatically-assigned value is the contents of @code{_LDADD} or
4095 @code{_LIBADD}, with most configure substitutions, @option{-l}, @option{-L},
4096 @option{-dlopen} and @option{-dlpreopen} options removed. The configure
4097 substitutions that are left in are only @samp{$(LIBOBJS)} and
4098 @samp{$(ALLOCA)}; these are left because it is known that they will not
4099 cause an invalid value for @code{_DEPENDENCIES} to be generated.
4102 You can override the linker on a per-program basis. By default the
4103 linker is chosen according to the languages used by the program. For
4104 instance, a program that includes C++ source code would use the C++
4105 compiler to link. The @code{_LINK} variable must hold the name of a
4106 command that can be passed all the @file{.o} file names as arguments.
4107 Note that the name of the underlying program is @emph{not} passed to
4108 @code{_LINK}; typically one uses @samp{$@@}:
4111 maude_LINK = $(CCLD) -magic -o $@@
4114 @item maude_CCASFLAGS
4116 @itemx maude_CPPFLAGS
4117 @itemx maude_CXXFLAGS
4119 @itemx maude_GCJFLAGS
4121 @itemx maude_OBJCFLAGS
4124 @cindex per-target compilation flags, defined
4125 Automake allows you to set compilation flags on a per-program (or
4126 per-library) basis. A single source file can be included in several
4127 programs, and it will potentially be compiled with different flags for
4128 each program. This works for any language directly supported by
4129 Automake. These @dfn{per-target compilation flags} are
4141 When using a per-target compilation flag, Automake will choose a
4142 different name for the intermediate object files. Ordinarily a file
4143 like @file{sample.c} will be compiled to produce @file{sample.o}.
4144 However, if the program's @code{_CFLAGS} variable is set, then the
4145 object file will be named, for instance, @file{maude-sample.o}. (See
4146 also @ref{renamed objects}.) The use of per-target compilation flags
4147 with C sources requires that the macro @code{AM_PROG_CC_C_O} be called
4148 from @file{configure.ac}.
4150 In compilations with per-target flags, the ordinary @samp{AM_} form of
4151 the flags variable is @emph{not} automatically included in the
4152 compilation (however, the user form of the variable @emph{is} included).
4153 So for instance, if you want the hypothetical @file{maude} compilations
4154 to also use the value of @code{AM_CFLAGS}, you would need to write:
4157 maude_CFLAGS = @dots{} your flags @dots{} $(AM_CFLAGS)
4160 @xref{Flag Variables Ordering}, for more discussion about the
4161 interaction between user variables, @samp{AM_} shadow variables, and
4162 per-target variables.
4164 @item maude_SHORTNAME
4165 On some platforms the allowable file names are very short. In order to
4166 support these systems and per-target compilation flags at the same
4167 time, Automake allows you to set a ``short name'' that will influence
4168 how intermediate object files are named. For instance, in the following
4172 bin_PROGRAMS = maude
4173 maude_CPPFLAGS = -DSOMEFLAG
4175 maude_SOURCES = sample.c @dots{}
4179 the object file would be named @file{m-sample.o} rather than
4180 @file{maude-sample.o}.
4182 This facility is rarely needed in practice,
4183 and we recommend avoiding it until you find it is required.
4186 @node Default _SOURCES
4187 @section Default @code{_SOURCES}
4191 @cindex @code{_SOURCES}, default
4192 @cindex default @code{_SOURCES}
4194 @code{_SOURCES} variables are used to specify source files of programs
4195 (@pxref{A Program}), libraries (@pxref{A Library}), and Libtool
4196 libraries (@pxref{A Shared Library}).
4198 When no such variable is specified for a target, Automake will define
4199 one itself. The default is to compile a single C file whose base name
4200 is the name of the target itself, with any extension replaced by
4201 @file{.c}. (Defaulting to C is terrible but we are stuck with it for
4202 historical reasons.)
4204 For example if you have the following somewhere in your
4205 @file{Makefile.am} with no corresponding @code{libfoo_a_SOURCES}:
4208 lib_LIBRARIES = libfoo.a sub/libc++.a
4212 @file{libfoo.a} will be built using a default source file named
4213 @file{libfoo.c}, and @file{sub/libc++.a} will be built from
4214 @file{sub/libc++.c}. (In older versions @file{sub/libc++.a}
4215 would be built from @file{sub_libc___a.c}, i.e., the default source
4216 was the canonized name of the target, with @file{.c} appended.
4217 We believe the new behavior is more sensible, but for backward
4218 compatibility automake will use the old name if a file or a rule
4219 with that name exist.)
4221 @cindex @code{check_PROGRAMS} example
4222 @vindex check_PROGRAMS
4223 Default sources are mainly useful in test suites, when building many
4224 tests programs each from a single source. For instance, in
4227 check_PROGRAMS = test1 test2 test3
4231 @file{test1}, @file{test2}, and @file{test3} will be built
4232 from @file{test1.c}, @file{test2.c}, and @file{test3.c}.
4234 @cindex Libtool modules, default source example
4235 @cindex default source, Libtool modules example
4236 Another case where is this convenient is building many Libtool modules
4237 (@file{moduleN.la}), each defined in its own file (@file{moduleN.c}).
4240 AM_LDFLAGS = -module
4241 lib_LTLIBRARIES = module1.la module2.la module3.la
4244 @cindex empty @code{_SOURCES}
4245 @cindex @code{_SOURCES}, empty
4246 Finally, there is one situation where this default source computation
4247 needs to be avoided: when a target should not be built from sources.
4248 We already saw such an example in @ref{true}; this happens when all
4249 the constituents of a target have already been compiled and need just
4250 to be combined using a @code{_LDADD} variable. Then it is necessary
4251 to define an empty @code{_SOURCES} variable, so that automake does not
4255 bin_PROGRAMS = target
4257 target_LDADD = libmain.a libmisc.a
4261 @section Special handling for @code{LIBOBJS} and @code{ALLOCA}
4263 @cindex @code{LIBOBJS}, example
4264 @cindex @code{ALLOCA}, example
4265 @cindex @code{LIBOBJS}, special handling
4266 @cindex @code{ALLOCA}, special handling
4272 The @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} variables list object
4273 files that should be compiled into the project to provide an
4274 implementation for functions that are missing or broken on the host
4275 system. They are substituted by @file{configure}.
4279 These variables are defined by Autoconf macros such as
4280 @code{AC_LIBOBJ}, @code{AC_REPLACE_FUNCS} (@pxref{Generic Functions, ,
4281 Generic Function Checks, autoconf, The Autoconf Manual}), or
4282 @code{AC_FUNC_ALLOCA} (@pxref{Particular Functions, , Particular
4283 Function Checks, autoconf, The Autoconf Manual}). Many other Autoconf
4284 macros call @code{AC_LIBOBJ} or @code{AC_REPLACE_FUNCS} to
4285 populate @samp{$(LIBOBJS)}.
4287 @acindex AC_LIBSOURCE
4289 Using these variables is very similar to doing conditional compilation
4290 using @code{AC_SUBST} variables, as described in @ref{Conditional
4291 Sources}. That is, when building a program, @samp{$(LIBOBJS)} and
4292 @samp{$(ALLOCA)} should be added to the associated @samp{*_LDADD}
4293 variable, or to the @samp{*_LIBADD} variable when building a library.
4294 However there is no need to list the corresponding sources in
4295 @samp{EXTRA_*_SOURCES} nor to define @samp{*_DEPENDENCIES}. Automake
4296 automatically adds @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} to the
4297 dependencies, and it will discover the list of corresponding source
4298 files automatically (by tracing the invocations of the
4299 @code{AC_LIBSOURCE} Autoconf macros).
4301 These variables are usually used to build a portability library that
4302 is linked with all the programs of the project. We now review a
4303 sample setup. First, @file{configure.ac} contains some checks that
4304 affect either @code{LIBOBJS} or @code{ALLOCA}.
4309 AC_CONFIG_LIBOBJ_DIR([lib])
4311 AC_FUNC_MALLOC dnl May add malloc.$(OBJEXT) to LIBOBJS
4312 AC_FUNC_MEMCMP dnl May add memcmp.$(OBJEXT) to LIBOBJS
4313 AC_REPLACE_FUNCS([strdup]) dnl May add strdup.$(OBJEXT) to LIBOBJS
4314 AC_FUNC_ALLOCA dnl May add alloca.$(OBJEXT) to ALLOCA
4323 @acindex AC_CONFIG_LIBOBJ_DIR
4325 The @code{AC_CONFIG_LIBOBJ_DIR} tells Autoconf that the source files
4326 of these object files are to be found in the @file{lib/} directory.
4327 Automake can also use this information, otherwise it expects the
4328 source files are to be in the directory where the @samp{$(LIBOBJS)}
4329 and @samp{$(ALLOCA)} variables are used.
4331 The @file{lib/} directory should therefore contain @file{malloc.c},
4332 @file{memcmp.c}, @file{strdup.c}, @file{alloca.c}. Here is its
4338 noinst_LIBRARIES = libcompat.a
4339 libcompat_a_SOURCES =
4340 libcompat_a_LIBADD = $(LIBOBJS) $(ALLOCA)
4343 The library can have any name, of course, and anyway it is not going
4344 to be installed: it just holds the replacement versions of the missing
4345 or broken functions so we can later link them in. In many projects
4346 also include extra functions, specific to the project, in that
4347 library: they are simply added on the @code{_SOURCES} line.
4349 @cindex Empty libraries and @samp{$(LIBOBJS)}
4350 @cindex @samp{$(LIBOBJS)} and empty libraries
4351 There is a small trap here, though: @samp{$(LIBOBJS)} and
4352 @samp{$(ALLOCA)} might be empty, and building an empty library is not
4353 portable. You should ensure that there is always something to put in
4354 @file{libcompat.a}. Most projects will also add some utility
4355 functions in that directory, and list them in
4356 @code{libcompat_a_SOURCES}, so in practice @file{libcompat.a} cannot
4359 Finally here is how this library could be used from the @file{src/}
4365 # Link all programs in this directory with libcompat.a
4366 LDADD = ../lib/libcompat.a
4368 bin_PROGRAMS = tool1 tool2 @dots{}
4369 tool1_SOURCES = @dots{}
4370 tool2_SOURCES = @dots{}
4373 When option @option{subdir-objects} is not used, as in the above
4374 example, the variables @samp{$(LIBOBJS)} or @samp{$(ALLOCA)} can only
4375 be used in the directory where their sources lie. E.g., here it would
4376 be wrong to use @samp{$(LIBOBJS)} or @samp{$(ALLOCA)} in
4377 @file{src/Makefile.am}. However if both @option{subdir-objects} and
4378 @code{AC_CONFIG_LIBOBJ_DIR} are used, it is OK to use these variables
4379 in other directories. For instance @file{src/Makefile.am} could be
4385 AUTOMAKE_OPTIONS = subdir-objects
4386 LDADD = $(LIBOBJS) $(ALLOCA)
4388 bin_PROGRAMS = tool1 tool2 @dots{}
4389 tool1_SOURCES = @dots{}
4390 tool2_SOURCES = @dots{}
4393 Because @samp{$(LIBOBJS)} and @samp{$(ALLOCA)} contain object
4394 file names that end with @samp{.$(OBJEXT)}, they are not suitable for
4395 Libtool libraries (where the expected object extension is @file{.lo}):
4396 @code{LTLIBOBJS} and @code{LTALLOCA} should be used instead.
4398 @code{LTLIBOBJS} is defined automatically by Autoconf and should not
4399 be defined by hand (as in the past), however at the time of writing
4400 @code{LTALLOCA} still needs to be defined from @code{ALLOCA} manually.
4401 @xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs.@: @code{LIBOBJS},
4402 autoconf, The Autoconf Manual}.
4405 @node Program variables
4406 @section Variables used when building a program
4408 Occasionally it is useful to know which @file{Makefile} variables
4409 Automake uses for compilations; for instance, you might need to do your
4410 own compilation in some special cases.
4412 Some variables are inherited from Autoconf; these are @code{CC},
4413 @code{CFLAGS}, @code{CPPFLAGS}, @code{DEFS}, @code{LDFLAGS}, and
4422 There are some additional variables that Automake defines on its own:
4426 The contents of this variable are passed to every compilation that invokes
4427 the C preprocessor; it is a list of arguments to the preprocessor. For
4428 instance, @option{-I} and @option{-D} options should be listed here.
4430 Automake already provides some @option{-I} options automatically. In
4431 particular it generates @samp{-I$(srcdir)}, @samp{-I.}, and a
4432 @option{-I} pointing to the directory holding @file{config.h} (if
4433 you've used @code{AC_CONFIG_HEADERS} or @code{AM_CONFIG_HEADER}). You
4434 can disable the default @option{-I} options using the
4435 @option{nostdinc} option.
4437 @code{AM_CPPFLAGS} is ignored in preference to a per-executable (or
4438 per-library) @code{_CPPFLAGS} variable if it is defined.
4441 This does the same job as @code{AM_CPPFLAGS} (or any per-target
4442 @code{_CPPFLAGS} variable if it is used). It is an older name for the
4443 same functionality. This variable is deprecated; we suggest using
4444 @code{AM_CPPFLAGS} and per-target @code{_CPPFLAGS} instead.
4447 This is the variable the @file{Makefile.am} author can use to pass
4448 in additional C compiler flags. It is more fully documented elsewhere.
4449 In some situations, this is not used, in preference to the
4450 per-executable (or per-library) @code{_CFLAGS}.
4453 This is the command used to actually compile a C source file. The
4454 file name is appended to form the complete command line.
4457 This is the variable the @file{Makefile.am} author can use to pass
4458 in additional linker flags. In some situations, this is not used, in
4459 preference to the per-executable (or per-library) @code{_LDFLAGS}.
4462 This is the command used to actually link a C program. It already
4463 includes @samp{-o $@@} and the usual variable references (for instance,
4464 @code{CFLAGS}); it takes as ``arguments'' the names of the object files
4465 and libraries to link in.
4470 @section Yacc and Lex support
4472 Automake has somewhat idiosyncratic support for Yacc and Lex.
4474 Automake assumes that the @file{.c} file generated by @command{yacc}
4475 (or @command{lex}) should be named using the basename of the input
4476 file. That is, for a yacc source file @file{foo.y}, Automake will
4477 cause the intermediate file to be named @file{foo.c} (as opposed to
4478 @file{y.tab.c}, which is more traditional).
4480 The extension of a yacc source file is used to determine the extension
4481 of the resulting C or C++ file. Files with the extension @file{.y}
4482 will be turned into @file{.c} files; likewise, @file{.yy} will become
4483 @file{.cc}; @file{.y++}, @file{c++}; and @file{.yxx}, @file{.cxx}.
4485 Likewise, lex source files can be used to generate C or C++; the
4486 extensions @file{.l}, @file{.ll}, @file{.l++}, and @file{.lxx} are
4489 You should never explicitly mention the intermediate (C or C++) file
4490 in any @code{SOURCES} variable; only list the source file.
4492 The intermediate files generated by @command{yacc} (or @command{lex})
4493 will be included in any distribution that is made. That way the user
4494 doesn't need to have @command{yacc} or @command{lex}.
4496 If a @command{yacc} source file is seen, then your @file{configure.ac} must
4497 define the variable @code{YACC}. This is most easily done by invoking
4498 the macro @code{AC_PROG_YACC} (@pxref{Particular Programs, , Particular
4499 Program Checks, autoconf, The Autoconf Manual}).
4503 When @code{yacc} is invoked, it is passed @code{YFLAGS} and
4504 @code{AM_YFLAGS}. The former is a user variable and the latter is
4505 intended for the @file{Makefile.am} author.
4507 @code{AM_YFLAGS} is usually used to pass the @option{-d} option to
4508 @command{yacc}. Automake knows what this means and will automatically
4509 adjust its rules to update and distribute the header file built by
4510 @samp{yacc -d}. What Automake cannot guess, though, is where this
4511 header will be used: it is up to you to ensure the header gets built
4512 before it is first used. Typically this is necessary in order for
4513 dependency tracking to work when the header is included by another
4514 file. The common solution is listing the header file in
4515 @code{BUILT_SOURCES} (@pxref{Sources}) as follows.
4518 BUILT_SOURCES = parser.h
4521 foo_SOURCES = @dots{} parser.y @dots{}
4524 If a @command{lex} source file is seen, then your @file{configure.ac}
4525 must define the variable @code{LEX}. You can use @code{AC_PROG_LEX}
4526 to do this (@pxref{Particular Programs, , Particular Program Checks,
4527 autoconf, The Autoconf Manual}), but using @code{AM_PROG_LEX} macro
4528 (@pxref{Macros}) is recommended.
4532 When @command{lex} is invoked, it is passed @code{LFLAGS} and
4533 @code{AM_LFLAGS}. The former is a user variable and the latter is
4534 intended for the @file{Makefile.am} author.
4536 When @code{AM_MAINTAINER_MODE} (@pxref{maintainer-mode}) is used, the
4537 rebuild rule for distributed Yacc and Lex sources are only used when
4538 @code{maintainer-mode} is enabled, or when the files have been erased.
4541 @cindex @command{ylwrap}
4542 @cindex @command{yacc}, multiple parsers
4543 @cindex Multiple @command{yacc} parsers
4544 @cindex Multiple @command{lex} lexers
4545 @cindex @command{lex}, multiple lexers
4548 Automake makes it possible to include multiple @command{yacc} (or
4549 @command{lex}) source files in a single program. When there is more
4550 than one distinct @command{yacc} (or @command{lex}) source file in a
4551 directory, Automake uses a small program called @command{ylwrap} to run
4552 @command{yacc} (or @command{lex}) in a subdirectory. This is
4553 necessary because yacc's output file name is fixed, and a parallel
4554 make could conceivably invoke more than one instance of @command{yacc}
4555 simultaneously. The @command{ylwrap} program is distributed with
4556 Automake. It should appear in the directory specified by
4557 @code{AC_CONFIG_AUX_DIR}, or one of its default locations
4558 (@pxref{Input, , Finding `configure' Input, autoconf, The Autoconf
4561 For @command{yacc}, simply managing locking is insufficient. The output of
4562 @command{yacc} always uses the same symbol names internally, so it isn't
4563 possible to link two @command{yacc} parsers into the same executable.
4565 We recommend using the following renaming hack used in @command{gdb}:
4567 #define yymaxdepth c_maxdepth
4568 #define yyparse c_parse
4570 #define yyerror c_error
4571 #define yylval c_lval
4572 #define yychar c_char
4573 #define yydebug c_debug
4574 #define yypact c_pact
4581 #define yyexca c_exca
4582 #define yyerrflag c_errflag
4583 #define yynerrs c_nerrs
4587 #define yy_yys c_yys
4588 #define yystate c_state
4591 #define yy_yyv c_yyv
4593 #define yylloc c_lloc
4594 #define yyreds c_reds
4595 #define yytoks c_toks
4596 #define yylhs c_yylhs
4597 #define yylen c_yylen
4598 #define yydefred c_yydefred
4599 #define yydgoto c_yydgoto
4600 #define yysindex c_yysindex
4601 #define yyrindex c_yyrindex
4602 #define yygindex c_yygindex
4603 #define yytable c_yytable
4604 #define yycheck c_yycheck
4605 #define yyname c_yyname
4606 #define yyrule c_yyrule
4609 For each define, replace the @samp{c_} prefix with whatever you like.
4610 These defines work for @command{bison}, @command{byacc}, and
4611 traditional @code{yacc}s. If you find a parser generator that uses a
4612 symbol not covered here, please report the new name so it can be added
4617 @section C++ Support
4620 @cindex Support for C++
4622 Automake includes full support for C++.
4624 Any package including C++ code must define the output variable
4625 @code{CXX} in @file{configure.ac}; the simplest way to do this is to use
4626 the @code{AC_PROG_CXX} macro (@pxref{Particular Programs, , Particular
4627 Program Checks, autoconf, The Autoconf Manual}).
4629 A few additional variables are defined when a C++ source file is seen:
4633 The name of the C++ compiler.
4636 Any flags to pass to the C++ compiler.
4639 The maintainer's variant of @code{CXXFLAGS}.
4642 The command used to actually compile a C++ source file. The file name
4643 is appended to form the complete command line.
4646 The command used to actually link a C++ program.
4650 @node Assembly Support
4651 @section Assembly Support
4653 Automake includes some support for assembly code. There are two forms
4654 of assembler files: normal (@file{*.s}) and preprocessed by @code{CPP}
4660 @vindex AM_CCASFLAGS
4662 The variable @code{CCAS} holds the name of the compiler used to build
4663 assembly code. This compiler must work a bit like a C compiler; in
4664 particular it must accept @option{-c} and @option{-o}. The values of
4665 @code{CCASFLAGS} and @code{AM_CCASFLAGS} (or its per-target
4666 definition) is passed to the compilation. For preprocessed files,
4667 @code{CPPFLAGS} and @code{AM_CPPFLAGS} are also used.
4669 The autoconf macro @code{AM_PROG_AS} will define @code{CCAS} and
4670 @code{CCASFLAGS} for you (unless they are already set, it simply sets
4671 @code{CCAS} to the C compiler and @code{CCASFLAGS} to the C compiler
4672 flags), but you are free to define these variables by other means.
4674 Only the suffixes @file{.s} and @file{.S} are recognized by
4675 @command{automake} as being files containing assembly code.
4678 @node Fortran 77 Support
4679 @comment node-name, next, previous, up
4680 @section Fortran 77 Support
4682 @cindex Fortran 77 support
4683 @cindex Support for Fortran 77
4685 Automake includes full support for Fortran 77.
4687 Any package including Fortran 77 code must define the output variable
4688 @code{F77} in @file{configure.ac}; the simplest way to do this is to use
4689 the @code{AC_PROG_F77} macro (@pxref{Particular Programs, , Particular
4690 Program Checks, autoconf, The Autoconf Manual}).
4692 A few additional variables are defined when a Fortran 77 source file is
4698 The name of the Fortran 77 compiler.
4701 Any flags to pass to the Fortran 77 compiler.
4704 The maintainer's variant of @code{FFLAGS}.
4707 Any flags to pass to the Ratfor compiler.
4710 The maintainer's variant of @code{RFLAGS}.
4713 The command used to actually compile a Fortran 77 source file. The file
4714 name is appended to form the complete command line.
4717 The command used to actually link a pure Fortran 77 program or shared
4722 Automake can handle preprocessing Fortran 77 and Ratfor source files in
4723 addition to compiling them@footnote{Much, if not most, of the
4724 information in the following sections pertaining to preprocessing
4725 Fortran 77 programs was taken almost verbatim from @ref{Catalogue of
4726 Rules, , Catalogue of Rules, make, The GNU Make Manual}.}. Automake
4727 also contains some support for creating programs and shared libraries
4728 that are a mixture of Fortran 77 and other languages (@pxref{Mixing
4729 Fortran 77 With C and C++}).
4731 These issues are covered in the following sections.
4734 * Preprocessing Fortran 77:: Preprocessing Fortran 77 sources
4735 * Compiling Fortran 77 Files:: Compiling Fortran 77 sources
4736 * Mixing Fortran 77 With C and C++:: Mixing Fortran 77 With C and C++
4740 @node Preprocessing Fortran 77
4741 @comment node-name, next, previous, up
4742 @subsection Preprocessing Fortran 77
4744 @cindex Preprocessing Fortran 77
4745 @cindex Fortran 77, Preprocessing
4746 @cindex Ratfor programs
4748 @file{N.f} is made automatically from @file{N.F} or @file{N.r}. This
4749 rule runs just the preprocessor to convert a preprocessable Fortran 77
4750 or Ratfor source file into a strict Fortran 77 source file. The precise
4751 command used is as follows:
4756 @code{$(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)@*
4757 $(AM_FFLAGS) $(FFLAGS)}
4760 @code{$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
4765 @node Compiling Fortran 77 Files
4766 @comment node-name, next, previous, up
4767 @subsection Compiling Fortran 77 Files
4769 @file{N.o} is made automatically from @file{N.f}, @file{N.F} or
4770 @file{N.r} by running the Fortran 77 compiler. The precise command used
4776 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS)}
4779 @code{$(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS)@*
4780 $(AM_FFLAGS) $(FFLAGS)}
4783 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
4788 @node Mixing Fortran 77 With C and C++
4789 @comment node-name, next, previous, up
4790 @subsection Mixing Fortran 77 With C and C++
4792 @cindex Fortran 77, mixing with C and C++
4793 @cindex Mixing Fortran 77 with C and C++
4794 @cindex Linking Fortran 77 with C and C++
4796 @cindex Mixing Fortran 77 with C and/or C++
4798 Automake currently provides @emph{limited} support for creating programs
4799 and shared libraries that are a mixture of Fortran 77 and C and/or C++.
4800 However, there are many other issues related to mixing Fortran 77 with
4801 other languages that are @emph{not} (currently) handled by Automake, but
4802 that are handled by other packages@footnote{For example,
4803 @uref{http://www-zeus.desy.de/~burow/cfortran/, the cfortran package}
4804 addresses all of these inter-language issues, and runs under nearly all
4805 Fortran 77, C and C++ compilers on nearly all platforms. However,
4806 @command{cfortran} is not yet Free Software, but it will be in the next
4810 Automake can help in two ways:
4814 Automatic selection of the linker depending on which combinations of
4818 Automatic selection of the appropriate linker flags (e.g., @option{-L} and
4819 @option{-l}) to pass to the automatically selected linker in order to link
4820 in the appropriate Fortran 77 intrinsic and run-time libraries.
4822 @cindex @code{FLIBS}, defined
4824 These extra Fortran 77 linker flags are supplied in the output variable
4825 @code{FLIBS} by the @code{AC_F77_LIBRARY_LDFLAGS} Autoconf macro
4826 supplied with newer versions of Autoconf (Autoconf version 2.13 and
4827 later). @xref{Fortran 77 Compiler Characteristics, , , autoconf, The
4831 If Automake detects that a program or shared library (as mentioned in
4832 some @code{_PROGRAMS} or @code{_LTLIBRARIES} primary) contains source
4833 code that is a mixture of Fortran 77 and C and/or C++, then it requires
4834 that the macro @code{AC_F77_LIBRARY_LDFLAGS} be called in
4835 @file{configure.ac}, and that either @code{$(FLIBS)}
4836 appear in the appropriate @code{_LDADD} (for programs) or @code{_LIBADD}
4837 (for shared libraries) variables. It is the responsibility of the
4838 person writing the @file{Makefile.am} to make sure that @samp{$(FLIBS)}
4839 appears in the appropriate @code{_LDADD} or
4840 @code{_LIBADD} variable.
4842 @cindex Mixed language example
4843 @cindex Example, mixed language
4845 For example, consider the following @file{Makefile.am}:
4849 foo_SOURCES = main.cc foo.f
4850 foo_LDADD = libfoo.la $(FLIBS)
4852 pkglib_LTLIBRARIES = libfoo.la
4853 libfoo_la_SOURCES = bar.f baz.c zardoz.cc
4854 libfoo_la_LIBADD = $(FLIBS)
4857 In this case, Automake will insist that @code{AC_F77_LIBRARY_LDFLAGS}
4858 is mentioned in @file{configure.ac}. Also, if @samp{$(FLIBS)} hadn't
4859 been mentioned in @code{foo_LDADD} and @code{libfoo_la_LIBADD}, then
4860 Automake would have issued a warning.
4865 * How the Linker is Chosen:: Automatic linker selection
4868 @node How the Linker is Chosen
4869 @comment node-name, next, previous, up
4870 @subsubsection How the Linker is Chosen
4872 @cindex Automatic linker selection
4873 @cindex Selecting the linker automatically
4875 When a program or library mixes several languages, Automake choose the
4876 linker according to the following priorities. (The names in
4877 parentheses are the variables containing the link command.)
4882 Native Java (@code{GCJLINK})
4885 C++ (@code{CXXLINK})
4888 Fortran 77 (@code{F77LINK})
4891 Fortran (@code{FCLINK})
4894 Objective C (@code{OBJCLINK})
4900 For example, if Fortran 77, C and C++ source code is compiled
4901 into a program, then the C++ linker will be used. In this case, if the
4902 C or Fortran 77 linkers required any special libraries that weren't
4903 included by the C++ linker, then they must be manually added to an
4904 @code{_LDADD} or @code{_LIBADD} variable by the user writing the
4907 Automake only looks at the file names listed in @file{_SOURCES}
4908 variables to choose the linker, and defaults to the C linker.
4909 Sometimes this is inconvenient because you are linking against a
4910 library written in another language and would like to set the linker
4911 more appropriately. @xref{Libtool Convenience Libraries}, for a
4912 trick with @code{nodist_EXTRA_@dots{}_SOURCES}.
4915 @node Fortran 9x Support
4916 @comment node-name, next, previous, up
4917 @section Fortran 9x Support
4919 @cindex Fortran 9x support
4920 @cindex Support for Fortran 9x
4922 Automake includes full support for Fortran 9x.
4924 Any package including Fortran 9x code must define the output variable
4925 @code{FC} in @file{configure.ac}; the simplest way to do this is to use
4926 the @code{AC_PROG_FC} macro (@pxref{Particular Programs, , Particular
4927 Program Checks, autoconf, The Autoconf Manual}).
4929 A few additional variables are defined when a Fortran 9x source file is
4935 The name of the Fortran 9x compiler.
4938 Any flags to pass to the Fortran 9x compiler.
4941 The maintainer's variant of @code{FCFLAGS}.
4944 The command used to actually compile a Fortran 9x source file. The file
4945 name is appended to form the complete command line.
4948 The command used to actually link a pure Fortran 9x program or shared
4954 * Compiling Fortran 9x Files:: Compiling Fortran 9x sources
4957 @node Compiling Fortran 9x Files
4958 @comment node-name, next, previous, up
4959 @subsection Compiling Fortran 9x Files
4961 @file{N.o} is made automatically from @file{N.f90} or @file{N.f95}
4962 by running the Fortran 9x compiler. The precise command used
4968 @code{$(FC) -c $(AM_FCFLAGS) $(FCFLAGS)}
4973 @comment node-name, next, previous, up
4974 @section Java Support
4976 @cindex Java support
4977 @cindex Support for Java
4979 Automake includes support for compiled Java, using @command{gcj}, the Java
4980 front end to the GNU Compiler Collection.
4982 Any package including Java code to be compiled must define the output
4983 variable @code{GCJ} in @file{configure.ac}; the variable @code{GCJFLAGS}
4984 must also be defined somehow (either in @file{configure.ac} or
4985 @file{Makefile.am}). The simplest way to do this is to use the
4986 @code{AM_PROG_GCJ} macro.
4990 By default, programs including Java source files are linked with
4993 As always, the contents of @code{AM_GCJFLAGS} are passed to every
4994 compilation invoking @command{gcj} (in its role as an ahead-of-time
4995 compiler, when invoking it to create @file{.class} files,
4996 @code{AM_JAVACFLAGS} is used instead). If it is necessary to pass
4997 options to @command{gcj} from @file{Makefile.am}, this variable, and not
4998 the user variable @code{GCJFLAGS}, should be used.
5002 @command{gcj} can be used to compile @file{.java}, @file{.class},
5003 @file{.zip}, or @file{.jar} files.
5005 When linking, @command{gcj} requires that the main class be specified
5006 using the @option{--main=} option. The easiest way to do this is to use
5007 the @code{_LDFLAGS} variable for the program.
5010 @node Support for Other Languages
5011 @comment node-name, next, previous, up
5012 @section Support for Other Languages
5014 Automake currently only includes full support for C, C++ (@pxref{C++
5015 Support}), Fortran 77 (@pxref{Fortran 77 Support}),
5016 Fortran 9x (@pxref{Fortran 9x Support}),
5017 and Java (@pxref{Java Support}). There is only rudimentary support for other
5018 languages, support for which will be improved based on user demand.
5020 Some limited support for adding your own languages is available via the
5021 suffix rule handling (@pxref{Suffixes}).
5025 @section Automatic de-ANSI-fication
5027 @cindex de-ANSI-fication, defined
5029 Although the GNU standards allow the use of ANSI C, this can have the
5030 effect of limiting portability of a package to some older compilers
5031 (notably the SunOS C compiler).
5033 Automake allows you to work around this problem on such machines by
5034 @dfn{de-ANSI-fying} each source file before the actual compilation takes
5037 @vindex AUTOMAKE_OPTIONS
5040 If the @file{Makefile.am} variable @code{AUTOMAKE_OPTIONS}
5041 (@pxref{Options}) contains the option @option{ansi2knr} then code to
5042 handle de-ANSI-fication is inserted into the generated
5045 This causes each C source file in the directory to be treated as ANSI C@.
5046 If an ANSI C compiler is available, it is used. If no ANSI C compiler
5047 is available, the @command{ansi2knr} program is used to convert the source
5048 files into K&R C, which is then compiled.
5050 The @command{ansi2knr} program is simple-minded. It assumes the source
5051 code will be formatted in a particular way; see the @command{ansi2knr} man
5054 @acindex AM_C_PROTOTYPES
5055 Support for de-ANSI-fication requires the source files @file{ansi2knr.c}
5056 and @file{ansi2knr.1} to be in the same package as the ANSI C source;
5057 these files are distributed with Automake. Also, the package
5058 @file{configure.ac} must call the macro @code{AM_C_PROTOTYPES}
5061 Automake also handles finding the @command{ansi2knr} support files in some
5062 other directory in the current package. This is done by prepending the
5063 relative path to the appropriate directory to the @command{ansi2knr}
5064 option. For instance, suppose the package has ANSI C code in the
5065 @file{src} and @file{lib} subdirectories. The files @file{ansi2knr.c} and
5066 @file{ansi2knr.1} appear in @file{lib}. Then this could appear in
5067 @file{src/Makefile.am}:
5070 AUTOMAKE_OPTIONS = ../lib/ansi2knr
5073 If no directory prefix is given, the files are assumed to be in the
5076 Note that automatic de-ANSI-fication will not work when the package is
5077 being built for a different host architecture. That is because automake
5078 currently has no way to build @command{ansi2knr} for the build machine.
5080 @c FIXME: this paragraph might be better moved to an `upgrading' section.
5081 @cindex @code{LTLIBOBJS} and @code{ansi2knr}
5082 @cindex @code{LIBOBJS} and @code{ansi2knr}
5083 @cindex @code{ansi2knr} and @code{LTLIBOBJS}
5084 @cindex @code{ansi2knr} and @code{LIBOBJS}
5085 Using @code{LIBOBJS} with source de-ANSI-fication used to require
5086 hand-crafted code in @file{configure} to append @samp{$U} to basenames
5087 in @code{LIBOBJS}. This is no longer true today. Starting with version
5088 2.54, Autoconf takes care of rewriting @code{LIBOBJS} and
5089 @code{LTLIBOBJS}. (@pxref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ}
5090 vs.@: @code{LIBOBJS}, autoconf, The Autoconf Manual})
5093 @section Automatic dependency tracking
5095 As a developer it is often painful to continually update the
5096 @file{Makefile.in} whenever the include-file dependencies change in a
5097 project. Automake supplies a way to automatically track dependency
5100 @cindex Dependency tracking
5101 @cindex Automatic dependency tracking
5103 Automake always uses complete dependencies for a compilation,
5104 including system headers. Automake's model is that dependency
5105 computation should be a side effect of the build. To this end,
5106 dependencies are computed by running all compilations through a
5107 special wrapper program called @command{depcomp}. @command{depcomp}
5108 understands how to coax many different C and C++ compilers into
5109 generating dependency information in the format it requires.
5110 @samp{automake -a} will install @command{depcomp} into your source
5111 tree for you. If @command{depcomp} can't figure out how to properly
5112 invoke your compiler, dependency tracking will simply be disabled for
5115 @cindex @command{depcomp}
5117 Experience with earlier versions of Automake (@pxref{Dependency
5118 Tracking Evolution}) taught us that it is not reliable to generate
5119 dependencies only on the maintainer's system, as configurations vary
5120 too much. So instead Automake implements dependency tracking at build
5123 Automatic dependency tracking can be suppressed by putting
5124 @option{no-dependencies} in the variable @code{AUTOMAKE_OPTIONS}, or
5125 passing @option{no-dependencies} as an argument to @code{AM_INIT_AUTOMAKE}
5126 (this should be the preferred way). Or, you can invoke @command{automake}
5127 with the @option{-i} option. Dependency tracking is enabled by default.
5129 @vindex AUTOMAKE_OPTIONS
5130 @opindex no-dependencies
5132 The person building your package also can choose to disable dependency
5133 tracking by configuring with @option{--disable-dependency-tracking}.
5135 @cindex Disabling dependency tracking
5136 @cindex Dependency tracking, disabling
5140 @section Support for executable extensions
5142 @cindex Executable extension
5143 @cindex Extension, executable
5146 On some platforms, such as Windows, executables are expected to have an
5147 extension such as @file{.exe}. On these platforms, some compilers (GCC
5148 among them) will automatically generate @file{foo.exe} when asked to
5149 generate @file{foo}.
5151 Automake provides mostly-transparent support for this. Unfortunately
5152 @emph{mostly} doesn't yet mean @emph{fully}. Until the English
5153 dictionary is revised, you will have to assist Automake if your package
5154 must support those platforms.
5156 One thing you must be aware of is that, internally, Automake rewrites
5157 something like this:
5160 bin_PROGRAMS = liver
5166 bin_PROGRAMS = liver$(EXEEXT)
5169 The targets Automake generates are likewise given the @samp{$(EXEEXT)}
5172 However, Automake cannot apply this rewriting to @command{configure}
5173 substitutions. This means that if you are conditionally building a
5174 program using such a substitution, then your @file{configure.ac} must
5175 take care to add @samp{$(EXEEXT)} when constructing the output variable.
5177 With Autoconf 2.13 and earlier, you must explicitly use @code{AC_EXEEXT}
5178 to get this support. With Autoconf 2.50, @code{AC_EXEEXT} is run
5179 automatically if you configure a compiler (say, through
5182 Sometimes maintainers like to write an explicit link rule for their
5183 program. Without executable extension support, this is easy---you
5184 simply write a rule whose target is the name of the program. However,
5185 when executable extension support is enabled, you must instead add the
5186 @samp{$(EXEEXT)} suffix.
5188 Unfortunately, due to the change in Autoconf 2.50, this means you must
5189 always add this extension. However, this is a problem for maintainers
5190 who know their package will never run on a platform that has
5191 executable extensions. For those maintainers, the @option{no-exeext}
5192 option (@pxref{Options}) will disable this feature. This works in a
5193 fairly ugly way; if @option{no-exeext} is seen, then the presence of a
5194 rule for a target named @code{foo} in @file{Makefile.am} will override
5195 an automake-generated rule for @samp{foo$(EXEEXT)}. Without
5196 the @option{no-exeext} option, this use will give a diagnostic.
5200 @chapter Other Derived Objects
5202 Automake can handle derived objects that are not C programs. Sometimes
5203 the support for actually building such objects must be explicitly
5204 supplied, but Automake will still automatically handle installation and
5208 * Scripts:: Executable scripts
5209 * Headers:: Header files
5210 * Data:: Architecture-independent data files
5211 * Sources:: Derived sources
5216 @section Executable Scripts
5218 @cindex @code{_SCRIPTS} primary, defined
5219 @cindex @code{SCRIPTS} primary, defined
5220 @cindex Primary variable, @code{SCRIPTS}
5223 It is possible to define and install programs that are scripts. Such
5224 programs are listed using the @code{SCRIPTS} primary name. Automake
5225 doesn't define any dependencies for scripts; the @file{Makefile.am}
5226 should include the appropriate rules.
5229 Automake does not assume that scripts are derived objects; such objects
5230 must be deleted by hand (@pxref{Clean}).
5232 The @command{automake} program itself is a Perl script that is generated
5233 from @file{automake.in}. Here is how this is handled:
5236 bin_SCRIPTS = automake
5237 CLEANFILES = $(bin_SCRIPTS)
5239 do_subst = sed -e 's,[@@]datadir[@@],$(datadir),g' \
5240 -e 's,[@@]PERL[@@],$(PERL),g' \
5241 -e 's,[@@]PACKAGE[@@],$(PACKAGE),g' \
5242 -e 's,[@@]VERSION[@@],$(VERSION),g' \
5245 automake: automake.in Makefile
5246 $(do_subst) < $(srcdir)/automake.in > automake
5250 Because---as we have just seen---scripts can be built, they are not
5251 distributed by default. Scripts that should be distributed can be
5252 specified using a @code{dist_} prefix as in other primaries. For
5253 instance, the following @file{Makefile.am} declares that
5254 @file{my_script} should be distributed and installed in
5258 dist_sbin_SCRIPTS = my_script
5261 @cindex @code{SCRIPTS}, installation directories
5262 @cindex Installing scripts
5265 @vindex sbin_SCRIPTS
5266 @vindex libexec_SCRIPTS
5267 @vindex pkgdata_SCRIPTS
5268 @vindex noinst_SCRIPTS
5269 @vindex check_SCRIPTS
5271 Script objects can be installed in @code{bindir}, @code{sbindir},
5272 @code{libexecdir}, or @code{pkgdatadir}.
5274 Scripts that need not being installed can be listed in
5275 @code{noinst_SCRIPTS}, and among them, those which are needed only by
5276 @samp{make check} should go in @code{check_SCRIPTS}.
5280 @section Header files
5282 @cindex @code{_HEADERS} primary, defined
5283 @cindex @code{HEADERS} primary, defined
5284 @cindex Primary variable, @code{HEADERS}
5286 @vindex noinst_HEADERS
5287 @cindex @code{HEADERS}, installation directories
5288 @cindex Installing headers
5289 @vindex include_HEADERS
5290 @vindex oldinclude_HEADERS
5291 @vindex pkginclude_HEADERS
5294 Header files that must be installed are specified by the
5295 @code{HEADERS} family of variables. Headers can be installed in
5296 @code{includedir}, @code{oldincludedir}, @code{pkgincludedir} or any
5297 other directory you may have defined (@pxref{Uniform}). For instance,
5300 include_HEADERS = foo.h bar/bar.h
5304 will install the two files as @file{$(includedir)/foo.h} and
5305 @file{$(includedir)/bar.h}.
5307 The @code{nobase_} prefix is also supported,
5310 nobase_include_HEADERS = foo.h bar/bar.h
5314 will install the two files as @file{$(includedir)/foo.h} and
5315 @file{$(includedir)/bar/bar.h} (@pxref{Alternative}).
5317 @vindex noinst_HEADERS
5318 Usually, only header files that accompany installed libraries need to
5319 be installed. Headers used by programs or convenience libraries are
5320 not installed. The @code{noinst_HEADERS} variable can be used for
5321 such headers. However when the header actually belongs to one
5322 convenient library or program, we recommend listing it in the
5323 program's or library's @code{_SOURCES} variable (@pxref{Program
5324 Sources}) instead of in @code{noinst_HEADERS}. This is clearer for
5325 the @file{Makefile.am} reader. @code{noinst_HEADERS} would be the
5326 right variable to use in a directory containing only headers and no
5327 associated library or program.
5329 All header files must be listed somewhere; in a @code{_SOURCES}
5330 variable or in a @code{_HEADERS} variable. Missing ones will not
5331 appear in the distribution.
5333 For header files that are built and must not be distributed, use the
5334 @code{nodist_} prefix as in @code{nodist_include_HEADERS} or
5335 @code{nodist_prog_SOURCES}. If these generated headers are needed
5336 during the build, you must also ensure they exist before they are
5337 used (@pxref{Sources}).
5341 @section Architecture-independent data files
5343 @cindex @code{_DATA} primary, defined
5344 @cindex @code{DATA} primary, defined
5345 @cindex Primary variable, @code{DATA}
5348 Automake supports the installation of miscellaneous data files using the
5349 @code{DATA} family of variables.
5353 @vindex sysconf_DATA
5354 @vindex sharedstate_DATA
5355 @vindex localstate_DATA
5356 @vindex pkgdata_DATA
5358 Such data can be installed in the directories @code{datadir},
5359 @code{sysconfdir}, @code{sharedstatedir}, @code{localstatedir}, or
5362 By default, data files are @emph{not} included in a distribution. Of
5363 course, you can use the @code{dist_} prefix to change this on a
5366 Here is how Automake declares its auxiliary data files:
5369 dist_pkgdata_DATA = clean-kr.am clean.am @dots{}
5374 @section Built sources
5376 Because Automake's automatic dependency tracking works as a side-effect
5377 of compilation (@pxref{Dependencies}) there is a bootstrap issue: a
5378 target should not be compiled before its dependencies are made, but
5379 these dependencies are unknown until the target is first compiled.
5381 Ordinarily this is not a problem, because dependencies are distributed
5382 sources: they preexist and do not need to be built. Suppose that
5383 @file{foo.c} includes @file{foo.h}. When it first compiles
5384 @file{foo.o}, @command{make} only knows that @file{foo.o} depends on
5385 @file{foo.c}. As a side-effect of this compilation @command{depcomp}
5386 records the @file{foo.h} dependency so that following invocations of
5387 @command{make} will honor it. In these conditions, it's clear there is
5388 no problem: either @file{foo.o} doesn't exist and has to be built
5389 (regardless of the dependencies), or accurate dependencies exist and
5390 they can be used to decide whether @file{foo.o} should be rebuilt.
5392 It's a different story if @file{foo.h} doesn't exist by the first
5393 @command{make} run. For instance, there might be a rule to build
5394 @file{foo.h}. This time @file{file.o}'s build will fail because the
5395 compiler can't find @file{foo.h}. @command{make} failed to trigger the
5396 rule to build @file{foo.h} first by lack of dependency information.
5398 @vindex BUILT_SOURCES
5399 @cindex @code{BUILT_SOURCES}, defined
5401 The @code{BUILT_SOURCES} variable is a workaround for this problem. A
5402 source file listed in @code{BUILT_SOURCES} is made on @samp{make all}
5403 or @samp{make check} (or even @samp{make install}) before other
5404 targets are processed. However, such a source file is not
5405 @emph{compiled} unless explicitly requested by mentioning it in some
5406 other @code{_SOURCES} variable.
5408 So, to conclude our introductory example, we could use
5409 @samp{BUILT_SOURCES = foo.h} to ensure @file{foo.h} gets built before
5410 any other target (including @file{foo.o}) during @samp{make all} or
5413 @code{BUILT_SOURCES} is actually a bit of a misnomer, as any file which
5414 must be created early in the build process can be listed in this
5415 variable. Moreover, all built sources do not necessarily have to be
5416 listed in @code{BUILT_SOURCES}. For instance, a generated @file{.c} file
5417 doesn't need to appear in @code{BUILT_SOURCES} (unless it is included by
5418 another source), because it's a known dependency of the associated
5421 It might be important to emphasize that @code{BUILT_SOURCES} is
5422 honored only by @samp{make all}, @samp{make check} and @samp{make
5423 install}. This means you cannot build a specific target (e.g.,
5424 @samp{make foo}) in a clean tree if it depends on a built source.
5425 However it will succeed if you have run @samp{make all} earlier,
5426 because accurate dependencies are already available.
5428 The next section illustrates and discusses the handling of built sources
5432 * Built sources example:: Several ways to handle built sources.
5435 @node Built sources example
5436 @subsection Built sources example
5438 Suppose that @file{foo.c} includes @file{bindir.h}, which is
5439 installation-dependent and not distributed: it needs to be built. Here
5440 @file{bindir.h} defines the preprocessor macro @code{bindir} to the
5441 value of the @command{make} variable @code{bindir} (inherited from
5444 We suggest several implementations below. It's not meant to be an
5445 exhaustive listing of all ways to handle built sources, but it will give
5446 you a few ideas if you encounter this issue.
5448 @unnumberedsubsec First try
5450 This first implementation will illustrate the bootstrap issue mentioned
5451 in the previous section (@pxref{Sources}).
5453 Here is a tentative @file{Makefile.am}.
5459 nodist_foo_SOURCES = bindir.h
5460 CLEANFILES = bindir.h
5462 echo '#define bindir "$(bindir)"' >$@@
5465 This setup doesn't work, because Automake doesn't know that @file{foo.c}
5466 includes @file{bindir.h}. Remember, automatic dependency tracking works
5467 as a side-effect of compilation, so the dependencies of @file{foo.o} will
5468 be known only after @file{foo.o} has been compiled (@pxref{Dependencies}).
5469 The symptom is as follows.
5473 source='foo.c' object='foo.o' libtool=no \
5474 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
5475 depmode=gcc /bin/sh ./depcomp \
5476 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
5477 foo.c:2: bindir.h: No such file or directory
5478 make: *** [foo.o] Error 1
5481 In this example @file{bindir.h} is not distributed, not installed, and
5482 it is not even being built on-time. One may wonder what the
5483 @samp{nodist_foo_SOURCES = bindir.h} line has any use at all. This
5484 line simply states that @file{bindir.h} is a source of @code{foo}, so
5485 for instance, it should be inspected while generating tags
5486 (@pxref{Tags}). In other words, it does not help our present problem,
5487 and the build would fail identically without it.
5489 @unnumberedsubsec Using @code{BUILT_SOURCES}
5491 A solution is to require @file{bindir.h} to be built before anything
5492 else. This is what @code{BUILT_SOURCES} is meant for (@pxref{Sources}).
5497 nodist_foo_SOURCES = bindir.h
5498 BUILT_SOURCES = bindir.h
5499 CLEANFILES = bindir.h
5501 echo '#define bindir "$(bindir)"' >$@@
5504 See how @file{bindir.h} get built first:
5508 echo '#define bindir "/usr/local/bin"' >bindir.h
5510 make[1]: Entering directory `/home/adl/tmp'
5511 source='foo.c' object='foo.o' libtool=no \
5512 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
5513 depmode=gcc /bin/sh ./depcomp \
5514 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
5515 gcc -g -O2 -o foo foo.o
5516 make[1]: Leaving directory `/home/adl/tmp'
5519 However, as said earlier, @code{BUILT_SOURCES} applies only to the
5520 @code{all}, @code{check}, and @code{install} targets. It still fails
5521 if you try to run @samp{make foo} explicitly:
5525 test -z "bindir.h" || rm -f bindir.h
5526 test -z "foo" || rm -f foo
5528 % : > .deps/foo.Po # Suppress previously recorded dependencies
5530 source='foo.c' object='foo.o' libtool=no \
5531 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
5532 depmode=gcc /bin/sh ./depcomp \
5533 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
5534 foo.c:2: bindir.h: No such file or directory
5535 make: *** [foo.o] Error 1
5538 @unnumberedsubsec Recording dependencies manually
5540 Usually people are happy enough with @code{BUILT_SOURCES} because they
5541 never build targets such as @samp{make foo} before @samp{make all}, as
5542 in the previous example. However if this matters to you, you can
5543 avoid @code{BUILT_SOURCES} and record such dependencies explicitly in
5544 the @file{Makefile.am}.
5549 nodist_foo_SOURCES = bindir.h
5550 foo.$(OBJEXT): bindir.h
5551 CLEANFILES = bindir.h
5553 echo '#define bindir "$(bindir)"' >$@@
5556 You don't have to list @emph{all} the dependencies of @file{foo.o}
5557 explicitly, only those that might need to be built. If a dependency
5558 already exists, it will not hinder the first compilation and will be
5559 recorded by the normal dependency tracking code. (Note that after
5560 this first compilation the dependency tracking code will also have
5561 recorded the dependency between @file{foo.o} and
5562 @file{bindir.h}; so our explicit dependency is really useful to
5563 the first build only.)
5565 Adding explicit dependencies like this can be a bit dangerous if you are
5566 not careful enough. This is due to the way Automake tries not to
5567 overwrite your rules (it assumes you know better than it).
5568 @samp{foo.$(OBJEXT): bindir.h} supersedes any rule Automake may want to
5569 output to build @samp{foo.$(OBJEXT)}. It happens to work in this case
5570 because Automake doesn't have to output any @samp{foo.$(OBJEXT):}
5571 target: it relies on a suffix rule instead (i.e., @samp{.c.$(OBJEXT):}).
5572 Always check the generated @file{Makefile.in} if you do this.
5574 @unnumberedsubsec Build @file{bindir.h} from @file{configure}
5576 It's possible to define this preprocessor macro from @file{configure},
5577 either in @file{config.h} (@pxref{Defining Directories, , Defining
5578 Directories, autoconf, The Autoconf Manual}), or by processing a
5579 @file{bindir.h.in} file using @code{AC_CONFIG_FILES}
5580 (@pxref{Configuration Actions, ,Configuration Actions, autoconf, The
5583 At this point it should be clear that building @file{bindir.h} from
5584 @file{configure} work well for this example. @file{bindir.h} will exist
5585 before you build any target, hence will not cause any dependency issue.
5587 The Makefile can be shrunk as follows. We do not even have to mention
5595 However, it's not always possible to build sources from
5596 @file{configure}, especially when these sources are generated by a tool
5597 that needs to be built first...
5599 @unnumberedsubsec Build @file{bindir.c}, not @file{bindir.h}.
5601 Another attractive idea is to define @code{bindir} as a variable or
5602 function exported from @file{bindir.o}, and build @file{bindir.c}
5603 instead of @file{bindir.h}.
5606 noinst_PROGRAMS = foo
5607 foo_SOURCES = foo.c bindir.h
5608 nodist_foo_SOURCES = bindir.c
5609 CLEANFILES = bindir.c
5611 echo 'const char bindir[] = "$(bindir)";' >$@@
5614 @file{bindir.h} contains just the variable's declaration and doesn't
5615 need to be built, so it won't cause any trouble. @file{bindir.o} is
5616 always dependent on @file{bindir.c}, so @file{bindir.c} will get built
5619 @unnumberedsubsec Which is best?
5621 There is no panacea, of course. Each solution has its merits and
5624 You cannot use @code{BUILT_SOURCES} if the ability to run @samp{make
5625 foo} on a clean tree is important to you.
5627 You won't add explicit dependencies if you are leery of overriding
5628 an Automake rule by mistake.
5630 Building files from @file{./configure} is not always possible, neither
5631 is converting @file{.h} files into @file{.c} files.
5634 @node Other GNU Tools
5635 @chapter Other GNU Tools
5637 Since Automake is primarily intended to generate @file{Makefile.in}s for
5638 use in GNU programs, it tries hard to interoperate with other GNU tools.
5641 * Emacs Lisp:: Emacs Lisp
5652 @cindex @code{_LISP} primary, defined
5653 @cindex @code{LISP} primary, defined
5654 @cindex Primary variable, @code{LISP}
5660 Automake provides some support for Emacs Lisp. The @code{LISP} primary
5661 is used to hold a list of @file{.el} files. Possible prefixes for this
5662 primary are @code{lisp_} and @code{noinst_}. Note that if
5663 @code{lisp_LISP} is defined, then @file{configure.ac} must run
5664 @code{AM_PATH_LISPDIR} (@pxref{Macros}).
5666 @vindex dist_lisp_LISP
5667 @vindex dist_noinst_LISP
5668 Lisp sources are not distributed by default. You can prefix the
5669 @code{LISP} primary with @code{dist_}, as in @code{dist_lisp_LISP} or
5670 @code{dist_noinst_LISP}, to indicate that these files should be
5673 Automake will byte-compile all Emacs Lisp source files using the Emacs
5674 found by @code{AM_PATH_LISPDIR}, if any was found.
5676 Byte-compiled Emacs Lisp files are not portable among all versions of
5677 Emacs, so it makes sense to turn this off if you expect sites to have
5678 more than one version of Emacs installed. Furthermore, many packages
5679 don't actually benefit from byte-compilation. Still, we recommend
5680 that you byte-compile your Emacs Lisp sources. It is probably better
5681 for sites with strange setups to cope for themselves than to make the
5682 installation less nice for everybody else.
5684 There are two ways to avoid byte-compiling. Historically, we have
5685 recommended the following construct.
5687 lisp_LISP = file1.el file2.el
5691 @code{ELCFILES} is an internal Automake variable that normally lists
5692 all @file{.elc} files that must be byte-compiled. Automake defines
5693 @code{ELCFILES} automatically from @code{lisp_LISP}. Emptying this
5694 variable explicitly prevents byte-compilation to occur.
5696 Since Automake 1.8, we now recommend using @code{lisp_DATA} instead. As
5699 lisp_DATA = file1.el file2.el
5702 Note that these two constructs are not equivalent. @code{_LISP} will
5703 not install a file if Emacs is not installed, while @code{_DATA} will
5704 always install its files.
5709 @cindex GNU Gettext support
5710 @cindex Gettext support
5711 @cindex Support for GNU Gettext
5713 If @code{AM_GNU_GETTEXT} is seen in @file{configure.ac}, then Automake
5714 turns on support for GNU gettext, a message catalog system for
5715 internationalization
5716 (@pxref{GNU Gettext, , , gettext, GNU gettext utilities}).
5718 The @code{gettext} support in Automake requires the addition of two
5719 subdirectories to the package, @file{intl} and @file{po}. Automake
5720 insures that these directories exist and are mentioned in
5726 Automake provides support for GNU Libtool (@pxref{Top, , Introduction,
5727 libtool, The Libtool Manual}) with the @code{LTLIBRARIES} primary.
5728 @xref{A Shared Library}.
5734 @cindex @code{_JAVA} primary, defined
5735 @cindex @code{JAVA} primary, defined
5736 @cindex Primary variable, @code{JAVA}
5738 Automake provides some minimal support for Java compilation with the
5739 @code{JAVA} primary.
5741 Any @file{.java} files listed in a @code{_JAVA} variable will be
5742 compiled with @code{JAVAC} at build time. By default, @file{.java}
5743 files are not included in the distribution, you should use the
5744 @code{dist_} prefix to distribute them.
5746 Here is a typical setup for distributing @file{.java} files and
5747 installing the @file{.class} files resulting from their compilation.
5750 javadir = $(datadir)/java
5751 dist_java_JAVA = a.java b.java @dots{}
5754 @cindex @code{JAVA} restrictions
5755 @cindex Restrictions for @code{JAVA}
5757 Currently Automake enforces the restriction that only one @code{_JAVA}
5758 primary can be used in a given @file{Makefile.am}. The reason for this
5759 restriction is that, in general, it isn't possible to know which
5760 @file{.class} files were generated from which @file{.java} files, so
5761 it would be impossible to know which files to install where. For
5762 instance, a @file{.java} file can define multiple classes; the resulting
5763 @file{.class} file names cannot be predicted without parsing the
5766 There are a few variables that are used when compiling Java sources:
5770 The name of the Java compiler. This defaults to @samp{javac}.
5773 The flags to pass to the compiler. This is considered to be a user
5774 variable (@pxref{User Variables}).
5777 More flags to pass to the Java compiler. This, and not
5778 @code{JAVACFLAGS}, should be used when it is necessary to put Java
5779 compiler flags into @file{Makefile.am}.
5782 The value of this variable is passed to the @option{-d} option to
5783 @code{javac}. It defaults to @samp{$(top_builddir)}.
5786 This variable is an @code{sh} expression that is used to set the
5787 @env{CLASSPATH} environment variable on the @code{javac} command line.
5788 (In the future we will probably handle class path setting differently.)
5795 @cindex @code{_PYTHON} primary, defined
5796 @cindex @code{PYTHON} primary, defined
5797 @cindex Primary variable, @code{PYTHON}
5800 Automake provides support for Python compilation with the @code{PYTHON}
5803 Any files listed in a @code{_PYTHON} variable will be byte-compiled
5804 with @command{py-compile} at install time. @command{py-compile}
5805 actually creates both standard (@file{.pyc}) and byte-compiled
5806 (@file{.pyo}) versions of the source files. Note that because
5807 byte-compilation occurs at install time, any files listed in
5808 @code{noinst_PYTHON} will not be compiled. Python source files are
5809 included in the distribution by default.
5811 Automake ships with an Autoconf macro called @code{AM_PATH_PYTHON} that
5812 will determine some Python-related directory variables (see below). If
5813 you have called @code{AM_PATH_PYTHON} from @file{configure.ac}, then you
5814 may use the following variables to list you Python source files in your
5815 variables: @code{python_PYTHON}, @code{pkgpython_PYTHON},
5816 @code{pyexecdir_PYTHON}, @code{pkgpyexecdir_PYTHON}, depending where you
5817 want your files installed.
5819 @defmac AM_PATH_PYTHON ([@var{VERSION}], [@var{ACTION-IF-FOUND}], [@var{ACTION-IF-NOT-FOUND}])
5821 Search a Python interpreter on the system. This macro takes three
5822 optional arguments. The first argument, if present, is the minimum
5823 version of Python required for this package: @code{AM_PATH_PYTHON}
5824 will skip any Python interpreter that is older than @var{VERSION}.
5825 If an interpreter is found and satisfies @var{VERSION}, then
5826 @var{ACTION-IF-FOUND} is run. Otherwise, @var{ACTION-IF-NOT-FOUND} is
5829 If @var{ACTION-IF-NOT-FOUND} is not specified, the default is to abort
5830 configure. This is fine when Python is an absolute requirement for the
5831 package. Therefore if Python >= 2.2 is only @emph{optional} to the
5832 package, @code{AM_PATH_PYTHON} could be called as follows.
5835 AM_PATH_PYTHON(2.2,, :)
5838 @code{AM_PATH_PYTHON} creates the following output variables based on
5839 the Python installation found during configuration.
5844 The name of the Python executable, or @samp{:} if no suitable
5845 interpreter could be found.
5847 Assuming @var{ACTION-IF-NOT-FOUND} is used (otherwise @file{./configure}
5848 will abort if Python is absent), the value of @code{PYTHON} can be used
5849 to setup a conditional in order to disable the relevant part of a build
5853 AM_PATH_PYTHON(,, :)
5854 AM_CONDITIONAL([HAVE_PYTHON], [test "$PYTHON" != :])
5857 @item PYTHON_VERSION
5858 The Python version number, in the form @var{major}.@var{minor}
5859 (e.g., @samp{1.5}). This is currently the value of
5860 @samp{sys.version[:3]}.
5863 The string @samp{$@{prefix@}}. This term may be used in future work
5864 that needs the contents of Python's @samp{sys.prefix}, but general
5865 consensus is to always use the value from configure.
5867 @item PYTHON_EXEC_PREFIX
5868 The string @samp{$@{exec_prefix@}}. This term may be used in future work
5869 that needs the contents of Python's @samp{sys.exec_prefix}, but general
5870 consensus is to always use the value from configure.
5872 @item PYTHON_PLATFORM
5873 The canonical name used by Python to describe the operating system, as
5874 given by @samp{sys.platform}. This value is sometimes needed when
5875 building Python extensions.
5878 The directory name for the @file{site-packages} subdirectory of the
5879 standard Python install tree.
5882 This is the directory under @code{pythondir} that is named after the
5883 package. That is, it is @samp{$(pythondir)/$(PACKAGE)}. It is provided
5887 This is the directory where Python extension modules (shared libraries)
5888 should be installed.
5891 This is a convenience variable that is defined as
5892 @samp{$(pyexecdir)/$(PACKAGE)}.
5895 All these directory variables have values that start with either
5896 @samp{$@{prefix@}} or @samp{$@{exec_prefix@}} unexpanded. This works
5897 fine in @file{Makefiles}, but it makes these variables hard to use in
5898 @file{configure}. This is mandated by the GNU coding standards, so
5899 that the user can run @samp{make prefix=/foo install}. The Autoconf
5900 manual has a section with more details on this topic
5901 (@pxref{Installation Directory Variables, , Installation Directory
5902 Variables, autoconf, The Autoconf Manual}). See also @ref{Hard-Coded
5907 @chapter Building documentation
5909 Currently Automake provides support for Texinfo and man pages.
5913 * Man pages:: Man pages
5920 @cindex @code{_TEXINFOS} primary, defined
5921 @cindex @code{TEXINFOS} primary, defined
5922 @cindex Primary variable, @code{TEXINFOS}
5923 @cindex HTML output using Texinfo
5924 @cindex PDF output using Texinfo
5925 @cindex PS output using Texinfo
5926 @cindex DVI output using Texinfo
5928 @vindex info_TEXINFOS
5930 If the current directory contains Texinfo source, you must declare it
5931 with the @code{TEXINFOS} primary. Generally Texinfo files are converted
5932 into info, and thus the @code{info_TEXINFOS} variable is most commonly used
5933 here. Any Texinfo source file must end in the @file{.texi},
5934 @file{.txi}, or @file{.texinfo} extension. We recommend @file{.texi}
5937 Automake generates rules to build @file{.info}, @file{.dvi},
5938 @file{.ps}, @file{.pdf} and @file{.html} files from your Texinfo
5939 sources. Following the GNU Coding Standards, only the @file{.info}
5940 files are built by @samp{make all} and installed by @samp{make
5941 install} (unless you use @option{no-installinfo}, see below).
5942 Furthermore, @file{.info} files are automatically distributed so that
5943 Texinfo is not a prerequisite for installing your package.
5949 @trindex install-dvi
5950 @trindex install-html
5951 @trindex install-pdf
5953 Other documentation formats can be built on request by @samp{make
5954 dvi}, @samp{make ps}, @samp{make pdf} and @samp{make html}, and they
5955 can be installed with @samp{make install-dvi}, @samp{make install-ps},
5956 @samp{make install-pdf} and @samp{make install-html} explicitly.
5957 @samp{make uninstall} will remove everything: the Texinfo
5958 documentation installed by default as well as all the above optional
5961 All these targets can be extended using @samp{-local} rules
5962 (@pxref{Extending}).
5964 @cindex Texinfo flag, @code{VERSION}
5965 @cindex Texinfo flag, @code{UPDATED}
5966 @cindex Texinfo flag, @code{EDITION}
5967 @cindex Texinfo flag, @code{UPDATED-MONTH}
5969 @cindex @code{VERSION} Texinfo flag
5970 @cindex @code{UPDATED} Texinfo flag
5971 @cindex @code{EDITION} Texinfo flag
5972 @cindex @code{UPDATED-MONTH} Texinfo flag
5974 @cindex @file{mdate-sh}
5976 If the @file{.texi} file @code{@@include}s @file{version.texi}, then
5977 that file will be automatically generated. The file @file{version.texi}
5978 defines four Texinfo flag you can reference using
5979 @code{@@value@{EDITION@}}, @code{@@value@{VERSION@}},
5980 @code{@@value@{UPDATED@}}, and @code{@@value@{UPDATED-MONTH@}}.
5985 Both of these flags hold the version number of your program. They are
5986 kept separate for clarity.
5989 This holds the date the primary @file{.texi} file was last modified.
5992 This holds the name of the month in which the primary @file{.texi} file
5996 The @file{version.texi} support requires the @command{mdate-sh}
5997 script; this script is supplied with Automake and automatically
5998 included when @command{automake} is invoked with the
5999 @option{--add-missing} option.
6001 If you have multiple Texinfo files, and you want to use the
6002 @file{version.texi} feature, then you have to have a separate version
6003 file for each Texinfo file. Automake will treat any include in a
6004 Texinfo file that matches @file{vers*.texi} just as an automatically
6005 generated version file.
6007 Sometimes an info file actually depends on more than one @file{.texi}
6008 file. For instance, in GNU Hello, @file{hello.texi} includes the file
6009 @file{gpl.texi}. You can tell Automake about these dependencies using
6010 the @code{@var{texi}_TEXINFOS} variable. Here is how GNU Hello does it:
6015 info_TEXINFOS = hello.texi
6016 hello_TEXINFOS = gpl.texi
6019 @cindex @file{texinfo.tex}
6021 By default, Automake requires the file @file{texinfo.tex} to appear in
6022 the same directory as the Texinfo source (this can be changed using the
6023 @code{TEXINFO_TEX} variable, see below). However, if you used
6024 @code{AC_CONFIG_AUX_DIR} in @file{configure.ac} (@pxref{Input, , Finding
6025 `configure' Input, autoconf, The Autoconf Manual}), then
6026 @file{texinfo.tex} is looked for there. Automake supplies
6027 @file{texinfo.tex} if @option{--add-missing} is given.
6029 @opindex no-texinfo.tex
6031 The option @option{no-texinfo.tex} can be used to eliminate the
6032 requirement for the file @file{texinfo.tex}. Use of the variable
6033 @code{TEXINFO_TEX} is preferable, however, because that allows the
6034 @code{dvi}, @code{ps}, and @code{pdf} targets to still work.
6036 @cindex Option, @code{noinstall-info}
6037 @cindex Target, @code{install-info}
6038 @cindex @code{install-info} target
6039 @cindex @code{noinstall-info} option
6041 @opindex no-installinfo
6042 @trindex install-info
6044 Automake generates an @code{install-info} rule; some people apparently
6045 use this. By default, info pages are installed by @samp{make
6046 install}, so running @code{make install-info} is pointless. This can
6047 be prevented via the @code{no-installinfo} option. In this case,
6048 @file{.info} files are not installed by default, and user must
6049 request this explicitly using @samp{make install-info}
6051 The following variables are used by the Texinfo build rules.
6055 The name of the program invoked to build @file{.info} files. This
6056 variable is defined by Automake. If the @command{makeinfo} program is
6057 found on the system then it will be used by default; otherwise
6058 @command{missing} will be used instead.
6061 The command invoked to build @file{.html} files. Automake
6062 defines this to @samp{$(MAKEINFO) --html}.
6065 User flags passed to each invocation of @samp{$(MAKEINFO)} and
6066 @samp{$(MAKEINFOHTML)}. This user variable (@pxref{User Variables}) is
6067 not expected to be defined in any @file{Makefile}; it can be used by
6068 users to pass extra flags to suit their needs.
6070 @item AM_MAKEINFOFLAGS
6071 @itemx AM_MAKEINFOHTMLFLAGS
6072 Maintainer flags passed to each @command{makeinfo} invocation. Unlike
6073 @code{MAKEINFOFLAGS}, these variables are meant to be defined by
6074 maintainers in @file{Makefile.am}. @samp{$(AM_MAKEINFOFLAGS)} is
6075 passed to @code{makeinfo} when building @file{.info} files; and
6076 @samp{$(AM_MAKEINFOHTMLFLAGS)} is used when building @file{.html}
6079 For instance, the following setting can be used to obtain one single
6080 @file{.html} file per manual, without node separators.
6082 AM_MAKEINFOHTMLFLAGS = --no-headers --no-split
6085 @code{AM_MAKEINFOHTMLFLAGS} defaults to @samp{$(AM_MAKEINFOFLAGS)}.
6086 This means that defining @code{AM_MAKEINFOFLAGS} without defining
6087 @code{AM_MAKEINFOHTMLFLAGS} will impact builds of both @file{.info}
6088 and @file{.html} files.
6091 The name of the command that converts a @file{.texi} file into a
6092 @file{.dvi} file. This defaults to @samp{texi2dvi}, a script that ships
6093 with the Texinfo package.
6096 The name of the command that translates a @file{.texi} file into a
6097 @file{.pdf} file. This defaults to @samp{$(TEXI2DVI) --pdf --batch}.
6100 The name of the command that build a @file{.ps} file out of a
6101 @file{.dvi} file. This defaults to @samp{dvips}.
6105 If your package has Texinfo files in many directories, you can use the
6106 variable @code{TEXINFO_TEX} to tell Automake where to find the canonical
6107 @file{texinfo.tex} for your package. The value of this variable should
6108 be the relative path from the current @file{Makefile.am} to
6112 TEXINFO_TEX = ../doc/texinfo.tex
6120 @cindex @code{_MANS} primary, defined
6121 @cindex @code{MANS} primary, defined
6122 @cindex Primary variable, @code{MANS}
6126 A package can also include man pages (but see the GNU standards on this
6127 matter, @ref{Man Pages, , , standards, The GNU Coding Standards}.) Man
6128 pages are declared using the @code{MANS} primary. Generally the
6129 @code{man_MANS} variable is used. Man pages are automatically installed in
6130 the correct subdirectory of @code{mandir}, based on the file extension.
6132 File extensions such as @file{.1c} are handled by looking for the valid
6133 part of the extension and using that to determine the correct
6134 subdirectory of @code{mandir}. Valid section names are the digits
6135 @samp{0} through @samp{9}, and the letters @samp{l} and @samp{n}.
6137 Sometimes developers prefer to name a man page something like
6138 @file{foo.man} in the source, and then rename it to have the correct
6139 suffix, for example @file{foo.1}, when installing the file. Automake
6140 also supports this mode. For a valid section named @var{SECTION},
6141 there is a corresponding directory named @samp{man@var{SECTION}dir},
6142 and a corresponding @code{_MANS} variable. Files listed in such a
6143 variable are installed in the indicated section. If the file already
6144 has a valid suffix, then it is installed as-is; otherwise the file
6145 suffix is changed to match the section.
6147 For instance, consider this example:
6149 man1_MANS = rename.man thesame.1 alsothesame.1c
6152 In this case, @file{rename.man} will be renamed to @file{rename.1} when
6153 installed, but the other files will keep their names.
6155 @cindex Target, @code{install-man}
6156 @cindex Option, @option{noinstall-man}
6157 @cindex @code{install-man} target
6158 @cindex @option{noinstall-man} option
6159 @opindex no-installman
6160 @trindex install-man
6162 By default, man pages are installed by @samp{make install}. However,
6163 since the GNU project does not require man pages, many maintainers do
6164 not expend effort to keep the man pages up to date. In these cases, the
6165 @option{no-installman} option will prevent the man pages from being
6166 installed by default. The user can still explicitly install them via
6167 @samp{make install-man}.
6169 Here is how the man pages are handled in GNU @command{cpio} (which
6170 includes both Texinfo documentation and man pages):
6173 man_MANS = cpio.1 mt.1
6174 EXTRA_DIST = $(man_MANS)
6177 Man pages are not currently considered to be source, because it is not
6178 uncommon for man pages to be automatically generated. Therefore they
6179 are not automatically included in the distribution. However, this can
6180 be changed by use of the @code{dist_} prefix.
6182 The @code{nobase_} prefix is meaningless for man pages and is
6187 @chapter What Gets Installed
6189 @cindex Installation support
6190 @cindex @samp{make install} support
6192 @section Basics of installation
6194 Naturally, Automake handles the details of actually installing your
6195 program once it has been built. All files named by the various
6196 primaries are automatically installed in the appropriate places when the
6197 user runs @samp{make install}.
6199 A file named in a primary is installed by copying the built file into
6200 the appropriate directory. The base name of the file is used when
6204 bin_PROGRAMS = hello subdir/goodbye
6207 In this example, both @samp{hello} and @samp{goodbye} will be installed
6208 in @samp{$(bindir)}.
6210 Sometimes it is useful to avoid the basename step at install time. For
6211 instance, you might have a number of header files in subdirectories of
6212 the source tree that are laid out precisely how you want to install
6213 them. In this situation you can use the @code{nobase_} prefix to
6214 suppress the base name step. For example:
6217 nobase_include_HEADERS = stdio.h sys/types.h
6220 Will install @file{stdio.h} in @samp{$(includedir)} and @file{types.h}
6221 in @samp{$(includedir)/sys}.
6223 @section The two parts of install
6225 Automake generates separate @code{install-data} and @code{install-exec}
6226 rules, in case the installer is installing on multiple machines that
6227 share directory structure---these targets allow the machine-independent
6228 parts to be installed only once. @code{install-exec} installs
6229 platform-dependent files, and @code{install-data} installs
6230 platform-independent files. The @code{install} target depends on both
6231 of these targets. While Automake tries to automatically segregate
6232 objects into the correct category, the @file{Makefile.am} author is, in
6233 the end, responsible for making sure this is done correctly.
6234 @trindex install-data
6235 @trindex install-exec
6237 @cindex Install, two parts of
6239 Variables using the standard directory prefixes @samp{data},
6240 @samp{info}, @samp{man}, @samp{include}, @samp{oldinclude},
6241 @samp{pkgdata}, or @samp{pkginclude} are installed by
6242 @code{install-data}.
6244 Variables using the standard directory prefixes @samp{bin},
6245 @samp{sbin}, @samp{libexec}, @samp{sysconf}, @samp{localstate},
6246 @samp{lib}, or @samp{pkglib} are installed by @code{install-exec}.
6248 For instance, @code{data_DATA} files are installed by @code{install-data},
6249 while @code{bin_PROGRAMS} files are installed by @code{install-exec}.
6251 Any variable using a user-defined directory prefix with @samp{exec} in
6252 the name (e.g., @code{myexecbin_PROGRAMS}) is installed by
6253 @code{install-exec}. All other user-defined prefixes are installed by
6254 @code{install-data}.
6256 @section Extending installation
6258 It is possible to extend this mechanism by defining an
6259 @code{install-exec-local} or @code{install-data-local} rule. If these
6260 rules exist, they will be run at @samp{make install} time. These
6261 rules can do almost anything; care is required.
6262 @trindex install-exec-local
6263 @trindex install-data-local
6265 Automake also supports two install hooks, @code{install-exec-hook} and
6266 @code{install-data-hook}. These hooks are run after all other install
6267 rules of the appropriate type, exec or data, have completed. So, for
6268 instance, it is possible to perform post-installation modifications
6269 using an install hook. @ref{Extending} gives some examples.
6270 @cindex Install hook
6272 @section Staged installs
6275 Automake generates support for the @code{DESTDIR} variable in all
6276 install rules. @code{DESTDIR} is used during the @samp{make install}
6277 step to relocate install objects into a staging area. Each object and
6278 path is prefixed with the value of @code{DESTDIR} before being copied
6279 into the install area. Here is an example of typical DESTDIR usage:
6282 mkdir /tmp/staging &&
6283 make DESTDIR=/tmp/staging install
6286 The @command{mkdir} command avoids a security problem if the attacker
6287 creates a symbolic link from @file{/tmp/staging} to a victim area;
6288 then @command{make} places install objects in a directory tree built under
6289 @file{/tmp/staging}. If @file{/gnu/bin/foo} and
6290 @file{/gnu/share/aclocal/foo.m4} are to be installed, the above command
6291 would install @file{/tmp/staging/gnu/bin/foo} and
6292 @file{/tmp/staging/gnu/share/aclocal/foo.m4}.
6294 This feature is commonly used to build install images and packages. For
6295 more information, see @ref{Makefile Conventions, , , standards, The GNU
6298 Support for @code{DESTDIR} is implemented by coding it directly into the
6299 install rules. If your @file{Makefile.am} uses a local install rule
6300 (e.g., @code{install-exec-local}) or an install hook, then you must
6301 write that code to respect @code{DESTDIR}.
6303 @section Rules for the user
6305 Automake also generates rules for targets @code{uninstall},
6306 @code{installdirs}, and @code{install-strip}.
6308 @trindex installdirs
6309 @trindex install-strip
6311 Automake supports @code{uninstall-local} and @code{uninstall-hook}.
6312 There is no notion of separate uninstalls for ``exec'' and ``data'', as
6313 these features would not provide additional functionality.
6315 Note that @code{uninstall} is not meant as a replacement for a real
6320 @chapter What Gets Cleaned
6322 @cindex @samp{make clean} support
6324 The GNU Makefile Standards specify a number of different clean rules.
6325 @xref{Standard Targets, , Standard Targets for Users, standards,
6326 The GNU Coding Standards}.
6328 Generally the files that can be cleaned are determined automatically by
6329 Automake. Of course, Automake also recognizes some variables that can
6330 be defined to specify additional files to clean. These variables are
6331 @code{MOSTLYCLEANFILES}, @code{CLEANFILES}, @code{DISTCLEANFILES}, and
6332 @code{MAINTAINERCLEANFILES}.
6333 @vindex MOSTLYCLEANFILES
6335 @vindex DISTCLEANFILES
6336 @vindex MAINTAINERCLEANFILES
6338 @trindex mostlyclean-local
6339 @trindex clean-local
6340 @trindex distclean-local
6341 @trindex maintainer-clean-local
6342 When cleaning involves more than deleting some hard-coded list of
6343 files, it is also possible to supplement the cleaning rules with your
6344 own commands. Simply define a rule for any of the
6345 @code{mostlyclean-local}, @code{clean-local}, @code{distclean-local},
6346 or @code{maintainer-clean-local} targets (@pxref{Extending}). A common
6347 case is deleting a directory, for instance, a directory created by the
6355 As the GNU Standards aren't always explicit as to which files should
6356 be removed by which rule, we've adopted a heuristic that we believe
6357 was first formulated by Fran@,{c}ois Pinard:
6361 If @command{make} built it, and it is commonly something that one would
6362 want to rebuild (for instance, a @file{.o} file), then
6363 @code{mostlyclean} should delete it.
6366 Otherwise, if @command{make} built it, then @code{clean} should delete it.
6369 If @command{configure} built it, then @code{distclean} should delete it.
6372 If the maintainer built it (for instance, a @file{.info} file), then
6373 @code{maintainer-clean} should delete it. However
6374 @code{maintainer-clean} should not delete anything that needs to exist
6375 in order to run @samp{./configure && make}.
6378 We recommend that you follow this same set of heuristics in your
6383 @chapter What Goes in a Distribution
6385 @section Basics of distribution
6387 @cindex @samp{make dist}
6392 The @code{dist} rule in the generated @file{Makefile.in} can be used
6393 to generate a gzip'd @code{tar} file and other flavors of archive for
6394 distribution. The files is named based on the @code{PACKAGE} and
6395 @code{VERSION} variables defined by @code{AM_INIT_AUTOMAKE}
6396 (@pxref{Macros}); more precisely the gzip'd @code{tar} file is named
6397 @samp{@var{package}-@var{version}.tar.gz}.
6399 You can use the @command{make} variable @code{GZIP_ENV} to control how gzip
6400 is run. The default setting is @option{--best}.
6402 @cindex @code{m4_include}, distribution
6403 @cindex @code{include}, distribution
6406 For the most part, the files to distribute are automatically found by
6407 Automake: all source files are automatically included in a distribution,
6408 as are all @file{Makefile.am}s and @file{Makefile.in}s. Automake also
6409 has a built-in list of commonly used files that are automatically
6410 included if they are found in the current directory (either physically,
6411 or as the target of a @file{Makefile.am} rule). This list is printed by
6412 @samp{automake --help}. Also, files that are read by @command{configure}
6413 (i.e.@: the source files corresponding to the files specified in various
6414 Autoconf macros such as @code{AC_CONFIG_FILES} and siblings) are
6415 automatically distributed. Files included in @file{Makefile.am}s (using
6416 @code{include}) or in @file{configure.ac} (using @code{m4_include}), and
6417 helper scripts installed with @samp{automake --add-missing} are also
6421 Still, sometimes there are files that must be distributed, but which
6422 are not covered in the automatic rules. These files should be listed in
6423 the @code{EXTRA_DIST} variable. You can mention files from
6424 subdirectories in @code{EXTRA_DIST}.
6426 You can also mention a directory in @code{EXTRA_DIST}; in this case the
6427 entire directory will be recursively copied into the distribution.
6428 Please note that this will also copy @emph{everything} in the directory,
6429 including CVS/RCS version control files. We recommend against using
6433 @vindex DIST_SUBDIRS
6434 If you define @code{SUBDIRS}, Automake will recursively include the
6435 subdirectories in the distribution. If @code{SUBDIRS} is defined
6436 conditionally (@pxref{Conditionals}), Automake will normally include
6437 all directories that could possibly appear in @code{SUBDIRS} in the
6438 distribution. If you need to specify the set of directories
6439 conditionally, you can set the variable @code{DIST_SUBDIRS} to the
6440 exact list of subdirectories to include in the distribution
6441 (@pxref{Conditional Subdirectories}).
6444 @section Fine-grained distribution control
6448 Sometimes you need tighter control over what does @emph{not} go into the
6449 distribution; for instance, you might have source files that are
6450 generated and that you do not want to distribute. In this case
6451 Automake gives fine-grained control using the @code{dist} and
6452 @code{nodist} prefixes. Any primary or @code{_SOURCES} variable can be
6453 prefixed with @code{dist_} to add the listed files to the distribution.
6454 Similarly, @code{nodist_} can be used to omit the files from the
6457 As an example, here is how you would cause some data to be distributed
6458 while leaving some source code out of the distribution:
6461 dist_data_DATA = distribute-this
6463 nodist_foo_SOURCES = do-not-distribute.c
6466 @section The dist hook
6470 Occasionally it is useful to be able to change the distribution before
6471 it is packaged up. If the @code{dist-hook} rule exists, it is run
6472 after the distribution directory is filled, but before the actual tar
6473 (or shar) file is created. One way to use this is for distributing
6474 files in subdirectories for which a new @file{Makefile.am} is overkill:
6478 mkdir $(distdir)/random
6479 cp -p $(srcdir)/random/a1 $(srcdir)/random/a2 $(distdir)/random
6482 Another way to to use this is for removing unnecessary files that get
6483 recursively included by specifying a directory in EXTRA_DIST:
6489 rm -rf `find $(distdir)/doc -name CVS`
6494 Two variables that come handy when writing @code{dist-hook} rules are
6495 @samp{$(distdir)} and @samp{$(top_distdir)}.
6497 @samp{$(distdir)} points to the directory where the @code{dist} rule
6498 will copy files from the current directory before creating the
6499 tarball. If you are at the top-level directory, then @samp{distdir =
6500 $(PACKAGE)-$(VERSION)}. When used from subdirectory named
6501 @file{foo/}, then @samp{distdir = ../$(PACKAGE)-$(VERSION)/foo}.
6502 @samp{$(distdir)} can be a relative or absolute path, do not assume
6505 @samp{$(top_distdir)} always points to the root directory of the
6506 distributed tree. At the top-level it's equal to @samp{$(distdir)}.
6507 In the @file{foo/} subdirectory
6508 @samp{top_distdir = ../$(PACKAGE)-$(VERSION)}.
6509 @samp{$(top_distdir)} too can be a relative or absolute path.
6511 Note that when packages are nested using @code{AC_CONFIG_SUBDIRS}
6512 (@pxref{Subpackages}), then @samp{$(distdir)} and
6513 @samp{$(top_distdir)} are relative to the package where @samp{make
6514 dist} was run, not to any sub-packages involved.
6516 @section Checking the distribution
6518 @cindex @samp{make distcheck}
6519 @cindex @samp{make distcleancheck}
6520 @vindex distcleancheck_listfiles
6521 @cindex @samp{make distuninstallcheck}
6522 @vindex distuninstallcheck_listfiles
6525 Automake also generates a @code{distcheck} rule that can be of help
6526 to ensure that a given distribution will actually work.
6527 @code{distcheck} makes a distribution, then tries to do a @code{VPATH}
6528 build, run the test suite, and finally make another tarfile to ensure the
6529 distribution is self-contained.
6531 @vindex DISTCHECK_CONFIGURE_FLAGS
6532 Building the package involves running @samp{./configure}. If you need
6533 to supply additional flags to @command{configure}, define them in the
6534 @code{DISTCHECK_CONFIGURE_FLAGS} variable, either in your top-level
6535 @file{Makefile.am}, or on the command line when invoking @command{make}.
6537 @trindex distcheck-hook
6538 If the @code{distcheck-hook} rule is defined in your top-level
6539 @file{Makefile.am}, then it will be invoked by @code{distcheck} after
6540 the new distribution has been unpacked, but before the unpacked copy
6541 is configured and built. Your @code{distcheck-hook} can do almost
6542 anything, though as always caution is advised. Generally this hook is
6543 used to check for potential distribution errors not caught by the
6544 standard mechanism. Note that @code{distcheck-hook} as well as
6545 @code{DISTCHECK_CONFIGURE_FLAGS} are not honored in a subpackage
6546 @file{Makefile.am}, but the @code{DISTCHECK_CONFIGURE_FLAGS} are
6547 passed down to the @command{configure} script of the subpackage.
6549 @trindex distcleancheck
6550 @vindex DISTCLEANFILES
6551 @vindex distcleancheck_listfiles
6552 Speaking of potential distribution errors, @code{distcheck} also
6553 ensures that the @code{distclean} rule actually removes all built
6554 files. This is done by running @samp{make distcleancheck} at the end of
6555 the @code{VPATH} build. By default, @code{distcleancheck} will run
6556 @code{distclean} and then make sure the build tree has been emptied by
6557 running @samp{$(distcleancheck_listfiles)}. Usually this check will
6558 find generated files that you forgot to add to the @code{DISTCLEANFILES}
6559 variable (@pxref{Clean}).
6561 The @code{distcleancheck} behavior should be OK for most packages,
6562 otherwise you have the possibility to override the definition of
6563 either the @code{distcleancheck} rule, or the
6564 @samp{$(distcleancheck_listfiles)} variable. For instance, to disable
6565 @code{distcleancheck} completely, add the following rule to your
6566 top-level @file{Makefile.am}:
6573 If you want @code{distcleancheck} to ignore built files that have not
6574 been cleaned because they are also part of the distribution, add the
6575 following definition instead:
6578 distcleancheck_listfiles = \
6579 find -type f -exec sh -c 'test -f $(srcdir)/@{@} || echo @{@}' ';'
6582 The above definition is not the default because it's usually an error if
6583 your Makefiles cause some distributed files to be rebuilt when the user
6584 build the package. (Think about the user missing the tool required to
6585 build the file; or if the required tool is built by your package,
6586 consider the cross-compilation case where it can't be run.) There is
6587 a FAQ entry about this (@pxref{distcleancheck}), make sure you read it
6588 before playing with @code{distcleancheck_listfiles}.
6590 @code{distcheck} also checks that the @code{uninstall} rule works
6591 properly, both for ordinary and @code{DESTDIR} builds. It does this
6592 by invoking @samp{make uninstall}, and then it checks the install tree
6593 to see if any files are left over. This check will make sure that you
6594 correctly coded your @code{uninstall}-related rules.
6596 By default, the checking is done by the @code{distuninstallcheck} rule,
6597 and the list of files in the install tree is generated by
6598 @samp{$(distuninstallcheck_listfiles}) (this is a variable whose value is
6599 a shell command to run that prints the list of files to stdout).
6601 Either of these can be overridden to modify the behavior of
6602 @code{distcheck}. For instance, to disable this check completely, you
6610 @section The types of distributions
6612 Automake generates rules to provide archives of the project for
6613 distributions in various formats. Their targets are:
6616 @item @code{dist-bzip2}
6617 Generate a bzip2 tar archive of the distribution. bzip2 archives are
6618 frequently smaller than gzipped archives.
6621 @item @code{dist-gzip}
6622 Generate a gzip tar archive of the distribution.
6625 @item @code{dist-shar}
6626 Generate a shar archive of the distribution.
6629 @item @code{dist-zip}
6630 Generate a zip archive of the distribution.
6633 @item @code{dist-tarZ}
6634 Generate a compressed tar archive of
6639 The rule @code{dist} (and its historical synonym @code{dist-all}) will
6640 create archives in all the enabled formats, @ref{Options}. By
6641 default, only the @code{dist-gzip} target is hooked to @code{dist}.
6645 @chapter Support for test suites
6648 @cindex @code{make check}
6651 Automake supports two forms of test suites.
6653 @section Simple Tests
6655 If the variable @code{TESTS} is defined, its value is taken to be a list
6656 of programs to run in order to do the testing. The programs can either
6657 be derived objects or source objects; the generated rule will look both
6658 in @code{srcdir} and @file{.}. Programs needing data files should look
6659 for them in @code{srcdir} (which is both an environment variable and a
6660 make variable) so they work when building in a separate directory
6661 (@pxref{Build Directories, , Build Directories , autoconf, The Autoconf
6662 Manual}), and in particular for the @code{distcheck} rule
6665 @cindex Exit status 77, special interpretation
6667 The number of failures will be printed at the end of the run. If a
6668 given test program exits with a status of 77, then its result is ignored
6669 in the final count. This feature allows non-portable tests to be
6670 ignored in environments where they don't make sense.
6672 The variable @code{TESTS_ENVIRONMENT} can be used to set environment
6673 variables for the test run; the environment variable @code{srcdir} is
6674 set in the rule. If all your test programs are scripts, you can also
6675 set @code{TESTS_ENVIRONMENT} to an invocation of the shell (e.g.
6676 @samp{$(SHELL) -x}); this can be useful for debugging the tests.
6678 @vindex TESTS_ENVIRONMENT
6680 @cindex Tests, expected failure
6681 @cindex Expected test failure
6683 You may define the variable @code{XFAIL_TESTS} to a list of tests
6684 (usually a subset of @code{TESTS}) that are expected to fail. This will
6685 reverse the result of those tests.
6688 Automake ensures that each program listed in @code{TESTS} is built
6689 before any tests are run; you can list both source and derived programs
6690 in @code{TESTS}. For instance, you might want to run a C program as a
6691 test. To do this you would list its name in @code{TESTS} and also in
6692 @code{check_PROGRAMS}, and then specify it as you would any other
6695 @section DejaGnu Tests
6697 If @uref{ftp://ftp.gnu.org/gnu/dejagnu/, @command{dejagnu}} appears in
6698 @code{AUTOMAKE_OPTIONS}, then a @command{dejagnu}-based test suite is
6699 assumed. The variable @code{DEJATOOL} is a list of names that are
6700 passed, one at a time, as the @option{--tool} argument to
6701 @command{runtest} invocations; it defaults to the name of the package.
6703 The variable @code{RUNTESTDEFAULTFLAGS} holds the @option{--tool} and
6704 @option{--srcdir} flags that are passed to dejagnu by default; this can be
6705 overridden if necessary.
6706 @vindex RUNTESTDEFAULTFLAGS
6708 The variables @code{EXPECT} and @code{RUNTEST} can
6709 also be overridden to provide project-specific values. For instance,
6710 you will need to do this if you are testing a compiler toolchain,
6711 because the default values do not take into account host and target
6718 The contents of the variable @code{RUNTESTFLAGS} are passed to the
6719 @code{runtest} invocation. This is considered a ``user variable''
6720 (@pxref{User Variables}). If you need to set @command{runtest} flags in
6721 @file{Makefile.am}, you can use @code{AM_RUNTESTFLAGS} instead.
6722 @vindex RUNTESTFLAGS
6723 @vindex AM_RUNTESTFLAGS
6725 @cindex @file{site.exp}
6726 Automake will generate rules to create a local @file{site.exp} file,
6727 defining various variables detected by @command{configure}. This file
6728 is automatically read by DejaGnu. It is OK for the user of a package
6729 to edit this file in order to tune the test suite. However this is
6730 not the place where the test suite author should define new variables:
6731 this should be done elsewhere in the real test suite code.
6732 Especially, @file{site.exp} should not be distributed.
6734 For more information regarding DejaGnu test suites, see @ref{Top, , ,
6735 dejagnu, The DejaGnu Manual}.
6737 In either case, the testing is done via @samp{make check}.
6739 @section Install Tests
6741 The @code{installcheck} target is available to the user as a way to
6742 run any tests after the package has been installed. You can add tests
6743 to this by writing an @code{installcheck-local} rule.
6747 @chapter Rebuilding Makefiles
6748 @cindex rebuild rules
6750 Automake generates rules to automatically rebuild @file{Makefile}s,
6751 @file{configure}, and other derived files like @file{Makefile.in}.
6753 @acindex AM_MAINTAINER_MODE
6754 If you are using @code{AM_MAINTAINER_MODE} in @file{configure.ac}, then
6755 these automatic rebuilding rules are only enabled in maintainer mode.
6757 @vindex ACLOCAL_AMFLAGS
6758 Sometimes you need to run @command{aclocal} with an argument like
6759 @option{-I} to tell it where to find @file{.m4} files. Since
6760 sometimes @command{make} will automatically run @command{aclocal}, you
6761 need a way to specify these arguments. You can do this by defining
6762 @code{ACLOCAL_AMFLAGS}; this holds arguments that are passed verbatim
6763 to @command{aclocal}. This variable is only useful in the top-level
6766 @vindex CONFIG_STATUS_DEPENDENCIES
6767 @vindex CONFIGURE_DEPENDENCIES
6768 @cindex @file{version.sh}, example
6769 @cindex @file{version.m4}, example
6771 Sometimes it is convenient to supplement the rebuild rules for
6772 @file{configure} or @file{config.status} with additional dependencies.
6773 The variables @code{CONFIGURE_DEPENDENCIES} and
6774 @code{CONFIG_STATUS_DEPENDENCIES} can be used to list these extra
6775 dependencies. These variable should be defined in all
6776 @file{Makefile}s of the tree (because these two rebuild rules are
6777 output in all them), so it is safer and easier to @code{AC_SUBST} them
6778 from @file{configure.ac}. For instance, the following statement will
6779 cause @file{configure} to be rerun each time @file{version.sh} is
6782 AC_SUBST([CONFIG_STATUS_DEPENDENCIES], ['$(top_srcdir)/version.sh'])
6785 Note the @samp{$(top_srcdir)/} in the file name. Since this variable
6786 is to be used in all @file{Makefile}s, its value must be sensible at
6787 any level in the build hierarchy.
6789 Beware not to mistake @code{CONFIGURE_DEPENDENCIES} for
6790 @code{CONFIG_STATUS_DEPENDENCIES}.
6792 @code{CONFIGURE_DEPENDENCIES} adds dependencies to the
6793 @file{configure} rule, whose effect is to run @command{autoconf}. This
6794 variable should be seldom used, because @command{automake} already tracks
6795 @code{m4_include}d files. However it can be useful when playing
6796 tricky games with @code{m4_esyscmd} or similar non-recommendable
6797 macros with side effects.
6799 @code{CONFIG_STATUS_DEPENDENCIES} adds dependencies to the
6800 @file{config.status} rule, whose effect is to run @file{configure}.
6801 This variable should therefore carry any non-standard source that may
6802 be read as a side effect of running configure, like @file{version.sh}
6803 in the example above.
6805 Speaking of @file{version.sh} scripts, we recommend against them
6806 today. They are mainly used when the version of a package is updated
6807 automatically by a script (e.g., in daily builds). Here is what some
6808 old-style @file{configure.ac}s may look like:
6811 . $srcdir/version.sh
6812 AM_INIT_AUTOMAKE([name], $VERSION_NUMBER)
6816 Here, @file{version.sh} is a shell fragment that sets
6817 @code{VERSION_NUMBER}. The problem with this example is that
6818 @command{automake} cannot track dependencies (listing @file{version.sh}
6819 in @command{CONFIG_STATUS_DEPENDENCIES}, and distributing this file is up
6820 to the user), and that it uses the obsolete form of @code{AC_INIT} and
6821 @code{AM_INIT_AUTOMAKE}. Upgrading to the new syntax is not
6822 straightforward, because shell variables are not allowed in
6823 @code{AC_INIT}'s arguments. We recommend that @file{version.sh} be
6824 replaced by an M4 file that is included by @file{configure.ac}:
6826 m4_include([version.m4])
6827 AC_INIT([name], VERSION_NUMBER)
6832 Here @file{version.m4} could contain something like
6833 @samp{m4_define([VERSION_NUMBER], [1.2])}. The advantage of this
6834 second form is that @command{automake} will take care of the
6835 dependencies when defining the rebuild rule, and will also distribute
6836 the file automatically. An inconvenience is that @command{autoconf}
6837 will now be rerun each time the version number is bumped, when only
6838 @file{configure} had to be rerun in the previous setup.
6842 @chapter Changing Automake's Behavior
6844 Various features of Automake can be controlled by options in the
6845 @file{Makefile.am}. Such options are applied on a per-@file{Makefile}
6846 basis when listed in a special @file{Makefile} variable named
6847 @code{AUTOMAKE_OPTIONS}. They are applied globally to all processed
6848 @file{Makefiles} when listed in the first argument of
6849 @code{AM_INIT_AUTOMAKE} in @file{configure.ac}. Currently understood
6851 @vindex AUTOMAKE_OPTIONS
6854 @item @option{gnits}
6856 @itemx @option{foreign}
6857 @itemx @option{cygnus}
6858 @cindex Option, @option{gnits}
6859 @cindex Option, @option{gnu}
6860 @cindex Option, @option{foreign}
6861 @cindex Option, @option{cygnus}
6867 Set the strictness as appropriate. The @option{gnits} option also
6868 implies options @option{readme-alpha} and @option{check-news}.
6870 @item @option{ansi2knr}
6871 @itemx @option{@var{path}/ansi2knr}
6872 @cindex Option, @option{ansi2knr}
6874 Turn on automatic de-ANSI-fication. @xref{ANSI}. If preceded by a
6875 path, the generated @file{Makefile.in} will look in the specified
6876 directory to find the @file{ansi2knr} program. The path should be a
6877 relative path to another directory in the same distribution (Automake
6878 currently does not check this).
6880 @item @option{check-news}
6881 @cindex Option, @option{check-news}
6883 Cause @samp{make dist} to fail unless the current version number appears
6884 in the first few lines of the @file{NEWS} file.
6886 @item @option{dejagnu}
6887 @cindex Option, @option{dejagnu}
6889 Cause @command{dejagnu}-specific rules to be generated. @xref{Tests}.
6891 @item @option{dist-bzip2}
6892 @cindex Option, @option{dist-bzip2}
6894 Hook @code{dist-bzip2} to @code{dist}.
6897 @item @option{dist-shar}
6898 @cindex Option, @option{dist-shar}
6900 Hook @code{dist-shar} to @code{dist}.
6903 @item @option{dist-zip}
6904 @cindex Option, @option{dist-zip}
6906 Hook @code{dist-zip} to @code{dist}.
6909 @item @option{dist-tarZ}
6910 @cindex Option, @option{dist-tarZ}
6912 Hook @code{dist-tarZ} to @code{dist}.
6915 @item @option{filename-length-max=99}
6916 @cindex Option, @option{filename-length-max=99}
6917 @opindex filename-length-max=99
6918 Abort if file names longer than 99 characters are found during
6919 @samp{make dist}. Such long file names are generally considered not to
6920 be portable in tarballs. See the @option{tar-v7} and @option{tar-ustar}
6921 options below. This option should be used in the top-level
6922 @file{Makefile.am} or as an argument of @code{AM_INIT_AUTOMAKE} in
6923 @file{configure.ac}, it will be ignored otherwise.
6925 @item @option{no-define}
6926 @cindex Option, @option{no-define}
6928 This options is meaningful only when passed as an argument to
6929 @code{AM_INIT_AUTOMAKE}. It will prevent the @code{PACKAGE} and
6930 @code{VERSION} variables to be @code{AC_DEFINE}d.
6932 @item @option{no-dependencies}
6933 @cindex Option, @option{no-dependencies}
6934 @opindex no-dependencies
6935 This is similar to using @option{--include-deps} on the command line,
6936 but is useful for those situations where you don't have the necessary
6937 bits to make automatic dependency tracking work
6938 (@pxref{Dependencies}). In this case the effect is to effectively
6939 disable automatic dependency tracking.
6941 @item @option{no-dist}
6942 @cindex Option, @option{no-dist}
6944 Don't emit any code related to @code{dist} target. This is useful
6945 when a package has its own method for making distributions.
6947 @item @option{no-dist-gzip}
6948 @cindex Option, @option{no-dist-gzip}
6949 @opindex no-dist-gzip
6950 Do not hook @code{dist-gzip} to @code{dist}.
6951 @trindex no-dist-gzip
6953 @item @option{no-exeext}
6954 @cindex Option, @option{no-exeext}
6956 If your @file{Makefile.am} defines a rule for target @code{foo}, it
6957 will override a rule for a target named @samp{foo$(EXEEXT)}. This is
6958 necessary when @code{EXEEXT} is found to be empty. However, by
6959 default automake will generate an error for this use. The
6960 @option{no-exeext} option will disable this error. This is intended for
6961 use only where it is known in advance that the package will not be
6962 ported to Windows, or any other operating system using extensions on
6965 @item @option{no-installinfo}
6966 @cindex Option, @option{no-installinfo}
6967 @opindex no-installinfo
6968 The generated @file{Makefile.in} will not cause info pages to be built
6969 or installed by default. However, @code{info} and @code{install-info}
6970 targets will still be available. This option is disallowed at
6971 @option{gnu} strictness and above.
6973 @trindex install-info
6975 @item @option{no-installman}
6976 @cindex Option, @option{no-installman}
6977 @opindex no-installman
6978 The generated @file{Makefile.in} will not cause man pages to be
6979 installed by default. However, an @code{install-man} target will still
6980 be available for optional installation. This option is disallowed at
6981 @option{gnu} strictness and above.
6982 @trindex install-man
6984 @item @option{nostdinc}
6985 @cindex Option, @option{nostdinc}
6987 This option can be used to disable the standard @option{-I} options that
6988 are ordinarily automatically provided by Automake.
6990 @item @option{no-texinfo.tex}
6991 @cindex Option, @option{no-texinfo.tex}
6992 @opindex no-texinfo.tex
6993 Don't require @file{texinfo.tex}, even if there are texinfo files in
6996 @item @option{readme-alpha}
6997 @cindex Option, @option{readme-alpha}
6998 @opindex readme-alpha
6999 If this release is an alpha release, and the file @file{README-alpha}
7000 exists, then it will be added to the distribution. If this option is
7001 given, version numbers are expected to follow one of two forms. The
7002 first form is @samp{@var{MAJOR}.@var{MINOR}.@var{ALPHA}}, where each
7003 element is a number; the final period and number should be left off for
7004 non-alpha releases. The second form is
7005 @samp{@var{MAJOR}.@var{MINOR}@var{ALPHA}}, where @var{ALPHA} is a
7006 letter; it should be omitted for non-alpha releases.
7008 @item @option{std-options}
7009 @cindex Options, @option{std-options}
7010 @cindex @samp{make installcheck}, testing @option{--help} and @option{--version}
7011 @cindex @option{--help} check
7012 @cindex @option{--version} check
7013 @opindex std-options
7015 Make the @code{installcheck} rule check that installed scripts and
7016 programs support the @option{--help} and @option{--version} options.
7017 This also provides a basic check that the program's
7018 run-time dependencies are satisfied after installation.
7020 @vindex AM_INSTALLCHECK_STD_OPTIONS_EXEMPT
7021 In a few situations, programs (or scripts) have to be exempted from this
7022 test. For instance, @command{false} (from GNU sh-utils) is never
7023 successful, even for @option{--help} or @option{--version}. You can list
7024 such programs in the variable @code{AM_INSTALLCHECK_STD_OPTIONS_EXEMPT}.
7025 Programs (not scripts) listed in this variable should be suffixed by
7026 @samp{$(EXEEXT)} for the sake of Win32 or OS/2. For instance, suppose we
7027 build @file{false} as a program but @file{true.sh} as a script, and that
7028 neither of them support @option{--help} or @option{--version}:
7031 AUTOMAKE_OPTIONS = std-options
7032 bin_PROGRAMS = false ...
7033 bin_SCRIPTS = true.sh ...
7034 AM_INSTALLCHECK_STD_OPTIONS_EXEMPT = false$(EXEEXT) true.sh
7037 @item @option{subdir-objects}
7038 @cindex Options, @option{subdir-objects}
7039 @opindex subdir-objects
7040 If this option is specified, then objects are placed into the
7041 subdirectory of the build directory corresponding to the subdirectory of
7042 the source file. For instance, if the source file is
7043 @file{subdir/file.cxx}, then the output file would be
7044 @file{subdir/file.o}.
7046 In order to use this option with C sources, you should add
7047 @code{AM_PROG_CC_C_O} to @file{configure.ac}.
7049 @item @option{tar-v7}
7050 @itemx @option{tar-ustar}
7051 @itemx @option{tar-pax}
7052 @cindex Option, @option{tar-v7}
7053 @cindex Option, @option{tar-ustar}
7054 @cindex Option, @option{tar-pax}
7055 @cindex @command{tar} formats
7056 @cindex v7 @command{tar} format
7057 @cindex ustar format
7063 These three mutually exclusive options select the tar format to use
7064 when generating tarballs with @samp{make dist}. (The tar file created
7065 is then compressed according to the set of @option{no-dist-gzip},
7066 @option{dist-bzip2} and @option{dist-tarZ} options in use.)
7068 These options must be passed as argument to @code{AM_INIT_AUTOMAKE}
7069 (@pxref{Macros}) because they can require additional configure checks.
7070 Automake will complain if it sees such options in an
7071 @code{AUTOMAKE_OPTIONS} variable.
7073 @option{tar-v7} selects the old V7 tar format. This is the historical
7074 default. This antiquated format is understood by all tar
7075 implementations and supports file names with up to 99 characters. When
7076 given longer file names some tar implementations will diagnose the
7077 problem while other will generate broken tarballs or use non-portable
7078 extensions. Furthermore, the V7 format cannot store empty
7079 directories. When using this format, consider using the
7080 @option{filename-length-max=99} option to catch file names too long.
7082 @option{tar-ustar} selects the ustar format defined by POSIX
7083 1003.1-1988. This format is believed to be old enough to be portable.
7084 It fully supports empty directories. It can store file names with up
7085 to 256 characters, provided that the file name can be split at
7086 directory separator in two parts, first of them being at most 155
7087 bytes long. So, in most cases the maximum file name length will be
7088 shorter than 256 characters. However you may run against broken tar
7089 implementations that incorrectly handle file names longer than 99
7090 characters (please report them to @email{bug-automake@@gnu.org} so we
7091 can document this accurately).
7093 @option{tar-pax} selects the new pax interchange format defined by POSIX
7094 1003.1-2001. It does not limit the length of file names. However,
7095 this format is very young and should probably be restricted to
7096 packages that target only very modern platforms. There are moves to
7097 change the pax format in an upward-compatible way, so this option may
7098 refer to a more recent version in the future.
7100 @xref{Formats, , Controlling the Archive Format, tar, GNU Tar}, for
7101 further discussion about tar formats.
7103 @command{configure} knows several ways to construct these formats. It
7104 will not abort if it cannot find a tool up to the task (so that the
7105 package can still be built), but @samp{make dist} will fail.
7108 @cindex Option, @var{version}
7109 A version number (e.g., @samp{0.30}) can be specified. If Automake is not
7110 newer than the version specified, creation of the @file{Makefile.in}
7113 @item @option{-W@var{category}} or @option{--warnings=@var{category}}
7114 @cindex Option, warnings
7115 @cindex Option, @option{-W@var{category}}
7116 @cindex Option, @option{--warnings=@var{category}}
7117 These options behave exactly like their command-line counterpart
7118 (@pxref{Invoking Automake}). This allows you to enable or disable some
7119 warning categories on a per-file basis. You can also setup some warnings
7120 for your entire project; for instance, try @samp{AM_INIT_AUTOMAKE([-Wall])}
7121 in your @file{configure.ac}.
7125 Unrecognized options are diagnosed by @command{automake}.
7127 If you want an option to apply to all the files in the tree, you can use
7128 the @code{AM_INIT_AUTOMAKE} macro in @file{configure.ac}.
7133 @chapter Miscellaneous Rules
7135 There are a few rules and variables that didn't fit anywhere else.
7138 * Tags:: Interfacing to etags and mkid
7139 * Suffixes:: Handling new file extensions
7140 * Multilibs:: Support for multilibs.
7145 @section Interfacing to @command{etags}
7147 @cindex @file{TAGS} support
7149 Automake will generate rules to generate @file{TAGS} files for use with
7150 GNU Emacs under some circumstances.
7153 If any C, C++ or Fortran 77 source code or headers are present, then
7154 @code{tags} and @code{TAGS} rules will be generated for the directory.
7155 All files listed using the @code{_SOURCES}, @code{_HEADERS}, and
7156 @code{_LISP} primaries will be used to generate tags. Note that
7157 generated source files that are not distributed must be declared in
7158 variables like @code{nodist_noinst_HEADERS} or
7159 @code{nodist_@var{prog}_SOURCES} or they will be ignored.
7161 A @code{tags} rule will be output at the topmost directory of a
7162 multi-directory package. When run from this topmost directory,
7163 @samp{make tags} will generate a @file{TAGS} file that includes by
7164 reference all @file{TAGS} files from subdirectories.
7166 The @code{tags} rule will also be generated if the variable
7167 @code{ETAGS_ARGS} is defined. This variable is intended for use in
7168 directories that contain taggable source that @command{etags} does
7169 not understand. The user can use the @code{ETAGSFLAGS} to pass
7170 additional flags to @command{etags}; @code{AM_ETAGSFLAGS} is also
7171 available for use in @file{Makefile.am}.
7174 @vindex AM_ETAGSFLAGS
7176 Here is how Automake generates tags for its source, and for nodes in its
7180 ETAGS_ARGS = automake.in --lang=none \
7181 --regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi
7184 If you add file names to @code{ETAGS_ARGS}, you will probably also
7185 want to define @code{TAGS_DEPENDENCIES}. The contents of this variable
7186 are added directly to the dependencies for the @code{tags} rule.
7187 @vindex TAGS_DEPENDENCIES
7189 Automake also generates a @code{ctags} rule that can be used to
7190 build @command{vi}-style @file{tags} files. The variable @code{CTAGS}
7191 is the name of the program to invoke (by default @command{ctags});
7192 @code{CTAGSFLAGS} can be used by the user to pass additional flags,
7193 and @code{AM_CTAGSFLAGS} can be used by the @file{Makefile.am}.
7195 Automake will also generate an @code{ID} rule that will run
7196 @command{mkid} on the source. This is only supported on a
7197 directory-by-directory basis.
7200 Finally, Automake also emit rules to support the
7201 @uref{http://www.gnu.org/software/global/, GNU Global Tags program}.
7202 The @code{GTAGS} rule runs Global Tags and puts the
7203 result in the top build directory. The variable @code{GTAGS_ARGS}
7204 holds arguments that are passed to @command{gtags}.
7209 @section Handling new file extensions
7211 @cindex Adding new @code{SUFFIXES}
7212 @cindex @code{SUFFIXES}, adding
7215 It is sometimes useful to introduce a new implicit rule to handle a file
7216 type that Automake does not know about.
7218 For instance, suppose you had a compiler that could compile @file{.foo}
7219 files to @file{.o} files. You would simply define an suffix rule for
7227 Then you could directly use a @file{.foo} file in a @code{_SOURCES}
7228 variable and expect the correct results:
7232 doit_SOURCES = doit.foo
7235 This was the simpler and more common case. In other cases, you will
7236 have to help Automake to figure which extensions you are defining your
7237 suffix rule for. This usually happens when your extensions does not
7238 start with a dot. Then, all you have to do is to put a list of new
7239 suffixes in the @code{SUFFIXES} variable @strong{before} you define your
7242 For instance, the following definition prevents Automake to misinterpret
7243 @samp{.idlC.cpp:} as an attempt to transform @file{.idlC} files into
7247 SUFFIXES = .idl C.cpp
7252 As you may have noted, the @code{SUFFIXES} variable behaves like the
7253 @code{.SUFFIXES} special target of @command{make}. You should not touch
7254 @code{.SUFFIXES} yourself, but use @code{SUFFIXES} instead and let
7255 Automake generate the suffix list for @code{.SUFFIXES}. Any given
7256 @code{SUFFIXES} go at the start of the generated suffixes list, followed
7257 by Automake generated suffixes not already in the list.
7260 @section Support for Multilibs
7262 Automake has support for an obscure feature called multilibs. A
7263 @dfn{multilib} is a library that is built for multiple different ABIs
7264 at a single time; each time the library is built with a different target
7265 flag combination. This is only useful when the library is intended to
7266 be cross-compiled, and it is almost exclusively used for compiler
7269 The multilib support is still experimental. Only use it if you are
7270 familiar with multilibs and can debug problems you might encounter.
7277 @cindex Including @file{Makefile} fragment
7278 @cindex @file{Makefile} fragment, including
7280 Automake supports an @code{include} directive that can be used to
7281 include other @file{Makefile} fragments when @command{automake} is run.
7282 Note that these fragments are read and interpreted by @command{automake},
7283 not by @command{make}. As with conditionals, @command{make} has no idea that
7284 @code{include} is in use.
7286 There are two forms of @code{include}:
7289 @item include $(srcdir)/file
7290 Include a fragment that is found relative to the current source
7293 @item include $(top_srcdir)/file
7294 Include a fragment that is found relative to the top source directory.
7297 Note that if a fragment is included inside a conditional, then the
7298 condition applies to the entire contents of that fragment.
7300 Makefile fragments included this way are always distributed because
7301 they are needed to rebuild @file{Makefile.in}.
7304 @chapter Conditionals
7306 @cindex Conditionals
7308 Automake supports a simple type of conditionals.
7310 @acindex AM_CONDITIONAL
7311 Before using a conditional, you must define it by using
7312 @code{AM_CONDITIONAL} in the @file{configure.ac} file (@pxref{Macros}).
7314 @defmac AM_CONDITIONAL (@var{conditional}, @var{condition})
7315 The conditional name, @var{conditional}, should be a simple string
7316 starting with a letter and containing only letters, digits, and
7317 underscores. It must be different from @samp{TRUE} and @samp{FALSE}
7318 that are reserved by Automake.
7320 The shell @var{condition} (suitable for use in a shell @code{if}
7321 statement) is evaluated when @command{configure} is run. Note that you
7322 must arrange for @emph{every} @code{AM_CONDITIONAL} to be invoked every
7323 time @command{configure} is run. If @code{AM_CONDITIONAL} is run
7324 conditionally (e.g., in a shell @code{if} statement), then the result
7325 will confuse automake.
7328 @cindex @option{--enable-debug}, example
7329 @cindex Example conditional @option{--enable-debug}
7330 @cindex Conditional example, @option{--enable-debug}
7332 Conditionals typically depend upon options that the user provides to
7333 the @command{configure} script. Here is an example of how to write a
7334 conditional that is true if the user uses the @option{--enable-debug}
7338 AC_ARG_ENABLE(debug,
7339 [ --enable-debug Turn on debugging],
7340 [case "$@{enableval@}" in
7343 *) AC_MSG_ERROR(bad value $@{enableval@} for --enable-debug) ;;
7344 esac],[debug=false])
7345 AM_CONDITIONAL(DEBUG, test x$debug = xtrue)
7348 Here is an example of how to use that conditional in @file{Makefile.am}:
7360 noinst_PROGRAMS = $(DBG)
7363 This trivial example could also be handled using @code{EXTRA_PROGRAMS}
7364 (@pxref{Conditional Programs}).
7366 You may only test a single variable in an @code{if} statement, possibly
7367 negated using @samp{!}. The @code{else} statement may be omitted.
7368 Conditionals may be nested to any depth. You may specify an argument to
7369 @code{else} in which case it must be the negation of the condition used
7370 for the current @code{if}. Similarly you may specify the condition
7371 that is closed by an @code{end}:
7382 Unbalanced conditions are errors.
7384 Note that conditionals in Automake are not the same as conditionals in
7385 GNU Make. Automake conditionals are checked at configure time by the
7386 @file{configure} script, and affect the translation from
7387 @file{Makefile.in} to @file{Makefile}. They are based on options passed
7388 to @file{configure} and on results that @file{configure} has discovered
7389 about the host system. GNU Make conditionals are checked at @command{make}
7390 time, and are based on variables passed to the make program or defined
7391 in the @file{Makefile}.
7393 Automake conditionals will work with any make program.
7397 @chapter The effect of @option{--gnu} and @option{--gnits}
7399 @cindex @option{--gnu}, required files
7400 @cindex @option{--gnu}, complete description
7402 The @option{--gnu} option (or @option{gnu} in the
7403 @code{AUTOMAKE_OPTIONS} variable) causes @command{automake} to check
7408 The files @file{INSTALL}, @file{NEWS}, @file{README}, @file{AUTHORS},
7409 and @file{ChangeLog}, plus one of @file{COPYING.LIB}, @file{COPYING.LESSER}
7410 or @file{COPYING}, are required at the topmost directory of the package.
7413 The options @option{no-installman} and @option{no-installinfo} are
7417 Note that this option will be extended in the future to do even more
7418 checking; it is advisable to be familiar with the precise requirements
7419 of the GNU standards. Also, @option{--gnu} can require certain
7420 non-standard GNU programs to exist for use by various maintainer-only
7421 rules; for instance, in the future @command{pathchk} might be required for
7424 @cindex @option{--gnits}, complete description
7426 The @option{--gnits} option does everything that @option{--gnu} does, and
7427 checks the following as well:
7431 @samp{make installcheck} will check to make sure that the @option{--help}
7432 and @option{--version} really print a usage message and a version string,
7433 respectively. This is the @option{std-options} option (@pxref{Options}).
7436 @samp{make dist} will check to make sure the @file{NEWS} file has been
7437 updated to the current version.
7440 @code{VERSION} is checked to make sure its format complies with Gnits
7442 @c FIXME xref when standards are finished
7445 @cindex @file{README-alpha}
7446 If @code{VERSION} indicates that this is an alpha release, and the file
7447 @file{README-alpha} appears in the topmost directory of a package, then
7448 it is included in the distribution. This is done in @option{--gnits}
7449 mode, and no other, because this mode is the only one where version
7450 number formats are constrained, and hence the only mode where Automake
7451 can automatically determine whether @file{README-alpha} should be
7455 The file @file{THANKS} is required.
7460 @chapter The effect of @option{--cygnus}
7462 @cindex @option{cygnus} strictness
7464 Some packages, notably GNU GCC and GNU gdb, have a build environment
7465 originally written at Cygnus Support (subsequently renamed Cygnus
7466 Solutions, and then later purchased by Red Hat). Packages with this
7467 ancestry are sometimes referred to as ``Cygnus'' trees.
7469 A Cygnus tree has slightly different rules for how a
7470 @file{Makefile.in} is to be constructed. Passing @option{--cygnus} to
7471 @command{automake} will cause any generated @file{Makefile.in} to
7472 comply with Cygnus rules.
7474 Here are the precise effects of @option{--cygnus}:
7478 Info files are always created in the build directory, and not in the
7482 @file{texinfo.tex} is not required if a Texinfo source file is
7483 specified. The assumption is that the file will be supplied, but in a
7484 place that Automake cannot find. This assumption is an artifact of how
7485 Cygnus packages are typically bundled.
7488 @samp{make dist} is not supported, and the rules for it are not
7489 generated. Cygnus-style trees use their own distribution mechanism.
7492 Certain tools will be searched for in the build tree as well as in the
7493 user's @env{PATH}. These tools are @command{runtest}, @command{expect},
7494 @command{makeinfo} and @command{texi2dvi}.
7497 @option{--foreign} is implied.
7500 The options @option{no-installinfo} and @option{no-dependencies} are
7504 The macros @code{AM_MAINTAINER_MODE} and @code{AM_CYGWIN32} are
7508 The @code{check} target doesn't depend on @code{all}.
7511 GNU maintainers are advised to use @option{gnu} strictness in preference
7512 to the special Cygnus mode. Some day, perhaps, the differences between
7513 Cygnus trees and GNU trees will disappear (for instance, as GCC is made
7514 more standards compliant). At that time the special Cygnus mode will be
7519 @chapter When Automake Isn't Enough
7521 In some situations, where Automake is not up to one task, one has to
7522 resort to handwritten rules or even handwritten @file{Makefile}s.
7525 * Extending:: Adding new rules or overriding existing ones.
7526 * Third-Party Makefiles:: Integrating Non-Automake @file{Makefile}s.
7530 @section Extending Automake Rules
7532 With some minor exceptions (like @code{_PROGRAMS} variables being
7533 rewritten to append @samp{$(EXEEXT)}), the contents of a
7534 @file{Makefile.am} is copied to @file{Makefile.in} verbatim.
7536 @cindex copying semantics
7538 These copying semantics means that many problems can be worked around
7539 by simply adding some @command{make} variables and rules to
7540 @file{Makefile.am}. Automake will ignore these additions.
7542 @cindex conflicting definitions
7543 @cindex rules, conflicting
7544 @cindex variables, conflicting
7545 @cindex definitions, conflicts
7547 Since a @file{Makefile.in} is built from data gathered from three
7548 different places (@file{Makefile.am}, @file{configure.ac}, and
7549 @command{automake} itself), it is possible to have conflicting
7550 definitions of rules or variables. When building @file{Makefile.in}
7551 the following priorities are respected by @command{automake} to ensure
7552 the user always have the last word. User defined variables in
7553 @file{Makefile.am} have priority over variables @code{AC_SUBST}ed from
7554 @file{configure.ac}, and @code{AC_SUBST}ed variables have priority
7555 over @command{automake}-defined variables. As far rules are
7556 concerned, a user-defined rule overrides any
7557 @command{automake}-defined rule for the same target.
7559 @cindex overriding rules
7560 @cindex overriding semantics
7561 @cindex rules, overriding
7563 These overriding semantics make it possible to fine tune some default
7564 settings of Automake, or replace some of its rules. Overriding
7565 Automake rules is often inadvisable, particularly in the topmost
7566 directory of a package with subdirectories. The @option{-Woverride}
7567 option (@pxref{Invoking Automake}) comes handy to catch overridden
7570 Note that Automake does not make any difference between rules with
7571 commands and rules that only specify dependencies. So it is not
7572 possible to append new dependencies to an @command{automake}-defined
7573 target without redefining the entire rule.
7575 @cindex @option{-local} targets
7576 @cindex local targets
7578 However, various useful targets have a @samp{-local} version you can
7579 specify in your @file{Makefile.am}. Automake will supplement the
7580 standard target with these user-supplied targets.
7595 @trindex check-local
7597 @trindex install-data
7598 @trindex install-data-local
7599 @trindex install-dvi
7600 @trindex install-dvi-local
7601 @trindex install-exec
7602 @trindex install-exec-local
7603 @trindex install-html
7604 @trindex install-html-local
7605 @trindex install-info
7606 @trindex install-info-local
7607 @trindex install-pdf
7608 @trindex install-pdf-local
7610 @trindex install-ps-local
7612 @trindex uninstall-local
7613 @trindex mostlyclean
7614 @trindex mostlyclean-local
7616 @trindex clean-local
7618 @trindex distclean-local
7619 @trindex installdirs
7620 @trindex installdirs-local
7621 @trindex installcheck
7622 @trindex installcheck-local
7624 The targets that support a local version are @code{all}, @code{info},
7625 @code{dvi}, @code{ps}, @code{pdf}, @code{html}, @code{check},
7626 @code{install-data}, @code{install-dvi}, @code{install-exec},
7627 @code{install-html}, @code{install-info}, @code{install-pdf},
7628 @code{install-ps}, @code{uninstall}, @code{installdirs},
7629 @code{installcheck} and the various @code{clean} targets
7630 (@code{mostlyclean}, @code{clean}, @code{distclean}, and
7631 @code{maintainer-clean}).
7633 Note that there are no @code{uninstall-exec-local} or
7634 @code{uninstall-data-local} targets; just use @code{uninstall-local}.
7635 It doesn't make sense to uninstall just data or just executables.
7637 For instance, here is one way to erase a subdirectory during
7638 @samp{make clean} (@pxref{Clean}).
7645 Older version of this manual used to show how to use
7646 @code{install-data-local} to install a file to some hard-coded
7647 location, but you should avoid this. (@pxref{Hard-Coded Install Paths})
7649 @cindex @option{-hook} targets
7650 @cindex hook targets
7652 Some rule also have a way to run another rule, called a @dfn{hook},
7653 after their work is done. The hook is named after the principal target,
7654 with @samp{-hook} appended. The targets allowing hooks are
7655 @code{install-data}, @code{install-exec}, @code{uninstall}, @code{dist},
7656 and @code{distcheck}.
7657 @trindex install-data-hook
7658 @trindex install-exec-hook
7659 @trindex uninstall-hook
7662 For instance, here is how to create a hard link to an installed program:
7666 ln $(DESTDIR)$(bindir)/program$(EXEEXT) \
7667 $(DESTDIR)$(bindir)/proglink$(EXEEXT)
7670 Although cheaper and more portable than symbolic links, hard links
7671 will not work everywhere (for instance, OS/2 does not have
7672 @command{ln}). Ideally you should fall back to @samp{cp -p} when
7673 @command{ln} does not work. An easy way, if symbolic links are
7674 acceptable to you, is to add @code{AC_PROG_LN_S} to
7675 @file{configure.ac} (@pxref{Particular Programs, , Particular Program
7676 Checks, autoconf, The Autoconf Manual}) and use @samp{$(LN_S)} in
7679 @cindex versioned binaries, installing
7680 @cindex installing versioned binaries
7681 @cindex @code{LN_S} example
7682 For instance, here is how you could install a versioned copy of a
7683 program using @samp{$(LN_S)}:
7687 cd $(DESTDIR)$(bindir) && \
7688 mv -f prog$(EXEEXT) prog-$(VERSION)$(EXEEXT) && \
7689 $(LN_S) prog-$(VERSION)$(EXEEXT) prog$(EXEEXT)
7692 Note that we rename the program so that a new version will erase the
7693 symbolic link, not the real binary. Also we @command{cd} into the
7694 destination directory in order to create relative links.
7696 When writing @code{install-exec-hook} or @code{install-data-hook},
7697 please bear in mind that the exec/data distinction is based on the
7698 installation directory, not on the primary used (@pxref{Install}). So
7699 a @code{foo_SCRIPTS} will be installed by @code{install-data}, and a
7700 @code{barexec_SCRIPTS} will be installed by @code{install-exec}. You
7701 should define your hooks consequently.
7703 @c FIXME should include discussion of variables you can use in these
7706 @node Third-Party Makefiles
7707 @section Third-Party @file{Makefile}s
7709 @cindex Third-party packages, interfacing with
7710 @cindex Interfacing with third-party packages
7712 In most projects all @file{Makefile}s are generated by Automake. In
7713 some cases, however, projects need to embed subdirectories with
7714 handwritten @file{Makefile}s. For instance, one subdirectory could be
7715 a third-party project with its own build system, not using Automake.
7717 It is possible to list arbitrary directories in @code{SUBDIRS} or
7718 @code{DIST_SUBDIRS} provided each of these directories has a
7719 @file{Makefile} that recognizes all the following recursive targets.
7721 @cindex recursive targets and third-party @file{Makefile}s
7722 When a user runs one of these targets, that target is run recursively
7723 in all subdirectories. This is why it is important that even
7724 third-party @file{Makefile}s support them.
7728 Compile the entire package. This is the default target in
7729 Automake-generated @file{Makefile}s, but it does not need to be the
7730 default in third-party @file{Makefile}s.
7736 Copy files to distribute into @samp{$(distdir)}, before a tarball is
7737 constructed. Of course this target is not required if the
7738 @option{no-dist} option (@pxref{Options}) is used.
7740 The variables @samp{$(top_distdir)} and @samp{$(distdir)}
7741 (@pxref{Dist}) will be passed from the outer package to the subpackage
7742 when the @code{distdir} target is invoked. These two variables have
7743 been adjusted for the directory that is being recursed into, so they
7750 Install or uninstall files (@pxref{Install}).
7757 Install only some specific documentation format (@pxref{Texinfo}).
7760 Create install directories, but do not install any files.
7764 Check the package (@pxref{Tests}).
7769 @itemx maintainer-clean
7770 Cleaning rules (@pxref{Clean}).
7777 Build the documentation in various formats (@pxref{Texinfo}).
7781 Build @file{TAGS} and @file{CTAGS} (@pxref{Tags}).
7784 If you have ever used Gettext in a project, this is a good example of
7785 how third-party @file{Makefile}s can be used with Automake. The
7786 @file{Makefile}s @command{gettextize} puts in the @file{po/} and
7787 @file{intl/} directories are handwritten @file{Makefile}s that
7788 implement all these targets. That way they can be added to
7789 @code{SUBDIRS} in Automake packages.
7791 Directories that are only listed in @code{DIST_SUBDIRS} but not in
7792 @code{SUBDIRS} need only the @code{distclean},
7793 @code{maintainer-clean}, and @code{distdir} rules (@pxref{Conditional
7796 Usually, many of these rules are irrelevant to the third-party
7797 subproject, but they are required for the whole package to work. It's
7798 OK to have a rule that does nothing, so if you are integrating a
7799 third-party project with no documentation or tag support, you could
7800 simply augment its @file{Makefile} as follows:
7803 EMPTY_AUTOMAKE_TARGETS = dvi pdf ps info html tags ctags
7804 .PHONY: $(EMPTY_AUTOMAKE_TARGETS)
7805 $(EMPTY_AUTOMAKE_TARGETS):
7808 Another aspect of integrating third-party build systems is whether
7809 they support VPATH builds. Obviously if the subpackage does not
7810 support VPATH builds the whole package will not support VPATH builds.
7811 This in turns means that @samp{make distcheck} will not work, because
7812 it relies on VPATH builds. Some people can live without this
7813 (actually, many Automake users have never heard of @samp{make
7814 distcheck}). Other people may prefer to revamp the existing
7815 @file{Makefile}s to support VPATH@. Doing so does not necessarily
7816 require Automake, only Autoconf is needed (@pxref{Build Directories, ,
7817 Build Directories, autoconf, The Autoconf Manual}). The necessary
7818 substitutions: @samp{@@scrdir@@}, @samp{@@top_srcdir@@}, and
7819 @samp{@@top_builddir@@} are defined by @file{configure} when it
7820 processes a @file{Makefile} (@pxref{Preset Output Variables, , Preset
7821 Output Variables, autoconf, The Autoconf Manual}), they are not
7822 computed by the Makefile like the aforementioned @samp{$(distdir)} and
7823 @samp{$(top_distdir)} variables..
7825 It is sometimes inconvenient to modify a third-party @file{Makefile}
7826 to introduce the above required targets. For instance, one may want to
7827 keep the third-party sources untouched to ease upgrades to new
7830 @cindex @file{GNUmakefile} including @file{Makefile}
7831 Here are two other ideas. If GNU make is assumed, one possibility is
7832 to add to that subdirectory a @file{GNUmakefile} that defines the
7833 required targets and include the third-party @file{Makefile}. For
7834 this to work in VPATH builds, @file{GNUmakefile} must lie in the build
7835 directory; the easiest way to do this is to write a
7836 @file{GNUmakefile.in} instead, and have it processed with
7837 @code{AC_CONFIG_FILES} from the outer package. For example if we
7838 assume @file{Makefile} defines all targets except the documentation
7839 targets, and that the @code{check} target is actually called
7840 @code{test}, we could write @file{GNUmakefile} (or
7841 @file{GNUmakefile.in}) like this:
7844 # First, include the real Makefile
7846 # Then, define the other targets needed by Automake Makefiles.
7847 .PHONY: dvi pdf ps info html check
7848 dvi pdf ps info html:
7852 @cindex Proxy @file{Makefile} for third-party packages
7853 A similar idea that does not use @code{include} is to write a proxy
7854 @file{Makefile} that dispatches rules to the real @file{Makefile},
7855 either with @samp{$(MAKE) -f Makefile.real $(AM_MAKEFLAGS) target} (if
7856 it's OK to rename the original @file{Makefile}) or with @samp{cd
7857 subdir && $(MAKE) $(AM_MAKEFLAGS) target} (if it's OK to store the
7858 subdirectory project one directory deeper). The good news is that
7859 this proxy @file{Makefile} can be generated with Automake. All we
7860 need are @option{-local} targets (@pxref{Extending}) that perform the
7861 dispatch. Of course the other Automake features are available, so you
7862 could decide to let Automake perform distribution or installation.
7863 Here is a possible @file{Makefile.am}:
7867 cd subdir && $(MAKE) $(AM_MAKEFLAGS) all
7869 cd subdir && $(MAKE) $(AM_MAKEFLAGS) test
7871 cd subdir && $(MAKE) $(AM_MAKEFLAGS) clean
7873 # Assuming the package knows how to install itself
7875 cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-data
7877 cd subdir && $(MAKE) $(AM_MAKEFLAGS) install-exec
7879 cd subdir && $(MAKE) $(AM_MAKEFLAGS) uninstall
7881 # Distribute files from here.
7882 EXTRA_DIST = subdir/Makefile subdir/program.c ...
7885 Pushing this idea to the extreme, it is also possible to ignore the
7886 subproject build system and build everything from this proxy
7887 @file{Makefile.am}. This might sounds very sensible if you need VPATH
7888 builds but the subproject does not support them.
7891 @chapter Distributing @file{Makefile.in}s
7893 Automake places no restrictions on the distribution of the resulting
7894 @file{Makefile.in}s. We still encourage software authors to
7895 distribute their work under terms like those of the GPL, but doing so
7896 is not required to use Automake.
7898 Some of the files that can be automatically installed via the
7899 @option{--add-missing} switch do fall under the GPL@. However, these also
7900 have a special exception allowing you to distribute them with your
7901 package, regardless of the licensing you choose.
7904 @node API versioning
7905 @chapter Automake API versioning
7907 New Automake releases usually include bug fixes and new features.
7908 Unfortunately they may also introduce new bugs and incompatibilities.
7909 This makes four reasons why a package may require a particular Automake
7912 Things get worse when maintaining a large tree of packages, each one
7913 requiring a different version of Automake. In the past, this meant that
7914 any developer (and sometime users) had to install several versions of
7915 Automake in different places, and switch @samp{$PATH} appropriately for
7918 Starting with version 1.6, Automake installs versioned binaries. This
7919 means you can install several versions of Automake in the same
7920 @samp{$prefix}, and can select an arbitrary Automake version by running
7921 @command{automake-1.6} or @command{automake-1.7} without juggling with
7922 @samp{$PATH}. Furthermore, @file{Makefile}'s generated by Automake 1.6
7923 will use @command{automake-1.6} explicitly in their rebuild rules.
7925 The number @samp{1.6} in @command{automake-1.6} is Automake's API version,
7926 not Automake's version. If a bug fix release is made, for instance
7927 Automake 1.6.1, the API version will remain 1.6. This means that a
7928 package that works with Automake 1.6 should also work with 1.6.1; after
7929 all, this is what people expect from bug fix releases.
7931 If your package relies on a feature or a bug fix introduced in
7932 a release, you can pass this version as an option to Automake to ensure
7933 older releases will not be used. For instance, use this in your
7934 @file{configure.ac}:
7937 AM_INIT_AUTOMAKE(1.6.1) dnl Require Automake 1.6.1 or better.
7940 or, in a particular @file{Makefile.am}:
7943 AUTOMAKE_OPTIONS = 1.6.1 # Require Automake 1.6.1 or better.
7946 Automake will print an error message if its version is
7947 older than the requested version.
7950 @heading What is in the API
7952 Automake's programming interface is not easy to define. Basically it
7953 should include at least all @strong{documented} variables and targets
7954 that a @file{Makefile.am} author can use, any behavior associated with
7955 them (e.g., the places where @samp{-hook}'s are run), the command line
7956 interface of @command{automake} and @command{aclocal}, @dots{}
7958 @heading What is not in the API
7960 Every undocumented variable, target, or command line option, is not part
7961 of the API@. You should avoid using them, as they could change from one
7962 version to the other (even in bug fix releases, if this helps to fix a
7965 If it turns out you need to use such a undocumented feature, contact
7966 @email{automake@@gnu.org} and try to get it documented and exercised by
7970 @chapter Upgrading a Package to a Newer Automake Version
7972 Automake maintains three kind of files in a package.
7975 @item @file{aclocal.m4}
7976 @item @file{Makefile.in}s
7977 @item auxiliary tools like @file{install-sh} or @file{py-compile}
7980 @file{aclocal.m4} is generated by @command{aclocal} and contains some
7981 Automake-supplied M4 macros. Auxiliary tools are installed by
7982 @samp{automake --add-missing} when needed. @file{Makefile.in}s are
7983 built from @file{Makefile.am} by @command{automake}, and rely on the
7984 definitions of the M4 macros put in @file{aclocal.m4} as well as the
7985 behavior of the auxiliary tools installed.
7987 Because all these files are closely related, it is important to
7988 regenerate all of them when upgrading to a newer Automake release.
7989 The usual way to do that is
7992 aclocal # with any option needed (such a -I m4)
7994 automake --add-missing --force-missing
7998 or more conveniently:
8004 The use of @option{--force-missing} ensures that auxiliary tools will be
8005 overridden by new versions (@pxref{Invoking Automake}).
8007 It is important to regenerate all these files each time Automake is
8008 upgraded, even between bug fixes releases. For instance, it is not
8009 unusual for a bug fix to involve changes to both the rules generated
8010 in @file{Makefile.in} and the supporting M4 macros copied to
8013 Presently @command{automake} is able to diagnose situations where
8014 @file{aclocal.m4} has been generated with another version of
8015 @command{aclocal}. However it never checks whether auxiliary scripts
8016 are up-to-date. In other words, @command{automake} will tell you when
8017 @command{aclocal} needs to be rerun, but it will never diagnose a
8018 missing @option{--force-missing}.
8020 Before upgrading to a new major release, it is a good idea to read the
8021 file @file{NEWS}. This file lists all changes between releases: new
8022 features, obsolete constructs, known incompatibilities, and
8026 @chapter Frequently Asked Questions about Automake
8028 This chapter covers some questions that often come up on the mailing
8032 * CVS:: CVS and generated files
8033 * maintainer-mode:: missing and AM_MAINTAINER_MODE
8034 * wildcards:: Why doesn't Automake support wildcards?
8035 * limitations on file names:: Limitations on source and installed file names
8036 * distcleancheck:: Files left in build directory after distclean
8037 * Flag Variables Ordering:: CFLAGS vs.@: AM_CFLAGS vs.@: mumble_CFLAGS
8038 * renamed objects:: Why are object files sometimes renamed?
8039 * Per-Object Flags:: How to simulate per-object flags?
8040 * Multiple Outputs:: Writing rules for tools with many output files
8041 * Hard-Coded Install Paths:: Installing to Hard-Coded Locations
8045 @section CVS and generated files
8047 @subsection Background: distributed generated files
8048 @cindex generated files, distributed
8049 @cindex rebuild rules
8051 Packages made with Autoconf and Automake ship with some generated
8052 files like @file{configure} or @file{Makefile.in}. These files were
8053 generated on the developer's host and are distributed so that
8054 end-users do not have to install the maintainer tools required to
8055 rebuild them. Other generated files like Lex scanners, Yacc parsers,
8056 or Info documentation, are usually distributed on similar grounds.
8058 Automake outputs rules in @file{Makefile}s to rebuild these files. For
8059 instance, @command{make} will run @command{autoconf} to rebuild
8060 @file{configure} whenever @file{configure.ac} is changed. This makes
8061 development safer by ensuring a @file{configure} is never out-of-date
8062 with respect to @file{configure.ac}.
8064 As generated files shipped in packages are up-to-date, and because
8065 @command{tar} preserves times-tamps, these rebuild rules are not
8066 triggered when a user unpacks and builds a package.
8068 @subsection Background: CVS and timestamps
8069 @cindex timestamps and CVS
8070 @cindex CVS and timestamps
8072 Unless you use CVS keywords (in which case files must be updated at
8073 commit time), CVS preserves timestamp during @samp{cvs commit} and
8074 @samp{cvs import -d} operations.
8076 When you check out a file using @samp{cvs checkout} its timestamp is
8077 set to that of the revision that is being checked out.
8079 However, during @command{cvs update}, files will have the date of the
8080 update, not the original timestamp of this revision. This is meant to
8081 make sure that @command{make} notices sources files have been updated.
8083 This timestamp shift is troublesome when both sources and generated
8084 files are kept under CVS@. Because CVS processes files in alphabetical
8085 order, @file{configure.ac} will appear older than @file{configure}
8086 after a @command{cvs update} that updates both files, even if
8087 @file{configure} was newer than @file{configure.ac} when it was
8088 checked in. Calling @command{make} will then trigger a spurious rebuild
8089 of @file{configure}.
8091 @subsection Living with CVS in Autoconfiscated projects
8092 @cindex CVS and generated files
8093 @cindex generated files and CVS
8095 There are basically two clans amongst maintainers: those who keep all
8096 distributed files under CVS, including generated files, and those who
8097 keep generated files @emph{out} of CVS.
8099 @subsubheading All files in CVS
8103 The CVS repository contains all distributed files so you know exactly
8104 what is distributed, and you can checkout any prior version entirely.
8107 Maintainers can see how generated files evolve (for instance, you can
8108 see what happens to your @file{Makefile.in}s when you upgrade Automake
8109 and make sure they look OK).
8112 Users do not need the autotools to build a checkout of the project, it
8113 works just like a released tarball.
8116 If users use @command{cvs update} to update their copy, instead of
8117 @command{cvs checkout} to fetch a fresh one, timestamps will be
8118 inaccurate. Some rebuild rules will be triggered and attempt to
8119 run developer tools such as @command{autoconf} or @command{automake}.
8121 Actually, calls to such tools are all wrapped into a call to the
8122 @command{missing} script discussed later (@pxref{maintainer-mode}).
8123 @command{missing} will take care of fixing the timestamps when these
8124 tools are not installed, so that the build can continue.
8127 In distributed development, developers are likely to have different
8128 version of the maintainer tools installed. In this case rebuilds
8129 triggered by timestamp lossage will lead to spurious changes
8130 to generated files. There are several solutions to this:
8134 All developers should use the same versions, so that the rebuilt files
8135 are identical to files in CVS@. (This starts to be difficult when each
8136 project you work on uses different versions.)
8138 Or people use a script to fix the timestamp after a checkout (the GCC
8139 folks have such a script).
8141 Or @file{configure.ac} uses @code{AM_MAINTAINER_MODE}, which will
8142 disable all these rebuild rules by default. This is further discussed
8143 in @ref{maintainer-mode}.
8147 Although we focused on spurious rebuilds, the converse can also
8148 happen. CVS's timestamp handling can also let you think an
8149 out-of-date file is up-to-date.
8151 For instance, suppose a developer has modified @file{Makefile.am} and
8152 has rebuilt @file{Makefile.in}. He then decide to do a last-minute
8153 change to @file{Makefile.am} right before checking in both files
8154 (without rebuilding @file{Makefile.in} to account for the change).
8156 This last change to @file{Makefile.am} make the copy of
8157 @file{Makefile.in} out-of-date. Since CVS processes files
8158 alphabetically, when another developer @samp{cvs update} his or her
8159 tree, @file{Makefile.in} will happen to be newer than
8160 @file{Makefile.am}. This other developer will not see
8161 @file{Makefile.in} is out-of-date.
8165 @subsubheading Generated files out of CVS
8167 One way to get CVS and @command{make} working peacefully is to never
8168 store generated files in CVS, i.e., do not CVS-control files that
8169 are @file{Makefile} targets (also called @emph{derived} files).
8171 This way developers are not annoyed by changes to generated files. It
8172 does not matter if they all have different versions (assuming they are
8173 compatible, of course). And finally, timestamps are not lost, changes
8174 to sources files can't be missed as in the
8175 @file{Makefile.am}/@file{Makefile.in} example discussed earlier.
8177 The drawback is that the CVS repository is not an exact copy of what
8178 is distributed and that users now need to install various development
8179 tools (maybe even specific versions) before they can build a checkout.
8180 But, after all, CVS's job is versioning, not distribution.
8182 Allowing developers to use different versions of their tools can also
8183 hide bugs during distributed development. Indeed, developers will be
8184 using (hence testing) their own generated files, instead of the
8185 generated files that will be released actually. The developer who
8186 prepares the tarball might be using a version of the tool that
8187 produces bogus output (for instance a non-portable C file), something
8188 other developers could have noticed if they weren't using their own
8189 versions of this tool.
8191 @subsection Third-party files
8192 @cindex CVS and third-party files
8193 @cindex third-party files and CVS
8195 Another class of files not discussed here (because they do not cause
8196 timestamp issues) are files that are shipped with a package, but
8197 maintained elsewhere. For instance, tools like @command{gettextize}
8198 and @command{autopoint} (from Gettext) or @command{libtoolize} (from
8199 Libtool), will install or update files in your package.
8201 These files, whether they are kept under CVS or not, raise similar
8202 concerns about version mismatch between developers' tools. The
8203 Gettext manual has a section about this, see @ref{CVS Issues, CVS
8204 Issues, Integrating with CVS, gettext, GNU gettext tools}.
8206 @node maintainer-mode
8207 @section @command{missing} and @code{AM_MAINTAINER_MODE}
8209 @subsection @command{missing}
8210 @cindex @command{missing}, purpose
8212 The @command{missing} script is a wrapper around several maintainer
8213 tools, designed to warn users if a maintainer tool is required but
8214 missing. Typical maintainer tools are @command{autoconf},
8215 @command{automake}, @command{bison}, etc. Because file generated by
8216 these tools are shipped with the other sources of a package, these
8217 tools shouldn't be required during a user build and they are not
8218 checked for in @file{configure}.
8220 However, if for some reason a rebuild rule is triggered and involves a
8221 missing tool, @command{missing} will notice it and warn the user.
8222 Besides the warning, when a tool is missing, @command{missing} will
8223 attempt to fix timestamps in a way that allows the build to continue.
8224 For instance, @command{missing} will touch @file{configure} if
8225 @command{autoconf} is not installed. When all distributed files are
8226 kept under CVS, this feature of @command{missing} allows user
8227 @emph{with no maintainer tools} to build a package off CVS, bypassing
8228 any timestamp inconsistency implied by @samp{cvs update}.
8230 If the required tool is installed, @command{missing} will run it and
8231 won't attempt to continue after failures. This is correct during
8232 development: developers love fixing failures. However, users with
8233 wrong versions of maintainer tools may get an error when the rebuild
8234 rule is spuriously triggered, halting the build. This failure to let
8235 the build continue is one of the arguments of the
8236 @code{AM_MAINTAINER_MODE} advocates.
8238 @subsection @code{AM_MAINTAINER_MODE}
8239 @cindex @code{AM_MAINTAINER_MODE}, purpose
8240 @acindex AM_MAINTAINER_MODE
8242 @code{AM_MAINTAINER_MODE} disables the so called "rebuild rules" by
8243 default. If you have @code{AM_MAINTAINER_MODE} in
8244 @file{configure.ac}, and run @samp{./configure && make}, then
8245 @command{make} will *never* attempt to rebuilt @file{configure},
8246 @file{Makefile.in}s, Lex or Yacc outputs, etc. I.e., this disables
8247 build rules for files that are usually distributed and that users
8248 should normally not have to update.
8250 If you run @samp{./configure --enable-maintainer-mode}, then these
8251 rebuild rules will be active.
8253 People use @code{AM_MAINTAINER_MODE} either because they do want their
8254 users (or themselves) annoyed by timestamps lossage (@pxref{CVS}), or
8255 because they simply can't stand the rebuild rules and prefer running
8256 maintainer tools explicitly.
8258 @code{AM_MAINTAINER_MODE} also allows you to disable some custom build
8259 rules conditionally. Some developers use this feature to disable
8260 rules that need exotic tools that users may not have available.
8262 Several years ago Fran@,{c}ois Pinard pointed out several arguments
8263 against this @code{AM_MAINTAINER_MODE} macro. Most of them relate to
8264 insecurity. By removing dependencies you get non-dependable builds:
8265 change to sources files can have no effect on generated files and this
8266 can be very confusing when unnoticed. He adds that security shouldn't
8267 be reserved to maintainers (what @option{--enable-maintainer-mode}
8268 suggests), on the contrary. If one user has to modify a
8269 @file{Makefile.am}, then either @file{Makefile.in} should be updated
8270 or a warning should be output (this is what Automake uses
8271 @command{missing} for) but the last thing you want is that nothing
8272 happens and the user doesn't notice it (this is what happens when
8273 rebuild rules are disabled by @code{AM_MAINTAINER_MODE}).
8275 Jim Meyering, the inventor of the @code{AM_MAINTAINER_MODE} macro was
8276 swayed by Fran@,{c}ois's arguments, and got rid of
8277 @code{AM_MAINTAINER_MODE} in all of his packages.
8279 Still many people continue to use @code{AM_MAINTAINER_MODE}, because
8280 it helps them working on projects where all files are kept under CVS,
8281 and because @command{missing} isn't enough if you have the wrong
8282 version of the tools.
8286 @section Why doesn't Automake support wildcards?
8289 Developers are lazy. They often would like to use wildcards in
8290 @file{Makefile.am}s, so they don't need to remember they have to
8291 update @file{Makefile.am}s every time they add, delete, or rename a
8294 There are several objections to this:
8297 When using CVS (or similar) developers need to remember they have to
8298 run @samp{cvs add} or @samp{cvs rm} anyway. Updating
8299 @file{Makefile.am} accordingly quickly becomes a reflex.
8301 Conversely, if your application doesn't compile
8302 because you forgot to add a file in @file{Makefile.am}, it will help
8303 you remember to @samp{cvs add} it.
8306 Using wildcards makes easy to distribute files by mistake. For
8307 instance, some code a developer is experimenting with (a test case,
8308 say) but that should not be part of the distribution.
8311 Using wildcards it's easy to omit some files by mistake. For
8312 instance, one developer creates a new file, uses it at many places,
8313 but forget to commit it. Another developer then checkout the
8314 incomplete project and is able to run `make dist' successfully,
8315 even though a file is missing.
8318 Listing files, you control *exactly* what you distribute.
8319 If some file that should be distributed is missing from your
8320 tree, @samp{make dist} will complain. Besides, you don't distribute
8321 more than what you listed.
8324 Finally it's really hard to @file{forget} adding a file to
8325 @file{Makefile.am}, because if you don't add it, it doesn't get
8326 compiled nor installed, so you can't even test it.
8329 Still, these are philosophical objections, and as such you may disagree,
8330 or find enough value in wildcards to dismiss all of them. Before you
8331 start writing a patch against Automake to teach it about wildcards,
8332 let's see the main technical issue: portability.
8334 Although @samp{$(wildcard ...)} works with GNU @command{make}, it is
8335 not portable to other @command{make} implementations.
8337 The only way Automake could support @command{$(wildcard ...)} is by
8338 expending @command{$(wildcard ...)} when @command{automake} is run.
8339 Resulting @file{Makefile.in}s would be portable since they would
8340 list all files and not use @samp{$(wildcard ...)}. However that
8341 means developers need to remember they must run @command{automake} each
8342 time they add, delete, or rename files.
8344 Compared to editing @file{Makefile.am}, this is really little win. Sure,
8345 it's easier and faster to type @samp{automake; make} than to type
8346 @samp{emacs Makefile.am; make}. But nobody bothered enough to write a
8347 patch add support for this syntax. Some people use scripts to
8348 generated file lists in @file{Makefile.am} or in separate
8349 @file{Makefile} fragments.
8351 Even if you don't care about portability, and are tempted to use
8352 @samp{$(wildcard ...)} anyway because you target only GNU Make, you
8353 should know there are many places where Automake need to know exactly
8354 which files should be processed. As Automake doesn't know how to
8355 expand @samp{$(wildcard ...)}, you cannot use it in these places.
8356 @samp{$(wildcard ...)} is a black box comparable to @code{AC_SUBST}ed
8357 variables as far Automake is concerned.
8359 You can get warnings about @samp{$(wildcard ...}) constructs using the
8360 @option{-Wportability} flag.
8362 @node limitations on file names
8363 @section Limitations on file names
8364 @cindex file names, limitations on
8366 Automake attempts to support all kinds of file names, even those that
8367 contain unusual characters or are unusually long. However, some
8368 limitations are imposed by the underlying operating system and tools.
8370 Most operating systems prohibit the use of the null byte in file
8371 names, and reserve @samp{/} as a directory separator. Also, they
8372 require that file names are properly encoded for the user's locale.
8373 Automake is subject to these limits.
8375 Portable packages should limit themselves to @acronym{POSIX} file
8376 names. These can contain @acronym{ASCII} letters and digits,
8377 @samp{_}, @samp{.}, and @samp{-}. File names consist of components
8378 separated by @samp{/}. File name components cannot begin with
8381 Portable POSIX file names cannot contain components that exceed a
8382 14-byte limit, but nowadays it's normally safe to assume the
8383 more-generous @acronym{XOPEN} limit of 255 bytes. @acronym{POSIX}
8384 limits file names to 255 bytes (@acronym{XOPEN} allows 1023 bytes),
8385 but you may want to limit a source tarball to file names to 99 bytes
8386 to avoid interoperability problems with old versions of @command{tar}.
8388 If you depart from these rules (e.g., by using non-@acronym{ASCII}
8389 characters in file names, or by using lengthy file names), your
8390 installers may have problems for reasons unrelated to Automake.
8391 However, if this does not concern you, you should know about the
8392 limitations imposed by Automake itself. These limitations are
8393 undesirable, but some of them seem to be inherent to underlying tools
8394 like Autoconf, Make, M4, and the shell. They fall into three
8395 categories: install directories, build directories, and file names.
8397 The following characters:
8400 @r{newline} " # $ ' `
8403 should not appear in the names of install directories. For example,
8404 the operand of @command{configure}'s @option{--prefix} option should
8405 not contain these characters.
8407 Build directories suffer the same limitations as install directories,
8408 and in addition should not contain the following characters:
8414 For example, the full name of the directory containing the source
8415 files should not contain these characters.
8417 Source and installation file names like @file{main.c} are limited even
8418 further: they should conform to the @acronym{POSIX}/@acronym{XOPEN}
8419 rules described above. In addition, if you plan to port to
8420 non-@acronym{POSIX} environments, you should avoid file names that
8421 differ only in case (e.g., @file{makefile} and @file{Makefile}).
8422 Nowadays it is no longer worth worrying about the 8.3 limits of
8423 @acronym{DOS} file systems.
8425 @node distcleancheck
8426 @section Files left in build directory after distclean
8427 @cindex @code{distclean}, diagnostic
8428 @cindex @samp{make distclean}, diagnostic
8429 @cindex dependencies and distributed files
8431 @trindex distcleancheck
8433 This is a diagnostic you might encounter while running @samp{make
8436 As explained in @ref{Dist}, @samp{make distcheck} attempts to build
8437 and check your package for errors like this one.
8439 @samp{make distcheck} will perform a @code{VPATH} build of your
8440 package, and then call @samp{make distclean}. Files left in the build
8441 directory after @samp{make distclean} has run are listed after this
8444 This diagnostic really covers two kinds of errors:
8448 files that are forgotten by distclean;
8450 distributed files that are erroneously rebuilt.
8453 The former left-over files are not distributed, so the fix is to mark
8454 them for cleaning (@pxref{Clean}), this is obvious and doesn't deserve
8457 The latter bug is not always easy to understand and fix, so let's
8458 proceed with an example. Suppose our package contains a program for
8459 which we want to build a man page using @command{help2man}. GNU
8460 @command{help2man} produces simple manual pages from the @option{--help}
8461 and @option{--version} output of other commands (@pxref{Top, , Overview,
8462 help2man, The Help2man Manual}). Because we don't to force want our
8463 users to install @command{help2man}, we decide to distribute the
8464 generated man page using the following setup.
8467 # This Makefile.am is bogus.
8470 dist_man_MANS = foo.1
8473 help2man --output=foo.1 ./foo$(EXEEXT)
8476 This will effectively distribute the man page. However,
8477 @samp{make distcheck} will fail with:
8480 ERROR: files left in build directory after distclean:
8484 Why was @file{foo.1} rebuilt? Because although distributed,
8485 @file{foo.1} depends on a non-distributed built file:
8486 @file{foo$(EXEEXT)}. @file{foo$(EXEEXT)} is built by the user, so it
8487 will always appear to be newer than the distributed @file{foo.1}.
8489 @samp{make distcheck} caught an inconsistency in our package. Our
8490 intent was to distribute @file{foo.1} so users do not need installing
8491 @command{help2man}, however since this our rule causes this file to be
8492 always rebuilt, users @emph{do} need @command{help2man}. Either we
8493 should ensure that @file{foo.1} is not rebuilt by users, or there is
8494 no point in distributing @file{foo.1}.
8496 More generally, the rule is that distributed files should never depend
8497 on non-distributed built files. If you distribute something
8498 generated, distribute its sources.
8500 One way to fix the above example, while still distributing
8501 @file{foo.1} is to not depend on @file{foo$(EXEEXT)}. For instance,
8502 assuming @command{foo --version} and @command{foo --help} do not
8503 change unless @file{foo.c} or @file{configure.ac} change, we could
8504 write the following @file{Makefile.am}:
8509 dist_man_MANS = foo.1
8511 foo.1: foo.c $(top_srcdir)/configure.ac
8512 $(MAKE) $(AM_MAKEFLAGS) foo$(EXEEXT)
8513 help2man --output=foo.1 ./foo$(EXEEXT)
8516 This way, @file{foo.1} will not get rebuilt every time
8517 @file{foo$(EXEEXT)} changes. The @command{make} call makes sure
8518 @file{foo$(EXEEXT)} is up-to-date before @command{help2man}. Another
8519 way to ensure this would be to use separate directories for binaries
8520 and man pages, and set @code{SUBDIRS} so that binaries are built
8523 We could also decide not to distribute @file{foo.1}. In
8524 this case it's fine to have @file{foo.1} dependent upon
8525 @file{foo$(EXEEXT)}, since both will have to be rebuilt.
8526 However it would be impossible to build the package in a
8527 cross-compilation, because building @file{foo.1} involves
8528 an @emph{execution} of @file{foo$(EXEEXT)}.
8530 Another context where such errors are common is when distributed files
8531 are built by tools that are built by the package. The pattern is
8535 distributed-file: built-tools distributed-sources
8540 should be changed to
8543 distributed-file: distributed-sources
8544 $(MAKE) $(AM_MAKEFLAGS) built-tools
8549 or you could choose not to distribute @file{distributed-file}, if
8550 cross-compilation does not matter.
8552 The points made through these examples are worth a summary:
8557 Distributed files should never depend upon non-distributed built
8560 Distributed files should be distributed will all their dependencies.
8562 If a file is @emph{intended} be rebuilt by users, there is no point in
8567 @vrindex distcleancheck_listfiles
8568 For desperate cases, it's always possible to disable this check by
8569 setting @code{distcleancheck_listfiles} as documented in @ref{Dist}.
8570 Make sure you do understand the reason why @samp{make distcheck}
8571 complains before you do this. @code{distcleancheck_listfiles} is a
8572 way to @emph{hide} errors, not to fix them. You can always do better.
8574 @node Flag Variables Ordering
8575 @section Flag Variables Ordering
8576 @cindex Ordering flag variables
8577 @cindex Flag variables, ordering
8580 What is the difference between @code{AM_CFLAGS}, @code{CFLAGS}, and
8581 @code{mumble_CFLAGS}?
8585 Why does @command{automake} output @code{CPPFLAGS} after
8586 @code{AM_CPPFLAGS} on compile lines? Shouldn't it be the converse?
8590 My @file{configure} adds some warning flags into @code{CXXFLAGS}. In
8591 one @file{Makefile.am} I would like to append a new flag, however if I
8592 put the flag into @code{AM_CXXFLAGS} it is prepended to the other
8593 flags, not appended.
8596 @subsection Compile Flag Variables
8597 @cindex Flag Variables, Ordering
8598 @cindex Compile Flag Variables
8599 @cindex @code{AM_CCASFLAGS} and @code{CCASFLAGS}
8600 @cindex @code{AM_CFLAGS} and @code{CFLAGS}
8601 @cindex @code{AM_CPPFLAGS} and @code{CPPFLAGS}
8602 @cindex @code{AM_CXXFLAGS} and @code{CXXFLAGS}
8603 @cindex @code{AM_FCFLAGS} and @code{FCFLAGS}
8604 @cindex @code{AM_FFLAGS} and @code{FFLAGS}
8605 @cindex @code{AM_GCJFLAGS} and @code{GCJFLAGS}
8606 @cindex @code{AM_LDFLAGS} and @code{LDFLAGS}
8607 @cindex @code{AM_LFLAGS} and @code{LFLAGS}
8608 @cindex @code{AM_LIBTOOLFLAGS} and @code{LIBTOOLFLAGS}
8609 @cindex @code{AM_OBJCFLAGS} and @code{OBJCFLAGS}
8610 @cindex @code{AM_RFLAGS} and @code{RFLAGS}
8611 @cindex @code{AM_YFLAGS} and @code{YFLAGS}
8612 @cindex @code{CCASFLAGS} and @code{AM_CCASFLAGS}
8613 @cindex @code{CFLAGS} and @code{AM_CFLAGS}
8614 @cindex @code{CPPFLAGS} and @code{AM_CPPFLAGS}
8615 @cindex @code{CXXFLAGS} and @code{AM_CXXFLAGS}
8616 @cindex @code{FCFLAGS} and @code{AM_FCFLAGS}
8617 @cindex @code{FFLAGS} and @code{AM_FFLAGS}
8618 @cindex @code{GCJFLAGS} and @code{AM_GCJFLAGS}
8619 @cindex @code{LDFLAGS} and @code{AM_LDFLAGS}
8620 @cindex @code{LFLAGS} and @code{AM_LFLAGS}
8621 @cindex @code{LIBTOOLFLAGS} and @code{AM_LIBTOOLFLAGS}
8622 @cindex @code{OBJCFLAGS} and @code{AM_OBJCFLAGS}
8623 @cindex @code{RFLAGS} and @code{AM_RFLAGS}
8624 @cindex @code{YFLAGS} and @code{AM_YFLAGS}
8626 This section attempts to answer all the above questions. We will
8627 mostly discuss @code{CPPFLAGS} in our examples, but actually the
8628 answer holds for all the compile flags used in Automake:
8629 @code{CCASFLAGS}, @code{CFLAGS}, @code{CPPFLAGS}, @code{CXXFLAGS},
8630 @code{FCFLAGS}, @code{FFLAGS}, @code{GCJFLAGS}, @code{LDFLAGS},
8631 @code{LFLAGS}, @code{LIBTOOLFLAGS}, @code{OBJCFLAGS}, @code{RFLAGS},
8634 @code{CPPFLAGS}, @code{AM_CPPFLAGS}, and @code{mumble_CPPFLAGS} are
8635 three variables that can be used to pass flags to the C preprocessor
8636 (actually these variables are also used for other languages like C++
8637 or preprocessed Fortran). @code{CPPFLAGS} is the user variable
8638 (@pxref{User Variables}), @code{AM_CPPFLAGS} is the Automake variable,
8639 and @code{mumble_CPPFLAGS} is the variable specific to the
8640 @code{mumble} target (we call this a per-target variable,
8641 @pxref{Program and Library Variables}).
8643 Automake always uses two of these variables when compiling C sources
8644 files. When compiling an object file for the @code{mumble} target,
8645 the first variable will be @code{mumble_CPPFLAGS} if it is defined, or
8646 @code{AM_CPPFLAGS} otherwise. The second variable is always
8649 In the following example,
8652 bin_PROGRAMS = foo bar
8654 bar_SOURCES = main.c
8655 foo_CPPFLAGS = -DFOO
8660 @file{xyz.o} will be compiled with @samp{$(foo_CPPFLAGS) $(CPPFLAGS)},
8661 (because @file{xyz.o} is part of the @code{foo} target), while
8662 @file{main.o} will be compiled with @samp{$(AM_CPPFLAGS) $(CPPFLAGS)}
8663 (because there is no per-target variable for target @code{bar}).
8665 The difference between @code{mumble_CPPFLAGS} and @code{AM_CPPFLAGS}
8666 being clear enough, let's focus on @code{CPPFLAGS}. @code{CPPFLAGS}
8667 is a user variable, i.e., a variable that users are entitled to modify
8668 in order to compile the package. This variable, like many others,
8669 is documented at the end of the output of @samp{configure --help}.
8671 For instance, someone who needs to add @file{/home/my/usr/include} to
8672 the C compiler's search path would configure a package with
8675 ./configure CPPFLAGS='-I /home/my/usr/include'
8679 and this flag would be propagated to the compile rules of all
8682 It is also not uncommon to override a user variable at
8683 @command{make}-time. Many installers do this with @code{prefix}, but
8684 this can be useful with compiler flags too. For instance, if, while
8685 debugging a C++ project, you need to disable optimization in one
8686 specific object file, you can run something like
8690 make CXXFLAGS=-O0 file.o
8694 The reason @samp{$(CPPFLAGS)} appears after @samp{$(AM_CPPFLAGS)} or
8695 @samp{$(mumble_CPPFLAGS)} in the compile command is that users
8696 should always have the last say. It probably makes more sense if you
8697 think about it while looking at the @samp{CXXFLAGS=-O0} above, which
8698 should supersede any other switch from @code{AM_CXXFLAGS} or
8699 @code{mumble_CXXFLAGS} (and this of course replaces the previous value
8700 of @code{CXXFLAGS}).
8702 You should never redefine a user variable such as @code{CPPFLAGS} in
8703 @file{Makefile.am}. Use @samp{automake -Woverride} to diagnose such
8704 mistakes. Even something like
8707 CPPFLAGS = -DDATADIR=\"$(datadir)\" @@CPPFLAGS@@
8711 is erroneous. Although this preserves @file{configure}'s value of
8712 @code{CPPFLAGS}, the definition of @code{DATADIR} will disappear if a
8713 user attempts to override @code{CPPFLAGS} from the @command{make}
8717 AM_CPPFLAGS = -DDATADIR=\"$(datadir)\"
8721 is all what is needed here if no per-target flags are used.
8723 You should not add options to these user variables within
8724 @file{configure} either, for the same reason. Occasionally you need
8725 to modify these variables to perform a test, but you should reset
8726 their values afterwards. In contrast, it is OK to modify the
8727 @samp{AM_} variables within @file{configure} if you @code{AC_SUBST}
8728 them, but it is rather rare that you need to do this, unless you
8729 really want to change the default definitions of the @samp{AM_}
8730 variables in all @file{Makefile}s.
8732 What we recommend is that you define extra flags in separate
8733 variables. For instance, you may write an Autoconf macro that computes
8734 a set of warning options for the C compiler, and @code{AC_SUBST} them
8735 in @code{WARNINGCFLAGS}; you may also have an Autoconf macro that
8736 determines which compiler and which linker flags should be used to
8737 link with library @file{libfoo}, and @code{AC_SUBST} these in
8738 @code{LIBFOOCFLAGS} and @code{LIBFOOLDFLAGS}. Then, a
8739 @file{Makefile.am} could use these variables as follows:
8742 AM_CFLAGS = $(WARNINGCFLAGS)
8743 bin_PROGRAMS = prog1 prog2
8744 prog1_SOURCES = @dots{}
8745 prog2_SOURCES = @dots{}
8746 prog2_CFLAGS = $(LIBFOOCFLAGS) $(AM_CFLAGS)
8747 prog2_LDFLAGS = $(LIBFOOLDFLAGS)
8750 In this example both programs will be compiled with the flags
8751 substituted into @samp{$(WARNINGCFLAGS)}, and @code{prog2} will
8752 additionally be compiled with the flags required to link with
8755 Note that listing @code{AM_CFLAGS} in a per-target @code{CFLAGS}
8756 variable is a common idiom to ensure that @code{AM_CFLAGS} applies to
8757 every target in a @file{Makefile.in}.
8759 Using variables like this gives you full control over the ordering of
8760 the flags. For instance, if there is a flag in $(WARNINGCFLAGS) that
8761 you want to negate for a particular target, you can use something like
8762 @samp{prog1_CFLAGS = $(AM_CFLAGS) -no-flag}. If all these flags had
8763 been forcefully appended to @code{CFLAGS}, there would be no way to
8764 disable one flag. Yet another reason to leave user variables to
8767 Finally, we have avoided naming the variable of the example
8768 @code{LIBFOO_LDFLAGS} (with an underscore) because that would cause
8769 Automake to think that this is actually a per-target variable (like
8770 @code{mumble_LDFLAGS}) for some non-declared @code{LIBFOO} target.
8772 @subsection Other Variables
8774 There are other variables in Automake that follow similar principles
8775 to allow user options. For instance, Texinfo rules (@pxref{Texinfo})
8776 use @code{MAKEINFOFLAGS} and @code{AM_MAKEINFOFLAGS}. Similarly,
8777 DejaGnu tests (@pxref{Tests}) use @code{RUNTESTDEFAULTFLAGS} and
8778 @code{AM_RUNTESTDEFAULTFLAGS}. The tags and ctags rules
8779 (@pxref{Tags}) use @code{ETAGSFLAGS}, @code{AM_ETAGSFLAGS},
8780 @code{CTAGSFLAGS}, and @code{AM_CTAGSFLAGS}. Java rules
8781 (@pxref{Java}) use @code{JAVACFLAGS} and @code{AM_JAVACFLAGS}. None
8782 of these rules do support per-target flags (yet).
8784 To some extent, even @code{AM_MAKEFLAGS} (@pxref{Subdirectories})
8785 obeys this naming scheme. The slight difference is that
8786 @code{MAKEFLAGS} is passed to sub-@command{make}s implicitly by
8787 @command{make} itself.
8789 However you should not think that all variables ending with
8790 @code{FLAGS} follow this convention. For instance,
8791 @code{DISTCHECK_CONFIGURE_FLAGS} (@pxref{Dist}),
8792 @code{ACLOCAL_AMFLAGS} (see @ref{Rebuilding} and @ref{Local Macros}),
8793 are two variables that are only useful to the maintainer and have no
8796 @code{ARFLAGS} (@pxref{A Library}) is usually defined by Automake and
8797 has neither @code{AM_} nor per-target cousin.
8799 Finally you should not think either that the existence of a per-target
8800 variable implies that of an @code{AM_} variable or that of a user
8801 variable. For instance, the @code{mumble_LDADD} per-target variable
8802 overrides the global @code{LDADD} variable (which is not a user
8803 variable), and @code{mumble_LIBADD} exists only as a per-target
8804 variable. @xref{Program and Library Variables}.
8807 @node renamed objects
8808 @section Why are object files sometimes renamed?
8810 This happens when per-target compilation flags are used. Object
8811 files need to be renamed just in case they would clash with object
8812 files compiled from the same sources, but with different flags.
8813 Consider the following example.
8816 bin_PROGRAMS = true false
8817 true_SOURCES = generic.c
8818 true_CPPFLAGS = -DEXIT_CODE=0
8819 false_SOURCES = generic.c
8820 false_CPPFLAGS = -DEXIT_CODE=1
8823 Obviously the two programs are built from the same source, but it
8824 would be bad if they shared the same object, because @file{generic.o}
8825 cannot be built with both @samp{-DEXIT_CODE=0} @emph{and}
8826 @samp{-DEXIT_CODE=1}. Therefore @command{automake} outputs rules to
8827 build two different objects: @file{true-generic.o} and
8828 @file{false-generic.o}.
8830 @command{automake} doesn't actually look whether source files are
8831 shared to decide if it must rename objects. It will just rename all
8832 objects of a target as soon as it sees per-target compilation flags
8835 It's OK to share object files when per-target compilation flags are not
8836 used. For instance, @file{true} and @file{false} will both use
8837 @file{version.o} in the following example.
8840 AM_CPPFLAGS = -DVERSION=1.0
8841 bin_PROGRAMS = true false
8842 true_SOURCES = true.c version.c
8843 false_SOURCES = false.c version.c
8846 Note that the renaming of objects is also affected by the
8847 @code{_SHORTNAME} variable (@pxref{Program and Library Variables}).
8850 @node Per-Object Flags
8851 @section Per-Object Flags Emulation
8852 @cindex Per-object flags, emulated
8855 One of my source files needs to be compiled with different flags. How
8859 Automake supports per-program and per-library compilation flags (see
8860 @ref{Program and Library Variables} and @ref{Flag Variables
8861 Ordering}). With this you can define compilation flags that apply to
8862 all files compiled for a target. For instance, in
8866 foo_SOURCES = foo.c foo.h bar.c bar.h main.c
8867 foo_CFLAGS = -some -flags
8871 @file{foo-foo.o}, @file{foo-bar.o}, and @file{foo-main.o} will all be
8872 compiled with @samp{-some -flags}. (If you wonder about the names of
8873 these object files, see @ref{renamed objects}.) Note that
8874 @code{foo_CFLAGS} gives the flags to use when compiling all the C
8875 sources of the @emph{program} @code{foo}, it has nothing to do with
8876 @file{foo.c} or @file{foo-foo.o} specifically.
8878 What if @file{foo.c} needs to be compiled into @file{foo.o} using some
8879 specific flags, that none of the other files require? Obviously
8880 per-program flags are not directly applicable here. Something like
8881 per-object flags are expected, i.e., flags that would be used only
8882 when creating @file{foo-foo.o}. Automake does not support that,
8883 however this is easy to simulate using a library that contains only
8884 that object, and compiling this library with per-library flags.
8888 foo_SOURCES = bar.c bar.h main.c
8889 foo_CFLAGS = -some -flags
8890 foo_LDADD = libfoo.a
8891 noinst_LIBRARIES = libfoo.a
8892 libfoo_a_SOURCES = foo.c foo.h
8893 libfoo_a_CFLAGS = -some -other -flags
8896 Here @file{foo-bar.o} and @file{foo-main.o} will all be
8897 compiled with @samp{-some -flags}, while @file{libfoo_a-foo.o} will
8898 be compiled using @samp{-some -other -flags}. Eventually, all
8899 three objects will be linked to form @file{foo}.
8901 This trick can also be achieved using Libtool convenience libraries,
8902 for instance @samp{noinst_LTLIBRARIES = libfoo.la} (@pxref{Libtool
8903 Convenience Libraries}).
8905 Another tempting idea to implement per-object flags is to override the
8906 compile rules @command{automake} would output for these files.
8907 Automake will not define a rule for a target you have defined, so you
8908 could think about defining the @samp{foo-foo.o: foo.c} rule yourself.
8909 We recommend against this, because this is error prone. For instance,
8910 if you add such a rule to the first example, it will break the day you
8911 decide to remove @code{foo_CFLAGS} (because @file{foo.c} will then be
8912 compiled as @file{foo.o} instead of @file{foo-foo.o}, @pxref{renamed
8913 objects}). Also in order to support dependency tracking, the two
8914 @file{.o}/@file{.obj} extensions, and all the other flags variables
8915 involved in a compilation, you will end up modifying a copy of the
8916 rule previously output by @command{automake} for this file. If a new
8917 release of Automake generates a different rule, your copy will need to
8920 @node Multiple Outputs
8921 @section Handling Tools that Produce Many Outputs
8922 @cindex multiple outputs, rules with
8923 @cindex many outputs, rules with
8924 @cindex rules with multiple outputs
8926 This section describes a @command{make} idiom that can be used when a
8927 tool produces multiple output files. It is not specific to Automake
8928 and can be used in ordinary @file{Makefile}s.
8930 Suppose we have a program called @command{foo} that will read one file
8931 called @file{data.foo} and produce two files named @file{data.c} and
8932 @file{data.h}. We want to write a @file{Makefile} rule that captures
8933 this one-to-two dependency.
8935 The naive rule is incorrect:
8938 # This is incorrect.
8939 data.c data.h: data.foo
8944 What the above rule really says is that @file{data.c} and
8945 @file{data.h} each depend on @file{data.foo}, and can each be built by
8946 running @samp{foo data.foo}. In other words it is equivalent to:
8949 # We do not want this.
8957 which means that @command{foo} can be run twice. Usually it will not
8958 be run twice, because @command{make} implementations are smart enough
8959 to check for the existence of the second file after the first one has
8960 been built; they will therefore detect that it already exists.
8961 However there are a few situations where it can run twice anyway:
8965 The most worrying case is when running a parallel @command{make}. If
8966 @file{data.c} and @file{data.h} are built in parallel, two @samp{foo
8967 data.foo} commands will run concurrently. This is harmful.
8969 Another case is when the dependency (here @file{data.foo}) is
8970 (or depends upon) a phony target.
8973 A solution that works with parallel @command{make} but not with
8974 phony dependencies is the following:
8977 data.c data.h: data.foo
8983 The above rules are equivalent to
8988 data.h: data.foo data.c
8992 therefore a parallel @command{make} will have to serialize the builds
8993 of @file{data.c} and @file{data.h}, and will detect that the second is
8994 no longer needed once the first is over.
8996 Using this pattern is probably enough for most cases. However it does
8997 not scale easily to more output files (in this scheme all output files
8998 must be totally ordered by the dependency relation), so we will
8999 explore a more complicated solution.
9001 Another idea is to write the following:
9004 # There is still a problem with this one.
9011 The idea is that @samp{foo data.foo} is run only when @file{data.c}
9012 needs to be updated, but we further state that @file{data.h} depends
9013 upon @file{data.c}. That way, if @file{data.h} is required and
9014 @file{data.foo} is out of date, the dependency on @file{data.c} will
9017 This is almost perfect, but suppose we have built @file{data.h} and
9018 @file{data.c}, and then we erase @file{data.h}. Then, running
9019 @samp{make data.h} will not rebuild @file{data.h}. The above rules
9020 just state that @file{data.c} must be up-to-date with respect to
9021 @file{data.foo}, and this is already the case.
9023 What we need is a rule that forces a rebuild when @file{data.h} is
9024 missing. Here it is:
9030 ## Recover from the removal of $@@
9031 @@if test -f $@@; then :; else \
9033 $(MAKE) $(AM_MAKEFLAGS) data.c; \
9037 The above scheme can be extended to handle more outputs and more
9038 inputs. One of the outputs is selected to serve as a witness to the
9039 successful completion of the command, it depends upon all inputs, and
9040 all other outputs depend upon it. For instance, if @command{foo}
9041 should additionally read @file{data.bar} and also produce
9042 @file{data.w} and @file{data.x}, we would write:
9045 data.c: data.foo data.bar
9046 foo data.foo data.bar
9047 data.h data.w data.x: data.c
9048 ## Recover from the removal of $@@
9049 @@if test -f $@@; then :; else \
9051 $(MAKE) $(AM_MAKEFLAGS) data.c; \
9055 However there are now two minor problems in this setup. One is related
9056 to the timestamp ordering of @file{data.h}, @file{data.w},
9057 @file{data.x}, and @file{data.c}. The other one is a race condition
9058 if a parallel @command{make} attempts to run multiple instances of the
9059 recover block at once.
9061 Let us deal with the first problem. @command{foo} outputs four files,
9062 but we do not know in which order these files are created. Suppose
9063 that @file{data.h} is created before @file{data.c}. Then we have a
9064 weird situation. The next time @command{make} is run, @file{data.h}
9065 will appear older than @file{data.c}, the second rule will be
9066 triggered, a shell will be started to execute the @samp{if@dots{}fi}
9067 command, but actually it will just execute the @code{then} branch,
9068 that is: nothing. In other words, because the witness we selected is
9069 not the first file created by @command{foo}, @command{make} will start
9070 a shell to do nothing each time it is run.
9072 A simple riposte is to fix the timestamps when this happens.
9075 data.c: data.foo data.bar
9076 foo data.foo data.bar
9077 data.h data.w data.x: data.c
9078 @@if test -f $@@; then \
9081 ## Recover from the removal of $@@
9083 $(MAKE) $(AM_MAKEFLAGS) data.c; \
9087 Another solution is to use a different and dedicated file as witness,
9088 rather than using any of @command{foo}'s outputs.
9091 data.stamp: data.foo data.bar
9094 foo data.foo data.bar
9095 @@mv -f data.tmp $@@
9096 data.c data.h data.w data.x: data.stamp
9097 ## Recover from the removal of $@@
9098 @@if test -f $@@; then :; else \
9100 $(MAKE) $(AM_MAKEFLAGS) data.stamp; \
9104 @file{data.tmp} is created before @command{foo} is run, so it has a
9105 timestamp older than output files output by @command{foo}. It is then
9106 renamed to @file{data.stamp} after @command{foo} has run, because we
9107 do not want to update @file{data.stamp} if @command{foo} fails.
9109 This solution still suffers from the second problem: the race
9110 condition in the recover rule. If, after a successful build, a user
9111 erases @file{data.c} and @file{data.h}, and runs @samp{make -j}, then
9112 @command{make} may start both recover rules in parallel. If the two
9113 instances of the rule execute @samp{$(MAKE) $(AM_MAKEFLAGS)
9114 data.stamp} concurrently the build is likely to fail (for instance, the
9115 two rules will create @file{data.tmp}, but only one can rename it).
9117 Admittedly, such a weird situation does not arise during ordinary
9118 builds. It occurs only when the build tree is mutilated. Here
9119 @file{data.c} and @file{data.h} have been explicitly removed without
9120 also removing @file{data.stamp} and the other output files.
9121 @code{make clean; make} will always recover from these situations even
9122 with parallel makes, so you may decide that the recover rule is solely
9123 to help non-parallel make users and leave things as-is. Fixing this
9124 requires some locking mechanism to ensure only one instance of the
9125 recover rule rebuilds @file{data.stamp}. One could imagine something
9126 along the following lines.
9129 data.c data.h data.w data.x: data.stamp
9130 ## Recover from the removal of $@@
9131 @@if test -f $@@; then :; else \
9132 trap 'rm -rf data.lock data.stamp 1 2 13 15; \
9133 ## mkdir is a portable test-and-set
9134 if mkdir data.lock 2>/dev/null; then \
9135 ## This code is being executed by the first process.
9137 $(MAKE) $(AM_MAKEFLAGS) data.stamp; \
9139 ## This code is being executed by the follower processes.
9140 ## Wait until the first process is done.
9141 while test -d data.lock; do sleep 1; done; \
9142 ## Succeed if and only if the first process succeeded.
9143 test -f data.stamp; exit $$?; \
9148 Using a dedicated witness, like @file{data.stamp}, is very handy when
9149 the list of output files is not known beforehand. As an illustration,
9150 consider the following rules to compile many @file{*.el} files into
9151 @file{*.elc} files in a single command. It does not matter how
9152 @code{ELFILES} is defined (as long as it is not empty: empty targets
9153 are not accepted by POSIX).
9156 ELFILES = one.el two.el three.el @dots{}
9157 ELCFILES = $(ELFILES:=c)
9159 elc-stamp: $(ELFILES)
9162 $(elisp_comp) $(ELFILES)
9163 @@mv -f elc-temp $@@
9165 $(ELCFILES): elc-stamp
9166 ## Recover from the removal of $@@
9167 @@if test -f $@@; then :; else \
9168 trap 'rm -rf elc-lock elc-stamp' 1 2 13 15; \
9169 if mkdir elc-lock 2>/dev/null; then \
9170 ## This code is being executed by the first process.
9172 $(MAKE) $(AM_MAKEFLAGS) elc-stamp; \
9175 ## This code is being executed by the follower processes.
9176 ## Wait until the first process is done.
9177 while test -d elc-lock; do sleep 1; done; \
9178 ## Succeed if and only if the first process succeeded.
9179 test -f elc-stamp; exit $$?; \
9184 For completeness it should be noted that GNU @command{make} is able to
9185 express rules with multiple output files using pattern rules
9186 (@pxref{Pattern Examples, , Pattern Rule Examples, make, The GNU Make
9187 Manual}). We do not discuss pattern rules here because they are not
9188 portable, but they can be convenient in packages that assume GNU
9192 @node Hard-Coded Install Paths
9193 @section Installing to Hard-Coded Locations
9196 My package needs to install some configuration file. I tried to use
9197 the following rule, but @samp{make distcheck} fails. Why?
9202 $(INSTALL_DATA) $(srcdir)/afile $(DESTDIR)/etc/afile
9207 My package needs to populate the installation directory of another
9208 package at install-time. I can easily compute that installation
9209 directory in @file{configure}, but if I install files therein,
9210 @samp{make distcheck} fails. How else should I do?
9213 These two setups share their symptoms: @samp{make distcheck} fails
9214 because they are installing files to hard-coded paths. In the later
9215 case the path is not really hard-coded in the package, but we can
9216 consider it to be hard-coded in the system (or in whichever tool that
9217 supplies the path). As long as the path does not use any of the
9218 standard directory variables (@samp{$(prefix)}, @samp{$(bindir)},
9219 @samp{$(datadir)}, etc.), the effect will be the same:
9220 user-installations are impossible.
9222 When a (non-root) user wants to install a package, he usually has no
9223 right to install anything in @file{/usr} or @file{/usr/local}. So he
9224 does something like @samp{./configure --prefix ~/usr} to install
9225 package in his own @file{~/usr} tree.
9227 If a package attempts to install something to some hard-coded path
9228 (e.g., @file{/etc/afile}), regardless of this @option{--prefix} setting,
9229 then the installation will fail. @samp{make distcheck} performs such
9230 a @option{--prefix} installation, hence it will fail too.
9232 Now, there are some easy solutions.
9234 The above @code{install-data-local} example for installing
9235 @file{/etc/afile} would be better replaced by
9238 sysconf_DATA = afile
9242 by default @code{sysconfdir} will be @samp{$(prefix)/etc}, because
9243 this is what the GNU Standards require. When such a package is
9244 installed on a FHS compliant system, the installer will have to set
9245 @samp{--sysconfdir=/etc}. As the maintainer of the package you
9246 should not be concerned by such site policies: use the appropriate
9247 standard directory variable to install your files so that installer
9248 can easily redefine these variables to match their site conventions.
9250 Installing files that should be used by another package, is slightly
9251 more involved. Let's take an example and assume you want to install
9252 shared library that is a Python extension module. If you ask Python
9253 where to install the library, it will answer something like this:
9256 % @kbd{python -c 'from distutils import sysconfig;
9257 print sysconfig.get_python_lib(1,0)'}
9258 /usr/lib/python2.3/site-packages
9261 If you indeed use this absolute path to install your shared library,
9262 non-root users will not be able to install the package, hence
9265 Let's do better. The @samp{sysconfig.get_python_lib()} function
9266 actually accepts a third argument that will replace Python's
9267 installation prefix.
9270 % @kbd{python -c 'from distutils import sysconfig;
9271 print sysconfig.get_python_lib(1,0,"$@{exec_prefix@}")'}
9272 $@{exec_prefix@}/lib/python2.3/site-packages
9275 You can also use this new path. If you do
9278 root users can install your package with the same @option{--prefix}
9279 as Python (you get the behavior of the previous attempt)
9282 non-root users can install your package too, they will have the
9283 extension module in a place that is not searched by Python but they
9284 can work around this using environment variables (and if you installed
9285 scripts that use this shared library, it's easy to tell Python were to
9286 look in the beginning of your script, so the script works in both
9290 The @code{AM_PATH_PYTHON} macro uses similar commands to define
9291 @samp{$(pythondir)} and @samp{$(pyexecdir)} (@pxref{Python}).
9293 Of course not all tools are as advanced as Python regarding that
9294 substitution of @var{prefix}. So another strategy is to figure the
9295 part of the of the installation directory that must be preserved. For
9296 instance, here is how @code{AM_PATH_LISPDIR} (@pxref{Emacs Lisp})
9297 computes @samp{$(lispdir)}:
9300 $EMACS -batch -q -eval '(while load-path
9301 (princ (concat (car load-path) "\n"))
9302 (setq load-path (cdr load-path)))' >conftest.out
9305 -e '/.*\/lib\/x*emacs\/site-lisp$/@{
9306 s,.*/lib/\(x*emacs/site-lisp\)$,$@{libdir@}/\1,;p;q;
9308 -e '/.*\/share\/x*emacs\/site-lisp$/@{
9309 s,.*/share/\(x*emacs/site-lisp\),$@{datarootdir@}/\1,;p;q;
9314 I.e., it just picks the first directory that looks like
9315 @file{*/lib/*emacs/site-lisp} or @file{*/share/*emacs/site-lisp} in
9316 the search path of emacs, and then substitutes @samp{$@{libdir@}} or
9317 @samp{$@{datadir@}} appropriately.
9319 The emacs case looks complicated because it processes a list and
9320 expect two possible layouts, otherwise it's easy, and the benefit for
9321 non-root users are really worth the extra @command{sed} invocation.
9325 @chapter History of Automake
9327 This chapter presents various aspects of the history of Automake. The
9328 exhausted reader can safely skip it; this will be more of interest to
9329 nostalgic people, or to those curious to learn about the evolution of
9333 * Timeline:: The Automake story.
9334 * Dependency Tracking Evolution:: Evolution of Automatic Dependency Tracking
9335 * Releases:: Statistics about Automake Releases
9342 @item 1994-09-19 First CVS commit.
9344 If we can trust the CVS repository, David J.@tie{}MacKenzie (djm) started
9345 working on Automake (or AutoMake, as it was spelt then) this Monday.
9347 The first version of the @command{automake} script looks as follows.
9356 if test ! -f $@{makefile@}.am; then
9357 echo "automake: $@{makefile@}.am: No such honkin' file"
9362 exec 4> $@{makefile@}.in
9367 From this you can already see that Automake will be about reading
9368 @file{*.am} file and producing @file{*.in} files. You cannot see
9369 anything else, but if you also know that David is the one who created
9370 Autoconf two years before you can guess the rest.
9372 Several commits follow, and by the end of the day Automake is
9373 reported to work for GNU fileutils and GNU m4.
9375 The modus operandi is the one that is still used today: variables
9376 assignments in @file{Makefile.am} files trigger injections of
9377 precanned @file{Makefile} fragments into the generated
9378 @file{Makefile.in}. The use of @file{Makefile} fragments was inspired
9379 by the 4.4BSD @command{make} and include files, however Automake aims
9380 to be portable and to conform to the GNU standards for @file{Makefile}
9381 variables and targets.
9383 At this point, the most recent release of Autoconf is version 1.11,
9384 and David is preparing to release Autoconf 2.0 in late October. As a
9385 matter of fact, he will barely touch Automake after September.
9387 @item 1994-11-05 David MacKenzie's last commit.
9389 At this point Automake is a 200 line portable shell script, plus 332
9390 lines of @file{Makefile} fragments. In the @file{README}, David
9391 states his ambivalence between ``portable shell'' and ``more
9392 appropriate language'':
9395 I wrote it keeping in mind the possibility of it becoming an Autoconf
9396 macro, so it would run at configure-time. That would slow
9397 configuration down a bit, but allow users to modify the Makefile.am
9398 without needing to fetch the AutoMake package. And, the Makefile.in
9399 files wouldn't need to be distributed. But all of AutoMake would. So
9400 I might reimplement AutoMake in Perl, m4, or some other more
9401 appropriate language.
9404 Automake is described as ``an experimental Makefile generator''.
9405 There is no documentation. Adventurous users are referred to the
9406 examples and patches needed to use Automake with GNU m4 1.3, fileutils
9407 3.9, time 1.6, and development versions of find and indent.
9409 These examples seem to have been lost. However at the time of writing
9410 (10 years later in September, 2004) the FSF still distributes a
9411 package that uses this version of Automake: check out GNU termutils
9414 @item 1995-11-12 Tom Tromey's first commit.
9416 After one year of inactivity, Tom Tromey takes over the package.
9417 Tom was working on GNU cpio back then, and doing this just for fun,
9418 having trouble finding a project to contribute to. So while hacking
9419 he wanted to bring the @file{Makefile.in} up to GNU standards. This
9420 was hard, and one day he saw Automake on @url{ftp://alpha.gnu.org/},
9421 grabbed it and tried it out.
9423 Tom didn't talk to djm about it until later, just to make sure he
9424 didn't mind if he made a release. He did a bunch of early releases to
9427 Gnits was (and still is) totally informal, just a few GNU friends who
9428 Fran@,cois Pinard knew, who were all interested in making a common
9429 infrastructure for GNU projects, and shared a similar outlook on how
9430 to do it. So they were able to make some progress. It came along
9431 with Autoconf and extensions thereof, and then Automake from David and
9432 Tom (who were both gnitsians). One of their ideas was to write a
9433 document paralleling the GNU standards, that was more strict in some
9434 ways and more detailed. They never finished the GNITS standards, but
9435 the ideas mostly made their way into Automake.
9437 @item 1995-11-23 Automake 0.20
9439 Besides introducing automatic dependency tracking (@pxref{Dependency
9440 Tracking Evolution}), this version also supplies a 9-page manual.
9442 At this time @command{aclocal} and @code{AM_INIT_AUTOMAKE} did not
9443 exist, so many things had to be done by hand. For instance, here is
9444 what a configure.in (this is the former name of the
9445 @file{configure.ac} we use today) must contain in order to use
9451 AC_DEFINE_UNQUOTED(PACKAGE, "$PACKAGE")
9452 AC_DEFINE_UNQUOTED(VERSION, "$VERSION")
9459 (Today all of the above is achieved by @code{AC_INIT} and
9460 @code{AM_INIT_AUTOMAKE}.)
9462 Here is how programs are specified in @file{Makefile.am}:
9466 hello_SOURCES = hello.c
9469 This looks pretty much like what we do today, except the
9470 @code{PROGRAMS} variable has no directory prefix specifying where
9471 @file{hello} should be installed: all programs are installed in
9472 @samp{$(bindir)}. @code{LIBPROGRAMS} can be used to specify programs
9473 that must be built but not installed (it is called
9474 @code{noinst_PROGRAMS} nowadays).
9476 Programs can be built conditionally using @code{AC_SUBST}itutions:
9479 PROGRAMS = @@progs@@
9480 AM_PROGRAMS = foo bar baz
9483 (@code{AM_PROGRAMS} has since then been renamed to
9484 @code{EXTRA_PROGRAMS}.)
9486 Similarly scripts, static libraries, and data can built and installed
9487 using the @code{LIBRARIES}, @code{SCRIPTS}, and @code{DATA} variables.
9488 However @code{LIBRARIES} were treated a bit specially in that Automake
9489 did automatically supply the @file{lib} and @file{.a} prefixes.
9490 Therefore to build @file{libcpio.a}, one had to write
9497 Extra files to distribute must be listed in @code{DIST_OTHER} (the
9498 ancestor of @code{EXTRA_DIST}). Also extra directories that are to be
9499 distributed should appear in @code{DIST_SUBDIRS}, but the manual
9500 describes this as a temporary ugly hack (today extra directories should
9501 also be listed in @code{EXTRA_DIST}, and @code{DIST_SUBDIRS} is used
9502 for another purpose, @pxref{Conditional Subdirectories}).
9504 @item 1995-11-26 Automake 0.21
9506 In less time that it takes to cook a frozen pizza, Tom rewrites
9507 Automake using Perl. At this time Perl 5 is only one year old, and
9508 Perl 4.036 is in use at many sites. Supporting several Perl versions
9509 has been a source of problems through the whole history of Automake.
9511 If you never used Perl 4, imagine Perl 5 without objects, without
9512 @samp{my} variables (only dynamically scoped @samp{local} variables),
9513 without function prototypes, with function calls that needs to be
9514 prefixed with @samp{&}, etc. Traces of this old style can still be
9515 found in today's @command{automake}.
9517 @item 1995-11-28 Automake 0.22
9518 @itemx 1995-11-29 Automake 0.23
9522 @item 1995-12-08 Automake 0.24
9523 @itemx 1995-12-10 Automake 0.25
9525 Releases are raining. 0.24 introduces the uniform naming scheme we
9526 use today, i.e., @code{bin_PROGRAMS} instead of @code{PROGRAMS},
9527 @code{noinst_LIBRARIES} instead of @code{LIBLIBRARIES}, etc. (However
9528 @code{EXTRA_PROGRAMS} does not exist yet, @code{AM_PROGRAMS} is still
9529 in use; and @code{TEXINFOS} and @code{MANS} still have no directory
9530 prefixes.) Adding support for prefixes like that was one of the major
9531 ideas in automake; it has lasted pretty well.
9533 AutoMake is renamed to Automake (Tom seems to recall it was Fran@,cois
9536 0.25 fixes a Perl 4 portability bug.
9538 @item 1995-12-18 Jim Meyering starts using Automake in GNU Textutils.
9539 @item 1995-12-31 Fran@,cois Pinard starts using Automake in GNU tar.
9541 @item 1996-01-03 Automake 0.26
9542 @itemx 1996-01-03 Automake 0.27
9544 Of the many change and suggestions sent by Fran@,cois Pinard and
9545 included in 0.26, the most important is perhaps the advise that to
9546 ease customization a user rule or variable definition should always
9547 override an Automake rule or definition.
9549 Gordon Matzigkeit and Jim Meyering are two other early contributors
9550 that have been sending fixes.
9552 0.27 fixes yet another Perl 4 portability bug.
9554 @item 1996-01-13 Automake 0.28
9556 Automake starts scanning @file{configure.in} for @code{LIBOBJS}
9557 support. This is an important step because until this version
9558 Automake did only know about the @file{Makefile.am}s it processed.
9559 @file{configure.in} was Autoconf's world and the link between Autoconf
9560 and Automake had to be done by the @file{Makefile.am} author. For
9561 instance, if @file{config.h} was generated by @file{configure}, it was the
9562 package maintainer's responsibility to define the @code{CONFIG_HEADER}
9563 variable in each @file{Makefile.am}.
9565 Succeeding releases will rely more and more on scanning
9566 @file{configure.in} to better automate the Autoconf integration.
9568 0.28 also introduces the @code{AUTOMAKE_OPTIONS} variable and the
9569 @option{--gnu} and @option{--gnits} options, the latter being stricter.
9571 @item 1996-02-07 Automake 0.29
9573 Thanks to @file{configure.in} scanning, @code{CONFIG_HEADER} is gone,
9574 and rebuild rules for @file{configure}-generated file are
9575 automatically output.
9577 @code{TEXINFOS} and @code{MANS} converted to the uniform naming
9580 @item 1996-02-24 Automake 0.30
9582 The test suite is born. It contains 9 tests. From now on test cases
9583 will be added pretty regularly (@pxref{Releases}), and this proved to
9584 be really helpful later on.
9586 @code{EXTRA_PROGRAMS} finally replaces @code{AM_PROGRAMS}.
9588 All the third-party Autoconf macros, written mostly by Fran@,cois
9589 Pinard (and later Jim Meyering), are distributed in Automake's
9590 hand-written @file{aclocal.m4} file. Package maintainers are expected
9591 to extract the necessary macros from this file. (In previous version
9592 you had to copy and paste them from the manual...)
9594 @item 1996-03-11 Automake 0.31
9596 The test suite in 0.30 was run via a long @code{check-local} rule. Upon
9597 Ulrich Drepper's suggestion, 0.31 makes it an Automake rule output
9598 whenever the @code{TESTS} variable is defined.
9600 @code{DIST_OTHER} is renamed to @code{EXTRA_DIST}, and the @code{check_}
9601 prefix is introduced. The syntax is now the same as today.
9603 @item 1996-03-15 Gordon Matzigkeit starts writing libtool.
9605 @item 1996-04-27 Automake 0.32
9607 @code{-hook} targets are introduced; an idea from Dieter Baron.
9609 @file{*.info} files, which were output in the build directory are
9610 now built in the source directory, because they are distributed. It
9611 seems these files like to move back and forth as that will happen
9612 again in future versions.
9614 @item 1996-05-18 Automake 0.33
9616 Gord Matzigkeit's main two contributions:
9619 @item very preliminary libtool support
9620 @item the distcheck rule
9623 Although they were very basic at this point, these are probably
9624 among the top features for Automake today.
9626 Jim Meyering also provides the infamous @code{jm_MAINTAINER_MODE},
9627 since then renamed to @code{AM_MAINTAINER_MODE} and abandoned by its
9628 author (@pxref{maintainer-mode}).
9630 @item 1996-05-28 Automake 1.0
9632 After only six months of heavy development, the automake script is
9633 3134 lines long, plus 973 lines of @file{Makefile} fragments. The
9634 package has 30 pages of documentation, and 38 test cases.
9635 @file{aclocal.m4} contains 4 macros.
9637 From now on and until version 1.4, new releases will occur at a rate
9638 of about one a year. 1.1 did not exist, actually 1.1b to 1.1p have
9639 been the name of beta releases for 1.2. This is the first time
9640 Automake uses suffix letters to designate beta releases, an habit that
9643 @item 1996-10-10 Kevin Dalley packages Automake 1.0 for Debian GNU/Linux.
9645 @item 1996-11-26 David J.@tie{}MacKenzie releases Autoconf 2.12.
9647 Between June and October, the Autoconf development is almost staled.
9648 Roland McGrath has been working at the beginning of the year. David
9649 comes back in November to release 2.12, but he won't touch Autoconf
9650 anymore after this year, and Autoconf then really stagnates. The
9651 desolate Autoconf @file{ChangeLog} for 1997 lists only 7 commits.
9653 @item 1997-02-28 @email{automake@@gnu.ai.mit.edu} list alive
9655 The mailing list is announced as follows:
9657 I've created the "automake" mailing list. It is
9658 "automake@@gnu.ai.mit.edu". Administrivia, as always, to
9659 automake-request@@gnu.ai.mit.edu.
9661 The charter of this list is discussion of automake, autoconf, and
9662 other configuration/portability tools (eg libtool). It is expected
9663 that discussion will range from pleas for help all the way up to
9666 This list is archived on the FSF machines. Offhand I don't know if
9667 you can get the archive without an account there.
9669 This list is open to anybody who wants to join. Tell all your
9674 Before that people were discussing Automake privately, on the Gnits
9675 mailing list (which is not public either), and less frequently on
9676 @code{gnu.misc.discuss}.
9678 @code{gnu.ai.mit.edu} is now @code{gnu.org}, in case you never
9679 noticed. The archives of the early years of the
9680 @code{automake@@gnu.org} list have been lost, so today it is almost
9681 impossible to find traces of discussions that occurred before 1999.
9682 This has been annoying more than once, as such discussions can be
9683 useful to understand the rationale behind a piece of uncommented code
9684 that was introduced back then.
9686 @item 1997-06-22 Automake 1.2
9688 Automake developments continues, and more and more new Autoconf macros
9689 are required. Distributing them in @file{aclocal.m4} and requiring
9690 people to browse this file to extract the relevant macros becomes
9691 uncomfortable. Ideally, some of them should be contributed to
9692 Autoconf so that they can be used directly, however Autoconf is
9693 currently inactive. Automake 1.2 consequently introduces
9694 @command{aclocal} (@command{aclocal} was actually started on
9695 1996-07-28), a tool that automatically constructs an @file{aclocal.m4}
9696 file from a repository of third-party macros. Because Autoconf has
9697 stalled, Automake also becomes a kind of repository for such
9698 third-party macros, even macros completely unrelated to Automake (for
9699 instance macros that fix broken Autoconf macros).
9701 The 1.2 release contains 20 macros, among which the
9702 @code{AM_INIT_AUTOMAKE} macro that simplifies the creation of
9703 @file{configure.in}.
9705 Libtool is fully supported using @code{*_LTLIBRARIES}.
9707 The missing script is introduced by Fran@,cois Pinard; it is meant to be
9708 a better solution than @code{AM_MAINTAINER_MODE}
9709 (@pxref{maintainer-mode}).
9711 Conditionals support was implemented by Ian Lance Taylor. At the
9712 time, Tom and Ian were working on an internal project at Cygnus. They
9713 were using ILU, which is pretty similar to CORBA@. They wanted to
9714 integrate ILU into their build, which was all @file{configure}-based,
9715 and Ian thought that adding conditionals to @command{automake} was
9716 simpler than doing all the work in @file{configure} (which was the
9717 standard at the time). So this was actually funded by Cygnus.
9719 This very useful but tricky feature will take a lot of time to
9720 stabilize. (At the time this text is written, there are still
9721 primaries that have not been updated to support conditional
9722 definitions in Automake 1.9.)
9724 The @command{automake} script has almost doubled: 6089 lines of Perl,
9725 plus 1294 lines of @file{Makefile} fragments.
9727 @item 1997-07-08 Gordon Matzigkeit releases Libtool 1.0.
9729 @item 1998-04-05 Automake 1.3
9731 This is a small advance compared to 1.2.
9732 It add support for assembly, and preliminary support for Java.
9734 Perl 5.004_04 is out, but fixes to support Perl 4 are still
9735 regularly submitted whenever Automake breaks it.
9737 @item 1998-09-06 @code{sourceware.cygnus.com} is on-line.
9739 Sourceware was setup by Jason Molenda to host open source projects.
9741 @item 1998-09-19 Automake CVS repository moved to @code{sourceware.cygnus.com}
9742 @itemx 1998-10-26 @code{sourceware.cygnus.com} announces it hosts Automake
9743 Automake is now hosted on @code{sourceware.cygnus.com}. It has a
9744 publicly accessible CVS repository. This CVS repository is a copy of
9745 the one Tom was using on his machine, which in turn is based on
9746 a copy of the CVS repository of David MacKenzie. This is why we still
9747 have to full source history. (Automake is still on Sourceware today,
9748 but the host has been renamed to @code{sources.redhat.com}.)
9750 The oldest file in the administrative directory of the CVS repository
9751 that was created on Sourceware is dated 1998-09-19, while the
9752 announcement that @command{automake} and @command{autoconf} had joined
9753 @command{sourceware} was made on 1998-10-26. They were among the
9754 first projects to be hosted there.
9756 The heedful reader will have noticed Automake was exactly 4-year-old
9759 @item 1999-01-05 Ben Elliston releases Autoconf 2.13.
9761 @item 1999-01-14 Automake 1.4
9763 This release adds support for Fortran 77 and for the @code{include}
9764 statement. Also, @samp{+=} assignments are introduced, but it is
9765 still quite easy to fool Automake when mixing this with conditionals.
9767 These two releases, Automake 1.4 and Autoconf 2.13 makes a duo that
9768 will be used together for years.
9770 @command{automake} is 7228 lines, plus 1591 lines of Makefile
9771 fragment, 20 macros (some 1.3 macros were finally contributed back to
9772 Autoconf), 197 test cases, and 51 pages of documentation.
9774 @item 1999-03-27 The @code{user-dep-branch} is created on the CVS repository.
9776 This implements a new dependency tracking schemed that should be
9777 able to handle automatic dependency tracking using any compiler (not
9778 just gcc) and any make (not just GNU @command{make}). In addition,
9779 the new scheme should be more reliable than the old one, as
9780 dependencies are generated on the end user's machine. Alexandre Oliva
9781 creates depcomp for this purpose.
9783 @xref{Dependency Tracking Evolution}, for more details about the
9784 evolution of automatic dependency tracking in Automake.
9786 @item 1999-11-21 The @code{user-dep-branch} is merged into the main trunk.
9788 This was a huge problem since we also had patches going in on the
9789 trunk. The merge took a long time and was very painful.
9793 Since September 1999 and until 2003, Akim Demaille will be zealously
9797 I think the next release should be called "3.0".@*
9798 Let's face it: you've basically rewritten autoconf.@*
9799 Every weekend there are 30 new patches.@*
9800 I don't see how we could call this "2.15" with a straight face.@*
9801 -- Tom Tromey on @email{autoconf@@gnu.org}
9804 Actually Akim works like a submarine: he will pile up patches while he
9805 works off-line during the weekend, and flush them in batch when he
9806 resurfaces on Monday.
9810 On this Wednesday, Autoconf 2.49c, the last beta before Autoconf 2.50
9811 is out, and Akim has to find something to do during his week-end :)
9815 Akim sends a batch of 14 patches to @email{automake@@gnu.org}.
9818 Aiieeee! I was dreading the day that the Demaillator turned his
9819 sights on automake@dots{} and now it has arrived! -- Tom Tromey
9822 It's only the beginning: in two months he will send 192 patches. Then
9823 he would slow down so Tom can catch up and review all this. Initially
9824 Tom actually read all these patches, then he probably trustingly
9825 answered OK to most of them, and finally gave up and let Akim apply
9826 whatever he wanted. There was no way to keep up with that patch rate.
9829 Anyway the patch below won't apply since it predates Akim's
9830 sourcequake; I have yet to figure where the relevant passage has
9831 been moved :) -- Alexandre Duret-Lutz
9834 All these patches were sent to and discussed on
9835 @email{automake@@gnu.org}, so subscribed users were literally drown in
9836 technical mails. Eventually, the @email{automake-patches@@gnu.org}
9837 mailing list was created in May.
9839 Year after year, Automake had drifted away from its initial design:
9840 construct @file{Makefile.in} by assembling various @file{Makefile}
9841 fragments. In 1.4, lots of @file{Makefile} rules are being emitted at
9842 various places in the @command{automake} script itself; this does not
9843 help ensuring a consistent treatment of these rules (for instance
9844 making sure that user-defined rules override Automake's own rules).
9845 One of Akim's goal was moving all these hard-coded rules to separate
9846 @file{Makefile} fragments, so the logic could be centralized in a
9847 @file{Makefile} fragment processor.
9849 Another significant contribution of Akim is the interface with the
9850 ``trace'' feature of Autoconf. The way to scan @file{configure.in} at
9851 this time was to read the file and grep the various macro of interest
9852 to Automake. Doing so could break in many unexpected ways; automake
9853 could miss some definition (for instance @samp{AC_SUBST([$1], [$2])}
9854 where the arguments are known only when M4 is run), or conversely it
9855 could detect some macro that was not expanded (because it is called
9856 conditionally). In the CVS version of Autoconf, Akim had implemented
9857 the @option{--trace} option, which provides accurate information about
9858 where macros are actually called and with what arguments. Akim will
9859 equip Automake with a second @file{configure.in} scanner that uses
9860 this @option{--trace} interface. Since it was not sensible to drop the
9861 Autoconf 2.13 compatibility yet, this experimental scanner was only
9862 used when an environment variable was set, the traditional
9863 grep-scanner being still the default.
9865 @item 2001-04-25 Gary V.@tie{}Vaughan releases Libtool 1.4
9867 It has been more than two years since Automake 1.4, CVS Automake has
9868 suffered lot's of heavy changes and still is not ready for release.
9869 Libtool 1.4 had to be distributed with a patch against Automake 1.4.
9871 @item 2001-05-08 Automake 1.4-p1
9872 @itemx 2001-05-24 Automake 1.4-p2
9874 Gary V.@tie{}Vaughan, the principal Libtool maintainer, makes a ``patch
9875 release'' of Automake:
9878 The main purpose of this release is to have a stable automake
9879 which is compatible with the latest stable libtool.
9882 The release also contains obvious fixes for bugs in Automake 1.4,
9883 some of which were reported almost monthly.
9885 @item 2001-05-21 Akim Demaille releases Autoconf 2.50
9887 @item 2001-06-07 Automake 1.4-p3
9888 @itemx 2001-06-10 Automake 1.4-p4
9889 @itemx 2001-07-15 Automake 1.4-p5
9891 Gary continues his patch-release series. These also add support for
9892 some new Autoconf 2.50 idioms. Essentially, Autoconf now advocates
9893 @file{configure.ac} over @file{configure.in}, and it introduces a new
9894 syntax for @code{AC_OUTPUT}ing files.
9896 @item 2001-08-23 Automake 1.5
9898 A major and long-awaited release, that comes more than two years after
9899 1.4. It brings many changes, among which:
9901 @item The new dependency tracking scheme that uses @command{depcomp}.
9902 Aside from the improvement on the dependency tracking itself
9903 (@pxref{Dependency Tracking Evolution}), this also streamlines the use
9904 of automake generated @file{Makefile.in}s as the @file{Makefile.in}s
9905 used during development are now the same as those used in
9906 distributions. Before that the @file{Makefile.in}s generated for
9907 maintainers required GNU @command{make} and GCC, they were different
9908 from the portable @file{Makefile} generated for distribution; this was
9909 causing some confusion.
9911 @item Support for per-target compilation flags.
9913 @item Support for reference to files in subdirectories in most
9914 @file{Makefile.am} variables.
9916 @item Introduction of the @code{dist_}, @code{nodist_}, and @code{nobase_}
9918 @item Perl 4 support is finally dropped.
9921 1.5 did broke several packages that worked with 1.4. Enough so that
9922 Linux distributions could not easily install the new Automake version
9923 without breaking many of the packages for which they had to run
9926 Some of these breakages were effectively bugs that would eventually be
9927 fixed in the next release. However, a lot of damage was caused by
9928 some changes made deliberately to render Automake stricter on some
9929 setup we did consider bogus. For instance, @samp{make distcheck} was
9930 improved to check that @samp{make uninstall} did remove all the files
9931 @samp{make install} installed, that @samp{make distclean} did not omit
9932 some file, and that a VPATH build would work even if the source
9933 directory was read-only. Similarly, Automake now rejects multiple
9934 definitions of the same variable (because that would mix very badly
9935 with conditionals), and @samp{+=} assignments with no previous
9936 definition. Because these changes all occurred suddenly after 1.4 had
9937 been established for more that two years, it hurt users.
9939 To make matter worse, meanwhile Autoconf (now at version 2.52) was
9940 facing similar troubles, for similar reasons.
9942 @item 2002-03-05 Automake 1.6
9944 This release introduced versioned installation (@pxref{API
9945 versioning}). This was mainly pushed by Havoc Pennington, taking the
9946 GNOME source tree as motive: due to incompatibilities between the
9947 autotools it's impossible for the GNOME packages to switch to Autoconf
9948 2.53 and Automake 1.5 all at once, so they are currently stuck with
9949 Autoconf 2.13 and Automake 1.4.
9951 The idea was to call this version @file{automake-1.6}, call all its
9952 bug-fix versions identically, and switch to @file{automake-1.7} for
9953 the next release that adds new features or changes some rules. This
9954 scheme implies maintaining a bug-fix branch in addition to the
9955 development trunk, which means more work from the maintainer, but
9956 providing regular bug-fix releases proved to be really worthwhile.
9958 Like 1.5, 1.6 also introduced a bunch of incompatibilities, meant or
9959 not. Perhaps the more annoying was the dependence on the newly
9960 released Autoconf 2.53. Autoconf seemed to have stabilized enough
9961 since its explosive 2.50 release, and included changes required to fix
9962 some bugs in Automake. In order to upgrade to Automake 1.6, people
9963 now had to upgrade Autoconf too; for some packages it was no picnic.
9965 While versioned installation helped people to upgrade, it also
9966 unfortunately allowed people not to upgrade. At the time of writing,
9967 some Linux distributions are shipping packages for Automake 1.4, 1.5,
9968 1.6, 1.7, 1.8, and 1.9. Most of these still install 1.4 by default.
9969 Some distribution also call 1.4 the ``stable'' version, and present
9970 ``1.9'' as the development version; this does not really makes sense
9971 since 1.9 is way more solid than 1.4. All this does not help the
9974 @item 2002-04-11 Automake 1.6.1
9976 1.6, and the upcoming 1.4-p6 release were the last release by Tom.
9977 This one and those following will be handled by Alexandre
9978 Duret-Lutz. Tom is still around, and will be there until about 1.7,
9979 but his interest into Automake is drifting away towards projects like
9982 Alexandre has been using Automake since 2000, and started to
9983 contribute mostly on Akim's incitement (Akim and Alexandre have been
9984 working in the same room from 1999 to 2002). In 2001 and 2002 he had
9985 a lot of free time to enjoy hacking Automake.
9987 @item 2002-06-14 Automake 1.6.2
9989 @item 2002-07-28 Automake 1.6.3
9990 @itemx 2002-07-28 Automake 1.4-p6
9992 Two releases on the same day. 1.6.3 is a bug-fix release.
9994 Tom Tromey backported the versioned installation mechanism on the 1.4
9995 branch, so that Automake 1.6.x and Automake 1.4-p6 could be installed
9996 side by side. Another request from the GNOME folks.
9998 @item 2002-09-25 Automake 1.7
10000 This release switches to the new @file{configure.ac} scanner Akim
10001 was experimenting in 1.5.
10003 @item 2002-10-16 Automake 1.7.1
10004 @itemx 2002-12-06 Automake 1.7.2
10005 @itemx 2003-02-20 Automake 1.7.3
10006 @itemx 2003-04-23 Automake 1.7.4
10007 @itemx 2003-05-18 Automake 1.7.5
10008 @itemx 2003-07-10 Automake 1.7.6
10009 @itemx 2003-09-07 Automake 1.7.7
10010 @itemx 2003-10-07 Automake 1.7.8
10012 Many bug-fix releases. 1.7 lasted because the development version
10013 (upcoming 1.8) was suffering some major internal revamping.
10015 @item 2003-10-26 Automake on screen
10017 Episode 49, `Repercussions', in the third season of the `Alias' TV
10018 show is first aired.
10020 Marshall, one of the character, is working on a computer virus that he
10021 has to modify before it gets into the wrong hands or something like
10022 that. The screenshots you see do not show any program code, they show
10023 a @file{Makefile.in} @code{generated by automake}...
10025 @item 2003-11-09 Automake 1.7.9
10027 @item 2003-12-10 Automake 1.8
10029 The most striking update is probably that of @command{aclocal}.
10031 @command{aclocal} now uses @code{m4_include} in the produced
10032 @code{aclocal.m4} when the included macros are already distributed
10033 with the package (an idiom used in many packages), which reduces code
10034 duplication. Many people liked that, but in fact this change was
10035 really introduced to fix a bug in rebuild rules: @file{Makefile.in}
10036 must be rebuilt whenever a dependency of @file{configure} changes, but
10037 all the @file{m4} files included in @file{aclocal.m4} where unknown
10038 from @command{automake}. Now @command{automake} can just trace the
10039 @code{m4_include}s to discover the dependencies.
10041 @command{aclocal} also starts using the @option{--trace} Autoconf option
10042 in order to discover used macros more accurately. This will turn out
10043 to be very tricky (later releases will improve this) as people had
10044 devised many ways to cope with the limitation of previous
10045 @command{aclocal} versions, notably using handwritten
10046 @code{m4_include}s: @command{aclocal} must make sure not to redefine a
10047 rule that is already included by such statement.
10049 Automake also has seen its guts rewritten. Although this rewriting
10050 took a lot of efforts, it is only apparent to the users in that some
10051 constructions previously disallowed by the implementation now work
10052 nicely. Conditionals, Locations, Variable and Rule definitions,
10053 Options: these items on which Automake works have been rewritten as
10054 separate Perl modules, and documented.
10056 @itemx 2004-01-11 Automake 1.8.1
10057 @itemx 2004-01-12 Automake 1.8.2
10058 @itemx 2004-03-07 Automake 1.8.3
10059 @itemx 2004-04-25 Automake 1.8.4
10060 @itemx 2004-05-16 Automake 1.8.5
10062 @item 2004-07-28 Automake 1.9
10064 This release tries to simplify the compilation rules it outputs to
10065 reduce the size of the Makefile. The complaint initially come from
10066 the libgcj developers. Their @file{Makefile.in} generated with
10067 Automake 1.4 and custom build rules (1.4 did not support compiled
10068 Java) is 250KB@. The one generated by 1.8 was over 9MB@! 1.9 gets it
10071 Aside from this it contains mainly minor changes and bug-fixes.
10073 @itemx 2004-08-11 Automake 1.9.1
10074 @itemx 2004-09-19 Automake 1.9.2
10076 Automake has ten years. This chapter of the manual was initially
10077 written for this occasion.
10081 @node Dependency Tracking Evolution
10082 @section Dependency Tracking in Automake
10084 Over the years Automake has deployed three different dependency
10085 tracking methods. Each method, including the current one, has had
10086 flaws of various sorts. Here we lay out the different dependency
10087 tracking methods, their flaws, and their fixes. We conclude with
10088 recommendations for tool writers, and by indicating future directions
10089 for dependency tracking work in Automake.
10091 @subsection First Take
10092 @unnumberedsubsubsec Description
10094 Our first attempt at automatic dependency tracking was based on the
10095 method recommended by GNU @command{make}. (@pxref{Automatic
10096 Prerequisites, , Generating Prerequisites Automatically, make, The GNU
10099 This version worked by precomputing dependencies ahead of time. For
10100 each source file, it had a special @file{.P} file that held the
10101 dependencies. There was a rule to generate a @file{.P} file by
10102 invoking the compiler appropriately. All such @file{.P} files were
10103 included by the @file{Makefile}, thus implicitly becoming dependencies
10104 of @file{Makefile}.
10106 @unnumberedsubsubsec Bugs
10108 This approach had several critical bugs.
10112 The code to generate the @file{.P} file relied on @command{gcc}.
10113 (A limitation, not technically a bug.)
10115 The dependency tracking mechanism itself relied on GNU @command{make}.
10116 (A limitation, not technically a bug.)
10118 Because each @file{.P} file was a dependency of @file{Makefile}, this
10119 meant that dependency tracking was done eagerly by @command{make}.
10120 For instance, @samp{make clean} would cause all the dependency files
10121 to be updated, and then immediately removed. This eagerness also
10122 caused problems with some configurations; if a certain source file
10123 could not be compiled on a given architecture for some reason,
10124 dependency tracking would fail, aborting the entire build.
10126 As dependency tracking was done as a pre-pass, compile times were
10127 doubled--the compiler had to be run twice per source file.
10129 @samp{make dist} re-ran @command{automake} to generate a
10130 @file{Makefile} that did not have automatic dependency tracking (and
10131 that was thus portable to any version of @command{make}). In order to
10132 do this portably, Automake had to scan the dependency files and remove
10133 any reference that was to a source file not in the distribution.
10134 This process was error-prone. Also, if @samp{make dist} was run in an
10135 environment where some object file had a dependency on a source file
10136 that was only conditionally created, Automake would generate a
10137 @file{Makefile} that referred to a file that might not appear in the
10138 end user's build. A special, hacky mechanism was required to work
10142 @unnumberedsubsubsec Historical Note
10144 The code generated by Automake is often inspired by the
10145 @file{Makefile} style of a particular author. In the case of the first
10146 implementation of dependency tracking, I believe the impetus and
10147 inspiration was Jim Meyering. (I could be mistaken. If you know
10148 otherwise feel free to correct me.)
10150 @subsection Dependencies As Side Effects
10151 @unnumberedsubsubsec Description
10153 The next refinement of Automake's automatic dependency tracking scheme
10154 was to implement dependencies as side effects of the compilation.
10155 This was aimed at solving the most commonly reported problems with the
10156 first approach. In particular we were most concerned with eliminating
10157 the weird rebuilding effect associated with make clean.
10159 In this approach, the @file{.P} files were included using the
10160 @code{-include} command, which let us create these files lazily. This
10161 avoided the @samp{make clean} problem.
10163 We only computed dependencies when a file was actually compiled. This
10164 avoided the performance penalty associated with scanning each file
10165 twice. It also let us avoid the other problems associated with the
10166 first, eager, implementation. For instance, dependencies would never
10167 be generated for a source file that was not compilable on a given
10168 architecture (because it in fact would never be compiled).
10170 @unnumberedsubsubsec Bugs
10174 This approach also relied on the existence of @command{gcc} and GNU
10175 @command{make}. (A limitation, not technically a bug.)
10177 Dependency tracking was still done by the developer, so the problems
10178 from the first implementation relating to massaging of dependencies by
10179 @samp{make dist} were still in effect.
10181 This implementation suffered from the ``deleted header file'' problem.
10182 Suppose a lazily-created @file{.P} file includes a dependency on a
10183 given header file, like this:
10186 maude.o: maude.c something.h
10189 Now suppose that the developer removes @file{something.h} and updates
10190 @file{maude.c} so that this include is no longer needed. If he runs
10191 @command{make}, he will get an error because there is no way to create
10192 @file{something.h}.
10194 We fixed this problem in a later release by further massaging the
10195 output of @command{gcc} to include a dummy dependency for each header
10199 @subsection Dependencies for the User
10200 @unnumberedsubsubsec Description
10202 The bugs associated with @samp{make dist}, over time, became a real
10203 problem. Packages using Automake were being built on a large number
10204 of platforms, and were becoming increasingly complex. Broken
10205 dependencies were distributed in ``portable'' @file{Makefile.in}s,
10206 leading to user complaints. Also, the requirement for @command{gcc}
10207 and GNU @command{make} was a constant source of bug reports. The next
10208 implementation of dependency tracking aimed to remove these problems.
10210 We realized that the only truly reliable way to automatically track
10211 dependencies was to do it when the package itself was built. This
10212 meant discovering a method portable to any version of make and any
10213 compiler. Also, we wanted to preserve what we saw as the best point
10214 of the second implementation: dependency computation as a side effect
10217 In the end we found that most modern make implementations support some
10218 form of include directive. Also, we wrote a wrapper script that let
10219 us abstract away differences between dependency tracking methods for
10220 compilers. For instance, some compilers cannot generate dependencies
10221 as a side effect of compilation. In this case we simply have the
10222 script run the compiler twice. Currently our wrapper script
10223 (@command{depcomp}) knows about twelve different compilers (including
10224 a "compiler" that simply invokes @command{makedepend} and then the
10225 real compiler, which is assumed to be a standard Unix-like C compiler
10226 with no way to do dependency tracking).
10228 @unnumberedsubsubsec Bugs
10232 Running a wrapper script for each compilation slows down the build.
10234 Many users don't really care about precise dependencies.
10236 This implementation, like every other automatic dependency tracking
10237 scheme in common use today (indeed, every one we've ever heard of),
10238 suffers from the ``duplicated new header'' bug.
10240 This bug occurs because dependency tracking tools, such as the
10241 compiler, only generate dependencies on the successful opening of a
10242 file, and not on every probe.
10244 Suppose for instance that the compiler searches three directories for
10245 a given header, and that the header is found in the third directory.
10246 If the programmer erroneously adds a header file with the same name to
10247 the first directory, then a clean rebuild from scratch could fail
10248 (suppose the new header file is buggy), whereas an incremental rebuild
10251 What has happened here is that people have a misunderstanding of what
10252 a dependency is. Tool writers think a dependency encodes information
10253 about which files were read by the compiler. However, a dependency
10254 must actually encode information about what the compiler tried to do.
10256 This problem is not serious in practice. Programmers typically do not
10257 use the same name for a header file twice in a given project. (At
10258 least, not in C or C++. This problem may be more troublesome in
10259 Java.) This problem is easy to fix, by modifying dependency
10260 generators to record every probe, instead of every successful open.
10263 Since automake generates dependencies as a side effect of compilation,
10264 there is a bootstrapping problem when header files are generated by
10265 running a program. The problem is that, the first time the build is
10266 done, there is no way by default to know that the headers are
10267 required, so make might try to run a compilation for which the headers
10268 have not yet been built.
10270 This was also a problem in the previous dependency tracking implementation.
10272 The current fix is to use @code{BUILT_SOURCES} to list built headers
10273 (@pxref{Sources}). This causes them to be built before any other
10274 other build rules are run. This is unsatisfactory as a general
10275 solution, however in practice it seems sufficient for most actual
10279 This code is used since Automake 1.5.
10281 In GCC 3.0, we managed to convince the maintainers to add special
10282 command-line options to help Automake more efficiently do its job. We
10283 hoped this would let us avoid the use of a wrapper script when
10284 Automake's automatic dependency tracking was used with @command{gcc}.
10286 Unfortunately, this code doesn't quite do what we want. In
10287 particular, it removes the dependency file if the compilation fails;
10288 we'd prefer that it instead only touch the file in any way if the
10289 compilation succeeds.
10291 Nevertheless, since Automake 1.7, when a recent @command{gcc} is
10292 detected at @command{configure} time, we inline the
10293 dependency-generation code and do not use the @command{depcomp}
10294 wrapper script. This makes compilations faster for those using this
10295 compiler (probably our primary user base). The counterpart is that
10296 because we have to encode two compilation rules in @file{Makefile}
10297 (with or without @command{depcomp}), the produced @file{Makefile}s are
10300 @subsection Techniques for Computing Dependencies
10302 There are actually several ways for a build tool like Automake to
10303 cause tools to generate dependencies.
10306 @item @command{makedepend}
10307 This was a commonly-used method in the past. The idea is to run a
10308 special program over the source and have it generate dependency
10309 information. Traditional implementations of @command{makedepend} ere
10310 not completely precise; ordinarily they were conservative and
10311 discovered too many dependencies.
10313 An obvious way to generate dependencies is to simply write the tool so
10314 that it can generate the information needed by the build tool. This is
10315 also the most portable method. Many compilers have an option to
10316 generate dependencies. Unfortunately, not all tools provide such an
10318 @item The file system
10319 It is possible to write a special file system that tracks opens,
10320 reads, writes, etc, and then feed this information back to the build
10321 tool. @command{clearmake} does this. This is a very powerful
10322 technique, as it doesn't require cooperation from the
10323 tool. Unfortunately it is also very difficult to implement and also
10324 not practical in the general case.
10325 @item @code{LD_PRELOAD}
10326 Rather than use the file system, one could write a special library to
10327 intercept @code{open} and other syscalls. This technique is also quite
10328 powerful, but unfortunately it is not portable enough for use in
10329 @command{automake}.
10332 @subsection Recommendations for Tool Writers
10334 We think that every compilation tool ought to be able to generate
10335 dependencies as a side effect of compilation. Furthermore, at least
10336 while @command{make}-based tools are nearly universally in use (at
10337 least in the free software community), the tool itself should generate
10338 dummy dependencies for header files, to avoid the deleted header file
10339 bug. Finally, the tool should generate a dependency for each probe,
10340 instead of each successful file open, in order to avoid the duplicated
10343 @subsection Future Directions for Automake's Dependency Tracking
10345 Currently, only languages and compilers understood by Automake can
10346 have dependency tracking enabled. We would like to see if it is
10347 practical (and worthwhile) to let this support be extended by the user
10348 to languages unknown to Automake.
10351 @section Release Statistics
10353 The following table (inspired by @samp{perlhist(1)}) quantifies the
10354 evolution of Automake using these metrics:
10358 The date and version of the release.
10360 The number of lines of the @command{automake} script.
10362 The number of lines of the @command{aclocal} script.
10364 The number of lines of the @command{Perl} supporting modules.
10366 The number of lines of the @file{Makefile} fragments. The number in parenthesis
10367 is the number of files.
10369 The number of lines (and files) of Autoconf macros.
10371 The number of pages of the documentation (the Postscript version).
10373 The number of test cases in the test suite.
10376 @multitable {8888-88-88} {8.8-p8} {8888} {888} {8888} {8888 (88)} {8888 (88)} {888} {888}
10377 @headitem Date @tab Rel @tab am @tab acl @tab pm @tab @file{*.am} @tab m4 @tab doc @tab t
10378 @item 1994-09-19 @tab CVS @tab 141 @tab @tab @tab 299 (24) @tab @tab @tab
10379 @item 1994-11-05 @tab CVS @tab 208 @tab @tab @tab 332 (28) @tab @tab @tab
10380 @item 1995-11-23 @tab 0.20 @tab 533 @tab @tab @tab 458 (35) @tab @tab 9 @tab
10381 @item 1995-11-26 @tab 0.21 @tab 613 @tab @tab @tab 480 (36) @tab @tab 11 @tab
10382 @item 1995-11-28 @tab 0.22 @tab 1116 @tab @tab @tab 539 (38) @tab @tab 12 @tab
10383 @item 1995-11-29 @tab 0.23 @tab 1240 @tab @tab @tab 541 (38) @tab @tab 12 @tab
10384 @item 1995-12-08 @tab 0.24 @tab 1462 @tab @tab @tab 504 (33) @tab @tab 14 @tab
10385 @item 1995-12-10 @tab 0.25 @tab 1513 @tab @tab @tab 511 (37) @tab @tab 15 @tab
10386 @item 1996-01-03 @tab 0.26 @tab 1706 @tab @tab @tab 438 (36) @tab @tab 16 @tab
10387 @item 1996-01-03 @tab 0.27 @tab 1706 @tab @tab @tab 438 (36) @tab @tab 16 @tab
10388 @item 1996-01-13 @tab 0.28 @tab 1964 @tab @tab @tab 934 (33) @tab @tab 16 @tab
10389 @item 1996-02-07 @tab 0.29 @tab 2299 @tab @tab @tab 936 (33) @tab @tab 17 @tab
10390 @item 1996-02-24 @tab 0.30 @tab 2544 @tab @tab @tab 919 (32) @tab 85 (1) @tab 20 @tab 9
10391 @item 1996-03-11 @tab 0.31 @tab 2877 @tab @tab @tab 919 (32) @tab 85 (1) @tab 29 @tab 17
10392 @item 1996-04-27 @tab 0.32 @tab 3058 @tab @tab @tab 921 (31) @tab 85 (1) @tab 30 @tab 26
10393 @item 1996-05-18 @tab 0.33 @tab 3110 @tab @tab @tab 926 (31) @tab 105 (1) @tab 30 @tab 35
10394 @item 1996-05-28 @tab 1.0 @tab 3134 @tab @tab @tab 973 (32) @tab 105 (1) @tab 30 @tab 38
10395 @item 1997-06-22 @tab 1.2 @tab 6089 @tab 385 @tab @tab 1294 (36) @tab 592 (23) @tab 37 @tab 126
10396 @item 1998-04-05 @tab 1.3 @tab 6415 @tab 422 @tab @tab 1470 (39) @tab 741 (26) @tab 39 @tab 156
10397 @item 1999-01-14 @tab 1.4 @tab 7240 @tab 426 @tab @tab 1591 (40) @tab 734 (23) @tab 51 @tab 197
10398 @item 2001-05-08 @tab 1.4-p1 @tab 7251 @tab 426 @tab @tab 1591 (40) @tab 734 (23) @tab 51 @tab 197
10399 @item 2001-05-24 @tab 1.4-p2 @tab 7268 @tab 439 @tab @tab 1591 (40) @tab 734 (23) @tab 49 @tab 197
10400 @item 2001-06-07 @tab 1.4-p3 @tab 7312 @tab 439 @tab @tab 1591 (40) @tab 734 (23) @tab 49 @tab 197
10401 @item 2001-06-10 @tab 1.4-p4 @tab 7321 @tab 439 @tab @tab 1591 (40) @tab 734 (23) @tab 49 @tab 198
10402 @item 2001-07-15 @tab 1.4-p5 @tab 7228 @tab 426 @tab @tab 1596 (40) @tab 734 (23) @tab 51 @tab 198
10403 @item 2001-08-23 @tab 1.5 @tab 8016 @tab 475 @tab 600 @tab 2654 (39) @tab 1166 (32) @tab 63 @tab 327
10404 @item 2002-03-05 @tab 1.6 @tab 8465 @tab 475 @tab 1136 @tab 2732 (39) @tab 1603 (31) @tab 66 @tab 365
10405 @item 2002-04-11 @tab 1.6.1 @tab 8544 @tab 475 @tab 1136 @tab 2741 (39) @tab 1603 (31) @tab 66 @tab 372
10406 @item 2002-06-14 @tab 1.6.2 @tab 8575 @tab 475 @tab 1136 @tab 2800 (39) @tab 1609 (31) @tab 67 @tab 386
10407 @item 2002-07-28 @tab 1.6.3 @tab 8600 @tab 475 @tab 1153 @tab 2809 (39) @tab 1609 (31) @tab 67 @tab 391
10408 @item 2002-07-28 @tab 1.4-p6 @tab 7332 @tab 455 @tab @tab 1596 (40) @tab 735 (24) @tab 49 @tab 197
10409 @item 2002-09-25 @tab 1.7 @tab 9189 @tab 471 @tab 1790 @tab 2965 (39) @tab 1606 (33) @tab 73 @tab 430
10410 @item 2002-10-16 @tab 1.7.1 @tab 9229 @tab 475 @tab 1790 @tab 2977 (39) @tab 1606 (33) @tab 73 @tab 437
10411 @item 2002-12-06 @tab 1.7.2 @tab 9334 @tab 475 @tab 1790 @tab 2988 (39) @tab 1606 (33) @tab 77 @tab 445
10412 @item 2003-02-20 @tab 1.7.3 @tab 9389 @tab 475 @tab 1790 @tab 3023 (39) @tab 1651 (34) @tab 84 @tab 448
10413 @item 2003-04-23 @tab 1.7.4 @tab 9429 @tab 475 @tab 1790 @tab 3031 (39) @tab 1644 (34) @tab 85 @tab 458
10414 @item 2003-05-18 @tab 1.7.5 @tab 9429 @tab 475 @tab 1790 @tab 3033 (39) @tab 1645 (34) @tab 85 @tab 459
10415 @item 2003-07-10 @tab 1.7.6 @tab 9442 @tab 475 @tab 1790 @tab 3033 (39) @tab 1660 (34) @tab 85 @tab 461
10416 @item 2003-09-07 @tab 1.7.7 @tab 9443 @tab 475 @tab 1790 @tab 3041 (39) @tab 1660 (34) @tab 90 @tab 467
10417 @item 2003-10-07 @tab 1.7.8 @tab 9444 @tab 475 @tab 1790 @tab 3041 (39) @tab 1660 (34) @tab 90 @tab 468
10418 @item 2003-11-09 @tab 1.7.9 @tab 9444 @tab 475 @tab 1790 @tab 3048 (39) @tab 1660 (34) @tab 90 @tab 468
10419 @item 2003-12-10 @tab 1.8 @tab 7171 @tab 585 @tab 7730 @tab 3236 (39) @tab 1666 (36) @tab 104 @tab 521
10420 @item 2004-01-11 @tab 1.8.1 @tab 7217 @tab 663 @tab 7726 @tab 3287 (39) @tab 1686 (36) @tab 104 @tab 525
10421 @item 2004-01-12 @tab 1.8.2 @tab 7217 @tab 663 @tab 7726 @tab 3288 (39) @tab 1686 (36) @tab 104 @tab 526
10422 @item 2004-03-07 @tab 1.8.3 @tab 7214 @tab 686 @tab 7735 @tab 3303 (39) @tab 1695 (36) @tab 111 @tab 530
10423 @item 2004-04-25 @tab 1.8.4 @tab 7214 @tab 686 @tab 7736 @tab 3310 (39) @tab 1701 (36) @tab 112 @tab 531
10424 @item 2004-05-16 @tab 1.8.5 @tab 7240 @tab 686 @tab 7736 @tab 3299 (39) @tab 1701 (36) @tab 112 @tab 533
10425 @item 2004-07-28 @tab 1.9 @tab 7508 @tab 715 @tab 7794 @tab 3352 (40) @tab 1812 (37) @tab 115 @tab 551
10426 @item 2004-08-11 @tab 1.9.1 @tab 7512 @tab 715 @tab 7794 @tab 3354 (40) @tab 1812 (37) @tab 115 @tab 552
10427 @item 2004-09-19 @tab 1.9.2 @tab 7512 @tab 715 @tab 7794 @tab 3354 (40) @tab 1812 (37) @tab 132 @tab 554
10431 @c ========================================================== Appendices
10434 @node Copying This Manual
10435 @appendix Copying This Manual
10438 * GNU Free Documentation License:: License for copying this manual
10448 * Macro Index:: Index of Autoconf macros
10449 * Variable Index:: Index of Makefile variables
10450 * General Index:: General index
10454 @appendixsec Macro Index
10458 @node Variable Index
10459 @appendixsec Variable Index
10463 @node General Index
10464 @appendixsec General Index
10473 @c LocalWords: texinfo setfilename settitle setchapternewpage texi direntry
10474 @c LocalWords: dircategory in's aclocal ifinfo titlepage Tromey vskip pt sp
10475 @c LocalWords: filll defcodeindex ov cv op tr syncodeindex fn cp vr ifnottex
10476 @c LocalWords: dir Automake's ac Dist Gnits gnits cygnus dfn Autoconf's pxref
10477 @c LocalWords: cindex Autoconf autoconf perl samp cvs dist trindex SUBST foo
10478 @c LocalWords: xs emph FIXME ref vindex pkglibdir pkgincludedir pkgdatadir mt
10479 @c LocalWords: pkg libdir cpio bindir sbindir rmt pax sbin zar zardir acindex
10480 @c LocalWords: HTML htmldir html noinst TEXINFOS nodist nobase strudel CFLAGS
10481 @c LocalWords: libmumble CC YFLAGS ansi knr itemx de fication config url comp
10482 @c LocalWords: depcomp elisp sh mdate mkinstalldirs mkdir py tex dvi ps pdf
10483 @c LocalWords: ylwrap zardoz INIT gettext acinclude mv FUNCS LIBOBJS LDADD fr
10484 @c LocalWords: uref featureful dnl src LINGUAS es ko nl pl sl sv PROG ISC doc
10485 @c LocalWords: POSIX STDC fcntl FUNC ALLOCA blksize struct stat intl po chmod
10486 @c LocalWords: ChangeLog SUBDIRS gettextize gpl testdata getopt INTLLIBS cpp
10487 @c LocalWords: localedir datadir DLOCALEDIR DEXIT CPPFLAGS autoreconf opindex
10488 @c LocalWords: AUX var symlink deps Wno Wnone package's aclocal's distclean
10489 @c LocalWords: ltmain xref LIBSOURCE LIBSOURCES LIBOBJ MEMCMP vs RANLIB CXX
10490 @c LocalWords: LDFLAGS LIBTOOL libtool XTRA LIBS gettext's acdir APIVERSION
10491 @c LocalWords: dirlist noindent usr MULTILIB multilib Multilibs TIOCGWINSZ sc
10492 @c LocalWords: GWINSZ termios SRCDIR tarball bzip LISPDIR lispdir XEmacs CCAS
10493 @c LocalWords: emacsen MicroEmacs CCASFLAGS UX GCJ gcj GCJFLAGS posix DMALLOC
10494 @c LocalWords: dmalloc ldmalloc REGEX regex rx DEPDIR DEP DEFUN aclocaldir fi
10495 @c LocalWords: mymacro myothermacro AMFLAGS autopoint autogen libtoolize yum
10496 @c LocalWords: autoheader README MAKEFLAGS subdir Inetutils sync COND endif
10497 @c LocalWords: Miller's installable includedir inc pkgdata EXEEXT libexec bsd
10498 @c LocalWords: pkglib libexecdir prog libcpio cpio's dlopen dlpreopen linux
10499 @c LocalWords: subsubsection OBJEXT esac lib LTLIBRARIES liblob LIBADD AR ar
10500 @c LocalWords: ARFLAGS cru ing maude libgettext lo LTLIBOBJS rpath SGI PRE yy
10501 @c LocalWords: libmaude CCLD CXXFLAGS FFLAGS LFLAGS OBJCFLAGS RFLAGS DEFS cc
10502 @c LocalWords: SHORTNAME vtable srcdir nostdinc basename yxx cxx ll lxx gdb
10503 @c LocalWords: lexers yymaxdepth maxdepth yyparse yylex yyerror yylval lval
10504 @c LocalWords: yychar yydebug yypact yyr yydef def yychk chk yypgo pgo yyact
10505 @c LocalWords: yyexca exca yyerrflag errflag yynerrs nerrs yyps yypv pv yys
10506 @c LocalWords: yystate yytmp tmp yyv yyval val yylloc lloc yyreds yytoks toks
10507 @c LocalWords: yylhs yylen yydefred yydgoto yysindex yyrindex yygindex yyname
10508 @c LocalWords: yytable yycheck yyrule byacc CXXCOMPILE CXXLINK FLINK cfortran
10509 @c LocalWords: Catalogue preprocessable FLIBS libfoo baz JAVACFLAGS java exe
10510 @c LocalWords: SunOS fying basenames exeext uninstalled oldinclude kr FSF's
10511 @c LocalWords: pkginclude oldincludedir sysconf sharedstate localstate gcc rm
10512 @c LocalWords: sysconfdir sharedstatedir localstatedir preexist CLEANFILES gz
10513 @c LocalWords: unnumberedsubsec depfile tmpdepfile depmode const interoperate
10514 @c LocalWords: JAVAC javac JAVAROOT builddir CLASSPATH ENV pyc pyo pkgpython
10515 @c LocalWords: pyexecdir pkgpyexecdir Python's pythondir pkgpythondir txi ois
10516 @c LocalWords: installinfo vers MAKEINFO makeinfo MAKEINFOFLAGS noinstall rf
10517 @c LocalWords: mandir thesame alsothesame installman myexecbin DESTDIR Pinard
10518 @c LocalWords: uninstall installdirs uninstalls MOSTLYCLEANFILES mostlyclean
10519 @c LocalWords: DISTCLEANFILES MAINTAINERCLEANFILES gzip'd GZIP gzip shar exp
10520 @c LocalWords: distdir distcheck distcleancheck listfiles distuninstallcheck
10521 @c LocalWords: VPATH tarfile stdout XFAIL DejaGnu dejagnu DEJATOOL runtest ln
10522 @c LocalWords: RUNTESTDEFAULTFLAGS toolchain RUNTESTFLAGS asis readme DVIPS
10523 @c LocalWords: installcheck gzipped tarZ std utils etags mkid multilibbing cd
10524 @c LocalWords: ARGS taggable ETAGSFLAGS lang ctags CTAGSFLAGS GTAGS gtags idl
10525 @c LocalWords: foocc doit idlC multilibs ABIs cmindex defmac ARG enableval FC
10526 @c LocalWords: MSG xtrue DBG pathchk CYGWIN afile proglink versioned CVS's TE
10527 @c LocalWords: wildcards Autoconfiscated subsubheading autotools Meyering API
10528 @c LocalWords: ois's wildcard Wportability cartouche vrindex printindex Duret
10529 @c LocalWords: DSOMEFLAG DVERSION automake Lutz insertcopying versioning FAQ
10530 @c LocalWords: LTLIBOBJ Libtool's libtool's libltdl dlopening itutions libbar
10531 @c LocalWords: WANTEDLIBS libhello sublibraries libtop libsub dlopened Ratfor
10532 @c LocalWords: mymodule timestamps timestamp underquoted MAKEINFOHTMLFLAGS te
10533 @c LocalWords: GNUmakefile buildir Subpackages subpackage's subpackages aux
10534 @c LocalWords: detailmenu Timeline pwd reldir AUTOM autom PREREQ FOOBAR libc
10535 @c LocalWords: libhand subpackage moduleN libmain libmisc FCFLAGS FCCOMPILE
10536 @c LocalWords: FCLINK subst sed ELCFILES elc MAKEINFOHTML dvips esyscmd ustar
10537 @c LocalWords: tarballs Woverride scrdir vfi ELFILES djm AutoMake honkin FSF
10538 @c LocalWords: fileutils precanned MacKenzie's reimplement termutils Tromey's
10539 @c LocalWords: cois gnitsians LIBPROGRAMS progs LIBLIBRARIES Textutils Ulrich
10540 @c LocalWords: Matzigkeit Drepper's Gord Matzigkeit's jm Dalley Debian eg org
10541 @c LocalWords: Administrivia ILU CORBA Sourceware Molenda sourceware Elliston
10542 @c LocalWords: dep Oliva Akim Demaille Aiieeee Demaillator Akim's sourcequake
10543 @c LocalWords: grep backported screenshots libgcj KB unnumberedsubsubsec pre
10544 @c LocalWords: precomputing hacky makedepend inline clearmake LD PRELOAD Rel
10545 @c LocalWords: syscalls perlhist acl pm multitable headitem fdl appendixsec
10546 @c LocalWords: LTALLOCA MALLOC malloc memcmp strdup alloca libcompat xyz DFOO
10547 @c LocalWords: unprefixed buildable preprocessed DBAZ DDATADIR WARNINGCFLAGS
10548 @c LocalWords: LIBFOOCFLAGS LIBFOOLDFLAGS ftable testSubDir obj LIBTOOLFLAGS
10549 @c LocalWords: barexec Pinard's