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 which creates GNU standards-compliant
14 Makefiles from template files. This edition documents version
17 Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
18 2003 Free Software Foundation, Inc.
21 Permission is granted to copy, distribute and/or modify this document
22 under the terms of the @acronym{GNU} Free Documentation License,
23 Version 1.1 or any later version published by the Free Software
24 Foundation; with no Invariant Sections, with the Front-Cover texts
25 being ``A @acronym{GNU} Manual,'' and with the Back-Cover Texts as in
26 (a) below. A copy of the license is included in the section entitled
27 ``@acronym{GNU} Free Documentation License.''
29 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and
30 modify this @acronym{GNU} Manual, like @acronym{GNU} software. Copies
31 published by the Free Software Foundation raise funds for
32 @acronym{GNU} development.''
36 @dircategory Software development
38 * automake: (automake). Making Makefile.in's.
41 @dircategory Individual utilities
43 * aclocal: (automake)Invoking aclocal. Generating aclocal.m4.
48 @subtitle For version @value{VERSION}, @value{UPDATED}
49 @author David MacKenzie
51 @author Alexandre Duret-Lutz
53 @vskip 0pt plus 1filll
57 @c Define an index of configure output variables.
59 @c Define an index of configure variables.
61 @c Define an index of options.
63 @c Define an index of targets.
65 @c Define an index of commands.
68 @c Put the macros and variables into their own index.
69 @c @syncodeindex fn cp
74 @c Put everything else into one index (arbitrarily chosen to be the concept index).
81 @comment node-name, next, previous, up
84 This file documents the GNU Automake package. Automake is a program
85 which creates GNU standards-compliant Makefiles from template files.
86 This edition documents version @value{VERSION}.
89 * Introduction:: Automake's purpose
90 * Generalities:: General ideas
91 * Examples:: Some example packages
92 * Invoking Automake:: Creating a Makefile.in
93 * configure:: Scanning configure.ac or configure.in
94 * Top level:: The top-level Makefile.am
95 * Alternative:: An alternative approach to subdirectories
96 * Rebuilding:: Automatic rebuilding of Makefile
97 * Programs:: Building programs and libraries
98 * Other objects:: Other derived objects
99 * Other GNU Tools:: Other GNU Tools
100 * Documentation:: Building documentation
101 * Install:: What gets installed
102 * Clean:: What gets cleaned
103 * Dist:: What goes in a distribution
104 * Tests:: Support for test suites
105 * Options:: Changing Automake's behavior
106 * Miscellaneous:: Miscellaneous rules
107 * Include:: Including extra files in an Automake template.
108 * Conditionals:: Conditionals
109 * Gnits:: The effect of @code{--gnu} and @code{--gnits}
110 * Cygnus:: The effect of @code{--cygnus}
111 * Extending:: Extending Automake
112 * Distributing:: Distributing the Makefile.in
113 * API versioning:: About compatibility between Automake versions
114 * FAQ:: Frequently Asked Questions
115 * Copying This Manual:: How to make copies of this manual
116 * Indices:: Indices of variables, macros, and concepts
123 @chapter Introduction
125 Automake is a tool for automatically generating @file{Makefile.in}s from
126 files called @file{Makefile.am}. Each @file{Makefile.am} is basically a
127 series of @code{make} variable definitions@footnote{These variables are
128 also called @dfn{make macros} in Make terminology, however in this
129 manual we reserve the term @dfn{macro} for Autoconf's macros.}, with
130 rules being thrown in occasionally. The generated @file{Makefile.in}s
131 are compliant with the GNU Makefile standards.
133 @cindex GNU Makefile standards
135 The GNU Makefile Standards Document
136 (@pxref{Makefile Conventions, , , standards, The GNU Coding Standards})
137 is long, complicated, and subject to change. The goal of Automake is to
138 remove the burden of Makefile maintenance from the back of the
139 individual GNU maintainer (and put it on the back of the Automake
142 The typical Automake input file is simply a series of variable definitions.
143 Each such file is processed to create a @file{Makefile.in}. There
144 should generally be one @file{Makefile.am} per directory of a project.
146 @cindex Constraints of Automake
147 @cindex Automake constraints
149 Automake does constrain a project in certain ways; for instance it
150 assumes that the project uses Autoconf (@pxref{Top, , Introduction,
151 autoconf, The Autoconf Manual}), and enforces certain restrictions on
152 the @file{configure.ac} contents@footnote{Older Autoconf versions used
153 @file{configure.in}. Autoconf 2.50 and greater promotes
154 @file{configure.ac} over @file{configure.in}. The rest of this
155 documentation will refer to @file{configure.ac}, but Automake also
156 supports @file{configure.in} for backward compatibility.}.
158 @cindex Automake requirements
159 @cindex Requirements, Automake
161 Automake requires @code{perl} in order to generate the
162 @file{Makefile.in}s. However, the distributions created by Automake are
163 fully GNU standards-compliant, and do not require @code{perl} in order
166 @cindex BUGS, reporting
167 @cindex Reporting BUGS
168 @cindex E-mail, bug reports
170 Mail suggestions and bug reports for Automake to
171 @email{bug-automake@@gnu.org}.
175 @chapter General ideas
177 The following sections cover a few basic ideas that will help you
178 understand how Automake works.
181 * General Operation:: General operation of Automake
182 * Strictness:: Standards conformance checking
183 * Uniform:: The Uniform Naming Scheme
184 * Canonicalization:: How derived variables are named
185 * User Variables:: Variables reserved for the user
186 * Auxiliary Programs:: Programs automake might require
190 @node General Operation
191 @section General Operation
193 Automake works by reading a @file{Makefile.am} and generating a
194 @file{Makefile.in}. Certain variables and targets defined in the
195 @file{Makefile.am} instruct Automake to generate more specialized code;
196 for instance, a @samp{bin_PROGRAMS} variable definition will cause targets
197 for compiling and linking programs to be generated.
199 @cindex Non-standard targets
200 @cindex cvs-dist, non-standard example
203 The variable definitions and targets in the @file{Makefile.am} are copied
204 verbatim into the generated file. This allows you to add arbitrary code
205 into the generated @file{Makefile.in}. For instance the Automake
206 distribution includes a non-standard @code{cvs-dist} target, which the
207 Automake maintainer uses to make distributions from his source control
210 @cindex GNU make extensions
212 Note that most GNU make extensions are not recognized by Automake. Using
213 such extensions in a @file{Makefile.am} will lead to errors or confusing
216 @cindex Append operator
217 A special exception is that the GNU make append operator, @samp{+=}, is
218 supported. This operator appends its right hand argument to the variable
219 specified on the left. Automake will translate the operator into
220 an ordinary @samp{=} operator; @samp{+=} will thus work with any make program.
222 Automake tries to keep comments grouped with any adjoining targets or
223 variable definitions.
225 @cindex Make targets, overriding
226 @cindex Overriding make targets
228 A target defined in @file{Makefile.am} generally overrides any such
229 target of a similar name that would be automatically generated by
230 @code{automake}. Although this is a supported feature, it is generally
231 best to avoid making use of it, as sometimes the generated rules are
234 @cindex Variables, overriding
235 @cindex Overriding make variables
237 Similarly, a variable defined in @file{Makefile.am} or @code{AC_SUBST}'ed
238 from @file{configure.ac} will override any definition of the variable that
239 @code{automake} would ordinarily create. This feature is more often
240 useful than the ability to override a target definition. Be warned that
241 many of the variables generated by @code{automake} are considered to be for
242 internal use only, and their names might change in future releases.
244 @cindex Recursive operation of Automake
245 @cindex Automake, recursive operation
246 @cindex Example of recursive operation
248 When examining a variable definition, Automake will recursively examine
249 variables referenced in the definition. For example, if Automake is
250 looking at the content of @code{foo_SOURCES} in this snippet
254 foo_SOURCES = c.c $(xs)
257 it would use the files @file{a.c}, @file{b.c}, and @file{c.c} as the
258 contents of @code{foo_SOURCES}.
260 @cindex ## (special Automake comment)
261 @cindex Special Automake comment
262 @cindex Comment, special to Automake
264 Automake also allows a form of comment which is @emph{not} copied into
265 the output; all lines beginning with @samp{##} (leading spaces allowed)
266 are completely ignored by Automake.
268 It is customary to make the first line of @file{Makefile.am} read:
270 @cindex Makefile.am, first line
271 @cindex First line of Makefile.am
274 ## Process this file with automake to produce Makefile.in
277 @c FIXME discuss putting a copyright into Makefile.am here? I would but
278 @c I don't know quite what to say.
280 @c FIXME document customary ordering of Makefile.am here!
286 @cindex Non-GNU packages
288 While Automake is intended to be used by maintainers of GNU packages, it
289 does make some effort to accommodate those who wish to use it, but do
290 not want to use all the GNU conventions.
292 @cindex Strictness, defined
293 @cindex Strictness, foreign
294 @cindex foreign strictness
295 @cindex Strictness, gnu
296 @cindex gnu strictness
297 @cindex Strictness, gnits
298 @cindex gnits strictness
300 To this end, Automake supports three levels of @dfn{strictness}---the
301 strictness indicating how stringently Automake should check standards
304 The valid strictness levels are:
308 Automake will check for only those things which are absolutely
309 required for proper operations. For instance, whereas GNU standards
310 dictate the existence of a @file{NEWS} file, it will not be required in
311 this mode. The name comes from the fact that Automake is intended to be
312 used for GNU programs; these relaxed rules are not the standard mode of
316 Automake will check---as much as possible---for compliance to the GNU
317 standards for packages. This is the default.
320 Automake will check for compliance to the as-yet-unwritten @dfn{Gnits
321 standards}. These are based on the GNU standards, but are even more
322 detailed. Unless you are a Gnits standards contributor, it is
323 recommended that you avoid this option until such time as the Gnits
324 standard is actually published (which may never happen).
327 For more information on the precise implications of the strictness
328 level, see @ref{Gnits}.
330 Automake also has a special ``cygnus'' mode which is similar to
331 strictness but handled differently. This mode is useful for packages
332 which are put into a ``Cygnus'' style tree (e.g., the GCC tree). For
333 more information on this mode, see @ref{Cygnus}.
337 @section The Uniform Naming Scheme
339 @cindex Uniform naming scheme
341 Automake variables generally follow a @dfn{uniform naming scheme} that
342 makes it easy to decide how programs (and other derived objects) are
343 built, and how they are installed. This scheme also supports
344 @code{configure} time determination of what should be built.
346 @cindex _PROGRAMS primary variable
347 @cindex PROGRAMS primary variable
348 @cindex Primary variable, PROGRAMS
349 @cindex Primary variable, defined
351 At @code{make} time, certain variables are used to determine which
352 objects are to be built. The variable names are made of several pieces
353 which are concatenated together.
355 The piece which tells automake what is being built is commonly called
356 the @dfn{primary}. For instance, the primary @code{PROGRAMS} holds a
357 list of programs which are to be compiled and linked.
360 @cindex pkglibdir, defined
361 @cindex pkgincludedir, defined
362 @cindex pkgdatadir, defined
365 @vindex pkgincludedir
368 A different set of names is used to decide where the built objects
369 should be installed. These names are prefixes to the primary which
370 indicate which standard directory should be used as the installation
371 directory. The standard directory names are given in the GNU standards
372 (@pxref{Directory Variables, , , standards, The GNU Coding Standards}).
373 Automake extends this list with @code{pkglibdir}, @code{pkgincludedir},
374 and @code{pkgdatadir}; these are the same as the non-@samp{pkg}
375 versions, but with @samp{$(PACKAGE)} appended. For instance,
376 @code{pkglibdir} is defined as @code{$(libdir)/$(PACKAGE)}.
377 @cvindex PACKAGE, directory
379 @cindex EXTRA_, prepending
381 For each primary, there is one additional variable named by prepending
382 @samp{EXTRA_} to the primary name. This variable is used to list
383 objects which may or may not be built, depending on what
384 @code{configure} decides. This variable is required because Automake
385 must statically know the entire list of objects that may be built in
386 order to generate a @file{Makefile.in} that will work in all cases.
388 @cindex EXTRA_PROGRAMS, defined
389 @cindex Example, EXTRA_PROGRAMS
392 For instance, @code{cpio} decides at configure time which programs are
393 built. Some of the programs are installed in @code{bindir}, and some
394 are installed in @code{sbindir}:
397 EXTRA_PROGRAMS = mt rmt
398 bin_PROGRAMS = cpio pax
399 sbin_PROGRAMS = $(MORE_PROGRAMS)
402 Defining a primary without a prefix as a variable, e.g.,
403 @code{PROGRAMS}, is an error.
405 Note that the common @samp{dir} suffix is left off when constructing the
406 variable names; thus one writes @samp{bin_PROGRAMS} and not
407 @samp{bindir_PROGRAMS}.
409 Not every sort of object can be installed in every directory. Automake
410 will flag those attempts it finds in error.
411 Automake will also diagnose obvious misspellings in directory names.
413 @cindex Extending list of installation directories
414 @cindex Installation directories, extending list
416 Sometimes the standard directories---even as augmented by Automake---
417 are not enough. In particular it is sometimes useful, for clarity, to
418 install objects in a subdirectory of some predefined directory. To this
419 end, Automake allows you to extend the list of possible installation
420 directories. A given prefix (e.g. @samp{zar}) is valid if a variable of
421 the same name with @samp{dir} appended is defined (e.g. @code{zardir}).
423 @cindex HTML installation, example
425 For instance, installation of HTML files is part of Automake, you could
426 use this to install raw HTML documentation:
429 htmldir = $(prefix)/html
430 html_DATA = automake.html
433 @cindex noinst primary prefix, definition
435 The special prefix @samp{noinst} indicates that the objects in question
436 should be built but not installed at all. This is usually used for
437 objects required to build the rest of your package, for instance static
438 libraries (@pxref{A Library}), or helper scripts.
440 @cindex check primary prefix, definition
442 The special prefix @samp{check} indicates that the objects in question
443 should not be built until the @code{make check} command is run. Those
444 objects are not installed either.
446 The current primary names are @samp{PROGRAMS}, @samp{LIBRARIES},
447 @samp{LISP}, @samp{PYTHON}, @samp{JAVA}, @samp{SCRIPTS}, @samp{DATA},
448 @samp{HEADERS}, @samp{MANS}, and @samp{TEXINFOS}.
460 Some primaries also allow additional prefixes which control other
461 aspects of @code{automake}'s behavior. The currently defined prefixes
462 are @samp{dist_}, @samp{nodist_}, and @samp{nobase_}. These prefixes
463 are explained later (@pxref{Program and Library Variables}).
466 @node Canonicalization
467 @section How derived variables are named
469 @cindex canonicalizing Automake variables
471 Sometimes a Makefile variable name is derived from some text the
472 maintainer supplies. For instance, a program name listed in
473 @samp{_PROGRAMS} is rewritten into the name of a @samp{_SOURCES}
474 variable. In cases like this, Automake canonicalizes the text, so that
475 program names and the like do not have to follow Makefile variable naming
476 rules. All characters in the name except for letters, numbers, the
477 strudel (@@), and the underscore are turned into underscores when making
480 For example, if your program is named @code{sniff-glue}, the derived
481 variable name would be @code{sniff_glue_SOURCES}, not
482 @code{sniff-glue_SOURCES}. Similarly the sources for a library named
483 @code{libmumble++.a} should be listed in the
484 @code{libmumble___a_SOURCES} variable.
486 The strudel is an addition, to make the use of Autoconf substitutions in
487 variable names less obfuscating.
491 @section Variables reserved for the user
493 @cindex variables, reserved for the user
494 @cindex user variables
496 Some @code{Makefile} variables are reserved by the GNU Coding Standards
497 for the use of the ``user'' -- the person building the package. For
498 instance, @code{CFLAGS} is one such variable.
500 Sometimes package developers are tempted to set user variables such as
501 @code{CFLAGS} because it appears to make their job easier -- they don't
502 have to introduce a second variable into every target.
504 However, the package itself should never set a user variable,
505 particularly not to include switches which are required for proper
506 compilation of the package. Since these variables are documented as
507 being for the package builder, that person rightfully expects to be able
508 to override any of these variables at build time.
510 To get around this problem, automake introduces an automake-specific
511 shadow variable for each user flag variable. (Shadow variables are not
512 introduced for variables like @code{CC}, where they would make no
513 sense.) The shadow variable is named by prepending @samp{AM_} to the
514 user variable's name. For instance, the shadow variable for
515 @code{YFLAGS} is @code{AM_YFLAGS}.
518 @node Auxiliary Programs
519 @section Programs automake might require
521 @cindex Programs, auxiliary
522 @cindex Auxiliary programs
524 Automake sometimes requires helper programs so that the generated
525 @file{Makefile} can do its work properly. There are a fairly large
526 number of them, and we list them here.
531 These two files are used by the automatic de-ANSI-fication support
535 This is a wrapper for compilers which don't accept both @samp{-c} and
536 @samp{-o} at the same time. It is only used when absolutely required.
537 Such compilers are rare.
541 These programs compute the canonical triplets for the given build, host,
542 or target architecture. These programs are updated regularly to support
543 new architectures and fix probes broken by changes in new kernel
544 versions. You are encouraged to fetch the latest versions of these
545 files from @url{ftp://ftp.gnu.org/gnu/config/} before making a release.
548 This program understands how to run a compiler so that it will generate
549 not only the desired output but also dependency information which is
550 then used by the automatic dependency tracking feature.
553 This program is used to byte-compile Emacs Lisp code.
556 This is a replacement for the @code{install} program which works on
557 platforms where @code{install} is unavailable or unusable.
560 This script is used to generate a @file{version.texi} file. It examines
561 a file and prints some date information about it.
564 This wraps a number of programs which are typically only required by
565 maintainers. If the program in question doesn't exist, @code{missing}
566 prints an informative warning and attempts to fix things so that the
570 This script used to be a wrapper around @code{mkdir -p}, which is not
571 portable. Now we use prefer to use @code{install-sh -d} when configure
572 finds that @code{mkdir -p} does not work, this makes one less script to
575 For backward compatibility @code{mkinstalldirs} is still used and
576 distributed when @code{automake} finds it in a package. But it is no
577 longer installed automatically, and it should be safe to remove it.
580 This is used to byte-compile Python scripts.
583 Not a program, this file is required for @code{make dvi}, @code{make ps}
584 and @code{make pdf} to work when Texinfo sources are in the package.
587 This program wraps @code{lex} and @code{yacc} and ensures that, for
588 instance, multiple @code{yacc} instances can be invoked in a single
589 directory in parallel.
595 @chapter Some example packages
598 * Complete:: A simple example, start to finish
599 * Hello:: A classic program
600 * true:: Building true and false
605 @section A simple example, start to finish
607 @cindex Complete example
609 Let's suppose you just finished writing @code{zardoz}, a program to make
610 your head float from vortex to vortex. You've been using Autoconf to
611 provide a portability framework, but your @file{Makefile.in}s have been
612 ad-hoc. You want to make them bulletproof, so you turn to Automake.
614 @cindex AM_INIT_AUTOMAKE, example use
616 The first step is to update your @file{configure.ac} to include the
617 commands that @code{automake} needs. The way to do this is to add an
618 @code{AM_INIT_AUTOMAKE} call just after @code{AC_INIT}:
626 Since your program doesn't have any complicating factors (e.g., it
627 doesn't use @code{gettext}, it doesn't want to build a shared library),
628 you're done with this part. That was easy!
630 @cindex aclocal program, introduction
631 @cindex aclocal.m4, preexisting
632 @cindex acinclude.m4, defined
634 Now you must regenerate @file{configure}. But to do that, you'll need
635 to tell @code{autoconf} how to find the new macro you've used. The
636 easiest way to do this is to use the @code{aclocal} program to generate
637 your @file{aclocal.m4} for you. But wait@dots{} maybe you already have an
638 @file{aclocal.m4}, because you had to write some hairy macros for your
639 program. The @code{aclocal} program lets you put your own macros into
640 @file{acinclude.m4}, so simply rename and then run:
643 mv aclocal.m4 acinclude.m4
648 @cindex zardoz example
650 Now it is time to write your @file{Makefile.am} for @code{zardoz}.
651 Since @code{zardoz} is a user program, you want to install it where the
652 rest of the user programs go: @code{bindir}. Additionally,
653 @code{zardoz} has some Texinfo documentation. Your @file{configure.ac}
654 script uses @code{AC_REPLACE_FUNCS}, so you need to link against
655 @samp{$(LIBOBJS)}. So here's what you'd write:
658 bin_PROGRAMS = zardoz
659 zardoz_SOURCES = main.c head.c float.c vortex9.c gun.c
660 zardoz_LDADD = $(LIBOBJS)
662 info_TEXINFOS = zardoz.texi
665 Now you can run @code{automake --add-missing} to generate your
666 @file{Makefile.in} and grab any auxiliary files you might need, and
671 @section A classic program
673 @cindex Example, GNU Hello
674 @cindex Hello example
675 @cindex GNU Hello, example
677 @uref{ftp://prep.ai.mit.edu/pub/gnu/hello-1.3.tar.gz, GNU hello} is
678 renowned for its classic simplicity and versatility. This section shows
679 how Automake could be used with the GNU Hello package. The examples
680 below are from the latest beta version of GNU Hello, but with all of the
681 maintainer-only code stripped out, as well as all copyright comments.
683 Of course, GNU Hello is somewhat more featureful than your traditional
684 two-liner. GNU Hello is internationalized, does option processing, and
685 has a manual and a test suite.
687 @cindex configure.ac, from GNU Hello
688 @cindex GNU Hello, configure.ac
689 @cindex Hello, configure.ac
691 Here is the @file{configure.ac} from GNU Hello.
692 @strong{Please note:} The calls to @code{AC_INIT} and @code{AM_INIT_AUTOMAKE}
693 in this example use a deprecated syntax. For the current approach,
694 see the description of @code{AM_INIT_AUTOMAKE} in @ref{Public macros}.
696 @c FIXME: This definitely requires an update, e.g. to GNU Hello 2.1.1.
699 dnl Process this file with autoconf to produce a configure script.
701 AM_INIT_AUTOMAKE(hello, 1.3.11)
702 AM_CONFIG_HEADER(config.h)
704 dnl Set of available languages.
705 ALL_LINGUAS="de fr es ko nl no pl pt sl sv"
707 dnl Checks for programs.
711 dnl Checks for libraries.
713 dnl Checks for header files.
715 AC_HAVE_HEADERS(string.h fcntl.h sys/file.h sys/param.h)
717 dnl Checks for library functions.
720 dnl Check for st_blksize in struct stat
723 dnl internationalization macros
725 AC_OUTPUT([Makefile doc/Makefile intl/Makefile po/Makefile.in \
726 src/Makefile tests/Makefile tests/hello],
727 [chmod +x tests/hello])
730 The @samp{AM_} macros are provided by Automake (or the Gettext library);
731 the rest are standard Autoconf macros.
734 The top-level @file{Makefile.am}:
737 EXTRA_DIST = BUGS ChangeLog.O
738 SUBDIRS = doc intl po src tests
741 As you can see, all the work here is really done in subdirectories.
743 The @file{po} and @file{intl} directories are automatically generated
744 using @code{gettextize}; they will not be discussed here.
746 @cindex Texinfo file handling example
747 @cindex Example, handling Texinfo files
749 In @file{doc/Makefile.am} we see:
752 info_TEXINFOS = hello.texi
753 hello_TEXINFOS = gpl.texi
756 This is sufficient to build, install, and distribute the GNU Hello
759 @cindex Regression test example
760 @cindex Example, regression test
762 Here is @file{tests/Makefile.am}:
766 EXTRA_DIST = hello.in testdata
769 The script @file{hello} is generated by @code{configure}, and is the
770 only test case. @code{make check} will run this test.
772 @cindex INCLUDES, example usage
774 Last we have @file{src/Makefile.am}, where all the real work is done:
775 @c FIXME: As all the Hello World excerpts in this manual, this
776 @c shows deprecated features (here: $(INCLUDES)).
780 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
781 hello_LDADD = $(INTLLIBS) $(ALLOCA)
782 localedir = $(datadir)/locale
783 INCLUDES = -I../intl -DLOCALEDIR=\"$(localedir)\"
788 @section Building true and false
790 @cindex Example, false and true
791 @cindex false Example
794 Here is another, trickier example. It shows how to generate two
795 programs (@code{true} and @code{false}) from the same source file
796 (@file{true.c}). The difficult part is that each compilation of
797 @file{true.c} requires different @code{cpp} flags.
800 bin_PROGRAMS = true false
802 false_LDADD = false.o
805 $(COMPILE) -DEXIT_CODE=0 -c true.c
808 $(COMPILE) -DEXIT_CODE=1 -o false.o -c true.c
811 Note that there is no @code{true_SOURCES} definition. Automake will
812 implicitly assume that there is a source file named @file{true.c}, and
813 define rules to compile @file{true.o} and link @file{true}. The
814 @code{true.o: true.c} rule supplied by the above @file{Makefile.am},
815 will override the Automake generated rule to build @file{true.o}.
817 @code{false_SOURCES} is defined to be empty---that way no implicit value
818 is substituted. Because we have not listed the source of
819 @file{false}, we have to tell Automake how to link the program. This is
820 the purpose of the @code{false_LDADD} line. A @code{false_DEPENDENCIES}
821 variable, holding the dependencies of the @file{false} target will be
822 automatically generated by Automake from the content of
825 The above rules won't work if your compiler doesn't accept both
826 @samp{-c} and @samp{-o}. The simplest fix for this is to introduce a
827 bogus dependency (to avoid problems with a parallel @code{make}):
830 true.o: true.c false.o
831 $(COMPILE) -DEXIT_CODE=0 -c true.c
834 $(COMPILE) -DEXIT_CODE=1 -c true.c && mv true.o false.o
837 Also, these explicit rules do not work if the de-ANSI-fication feature
838 is used (@pxref{ANSI}). Supporting de-ANSI-fication requires a little
842 true._o: true._c false.o
843 $(COMPILE) -DEXIT_CODE=0 -c true.c
846 $(COMPILE) -DEXIT_CODE=1 -c true.c && mv true._o false.o
849 As it turns out, there is also a much easier way to do this same task.
850 Some of the above techniques are useful enough that we've kept the
851 example in the manual. However if you were to build @code{true} and
852 @code{false} in real life, you would probably use per-program
853 compilation flags, like so:
856 bin_PROGRAMS = false true
858 false_SOURCES = true.c
859 false_CPPFLAGS = -DEXIT_CODE=1
861 true_SOURCES = true.c
862 true_CPPFLAGS = -DEXIT_CODE=0
865 In this case Automake will cause @file{true.c} to be compiled twice,
866 with different flags. De-ANSI-fication will work automatically. In
867 this instance, the names of the object files would be chosen by
868 automake; they would be @file{false-true.o} and @file{true-true.o}.
869 (The name of the object files rarely matters.)
872 @node Invoking Automake
873 @chapter Creating a @file{Makefile.in}
875 @cindex Multiple configure.ac files
876 @cindex Invoking Automake
877 @cindex Automake, invoking
879 To create all the @file{Makefile.in}s for a package, run the
880 @code{automake} program in the top level directory, with no arguments.
881 @code{automake} will automatically find each appropriate
882 @file{Makefile.am} (by scanning @file{configure.ac}; @pxref{configure})
883 and generate the corresponding @file{Makefile.in}. Note that
884 @code{automake} has a rather simplistic view of what constitutes a
885 package; it assumes that a package has only one @file{configure.ac}, at
886 the top. If your package has multiple @file{configure.ac}s, then you
887 must run @code{automake} in each directory holding a
888 @file{configure.ac}. (Alternatively, you may rely on Autoconf's
889 @code{autoreconf}, which is able to recurse your package tree and run
890 @code{automake} where appropriate.)
892 You can optionally give @code{automake} an argument; @file{.am} is
893 appended to the argument and the result is used as the name of the input
894 file. This feature is generally only used to automatically rebuild an
895 out-of-date @file{Makefile.in}. Note that @code{automake} must always
896 be run from the topmost directory of a project, even if being used to
897 regenerate the @file{Makefile.in} in some subdirectory. This is
898 necessary because @code{automake} must scan @file{configure.ac}, and
899 because @code{automake} uses the knowledge that a @file{Makefile.in} is
900 in a subdirectory to change its behavior in some cases.
903 Automake will run @code{autoconf} to scan @file{configure.ac} and its
904 dependencies (@file{aclocal.m4}), therefore @code{autoconf} must be in
905 your @code{PATH}. If there is an @code{AUTOCONF} variable in your
906 environment it will be used instead of @code{autoconf}, this allows you
907 to select a particular version of Autoconf. By the way, don't
908 misunderstand this paragraph: Automake runs @code{autoconf} to
909 @strong{scan} your @file{configure.ac}, this won't build
910 @file{configure} and you still have to run @code{autoconf} yourself for
913 @cindex Automake options
914 @cindex Options, Automake
915 @cindex Strictness, command line
917 @code{automake} accepts the following options:
919 @cindex Extra files distributed with Automake
920 @cindex Files distributed with Automake
927 @opindex --add-missing
928 Automake requires certain common files to exist in certain situations;
929 for instance @file{config.guess} is required if @file{configure.ac} runs
930 @code{AC_CANONICAL_HOST}. Automake is distributed with several of these
931 files (@pxref{Auxiliary Programs}); this option will cause the missing
932 ones to be automatically added to the package, whenever possible. In
933 general if Automake tells you a file is missing, try using this option.
934 By default Automake tries to make a symbolic link pointing to its own
935 copy of the missing file; this can be changed with @code{--copy}.
937 Many of the potentially-missing files are common scripts whose
938 location may be specified via the @code{AC_CONFIG_AUX_DIR} macro.
939 Therefore, @code{AC_CONFIG_AUX_DIR}'s setting affects whether a
940 file is considered missing, and where the missing file is added
943 @item --libdir=@var{dir}
945 Look for Automake data files in directory @var{dir} instead of in the
946 installation directory. This is typically used for debugging.
952 When used with @code{--add-missing}, causes installed files to be
953 copied. The default is to make a symbolic link.
957 Causes the generated @file{Makefile.in}s to follow Cygnus rules, instead
958 of GNU or Gnits rules. For more information, see @ref{Cygnus}.
962 @itemx --force-missing
963 @opindex --force-missing
964 When used with @code{--add-missing}, causes standard files to be reinstalled
965 even if they already exist in the source tree. This involves removing
966 the file from the source tree before creating the new symlink (or, with
967 @code{--copy}, copying the new file).
971 Set the global strictness to @samp{foreign}. For more information, see
976 Set the global strictness to @samp{gnits}. For more information, see
981 Set the global strictness to @samp{gnu}. For more information, see
982 @ref{Gnits}. This is the default strictness.
986 Print a summary of the command line options and exit.
991 This disables the dependency tracking feature in generated
992 @file{Makefile}s; see @ref{Dependencies}.
995 @opindex --include-deps
996 This enables the dependency tracking feature. This feature is enabled
997 by default. This option is provided for historical reasons only and
998 probably should not be used.
1002 Ordinarily @code{automake} creates all @file{Makefile.in}s mentioned in
1003 @file{configure.ac}. This option causes it to only update those
1004 @file{Makefile.in}s which are out of date with respect to one of their
1008 @itemx --output-dir=@var{dir}
1010 @opindex --output-dir
1011 Put the generated @file{Makefile.in} in the directory @var{dir}.
1012 Ordinarily each @file{Makefile.in} is created in the directory of the
1013 corresponding @file{Makefile.am}. This option is deprecated and will be
1014 removed in a future release.
1020 Cause Automake to print information about which files are being read or
1025 Print the version number of Automake and exit.
1028 @item --warnings=@var{category}
1031 Output warnings falling in @var{category}. @var{category} can be
1035 warnings related to the GNU Coding Standards
1036 (@pxref{Top, , , standards, The GNU Coding Standards}).
1038 obsolete features or constructions
1040 user redefinitions of Automake rules or variables
1042 portability issues (e.g., use of Make features which are known not portable)
1044 weird syntax, unused variables, typos
1046 unsupported or incomplete features
1050 turn off all the warnings
1052 treat warnings as errors
1055 A category can be turned off by prefixing its name with @samp{no-}. For
1056 instance @samp{-Wno-syntax} will hide the warnings about unused
1059 The categories output by default are @samp{syntax} and
1060 @samp{unsupported}. Additionally, @samp{gnu} is enabled in @samp{--gnu} and
1061 @samp{--gnits} strictness.
1063 @samp{portability} warnings are currently disabled by default, but they
1064 will be enabled in @samp{--gnu} and @samp{--gnits} strictness in a
1068 The environment variable @samp{WARNINGS} can contain a comma separated
1069 list of categories to enable. It will be taken into account before the
1070 command-line switches, this way @samp{-Wnone} will also ignore any
1071 warning category enabled by @samp{WARNINGS}. This variable is also used
1072 by other tools like @command{autoconf}; unknown categories are ignored
1079 @chapter Scanning @file{configure.ac}
1081 @cindex configure.ac, scanning
1082 @cindex Scanning configure.ac
1084 Automake scans the package's @file{configure.ac} to determine certain
1085 information about the package. Some @code{autoconf} macros are required
1086 and some variables must be defined in @file{configure.ac}. Automake
1087 will also use information from @file{configure.ac} to further tailor its
1090 Automake also supplies some Autoconf macros to make the maintenance
1091 easier. These macros can automatically be put into your
1092 @file{aclocal.m4} using the @code{aclocal} program.
1095 * Requirements:: Configuration requirements
1096 * Optional:: Other things Automake recognizes
1097 * Invoking aclocal:: Auto-generating aclocal.m4
1098 * aclocal options:: aclocal command line arguments
1099 * Macro search path:: Modifying aclocal's search path
1100 * Macros:: Autoconf macros supplied with Automake
1101 * Extending aclocal:: Writing your own aclocal macros
1102 * Local Macros:: Organizing local macros
1103 * Future of aclocal:: aclocal's scheduled death
1108 @section Configuration requirements
1110 @cindex Automake requirements
1111 @cindex Requirements of Automake
1113 The one real requirement of Automake is that your @file{configure.ac}
1114 call @code{AM_INIT_AUTOMAKE}. This macro does several things which are
1115 required for proper Automake operation (@pxref{Macros}).
1116 @cvindex AM_INIT_AUTOMAKE
1118 Here are the other macros which Automake requires but which are not run
1119 by @code{AM_INIT_AUTOMAKE}:
1122 @item AC_CONFIG_FILES
1124 Automake uses these to determine which files to create (@pxref{Output, ,
1125 Creating Output Files, autoconf, The Autoconf Manual}). A listed file
1126 is considered to be an Automake generated @file{Makefile} if there
1127 exists a file with the same name and the @file{.am} extension appended.
1128 Typically, @code{AC_CONFIG_FILES([foo/Makefile])} will cause Automake to
1129 generate @file{foo/Makefile.in} if @file{foo/Makefile.am} exists.
1131 When using @code{AC_CONFIG_FILES} with multiple input files, as in
1132 @code{AC_CONFIG_FILES([Makefile:top.in:Makefile.in:bot.in])}, Automake
1133 will generate the first @file{.in} input file for which a @file{.am}
1134 file exists. If no such file exists the output file is not considered
1135 to be Automake generated.
1137 Files created by @code{AC_CONFIG_FILES} are removed by @code{make distclean}.
1138 @cvindex AC_CONFIG_FILES
1144 @section Other things Automake recognizes
1146 @cindex Macros Automake recognizes
1147 @cindex Recognized macros by Automake
1149 Every time Automake is run it calls Autoconf to trace
1150 @file{configure.ac}. This way it can recognize the use of certain
1151 macros and tailor the generated @file{Makefile.in} appropriately.
1152 Currently recognized macros and their effects are:
1155 @item AC_CONFIG_HEADERS
1156 Automake will generate rules to rebuild these headers. Older versions
1157 of Automake required the use of @code{AM_CONFIG_HEADER}
1158 (@pxref{Macros}); this is no longer the case today.
1159 @cvindex AC_CONFIG_HEADERS
1161 @item AC_CONFIG_LINKS
1162 Automake will generate rules to remove @file{configure} generated links on
1163 @code{make distclean} and to distribute named source files as part of
1165 @cvindex AC_CONFIG_LINKS
1167 @item AC_CONFIG_AUX_DIR
1168 Automake will look for various helper scripts, such as
1169 @file{install-sh}, in the directory named in this macro invocation.
1170 @c This list is accurate relative to version 1.8
1171 (The full list of scripts is: @file{config.guess}, @file{config.sub},
1172 @file{depcomp}, @file{elisp-comp}, @file{compile}, @file{install-sh},
1173 @file{ltmain.sh}, @file{mdate-sh}, @file{missing}, @file{mkinstalldirs},
1174 @file{py-compile}, @file{texinfo.tex}, and @file{ylwrap}.) Not all
1175 scripts are always searched for; some scripts will only be sought if the
1176 generated @file{Makefile.in} requires them.
1177 @cvindex AC_CONFIG_AUX_DIR
1179 If @code{AC_CONFIG_AUX_DIR} is not given, the scripts are looked for in
1180 their @samp{standard} locations. For @file{mdate-sh},
1181 @file{texinfo.tex}, and @file{ylwrap}, the standard location is the
1182 source directory corresponding to the current @file{Makefile.am}. For
1183 the rest, the standard location is the first one of @file{.}, @file{..},
1184 or @file{../..} (relative to the top source directory) that provides any
1185 one of the helper scripts. @xref{Input, , Finding `configure' Input,
1186 autoconf, The Autoconf Manual}.
1188 Required files from @code{AC_CONFIG_AUX_DIR} are automatically
1189 distributed, even if there is no @file{Makefile.am} in this directory.
1191 @item AC_CANONICAL_HOST
1192 Automake will ensure that @file{config.guess} and @file{config.sub}
1193 exist. Also, the @file{Makefile} variables @samp{host_alias} and
1194 @samp{host_triplet} are introduced. See @ref{Canonicalizing, ,
1195 Getting the Canonical System Type, autoconf, The Autoconf Manual}.
1196 @cvindex AC_CANONICAL_HOST
1198 @vindex host_triplet
1200 @item AC_CANONICAL_SYSTEM
1201 This is similar to @code{AC_CANONICAL_HOST}, but also defines the
1202 @file{Makefile} variables @samp{build_alias} and @samp{target_alias}.
1203 @xref{Canonicalizing, , Getting the Canonical System Type, autoconf, The
1205 @cvindex AC_CANONICAL_SYSTEM
1207 @vindex target_alias
1210 @itemx AC_LIBSOURCES
1212 Automake will automatically distribute any file listed in
1213 @code{AC_LIBSOURCE} or @code{AC_LIBSOURCES}.
1215 Note that the @code{AC_LIBOBJ} macro calls @code{AC_LIBSOURCE}. So if
1216 an Autoconf macro is documented to call @code{AC_LIBOBJ([file])}, then
1217 @file{file.c} will be distributed automatically by Automake. This
1218 encompasses many macros like @code{AC_FUNC_ALLOCA},
1219 @code{AC_FUNC_MEMCMP}, @code{AC_REPLACE_FUNCS}, and others.
1221 @cvindex AC_LIBSOURCE
1222 @cvindex AC_LIBSOURCES
1224 By the way, direct assignments to @code{LIBOBJS} are no longer
1225 supported. You should always use @code{AC_LIBOBJ} for this purpose.
1226 @xref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ} vs. @code{LIBOBJS},
1227 autoconf, The Autoconf Manual}.
1230 @item AC_PROG_RANLIB
1231 This is required if any libraries are built in the package.
1232 @xref{Particular Programs, , Particular Program Checks, autoconf, The
1234 @cvindex AC_PROG_RANLIB
1237 This is required if any C++ source is included. @xref{Particular
1238 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
1239 @cvindex AC_PROG_CXX
1242 This is required if any Fortran 77 source is included. This macro is
1243 distributed with Autoconf version 2.13 and later. @xref{Particular
1244 Programs, , Particular Program Checks, autoconf, The Autoconf Manual}.
1245 @cvindex AC_PROG_F77
1247 @item AC_F77_LIBRARY_LDFLAGS
1248 This is required for programs and shared libraries that are a mixture of
1249 languages that include Fortran 77 (@pxref{Mixing Fortran 77 With C and
1250 C++}). @xref{Macros, , Autoconf macros supplied with Automake}.
1251 @cvindex AC_F77_LIBRARY_LDFLAGS
1253 @item AC_PROG_LIBTOOL
1254 Automake will turn on processing for @code{libtool} (@pxref{Top, ,
1255 Introduction, libtool, The Libtool Manual}).
1256 @cvindex AC_PROG_LIBTOOL
1259 If a Yacc source file is seen, then you must either use this macro or
1260 define the variable @samp{YACC} in @file{configure.ac}. The former is
1261 preferred (@pxref{Particular Programs, , Particular Program Checks,
1262 autoconf, The Autoconf Manual}).
1263 @cvindex AC_PROG_YACC
1267 If a Lex source file is seen, then this macro must be used.
1268 @xref{Particular Programs, , Particular Program Checks, autoconf, The
1270 @cvindex AC_PROG_LEX
1274 The first argument is automatically defined as a variable in each
1275 generated @file{Makefile.in}. @xref{Setting Output Variables, , Setting
1276 Output Variables, autoconf, The Autoconf Manual}.
1278 If the Autoconf manual says that a macro calls @code{AC_SUBST} for
1279 @var{var}, or defines the output variable @var{var} then @var{var} will
1280 be defined in each @file{Makefile.in} generated by Automake.
1281 E.g. @code{AC_PATH_XTRA} defines @code{X_CFLAGS} and @code{X_LIBS}, so
1282 you can use these variables in any @file{Makefile.am} if
1283 @code{AC_PATH_XTRA} is called.
1285 @item AM_C_PROTOTYPES
1286 This is required when using automatic de-ANSI-fication; see @ref{ANSI}.
1287 @cvindex AM_C_PROTOTYPES
1289 @item AM_GNU_GETTEXT
1290 This macro is required for packages which use GNU gettext
1291 (@pxref{gettext}). It is distributed with gettext. If Automake sees
1292 this macro it ensures that the package meets some of gettext's
1294 @cvindex AM_GNU_GETTEXT
1296 @item AM_MAINTAINER_MODE
1297 @opindex --enable-maintainer-mode
1298 This macro adds a @samp{--enable-maintainer-mode} option to
1299 @code{configure}. If this is used, @code{automake} will cause
1300 @samp{maintainer-only} rules to be turned off by default in the
1301 generated @file{Makefile.in}s. This macro defines the
1302 @samp{MAINTAINER_MODE} conditional, which you can use in your own
1304 @cvindex AM_MAINTAINER_MODE
1308 Files included by @file{configure.ac} using this macro will be
1309 detected by Automake and automatically distributed. They will also
1310 appear as dependencies in @file{Makefile} rules.
1312 @code{m4_include} is seldom used by @file{configure.ac} authors, but
1313 can appear in @file{aclocal.m4} when @command{aclocal} detects that
1314 some required macros come from files local to your package (as
1315 opposed to macros installed in a system-wide directory, see
1316 @ref{Invoking aclocal}).
1321 @node Invoking aclocal
1322 @section Auto-generating aclocal.m4
1324 @cindex Invoking aclocal
1325 @cindex aclocal, Invoking
1327 Automake includes a number of Autoconf macros which can be used in
1328 your package (@pxref{Macros}); some of them are actually required by
1329 Automake in certain situations. These macros must be defined in your
1330 @file{aclocal.m4}; otherwise they will not be seen by
1333 The @command{aclocal} program will automatically generate
1334 @file{aclocal.m4} files based on the contents of @file{configure.ac}.
1335 This provides a convenient way to get Automake-provided macros,
1336 without having to search around. The @command{aclocal} mechanism
1337 allows other packages to supply their own macros (@pxref{Extending
1338 aclocal}). You can also use it to maintain your own set of custom
1339 macros (@pxref{Local Macros}).
1341 At startup, @command{aclocal} scans all the @file{.m4} files it can
1342 find, looking for macro definitions (@pxref{Macro search path}). Then
1343 it scans @file{configure.ac}. Any mention of one of the macros found
1344 in the first step causes that macro, and any macros it in turn
1345 requires, to be put into @file{aclocal.m4}.
1347 @emph{Putting} the file that contains the macro definition into
1348 @file{aclocal.m4} is usually done by copying the entire text of this
1349 file, including unused macro definitions as well as both @samp{#} and
1350 @samp{dnl} comments. If you want to make a comment which will be
1351 completely ignored by @command{aclocal}, use @samp{##} as the comment
1354 When @command{aclocal} detects that the file containing the macro
1355 definition is in a subdirectory of your package, it will use
1356 @code{m4_include} instead of copying it; this makes the package
1357 smaller and eases dependency tracking. This only works if the
1358 subdirectory containing the macro was specified as a relative search
1359 path with @command{aclocal}'s @code{-I} argument. (@pxref{Local
1360 Macros} for an example.) Any macro which is found in a system-wide
1361 directory, or via an absolute search path will be copied.
1363 The contents of @file{acinclude.m4}, if it exists, are also
1364 automatically included in @file{aclocal.m4}. We recommend against
1365 using @file{acinclude.m4} in new packages (@pxref{Local Macros}).
1368 While computing @file{aclocal.m4}, @code{aclocal} runs @code{autom4te}
1369 (@pxref{Using autom4te, , Using @code{Autom4te}, autoconf, The
1370 Autoconf Manual}) in order to trace the macros which are really used,
1371 and omit from @file{aclocal.m4} all macros which are mentioned but
1372 otherwise unexpanded (this can happen when a macro is called
1373 conditionally). @code{autom4te} is expected to be in the @code{PATH},
1374 just as @code{autoconf}. Its location can be overridden using the
1375 @code{AUTOM4TE} environment variable.
1378 * aclocal options:: Options supported by aclocal
1379 * Macro search path:: How aclocal finds .m4 files
1382 @node aclocal options
1383 @section aclocal options
1385 @cindex aclocal, Options
1386 @cindex Options, aclocal
1388 @code{aclocal} accepts the following options:
1391 @item --acdir=@var{dir}
1393 Look for the macro files in @var{dir} instead of the installation
1394 directory. This is typically used for debugging.
1398 Print a summary of the command line options and exit.
1402 Add the directory @var{dir} to the list of directories searched for
1407 Always overwrite the output file. The default is to overwrite the output
1408 file only when really needed, i.e., when its contents changes or if one
1409 of its dependencies is younger.
1411 @item --output=@var{file}
1413 Cause the output to be put into @var{file} instead of @file{aclocal.m4}.
1415 @item --print-ac-dir
1416 @opindex --print-ac-dir
1417 Prints the name of the directory which @code{aclocal} will search to
1418 find third-party @file{.m4} files. When this option is given, normal
1419 processing is suppressed. This option can be used by a package to
1420 determine where to install a macro file.
1424 Print the names of the files it examines.
1428 Print the version number of Automake and exit.
1431 @node Macro search path
1432 @section Macro search path
1434 @cindex Macro search path
1435 @cindex aclocal search path
1437 By default, @command{aclocal} searches for @file{.m4} files in the following
1438 directories, in this order:
1441 @item @var{acdir-APIVERSION}
1442 This is where the @file{.m4} macros distributed with automake itself
1443 are stored. @var{APIVERSION} depends on the automake release used;
1444 for automake 1.6.x, @var{APIVERSION} = @code{1.6}.
1447 This directory is intended for third party @file{.m4} files, and is
1448 configured when @command{automake} itself is built. This is
1449 @file{@@datadir@@/aclocal/}, which typically
1450 expands to @file{$@{prefix@}/share/aclocal/}. To find the compiled-in
1451 value of @var{acdir}, use the @code{--print-ac-dir} option
1452 (@pxref{aclocal options}).
1455 As an example, suppose that automake-1.6.2 was configured with
1456 @code{--prefix=/usr/local}. Then, the search path would be:
1459 @item @file{/usr/local/share/aclocal-1.6/}
1460 @item @file{/usr/local/share/aclocal/}
1463 As explained in (@pxref{aclocal options}), there are several options that
1464 can be used to change or extend this search path.
1466 @subsection Modifying the macro search path: @code{--acdir}
1468 The most obvious option to modify the search path is
1469 @code{--acdir=@var{dir}}, which changes default directory and
1470 drops the @var{APIVERSION} directory. For example, if one specifies
1471 @code{--acdir=/opt/private/}, then the search path becomes:
1474 @item @file{/opt/private/}
1477 Note that this option, @code{--acdir}, is intended for use
1478 by the internal automake test suite only; it is not ordinarily
1479 needed by end-users.
1481 @subsection Modifying the macro search path: @code{-I @var{dir}}
1483 Any extra directories specified using @code{-I} options
1484 (@pxref{aclocal options}) are @emph{prepended} to this search list. Thus,
1485 @code{aclocal -I /foo -I /bar} results in the following search path:
1490 @item @var{acdir}-@var{APIVERSION}
1494 @subsection Modifying the macro search path: @file{dirlist}
1495 @cindex @file{dirlist}
1497 There is a third mechanism for customizing the search path. If a
1498 @file{dirlist} file exists in @var{acdir}, then that file is assumed to
1499 contain a list of directories, one per line, to be added to the search
1500 list. These directories are searched @emph{after} all other
1503 For example, suppose
1504 @file{@var{acdir}/dirlist} contains the following:
1512 and that @code{aclocal} was called with the @code{-I /foo -I /bar} options.
1513 Then, the search path would be
1518 @item @var{acdir}-@var{APIVERSION}
1524 If the @code{--acdir=@var{dir}} option is used, then @command{aclocal}
1525 will search for the @file{dirlist} file in @var{dir}. In the
1526 @code{--acdir=/opt/private/} example above, @command{aclocal} would look
1527 for @file{/opt/private/dirlist}. Again, however, the @code{--acdir}
1528 option is intended for use by the internal automake test suite only;
1529 @code{--acdir} is not ordinarily needed by end-users.
1531 @file{dirlist} is useful in the following situation: suppose that
1532 @code{automake} version @code{1.6.2} is installed with
1533 $prefix=/usr by the system vendor. Thus, the default search
1537 @item @file{/usr/share/aclocal-1.6/}
1538 @item @file{/usr/share/aclocal/}
1541 However, suppose further that many packages have been manually
1542 installed on the system, with $prefix=/usr/local, as is typical.
1543 In that case, many of these ``extra'' @file{.m4} files are in
1544 @file{/usr/local/share/aclocal}. The only way to force
1545 @file{/usr/bin/aclocal} to find these ``extra'' @file{.m4} files
1546 is to always call @code{aclocal -I /usr/local/share/aclocal}.
1547 This is inconvenient. With @file{dirlist}, one may create the file
1549 @file{/usr/share/aclocal/dirlist}
1552 which contains only the single line
1554 @file{/usr/local/share/aclocal}
1556 Now, the ``default'' search path on the affected system is
1559 @item @file{/usr/share/aclocal-1.6/}
1560 @item @file{/usr/share/aclocal/}
1561 @item @file{/usr/local/share/aclocal/}
1564 without the need for @code{-I} options; @code{-I} options can be reserved
1565 for project-specific needs (@file{my-source-dir/m4/}), rather than
1566 using it to work around local system-dependent tool installation
1569 Similarly, @file{dirlist} can be handy if you have installed a local
1570 copy Automake on your account and want @command{aclocal} to look for
1571 macros installed at other places on the system.
1575 @section Autoconf macros supplied with Automake
1577 Automake ships with several Autoconf macros that you can use from your
1578 @file{configure.ac}. When you use one of them it will be included by
1579 @code{aclocal} in @file{aclocal.m4}.
1582 * Public macros:: Macros that you can use.
1583 * Private macros:: Macros that you should not use.
1586 @c consider generating the following subsections automatically from m4 files.
1589 @subsection Public macros
1592 @item AM_CONFIG_HEADER
1593 Automake will generate rules to automatically regenerate the config
1594 header. This obsolete macro is a synonym of @code{AC_CONFIG_HEADERS}
1595 today (@pxref{Optional}).
1596 @cvindex AM_CONFIG_HEADER
1598 @item AM_ENABLE_MULTILIB
1599 This is used when a ``multilib'' library is being built. The first
1600 optional argument is the name of the @file{Makefile} being generated; it
1601 defaults to @samp{Makefile}. The second option argument is used to find
1602 the top source directory; it defaults to the empty string (generally
1603 this should not be used unless you are familiar with the internals).
1606 @item AM_C_PROTOTYPES
1607 Check to see if function prototypes are understood by the compiler. If
1608 so, define @samp{PROTOTYPES} and set the output variables @samp{U} and
1609 @samp{ANSI2KNR} to the empty string. Otherwise, set @samp{U} to
1610 @samp{_} and @samp{ANSI2KNR} to @samp{./ansi2knr}. Automake uses these
1611 values to implement automatic de-ANSI-fication.
1612 @cvindex AM_C_PROTOTYPES
1614 @item AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
1615 If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then
1616 define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be
1617 found in @file{<termios.h>}.
1618 @cvindex AM_HEADER_TIOCGWINSZ_NEEDS_SYS_IOCTL
1620 @item AM_INIT_AUTOMAKE([OPTIONS])
1621 @itemx AM_INIT_AUTOMAKE(PACKAGE, VERSION, [NO-DEFINE])
1622 Runs many macros required for proper operation of the generated Makefiles.
1624 This macro has two forms, the first of which is preferred.
1625 In this form, @code{AM_INIT_AUTOMAKE} is called with a
1626 single argument --- a space-separated list of Automake options which should
1627 be applied to every @file{Makefile.am} in the tree. The effect is as if
1628 each option were listed in @code{AUTOMAKE_OPTIONS}.
1630 The second, deprecated, form of @code{AM_INIT_AUTOMAKE} has two required
1631 arguments: the package and the version number. This form is
1632 obsolete because the @var{package} and @var{version} can be obtained
1633 from Autoconf's @code{AC_INIT} macro (which itself has an old and a new
1636 If your @file{configure.ac} has:
1639 AM_INIT_AUTOMAKE(mumble, 1.5)
1641 you can modernize it as follows:
1643 AC_INIT(mumble, 1.5)
1644 AC_CONFIG_SRCDIR(src/foo.c)
1648 Note that if you're upgrading your @file{configure.ac} from an earlier
1649 version of Automake, it is not always correct to simply move the package
1650 and version arguments from @code{AM_INIT_AUTOMAKE} directly to
1651 @code{AC_INIT}, as in the example above. The first argument to
1652 @code{AC_INIT} should be the name of your package (e.g. @samp{GNU Automake}),
1653 not the tarball name (e.g. @samp{automake}) that you used to pass to
1654 @code{AM_INIT_AUTOMAKE}. Autoconf tries to derive a tarball name from
1655 the package name, which should work for most but not all package names.
1656 (If it doesn't work for yours, you can use the
1657 four-argument form of @code{AC_INIT} --- supported in Autoconf versions
1658 greater than 2.52g --- to provide the tarball name explicitly).
1660 By default this macro @code{AC_DEFINE}'s @samp{PACKAGE} and
1661 @samp{VERSION}. This can be avoided by passing the @samp{no-define}
1664 AM_INIT_AUTOMAKE([gnits 1.5 no-define dist-bzip2])
1666 or by passing a third non-empty argument to the obsolete form.
1668 @cvindex PACKAGE, prevent definition
1669 @cvindex VERSION, prevent definition
1672 @item AM_PATH_LISPDIR
1673 Searches for the program @code{emacs}, and, if found, sets the output
1674 variable @code{lispdir} to the full path to Emacs' site-lisp directory.
1676 Note that this test assumes the @code{emacs} found to be a version that
1677 supports Emacs Lisp (such as @sc{gnu} Emacs or XEmacs). Other emacsen
1678 can cause this test to hang (some, like old versions of MicroEmacs,
1679 start up in interactive mode, requiring @samp{C-x C-c} to exit, which
1680 is hardly obvious for a non-emacs user). In most cases, however, you
1681 should be able to use @samp{C-c} to kill the test. In order to avoid
1682 problems, you can set @code{EMACS} to ``no'' in the environment, or
1683 use the @samp{--with-lispdir} option to @command{configure} to
1684 explicitly set the correct path (if you're sure you have an @code{emacs}
1685 that supports Emacs Lisp.
1686 @cvindex AM_PATH_LISPDIR
1689 Use this macro when you have assembly code in your project. This will
1690 choose the assembler for you (by default the C compiler) and set
1691 @code{CCAS}, and will also set @code{CCASFLAGS} if required.
1693 @item AM_PROG_CC_C_O
1694 This is like @code{AC_PROG_CC_C_O}, but it generates its results in the
1695 manner required by automake. You must use this instead of
1696 @code{AC_PROG_CC_C_O} when you need this functionality.
1699 @cindex HP-UX 10, lex problems
1700 @cindex lex problems with HP-UX 10
1701 Like @code{AC_PROG_LEX} (@pxref{Particular Programs, , Particular
1702 Program Checks, autoconf, The Autoconf Manual}), but uses the
1703 @code{missing} script on systems that do not have @code{lex}.
1704 @samp{HP-UX 10} is one such system.
1707 This macro finds the @code{gcj} program or causes an error. It sets
1708 @samp{GCJ} and @samp{GCJFLAGS}. @code{gcj} is the Java front-end to the
1709 GNU Compiler Collection.
1710 @cvindex AM_PROG_GCJ
1712 @item AM_SYS_POSIX_TERMIOS
1713 @cvindex am_cv_sys_posix_termios
1714 @cindex POSIX termios headers
1715 @cindex termios POSIX headers
1716 Check to see if POSIX termios headers and functions are available on the
1717 system. If so, set the shell variable @code{am_cv_sys_posix_termios} to
1718 @samp{yes}. If not, set the variable to @samp{no}.
1720 @item AM_WITH_DMALLOC
1721 @cvindex WITH_DMALLOC
1722 @cindex dmalloc, support for
1723 @opindex --with-dmalloc
1725 @uref{ftp://ftp.letters.com/src/dmalloc/dmalloc.tar.gz, dmalloc}
1726 package. If the user configures with @samp{--with-dmalloc}, then define
1727 @code{WITH_DMALLOC} and add @samp{-ldmalloc} to @code{LIBS}.
1731 @opindex --with-regex
1732 @cindex regex package
1734 Adds @samp{--with-regex} to the @code{configure} command line. If
1735 specified (the default), then the @samp{regex} regular expression
1736 library is used, @file{regex.o} is put into @samp{LIBOBJS}, and
1737 @samp{WITH_REGEX} is defined. If @samp{--without-regex} is given, then
1738 the @samp{rx} regular expression library is used, and @file{rx.o} is put
1739 into @samp{LIBOBJS}.
1743 @node Private macros
1744 @subsection Private macros
1746 The following macros are private macros you should not call directly.
1747 They are called by the other public macros when appropriate. Do not
1748 rely on them, as they might be changed in a future version. Consider
1749 them as implementation details; or better, do not consider them at all:
1753 @item _AM_DEPENDENCIES
1754 @itemx AM_SET_DEPDIR
1756 @itemx AM_OUTPUT_DEPENDENCY_COMMANDS
1757 These macros are used to implement Automake's automatic dependency
1758 tracking scheme. They are called automatically by automake when
1759 required, and there should be no need to invoke them manually.
1761 @item AM_MAKE_INCLUDE
1762 This macro is used to discover how the user's @code{make} handles
1763 @code{include} statements. This macro is automatically invoked when
1764 needed; there should be no need to invoke it manually.
1766 @item AM_PROG_INSTALL_STRIP
1767 This is used to find a version of @code{install} which can be used to
1768 @code{strip} a program at installation time. This macro is
1769 automatically included when required.
1771 @item AM_SANITY_CHECK
1772 This checks to make sure that a file created in the build directory is
1773 newer than a file in the source directory. This can fail on systems
1774 where the clock is set incorrectly. This macro is automatically run
1775 from @code{AM_INIT_AUTOMAKE}.
1780 @node Extending aclocal
1781 @section Writing your own aclocal macros
1783 @cindex aclocal, extending
1784 @cindex Extending aclocal
1786 The @command{aclocal} program doesn't have any built-in knowledge of any
1787 macros, so it is easy to extend it with your own macros.
1789 This can be used by libraries which want to supply their own Autoconf
1790 macros for use by other programs. For instance the @command{gettext}
1791 library supplies a macro @code{AM_GNU_GETTEXT} which should be used by
1792 any package using @command{gettext}. When the library is installed, it
1793 installs this macro so that @command{aclocal} will find it.
1795 A macro file's name should end in @file{.m4}. Such files should be
1796 installed in @file{$(datadir)/aclocal}. This is as simple as writing:
1799 aclocaldir = $(datadir)/aclocal
1800 aclocal_DATA = mymacro.m4 myothermacro.m4
1803 A file of macros should be a series of properly quoted
1804 @code{AC_DEFUN}'s (@pxref{Macro Definitions, , , autoconf, The
1805 Autoconf Manual}). The @command{aclocal} programs also understands
1806 @code{AC_REQUIRE} (@pxref{Prerequisite Macros, , , autoconf, The
1807 Autoconf Manual}), so it is safe to put each macro in a separate file.
1808 Each file should have no side effects but macro definitions.
1809 Especially, any call to @code{AC_PREREQ} should be done inside the
1810 defined macro, not at the beginning of the file.
1812 @cindex underquoted AC_DEFUN
1816 Starting with Automake 1.8, @command{aclocal} will warn about all
1817 underquoted calls to @code{AC_DEFUN}. We realize this will annoy a
1818 lot of people, because @command{aclocal} was not so strict in the past
1819 and many third party macros are underquoted; and we have to apologize
1820 for this temporary inconvenience. The reason we have to be stricter
1821 is that a future implementation of @command{aclocal} (@pxref{Future of
1822 aclocal}) will have to temporary include all these third party
1823 @file{.m4} files, maybe several times, even those which are not
1824 actually needed. Doing so should alleviate many problem of the
1825 current implementation, however it requires a stricter style from the
1826 macro authors. Hopefully it is easy to revise the existing macros.
1832 [AC_REQUIRE([AX_SOMETHING])dnl
1838 should be rewritten as
1840 AC_DEFUN([AX_FOOBAR],
1842 AC_REQUIRE([AX_SOMETHING])dnl
1848 Wrapping the @code{AC_PREREQ} call inside the macro ensures that
1849 Autoconf 2.57 will not be required if @code{AX_FOOBAR} is not actually
1850 used. Most importantly, quoting the first argument of @code{AC_DEFUN}
1851 allows the macro to be redefined or included twice (otherwise this
1852 first argument would be expansed during the second definition).
1854 If you have been directed here by the @command{aclocal} diagnostic but
1855 are not the maintainer of the implicated macro, you will want to
1856 contact the maintainer of that macro. Please make sure you have the
1857 last version of the macro and that the problem already hasn't been
1858 reported before doing so: people tend to work faster when they aren't
1861 Another situation where @command{aclocal} is commonly used is to
1862 manage macros which are used locally by the package, @ref{Local
1866 @section Handling Local Macros
1868 Feature tests offered by Autoconf do not cover all needs. People
1869 often have to supplement existing tests with their own macros, or
1870 with third-party macros.
1872 There are two ways to organize custom macros in a package.
1874 The first possibility (the historical practice) is to list all your
1875 macros in @file{acinclude.m4}. This file will be included in
1876 @file{aclocal.m4} when you run @command{aclocal}, and its macro(s) will
1877 henceforth be visible to @command{autoconf}. However if it contains
1878 numerous macros, it will rapidly become difficult to maintain, and it
1879 will be almost impossible to share macros between package.
1881 The second possibility, which we do recommend, is to write each macro
1882 in its own file and gather all these files in a directory. This
1883 directory is usually called @file{m4/}. To build @file{aclocal.m4},
1884 one should therefore instruct @command{aclocal} to scan @file{m4/}.
1885 From the command line, this is done with @code{aclocal -I m4}. The
1886 top-level @file{Makefile.am} should also be updated to define
1889 ACLOCAL_AMFLAGS = -I m4
1892 @code{ACLOCAL_AMFLAGS} contains options to pass to @command{aclocal}
1893 when @file{aclocal.m4} is to be rebuilt by @code{make}. This line is
1894 also used by @command{autoreconf} (@pxref{autoreconf Invocation, ,
1895 Using @command{autoreconf} to Update @file{configure} Scripts,
1896 autoconf, The Autoconf Manual}) to run @command{aclocal} with suitable
1897 options, or by @command{autopoint} (@pxref{autopoint Invocation, ,
1898 Invoking the @command{autopoint} Program, gettext, GNU gettext tools})
1899 and @command{gettextize} (@pxref{gettextize Invocation, , Invoking the
1900 @command{gettextize} Program, gettext, GNU gettext tools}) to locate
1901 the place where Gettext's macros should be installed. So even if you
1902 do not really care about the rebuild rules, you should define
1903 @code{ACLOCAL_AMFLAGS}.
1905 When @code{aclocal -I m4} is run, it will build a @code{aclocal.m4}
1906 that @code{m4_include}s any file from @file{m4/} that defines a
1907 required macro. Macros not found locally will still be searched in
1908 system-wide directories, as explained in @ref{Macro search path}.
1910 Custom macros should be distributed for the same reason that
1911 @file{configure.ac} is: so that other people have all the sources of
1912 your package if they want to work on it. Actually, this distribution
1913 happens automatically because all @code{m4_include}d files are
1916 However there is no consensus on the distribution of third-party
1917 macros that your package may use. Many libraries install their own
1918 macro in the system-wide @command{aclocal} directory (@pxref{Extending
1919 aclocal}). For instance Guile ships with a file called
1920 @file{guile.m4} that contains the macro @code{GUILE_FLAGS} which can
1921 be used to define setup compiler and linker flags appropriate for
1922 using Guile. Using @code{GUILE_FLAGS} in @file{configure.ac} will
1923 cause @command{aclocal} to copy @file{guile.m4} into
1924 @file{aclocal.m4}, but as @file{guile.m4} is not part of the project,
1925 it will not be distributed. Technically, that means a user which
1926 needs to rebuild @file{aclocal.m4} will have to install Guile first.
1927 This is probably OK, if Guile already is a requirement to build the
1928 package. However, if Guile is only an optional feature, or if your
1929 package might run on architectures where Guile cannot be installed,
1930 this requirement will hinder development. An easy solution is to copy
1931 such third-party macros in your local @file{m4/} directory so they get
1934 @node Future of aclocal
1935 @section The Future of @command{aclocal}
1936 @cindex aclocal's scheduled death
1938 @command{aclocal} is expected to disappear. This feature really
1939 should not be offered by Automake. Automake should focus on generating
1940 @file{Makefile}s; dealing with M4 macros really is Autoconf's job.
1941 That some people install Automake just to use @command{aclocal}, but
1942 do not use @command{automake} otherwise is an indication of how that
1943 feature is misplaced.
1945 The new implementation will probably be done slightly differently.
1946 For instance it could enforce the @file{m4/}-style layout discussed in
1947 @ref{Local Macros}, and take care of copying (or even updating)
1948 third-party macro into this directory.
1950 We have no idea when and how this will happen. This has been
1951 discussed several times in the past, but someone still has to commit
1952 itself to that non-trivial task.
1954 From the user point of view, @command{aclocal}'s removal might turn
1955 out to be painful. There is a simple precaution that you may take to
1956 make that switch more seamless: never call @command{aclocal} yourself.
1957 Keep this guy under the exclusive control of @command{autoreconf} and
1958 Automake's rebuild rules. Hopefully you won't need to worry about
1959 things breaking, when @command{aclocal} disappears, because everything
1960 will have been taken care of. If otherwise you used to call
1961 @command{aclocal} directly yourself or from some script, you will
1962 quickly notice the change.
1964 Many packages come with a script called @file{bootstrap.sh} or
1965 @file{autogen.sh}, that will just call @command{aclocal},
1966 @command{libtoolize}, @command{gettextize} or @command{autopoint},
1967 @command{autoconf}, @command{autoheader}, and @command{automake} in
1968 the right order. Actually this is precisely what @command{autoreconf}
1969 can do for you. If your package has such a @file{bootstrap.sh} or
1970 @file{autogen.sh} script, consider using @command{autoreconf}. That
1971 should simplify its logic a lot (less things to maintain, yum!), it's
1972 even likely you will not need the script anymore, and more to the point
1973 you will not call @command{aclocal} directly anymore.
1977 @chapter The top-level @file{Makefile.am}
1979 @section Recursing subdirectories
1981 @cindex SUBDIRS, explained
1983 In packages with subdirectories, the top level @file{Makefile.am} must
1984 tell Automake which subdirectories are to be built. This is done via
1985 the @code{SUBDIRS} variable.
1988 The @code{SUBDIRS} variable holds a list of subdirectories in which
1989 building of various sorts can occur. Many targets (e.g. @code{all}) in
1990 the generated @file{Makefile} will run both locally and in all specified
1991 subdirectories. Note that the directories listed in @code{SUBDIRS} are
1992 not required to contain @file{Makefile.am}s; only @file{Makefile}s
1993 (after configuration). This allows inclusion of libraries from packages
1994 which do not use Automake (such as @code{gettext}).
1996 In packages that use subdirectories, the top-level @file{Makefile.am} is
1997 often very short. For instance, here is the @file{Makefile.am} from the
1998 GNU Hello distribution:
2001 EXTRA_DIST = BUGS ChangeLog.O README-alpha
2002 SUBDIRS = doc intl po src tests
2005 When Automake invokes @code{make} in a subdirectory, it uses the value
2006 of the @code{MAKE} variable. It passes the value of the variable
2007 @code{AM_MAKEFLAGS} to the @code{make} invocation; this can be set in
2008 @file{Makefile.am} if there are flags you must always pass to
2013 The directories mentioned in @code{SUBDIRS} must be direct children of
2014 the current directory. For instance, you cannot put @samp{src/subdir}
2015 into @code{SUBDIRS}. Instead you should put @code{SUBDIRS = subdir}
2016 into @file{src/Makefile.am}. Automake can be used to construct packages
2017 of arbitrary depth this way.
2019 By default, Automake generates @file{Makefiles} which work depth-first
2020 (@samp{postfix}). However, it is possible to change this ordering. You
2021 can do this by putting @samp{.} into @code{SUBDIRS}. For instance,
2022 putting @samp{.} first will cause a @samp{prefix} ordering of
2023 directories. All @samp{clean} targets are run in reverse order of build
2026 @section Conditional subdirectories
2027 @cindex Subdirectories, building conditionally
2028 @cindex Conditional subdirectories
2029 @cindex @code{SUBDIRS}, conditional
2030 @cindex Conditional @code{SUBDIRS}
2032 It is possible to define the @code{SUBDIRS} variable conditionally if,
2033 like in the case of GNU @code{Inetutils}, you want to only build a
2034 subset of the entire package.
2036 To illustrate how this works, let's assume we have two directories
2037 @file{src/} and @file{opt/}. @file{src/} should always be built, but we
2038 want to decide in @code{./configure} whether @file{opt/} will be built
2039 or not. (For this example we will assume that @file{opt/} should be
2040 built when the variable @code{$want_opt} was set to @code{yes}.)
2042 Running @code{make} should thus recurse into @file{src/} always, and
2043 then maybe in @file{opt/}.
2045 However @code{make dist} should always recurse into both @file{src/} and
2046 @file{opt/}. Because @file{opt/} should be distributed even if it is
2047 not needed in the current configuration. This means @file{opt/Makefile}
2048 should be created unconditionally. @footnote{Don't try seeking a
2049 solution where @file{opt/Makefile} is created conditionally, this is a
2050 lot trickier than the solutions presented here.}
2052 There are two ways to setup a project like this. You can use Automake
2053 conditionals (@pxref{Conditionals}) or use Autoconf @code{AC_SUBST}
2054 variables (@pxref{Setting Output Variables, , Setting Output Variables,
2055 autoconf, The Autoconf Manual}). Using Automake conditionals is the
2058 @subsection Conditional subdirectories with @code{AM_CONDITIONAL}
2059 @cindex @code{SUBDIRS} and @code{AM_CONDITIONAL}
2060 @cindex @code{AM_CONDITIONAL} and @code{SUBDIRS}
2062 @c The test case for the setup described here is
2063 @c test/subdircond2.test
2064 @c Try to keep it in sync.
2066 @file{configure} should output the @file{Makefile} for each directory
2067 and define a condition into which @file{opt/} should be built.
2071 AM_CONDITIONAL([COND_OPT], [test "$want_opt" = yes])
2072 AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
2076 Then @code{SUBDIRS} can be defined in the top-level @file{Makefile.am}
2083 SUBDIRS = src $(MAYBE_OPT)
2086 As you can see, running @code{make} will rightly recurse into
2087 @file{src/} and maybe @file{opt/}.
2089 @vindex DIST_SUBDIRS
2090 As you can't see, running @code{make dist} will recurse into both
2091 @file{src/} and @file{opt/} directories because @code{make dist}, unlike
2092 @code{make all}, doesn't use the @code{SUBDIRS} variable. It uses the
2093 @code{DIST_SUBDIRS} variable.
2095 In this case Automake will define @code{DIST_SUBDIRS = src opt}
2096 automatically because it knows that @code{MAYBE_OPT} can contain
2097 @code{opt} in some condition.
2099 @subsection Conditional subdirectories with @code{AC_SUBST}
2100 @cindex @code{SUBDIRS} and @code{AC_SUBST}
2101 @cindex @code{AC_SUBST} and @code{SUBDIRS}
2103 @c The test case for the setup described here is
2104 @c test/subdircond3.test
2105 @c Try to keep it in sync.
2107 Another idea is to define @code{MAYBE_OPT} from @file{./configure} using
2112 if test "$want_opt" = yes; then
2117 AC_SUBST([MAYBE_OPT])
2118 AC_CONFIG_FILES([Makefile src/Makefile opt/Makefile])
2122 In this case the top-level @file{Makefile.am} should look as follows.
2125 SUBDIRS = src $(MAYBE_OPT)
2126 DIST_SUBDIRS = src opt
2129 The drawback is that since Automake cannot guess what the possible
2130 values of @code{MAYBE_OPT} are, it is necessary to define
2131 @code{DIST_SUBDIRS}.
2133 @subsection How @code{DIST_SUBDIRS} is used
2134 @cindex @code{DIST_SUBDIRS}, explained
2136 As shown in the above examples, @code{DIST_SUBDIRS} is used by targets
2137 that need to recurse in all directories, even those which have been
2138 conditionally left out of the build.
2140 Precisely, @code{DIST_SUBDIRS} is used by @code{make dist}, @code{make
2141 distclean}, and @code{make maintainer-clean}. All other recursive
2142 targets use @code{SUBDIRS}.
2144 Automake will define @code{DIST_SUBDIRS} automatically from the
2145 possibles values of @code{SUBDIRS} in all conditions.
2147 If @code{SUBDIRS} contains @code{AC_SUBST} variables,
2148 @code{DIST_SUBDIRS} will not be defined correctly because Automake
2149 doesn't know the possible values of these variables. In this case
2150 @code{DIST_SUBDIRS} needs to be defined manually.
2154 @chapter An Alternative Approach to Subdirectories
2156 If you've ever read Peter Miller's excellent paper,
2157 @uref{http://www.pcug.org.au/~millerp/rmch/recu-make-cons-harm.html,
2158 Recursive Make Considered Harmful}, the preceding section on the use of
2159 subdirectories will probably come as unwelcome advice. For those who
2160 haven't read the paper, Miller's main thesis is that recursive
2161 @code{make} invocations are both slow and error-prone.
2163 Automake provides sufficient cross-directory support @footnote{We
2164 believe. This work is new and there are probably warts.
2165 @xref{Introduction}, for information on reporting bugs.} to enable you
2166 to write a single @file{Makefile.am} for a complex multi-directory
2170 By default an installable file specified in a subdirectory will have its
2171 directory name stripped before installation. For instance, in this
2172 example, the header file will be installed as
2173 @file{$(includedir)/stdio.h}:
2176 include_HEADERS = inc/stdio.h
2180 @cindex Path stripping, avoiding
2181 @cindex Avoiding path stripping
2183 However, the @samp{nobase_} prefix can be used to circumvent this path
2184 stripping. In this example, the header file will be installed as
2185 @file{$(includedir)/sys/types.h}:
2188 nobase_include_HEADERS = sys/types.h
2191 @cindex nobase_ and dist_ or nodist_
2192 @cindex dist_ and nobase_
2193 @cindex nodist_ and nobase_
2195 @samp{nobase_} should be specified first when used in conjunction with
2196 either @samp{dist_} or @samp{nodist_} (@pxref{Dist}). For instance:
2199 nobase_dist_pkgdata_DATA = images/vortex.pgm
2203 @chapter Rebuilding Makefiles
2205 Automake generates rules to automatically rebuild @file{Makefile}s,
2206 @file{configure}, and other derived files like @file{Makefile.in}.
2208 If you are using @code{AM_MAINTAINER_MODE} in @file{configure.ac}, then
2209 these automatic rebuilding rules are only enabled in maintainer mode.
2211 Sometimes you need to run @code{aclocal} with an argument like @code{-I}
2212 to tell it where to find @file{.m4} files. Since sometimes @code{make}
2213 will automatically run @code{aclocal}, you need a way to specify these
2214 arguments. You can do this by defining @code{ACLOCAL_AMFLAGS}; this
2215 holds arguments which are passed verbatim to @code{aclocal}. This variable
2216 is only useful in the top-level @file{Makefile.am}.
2217 @vindex ACLOCAL_AMFLAGS
2221 @chapter Building Programs and Libraries
2223 A large part of Automake's functionality is dedicated to making it easy
2224 to build programs and libraries.
2227 * A Program:: Building a program
2228 * A Library:: Building a library
2229 * A Shared Library:: Building a Libtool library
2230 * Program and Library Variables:: Variables controlling program and
2232 * LIBOBJS:: Special handling for LIBOBJS and ALLOCA
2233 * Program variables:: Variables used when building a program
2234 * Yacc and Lex:: Yacc and Lex support
2236 * Assembly Support::
2237 * Fortran 77 Support::
2239 * Support for Other Languages::
2240 * ANSI:: Automatic de-ANSI-fication
2241 * Dependencies:: Automatic dependency tracking
2242 * EXEEXT:: Support for executable extensions
2247 @section Building a program
2249 In order to build a program, you need to tell Automake which sources
2250 are part of it, and which libraries it should be linked with.
2252 This section also covers conditional compilation of sources or
2253 programs. Most of the comments about these also apply to libraries
2254 (@pxref{A Library}) and libtool libraries (@pxref{A Shared Library}).
2257 * Program Sources:: Defining program sources
2258 * Linking:: Linking with libraries or extra objects
2259 * Conditional Sources:: Handling conditional sources
2260 * Conditional Programs:: Building program conditionally
2263 @node Program Sources
2264 @subsection Defining program sources
2266 @cindex PROGRAMS, bindir
2267 @vindex bin_PROGRAMS
2268 @vindex sbin_PROGRAMS
2269 @vindex libexec_PROGRAMS
2270 @vindex pkglib_PROGRAMS
2271 @vindex noinst_PROGRAMS
2272 @vindex check_PROGRAMS
2274 In a directory containing source that gets built into a program (as
2275 opposed to a library or a script), the @samp{PROGRAMS} primary is used.
2276 Programs can be installed in @code{bindir}, @code{sbindir},
2277 @code{libexecdir}, @code{pkglibdir}, or not at all (@samp{noinst}).
2278 They can also be built only for @code{make check}, in which case the
2279 prefix is @samp{check}.
2284 bin_PROGRAMS = hello
2287 In this simple case, the resulting @file{Makefile.in} will contain code
2288 to generate a program named @code{hello}.
2290 Associated with each program are several assisting variables which are
2291 named after the program. These variables are all optional, and have
2292 reasonable defaults. Each variable, its use, and default is spelled out
2293 below; we use the ``hello'' example throughout.
2295 The variable @code{hello_SOURCES} is used to specify which source files
2296 get built into an executable:
2299 hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
2302 This causes each mentioned @samp{.c} file to be compiled into the
2303 corresponding @samp{.o}. Then all are linked to produce @file{hello}.
2305 @cindex _SOURCES primary, defined
2306 @cindex SOURCES primary, defined
2307 @cindex Primary variable, SOURCES
2309 If @samp{hello_SOURCES} is not specified, then it defaults to the single
2310 file @file{hello.c}; that is, the default is to compile a single C file
2311 whose base name is the name of the program itself. (This is a terrible
2312 default but we are stuck with it for historical reasons.)
2316 Multiple programs can be built in a single directory. Multiple programs
2317 can share a single source file, which must be listed in each
2318 @samp{_SOURCES} definition.
2320 @cindex Header files in _SOURCES
2321 @cindex _SOURCES and header files
2323 Header files listed in a @samp{_SOURCES} definition will be included in
2324 the distribution but otherwise ignored. In case it isn't obvious, you
2325 should not include the header file generated by @file{configure} in a
2326 @samp{_SOURCES} variable; this file should not be distributed. Lex
2327 (@samp{.l}) and Yacc (@samp{.y}) files can also be listed; see @ref{Yacc
2332 @subsection Linking the program
2334 If you need to link against libraries that are not found by
2335 @code{configure}, you can use @code{LDADD} to do so. This variable is
2336 used to specify additional objects or libraries to link with; it is
2337 inappropriate for specifying specific linker flags, you should use
2338 @code{AM_LDFLAGS} for this purpose.
2342 @cindex prog_LDADD, defined
2344 Sometimes, multiple programs are built in one directory but do not share
2345 the same link-time requirements. In this case, you can use the
2346 @samp{@var{prog}_LDADD} variable (where @var{prog} is the name of the
2347 program as it appears in some @samp{_PROGRAMS} variable, and usually
2348 written in lowercase) to override the global @code{LDADD}. If this
2349 variable exists for a given program, then that program is not linked
2353 For instance, in GNU cpio, @code{pax}, @code{cpio} and @code{mt} are
2354 linked against the library @file{libcpio.a}. However, @code{rmt} is
2355 built in the same directory, and has no such link requirement. Also,
2356 @code{mt} and @code{rmt} are only built on certain architectures. Here
2357 is what cpio's @file{src/Makefile.am} looks like (abridged):
2360 bin_PROGRAMS = cpio pax $(MT)
2361 libexec_PROGRAMS = $(RMT)
2362 EXTRA_PROGRAMS = mt rmt
2364 LDADD = ../lib/libcpio.a $(INTLLIBS)
2367 cpio_SOURCES = @dots{}
2368 pax_SOURCES = @dots{}
2369 mt_SOURCES = @dots{}
2370 rmt_SOURCES = @dots{}
2373 @cindex _LDFLAGS, defined
2375 @samp{@var{prog}_LDADD} is inappropriate for passing program-specific
2376 linker flags (except for @samp{-l}, @samp{-L}, @samp{-dlopen} and
2377 @samp{-dlpreopen}). So, use the @samp{@var{prog}_LDFLAGS} variable for
2381 @cindex _DEPENDENCIES, defined
2383 It is also occasionally useful to have a program depend on some other
2384 target which is not actually part of that program. This can be done
2385 using the @samp{@var{prog}_DEPENDENCIES} variable. Each program depends
2386 on the contents of such a variable, but no further interpretation is
2389 If @samp{@var{prog}_DEPENDENCIES} is not supplied, it is computed by
2390 Automake. The automatically-assigned value is the contents of
2391 @samp{@var{prog}_LDADD}, with most configure substitutions, @samp{-l},
2392 @samp{-L}, @samp{-dlopen} and @samp{-dlpreopen} options removed. The
2393 configure substitutions that are left in are only @samp{$(LIBOBJS)} and
2394 @samp{$(ALLOCA)}; these are left because it is known that they will not
2395 cause an invalid value for @samp{@var{prog}_DEPENDENCIES} to be
2399 @node Conditional Sources
2400 @subsection Conditional compilation of sources
2402 You can't put a configure substitution (e.g., @samp{@@FOO@@} or
2403 @samp{$(FOO)} where @code{FOO} is defined via @code{AC_SUBST}) into a
2404 @samp{_SOURCES} variable. The reason for this is a bit hard to
2405 explain, but suffice to say that it simply won't work. Automake will
2406 give an error if you try to do this.
2408 Fortunately there are two other ways to achieve the same result. One is
2409 to use configure substitutions in @code{_LDADD} variables, the other is
2410 to use an Automake conditional.
2412 @subsubsection Conditional compilation using @code{_LDADD} substitutions
2414 @cindex EXTRA_prog_SOURCES, defined
2416 Automake must know all the source files that could possibly go into a
2417 program, even if not all the files are built in every circumstance. Any
2418 files which are only conditionally built should be listed in the
2419 appropriate @samp{EXTRA_} variable. For instance, if
2420 @file{hello-linux.c} or @file{hello-generic.c} were conditionally included
2421 in @code{hello}, the @file{Makefile.am} would contain:
2424 bin_PROGRAMS = hello
2425 hello_SOURCES = hello-common.c
2426 EXTRA_hello_SOURCES = hello-linux.c hello-generic.c
2427 hello_LDADD = $(HELLO_SYSTEM)
2428 hello_DEPENDENCIES = $(HELLO_SYSTEM)
2432 You can then setup the @code{$(HELLO_SYSTEM)} substitution from
2433 @file{configure.ac}:
2438 *linux*) HELLO_SYSTEM='hello-linux.$(OBJEXT)' ;;
2439 *) HELLO_SYSTEM='hello-generic.$(OBJEXT)' ;;
2441 AC_SUBST([HELLO_SYSTEM])
2445 In this case, @code{HELLO_SYSTEM} should be replaced by
2446 @file{hello-linux.o} or @file{hello-bsd.o}, and added to
2447 @code{hello_DEPENDENCIES} and @code{hello_LDADD} in order to be built
2450 @subsubsection Conditional compilation using Automake conditionals
2452 An often simpler way to compile source files conditionally is to use
2453 Automake conditionals. For instance, you could use this
2454 @file{Makefile.am} construct to build the same @file{hello} example:
2457 bin_PROGRAMS = hello
2459 hello_SOURCES = hello-linux.c hello-common.c
2461 hello_SOURCES = hello-generic.c hello-common.c
2465 In this case, your @file{configure.ac} should setup the @code{LINUX}
2466 conditional using @code{AM_CONDITIONAL} (@pxref{Conditionals}).
2468 When using conditionals like this you don't need to use the
2469 @samp{EXTRA_} variable, because Automake will examine the contents of
2470 each variable to construct the complete list of source files.
2472 If your program uses a lot of files, you will probably prefer a
2473 conditional @code{+=}.
2476 bin_PROGRAMS = hello
2477 hello_SOURCES = hello-common.c
2479 hello_SOURCES += hello-linux.c
2481 hello_SOURCES += hello-generic.c
2485 @node Conditional Programs
2486 @subsection Conditional compilation of programs
2487 @cindex Conditional programs
2488 @cindex Programs, conditional
2490 Sometimes it is useful to determine the programs that are to be built
2491 at configure time. For instance, GNU @code{cpio} only builds
2492 @code{mt} and @code{rmt} under special circumstances. The means to
2493 achieve conditional compilation of programs are the same you can use
2494 to compile source files conditionally: substitutions or conditionals.
2496 @subsubsection Conditional programs using @code{configure} substitutions
2498 In this case, you must notify Automake of all the programs that can
2499 possibly be built, but at the same time cause the generated
2500 @file{Makefile.in} to use the programs specified by @code{configure}.
2501 This is done by having @code{configure} substitute values into each
2502 @samp{_PROGRAMS} definition, while listing all optionally built programs
2503 in @code{EXTRA_PROGRAMS}.
2504 @vindex EXTRA_PROGRAMS
2505 @cindex EXTRA_PROGRAMS, defined
2508 bin_PROGRAMS = cpio pax $(MT)
2509 libexec_PROGRAMS = $(RMT)
2510 EXTRA_PROGRAMS = mt rmt
2513 As explained in @ref{EXEEXT}, Automake will rewrite
2514 @code{bin_PROGRAMS}, @code{libexec_PROGRAMS}, and
2515 @code{EXTRA_PROGRAMS}, appending @code{$(EXEEXT)} to each binary.
2516 Obviously it cannot rewrite values obtained at run-time through
2517 @code{configure} substitutions, therefore you should take care of
2518 appending @code{$(EXEEXT)} yourself, as in @code{AC_SUBST([MT],
2519 ['mt$@{EXEEXT@}'])}.
2521 @subsubsection Conditional programs using Automake conditionals
2523 You can also use Automake conditionals (@pxref{Conditionals}) to
2524 select programs to be built. In this case you don't have to worry
2525 about @code{$(EXEEXT)} or @code{EXTRA_PROGRAMS}.
2528 bin_PROGRAMS = cpio pax
2533 libexec_PROGRAMS = rmt
2539 @section Building a library
2541 @cindex _LIBRARIES primary, defined
2542 @cindex LIBRARIES primary, defined
2543 @cindex Primary variable, LIBRARIES
2545 @vindex lib_LIBRARIES
2546 @vindex pkglib_LIBRARIES
2547 @vindex noinst_LIBRARIES
2549 Building a library is much like building a program. In this case, the
2550 name of the primary is @samp{LIBRARIES}. Libraries can be installed in
2551 @code{libdir} or @code{pkglibdir}.
2553 @xref{A Shared Library}, for information on how to build shared
2554 libraries using libtool and the @samp{LTLIBRARIES} primary.
2556 Each @samp{_LIBRARIES} variable is a list of the libraries to be built.
2557 For instance to create a library named @file{libcpio.a}, but not install
2558 it, you would write:
2561 noinst_LIBRARIES = libcpio.a
2564 The sources that go into a library are determined exactly as they are
2565 for programs, via the @samp{_SOURCES} variables. Note that the library
2566 name is canonicalized (@pxref{Canonicalization}), so the @samp{_SOURCES}
2567 variable corresponding to @file{liblob.a} is @samp{liblob_a_SOURCES},
2568 not @samp{liblob.a_SOURCES}.
2570 @cindex _LIBADD primary, defined
2571 @cindex LIBADD primary, defined
2572 @cindex Primary variable, LIBADD
2574 Extra objects can be added to a library using the
2575 @samp{@var{library}_LIBADD} variable. This should be used for objects
2576 determined by @code{configure}. Again from @code{cpio}:
2581 libcpio_a_LIBADD = $(LIBOBJS) $(ALLOCA)
2584 In addition, sources for extra objects that will not exist until
2585 configure-time must be added to the @code{BUILT_SOURCES} variable
2588 Building a static library is done by compiling all object files, then
2589 by invoking @code{$(AR) $(ARFLAGS)} followed by the name of the
2590 library and the list of objects, and finally by calling
2591 @code{$(RANLIB)} on that library. You should call
2592 @code{AC_PROG_RANLIB} from your @file{configure.ac} to define
2593 @code{RANLIB} (Automake will complain otherwise). @code{AR} and
2594 @code{ARFLAGS} default to @code{ar} and @code{cru} respectively; you
2595 can override these two variables my setting them in your
2596 @file{Makefile.am}, by @code{AC_SUBST}ing them from your
2597 @file{configure.ac}, or by defining a per-library @code{maude_AR}
2598 variable (@pxref{Program and Library Variables}).
2600 @node A Shared Library
2601 @section Building a Shared Library
2603 @cindex Shared libraries, support for
2605 Building shared libraries portably is a relatively complex matter.
2606 For this reason, GNU Libtool (@pxref{Top, , Introduction, libtool, The
2607 Libtool Manual}) was created to help build shared libraries in a
2608 platform-independent way.
2611 * Libtool Concept:: Introducing Libtool
2612 * Libtool Libraries:: Declaring Libtool Libraries
2613 * Conditional Libtool Libraries:: Building Libtool Libraries Conditionally
2614 * Conditional Libtool Sources:: Choosing Library Sources Conditionally
2615 * Libtool Convenience Libraries:: Building Convenience Libtool Libraries
2616 * Libtool Modules:: Building Libtool Modules
2617 * Libtool Flags:: Using _LIBADD and _LDFLAGS
2618 * LTLIBOBJ:: Using $(LTLIBOBJ)
2619 * Libtool Issues:: Common Issues Related to Libtool's Use
2622 @node Libtool Concept
2623 @subsection The Libtool Concept
2625 @cindex libtool, introduction
2626 @cindex libtool library, definition
2627 @cindex suffix .la, defined
2628 @cindex .la suffix, defined
2630 Libtool abstracts shared and static libraries into a unified
2631 concept henceforth called @dfn{libtool libraries}. Libtool libraries
2632 are files using the @file{.la} suffix, and can designate a static
2633 library, a shared library, or maybe both. Their exact nature cannot
2634 be determined until @file{./configure} is run: not all platforms
2635 support all kinds of libraries, and users can explicitly select which
2636 libraries should be built. (However the package's maintainers can
2637 tune the default, @xref{AC_PROG_LIBTOOL, , The @code{AC_PROG_LIBTOOL}
2638 macro, libtool, The Libtool Manual}.)
2640 @cindex suffix .lo, defined
2641 Because object files for shared and static libraries must be compiled
2642 differently, libtool is also used during compilation. Object files
2643 built by libtool are called @dfn{libtool objects}: these are files
2644 using the @file{.lo} suffix. Libtool libraries are built from these
2647 You should not assume anything about the structure of @file{.la} or
2648 @file{.lo} files and how libtool constructs them: this is libtool's
2649 concern, and the last thing one wants is to learn about libtool's
2650 guts. However the existence of these files matters, because they are
2651 used as targets and dependencies in @file{Makefile}s when building
2652 libtool libraries. There are situations where you may have to refer
2653 to these, for instance when expressing dependencies for building
2654 source files conditionally (@pxref{Conditional Libtool Sources}).
2656 @cindex libltdl, introduction
2658 People considering writing a plug-in system, with dynamically loaded
2659 modules, should look into @file{libltdl}: libtool's dlopening library
2660 (@pxref{Using libltdl, , Using libltdl, libtool, The Libtool Manual}).
2661 This offers a portable dlopening facility to load libtool libraries
2662 dynamically, and can also achieve static linking where unavoidable.
2664 Before we discuss how to use libtool with Automake in details, it
2665 should be noted that the libtool manual also has a section about how
2666 to use Automake with libtool (@pxref{Using Automake, , Using Automake
2667 with Libtool, libtool, The Libtool Manual}).
2669 @node Libtool Libraries
2670 @subsection Building Libtool Libraries
2672 @cindex _LTLIBRARIES primary, defined
2673 @cindex LTLIBRARIES primary, defined
2674 @cindex Primary variable, LTLIBRARIES
2675 @cindex Example of shared libraries
2676 @vindex lib_LTLIBRARIES
2677 @vindex pkglib_LTLIBRARIES
2679 Automake uses libtool to build libraries declared with the
2680 @samp{LTLIBRARIES} primary. Each @samp{_LTLIBRARIES} variable is a
2681 list of libtool libraries to build. For instance, to create a libtool
2682 library named @file{libgettext.la}, and install it in @samp{libdir},
2686 lib_LTLIBRARIES = libgettext.la
2687 libgettext_la_SOURCES = gettext.c gettext.h @dots{}
2690 Automake predefines the variable @samp{pkglibdir}, so you can use
2691 @code{pkglib_LTLIBRARIES} to install libraries in
2692 @code{$(libdir)/@@PACKAGE@@/}.
2694 @node Conditional Libtool Libraries
2695 @subsection Building Libtool Libraries Conditionally
2696 @cindex libtool libraries, conditional
2697 @cindex conditional libtool libraries
2699 Like conditional programs (@pxref{Conditional Programs}), there are
2700 two main ways to build conditional libraries: using Automake
2701 conditionals or using Autoconf @code{AC_SUBST}itutions.
2703 The important implementation detail you have to be aware of is that
2704 the place where a library will be installed matters to libtool: it
2705 needs to be indicated @emph{at link-time} using the @code{-rpath}
2708 For libraries whose destination directory is known when Automake runs,
2709 Automake will automatically supply the appropriate @samp{-rpath}
2710 option to libtool. This is the case for libraries listed explicitly in
2711 some installable @code{_LTLIBRARIES} variables such as
2712 @code{lib_LTLIBRARIES}.
2714 However, for libraries determined at configure time (and thus
2715 mentioned in @code{EXTRA_LTLIBRARIES}), Automake does not know the
2716 final installation directory. For such libraries you must add the
2717 @samp{-rpath} option to the appropriate @samp{_LDFLAGS} variable by
2720 The examples below illustrate the differences between these two methods.
2722 Here is an example where @code{$(WANTEDLIBS)} is an @code{AC_SUBST}ed
2723 variable set at @file{./configure}-time to either @file{libfoo.la},
2724 @file{libbar.la}, both, or none. Although @code{$(WANTEDLIBS)}
2725 appears in the @code{lib_LTLIBRARIES}, Automake cannot guess it
2726 relates to @file{libfoo.la} or @file{libbar.la} by the time it creates
2727 the link rule for these two libraries. Therefore the @code{-rpath}
2728 argument must be explicitly supplied.
2731 EXTRA_LTLIBRARIES = libfoo.la libbar.la
2732 lib_LTLIBRARIES = $(WANTEDLIBS)
2733 libfoo_la_SOURCES = foo.c @dots{}
2734 libfoo_la_LDFLAGS = -rpath '$(libdir)'
2735 libbar_la_SOURCES = bar.c @dots{}
2736 libbar_la_LDFLAGS = -rpath '$(libdir)'
2739 Here is how the same @file{Makefile.am} would look using Automake
2740 conditionals named @code{WANT_LIBFOO} and @code{WANT_LIBBAR}. Now
2741 Automake is able to compute the @code{-rpath} setting itself, because
2742 it's clear that both libraries will end up in @code{$(libdir)} if they
2748 lib_LTLIBRARIES += libfoo.la
2751 lib_LTLIBRARIES += libbar.la
2753 libfoo_la_SOURCES = foo.c @dots{}
2754 libbar_la_SOURCES = bar.c @dots{}
2757 @node Conditional Libtool Sources
2758 @subsection Libtool Libraries with Conditional Sources
2760 Conditional compilation of sources in a library can be achieved in the
2761 same way as conditional compilation of sources in a program
2762 (@pxref{Conditional Sources}). The only difference is that
2763 @code{_LIBADD} should be used instead of @code{_LDADD} and that it
2764 should mention libtool objects (@file{.lo} files).
2766 So, to mimic the @file{hello} example from @ref{Conditional Sources},
2767 we could build a @file{libhello.la} library using either
2768 @file{hello-linux.c} or @file{hello-generic.c} with the following
2772 lib_LTLIBRARIES = libhello.la
2773 libhello_la_SOURCES = hello-common.c
2774 EXTRA_libhello_la_SOURCES = hello-linux.c hello-generic.c
2775 libhello_la_LIBADD = $(HELLO_SYSTEM)
2776 libhello_la_DEPENDENCIES = $(HELLO_SYSTEM)
2780 And make sure @code{$(HELLO_SYSTEM)} is set to either
2781 @file{hello-linux.lo} or @file{hello-generic.lo} in
2784 Or we could simply use an Automake conditional as follows.
2787 lib_LTLIBRARIES = libhello.la
2788 libhello_la_SOURCES = hello-common.c
2790 libhello_la_SOURCES += hello-linux.c
2792 libhello_la_SOURCES += hello-generic.c
2796 @node Libtool Convenience Libraries
2797 @subsection Libtool Convenience Libraries
2798 @cindex convenience libraries, libtool
2799 @cindex libtool convenience libraries
2800 @vindex noinst_LTLIBRARIES
2801 @vindex check_LTLIBRARIES
2803 Sometimes you want to build libtool libraries which should not be
2804 installed. These are called @dfn{libtool convenience libraries} and
2805 are typically used to encapsulate many sublibraries, later gathered
2806 into one big installed library.
2808 Libtool convenience libraries are declared by
2809 @code{noinst_LTLIBRARIES}, @code{check_LTLIBRARIES}, or even
2810 @code{EXTRA_LTLIBRARIES}. Unlike installed libtool libraries they do
2811 not need an @code{-rpath} flag at link time (actually this is the only
2814 Convenience libraries listed in @code{noinst_LTLIBRARIES} are always
2815 built. Those listed in @code{check_LTLIBRARIES} are built only upon
2816 @code{make check}. Finally, libraries listed in
2817 @code{EXTRA_LTLIBRARIES} are never built explicitly: Automake outputs
2818 rules to build them, but if the library does not appear as a Makefile
2819 dependency anywhere it won't be built (this is why
2820 @code{EXTRA_LTLIBRARIES} is used for conditional compilation).
2822 Here is a sample setup merging libtool convenience libraries from
2823 subdirectories into one main @file{libtop.la} library.
2826 # -- Top-level Makefile.am --
2827 SUBDIRS = sub1 sub2 @dots{}
2828 lib_LTLIBRARIES = libtop.la
2830 libtop_la_LIBADD = \
2835 # -- sub1/Makefile.am --
2836 noinst_LTLIBRARIES = libsub1.la
2837 libsub1_la_SOURCES = @dots{}
2839 # -- sub2/Makefile.am --
2840 # showing nested convenience libraries
2841 SUBDIRS = sub2.1 sub2.2 @dots{}
2842 noinst_LTLIBRARIES = libsub2.la
2843 libsub2_la_SOURCES =
2844 libsub2_la_LIBADD = \
2850 @node Libtool Modules
2851 @subsection Libtool Modules
2852 @cindex modules, libtool
2853 @cindex libtool modules
2854 @cindex -module, libtool
2856 These are libtool libraries meant to be dlopened. They are
2857 indicated to libtool by passing @code{-module} at link-time.
2860 pkglib_LTLIBRARIES = mymodule.la
2861 mymodule_la_SOURCES = doit.c
2862 mymodule_LDFLAGS = -module
2865 Ordinarily, Automake requires that a Library's name starts with
2866 @samp{lib}. However, when building a dynamically loadable module you
2867 might wish to use a "nonstandard" name.
2870 @subsection _LIBADD and _LDFLAGS
2871 @cindex _LIBADD, libtool
2872 @cindex _LDFLAGS, libtool
2874 As shown in previous sections, the @samp{@var{library}_LIBADD}
2875 variable should be used to list extra libtool objects (@file{.lo}
2876 files) or libtool libraries (@file{.la}) to add to @var{library}.
2878 The @samp{@var{library}_LDFLAGS} variable is the place to list
2879 additional libtool flags, such as @samp{-version-info},
2880 @samp{-static}, and a lot more. See @xref{Link mode, , Using libltdl,
2881 libtool, The Libtool Manual}.
2883 @node LTLIBOBJ, Libtool Issues, Libtool Flags, A Shared Library
2884 @subsection @code{LTLIBOBJS}
2885 @cindex @code{LTLIBOBJS}, special handling
2890 Where an ordinary library might include @code{$(LIBOBJS)}, a libtool
2891 library must use @code{$(LTLIBOBJS)}. This is required because the
2892 object files that libtool operates on do not necessarily end in
2895 Nowadays, the computation of @code{LTLIBOBJS} from @code{LIBOBJS} is
2896 performed automatically by Autoconf (@pxref{AC_LIBOBJ vs LIBOBJS, ,
2897 @code{AC_LIBOBJ} vs. @code{LIBOBJS}, autoconf, The Autoconf Manual}).
2899 @node Libtool Issues
2900 @subsection Common Issues Related to Libtool's Use
2902 @subsubsection @code{required file `./ltmain.sh' not found}
2903 @cindex ltmain.sh not found
2904 @cindex libtoolize, no longer run by Automake
2905 @cindex libtoolize and autoreconf
2906 @cindex autoreconf and libtoolize
2907 @cindex bootstrap.sh and autoreconf
2908 @cindex autogen.sh and autoreconf
2910 Libtool comes with a tool called @command{libtoolize} that will
2911 install libtool's supporting files into a package. Running this
2912 command will install @file{ltmain.sh}. You should execute it before
2913 @command{aclocal} and @command{automake}.
2915 People upgrading old packages to newer autotools are likely to face
2916 this issue because older Automake versions used to call
2917 @command{libtoolize}. Therefore old build scripts do not call
2918 @command{libtoolize}.
2920 Since Automake 1.6, it has been decided that running
2921 @command{libtoolize} was none of Automake's business. Instead, that
2922 functionality has been moved into the @command{autoreconf} command
2923 (@pxref{autoreconf Invocation, , Using @command{autoreconf}, autoconf,
2924 The Autoconf Manual}). If you do not want to remember what to run and
2925 when, just learn the @command{autoreconf} command. Hopefully,
2926 replacing existing @file{bootstrap.sh} or @file{autogen.sh} scripts by
2927 a call to @command{autoreconf} should also free you from any similar
2928 incompatible change in the future.
2930 @subsubsection Objects @code{created with both libtool and without}
2932 Sometimes, the same source file is used both to build a libtool
2933 library and to build another non-libtool target (be it a program or
2936 Let's consider the following @file{Makefile.am}.
2940 prog_SOURCES = prog.c foo.c @dots{}
2942 lib_LTLIBRARIES = libfoo.la
2943 libfoo_la_SOURCES = foo.c @dots{}
2947 (In this trivial case the issue could be avoided by linking
2948 @file{libfoo.la} with @file{prog} instead of listing @file{foo.c} in
2949 @code{prog_SOURCES}. But let's assume we really want to keep
2950 @file{prog} and @file{libfoo.la} separate.)
2952 Technically, it means that we should build @file{foo.$(OBJEXT)} for
2953 @file{prog}, and @file{foo.lo} for @file{libfoo.la}. The problem is
2954 that in the course of creating @file{foo.lo}, libtool may erase (or
2955 replace) @file{foo.$(OBJEXT)} -- and this cannot be avoided.
2957 Therefore, when Automake detects this situation it will complain
2958 with a message such as
2960 object `foo.$(OBJEXT)' created both with libtool and without
2963 A workaround for this issue is to ensure that these two objects get
2964 different basenames. As explained in @ref{renamed objects}, this
2965 happens automatically when per-targets flags are used.
2969 prog_SOURCES = prog.c foo.c @dots{}
2970 prog_CFLAGS = $(AM_CFLAGS)
2972 lib_LTLIBRARIES = libfoo.la
2973 libfoo_la_SOURCES = foo.c @dots{}
2977 Adding @code{prog_CFLAGS = $(AM_CFLAGS)} is almost a no-op, because
2978 when the @code{prog_CFLAGS} is defined, it is used instead of
2979 @code{AM_CFLAGS}. However as a side effect it will cause
2980 @file{prog.c} and @file{foo.c} to be compiled as
2981 @file{prog-prog.$(OBJEXT)} and @file{prog-foo.$(OBJEXT)} which solves
2984 @node Program and Library Variables
2985 @section Program and Library Variables
2987 Associated with each program are a collection of variables which can be
2988 used to modify how that program is built. There is a similar list of
2989 such variables for each library. The canonical name of the program (or
2990 library) is used as a base for naming these variables.
2992 In the list below, we use the name ``maude'' to refer to the program or
2993 library. In your @file{Makefile.am} you would replace this with the
2994 canonical name of your program. This list also refers to ``maude'' as a
2995 program, but in general the same rules apply for both static and dynamic
2996 libraries; the documentation below notes situations where programs and
3001 This variable, if it exists, lists all the source files which are
3002 compiled to build the program. These files are added to the
3003 distribution by default. When building the program, Automake will cause
3004 each source file to be compiled to a single @file{.o} file (or
3005 @file{.lo} when using libtool). Normally these object files are named
3006 after the source file, but other factors can change this. If a file in
3007 the @samp{_SOURCES} variable has an unrecognized extension, Automake
3008 will do one of two things with it. If a suffix rule exists for turning
3009 files with the unrecognized extension into @file{.o} files, then
3010 automake will treat this file as it will any other source file
3011 (@pxref{Support for Other Languages}). Otherwise, the file will be
3012 ignored as though it were a header file.
3014 The prefixes @samp{dist_} and @samp{nodist_} can be used to control
3015 whether files listed in a @samp{_SOURCES} variable are distributed.
3016 @samp{dist_} is redundant, as sources are distributed by default, but it
3017 can be specified for clarity if desired.
3019 It is possible to have both @samp{dist_} and @samp{nodist_} variants of
3020 a given @samp{_SOURCES} variable at once; this lets you easily
3021 distribute some files and not others, for instance:
3024 nodist_maude_SOURCES = nodist.c
3025 dist_maude_SOURCES = dist-me.c
3028 By default the output file (on Unix systems, the @file{.o} file) will be
3029 put into the current build directory. However, if the option
3030 @code{subdir-objects} is in effect in the current directory then the
3031 @file{.o} file will be put into the subdirectory named after the source
3032 file. For instance, with @code{subdir-objects} enabled,
3033 @file{sub/dir/file.c} will be compiled to @file{sub/dir/file.o}. Some
3034 people prefer this mode of operation. You can specify
3035 @code{subdir-objects} in @code{AUTOMAKE_OPTIONS} (@pxref{Options}).
3036 @cindex Subdirectory, objects in
3037 @cindex Objects in subdirectory
3040 @item EXTRA_maude_SOURCES
3041 Automake needs to know the list of files you intend to compile
3042 @emph{statically}. For one thing, this is the only way Automake has of
3043 knowing what sort of language support a given @file{Makefile.in}
3044 requires. @footnote{There are other, more obscure reasons reasons for
3045 this limitation as well.} This means that, for example, you can't put a
3046 configure substitution like @samp{@@my_sources@@} into a @samp{_SOURCES}
3047 variable. If you intend to conditionally compile source files and use
3048 @file{configure} to substitute the appropriate object names into, e.g.,
3049 @samp{_LDADD} (see below), then you should list the corresponding source
3050 files in the @samp{EXTRA_} variable.
3052 This variable also supports @samp{dist_} and @samp{nodist_} prefixes,
3053 e.g., @samp{nodist_EXTRA_maude_SOURCES}.
3056 A static library is created by default by invoking @code{$(AR)
3057 $(ARFLAGS)} followed by the name of the library and then the objects
3058 being put into the library. You can override this by setting the
3059 @samp{_AR} variable. This is usually used with C++; some C++
3060 compilers require a special invocation in order to instantiate all the
3061 templates which should go into a library. For instance, the SGI C++
3062 compiler likes this variable set like so:
3064 libmaude_a_AR = $(CXX) -ar -o
3068 Extra objects can be added to a @emph{library} using the @samp{_LIBADD}
3069 variable. For instance this should be used for objects determined by
3070 @code{configure} (@pxref{A Library}).
3073 Extra objects can be added to a @emph{program} by listing them in the
3074 @samp{_LDADD} variable. For instance this should be used for objects
3075 determined by @code{configure} (@pxref{Linking}).
3077 @samp{_LDADD} and @samp{_LIBADD} are inappropriate for passing
3078 program-specific linker flags (except for @samp{-l}, @samp{-L},
3079 @samp{-dlopen} and @samp{-dlpreopen}). Use the @samp{_LDFLAGS} variable
3082 For instance, if your @file{configure.ac} uses @code{AC_PATH_XTRA}, you
3083 could link your program against the X libraries like so:
3086 maude_LDADD = $(X_PRE_LIBS) $(X_LIBS) $(X_EXTRA_LIBS)
3090 This variable is used to pass extra flags to the link step of a program
3091 or a shared library.
3093 @item maude_DEPENDENCIES
3094 It is also occasionally useful to have a program depend on some other
3095 target which is not actually part of that program. This can be done
3096 using the @samp{_DEPENDENCIES} variable. Each program depends on the
3097 contents of such a variable, but no further interpretation is done.
3099 If @samp{_DEPENDENCIES} is not supplied, it is computed by Automake.
3100 The automatically-assigned value is the contents of @samp{_LDADD} or
3101 @samp{_LIBADD}, with most configure substitutions, @samp{-l}, @samp{-L},
3102 @samp{-dlopen} and @samp{-dlpreopen} options removed. The configure
3103 substitutions that are left in are only @samp{$(LIBOBJS)} and
3104 @samp{$(ALLOCA)}; these are left because it is known that they will not
3105 cause an invalid value for @samp{_DEPENDENCIES} to be generated.
3108 You can override the linker on a per-program basis. By default the
3109 linker is chosen according to the languages used by the program. For
3110 instance, a program that includes C++ source code would use the C++
3111 compiler to link. The @samp{_LINK} variable must hold the name of a
3112 command which can be passed all the @file{.o} file names as arguments.
3113 Note that the name of the underlying program is @emph{not} passed to
3114 @samp{_LINK}; typically one uses @samp{$@@}:
3117 maude_LINK = $(CCLD) -magic -o $@@
3120 @item maude_CCASFLAGS
3122 @itemx maude_CPPFLAGS
3123 @itemx maude_CXXFLAGS
3125 @itemx maude_GCJFLAGS
3127 @itemx maude_OBJCFLAGS
3130 @cindex per-target compilation flags, defined
3131 Automake allows you to set compilation flags on a per-program (or
3132 per-library) basis. A single source file can be included in several
3133 programs, and it will potentially be compiled with different flags for
3134 each program. This works for any language directly supported by
3135 Automake. These @dfn{per-target compilation flags} are
3147 When using a per-target compilation flag, Automake will choose a
3148 different name for the intermediate object files. Ordinarily a file
3149 like @file{sample.c} will be compiled to produce @file{sample.o}.
3150 However, if the program's @samp{_CFLAGS} variable is set, then the
3151 object file will be named, for instance, @file{maude-sample.o}.
3152 (See also @ref{renamed objects}.)
3154 In compilations with per-target flags, the ordinary @samp{AM_} form of
3155 the flags variable is @emph{not} automatically included in the
3156 compilation (however, the user form of the variable @emph{is} included).
3157 So for instance, if you want the hypothetical @file{maude} compilations
3158 to also use the value of @samp{AM_CFLAGS}, you would need to write:
3161 maude_CFLAGS = @dots{} your flags @dots{} $(AM_CFLAGS)
3165 @item maude_SHORTNAME
3166 On some platforms the allowable file names are very short. In order to
3167 support these systems and per-target compilation flags at the same
3168 time, Automake allows you to set a ``short name'' which will influence
3169 how intermediate object files are named. For instance, in the following
3173 bin_PROGRAMS = maude
3174 maude_CPPFLAGS = -DSOMEFLAG
3176 maude_SOURCES = sample.c @dots{}
3180 the object file would be named @file{m-sample.o} rather than
3181 @file{maude-sample.o}.
3183 This facility is rarely needed in practice,
3184 and we recommend avoiding it until you find it is required.
3188 @section Special handling for LIBOBJS and ALLOCA
3190 @cindex @code{LIBOBJS}, special handling
3191 @cindex @code{ALLOCA}, special handling
3193 Automake explicitly recognizes the use of @code{$(LIBOBJS)} and
3194 @code{$(ALLOCA)}, and uses this information, plus the list of
3195 @code{LIBOBJS} files derived from @file{configure.ac} to automatically
3196 include the appropriate source files in the distribution (@pxref{Dist}).
3197 These source files are also automatically handled in the
3198 dependency-tracking scheme; see @xref{Dependencies}.
3200 @code{$(LIBOBJS)} and @code{$(ALLOCA)} are specially recognized in any
3201 @samp{_LDADD} or @samp{_LIBADD} variable.
3204 @node Program variables
3205 @section Variables used when building a program
3207 Occasionally it is useful to know which @file{Makefile} variables
3208 Automake uses for compilations; for instance you might need to do your
3209 own compilation in some special cases.
3211 Some variables are inherited from Autoconf; these are @code{CC},
3212 @code{CFLAGS}, @code{CPPFLAGS}, @code{DEFS}, @code{LDFLAGS}, and
3221 There are some additional variables which Automake itself defines:
3225 The contents of this variable are passed to every compilation which invokes
3226 the C preprocessor; it is a list of arguments to the preprocessor. For
3227 instance, @samp{-I} and @samp{-D} options should be listed here.
3229 Automake already provides some @samp{-I} options automatically. In
3230 particular it generates @samp{-I$(srcdir)}, @samp{-I.}, and a @samp{-I}
3231 pointing to the directory holding @file{config.h} (if you've used
3232 @code{AC_CONFIG_HEADERS} or @code{AM_CONFIG_HEADER}). You can disable
3233 the default @samp{-I} options using the @samp{nostdinc} option.
3235 @code{AM_CPPFLAGS} is ignored in preference to a per-executable (or
3236 per-library) @code{_CPPFLAGS} variable if it is defined.
3239 This does the same job as @samp{AM_CPPFLAGS} (or any per-target
3240 @samp{_CPPFLAGS} variable if it is used). It is an older name for the
3241 same functionality. This variable is deprecated; we suggest using
3242 @samp{AM_CPPFLAGS} and per-target @samp{_CPPFLAGS} instead.
3245 This is the variable which the @file{Makefile.am} author can use to pass
3246 in additional C compiler flags. It is more fully documented elsewhere.
3247 In some situations, this is not used, in preference to the
3248 per-executable (or per-library) @code{_CFLAGS}.
3251 This is the command used to actually compile a C source file. The
3252 filename is appended to form the complete command line.
3255 This is the variable which the @file{Makefile.am} author can use to pass
3256 in additional linker flags. In some situations, this is not used, in
3257 preference to the per-executable (or per-library) @code{_LDFLAGS}.
3260 This is the command used to actually link a C program. It already
3261 includes @samp{-o $@@} and the usual variable references (for instance,
3262 @code{CFLAGS}); it takes as ``arguments'' the names of the object files
3263 and libraries to link in.
3268 @section Yacc and Lex support
3270 Automake has somewhat idiosyncratic support for Yacc and Lex.
3272 Automake assumes that the @file{.c} file generated by @code{yacc} (or
3273 @code{lex}) should be named using the basename of the input file. That
3274 is, for a yacc source file @file{foo.y}, Automake will cause the
3275 intermediate file to be named @file{foo.c} (as opposed to
3276 @file{y.tab.c}, which is more traditional).
3278 The extension of a yacc source file is used to determine the extension
3279 of the resulting @samp{C} or @samp{C++} file. Files with the extension
3280 @samp{.y} will be turned into @samp{.c} files; likewise, @samp{.yy} will
3281 become @samp{.cc}; @samp{.y++}, @samp{c++}; and @samp{.yxx},
3284 Likewise, lex source files can be used to generate @samp{C} or
3285 @samp{C++}; the extensions @samp{.l}, @samp{.ll}, @samp{.l++}, and
3286 @samp{.lxx} are recognized.
3288 You should never explicitly mention the intermediate (@samp{C} or
3289 @samp{C++}) file in any @samp{SOURCES} variable; only list the source
3292 The intermediate files generated by @code{yacc} (or @code{lex}) will be
3293 included in any distribution that is made. That way the user doesn't
3294 need to have @code{yacc} or @code{lex}.
3296 If a @code{yacc} source file is seen, then your @file{configure.ac} must
3297 define the variable @samp{YACC}. This is most easily done by invoking
3298 the macro @samp{AC_PROG_YACC} (@pxref{Particular Programs, , Particular
3299 Program Checks, autoconf, The Autoconf Manual}).
3301 When @code{yacc} is invoked, it is passed @samp{YFLAGS} and
3302 @samp{AM_YFLAGS}. The former is a user variable and the latter is
3303 intended for the @file{Makefile.am} author.
3305 @samp{AM_YFLAGS} is usually used to pass the @code{-d} option to
3306 @code{yacc}. Automake knows what this means and will automatically
3307 adjust its rules to update and distribute the header file built by
3308 @code{yacc -d}. What Automake cannot guess, though, is where this
3309 header will be used: it is up to you to ensure the header gets built
3310 before it is first used. Typically this is necessary in order for
3311 dependency tracking to work when the header is included by another
3312 file. The common solution is listing the header file in
3313 @code{BUILT_SOURCES} (@pxref{Sources}) as follows.
3316 BUILT_SOURCES = parser.h
3319 foo_SOURCES = @dots{} parser.y @dots{}
3322 If a @code{lex} source file is seen, then your @file{configure.ac}
3323 must define the variable @samp{LEX}. You can use @samp{AC_PROG_LEX}
3324 to do this (@pxref{Particular Programs, , Particular Program Checks,
3325 autoconf, The Autoconf Manual}), but using @code{AM_PROG_LEX} macro
3326 (@pxref{Macros}) is recommended.
3328 When @code{lex} is invoked, it is passed @samp{LFLAGS} and
3329 @samp{AM_LFLAGS}. The former is a user variable and the latter is
3330 intended for the @file{Makefile.am} author.
3335 @cindex yacc, multiple parsers
3336 @cindex Multiple yacc parsers
3337 @cindex Multiple lex lexers
3338 @cindex lex, multiple lexers
3341 Automake makes it possible to include multiple @code{yacc} (or
3342 @code{lex}) source files in a single program. When there is more than
3343 one distinct @code{yacc} (or @code{lex}) source file in a directory,
3344 Automake uses a small program called @code{ylwrap} to run @code{yacc}
3345 (or @code{lex}) in a subdirectory. This is necessary because yacc's
3346 output filename is fixed, and a parallel make could conceivably invoke
3347 more than one instance of @code{yacc} simultaneously. The @code{ylwrap}
3348 program is distributed with Automake. It should appear in the directory
3349 specified by @samp{AC_CONFIG_AUX_DIR} (@pxref{Input, , Finding
3350 `configure' Input, autoconf, The Autoconf Manual}), or the current
3351 directory if that macro is not used in @file{configure.ac}.
3353 For @code{yacc}, simply managing locking is insufficient. The output of
3354 @code{yacc} always uses the same symbol names internally, so it isn't
3355 possible to link two @code{yacc} parsers into the same executable.
3357 We recommend using the following renaming hack used in @code{gdb}:
3359 #define yymaxdepth c_maxdepth
3360 #define yyparse c_parse
3362 #define yyerror c_error
3363 #define yylval c_lval
3364 #define yychar c_char
3365 #define yydebug c_debug
3366 #define yypact c_pact
3373 #define yyexca c_exca
3374 #define yyerrflag c_errflag
3375 #define yynerrs c_nerrs
3379 #define yy_yys c_yys
3380 #define yystate c_state
3383 #define yy_yyv c_yyv
3385 #define yylloc c_lloc
3386 #define yyreds c_reds
3387 #define yytoks c_toks
3388 #define yylhs c_yylhs
3389 #define yylen c_yylen
3390 #define yydefred c_yydefred
3391 #define yydgoto c_yydgoto
3392 #define yysindex c_yysindex
3393 #define yyrindex c_yyrindex
3394 #define yygindex c_yygindex
3395 #define yytable c_yytable
3396 #define yycheck c_yycheck
3397 #define yyname c_yyname
3398 #define yyrule c_yyrule
3401 For each define, replace the @samp{c_} prefix with whatever you like.
3402 These defines work for @code{bison}, @code{byacc}, and traditional
3403 @code{yacc}s. If you find a parser generator that uses a symbol not
3404 covered here, please report the new name so it can be added to the list.
3408 @section C++ Support
3411 @cindex Support for C++
3413 Automake includes full support for C++.
3415 Any package including C++ code must define the output variable
3416 @samp{CXX} in @file{configure.ac}; the simplest way to do this is to use
3417 the @code{AC_PROG_CXX} macro (@pxref{Particular Programs, , Particular
3418 Program Checks, autoconf, The Autoconf Manual}).
3420 A few additional variables are defined when a C++ source file is seen:
3424 The name of the C++ compiler.
3427 Any flags to pass to the C++ compiler.
3430 The maintainer's variant of @code{CXXFLAGS}.
3433 The command used to actually compile a C++ source file. The file name
3434 is appended to form the complete command line.
3437 The command used to actually link a C++ program.
3441 @node Assembly Support
3442 @section Assembly Support
3444 Automake includes some support for assembly code.
3446 The variable @code{CCAS} holds the name of the compiler used to build
3447 assembly code. This compiler must work a bit like a C compiler; in
3448 particular it must accept @samp{-c} and @samp{-o}. The value of
3449 @code{CCASFLAGS} is passed to the compilation.
3453 You are required to set @code{CCAS} and @code{CCASFLAGS} via
3454 @file{configure.ac}. The autoconf macro @code{AM_PROG_AS} will do this
3455 for you. Unless they are already set, it simply sets @code{CCAS} to the
3456 C compiler and @code{CCASFLAGS} to the C compiler flags.
3458 Only the suffixes @samp{.s} and @samp{.S} are recognized by
3459 @code{automake} as being files containing assembly code.
3462 @node Fortran 77 Support
3463 @comment node-name, next, previous, up
3464 @section Fortran 77 Support
3466 @cindex Fortran 77 support
3467 @cindex Support for Fortran 77
3469 Automake includes full support for Fortran 77.
3471 Any package including Fortran 77 code must define the output variable
3472 @samp{F77} in @file{configure.ac}; the simplest way to do this is to use
3473 the @code{AC_PROG_F77} macro (@pxref{Particular Programs, , Particular
3474 Program Checks, autoconf, The Autoconf Manual}). @xref{Fortran 77 and
3477 A few additional variables are defined when a Fortran 77 source file is
3483 The name of the Fortran 77 compiler.
3486 Any flags to pass to the Fortran 77 compiler.
3489 The maintainer's variant of @code{FFLAGS}.
3492 Any flags to pass to the Ratfor compiler.
3495 The maintainer's variant of @code{RFLAGS}.
3498 The command used to actually compile a Fortran 77 source file. The file
3499 name is appended to form the complete command line.
3502 The command used to actually link a pure Fortran 77 program or shared
3507 Automake can handle preprocessing Fortran 77 and Ratfor source files in
3508 addition to compiling them@footnote{Much, if not most, of the
3509 information in the following sections pertaining to preprocessing
3510 Fortran 77 programs was taken almost verbatim from @ref{Catalogue of
3511 Rules, , Catalogue of Rules, make, The GNU Make Manual}.}. Automake
3512 also contains some support for creating programs and shared libraries
3513 that are a mixture of Fortran 77 and other languages (@pxref{Mixing
3514 Fortran 77 With C and C++}).
3516 These issues are covered in the following sections.
3519 * Preprocessing Fortran 77::
3520 * Compiling Fortran 77 Files::
3521 * Mixing Fortran 77 With C and C++::
3522 * Fortran 77 and Autoconf::
3526 @node Preprocessing Fortran 77
3527 @comment node-name, next, previous, up
3528 @subsection Preprocessing Fortran 77
3530 @cindex Preprocessing Fortran 77
3531 @cindex Fortran 77, Preprocessing
3532 @cindex Ratfor programs
3534 @file{N.f} is made automatically from @file{N.F} or @file{N.r}. This
3535 rule runs just the preprocessor to convert a preprocessable Fortran 77
3536 or Ratfor source file into a strict Fortran 77 source file. The precise
3537 command used is as follows:
3542 @code{$(F77) -F $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_FFLAGS) $(FFLAGS)}
3545 @code{$(F77) -F $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
3550 @node Compiling Fortran 77 Files
3551 @comment node-name, next, previous, up
3552 @subsection Compiling Fortran 77 Files
3554 @file{N.o} is made automatically from @file{N.f}, @file{N.F} or
3555 @file{N.r} by running the Fortran 77 compiler. The precise command used
3561 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS)}
3564 @code{$(F77) -c $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_FFLAGS) $(FFLAGS)}
3567 @code{$(F77) -c $(AM_FFLAGS) $(FFLAGS) $(AM_RFLAGS) $(RFLAGS)}
3572 @node Mixing Fortran 77 With C and C++
3573 @comment node-name, next, previous, up
3574 @subsection Mixing Fortran 77 With C and C++
3576 @cindex Fortran 77, mixing with C and C++
3577 @cindex Mixing Fortran 77 with C and C++
3578 @cindex Linking Fortran 77 with C and C++
3580 @cindex Mixing Fortran 77 with C and/or C++
3582 Automake currently provides @emph{limited} support for creating programs
3583 and shared libraries that are a mixture of Fortran 77 and C and/or C++.
3584 However, there are many other issues related to mixing Fortran 77 with
3585 other languages that are @emph{not} (currently) handled by Automake, but
3586 that are handled by other packages@footnote{For example,
3587 @uref{http://www-zeus.desy.de/~burow/cfortran/, the cfortran package}
3588 addresses all of these inter-language issues, and runs under nearly all
3589 Fortran 77, C and C++ compilers on nearly all platforms. However,
3590 @code{cfortran} is not yet Free Software, but it will be in the next
3594 Automake can help in two ways:
3598 Automatic selection of the linker depending on which combinations of
3602 Automatic selection of the appropriate linker flags (e.g. @samp{-L} and
3603 @samp{-l}) to pass to the automatically selected linker in order to link
3604 in the appropriate Fortran 77 intrinsic and run-time libraries.
3606 @cindex FLIBS, defined
3607 These extra Fortran 77 linker flags are supplied in the output variable
3608 @code{FLIBS} by the @code{AC_F77_LIBRARY_LDFLAGS} Autoconf macro
3609 supplied with newer versions of Autoconf (Autoconf version 2.13 and
3610 later). @xref{Fortran 77 Compiler Characteristics, , , autoconf, The
3614 If Automake detects that a program or shared library (as mentioned in
3615 some @code{_PROGRAMS} or @code{_LTLIBRARIES} primary) contains source
3616 code that is a mixture of Fortran 77 and C and/or C++, then it requires
3617 that the macro @code{AC_F77_LIBRARY_LDFLAGS} be called in
3618 @file{configure.ac}, and that either @code{$(FLIBS)}
3619 appear in the appropriate @code{_LDADD} (for programs) or @code{_LIBADD}
3620 (for shared libraries) variables. It is the responsibility of the
3621 person writing the @file{Makefile.am} to make sure that @code{$(FLIBS)}
3622 appears in the appropriate @code{_LDADD} or
3623 @code{_LIBADD} variable.
3625 @cindex Mixed language example
3626 @cindex Example, mixed language
3628 For example, consider the following @file{Makefile.am}:
3632 foo_SOURCES = main.cc foo.f
3633 foo_LDADD = libfoo.la $(FLIBS)
3635 pkglib_LTLIBRARIES = libfoo.la
3636 libfoo_la_SOURCES = bar.f baz.c zardoz.cc
3637 libfoo_la_LIBADD = $(FLIBS)
3640 In this case, Automake will insist that @code{AC_F77_LIBRARY_LDFLAGS}
3641 is mentioned in @file{configure.ac}. Also, if @code{$(FLIBS)} hadn't
3642 been mentioned in @code{foo_LDADD} and @code{libfoo_la_LIBADD}, then
3643 Automake would have issued a warning.
3648 * How the Linker is Chosen::
3651 @node How the Linker is Chosen
3652 @comment node-name, next, previous, up
3653 @subsubsection How the Linker is Chosen
3655 @cindex Automatic linker selection
3656 @cindex Selecting the linker automatically
3658 The following diagram demonstrates under what conditions a particular
3659 linker is chosen by Automake.
3661 For example, if Fortran 77, C and C++ source code were to be compiled
3662 into a program, then the C++ linker will be used. In this case, if the
3663 C or Fortran 77 linkers required any special libraries that weren't
3664 included by the C++ linker, then they must be manually added to an
3665 @code{_LDADD} or @code{_LIBADD} variable by the user writing the
3671 code \ C C++ Fortran
3672 ----------------- +---------+---------+---------+
3676 +---------+---------+---------+
3680 +---------+---------+---------+
3684 +---------+---------+---------+
3688 +---------+---------+---------+
3690 C + Fortran | | | x |
3692 +---------+---------+---------+
3694 C++ + Fortran | | x | |
3696 +---------+---------+---------+
3698 C + C++ + Fortran | | x | |
3700 +---------+---------+---------+
3704 @node Fortran 77 and Autoconf
3705 @comment node-name, next, previous, up
3706 @subsection Fortran 77 and Autoconf
3708 The current Automake support for Fortran 77 requires a recent enough
3709 version of Autoconf that also includes support for Fortran 77. Full
3710 Fortran 77 support was added to Autoconf 2.13, so you will want to use
3711 that version of Autoconf or later.
3715 @comment node-name, next, previous, up
3716 @section Java Support
3718 @cindex Java support
3719 @cindex Support for Java
3721 Automake includes support for compiled Java, using @code{gcj}, the Java
3722 front end to the GNU Compiler Collection.
3724 Any package including Java code to be compiled must define the output
3725 variable @samp{GCJ} in @file{configure.ac}; the variable @samp{GCJFLAGS}
3726 must also be defined somehow (either in @file{configure.ac} or
3727 @file{Makefile.am}). The simplest way to do this is to use the
3728 @code{AM_PROG_GCJ} macro.
3732 By default, programs including Java source files are linked with
3735 As always, the contents of @samp{AM_GCJFLAGS} are passed to every
3736 compilation invoking @code{gcj} (in its role as an ahead-of-time
3737 compiler -- when invoking it to create @file{.class} files,
3738 @samp{AM_JAVACFLAGS} is used instead). If it is necessary to pass
3739 options to @code{gcj} from @file{Makefile.am}, this variable, and not
3740 the user variable @samp{GCJFLAGS}, should be used.
3744 @code{gcj} can be used to compile @file{.java}, @file{.class},
3745 @file{.zip}, or @file{.jar} files.
3747 When linking, @code{gcj} requires that the main class be specified
3748 using the @samp{--main=} option. The easiest way to do this is to use
3749 the @code{_LDFLAGS} variable for the program.
3752 @node Support for Other Languages
3753 @comment node-name, next, previous, up
3754 @section Support for Other Languages
3756 Automake currently only includes full support for C, C++ (@pxref{C++
3757 Support}), Fortran 77 (@pxref{Fortran 77 Support}), and Java
3758 (@pxref{Java Support}). There is only rudimentary support for other
3759 languages, support for which will be improved based on user demand.
3761 Some limited support for adding your own languages is available via the
3762 suffix rule handling; see @ref{Suffixes}.
3766 @section Automatic de-ANSI-fication
3768 @cindex de-ANSI-fication, defined
3770 Although the GNU standards allow the use of ANSI C, this can have the
3771 effect of limiting portability of a package to some older compilers
3772 (notably the SunOS C compiler).
3774 Automake allows you to work around this problem on such machines by
3775 @dfn{de-ANSI-fying} each source file before the actual compilation takes
3778 @vindex AUTOMAKE_OPTIONS
3781 If the @file{Makefile.am} variable @code{AUTOMAKE_OPTIONS}
3782 (@pxref{Options}) contains the option @code{ansi2knr} then code to
3783 handle de-ANSI-fication is inserted into the generated
3786 This causes each C source file in the directory to be treated as ANSI C@.
3787 If an ANSI C compiler is available, it is used. If no ANSI C compiler
3788 is available, the @code{ansi2knr} program is used to convert the source
3789 files into K&R C, which is then compiled.
3791 The @code{ansi2knr} program is simple-minded. It assumes the source
3792 code will be formatted in a particular way; see the @code{ansi2knr} man
3795 Support for de-ANSI-fication requires the source files @file{ansi2knr.c}
3796 and @file{ansi2knr.1} to be in the same package as the ANSI C source;
3797 these files are distributed with Automake. Also, the package
3798 @file{configure.ac} must call the macro @code{AM_C_PROTOTYPES}
3800 @cvindex AM_C_PROTOTYPES
3802 Automake also handles finding the @code{ansi2knr} support files in some
3803 other directory in the current package. This is done by prepending the
3804 relative path to the appropriate directory to the @code{ansi2knr}
3805 option. For instance, suppose the package has ANSI C code in the
3806 @file{src} and @file{lib} subdirectories. The files @file{ansi2knr.c} and
3807 @file{ansi2knr.1} appear in @file{lib}. Then this could appear in
3808 @file{src/Makefile.am}:
3811 AUTOMAKE_OPTIONS = ../lib/ansi2knr
3814 If no directory prefix is given, the files are assumed to be in the
3817 Note that automatic de-ANSI-fication will not work when the package is
3818 being built for a different host architecture. That is because automake
3819 currently has no way to build @code{ansi2knr} for the build machine.
3821 @c FIXME: this paragraph might be better moved to an `upgrading' section.
3822 @cindex @code{LTLIBOBJS} and @code{ansi2knr}
3823 @cindex @code{LIBOBJS} and @code{ansi2knr}
3824 @cindex @code{ansi2knr} and @code{LTLIBOBJS}
3825 @cindex @code{ansi2knr} and @code{LIBOBJS}
3826 Using @code{LIBOBJS} with source de-ANSI-fication used to require
3827 hand-crafted code in @file{configure} to append @code{$U} to basenames
3828 in @code{LIBOBJS}. This is no longer true today. Starting with version
3829 2.54, Autoconf takes care of rewriting @code{LIBOBJS} and
3830 @code{LTLIBOBJS}. (@pxref{AC_LIBOBJ vs LIBOBJS, , @code{AC_LIBOBJ}
3831 vs. @code{LIBOBJS}, autoconf, The Autoconf Manual})
3834 @section Automatic dependency tracking
3836 As a developer it is often painful to continually update the
3837 @file{Makefile.in} whenever the include-file dependencies change in a
3838 project. Automake supplies a way to automatically track dependency
3841 @cindex Dependency tracking
3842 @cindex Automatic dependency tracking
3844 Automake always uses complete dependencies for a compilation, including
3845 system headers. Automake's model is that dependency computation should
3846 be a side effect of the build. To this end, dependencies are computed
3847 by running all compilations through a special wrapper program called
3848 @code{depcomp}. @code{depcomp} understands how to coax many different C
3849 and C++ compilers into generating dependency information in the format
3850 it requires. @code{automake -a} will install @code{depcomp} into your
3851 source tree for you. If @code{depcomp} can't figure out how to properly
3852 invoke your compiler, dependency tracking will simply be disabled for
3857 Experience with earlier versions of Automake @footnote{See
3858 @uref{http://sources.redhat.com/automake/dependencies.html} for more
3859 information on the history and experiences with automatic dependency
3860 tracking in Automake} taught us that it is not reliable to generate
3861 dependencies only on the maintainer's system, as configurations vary too
3862 much. So instead Automake implements dependency tracking at build time.
3864 Automatic dependency tracking can be suppressed by putting
3865 @code{no-dependencies} in the variable @code{AUTOMAKE_OPTIONS}, or
3866 passing @code{no-dependencies} as an argument to @code{AM_INIT_AUTOMAKE}
3867 (this should be the preferred way). Or, you can invoke @code{automake}
3868 with the @code{-i} option. Dependency tracking is enabled by default.
3870 @vindex AUTOMAKE_OPTIONS
3871 @opindex no-dependencies
3873 The person building your package also can choose to disable dependency
3874 tracking by configuring with @code{--disable-dependency-tracking}.
3876 @cindex Disabling dependency tracking
3877 @cindex Dependency tracking, disabling
3881 @section Support for executable extensions
3883 @cindex Executable extension
3884 @cindex Extension, executable
3887 On some platforms, such as Windows, executables are expected to have an
3888 extension such as @samp{.exe}. On these platforms, some compilers (GCC
3889 among them) will automatically generate @file{foo.exe} when asked to
3890 generate @file{foo}.
3892 Automake provides mostly-transparent support for this. Unfortunately
3893 @emph{mostly} doesn't yet mean @emph{fully}. Until the English
3894 dictionary is revised, you will have to assist Automake if your package
3895 must support those platforms.
3897 One thing you must be aware of is that, internally, Automake rewrites
3898 something like this:
3901 bin_PROGRAMS = liver
3907 bin_PROGRAMS = liver$(EXEEXT)
3910 The targets Automake generates are likewise given the @samp{$(EXEEXT)}
3911 extension. @code{EXEEXT}
3913 However, Automake cannot apply this rewriting to @code{configure}
3914 substitutions. This means that if you are conditionally building a
3915 program using such a substitution, then your @file{configure.ac} must
3916 take care to add @samp{$(EXEEXT)} when constructing the output variable.
3918 With Autoconf 2.13 and earlier, you must explicitly use @code{AC_EXEEXT}
3919 to get this support. With Autoconf 2.50, @code{AC_EXEEXT} is run
3920 automatically if you configure a compiler (say, through
3923 Sometimes maintainers like to write an explicit link rule for their
3924 program. Without executable extension support, this is easy---you
3925 simply write a target with the same name as the program. However, when
3926 executable extension support is enabled, you must instead add the
3927 @samp{$(EXEEXT)} suffix.
3929 Unfortunately, due to the change in Autoconf 2.50, this means you must
3930 always add this extension. However, this is a problem for maintainers
3931 who know their package will never run on a platform that has executable
3932 extensions. For those maintainers, the @code{no-exeext} option
3933 (@pxref{Options}) will disable this feature. This works in a fairly
3934 ugly way; if @code{no-exeext} is seen, then the presence of a target
3935 named @code{foo} in @file{Makefile.am} will override an
3936 automake-generated target of the form @code{foo$(EXEEXT)}. Without the
3937 @code{no-exeext} option, this use will give an error.
3941 @chapter Other Derived Objects
3943 Automake can handle derived objects which are not C programs. Sometimes
3944 the support for actually building such objects must be explicitly
3945 supplied, but Automake will still automatically handle installation and
3949 * Scripts:: Executable scripts
3950 * Headers:: Header files
3951 * Data:: Architecture-independent data files
3952 * Sources:: Derived sources
3957 @section Executable Scripts
3959 @cindex _SCRIPTS primary, defined
3960 @cindex SCRIPTS primary, defined
3961 @cindex Primary variable, SCRIPTS
3963 It is possible to define and install programs which are scripts. Such
3964 programs are listed using the @samp{SCRIPTS} primary name. Automake
3965 doesn't define any dependencies for scripts; the @file{Makefile.am}
3966 should include the appropriate rules.
3969 Automake does not assume that scripts are derived objects; such objects
3970 must be deleted by hand (@pxref{Clean}).
3972 The @code{automake} program itself is a Perl script that is generated
3973 from @file{automake.in}. Here is how this is handled:
3976 bin_SCRIPTS = automake
3977 CLEANFILES = $(bin_SCRIPTS)
3979 do_subst = sed -e 's,[@@]datadir[@@],$(datadir),g' \
3980 -e 's,[@@]PERL[@@],$(PERL),g' \
3981 -e 's,[@@]PACKAGE[@@],$(PACKAGE),g' \
3982 -e 's,[@@]VERSION[@@],$(VERSION),g' \
3985 automake: automake.in Makefile
3986 $(do_subst) < $(srcdir)/automake.in > automake
3990 Because---as we have just seen---scripts can be built, they are not
3991 distributed by default. Scripts that should be distributed can be
3992 specified using a @code{dist_} prefix as in other primaries. For
3993 instance the following @file{Makefile.am} declares that
3994 @file{my_script} should be distributed and installed in
3998 dist_sbin_SCRIPTS = my_script
4001 @cindex SCRIPTS, installation directories
4002 @cindex Installing scripts
4005 @vindex sbin_SCRIPTS
4006 @vindex libexec_SCRIPTS
4007 @vindex pkgdata_SCRIPTS
4008 @vindex noinst_SCRIPTS
4009 @vindex check_SCRIPTS
4011 Script objects can be installed in @code{bindir}, @code{sbindir},
4012 @code{libexecdir}, or @code{pkgdatadir}.
4014 Scripts that need not being installed can be listed in
4015 @code{noinst_SCRIPTS}, and among them, those which are needed only by
4016 @code{make check} should go in @code{check_SCRIPTS}.
4020 @section Header files
4022 @cindex _HEADERS primary, defined
4023 @cindex HEADERS primary, defined
4024 @cindex Primary variable, HEADERS
4026 @vindex noinst_HEADERS
4028 Header files are specified by the @samp{HEADERS} family of variables.
4029 Generally header files are not installed, so the @code{noinst_HEADERS}
4030 variable will be the most used. @footnote{However, for the case of a
4031 non-installed header file that is actually used by a particular program,
4032 we recommend listing it in the program's @samp{_SOURCES} variable
4033 instead of in @code{noinst_HEADERS}. We believe this is more clear.}
4036 All header files must be listed somewhere; missing ones will not appear
4037 in the distribution. Often it is clearest to list uninstalled headers
4038 with the rest of the sources for a program. @xref{A Program}. Headers
4039 listed in a @samp{_SOURCES} variable need not be listed in any
4040 @samp{_HEADERS} variable.
4042 @cindex HEADERS, installation directories
4043 @cindex Installing headers
4045 @vindex include_HEADERS
4046 @vindex oldinclude_HEADERS
4047 @vindex pkginclude_HEADERS
4049 Headers can be installed in @code{includedir}, @code{oldincludedir}, or
4050 @code{pkgincludedir}.
4054 @section Architecture-independent data files
4056 @cindex _DATA primary, defined
4057 @cindex DATA primary, defined
4058 @cindex Primary variable, DATA
4060 Automake supports the installation of miscellaneous data files using the
4061 @samp{DATA} family of variables.
4065 @vindex sysconf_DATA
4066 @vindex sharedstate_DATA
4067 @vindex localstate_DATA
4068 @vindex pkgdata_DATA
4070 Such data can be installed in the directories @code{datadir},
4071 @code{sysconfdir}, @code{sharedstatedir}, @code{localstatedir}, or
4074 By default, data files are @emph{not} included in a distribution. Of
4075 course, you can use the @samp{dist_} prefix to change this on a
4078 Here is how Automake declares its auxiliary data files:
4081 dist_pkgdata_DATA = clean-kr.am clean.am @dots{}
4086 @section Built sources
4088 Because Automake's automatic dependency tracking works as a side-effect
4089 of compilation (@pxref{Dependencies}) there is a bootstrap issue: a
4090 target should not be compiled before its dependencies are made, but
4091 these dependencies are unknown until the target is first compiled.
4093 Ordinarily this is not a problem, because dependencies are distributed
4094 sources: they preexist and do not need to be built. Suppose that
4095 @file{foo.c} includes @file{foo.h}. When it first compiles
4096 @file{foo.o}, @command{make} only knows that @file{foo.o} depends on
4097 @file{foo.c}. As a side-effect of this compilation @code{depcomp}
4098 records the @file{foo.h} dependency so that following invocations of
4099 @command{make} will honor it. In these conditions, it's clear there is
4100 no problem: either @file{foo.o} doesn't exist and has to be built
4101 (regardless of the dependencies), either accurate dependencies exist and
4102 they can be used to decide whether @file{foo.o} should be rebuilt.
4104 It's a different story if @file{foo.h} doesn't exist by the first
4105 @command{make} run. For instance there might be a rule to build
4106 @file{foo.h}. This time @file{file.o}'s build will fail because the
4107 compiler can't find @file{foo.h}. @command{make} failed to trigger the
4108 rule to build @file{foo.h} first by lack of dependency information.
4110 @vindex BUILT_SOURCES
4111 @cindex BUILT_SOURCES, defined
4113 The @code{BUILT_SOURCES} variable is a workaround for this problem. A
4114 source file listed in @code{BUILT_SOURCES} is made on @code{make all}
4115 or @code{make check} (or even @code{make install}) before other
4116 targets are processed. However, such a source file is not
4117 @emph{compiled} unless explicitly requested by mentioning it in some
4118 other @samp{_SOURCES} variable.
4120 So, to conclude our introductory example, we could use
4121 @code{BUILT_SOURCES = foo.h} to ensure @file{foo.h} gets built before
4122 any other target (including @file{foo.o}) during @code{make all} or
4125 @code{BUILT_SOURCES} is actually a bit of a misnomer, as any file which
4126 must be created early in the build process can be listed in this
4127 variable. Moreover, all built sources do not necessarily have to be
4128 listed in @code{BUILT_SOURCES}. For instance a generated @file{.c} file
4129 doesn't need to appear in @code{BUILT_SOURCES} (unless it is included by
4130 another source), because it's a known dependency of the associated
4133 It might be important to emphasize that @code{BUILT_SOURCES} is
4134 honored only by @code{make all}, @code{make check} and @code{make
4135 install}. This means you cannot build a specific target (e.g.,
4136 @code{make foo}) in a clean tree if it depends on a built source.
4137 However it will succeed if you have run @code{make all} earlier,
4138 because accurate dependencies are already available.
4140 The next section illustrates and discusses the handling of built sources
4144 * Built sources example:: Several ways to handle built sources.
4147 @node Built sources example
4148 @subsection Built sources example
4150 Suppose that @file{foo.c} includes @file{bindir.h}, which is
4151 installation-dependent and not distributed: it needs to be built. Here
4152 @file{bindir.h} defines the preprocessor macro @code{bindir} to the
4153 value of the @command{make} variable @code{bindir} (inherited from
4156 We suggest several implementations below. It's not meant to be an
4157 exhaustive listing of all ways to handle built sources, but it will give
4158 you a few ideas if you encounter this issue.
4160 @unnumberedsubsec First try
4162 This first implementation will illustrate the bootstrap issue mentioned
4163 in the previous section (@pxref{Sources}).
4165 Here is a tentative @file{Makefile.am}.
4171 nodist_foo_SOURCES = bindir.h
4172 CLEANFILES = bindir.h
4174 echo '#define bindir "$(bindir)"' >$@@
4177 This setup doesn't work, because Automake doesn't know that @file{foo.c}
4178 includes @file{bindir.h}. Remember, automatic dependency tracking works
4179 as a side-effect of compilation, so the dependencies of @file{foo.o} will
4180 be known only after @file{foo.o} has been compiled (@pxref{Dependencies}).
4181 The symptom is as follows.
4185 source='foo.c' object='foo.o' libtool=no \
4186 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
4187 depmode=gcc /bin/sh ./depcomp \
4188 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
4189 foo.c:2: bindir.h: No such file or directory
4190 make: *** [foo.o] Error 1
4193 @unnumberedsubsec Using @code{BUILT_SOURCES}
4195 A solution is to require @file{bindir.h} to be built before anything
4196 else. This is what @code{BUILT_SOURCES} is meant for (@pxref{Sources}).
4201 BUILT_SOURCES = bindir.h
4202 CLEANFILES = bindir.h
4204 echo '#define bindir "$(bindir)"' >$@@
4207 See how @file{bindir.h} get built first:
4211 echo '#define bindir "/usr/local/bin"' >bindir.h
4213 make[1]: Entering directory `/home/adl/tmp'
4214 source='foo.c' object='foo.o' libtool=no \
4215 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
4216 depmode=gcc /bin/sh ./depcomp \
4217 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
4218 gcc -g -O2 -o foo foo.o
4219 make[1]: Leaving directory `/home/adl/tmp'
4222 However, as said earlier, @code{BUILT_SOURCES} applies only to the
4223 @code{all}, @code{check}, and @code{install} targets. It still fails
4224 if you try to run @code{make foo} explicitly:
4228 test -z "bindir.h" || rm -f bindir.h
4229 test -z "foo" || rm -f foo
4231 % : > .deps/foo.Po # Suppress previously recorded dependencies
4233 source='foo.c' object='foo.o' libtool=no \
4234 depfile='.deps/foo.Po' tmpdepfile='.deps/foo.TPo' \
4235 depmode=gcc /bin/sh ./depcomp \
4236 gcc -I. -I. -g -O2 -c `test -f 'foo.c' || echo './'`foo.c
4237 foo.c:2: bindir.h: No such file or directory
4238 make: *** [foo.o] Error 1
4241 @unnumberedsubsec Recording dependencies manually
4243 Usually people are happy enough with @code{BUILT_SOURCES} because they
4244 never run targets such as @code{make foo} before @code{make all}, as in
4245 the previous example. However if this matters to you, you can avoid
4246 @code{BUILT_SOURCES} and record such dependencies explicitly in the
4252 foo.$(OBJEXT): bindir.h
4253 CLEANFILES = bindir.h
4255 echo '#define bindir "$(bindir)"' >$@@
4258 You don't have to list @emph{all} the dependencies of @code{foo.o}
4259 explicitly, only those which might need to be built. If a dependency
4260 already exists, it will not hinder the first compilation and will be
4261 recorded by the normal dependency tracking code. (Note that after this
4262 first compilation the dependency tracking code will also have recorded
4263 the dependency between @code{foo.o} and @code{bindir.h}; so our explicit
4264 dependency is really useful to the first build only.)
4266 Adding explicit dependencies like this can be a bit dangerous if you are
4267 not careful enough. This is due to the way Automake tries not to
4268 overwrite your rules (it assumes you know better than it).
4269 @code{foo.$(OBJEXT): bindir.h} supersedes any rule Automake may want to
4270 output to build @code{foo.$(OBJEXT)}. It happens to work in this case
4271 because Automake doesn't have to output any @code{foo.$(OBJEXT):}
4272 target: it relies on a suffix rule instead (i.e., @code{.c.$(OBJEXT):}).
4273 Always check the generated @file{Makefile.in} if you do this.
4275 @unnumberedsubsec Build @file{bindir.h} from @file{configure}
4277 It's possible to define this preprocessor macro from @file{configure},
4278 either in @file{config.h} (@pxref{Defining Directories, , Defining
4279 Directories, autoconf, The Autoconf Manual}), or by processing a
4280 @file{bindir.h.in} file using @code{AC_CONFIG_FILES}
4281 (@pxref{Configuration Actions, ,Configuration Actions, autoconf, The
4284 At this point it should be clear that building @file{bindir.h} from
4285 @file{configure} work well for this example. @file{bindir.h} will exist
4286 before you build any target, hence will not cause any dependency issue.
4288 The Makefile can be shrunk as follows. We do not even have to mention
4296 However, it's not always possible to build sources from
4297 @file{configure}, especially when these sources are generated by a tool
4298 that needs to be built first...
4300 @unnumberedsubsec Build @file{bindir.c}, not @file{bindir.h}.
4302 Another attractive idea is to define @code{bindir} as a variable or
4303 function exported from @file{bindir.o}, and build @file{bindir.c}
4304 instead of @file{bindir.h}.
4307 noinst_PROGRAMS = foo
4308 foo_SOURCES = foo.c bindir.h
4309 nodist_foo_SOURCES = bindir.c
4310 CLEANFILES = bindir.c
4312 echo 'const char bindir[] = "$(bindir)";' >$@
4315 @file{bindir.h} contains just the variable's declaration and doesn't
4316 need to be built, so it won't cause any trouble. @file{bindir.o} is
4317 always dependent on @file{bindir.c}, so @file{bindir.c} will get built
4320 @unnumberedsubsec Which is best?
4322 There is no panacea, of course. Each solution has its merits and
4325 You cannot use @code{BUILT_SOURCES} if the ability to run @code{make
4326 foo} on a clean tree is important to you.
4328 You won't add explicit dependencies if you are leery of overriding
4329 an Automake target by mistake.
4331 Building files from @file{./configure} is not always possible, neither
4332 is converting @file{.h} files into @file{.c} files.
4335 @node Other GNU Tools
4336 @chapter Other GNU Tools
4338 Since Automake is primarily intended to generate @file{Makefile.in}s for
4339 use in GNU programs, it tries hard to interoperate with other GNU tools.
4342 * Emacs Lisp:: Emacs Lisp
4353 @cindex _LISP primary, defined
4354 @cindex LISP primary, defined
4355 @cindex Primary variable, LISP
4361 Automake provides some support for Emacs Lisp. The @samp{LISP} primary
4362 is used to hold a list of @file{.el} files. Possible prefixes for this
4363 primary are @samp{lisp_} and @samp{noinst_}. Note that if
4364 @code{lisp_LISP} is defined, then @file{configure.ac} must run
4365 @code{AM_PATH_LISPDIR} (@pxref{Macros}).
4367 Automake will byte-compile all Emacs Lisp source files using the Emacs
4368 found by @code{AM_PATH_LISPDIR}, if any was found.
4370 Byte-compiled Emacs Lisp files are not portable among all versions of
4371 Emacs, so it makes sense to turn this off if you expect sites to have
4372 more than one version of Emacs installed. Furthermore, many packages
4373 don't actually benefit from byte-compilation. Still, we recommend
4374 that you byte-compile your Emacs Lisp sources. It is probably better
4375 for sites with strange setups to cope for themselves than to make the
4376 installation less nice for everybody else.
4378 There are two ways to avoid byte-compiling. Historically, we have
4379 recommended the following construct.
4381 lisp_LISP = file1.el file2.el
4385 @code{ELCFILES} is an internal Automake variables that normally lists
4386 all @file{.elc} files that must be byte-compiled. Automake defines
4387 @code{ELCFILES} automatically from @code{lisp_LISP}. Emptying this
4388 variables explicitly prevents byte-compilation to occur.
4390 Since Automake 1.8, we now recommend using @code{lisp_DATA} instead. As
4393 lisp_DATA = file1.el file2.el
4396 Note that these two constructs are not equivalent. @code{_LISP} will
4397 not install a file if Emacs is not installed, while @code{_DATA} will
4398 always install its files.
4403 @cindex GNU Gettext support
4404 @cindex Gettext support
4405 @cindex Support for GNU Gettext
4407 If @code{AM_GNU_GETTEXT} is seen in @file{configure.ac}, then Automake
4408 turns on support for GNU gettext, a message catalog system for
4409 internationalization
4410 (@pxref{GNU Gettext, , , gettext, GNU gettext utilities}).
4412 The @code{gettext} support in Automake requires the addition of two
4413 subdirectories to the package, @file{intl} and @file{po}. Automake
4414 insures that these directories exist and are mentioned in
4417 @vindex dist_lisp_LISP
4418 @vindex dist_noinst_LISP
4419 Lisp sources are not distributed by default. You can prefix the
4420 @code{LISP} primary with @code{dist_}, as in @code{dist_lisp_LISP} or
4421 @code{dist_noinst_LISP}, to indicate that these files should be
4427 Automake provides support for GNU Libtool (@pxref{Top, , Introduction,
4428 libtool, The Libtool Manual}) with the @samp{LTLIBRARIES} primary.
4429 @xref{A Shared Library}.
4435 @cindex _JAVA primary, defined
4436 @cindex JAVA primary, defined
4437 @cindex Primary variable, JAVA
4439 Automake provides some minimal support for Java compilation with the
4440 @samp{JAVA} primary.
4442 Any @file{.java} files listed in a @samp{_JAVA} variable will be
4443 compiled with @code{JAVAC} at build time. By default, @file{.class}
4444 files are not included in the distribution.
4446 @cindex JAVA restrictions
4447 @cindex Restrictions for JAVA
4449 Currently Automake enforces the restriction that only one @samp{_JAVA}
4450 primary can be used in a given @file{Makefile.am}. The reason for this
4451 restriction is that, in general, it isn't possible to know which
4452 @file{.class} files were generated from which @file{.java} files -- so
4453 it would be impossible to know which files to install where. For
4454 instance, a @file{.java} file can define multiple classes; the resulting
4455 @file{.class} file names cannot be predicted without parsing the
4458 There are a few variables which are used when compiling Java sources:
4462 The name of the Java compiler. This defaults to @samp{javac}.
4465 The flags to pass to the compiler. This is considered to be a user
4466 variable (@pxref{User Variables}).
4469 More flags to pass to the Java compiler. This, and not
4470 @code{JAVACFLAGS}, should be used when it is necessary to put Java
4471 compiler flags into @file{Makefile.am}.
4474 The value of this variable is passed to the @samp{-d} option to
4475 @code{javac}. It defaults to @samp{$(top_builddir)}.
4478 This variable is an @code{sh} expression which is used to set the
4479 @code{CLASSPATH} environment variable on the @code{javac} command line.
4480 (In the future we will probably handle class path setting differently.)
4487 @cindex _PYTHON primary, defined
4488 @cindex PYTHON primary, defined
4489 @cindex Primary variable, PYTHON
4492 Automake provides support for Python compilation with the @samp{PYTHON}
4495 Any files listed in a @samp{_PYTHON} variable will be byte-compiled with
4496 @code{py-compile} at install time. @code{py-compile} actually creates
4497 both standard (@file{.pyc}) and byte-compiled (@file{.pyo}) versions of
4498 the source files. Note that because byte-compilation occurs at install
4499 time, any files listed in @samp{noinst_PYTHON} will not be compiled.
4500 Python source files are included in the distribution by default.
4502 Automake ships with an Autoconf macro called @code{AM_PATH_PYTHON} which
4503 will determine some Python-related directory variables (see below). If
4504 you have called @code{AM_PATH_PYTHON} from @file{configure.ac}, then you
4505 may use the following variables to list you Python source files in your
4506 variables: @samp{python_PYTHON}, @samp{pkgpython_PYTHON},
4507 @samp{pyexecdir_PYTHON}, @samp{pkgpyexecdir_PYTHON}, depending where you
4508 want your files installed.
4510 @code{AM_PATH_PYTHON([@var{VERSION}], [@var{ACTION-IF-FOUND}],
4511 [@var{ACTION-IF-NOT-FOUND}])} takes three optional arguments. It will
4512 search a Python interpreter on the system. The first argument, if
4513 present, is the minimum version of Python required for this package:
4514 @code{AM_PATH_PYTHON} will skip any Python interpreter which is older
4515 than @var{VERSION}. If an interpreter is found and satisfies
4516 @var{VERSION}, then @var{ACTION-IF-FOUND} is run. Otherwise,
4517 @var{ACTION-IF-NOT-FOUND} is run.
4519 If @var{ACTION-IF-NOT-FOUND} is not specified, the default is to abort
4520 configure. This is fine when Python is an absolute requirement for the
4521 package. Therefore if Python >= 2.2 is only @emph{optional} to the
4522 package, @code{AM_PATH_PYTHON} could be called as follows.
4525 AM_PATH_PYTHON(2.2,, :)
4528 @code{AM_PATH_PYTHON} creates several output variables based on the
4529 Python installation found during configuration.
4533 The name of the Python executable, or @code{:} if no suitable
4534 interpreter could be found.
4536 Assuming @var{ACTION-IF-NOT-FOUND} is used (otherwise @file{./configure}
4537 will abort if Python is absent), the value of @code{PYTHON} can be used
4538 to setup a conditional in order to disable the relevant part of a build
4542 AM_PATH_PYTHON(,, :)
4543 AM_CONDITIONAL([HAVE_PYTHON], [test "$PYTHON" != :])
4547 If the @var{ACTION-IF-NOT-FOUND}
4550 @item PYTHON_VERSION
4551 The Python version number, in the form @var{major}.@var{minor}
4552 (e.g. @samp{1.5}). This is currently the value of
4553 @code{sys.version[:3]}.
4556 The string @code{$@{prefix@}}. This term may be used in future work
4557 which needs the contents of Python's @code{sys.prefix}, but general
4558 consensus is to always use the value from configure.
4560 @item PYTHON_EXEC_PREFIX
4561 The string @code{$@{exec_prefix@}}. This term may be used in future work
4562 which needs the contents of Python's @code{sys.exec_prefix}, but general
4563 consensus is to always use the value from configure.
4565 @item PYTHON_PLATFORM
4566 The canonical name used by Python to describe the operating system, as
4567 given by @code{sys.platform}. This value is sometimes needed when
4568 building Python extensions.
4571 The directory name for the @file{site-packages} subdirectory of the
4572 standard Python install tree.
4575 This is is the directory under @code{pythondir} which is named after the
4576 package. That is, it is @samp{$(pythondir)/$(PACKAGE)}. It is provided
4580 This is the directory where Python extension modules (shared libraries)
4581 should be installed.
4584 This is a convenience variable which is defined as
4585 @samp{$(pyexecdir)/$(PACKAGE)}.
4588 All these directory variables have values that start with either
4589 @code{$@{prefix@}} or @code{$@{exec_prefix@}} unexpanded. This works
4590 fine in @file{Makefiles}, but it makes these variables hard to use in
4591 @file{configure}. This is mandated by the GNU coding standards, so
4592 that the user can run @code{make prefix=/foo install}. The Autoconf
4593 manual has a section with more details on this topic
4594 (@pxref{Installation Directory Variables, , Installation Directory
4595 Variables, autoconf, The Autoconf Manual}).
4599 @chapter Building documentation
4601 Currently Automake provides support for Texinfo and man pages.
4605 * Man pages:: Man pages
4612 @cindex _TEXINFOS primary, defined
4613 @cindex TEXINFOS primary, defined
4614 @cindex Primary variable, TEXINFOS
4615 @cindex HTML output using Texinfo
4616 @cindex PDF output using Texinfo
4617 @cindex PS output using Texinfo
4618 @cindex DVI output using Texinfo
4620 If the current directory contains Texinfo source, you must declare it
4621 with the @samp{TEXINFOS} primary. Generally Texinfo files are converted
4622 into info, and thus the @code{info_TEXINFOS} variable is most commonly used
4623 here. Any Texinfo source file must end in the @file{.texi},
4624 @file{.txi}, or @file{.texinfo} extension. We recommend @file{.texi}
4627 @vindex info_TEXINFOS
4629 Automake generates rules to build @file{.info}, @file{.dvi}, @file{.ps},
4630 @file{.pdf} and @file{.html} files from your Texinfo sources.
4631 The @file{.info} files are built by @code{make all} and installed
4632 by @code{make install} (unless you use @code{no-installinfo}, see below).
4633 The other files can be built on request by @code{make dvi}, @code{make ps},
4634 @code{make pdf} and @code{make html}.
4636 @cindex Texinfo flag, VERSION
4637 @cindex Texinfo flag, UPDATED
4638 @cindex Texinfo flag, EDITION
4639 @cindex Texinfo flag, UPDATED-MONTH
4641 @cindex VERSION Texinfo flag
4642 @cindex UPDATED Texinfo flag
4643 @cindex EDITION Texinfo flag
4644 @cindex UPDATED-MONTH Texinfo flag
4648 If the @file{.texi} file @code{@@include}s @file{version.texi}, then
4649 that file will be automatically generated. The file @file{version.texi}
4650 defines four Texinfo flag you can reference using
4651 @code{@@value@{EDITION@}}, @code{@@value@{VERSION@}},
4652 @code{@@value@{UPDATED@}}, and @code{@@value@{UPDATED-MONTH@}}.
4657 Both of these flags hold the version number of your program. They are
4658 kept separate for clarity.
4661 This holds the date the primary @file{.texi} file was last modified.
4664 This holds the name of the month in which the primary @file{.texi} file
4668 The @file{version.texi} support requires the @code{mdate-sh} program;
4669 this program is supplied with Automake and automatically included when
4670 @code{automake} is invoked with the @code{--add-missing} option.
4672 If you have multiple Texinfo files, and you want to use the
4673 @file{version.texi} feature, then you have to have a separate version
4674 file for each Texinfo file. Automake will treat any include in a
4675 Texinfo file that matches @samp{vers*.texi} just as an automatically
4676 generated version file.
4678 Sometimes an info file actually depends on more than one @file{.texi}
4679 file. For instance, in GNU Hello, @file{hello.texi} includes the file
4680 @file{gpl.texi}. You can tell Automake about these dependencies using
4681 the @code{@var{texi}_TEXINFOS} variable. Here is how GNU Hello does it:
4686 info_TEXINFOS = hello.texi
4687 hello_TEXINFOS = gpl.texi
4692 By default, Automake requires the file @file{texinfo.tex} to appear in
4693 the same directory as the Texinfo source (this can be changed using the
4694 @code{TEXINFO_TEX} variable, see below). However, if you used
4695 @code{AC_CONFIG_AUX_DIR} in @file{configure.ac} (@pxref{Input, , Finding
4696 `configure' Input, autoconf, The Autoconf Manual}), then
4697 @file{texinfo.tex} is looked for there. Automake supplies
4698 @file{texinfo.tex} if @samp{--add-missing} is given.
4700 @opindex no-texinfo.tex
4702 The option @samp{no-texinfo.tex} can be used to eliminate the
4703 requirement for @file{texinfo.tex}. Use of the variable
4704 @code{TEXINFO_TEX} is preferable, however, because that allows the
4705 @code{dvi}, @code{ps}, and @code{pdf} targets to still work.
4707 @cindex Target, install-info
4708 @cindex Target, noinstall-info
4709 @cindex install-info target
4710 @cindex noinstall-info target
4712 @opindex no-installinfo
4713 @trindex install-info
4715 Automake generates an @code{install-info} target; some people apparently
4716 use this. By default, info pages are installed by @samp{make install}.
4717 This can be prevented via the @code{no-installinfo} option.
4719 The following variables are used by the Texinfo build rules.
4723 The name of the program invoked to build @file{.info} files. This
4724 variable is defined by Automake. If the @code{makeinfo} program is
4725 found on the system then it will be used by default; otherwise
4726 @code{missing} will be used instead.
4729 The command invoked to build @file{.html} files. Automake
4730 defines this to @code{$(MAKEINFO) --html}.
4733 User flags passed to each invocation of @code{$(MAKEINFO)} and
4734 @code{$(MAKEINFOHTML)}. This user variable (@pxref{User Variables}) is
4735 not expected to be defined in any @file{Makefile}; it can be used by
4736 users to pass extra flags to suit their needs.
4738 @item AM_MAKEINFOFLAGS
4739 @itemx AM_MAKEINFOHTMLFLAGS
4740 Maintainer flags passed to each @code{makeinfo} invocation. These
4741 are maintainer variables that can be overridden in @file{Makefile.am}.
4742 @code{$(AM_MAKEINFOFLAGS)} is passed to @code{makeinfo} when building
4743 @file{.info} files; and @code{$(AM_MAKEINFOHTMLFLAGS)} is used when
4744 building @file{.html} files.
4746 For instance the following setting can be used to obtain one single
4747 @file{.html} file per manual, without node separators.
4749 AM_MAKEINFOHTMLFLAGS = --no-headers --no-split
4752 By default, @code{$(AM_MAKEINFOHTMLFLAGS)} is set to
4753 @code{$(AM_MAKEINFOFLAGS)}. This means that defining
4754 @code{$(AM_MAKEINFOFLAGS)} without defining
4755 @code{$(AM_MAKEINFOHTMLFLAGS)} will impact builds of both @file{.info}
4756 and @file{.html} files.
4759 The name of the command that converts a @file{.texi} file into a
4760 @file{.dvi} file. This defaults to @code{texi2dvi}, a script that ships
4761 with the Texinfo package.
4764 The name of the command that translates a @file{.texi} file into a
4765 @file{.pdf} file. This defaults to @code{$(TEXI2DVI) --pdf --batch}.
4768 The name of the command that build a @file{.ps} file out of a
4769 @file{.dvi} file. This defaults to @code{dvips}.
4773 If your package has Texinfo files in many directories, you can use the
4774 variable @code{TEXINFO_TEX} to tell Automake where to find the canonical
4775 @file{texinfo.tex} for your package. The value of this variable should
4776 be the relative path from the current @file{Makefile.am} to
4780 TEXINFO_TEX = ../doc/texinfo.tex
4788 @cindex _MANS primary, defined
4789 @cindex MANS primary, defined
4790 @cindex Primary variable, MANS
4792 A package can also include man pages (but see the GNU standards on this
4793 matter, @ref{Man Pages, , , standards, The GNU Coding Standards}.) Man
4794 pages are declared using the @samp{MANS} primary. Generally the
4795 @code{man_MANS} variable is used. Man pages are automatically installed in
4796 the correct subdirectory of @code{mandir}, based on the file extension.
4800 File extensions such as @samp{.1c} are handled by looking for the valid
4801 part of the extension and using that to determine the correct
4802 subdirectory of @code{mandir}. Valid section names are the digits
4803 @samp{0} through @samp{9}, and the letters @samp{l} and @samp{n}.
4805 Sometimes developers prefer to name a man page something like
4806 @file{foo.man} in the source, and then rename it to have the correct
4807 suffix, e.g. @file{foo.1}, when installing the file. Automake also
4808 supports this mode. For a valid section named @var{SECTION}, there is a
4809 corresponding directory named @samp{man@var{SECTION}dir}, and a
4810 corresponding @samp{_MANS} variable. Files listed in such a variable
4811 are installed in the indicated section. If the file already has a
4812 valid suffix, then it is installed as-is; otherwise the file suffix is
4813 changed to match the section.
4815 For instance, consider this example:
4817 man1_MANS = rename.man thesame.1 alsothesame.1c
4820 In this case, @file{rename.man} will be renamed to @file{rename.1} when
4821 installed, but the other files will keep their names.
4823 @cindex Target, install-man
4824 @cindex Target, noinstall-man
4825 @cindex install-man target
4826 @cindex noinstall-man target
4828 @c Use @samp{make install} per documentation: (texi)code.
4829 By default, man pages are installed by @samp{make install}. However,
4830 since the GNU project does not require man pages, many maintainers do
4831 not expend effort to keep the man pages up to date. In these cases, the
4832 @code{no-installman} option will prevent the man pages from being
4833 installed by default. The user can still explicitly install them via
4834 @samp{make install-man}.
4835 @opindex no-installman
4836 @trindex install-man
4838 Here is how the man pages are handled in GNU @code{cpio} (which includes
4839 both Texinfo documentation and man pages):
4842 man_MANS = cpio.1 mt.1
4843 EXTRA_DIST = $(man_MANS)
4846 Man pages are not currently considered to be source, because it is not
4847 uncommon for man pages to be automatically generated. Therefore they
4848 are not automatically included in the distribution. However, this can
4849 be changed by use of the @samp{dist_} prefix.
4851 The @samp{nobase_} prefix is meaningless for man pages and is
4856 @chapter What Gets Installed
4858 @cindex Installation support
4859 @cindex make install support
4861 @section Basics of installation
4863 Naturally, Automake handles the details of actually installing your
4864 program once it has been built. All files named by the various
4865 primaries are automatically installed in the appropriate places when the
4866 user runs @code{make install}.
4868 A file named in a primary is installed by copying the built file into
4869 the appropriate directory. The base name of the file is used when
4873 bin_PROGRAMS = hello subdir/goodbye
4876 In this example, both @samp{hello} and @samp{goodbye} will be installed
4877 in @code{$(bindir)}.
4879 Sometimes it is useful to avoid the basename step at install time. For
4880 instance, you might have a number of header files in subdirectories of
4881 the source tree which are laid out precisely how you want to install
4882 them. In this situation you can use the @samp{nobase_} prefix to
4883 suppress the base name step. For example:
4886 nobase_include_HEADERS = stdio.h sys/types.h
4889 Will install @file{stdio.h} in @code{$(includedir)} and @file{types.h}
4890 in @code{$(includedir)/sys}.
4892 @section The two parts of install
4894 Automake generates separate @code{install-data} and @code{install-exec}
4895 targets, in case the installer is installing on multiple machines which
4896 share directory structure---these targets allow the machine-independent
4897 parts to be installed only once. @code{install-exec} installs
4898 platform-dependent files, and @code{install-data} installs
4899 platform-independent files. The @code{install} target depends on both
4900 of these targets. While Automake tries to automatically segregate
4901 objects into the correct category, the @file{Makefile.am} author is, in
4902 the end, responsible for making sure this is done correctly.
4903 @trindex install-data
4904 @trindex install-exec
4906 @cindex Install, two parts of
4908 Variables using the standard directory prefixes @samp{data},
4909 @samp{info}, @samp{man}, @samp{include}, @samp{oldinclude},
4910 @samp{pkgdata}, or @samp{pkginclude} (e.g. @samp{data_DATA}) are
4911 installed by @samp{install-data}.
4913 Variables using the standard directory prefixes @samp{bin}, @samp{sbin},
4914 @samp{libexec}, @samp{sysconf}, @samp{localstate}, @samp{lib}, or
4915 @samp{pkglib} (e.g. @samp{bin_PROGRAMS}) are installed by
4916 @samp{install-exec}.
4918 Any variable using a user-defined directory prefix with @samp{exec} in
4919 the name (e.g. @samp{myexecbin_PROGRAMS} is installed by
4920 @samp{install-exec}. All other user-defined prefixes are installed by
4921 @samp{install-data}.
4923 @section Extending installation
4925 It is possible to extend this mechanism by defining an
4926 @code{install-exec-local} or @code{install-data-local} target. If these
4927 targets exist, they will be run at @samp{make install} time. These
4928 rules can do almost anything; care is required.
4929 @trindex install-exec-local
4930 @trindex install-data-local
4932 Automake also supports two install hooks, @code{install-exec-hook} and
4933 @code{install-data-hook}. These hooks are run after all other install
4934 rules of the appropriate type, exec or data, have completed. So, for
4935 instance, it is possible to perform post-installation modifications
4936 using an install hook.
4937 @cindex Install hook
4939 @section Staged installs
4942 Automake generates support for the @samp{DESTDIR} variable in all
4943 install rules. @samp{DESTDIR} is used during the @samp{make install}
4944 step to relocate install objects into a staging area. Each object and
4945 path is prefixed with the value of @samp{DESTDIR} before being copied
4946 into the install area. Here is an example of typical DESTDIR usage:
4949 make DESTDIR=/tmp/staging install
4952 This places install objects in a directory tree built under
4953 @file{/tmp/staging}. If @file{/gnu/bin/foo} and
4954 @file{/gnu/share/aclocal/foo.m4} are to be installed, the above command
4955 would install @file{/tmp/staging/gnu/bin/foo} and
4956 @file{/tmp/staging/gnu/share/aclocal/foo.m4}.
4958 This feature is commonly used to build install images and packages. For
4959 more information, see @ref{Makefile Conventions, , , standards, The GNU
4962 Support for @samp{DESTDIR} is implemented by coding it directly into the
4963 install rules. If your @file{Makefile.am} uses a local install rule
4964 (e.g., @code{install-exec-local}) or an install hook, then you must
4965 write that code to respect @samp{DESTDIR}.
4967 @section Rules for the user
4969 Automake also generates an @code{uninstall} target, an
4970 @code{installdirs} target, and an @code{install-strip} target.
4972 @trindex installdirs
4973 @trindex install-strip
4975 Automake supports @code{uninstall-local} and @code{uninstall-hook}.
4976 There is no notion of separate uninstalls for ``exec'' and ``data'', as
4977 these features would not provide additional functionality.
4979 Note that @code{uninstall} is not meant as a replacement for a real
4984 @chapter What Gets Cleaned
4986 @cindex make clean support
4988 The GNU Makefile Standards specify a number of different clean rules.
4989 See @xref{Standard Targets, , Standard Targets for Users, standards,
4990 The GNU Coding Standards}.
4992 Generally the files that can be cleaned are determined automatically by
4993 Automake. Of course, Automake also recognizes some variables that can
4994 be defined to specify additional files to clean. These variables are
4995 @code{MOSTLYCLEANFILES}, @code{CLEANFILES}, @code{DISTCLEANFILES}, and
4996 @code{MAINTAINERCLEANFILES}.
4997 @vindex MOSTLYCLEANFILES
4999 @vindex DISTCLEANFILES
5000 @vindex MAINTAINERCLEANFILES
5002 As the GNU Standards aren't always explicit as to which files should be
5003 removed by which target, we've adopted a heuristic which we believe was
5004 first formulated by Fran@,{c}ois Pinard:
5008 If @code{make} built it, and it is commonly something that one would
5009 want to rebuild (for instance, a @file{.o} file), then
5010 @code{mostlyclean} should delete it.
5013 Otherwise, if @code{make} built it, then @code{clean} should delete it.
5016 If @code{configure} built it, then @code{distclean} should delete it.
5019 If the maintainer built it (for instance, a @file{.info} file), then
5020 @code{maintainer-clean} should delete it. However
5021 @code{maintainer-clean} should not delete anything that needs to exist
5022 in order to run @code{./configure && make}.
5025 We recommend that you follow this same set of heuristics in your
5030 @chapter What Goes in a Distribution
5032 @section Basics of distribution
5036 The @code{dist} target in the generated @file{Makefile.in} can be used
5037 to generate a gzip'd @code{tar} file and other flavors of archive for
5038 distribution. The files is named based on the @samp{PACKAGE} and
5039 @samp{VERSION} variables defined by @code{AM_INIT_AUTOMAKE}
5040 (@pxref{Macros}); more precisely the gzip'd @code{tar} file is named
5041 @samp{@var{package}-@var{version}.tar.gz}.
5045 You can use the @code{make} variable @samp{GZIP_ENV} to control how gzip
5046 is run. The default setting is @samp{--best}.
5048 For the most part, the files to distribute are automatically found by
5049 Automake: all source files are automatically included in a distribution,
5050 as are all @file{Makefile.am}s and @file{Makefile.in}s. Automake also
5051 has a built-in list of commonly used files which are automatically
5052 included if they are found in the current directory (either physically,
5053 or as the target of a @file{Makefile.am} rule). This list is printed by
5054 @samp{automake --help}. Also, files which are read by @code{configure}
5055 (i.e. the source files corresponding to the files specified in various
5056 Autoconf macros such as @code{AC_CONFIG_FILES} and siblings) are
5057 automatically distributed. Files included in @file{Makefile.am}s (using
5058 @code{include}) or in @file{configure.ac} (using @code{m4_include}), and
5059 helper scripts installed with @samp{automake --add-missing} are also
5062 @cvindex m4_include, distribution
5064 Still, sometimes there are files which must be distributed, but which
5065 are not covered in the automatic rules. These files should be listed in
5066 the @code{EXTRA_DIST} variable. You can mention files from
5067 subdirectories in @code{EXTRA_DIST}.
5069 You can also mention a directory in @code{EXTRA_DIST}; in this case the
5070 entire directory will be recursively copied into the distribution.
5071 Please note that this will also copy @emph{everything} in the directory,
5072 including CVS/RCS version control files. We recommend against using
5076 If you define @code{SUBDIRS}, Automake will recursively include the
5077 subdirectories in the distribution. If @code{SUBDIRS} is defined
5078 conditionally (@pxref{Conditionals}), Automake will normally include all
5079 directories that could possibly appear in @code{SUBDIRS} in the
5080 distribution. If you need to specify the set of directories
5081 conditionally, you can set the variable @code{DIST_SUBDIRS} to the exact
5082 list of subdirectories to include in the distribution (@pxref{Top level}).
5083 @vindex DIST_SUBDIRS
5086 @section Fine-grained distribution control
5088 Sometimes you need tighter control over what does @emph{not} go into the
5089 distribution; for instance you might have source files which are
5090 generated and which you do not want to distribute. In this case
5091 Automake gives fine-grained control using the @samp{dist} and
5092 @samp{nodist} prefixes. Any primary or @samp{_SOURCES} variable can be
5093 prefixed with @samp{dist_} to add the listed files to the distribution.
5094 Similarly, @samp{nodist_} can be used to omit the files from the
5099 As an example, here is how you would cause some data to be distributed
5100 while leaving some source code out of the distribution:
5103 dist_data_DATA = distribute-this
5105 nodist_foo_SOURCES = do-not-distribute.c
5108 @section The dist hook
5112 Occasionally it is useful to be able to change the distribution before
5113 it is packaged up. If the @code{dist-hook} target exists, it is run
5114 after the distribution directory is filled, but before the actual tar
5115 (or shar) file is created. One way to use this is for distributing
5116 files in subdirectories for which a new @file{Makefile.am} is overkill:
5120 mkdir $(distdir)/random
5121 cp -p $(srcdir)/random/a1 $(srcdir)/random/a2 $(distdir)/random
5124 Another way to to use this is for removing unnecessary files that get
5125 recursively included by specifying a directory in EXTRA_DIST:
5131 rm -rf `find $(distdir)/doc -name CVS`
5136 Two variables that come handy when writing @code{dist-hook} targets are
5137 @code{$(distdir)} and @code{$(top_distdir)}.
5139 @code{$(distdir)} points to the directory where the @code{dist} target
5140 will copy files from the current directory before creating the
5141 tarball. If you are at the top-level directory, then @code{distdir =
5142 $(PACKAGE)-$(VERSION)}. When used from subdirectory named
5143 @file{foo/}, then @code{distdir = ../$(PACKAGE)-$(VERSION)/foo}.
5145 @code{$(top_distdir)} always points to the root directory of the
5146 distributed tree. At the top-level it's equal to @code{$(distdir)}.
5147 In the @file{foo/} subdirectory
5148 @code{top_distdir = ../$(PACKAGE)-$(VERSION)}.
5150 Note that when packages are nested using @code{AC_CONFIG_SUBDIRS}
5151 (@pxref{Subdirectories, AC_CONFIG_SUBDIRS, Configuring Other Packages
5152 in Subdirectories, autoconf, The Autoconf Manual}), then
5153 @code{$(distdir)} and @code{$(top_distdir)} are relative to the
5154 package where @code{make dist} was run, not to any sub-packages
5157 @section Checking the distribution
5159 @cindex make distcheck
5160 @cindex make distcleancheck
5161 @vindex distcleancheck_listfiles
5162 @cindex make distuninstallcheck
5163 @vindex distuninstallcheck_listfiles
5165 Automake also generates a @code{distcheck} target which can be of help
5166 to ensure that a given distribution will actually work.
5167 @code{distcheck} makes a distribution, then tries to do a @code{VPATH}
5168 build, run the test suite, and finally make another tarfile to ensure the
5169 distribution is self-contained.
5172 Building the package involves running @code{./configure}. If you need
5173 to supply additional flags to @code{configure}, define them in the
5174 @code{DISTCHECK_CONFIGURE_FLAGS} variable, either in your top-level
5175 @file{Makefile.am}, or on the command line when invoking @code{make}.
5176 @vindex DISTCHECK_CONFIGURE_FLAGS
5178 If the target @code{distcheck-hook} is defined in your
5179 @file{Makefile.am}, then it will be invoked by @code{distcheck} after
5180 the new distribution has been unpacked, but before the unpacked copy is
5181 configured and built. Your @code{distcheck-hook} can do almost
5182 anything, though as always caution is advised. Generally this hook is
5183 used to check for potential distribution errors not caught by the
5186 Speaking about potential distribution errors, @code{distcheck} will also
5187 ensure that the @code{distclean} target actually removes all built
5188 files. This is done by running @code{make distcleancheck} at the end of
5189 the @code{VPATH} build. By default, @code{distcleancheck} will run
5190 @code{distclean} and then make sure the build tree has been emptied by
5191 running @code{$(distcleancheck_listfiles)}. Usually this check will
5192 find generated files that you forgot to add to the @code{DISTCLEANFILES}
5193 variable (@pxref{Clean}).
5194 @trindex distcleancheck
5196 The @code{distcleancheck} behavior should be OK for most packages,
5197 otherwise you have the possibility to override the definition of
5198 either the @code{distcleancheck} target, or the
5199 @code{$(distcleancheck_listfiles)} variable. For instance to disable
5200 @code{distcleancheck} completely, add the following rule to your
5201 top-level @file{Makefile.am}:
5202 @vindex distcleancheck_listfiles
5209 If you want @code{distcleancheck} to ignore built files which have not
5210 been cleaned because they are also part of the distribution, add the
5211 following definition instead:
5214 distcleancheck_listfiles = \
5215 find -type f -exec sh -c 'test -f $(srcdir)/@{@} || echo @{@}' ';'
5218 The above definition is not the default because it's usually an error if
5219 your Makefiles cause some distributed files to be rebuilt when the user
5220 build the package. (Think about the user missing the tool required to
5221 build the file; or if the required tool is built by your package,
5222 consider the cross-compilation case where it can't be run.) There is
5223 a FAQ entry about this (@pxref{distcleancheck}), make sure you read it
5224 before playing with @code{distcleancheck_listfiles}.
5226 @code{distcheck} also checks that the @code{uninstall} target works
5227 properly, both for ordinary and @samp{DESTDIR} builds. It does this
5228 by invoking @code{make uninstall}, and then it checks the install tree
5229 to see if any files are left over. This check will make sure that you
5230 correctly coded your @code{uninstall}-related targets.
5232 By default, the checking is done by the @code{distuninstallcheck} target,
5233 and the list of files in the install tree is generated by
5234 @code{$(distuninstallcheck_listfiles}) (this is a variable whose value is
5235 a shell command to run that prints the list of files to stdout).
5237 Either of these can be overridden to modify the behavior of
5238 @code{distcheck}. For instance, to disable this check completely, you
5246 @section The types of distributions
5248 Automake generates targets to provide archives of the project for
5249 distributions in various formats. These targets are:
5252 @item @code{dist-bzip2}
5253 Generate a bzip2 tar archive of the distribution. bzip2 archives are
5254 frequently smaller than gzipped archives.
5257 @item @code{dist-gzip}
5258 Generate a gzip tar archive of the distribution.
5261 @item @code{dist-shar}
5262 Generate a shar archive of the distribution.
5265 @item @code{dist-zip}
5266 Generate a zip archive of the distribution.
5269 @item @code{dist-tarZ}
5270 Generate a compressed tar archive of
5275 The targets @code{dist} and its synonym @code{dist-all} will create
5276 archives in all the enabled formats, @ref{Options}. By default, only
5277 the @code{dist-gzip} target is hooked to @code{dist}.
5281 @chapter Support for test suites
5286 Automake supports two forms of test suites.
5288 @section Simple Tests
5290 If the variable @code{TESTS} is defined, its value is taken to be a list
5291 of programs to run in order to do the testing. The programs can either
5292 be derived objects or source objects; the generated rule will look both
5293 in @code{srcdir} and @file{.}. Programs needing data files should look
5294 for them in @code{srcdir} (which is both an environment variable and a
5295 make variable) so they work when building in a separate directory
5296 (@pxref{Build Directories, , Build Directories , autoconf, The Autoconf
5297 Manual}), and in particular for the @code{distcheck} target
5300 @cindex Exit status 77, special interpretation
5302 The number of failures will be printed at the end of the run. If a
5303 given test program exits with a status of 77, then its result is ignored
5304 in the final count. This feature allows non-portable tests to be
5305 ignored in environments where they don't make sense.
5307 The variable @code{TESTS_ENVIRONMENT} can be used to set environment
5308 variables for the test run; the environment variable @code{srcdir} is
5309 set in the rule. If all your test programs are scripts, you can also
5310 set @code{TESTS_ENVIRONMENT} to an invocation of the shell (e.g.
5311 @samp{$(SHELL) -x}); this can be useful for debugging the tests.
5313 @vindex TESTS_ENVIRONMENT
5315 @cindex Tests, expected failure
5316 @cindex Expected test failure
5318 You may define the variable @code{XFAIL_TESTS} to a list of tests
5319 (usually a subset of @code{TESTS}) that are expected to fail. This will
5320 reverse the result of those tests.
5323 Automake ensures that each program listed in @code{TESTS} is built
5324 before any tests are run; you can list both source and derived programs
5325 in @code{TESTS}. For instance, you might want to run a C program as a
5326 test. To do this you would list its name in @code{TESTS} and also in
5327 @code{check_PROGRAMS}, and then specify it as you would any other
5330 @section DejaGnu Tests
5332 If @uref{ftp://ftp.gnu.org/gnu/dejagnu/, @samp{dejagnu}} appears in
5333 @code{AUTOMAKE_OPTIONS}, then a @code{dejagnu}-based test suite is
5334 assumed. The variable @code{DEJATOOL} is a list of names which are
5335 passed, one at a time, as the @code{--tool} argument to @code{runtest}
5336 invocations; it defaults to the name of the package.
5338 The variable @code{RUNTESTDEFAULTFLAGS} holds the @code{--tool} and
5339 @code{--srcdir} flags that are passed to dejagnu by default; this can be
5340 overridden if necessary.
5341 @vindex RUNTESTDEFAULTFLAGS
5343 The variables @code{EXPECT} and @code{RUNTEST} can
5344 also be overridden to provide project-specific values. For instance,
5345 you will need to do this if you are testing a compiler toolchain,
5346 because the default values do not take into account host and target
5353 The contents of the variable @code{RUNTESTFLAGS} are passed to the
5354 @code{runtest} invocation. This is considered a ``user variable''
5355 (@pxref{User Variables}). If you need to set @code{runtest} flags in
5356 @file{Makefile.am}, you can use @code{AM_RUNTESTFLAGS} instead.
5357 @vindex RUNTESTFLAGS
5358 @vindex AM_RUNTESTFLAGS
5360 @cindex @file{site.exp}
5361 Automake will generate rules to create a local @file{site.exp} file,
5362 defining various variables detected by @code{./configure}. This file
5363 is automatically read by DejaGnu. It is OK for the user of a package
5364 to edit this file in order to tune the test suite. However this is
5365 not the place where the test suite author should define new variables:
5366 this should be done elsewhere in the real test suite code.
5367 Especially, @file{site.exp} should not be distributed.
5369 For more information regarding DejaGnu test suites, see @xref{Top, , ,
5370 dejagnu, The DejaGnu Manual}.
5372 In either case, the testing is done via @samp{make check}.
5374 @section Install Tests
5376 The @code{installcheck} target is available to the user as a way to run
5377 any tests after the package has been installed. You can add tests to
5378 this by writing an @code{installcheck-local} target.
5382 @chapter Changing Automake's Behavior
5384 Various features of Automake can be controlled by options in the
5385 @file{Makefile.am}. Such options are applied on a per-@file{Makefile}
5386 basis when listed in a special @file{Makefile} variable named
5387 @code{AUTOMAKE_OPTIONS}. They are applied globally to all processed
5388 @file{Makefiles} when listed in the first argument of
5389 @code{AM_INIT_AUTOMAKE} in @file{configure.ac}. Currently understood
5391 @vindex AUTOMAKE_OPTIONS
5396 @itemx @code{foreign}
5397 @itemx @code{cygnus}
5398 @cindex Option, gnits
5400 @cindex Option, foreign
5401 @cindex Option, cygnus
5403 Set the strictness as appropriate. The @code{gnits} option also implies
5404 @code{readme-alpha} and @code{check-news}.
5406 @item @code{ansi2knr}
5407 @itemx @code{@var{path}/ansi2knr}
5408 @cindex Option, ansi2knr
5409 Turn on automatic de-ANSI-fication. @xref{ANSI}. If preceded by a
5410 path, the generated @file{Makefile.in} will look in the specified
5411 directory to find the @file{ansi2knr} program. The path should be a
5412 relative path to another directory in the same distribution (Automake
5413 currently does not check this).
5415 @item @code{check-news}
5416 @cindex Option, check-news
5417 Cause @code{make dist} to fail unless the current version number appears
5418 in the first few lines of the @file{NEWS} file.
5420 @item @code{dejagnu}
5421 @cindex Option, dejagnu
5422 Cause @code{dejagnu}-specific rules to be generated. @xref{Tests}.
5424 @item @code{dist-bzip2}
5425 @cindex Option, dist-bzip2
5426 Hook @code{dist-bzip2} to @code{dist}.
5429 @item @code{dist-shar}
5430 @cindex Option, dist-shar
5431 Hook @code{dist-shar} to @code{dist}.
5434 @item @code{dist-zip}
5435 @cindex Option, dist-zip
5436 Hook @code{dist-zip} to @code{dist}.
5439 @item @code{dist-tarZ}
5440 @cindex Option, dist-tarZ
5441 Hook @code{dist-tarZ} to @code{dist}.
5444 @item @code{no-define}
5445 @cindex Option, no-define
5446 This options is meaningful only when passed as an argument to
5447 @code{AM_INIT_AUTOMAKE}. It will prevent the @code{PACKAGE} and
5448 @code{VERSION} variables to be @code{AC_DEFINE}d.
5450 @item @code{no-dependencies}
5451 @cindex Option, no-dependencies
5452 This is similar to using @samp{--include-deps} on the command line, but
5453 is useful for those situations where you don't have the necessary bits
5454 to make automatic dependency tracking work @xref{Dependencies}. In this
5455 case the effect is to effectively disable automatic dependency tracking.
5457 @item @code{no-dist}
5458 @cindex Option, no-dist
5459 Don't emit any code related to @code{dist} target. This is useful
5460 when a package has its own method for making distributions.
5462 @item @code{no-dist-gzip}
5463 @cindex Option, no-dist-gzip
5464 Do not hook @code{dist-gzip} to @code{dist}.
5465 @trindex no-dist-gzip
5467 @item @code{no-exeext}
5468 @cindex Option, no-exeext
5469 If your @file{Makefile.am} defines a target @samp{foo}, it will override
5470 a target named @samp{foo$(EXEEXT)}. This is necessary when
5471 @code{EXEEXT} is found to be empty. However, by default automake will
5472 generate an error for this use. The @code{no-exeext} option will
5473 disable this error. This is intended for use only where it is known in
5474 advance that the package will not be ported to Windows, or any other
5475 operating system using extensions on executables.
5477 @item @code{no-installinfo}
5478 @cindex Option, no-installinfo
5479 The generated @file{Makefile.in} will not cause info pages to be built
5480 or installed by default. However, @code{info} and @code{install-info}
5481 targets will still be available. This option is disallowed at
5482 @samp{GNU} strictness and above.
5484 @trindex install-info
5486 @item @code{no-installman}
5487 @cindex Option, no-installman
5488 The generated @file{Makefile.in} will not cause man pages to be
5489 installed by default. However, an @code{install-man} target will still
5490 be available for optional installation. This option is disallowed at
5491 @samp{GNU} strictness and above.
5492 @trindex install-man
5494 @item @code{nostdinc}
5495 @cindex Option, nostdinc
5496 This option can be used to disable the standard @samp{-I} options which
5497 are ordinarily automatically provided by Automake.
5499 @item @code{no-texinfo.tex}
5500 @cindex Option, no-texinfo
5501 Don't require @file{texinfo.tex}, even if there are texinfo files in
5504 @item @code{readme-alpha}
5505 @cindex Option, readme-alpha
5506 If this release is an alpha release, and the file @file{README-alpha}
5507 exists, then it will be added to the distribution. If this option is
5508 given, version numbers are expected to follow one of two forms. The
5509 first form is @samp{@var{MAJOR}.@var{MINOR}.@var{ALPHA}}, where each
5510 element is a number; the final period and number should be left off for
5511 non-alpha releases. The second form is
5512 @samp{@var{MAJOR}.@var{MINOR}@var{ALPHA}}, where @var{ALPHA} is a
5513 letter; it should be omitted for non-alpha releases.
5515 @item @code{std-options}
5516 @cindex Options, std-options
5517 @cindex make installcheck
5518 Make the @code{installcheck} target check that installed scripts and
5519 programs support the @code{--help} and @code{--version} options.
5520 This also provides a basic check that the program's
5521 run-time dependencies are satisfied after installation.
5523 @vindex AM_INSTALLCHECK_STD_OPTIONS_EXEMPT
5524 In a few situations, programs (or scripts) have to be exempted from this
5525 test. For instance @command{false} (from GNU sh-utils) is never
5526 successful, even for @code{--help} or @code{--version}. You can list
5527 such programs in the variable @code{AM_INSTALLCHECK_STD_OPTIONS_EXEMPT}.
5528 Programs (not scripts) listed in this variable should be suffixed by
5529 @code{$(EXEEXT)} for the sake of Win32 or OS/2. For instance suppose we
5530 build @code{false} as a program but @code{true.sh} as a script, and that
5531 neither of them support @code{--help} or @code{--version}:
5534 AUTOMAKE_OPTIONS = std-options
5535 bin_PROGRAMS = false ...
5536 bin_SCRIPTS = true.sh ...
5537 AM_INSTALLCHECK_STD_OPTIONS_EXEMPT = false$(EXEEXT) true.sh
5540 @item @code{subdir-objects}
5541 If this option is specified, then objects are placed into the
5542 subdirectory of the build directory corresponding to the subdirectory of
5543 the source file. For instance if the source file is
5544 @file{subdir/file.cxx}, then the output file would be
5545 @file{subdir/file.o}.
5548 @cindex Option, version
5549 A version number (e.g. @samp{0.30}) can be specified. If Automake is not
5550 newer than the version specified, creation of the @file{Makefile.in}
5553 @item @code{-W@var{category}} or @code{--warnings=@var{category}}
5554 @cindex Option, warnings
5555 These options behave exactly like their command-line counterpart
5556 (@pxref{Invoking Automake}). This allows you to enable or disable some
5557 warning categories on a per-file basis. You can also setup some warnings
5558 for your entire project; for instance try @code{AM_INIT_AUTOMAKE([-Wall])}
5559 in your @file{configure.ac}.
5563 Unrecognized options are diagnosed by @code{automake}.
5565 If you want an option to apply to all the files in the tree, you can use
5566 the @code{AM_INIT_AUTOMAKE} macro in @file{configure.ac}.
5571 @chapter Miscellaneous Rules
5573 There are a few rules and variables that didn't fit anywhere else.
5576 * Tags:: Interfacing to etags and mkid
5577 * Suffixes:: Handling new file extensions
5578 * Multilibs:: Support for multilibs.
5583 @section Interfacing to @code{etags}
5585 @cindex TAGS support
5587 Automake will generate rules to generate @file{TAGS} files for use with
5588 GNU Emacs under some circumstances.
5590 If any C, C++ or Fortran 77 source code or headers are present, then
5591 @code{tags} and @code{TAGS} targets will be generated for the directory.
5594 At the topmost directory of a multi-directory package, a @code{tags}
5595 target file will be generated which, when run, will generate a
5596 @file{TAGS} file that includes by reference all @file{TAGS} files from
5599 The @code{tags} target will also be generated if the variable
5600 @code{ETAGS_ARGS} is defined. This variable is intended for use in
5601 directories which contain taggable source that @code{etags} does not
5602 understand. The user can use the @code{ETAGSFLAGS} to pass additional
5603 flags to @code{etags}; @code{AM_ETAGSFLAGS} is also available for use in
5607 @vindex AM_ETAGSFLAGS
5609 Here is how Automake generates tags for its source, and for nodes in its
5613 ETAGS_ARGS = automake.in --lang=none \
5614 --regex='/^@@node[ \t]+\([^,]+\)/\1/' automake.texi
5617 If you add filenames to @samp{ETAGS_ARGS}, you will probably also
5618 want to set @samp{TAGS_DEPENDENCIES}. The contents of this variable
5619 are added directly to the dependencies for the @code{tags} target.
5620 @vindex TAGS_DEPENDENCIES
5622 Automake also generates a @code{ctags} target which can be used to
5623 build @command{vi}-style @file{tags} files. The variable @code{CTAGS}
5624 is the name of the program to invoke (by default @samp{ctags});
5625 @code{CTAGSFLAGS} can be used by the user to pass additional flags,
5626 and @code{AM_CTAGSFLAGS} can be used by the @file{Makefile.am}.
5628 Automake will also generate an @code{ID} target which will run
5629 @code{mkid} on the source. This is only supported on a
5630 directory-by-directory basis.
5633 Automake also supports the @uref{http://www.gnu.org/software/global/,
5634 GNU Global Tags program}. The @code{GTAGS} target runs Global Tags
5635 automatically and puts the result in the top build directory. The
5636 variable @code{GTAGS_ARGS} holds arguments which are passed to
5642 @section Handling new file extensions
5644 @cindex Adding new SUFFIXES
5645 @cindex SUFFIXES, adding
5648 It is sometimes useful to introduce a new implicit rule to handle a file
5649 type that Automake does not know about.
5651 For instance, suppose you had a compiler which could compile @samp{.foo}
5652 files to @samp{.o} files. You would simply define an suffix rule for
5660 Then you could directly use a @samp{.foo} file in a @samp{_SOURCES}
5661 variable and expect the correct results:
5665 doit_SOURCES = doit.foo
5668 This was the simpler and more common case. In other cases, you will
5669 have to help Automake to figure which extensions you are defining your
5670 suffix rule for. This usually happens when your extensions does not
5671 start with a dot. Then, all you have to do is to put a list of new
5672 suffixes in the @code{SUFFIXES} variable @strong{before} you define your
5675 For instance the following definition prevents Automake to misinterpret
5676 @samp{.idlC.cpp:} as an attempt to transform @samp{.idlC} into
5680 SUFFIXES = .idl C.cpp
5685 As you may have noted, the @code{SUFFIXES} variable behaves like the
5686 @code{.SUFFIXES} special target of @code{make}. You should not touch
5687 @code{.SUFFIXES} yourself, but use @code{SUFFIXES} instead and let
5688 Automake generate the suffix list for @code{.SUFFIXES}. Any given
5689 @code{SUFFIXES} go at the start of the generated suffixes list, followed
5690 by Automake generated suffixes not already in the list.
5693 @section Support for Multilibs
5695 Automake has support for an obscure feature called multilibs. A
5696 @dfn{multilib} is a library which is built for multiple different ABIs
5697 at a single time; each time the library is built with a different target
5698 flag combination. This is only useful when the library is intended to
5699 be cross-compiled, and it is almost exclusively used for compiler
5702 The multilib support is still experimental. Only use it if you are
5703 familiar with multilibs and can debug problems you might encounter.
5710 @cindex Including Makefile fragment
5711 @cindex Makefile fragment, including
5713 Automake supports an @code{include} directive which can be used to
5714 include other @file{Makefile} fragments when @code{automake} is run.
5715 Note that these fragments are read and interpreted by @code{automake},
5716 not by @code{make}. As with conditionals, @code{make} has no idea that
5717 @code{include} is in use.
5719 There are two forms of @code{include}:
5722 @item include $(srcdir)/file
5723 Include a fragment which is found relative to the current source
5726 @item include $(top_srcdir)/file
5727 Include a fragment which is found relative to the top source directory.
5730 Note that if a fragment is included inside a conditional, then the
5731 condition applies to the entire contents of that fragment.
5733 Makefile fragments included this way are always distributed because
5734 there are needed to rebuild @file{Makefile.in}.
5737 @chapter Conditionals
5739 @cindex Conditionals
5741 Automake supports a simple type of conditionals.
5743 @cvindex AM_CONDITIONAL
5744 Before using a conditional, you must define it by using
5745 @code{AM_CONDITIONAL} in the @code{configure.ac} file (@pxref{Macros}).
5747 @defmac AM_CONDITIONAL (@var{conditional}, @var{condition})
5748 The conditional name, @var{conditional}, should be a simple string
5749 starting with a letter and containing only letters, digits, and
5750 underscores. It must be different from @samp{TRUE} and @samp{FALSE}
5751 which are reserved by Automake.
5753 The shell @var{condition} (suitable for use in a shell @code{if}
5754 statement) is evaluated when @code{configure} is run. Note that you
5755 must arrange for @emph{every} @code{AM_CONDITIONAL} to be invoked every
5756 time @code{configure} is run -- if @code{AM_CONDITIONAL} is run
5757 conditionally (e.g., in a shell @code{if} statement), then the result
5758 will confuse automake.
5761 @cindex --enable-debug, example
5762 @cindex Example conditional --enable-debug
5763 @cindex Conditional example, --enable-debug
5765 Conditionals typically depend upon options which the user provides to
5766 the @code{configure} script. Here is an example of how to write a
5767 conditional which is true if the user uses the @samp{--enable-debug}
5771 AC_ARG_ENABLE(debug,
5772 [ --enable-debug Turn on debugging],
5773 [case "$@{enableval@}" in
5776 *) AC_MSG_ERROR(bad value $@{enableval@} for --enable-debug) ;;
5777 esac],[debug=false])
5778 AM_CONDITIONAL(DEBUG, test x$debug = xtrue)
5781 Here is an example of how to use that conditional in @file{Makefile.am}:
5793 noinst_PROGRAMS = $(DBG)
5796 This trivial example could also be handled using EXTRA_PROGRAMS
5797 (@pxref{Conditional Programs}).
5799 You may only test a single variable in an @code{if} statement, possibly
5800 negated using @samp{!}. The @code{else} statement may be omitted.
5801 Conditionals may be nested to any depth. You may specify an argument to
5802 @code{else} in which case it must be the negation of the condition used
5803 for the current @code{if}. Similarly you may specify the condition
5804 which is closed by an @code{end}:
5815 Unbalanced conditions are errors.
5817 Note that conditionals in Automake are not the same as conditionals in
5818 GNU Make. Automake conditionals are checked at configure time by the
5819 @file{configure} script, and affect the translation from
5820 @file{Makefile.in} to @file{Makefile}. They are based on options passed
5821 to @file{configure} and on results that @file{configure} has discovered
5822 about the host system. GNU Make conditionals are checked at @code{make}
5823 time, and are based on variables passed to the make program or defined
5824 in the @file{Makefile}.
5826 Automake conditionals will work with any make program.
5830 @chapter The effect of @code{--gnu} and @code{--gnits}
5832 @cindex --gnu, required files
5833 @cindex --gnu, complete description
5835 The @samp{--gnu} option (or @samp{gnu} in the @samp{AUTOMAKE_OPTIONS}
5836 variable) causes @code{automake} to check the following:
5840 The files @file{INSTALL}, @file{NEWS}, @file{README}, @file{AUTHORS},
5841 and @file{ChangeLog}, plus one of @file{COPYING.LIB}, @file{COPYING.LESSER}
5842 or @file{COPYING}, are required at the topmost directory of the package.
5845 The options @samp{no-installman} and @samp{no-installinfo} are
5849 Note that this option will be extended in the future to do even more
5850 checking; it is advisable to be familiar with the precise requirements
5851 of the GNU standards. Also, @samp{--gnu} can require certain
5852 non-standard GNU programs to exist for use by various maintainer-only
5853 targets; for instance in the future @code{pathchk} might be required for
5856 @cindex --gnits, complete description
5858 The @samp{--gnits} option does everything that @samp{--gnu} does, and
5859 checks the following as well:
5863 @samp{make installcheck} will check to make sure that the @code{--help}
5864 and @code{--version} really print a usage message and a version string,
5865 respectively. This is the @code{std-options} option (@pxref{Options}).
5868 @samp{make dist} will check to make sure the @file{NEWS} file has been
5869 updated to the current version.
5872 @samp{VERSION} is checked to make sure its format complies with Gnits
5874 @c FIXME xref when standards are finished
5877 @cindex README-alpha
5878 If @samp{VERSION} indicates that this is an alpha release, and the file
5879 @file{README-alpha} appears in the topmost directory of a package, then
5880 it is included in the distribution. This is done in @samp{--gnits}
5881 mode, and no other, because this mode is the only one where version
5882 number formats are constrained, and hence the only mode where Automake
5883 can automatically determine whether @file{README-alpha} should be
5887 The file @file{THANKS} is required.
5892 @chapter The effect of @code{--cygnus}
5894 @cindex Cygnus strictness
5896 Some packages, notably GNU GCC and GNU gdb, have a build environment
5897 originally written at Cygnus Support (subsequently renamed Cygnus
5898 Solutions, and then later purchased by Red Hat). Packages with this
5899 ancestry are sometimes referred to as ``Cygnus'' trees.
5901 A Cygnus tree has slightly different rules for how a @file{Makefile.in}
5902 is to be constructed. Passing @samp{--cygnus} to @code{automake} will
5903 cause any generated @file{Makefile.in} to comply with Cygnus rules.
5905 Here are the precise effects of @samp{--cygnus}:
5909 Info files are always created in the build directory, and not in the
5913 @file{texinfo.tex} is not required if a Texinfo source file is
5914 specified. The assumption is that the file will be supplied, but in a
5915 place that Automake cannot find. This assumption is an artifact of how
5916 Cygnus packages are typically bundled.
5919 @samp{make dist} is not supported, and the rules for it are not
5920 generated. Cygnus-style trees use their own distribution mechanism.
5923 Certain tools will be searched for in the build tree as well as in the
5924 user's @samp{PATH}. These tools are @code{runtest}, @code{expect},
5925 @code{makeinfo} and @code{texi2dvi}.
5928 @code{--foreign} is implied.
5931 The options @samp{no-installinfo} and @samp{no-dependencies} are
5935 The macros @samp{AM_MAINTAINER_MODE} and @samp{AM_CYGWIN32} are
5939 The @code{check} target doesn't depend on @code{all}.
5942 GNU maintainers are advised to use @samp{gnu} strictness in preference
5943 to the special Cygnus mode. Some day, perhaps, the differences between
5944 Cygnus trees and GNU trees will disappear (for instance, as GCC is made
5945 more standards compliant). At that time the special Cygnus mode will be
5950 @chapter When Automake Isn't Enough
5952 With some minor exceptions (like @code{_PROGRAMS} variables being
5953 rewritten to append @code{$(EXEEXT)}), the contents of a
5954 @file{Makefile.am} is copied to @file{Makefile.in} verbatim.
5956 @cindex copying semantics
5958 These copying semantics means that many problems can be worked around
5959 by simply adding some @code{make} variables and rules to
5960 @file{Makefile.am}. Automake will ignore these additions.
5962 @cindex conflicting definitions
5963 @cindex rules, conflicting
5964 @cindex variables, conflicting
5965 @cindex definitions, conflicts
5967 Since a @file{Makefile.in} is built from data gathered from three
5968 different places (@file{Makefile.am}, @file{configure.ac}, and
5969 @command{automake} itself), it is possible to have conflicting
5970 definitions of rules or variables. When building @file{Makefile.in}
5971 the following priorities are respected by @command{automake} to ensure
5972 the user always have the last word. User defined variables in
5973 @file{Makefile.am} have priority over variables @code{AC_SUBST}ed from
5974 @file{configure.ac}, and @code{AC_SUBST}ed variables have priority
5975 over @command{automake}-defined variables. As far rules are
5976 concerned, a user-defined rule overrides any
5977 @command{automake}-defined rule for the same target.
5979 @cindex overriding rules
5980 @cindex overriding semantics
5981 @cindex rules, overriding
5983 These overriding semantics make it possible to fine tune some default
5984 settings of Automake, or replace some of its rules. Overriding
5985 Automake rules is often inadvisable, particularly in the topmost
5986 directory of a package with subdirectories. The @code{-Woverride}
5987 option (@pxref{Invoking Automake}) comes handy to catch overridden
5990 Note that Automake does not make any difference between rules with
5991 commands and rules that only specify dependencies. So it is not
5992 possible to append new dependencies to an @code{automake}-defined
5993 target without redefining the entire rule.
5995 @cindex -local targets
5996 @cindex local targets
5998 However, various useful targets have a @samp{-local} version you can
5999 specify in your @file{Makefile.in}. Automake will supplement the
6000 standard target with these user-supplied targets.
6015 @trindex check-local
6017 @trindex install-data-local
6018 @trindex install-exec
6019 @trindex install-exec-local
6021 @trindex uninstall-local
6022 @trindex mostlyclean
6023 @trindex mostlyclean-local
6025 @trindex clean-local
6027 @trindex distclean-local
6028 @trindex installdirs
6029 @trindex installdirs-local
6030 @trindex installcheck
6031 @trindex installcheck-local
6033 The targets that support a local version are @code{all}, @code{info},
6034 @code{dvi}, @code{ps}, @code{pdf}, @code{html}, @code{check},
6035 @code{install-data}, @code{install-exec}, @code{uninstall},
6036 @code{installdirs}, @code{installcheck} and the various @code{clean} targets
6037 (@code{mostlyclean}, @code{clean}, @code{distclean}, and
6038 @code{maintainer-clean}). Note that there are no
6039 @code{uninstall-exec-local} or @code{uninstall-data-local} targets; just
6040 use @code{uninstall-local}. It doesn't make sense to uninstall just
6041 data or just executables.
6043 For instance, here is one way to install a file in @file{/etc}:
6047 $(INSTALL_DATA) $(srcdir)/afile $(DESTDIR)/etc/afile
6050 @cindex -hook targets
6051 @cindex hook targets
6053 Some targets also have a way to run another target, called a @dfn{hook},
6054 after their work is done. The hook is named after the principal target,
6055 with @samp{-hook} appended. The targets allowing hooks are
6056 @code{install-data}, @code{install-exec}, @code{uninstall}, @code{dist},
6057 and @code{distcheck}.
6058 @trindex install-data-hook
6059 @trindex install-exec-hook
6060 @trindex uninstall-hook
6063 For instance, here is how to create a hard link to an installed program:
6067 ln $(DESTDIR)$(bindir)/program$(EXEEXT) \
6068 $(DESTDIR)$(bindir)/proglink$(EXEEXT)
6071 Although cheaper and more portable than symbolic links, hard links
6072 will not work everywhere (for instance OS/2 does not have
6073 @command{ln}). Ideally you should fall back to @code{cp -p} when
6074 @code{ln} does not work. An easy way, if symbolic links are
6075 acceptable to you, is to add @code{AC_PROG_LN_S} to
6076 @file{configure.ac} (@pxref{Particular Programs, , Particular Program
6077 Checks, autoconf, The Autoconf Manual}) and use @code{$(LN_S)} in
6080 @cindex versioned binaries, installing
6081 @cindex installing versioned binaries
6082 @cindex LN_S example
6083 For instance, here is how you could install a versioned copy of a
6084 program using @code{$(LN_S)}:
6088 cd $(DESTDIR)$(bindir) && \
6089 mv -f prog$(EXEEXT) prog-$(VERSION)$(EXEEXT) && \
6090 $(LN_S) prog-$(VERSION)$(EXEEXT) prog$(EXEEXT)
6093 Note that we rename the program so that a new version will erase the
6094 symbolic link, not the real binary. Also we @code{cd} into the
6095 destination directory in order to create relative links.
6097 @c FIXME should include discussion of variables you can use in these
6101 @chapter Distributing @file{Makefile.in}s
6103 Automake places no restrictions on the distribution of the resulting
6104 @file{Makefile.in}s. We still encourage software authors to distribute
6105 their work under terms like those of the GPL, but doing so is not
6106 required to use Automake.
6108 Some of the files that can be automatically installed via the
6109 @code{--add-missing} switch do fall under the GPL@. However, these also
6110 have a special exception allowing you to distribute them with your
6111 package, regardless of the licensing you choose.
6114 @node API versioning
6115 @chapter Automake API versioning
6117 New Automake releases usually include bug fixes and new features.
6118 Unfortunately they may also introduce new bugs and incompatibilities.
6119 This makes four reasons why a package may require a particular Automake
6122 Things get worse when maintaining a large tree of packages, each one
6123 requiring a different version of Automake. In the past, this meant that
6124 any developer (and sometime users) had to install several versions of
6125 Automake in different places, and switch @samp{$PATH} appropriately for
6128 Starting with version 1.6, Automake installs versioned binaries. This
6129 means you can install several versions of Automake in the same
6130 @samp{$prefix}, and can select an arbitrary Automake version by running
6131 @samp{automake-1.6} or @samp{automake-1.7} without juggling with
6132 @samp{$PATH}. Furthermore, @file{Makefile}'s generated by Automake 1.6
6133 will use @samp{automake-1.6} explicitly in their rebuild rules.
6135 Note that @samp{1.6} in @samp{automake-1.6} is Automake's API version,
6136 not Automake's version. If a bug fix release is made, for instance
6137 Automake 1.6.1, the API version will remain 1.6. This means that a
6138 package which work with Automake 1.6 should also work with 1.6.1; after
6139 all, this is what people expect from bug fix releases.
6141 Note that if your package relies on a feature or a bug fix introduced in
6142 a release, you can pass this version as an option to Automake to ensure
6143 older releases will not be used. For instance, use this in your
6144 @file{configure.ac}:
6147 AM_INIT_AUTOMAKE(1.6.1) dnl Require Automake 1.6.1 or better.
6150 or, in a particular @file{Makefile.am}:
6153 AUTOMAKE_OPTIONS = 1.6.1 # Require Automake 1.6.1 or better.
6156 Automake will print an error message if its version is
6157 older than the requested version.
6160 @heading What is in the API
6162 Automake's programming interface is not easy to define. Basically it
6163 should include at least all @strong{documented} variables and targets
6164 that a @samp{Makefile.am} author can use, any behavior associated with
6165 them (e.g. the places where @samp{-hook}'s are run), the command line
6166 interface of @samp{automake} and @samp{aclocal}, @dots{}
6168 @heading What is not in the API
6170 Every undocumented variable, target, or command line option, is not part
6171 of the API@. You should avoid using them, as they could change from one
6172 version to the other (even in bug fix releases, if this helps to fix a
6175 If it turns out you need to use such a undocumented feature, contact
6176 @email{automake@@gnu.org} and try to get it documented and exercised by
6180 @chapter Frequently Asked Questions about Automake
6182 This chapter covers some questions that often come up on the mailing
6186 * CVS:: CVS and generated files
6187 * maintainer-mode:: missing and AM_MAINTAINER_MODE
6188 * wildcards:: Why doesn't Automake support wildcards?
6189 * distcleancheck:: Files left in build directory after distclean
6190 * renamed objects:: Why are object files sometimes renamed?
6194 @section CVS and generated files
6196 @subsection Background: distributed generated files
6197 @cindex generated files, distributed
6198 @cindex rebuild rules
6200 Packages made with Autoconf and Automake ship with some generated
6201 files like @file{configure} or @file{Makefile.in}. These files were
6202 generated on the developer's host and are distributed so that
6203 end-users do not have to install the maintainer tools required to
6204 rebuild them. Other generated files like Lex scanners, Yacc parsers,
6205 or Info documentation, are usually distributed on similar grounds.
6207 Automake outputs rules in @file{Makefile}s to rebuild these files. For
6208 instance @command{make} will run @command{autoconf} to rebuild
6209 @file{configure} whenever @file{configure.ac} is changed. This makes
6210 development safer by ensuring a @file{configure} is never out-of-date
6211 with respect to @file{configure.ac}.
6213 As generated files shipped in packages are up-to-date, and because
6214 @command{tar} preserves times-tamps, these rebuild rules are not
6215 triggered when a user unpacks and builds a package.
6217 @subsection Background: CVS and timestamps
6218 @cindex timestamps and CVS
6219 @cindex CVS and timestamps
6221 Unless you use CVS keywords (in which case files must be updated at
6222 commit time), CVS preserves timestamp during @code{cvs commit} and
6223 @code{cvs import -d} operations.
6225 When you check out a file using @code{cvs checkout} its timestamp is
6226 set to that of the revision which is being checked out.
6228 However, during @command{cvs update}, files will have the date of the
6229 update, not the original timestamp of this revision. This is meant to
6230 make sure that @command{make} notices sources files have been updated.
6232 This times tamp shift is troublesome when both sources and generated
6233 files are kept under CVS. Because CVS processes files in alphabetical
6234 order, @file{configure.ac} will appear older than @file{configure}
6235 after a @command{cvs update} that updates both files, even if
6236 @file{configure} was newer than @file{configure.ac} when it was
6237 checked in. Calling @code{make} will then trigger a spurious rebuild
6238 of @file{configure}.
6240 @subsection Living with CVS in Autoconfiscated projects
6241 @cindex CVS and generated files
6242 @cindex generated files and CVS
6244 There are basically two clans amongst maintainers: those who keep all
6245 distributed files under CVS, including generated files, and those who
6246 keep generated files @emph{out} of CVS.
6248 @subsubheading All files in CVS
6252 The CVS repository contains all distributed files so you know exactly
6253 what is distributed, and you can checkout any prior version entirely.
6256 Maintainers can see how generated files evolve (for instance you can
6257 see what happens to your @file{Makefile.in}s when you upgrade Automake
6258 and make sure they look OK).
6261 Users do not need the autotools to build a checkout of the project, it
6262 works just like a released tarball.
6265 If users use @command{cvs update} to update their copy, instead of
6266 @command{cvs checkout} to fetch a fresh one, timestamps will be
6267 inaccurate. Some rebuild rules will be triggered and attempt to
6268 run developer tools such as @command{autoconf} or @command{automake}.
6270 Actually, calls to such tools are all wrapped into a call to the
6271 @command{missing} script discussed later (@pxref{maintainer-mode}).
6272 @command{missing} will take care of fixing the timestamps when these
6273 tools are not installed, so that the build can continue.
6276 In distributed development, developers are likely to have different
6277 version of the maintainer tools installed. In this case rebuilds
6278 triggered by timestamp lossage will lead to spurious changes
6279 to generated files. There are several solutions to this:
6283 All developers should use the same versions, so that the rebuilt files
6284 are identical to files in CVS. (This starts to be difficult when each
6285 project you work on uses different versions.)
6287 Or people use a script to fix the timestamp after a checkout (the GCC
6288 folks have such a script).
6290 Or @file{configure.ac} uses @code{AM_MAINTAINER_MODE}, which will
6291 disable all these rebuild rules by default. This is further discussed
6292 in @ref{maintainer-mode}.
6296 Although we focused on spurious rebuilds, the converse can also
6297 happen. CVS's timestamp handling can also let you think an
6298 out-of-date file is up-to-date.
6300 For instance, suppose a developer has modified @file{Makefile.am} and
6301 rebuilt @file{Makefile.in}, and then decide to do a last-minute change
6302 to @file{Makefile.am} right before checking in both files (without
6303 rebuilding @file{Makefile.in} to account for the change).
6305 This last change to @file{Makefile.am} make the copy of
6306 @file{Makefile.in} out-of-date. Since CVS processes files
6307 alphabetically, when another developer @code{cvs update} his or her
6308 tree, @file{Makefile.in} will happen to be newer than
6309 @file{Makefile.am}. This other developer will not see
6310 @file{Makefile.in} is out-of-date.
6314 @subsubheading Generated files out of CVS
6316 One way to get CVS and @code{make} working peacefully is to never
6317 store generated files in CVS, i.e., do not CVS-control files which are
6318 @code{Makefile} targets (or @emph{derived} files in Make terminology).
6320 This way developers are not annoyed by changes to generated files. It
6321 does not matter if they all have different versions (assuming they are
6322 compatible, of course). And finally, timestamps are not lost, changes
6323 to sources files can't be missed as in the
6324 @file{Makefile.am}/@file{Makefile.in} example discussed earlier.
6326 The drawback is that the CVS repository is not an exact copy of what
6327 is distributed and that users now need to install various development
6328 tools (maybe even specific versions) before they can build a checkout.
6329 But, after all, CVS's job is versioning, not distribution.
6331 Allowing developers to use different versions of their tools can also
6332 hide bugs during distributed development. Indeed, developers will be
6333 using (hence testing) their own generated files, instead of the
6334 generated files that will be released actually. The developer who
6335 prepares the tarball might be using a version of the tool that
6336 produces bogus output (for instance a non-portable C file), something
6337 other developers could have noticed if they weren't using their own
6338 versions of this tool.
6340 @subsection Third-party files
6341 @cindex CVS and third-party files
6342 @cindex third-party files and CVS
6344 Another class of files not discussed here (because they do not cause
6345 timestamp issues) are files which are shipped with a package, but
6346 maintained elsewhere. For instance tools like @command{gettextize}
6347 and @command{autopoint} (from Gettext) or @command{libtoolize} (from
6348 Libtool), will install or update files in your package.
6350 These files, whether they are kept under CVS or not, raise similar
6351 concerns about version mismatch between developers' tools. The
6352 Gettext manual has a section about this, see @ref{CVS Issues, CVS
6353 Issues, Integrating with CVS, gettext, GNU gettext tools}.
6355 @node maintainer-mode
6356 @section @command{missing} and @code{AM_MAINTAINER_MODE}
6358 @subsection @command{missing}
6359 @cindex missing, purpose
6361 The @command{missing} script is a wrapper around several maintainer
6362 tools, designed to warn users if a maintainer tool is required but
6363 missing. Typical maintainer tools are @command{autoconf},
6364 @command{automake}, @command{bison}, etc. Because file generated by
6365 these tools are shipped with the other sources of a package, these
6366 tools shouldn't be required during a user build and they are not
6367 checked for in @file{configure}.
6369 However, if for some reason a rebuild rule is triggered and involves a
6370 missing tool, @command{missing} will notice it and warn the user.
6371 Besides the warning, when a tool is missing, @command{missing} will
6372 attempt to fix timestamps in a way which allow the build to continue.
6373 For instance @command{missing} will touch @file{configure} if
6374 @command{autoconf} is not installed. When all distributed files are
6375 kept under CVS, this feature of @command{missing} allows user
6376 @emph{with no maintainer tools} to build a package off CVS, bypassing
6377 any timestamp inconsistency implied by @code{cvs update}.
6379 If the required tool is installed, @command{missing} will run it and
6380 won't attempt to continue after failures. This is correct during
6381 development: developers love fixing failures. However, users with
6382 wrong versions of maintainer tools may get an error when the rebuild
6383 rule is spuriously triggered, halting the build. This failure to let
6384 the build continue is one of the arguments of the
6385 @code{AM_MAINTAINER_MODE} advocates.
6387 @subsection @code{AM_MAINTAINER_MODE}
6388 @cindex AM_MAINTAINER_MODE, purpose
6389 @cvindex AM_MAINTAINER_MODE
6391 @code{AM_MAINTAINER_MODE} disables the so called "rebuild rules" by
6392 default. If you have @code{AM_MAINTAINER_MODE} in
6393 @file{configure.ac}, and run @code{./configure && make}, then
6394 @command{make} will *never* attempt to rebuilt @file{configure},
6395 @file{Makefile.in}s, Lex or Yacc outputs, etc. I.e., this disables
6396 build rules for files which are usually distributed and that users
6397 should normally not have to update.
6399 If you run @code{./configure --enable-maintainer-mode}, then these
6400 rebuild rules will be active.
6402 People use @code{AM_MAINTAINER_MODE} either because they do want their
6403 users (or themselves) annoyed by timestamps lossage (@pxref{CVS}), or
6404 because they simply can't stand the rebuild rules and prefer running
6405 maintainer tools explicitly.
6407 @code{AM_MAINTAINER_MODE} also allows you to disable some custom build
6408 rules conditionally. Some developers use this feature to disable
6409 rules that need exotic tools that users may not have available.
6411 Several years ago Fran@,{c}ois Pinard pointed out several arguments
6412 against @code{AM_MAINTAINER_MODE}. Most of them relate to insecurity.
6413 By removing dependencies you get non-dependable builds: change to
6414 sources files can have no effect on generated files and this can be
6415 very confusing when unnoticed. He adds that security shouldn't be
6416 reserved to maintainers (what @code{--enable-maintainer-mode}
6417 suggests), on the contrary. If one user has to modify a
6418 @file{Makefile.am}, then either @file{Makefile.in} should be updated
6419 or a warning should be output (this is what Automake uses
6420 @code{missing} for) but the last thing you want is that nothing
6421 happens and the user doesn't notice it (this is what happens when
6422 rebuild rules are disabled by @code{AM_MAINTAINER_MODE}).
6424 Jim Meyering, the inventor of the @code{AM_MAINTAINER_MODE} macro was
6425 swayed by Fran@,{c}ois's arguments, and got rid of
6426 @code{AM_MAINTAINER_MODE} in all of his packages.
6428 Still many people continue to use @code{AM_MAINTAINER_MODE}, because
6429 it helps them working on projects where all files are kept under CVS,
6430 and because @command{missing} isn't enough if you have the wrong
6431 version of the tools.
6435 @section Why doesn't Automake support wildcards?
6438 Developers are lazy. They often would like to use wildcards in
6439 @file{Makefile.am}s, so they don't need to remember they have to
6440 update @file{Makefile.am}s every time they add, delete, or rename a
6443 There are several objections to this:
6446 When using CVS (or similar) developers need to remember they have to
6447 run @code{cvs add} or @code{cvs rm} anyway. Updating
6448 @file{Makefile.am} accordingly quickly becomes a reflex.
6450 Conversely, if your application doesn't compile
6451 because you forgot to add a file in @file{Makefile.am}, it will help
6452 you remember to @code{cvs add} it.
6455 Using wildcards makes easy to distribute files by mistake. For
6456 instance some code a developer is experimenting with (a test case,
6457 say) but which should not be part of the distribution.
6460 Using wildcards it's easy to omit some files by mistake. For
6461 instance one developer creates a new file, uses it at many places,
6462 but forget to commit it. Another developer then checkout the
6463 incomplete project and is able to run `make dist' successfully,
6464 even though a file is missing.
6467 Listing files, you control *exactly* what you distribute.
6468 If some file that should be distributed is missing from your
6469 tree, @code{make dist} will complain. Besides, you don't distribute
6470 more than what you listed.
6473 Finally it's really hard to @file{forget} adding a file to
6474 @file{Makefile.am}, because if you don't add it, it doesn't get
6475 compiled nor installed, so you can't even test it.
6478 Still, these are philosophical objections, and as such you may disagree,
6479 or find enough value in wildcards to dismiss all of them. Before you
6480 start writing a patch against Automake to teach it about wildcards,
6481 let's see the main technical issue: portability.
6483 Although @code{$(wildcard ...)} works with GNU @command{make}, it is
6484 not portable to other @command{make} implementations.
6486 The only way Automake could support @command{$(wildcard ...)} is by
6487 expending @command{$(wildcard ...)} when @command{automake} is run.
6488 Resulting @file{Makefile.in}s would be portable since they would
6489 list all files and not use @code{$(wildcard ...)}. However that
6490 means developers need to remember they must run @code{automake} each
6491 time they add, delete, or rename files.
6493 Compared to editing @file{Makefile.am}, this is really little win. Sure,
6494 it's easier and faster to type @code{automake; make} than to type
6495 @code{emacs Makefile.am; make}. But nobody bothered enough to write a
6496 patch add support for this syntax. Some people use scripts to
6497 generated file lists in @file{Makefile.am} or in separate
6498 @file{Makefile} fragments.
6500 Even if you don't care about portability, and are tempted to use
6501 @code{$(wildcard ...)} anyway because you target only GNU Make, you
6502 should know there are many places where Automake need to know exactly
6503 which files should be processed. As Automake doesn't know how to
6504 expand @code{$(wildcard ...)}, you cannot use it in these places.
6505 @code{$(wildcard ...)} is a black box comparable to @code{AC_SUBST}ed
6506 variables as far Automake is concerned.
6508 You can get warnings about @code{$(wildcard ...}) constructs using the
6509 @code{-Wportability} flag.
6511 @node distcleancheck
6512 @section Files left in build directory after distclean
6513 @cindex distclean, diagnostic
6514 @cindex dependencies and distributed files
6516 @trindex distcleancheck
6518 This is a diagnostic you might encounter while running @code{make
6521 As explained in @ref{Dist}, @code{make distcheck} attempts to build
6522 and check your package for errors like this one.
6524 @code{make distcheck} will perform a @code{VPATH} build of your
6525 package, and then call @code{make distclean}. Files left in the build
6526 directory after @code{make distclean} has run are listed after this
6529 This diagnostic really covers two kinds of errors:
6533 files that are forgotten by distclean;
6535 distributed files that are erroneously rebuilt.
6538 The former left-over files are not distributed, so the fix is to mark
6539 them for cleaning (@pxref{Clean}), this is obvious and doesn't deserve
6542 The latter bug is not always easy to understand and fix, so let's
6543 proceed with an example. Suppose our package contains a program for
6544 which we want to build a man page using @command{help2man}. GNU
6545 @command{help2man} produces simple manual pages from the @code{--help}
6546 and @code{--version} output of other commands (@pxref{Top, , Overview,
6547 help2man, The Help2man Manual}). Because we don't to force want our
6548 users to install @command{help2man}, we decide to distribute the
6549 generated man page using the following setup.
6552 # This Makefile.am is bogus.
6555 dist_man_MANS = foo.1
6558 help2man --output=foo.1 ./foo$(EXEEXT)
6561 This will effectively distribute the man page. However,
6562 @code{make distcheck} will fail with:
6565 ERROR: files left in build directory after distclean:
6569 Why was @file{foo.1} rebuilt? Because although distributed,
6570 @file{foo.1} depends on a non-distributed built file:
6571 @file{foo$(EXEEXT)}. @file{foo$(EXEEXT)} is built by the user, so it
6572 will always appear to be newer than the distributed @file{foo.1}.
6574 @code{make distcheck} caught an inconsistency in our package. Our
6575 intent was to distribute @file{foo.1} so users do not need installing
6576 @command{help2man}, however since this our rule causes this file to be
6577 always rebuilt, users @emph{do} need @command{help2man}. Either we
6578 should ensure that @file{foo.1} is not rebuilt by users, or there is
6579 no point in distributing @file{foo.1}.
6581 More generally, the rule is that distributed files should never depend
6582 on non-distributed built files. If you distribute something
6583 generated, distribute its sources.
6585 One way to fix the above example, while still distributing
6586 @file{foo.1} is to not depend on @file{foo$(EXEEXT)}. For instance,
6587 assuming @command{foo --version} and @command{foo --help} do not
6588 change unless @file{foo.c} or @file{configure.ac} change, we could
6589 write the following @file{Makefile.am}:
6594 dist_man_MANS = foo.1
6596 foo.1: foo.c $(top_srcdir)/configure.ac
6597 $(MAKE) $(AM_MAKEFLAGS) foo$(EXEEXT)
6598 help2man --output=foo.1 ./foo$(EXEEXT)
6601 This way, @file{foo.1} will not get rebuilt every time
6602 @file{foo$(EXEEXT)} changes. The @command{make} call makes sure
6603 @file{foo$(EXEEXT)} is up-to-date before @command{help2man}. Another
6604 way to ensure this would be to use separate directories for binaries
6605 and man pages, and set @code{SUBDIRS} so that binaries are built
6608 We could also decide not to distribute @file{foo.1}. In
6609 this case it's fine to have @file{foo.1} dependent upon
6610 @file{foo$(EXEEXT)}, since both will have to be rebuilt.
6611 However it would be impossible to build the package in a
6612 cross-compilation, because building @file{foo.1} involves
6613 an @emph{execution} of @file{foo$(EXEEXT)}.
6615 Another context where such errors are common is when distributed files
6616 are built by tools which are built by the package. The pattern is similar:
6619 distributed-file: built-tools distributed-sources
6624 should be changed to
6627 distributed-file: distributed-sources
6628 $(MAKE) $(AM_MAKEFLAGS) built-tools
6633 or you could choose not to distribute @file{distributed-file}, if
6634 cross-compilation does not matter.
6636 The points made through these examples are worth a summary:
6641 Distributed files should never depend upon non-distributed built
6644 Distributed files should be distributed will all their dependencies.
6646 If a file is @emph{intended} be rebuilt by users, there is no point in
6651 @vrindex distcleancheck_listfiles
6652 For desperate cases, it's always possible to disable this check by
6653 setting @code{distcleancheck_listfiles} as documented in @ref{Dist}.
6654 Make sure you do understand the reason why @code{make distcheck}
6655 complains before you do this. @code{distcleancheck_listfiles} is a
6656 way to @emph{hide} errors, not to fix them. You can always do better.
6658 @node renamed objects
6659 @section Why are object files sometimes renamed?
6661 This happens when per-target compilation flags are used. Object
6662 files need to be renamed just in case they would clash with object
6663 files compiled from the same sources, but with different flags.
6664 Consider the following example.
6667 bin_PROGRAMS = true false
6668 true_SOURCES = generic.c
6669 true_CPPFLAGS = -DEXIT_CODE=0
6670 false_SOURCES = generic.c
6671 false_CPPFLAGS = -DEXIT_CODE=1
6674 Obviously the two programs are built from the same source, but it
6675 would be bad if they shared the same object, because @file{generic.o}
6676 cannot be built with both @code{-DEXIT_CODE=0} *and*
6677 @code{-DEXIT_CODE=1}. Therefore @command{automake} outputs rules to
6678 build two different objects: @file{true-generic.o} and
6679 @file{false-generic.o}.
6681 @command{automake} doesn't actually look whether sources files are
6682 shared to decide if it must rename objects. It will just rename all
6683 objects of a target as soon as it sees per-target compilation flags
6686 It's OK to share object files when per-target compilation flags are not
6687 used. For instance @file{true} and @file{false} will both use
6688 @file{version.o} in the following example.
6691 AM_CPPFLAGS = -DVERSION=1.0
6692 bin_PROGRAMS = true false
6693 true_SOURCES = true.c version.c
6694 false_SOURCES = false.c version.c
6697 Note that the renaming of objects is also affected by the
6698 @code{_SHORTNAME} variable (@pxref{Program and Library Variables}).
6700 @c ========================================================== Appendices
6703 @node Copying This Manual
6704 @appendix Copying This Manual
6707 * GNU Free Documentation License:: License for copying this manual
6717 * Macro and Variable Index:: Index of Autoconf macros and Automake variables
6718 * General Index:: General index
6721 @node Macro and Variable Index
6722 @appendixsec Macro and Variable Index
6727 @appendixsec General Index
6736 @c LocalWords: texinfo setfilename settitle setchapternewpage texi direntry
6737 @c LocalWords: dircategory in's aclocal ifinfo titlepage Tromey vskip pt sp
6738 @c LocalWords: filll defcodeindex ov cv op tr syncodeindex fn cp vr ifnottex
6739 @c LocalWords: dir Automake's ac Dist Gnits gnits cygnus dfn Autoconf's pxref
6740 @c LocalWords: cindex Autoconf autoconf perl samp cvs dist trindex SUBST foo
6741 @c LocalWords: xs emph FIXME ref vindex pkglibdir pkgincludedir pkgdatadir mt
6742 @c LocalWords: pkg libdir cvindex cpio bindir sbindir rmt pax sbin zar zardir
6743 @c LocalWords: HTML htmldir html noinst TEXINFOS nodist nobase strudel CFLAGS
6744 @c LocalWords: libmumble CC YFLAGS ansi knr itemx de fication config url comp
6745 @c LocalWords: depcomp elisp sh mdate mkinstalldirs mkdir py tex dvi ps pdf
6746 @c LocalWords: ylwrap zardoz INIT gettext acinclude mv FUNCS LIBOBJS LDADD fr
6747 @c LocalWords: uref featureful dnl src LINGUAS es ko nl pl sl sv PROG ISC doc
6748 @c LocalWords: POSIX STDC fcntl FUNC ALLOCA blksize struct stat intl po chmod
6749 @c LocalWords: ChangeLog SUBDIRS gettextize gpl testdata getopt INTLLIBS cpp
6750 @c LocalWords: localedir datadir DLOCALEDIR DEXIT CPPFLAGS autoreconf opindex
6751 @c LocalWords: AUX var symlink deps Wno Wnone package's aclocal's distclean
6752 @c LocalWords: ltmain xref LIBSOURCE LIBSOURCES LIBOBJ MEMCMP vs RANLIB CXX
6753 @c LocalWords: LDFLAGS LIBTOOL libtool XTRA LIBS gettext's acdir APIVERSION
6754 @c LocalWords: dirlist noindent usr MULTILIB multilib Multilibs TIOCGWINSZ sc
6755 @c LocalWords: GWINSZ termios SRCDIR tarball bzip LISPDIR lispdir XEmacs CCAS
6756 @c LocalWords: emacsen MicroEmacs CCASFLAGS UX GCJ gcj GCJFLAGS posix DMALLOC
6757 @c LocalWords: dmalloc ldmalloc REGEX regex rx DEPDIR DEP DEFUN aclocaldir fi
6758 @c LocalWords: mymacro myothermacro AMFLAGS autopoint autogen libtoolize yum
6759 @c LocalWords: autoheader README MAKEFLAGS subdir Inetutils sync COND endif
6760 @c LocalWords: Miller's installable includedir inc pkgdata EXEEXT libexec bsd
6761 @c LocalWords: pkglib libexecdir prog libcpio cpio's dlopen dlpreopen linux
6762 @c LocalWords: subsubsection OBJEXT esac lib LTLIBRARIES liblob LIBADD AR ar
6763 @c LocalWords: ARFLAGS cru ing maude libgettext lo LTLIBOBJS rpath SGI PRE yy
6764 @c LocalWords: libmaude CCLD CXXFLAGS FFLAGS LFLAGS OBJCFLAGS RFLAGS DEFS cc
6765 @c LocalWords: SHORTNAME vtable srcdir nostdinc basename yxx cxx ll lxx gdb
6766 @c LocalWords: lexers yymaxdepth maxdepth yyparse yylex yyerror yylval lval
6767 @c LocalWords: yychar yydebug yypact yyr yydef def yychk chk yypgo pgo yyact
6768 @c LocalWords: yyexca exca yyerrflag errflag yynerrs nerrs yyps yypv pv yys
6769 @c LocalWords: yystate yytmp tmp yyv yyval val yylloc lloc yyreds yytoks toks
6770 @c LocalWords: yylhs yylen yydefred yydgoto yysindex yyrindex yygindex yyname
6771 @c LocalWords: yytable yycheck yyrule byacc CXXCOMPILE CXXLINK FLINK cfortran
6772 @c LocalWords: Catalogue preprocessable FLIBS libfoo baz JAVACFLAGS java exe
6773 @c LocalWords: SunOS fying basenames exeext uninstalled oldinclude kr FSF's
6774 @c LocalWords: pkginclude oldincludedir sysconf sharedstate localstate gcc rm
6775 @c LocalWords: sysconfdir sharedstatedir localstatedir preexist CLEANFILES gz
6776 @c LocalWords: unnumberedsubsec depfile tmpdepfile depmode const interoperate
6777 @c LocalWords: JAVAC javac JAVAROOT builddir CLASSPATH ENV pyc pyo pkgpython
6778 @c LocalWords: pyexecdir pkgpyexecdir Python's pythondir pkgpythondir txi ois
6779 @c LocalWords: installinfo vers MAKEINFO makeinfo MAKEINFOFLAGS noinstall rf
6780 @c LocalWords: mandir thesame alsothesame installman myexecbin DESTDIR Pinard
6781 @c LocalWords: uninstall installdirs uninstalls MOSTLYCLEANFILES mostlyclean
6782 @c LocalWords: DISTCLEANFILES MAINTAINERCLEANFILES gzip'd GZIP gzip shar exp
6783 @c LocalWords: distdir distcheck distcleancheck listfiles distuninstallcheck
6784 @c LocalWords: VPATH tarfile stdout XFAIL DejaGnu dejagnu DEJATOOL runtest ln
6785 @c LocalWords: RUNTESTDEFAULTFLAGS toolchain RUNTESTFLAGS asis readme DVIPS
6786 @c LocalWords: installcheck gzipped tarZ std utils etags mkid multilibbing cd
6787 @c LocalWords: ARGS taggable ETAGSFLAGS lang ctags CTAGSFLAGS GTAGS gtags idl
6788 @c LocalWords: foocc doit idlC multilibs ABIs cmindex defmac ARG enableval
6789 @c LocalWords: MSG xtrue DBG pathchk CYGWIN afile proglink versioned CVS's
6790 @c LocalWords: wildcards Autoconfiscated subsubheading autotools Meyering API
6791 @c LocalWords: ois's wildcard Wportability cartouche vrindex printindex Duret
6792 @c LocalWords: DSOMEFLAG DVERSION automake Lutz insertcopying versioning FAQ
6793 @c LocalWords: LTLIBOBJ Libtool's libtool's libltdl dlopening itutions libbar
6794 @c LocalWords: WANTEDLIBS libhello sublibraries libtop libsub dlopened Ratfor
6795 @c LocalWords: mymodule timestamps timestamp underquoted MAKEINFOHTMLFLAGS